commit fea681dafb1363a154b7fc6d59baa83d2a9ebc5c Author: Michael Kerrisk Date: Wed Nov 3 13:51:07 2004 +0000 Import of man-pages 1.70 diff --git a/Makefile b/Makefile new file mode 100644 index 000000000..d28660d28 --- /dev/null +++ b/Makefile @@ -0,0 +1,59 @@ +# Do "make screen" first, if you want to protect already installed, +# more up-to-date manual pages than the ones included in this package. +# Do "make install" to copy the pages to their destination. +# Do "make gz" or "make bz2" first if you use compressed source pages. + +MANDIR=$(prefix)/usr/share/man + +GZIP=gzip -9 +BZIP2=bzip2 -9 + +all: screen remove install + +allgz: gz all + +allbz: bz2 all + +screen: + -mkdir not_installed + for i in man?/*; do \ + if [ $(MANDIR)/"$$i" -nt "$$i" ]; then \ + cmp -s $(MANDIR)/"$$i" "$$i" > /dev/null 2>&1; \ + if [ "$$?" != 0 ]; then mv "$$i" not_installed; fi; \ + fi; \ + done + +remove: + for i in man?/* man??/*; do \ + rm -f $(MANDIR)/"$$i" $(MANDIR)/"$$i".gz $(MANDIR)/"$$i".bz2; \ + done + +gz: + for i in man? man??; do $(GZIP) "$$i"/*; done + +bz2: + for i in man? man??; do $(BZIP2) "$$i"/*; done + +# Use with +# make HTDIR=/some/dir HTOPTS=whatever html +# The sed removes the lines "Content-type: text/html\n\n" +html: + @if [ x$(HTDIR) = x ]; then echo "You must set HTDIR."; else \ + for i in man?; do \ + [ -d $(HTDIR)/"$$i" ] || mkdir -p $(HTDIR)/"$$i"; \ + find "$$i/" -type f | while read f; do \ + (cd "$$i"; man2html $(HTOPTS) `basename $$f`) | \ + sed -e '1,2d' > $(HTDIR)/"$$i"/`basename $$f`.html; \ + done; \ + done; fi + +README=$(MANDIR)/man1/README +install: + for i in man? man??; do \ + install -d -m 755 $(MANDIR)/"$$i"; \ + install -m 644 "$$i"/* $(MANDIR)/"$$i"; \ + done; \ + rm -f $(README) $(README).gz $(README).bz2 + +# someone might also want to look at /var/catman/cat2 or so ... +# a problem is that the location of cat pages varies a lot diff --git a/POSIX-COPYRIGHT b/POSIX-COPYRIGHT new file mode 100644 index 000000000..d830db0ec --- /dev/null +++ b/POSIX-COPYRIGHT @@ -0,0 +1,25 @@ +The Institute of Electrical and Electronics Engineers (IEEE) and +The Open Group, have given us permission to reprint portions of +their documentation. + +In the following statement, the phrase ``this text'' refers to +portions of the system documentation. + +Portions of this text are reprinted and reproduced in electronic form +in the linux-manpages package, from IEEE Std 1003.1 (TM), 2003 Edition, +Standard for Information Technology -- Portable Operating System +Interface (POSIX (R)), The Open Group Base Specifications Issue 6, +Copyright (C) 2001-2003 by the Institute of Electrical and Electronics +Engineers, Inc and The Open Group. In the event of any discrepancy +between these versions and the original IEEE and The Open Group +Standard, the original IEEE and The Open Group Standard is the referee +document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . + +This notice shall appear on any product containing this material. + +Redistribution of this material is permitted so long as this notice and +the corresponding notices within each POSIX manual page are retained on +any distribution, and the nroff source is included. Modifications to +the text are permitted so long as any conflicts with the standard +are clearly marked as such in the text. diff --git a/README b/README new file mode 100644 index 000000000..d5d6b62c3 --- /dev/null +++ b/README @@ -0,0 +1,40 @@ +This package contains the Linux man pages for all chapters +except 1, 6 and 8. Some more information is given in the +`Announce' file. + +Install by copying to your favourite location. +"make install" will just copy them to /usr/share/man/man[1-8]. +"make" will move the pages from this package that are older than +the already installed ones to a subdirectory `not_installed', +then remove old versions (compressed or not), +compress the pages, and copy them to /usr/share/man/man[1-8]. + + +Note that you may have to remove preformatted pages. + +Note that sometimes these pages are duplicates of pages +also distributed in other packages. This has been reported +about dlclose.3, dlerror.3, dlopen.3, dlsym.3 (found in ld.so), +about resolver.3, resolv.conf.5 (found in bind-utils), +and about passwd.5, and mailaddr.7. Be careful not to +overwrite more up-to-date versions. +Reports on further duplicates are welcome. +Formerly present and now removed duplicates: + *_module.2, get_kernel_syms.2 (found in modutils-2.1.*), + exports.5 (found in nfs-server-2.2*), + fstab.5, nfs.5 (found in util-linux-2.12*), + lilo.8, lilo.conf.5 (found in lilo-21.6*). + +Note that the pages that come with GNU fileutils are really +help texts (indeed, are generated automatically from help texts), +and worse than worthless. Without them people would have good +detailed man pages, such as those found here in man1. +As it is, many distributions install these "man pages", +to the detriment of their users. + +Copyrights: These man pages come under various copyrights. +For the POSIX pages, see the file POSIX-COPYRIGHT. +All other pages are freely distributable when the nroff source is included. + +Send corrections and additions to mtk-manpages@gmx.net +(man.7 has some info on the macros to use). diff --git a/man-pages-1.70.Announce b/man-pages-1.70.Announce new file mode 100644 index 000000000..c9f89d23d --- /dev/null +++ b/man-pages-1.70.Announce @@ -0,0 +1,109 @@ +RELEASE +After more than nine years and 64 releases, +the old Linux man page maintainer announces a last release. . . + + man-pages-1.70.tar.gz - man pages for Linux + + +NEW MAINTAINER +Michael Kerrisk has accepted to take over maintenance. (Thanks!) +Send comments and patches to + + mtk-manpages@gmx.net + + + +POSIX +This release contains a copy of the POSIX 1003.1-2003 man pages. +The directories man0p, man1p, man3p contain descriptions of the +headers, the utilities, and the functions documented in that standard. +For the copyright notice, see the file POSIX-COPYRIGHT. + +In order to use this, put in {/usr/share/misc/}man.conf{ig} or so +your favourite order of looking at these pages, for example, +MANSECT 1p:1:8:0p:3p:2:3:4:5:6:7:9:tcl:n:l:p:o +or set the MANSECT environment variable. + +OTHER PAGES +The remaining pages are most of the section 2, 3, 4, 5, 7 man pages +for Linux, and in addition section 1 man pages for the fileutils-4.0 +utilities, and section 5 and 8 man pages for the timezone utilities. + +[The latter were taken from ftp://elsie.nci.nih.gov/pub/tzcode2001a.tar.gz.] +[The section 3 man pages for the db routines have been taken from +ftp://ftp.terra.net/pub/sleepycat/db.1.86.tar.gz.] +[The rpc man pages were taken from the 4.4BSD-Lite CDROM.] + + +Differences from version 1.69: + + The man pages + + ls.1 + + chroot.2 exit_group.2 mmap.2 nanosleep.2 remap_file_pages.2 + undocumented.2 wait.2 + + HUGE_VAL.3 HUGE_VALF.3 HUGE_VALL.3 INFINITY.3 NAN.3 + dl_iterate_phdr.3 drand48_r.3 endnetgrent.3 erand48_r.3 + finite.3 finitef.3 finitel.3 fpclassify.3 gethostent.3 + gethostent_r.3 getnetgrent.3 getnetgrent_r.3 grantpt.3 + ilogb.3 ilogbf.3 ilogbl.3 innetgr.3 isalpha.3 isinf.3 + isinff.3 isinfl.3 jrand48_r.3 lcong48_r.3 ldexp.3 + logb.3 logbf.3 logbl.3 lrand48_r.3 mrand48_r.3 nrand48_r.3 + openpty.3 ptsname.3 remquo.3 remquof.3 remquol.3 resolver.3 + scalb.3 scalbf.3 scalbl.3 scalbln.3 scalblnf.3 scalblnl.3 + scalbn.3 scalbnf.3 scalbnl.3 seed48_r.3 setnetgrent.3 + significand.3 significandf.3 significandl.3 srand48_r.3 + termios.3 undocumented.3 unlockpt.3 + + resolv.conf.5 utmp.5 + + ip.7 + + ld-linux.8 ld-linux.so.8 + + are new or have been updated. Typographical or grammatical errors + have been corrected in several other places. + +Here is a breakdown of what this distribution contains: + + Section 0p = POSIX headers + Section 1p = POSIX utilities + Section 3p = POSIX functions + + Section 1 = user commands (intro, and pages not maintained by FSF) + Section 2 = system calls + Section 3 = libc calls + Section 4 = devices (e.g., hd, sd) + Section 5 = file formats and protocols (e.g., wtmp, /etc/passwd, nfs) + Section 6 = games (intro only) + Section 7 = conventions, macro packages, etc. + Section 8 = system administration (intro only) + + Usually, there are no section 1, 6 and 8 man pages because these + should be distributed with the binaries they are written for. + Sometimes Section 9 is used for man pages describing parts of the kernel. + + Note that only Section 2 is rather complete, but Section 3 contains + several hundred man pages. If you want to write some man pages, + please do so and mail them to mtk-manpages@gmx.net. + + +Copyright information: + + For the POSIX pages permission to distribute was given by IEEE + and the Open Group, see POSIX-COPYRIGHT. + + For the remaining pages, please note that these man pages are + distributed under a variety of copyright licenses. Although these + licenses permit free distribution of the nroff sources contained in + this package, commercial distribution may impose other requirements + (e.g., acknowledgement of copyright or inclusion of the raw nroff + sources with the commercial distribution). + If you distribute these man pages commercially, it is your + responsibility to figure out your obligations. (For many man pages, + these obligations require you to distribute nroff sources with any + pre-formatted man pages that you provide.) Each file that contains + nroff source for a man page also contains the author(s) name, email + address, and copyright notice. diff --git a/man-pages-1.70.lsm b/man-pages-1.70.lsm new file mode 100644 index 000000000..778d3feb6 --- /dev/null +++ b/man-pages-1.70.lsm @@ -0,0 +1,16 @@ +Begin3 +Title: Section 2, 3, 4, 5 and 7 man pages for Linux +Version: 1.70 +Entered-date: 2004-10-31 +Description: Linux and POSIX manual pages +Keywords: man pages +Author: several +Maintained-by: Andries Brouwer + Michael Kerrisk +Primary-site: ftp://ftp.win.tue.nl/pub/linux-local/manpages + 2281k man-pages-1.70.tar.gz +Alternate-site: ftp://ftp.XX.kernel.org/pub/linux/docs/manpages +Copying-policy: several; for the POSIX pages, see the file POSIX-COPYRIGHT; + the other pages are all freely distributable provided + nroff source is provided +End diff --git a/man0p/aio.h.0p b/man0p/aio.h.0p new file mode 100644 index 000000000..828cb0aff --- /dev/null +++ b/man0p/aio.h.0p @@ -0,0 +1,116 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +aio.h \- asynchronous input and output (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBaiocb\fP structure which +shall include at least the following members: +.sp +.RS +.nf + +\fBint aio_fildes \fP File descriptor. \fB +off_t aio_offset \fP File offset. \fB +volatile void *aio_buf \fP Location of buffer. \fB +size_t aio_nbytes \fP Length of transfer. \fB +int aio_reqprio \fP Request priority offset. \fB +struct sigevent aio_sigevent \fP Signal number and value. \fB +int aio_lio_opcode\fP Operation to be performed. \fB +\fP +.fi +.RE +.LP +This header shall also include the following constants: +.TP 7 +AIO_ALLDONE +A return value indicating that none of the requested operations could +be canceled since they are already complete. +.TP 7 +AIO_CANCELED +A return value indicating that all requested operations have been +canceled. +.TP 7 +AIO_NOTCANCELED +.sp +A return value indicating that some of the requested operations could +not be canceled since they are in progress. +.TP 7 +LIO_NOP +A \fIlio_listio\fP() element operation option indicating that no transfer +is +requested. +.TP 7 +LIO_NOWAIT +A \fIlio_listio\fP() synchronization operation indicating that the +calling thread +is to continue execution while the \fIlio_listio\fP() operation is +being performed, and +no notification is given when the operation is complete. +.TP 7 +LIO_READ +A \fIlio_listio\fP() element operation option requesting a read. +.TP 7 +LIO_WAIT +A \fIlio_listio\fP() synchronization operation indicating that the +calling thread +is to suspend until the \fIlio_listio\fP() operation is complete. +.TP 7 +LIO_WRITE +A \fIlio_listio\fP() element operation option requesting a write. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint aio_cancel(int, struct aiocb *); +int aio_error(const struct aiocb *); +int aio_fsync(int, struct aiocb *); +int aio_read(struct aiocb *); +ssize_t aio_return(struct aiocb *); +int aio_suspend(const struct aiocb *const[], int, + const struct timespec *); +int aio_write(struct aiocb *); +int lio_listio(int, struct aiocb *restrict const[restrict], int, + struct sigevent *restrict); +\fP +.fi +.RE +.LP +Inclusion of the \fI\fP header may make visible symbols defined +in the headers \fI\fP, \fI\fP, \fI\fP, +and \fI\fP. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , \fI\fP , \fI\fP +, the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, \fIfsync\fP(), \fIlseek\fP(), \fIread\fP(), +\fIwrite\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/assert.h.0p b/man0p/assert.h.0p new file mode 100644 index 000000000..902142bee --- /dev/null +++ b/man0p/assert.h.0p @@ -0,0 +1,58 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +assert.h \- verify program assertion +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fIassert\fP() macro. +It refers to +the macro NDEBUG which is not defined in the header. If NDEBUG is +defined as a macro name before the inclusion of this header, the +\fIassert\fP() macro shall be defined simply as: +.sp +.RS +.nf + +\fB#define assert(ignore)((void) 0) +\fP +.fi +.RE +.LP +Otherwise, the macro behaves as described in \fIassert\fP(). +.LP +The \fIassert\fP() macro shall be redefined according to the current +state of NDEBUG +each time \fI\fP is included. +.LP +The \fIassert\fP() macro shall be implemented as a macro, not as a +function. If the +macro definition is suppressed in order to access an actual function, +the behavior is undefined. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIassert\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/complex.h.0p b/man0p/complex.h.0p new file mode 100644 index 000000000..960400670 --- /dev/null +++ b/man0p/complex.h.0p @@ -0,0 +1,210 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +complex.h \- complex arithmetic +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following macros: +.TP 7 +complex +Expands to \fB_Complex\fP. +.TP 7 +_Complex_I +Expands to a constant expression of type \fBconst float _Complex\fP, +with the value of the imaginary unit (that is, a number +\fIi\fP such that \fIi\fP**2=-1). +.TP 7 +imaginary +Expands to \fB_Imaginary\fP. +.TP 7 +_Imaginary_I +Expands to a constant expression of type \fBconst float _Imaginary\fP +with the value of the imaginary unit. +.TP 7 +I +Expands to either _Imaginary_I or _Complex_I. If _Imaginary_I is not +defined, I expands to _Complex_I. +.sp +.LP +The macros imaginary and _Imaginary_I shall be defined if and only +if the implementation supports imaginary types. +.LP +An application may undefine and then, perhaps, redefine the complex, +imaginary, and I macros. +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBdouble cabs(double complex); +float cabsf(float complex); +long double cabsl(long double complex); +double complex cacos(double complex); +float complex cacosf(float complex); +double complex cacosh(double complex); +float complex cacoshf(float complex); +long double complex cacoshl(long double complex); +long double complex cacosl(long double complex); +double carg(double complex); +float cargf(float complex); +long double cargl(long double complex); +double complex casin(double complex); +float complex casinf(float complex); +double complex casinh(double complex); +float complex casinhf(float complex); +long double complex casinhl(long double complex); +long double complex casinl(long double complex); +double complex catan(double complex); +float complex catanf(float complex); +double complex catanh(double complex); +float complex catanhf(float complex); +long double complex catanhl(long double complex); +long double complex catanl(long double complex); +double complex ccos(double complex); +float complex ccosf(float complex); +double complex ccosh(double complex); +float complex ccoshf(float complex); +long double complex ccoshl(long double complex); +long double complex ccosl(long double complex); +double complex cexp(double complex); +float complex cexpf(float complex); +long double complex cexpl(long double complex); +double cimag(double complex); +float cimagf(float complex); +long double cimagl(long double complex); +double complex clog(double complex); +float complex clogf(float complex); +long double complex clogl(long double complex); +double complex conj(double complex); +float complex conjf(float complex); +long double complex conjl(long double complex); +double complex cpow(double complex, double complex); +float complex cpowf(float complex, float complex); +long double complex cpowl(long double complex, long double complex); +double complex cproj(double complex); +float complex cprojf(float complex); +long double complex cprojl(long double complex); +double creal(double complex); +float crealf(float complex); +long double creall(long double complex); +double complex csin(double complex); +float complex csinf(float complex); +double complex csinh(double complex); +float complex csinhf(float complex); +long double complex csinhl(long double complex); +long double complex csinl(long double complex); +double complex csqrt(double complex); +float complex csqrtf(float complex); +long double complex csqrtl(long double complex); +double complex ctan(double complex); +float complex ctanf(float complex); +double complex ctanh(double complex); +float complex ctanhf(float complex); +long double complex ctanhl(long double complex); +long double complex ctanl(long double complex); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Values are interpreted as radians, not degrees. +.SH RATIONALE +.LP +The choice of \fII\fP instead of \fIi\fP for the imaginary unit concedes +to the widespread use of the identifier \fIi\fP for +other purposes. The application can use a different identifier, say +\fIj\fP, for the imaginary unit by following the inclusion of +the \fI\fP header with: +.sp +.RS +.nf + +\fB#undef I +#define j _Imaginary_I +\fP +.fi +.RE +.LP +An \fII\fP suffix to designate imaginary constants is not required, +as multiplication by \fII\fP provides a sufficiently +convenient and more generally useful notation for imaginary terms. +The corresponding real type for the imaginary unit is +\fBfloat\fP, so that use of \fII\fP for algorithmic or notational +convenience will not result in widening types. +.LP +On systems with imaginary types, the application has the ability to +control whether use of the macro I introduces an imaginary +type, by explicitly defining I to be _Imaginary_I or _Complex_I. Disallowing +imaginary types is useful for some applications +intended to run on implementations without support for such types. +.LP +The macro _Imaginary_I provides a test for whether imaginary types +are supported. +.LP +The \fIcis\fP() function (\fIcos\fP(\fIx\fP) + \fII\fP*\fIsin\fP(\fIx\fP)) +was considered but rejected because its +implementation is easy and straightforward, even though some implementations +could compute sine and cosine more efficiently in +tandem. +.SH FUTURE DIRECTIONS +.LP +The following function names and the same names suffixed with \fIf\fP +or \fIl\fP are reserved for future use, and may be added +to the declarations in the \fI\fP header. +.TS C +center; lw(26) lw(26) lw(26). +T{ +.br +\fIcerf\fP() +.br +\fIcerfc\fP() +.br +\fIcexp2\fP() +.br +\ +T} T{ +.br +\fIcexpm1\fP() +.br +\fIclog10\fP() +.br +\fIclog1p\fP() +.br +\ +T} T{ +.br +\fIclog2\fP() +.br +\fIclgamma\fP() +.br +\fIctgamma\fP() +.br +\ +T} +.TE +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIcabs\fP(), +\fIcacos\fP(), \fIcacosh\fP(), \fIcarg\fP(), \fIcasin\fP(), \fIcasinh\fP(), +\fIcatan\fP(), \fIcatanh\fP(), \fIccos\fP(), \fIccosh\fP(), \fIcexp\fP(), +\fIcimag\fP(), \fIclog\fP(), \fIconj\fP(), \fIcpow\fP(), \fIcproj\fP(), +\fIcreal\fP(), \fIcsin\fP(), \fIcsinh\fP(), \fIcsqrt\fP(), \fIctan\fP(), +\fIctanh\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/cpio.h.0p b/man0p/cpio.h.0p new file mode 100644 index 000000000..1268d8e6b --- /dev/null +++ b/man0p/cpio.h.0p @@ -0,0 +1,70 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +cpio.h \- cpio archive values +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +Values needed by the \fIc_mode\fP field of the \fIcpio\fP archive +format are described as follows: +.TS C +center; l1 l1 l. +\fBName\fP \fBDescription\fP \fBValue (Octal)\fP +C_IRUSR Read by owner. 0000400 +C_IWUSR Write by owner. 0000200 +C_IXUSR Execute by owner. 0000100 +C_IRGRP Read by group. 0000040 +C_IWGRP Write by group. 0000020 +C_IXGRP Execute by group. 0000010 +C_IROTH Read by others. 0000004 +C_IWOTH Write by others. 0000002 +C_IXOTH Execute by others. 0000001 +C_ISUID Set user ID. 0004000 +C_ISGID Set group ID. 0002000 +C_ISVTX On directories, restricted deletion flag. 0001000 +C_ISDIR Directory. 0040000 +C_ISFIFO FIFO. 0010000 +C_ISREG Regular file. 0100000 +C_ISBLK Block special. 0060000 +C_ISCHR Character special. 0020000 +C_ISCTG Reserved. 0110000 +C_ISLNK Symbolic link. 0120000 +C_ISSOCK Socket. 0140000 +.TE +.LP +The header shall define the symbolic constant: +.sp +.RS +.nf + +\fBMAGIC "070707" +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Shell and Utilities volume of IEEE\ Std\ 1003.1-2001, \fIpax\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/ctype.h.0p b/man0p/ctype.h.0p new file mode 100644 index 000000000..737cbb6d1 --- /dev/null +++ b/man0p/ctype.h.0p @@ -0,0 +1,89 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +ctype.h \- character types +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +Some of the functionality described on this reference page extends +the ISO\ C standard. Applications shall define +the appropriate feature test macro (see the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, Section 2.2, The Compilation Environment) +to enable the visibility of these symbols in this +header. +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint isalnum(int); +int isalpha(int); + +int isascii(int); + +int isblank(int); +int iscntrl(int); +int isdigit(int); +int isgraph(int); +int islower(int); +int isprint(int); +int ispunct(int); +int isspace(int); +int isupper(int); +int isxdigit(int); + +int toascii(int); + +int tolower(int); +int toupper(int); +\fP +.fi +.RE +.LP +The following are defined as macros: +.sp +.RS +.nf + +\fB +int _toupper(int); +int _tolower(int); + +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIisalnum\fP(), \fIisalpha\fP(), \fIisascii\fP(), \fIiscntrl\fP(), +\fIisdigit\fP(), \fIisgraph\fP(), \fIislower\fP(), \fIisprint\fP(), +\fIispunct\fP(), \fIisspace\fP(), \fIisupper\fP(), \fIisxdigit\fP(), +\fImblen\fP(), \fImbstowcs\fP(), \fImbtowc\fP(), \fIsetlocale\fP(), +\fItoascii\fP(), \fItolower\fP(), \fI_tolower\fP(), \fItoupper\fP(), +\fI_toupper\fP(), \fIwcstombs\fP(), \fIwctomb\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/dirent.h.0p b/man0p/dirent.h.0p new file mode 100644 index 000000000..9cfa5a4cc --- /dev/null +++ b/man0p/dirent.h.0p @@ -0,0 +1,125 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +dirent.h \- format of directory entries +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The internal format of directories is unspecified. +.LP +The \fI\fP header shall define the following type: +.TP 7 +\fBDIR\fP +A type representing a directory stream. +.sp +.LP +It shall also define the structure \fBdirent\fP which shall include +the following members: +.sp +.RS +.nf + +\fB +ino_t d_ino \fP File serial number. \fB + +char d_name[] \fP Name of entry. \fB +\fP +.fi +.RE +.LP +The type \fBino_t\fP shall be defined as described in \fI\fP +\&. +.LP +The character array \fId_name\fP is of unspecified size, but the number +of bytes preceding the terminating null byte shall not +exceed {NAME_MAX}. +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint closedir(DIR *); +DIR *opendir(const char *); +struct dirent *readdir(DIR *); + +int readdir_r(DIR *restrict, struct dirent *restrict, + struct dirent **restrict); + +void rewinddir(DIR *); + +void seekdir(DIR *, long); +long telldir(DIR *); + +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Information similar to that in the \fI\fP header is contained +in a file \fI\fP in 4.2 BSD and +4.3 BSD. The equivalent in these implementations of \fBstruct dirent\fP +from this volume of IEEE\ Std\ 1003.1-2001 is +\fBstruct direct\fP. The filename was changed because the name \fI\fP +was also used in earlier implementations +to refer to definitions related to the older access method; this produced +name conflicts. The name of the structure was changed +because this volume of IEEE\ Std\ 1003.1-2001 does not completely +define what is in the structure, so it could be different +on some implementations from \fBstruct direct\fP. +.LP +The name of an array of \fBchar\fP of an unspecified size should not +be used as an lvalue. Use of: +.sp +.RS +.nf + +\fBsizeof(d_name) +\fP +.fi +.RE +.LP +is incorrect; use: +.sp +.RS +.nf + +\fBstrlen(d_name) +\fP +.fi +.RE +.LP +instead. +.LP +The array of \fBchar\fP \fId_name\fP is not a fixed size. Implementations +may need to declare \fBstruct dirent\fP with an +array size for \fId_name\fP of 1, but the actual number of characters +provided matches (or only slightly exceeds) the length of +the filename. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIclosedir\fP(), \fIopendir\fP(), \fIreaddir\fP(), \fIreaddir_r\fP(), +\fIrewinddir\fP(), \fIseekdir\fP(), \fItelldir\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/dlfcn.h.0p b/man0p/dlfcn.h.0p new file mode 100644 index 000000000..e5c45a56d --- /dev/null +++ b/man0p/dlfcn.h.0p @@ -0,0 +1,65 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +dlfcn.h \- dynamic linking +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define at least the following macros +for use in the construction of a \fIdlopen\fP() \fImode\fP argument: +.TP 7 +RTLD_LAZY +Relocations are performed at an implementation-defined time. +.TP 7 +RTLD_NOW +Relocations are performed when the object is loaded. +.TP 7 +RTLD_GLOBAL +All symbols are available for relocation processing of other modules. +.TP 7 +RTLD_LOCAL +All symbols are not made available for relocation processing by other +modules. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint dlclose(void *); +char *dlerror(void); +void *dlopen(const char *, int); +void *dlsym(void *restrict, const char *restrict); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIdlopen\fP(), +\fIdlclose\fP(), \fIdlsym\fP(), \fIdlerror\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/errno.h.0p b/man0p/errno.h.0p new file mode 100644 index 000000000..0659b449f --- /dev/null +++ b/man0p/errno.h.0p @@ -0,0 +1,290 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +errno.h \- system error numbers +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +Some of the functionality described on this reference page extends +the ISO\ C standard. Any conflict between the +requirements described here and the ISO\ C standard is unintentional. +This volume of IEEE\ Std\ 1003.1-2001 defers to +the ISO\ C standard. +.LP +The +ISO\ C standard only requires the symbols [EDOM], [EILSEQ], and [ERANGE] +to be defined. +.LP +The \fI\fP header shall provide a declaration for \fIerrno\fP +and give positive values for the following +symbolic constants. Their values shall be unique except as noted below. +.TP 7 +.B E2BIG +Argument list too long. +.TP 7 +.B EACCES +Permission denied. +.TP 7 +.B EADDRINUSE +Address in use. +.TP 7 +.B EADDRNOTAVAIL +Address not available. +.TP 7 +.B EAFNOSUPPORT +Address family not supported. +.TP 7 +.B EAGAIN +Resource unavailable, try again (may be the same value as [EWOULDBLOCK]). +.TP 7 +.B EALREADY +Connection already in progress. +.TP 7 +.B EBADF +Bad file descriptor. +.TP 7 +.B EBADMSG +Bad message. +.TP 7 +.B EBUSY +Device or resource busy. +.TP 7 +.B ECANCELED +Operation canceled. +.TP 7 +.B ECHILD +No child processes. +.TP 7 +.B ECONNABORTED +Connection aborted. +.TP 7 +.B ECONNREFUSED +Connection refused. +.TP 7 +.B ECONNRESET +Connection reset. +.TP 7 +.B EDEADLK +Resource deadlock would occur. +.TP 7 +.B EDESTADDRREQ +Destination address required. +.TP 7 +.B EDOM +Mathematics argument out of domain of function. +.TP 7 +.B EDQUOT +Reserved. +.TP 7 +.B EEXIST +File exists. +.TP 7 +.B EFAULT +Bad address. +.TP 7 +.B EFBIG +File too large. +.TP 7 +.B EHOSTUNREACH +Host is unreachable. +.TP 7 +.B EIDRM +Identifier removed. +.TP 7 +.B EILSEQ +Illegal byte sequence. +.TP 7 +.B EINPROGRESS +Operation in progress. +.TP 7 +.B EINTR +Interrupted function. +.TP 7 +.B EINVAL +Invalid argument. +.TP 7 +.B EIO +I/O error. +.TP 7 +.B EISCONN +Socket is connected. +.TP 7 +.B EISDIR +Is a directory. +.TP 7 +.B ELOOP +Too many levels of symbolic links. +.TP 7 +.B EMFILE +Too many open files. +.TP 7 +.B EMLINK +Too many links. +.TP 7 +.B EMSGSIZE +Message too large. +.TP 7 +.B EMULTIHOP +Reserved. +.TP 7 +.B ENAMETOOLONG +Filename too long. +.TP 7 +.B ENETDOWN +Network is down. +.TP 7 +.B ENETRESET +Connection aborted by network. +.TP 7 +.B ENETUNREACH +Network unreachable. +.TP 7 +.B ENFILE +Too many files open in system. +.TP 7 +.B ENOBUFS +No buffer space available. +.TP 7 +.B ENODATA +No message is available on the STREAM head read queue. +.TP 7 +.B ENODEV +No such device. +.TP 7 +.B ENOENT +No such file or directory. +.TP 7 +.B ENOEXEC +Executable file format error. +.TP 7 +.B ENOLCK +No locks available. +.TP 7 +.B ENOLINK +Reserved. +.TP 7 +.B ENOMEM +Not enough space. +.TP 7 +.B ENOMSG +No message of the desired type. +.TP 7 +.B ENOPROTOOPT +Protocol not available. +.TP 7 +.B ENOSPC +No space left on device. +.TP 7 +.B ENOSR +No STREAM resources. +.TP 7 +.B ENOSTR +Not a STREAM. +.TP 7 +.B ENOSYS +Function not supported. +.TP 7 +.B ENOTCONN +The socket is not connected. +.TP 7 +.B ENOTDIR +Not a directory. +.TP 7 +.B ENOTEMPTY +Directory not empty. +.TP 7 +.B ENOTSOCK +Not a socket. +.TP 7 +.B ENOTSUP +Not supported. +.TP 7 +.B ENOTTY +Inappropriate I/O control operation. +.TP 7 +.B ENXIO +No such device or address. +.TP 7 +.B EOPNOTSUPP +Operation not supported on socket. +.TP 7 +.B EOVERFLOW +Value too large to be stored in data type. +.TP 7 +.B EPERM +Operation not permitted. +.TP 7 +.B EPIPE +Broken pipe. +.TP 7 +.B EPROTO +Protocol error. +.TP 7 +.B EPROTONOSUPPORT +.sp +Protocol not supported. +.TP 7 +.B EPROTOTYPE +Protocol wrong type for socket. +.TP 7 +.B ERANGE +Result too large. +.TP 7 +.B EROFS +Read-only file system. +.TP 7 +.B ESPIPE +Invalid seek. +.TP 7 +.B ESRCH +No such process. +.TP 7 +.B ESTALE +Reserved. +.TP 7 +.B ETIME +Stream \fIioctl\fP() timeout. +.TP 7 +.B ETIMEDOUT +Connection timed out. +.TP 7 +.B ETXTBSY +Text file busy. +.TP 7 +.B EWOULDBLOCK +Operation would block (may be the same value as [EAGAIN]). +.TP 7 +.B EXDEV +Cross-device link. +.sp +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Additional error numbers may be defined on conforming systems; see +the System Interfaces volume of +IEEE\ Std\ 1003.1-2001. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, Section 2.3, +Error +Numbers +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/fcntl.h.0p b/man0p/fcntl.h.0p new file mode 100644 index 000000000..2e7839856 --- /dev/null +++ b/man0p/fcntl.h.0p @@ -0,0 +1,222 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +fcntl.h \- file control options +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following requests and +arguments for use by the functions \fIfcntl\fP() and \fIopen\fP(). +.LP +Values for \fIcmd\fP used by \fIfcntl\fP() (the following values are +unique) are as +follows: +.TP 7 +F_DUPFD +Duplicate file descriptor. +.TP 7 +F_GETFD +Get file descriptor flags. +.TP 7 +F_SETFD +Set file descriptor flags. +.TP 7 +F_GETFL +Get file status flags and file access modes. +.TP 7 +F_SETFL +Set file status flags. +.TP 7 +F_GETLK +Get record locking information. +.TP 7 +F_SETLK +Set record locking information. +.TP 7 +F_SETLKW +Set record locking information; wait if blocked. +.TP 7 +F_GETOWN +Get process or process group ID to receive SIGURG signals. +.TP 7 +F_SETOWN +Set process or process group ID to receive SIGURG signals. +.sp +.LP +File descriptor flags used for \fIfcntl\fP() are as follows: +.TP 7 +FD_CLOEXEC +Close the file descriptor upon execution of an \fIexec\fP family function. +.sp +.LP +Values for \fIl_type\fP used for record locking with \fIfcntl\fP() +(the following values +are unique) are as follows: +.TP 7 +F_RDLCK +Shared or read lock. +.TP 7 +F_UNLCK +Unlock. +.TP 7 +F_WRLCK +Exclusive or write lock. +.sp +.LP +The values used for \fIl_whence\fP, SEEK_SET, SEEK_CUR, and SEEK_END +shall be defined as described in \fI\fP . +.LP +The following values are file creation flags and are used in the \fIoflag\fP +value to \fIopen\fP(). They shall be bitwise-distinct. +.TP 7 +O_CREAT +Create file if it does not exist. +.TP 7 +O_EXCL +Exclusive use flag. +.TP 7 +O_NOCTTY +Do not assign controlling terminal. +.TP 7 +O_TRUNC +Truncate flag. +.sp +.LP +File status flags used for \fIopen\fP() and \fIfcntl\fP() are as follows: +.TP 7 +O_APPEND +Set append mode. +.TP 7 +O_DSYNC +Write according to synchronized I/O data integrity completion. +.TP 7 +O_NONBLOCK +Non-blocking mode. +.TP 7 +O_RSYNC +Synchronized read I/O operations. +.TP 7 +O_SYNC +Write according to synchronized I/O file integrity completion. +.sp +.LP +Mask for use with file access modes is as follows: +.TP 7 +O_ACCMODE +Mask for file access modes. +.sp +.LP +File access modes used for \fIopen\fP() and \fIfcntl\fP() are as follows: +.TP 7 +O_RDONLY +Open for reading only. +.TP 7 +O_RDWR +Open for reading and writing. +.TP 7 +O_WRONLY +Open for writing only. +.sp +.LP +The symbolic names for file modes for use as values of \fBmode_t\fP +shall be defined as described in \fI\fP . +.LP +Values for \fIadvice\fP used by \fIposix_fadvise\fP() are as follows: +.TP 7 +POSIX_FADV_NORMAL +.sp +The application has no advice to give on its behavior with respect +to the specified data. It is the default characteristic if no +advice is given for an open file. +.TP 7 +POSIX_FADV_SEQUENTIAL +.sp +The application expects to access the specified data sequentially +from lower offsets to higher offsets. +.TP 7 +POSIX_FADV_RANDOM +.sp +The application expects to access the specified data in a random order. +.TP 7 +POSIX_FADV_WILLNEED +.sp +The application expects to access the specified data in the near future. +.TP 7 +POSIX_FADV_DONTNEED +.sp +The application expects that it will not access the specified data +in the near future. +.TP 7 +POSIX_FADV_NOREUSE +.sp +The application expects to access the specified data once and then +not reuse it thereafter. +.sp +.LP +The structure \fBflock\fP describes a file lock. It shall include +the following members: +.sp +.RS +.nf + +\fBshort l_type \fP Type of lock; F_RDLCK, F_WRLCK, F_UNLCK. \fB +short l_whence\fP Flag for starting offset. \fB +off_t l_start \fP Relative offset in bytes. \fB +off_t l_len \fP Size; if 0 then until EOF. \fB +pid_t l_pid \fP Process ID of the process holding the lock; returned with F_GETLK. \fB +\fP +.fi +.RE +.LP +The \fBmode_t\fP, \fBoff_t\fP, and \fBpid_t\fP types shall be defined +as described in \fI\fP . +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint creat(const char *, mode_t); +int fcntl(int, int, ...); +int open(const char *, int, ...); + +int posix_fadvise(int, off_t, size_t, int); +int posix_fallocate(int, off_t, size_t); + +\fP +.fi +.RE +.LP +Inclusion of the \fI\fP header may also make visible all +symbols from \fI\fP and \fI\fP. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , \fI\fP , the +System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIcreat\fP(), +\fIexec\fP, \fIfcntl\fP(), \fIopen\fP(), \fIposix_fadvise\fP(), \fIposix_fallocate\fP(), +\fIposix_madvise\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/fenv.h.0p b/man0p/fenv.h.0p new file mode 100644 index 000000000..550806749 --- /dev/null +++ b/man0p/fenv.h.0p @@ -0,0 +1,247 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +fenv.h \- floating-point environment +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following data types through +\fBtypedef\fP: +.TP 7 +\fBfenv_t\fP +Represents the entire floating-point environment. The floating-point +environment refers collectively to any floating-point +status flags and control modes supported by the implementation. +.TP 7 +\fBfexcept_t\fP +Represents the floating-point status flags collectively, including +any status the implementation associates with the flags. A +floating-point status flag is a system variable whose value is set +(but never cleared) when a floating-point exception is raised, +which occurs as a side effect of exceptional floating-point arithmetic +to provide auxiliary information. A floating-point control +mode is a system variable whose value may be set by the user to affect +the subsequent behavior of floating-point arithmetic. +.sp +.LP +The \fI\fP header shall define the following constants if +and only if the implementation supports the +floating-point exception by means of the floating-point functions +\fIfeclearexcept\fP(), \fIfegetexceptflag\fP(), \fIferaiseexcept\fP(), +\fIfesetexceptflag\fP(), and \fIfetestexcept\fP(). Each expands to +an integer constant expression with values such that +bitwise-inclusive ORs of all combinations of the constants result +in distinct values. +.sp +.RS +.nf + +FE_DIVBYZERO +FE_INEXACT +FE_INVALID +FE_OVERFLOW +FE_UNDERFLOW +.fi +.RE +.LP +The \fI\fP header shall define the following constant, which +is simply the bitwise-inclusive OR of all +floating-point exception constants defined above: +.sp +.RS +.nf + +FE_ALL_EXCEPT +.fi +.RE +.LP +The \fI\fP header shall define the following constants if +and only if the implementation supports getting and +setting the represented rounding direction by means of the \fIfegetround\fP() +and \fIfesetround\fP() functions. Each expands to an integer constant +expression whose values +are distinct non-negative vales. +.sp +.RS +.nf + +FE_DOWNWARD +FE_TONEAREST +FE_TOWARDZERO +FE_UPWARD +.fi +.RE +.LP +The \fI\fP header shall define the following constant, which +represents the default floating-point environment +(that is, the one installed at program startup) and has type pointer +to const-qualified \fBfenv_t\fP. It can be used as an +argument to the functions within the \fI\fP header that manage +the floating-point environment. +.sp +.RS +.nf + +FE_DFL_ENV +.fi +.RE +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint feclearexcept(int); +int fegetexceptflag(fexcept_t *, int); +int feraiseexcept(int); +int fesetexceptflag(const fexcept_t *, int); +int fetestexcept(int); +int fegetround(void); +int fesetround(int); +int fegetenv(fenv_t *); +int feholdexcept(fenv_t *); +int fesetenv(const fenv_t *); +int feupdateenv(const fenv_t *); +\fP +.fi +.RE +.LP +The FENV_ACCESS pragma provides a means to inform the implementation +when an application might access the floating-point +environment to test floating-point status flags or run under non-default +floating-point control modes. The pragma shall occur +either outside external declarations or preceding all explicit declarations +and statements inside a compound statement. When +outside external declarations, the pragma takes effect from its occurrence +until another FENV_ACCESS pragma is encountered, or +until the end of the translation unit. When inside a compound statement, +the pragma takes effect from its occurrence until another +FENV_ACCESS pragma is encountered (including within a nested compound +statement), or until the end of the compound statement; at +the end of a compound statement the state for the pragma is restored +to its condition just before the compound statement. If this +pragma is used in any other context, the behavior is undefined. If +part of an application tests floating-point status flags, sets +floating-point control modes, or runs under non-default mode settings, +but was translated with the state for the FENV_ACCESS pragma +off, the behavior is undefined. The default state (on or off) for +the pragma is implementation-defined. (When execution passes from +a part of the application translated with FENV_ACCESS off to a part +translated with FENV_ACCESS on, the state of the floating-point +status flags is unspecified and the floating-point control modes have +their default settings.) +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +This header is designed to support the floating-point exception status +flags and directed-rounding control modes required by the +IEC\ 60559:1989 standard, and other similar floating-point state information. +Also it is designed to facilitate code +portability among all systems. +.LP +Certain application programming conventions support the intended model +of use for the floating-point environment: +.IP " *" 3 +A function call does not alter its caller's floating-point control +modes, clear its caller's floating-point status flags, nor +depend on the state of its caller's floating-point status flags unless +the function is so documented. +.LP +.IP " *" 3 +A function call is assumed to require default floating-point control +modes, unless its documentation promises otherwise. +.LP +.IP " *" 3 +A function call is assumed to have the potential for raising floating-point +exceptions, unless its documentation promises +otherwise. +.LP +.LP +With these conventions, an application can safely assume default floating-point +control modes (or be unaware of them). The +responsibilities associated with accessing the floating-point environment +fall on the application that does so explicitly. +.LP +Even though the rounding direction macros may expand to constants +corresponding to the values of FLT_ROUNDS, they are not +required to do so. +.LP +For example: +.sp +.RS +.nf + +\fB#include +void f(double x) +{ + #pragma STDC FENV_ACCESS ON + void g(double); + void h(double); + /* ... */ + g(x + 1); + h(x + 1); + /* ... */ +} +\fP +.fi +.RE +.LP +If the function \fIg\fP() might depend on status flags set as a side +effect of the first \fIx\fP+1, or if the second +\fIx\fP+1 might depend on control modes set as a side effect of the +call to function \fIg\fP(), then the application shall +contain an appropriately placed invocation as follows: +.sp +.RS +.nf + +\fB#pragma STDC FENV_ACCESS ON +\fP +.fi +.RE +.SH RATIONALE +.SS The fexcept_t Type +.LP +\fBfexcept_t\fP does not have to be an integer type. Its values must +be obtained by a call to \fIfegetexceptflag\fP(), and cannot be created +by logical operations from the exception +macros. An implementation might simply implement \fBfexcept_t\fP as +an \fBint\fP and use the representations reflected by the +exception macros, but is not required to; other representations might +contain extra information about the exceptions. +\fBfexcept_t\fP might be a \fBstruct\fP with a member for each exception +(that might hold the address of the first or last +floating-point instruction that caused that exception). The ISO/IEC\ 9899:1999 +standard makes no claims about the internals of +an \fBfexcept_t\fP, and so the user cannot inspect it. +.SS Exception and Rounding Macros +.LP +Macros corresponding to unsupported modes and rounding directions +are not defined by the implementation and must not be defined +by the application. An application might use \fB#ifdef\fP to test +for this. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIfeclearexcept\fP(), +\fIfegetenv\fP(), \fIfegetexceptflag\fP(), \fIfegetround\fP(), +\fIfeholdexcept\fP(), \fIferaiseexcept\fP(), \fIfesetenv\fP(), \fIfesetexceptflag\fP(), +\fIfesetround\fP(), +\fIfetestexcept\fP(), \fIfeupdateenv\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/float.h.0p b/man0p/float.h.0p new file mode 100644 index 000000000..28563691a --- /dev/null +++ b/man0p/float.h.0p @@ -0,0 +1,328 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +float.h \- floating types +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The characteristics of floating types are defined in terms of a model +that describes a representation of floating-point numbers +and values that provide information about an implementation's floating-point +arithmetic. +.LP +The following parameters are used to define the model for each floating-point +type: +.TP 7 +\fIs\fP +Sign (\(+-1). +.TP 7 +\fIb\fP +Base or radix of exponent representation (an integer >1). +.TP 7 +\fIe\fP +Exponent (an integer between a minimum \fIe\fP_min and a maximum \fIe\fP_max). +.TP 7 +\fIp\fP +Precision (the number of base-\fIb\fP digits in the significand). +.TP 7 +\fIf\fP_k +Non-negative integers less than \fIb\fP (the significand digits). +.sp +.LP +A floating-point number \fIx\fP is defined by the following model: +.LP +.LP +In addition to normalized floating-point numbers (\fIf\fP_1>0 if \fIx\fP!=0), +floating types may be able to contain other +kinds of floating-point numbers, such as subnormal floating-point +numbers ( \fIx\fP!=0, \fIe\fP= \fIe\fP_min, \fIf\fP_1=0) and +unnormalized floating-point numbers ( \fIx\fP!=0, \fIe\fP> \fIe\fP_min, +\fIf\fP_1=0), and values that are not floating-point +numbers, such as infinities and NaNs. A \fINaN\fP is an encoding signifying +Not-a-Number. A \fIquiet NaN\fP propagates through +almost every arithmetic operation without raising a floating-point +exception; a \fIsignaling NaN\fP generally raises a +floating-point exception when occurring as an arithmetic operand. +.LP +The accuracy of the floating-point operations ( \fB'+'\fP , \fB'-'\fP +, \fB'*'\fP , \fB'/'\fP ) and of the library +functions in \fI\fP and \fI\fP that return floating-point +results is implementation-defined. The +implementation may state that the accuracy is unknown. +.LP +All integer values in the \fI\fP header, except FLT_ROUNDS, +shall be constant expressions suitable for use in +\fB#if\fP preprocessing directives; all floating values shall be constant +expressions. All except DECIMAL_DIG, FLT_EVAL_METHOD, +FLT_RADIX, and FLT_ROUNDS have separate names for all three floating-point +types. The floating-point model representation is +provided for all values except FLT_EVAL_METHOD and FLT_ROUNDS. +.LP +The rounding mode for floating-point addition is characterized by +the implementation-defined value of FLT_ROUNDS: +.TP 7 +-1 +Indeterminable. +.TP 7 +\ 0 +Toward zero. +.TP 7 +\ 1 +To nearest. +.TP 7 +\ 2 +Toward positive infinity. +.TP 7 +\ 3 +Toward negative infinity. +.sp +.LP +All other values for FLT_ROUNDS characterize implementation-defined +rounding behavior. +.LP +The values of operations with floating operands and values subject +to the usual arithmetic conversions and of floating constants +are evaluated to a format whose range and precision may be greater +than required by the type. The use of evaluation formats is +characterized by the implementation-defined value of FLT_EVAL_METHOD: +.TP 7 +-1 +Indeterminable. +.TP 7 +\ 0 +Evaluate all operations and constants just to the range and precision +of the type. +.TP 7 +\ 1 +Evaluate operations and constants of type \fBfloat\fP and \fBdouble\fP +to the range and precision of the \fBdouble\fP type; +evaluate \fBlong double\fP operations and constants to the range and +precision of the \fBlong double\fP type. +.TP 7 +\ 2 +Evaluate all operations and constants to the range and precision of +the \fBlong double\fP type. +.sp +.LP +All other negative values for FLT_EVAL_METHOD characterize implementation-defined +behavior. +.LP +The values given in the following list shall be defined as constant +expressions with implementation-defined values that are +greater or equal in magnitude (absolute value) to those shown, with +the same sign. +.IP " *" 3 +Radix of exponent representation, \fIb\fP. +.TP 7 +FLT_RADIX +.RS +2 +.RE +.sp +.LP +.IP " *" 3 +Number of base-FLT_RADIX digits in the floating-point significand, +\fIp\fP. +.TP 7 +FLT_MANT_DIG +.TP 7 +DBL_MANT_DIG +.TP 7 +LDBL_MANT_DIG +.sp +.LP +.IP " *" 3 +Number of decimal digits, \fIn\fP, such that any floating-point number +in the widest supported floating type with \fIp\fP_max +radix \fIb\fP digits can be rounded to a floating-point number with +\fIn\fP decimal digits and back again without change to the +value. +.LP +.TP 7 +DECIMAL_DIG +.RS +10 +.RE +.sp +.LP +.IP " *" 3 +Number of decimal digits, \fIq\fP, such that any floating-point number +with \fIq\fP decimal digits can be rounded into a +floating-point number with \fIp\fP radix \fIb\fP digits and back again +without change to the \fIq\fP decimal digits. +.LP +.TP 7 +FLT_DIG +.RS +6 +.RE +.TP 7 +DBL_DIG +.RS +10 +.RE +.TP 7 +LDBL_DIG +.RS +10 +.RE +.sp +.LP +.IP " *" 3 +Minimum negative integer such that FLT_RADIX raised to that power +minus 1 is a normalized floating-point number, \fIe\fP_min. +.TP 7 +FLT_MIN_EXP +.TP 7 +DBL_MIN_EXP +.TP 7 +LDBL_MIN_EXP +.sp +.LP +.IP " *" 3 +Minimum negative integer such that 10 raised to that power is in the +range of normalized floating-point numbers. +.LP +.TP 7 +FLT_MIN_10_EXP +.RS +-37 +.RE +.TP 7 +DBL_MIN_10_EXP +.RS +-37 +.RE +.TP 7 +LDBL_MIN_10_EXP +.RS +-37 +.RE +.sp +.LP +.IP " *" 3 +Maximum integer such that FLT_RADIX raised to that power minus 1 is +a representable finite floating-point number, \fIe\fP_max. +.TP 7 +FLT_MAX_EXP +.TP 7 +DBL_MAX_EXP +.TP 7 +LDBL_MAX_EXP +.sp +.LP +.IP " *" 3 +Maximum integer such that 10 raised to that power is in the range +of representable finite floating-point numbers. +.LP +.TP 7 +FLT_MAX_10_EXP +.RS ++37 +.RE +.TP 7 +DBL_MAX_10_EXP +.RS ++37 +.RE +.TP 7 +LDBL_MAX_10_EXP +.RS ++37 +.RE +.sp +.LP +.LP +The values given in the following list shall be defined as constant +expressions with implementation-defined values that are +greater than or equal to those shown: +.IP " *" 3 +Maximum representable finite floating-point number. +.LP +.TP 7 +FLT_MAX +.RS +1E+37 +.RE +.TP 7 +DBL_MAX +.RS +1E+37 +.RE +.TP 7 +LDBL_MAX +.RS +1E+37 +.RE +.sp +.LP +.LP +The values given in the following list shall be defined as constant +expressions with implementation-defined (positive) values +that are less than or equal to those shown: +.IP " *" 3 +The difference between 1 and the least value greater than 1 that is +representable in the given floating-point type, \fIb\fP**1-\fIp\fP. +.TP 7 +FLT_EPSILON +.RS +1E-5 +.RE +.TP 7 +DBL_EPSILON +.RS +1E-9 +.RE +.TP 7 +LDBL_EPSILON +.RS +1E-9 +.RE +.sp +.LP +.IP " *" 3 +Minimum normalized positive floating-point number, \fIb\fP**\fIe\fP_min. +.TP 7 +FLT_MIN +.RS +1E-37 +.RE +.TP 7 +DBL_MIN +.RS +1E-37 +.RE +.TP 7 +LDBL_MIN +.RS +1E-37 +.RE +.sp +.LP +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/fmtmsg.h.0p b/man0p/fmtmsg.h.0p new file mode 100644 index 000000000..46717bed4 --- /dev/null +++ b/man0p/fmtmsg.h.0p @@ -0,0 +1,129 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +fmtmsg.h \- message display structures +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following macros, which +expand to constant integer expressions: +.TP 7 +MM_HARD +Source of the condition is hardware. +.TP 7 +MM_SOFT +Source of the condition is software. +.TP 7 +MM_FIRM +Source of the condition is firmware. +.TP 7 +MM_APPL +Condition detected by application. +.TP 7 +MM_UTIL +Condition detected by utility. +.TP 7 +MM_OPSYS +Condition detected by operating system. +.TP 7 +MM_RECOVER +Recoverable error. +.TP 7 +MM_NRECOV +Non-recoverable error. +.TP 7 +MM_HALT +Error causing application to halt. +.TP 7 +MM_ERROR +Application has encountered a non-fatal fault. +.TP 7 +MM_WARNING +Application has detected unusual non-error condition. +.TP 7 +MM_INFO +Informative message. +.TP 7 +MM_NOSEV +No severity level provided for the message. +.TP 7 +MM_PRINT +Display message on standard error. +.TP 7 +MM_CONSOLE +Display message on system console. +.sp +.LP +The table below indicates the null values and identifiers for \fIfmtmsg\fP() +arguments. +The \fI\fP header shall define the macros in the \fBIdentifier\fP +column, which expand to constant expressions +that expand to expressions of the type indicated in the \fBType\fP +column: +.TS C +center; l l l l. +\fBArgument\fP \fBType\fP \fBNull-Value\fP \fBIdentifier\fP +\fIlabel\fP \fBchar *\fP (\fBchar\fP*)0 MM_NULLLBL +\fIseverity\fP \fBint\fP 0 MM_NULLSEV +\fIclass\fP \fBlong\fP \fB0L\fP MM_NULLMC +\fItext\fP \fBchar *\fP (\fBchar\fP*)0 MM_NULLTXT +\fIaction\fP \fBchar *\fP (\fBchar\fP*)0 MM_NULLACT +\fItag\fP \fBchar *\fP (\fBchar\fP*)0 MM_NULLTAG +.TE +.LP +The \fI\fP header shall also define the following macros +for use as return values for \fIfmtmsg\fP(): +.TP 7 +MM_OK +The function succeeded. +.TP 7 +MM_NOTOK +The function failed completely. +.TP 7 +MM_NOMSG +The function was unable to generate a message on standard error, but +otherwise succeeded. +.TP 7 +MM_NOCON +The function was unable to generate a console message, but otherwise +succeeded. +.sp +.LP +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS +.nf + +\fBint fmtmsg(long, const char *, int, + const char *, const char *, const char *); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIfmtmsg\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/fnmatch.h.0p b/man0p/fnmatch.h.0p new file mode 100644 index 000000000..8deb8fd70 --- /dev/null +++ b/man0p/fnmatch.h.0p @@ -0,0 +1,65 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +fnmatch.h \- filename-matching types +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following constants: +.TP 7 +FNM_NOMATCH +The string does not match the specified pattern. +.TP 7 +FNM_PATHNAME +Slash in \fIstring\fP only matches slash in \fIpattern\fP. +.TP 7 +FNM_PERIOD +Leading period in \fIstring\fP must be exactly matched by period in +\fIpattern\fP. +.TP 7 +FNM_NOESCAPE +Disable backslash escaping. +.TP 7 +FNM_NOSYS +Reserved. +.sp +.LP +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS +.nf + +\fBint fnmatch(const char *, const char *, int); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIfnmatch\fP(), +the +Shell and Utilities volume of IEEE\ Std\ 1003.1-2001 +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/ftw.h.0p b/man0p/ftw.h.0p new file mode 100644 index 000000000..08151a0af --- /dev/null +++ b/man0p/ftw.h.0p @@ -0,0 +1,111 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +ftw.h \- file tree traversal +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBFTW\fP structure that +includes at least the following members: +.sp +.RS +.nf + +\fBint base +int level +\fP +.fi +.RE +.LP +The \fI\fP header shall define macros for use as values of +the third argument to the application-supplied function +that is passed as the second argument to \fIftw\fP() and \fInftw\fP(): +.TP 7 +FTW_F +File. +.TP 7 +FTW_D +Directory. +.TP 7 +FTW_DNR +Directory without read permission. +.TP 7 +FTW_DP +Directory with subdirectories visited. +.TP 7 +FTW_NS +Unknown type; \fIstat\fP() failed. +.TP 7 +FTW_SL +Symbolic link. +.TP 7 +FTW_SLN +Symbolic link that names a nonexistent file. +.sp +.LP +The \fI\fP header shall define macros for use as values of +the fourth argument to \fInftw\fP(): +.TP 7 +FTW_PHYS +Physical walk, does not follow symbolic links. Otherwise, \fInftw\fP() +follows links but +does not walk down any path that crosses itself. +.TP 7 +FTW_MOUNT +The walk does not cross a mount point. +.TP 7 +FTW_DEPTH +All subdirectories are visited before the directory itself. +.TP 7 +FTW_CHDIR +The walk changes to each directory before reading it. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint ftw(const char *, int (*)(const char *, const struct stat *, + int), int); +int nftw(const char *, int (*)(const char *, const struct stat *, + int, struct FTW*), int, int); +\fP +.fi +.RE +.LP +The \fI\fP header shall define the \fBstat\fP structure and +the symbolic names for \fIst_mode\fP and the file +type test macros as described in \fI\fP . +.LP +Inclusion of the \fI\fP header may also make visible all symbols +from \fI\fP. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIftw\fP(), \fInftw\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/glob.h.0p b/man0p/glob.h.0p new file mode 100644 index 000000000..35338af09 --- /dev/null +++ b/man0p/glob.h.0p @@ -0,0 +1,111 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +glob.h \- pathname pattern-matching types +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the structures and symbolic +constants used by the \fIglob\fP() function. +.LP +The structure type \fBglob_t\fP shall contain at least the following +members: +.sp +.RS +.nf + +\fBsize_t gl_pathc\fP Count of paths matched by \fIpattern.\fP \fB +char **gl_pathv\fP Pointer to a list of matched pathnames. \fB +size_t gl_offs \fP Slots to reserve at the beginning of \fIgl_pathv.\fP \fB +\fP +.fi +.RE +.LP +The following constants shall be provided as values for the \fIflags\fP +argument: +.TP 7 +GLOB_APPEND +Append generated pathnames to those previously obtained. +.TP 7 +GLOB_DOOFFS +Specify how many null pointers to add to the beginning of \fIgl_pathv\fP. +.TP 7 +GLOB_ERR +Cause \fIglob\fP() to return on error. +.TP 7 +GLOB_MARK +Each pathname that is a directory that matches \fIpattern\fP has a +slash appended. +.TP 7 +GLOB_NOCHECK +If \fIpattern\fP does not match any pathname, then return a list consisting +of only \fIpattern\fP. +.TP 7 +GLOB_NOESCAPE +Disable backslash escaping. +.TP 7 +GLOB_NOSORT +Do not sort the pathnames returned. +.sp +.LP +The following constants shall be defined as error return values: +.TP 7 +GLOB_ABORTED +The scan was stopped because GLOB_ERR was set or (*\fIerrfunc\fP)() +returned non-zero. +.TP 7 +GLOB_NOMATCH +The pattern does not match any existing pathname, and GLOB_NOCHECK +was not set in \fIflags\fP. +.TP 7 +GLOB_NOSPACE +An attempt to allocate memory failed. +.TP 7 +GLOB_NOSYS +Reserved. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint glob(const char *restrict, int, int (*)(const char *, int), + glob_t *restrict); +void globfree (glob_t *); +\fP +.fi +.RE +.LP +The implementation may define additional macros or constants using +names beginning with GLOB_. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIglob\fP(), +the Shell +and Utilities volume of IEEE\ Std\ 1003.1-2001 +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/grp.h.0p b/man0p/grp.h.0p new file mode 100644 index 000000000..914750d30 --- /dev/null +++ b/man0p/grp.h.0p @@ -0,0 +1,74 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +grp.h \- group structure +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall declare the structure \fBgroup\fP which +shall include the following members: +.sp +.RS +.nf + +\fBchar *gr_name\fP The name of the group. \fB +gid_t gr_gid \fP Numerical group ID. \fB +char **gr_mem \fP Pointer to a null-terminated array of character \fB + \fP pointers to member names. \fB +\fP +.fi +.RE +.LP +The \fBgid_t\fP type shall be defined as described in \fI\fP +\&. +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBstruct group *getgrgid(gid_t); +struct group *getgrnam(const char *); + +int getgrgid_r(gid_t, struct group *, char *, + size_t, struct group **); +int getgrnam_r(const char *, struct group *, char *, + size_t , struct group **); + + +struct group *getgrent(void); +void endgrent(void); +void setgrent(void); + +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIendgrent\fP(), \fIgetgrgid\fP(), \fIgetgrnam\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/iconv.h.0p b/man0p/iconv.h.0p new file mode 100644 index 000000000..42994d9d0 --- /dev/null +++ b/man0p/iconv.h.0p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +iconv.h \- codeset conversion facility +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following type: +.TP 7 +\fBiconv_t\fP +Identifies the conversion from one codeset to another. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBiconv_t iconv_open(const char *, const char *); +size_t iconv(iconv_t, char **restrict, size_t *restrict, + char **restrict, size_t *restrict); +int iconv_close(iconv_t); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIiconv\fP(), +\fIiconv_close\fP(), \fIiconv_open\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/if.h.0p b/man0p/if.h.0p new file mode 100644 index 000000000..321e2faa1 --- /dev/null +++ b/man0p/if.h.0p @@ -0,0 +1,69 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +net/if.h \- sockets local interfaces +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBif_nameindex\fP structure +that includes at least the following +members: +.sp +.RS +.nf + +\fBunsigned if_index \fP Numeric index of the interface. \fB +char *if_name \fP Null-terminated name of the interface. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the following macro for the +length of a buffer containing an interface name +(including the terminating NULL character): +.TP 7 +IF_NAMESIZE +Interface name length. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBunsigned if_nametoindex(const char *); +char *if_indextoname(unsigned, char *); +struct if_nameindex *if_nameindex(void); +void if_freenameindex(struct if_nameindex *); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIif_freenameindex\fP(), +\fIif_indextoname\fP(), \fIif_nameindex\fP(), \fIif_nametoindex\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/in.h.0p b/man0p/in.h.0p new file mode 100644 index 000000000..e0a6a8c90 --- /dev/null +++ b/man0p/in.h.0p @@ -0,0 +1,315 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +netinet/in.h \- Internet address family +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following types: +.TP 7 +\fBin_port_t\fP +Equivalent to the type \fBuint16_t\fP as defined in \fI\fP +\&. +.TP 7 +\fBin_addr_t\fP +Equivalent to the type \fBuint32_t\fP as defined in \fI\fP +\&. +.sp +.LP +The \fBsa_family_t\fP type shall be defined as described in \fI\fP +\&. +.LP +The \fBuint8_t\fP and \fBuint32_t\fP type shall be defined as described +in \fI\fP. Inclusion of the \fI\fP header +may also make +visible all symbols from \fI\fP and \fI\fP. +.LP +The \fI\fP header shall define the \fBin_addr\fP structure +that includes at least the following +member: +.sp +.RS +.nf + +\fBin_addr_t s_addr +\fP +.fi +.RE +.LP +The \fI\fP header shall define the \fBsockaddr_in\fP +structure that includes at least the following +members (all in network byte order): +.sp +.RS +.nf + +\fBsa_family_t sin_family \fP AF_INET. \fB +in_port_t sin_port \fP Port number. \fB +struct in_addr sin_addr \fP IP address. \fB +\fP +.fi +.RE +.LP +The \fBsockaddr_in\fP structure is used to store addresses for the +Internet address family. Values of this type shall be cast +by applications to \fBstruct sockaddr\fP for use with socket functions. +.LP +The \fI\fP header shall define the \fBin6_addr\fP structure +that contains at least the following +member: +.sp +.RS +.nf + +\fBuint8_t s6_addr[16] +\fP +.fi +.RE +.LP +This array is used to contain a 128-bit IPv6 address, stored in network +byte order. +.LP +The \fI\fP header shall define the \fBsockaddr_in6\fP +structure that includes at least the following +members (all in network byte order): +.sp +.RS +.nf + +\fBsa_family_t sin6_family \fP AF_INET6. \fB +in_port_t sin6_port \fP Port number. \fB +uint32_t sin6_flowinfo \fP IPv6 traffic class and flow information. \fB +struct in6_addr sin6_addr \fP IPv6 address. \fB +uint32_t sin6_scope_id \fP Set of interfaces for a scope. \fB +\fP +.fi +.RE +.LP +The \fBsockaddr_in6\fP structure shall be set to zero by an application +prior to using it, since implementations are free to +have additional, implementation-defined fields in \fBsockaddr_in6\fP. +.LP +The \fIsin6_scope_id\fP field is a 32-bit integer that identifies +a set of interfaces as appropriate for the scope of the +address carried in the \fIsin6_addr\fP field. For a link scope \fIsin6_addr\fP, +the application shall ensure that +\fIsin6_scope_id\fP is a link index. For a site scope \fIsin6_addr\fP, +the application shall ensure that \fIsin6_scope_id\fP is +a site index. The mapping of \fIsin6_scope_id\fP to an interface or +set of interfaces is implementation-defined. +.LP +The \fI\fP header shall declare the following external +variable: +.sp +.RS +.nf + +\fBconst struct in6_addr in6addr_any +\fP +.fi +.RE +.LP +This variable is initialized by the system to contain the wildcard +IPv6 address. The \fI\fP header also +defines the IN6ADDR_ANY_INIT macro. This macro must be constant at +compile time and can be used to initialize a variable of type +\fBstruct in6_addr\fP to the IPv6 wildcard address. +.LP +The \fI\fP header shall declare the following external +variable: +.sp +.RS +.nf + +\fBconst struct in6_addr in6addr_loopback +\fP +.fi +.RE +.LP +This variable is initialized by the system to contain the loopback +IPv6 address. The \fI\fP header also +defines the IN6ADDR_LOOPBACK_INIT macro. This macro must be constant +at compile time and can be used to initialize a variable of +type \fBstruct in6_addr\fP to the IPv6 loopback address. +.LP +The \fI\fP header shall define the \fBipv6_mreq\fP structure +that includes at least the following +members: +.sp +.RS +.nf + +\fBstruct in6_addr ipv6mr_multiaddr \fP IPv6 multicast address. \fB +unsigned ipv6mr_interface \fP Interface index. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the following macros +for use as values of the \fIlevel\fP argument of \fIgetsockopt\fP() +and \fIsetsockopt\fP(): +.TP 7 +IPPROTO_IP +Internet protocol. +.TP 7 +IPPROTO_IPV6 +Internet Protocol Version 6. +.TP 7 +IPPROTO_ICMP +Control message protocol. +.TP 7 +IPPROTO_RAW +Raw IP Packets Protocol. +.TP 7 +IPPROTO_TCP +Transmission control protocol. +.TP 7 +IPPROTO_UDP +User datagram protocol. +.sp +.LP +The \fI\fP header shall define the following macros +for use as destination addresses for \fIconnect\fP(), \fIsendmsg\fP(), +and \fIsendto\fP(): +.TP 7 +INADDR_ANY +IPv4 local host address. +.TP 7 +INADDR_BROADCAST +IPv4 broadcast address. +.sp +.LP +The \fI\fP header shall define the following macro to +help applications declare buffers of the proper size +to store IPv4 addresses in string form: +.TP 7 +INET_ADDRSTRLEN +16. Length of the string form for IP. +.sp +.LP +The \fIhtonl\fP(), \fIhtons\fP(), \fIntohl\fP(), and \fIntohs\fP() +functions shall be +available as defined in \fI\fP . Inclusion of the +\fI\fP header may also make visible all symbols from +\fI\fP . +.LP +The \fI\fP header shall define the following macro to +help applications declare buffers of the proper +size to store IPv6 addresses in string form: +.TP 7 +INET6_ADDRSTRLEN +46. Length of the string form for IPv6. +.sp +.LP +The \fI\fP header shall define the following macros, +with distinct integer values, for use in the +\fIoption_name\fP argument in the \fIgetsockopt\fP() or \fIsetsockopt\fP() +functions at protocol level IPPROTO_IPV6: +.TP 7 +IPV6_JOIN_GROUP +Join a multicast group. +.TP 7 +IPV6_LEAVE_GROUP +Quit a multicast group. +.TP 7 +IPV6_MULTICAST_HOPS +.sp +Multicast hop limit. +.TP 7 +IPV6_MULTICAST_IF +Interface to use for outgoing multicast packets. +.TP 7 +IPV6_MULTICAST_LOOP +.sp +Multicast packets are delivered back to the local application. +.TP 7 +IPV6_UNICAST_HOPS +Unicast hop limit. +.TP 7 +IPV6_V6ONLY +Restrict AF_INET6 socket to IPv6 communications only. +.sp +.LP +The \fI\fP header shall define the following macros +that test for special IPv6 addresses. Each macro is of +type \fBint\fP and takes a single argument of type \fBconst struct +in6_addr *\fP: +.TP 7 +IN6_IS_ADDR_UNSPECIFIED +.sp +Unspecified address. +.TP 7 +IN6_IS_ADDR_LOOPBACK +.sp +Loopback address. +.TP 7 +IN6_IS_ADDR_MULTICAST +.sp +Multicast address. +.TP 7 +IN6_IS_ADDR_LINKLOCAL +.sp +Unicast link-local address. +.TP 7 +IN6_IS_ADDR_SITELOCAL +.sp +Unicast site-local address. +.TP 7 +IN6_IS_ADDR_V4MAPPED +.sp +IPv4 mapped address. +.TP 7 +IN6_IS_ADDR_V4COMPAT +.sp +IPv4-compatible address. +.TP 7 +IN6_IS_ADDR_MC_NODELOCAL +.sp +Multicast node-local address. +.TP 7 +IN6_IS_ADDR_MC_LINKLOCAL +.sp +Multicast link-local address. +.TP 7 +IN6_IS_ADDR_MC_SITELOCAL +.sp +Multicast site-local address. +.TP 7 +IN6_IS_ADDR_MC_ORGLOCAL +.sp +Multicast organization-local address. +.TP 7 +IN6_IS_ADDR_MC_GLOBAL +.sp +Multicast global address. +.sp +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIHost and Network Byte Orders\fP , \fI\fP , \fI\fP +, \fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIconnect\fP(), \fIgetsockopt\fP(), \fIhtonl\fP(), \fIhtons\fP(), +\fIntohl\fP(), \fIntohs\fP(), \fIsendmsg\fP(), \fIsendto\fP(), \fIsetsockopt\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/inet.h.0p b/man0p/inet.h.0p new file mode 100644 index 000000000..03df3ac6c --- /dev/null +++ b/man0p/inet.h.0p @@ -0,0 +1,79 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +arpa/inet.h \- definitions for internet operations +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fBin_port_t\fP and \fBin_addr_t\fP types shall be defined as +described in \fI\fP . +.LP +The \fBin_addr\fP structure shall be defined as described in \fI\fP +\&. +.LP +The INET_ADDRSTRLEN \ and INET6_ADDRSTRLEN macros +shall be defined as described in \fI\fP . +.LP +The following shall either be declared as functions, defined as macros, +or both. If functions are declared, function prototypes +shall be provided. +.sp +.RS +.nf + +\fBuint32_t htonl(uint32_t); +uint16_t htons(uint16_t); +uint32_t ntohl(uint32_t); +uint16_t ntohs(uint16_t); +\fP +.fi +.RE +.LP +The \fBuint32_t\fP and \fBuint16_t\fP types shall be defined as described +in \fI\fP . +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBin_addr_t inet_addr(const char *); +char *inet_ntoa(struct in_addr); +const char *inet_ntop(int, const void *restrict, char *restrict, + socklen_t); +int inet_pton(int, const char *restrict, void *restrict); +\fP +.fi +.RE +.LP +Inclusion of the \fI\fP header may also make visible +all symbols from \fI\fP and \fI\fP. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, \fIhtonl\fP(), \fIinet_addr\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/inttypes.h.0p b/man0p/inttypes.h.0p new file mode 100644 index 000000000..b841ebbca --- /dev/null +++ b/man0p/inttypes.h.0p @@ -0,0 +1,163 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +inttypes.h \- fixed size integer types +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +Some of the functionality described on this reference page extends +the ISO\ C standard. Applications shall define +the appropriate feature test macro (see the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, Section 2.2, The Compilation Environment) +to enable the visibility of these symbols in this +header. +.LP +The \fI\fP header shall include the \fI\fP +header. +.LP +The \fI\fP header shall include a definition of at least +the following type: +.TP 7 +\fBimaxdiv_t\fP +Structure type that is the type of the value returned by the \fIimaxdiv\fP() +function. +.sp +.LP +The following macros shall be defined. Each expands to a character +string literal containing a conversion specifier, possibly +modified by a length modifier, suitable for use within the \fIformat\fP +argument of a formatted input/output function when +converting the corresponding integer type. These macros have the general +form of PRI (character string literals for the \fIfprintf\fP() and +\fIfwprintf\fP() family of +functions) or SCN (character string literals for the \fIfscanf\fP() +and \fIfwscanf\fP() family of functions), followed by the conversion +specifier, followed by a name +corresponding to a similar type name in \fI\fP. In these +names, \fIN\fP +represents the width of the type as described in \fI\fP. +For example, +\fIPRIdFAST32\fP can be used in a format string to print the value +of an integer of type \fBint_fast32_t\fP. +.LP +The \fIfprintf\fP() macros for signed integers are: +.TS C +center; l2 l2 l2 l2 l. +PRId\fIN\fP PRIdLEAST\fIN\fP PRIdFAST\fIN\fP PRIdMAX PRIdPTR +PRIi\fIN\fP PRIiLEAST\fIN\fP PRIiFAST\fIN\fP PRIiMAX PRIiPTR +.TE +.LP +The \fIfprintf\fP() macros for unsigned integers are: +.TS C +center; l2 l2 l2 l2 l. +PRIo\fIN\fP PRIoLEAST\fIN\fP PRIoFAST\fIN\fP PRIoMAX PRIoPTR +PRIu\fIN\fP PRIuLEAST\fIN\fP PRIuFAST\fIN\fP PRIuMAX PRIuPTR +PRIx\fIN\fP PRIxLEAST\fIN\fP PRIxFAST\fIN\fP PRIxMAX PRIxPTR +PRIX\fIN\fP PRIXLEAST\fIN\fP PRIXFAST\fIN\fP PRIXMAX PRIXPTR +.TE +.LP +The \fIfscanf\fP() macros for signed integers are: +.TS C +center; l2 l2 l2 l2 l. +SCNd\fIN\fP SCNdLEAST\fIN\fP SCNdFAST\fIN\fP SCNdMAX SCNdPTR +SCNi\fIN\fP SCNiLEAST\fIN\fP SCNiFAST\fIN\fP SCNiMAX SCNiPTR +.TE +.LP +The \fIfscanf\fP() macros for unsigned integers are: +.TS C +center; l2 l2 l2 l2 l. +SCNo\fIN\fP SCNoLEAST\fIN\fP SCNoFAST\fIN\fP SCNoMAX SCNoPTR +SCNu\fIN\fP SCNuLEAST\fIN\fP SCNuFAST\fIN\fP SCNuMAX SCNuPTR +SCNx\fIN\fP SCNxLEAST\fIN\fP SCNxFAST\fIN\fP SCNxMAX SCNxPTR +.TE +.LP +For each type that the implementation provides in \fI\fP, +the +corresponding \fIfprintf\fP() and \fIfwprintf\fP() macros shall be +defined and the corresponding \fIfscanf\fP() and \fIfwscanf\fP() macros +shall be defined +unless the implementation does not have a suitable modifier for the +type. +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBintmax_t imaxabs(intmax_t); +imaxdiv_t imaxdiv(intmax_t, intmax_t); +intmax_t strtoimax(const char *restrict, char **restrict, int); +uintmax_t strtoumax(const char *restrict, char **restrict, int); +intmax_t wcstoimax(const wchar_t *restrict, wchar_t **restrict, int); +uintmax_t wcstoumax(const wchar_t *restrict, wchar_t **restrict, int); +\fP +.fi +.RE +.SH EXAMPLES +.sp +.RS +.nf + +\fB#include +#include +int main(void) +{ + uintmax_t i = UINTMAX_MAX; // This type always exists. + wprintf(L"The largest integer value is %020" + PRIxMAX "\\n", i); + return 0; +} +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The purpose of \fI\fP is to provide a set of integer types +whose definitions are consistent across machines +and independent of operating systems and other implementation idiosyncrasies. +It defines, via \fBtypedef\fP, integer types of +various sizes. Implementations are free to \fBtypedef\fP them as ISO\ C +standard integer types or extensions that they +support. Consistent use of this header will greatly increase the portability +of applications across platforms. +.SH RATIONALE +.LP +The ISO/IEC\ 9899:1990 standard specified that the language should +support four signed and unsigned integer data types- +\fBchar\fP, \fBshort\fP, \fBint\fP, and \fBlong\fP- but placed very +little requirement on their size other than that \fBint\fP +and \fBshort\fP be at least 16 bits and \fBlong\fP be at least as +long as \fBint\fP and not smaller than 32 bits. For 16-bit +systems, most implementations assigned 8, 16, 16, and 32 bits to \fBchar\fP, +\fBshort\fP, \fBint\fP, and \fBlong\fP, +respectively. For 32-bit systems, the common practice has been to +assign 8, 16, 32, and 32 bits to these types. This difference in +\fBint\fP size can create some problems for users who migrate from +one system to another which assigns different sizes to integer +types, because the ISO\ C standard integer promotion rule can produce +silent changes unexpectedly. The need for defining an +extended integer type increased with the introduction of 64-bit systems. +.SH FUTURE DIRECTIONS +.LP +Macro names beginning with PRI or SCN followed by any lowercase letter +or \fB'X'\fP may be added to the macros defined in the +\fI\fP header. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIimaxdiv\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/ipc.h.0p b/man0p/ipc.h.0p new file mode 100644 index 000000000..5342855f1 --- /dev/null +++ b/man0p/ipc.h.0p @@ -0,0 +1 @@ +.so man0p/sys_ipc.h.0p diff --git a/man0p/iso646.h.0p b/man0p/iso646.h.0p new file mode 100644 index 000000000..7d7f0d813 --- /dev/null +++ b/man0p/iso646.h.0p @@ -0,0 +1,71 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +iso646.h \- alternative spellings +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following eleven macros +(on the left) that expand to the corresponding +tokens (on the right): +.TP 7 +and +\fB&&\fP +.TP 7 +and_eq +\fB&=\fP +.TP 7 +bitand +\fB&\fP +.TP 7 +bitor +\fB|\fP +.TP 7 +compl +\fB~\fP +.TP 7 +not +\fB!\fP +.TP 7 +not_eq +\fB!=\fP +.TP 7 +or +\fB||\fP +.TP 7 +or_eq +\fB|=\fP +.TP 7 +xor +\fB^\fP +.TP 7 +xor_eq +\fB^=\fP +.sp +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +None. +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/langinfo.h.0p b/man0p/langinfo.h.0p new file mode 100644 index 000000000..08ccdd826 --- /dev/null +++ b/man0p/langinfo.h.0p @@ -0,0 +1,360 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +langinfo.h \- language information constants +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header contains the constants used to identify +items of \fIlanginfo\fP data (see \fInl_langinfo\fP()). The type of +the constant, \fBnl_item\fP, shall be defined as described +in \fI\fP . +.LP +The following constants shall be defined. The entries under \fBCategory\fP +indicate in which \fIsetlocale\fP() category each item is defined. +.TS C +center; l1 l1 lw(40). +\fBConstant\fP \fBCategory\fP T{ +.na +\fBMeaning\fP +.ad +T} +CODESET \fILC_CTYPE\fP T{ +.na +Codeset name. +.ad +T} +D_T_FMT \fILC_TIME\fP T{ +.na +String for formatting date and time. +.ad +T} +D_FMT \fILC_TIME\fP T{ +.na +Date format string. +.ad +T} +T_FMT \fILC_TIME\fP T{ +.na +Time format string. +.ad +T} +T_FMT_AMPM \fILC_TIME\fP T{ +.na +a.m. or p.m. time format string. +.ad +T} +AM_STR \fILC_TIME\fP T{ +.na +Ante-meridiem affix. +.ad +T} +PM_STR \fILC_TIME\fP T{ +.na +Post-meridiem affix. +.ad +T} +DAY_1 \fILC_TIME\fP T{ +.na +Name of the first day of the week (for example, Sunday). +.ad +T} +DAY_2 \fILC_TIME\fP T{ +.na +Name of the second day of the week (for example, Monday). +.ad +T} +DAY_3 \fILC_TIME\fP T{ +.na +Name of the third day of the week (for example, Tuesday). +.ad +T} +DAY_4 \fILC_TIME\fP T{ +.na +Name of the fourth day of the week +.ad +T} + \fI\ \fP T{ +.na +(for example, Wednesday). +.ad +T} +DAY_5 \fILC_TIME\fP T{ +.na +Name of the fifth day of the week (for example, Thursday). +.ad +T} +DAY_6 \fILC_TIME\fP T{ +.na +Name of the sixth day of the week (for example, Friday). +.ad +T} +DAY_7 \fILC_TIME\fP T{ +.na +Name of the seventh day of the week +.ad +T} + \fI\ \fP T{ +.na +(for example, Saturday). +.ad +T} +ABDAY_1 \fILC_TIME\fP T{ +.na +Abbreviated name of the first day of the week. +.ad +T} +ABDAY_2 \fILC_TIME\fP T{ +.na +Abbreviated name of the second day of the week. +.ad +T} +ABDAY_3 \fILC_TIME\fP T{ +.na +Abbreviated name of the third day of the week. +.ad +T} +ABDAY_4 \fILC_TIME\fP T{ +.na +Abbreviated name of the fourth day of the week. +.ad +T} +ABDAY_5 \fILC_TIME\fP T{ +.na +Abbreviated name of the fifth day of the week. +.ad +T} +ABDAY_6 \fILC_TIME\fP T{ +.na +Abbreviated name of the sixth day of the week. +.ad +T} +ABDAY_7 \fILC_TIME\fP T{ +.na +Abbreviated name of the seventh day of the week. +.ad +T} +MON_1 \fILC_TIME\fP T{ +.na +Name of the first month of the year. +.ad +T} +MON_2 \fILC_TIME\fP T{ +.na +Name of the second month. +.ad +T} +MON_3 \fILC_TIME\fP T{ +.na +Name of the third month. +.ad +T} +MON_4 \fILC_TIME\fP T{ +.na +Name of the fourth month. +.ad +T} +MON_5 \fILC_TIME\fP T{ +.na +Name of the fifth month. +.ad +T} +MON_6 \fILC_TIME\fP T{ +.na +Name of the sixth month. +.ad +T} +MON_7 \fILC_TIME\fP T{ +.na +Name of the seventh month. +.ad +T} +MON_8 \fILC_TIME\fP T{ +.na +Name of the eighth month. +.ad +T} +MON_9 \fILC_TIME\fP T{ +.na +Name of the ninth month. +.ad +T} +MON_10 \fILC_TIME\fP T{ +.na +Name of the tenth month. +.ad +T} +MON_11 \fILC_TIME\fP T{ +.na +Name of the eleventh month. +.ad +T} +MON_12 \fILC_TIME\fP T{ +.na +Name of the twelfth month. +.ad +T} +ABMON_1 \fILC_TIME\fP T{ +.na +Abbreviated name of the first month. +.ad +T} +ABMON_2 \fILC_TIME\fP T{ +.na +Abbreviated name of the second month. +.ad +T} +ABMON_3 \fILC_TIME\fP T{ +.na +Abbreviated name of the third month. +.ad +T} +ABMON_4 \fILC_TIME\fP T{ +.na +Abbreviated name of the fourth month. +.ad +T} +ABMON_5 \fILC_TIME\fP T{ +.na +Abbreviated name of the fifth month. +.ad +T} +ABMON_6 \fILC_TIME\fP T{ +.na +Abbreviated name of the sixth month. +.ad +T} +ABMON_7 \fILC_TIME\fP T{ +.na +Abbreviated name of the seventh month. +.ad +T} +ABMON_8 \fILC_TIME\fP T{ +.na +Abbreviated name of the eighth month. +.ad +T} +ABMON_9 \fILC_TIME\fP T{ +.na +Abbreviated name of the ninth month. +.ad +T} +ABMON_10 \fILC_TIME\fP T{ +.na +Abbreviated name of the tenth month. +.ad +T} +ABMON_11 \fILC_TIME\fP T{ +.na +Abbreviated name of the eleventh month. +.ad +T} +ABMON_12 \fILC_TIME\fP T{ +.na +Abbreviated name of the twelfth month. +.ad +T} +ERA \fILC_TIME\fP T{ +.na +Era description segments. +.ad +T} +ERA_D_FMT \fILC_TIME\fP T{ +.na +Era date format string. +.ad +T} +ERA_D_T_FMT \fILC_TIME\fP T{ +.na +Era date and time format string. +.ad +T} +ERA_T_FMT \fILC_TIME\fP T{ +.na +Era time format string. +.ad +T} +ALT_DIGITS \fILC_TIME\fP T{ +.na +Alternative symbols for digits. +.ad +T} +RADIXCHAR \fILC_NUMERIC\fP T{ +.na +Radix character. +.ad +T} +THOUSEP \fILC_NUMERIC\fP T{ +.na +Separator for thousands. +.ad +T} +YESEXPR \fILC_MESSAGES\fP T{ +.na +Affirmative response expression. +.ad +T} +NOEXPR \fILC_MESSAGES\fP T{ +.na +Negative response expression. +.ad +T} +CRNCYSTR \fILC_MONETARY\fP T{ +.na +Local currency symbol, preceded by \fB'-'\fP if the symbol should appear before the value, \fB'+'\fP if the symbol should appear after the value, or \fB'.'\fP if the symbol should replace the radix character. If the local currency symbol is the empty string, implementations may return the empty string ( \fB""\fP ). +.ad +T} +.TE +.LP +If the locale's values for \fBp_cs_precedes\fP and \fBn_cs_precedes\fP +do not match, the value of \fInl_langinfo\fP(CRNCYSTR) +is unspecified. +.LP +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS +.nf + +\fBchar *nl_langinfo(nl_item); +\fP +.fi +.RE +.LP +Inclusion of the \fI\fP header may also make visible all +symbols from \fI\fP. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Wherever possible, users are advised to use functions compatible with +those in the ISO\ C standard to access items of +\fIlanginfo\fP data. In particular, the \fIstrftime\fP() function +should be used to +access date and time information defined in category \fILC_TIME .\fP +The \fIlocaleconv\fP() function should be used to access information +corresponding to RADIXCHAR, +THOUSEP, and CRNCYSTR. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fInl_langinfo\fP(), +\fIlocaleconv\fP(), \fIstrfmon\fP(), \fIstrftime\fP(), \fILocale\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/libgen.h.0p b/man0p/libgen.h.0p new file mode 100644 index 000000000..fe35610fb --- /dev/null +++ b/man0p/libgen.h.0p @@ -0,0 +1,46 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +libgen.h \- definitions for pattern matching functions +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBchar *basename(char *); +char *dirname(char *); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIbasename\fP(), +\fIdirname\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/limits.h.0p b/man0p/limits.h.0p new file mode 100644 index 000000000..065c9d600 --- /dev/null +++ b/man0p/limits.h.0p @@ -0,0 +1,1044 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +limits.h \- implementation-defined constants +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +Some of the functionality described on this reference page extends +the ISO\ C standard. Applications shall define +the appropriate feature test macro (see the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, Section 2.2, The Compilation Environment) +to enable the visibility of these symbols in this +header. +.LP +Many of the symbols listed here are not defined by the ISO/IEC\ 9899:1999 +standard. Such symbols are not shown as CX shaded. +.LP +The \fI\fP header shall define various symbolic names. Different +categories of names are described below. +.LP +The names represent various limits on resources that the implementation +imposes on applications. +.LP +Implementations may choose any appropriate value for each limit, provided +it is not more restrictive than the Minimum Acceptable +Values listed below. Symbolic constant names beginning with _POSIX +may be found in \fI\fP . +.LP +Applications should not assume any particular value for a limit. To +achieve maximum portability, an application should not +require more resource than the Minimum Acceptable Value quantity. +However, an application wishing to avail itself of the full +amount of a resource available on an implementation may make use of +the value given in \fI\fP on that particular +implementation, by using the symbolic names listed below. It should +be noted, however, that many of the listed limits are not +invariant, and at runtime, the value of the limit may differ from +those given in this header, for the following reasons: +.IP " *" 3 +The limit is pathname-dependent. +.LP +.IP " *" 3 +The limit differs between the compile and runtime machines. +.LP +.LP +For these reasons, an application may use the \fIfpathconf\fP(), \fIpathconf\fP(), +and \fIsysconf\fP() functions to +determine the actual value of a limit at runtime. +.LP +The items in the list ending in _MIN give the most negative values +that the mathematical types are guaranteed to be capable of +representing. Numbers of a more negative value may be supported on +some implementations, as indicated by the +\fI\fP header on the implementation, but applications requiring +such numbers are not guaranteed to be portable to +all implementations. For positive constants ending in _MIN, this indicates +the minimum acceptable value. +.SS Runtime Invariant Values (Possibly Indeterminate) +.LP +A definition of one of the symbolic names in the following list shall +be omitted from \fI\fP on specific +implementations where the corresponding value is equal to or greater +than the stated minimum, but is unspecified. +.LP +This indetermination might depend on the amount of available memory +space on a specific instance of a specific implementation. +The actual value supported by a specific instance shall be provided +by the \fIsysconf\fP() +function. +.TP 7 +{AIO_LISTIO_MAX} +.sp +Maximum number of I/O operations in a single list I/O call supported +by the implementation. +.br +Minimum Acceptable Value: {_POSIX_AIO_LISTIO_MAX} +.TP 7 +{AIO_MAX} +.sp +Maximum number of outstanding asynchronous I/O operations supported +by the implementation. +.br +Minimum Acceptable Value: {_POSIX_AIO_MAX} +.TP 7 +{AIO_PRIO_DELTA_MAX} +.sp +The maximum amount by which a process can decrease its asynchronous +I/O priority level from its own scheduling priority. +.br +Minimum Acceptable Value: 0 +.TP 7 +{ARG_MAX} +Maximum length of argument to the \fIexec\fP functions including environment +data. +.br +Minimum Acceptable Value: {_POSIX_ARG_MAX} +.TP 7 +{ATEXIT_MAX} +.sp +Maximum number of functions that may be registered with \fIatexit\fP(). +.br +Minimum Acceptable Value: 32 +.TP 7 +{CHILD_MAX} +Maximum number of simultaneous processes per real user ID. +.br +Minimum Acceptable Value: {_POSIX_CHILD_MAX} +.TP 7 +{DELAYTIMER_MAX} +.sp +Maximum number of timer expiration overruns. +.br +Minimum Acceptable Value: {_POSIX_DELAYTIMER_MAX} +.TP 7 +{HOST_NAME_MAX} +Maximum length of a host name (not including the terminating null) +as returned from the \fIgethostname\fP() function. +.br +Minimum Acceptable Value: {_POSIX_HOST_NAME_MAX} +.TP 7 +{IOV_MAX} +.sp +Maximum number of \fBiovec\fP structures that one process has available +for use with \fIreadv\fP() or \fIwritev\fP(). +.br +Minimum Acceptable Value: {_XOPEN_IOV_MAX} +.TP 7 +{LOGIN_NAME_MAX} +Maximum length of a login name. +.br +Minimum Acceptable Value: {_POSIX_LOGIN_NAME_MAX} +.TP 7 +{MQ_OPEN_MAX} +.sp +The maximum number of open message queue descriptors a process may +hold. +.br +Minimum Acceptable Value: {_POSIX_MQ_OPEN_MAX} +.TP 7 +{MQ_PRIO_MAX} +.sp +The maximum number of message priorities supported by the implementation. +.br +Minimum Acceptable Value: {_POSIX_MQ_PRIO_MAX} +.TP 7 +{OPEN_MAX} +Maximum number of files that one process can have open at any one +time. +.br +Minimum Acceptable Value: {_POSIX_OPEN_MAX} +.TP 7 +{PAGESIZE} +Size in bytes of a page. +.br +Minimum Acceptable Value: 1 +.TP 7 +{PAGE_SIZE} +.sp +Equivalent to {PAGESIZE}. If either {PAGESIZE} or {PAGE_SIZE} is defined, +the other is defined with the same value. +.TP 7 +{PTHREAD_DESTRUCTOR_ITERATIONS} +.sp +Maximum number of attempts made to destroy a thread's thread-specific +data values on thread exit. +.br +Minimum Acceptable Value: {_POSIX_THREAD_DESTRUCTOR_ITERATIONS} +.TP 7 +{PTHREAD_KEYS_MAX} +.sp +Maximum number of data keys that can be created by a process. +.br +Minimum Acceptable Value: {_POSIX_THREAD_KEYS_MAX} +.TP 7 +{PTHREAD_STACK_MIN} +.sp +Minimum size in bytes of thread stack storage. +.br +Minimum Acceptable Value: 0 +.TP 7 +{PTHREAD_THREADS_MAX} +.sp +Maximum number of threads that can be created per process. +.br +Minimum Acceptable Value: {_POSIX_THREAD_THREADS_MAX} +.TP 7 +{RE_DUP_MAX} +The number of repeated occurrences of a BRE permitted by the \fIregexec\fP() +and \fIregcomp\fP() functions when using the interval notation {\\(\fIm\fP,\fIn\fP\\}; +see \fIBREs Matching Multiple Characters\fP . +.br +Minimum Acceptable Value: {_POSIX2_RE_DUP_MAX} +.TP 7 +{RTSIG_MAX} +.sp +Maximum number of realtime signals reserved for application use in +this implementation. +.br +Minimum Acceptable Value: {_POSIX_RTSIG_MAX} +.TP 7 +{SEM_NSEMS_MAX} +.sp +Maximum number of semaphores that a process may have. +.br +Minimum Acceptable Value: {_POSIX_SEM_NSEMS_MAX} +.TP 7 +{SEM_VALUE_MAX} +.sp +The maximum value a semaphore may have. +.br +Minimum Acceptable Value: {_POSIX_SEM_VALUE_MAX} +.TP 7 +{SIGQUEUE_MAX} +.sp +Maximum number of queued signals that a process may send and have +pending at the receiver(s) at any time. +.br +Minimum Acceptable Value: {_POSIX_SIGQUEUE_MAX} +.TP 7 +{SS_REPL_MAX} +.sp +The maximum number of replenishment operations that may be simultaneously +pending for a particular sporadic server scheduler. +.br +Minimum Acceptable Value: {_POSIX_SS_REPL_MAX} +.TP 7 +{STREAM_MAX} +The number of streams that one process can have open at one time. +If defined, it has the same value as {FOPEN_MAX} (see \fI\fP +). +.br +Minimum Acceptable Value: {_POSIX_STREAM_MAX} +.TP 7 +{SYMLOOP_MAX} +Maximum number of symbolic links that can be reliably traversed in +the resolution of a pathname in the absence of a loop. +.br +Minimum Acceptable Value: {_POSIX_SYMLOOP_MAX} +.TP 7 +{TIMER_MAX} +.sp +Maximum number of timers per process supported by the implementation. +.br +Minimum Acceptable Value: {_POSIX_TIMER_MAX} +.TP 7 +{TRACE_EVENT_NAME_MAX} +.sp +Maximum length of the trace event name. +.br +Minimum Acceptable Value: {_POSIX_TRACE_EVENT_NAME_MAX} +.TP 7 +{TRACE_NAME_MAX} +.sp +Maximum length of the trace generation version string or of the trace +stream name. +.br +Minimum Acceptable Value: {_POSIX_TRACE_NAME_MAX} +.TP 7 +{TRACE_SYS_MAX} +.sp +Maximum number of trace streams that may simultaneously exist in the +system. +.br +Minimum Acceptable Value: {_POSIX_TRACE_SYS_MAX} +.TP 7 +{TRACE_USER_EVENT_MAX} +.sp +Maximum number of user trace event type identifiers that may simultaneously +exist in a traced process, including the predefined +user trace event POSIX_TRACE_UNNAMED_USER_EVENT. +.br +Minimum Acceptable Value: {_POSIX_TRACE_USER_EVENT_MAX} +.TP 7 +{TTY_NAME_MAX} +Maximum length of terminal device name. +.br +Minimum Acceptable Value: {_POSIX_TTY_NAME_MAX} +.TP 7 +{TZNAME_MAX} +Maximum number of bytes supported for the name of a timezone (not +of the \fITZ\fP variable). +.br +Minimum Acceptable Value: {_POSIX_TZNAME_MAX} +.sp +.TP 7 +\fBNote:\fP +The length given by {TZNAME_MAX} does not include the quoting characters +mentioned in \fIOther Environment Variables\fP . +.sp +.SS Pathname Variable Values +.LP +The values in the following list may be constants within an implementation +or may vary from one pathname to another. For +example, file systems or directories may have different characteristics. +.LP +A definition of one of the values shall be omitted from the \fI\fP +header on specific implementations where the +corresponding value is equal to or greater than the stated minimum, +but where the value can vary depending on the file to which it +is applied. The actual value supported for a specific pathname shall +be provided by the \fIpathconf\fP() function. +.TP 7 +{FILESIZEBITS} +Minimum number of bits needed to represent, as a signed integer value, +the maximum size of a regular file allowed in the specified +directory. +.br +Minimum Acceptable Value: 32 +.TP 7 +{LINK_MAX} +Maximum number of links to a single file. +.br +Minimum Acceptable Value: {_POSIX_LINK_MAX} +.TP 7 +{MAX_CANON} +Maximum number of bytes in a terminal canonical input line. +.br +Minimum Acceptable Value: {_POSIX_MAX_CANON} +.TP 7 +{MAX_INPUT} +Minimum number of bytes for which space is available in a terminal +input queue; therefore, the maximum number of bytes a conforming +application may require to be typed as input before reading them. +.br +Minimum Acceptable Value: {_POSIX_MAX_INPUT} +.TP 7 +{NAME_MAX} +Maximum number of bytes in a filename (not including terminating null). +.br +Minimum Acceptable Value: {_POSIX_NAME_MAX} +.br +Minimum Acceptable Value: {_XOPEN_NAME_MAX} +.TP 7 +{PATH_MAX} +Maximum number of bytes in a pathname, including the terminating null +character. +.br +Minimum Acceptable Value: {_POSIX_PATH_MAX} +.br +Minimum Acceptable Value: {_XOPEN_PATH_MAX} +.TP 7 +{PIPE_BUF} +Maximum number of bytes that is guaranteed to be atomic when writing +to a pipe. +.br +Minimum Acceptable Value: {_POSIX_PIPE_BUF} +.TP 7 +{POSIX_ALLOC_SIZE_MIN} +.sp +Minimum number of bytes of storage actually allocated for any portion +of a file. +.br +Minimum Acceptable Value: Not specified. +.TP 7 +{POSIX_REC_INCR_XFER_SIZE} +.sp +Recommended increment for file transfer sizes between the {POSIX_REC_MIN_XFER_SIZE} +and {POSIX_REC_MAX_XFER_SIZE} values. +.br +Minimum Acceptable Value: Not specified. +.TP 7 +{POSIX_REC_MAX_XFER_SIZE} +.sp +Maximum recommended file transfer size. +.br +Minimum Acceptable Value: Not specified. +.TP 7 +{POSIX_REC_MIN_XFER_SIZE} +.sp +Minimum recommended file transfer size. +.br +Minimum Acceptable Value: Not specified. +.TP 7 +{POSIX_REC_XFER_ALIGN} +.sp +Recommended file transfer buffer alignment. +.br +Minimum Acceptable Value: Not specified. +.TP 7 +{SYMLINK_MAX} +Maximum number of bytes in a symbolic link. +.br +Minimum Acceptable Value: {_POSIX_SYMLINK_MAX} +.sp +.SS Runtime Increasable Values +.LP +The magnitude limitations in the following list shall be fixed by +specific implementations. An application should assume that +the value supplied by \fI\fP in a specific implementation +is the minimum that pertains whenever the application is +run under that implementation. A specific instance of a specific implementation +may increase the value relative to that supplied by +\fI\fP for that implementation. The actual value supported +by a specific instance shall be provided by the \fIsysconf\fP() function. +.TP 7 +{BC_BASE_MAX} +Maximum \fIobase\fP values allowed by the \fIbc\fP utility. +.br +Minimum Acceptable Value: {_POSIX2_BC_BASE_MAX} +.TP 7 +{BC_DIM_MAX} +Maximum number of elements permitted in an array by the \fIbc\fP utility. +.br +Minimum Acceptable Value: {_POSIX2_BC_DIM_MAX} +.TP 7 +{BC_SCALE_MAX} +Maximum \fIscale\fP value allowed by the \fIbc\fP utility. +.br +Minimum Acceptable Value: {_POSIX2_BC_SCALE_MAX} +.TP 7 +{BC_STRING_MAX} +Maximum length of a string constant accepted by the \fIbc\fP utility. +.br +Minimum Acceptable Value: {_POSIX2_BC_STRING_MAX} +.TP 7 +{CHARCLASS_NAME_MAX} +Maximum number of bytes in a character class name. +.br +Minimum Acceptable Value: {_POSIX2_CHARCLASS_NAME_MAX} +.TP 7 +{COLL_WEIGHTS_MAX} +Maximum number of weights that can be assigned to an entry of the +\fILC_COLLATE\fP \fBorder\fP keyword in the locale definition +file; see \fILocale\fP . +.br +Minimum Acceptable Value: {_POSIX2_COLL_WEIGHTS_MAX} +.TP 7 +{EXPR_NEST_MAX} +Maximum number of expressions that can be nested within parentheses +by the \fIexpr\fP +utility. +.br +Minimum Acceptable Value: {_POSIX2_EXPR_NEST_MAX} +.TP 7 +{LINE_MAX} +Unless otherwise noted, the maximum length, in bytes, of a utility's +input line (either standard input or another file), when the +utility is described as processing text files. The length includes +room for the trailing . +.br +Minimum Acceptable Value: {_POSIX2_LINE_MAX} +.TP 7 +{NGROUPS_MAX} +Maximum number of simultaneous supplementary group IDs per process. +.br +Minimum Acceptable Value: {_POSIX_NGROUPS_MAX} +.TP 7 +{RE_DUP_MAX} +Maximum number of repeated occurrences of a regular expression permitted +when using the interval notation \\{\fIm\fP,\fIn\fP\\}; +see \fIRegular Expressions\fP . +.br +Minimum Acceptable Value: {_POSIX2_RE_DUP_MAX} +.sp +.SS Maximum Values +.LP +The symbolic constants in the following list shall be defined in \fI\fP +with the values shown. These are symbolic +names for the most restrictive value for certain features on an implementation +supporting the Timers option. A conforming +implementation shall provide values no larger than these values. A +conforming application must not require a smaller value for +correct operation. +.TP 7 +{_POSIX_CLOCKRES_MIN} +.sp +The resolution of the CLOCK_REALTIME clock, in nanoseconds. +.br +Value: 20 000 000 +.LP +If the Monotonic Clock option is supported, the resolution of the +CLOCK_MONOTONIC clock, in nanoseconds, is represented by +{_POSIX_CLOCKRES_MIN}. +.sp +.SS Minimum Values +.LP +The symbolic constants in the following list shall be defined in \fI\fP +with the values shown. These are +symbolic names for the most restrictive value for certain features +on an implementation conforming to this volume of +IEEE\ Std\ 1003.1-2001. Related symbolic constants are defined elsewhere +in this volume of IEEE\ Std\ 1003.1-2001 +which reflect the actual implementation and which need not be as restrictive. +A conforming implementation shall provide values at +least this large. A strictly conforming application must not require +a larger value for correct operation. +.TP 7 +{_POSIX_AIO_LISTIO_MAX} +.sp +The number of I/O operations that can be specified in a list I/O call. +.br +Value: 2 +.TP 7 +{_POSIX_AIO_MAX} +.sp +The number of outstanding asynchronous I/O operations. +.br +Value: 1 +.TP 7 +{_POSIX_ARG_MAX} +Maximum length of argument to the \fIexec\fP functions including environment +data. +.br +Value: 4 096 +.TP 7 +{_POSIX_CHILD_MAX} +Maximum number of simultaneous processes per real user ID. +.br +Value: 25 +.TP 7 +{_POSIX_DELAYTIMER_MAX} +.sp +The number of timer expiration overruns. +.br +Value: 32 +.TP 7 +{_POSIX_HOST_NAME_MAX} +Maximum length of a host name (not including the terminating null) +as returned from the \fIgethostname\fP() function. +.br +Value: 255 +.TP 7 +{_POSIX_LINK_MAX} +Maximum number of links to a single file. +.br +Value: 8 +.TP 7 +{_POSIX_LOGIN_NAME_MAX} +The size of the storage required for a login name, in bytes, including +the terminating null. +.br +Value: 9 +.TP 7 +{_POSIX_MAX_CANON} +Maximum number of bytes in a terminal canonical input queue. +.br +Value: 255 +.TP 7 +{_POSIX_MAX_INPUT} +Maximum number of bytes allowed in a terminal input queue. +.br +Value: 255 +.TP 7 +{_POSIX_MQ_OPEN_MAX} +.sp +The number of message queues that can be open for a single process. +.br +Value: 8 +.TP 7 +{_POSIX_MQ_PRIO_MAX} +.sp +The maximum number of message priorities supported by the implementation. +.br +Value: 32 +.TP 7 +{_POSIX_NAME_MAX} +Maximum number of bytes in a filename (not including terminating null). +.br +Value: 14 +.TP 7 +{_POSIX_NGROUPS_MAX} +Maximum number of simultaneous supplementary group IDs per process. +.br +Value: 8 +.TP 7 +{_POSIX_OPEN_MAX} +Maximum number of files that one process can have open at any one +time. +.br +Value: 20 +.TP 7 +{_POSIX_PATH_MAX} +Maximum number of bytes in a pathname. +.br +Value: 256 +.TP 7 +{_POSIX_PIPE_BUF} +Maximum number of bytes that is guaranteed to be atomic when writing +to a pipe. +.br +Value: 512 +.TP 7 +{_POSIX_RE_DUP_MAX} +The number of repeated occurrences of a BRE permitted by the \fIregexec\fP() +and \fIregcomp\fP() functions when using the interval notation {\\(\fIm\fP,\fIn\fP\\}; +see \fIBREs Matching Multiple Characters\fP . +.br +Value: 255 +.TP 7 +{_POSIX_RTSIG_MAX} +.sp +The number of realtime signal numbers reserved for application use. +.br +Value: 8 +.TP 7 +{_POSIX_SEM_NSEMS_MAX} +.sp +The number of semaphores that a process may have. +.br +Value: 256 +.TP 7 +{_POSIX_SEM_VALUE_MAX} +.sp +The maximum value a semaphore may have. +.br +Value: 32 767 +.TP 7 +{_POSIX_SIGQUEUE_MAX} +.sp +The number of queued signals that a process may send and have pending +at the receiver(s) at any time. +.br +Value: 32 +.TP 7 +{_POSIX_SSIZE_MAX} +The value that can be stored in an object of type \fBssize_t\fP. +.br +Value: 32 767 +.TP 7 +{_POSIX_STREAM_MAX} +The number of streams that one process can have open at one time. +.br +Value: 8 +.TP 7 +{_POSIX_SS_REPL_MAX} +.sp +The number of replenishment operations that may be simultaneously +pending for a particular sporadic server scheduler. +.br +Value: 4 +.TP 7 +{_POSIX_SYMLINK_MAX} +The number of bytes in a symbolic link. +.br +Value: 255 +.TP 7 +{_POSIX_SYMLOOP_MAX} +The number of symbolic links that can be traversed in the resolution +of a pathname in the absence of a loop. +.br +Value: 8 +.TP 7 +{_POSIX_THREAD_DESTRUCTOR_ITERATIONS} +.sp +The number of attempts made to destroy a thread's thread-specific +data values on thread exit. +.br +Value: 4 +.TP 7 +{_POSIX_THREAD_KEYS_MAX} +.sp +The number of data keys per process. +.br +Value: 128 +.TP 7 +{_POSIX_THREAD_THREADS_MAX} +.sp +The number of threads per process. +.br +Value: 64 +.TP 7 +{_POSIX_TIMER_MAX} +.sp +The per-process number of timers. +.br +Value: 32 +.TP 7 +{_POSIX_TRACE_EVENT_NAME_MAX} +.sp +The length in bytes of a trace event name. +.br +Value: 30 +.TP 7 +{_POSIX_TRACE_NAME_MAX} +.sp +The length in bytes of a trace generation version string or a trace +stream name. +.br +Value: 8 +.TP 7 +{_POSIX_TRACE_SYS_MAX} +.sp +The number of trace streams that may simultaneously exist in the system. +.br +Value: 8 +.TP 7 +{_POSIX_TRACE_USER_EVENT_MAX} +.sp +The number of user trace event type identifiers that may simultaneously +exist in a traced process, including the predefined user +trace event POSIX_TRACE_UNNAMED_USER_EVENT. +.br +Value: 32 +.TP 7 +{_POSIX_TTY_NAME_MAX} +The size of the storage required for a terminal device name, in bytes, +including the terminating null. +.br +Value: 9 +.TP 7 +{_POSIX_TZNAME_MAX} +Maximum number of bytes supported for the name of a timezone (not +of the \fITZ\fP variable). +.br +Value: 6 +.TP 7 +\fBNote:\fP +.RS +The length given by {_POSIX_TZNAME_MAX} does not include the quoting +characters mentioned in \fIOther Environment Variables\fP . +.RE +.sp +.TP 7 +{_POSIX2_BC_BASE_MAX} +Maximum \fIobase\fP values allowed by the \fIbc\fP utility. +.br +Value: 99 +.TP 7 +{_POSIX2_BC_DIM_MAX} +Maximum number of elements permitted in an array by the \fIbc\fP utility. +.br +Value: 2 048 +.TP 7 +{_POSIX2_BC_SCALE_MAX} +Maximum \fIscale\fP value allowed by the \fIbc\fP utility. +.br +Value: 99 +.TP 7 +{_POSIX2_BC_STRING_MAX} +Maximum length of a string constant accepted by the \fIbc\fP utility. +.br +Value: 1 000 +.TP 7 +{_POSIX2_CHARCLASS_NAME_MAX} +Maximum number of bytes in a character class name. +.br +Value: 14 +.TP 7 +{_POSIX2_COLL_WEIGHTS_MAX} +Maximum number of weights that can be assigned to an entry of the +\fILC_COLLATE\fP \fBorder\fP keyword in the locale definition +file; see \fILocale\fP . +.br +Value: 2 +.TP 7 +{_POSIX2_EXPR_NEST_MAX} +Maximum number of expressions that can be nested within parentheses +by the \fIexpr\fP +utility. +.br +Value: 32 +.TP 7 +{_POSIX2_LINE_MAX} +Unless otherwise noted, the maximum length, in bytes, of a utility's +input line (either standard input or another file), when the +utility is described as processing text files. The length includes +room for the trailing . +.br +Value: 2 048 +.TP 7 +{_POSIX2_RE_DUP_MAX +Maximum number of repeated occurrences of a regular expression permitted +when using the interval notation \\{\fIm\fP,\fIn\fP\\}; +see \fIRegular Expressions\fP . +.br +Value: 255 +.TP 7 +{_XOPEN_IOV_MAX} +.sp +Maximum number of \fBiovec\fP structures that one process has available +for use with \fIreadv\fP() or \fIwritev\fP(). +.br +Value: 16 +.TP 7 +{_XOPEN_NAME_MAX} +.sp +Maximum number of bytes in a filename (not including the terminating +null). +.br +Value: 255 +.TP 7 +{_XOPEN_PATH_MAX} +.sp +Maximum number of bytes in a pathname. +.br +Value: 1024 +.sp +.SS Numerical Limits +.LP +The values in the following lists shall be defined in \fI\fP +and are constant expressions suitable for use in +\fB#if\fP preprocessing directives. Moreover, except for {CHAR_BIT}, +{DBL_DIG}, {DBL_MAX}, {FLT_DIG}, {FLT_MAX}, {LONG_BIT}, +{WORD_BIT}, and {MB_LEN_MAX}, the symbolic names are defined as +expressions of the correct type. +.LP +If the value of an object of type \fBchar\fP is treated as a signed +integer when used in an expression, the value of {CHAR_MIN} +is the same as that of {SCHAR_MIN} and the value of {CHAR_MAX} is +the same as that of {SCHAR_MAX}. Otherwise, the value of +{CHAR_MIN} is 0 and the value of {CHAR_MAX} is the same as that of +{UCHAR_MAX}. +.TP 7 +{CHAR_BIT} +Number of bits in a type \fBchar\fP. +.br +Value: +8 +.TP 7 +{CHAR_MAX} +Maximum value of type \fBchar\fP. +.br +Value: {UCHAR_MAX} or {SCHAR_MAX} +.TP 7 +{CHAR_MIN} +Minimum value of type \fBchar\fP. +.br +Value: {SCHAR_MIN} or 0 +.TP 7 +{INT_MAX} +Maximum value of an \fBint\fP. +.br +Minimum Acceptable Value: 2 147 483 647 +.TP 7 +{LONG_BIT} +.sp +Number of bits in a \fBlong\fP. +.br +Minimum Acceptable Value: 32 +.TP 7 +{LONG_MAX} +Maximum value of a \fBlong\fP. +.br +Minimum Acceptable Value: +2 147 483 647 +.TP 7 +{MB_LEN_MAX} +Maximum number of bytes in a character, for any supported locale. +.br +Minimum Acceptable Value: 1 +.TP 7 +{SCHAR_MAX} +Maximum value of type \fBsigned char\fP. +.br +Value: ++127 +.TP 7 +{SHRT_MAX} +Maximum value of type \fBshort\fP. +.br +Minimum Acceptable Value: +32 767 +.TP 7 +{SSIZE_MAX} +Maximum value of an object of type \fBssize_t\fP. +.br +Minimum Acceptable Value: {_POSIX_SSIZE_MAX} +.TP 7 +{UCHAR_MAX} +Maximum value of type \fBunsigned char\fP. +.br +Value: +255 +.TP 7 +{UINT_MAX} +Maximum value of type \fBunsigned\fP. +.br +Minimum Acceptable Value: 4 294 967 295 +.TP 7 +{ULONG_MAX} +Maximum value of type \fBunsigned long\fP. +.br +Minimum Acceptable Value: 4 294 967 295 +.TP 7 +{USHRT_MAX} +Maximum value for a type \fBunsigned short\fP. +.br +Minimum Acceptable Value: 65 535 +.TP 7 +{WORD_BIT} +.sp +Number of bits in a word or type \fBint\fP. +.br +Minimum Acceptable Value: 16 +.TP 7 +{INT_MIN} +Minimum value of type \fBint\fP. +.br +Maximum Acceptable Value: -2 147 483 647 +.TP 7 +{LONG_MIN} +Minimum value of type \fBlong\fP. +.br +Maximum Acceptable Value: -2 147 483 647 +.TP 7 +{SCHAR_MIN} +Minimum value of type \fBsigned char\fP. +.br +Value: +-128 +.TP 7 +{SHRT_MIN} +Minimum value of type \fBshort\fP. +.br +Maximum Acceptable Value: -32 767 +.TP 7 +{LLONG_MIN} +Minimum value of type \fBlong long\fP. +.br +Maximum Acceptable Value: -9223372036854775807 +.TP 7 +{LLONG_MAX} +Maximum value of type \fBlong long\fP. +.br +Minimum Acceptable Value: +9223372036854775807 +.TP 7 +{ULLONG_MAX} +Maximum value of type \fBunsigned long long\fP. +.br +Minimum Acceptable Value: 18446744073709551615 +.sp +.SS Other Invariant Values +.LP +The following constants shall be defined on all implementations in +\fI\fP: +.TP 7 +{CHARCLASS_NAME_MAX} +.sp +Maximum number of bytes in a character class name. +.br +Minimum Acceptable Value: 14 +.TP 7 +{NL_ARGMAX} +.sp +Maximum value of \fIdigit\fP in calls to the \fIprintf\fP() and \fIscanf\fP() +functions. +.br +Minimum Acceptable Value: 9 +.TP 7 +{NL_LANGMAX} +.sp +Maximum number of bytes in a \fILANG\fP name. +.br +Minimum Acceptable Value: 14 +.TP 7 +{NL_MSGMAX} +.sp +Maximum message number. +.br +Minimum Acceptable Value: 32 767 +.TP 7 +{NL_NMAX} +.sp +Maximum number of bytes in an N-to-1 collation mapping. +.br +Minimum Acceptable Value: No guaranteed value across all conforming +implementations. +.TP 7 +{NL_SETMAX} +.sp +Maximum set number. +.br +Minimum Acceptable Value: 255 +.TP 7 +{NL_TEXTMAX} +.sp +Maximum number of bytes in a message string. +.br +Minimum Acceptable Value: {_POSIX2_LINE_MAX} +.TP 7 +{NZERO} +.sp +Default process priority. +.br +Minimum Acceptable Value: 20 +.sp +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +A request was made to reduce the value of {_POSIX_LINK_MAX} from the +value of 8 specified for it in the POSIX.1-1990 standard to +2. The standard developers decided to deny this request for several +reasons: +.IP " *" 3 +They wanted to avoid making any changes to the standard that could +break conforming applications, and the requested change could +have that effect. +.LP +.IP " *" 3 +The use of multiple hard links to a file cannot always be replaced +with use of symbolic links. Symbolic links are semantically +different from hard links in that they associate a pathname with another +pathname rather than a pathname with a file. This has +implications for access control, file permanence, and transparency. +.LP +.IP " *" 3 +The original standard developers had considered the issue of allowing +for implementations that did not in general support hard +links, and decided that this would reduce consensus on the standard. +.LP +.LP +Systems that support historical versions of the development option +of the ISO\ POSIX-2 standard retain the name +{_POSIX2_RE_DUP_MAX} as an alias for {_POSIX_RE_DUP_MAX}. +.TP 7 +{PATH_MAX} +IEEE PASC Interpretation 1003.1 #15 addressed the inconsistency in +the standard with the definition of pathname and the description +of {PATH_MAX}, allowing application writers to allocate either {PATH_MAX} +or {PATH_MAX}+1 bytes. The inconsistency has been removed +by correction to the {PATH_MAX} definition to include the null character. +With this change, applications that previously allocated +{PATH_MAX} bytes will continue to succeed. +.TP 7 +{SYMLINK_MAX} +This symbol refers to space for data that is stored in the file system, +as opposed to {PATH_MAX} which is the length of a name that +can be passed to a function. In some existing implementations, the +filenames pointed to by symbolic links are stored in the inodes +of the links, so it is important that {SYMLINK_MAX} not be constrained +to be as large as {PATH_MAX}. +.sp +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIfpathconf\fP(), +\fIpathconf\fP(), \fIsysconf\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/locale.h.0p b/man0p/locale.h.0p new file mode 100644 index 000000000..dc2a7b50d --- /dev/null +++ b/man0p/locale.h.0p @@ -0,0 +1,117 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +locale.h \- category macros +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +Some of the functionality described on this reference page extends +the ISO\ C standard. Any conflict between the +requirements described here and the ISO\ C standard is unintentional. +This volume of IEEE\ Std\ 1003.1-2001 defers to +the ISO\ C standard. +.LP +The \fI\fP header shall provide a definition for \fBlconv\fP +structure, which shall include at least the +following members. (See the definitions of \fILC_MONETARY\fP in \fILC_MONETARY\fP +and +\fILC_NUMERIC\fP .) +.sp +.RS +.nf + +\fBchar *currency_symbol +char *decimal_point +char frac_digits +char *grouping +char *int_curr_symbol +char int_frac_digits +char int_n_cs_precedes +char int_n_sep_by_space +char int_n_sign_posn +char int_p_cs_precedes +char int_p_sep_by_space +char int_p_sign_posn +char *mon_decimal_point +char *mon_grouping +char *mon_thousands_sep +char *negative_sign +char n_cs_precedes +char n_sep_by_space +char n_sign_posn +char *positive_sign +char p_cs_precedes +char p_sep_by_space +char p_sign_posn +char *thousands_sep +\fP +.fi +.RE +.LP +The \fI\fP header shall define NULL (as defined in \fI\fP +) and at +least the following as macros: +.LP +.sp +\fILC_ALL\fP +.br +\fILC_COLLATE\fP +.br +\fILC_CTYPE\fP +.br +.sp +\fILC_MESSAGES\fP +.br +.sp +\fILC_MONETARY\fP +.br +\fILC_NUMERIC\fP +.br +\fILC_TIME\fP +.br +.LP +which shall expand to distinct integer constant expressions, for use +as the first argument to the \fIsetlocale\fP() function. +.LP +Additional macro definitions, beginning with the characters \fILC_\fP +and an uppercase letter, may also be given here. +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBstruct lconv *localeconv (void); +char *setlocale(int, const char *); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIlocaleconv\fP(), +\fIsetlocale\fP(), \fIEnvironment Variables\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/math.h.0p b/man0p/math.h.0p new file mode 100644 index 000000000..3c598f670 --- /dev/null +++ b/man0p/math.h.0p @@ -0,0 +1,487 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +math.h \- mathematical declarations +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +Some of the functionality described on this reference page extends +the ISO\ C standard. Applications shall define +the appropriate feature test macro (see the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, Section 2.2, The Compilation Environment) +to enable the visibility of these symbols in this +header. +.LP +The \fI\fP header shall include definitions for at least the +following types: +.TP 7 +\fBfloat_t\fP +A real-floating type at least as wide as \fBfloat\fP. +.TP 7 +\fBdouble_t\fP +A real-floating type at least as wide as \fBdouble\fP, and at least +as wide as \fBfloat_t\fP. +.sp +.LP +If FLT_EVAL_METHOD equals 0, \fBfloat_t\fP and \fBdouble_t\fP shall +be \fBfloat\fP and \fBdouble\fP, respectively; if +FLT_EVAL_METHOD equals 1, they shall both be \fBdouble\fP; if FLT_EVAL_METHOD +equals 2, they shall both be \fBlong double\fP; for +other values of FLT_EVAL_METHOD, they are otherwise implementation-defined. +.LP +The \fI\fP header shall define the following macros, where +real-floating indicates that the argument shall be an +expression of real-floating type: +.sp +.RS +.nf + +\fBint fpclassify(real-floating x); +int isfinite(real-floating x); +int isinf(real-floating x); +int isnan(real-floating x); +int isnormal(real-floating x); +int signbit(real-floating x); +int isgreater(real-floating x, real-floating y); +int isgreaterequal(real-floating x, real-floating y); +int isless(real-floating x, real-floating y); +int islessequal(real-floating x, real-floating y); +int islessgreater(real-floating x, real-floating y); +int isunordered(real-floating x, real-floating y); +\fP +.fi +.RE +.LP +The \fI\fP header shall provide for the following constants. +The values are of type \fBdouble\fP and are +accurate within the precision of the \fBdouble\fP type. +.TP 7 +M_E +Value of \fIe\fP +.TP 7 +M_LOG2E +Value of log_2\fIe\fP +.TP 7 +M_LOG10E +Value of log_10\fIe\fP +.TP 7 +M_LN2 +Value of log_e2 +.TP 7 +M_LN10 +Value of log_e10 +.TP 7 +M_PI +Value of pi +.TP 7 +M_PI_2 +Value of pi/2 +.TP 7 +M_PI_4 +Value of pi/4 +.TP 7 +M_1_PI +Value of 1/pi +.TP 7 +M_2_PI +Value of 2/pi +.TP 7 +M_2_SQRTPI +Value of 2/ sqrt pi +.TP 7 +M_SQRT2 +Value of sqrt 2 +.TP 7 +M_SQRT1_2 +Value of 1/sqrt 2 +.sp +.LP +The header shall define the following symbolic constants: +.TP 7 +MAXFLOAT +Value of maximum non-infinite single-precision floating-point number. +.TP 7 +HUGE_VAL +A positive \fBdouble\fP expression, not necessarily representable +as a \fBfloat\fP. Used as an error value returned by the +mathematics library. HUGE_VAL evaluates to +infinity on systems supporting +IEEE\ Std\ 754-1985. +.TP 7 +HUGE_VALF +A positive \fBfloat\fP constant expression. Used as an error value +returned by the mathematics library. HUGE_VALF evaluates to ++infinity on systems supporting IEEE\ Std\ 754-1985. +.TP 7 +HUGE_VALL +A positive \fBlong double\fP constant expression. Used as an error +value returned by the mathematics library. HUGE_VALL +evaluates to +infinity on systems supporting IEEE\ Std\ 754-1985. +.TP 7 +INFINITY +A constant expression of type \fBfloat\fP representing positive or +unsigned infinity, if available; else a positive constant +of type \fBfloat\fP that overflows at translation time. +.TP 7 +NAN +A constant expression of type \fBfloat\fP representing a quiet NaN. +This symbolic constant is only defined if the +implementation supports quiet NaNs for the \fBfloat\fP type. +.sp +.LP +The following macros shall be defined for number classification. They +represent the mutually-exclusive kinds of floating-point +values. They expand to integer constant expressions with distinct +values. Additional implementation-defined floating-point +classifications, with macro definitions beginning with FP_ and an +uppercase letter, may also be specified by the +implementation. +.sp +.RS +.nf + +FP_INFINITE +FP_NAN +FP_NORMAL +FP_SUBNORMAL +FP_ZERO +.fi +.RE +.LP +The following optional macros indicate whether the \fIfma\fP() family +of functions are fast +compared with direct code: +.sp +.RS +.nf + +FP_FAST_FMA +FP_FAST_FMAF +FP_FAST_FMAL +.fi +.RE +.LP +The FP_FAST_FMA macro shall be defined to indicate that the \fIfma\fP() +function generally +executes about as fast as, or faster than, a multiply and an add of +\fBdouble\fP operands. The other macros have the equivalent +meaning for the \fBfloat\fP and \fBlong double\fP versions. +.LP +The following macros shall expand to integer constant expressions +whose values are returned by \fIilogb\fP( \fIx\fP) if +\fIx\fP is zero or NaN, respectively. The value of FP_ILOGB0 shall +be either {INT_MIN} or - {INT_MAX}. The value of FP_ILOGBNAN +shall be either {INT_MAX} or {INT_MIN}. +.sp +.RS +.nf + +FP_ILOGB0 +FP_ILOGBNAN +.fi +.RE +.LP +The following macros shall expand to the integer constants 1 and 2, +respectively; +.sp +.RS +.nf + +MATH_ERRNO +MATH_ERREXCEPT +.fi +.RE +.LP +The following macro shall expand to an expression that has type \fBint\fP +and the value MATH_ERRNO, MATH_ERREXCEPT, or the +bitwise-inclusive OR of both: +.sp +.RS +.nf + +math_errhandling +.fi +.RE +.LP +The value of math_errhandling is constant for the duration of the +program. It is unspecified whether math_errhandling is a macro +or an identifier with external linkage. If a macro definition is suppressed +or a program defines an identifier with the name +math_errhandling , the behavior is undefined. If the expression (math_errhandling +& MATH_ERREXCEPT) can be non-zero, the +implementation shall define the macros FE_DIVBYZERO, FE_INVALID, and +FE_OVERFLOW in \fI\fP. +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBdouble acos(double); +float acosf(float); +double acosh(double); +float acoshf(float); +long double acoshl(long double); +long double acosl(long double); +double asin(double); +float asinf(float); +double asinh(double); +float asinhf(float); +long double asinhl(long double); +long double asinl(long double); +double atan(double); +double atan2(double, double); +float atan2f(float, float); +long double atan2l(long double, long double); +float atanf(float); +double atanh(double); +float atanhf(float); +long double atanhl(long double); +long double atanl(long double); +double cbrt(double); +float cbrtf(float); +long double cbrtl(long double); +double ceil(double); +float ceilf(float); +long double ceill(long double); +double copysign(double, double); +float copysignf(float, float); +long double copysignl(long double, long double); +double cos(double); +float cosf(float); +double cosh(double); +float coshf(float); +long double coshl(long double); +long double cosl(long double); +double erf(double); +double erfc(double); +float erfcf(float); +long double erfcl(long double); +float erff(float); +long double erfl(long double); +double exp(double); +double exp2(double); +float exp2f(float); +long double exp2l(long double); +float expf(float); +long double expl(long double); +double expm1(double); +float expm1f(float); +long double expm1l(long double); +double fabs(double); +float fabsf(float); +long double fabsl(long double); +double fdim(double, double); +float fdimf(float, float); +long double fdiml(long double, long double); +double floor(double); +float floorf(float); +long double floorl(long double); +double fma(double, double, double); +float fmaf(float, float, float); +long double fmal(long double, long double, long double); +double fmax(double, double); +float fmaxf(float, float); +long double fmaxl(long double, long double); +double fmin(double, double); +float fminf(float, float); +long double fminl(long double, long double); +double fmod(double, double); +float fmodf(float, float); +long double fmodl(long double, long double); +double frexp(double, int *); +float frexpf(float value, int *); +long double frexpl(long double value, int *); +double hypot(double, double); +float hypotf(float, float); +long double hypotl(long double, long double); +int ilogb(double); +int ilogbf(float); +int ilogbl(long double); + +double j0(double); +double j1(double); +double jn(int, double); + +double ldexp(double, int); +float ldexpf(float, int); +long double ldexpl(long double, int); +double lgamma(double); +float lgammaf(float); +long double lgammal(long double); +long long llrint(double); +long long llrintf(float); +long long llrintl(long double); +long long llround(double); +long long llroundf(float); +long long llroundl(long double); +double log(double); +double log10(double); +float log10f(float); +long double log10l(long double); +double log1p(double); +float log1pf(float); +long double log1pl(long double); +double log2(double); +float log2f(float); +long double log2l(long double); +double logb(double); +float logbf(float); +long double logbl(long double); +float logf(float); +long double logl(long double); +long lrint(double); +long lrintf(float); +long lrintl(long double); +long lround(double); +long lroundf(float); +long lroundl(long double); +double modf(double, double *); +float modff(float, float *); +long double modfl(long double, long double *); +double nan(const char *); +float nanf(const char *); +long double nanl(const char *); +double nearbyint(double); +float nearbyintf(float); +long double nearbyintl(long double); +double nextafter(double, double); +float nextafterf(float, float); +long double nextafterl(long double, long double); +double nexttoward(double, long double); +float nexttowardf(float, long double); +long double nexttowardl(long double, long double); +double pow(double, double); +float powf(float, float); +long double powl(long double, long double); +double remainder(double, double); +float remainderf(float, float); +long double remainderl(long double, long double); +double remquo(double, double, int *); +float remquof(float, float, int *); +long double remquol(long double, long double, int *); +double rint(double); +float rintf(float); +long double rintl(long double); +double round(double); +float roundf(float); +long double roundl(long double); + +double scalb(double, double); + +double scalbln(double, long); +float scalblnf(float, long); +long double scalblnl(long double, long); +double scalbn(double, int); +float scalbnf(float, int); +long double scalbnl(long double, int); +double sin(double); +float sinf(float); +double sinh(double); +float sinhf(float); +long double sinhl(long double); +long double sinl(long double); +double sqrt(double); +float sqrtf(float); +long double sqrtl(long double); +double tan(double); +float tanf(float); +double tanh(double); +float tanhf(float); +long double tanhl(long double); +long double tanl(long double); +double tgamma(double); +float tgammaf(float); +long double tgammal(long double); +double trunc(double); +float truncf(float); +long double truncl(long double); + +double y0(double); +double y1(double); +double yn(int, double); + +\fP +.fi +.RE +.LP +The following external variable shall be defined: +.sp +.RS +.nf + +\fB +extern int signgam; + +\fP +.fi +.RE +.LP +The behavior of each of the functions defined in \fI\fP is +specified in the System Interfaces volume of +IEEE\ Std\ 1003.1-2001 for all representable values of its input arguments, +except where stated otherwise. Each function +shall execute as if it were a single operation without generating +any externally visible exceptional conditions. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The FP_CONTRACT pragma can be used to allow (if the state is on) or +disallow (if the state is off) the implementation to +contract expressions. Each pragma can occur either outside external +declarations or preceding all explicit declarations and +statements inside a compound statement. When outside external declarations, +the pragma takes effect from its occurrence until +another FP_CONTRACT pragma is encountered, or until the end of the +translation unit. When inside a compound statement, the pragma +takes effect from its occurrence until another FP_CONTRACT pragma +is encountered (including within a nested compound statement), or +until the end of the compound statement; at the end of a compound +statement the state for the pragma is restored to its condition +just before the compound statement. If this pragma is used in any +other context, the behavior is undefined. The default state (on +or off) for the pragma is implementation-defined. +.SH RATIONALE +.LP +Before the ISO/IEC\ 9899:1999 standard, the math library was defined +only for the floating type \fBdouble\fP. All the names +formed by appending \fB'f'\fP or \fB'l'\fP to a name in \fI\fP +were reserved to allow for the definition of +\fBfloat\fP and \fBlong double\fP libraries; and the ISO/IEC\ 9899:1999 +standard provides for all three versions of math +functions. +.LP +The functions \fIecvt\fP(), \fIfcvt\fP(), and \fIgcvt\fP() have been +dropped from the ISO\ C standard since their capability is available +through \fIsprintf\fP(). These are provided on XSI-conformant systems +supporting the +Legacy Option Group. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIacos\fP(), \fIacosh\fP(), +\fIasin\fP(), \fIatan\fP(), \fIatan2\fP(), \fIcbrt\fP(), \fIceil\fP(), +\fIcos\fP(), \fIcosh\fP(), \fIerf\fP(), \fIexp\fP(), \fIexpm1\fP(), +\fIfabs\fP(), \fIfloor\fP(), \fIfmod\fP(), \fIfrexp\fP(), \fIhypot\fP(), +\fIilogb\fP(), \fIisnan\fP(), \fIj0\fP(), \fIldexp\fP(), \fIlgamma\fP(), +\fIlog\fP(), \fIlog10\fP(), \fIlog1p\fP(), \fIlogb\fP(), \fImodf\fP(), +\fInextafter\fP(), \fIpow\fP(), \fIremainder\fP(), \fIrint\fP(), \fIscalb\fP(), +\fIsin\fP(), \fIsinh\fP(), \fIsqrt\fP(), \fItan\fP(), \fItanh\fP(), +\fIy0\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/mman.h.0p b/man0p/mman.h.0p new file mode 100644 index 000000000..96c671784 --- /dev/null +++ b/man0p/mman.h.0p @@ -0,0 +1 @@ +.so man0p/sys_mman.h.0p diff --git a/man0p/monetary.h.0p b/man0p/monetary.h.0p new file mode 100644 index 000000000..68e9b0be9 --- /dev/null +++ b/man0p/monetary.h.0p @@ -0,0 +1,53 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +monetary.h \- monetary types +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following types: +.TP 7 +\fBsize_t\fP +As described in \fI\fP . +.TP 7 +\fBssize_t\fP +As described in \fI\fP . +.sp +.LP +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS +.nf + +\fBssize_t strfmon(char *restrict, size_t, const char *restrict, ...); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIstrfmon\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/mqueue.h.0p b/man0p/mqueue.h.0p new file mode 100644 index 000000000..e8246244e --- /dev/null +++ b/man0p/mqueue.h.0p @@ -0,0 +1,88 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +mqueue.h \- message queues (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBmqd_t\fP type, which +is used for message queue descriptors. This is not +an array type. +.LP +The \fI\fP header shall define the \fBsigevent\fP structure +(as described in \fI\fP ) and the \fBmq_attr\fP structure, +which is used in getting and setting the attributes +of a message queue. Attributes are initially set when the message +queue is created. An \fBmq_attr\fP structure shall have at least +the following fields: +.sp +.RS +.nf + +\fBlong mq_flags \fP Message queue flags. \fB +long mq_maxmsg \fP Maximum number of messages. \fB +long mq_msgsize \fP Maximum message size. \fB +long mq_curmsgs \fP Number of messages currently queued. \fB +\fP +.fi +.RE +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint mq_close(mqd_t); +int mq_getattr(mqd_t, struct mq_attr *); +int mq_notify(mqd_t, const struct sigevent *); +mqd_t mq_open(const char *, int, ...); +ssize_t mq_receive(mqd_t, char *, size_t, unsigned *); +int mq_send(mqd_t, const char *, size_t, unsigned ); +int mq_setattr(mqd_t, const struct mq_attr *restrict, + struct mq_attr *restrict); + +ssize_t mq_timedreceive(mqd_t, char *restrict, size_t, + unsigned *restrict, const struct timespec *restrict); +int mq_timedsend(mqd_t, const char *, size_t, unsigned , + const struct timespec *); + +int mq_unlink(const char *); +\fP +.fi +.RE +.LP +Inclusion of the \fI\fP header may make visible symbols +defined in the headers \fI\fP, \fI\fP, \fI\fP, +and \fI\fP. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , \fI\fP , \fI\fP +, the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, \fImq_close\fP(), \fImq_getattr\fP(), \fImq_notify\fP(), +\fImq_open\fP(), \fImq_receive\fP(), \fImq_send\fP(), \fImq_setattr\fP(), +\fImq_timedreceive\fP(), \fImq_timedsend\fP(), \fImq_unlink\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/msg.h.0p b/man0p/msg.h.0p new file mode 100644 index 000000000..e905a24e5 --- /dev/null +++ b/man0p/msg.h.0p @@ -0,0 +1 @@ +.so man0p/sys_msg.h.0p diff --git a/man0p/ndbm.h.0p b/man0p/ndbm.h.0p new file mode 100644 index 000000000..882514f38 --- /dev/null +++ b/man0p/ndbm.h.0p @@ -0,0 +1,84 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +ndbm.h \- definitions for ndbm database operations +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBdatum\fP type as a structure +that includes at least the following +members: +.sp +.RS +.nf + +\fBvoid *dptr \fP A pointer to the application's data. \fB +size_t dsize\fP The size of the object pointed to by \fIdptr.\fP \fB +\fP +.fi +.RE +.LP +The \fBsize_t\fP type shall be defined as described in \fI\fP +\&. +.LP +The \fI\fP header shall define the \fBDBM\fP type. +.LP +The following constants shall be defined as possible values for the +\fIstore_mode\fP argument to \fIdbm_store\fP(): +.TP 7 +DBM_INSERT +Insertion of new entries only. +.TP 7 +DBM_REPLACE +Allow replacing existing entries. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint dbm_clearerr(DBM *); +void dbm_close(DBM *); +int dbm_delete(DBM *, datum); +int dbm_error(DBM *); +datum dbm_fetch(DBM *, datum); +datum dbm_firstkey(DBM *); +datum dbm_nextkey(DBM *); +DBM *dbm_open(const char *, int, mode_t); +int dbm_store(DBM *, datum, datum, int); +\fP +.fi +.RE +.LP +The \fBmode_t\fP type shall be defined through \fBtypedef\fP as described +in \fI\fP . +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIdbm_clearerr\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/netdb.h.0p b/man0p/netdb.h.0p new file mode 100644 index 000000000..e52c3b550 --- /dev/null +++ b/man0p/netdb.h.0p @@ -0,0 +1,298 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +netdb.h \- definitions for network database operations +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header may define the \fBin_port_t\fP type and +the \fBin_addr_t\fP type as described in \fI\fP . +.LP +The \fI\fP header shall define the \fBhostent\fP structure +that includes at least the following members: +.sp +.RS +.nf + +\fBchar *h_name \fP Official name of the host. \fB +char **h_aliases \fP A pointer to an array of pointers to \fB + \fP alternative host names, terminated by a \fB + \fP null pointer. \fB +int h_addrtype \fP Address type. \fB +int h_length \fP The length, in bytes, of the address. \fB +char **h_addr_list \fP A pointer to an array of pointers to network \fB + \fP addresses (in network byte order) for the host, \fB + \fP terminated by a null pointer. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the \fBnetent\fP structure +that includes at least the following members: +.sp +.RS +.nf + +\fBchar *n_name \fP Official, fully-qualified (including the \fB + \fP domain) name of the host. \fB +char **n_aliases \fP A pointer to an array of pointers to \fB + \fP alternative network names, terminated by a \fB + \fP null pointer. \fB +int n_addrtype \fP The address type of the network. \fB +uint32_t n_net \fP The network number, in host byte order. \fB +\fP +.fi +.RE +.LP +The \fBuint32_t\fP type shall be defined as described in \fI\fP +\&. +.LP +The \fI\fP header shall define the \fBprotoent\fP structure +that includes at least the following members: +.sp +.RS +.nf + +\fBchar *p_name \fP Official name of the protocol. \fB +char **p_aliases \fP A pointer to an array of pointers to \fB + \fP alternative protocol names, terminated by \fB + \fP a null pointer. \fB +int p_proto \fP The protocol number. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the \fBservent\fP structure +that includes at least the following members: +.sp +.RS +.nf + +\fBchar *s_name \fP Official name of the service. \fB +char **s_aliases \fP A pointer to an array of pointers to \fB + \fP alternative service names, terminated by \fB + \fP a null pointer. \fB +int s_port \fP The port number at which the service \fB + \fP resides, in network byte order. \fB +char *s_proto \fP The name of the protocol to use when \fB + \fP contacting the service. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the IPPORT_RESERVED macro +with the value of the highest reserved Internet port +number. +.LP +When the \fI\fP header is included, \fIh_errno\fP shall be +available as a modifiable lvalue of type \fBint\fP. It +is unspecified whether \fIh_errno\fP is a macro or an identifier declared +with external linkage. +.LP +The \fI\fP header shall define the following macros for use +as error values for \fIgethostbyaddr\fP() and \fIgethostbyname\fP(): +.sp +.RS +.nf + +HOST_NOT_FOUND +NO_DATA +NO_RECOVERY +TRY_AGAIN +.fi +.RE +.SS Address Information Structure +.LP +The \fI\fP header shall define the \fBaddrinfo\fP structure +that includes at least the following members: +.sp +.RS +.nf + +\fBint ai_flags \fP Input flags. \fB +int ai_family \fP Address family of socket. \fB +int ai_socktype \fP Socket type. \fB +int ai_protocol \fP Protocol of socket. \fB +socklen_t ai_addrlen \fP Length of socket address. \fB +struct sockaddr *ai_addr \fP Socket address of socket. \fB +char *ai_canonname \fP Canonical name of service location. \fB +struct addrinfo *ai_next \fP Pointer to next in list. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the following macros that +evaluate to bitwise-distinct integer constants for use +in the \fIflags\fP field of the \fBaddrinfo\fP structure: +.TP 7 +AI_PASSIVE +Socket address is intended for \fIbind\fP(). +.TP 7 +AI_CANONNAME +.sp +Request for canonical name. +.TP 7 +AI_NUMERICHOST +.sp +Return numeric host address as name. +.TP 7 +AI_NUMERICSERV +.sp +Inhibit service name resolution. +.TP 7 +AI_V4MAPPED +If no IPv6 addresses are found, query for IPv4 addresses and return +them to the caller as IPv4-mapped IPv6 addresses. +.TP 7 +AI_ALL +Query for both IPv4 and IPv6 addresses. +.TP 7 +AI_ADDRCONFIG +.sp +Query for IPv4 addresses only when an IPv4 address is configured; +query for IPv6 addresses only when an IPv6 address is +configured. +.sp +.LP +The \fI\fP header shall define the following macros that +evaluate to bitwise-distinct integer constants for use +in the \fIflags\fP argument to \fIgetnameinfo\fP(): +.TP 7 +NI_NOFQDN +Only the nodename portion of the FQDN is returned for local hosts. +.TP 7 +NI_NUMERICHOST +.sp +The numeric form of the node's address is returned instead of its +name. +.TP 7 +NI_NAMEREQD +Return an error if the node's name cannot be located in the database. +.TP 7 +NI_NUMERICSERV +.sp +The numeric form of the service address is returned instead of its +name. +.TP 7 +NI_NUMERICSCOPE +.sp +For IPv6 addresses, the numeric form of the scope identifier is returned +instead of its name. +.TP 7 +NI_DGRAM +Indicates that the service is a datagram service (SOCK_DGRAM). +.sp +.SS Address Information Errors +.LP +The \fI\fP header shall define the following macros for use +as error values for \fIgetaddrinfo\fP() and \fIgetnameinfo\fP(): +.TP 7 +EAI_AGAIN +The name could not be resolved at this time. Future attempts may succeed. +.TP 7 +EAI_BADFLAGS +The flags had an invalid value. +.TP 7 +EAI_FAIL +A non-recoverable error occurred. +.TP 7 +EAI_FAMILY +The address family was not recognized or the address length was invalid +for the specified family. +.TP 7 +EAI_MEMORY +There was a memory allocation failure. +.TP 7 +EAI_NONAME +The name does not resolve for the supplied parameters. +.LP +NI_NAMEREQD is set and the host's name cannot be located, or both +\fInodename\fP and \fIservname\fP were null. +.TP 7 +EAI_SERVICE +The service passed was not recognized for the specified socket type. +.TP 7 +EAI_SOCKTYPE +The intended socket type was not recognized. +.TP 7 +EAI_SYSTEM +A system error occurred. The error code can be found in \fIerrno\fP. +.TP 7 +EAI_OVERFLOW +.sp +An argument buffer overflowed. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBvoid endhostent(void); +void endnetent(void); +void endprotoent(void); +void endservent(void); +void freeaddrinfo(struct addrinfo *); +const char *gai_strerror(int); +int getaddrinfo(const char *restrict, const char *restrict, + const struct addrinfo *restrict, + struct addrinfo **restrict); +struct hostent *gethostbyaddr(const void *, socklen_t, int); +struct hostent *gethostbyname(const char *); +struct hostent *gethostent(void); +int getnameinfo(const struct sockaddr *restrict, socklen_t, + char *restrict, socklen_t, char *restrict, + socklen_t, int); +struct netent *getnetbyaddr(uint32_t, int); +struct netent *getnetbyname(const char *); +struct netent *getnetent(void); +struct protoent *getprotobyname(const char *); +struct protoent *getprotobynumber(int); +struct protoent *getprotoent(void); +struct servent *getservbyname(const char *, const char *); +struct servent *getservbyport(int, const char *); +struct servent *getservent(void); +void sethostent(int); +void setnetent(int); +void setprotoent(int); +void setservent(int); +\fP +.fi +.RE +.LP +The type \fBsocklen_t\fP shall be defined through \fBtypedef\fP as +described in \fI\fP. +.LP +Inclusion of the \fI\fP header may also make visible all +symbols from \fI\fP, \fI\fP, and \fI\fP. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , \fI\fP , +the System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIbind\fP(), +\fIendhostent\fP(), \fIendnetent\fP(), \fIendprotoent\fP(), \fIendservent\fP(), +\fIgetaddrinfo\fP(), \fIgetnameinfo\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/nl_types.h.0p b/man0p/nl_types.h.0p new file mode 100644 index 000000000..0085acd3e --- /dev/null +++ b/man0p/nl_types.h.0p @@ -0,0 +1,82 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +nl_types.h \- data types +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall contain definitions of at least +the following types: +.TP 7 +\fBnl_catd\fP +Used by the message catalog functions \fIcatopen\fP(), \fIcatgets\fP(), +and \fIcatclose\fP() to identify a +catalog descriptor. +.TP 7 +\fBnl_item\fP +Used by \fInl_langinfo\fP() to identify items of \fIlanginfo\fP data. +Values of +objects of type \fBnl_item\fP are defined in \fI\fP . +.sp +.LP +The \fI\fP header shall contain definitions of at least +the following constants: +.TP 7 +NL_SETD +Used by \fIgencat\fP when no $\fIset\fP directive is specified in +a message text source file; see the Internationalization +Guide. This constant can be passed as the value of \fIset_id\fP on +subsequent calls to \fIcatgets\fP() (that is, to retrieve messages +from the default message set). The value of NL_SETD +is implementation-defined. +.TP 7 +NL_CAT_LOCALE +Value that must be passed as the \fIoflag\fP argument to \fIcatopen\fP() +to ensure +that message catalog selection depends on the \fILC_MESSAGES\fP locale +category, rather than directly on the \fILANG\fP +environment variable. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint catclose(nl_catd); +char *catgets(nl_catd, int, int, const char *); +nl_catd catopen(const char *, int); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIcatclose\fP(), \fIcatgets\fP(), \fIcatopen\fP(), \fInl_langinfo\fP(), +the Shell and +Utilities volume of IEEE\ Std\ 1003.1-2001, \fIgencat\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/poll.h.0p b/man0p/poll.h.0p new file mode 100644 index 000000000..e18489f37 --- /dev/null +++ b/man0p/poll.h.0p @@ -0,0 +1,110 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +poll.h \- definitions for the poll() function +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBpollfd\fP structure +that includes at least the following members: +.sp +.RS +.nf + +\fBint fd \fP The following descriptor being polled. \fB +short events \fP The input event flags (see below). \fB +short revents \fP The output event flags (see below). \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the following type through +\fBtypedef\fP: +.TP 7 +\fBnfds_t\fP +An unsigned integer type used for the number of file descriptors. +.sp +.LP +The implementation shall support one or more programming environments +in which the width of \fBnfds_t\fP is no greater than the +width of type \fBlong\fP. The names of these programming environments +can be obtained using the \fIconfstr\fP() function or the \fIgetconf\fP +utility. +.LP +The following symbolic constants shall be defined, zero or more of +which may be OR'ed together to form the \fIevents\fP or +\fIrevents\fP members in the \fBpollfd\fP structure: +.TP 7 +POLLIN +Data other than high-priority data may be read without blocking. +.TP 7 +POLLRDNORM +Normal data may be read without blocking. +.TP 7 +POLLRDBAND +Priority data may be read without blocking. +.TP 7 +POLLPRI +High priority data may be read without blocking. +.TP 7 +POLLOUT +Normal data may be written without blocking. +.TP 7 +POLLWRNORM +Equivalent to POLLOUT. +.TP 7 +POLLWRBAND +Priority data may be written. +.TP 7 +POLLERR +An error has occurred ( \fIrevents\fP only). +.TP 7 +POLLHUP +Device has been disconnected ( \fIrevents\fP only). +.TP 7 +POLLNVAL +Invalid \fIfd\fP member ( \fIrevents\fP only). +.sp +.LP +The significance and semantics of normal, priority, and high-priority +data are file and device-specific. +.LP +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS +.nf + +\fBint poll(struct pollfd[], nfds_t, int); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIconfstr\fP(), +\fIpoll\fP(), the Shell and Utilities volume of IEEE\ Std\ 1003.1-2001, +\fIgetconf\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/pthread.h.0p b/man0p/pthread.h.0p new file mode 100644 index 000000000..b5b93bddd --- /dev/null +++ b/man0p/pthread.h.0p @@ -0,0 +1,385 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +pthread.h \- threads +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following symbols: +.LP +.sp +.sp +PTHREAD_BARRIER_SERIAL_THREAD +.br +.sp +PTHREAD_CANCEL_ASYNCHRONOUS +.br +PTHREAD_CANCEL_ENABLE +.br +PTHREAD_CANCEL_DEFERRED +.br +PTHREAD_CANCEL_DISABLE +.br +PTHREAD_CANCELED +.br +PTHREAD_COND_INITIALIZER +.br +PTHREAD_CREATE_DETACHED +.br +PTHREAD_CREATE_JOINABLE +.br +PTHREAD_EXPLICIT_SCHED +.br +PTHREAD_INHERIT_SCHED +.br +.sp +PTHREAD_MUTEX_DEFAULT +.br +PTHREAD_MUTEX_ERRORCHECK +.br +.sp +PTHREAD_MUTEX_INITIALIZER +.br +.sp +PTHREAD_MUTEX_NORMAL +.br +PTHREAD_MUTEX_RECURSIVE +.br +.sp +PTHREAD_ONCE_INIT +.br +.sp +PTHREAD_PRIO_INHERIT +.br +.sp +.sp +PTHREAD_PRIO_NONE +.br +.sp +.sp +PTHREAD_PRIO_PROTECT +.br +.sp +PTHREAD_PROCESS_SHARED +.br +PTHREAD_PROCESS_PRIVATE +.br +.sp +PTHREAD_SCOPE_PROCESS +.br +PTHREAD_SCOPE_SYSTEM +.br +.sp +.LP +The following types shall be defined as described in \fI\fP +: +.LP +.sp +\fBpthread_attr_t\fP +.br +.sp +\fBpthread_barrier_t\fP +.br +\fBpthread_barrierattr_t\fP +.br +.sp +\fBpthread_cond_t\fP +.br +\fBpthread_condattr_t\fP +.br +\fBpthread_key_t\fP +.br +\fBpthread_mutex_t\fP +.br +\fBpthread_mutexattr_t\fP +.br +\fBpthread_once_t\fP +.br +\fBpthread_rwlock_t\fP +.br +\fBpthread_rwlockattr_t\fP +.br +.sp +\fBpthread_spinlock_t\fP +.br +.sp +\fBpthread_t\fP +.br +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint pthread_atfork(void (*)(void), void (*)(void), + void(*)(void)); +int pthread_attr_destroy(pthread_attr_t *); +int pthread_attr_getdetachstate(const pthread_attr_t *, int *); + +int pthread_attr_getguardsize(const pthread_attr_t *restrict, + size_t *restrict); + + +int pthread_attr_getinheritsched(const pthread_attr_t *restrict, + int *restrict); + +int pthread_attr_getschedparam(const pthread_attr_t *restrict, + struct sched_param *restrict); + +int pthread_attr_getschedpolicy(const pthread_attr_t *restrict, + int *restrict); + + +int pthread_attr_getscope(const pthread_attr_t *restrict, + int *restrict); + + +int pthread_attr_getstack(const pthread_attr_t *restrict, + void **restrict, size_t *restrict); + + +int pthread_attr_getstackaddr(const pthread_attr_t *restrict, + void **restrict); + + +int pthread_attr_getstacksize(const pthread_attr_t *restrict, + size_t *restrict); + +int pthread_attr_init(pthread_attr_t *); +int pthread_attr_setdetachstate(pthread_attr_t *, int); + +int pthread_attr_setguardsize(pthread_attr_t *, size_t); + + +int pthread_attr_setinheritsched(pthread_attr_t *, int); + +int pthread_attr_setschedparam(pthread_attr_t *restrict, + const struct sched_param *restrict); + +int pthread_attr_setschedpolicy(pthread_attr_t *, int); +int pthread_attr_setscope(pthread_attr_t *, int); + + +int pthread_attr_setstack(pthread_attr_t *, void *, size_t); + + +int pthread_attr_setstackaddr(pthread_attr_t *, void *); + + +int pthread_attr_setstacksize(pthread_attr_t *, size_t); + + +int pthread_barrier_destroy(pthread_barrier_t *); +int pthread_barrier_init(pthread_barrier_t *restrict, + const pthread_barrierattr_t *restrict, unsigned); +int pthread_barrier_wait(pthread_barrier_t *); +int pthread_barrierattr_destroy(pthread_barrierattr_t *); + + +int pthread_barrierattr_getpshared( + const pthread_barrierattr_t *restrict, int *restrict); + + +int pthread_barrierattr_init(pthread_barrierattr_t *); + + +int pthread_barrierattr_setpshared(pthread_barrierattr_t *, int); + +int pthread_cancel(pthread_t); +void pthread_cleanup_push(void (*)(void *), void *); +void pthread_cleanup_pop(int); +int pthread_cond_broadcast(pthread_cond_t *); +int pthread_cond_destroy(pthread_cond_t *); +int pthread_cond_init(pthread_cond_t *restrict, + const pthread_condattr_t *restrict); +int pthread_cond_signal(pthread_cond_t *); +int pthread_cond_timedwait(pthread_cond_t *restrict, + pthread_mutex_t *restrict, const struct timespec *restrict); +int pthread_cond_wait(pthread_cond_t *restrict, + pthread_mutex_t *restrict); +int pthread_condattr_destroy(pthread_condattr_t *); + +int pthread_condattr_getclock(const pthread_condattr_t *restrict, + clockid_t *restrict); + + +int pthread_condattr_getpshared(const pthread_condattr_t *restrict, + int *restrict); + +int pthread_condattr_init(pthread_condattr_t *); + +int pthread_condattr_setclock(pthread_condattr_t *, clockid_t); + + +int pthread_condattr_setpshared(pthread_condattr_t *, int); + +int pthread_create(pthread_t *restrict, const pthread_attr_t *restrict, + void *(*)(void *), void *restrict); +int pthread_detach(pthread_t); +int pthread_equal(pthread_t, pthread_t); +void pthread_exit(void *); + +int pthread_getconcurrency(void); + + +int pthread_getcpuclockid(pthread_t, clockid_t *); + + +int pthread_getschedparam(pthread_t, int *restrict, + struct sched_param *restrict); + +void *pthread_getspecific(pthread_key_t); +int pthread_join(pthread_t, void **); +int pthread_key_create(pthread_key_t *, void (*)(void *)); +int pthread_key_delete(pthread_key_t); +int pthread_mutex_destroy(pthread_mutex_t *); + +int pthread_mutex_getprioceiling(const pthread_mutex_t *restrict, + int *restrict); + +int pthread_mutex_init(pthread_mutex_t *restrict, + const pthread_mutexattr_t *restrict); +int pthread_mutex_lock(pthread_mutex_t *); + +int pthread_mutex_setprioceiling(pthread_mutex_t *restrict, int, + int *restrict); + + +int pthread_mutex_timedlock(pthread_mutex_t *, + const struct timespec *); + +int pthread_mutex_trylock(pthread_mutex_t *); +int pthread_mutex_unlock(pthread_mutex_t *); +int pthread_mutexattr_destroy(pthread_mutexattr_t *); + +int pthread_mutexattr_getprioceiling( + const pthread_mutexattr_t *restrict, int *restrict); + + +int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *restrict, + int *restrict); + + +int pthread_mutexattr_getpshared(const pthread_mutexattr_t *restrict, + int *restrict); + + +int pthread_mutexattr_gettype(const pthread_mutexattr_t *restrict, + int *restrict); + +int pthread_mutexattr_init(pthread_mutexattr_t *); + +int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *, int); + + +int pthread_mutexattr_setprotocol(pthread_mutexattr_t *, int); + + +int pthread_mutexattr_setpshared(pthread_mutexattr_t *, int); + + +int pthread_mutexattr_settype(pthread_mutexattr_t *, int); + +int pthread_once(pthread_once_t *, void (*)(void)); +int pthread_rwlock_destroy(pthread_rwlock_t *); +int pthread_rwlock_init(pthread_rwlock_t *restrict, + const pthread_rwlockattr_t *restrict); +int pthread_rwlock_rdlock(pthread_rwlock_t *); + +int pthread_rwlock_timedrdlock(pthread_rwlock_t *restrict, + const struct timespec *restrict); +int pthread_rwlock_timedwrlock(pthread_rwlock_t *restrict, + const struct timespec *restrict); + +int pthread_rwlock_tryrdlock(pthread_rwlock_t *); +int pthread_rwlock_trywrlock(pthread_rwlock_t *); +int pthread_rwlock_unlock(pthread_rwlock_t *); +int pthread_rwlock_wrlock(pthread_rwlock_t *); +int pthread_rwlockattr_destroy(pthread_rwlockattr_t *); + +int pthread_rwlockattr_getpshared( + const pthread_rwlockattr_t *restrict, int *restrict); + +int pthread_rwlockattr_init(pthread_rwlockattr_t *); + +int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *, int); + +pthread_t + pthread_self(void); +int pthread_setcancelstate(int, int *); +int pthread_setcanceltype(int, int *); + +int pthread_setconcurrency(int); + + +int pthread_setschedparam(pthread_t, int, + const struct sched_param *); + + +int pthread_setschedprio(pthread_t, int); + +int pthread_setspecific(pthread_key_t, const void *); + +int pthread_spin_destroy(pthread_spinlock_t *); +int pthread_spin_init(pthread_spinlock_t *, int); +int pthread_spin_lock(pthread_spinlock_t *); +int pthread_spin_trylock(pthread_spinlock_t *); +int pthread_spin_unlock(pthread_spinlock_t *); + +void pthread_testcancel(void); +\fP +.fi +.RE +.LP +Inclusion of the \fI\fP header shall make symbols defined +in the headers \fI\fP and \fI\fP visible. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , \fI\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIpthread_attr_getguardsize\fP(), +\fIpthread_attr_init\fP(), \fIpthread_attr_setscope\fP(), \fIpthread_barrier_destroy\fP(), +\fIpthread_barrier_init\fP(), \fIpthread_barrier_wait\fP(), \fIpthread_barrierattr_destroy\fP(), +\fIpthread_barrierattr_getpshared\fP(), \fIpthread_barrierattr_init\fP(), +\fIpthread_barrierattr_setpshared\fP(), \fIpthread_cancel\fP(), \fIpthread_cleanup_pop\fP(), +\fIpthread_cond_init\fP(), \fIpthread_cond_signal\fP(), \fIpthread_cond_wait\fP(), +\fIpthread_condattr_getclock\fP(), \fIpthread_condattr_init\fP(), +\fIpthread_condattr_setclock\fP(), \fIpthread_create\fP(), \fIpthread_detach\fP(), +\fIpthread_equal\fP(), \fIpthread_exit\fP(), +\fIpthread_getconcurrency\fP(), \fIpthread_getcpuclockid\fP(), \fIpthread_getschedparam\fP(), +\fIpthread_join\fP(), \fIpthread_key_create\fP(), \fIpthread_key_delete\fP(), +\fIpthread_mutex_init\fP(), \fIpthread_mutex_lock\fP(), \fIpthread_mutex_setprioceiling\fP(), +\fIpthread_mutex_timedlock\fP(), \fIpthread_mutexattr_init\fP(), \fIpthread_mutexattr_gettype\fP(), +\fIpthread_mutexattr_setprotocol\fP(), \fIpthread_once\fP(), \fIpthread_rwlock_destroy\fP(), +\fIpthread_rwlock_init\fP(), \fIpthread_rwlock_rdlock\fP(), \fIpthread_rwlock_timedrdlock\fP(), +\fIpthread_rwlock_timedwrlock\fP(), \fIpthread_rwlock_tryrdlock\fP(), +\fIpthread_rwlock_trywrlock\fP(), \fIpthread_rwlock_unlock\fP(), \fIpthread_rwlock_wrlock\fP(), +\fIpthread_rwlockattr_destroy\fP(), \fIpthread_rwlockattr_getpshared\fP(), +\fIpthread_rwlockattr_init\fP(), \fIpthread_rwlockattr_setpshared\fP(), +\fIpthread_self\fP(), \fIpthread_setcancelstate\fP(), \fIpthread_setspecific\fP(), +\fIpthread_spin_destroy\fP(), \fIpthread_spin_init\fP(), \fIpthread_spin_lock\fP(), +\fIpthread_spin_trylock\fP(), \fIpthread_spin_unlock\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/pwd.h.0p b/man0p/pwd.h.0p new file mode 100644 index 000000000..b90cf19dd --- /dev/null +++ b/man0p/pwd.h.0p @@ -0,0 +1,76 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +pwd.h \- password structure +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall provide a definition for \fBstruct +passwd\fP, which shall include at least the following +members: +.sp +.RS +.nf + +\fBchar *pw_name \fP User's login name. \fB +uid_t pw_uid \fP Numerical user ID. \fB +gid_t pw_gid \fP Numerical group ID. \fB +char *pw_dir \fP Initial working directory. \fB +char *pw_shell \fP Program to use as shell. \fB +\fP +.fi +.RE +.LP +The \fBgid_t\fP and \fBuid_t\fP types shall be defined as described +in \fI\fP . +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBstruct passwd *getpwnam(const char *); +struct passwd *getpwuid(uid_t); + +int getpwnam_r(const char *, struct passwd *, char *, + size_t, struct passwd **); +int getpwuid_r(uid_t, struct passwd *, char *, + size_t, struct passwd **); + + +void endpwent(void); +struct passwd *getpwent(void); +void setpwent(void); + +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIendpwent\fP(), \fIgetpwnam\fP(), \fIgetpwuid\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/regex.h.0p b/man0p/regex.h.0p new file mode 100644 index 000000000..f8da9f2b8 --- /dev/null +++ b/man0p/regex.h.0p @@ -0,0 +1,164 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +regex.h \- regular expression matching types +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the structures and symbolic +constants used by the \fIregcomp\fP(), \fIregexec\fP(), \fIregerror\fP(), +and \fIregfree\fP() functions. +.LP +The structure type \fBregex_t\fP shall contain at least the following +member: +.sp +.RS +.nf + +\fBsize_t re_nsub \fP Number of parenthesized subexpressions. \fB +\fP +.fi +.RE +.LP +The type \fBsize_t\fP shall be defined as described in \fI\fP +\&. +.LP +The type \fBregoff_t\fP shall be defined as a signed integer type +that can hold the largest value that can be stored in either +a type \fBoff_t\fP or type \fBssize_t\fP. The structure type \fBregmatch_t\fP +shall contain at least the following members: +.sp +.RS +.nf + +\fBregoff_t rm_so \fP Byte offset from start of string \fB + \fP to start of substring. \fB +regoff_t rm_eo \fP Byte offset from start of string of the \fB + \fP first character after the end of substring. \fB +\fP +.fi +.RE +.LP +Values for the \fIcflags\fP parameter to the \fIregcomp\fP() function +are as +follows: +.TP 7 +REG_EXTENDED +Use Extended Regular Expressions. +.TP 7 +REG_ICASE +Ignore case in match. +.TP 7 +REG_NOSUB +Report only success or fail in \fIregexec\fP(). +.TP 7 +REG_NEWLINE +Change the handling of . +.sp +.LP +Values for the \fIeflags\fP parameter to the \fIregexec\fP() function +are as +follows: +.TP 7 +REG_NOTBOL +The circumflex character ( \fB'^'\fP ), when taken as a special character, +does not match the beginning of +\fIstring\fP. +.TP 7 +REG_NOTEOL +The dollar sign ( \fB'$'\fP ), when taken as a special character, +does not match the end of \fIstring\fP. +.sp +.LP +The following constants shall be defined as error return values: +.TP 7 +REG_NOMATCH +\fIregexec\fP() failed to match. +.TP 7 +REG_BADPAT +Invalid regular expression. +.TP 7 +REG_ECOLLATE +Invalid collating element referenced. +.TP 7 +REG_ECTYPE +Invalid character class type referenced. +.TP 7 +REG_EESCAPE +Trailing \fB'\\'\fP in pattern. +.TP 7 +REG_ESUBREG +Number in \\\fIdigit\fP invalid or in error. +.TP 7 +REG_EBRACK +\fB"[]"\fP imbalance. +.TP 7 +REG_EPAREN +\fB"\\(\\)"\fP or \fB"()"\fP imbalance. +.TP 7 +REG_EBRACE +\fB"\\{\\}"\fP imbalance. +.TP 7 +REG_BADBR +Content of \fB"\\{\\}"\fP invalid: not a number, number too large, +more than two numbers, first larger than second. +.TP 7 +REG_ERANGE +Invalid endpoint in range expression. +.TP 7 +REG_ESPACE +Out of memory. +.TP 7 +REG_BADRPT +\fB'?'\fP , \fB'*'\fP , or \fB'+'\fP not preceded by valid regular +expression. +.TP 7 +REG_ENOSYS +Reserved. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint regcomp(regex_t *restrict, const char *restrict, int); +size_t regerror(int, const regex_t *restrict, char *restrict, size_t); +int regexec(const regex_t *restrict, const char *restrict, size_t, + regmatch_t[restrict], int); +void regfree(regex_t *); +\fP +.fi +.RE +.LP +The implementation may define additional macros or constants using +names beginning with REG_. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIregcomp\fP(), the Shell and Utilities volume of IEEE\ Std\ 1003.1-2001 +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/resource.h.0p b/man0p/resource.h.0p new file mode 100644 index 000000000..8790e2dd8 --- /dev/null +++ b/man0p/resource.h.0p @@ -0,0 +1 @@ +.so man0p/sys_resource.h.0p diff --git a/man0p/sched.h.0p b/man0p/sched.h.0p new file mode 100644 index 000000000..1d52bc727 --- /dev/null +++ b/man0p/sched.h.0p @@ -0,0 +1,118 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sched.h \- execution scheduling (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBsched_param\fP structure, +which contains the scheduling parameters +required for implementation of each supported scheduling policy. This +structure shall contain at least the following member: +.sp +.RS +.nf + +\fBint sched_priority \fP Process execution scheduling priority. \fB +\fP +.fi +.RE +.LP +In addition, if _POSIX_SPORADIC_SERVER or _POSIX_THREAD_SPORADIC_SERVER +is defined, the \fBsched_param\fP structure defined in +\fI\fP shall contain the following members in addition to +those specified above: +.sp +.RS +.nf + +\fBint sched_ss_low_priority\fP Low scheduling priority for \fB + \fP sporadic server. \fB +struct timespec sched_ss_repl_period \fP Replenishment period for \fB + \fP sporadic server. \fB +struct timespec sched_ss_init_budget \fP Initial budget for sporadic server. \fB +int sched_ss_max_repl \fP Maximum pending replenishments for \fB + \fP sporadic server. \fB +\fP +.fi +.RE +.LP +Each process is controlled by an associated scheduling policy and +priority. Associated with each policy is a priority range. +Each policy definition specifies the minimum priority range for that +policy. The priority ranges for each policy may overlap the +priority ranges of other policies. +.LP +Four scheduling policies are defined; others may be defined by the +implementation. The four standard policies are indicated by +the values of the following symbolic constants: +.TP 7 +SCHED_FIFO +First in-first out (FIFO) scheduling policy. +.TP 7 +SCHED_RR +Round robin scheduling policy. +.TP 7 +SCHED_SPORADIC +Sporadic server scheduling policy. +.TP 7 +SCHED_OTHER +Another scheduling policy. +.sp +.LP +The values of these constants are distinct. +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fB +int sched_get_priority_max(int); +int sched_get_priority_min(int); + +int sched_getparam(pid_t, struct sched_param *); +int sched_getscheduler(pid_t); + +int sched_rr_get_interval(pid_t, struct timespec *); + +int sched_setparam(pid_t, const struct sched_param *); +int sched_setscheduler(pid_t, int, const struct sched_param *); + +int sched_yield(void); + + +\fP +.fi +.RE +.LP +Inclusion of the \fI\fP header may make visible all symbols +from the \fI\fP header. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/search.h.0p b/man0p/search.h.0p new file mode 100644 index 000000000..e00ea386f --- /dev/null +++ b/man0p/search.h.0p @@ -0,0 +1,90 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +search.h \- search tables +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBENTRY\fP type for +structure \fBentry\fP which shall include the +following members: +.sp +.RS +.nf + +\fBchar *key +void *data +\fP +.fi +.RE +.LP +and shall define \fBACTION\fP and \fBVISIT\fP as enumeration data +types through type definitions as follows: +.sp +.RS +.nf + +\fBenum { FIND, ENTER } ACTION; +enum { preorder, postorder, endorder, leaf } VISIT; +\fP +.fi +.RE +.LP +The \fBsize_t\fP type shall be defined as described in \fI\fP +\&. +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint hcreate(size_t); +void hdestroy(void); +ENTRY *hsearch(ENTRY, ACTION); +void insque(void *, void *); +void *lfind(const void *, const void *, size_t *, + size_t, int (*)(const void *, const void *)); +void *lsearch(const void *, void *, size_t *, + size_t, int (*)(const void *, const void *)); +void remque(void *); +void *tdelete(const void *restrict, void **restrict, + int(*)(const void *, const void *)); +void *tfind(const void *, void *const *, + int(*)(const void *, const void *)); +void *tsearch(const void *, void **, + int(*)(const void *, const void *)); +void twalk(const void *, + void (*)(const void *, VISIT, int )); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIhcreate\fP(), \fIinsque\fP(), \fIlsearch\fP(), \fIremque\fP(), +\fItsearch\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/select.h.0p b/man0p/select.h.0p new file mode 100644 index 000000000..622fe520f --- /dev/null +++ b/man0p/select.h.0p @@ -0,0 +1 @@ +.so man0p/sys_select.h.0p diff --git a/man0p/sem.h.0p b/man0p/sem.h.0p new file mode 100644 index 000000000..779dc5282 --- /dev/null +++ b/man0p/sem.h.0p @@ -0,0 +1 @@ +.so man0p/sys_sem.h.0p diff --git a/man0p/semaphore.h.0p b/man0p/semaphore.h.0p new file mode 100644 index 000000000..392c13b2d --- /dev/null +++ b/man0p/semaphore.h.0p @@ -0,0 +1,67 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +semaphore.h \- semaphores (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBsem_t\fP type, +used in performing semaphore operations. The semaphore +may be implemented using a file descriptor, in which case applications +are able to open up at least a total of {OPEN_MAX} files and +semaphores. The symbol SEM_FAILED shall be defined (see \fIsem_open\fP()). +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint sem_close(sem_t *); +int sem_destroy(sem_t *); +int sem_getvalue(sem_t *restrict, int *restrict); +int sem_init(sem_t *, int, unsigned); +sem_t *sem_open(const char *, int, ...); +int sem_post(sem_t *); + +int sem_timedwait(sem_t *restrict, const struct timespec *restrict); + +int sem_trywait(sem_t *); +int sem_unlink(const char *); +int sem_wait(sem_t *); +\fP +.fi +.RE +.LP +Inclusion of the \fI\fP header may make visible symbols +defined in the headers \fI\fP and \fI\fP. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIsem_destroy\fP(), +\fIsem_getvalue\fP(), \fIsem_init\fP(), \fIsem_open\fP(), \fIsem_post\fP(), +\fIsem_timedwait\fP(), \fIsem_trywait\fP(), \fIsem_unlink\fP(), \fIsem_wait\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/setjmp.h.0p b/man0p/setjmp.h.0p new file mode 100644 index 000000000..5a8c515f9 --- /dev/null +++ b/man0p/setjmp.h.0p @@ -0,0 +1,78 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +setjmp.h \- stack environment declarations +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +Some of the functionality described on this reference page extends +the ISO\ C standard. Applications shall define +the appropriate feature test macro (see the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, Section 2.2, The Compilation Environment) +to enable the visibility of these symbols in this +header. +.LP +The \fI\fP header shall define the array types \fBjmp_buf\fP +and \fBsigjmp_buf\fP. +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBvoid longjmp(jmp_buf, int); + +void siglongjmp(sigjmp_buf, int); + + +void _longjmp(jmp_buf, int); + +\fP +.fi +.RE +.LP +The following may be declared as a function, or defined as a macro, +or both. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint setjmp(jmp_buf); + +int sigsetjmp(sigjmp_buf, int); + + +int _setjmp(jmp_buf); + +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIlongjmp\fP(), +\fI_longjmp\fP(), \fIsetjmp\fP(), \fIsiglongjmp\fP(), \fIsigsetjmp\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/shm.h.0p b/man0p/shm.h.0p new file mode 100644 index 000000000..7d34a0d1a --- /dev/null +++ b/man0p/shm.h.0p @@ -0,0 +1 @@ +.so man0p/sys_shm.h.0p diff --git a/man0p/signal.h.0p b/man0p/signal.h.0p new file mode 100644 index 000000000..1cfa3f019 --- /dev/null +++ b/man0p/signal.h.0p @@ -0,0 +1,788 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +signal.h \- signals +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +Some of the functionality described on this reference page extends +the ISO\ C standard. Applications shall define +the appropriate feature test macro (see the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, Section 2.2, The Compilation Environment) +to enable the visibility of these symbols in this +header. +.LP +The \fI\fP header shall define the following symbolic constants, +each of which expands to a distinct constant +expression of the type: +.sp +.RS +.nf + +\fBvoid (*)(int) +\fP +.fi +.RE +.LP +whose value matches no declarable function. +.TP 7 +SIG_DFL +Request for default signal handling. +.TP 7 +SIG_ERR +Return value from \fIsignal\fP() in case of error. +.TP 7 +SIG_HOLD +Request that signal be held. +.TP 7 +SIG_IGN +Request that signal be ignored. +.sp +.LP +The following data types shall be defined through \fBtypedef\fP: +.TP 7 +\fBsig_atomic_t\fP +Possibly volatile-qualified integer type of an object that can be +accessed as an atomic entity, even in the presence of +asynchronous interrupts. +.TP 7 +\fBsigset_t\fP +Integer or structure type of an object used to represent sets of signals. +.TP 7 +\fBpid_t\fP +As +described in \fI\fP . +.sp +.LP +The \fI\fP header shall define the \fBsigevent\fP structure, +which has at least the following members: +.sp +.RS +.nf + +\fBint sigev_notify \fP Notification type. \fB +int sigev_signo \fP Signal number. \fB +union sigval sigev_value \fP Signal value. \fB +void(*)(union sigval) sigev_notify_function \fP Notification function. \fB +(pthread_attr_t *) sigev_notify_attributes\fP Notification attributes. \fB +\fP +.fi +.RE +.LP +The following values of \fIsigev_notify\fP shall be defined: +.TP 7 +SIGEV_NONE +No asynchronous notification is delivered when the event of interest +occurs. +.TP 7 +SIGEV_SIGNAL +A queued signal, with an application-defined value, is generated when +the event of interest occurs. +.TP 7 +SIGEV_THREAD +A notification function is called to perform notification. +.sp +.LP +The \fBsigval\fP union shall be defined as: +.sp +.RS +.nf + +\fBint sival_int \fP Integer signal value. \fB +void *sival_ptr \fP Pointer signal value. \fB +\fP +.fi +.RE +.LP +This header shall also declare the macros SIGRTMIN and SIGRTMAX, which +evaluate to integer expressions, and specify a range of +signal numbers that are reserved for application use and for which +the realtime signal behavior specified in this volume of +IEEE\ Std\ 1003.1-2001 is supported. The signal numbers in this range +do not overlap any of the signals specified in the +following table. +.LP +The range SIGRTMIN through SIGRTMAX inclusive shall include at least +{RTSIG_MAX} signal numbers. +.LP +It is implementation-defined whether realtime signal behavior is supported +for other signals. +.LP +This header also declares the constants that are used to refer to +the signals that occur in the system. Signals defined here +begin with the letters SIG. Each of the signals have distinct positive +integer values. The value 0 is reserved for use as the null +signal (see \fIkill\fP()). Additional implementation-defined signals +may occur in the +system. +.LP +The +ISO\ C standard only requires the signal names SIGABRT, SIGFPE, SIGILL, +SIGINT, SIGSEGV, and SIGTERM to be defined. +.LP +The following signals shall be supported on all implementations (default +actions are explained below the table): +.TS C +center; l1 l1 lw(40). +\fBSignal\fP \fBDefault Action\fP T{ +.na +\fBDescription\fP +.ad +T} +SIGABRT A T{ +.na +Process abort signal. +.ad +T} +SIGALRM T T{ +.na +Alarm clock. +.ad +T} +SIGBUS A T{ +.na +Access to an undefined portion of a memory object. +.ad +T} +SIGCHLD I T{ +.na +Child process terminated, stopped, +.ad +T} +\ \ T{ +.na +or continued. +.ad +T} +SIGCONT C T{ +.na +Continue executing, if stopped. +.ad +T} +SIGFPE A T{ +.na +Erroneous arithmetic operation. +.ad +T} +SIGHUP T T{ +.na +Hangup. +.ad +T} +SIGILL A T{ +.na +Illegal instruction. +.ad +T} +SIGINT T T{ +.na +Terminal interrupt signal. +.ad +T} +SIGKILL T T{ +.na +Kill (cannot be caught or ignored). +.ad +T} +SIGPIPE T T{ +.na +Write on a pipe with no one to read it. +.ad +T} +SIGQUIT A T{ +.na +Terminal quit signal. +.ad +T} +SIGSEGV A T{ +.na +Invalid memory reference. +.ad +T} +SIGSTOP S T{ +.na +Stop executing (cannot be caught or ignored). +.ad +T} +SIGTERM T T{ +.na +Termination signal. +.ad +T} +SIGTSTP S T{ +.na +Terminal stop signal. +.ad +T} +SIGTTIN S T{ +.na +Background process attempting read. +.ad +T} +SIGTTOU S T{ +.na +Background process attempting write. +.ad +T} +SIGUSR1 T T{ +.na +User-defined signal 1. +.ad +T} +SIGUSR2 T T{ +.na +User-defined signal 2. +.ad +T} +SIGPOLL T T{ +.na +Pollable event. +.ad +T} +SIGPROF T T{ +.na +Profiling timer expired. +.ad +T} +SIGSYS A T{ +.na +Bad system call. +.ad +T} +SIGTRAP A T{ +.na +Trace/breakpoint trap. +.ad +T} +SIGURG I T{ +.na +High bandwidth data is available at a socket. +.ad +T} +SIGVTALRM T T{ +.na +Virtual timer expired. +.ad +T} +SIGXCPU A T{ +.na +CPU time limit exceeded. +.ad +T} +SIGXFSZ A T{ +.na +File size limit exceeded. +.ad +T} +.TE +.LP +The default actions are as follows: +.TP 7 +T +Abnormal termination of the process. The process is terminated with +all the consequences of \fI_exit\fP() except that the status made +available to \fIwait\fP() and \fIwaitpid\fP() indicates abnormal +termination by the specified signal. +.TP 7 +A +Abnormal termination of the process. +.br +Additionally, implementation-defined abnormal termination actions, +such as creation of a \fBcore\fP file, may occur. +.TP 7 +I +Ignore the signal. +.TP 7 +S +Stop the process. +.TP 7 +C +Continue the process, if it is stopped; otherwise, ignore the signal. +.sp +.sp +.LP +The +header shall provide a declaration of \fBstruct sigaction\fP, including +at least the following members: +.sp +.RS +.nf + +\fBvoid (*sa_handler)(int) \fP Pointer to a signal-catching function or one of the macros \fB + \fP SIG_IGN or SIG_DFL. \fB +sigset_t sa_mask \fP Set of signals to be blocked during execution of the signal \fB + \fP handling function. \fB +int sa_flags \fP Special flags. \fB +void (*sa_sigaction)(int, siginfo_t *, void *) + \fP Pointer to a signal-catching function. \fB +\fP +.fi +.RE +.LP +The storage occupied by \fIsa_handler\fP and \fIsa_sigaction\fP may +overlap, and a conforming application shall not use both +simultaneously. +.LP +The following shall be declared as constants: +.TP 7 +SA_NOCLDSTOP +Do +not generate SIGCHLD when children stop +.br +or +stopped children continue. +.TP 7 +SIG_BLOCK +The resulting set is the union of the current set and the signal set +pointed to by the argument \fIset\fP. +.TP 7 +SIG_UNBLOCK +The resulting set is the intersection of the current set and the complement +of the signal set pointed to by the argument +\fIset\fP. +.TP 7 +SIG_SETMASK +The resulting set is the signal set pointed to by the argument \fIset\fP. +.TP 7 +SA_ONSTACK +Causes signal delivery to occur on an alternate stack. +.TP 7 +SA_RESETHAND +Causes signal dispositions to be set to SIG_DFL on entry to signal +handlers. +.TP 7 +SA_RESTART +Causes certain functions to become restartable. +.TP 7 +SA_SIGINFO +Causes extra information to be passed to signal handlers at the time +of receipt of a signal. +.TP 7 +SA_NOCLDWAIT +Causes implementations not to create zombie processes on child death. +.TP 7 +SA_NODEFER +Causes signal not to be automatically blocked on entry to signal handler. +.TP 7 +SS_ONSTACK +Process is executing on an alternate signal stack. +.TP 7 +SS_DISABLE +Alternate signal stack is disabled. +.TP 7 +MINSIGSTKSZ +Minimum stack size for a signal handler. +.TP 7 +SIGSTKSZ +Default size in bytes for the alternate signal stack. +.sp +.LP +The \fBucontext_t\fP structure shall be defined through \fBtypedef\fP +as described in \fI\fP. +.LP +The \fBmcontext_t\fP type shall be defined through \fBtypedef\fP as +described in \fI\fP. +.LP +The \fI\fP header shall define the \fBstack_t\fP type as +a structure that includes at least the following +members: +.sp +.RS +.nf + +\fBvoid *ss_sp \fP Stack base or pointer. \fB +size_t ss_size \fP Stack size. \fB +int ss_flags \fP Flags. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the \fBsigstack\fP structure +that includes at least the following members: +.sp +.RS +.nf + +\fBint ss_onstack \fP Non-zero when signal stack is in use. \fB +void *ss_sp \fP Signal stack pointer. \fB +\fP +.fi +.RE +.LP +The +\fI\fP header shall define the \fBsiginfo_t\fP type as a +structure that includes at least the following members: +.sp +.RS +.nf + +\fB +int si_signo \fP Signal number. \fB + + +int si_errno \fP If non-zero, an \fIerrno\fP value associated with \fB + \fP this signal, as defined in \fB.\fP \fB + + +int si_code \fP Signal code. \fB + + +pid_t si_pid \fP Sending process ID. \fB +uid_t si_uid \fP Real user ID of sending process. \fB +void *si_addr \fP Address of faulting instruction. \fB +int si_status\fP Exit value or signal. \fB +long si_band \fP Band event for SIGPOLL. \fB + + +union sigval si_value \fP Signal value. \fB + +\fP +.fi +.RE +.LP +The macros specified in the \fBCode\fP column of the following table +are defined for use as values of \fIsi_code\fP that are +\ signal-specific or non-signal-specific reasons why the signal +was generated. +.TS C +center; l l lw(40). +\fBSignal\fP \fBCode\fP T{ +.na +\fBReason\fP +.ad +T} +SIGILL ILL_ILLOPC T{ +.na +Illegal opcode. +.ad +T} +\ ILL_ILLOPN T{ +.na +Illegal operand. +.ad +T} +\ ILL_ILLADR T{ +.na +Illegal addressing mode. +.ad +T} +\ ILL_ILLTRP T{ +.na +Illegal trap. +.ad +T} +\ ILL_PRVOPC T{ +.na +Privileged opcode. +.ad +T} +\ ILL_PRVREG T{ +.na +Privileged register. +.ad +T} +\ ILL_COPROC T{ +.na +Coprocessor error. +.ad +T} +\ ILL_BADSTK T{ +.na +Internal stack error. +.ad +T} +SIGFPE FPE_INTDIV T{ +.na +Integer divide by zero. +.ad +T} +\ FPE_INTOVF T{ +.na +Integer overflow. +.ad +T} +\ FPE_FLTDIV T{ +.na +Floating-point divide by zero. +.ad +T} +\ FPE_FLTOVF T{ +.na +Floating-point overflow. +.ad +T} +\ FPE_FLTUND T{ +.na +Floating-point underflow. +.ad +T} +\ FPE_FLTRES T{ +.na +Floating-point inexact result. +.ad +T} +\ FPE_FLTINV T{ +.na +Invalid floating-point operation. +.ad +T} +\ FPE_FLTSUB T{ +.na +Subscript out of range. +.ad +T} +SIGSEGV SEGV_MAPERR T{ +.na +Address not mapped to object. +.ad +T} +\ SEGV_ACCERR T{ +.na +Invalid permissions for mapped object. +.ad +T} +SIGBUS BUS_ADRALN T{ +.na +Invalid address alignment. +.ad +T} +\ BUS_ADRERR T{ +.na +Nonexistent physical address. +.ad +T} +\ BUS_OBJERR T{ +.na +Object-specific hardware error. +.ad +T} +SIGTRAP TRAP_BRKPT T{ +.na +Process breakpoint. +.ad +T} +\ TRAP_TRACE T{ +.na +Process trace trap. +.ad +T} +SIGCHLD CLD_EXITED T{ +.na +Child has exited. +.ad +T} +\ CLD_KILLED T{ +.na +Child has terminated abnormally and did not create a \fBcore\fP file. +.ad +T} +\ CLD_DUMPED T{ +.na +Child has terminated abnormally and created a \fBcore\fP file. +.ad +T} +\ CLD_TRAPPED T{ +.na +Traced child has trapped. +.ad +T} +\ CLD_STOPPED T{ +.na +Child has stopped. +.ad +T} +\ CLD_CONTINUED T{ +.na +Stopped child has continued. +.ad +T} +SIGPOLL POLL_IN T{ +.na +Data input available. +.ad +T} +\ POLL_OUT T{ +.na +Output buffers available. +.ad +T} +\ POLL_MSG T{ +.na +Input message available. +.ad +T} +\ POLL_ERR T{ +.na +I/O error. +.ad +T} +\ POLL_PRI T{ +.na +High priority input available. +.ad +T} +\ POLL_HUP T{ +.na +Device disconnected. +.ad +T} +Any SI_USER T{ +.na +Signal sent by \fIkill\fP(). +.ad +T} +\ SI_QUEUE T{ +.na +Signal sent by the \fIsigqueue\fP(). +.ad +T} +\ SI_TIMER T{ +.na +Signal generated by expiration of a timer set by \fItimer_settime\fP(). +.ad +T} +\ SI_ASYNCIO T{ +.na +Signal generated by completion of an asynchronous I/O request. +.ad +T} +\ SI_MESGQ T{ +.na +Signal generated by arrival of a message on an empty message queue. +.ad +T} +.TE +.LP +Implementations may support additional \fIsi_code\fP values not included +in this list, may generate values included in this list +under circumstances other than those described in this list, and may +contain extensions or limitations that prevent some values +from being generated. Implementations do not generate a different +value from the ones described in this list for circumstances +described in this list. +.LP +In addition, the following signal-specific information shall be available: +.TS C +center; l1 l1 l. +\fBSignal\fP \fBMember\fP \fBValue\fP +SIGILL \fBvoid * \fIsi_addr\fP\fP Address of faulting instruction. +SIGFPE \fB\ \fP \ +SIGSEGV \fBvoid * \fIsi_addr\fP\fP Address of faulting memory reference. +SIGBUS \fB\ \fP \ +SIGCHLD \fBpid_t \fIsi_pid\fP\fP Child process ID. +\ \fBint \fIsi_status\fP\fP Exit value or signal. +\ \fBuid_t \fIsi_uid\fP\fP Real user ID of the process that sent the signal. +SIGPOLL \fBlong \fIsi_band\fP\fP Band event for POLL_IN, POLL_OUT, or POLL_MSG. +.TE +.LP +For some implementations, the value of \fIsi_addr\fP may be inaccurate. +.LP +The following shall be declared as functions and may also be defined +as macros: +.sp +.RS +.nf + +\fB +void (*bsd_signal(int, void (*)(int)))(int); + + +int kill(pid_t, int); + + +int killpg(pid_t, int); + + +int pthread_kill(pthread_t, int); +int pthread_sigmask(int, const sigset_t *, sigset_t *); + +int raise(int); + +int sigaction(int, const struct sigaction *restrict, + struct sigaction *restrict); +int sigaddset(sigset_t *, int); + + +int sigaltstack(const stack_t *restrict, stack_t *restrict); + + +int sigdelset(sigset_t *, int); +int sigemptyset(sigset_t *); +int sigfillset(sigset_t *); + + +int sighold(int); +int sigignore(int); +int siginterrupt(int, int); + + +int sigismember(const sigset_t *, int); + +void (*signal(int, void (*)(int)))(int); + +int sigpause(int); + + +int sigpending(sigset_t *); +int sigprocmask(int, const sigset_t *restrict, sigset_t *restrict); + + +int sigqueue(pid_t, int, const union sigval); + + +int sigrelse(int); +void (*sigset(int, void (*)(int)))(int); + + +int sigsuspend(const sigset_t *); + + +int sigtimedwait(const sigset_t *restrict, siginfo_t *restrict, + const struct timespec *restrict); + + +int sigwait(const sigset_t *restrict, int *restrict); + + +int sigwaitinfo(const sigset_t *restrict, siginfo_t *restrict); + +\fP +.fi +.RE +.LP +Inclusion of the \fI\fP header may make visible all symbols +from the \fI\fP header. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , \fI\fP , \fI\fP +, \fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIalarm\fP(), \fIbsd_signal\fP(), \fIioctl\fP(), \fIkill\fP(), \fIkillpg\fP(), +\fIraise\fP(), \fIsigaction\fP(), \fIsigaddset\fP(), \fIsigaltstack\fP(), +\fIsigdelset\fP(), \fIsigemptyset\fP(), \fIsigfillset\fP(), \fIsiginterrupt\fP(), +\fIsigismember\fP(), \fIsignal\fP(), \fIsigpending\fP(), \fIsigprocmask\fP(), +\fIsigqueue\fP(), \fIsigsuspend\fP(), \fIsigwaitinfo\fP(), \fIwait\fP(), +\fIwaitid\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/socket.h.0p b/man0p/socket.h.0p new file mode 100644 index 000000000..0249e23b1 --- /dev/null +++ b/man0p/socket.h.0p @@ -0,0 +1 @@ +.so man0p/sys_socket.h.0p diff --git a/man0p/spawn.h.0p b/man0p/spawn.h.0p new file mode 100644 index 000000000..c553d2ac5 --- /dev/null +++ b/man0p/spawn.h.0p @@ -0,0 +1,128 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +spawn.h \- spawn (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBposix_spawnattr_t\fP +and \fBposix_spawn_file_actions_t\fP types used in +performing spawn operations. +.LP +The \fI\fP header shall define the flags that may be set +in a \fBposix_spawnattr_t\fP object using the \fIposix_spawnattr_setflags\fP() +function: +.LP +.sp +POSIX_SPAWN_RESETIDS +.br +POSIX_SPAWN_SETPGROUP +.br +.sp +POSIX_SPAWN_SETSCHEDPARAM +.br +POSIX_SPAWN_SETSCHEDULER +.br +.sp +POSIX_SPAWN_SETSIGDEF +.br +POSIX_SPAWN_SETSIGMASK +.br +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint posix_spawn(pid_t *restrict, const char *restrict, + const posix_spawn_file_actions_t *, + const posix_spawnattr_t *restrict, char *const [restrict], + char *const [restrict]); +int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t *, + int); +int posix_spawn_file_actions_adddup2(posix_spawn_file_actions_t *, + int, int); +int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t *restrict, + int, const char *restrict, int, mode_t); +int posix_spawn_file_actions_destroy(posix_spawn_file_actions_t *); +int posix_spawn_file_actions_init(posix_spawn_file_actions_t *); +int posix_spawnattr_destroy(posix_spawnattr_t *); +int posix_spawnattr_getsigdefault(const posix_spawnattr_t *restrict, + sigset_t *restrict); +int posix_spawnattr_getflags(const posix_spawnattr_t *restrict, + short *restrict); +int posix_spawnattr_getpgroup(const posix_spawnattr_t *restrict, + pid_t *restrict); + +int posix_spawnattr_getschedparam(const posix_spawnattr_t *restrict, + struct sched_param *restrict); +int posix_spawnattr_getschedpolicy(const posix_spawnattr_t *restrict, + int *restrict); + +int posix_spawnattr_getsigmask(const posix_spawnattr_t *restrict, + sigset_t *restrict); +int posix_spawnattr_init(posix_spawnattr_t *); +int posix_spawnattr_setsigdefault(posix_spawnattr_t *restrict, + const sigset_t *restrict); +int posix_spawnattr_setflags(posix_spawnattr_t *, short); +int posix_spawnattr_setpgroup(posix_spawnattr_t *, pid_t); +.sp + + +int posix_spawnattr_setschedparam(posix_spawnattr_t *restrict, + const struct sched_param *restrict); +int posix_spawnattr_setschedpolicy(posix_spawnattr_t *, int); + +int posix_spawnattr_setsigmask(posix_spawnattr_t *restrict, + const sigset_t *restrict); +int posix_spawnp(pid_t *restrict, const char *restrict, + const posix_spawn_file_actions_t *, + const posix_spawnattr_t *restrict, + char *const [restrict], char *const [restrict]); +\fP +.fi +.RE +.LP +Inclusion of the \fI\fP header may make visible symbols defined +in the \fI\fP, \fI\fP, and \fI\fP +headers. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , \fI\fP , \fI\fP +, the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, \fIposix_spawnattr_destroy\fP(), +\fIposix_spawnattr_getsigdefault\fP(), \fIposix_spawnattr_getflags\fP(), +\fIposix_spawnattr_getpgroup\fP(), \fIposix_spawnattr_getschedparam\fP(), +\fIposix_spawnattr_getschedpolicy\fP(), \fIposix_spawnattr_getsigmask\fP(), +\fIposix_spawnattr_init\fP(), \fIposix_spawnattr_setsigdefault\fP(), +\fIposix_spawnattr_setflags\fP(), \fIposix_spawnattr_setpgroup\fP(), +\fIposix_spawnattr_setschedparam\fP(), \fIposix_spawnattr_setschedpolicy\fP(), +\fIposix_spawnattr_setsigmask\fP(), \fIposix_spawn\fP(), \fIposix_spawn_file_actions_addclose\fP(), +\fIposix_spawn_file_actions_adddup2\fP(), \fIposix_spawn_file_actions_addopen\fP(), +\fIposix_spawn_file_actions_destroy\fP(), \fIposix_spawn_file_actions_init\fP(), +\fIposix_spawnp\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/stat.h.0p b/man0p/stat.h.0p new file mode 100644 index 000000000..1cec65df3 --- /dev/null +++ b/man0p/stat.h.0p @@ -0,0 +1 @@ +.so man0p/sys_stat.h.0p diff --git a/man0p/statvfs.h.0p b/man0p/statvfs.h.0p new file mode 100644 index 000000000..2150e284e --- /dev/null +++ b/man0p/statvfs.h.0p @@ -0,0 +1 @@ +.so man0p/sys_statvfs.h.0p diff --git a/man0p/stdarg.h.0p b/man0p/stdarg.h.0p new file mode 100644 index 000000000..dc74c418b --- /dev/null +++ b/man0p/stdarg.h.0p @@ -0,0 +1,161 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +stdarg.h \- handle variable argument list +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void va_start(va_list\fP \fIap\fP\fB,\fP \fIargN\fP\fB); +.br +void va_copy(va_list\fP \fIdest\fP\fB, va_list\fP \fIsrc\fP\fB); +.br +type va_arg(va_list\fP \fIap\fP\fB,\fP \fItype\fP\fB); +.br +void va_end(va_list\fP \fIap\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fI\fP header shall contain a set of macros which allows +portable functions that accept variable argument +lists to be written. Functions that have variable argument lists (such +as \fIprintf\fP()) +but do not use these macros are inherently non-portable, as different +systems use different argument-passing conventions. +.LP +The type \fBva_list\fP shall be defined for variables used to traverse +the list. +.LP +The \fIva_start\fP() macro is invoked to initialize \fIap\fP to the +beginning of the list before any calls to +\fIva_arg\fP(). +.LP +The \fIva_copy\fP() macro initializes \fIdest\fP as a copy of \fIsrc\fP, +as if the \fIva_start\fP() macro had been applied +to \fIdest\fP followed by the same sequence of uses of the \fIva_arg\fP() +macro as had previously been used to reach the present +state of \fIsrc\fP. Neither the \fIva_copy\fP() nor \fIva_start\fP() +macro shall be invoked to reinitialize \fIdest\fP without +an intervening invocation of the \fIva_end\fP() macro for the same +\fIdest\fP. +.LP +The object \fIap\fP may be passed as an argument to another function; +if that function invokes the \fIva_arg\fP() macro with +parameter \fIap\fP, the value of \fIap\fP in the calling function +is unspecified and shall be passed to the \fIva_end\fP() macro +prior to any further reference to \fIap\fP. The parameter \fIargN\fP +is the identifier of the rightmost parameter in the variable +parameter list in the function definition (the one just before the +\&...). If the parameter \fIargN\fP is declared with the +\fBregister\fP storage class, with a function type or array type, +or with a type that is not compatible with the type that results +after application of the default argument promotions, the behavior +is undefined. +.LP +The \fIva_arg\fP() macro shall return the next argument in the list +pointed to by \fIap\fP. Each invocation of \fIva_arg\fP() +modifies \fIap\fP so that the values of successive arguments are returned +in turn. The \fItype\fP parameter shall be a type name +specified such that the type of a pointer to an object that has the +specified type can be obtained simply by postfixing a +\fB'*'\fP to type. If there is no actual next argument, or if \fItype\fP +is not compatible with the type of the actual next +argument (as promoted according to the default argument promotions), +the behavior is undefined, except for the following cases: +.IP " *" 3 +One type is a signed integer type, the other type is the corresponding +unsigned integer type, and the value is representable in +both types. +.LP +.IP " *" 3 +One type is a pointer to \fBvoid\fP and the other is a pointer to +a character type. +.LP +.IP " *" 3 +Both types are pointers. +.LP +.LP +Different types can be mixed, but it is up to the routine to know +what type of argument is expected. +.LP +The \fIva_end\fP() macro is used to clean up; it invalidates \fIap\fP +for use (unless \fIva_start\fP() or \fIva_copy\fP() is +invoked again). +.LP +Each invocation of the \fIva_start\fP() and \fIva_copy\fP() macros +shall be matched by a corresponding invocation of the +\fIva_end\fP() macro in the same function. +.LP +Multiple traversals, each bracketed by \fIva_start\fP() ... \fIva_end\fP(), +are possible. +.SH EXAMPLES +.LP +This example is a possible implementation of \fIexecl\fP(): +.sp +.RS +.nf + +\fB#include +.sp + +#define MAXARGS 31 + +.sp + +/* + * execl is called by + * execl(file, arg1, arg2, ..., (char *)(0)); + */ +int execl(const char *file, const char *args, ...) +{ + va_list ap; + char *array[MAXARGS +1]; + int argno = 0; +.sp + + va_start(ap, args); + while (args != 0 && argno < MAXARGS) + { + array[argno++] = args; + args = va_arg(ap, const char *); + } + array[argno] = (char *) 0; + va_end(ap); + return execv(file, array); +} +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +It is up to the calling routine to communicate to the called routine +how many arguments there are, since it is not always +possible for the called routine to determine this in any other way. +For example, \fIexecl\fP() is passed a null pointer to signal the +end of the list. The \fIprintf\fP() function can tell how many arguments +are there by the \fIformat\fP argument. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIexec\fP, +\fIprintf\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/stdbool.h.0p b/man0p/stdbool.h.0p new file mode 100644 index 000000000..d5d063973 --- /dev/null +++ b/man0p/stdbool.h.0p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +stdbool.h \- boolean type and values +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following macros: +.TP 7 +bool +Expands to \fB_Bool\fP. +.TP 7 +true +Expands to the integer constant 1. +.TP 7 +false +Expands to the integer constant 0. +.TP 7 +__bool_true_false_are_defined +.sp +Expands to the integer constant 1. +.sp +.LP +An application may undefine and then possibly redefine the macros +bool, true, and false. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +The ability to undefine and redefine the macros bool, true, and false +is an obsolescent feature and may be withdrawn in a future +version. +.SH SEE ALSO +.LP +None. +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/stddef.h.0p b/man0p/stddef.h.0p new file mode 100644 index 000000000..caccb1585 --- /dev/null +++ b/man0p/stddef.h.0p @@ -0,0 +1,72 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +stddef.h \- standard type definitions +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following macros: +.TP 7 +NULL +Null pointer constant. +.TP 7 +offsetof(\fItype\fP, \fImember-designator\fP) +.sp +Integer constant expression of type \fBsize_t\fP, the value of which +is the offset in bytes to the structure member +(\fImember-designator\fP), from the beginning of its structure (\fItype\fP). +.sp +.LP +The \fI\fP header shall define the following types: +.TP 7 +\fBptrdiff_t\fP +Signed integer type of the result of subtracting two pointers. +.TP 7 +\fBwchar_t\fP +Integer type whose range of values can represent distinct wide-character +codes for all members of the largest character set +specified among the locales supported by the compilation environment: +the null character has the code value 0 and each member of +the portable character set has a code value equal to its value when +used as the lone character in an integer character +constant. +.TP 7 +\fBsize_t\fP +Unsigned integer type of the result of the \fIsizeof\fP operator. +.sp +.LP +The implementation shall support one or more programming environments +in which the widths of \fBptrdiff_t\fP, \fBsize_t\fP, +and \fBwchar_t\fP are no greater than the width of type \fBlong\fP. +The names of these programming environments can be obtained +using the \fIconfstr\fP() function or the \fIgetconf\fP utility. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIconfstr\fP(), the +Shell and +Utilities volume of IEEE\ Std\ 1003.1-2001, \fIgetconf\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/stdint.h.0p b/man0p/stdint.h.0p new file mode 100644 index 000000000..637b4009d --- /dev/null +++ b/man0p/stdint.h.0p @@ -0,0 +1,578 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +stdint.h \- integer types +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +Some of the functionality described on this reference page extends +the ISO\ C standard. Applications shall define +the appropriate feature test macro (see the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, Section 2.2, The Compilation Environment) +to enable the visibility of these symbols in this +header. +.LP +The \fI\fP header shall declare sets of integer types having +specified widths, and shall define corresponding +sets of macros. It shall also define macros that specify limits of +integer types corresponding to types defined in other standard +headers. +.TP 7 +\fBNote:\fP +The "width" of an integer type is the number of bits used to store +its value in a pure binary system; the actual type may use +more bits than that (for example, a 28-bit type could be stored in +32 bits of actual storage). An \fIN\fP-bit signed type has +values in the range -2**\fIN\fP-1 or 1-2**\fIN\fP-1 to +2**\fIN\fP-1-1, while an \fIN\fP-bit unsigned type has values in the +range 0 to +2**\fIN\fP-1. +.sp +.LP +Types are defined in the following categories: +.IP " *" 3 +Integer types having certain exact widths +.LP +.IP " *" 3 +Integer types having at least certain specified widths +.LP +.IP " *" 3 +Fastest integer types having at least certain specified widths +.LP +.IP " *" 3 +Integer types wide enough to hold pointers to objects +.LP +.IP " *" 3 +Integer types having greatest width +.LP +.LP +(Some of these types may denote the same type.) +.LP +Corresponding macros specify limits of the declared types and construct +suitable constants. +.LP +For each type described herein that the implementation provides, the +\fI\fP header shall declare that +\fBtypedef\fP name and define the associated macros. Conversely, for +each type described herein that the implementation does not +provide, the \fI\fP header shall not declare that \fBtypedef\fP +name, nor shall it define the associated macros. +An implementation shall provide those types described as required, +but need not provide any of the others (described as +optional). +.SS Integer Types +.LP +When \fBtypedef\fP names differing only in the absence or presence +of the initial \fIu\fP are defined, they shall denote +corresponding signed and unsigned types as described in the ISO/IEC\ 9899:1999 +standard, Section 6.2.5; an implementation +providing one of these corresponding types shall also provide the +other. +.LP +In the following descriptions, the symbol \fIN\fP represents an unsigned +decimal integer with no leading zeros (for example, 8 +or 24, but not 04 or 048). +.IP " *" 3 +Exact-width integer types +.LP +The \fBtypedef\fP name \fBint\fP \fIN\fP \fB_t\fP designates a signed +integer type with width \fIN\fP, no padding bits, and +a two's-complement representation. Thus, \fBint8_t\fP denotes a signed +integer type with a width of exactly 8 bits. +.LP +The \fBtypedef\fP name \fBuint\fP \fIN\fP \fB_t\fP designates an unsigned +integer type with width \fIN\fP. Thus, +\fBuint24_t\fP denotes an unsigned integer type with a width of exactly +24 bits. +.LP +The +following types are required: +.LP +.sp +\fBint8_t\fP +.br +\fBint16_t\fP +.br +\fBint32_t\fP +.br +\fBuint8_t\fP +.br +\fBuint16_t\fP +.br +\fBuint32_t\fP +.br +.LP +If an implementation provides integer types with width 64 that meet +these requirements, then the following types are required: +\fBint64_t\fP \fBuint64_t\fP +.LP +In +particular, this will be the case if any of the following are true: +.RS +.IP " *" 3 +The implementation supports the _POSIX_V6_ILP32_OFFBIG programming +environment and the application is being built in the +_POSIX_V6_ILP32_OFFBIG programming environment (see the Shell and +Utilities volume of IEEE\ Std\ 1003.1-2001, \fIc99\fP, Programming +Environments). +.LP +.IP " *" 3 +The implementation supports the _POSIX_V6_LP64_OFF64 programming environment +and the application is being built in the +_POSIX_V6_LP64_OFF64 programming environment. +.LP +.IP " *" 3 +The implementation supports the _POSIX_V6_LPBIG_OFFBIG programming +environment and the application is being built in the +_POSIX_V6_LPBIG_OFFBIG programming environment. +.LP +.RE +.LP +All other types of this form are optional. +.LP +.IP " *" 3 +Minimum-width integer types +.LP +The \fBtypedef\fP name \fBint_least\fP \fIN\fP \fB_t\fP designates +a signed integer type with a width of at least \fIN\fP, +such that no signed integer type with lesser size has at least the +specified width. Thus, \fBint_least32_t\fP denotes a signed +integer type with a width of at least 32 bits. +.LP +The \fBtypedef\fP name \fBuint_least\fP \fIN\fP \fB_t\fP designates +an unsigned integer type with a width of at least +\fIN\fP, such that no unsigned integer type with lesser size has at +least the specified width. Thus, \fBuint_least16_t\fP denotes +an unsigned integer type with a width of at least 16 bits. +.LP +The following types are required: \fBint_least8_t\fP \fBint_least16_t\fP +\fBint_least32_t\fP \fBint_least64_t\fP +\fBuint_least8_t\fP \fBuint_least16_t\fP \fBuint_least32_t\fP \fBuint_least64_t\fP +.LP +All other types of this form are optional. +.LP +.IP " *" 3 +Fastest minimum-width integer types +.LP +Each of the following types designates an integer type that is usually +fastest to operate with among all integer types that have +at least the specified width. +.LP +The designated type is not guaranteed to be fastest for all purposes; +if the implementation has no clear grounds for choosing +one type over another, it will simply pick some integer type satisfying +the signedness and width requirements. +.LP +The \fBtypedef\fP name \fBint_fast\fP \fIN\fP \fB_t\fP designates +the fastest signed integer type with a width of at least +\fIN\fP. The \fBtypedef\fP name \fBuint_fast\fP \fIN\fP \fB_t\fP designates +the fastest unsigned integer type with a width of +at least \fIN\fP. +.LP +The following types are required: \fBint_fast8_t\fP \fBint_fast16_t\fP +\fBint_fast32_t\fP \fBint_fast64_t\fP +\fBuint_fast8_t\fP \fBuint_fast16_t\fP \fBuint_fast32_t\fP \fBuint_fast64_t\fP +.LP +All other types of this form are optional. +.LP +.IP " *" 3 +Integer types capable of holding object pointers +.LP +The following type designates a signed integer type with the property +that any valid pointer to \fBvoid\fP can be converted to +this type, then converted back to a pointer to \fBvoid\fP, and the +result will compare equal to the original pointer: +\fBintptr_t\fP +.LP +The following type designates an unsigned integer type with the property +that any valid pointer to \fBvoid\fP can be converted +to this type, then converted back to a pointer to \fBvoid\fP, and +the result will compare equal to the original pointer: +\fBuintptr_t\fP +.LP +On XSI-conformant systems, the \fBintptr_t\fP and \fBuintptr_t\fP +types are required; \ otherwise, they are optional. +.LP +.IP " *" 3 +Greatest-width integer types +.LP +The following type designates a signed integer type capable of representing +any value of any signed integer type: +\fBintmax_t\fP +.LP +The following type designates an unsigned integer type capable of +representing any value of any unsigned integer type: +\fBuintmax_t\fP +.LP +These types are required. +.LP +.TP 7 +\fBNote:\fP +Applications can test for optional types by using the corresponding +limit macro from Limits of +Specified-Width Integer Types . +.sp +.SS Limits of Specified-Width Integer Types +.LP +The following macros specify the minimum and maximum limits of the +types declared in the \fI\fP header. Each +macro name corresponds to a similar type name in Integer Types . +.LP +Each instance of any defined macro shall be replaced by a constant +expression suitable for use in \fB#if\fP preprocessing +directives, and this expression shall have the same type as would +an expression that is an object of the corresponding type +converted according to the integer promotions. Its implementation-defined +value shall be equal to or greater in magnitude (absolute +value) than the corresponding value given below, with the same sign, +except where stated to be exactly the given value. +.IP " *" 3 +Limits of exact-width integer types +.RS +.IP " *" 3 +Minimum values of exact-width signed integer types: +.TP 7 +{INT\fIN\fP_MIN} +.RS +Exactly -(2 **N-1) +.RE +.sp +.LP +.IP " *" 3 +Maximum values of exact-width signed integer types: +.TP 7 +{INT\fIN\fP_MAX} +.RS +Exactly 2**N-1 -1 +.RE +.sp +.LP +.IP " *" 3 +Maximum values of exact-width unsigned integer types: +.TP 7 +{UINT\fIN\fP_MAX} +.RS +Exactly 2 **N -1 +.RE +.sp +.LP +.RE +.LP +.IP " *" 3 +Limits of minimum-width integer types +.RS +.IP " *" 3 +Minimum values of minimum-width signed integer types: +.TP 7 +{INT_LEAST\fIN\fP_MIN} +.RS +-(2 ** N-1 -1) +.RE +.sp +.LP +.IP " *" 3 +Maximum values of minimum-width signed integer types: +.TP 7 +{INT_LEAST\fIN\fP_MAX} +.RS +2 ** N-1 -1 +.RE +.sp +.LP +.IP " *" 3 +Maximum values of minimum-width unsigned integer types: +.TP 7 +{UINT_LEAST\fIN\fP_MAX} +.RS +2 ** N -1 +.RE +.sp +.LP +.RE +.LP +.IP " *" 3 +Limits of fastest minimum-width integer types +.RS +.IP " *" 3 +Minimum values of fastest minimum-width signed integer types: +.TP 7 +{INT_FAST\fIN\fP_MIN} +.RS +-(2 ** N-1 -1) +.RE +.sp +.LP +.IP " *" 3 +Maximum values of fastest minimum-width signed integer types: +.TP 7 +{INT_FAST\fIN\fP_MAX} +.RS +2 ** N-1 -1 +.RE +.sp +.LP +.IP " *" 3 +Maximum values of fastest minimum-width unsigned integer types: +.TP 7 +{UINT_FAST\fIN\fP_MAX} +.RS +2 ** N -1 +.RE +.sp +.LP +.RE +.LP +.IP " *" 3 +Limits of integer types capable of holding object pointers +.RS +.IP " *" 3 +Minimum value of pointer-holding signed integer type: +.TP 7 +{INTPTR_MIN} +.RS +-(2 ** 15 -1) +.RE +.sp +.LP +.IP " *" 3 +Maximum value of pointer-holding signed integer type: +.TP 7 +{INTPTR_MAX} +.RS +2 ** 15 -1 +.RE +.sp +.LP +.IP " *" 3 +Maximum value of pointer-holding unsigned integer type: +.TP 7 +{UINTPTR_MAX} +.RS +2 ** 16 -1 +.RE +.sp +.LP +.RE +.LP +.IP " *" 3 +Limits of greatest-width integer types +.RS +.IP " *" 3 +Minimum value of greatest-width signed integer type: +.TP 7 +{INTMAX_MIN} +.RS +-(2 ** 63 -1) +.RE +.sp +.LP +.IP " *" 3 +Maximum value of greatest-width signed integer type: +.TP 7 +{INTMAX_MAX} +.RS +2 ** 63 -1 +.RE +.sp +.LP +.IP " *" 3 +Maximum value of greatest-width unsigned integer type: +.TP 7 +{UINTMAX_MAX} +.RS +2 ** 64 -1 +.RE +.sp +.LP +.RE +.LP +.SS Limits of Other Integer Types +.LP +The following macros specify the minimum and maximum limits of integer +types corresponding to types defined in other standard +headers. +.LP +Each instance of these macros shall be replaced by a constant expression +suitable for use in \fB#if\fP preprocessing +directives, and this expression shall have the same type as would +an expression that is an object of the corresponding type +converted according to the integer promotions. Its implementation-defined +value shall be equal to or greater in magnitude (absolute +value) than the corresponding value given below, with the same sign. +.IP " *" 3 +Limits of \fBptrdiff_t\fP: +.TP 7 +{PTRDIFF_MIN} +.RS +-65535 +.RE +.TP 7 +{PTRDIFF_MAX} +.RS ++65535 +.RE +.sp +.LP +.IP " *" 3 +Limits of \fBsig_atomic_t\fP: +.TP 7 +{SIG_ATOMIC_MIN} +.RS +See below. +.RE +.TP 7 +{SIG_ATOMIC_MAX} +.RS +See below. +.RE +.sp +.LP +.IP " *" 3 +Limit of \fBsize_t\fP: +.TP 7 +{SIZE_MAX} +.RS +65535 +.RE +.sp +.LP +.IP " *" 3 +Limits of \fBwchar_t\fP: +.TP 7 +{WCHAR_MIN} +.RS +See below. +.RE +.TP 7 +{WCHAR_MAX} +.RS +See below. +.RE +.sp +.LP +.IP " *" 3 +Limits of \fBwint_t\fP: +.TP 7 +{WINT_MIN} +.RS +See below. +.RE +.TP 7 +{WINT_MAX} +.RS +See below. +.RE +.sp +.LP +.LP +If \fBsig_atomic_t\fP (see the \fI\fP header) is defined +as a signed +integer type, the value of {SIG_ATOMIC_MIN} shall be no greater than +-127 and the value of {SIG_ATOMIC_MAX} shall be no less than +127; otherwise, \fBsig_atomic_t\fP shall be defined as an unsigned +integer type, and the value of {SIG_ATOMIC_MIN} shall be 0 and +the value of {SIG_ATOMIC_MAX} shall be no less than 255. +.LP +If \fBwchar_t\fP (see the \fI\fP header) is defined as a +signed +integer type, the value of {WCHAR_MIN} shall be no greater than -127 +and the value of {WCHAR_MAX} shall be no less than 127; +otherwise, \fBwchar_t\fP shall be defined as an unsigned integer type, +and the value of {WCHAR_MIN} shall be 0 and the value of +{WCHAR_MAX} shall be no less than 255. +.LP +If \fBwint_t\fP (see the \fI\fP header) is defined as a signed +integer +type, the value of {WINT_MIN} shall be no greater than -32767 and +the value of {WINT_MAX} shall be no less than 32767; otherwise, +\fBwint_t\fP shall be defined as an unsigned integer type, and the +value of {WINT_MIN} shall be 0 and the value of {WINT_MAX} +shall be no less than 65535. +.SS Macros for Integer Constant Expressions +.LP +The following macros expand to integer constant expressions suitable +for initializing objects that have integer types +corresponding to types defined in the \fI\fP header. Each +macro name corresponds to a similar type name listed +under \fIMinimum-width integer types\fP and \fIGreatest-width integer +types\fP. +.LP +Each invocation of one of these macros shall expand to an integer +constant expression suitable for use in \fB#if\fP +preprocessing directives. The type of the expression shall have the +same type as would an expression that is an object of the +corresponding type converted according to the integer promotions. +The value of the expression shall be that of the argument. +.LP +The argument in any instance of these macros shall be a decimal, octal, +or hexadecimal constant with a value that does not +exceed the limits for the corresponding type. +.IP " *" 3 +Macros for minimum-width integer constant expressions +.LP +The macro \fIINTN_C\fP( \fIvalue\fP) shall expand to an integer constant +expression corresponding to the type \fBint_least\fP +\fIN\fP \fB_t\fP. The macro \fIUINTN_C\fP( \fIvalue\fP) shall expand +to an integer constant expression corresponding to the +type \fBuint_least\fP \fIN\fP \fB_t\fP. For example, if \fBuint_least64_t\fP +is a name for the type \fBunsigned long long\fP, +then \fIUINT64_C\fP(0x123) might expand to the integer constant 0x123ULL. +.LP +.IP " *" 3 +Macros for greatest-width integer constant expressions +.LP +The following macro expands to an integer constant expression having +the value specified by its argument and the type +\fBintmax_t\fP: INTMAX_C(\fIvalue\fP) +.LP +The following macro expands to an integer constant expression having +the value specified by its argument and the type +\fBuintmax_t\fP: UINTMAX_C(\fIvalue\fP) +.LP +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fI\fP header is a subset of the \fI\fP +header +more suitable for use in freestanding environments, which might not +support the formatted I/O functions. In some environments, if +the formatted conversion support is not wanted, using this header +instead of the \fI\fP header avoids defining such a large +number of macros. +.LP +As a consequence of adding \fBint8_t\fP, the following are true: +.IP " *" 3 +A byte is exactly 8 bits. +.LP +.IP " *" 3 +{CHAR_BIT} has the value 8, {SCHAR_MAX} has the value 127, {SCHAR_MIN} +has the value -127 or -128, and {UCHAR_MAX} has the value +255. +.LP +.SH FUTURE DIRECTIONS +.LP +\fBtypedef\fP names beginning with \fBint\fP or \fBuint\fP and ending +with _t may be added to the types defined in the +\fI\fP header. Macro names beginning with INT or UINT and +ending with _MAX, _MIN, or _C may be added to the macros +defined in the \fI\fP header. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , \fI\fP , \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/stdio.h.0p b/man0p/stdio.h.0p new file mode 100644 index 000000000..33b11e026 --- /dev/null +++ b/man0p/stdio.h.0p @@ -0,0 +1,251 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +stdio.h \- standard buffered input/output +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +Some of the functionality described on this reference page extends +the ISO\ C standard. Applications shall define +the appropriate feature test macro (see the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, Section 2.2, The Compilation Environment) +to enable the visibility of these symbols in this +header. +.LP +The \fI\fP header shall define the following macros as positive +integer constant expressions: +.TP 7 +BUFSIZ +Size of \fI\fP buffers. +.TP 7 +_IOFBF +Input/output fully buffered. +.TP 7 +_IOLBF +Input/output line buffered. +.TP 7 +_IONBF +Input/output unbuffered. +.TP 7 +L_ctermid +Maximum size of character array to hold \fIctermid\fP() output. +.TP 7 +L_tmpnam +Maximum size of character array to hold \fItmpnam\fP() output. +.TP 7 +SEEK_CUR +Seek relative to current position. +.TP 7 +SEEK_END +Seek relative to end-of-file. +.TP 7 +SEEK_SET +Seek relative to start-of-file. +.sp +.LP +The following macros shall be defined as positive integer constant +expressions which denote implementation limits: +.TP 7 +{FILENAME_MAX} +Maximum size in bytes of the longest filename string that the implementation +guarantees can be opened. +.TP 7 +{FOPEN_MAX} +Number of streams which the implementation guarantees can be open +simultaneously. The value is at least eight. +.TP 7 +{TMP_MAX} +Minimum number of unique filenames generated by \fItmpnam\fP(). Maximum +number of times +an application can call \fItmpnam\fP() reliably. The value of {TMP_MAX} +is at least 25. +\ On XSI-conformant systems, the value of {TMP_MAX} is at least 10000. +.sp +.LP +The following macro name shall be defined as a negative integer constant +expression: +.TP 7 +EOF +End-of-file return value. +.sp +.LP +The following macro name shall be defined as a null pointer constant: +.TP 7 +NULL +Null pointer. +.sp +.LP +The following macro name shall be defined as a string constant: +.TP 7 +P_tmpdir +Default directory prefix for \fItempnam\fP(). +.sp +.LP +The following shall be defined as expressions of type "pointer to +\fBFILE\fP" that point to the \fBFILE\fP objects +associated, respectively, with the standard error, input, and output +streams: +.TP 7 +\fIstderr\fP +Standard error output stream. +.TP 7 +\fIstdin\fP +Standard input stream. +.TP 7 +\fIstdout\fP +Standard output stream. +.sp +.LP +The following data types shall be defined through \fBtypedef\fP: +.TP 7 +\fBFILE\fP +A structure containing information about a file. +.TP 7 +\fBfpos_t\fP +A non-array type containing all information needed to specify uniquely +every position within a file. +.TP 7 +\fBva_list\fP +As described in \fI\fP . +.TP 7 +\fBsize_t\fP +As described in \fI\fP . +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBvoid clearerr(FILE *); + +char *ctermid(char *); + +int fclose(FILE *); + +FILE *fdopen(int, const char *); + +int feof(FILE *); +int ferror(FILE *); +int fflush(FILE *); +int fgetc(FILE *); +int fgetpos(FILE *restrict, fpos_t *restrict); +char *fgets(char *restrict, int, FILE *restrict); + +int fileno(FILE *); + + +void flockfile(FILE *); + +FILE *fopen(const char *restrict, const char *restrict); +int fprintf(FILE *restrict, const char *restrict, ...); +int fputc(int, FILE *); +int fputs(const char *restrict, FILE *restrict); +size_t fread(void *restrict, size_t, size_t, FILE *restrict); +FILE *freopen(const char *restrict, const char *restrict, + FILE *restrict); +int fscanf(FILE *restrict, const char *restrict, ...); +int fseek(FILE *, long, int); + +int fseeko(FILE *, off_t, int); + +int fsetpos(FILE *, const fpos_t *); +long ftell(FILE *); + +off_t ftello(FILE *); + + +int ftrylockfile(FILE *); +void funlockfile(FILE *); + +size_t fwrite(const void *restrict, size_t, size_t, FILE *restrict); +int getc(FILE *); +int getchar(void); + +int getc_unlocked(FILE *); +int getchar_unlocked(void); + +char *gets(char *); + +int pclose(FILE *); + +void perror(const char *); + +FILE *popen(const char *, const char *); + +int printf(const char *restrict, ...); +int putc(int, FILE *); +int putchar(int); + +int putc_unlocked(int, FILE *); +int putchar_unlocked(int); + +int puts(const char *); +int remove(const char *); +int rename(const char *, const char *); +void rewind(FILE *); +int scanf(const char *restrict, ...); +void setbuf(FILE *restrict, char *restrict); +int setvbuf(FILE *restrict, char *restrict, int, size_t); +int snprintf(char *restrict, size_t, const char *restrict, ...); +int sprintf(char *restrict, const char *restrict, ...); +int sscanf(const char *restrict, const char *restrict, int ...); + +char *tempnam(const char *, const char *); + +FILE *tmpfile(void); +char *tmpnam(char *); +int ungetc(int, FILE *); +int vfprintf(FILE *restrict, const char *restrict, va_list); +int vfscanf(FILE *restrict, const char *restrict, va_list); +int vprintf(const char *restrict, va_list); +int vscanf(const char *restrict, va_list); +int vsnprintf(char *restrict, size_t, const char *restrict, va_list; +int vsprintf(char *restrict, const char *restrict, va_list); +int vsscanf(const char *restrict, const char *restrict, va_list arg); +\fP +.fi +.RE +.LP +Inclusion of the \fI\fP header may also make visible all +symbols from \fI\fP. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , \fI\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIclearerr\fP(), \fIctermid\fP(), +\fIfclose\fP(), \fIfdopen\fP(), \fIfgetc\fP(), \fIfgetpos\fP(), \fIferror\fP(), +\fIfeof\fP(), \fIfflush\fP(), \fIfgets\fP(), \fIfileno\fP(), \fIflockfile\fP(), +\fIfopen\fP(), \fIfputc\fP(), \fIfputs\fP(), \fIfread\fP(), \fIfreopen\fP(), +\fIfseek\fP(), \fIfsetpos\fP(), \fIftell\fP(), \fIfwrite\fP(), \fIgetc\fP(), +\fIgetc_unlocked\fP(), \fIgetwchar\fP(), \fIgetchar\fP(), \fIgetopt\fP(), +\fIgets\fP(), \fIpclose\fP(), \fIperror\fP(), \fIpopen\fP(), \fIprintf\fP(), +\fIputc\fP(), \fIputchar\fP(), \fIputs\fP(), \fIputwchar\fP(), \fIremove\fP(), +\fIrename\fP(), \fIrewind\fP(), \fIscanf\fP(), \fIsetbuf\fP(), \fIsetvbuf\fP(), +\fIsscanf\fP(), \fIstdin\fP, \fIsystem\fP(), \fItempnam\fP(), \fItmpfile\fP(), +\fItmpnam\fP(), \fIungetc\fP(), \fIvfscanf\fP(), \fIvscanf\fP(), \fIvprintf\fP(), +\fIvsscanf\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/stdlib.h.0p b/man0p/stdlib.h.0p new file mode 100644 index 000000000..59d1c8959 --- /dev/null +++ b/man0p/stdlib.h.0p @@ -0,0 +1,237 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +stdlib.h \- standard library definitions +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +Some of the functionality described on this reference page extends +the ISO\ C standard. Applications shall define +the appropriate feature test macro (see the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, Section 2.2, The Compilation Environment) +to enable the visibility of these symbols in this +header. +.LP +The \fI\fP header shall define the following macros: +.TP 7 +EXIT_FAILURE +Unsuccessful termination for \fIexit\fP(); evaluates to a non-zero +value. +.TP 7 +EXIT_SUCCESS +Successful termination for \fIexit\fP(); evaluates to 0. +.TP 7 +NULL +Null pointer. +.TP 7 +{RAND_MAX} +Maximum value returned by \fIrand\fP(); at least 32767. +.TP 7 +{MB_CUR_MAX} +Integer expression whose value is the maximum number of bytes in a +character specified by the current locale. +.sp +.LP +The following data types shall be defined through \fBtypedef\fP: +.TP 7 +\fBdiv_t\fP +Structure type returned by the \fIdiv\fP() function. +.TP 7 +\fBldiv_t\fP +Structure type returned by the \fIldiv\fP() function. +.TP 7 +\fBlldiv_t\fP +Structure type returned by the \fIlldiv\fP() function. +.TP 7 +\fBsize_t\fP +As described in \fI\fP . +.TP 7 +\fBwchar_t\fP +As described in \fI\fP . +.sp +.LP +In addition, the following symbolic names and macros shall be defined +as in \fI\fP , for use in decoding the return value from +\fIsystem\fP(): +.LP +.sp +.sp +WNOHANG +.br +WUNTRACED +.br +WEXITSTATUS +.br +WIFEXITED +.br +WIFSIGNALED +.br +WIFSTOPPED +.br +WSTOPSIG +.br +WTERMSIG +.br +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBvoid _Exit(int); + +long a64l(const char *); + +void abort(void); +int abs(int); +int atexit(void (*)(void)); +double atof(const char *); +int atoi(const char *); +long atol(const char *); +long long atoll(const char *); +void *bsearch(const void *, const void *, size_t, size_t, + int (*)(const void *, const void *)); +void *calloc(size_t, size_t); +div_t div(int, int); + +double drand48(void); +char *ecvt(double, int, int *restrict, int *restrict); (\fP\fBLEGACY\fP \fB) +double erand48(unsigned short[3]); + +void exit(int); + +char *fcvt(double, int, int *restrict, int *restrict); (\fP\fBLEGACY\fP \fB) + +void free(void *); + +char *gcvt(double, int, char *); (\fP\fBLEGACY\fP \fB) + +char *getenv(const char *); + +int getsubopt(char **, char *const *, char **); +int grantpt(int); +char *initstate(unsigned, char *, size_t); +long jrand48(unsigned short[3]); +char *l64a(long); + +long labs(long); + +void lcong48(unsigned short[7]); + +ldiv_t ldiv(long, long); +long long llabs(long long); +lldiv_t lldiv(long long, long long); + +long lrand48(void); + +void *malloc(size_t); +int mblen(const char *, size_t); +size_t mbstowcs(wchar_t *restrict, const char *restrict, size_t); +int mbtowc(wchar_t *restrict, const char *restrict, size_t); + +char *mktemp(char *); (\fP\fBLEGACY\fP \fB) +int mkstemp(char *); +long mrand48(void); +long nrand48(unsigned short[3]); + + +int posix_memalign(void **, size_t, size_t); + + +int posix_openpt(int); +char *ptsname(int); +int putenv(char *); + +void qsort(void *, size_t, size_t, int (*)(const void *, + const void *)); +int rand(void); + +int rand_r(unsigned *); + + +long random(void); + +void *realloc(void *, size_t); + +char *realpath(const char *restrict, char *restrict); +unsigned short seed48(unsigned short[3]); + + +int setenv(const char *, const char *, int); + + +void setkey(const char *); +char *setstate(const char *); + +void srand(unsigned); + +void srand48(long); +void srandom(unsigned); + +double strtod(const char *restrict, char **restrict); +float strtof(const char *restrict, char **restrict); +long strtol(const char *restrict, char **restrict, int); +long double strtold(const char *restrict, char **restrict); +long long strtoll(const char *restrict, char **restrict, int); +unsigned long strtoul(const char *restrict, char **restrict, int); +unsigned long long + strtoull(const char *restrict, char **restrict, int); +int system(const char *); + +int unlockpt(int); + + +int unsetenv(const char *); + +size_t wcstombs(char *restrict, const wchar_t *restrict, size_t); +int wctomb(char *, wchar_t); +\fP +.fi +.RE +.LP +Inclusion of the \fI\fP header may also make visible all +symbols from \fI\fP, \fI\fP, \fI\fP, and +\fI\fP. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , \fI\fP , \fI\fP +, \fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fI_Exit\fP(), \fIa64l\fP(), \fIabort\fP(), \fIabs\fP(), \fIatexit\fP(), +\fIatof\fP(), \fIatoi\fP(), \fIatol\fP(), \fIatoll\fP(), \fIbsearch\fP(), +\fIcalloc\fP(), \fIdiv\fP(), \fIdrand48\fP(), \fIerand48\fP(), \fIexit\fP(), +\fIfree\fP(), \fIgetenv\fP(), \fIgetsubopt\fP(), \fIgrantpt\fP(), +\fIinitstate\fP(), \fIjrand48\fP(), \fIl64a\fP(), \fIlabs\fP(), \fIlcong48\fP(), +\fIldiv\fP(), \fIllabs\fP(), \fIlldiv\fP(), \fIlrand48\fP(), \fImalloc\fP(), +\fImblen\fP(), \fImbstowcs\fP(), \fImbtowc\fP(), \fImkstemp\fP(), +\fImrand48\fP(), \fInrand48\fP(), \fIposix_memalign\fP(), \fIptsname\fP(), +\fIputenv\fP(), \fIqsort\fP(), \fIrand\fP(), \fIrealloc\fP(), \fIrealpath\fP(), +\fIsetstate\fP(), \fIsrand\fP(), \fIsrand48\fP(), \fIsrandom\fP(), +\fIstrtod\fP(), \fIstrtof\fP(), \fIstrtol\fP(), \fIstrtold\fP(), \fIstrtoll\fP(), +\fIstrtoul\fP(), \fIstrtoull\fP(), \fIunlockpt\fP(), \fIwcstombs\fP(), +\fIwctomb\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/string.h.0p b/man0p/string.h.0p new file mode 100644 index 000000000..59ec62889 --- /dev/null +++ b/man0p/string.h.0p @@ -0,0 +1,102 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +string.h \- string operations +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +Some of the functionality described on this reference page extends +the ISO\ C standard. Applications shall define +the appropriate feature test macro (see the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, Section 2.2, The Compilation Environment) +to enable the visibility of these symbols in this +header. +.LP +The \fI\fP header shall define the following: +.TP 7 +NULL +Null pointer constant. +.TP 7 +\fBsize_t\fP +As described in \fI\fP . +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fB +void *memccpy(void *restrict, const void *restrict, int, size_t); + +void *memchr(const void *, int, size_t); +int memcmp(const void *, const void *, size_t); +void *memcpy(void *restrict, const void *restrict, size_t); +void *memmove(void *, const void *, size_t); +void *memset(void *, int, size_t); +char *strcat(char *restrict, const char *restrict); +char *strchr(const char *, int); +int strcmp(const char *, const char *); +int strcoll(const char *, const char *); +char *strcpy(char *restrict, const char *restrict); +size_t strcspn(const char *, const char *); + +char *strdup(const char *); + +char *strerror(int); + +int *strerror_r(int, char *, size_t); + +size_t strlen(const char *); +char *strncat(char *restrict, const char *restrict, size_t); +int strncmp(const char *, const char *, size_t); +char *strncpy(char *restrict, const char *restrict, size_t); +char *strpbrk(const char *, const char *); +char *strrchr(const char *, int); +size_t strspn(const char *, const char *); +char *strstr(const char *, const char *); +char *strtok(char *restrict, const char *restrict); + +char *strtok_r(char *, const char *, char **); + +size_t strxfrm(char *restrict, const char *restrict, size_t); +\fP +.fi +.RE +.LP +Inclusion of the \fI\fP header may also make visible all +symbols from \fI\fP. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fImemccpy\fP(), \fImemchr\fP(), +\fImemcmp\fP(), \fImemcpy\fP(), \fImemmove\fP(), \fImemset\fP(), \fIstrcat\fP(), +\fIstrchr\fP(), \fIstrcmp\fP(), \fIstrcoll\fP(), \fIstrcpy\fP(), \fIstrcspn\fP(), +\fIstrdup\fP(), \fIstrerror\fP(), \fIstrlen\fP(), \fIstrncat\fP(), +\fIstrncmp\fP(), \fIstrncpy\fP(), \fIstrpbrk\fP(), \fIstrrchr\fP(), +\fIstrspn\fP(), \fIstrstr\fP(), \fIstrtok\fP(), \fIstrxfrm\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/strings.h.0p b/man0p/strings.h.0p new file mode 100644 index 000000000..8df15690b --- /dev/null +++ b/man0p/strings.h.0p @@ -0,0 +1,55 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +strings.h \- string operations +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint bcmp(const void *, const void *, size_t); (\fP\fBLEGACY\fP \fB) +void bcopy(const void *, void *, size_t); (\fP\fBLEGACY\fP \fB) +void bzero(void *, size_t); (\fP\fBLEGACY\fP \fB) +int ffs(int); +char *index(const char *, int); (\fP\fBLEGACY\fP \fB) +char *rindex(const char *, int); (\fP\fBLEGACY\fP \fB) +int strcasecmp(const char *, const char *); +int strncasecmp(const char *, const char *, size_t); +\fP +.fi +.RE +.LP +The \fBsize_t\fP type shall be defined through \fBtypedef\fP as described +in \fI\fP . +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIffs\fP(), \fIstrcasecmp\fP(), \fIstrncasecmp\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/stropts.h.0p b/man0p/stropts.h.0p new file mode 100644 index 000000000..3dbc8feab --- /dev/null +++ b/man0p/stropts.h.0p @@ -0,0 +1,399 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +stropts.h \- STREAMS interface (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBbandinfo\fP structure +that includes at least the following members: +.sp +.RS +.nf + +\fBunsigned char bi_pri \fP Priority band. \fB +int bi_flag \fP Flushing type. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the \fBstrpeek\fP structure +that includes at least the following members: +.sp +.RS +.nf + +\fBstruct strbuf ctlbuf \fP The control portion of the message. \fB +struct strbuf databuf \fP The data portion of the message. \fB +t_uscalar_t flags \fP RS_HIPRI or 0. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the \fBstrbuf\fP structure +that includes at least the following members: +.sp +.RS +.nf + +\fBint maxlen \fP Maximum buffer length. \fB +int len \fP Length of data. \fB +char *buf \fP Pointer to buffer. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the \fBstrfdinsert\fP structure +that includes at least the following +members: +.sp +.RS +.nf + +\fBstruct strbuf ctlbuf \fP The control portion of the message. \fB +struct strbuf databuf \fP The data portion of the message. \fB +t_uscalar_t flags \fP RS_HIPRI or 0. \fB +int fildes \fP File descriptor of the other STREAM. \fB +int offset \fP Relative location of the stored value. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the \fBstrioctl\fP structure +that includes at least the following members: +.sp +.RS +.nf + +\fBint ic_cmd \fP \fIioctl\fP() command. \fB +int ic_timout \fP Timeout for response. \fB +int ic_len \fP Length of data. \fB +char *ic_dp \fP Pointer to buffer. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the \fBstrrecvfd\fP structure +that includes at least the following +members: +.sp +.RS +.nf + +\fBint fda \fP Received file descriptor. \fB +uid_t uid \fP UID of sender. \fB +gid_t gid \fP GID of sender. \fB +\fP +.fi +.RE +.LP +The \fBuid_t\fP and \fBgid_t\fP types shall be defined through \fBtypedef\fP +as described in \fI\fP . +.LP +The \fI\fP header shall define the \fBt_scalar_t\fP and +\fBt_uscalar_t\fP types, respectively, as signed and +unsigned opaque types of equal length of at least 32 bits. +.LP +The \fI\fP header shall define the \fBstr_list\fP structure +that includes at least the following members: +.sp +.RS +.nf + +\fBint sl_nmods \fP Number of STREAMS module names. \fB +struct str_mlist *sl_modlist \fP STREAMS module names. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the \fBstr_mlist\fP structure +that includes at least the following member: +.sp +.RS +.nf + +\fBchar l_name[FMNAMESZ+1] \fP A STREAMS module name. \fB +\fP +.fi +.RE +.LP +At least the following macros shall be defined for use as the \fIrequest\fP +argument to \fIioctl\fP(): +.TP 7 +I_PUSH +Push a STREAMS module. +.TP 7 +I_POP +Pop a STREAMS module. +.TP 7 +I_LOOK +Get the top module name. +.TP 7 +I_FLUSH +Flush a STREAM. +.TP 7 +I_FLUSHBAND +Flush one band of a STREAM. +.TP 7 +I_SETSIG +Ask for notification signals. +.TP 7 +I_GETSIG +Retrieve current notification signals. +.TP 7 +I_FIND +Look for a STREAMS module. +.TP 7 +I_PEEK +Peek at the top message on a STREAM. +.TP 7 +I_SRDOPT +Set the read mode. +.TP 7 +I_GRDOPT +Get the read mode. +.TP 7 +I_NREAD +Size the top message. +.TP 7 +I_FDINSERT +Send implementation-defined information about another STREAM. +.TP 7 +I_STR +Send a STREAMS \fIioctl\fP(). +.TP 7 +I_SWROPT +Set the write mode. +.TP 7 +I_GWROPT +Get the write mode. +.TP 7 +I_SENDFD +Pass a file descriptor through a STREAMS pipe. +.TP 7 +I_RECVFD +Get a file descriptor sent via I_SENDFD. +.TP 7 +I_LIST +Get all the module names on a STREAM. +.TP 7 +I_ATMARK +Is the top message "marked''? +.TP 7 +I_CKBAND +See if any messages exist in a band. +.TP 7 +I_GETBAND +Get the band of the top message on a STREAM. +.TP 7 +I_CANPUT +Is a band writable? +.TP 7 +I_SETCLTIME +Set close time delay. +.TP 7 +I_GETCLTIME +Get close time delay. +.TP 7 +I_LINK +Connect two STREAMs. +.TP 7 +I_UNLINK +Disconnect two STREAMs. +.TP 7 +I_PLINK +Persistently connect two STREAMs. +.TP 7 +I_PUNLINK +Dismantle a persistent STREAMS link. +.sp +.LP +At least the following macros shall be defined for use with I_LOOK: +.TP 7 +FMNAMESZ +The minimum size in bytes of the buffer referred to by the \fIarg\fP +argument. +.sp +.LP +At least the following macros shall be defined for use with I_FLUSH: +.TP 7 +FLUSHR +Flush read queues. +.TP 7 +FLUSHW +Flush write queues. +.TP 7 +FLUSHRW +Flush read and write queues. +.sp +.LP +At least the following macros shall be defined for use with I_SETSIG: +.TP 7 +S_RDNORM +A normal (priority band set to 0) message has arrived at the head +of a STREAM head read queue. +.TP 7 +S_RDBAND +A message with a non-zero priority band has arrived at the head of +a STREAM head read queue. +.TP 7 +S_INPUT +A message, other than a high-priority message, has arrived at the +head of a STREAM head read queue. +.TP 7 +S_HIPRI +A high-priority message is present on a STREAM head read queue. +.TP 7 +S_OUTPUT +The write queue for normal data (priority band 0) just below the STREAM +head is no longer full. This notifies the process that +there is room on the queue for sending (or writing) normal data downstream. +.TP 7 +S_WRNORM +Equivalent to S_OUTPUT. +.TP 7 +S_WRBAND +The write queue for a non-zero priority band just below the STREAM +head is no longer full. +.TP 7 +S_MSG +A STREAMS signal message that contains the SIGPOLL signal reaches +the front of the STREAM head read queue. +.TP 7 +S_ERROR +Notification of an error condition reaches the STREAM head. +.TP 7 +S_HANGUP +Notification of a hangup reaches the STREAM head. +.TP 7 +S_BANDURG +When used in conjunction with S_RDBAND, SIGURG is generated instead +of SIGPOLL when a priority message reaches the front of the +STREAM head read queue. +.sp +.LP +At least the following macros shall be defined for use with I_PEEK: +.TP 7 +RS_HIPRI +Only look for high-priority messages. +.sp +.LP +At least the following macros shall be defined for use with I_SRDOPT: +.TP 7 +RNORM +Byte-STREAM mode, the default. +.TP 7 +RMSGD +Message-discard mode. +.TP 7 +RMSGN +Message-non-discard mode. +.TP 7 +RPROTNORM +Fail \fIread\fP() with [EBADMSG] if a message containing a control +part is at the front +of the STREAM head read queue. +.TP 7 +RPROTDAT +Deliver the control part of a message as data when a process issues +a \fIread\fP(). +.TP 7 +RPROTDIS +Discard the control part of a message, delivering any data part, when +a process issues a \fIread\fP(). +.sp +.LP +At least the following macros shall be defined for use with I_SWOPT: +.TP 7 +SNDZERO +Send a zero-length message downstream when a \fIwrite\fP() of 0 bytes +occurs. +.sp +.LP +At least the following macros shall be defined for use with I_ATMARK: +.TP 7 +ANYMARK +Check if the message is marked. +.TP 7 +LASTMARK +Check if the message is the last one marked on the queue. +.sp +.LP +At least the following macros shall be defined for use with I_UNLINK: +.TP 7 +MUXID_ALL +Unlink all STREAMs linked to the STREAM associated with \fIfildes\fP. +.sp +.LP +The following macros shall be defined for \fIgetmsg\fP(), \fIgetpmsg\fP(), +\fIputmsg\fP(), and \fIputpmsg\fP(): +.TP 7 +MSG_ANY +Receive any message. +.TP 7 +MSG_BAND +Receive message from specified band. +.TP 7 +MSG_HIPRI +Send/receive high-priority message. +.TP 7 +MORECTL +More control information is left in message. +.TP 7 +MOREDATA +More data is left in message. +.sp +.LP +The \fI\fP header may make visible all of the symbols from +\fI\fP. +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint isastream(int); +int getmsg(int, struct strbuf *restrict, struct strbuf *restrict, + int *restrict); +int getpmsg(int, struct strbuf *restrict, struct strbuf *restrict, + int *restrict, int *restrict); +int ioctl(int, int, ... ); +int putmsg(int, const struct strbuf *, const struct strbuf *, int); +int putpmsg(int, const struct strbuf *, const struct strbuf *, int, + int); +int fattach(int, const char *); +int fdetach(const char *); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIclose\fP(), \fIfcntl\fP(), +\fIgetmsg\fP(), \fIioctl\fP(), \fIopen\fP(), \fIpipe\fP(), \fIread\fP(), +\fIpoll\fP(), \fIputmsg\fP(), \fIsignal\fP(), \fIwrite\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_ipc.h.0p b/man0p/sys_ipc.h.0p new file mode 100644 index 000000000..c7a0f46b1 --- /dev/null +++ b/man0p/sys_ipc.h.0p @@ -0,0 +1,100 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/ipc.h \- XSI interprocess communication access structure +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header is used by three mechanisms for XSI interprocess +communication (IPC): messages, semaphores, +and shared memory. All use a common structure type, \fBipc_perm\fP, +to pass information used in determining permission to perform +an IPC operation. +.LP +The \fBipc_perm\fP structure shall contain the following members: +.sp +.RS +.nf + +\fBuid_t uid \fP Owner's user ID. \fB +gid_t gid \fP Owner's group ID. \fB +uid_t cuid \fP Creator's user ID. \fB +gid_t cgid \fP Creator's group ID. \fB +mode_t mode \fP Read/write permission. \fB +\fP +.fi +.RE +.LP +The \fBuid_t\fP, \fBgid_t\fP, \fBmode_t\fP, and \fBkey_t\fP types +shall be defined as described in \fI\fP . +.LP +Definitions shall be provided for the following constants: +.LP +Mode bits: +.TP 7 +IPC_CREAT +Create entry if key does not exist. +.TP 7 +IPC_EXCL +Fail if key exists. +.TP 7 +IPC_NOWAIT +Error if request must wait. +.sp +.LP +Keys: +.TP 7 +IPC_PRIVATE +Private key. +.sp +.LP +Control commands: +.TP 7 +IPC_RMID +Remove identifier. +.TP 7 +IPC_SET +Set options. +.TP 7 +IPC_STAT +Get options. +.sp +.LP +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS +.nf + +\fBkey_t ftok(const char *, int); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIftok\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_mman.h.0p b/man0p/sys_mman.h.0p new file mode 100644 index 000000000..fa3ea2c61 --- /dev/null +++ b/man0p/sys_mman.h.0p @@ -0,0 +1,229 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/mman.h \- memory management declarations +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall be supported if the implementation +supports at least one of the following +options: +.IP " *" 3 +The Memory Mapped Files option +.LP +.IP " *" 3 +The Shared Memory Objects option +.LP +.IP " *" 3 +The Process Memory Locking option +.LP +.IP " *" 3 +The Memory Protection option +.LP +.IP " *" 3 +The Typed Memory Objects option +.LP +.IP " *" 3 +The Synchronized Input and Output option +.LP +.IP " *" 3 +The Advisory Information option +.LP +.IP " *" 3 +The Typed Memory Objects option +.LP +.LP +If one or more of the Advisory Information, Memory Mapped Files, or +Shared Memory Objects options are supported, the following +protection options shall be defined: +.TP 7 +PROT_READ +Page can be read. +.TP 7 +PROT_WRITE +Page can be written. +.TP 7 +PROT_EXEC +Page can be executed. +.TP 7 +PROT_NONE +Page cannot be accessed. +.sp +.LP +The following \fIflag\fP options shall be defined: +.TP 7 +MAP_SHARED +Share changes. +.TP 7 +MAP_PRIVATE +Changes are private. +.TP 7 +MAP_FIXED +Interpret \fIaddr\fP exactly. +.sp +.LP +The following flags shall be defined for \fImsync\fP(): +.TP 7 +MS_ASYNC +Perform asynchronous writes. +.TP 7 +MS_SYNC +Perform synchronous writes. +.TP 7 +MS_INVALIDATE +Invalidate mappings. +.sp +.LP +The following symbolic constants shall be defined for the \fImlockall\fP() +function: +.TP 7 +MCL_CURRENT +Lock currently mapped pages. +.TP 7 +MCL_FUTURE +Lock pages that become mapped. +.sp +.LP +The symbolic constant MAP_FAILED shall be defined to indicate a failure +from the \fImmap\fP() function. +.LP +If the Advisory Information and either the Memory Mapped Files or +Shared Memory Objects options are supported, values for +\fIadvice\fP used by \fIposix_madvise\fP() shall be defined as follows: +.TP 7 +POSIX_MADV_NORMAL +.sp +The application has no advice to give on its behavior with respect +to the specified range. It is the default characteristic if no +advice is given for a range of memory. +.TP 7 +POSIX_MADV_SEQUENTIAL +.sp +The application expects to access the specified range sequentially +from lower addresses to higher addresses. +.TP 7 +POSIX_MADV_RANDOM +.sp +The application expects to access the specified range in a random +order. +.TP 7 +POSIX_MADV_WILLNEED +.sp +The application expects to access the specified range in the near +future. +.TP 7 +POSIX_MADV_DONTNEED +.sp +The application expects that it will not access the specified range +in the near future. +.sp +.LP +The following flags shall be defined for \fIposix_typed_mem_open\fP(): +.TP 7 +POSIX_TYPED_MEM_ALLOCATE +.sp +Allocate on \fImmap\fP(). +.TP 7 +POSIX_TYPED_MEM_ALLOCATE_CONTIG +.sp +Allocate contiguously on \fImmap\fP(). +.TP 7 +POSIX_TYPED_MEM_MAP_ALLOCATABLE +.sp +Map on \fImmap\fP(), without affecting allocatability. +.sp +.LP +The \fBmode_t\fP, \fBoff_t\fP, and \fBsize_t\fP types shall be defined +as described in \fI\fP . +.LP +The \fI\fP header shall define the structure \fBposix_typed_mem_info\fP, +which includes at least the +following member: +.sp +.RS +.nf + +\fBsize_t posix_tmi_length \fP Maximum length which may be allocated \fB + \fP from a typed memory object. \fB +\fP +.fi +.RE +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fB +int mlock(const void *, size_t); + + +int mlockall(int); + + +void *mmap(void *, size_t, int, int, int, off_t); + + +int mprotect(void *, size_t, int); + + +int msync(void *, size_t, int); + + +int munlock(const void *, size_t); + + +int munlockall(void); + + +int munmap(void *, size_t); + + +int posix_madvise(void *, size_t, int); + + +int posix_mem_offset(const void *restrict, size_t, off_t *restrict, + size_t *restrict, int *restrict); +int posix_typed_mem_get_info(int, struct posix_typed_mem_info *); +int posix_typed_mem_open(const char *, int, int); + + +int shm_open(const char *, int, mode_t); +int shm_unlink(const char *); + +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fImlock\fP(), \fImlockall\fP(), \fImmap\fP(), +\fImprotect\fP(), \fImsync\fP(), \fImunlock\fP(), \fImunlockall\fP(), +\fImunmap\fP(), \fIposix_mem_offset\fP(), +\fIposix_typed_mem_get_info\fP(), \fIposix_typed_mem_open\fP(), \fIshm_open\fP(), +\fIshm_unlink\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_msg.h.0p b/man0p/sys_msg.h.0p new file mode 100644 index 000000000..8e486967a --- /dev/null +++ b/man0p/sys_msg.h.0p @@ -0,0 +1,96 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/msg.h \- XSI message queue structures +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following data types +through \fBtypedef\fP: +.TP 7 +\fBmsgqnum_t\fP +Used for the number of messages in the message queue. +.TP 7 +\fBmsglen_t\fP +Used for the number of bytes allowed in a message queue. +.sp +.LP +These types shall be unsigned integer types that are able to store +values at least as large as a type \fBunsigned short\fP. +.LP +The \fI\fP header shall define the following constant as +a message operation flag: +.TP 7 +MSG_NOERROR +No error if big message. +.sp +.LP +The \fBmsqid_ds\fP structure shall contain the following members: +.sp +.RS +.nf + +\fBstruct ipc_perm msg_perm \fP Operation permission structure. \fB +msgqnum_t msg_qnum \fP Number of messages currently on queue. \fB +msglen_t msg_qbytes\fP Maximum number of bytes allowed on queue. \fB +pid_t msg_lspid \fP Process ID of last \fImsgsnd\fP + (). \fB +pid_t msg_lrpid \fP Process ID of last \fImsgrcv\fP + (). \fB +time_t msg_stime \fP Time of last \fImsgsnd\fP + (). \fB +time_t msg_rtime \fP Time of last \fImsgrcv\fP + (). \fB +time_t msg_ctime \fP Time of last change. \fB +\fP +.fi +.RE +.LP +The \fBpid_t\fP, \fBtime_t\fP, \fBkey_t\fP, \fBsize_t\fP, and \fBssize_t\fP +types shall be defined as described in \fI\fP . +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint msgctl(int, int, struct msqid_ds *); +int msgget(key_t, int); +ssize_t msgrcv(int, void *, size_t, long, int); +int msgsnd(int, const void *, size_t, int); +\fP +.fi +.RE +.LP +In addition, all of the symbols from \fI\fP shall be defined +when +this header is included. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , \fImsgctl\fP(), \fImsgget\fP(), +\fImsgrcv\fP(), \fImsgsnd\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_resource.h.0p b/man0p/sys_resource.h.0p new file mode 100644 index 000000000..e5ea100b2 --- /dev/null +++ b/man0p/sys_resource.h.0p @@ -0,0 +1,158 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/resource.h \- definitions for XSI resource operations +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following symbolic +constants as possible values of the \fIwhich\fP +argument of \fIgetpriority\fP() and \fIsetpriority\fP(): +.TP 7 +PRIO_PROCESS +Identifies the \fIwho\fP argument as a process ID. +.TP 7 +PRIO_PGRP +Identifies the \fIwho\fP argument as a process group ID. +.TP 7 +PRIO_USER +Identifies the \fIwho\fP argument as a user ID. +.sp +.LP +The following type shall be defined through \fBtypedef\fP: +.TP 7 +\fBrlim_t\fP +Unsigned integer type used for limit values. +.sp +.LP +The following symbolic constants shall be defined: +.TP 7 +RLIM_INFINITY +A value of \fBrlim_t\fP indicating no limit. +.TP 7 +RLIM_SAVED_MAX +A value of type \fBrlim_t\fP indicating an unrepresentable saved hard +limit. +.TP 7 +RLIM_SAVED_CUR +A value of type \fBrlim_t\fP indicating an unrepresentable saved soft +limit. +.sp +.LP +On implementations where all resource limits are representable in +an object of type \fBrlim_t\fP, RLIM_SAVED_MAX and +RLIM_SAVED_CUR need not be distinct from RLIM_INFINITY. +.LP +The following symbolic constants shall be defined as possible values +of the \fIwho\fP parameter of \fIgetrusage\fP(): +.TP 7 +RUSAGE_SELF +Returns information about the current process. +.TP 7 +RUSAGE_CHILDREN +Returns information about children of the current process. +.sp +.LP +The \fI\fP header shall define the \fBrlimit\fP structure +that includes at least the following +members: +.sp +.RS +.nf + +\fBrlim_t rlim_cur \fP The current (soft) limit. \fB +rlim_t rlim_max \fP The hard limit. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the \fBrusage\fP structure +that includes at least the following +members: +.sp +.RS +.nf + +\fBstruct timeval ru_utime \fP User time used. \fB +struct timeval ru_stime \fP System time used. \fB +\fP +.fi +.RE +.LP +The \fBtimeval\fP structure shall be defined as described in \fI\fP +\&. +.LP +The following symbolic constants shall be defined as possible values +for the \fIresource\fP argument of \fIgetrlimit\fP() and \fIsetrlimit\fP(): +.TP 7 +RLIMIT_CORE +Limit on size of \fBcore\fP file. +.TP 7 +RLIMIT_CPU +Limit on CPU time per process. +.TP 7 +RLIMIT_DATA +Limit on data segment size. +.TP 7 +RLIMIT_FSIZE +Limit on file size. +.TP 7 +RLIMIT_NOFILE +Limit on number of open files. +.TP 7 +RLIMIT_STACK +Limit on stack size. +.TP 7 +RLIMIT_AS +Limit on address space size. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint getpriority(int, id_t); +int getrlimit(int, struct rlimit *); +int getrusage(int, struct rusage *); +int setpriority(int, id_t, int); +int setrlimit(int, const struct rlimit *); +\fP +.fi +.RE +.LP +The \fBid_t\fP type shall be defined through \fBtypedef\fP as described +in \fI\fP . +.LP +Inclusion of the \fI\fP header may also make visible +all symbols from \fI\fP. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, \fIgetpriority\fP(), \fIgetrusage\fP(), +\fIgetrlimit\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_select.h.0p b/man0p/sys_select.h.0p new file mode 100644 index 000000000..979363200 --- /dev/null +++ b/man0p/sys_select.h.0p @@ -0,0 +1,115 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/select.h \- select types +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBtimeval\fP structure +that includes at least the following +members: +.sp +.RS +.nf + +\fBtime_t tv_sec \fP Seconds. \fB +suseconds_t tv_usec \fP Microseconds. \fB +\fP +.fi +.RE +.LP +The \fBtime_t\fP and \fBsuseconds_t\fP types shall be defined as described +in \fI\fP . +.LP +The \fBsigset_t\fP type shall be defined as described in \fI\fP +\&. +.LP +The \fBtimespec\fP structure shall be defined as described in \fI\fP +\&. +.LP +The \fI\fP header shall define the \fBfd_set\fP type +as a structure. +.LP +Each of the following may be declared as a function, or defined as +a macro, or both: +.TP 7 +\fBvoid\fP \fIFD_CLR\fP(\fBint\fP \fIfd\fP, \fBfd_set *\fP\fIfdset\fP) +.sp +Clears the bit for the file descriptor \fIfd\fP in the file descriptor +set \fIfdset\fP. +.TP 7 +\fBint\fP \fIFD_ISSET\fP(\fBint\fP \fIfd\fP, \fBfd_set *\fP\fIfdset\fP) +.sp +Returns a non-zero value if the bit for the file descriptor \fIfd\fP +is set in the file descriptor set by \fIfdset\fP, and 0 +otherwise. +.TP 7 +\fBvoid\fP \fIFD_SET\fP(\fBint\fP \fIfd\fP, \fBfd_set *\fP\fIfdset\fP) +.sp +Sets the bit for the file descriptor \fIfd\fP in the file descriptor +set \fIfdset\fP. +.TP 7 +\fBvoid\fP \fIFD_ZERO\fP(\fBfd_set *\fP\fIfdset\fP) +.sp +Initializes the file descriptor set \fIfdset\fP to have zero bits +for all file descriptors. +.sp +.LP +If implemented as macros, these may evaluate their arguments more +than once, so applications should ensure that the arguments +they supply are never expressions with side effects. +.LP +The following shall be defined as a macro: +.TP 7 +FD_SETSIZE +.sp +Maximum number of file descriptors in an \fBfd_set\fP structure. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint pselect(int, fd_set *restrict, fd_set *restrict, fd_set *restrict, + const struct timespec *restrict, const sigset_t *restrict); +int select(int, fd_set *restrict, fd_set *restrict, fd_set *restrict, + struct timeval *restrict); +\fP +.fi +.RE +.LP +Inclusion of the \fI\fP header may make visible all +symbols from the headers \fI\fP, \fI\fP, +and \fI\fP. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , +\fI\fP , \fI\fP , the +System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIpselect\fP(), +\fIselect\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_sem.h.0p b/man0p/sys_sem.h.0p new file mode 100644 index 000000000..5cd3b3b4c --- /dev/null +++ b/man0p/sys_sem.h.0p @@ -0,0 +1,131 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/sem.h \- XSI semaphore facility +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following constants +and structures. +.LP +Semaphore operation flags: +.TP 7 +SEM_UNDO +Set up adjust on exit entry. +.sp +.LP +Command definitions for the \fIsemctl\fP() function shall be provided +as follows: +.TP 7 +GETNCNT +Get \fIsemncnt\fP. +.TP 7 +GETPID +Get \fIsempid\fP. +.TP 7 +GETVAL +Get \fIsemval\fP. +.TP 7 +GETALL +Get all cases of \fIsemval\fP. +.TP 7 +GETZCNT +Get \fIsemzcnt\fP. +.TP 7 +SETVAL +Set \fIsemval\fP. +.TP 7 +SETALL +Set all cases of \fIsemval\fP. +.sp +.LP +The \fBsemid_ds\fP structure shall contain the following members: +.sp +.RS +.nf + +\fBstruct ipc_perm sem_perm \fP Operation permission structure. \fB +unsigned short sem_nsems\fP Number of semaphores in set. \fB +time_t sem_otime\fP Last \fIsemop\fP + () time. \fB +time_t sem_ctime\fP Last time changed by \fIsemctl\fP + (). \fB +\fP +.fi +.RE +.LP +The \fBpid_t\fP, \fBtime_t\fP, \fBkey_t\fP, and \fBsize_t\fP types +shall be defined as described in \fI\fP . +.LP +A semaphore shall be represented by an anonymous structure containing +the following members: +.sp +.RS +.nf + +\fBunsigned short semval \fP Semaphore value. \fB +pid_t sempid \fP Process ID of last operation. \fB +unsigned short semncnt \fP Number of processes waiting for \fIsemval\fP \fB + \fP to become greater than current value. \fB +unsigned short semzcnt \fP Number of processes waiting for \fIsemval\fP \fB + \fP to become 0. \fB +\fP +.fi +.RE +.LP +The \fBsembuf\fP structure shall contain the following members: +.sp +.RS +.nf + +\fBunsigned short sem_num \fP Semaphore number. \fB +short sem_op \fP Semaphore operation. \fB +short sem_flg \fP Operation flags. \fB +\fP +.fi +.RE +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint semctl(int, int, int, ...); +int semget(key_t, int, int); +int semop(int, struct sembuf *, size_t); +\fP +.fi +.RE +.LP +In addition, all of the symbols from \fI\fP shall be defined +when +this header is included. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , \fIsemctl\fP(), \fIsemget\fP(), +\fIsemop\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_shm.h.0p b/man0p/sys_shm.h.0p new file mode 100644 index 000000000..fc247f8a4 --- /dev/null +++ b/man0p/sys_shm.h.0p @@ -0,0 +1,99 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/shm.h \- XSI shared memory facility +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following symbolic constants: +.TP 7 +SHM_RDONLY +Attach read-only (else read-write). +.TP 7 +SHM_RND +Round attach address to SHMLBA. +.sp +.LP +The \fI\fP header shall define the following symbolic value: +.TP 7 +SHMLBA +Segment low boundary address multiple. +.sp +.LP +The following data types shall be defined through \fBtypedef\fP: +.TP 7 +\fBshmatt_t\fP +Unsigned integer used for the number of current attaches that must +be able to store values at least as large as a type +\fBunsigned short\fP. +.sp +.LP +The \fBshmid_ds\fP structure shall contain the following members: +.sp +.RS +.nf + +\fBstruct ipc_perm shm_perm \fP Operation permission structure. \fB +size_t shm_segsz \fP Size of segment in bytes. \fB +pid_t shm_lpid \fP Process ID of last shared memory operation. \fB +pid_t shm_cpid \fP Process ID of creator. \fB +shmatt_t shm_nattch\fP Number of current attaches. \fB +time_t shm_atime \fP Time of last \fIshmat\fP + (). \fB +time_t shm_dtime \fP Time of last \fIshmdt\fP + (). \fB +time_t shm_ctime \fP Time of last change by \fIshmctl\fP + (). \fB +\fP +.fi +.RE +.LP +The \fBpid_t\fP, \fBtime_t\fP, \fBkey_t\fP, and \fBsize_t\fP types +shall be defined as described in \fI\fP . +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBvoid *shmat(int, const void *, int); +int shmctl(int, int, struct shmid_ds *); +int shmdt(const void *); +int shmget(key_t, size_t, int); +\fP +.fi +.RE +.LP +In addition, all of the symbols from \fI\fP shall be defined +when +this header is included. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, \fIshmat\fP(), \fIshmctl\fP(), \fIshmdt\fP(), +\fIshmget\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_socket.h.0p b/man0p/sys_socket.h.0p new file mode 100644 index 000000000..12cca0b6b --- /dev/null +++ b/man0p/sys_socket.h.0p @@ -0,0 +1,446 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/socket.h \- main sockets header +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the type \fBsocklen_t\fP, +which is an integer type of width of at least 32 +bits; see APPLICATION USAGE. +.LP +The \fI\fP header shall define the unsigned integer +type \fBsa_family_t\fP. +.LP +The \fI\fP header shall define the \fBsockaddr\fP structure +that includes at least the following +members: +.sp +.RS +.nf + +\fBsa_family_t sa_family \fP Address family. \fB +char sa_data[] \fP Socket address (variable-length data). \fB +\fP +.fi +.RE +.LP +The \fBsockaddr\fP structure is used to define a socket address which +is used in the \fIbind\fP(), \fIconnect\fP(), \fIgetpeername\fP(), +\fIgetsockname\fP(), +\fIrecvfrom\fP(), and \fIsendto\fP() +functions. +.LP +The \fI\fP header shall define the \fBsockaddr_storage\fP +structure. This structure shall be: +.IP " *" 3 +Large enough to accommodate all supported protocol-specific address +structures +.LP +.IP " *" 3 +Aligned at an appropriate boundary so that pointers to it can be cast +as pointers to protocol-specific address structures and +used to access the fields of those structures without alignment problems +.LP +.LP +The \fBsockaddr_storage\fP structure shall contain at least the following +members: +.sp +.RS +.nf + +\fBsa_family_t ss_family +\fP +.fi +.RE +.LP +When a \fBsockaddr_storage\fP structure is cast as a \fBsockaddr\fP +structure, the \fIss_family\fP field of the +\fBsockaddr_storage\fP structure shall map onto the \fIsa_family\fP +field of the \fBsockaddr\fP structure. When a +\fBsockaddr_storage\fP structure is cast as a protocol-specific address +structure, the \fIss_family\fP field shall map onto a +field of that structure that is of type \fBsa_family_t\fP and that +identifies the protocol's address family. +.LP +The \fI\fP header shall define the \fBmsghdr\fP structure +that includes at least the following +members: +.sp +.RS +.nf + +\fBvoid *msg_name \fP Optional address. \fB +socklen_t msg_namelen \fP Size of address. \fB +struct iovec *msg_iov \fP Scatter/gather array. \fB +int msg_iovlen \fP Members in \fImsg_iov\fP. \fB +void *msg_control \fP Ancillary data; see below. \fB +socklen_t msg_controllen \fP Ancillary data buffer \fIlen\fP. \fB +int msg_flags \fP Flags on received message. \fB +\fP +.fi +.RE +.LP +The \fBmsghdr\fP structure is used to minimize the number of directly +supplied parameters to the \fIrecvmsg\fP() and \fIsendmsg\fP() functions. +This +structure is used as a \fIvalue\fP- \fIresult\fP parameter in the +\fIrecvmsg\fP() +function and \fIvalue\fP only for the \fIsendmsg\fP() function. +.LP +The \fBiovec\fP structure shall be defined as described in \fI\fP +\&. +.LP +The \fI\fP header shall define the \fBcmsghdr\fP structure +that includes at least the following +members: +.sp +.RS +.nf + +\fBsocklen_t cmsg_len \fP Data byte count, including the \fBcmsghdr\fP. \fB +int cmsg_level \fP Originating protocol. \fB +int cmsg_type \fP Protocol-specific type. \fB +\fP +.fi +.RE +.LP +The \fBcmsghdr\fP structure is used for storage of ancillary data +object information. +.LP +Ancillary data consists of a sequence of pairs, each consisting of +a \fBcmsghdr\fP structure followed by a data array. The data +array contains the ancillary data message, and the \fBcmsghdr\fP structure +contains descriptive information that allows an +application to correctly parse the data. +.LP +The values for \fIcmsg_level\fP shall be legal values for the \fIlevel\fP +argument to the \fIgetsockopt\fP() and \fIsetsockopt\fP() +functions. The system documentation shall specify the \fIcmsg_type\fP +definitions for the supported protocols. +.LP +Ancillary data is also possible at the socket level. The \fI\fP +header defines the following macro for use +as the \fIcmsg_type\fP value when \fIcmsg_level\fP is SOL_SOCKET: +.TP 7 +SCM_RIGHTS +Indicates that the data array contains the access rights to be sent +or received. +.sp +.LP +The \fI\fP header defines the following macros to gain +access to the data arrays in the ancillary data +associated with a message header: +.TP 7 +CMSG_DATA(\fIcmsg\fP) +.sp +If the argument is a pointer to a \fBcmsghdr\fP structure, this macro +shall return an unsigned character pointer to the data array +associated with the \fBcmsghdr\fP structure. +.TP 7 +CMSG_NXTHDR(\fImhdr,cmsg\fP) +.sp +If the first argument is a pointer to a \fBmsghdr\fP structure and +the second argument is a pointer to a \fBcmsghdr\fP structure +in the ancillary data pointed to by the \fImsg_control\fP field of +that \fBmsghdr\fP structure, this macro shall return a pointer +to the next \fBcmsghdr\fP structure, or a null pointer if this structure +is the last \fBcmsghdr\fP in the ancillary data. +.TP 7 +CMSG_FIRSTHDR(\fImhdr\fP) +.sp +If the argument is a pointer to a \fBmsghdr\fP structure, this macro +shall return a pointer to the first \fBcmsghdr\fP structure +in the ancillary data associated with this \fBmsghdr\fP structure, +or a null pointer if there is no ancillary data associated with +the \fBmsghdr\fP structure. +.sp +.LP +The \fI\fP header shall define the \fBlinger\fP structure +that includes at least the following +members: +.sp +.RS +.nf + +\fBint l_onoff \fP Indicates whether linger option is enabled. \fB +int l_linger \fP Linger time, in seconds. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the following macros, +with distinct integer values: +.TP 7 +SOCK_DGRAM +Datagram socket. +.TP 7 +SOCK_RAW +Raw Protocol Interface. +.TP 7 +SOCK_SEQPACKET +Sequenced-packet socket. +.TP 7 +SOCK_STREAM +Byte-stream socket. +.sp +.LP +The \fI\fP header shall define the following macro for +use as the \fIlevel\fP argument of \fIsetsockopt\fP() and \fIgetsockopt\fP(). +.TP 7 +SOL_SOCKET +Options to be accessed at socket level, not protocol level. +.sp +.LP +The \fI\fP header shall define the following macros, +with distinct integer values, for use as the +\fIoption_name\fP argument in \fIgetsockopt\fP() or \fIsetsockopt\fP() +calls: +.TP 7 +SO_ACCEPTCONN +Socket is accepting connections. +.TP 7 +SO_BROADCAST +Transmission of broadcast messages is supported. +.TP 7 +SO_DEBUG +Debugging information is being recorded. +.TP 7 +SO_DONTROUTE +Bypass normal routing. +.TP 7 +SO_ERROR +Socket error status. +.TP 7 +SO_KEEPALIVE +Connections are kept alive with periodic messages. +.TP 7 +SO_LINGER +Socket lingers on close. +.TP 7 +SO_OOBINLINE +Out-of-band data is transmitted in line. +.TP 7 +SO_RCVBUF +Receive buffer size. +.TP 7 +SO_RCVLOWAT +Receive ``low water mark''. +.TP 7 +SO_RCVTIMEO +Receive timeout. +.TP 7 +SO_REUSEADDR +Reuse of local addresses is supported. +.TP 7 +SO_SNDBUF +Send buffer size. +.TP 7 +SO_SNDLOWAT +Send ``low water mark''. +.TP 7 +SO_SNDTIMEO +Send timeout. +.TP 7 +SO_TYPE +Socket type. +.sp +.LP +The \fI\fP header shall define the following macro as +the maximum \fIbacklog\fP queue length which may be +specified by the \fIbacklog\fP field of the \fIlisten\fP() function: +.TP 7 +SOMAXCONN +The maximum \fIbacklog\fP queue length. +.sp +.LP +The \fI\fP header shall define the following macros, +with distinct integer values, for use as the valid +values for the \fImsg_flags\fP field in the \fBmsghdr\fP structure, +or the \fIflags\fP parameter in \fIrecvfrom\fP(), \fIrecvmsg\fP(), +\fIsendmsg\fP(), or \fIsendto\fP() calls: +.TP 7 +MSG_CTRUNC +Control data truncated. +.TP 7 +MSG_DONTROUTE +Send without using routing tables. +.TP 7 +MSG_EOR +Terminates a record (if supported by the protocol). +.TP 7 +MSG_OOB +Out-of-band data. +.TP 7 +MSG_PEEK +Leave received data in queue. +.TP 7 +MSG_TRUNC +Normal data truncated. +.TP 7 +MSG_WAITALL +Attempt to fill the read buffer. +.sp +.LP +The \fI\fP header shall define the following macros, +with distinct integer values: +.TP 7 +AF_INET +Internet domain sockets for use with IPv4 addresses. +.TP 7 +AF_INET6 +Internet domain sockets for use with IPv6 addresses. +.TP 7 +AF_UNIX +UNIX domain sockets. +.TP 7 +AF_UNSPEC +Unspecified. +.sp +.LP +The \fI\fP header shall define the following macros, +with distinct integer values: +.TP 7 +SHUT_RD +Disables further receive operations. +.TP 7 +SHUT_RDWR +Disables further send and receive operations. +.TP 7 +SHUT_WR +Disables further send operations. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint accept(int, struct sockaddr *restrict, socklen_t *restrict); +int bind(int, const struct sockaddr *, socklen_t); +int connect(int, const struct sockaddr *, socklen_t); +int getpeername(int, struct sockaddr *restrict, socklen_t *restrict); +int getsockname(int, struct sockaddr *restrict, socklen_t *restrict); +int getsockopt(int, int, int, void *restrict, socklen_t *restrict); +int listen(int, int); +ssize_t recv(int, void *, size_t, int); +ssize_t recvfrom(int, void *restrict, size_t, int, + struct sockaddr *restrict, socklen_t *restrict); +ssize_t recvmsg(int, struct msghdr *, int); +ssize_t send(int, const void *, size_t, int); +ssize_t sendmsg(int, const struct msghdr *, int); +ssize_t sendto(int, const void *, size_t, int, const struct sockaddr *, + socklen_t); +int setsockopt(int, int, int, const void *, socklen_t); +int shutdown(int, int); +int socket(int, int, int); +int sockatmark(int); +int socketpair(int, int, int, int[2]); +\fP +.fi +.RE +.LP +Inclusion of \fI\fP may also make visible all symbols +from \fI\fP. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +To forestall portability problems, it is recommended that applications +not use values larger than 2**31 +-1 for the \fBsocklen_t\fP type. +.LP +The \fBsockaddr_storage\fP structure solves the problem of declaring +storage for automatic variables which is both large enough +and aligned enough for storing the socket address data structure of +any family. For example, code with a file descriptor and +without the context of the address family can pass a pointer to a +variable of this type, where a pointer to a socket address +structure is expected in calls such as \fIgetpeername\fP(), and determine +the +address family by accessing the received content after the call. +.LP +The example below illustrates a data structure which aligns on a 64-bit +boundary. An implementation-defined field +\fI_ss_align\fP following \fI_ss_pad1\fP is used to force a 64-bit +alignment which covers proper alignment good enough for needs +of at least \fBsockaddr_in6\fP (IPv6) and \fBsockaddr_in\fP (IPv4) +address data structures. The size of padding field +\fI_ss_pad1\fP depends on the chosen alignment boundary. The size +of padding field \fI_ss_pad2\fP depends on the value of overall +size chosen for the total size of the structure. This size and alignment +are represented in the above example by +implementation-defined (not required) constants _SS_MAXSIZE (chosen +value 128) and _SS_ALIGNMENT (with chosen value 8). Constants +_SS_PAD1SIZE (derived value 6) and _SS_PAD2SIZE (derived value 112) +are also for illustration and not required. The +implementation-defined definitions and structure field names above +start with an underscore to denote implementation private name +space. Portable code is not expected to access or reference those +fields or constants. +.sp +.RS +.nf + +\fB/* + * Desired design of maximum size and alignment. + */ +#define _SS_MAXSIZE 128 + /* Implementation-defined maximum size. */ +#define _SS_ALIGNSIZE (sizeof(int64_t)) + /* Implementation-defined desired alignment. */ +.sp + +/* + * Definitions used for sockaddr_storage structure paddings design. + */ +#define _SS_PAD1SIZE (_SS_ALIGNSIZE - sizeof(sa_family_t)) +#define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof(sa_family_t)+ \\ + _SS_PAD1SIZE + _SS_ALIGNSIZE)) +struct sockaddr_storage { + sa_family_t ss_family; /* Address family. */ +/* + * Following fields are implementation-defined. + */ + char _ss_pad1[_SS_PAD1SIZE]; + /* 6-byte pad; this is to make implementation-defined + pad up to alignment field that follows explicit in + the data structure. */ + int64_t _ss_align; /* Field to force desired structure + storage alignment. */ + char _ss_pad2[_SS_PAD2SIZE]; + /* 112-byte pad to achieve desired size, + _SS_MAXSIZE value minus size of ss_family + __ss_pad1, __ss_align fields is 112. */ +}; +\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIaccept\fP(), \fIbind\fP(), \fIconnect\fP(), +\fIgetpeername\fP(), \fIgetsockname\fP(), +\fIgetsockopt\fP(), \fIlisten\fP(), \fIrecv\fP(), \fIrecvfrom\fP(), +\fIrecvmsg\fP(), \fIsend\fP(), \fIsendmsg\fP(), \fIsendto\fP(), \fIsetsockopt\fP(), +\fIshutdown\fP(), \fIsocket\fP(), \fIsocketpair\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_stat.h.0p b/man0p/sys_stat.h.0p new file mode 100644 index 000000000..40990938e --- /dev/null +++ b/man0p/sys_stat.h.0p @@ -0,0 +1,355 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/stat.h \- data returned by the stat() function +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the structure of the data +returned by the functions \fIfstat\fP(), \fIlstat\fP(), and \fIstat\fP(). +.LP +The \fBstat\fP structure shall contain at least the following members: +.sp +.RS +.nf + +\fBdev_t st_dev \fP Device ID of device containing file. \fB +ino_t st_ino \fP File serial number. \fB +mode_t st_mode \fP Mode of file (see below). \fB +nlink_t st_nlink \fP Number of hard links to the file. \fB +uid_t st_uid \fP User ID of file. \fB +gid_t st_gid \fP Group ID of file. \fB + +dev_t st_rdev \fP Device ID (if file is character or block special). \fB + +off_t st_size \fP For regular files, the file size in bytes. \fB + \fP For symbolic links, the length in bytes of the \fB + \fP pathname contained in the symbolic link. \fB + + \fP For a shared memory object, the length in bytes. \fB + + + \fP For a typed memory object, the length in bytes. \fB + + \fP For other file types, the use of this field is \fB + \fP unspecified. \fB +time_t st_atime \fP Time of last access. \fB +time_t st_mtime \fP Time of last data modification. \fB +time_t st_ctime \fP Time of last status change. \fB + +blksize_t st_blksize\fP A file system-specific preferred I/O block size for \fB + \fP this object. In some file system types, this may \fB + \fP vary from file to file. \fB +blkcnt_t st_blocks \fP Number of blocks allocated for this object. \fB + +\fP +.fi +.RE +.LP +The \fIst_ino\fP and \fIst_dev\fP fields taken together uniquely identify +the file within the system. The \fBblkcnt_t\fP, +\fBblksize_t\fP, \fBdev_t\fP, \fBino_t\fP, \fBmode_t\fP, \fBnlink_t\fP, +\fBuid_t\fP, \fBgid_t\fP, \fBoff_t\fP, and +\fBtime_t\fP types shall be defined as described in \fI\fP +\&. Times +shall be given in seconds since the Epoch. +.LP +Unless otherwise specified, the structure members \fIst_mode\fP, \fIst_ino\fP, +\fIst_dev\fP, \fIst_uid\fP, \fIst_gid\fP, +\fIst_atime\fP, \fIst_ctime\fP, and \fIst_mtime\fP shall have meaningful +values for all file types defined in +IEEE\ Std\ 1003.1-2001. +.LP +For symbolic links, the \fIst_mode\fP member shall contain meaningful +information, which can be used with the file type macros +described below, that take a \fImode\fP argument. The \fIst_size\fP +member shall contain the length, in bytes, of the pathname +contained in the symbolic link. File mode bits and the contents of +the remaining members of the \fBstat\fP structure are +unspecified. The value returned in the \fIst_size\fP field shall be +the length of the contents of the symbolic link, and shall not +count a trailing null if one is present. +.LP +The following symbolic names for the values of type \fBmode_t\fP shall +also be defined. +.LP +File type: +.TP 7 +S_IFMT +Type of file. +.TP 7 +S_IFBLK +.RS +Block special. +.RE +.TP 7 +S_IFCHR +.RS +Character special. +.RE +.TP 7 +S_IFIFO +.RS +FIFO special. +.RE +.TP 7 +S_IFREG +.RS +Regular. +.RE +.TP 7 +S_IFDIR +.RS +Directory. +.RE +.TP 7 +S_IFLNK +.RS +Symbolic link. +.RE +.TP 7 +S_IFSOCK +.RS +Socket. +.RE +.sp +.sp +.LP +File mode bits: +.TP 7 +S_IRWXU +Read, write, execute/search by owner. +.TP 7 +S_IRUSR +.RS +Read permission, owner. +.RE +.TP 7 +S_IWUSR +.RS +Write permission, owner. +.RE +.TP 7 +S_IXUSR +.RS +Execute/search permission, owner. +.RE +.sp +.TP 7 +S_IRWXG +Read, write, execute/search by group. +.TP 7 +S_IRGRP +.RS +Read permission, group. +.RE +.TP 7 +S_IWGRP +.RS +Write permission, group. +.RE +.TP 7 +S_IXGRP +.RS +Execute/search permission, group. +.RE +.sp +.TP 7 +S_IRWXO +Read, write, execute/search by others. +.TP 7 +S_IROTH +.RS +Read permission, others. +.RE +.TP 7 +S_IWOTH +.RS +Write permission, others. +.RE +.TP 7 +S_IXOTH +.RS +Execute/search permission, others. +.RE +.sp +.TP 7 +S_ISUID +Set-user-ID on execution. +.TP 7 +S_ISGID +Set-group-ID on execution. +.TP 7 +S_ISVTX +On directories, restricted deletion flag. +.sp +.LP +The bits defined by S_IRUSR, S_IWUSR, S_IXUSR, S_IRGRP, S_IWGRP, S_IXGRP, +S_IROTH, S_IWOTH, S_IXOTH, S_ISUID, S_ISGID, \ and +S_ISVTX \ shall be unique. +.LP +S_IRWXU is the bitwise-inclusive OR of S_IRUSR, S_IWUSR, and S_IXUSR. +.LP +S_IRWXG is the bitwise-inclusive OR of S_IRGRP, S_IWGRP, and S_IXGRP. +.LP +S_IRWXO is the bitwise-inclusive OR of S_IROTH, S_IWOTH, and S_IXOTH. +.LP +Implementations may OR other implementation-defined bits into S_IRWXU, +S_IRWXG, and S_IRWXO, but they shall not overlap any of +the other bits defined in this volume of IEEE\ Std\ 1003.1-2001. The +\fIfile permission bits\fP are defined to be those +corresponding to the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and +S_IRWXO. +.LP +The following macros shall be provided to test whether a file is of +the specified type. The value \fIm\fP supplied to the +macros is the value of \fIst_mode\fP from a \fBstat\fP structure. +The macro shall evaluate to a non-zero value if the test is +true; 0 if the test is false. +.TP 7 +S_ISBLK(\fIm\fP) +Test for a block special file. +.TP 7 +S_ISCHR(\fIm\fP) +Test for a character special file. +.TP 7 +S_ISDIR(\fIm\fP) +Test for a directory. +.TP 7 +S_ISFIFO(\fIm\fP) +Test for a pipe or FIFO special file. +.TP 7 +S_ISREG(\fIm\fP) +Test for a regular file. +.TP 7 +S_ISLNK(\fIm\fP) +Test for a symbolic link. +.TP 7 +S_ISSOCK(\fIm\fP) +Test for a socket. +.sp +.LP +The implementation may implement message queues, semaphores, or shared +memory objects as distinct file types. The following +macros shall be provided to test whether a file is of the specified +type. The value of the \fIbuf\fP argument supplied to the +macros is a pointer to a \fBstat\fP structure. The macro shall evaluate +to a non-zero value if the specified object is implemented +as a distinct file type and the specified file type is contained in +the \fBstat\fP structure referenced by \fIbuf\fP. Otherwise, +the macro shall evaluate to zero. +.TP 7 +S_TYPEISMQ(\fIbuf\fP) +Test for a message queue. +.TP 7 +S_TYPEISSEM(\fIbuf\fP) +Test for a semaphore. +.TP 7 +S_TYPEISSHM(\fIbuf\fP) +Test for a shared memory object. +.sp +.LP +The implementation may implement typed memory objects as distinct +file types, and the following macro shall test whether a +file is of the specified type. The value of the \fIbuf\fP argument +supplied to the macros is a pointer to a \fBstat\fP structure. +The macro shall evaluate to a non-zero value if the specified object +is implemented as a distinct file type and the specified file +type is contained in the \fBstat\fP structure referenced by \fIbuf\fP. +Otherwise, the macro shall evaluate to zero. +.TP 7 +S_TYPEISTMO(\fIbuf\fP) +Test macro for a typed memory object. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint chmod(const char *, mode_t); +int fchmod(int, mode_t); +int fstat(int, struct stat *); +int lstat(const char *restrict, struct stat *restrict); +int mkdir(const char *, mode_t); +int mkfifo(const char *, mode_t); + +int mknod(const char *, mode_t, dev_t); + +int stat(const char *restrict, struct stat *restrict); +mode_t umask(mode_t); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Use of the macros is recommended for determining the type of a file. +.SH RATIONALE +.LP +A conforming C-language application must include \fI\fP +for functions that have arguments or return values of +type \fBmode_t\fP, so that symbolic values for that type can be used. +An alternative would be to require that these constants are +also defined by including \fI\fP. +.LP +The S_ISUID and S_ISGID bits may be cleared on any write, not just +on \fIopen\fP(), as +some historical implementations do. +.LP +System calls that update the time entry fields in the \fBstat\fP structure +must be documented by the implementors. +POSIX-conforming systems should not update the time entry fields for +functions listed in the System Interfaces volume of +IEEE\ Std\ 1003.1-2001 unless the standard requires that they do, +except in the case of documented extensions to the +standard. +.LP +Note that \fIst_dev\fP must be unique within a Local Area Network +(LAN) in a ``system'' made up of multiple computers' file +systems connected by a LAN. +.LP +Networked implementations of a POSIX-conforming system must guarantee +that all files visible within the file tree (including +parts of the tree that may be remotely mounted from other machines +on the network) on each individual processor are uniquely +identified by the combination of the \fIst_ino\fP and \fIst_dev\fP +fields. +.LP +The unit for the \fIst_blocks\fP member of the \fBstat\fP structure +is not defined within IEEE\ Std\ 1003.1-2001. In +some implementations it is 512 bytes. It may differ on a file system +basis. There is no correlation between values of the +\fIst_blocks\fP and \fIst_blksize\fP, and the \fIf_bsize\fP (from +\fI\fP) structure members. +.LP +Traditionally, some implementations defined the multiplier for \fIst_blocks\fP +in +\fI\fP as the symbol DEV_BSIZE. +.SH FUTURE DIRECTIONS +.LP +No new S_IFMT symbolic names for the file type values of \fBmode_t\fP +will be defined by IEEE\ Std\ 1003.1-2001; if new +file types are required, they will only be testable through \fIS_ISxx\fP() +or \fIS_TYPEISxxx\fP() macros instead. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, \fIchmod\fP(), \fIfchmod\fP(), \fIfstat\fP(), +\fIlstat\fP(), \fImkdir\fP(), \fImkfifo\fP(), \fImknod\fP(), \fIstat\fP(), +\fIumask\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_statvfs.h.0p b/man0p/sys_statvfs.h.0p new file mode 100644 index 000000000..b99439c25 --- /dev/null +++ b/man0p/sys_statvfs.h.0p @@ -0,0 +1,83 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/statvfs.h \- VFS File System information structure +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBstatvfs\fP structure +that includes at least the following +members: +.sp +.RS +.nf + +\fBunsigned long f_bsize \fP File system block size. \fB +unsigned long f_frsize \fP Fundamental file system block size. \fB +fsblkcnt_t f_blocks \fP Total number of blocks on file system in units of \fIf_frsize.\fP \fB +fsblkcnt_t f_bfree \fP Total number of free blocks. \fB +fsblkcnt_t f_bavail \fP Number of free blocks available to \fB + \fP non-privileged process. \fB +fsfilcnt_t f_files \fP Total number of file serial numbers. \fB +fsfilcnt_t f_ffree \fP Total number of free file serial numbers. \fB +fsfilcnt_t f_favail \fP Number of file serial numbers available to \fB + \fP non-privileged process. \fB +unsigned long f_fsid \fP File system ID. \fB +unsigned long f_flag \fP Bit mask of \fIf_flag\fP values. \fB +unsigned long f_namemax \fP Maximum filename length. \fB +\fP +.fi +.RE +.LP +The \fBfsblkcnt_t\fP and \fBfsfilcnt_t\fP types shall be defined as +described in \fI\fP . +.LP +The following flags for the \fIf_flag\fP member shall be defined: +.TP 7 +ST_RDONLY +Read-only file system. +.TP 7 +ST_NOSUID +Does not support the semantics of the ST_ISUID and ST_ISGID file mode +bits. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint statvfs(const char *restrict, struct statvfs *restrict); +int fstatvfs(int, struct statvfs *); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIfstatvfs\fP(), \fIstatvfs\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_time.h.0p b/man0p/sys_time.h.0p new file mode 100644 index 000000000..6bd674937 --- /dev/null +++ b/man0p/sys_time.h.0p @@ -0,0 +1,103 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/time.h \- time types +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBtimeval\fP structure +that includes at least the following members: +.sp +.RS +.nf + +\fBtime_t tv_sec \fP Seconds. \fB +suseconds_t tv_usec \fP Microseconds. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall define the \fBitimerval\fP structure +that includes at least the following +members: +.sp +.RS +.nf + +\fBstruct timeval it_interval\fP Timer interval. \fB +struct timeval it_value \fP Current value. \fB +\fP +.fi +.RE +.LP +The \fBtime_t\fP and \fBsuseconds_t\fP types shall be defined as described +in \fI\fP . +.LP +The \fBfd_set\fP type shall be defined as described in \fI\fP +\&. +.LP +The \fI\fP header shall define the following values for +the \fIwhich\fP argument of \fIgetitimer\fP() and \fIsetitimer\fP(): +.TP 7 +ITIMER_REAL +Decrements in real time. +.TP 7 +ITIMER_VIRTUAL +Decrements in process virtual time. +.TP 7 +ITIMER_PROF +Decrements both in process virtual time and when the system is running +on behalf of the process. +.sp +.LP +The following shall be defined as described in \fI\fP +: \fIFD_CLR\fP() \fIFD_ISSET\fP() \fIFD_SET\fP() \fIFD_ZERO\fP() FD_SETSIZE +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint getitimer(int, struct itimerval *); +int gettimeofday(struct timeval *restrict, void *restrict); +int select(int, fd_set *restrict, fd_set *restrict, fd_set *restrict, + struct timeval *restrict); +int setitimer(int, const struct itimerval *restrict, + struct itimerval *restrict); +int utimes(const char *, const struct timeval [2]); (\fP\fBLEGACY\fP \fB) +\fP +.fi +.RE +.LP +Inclusion of the \fI\fP header may make visible all symbols +from the \fI\fP header. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, \fIgetitimer\fP(), \fIgettimeofday\fP(), +\fIselect\fP(), \fIsetitimer\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_timeb.h.0p b/man0p/sys_timeb.h.0p new file mode 100644 index 000000000..2992398db --- /dev/null +++ b/man0p/sys_timeb.h.0p @@ -0,0 +1,61 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/timeb.h \- additional definitions for date and time +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBtimeb\fP structure +that includes at least the following members: +.sp +.RS +.nf + +\fBtime_t time \fP The seconds portion of the current time. \fB +unsigned short millitm \fP The milliseconds portion of the current time. \fB +short timezone\fP The local timezone in minutes west of Greenwich. \fB +short dstflag \fP TRUE if Daylight Savings Time is in effect. \fB +\fP +.fi +.RE +.LP +The \fBtime_t\fP type shall be defined as described in \fI\fP +\&. +.LP +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS +.nf + +\fBint ftime(struct timeb *); (\fP\fBLEGACY\fP \fB) +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_times.h.0p b/man0p/sys_times.h.0p new file mode 100644 index 000000000..9ea5476a6 --- /dev/null +++ b/man0p/sys_times.h.0p @@ -0,0 +1,63 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/times.h \- file access and modification times structure +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the structure \fBtms\fP, +which is returned by \fItimes\fP() and includes at least the following +members: +.sp +.RS +.nf + +\fBclock_t tms_utime \fP User CPU time. \fB +clock_t tms_stime \fP System CPU time. \fB +clock_t tms_cutime\fP User CPU time of terminated child processes. \fB +clock_t tms_cstime\fP System CPU time of terminated child processes. \fB +\fP +.fi +.RE +.LP +The \fBclock_t\fP type shall be defined as described in \fI\fP +\&. +.LP +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS +.nf + +\fBclock_t times(struct tms *); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fItimes\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_types.h.0p b/man0p/sys_types.h.0p new file mode 100644 index 000000000..8a540095f --- /dev/null +++ b/man0p/sys_types.h.0p @@ -0,0 +1,291 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/types.h \- data types +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall include definitions for at least +the following types: +.TP 7 +\fBblkcnt_t\fP +Used for file block counts. +.TP 7 +\fBblksize_t\fP +Used for block sizes. +.TP 7 +\fBclock_t\fP +Used for system times in clock ticks or CLOCKS_PER_SEC; see \fI\fP +\&. +.TP 7 +\fBclockid_t\fP +Used for clock ID type in the clock and timer functions. +.TP 7 +\fBdev_t\fP +Used for device IDs. +.TP 7 +\fBfsblkcnt_t\fP +Used for file system block counts. +.TP 7 +\fBfsfilcnt_t\fP +Used for file system file counts. +.TP 7 +\fBgid_t\fP +Used for group IDs. +.TP 7 +\fBid_t\fP +Used as a general identifier; can be used to contain at least a \fBpid_t\fP, +\fBuid_t\fP, or \fBgid_t\fP. +.TP 7 +\fBino_t\fP +Used for file serial numbers. +.TP 7 +\fBkey_t\fP +Used for XSI interprocess communication. +.TP 7 +\fBmode_t\fP +Used for some file attributes. +.TP 7 +\fBnlink_t\fP +Used for link counts. +.TP 7 +\fBoff_t\fP +Used for file sizes. +.TP 7 +\fBpid_t\fP +Used for process IDs and process group IDs. +.TP 7 +\fBpthread_attr_t\fP +Used to identify a thread attribute object. +.TP 7 +\fBpthread_barrier_t\fP +Used to identify a barrier. +.TP 7 +\fBpthread_barrierattr_t\fP +Used to define a barrier attributes object. +.TP 7 +\fBpthread_cond_t\fP +Used for condition variables. +.TP 7 +\fBpthread_condattr_t\fP +Used to identify a condition attribute object. +.TP 7 +\fBpthread_key_t\fP +Used for thread-specific data keys. +.TP 7 +\fBpthread_mutex_t\fP +Used for mutexes. +.TP 7 +\fBpthread_mutexattr_t\fP +Used to identify a mutex attribute object. +.TP 7 +\fBpthread_once_t\fP +Used for dynamic package initialization. +.TP 7 +\fBpthread_rwlock_t\fP +Used for read-write locks. +.TP 7 +\fBpthread_rwlockattr_t\fP +Used for read-write lock attributes. +.TP 7 +\fBpthread_spinlock_t\fP +Used to identify a spin lock. +.TP 7 +\fBpthread_t\fP +Used to identify a thread. +.TP 7 +\fBsize_t\fP +Used for sizes of objects. +.TP 7 +\fBssize_t\fP +Used for a count of bytes or an error indication. +.TP 7 +\fBsuseconds_t\fP +Used for time in microseconds. +.TP 7 +\fBtime_t\fP +Used for time in seconds. +.TP 7 +\fBtimer_t\fP +Used for timer ID returned by \fItimer_create\fP(). +.TP 7 +\fBtrace_attr_t\fP +Used to identify a trace stream attributes object. +.TP 7 +\fBtrace_event_id_t\fP +Used to identify a trace event type. +.TP 7 +\fBtrace_event_set_t\fP +Used to identify a trace event type set. +.TP 7 +\fBtrace_id_t\fP +Used to identify a trace stream. +.TP 7 +\fBuid_t\fP +Used for user IDs. +.TP 7 +\fBuseconds_t\fP +Used for time in microseconds. +.sp +.LP +All of the types shall be defined as arithmetic types of an appropriate +length, with the following exceptions: +.LP +.sp +.sp +\fBkey_t\fP +.br +.sp +.sp +\fBpthread_attr_t\fP +.br +.sp +.sp +\fBpthread_barrier_t\fP +.br +\fBpthread_barrierattr_t\fP +.br +.sp +.sp +\fBpthread_cond_t\fP +.br +\fBpthread_condattr_t\fP +.br +\fBpthread_key_t\fP +.br +\fBpthread_mutex_t\fP +.br +\fBpthread_mutexattr_t\fP +.br +\fBpthread_once_t\fP +.br +\fBpthread_rwlock_t\fP +.br +\fBpthread_rwlockattr_t\fP +.br +.sp +.sp +\fBpthread_spinlock_t\fP +.br +.sp +.sp +\fBtrace_attr_t\fP +.br +\fBtrace_event_id_t\fP +.br +.sp +.sp +\fBtrace_event_set_t\fP +.br +.sp +.sp +\fBtrace_id_t\fP +.br +.sp +.LP +Additionally: +.IP " *" 3 +\fBmode_t\fP shall be an integer type. +.LP +.IP " *" 3 +\fBnlink_t\fP, \fBuid_t\fP, \fBgid_t\fP, and \fBid_t\fP shall be integer +types. +.LP +.IP " *" 3 +\fBblkcnt_t\fP and \fBoff_t\fP shall be signed integer types. +.LP +.IP " *" 3 +\fBfsblkcnt_t\fP, \fBfsfilcnt_t\fP, \ and +\fBino_t\fP shall be defined as unsigned integer types. +.LP +.IP " *" 3 +\fBsize_t\fP shall be an unsigned integer type. +.LP +.IP " *" 3 +\fBblksize_t\fP, \fBpid_t\fP, and \fBssize_t\fP shall be signed integer +types. +.LP +.IP " *" 3 +\fBtime_t\fP and \fBclock_t\fP shall be integer or real-floating types. +.LP +.LP +The type \fBssize_t\fP shall be capable of storing values at least +in the range [-1,\ {SSIZE_MAX}]. \ The type +\fBuseconds_t\fP shall be an unsigned integer type capable of storing +values at least in the range [0,\ 1000000]. The type +\fBsuseconds_t\fP shall be a signed integer type capable of storing +values at least in the range [-1,\ 1000000]. +.LP +The implementation shall support one or more programming environments +in which the widths of \fBblksize_t\fP, \fBpid_t\fP, +\fBsize_t\fP, \fBssize_t\fP, \fBsuseconds_t\fP, and \fBuseconds_t\fP +are no greater than the width of type \fBlong\fP. The +names of these programming environments can be obtained using the +\fIconfstr\fP() +function or the \fIgetconf\fP utility. +.LP +There are no defined comparison or assignment operators for the following +types: +.LP +.sp +.sp +\fBpthread_attr_t\fP +.br +.sp +.sp +\fBpthread_barrier_t\fP +.br +\fBpthread_barrierattr_t\fP +.br +.sp +.sp +\fBpthread_cond_t\fP +.br +\fBpthread_condattr_t\fP +.br +\fBpthread_mutex_t\fP +.br +\fBpthread_mutexattr_t\fP +.br +\fBpthread_rwlock_t\fP +.br +\fBpthread_rwlockattr_t\fP +.br +.sp +.sp +\fBpthread_spinlock_t\fP +.br +.sp +.sp +\fBtrace_attr_t\fP +.br +.sp +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIconfstr\fP(), the Shell and Utilities volume of IEEE\ Std\ 1003.1-2001, +\fIgetconf\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_uio.h.0p b/man0p/sys_uio.h.0p new file mode 100644 index 000000000..a27abc141 --- /dev/null +++ b/man0p/sys_uio.h.0p @@ -0,0 +1,71 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/uio.h \- definitions for vector I/O operations +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBiovec\fP structure +that includes at least the following members: +.sp +.RS +.nf + +\fBvoid *iov_base \fP Base address of a memory region for input or output. \fB +size_t iov_len \fP The size of the memory pointed to by \fIiov_base.\fP \fB +\fP +.fi +.RE +.LP +The \fI\fP header uses the \fBiovec\fP structure for scatter/gather +I/O. +.LP +The \fBssize_t\fP and \fBsize_t\fP types shall be defined as described +in \fI\fP. +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBssize_t readv(int, const struct iovec *, int); +ssize_t writev(int, const struct iovec *, int); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The implementation can put a limit on the number of scatter/gather +elements which can be processed in one call. The symbol +{IOV_MAX} defined in \fI\fP should always be used to learn +about the +limits instead of assuming a fixed value. +.SH RATIONALE +.LP +Traditionally, the maximum number of scatter/gather elements the system +can process in one call were described by the symbolic +value {UIO_MAXIOV}. In IEEE\ Std\ 1003.1-2001 this value is replaced +by the constant {IOV_MAX} which can be found in \fI\fP. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, \fIread\fP(), \fIwrite\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_un.h.0p b/man0p/sys_un.h.0p new file mode 100644 index 000000000..55bf402c7 --- /dev/null +++ b/man0p/sys_un.h.0p @@ -0,0 +1,62 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/un.h \- definitions for UNIX domain sockets +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBsockaddr_un\fP structure +that includes at least the following +members: +.sp +.RS +.nf + +\fBsa_family_t sun_family \fP Address family. \fB +char sun_path[] \fP Socket pathname. \fB +\fP +.fi +.RE +.LP +The \fBsockaddr_un\fP structure is used to store addresses for UNIX +domain sockets. Values of this type shall be cast by +applications to \fBstruct sockaddr\fP for use with socket functions. +.LP +The \fBsa_family_t\fP type shall be defined as described in \fI\fP +\&. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The size of \fIsun_path\fP has intentionally been left undefined. +This is because different implementations use different +sizes. For example, 4.3 BSD uses a size of 108, and 4.4 BSD uses a +size of 104. Since most implementations originate from BSD +versions, the size is typically in the range 92 to 108. +.LP +Applications should not assume a particular length for \fIsun_path\fP +or assume that it can hold {_POSIX_PATH_MAX} characters +(255). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIbind\fP(), \fIsocket\fP(), \fIsocketpair\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_utsname.h.0p b/man0p/sys_utsname.h.0p new file mode 100644 index 000000000..8f6955b59 --- /dev/null +++ b/man0p/sys_utsname.h.0p @@ -0,0 +1,64 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/utsname.h \- system name structure +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the structure \fButsname\fP +which shall include at least the following +members: +.sp +.RS +.nf + +\fBchar sysname[] \fP Name of this implementation of the operating system. \fB +char nodename[]\fP Name of this node within an implementation-defined \fB + \fP communications network. \fB +char release[] \fP Current release level of this implementation. \fB +char version[] \fP Current version level of this release. \fB +char machine[] \fP Name of the hardware type on which the system is running. \fB +\fP +.fi +.RE +.LP +The character arrays are of unspecified size, but the data stored +in them shall be terminated by a null byte. +.LP +The following shall be declared as a function and may also be defined +as a macro: +.sp +.RS +.nf + +\fBint uname(struct utsname *); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIuname\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/sys_wait.h.0p b/man0p/sys_wait.h.0p new file mode 100644 index 000000000..9ad940577 --- /dev/null +++ b/man0p/sys_wait.h.0p @@ -0,0 +1,122 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +sys/wait.h \- declarations for waiting +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following symbolic +constants for use with \fIwaitpid\fP(): +.TP 7 +WNOHANG +Do not hang if no status is available; return immediately. +.TP 7 +WUNTRACED +Report status of stopped child process. +.sp +.LP +The \fI\fP header shall define the following macros for +analysis of process status values: +.TP 7 +WEXITSTATUS +Return exit status. +.TP 7 +WIFCONTINUED +True if child has been continued. +.TP 7 +WIFEXITED +True if child exited normally. +.TP 7 +WIFSIGNALED +True if child exited due to uncaught signal. +.TP 7 +WIFSTOPPED +True if child is currently stopped. +.TP 7 +WSTOPSIG +Return signal number that caused process to stop. +.TP 7 +WTERMSIG +Return signal number that caused process to terminate. +.sp +.LP +The following symbolic constants shall be defined as possible values +for the \fIoptions\fP argument to \fIwaitid\fP(): +.TP 7 +WEXITED +Wait for processes that have exited. +.TP 7 +WSTOPPED +Status is returned for any child that has stopped upon receipt of +a signal. +.TP 7 +WCONTINUED +Status is returned for any child that was stopped and has been continued. +.TP 7 +WNOHANG +Return immediately if there are no children to wait for. +.TP 7 +WNOWAIT +Keep the process whose status is returned in \fIinfop\fP in a waitable +state. +.sp +.LP +The type \fBidtype_t\fP shall be defined as an enumeration type whose +possible values shall include at least the following: +P_ALL P_PID P_PGID +.LP +The \fBid_t\fP and \fBpid_t\fP types shall be defined as described +in \fI\fP . +.LP +The \fBsiginfo_t\fP type shall be defined as described in \fI\fP +\&. +.LP +The \fBrusage\fP structure shall be defined as described in \fI\fP +\&. +.LP +Inclusion of the \fI\fP header may also make visible all +symbols from \fI\fP and \fI\fP. +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBpid_t wait(int *); + +int waitid(idtype_t, id_t, siginfo_t *, int); + +pid_t waitpid(pid_t, int *, int); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , \fI\fP , +the System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIwait\fP(), +\fIwaitid\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/syslog.h.0p b/man0p/syslog.h.0p new file mode 100644 index 000000000..5eacf1391 --- /dev/null +++ b/man0p/syslog.h.0p @@ -0,0 +1,159 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +syslog.h \- definitions for system error logging +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following symbolic constants, +zero or more of which may be OR'ed together to +form the \fIlogopt\fP option of \fIopenlog\fP(): +.TP 7 +LOG_PID +Log the process ID with each message. +.TP 7 +LOG_CONS +Log to the system console on error. +.TP 7 +LOG_NDELAY +Connect to syslog daemon immediately. +.TP 7 +LOG_ODELAY +Delay open until \fIsyslog\fP() is called. +.TP 7 +LOG_NOWAIT +Do not wait for child processes. +.sp +.LP +The following symbolic constants shall be defined as possible values +of the \fIfacility\fP argument to \fIopenlog\fP(): +.TP 7 +LOG_KERN +Reserved for message generated by the system. +.TP 7 +LOG_USER +Message generated by a process. +.TP 7 +LOG_MAIL +Reserved for message generated by mail system. +.TP 7 +LOG_NEWS +Reserved for message generated by news system. +.TP 7 +LOG_UUCP +Reserved for message generated by UUCP system. +.TP 7 +LOG_DAEMON +Reserved for message generated by system daemon. +.TP 7 +LOG_AUTH +Reserved for message generated by authorization daemon. +.TP 7 +LOG_CRON +Reserved for message generated by clock daemon. +.TP 7 +LOG_LPR +Reserved for message generated by printer system. +.TP 7 +LOG_LOCAL0 +Reserved for local use. +.TP 7 +LOG_LOCAL1 +Reserved for local use. +.TP 7 +LOG_LOCAL2 +Reserved for local use. +.TP 7 +LOG_LOCAL3 +Reserved for local use. +.TP 7 +LOG_LOCAL4 +Reserved for local use. +.TP 7 +LOG_LOCAL5 +Reserved for local use. +.TP 7 +LOG_LOCAL6 +Reserved for local use. +.TP 7 +LOG_LOCAL7 +Reserved for local use. +.sp +.LP +The following shall be declared as macros for constructing the \fImaskpri\fP +argument to \fIsetlogmask\fP(). The following macros expand to an +expression of type \fBint\fP when the +argument \fIpri\fP is an expression of type \fBint\fP: +.TP 7 +LOG_MASK(\fIpri\fP) +A mask for priority \fIpri\fP. +.sp +.LP +The following constants shall be defined as possible values for the +\fIpriority\fP argument of \fIsyslog\fP(): +.TP 7 +LOG_EMERG +A panic condition was reported to all processes. +.TP 7 +LOG_ALERT +A condition that should be corrected immediately. +.TP 7 +LOG_CRIT +A critical condition. +.TP 7 +LOG_ERR +An error message. +.TP 7 +LOG_WARNING +A warning message. +.TP 7 +LOG_NOTICE +A condition requiring special handling. +.TP 7 +LOG_INFO +A general information message. +.TP 7 +LOG_DEBUG +A message useful for debugging programs. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBvoid closelog(void); +void openlog(const char *, int, int); +int setlogmask(int); +void syslog(int, const char *, ...); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIcloselog\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/tar.h.0p b/man0p/tar.h.0p new file mode 100644 index 000000000..df6de9241 --- /dev/null +++ b/man0p/tar.h.0p @@ -0,0 +1,79 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +tar.h \- extended tar definitions +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define header block definitions as +follows. +.LP +General definitions: +.TS C +center; l2 l2 l. +\fBName\fP \fBDescription\fP \fBValue\fP +TMAGIC "ustar" ustar plus null byte. +TMAGLEN 6 Length of the above. +TVERSION "00" 00 without a null byte. +TVERSLEN 2 Length of the above. +.TE +.LP +\fITypeflag\fP field definitions: +.TS C +center; l l l. +\fBName\fP \fBDescription\fP \fBValue\fP +REGTYPE '0' Regular file. +AREGTYPE '\\0' Regular file. +LNKTYPE '1' Link. +SYMTYPE '2' Symbolic link. +CHRTYPE '3' Character special. +BLKTYPE '4' Block special. +DIRTYPE '5' Directory. +FIFOTYPE '6' FIFO special. +CONTTYPE '7' Reserved. +.TE +.LP +\fIMode\fP field bit definitions (octal): +.TS C +center; l1 l1 l. +\fBName\fP \fBDescription\fP \fBValue\fP +TSUID 04000 Set UID on execution. +TSGID 02000 Set GID on execution. +TSVTX 01000 On directories, restricted deletion flag.\ \ \ +TUREAD 00400 Read by owner. +TUWRITE 00200 Write by owner special. +TUEXEC 00100 Execute/search by owner. +TGREAD 00040 Read by group. +TGWRITE 00020 Write by group. +TGEXEC 00010 Execute/search by group. +TOREAD 00004 Read by other. +TOWRITE 00002 Write by other. +TOEXEC 00001 Execute/search by other. +.TE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Shell and Utilities volume of IEEE\ Std\ 1003.1-2001, \fIpax\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/tcp.h.0p b/man0p/tcp.h.0p new file mode 100644 index 000000000..8fc84ac6e --- /dev/null +++ b/man0p/tcp.h.0p @@ -0,0 +1,47 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +netinet/tcp.h \- definitions for the Internet Transmission Control +Protocol (TCP) +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the following macro +for use as a socket option at the IPPROTO_TCP +level: +.TP 7 +TCP_NODELAY +Avoid coalescing of small segments. +.sp +.LP +The macro shall be defined in the header. The implementation need +not allow the value of the option to be set via \fIsetsockopt\fP() +or retrieved via \fIgetsockopt\fP(). +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIgetsockopt\fP(), \fIsetsockopt\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/termios.h.0p b/man0p/termios.h.0p new file mode 100644 index 000000000..6f0d2c06f --- /dev/null +++ b/man0p/termios.h.0p @@ -0,0 +1,492 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +termios.h \- define values for termios +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header contains the definitions used by the +terminal I/O interfaces (see \fIGeneral Terminal Interface\fP for +the structures and names defined). +.SS The termios Structure +.LP +The following data types shall be defined through \fBtypedef\fP: +.TP 7 +\fBcc_t\fP +Used for terminal special characters. +.TP 7 +\fBspeed_t\fP +Used for terminal baud rates. +.TP 7 +\fBtcflag_t\fP +Used for terminal modes. +.sp +.LP +The above types shall be all unsigned integer types. +.LP +The implementation shall support one or more programming environments +in which the widths of \fBcc_t\fP, \fBspeed_t\fP, and +\fBtcflag_t\fP are no greater than the width of type \fBlong\fP. The +names of these programming environments can be obtained +using the \fIconfstr\fP() function or the \fIgetconf\fP utility. +.LP +The \fBtermios\fP structure shall be defined, and shall include at +least the following members: +.sp +.RS +.nf + +\fBtcflag_t c_iflag \fP Input modes. \fB +tcflag_t c_oflag \fP Output modes. \fB +tcflag_t c_cflag \fP Control modes. \fB +tcflag_t c_lflag \fP Local modes. \fB +cc_t c_cc[NCCS] \fP Control characters. \fB +\fP +.fi +.RE +.LP +A definition shall be provided for: +.TP 7 +NCCS +Size of the array \fIc_cc\fP for control characters. +.sp +.LP +The following subscript names for the array \fIc_cc\fP shall be defined: +.TS C +center;c s l. +\fBSubscript Usage\fP \ +.T& +l l l. +\fBCanonical Mode\fP \fBNon-Canonical Mode\fP \fBDescription\fP +VEOF \ EOF character. +VEOL \ EOL character. +VERASE \ ERASE character. +VINTR VINTR INTR character. +VKILL \ KILL character. +\ VMIN MIN value. +VQUIT VQUIT QUIT character. +VSTART VSTART START character. +VSTOP VSTOP STOP character. +VSUSP VSUSP SUSP character. +\ VTIME TIME value. +.TE +.LP +The subscript values shall be unique, except that the VMIN and VTIME +subscripts may have the same values as the VEOF and VEOL +subscripts, respectively. +.LP +The following flags shall be provided. +.SS Input Modes +.LP +The \fIc_iflag\fP field describes the basic terminal input control: +.TP 7 +BRKINT +Signal interrupt on break. +.TP 7 +ICRNL +Map CR to NL on input. +.TP 7 +IGNBRK +Ignore break condition. +.TP 7 +IGNCR +Ignore CR. +.TP 7 +IGNPAR +Ignore characters with parity errors. +.TP 7 +INLCR +Map NL to CR on input. +.TP 7 +INPCK +Enable input parity check. +.TP 7 +ISTRIP +Strip character. +.TP 7 +IXANY +Enable any character to restart output. +.TP 7 +IXOFF +Enable start/stop input control. +.TP 7 +IXON +Enable start/stop output control. +.TP 7 +PARMRK +Mark parity errors. +.sp +.SS Output Modes +.LP +The \fIc_oflag\fP field specifies the system treatment of output: +.TP 7 +OPOST +Post-process output. +.TP 7 +ONLCR +Map NL to CR-NL on output. +.TP 7 +OCRNL +Map CR to NL on output. +.TP 7 +ONOCR +No CR output at column 0. +.TP 7 +ONLRET +NL performs CR function. +.TP 7 +OFILL +Use fill characters for delay. +.TP 7 +NLDLY +Select newline delays: +.TP 7 +NL0 +.RS +Newline type 0. +.RE +.TP 7 +NL1 +.RS +Newline type 1. +.RE +.sp +.TP 7 +CRDLY +Select carriage-return delays: +.TP 7 +CR0 +.RS +Carriage-return delay type 0. +.RE +.TP 7 +CR1 +.RS +Carriage-return delay type 1. +.RE +.TP 7 +CR2 +.RS +Carriage-return delay type 2. +.RE +.TP 7 +CR3 +.RS +Carriage-return delay type 3. +.RE +.sp +.TP 7 +TABDLY +Select horizontal-tab delays: +.TP 7 +TAB0 +.RS +Horizontal-tab delay type 0. +.RE +.TP 7 +TAB1 +.RS +Horizontal-tab delay type 1. +.RE +.TP 7 +TAB2 +.RS +Horizontal-tab delay type 2. +.RE +.TP 7 +TAB3 +.RS +Expand tabs to spaces. +.RE +.sp +.TP 7 +BSDLY +Select backspace delays: +.TP 7 +BS0 +.RS +Backspace-delay type 0. +.RE +.TP 7 +BS1 +.RS +Backspace-delay type 1. +.RE +.sp +.TP 7 +VTDLY +Select vertical-tab delays: +.TP 7 +VT0 +.RS +Vertical-tab delay type 0. +.RE +.TP 7 +VT1 +.RS +Vertical-tab delay type 1. +.RE +.sp +.TP 7 +FFDLY +Select form-feed delays: +.TP 7 +FF0 +.RS +Form-feed delay type 0. +.RE +.TP 7 +FF1 +.RS +Form-feed delay type 1. +.RE +.sp +.sp +.SS Baud Rate Selection +.LP +The input and output baud rates are stored in the \fBtermios\fP structure. +These are the valid values for objects of type +\fBspeed_t\fP. The following values shall be defined, but not all +baud rates need be supported by the underlying hardware. +.TP 7 +B0 +Hang up +.TP 7 +B50 +50 baud +.TP 7 +B75 +75 baud +.TP 7 +B110 +110 baud +.TP 7 +B134 +134.5 baud +.TP 7 +B150 +150 baud +.TP 7 +B200 +200 baud +.TP 7 +B300 +300 baud +.TP 7 +B600 +600 baud +.TP 7 +B1200 +1200 baud +.TP 7 +B1800 +1800 baud +.TP 7 +B2400 +2400 baud +.TP 7 +B4800 +4800 baud +.TP 7 +B9600 +9600 baud +.TP 7 +B19200 +19200 baud +.TP 7 +B38400 +38400 baud +.sp +.SS Control Modes +.LP +The \fIc_cflag\fP field describes the hardware control of the terminal; +not all values specified are required to be supported +by the underlying hardware: +.TP 7 +CSIZE +Character size: +.TP 7 +CS5 +.RS +5 bits +.RE +.TP 7 +CS6 +.RS +6 bits +.RE +.TP 7 +CS7 +.RS +7 bits +.RE +.TP 7 +CS8 +.RS +8 bits +.RE +.sp +.TP 7 +CSTOPB +Send two stop bits, else one. +.TP 7 +CREAD +Enable receiver. +.TP 7 +PARENB +Parity enable. +.TP 7 +PARODD +Odd parity, else even. +.TP 7 +HUPCL +Hang up on last close. +.TP 7 +CLOCAL +Ignore modem status lines. +.sp +.LP +The implementation shall support the functionality associated with +the symbols CS7, CS8, CSTOPB, PARODD, and PARENB. +.SS Local Modes +.LP +The \fIc_lflag\fP field of the argument structure is used to control +various terminal functions: +.TP 7 +ECHO +Enable echo. +.TP 7 +ECHOE +Echo erase character as error-correcting backspace. +.TP 7 +ECHOK +Echo KILL. +.TP 7 +ECHONL +Echo NL. +.TP 7 +ICANON +Canonical input (erase and kill processing). +.TP 7 +IEXTEN +Enable extended input character processing. +.TP 7 +ISIG +Enable signals. +.TP 7 +NOFLSH +Disable flush after interrupt or quit. +.TP 7 +TOSTOP +Send SIGTTOU for background output. +.sp +.SS Attribute Selection +.LP +The following symbolic constants for use with \fItcsetattr\fP() are +defined: +.TP 7 +TCSANOW +Change attributes immediately. +.TP 7 +TCSADRAIN +Change attributes when output has drained. +.TP 7 +TCSAFLUSH +Change attributes when output has drained; also flush pending input. +.sp +.SS Line Control +.LP +The following symbolic constants for use with \fItcflush\fP() shall +be defined: +.TP 7 +TCIFLUSH +Flush pending input. +.TP 7 +TCIOFLUSH +Flush both pending input and untransmitted output. +.TP 7 +TCOFLUSH +Flush untransmitted output. +.sp +.LP +The following symbolic constants for use with \fItcflow\fP() shall +be defined: +.TP 7 +TCIOFF +Transmit a STOP character, intended to suspend input data. +.TP 7 +TCION +Transmit a START character, intended to restart input data. +.TP 7 +TCOOFF +Suspend output. +.TP 7 +TCOON +Restart output. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBspeed_t cfgetispeed(const struct termios *); +speed_t cfgetospeed(const struct termios *); +int cfsetispeed(struct termios *, speed_t); +int cfsetospeed(struct termios *, speed_t); +int tcdrain(int); +int tcflow(int, int); +int tcflush(int, int); +int tcgetattr(int, struct termios *); + +pid_t tcgetsid(int); + +int tcsendbreak(int, int); +int tcsetattr(int, int, const struct termios *); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The following names are reserved for XSI-conformant systems to use +as an extension to the above; therefore strictly conforming +applications shall not use them: +.TS C +center; l l l. +CBAUD EXTB VDSUSP +DEFECHO FLUSHO VLNEXT +ECHOCTL LOBLK VREPRINT +ECHOKE PENDIN VSTATUS +ECHOPRT SWTCH VWERASE +EXTA VDISCARD \ +.TE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIcfgetispeed\fP(), +\fIcfgetospeed\fP(), \fIcfsetispeed\fP(), \fIcfsetospeed\fP(), \fIconfstr\fP(), +\fItcdrain\fP(), \fItcflow\fP(), \fItcflush\fP(), \fItcgetattr\fP(), +\fItcgetsid\fP(), \fItcsendbreak\fP(), \fItcsetattr\fP(), the Shell +and Utilities volume of IEEE\ Std\ 1003.1-2001, \fIgetconf\fP, \fIGeneral +Terminal Interface\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/tgmath.h.0p b/man0p/tgmath.h.0p new file mode 100644 index 000000000..e2c7083ae --- /dev/null +++ b/man0p/tgmath.h.0p @@ -0,0 +1,345 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +tgmath.h \- type-generic macros +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall include the headers \fI\fP +and \fI\fP and shall define several type-generic macros. +.LP +Of the functions contained within the \fI\fP and \fI\fP +headers without an \fIf\fP ( \fBfloat\fP) or \fIl\fP ( \fBlong +double\fP) suffix, several have one or more parameters whose corresponding +real type is \fBdouble\fP. For each such function, +except \fImodf\fP(), there shall be a corresponding type-generic macro. +The parameters whose +corresponding real type is \fBdouble\fP in the function synopsis are +generic parameters. Use of the macro invokes a function whose +corresponding real type and type domain are determined by the arguments +for the generic parameters. +.LP +Use of the macro invokes a function whose generic parameters have +the corresponding real type determined as follows: +.IP " *" 3 +First, if any argument for generic parameters has type \fBlong double\fP, +the type determined is \fBlong double\fP. +.LP +.IP " *" 3 +Otherwise, if any argument for generic parameters has type \fBdouble\fP +or is of integer type, the type determined is +\fBdouble\fP. +.LP +.IP " *" 3 +Otherwise, the type determined is \fBfloat\fP. +.LP +.LP +For each unsuffixed function in the \fI\fP header for which +there is a +function in the \fI\fP header with the same name except +for a \fIc\fP +prefix, the corresponding type-generic macro (for both functions) +has the same name as the function in the \fI\fP header. The +corresponding type-generic macro for \fIfabs\fP() and \fIcabs\fP() +is \fIfabs\fP(). +.TS C +center; l l l. +\fB\fP \fB\fP \fBType-Generic\fP +\fBFunction\fP \fBFunction\fP \fBMacro\fP +\fIacos\fP() \fIcacos\fP() \fIacos\fP() +\fIasin\fP() \fIcasin\fP() \fIasin\fP() +\fIatan\fP() \fIcatan\fP() \fIatan\fP() +\fIacosh\fP() \fIcacosh\fP() \fIacosh\fP() +\fIasinh\fP() \fIcasinh\fP() \fIasinh\fP() +\fIatanh\fP() \fIcatanh\fP() \fIatanh\fP() +\fIcos\fP() \fIccos\fP() \fIcos\fP() +\fIsin\fP() \fIcsin\fP() \fIsin\fP() +\fItan\fP() \fIctan\fP() \fItan\fP() +\fIcosh\fP() \fIccosh\fP() \fIcosh\fP() +\fIsinh\fP() \fIcsinh\fP() \fIsinh\fP() +\fItanh\fP() \fIctanh\fP() \fItanh\fP() +\fIexp\fP() \fIcexp\fP() \fIexp\fP() +\fIlog\fP() \fIclog\fP() \fIlog\fP() +\fIpow\fP() \fIcpow\fP() \fIpow\fP() +\fIsqrt\fP() \fIcsqrt\fP() \fIsqrt\fP() +\fIfabs\fP() \fIcabs\fP() \fIfabs\fP() +.TE +.LP +If at least one argument for a generic parameter is complex, then +use of the macro invokes a complex function; otherwise, use of +the macro invokes a real function. +.LP +For each unsuffixed function in the \fI\fP header without +a +\fIc\fP-prefixed counterpart in the \fI\fP header, the +corresponding +type-generic macro has the same name as the function. These type-generic +macros are: +.TS C +center; lw(19) lw(19) lw(19) lw(19). +T{ +.br +\fIatan2\fP() +.br +\fIcbrt\fP() +.br +\fIceil\fP() +.br +\fIcopysign\fP() +.br +\fIerf\fP() +.br +\fIerfc\fP() +.br +\fIexp2\fP() +.br +\fIexpm1\fP() +.br +\fIfdim\fP() +.br +\fIfloor\fP() +.br +\ +T} T{ +.br +\fIfma\fP() +.br +\fIfmax\fP() +.br +\fIfmin\fP() +.br +\fIfmod\fP() +.br +\fIfrexp\fP() +.br +\fIhypot\fP() +.br +\fIilogb\fP() +.br +\fIldexp\fP() +.br +\fIlgamma\fP() +.br +\fIllrint\fP() +.br +\ +T} T{ +.br +\fIllround\fP() +.br +\fIlog10\fP() +.br +\fIlog1p\fP() +.br +\fIlog2\fP() +.br +\fIlogb\fP() +.br +\fIlrint\fP() +.br +\fIlround\fP() +.br +\fInearbyint\fP() +.br +\fInextafter\fP() +.br +\fInexttoward\fP() +.br +\ +T} T{ +.br +\fIremainder\fP() +.br +\fIremquo\fP() +.br +\fIrint\fP() +.br +\fIround\fP() +.br +\fIscalbn\fP() +.br +\fIscalbln\fP() +.br +\fItgamma\fP() +.br +\fItrunc\fP() +.br +\ +T} +.TE +.LP +If all arguments for generic parameters are real, then use of the +macro invokes a real function; otherwise, use of the macro +results in undefined behavior. +.LP +For each unsuffixed function in the \fI\fP header that +is not a +\fIc\fP-prefixed counterpart to a function in the \fI\fP header, +the +corresponding type-generic macro has the same name as the function. +These type-generic macros are: +.sp +.RS +.nf + +\fIcarg\fP() +\fIcimag\fP() +\fIconj\fP() +\fIcproj\fP() +\fIcreal\fP() +.fi +.RE +.LP +Use of the macro with any real or complex argument invokes a complex +function. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +With the declarations: +.sp +.RS +.nf + +\fB#include +int n; +float f; +double d; +long double ld; +float complex fc; +double complex dc; +long double complex ldc; +\fP +.fi +.RE +.LP +functions invoked by use of type-generic macros are shown in the following +table: +.TS C +center; l2 l. +\fBMacro\fP \fBUse Invokes\fP +\fIexp\fP(\fIn\fP) \fIexp\fP(\fIn\fP), the function +\fIacosh\fP(\fIf\fP) \fIacoshf\fP(\fIf\fP) +\fIsin\fP(\fId\fP) \fIsin\fP(\fId\fP), the function +\fIatan\fP(\fIld\fP) \fIatanl\fP(\fIld\fP) +\fIlog\fP(\fIfc\fP) \fIclogf\fP(\fIfc\fP) +\fIsqrt\fP(\fIdc\fP) \fIcsqrt\fP(\fIdc\fP) +\fIpow\fP(\fIldc,f\fP) \fIcpowl\fP(\fIldc, f\fP) +\fIremainder\fP(\fIn,n\fP) \fIremainder\fP(\fIn, n\fP), the function +\fInextafter\fP(\fId,f\fP) \fInextafter\fP(\fId, f\fP), the function +\fInexttoward\fP(\fIf,ld\fP) \fInexttowardf\fP(\fIf, ld\fP) +\fIcopysign\fP(\fIn,ld\fP) \fIcopysignl\fP(\fIn, ld\fP) +\fIceil\fP(\fIfc\fP) Undefined behavior +\fIrint\fP(\fIdc\fP) Undefined behavior +\fIfmax\fP(\fIldc,ld\fP) Undefined behavior +\fIcarg\fP(\fIn\fP) \fIcarg\fP(\fIn\fP), the function +\fIcproj\fP(\fIf\fP) \fIcprojf\fP(\fIf\fP) +\fIcreal\fP(\fId\fP) \fIcreal\fP(\fId\fP), the function +\fIcimag\fP(\fIld\fP) \fIcimagl\fP(\fIld\fP) +\fIcabs\fP(\fIfc\fP) \fIcabsf\fP(\fIfc\fP) +\fIcarg\fP(\fIdc\fP) \fIcarg\fP(\fIdc\fP), the function +\fIcproj\fP(\fIldc\fP) \fIcprojl\fP(\fIldc\fP) +.TE +.SH RATIONALE +.LP +Type-generic macros allow calling a function whose type is determined +by the argument type, as is the case for C operators such +as \fB'+'\fP and \fB'*'\fP . For example, with a type-generic \fIcos\fP() +macro, the +expression \fIcos\fP(( \fBfloat\fP) \fIx\fP) will have type \fBfloat\fP. +This feature enables writing more portably efficient +code and alleviates need for awkward casting and suffixing in the +process of porting or adjusting precision. Generic math functions +are a widely appreciated feature of Fortran. +.LP +The only arguments that affect the type resolution are the arguments +corresponding to the parameters that have type +\fBdouble\fP in the synopsis. Hence the type of a type-generic call +to \fInexttoward\fP(), whose second parameter is \fBlong double\fP +in the synopsis, is determined +solely by the type of the first argument. +.LP +The term "type-generic" was chosen over the proposed alternatives +of intrinsic and overloading. The term is more specific than +intrinsic, which already is widely used with a more general meaning, +and reflects a closer match to Fortran's generic functions +than to C++ overloading. +.LP +The macros are placed in their own header in order not to silently +break old programs that include the \fI\fP header; for example, +with: +.sp +.RS +.nf + +\fBprintf ("%e", sin(x)) +\fP +.fi +.RE +.LP +\fImodf\fP( \fBdouble\fP, \fBdouble *\fP) is excluded because no way +was seen to make it safe without complicating the type +resolution. +.LP +The implementation might, as an extension, endow appropriate ones +of the macros that IEEE\ Std\ 1003.1-2001 specifies +only for real arguments with the ability to invoke the complex functions. +.LP +IEEE\ Std\ 1003.1-2001 does not prescribe any particular implementation +mechanism for generic macros. It could be +implemented simply with built-in macros. The generic macro for \fIsqrt\fP(), +for example, +could be implemented with: +.sp +.RS +.nf + +\fB#undef sqrt +#define sqrt(x) __BUILTIN_GENERIC_sqrt(x) +\fP +.fi +.RE +.LP +Generic macros are designed for a useful level of consistency with +C++ overloaded math functions. +.LP +The great majority of existing C programs are expected to be unaffected +when the \fI\fP header is included +instead of the \fI\fP or \fI\fP headers. Generic +macros are similar to the ISO/IEC\ 9899:1999 +standard library masking macros, though the semantic types of return +values differ. +.LP +The ability to overload on integer as well as floating types would +have been useful for some functions; for example, \fIcopysign\fP(). +Overloading with different numbers of arguments would have allowed +reusing +names; for example, \fIremainder\fP() for \fIremquo\fP(). However, +these facilities would have complicated the specification; and their +natural consistent use, such as for a floating \fIabs\fP() or a two-argument +\fIatan\fP(), would have introduced further inconsistencies with the +ISO/IEC\ 9899:1999 standard +for insufficient benefit. +.LP +The ISO\ C standard in no way limits the implementation's options +for efficiency, including inlining library functions. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, \fIcabs\fP(), \fIfabs\fP(), \fImodf\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/time.h.0p b/man0p/time.h.0p new file mode 100644 index 000000000..23ec48204 --- /dev/null +++ b/man0p/time.h.0p @@ -0,0 +1,244 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +time.h \- time types +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +Some of the functionality described on this reference page extends +the ISO\ C standard. Applications shall define +the appropriate feature test macro (see the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, Section 2.2, The Compilation Environment) +to enable the visibility of these symbols in this +header. +.LP +The \fI\fP header shall declare the structure \fBtm\fP, which +shall include at least the following members: +.sp +.RS +.nf + +\fBint tm_sec \fP Seconds [0,60]. \fB +int tm_min \fP Minutes [0,59]. \fB +int tm_hour \fP Hour [0,23]. \fB +int tm_mday \fP Day of month [1,31]. \fB +int tm_mon \fP Month of year [0,11]. \fB +int tm_year \fP Years since 1900. \fB +int tm_wday \fP Day of week [0,6] (Sunday =0). \fB +int tm_yday \fP Day of year [0,365]. \fB +int tm_isdst\fP Daylight Savings flag. \fB +\fP +.fi +.RE +.LP +The value of \fItm_isdst\fP shall be positive if Daylight Savings +Time is in effect, 0 if Daylight Savings Time is not in +effect, and negative if the information is not available. +.LP +The \fI\fP header shall define the following symbolic names: +.TP 7 +NULL +Null pointer constant. +.TP 7 +CLOCKS_PER_SEC +A number used to convert the value returned by the \fIclock\fP() function +into +seconds. +.TP 7 +CLOCK_PROCESS_CPUTIME_ID +.sp +The identifier of the CPU-time clock associated with the process making +a \fIclock\fP() or +\fItimer*\fP() function call. +.TP 7 +CLOCK_THREAD_CPUTIME_ID +.sp +The identifier of the CPU-time clock associated with the thread making +a \fIclock\fP() or \fItimer*\fP() function call. +.sp +.LP +The \fI\fP header shall declare the structure \fBtimespec\fP, +which has at least the following members: +.sp +.RS +.nf + +\fBtime_t tv_sec \fP Seconds. \fB +long tv_nsec \fP Nanoseconds. \fB +\fP +.fi +.RE +.LP +The \fI\fP header shall also declare the \fBitimerspec\fP +structure, which has at least the following +members: +.sp +.RS +.nf + +\fBstruct timespec it_interval \fP Timer period. \fB +struct timespec it_value \fP Timer expiration. \fB +\fP +.fi +.RE +.LP +The following manifest constants shall be defined: +.TP 7 +CLOCK_REALTIME +The identifier of the system-wide realtime clock. +.TP 7 +TIMER_ABSTIME +Flag indicating time is absolute. For functions taking timer objects, +this refers to the clock associated with the timer. +.TP 7 +CLOCK_MONOTONIC +.sp +The identifier for the system-wide monotonic clock, which is defined +as a clock whose value cannot be set via \fIclock_settime\fP() and +which cannot have backward clock jumps. The maximum possible clock +jump shall be implementation-defined. +.sp +.LP +The \fBclock_t\fP, \fBsize_t\fP, \fBtime_t\fP, \fBclockid_t\fP, +and \fBtimer_t\fP types shall be defined as described in \fI\fP +\&. +.LP +Although the value of CLOCKS_PER_SEC is required to be 1 million on +all XSI-conformant systems, it may be variable on other +systems, and it should not be assumed that CLOCKS_PER_SEC is a compile-time +constant. +.LP +The \fI\fP header shall provide a declaration for \fIgetdate_err\fP. +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBchar *asctime(const struct tm *); + +char *asctime_r(const struct tm *restrict, char *restrict); + +clock_t clock(void); + +int clock_getcpuclockid(pid_t, clockid_t *); + + +int clock_getres(clockid_t, struct timespec *); +int clock_gettime(clockid_t, struct timespec *); + + +int clock_nanosleep(clockid_t, int, const struct timespec *, + struct timespec *); + + +int clock_settime(clockid_t, const struct timespec *); + +char *ctime(const time_t *); + +char *ctime_r(const time_t *, char *); + +double difftime(time_t, time_t); + +struct tm *getdate(const char *); + +struct tm *gmtime(const time_t *); + +struct tm *gmtime_r(const time_t *restrict, struct tm *restrict); + +struct tm *localtime(const time_t *); + +struct tm *localtime_r(const time_t *restrict, struct tm *restrict); + +time_t mktime(struct tm *); + +int nanosleep(const struct timespec *, struct timespec *); + +size_t strftime(char *restrict, size_t, const char *restrict, + const struct tm *restrict); + +char *strptime(const char *restrict, const char *restrict, + struct tm *restrict); + +time_t time(time_t *); + +int timer_create(clockid_t, struct sigevent *restrict, + timer_t *restrict); +int timer_delete(timer_t); +int timer_gettime(timer_t, struct itimerspec *); +int timer_getoverrun(timer_t); +int timer_settime(timer_t, int, const struct itimerspec *restrict, + struct itimerspec *restrict); + + +void tzset(void); + +\fP +.fi +.RE +.sp +.LP +The following shall be declared as variables: +.sp +.RS +.nf + +\fB +extern int daylight; +extern long timezone; + + +extern char *tzname[]; + +\fP +.fi +.RE +.LP +Inclusion of the \fI\fP header may make visible all symbols +from the \fI\fP header. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The range [0,60] for \fItm_sec\fP allows for the occasional leap second. +.LP +\fItm_year\fP is a signed value; therefore, years before 1900 may +be represented. +.LP +To obtain the number of clock ticks per second returned by the \fItimes\fP() +function, +applications should call \fIsysconf\fP(_SC_CLK_TCK). +.SH RATIONALE +.LP +The range [0,60] seconds allows for positive or negative leap seconds. +The formal definition of UTC does not permit double leap +seconds, so all mention of double leap seconds has been removed, and +the range shortened from the former [0,61] seconds seen in +previous versions of POSIX. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIasctime\fP(), \fIclock\fP(), +\fIclock_getcpuclockid\fP(), \fIclock_getres\fP(), \fIclock_nanosleep\fP(), +\fIctime\fP(), \fIdifftime\fP(), \fIgetdate\fP(), \fIgmtime\fP(), +\fIlocaltime\fP(), \fImktime\fP(), \fInanosleep\fP(), \fIstrftime\fP(), +\fIstrptime\fP(), \fIsysconf\fP(), \fItime\fP(), \fItimer_create\fP(), +\fItimer_delete\fP(), \fItimer_getoverrun\fP(), \fItzname\fP, \fItzset\fP(), +\fIutime\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/timeb.h.0p b/man0p/timeb.h.0p new file mode 100644 index 000000000..a8f53e551 --- /dev/null +++ b/man0p/timeb.h.0p @@ -0,0 +1 @@ +.so man0p/sys_timeb.h.0p diff --git a/man0p/times.h.0p b/man0p/times.h.0p new file mode 100644 index 000000000..d7e1e3cc1 --- /dev/null +++ b/man0p/times.h.0p @@ -0,0 +1 @@ +.so man0p/sys_times.h.0p diff --git a/man0p/trace.h.0p b/man0p/trace.h.0p new file mode 100644 index 000000000..9b9e9babb --- /dev/null +++ b/man0p/trace.h.0p @@ -0,0 +1,293 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +trace.h \- tracing +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBposix_trace_event_info\fP +structure that includes at least the following +members: +.sp +.RS +.nf + +\fBtrace_event_id_t posix_event_id +pid_t posix_pid +void *posix_prog_address +int posix_truncation_status +struct timespec posix_timestamp + +pthread_t posix_thread_id + +\fP +.fi +.RE +.LP +The \fI\fP header shall define the \fBposix_trace_status_info\fP +structure that includes at least the following +members: +.sp +.RS +.nf + +\fBint posix_stream_status +int posix_stream_full_status +int posix_stream_overrun_status + +int posix_stream_flush_status +int posix_stream_flush_error +int posix_log_overrun_status +int posix_log_full_status + +\fP +.fi +.RE +.LP +The \fI\fP header shall define the following symbols: +.LP +.sp +POSIX_TRACE_ALL_EVENTS +.br +.sp +POSIX_TRACE_APPEND +.br +.sp +.sp +POSIX_TRACE_CLOSE_FOR_CHILD +.br +.sp +.sp +POSIX_TRACE_FILTER +.br +.sp +.sp +POSIX_TRACE_FLUSH +.br +POSIX_TRACE_FLUSH_START +.br +POSIX_TRACE_FLUSH_STOP +.br +POSIX_TRACE_FLUSHING +.br +.sp +POSIX_TRACE_FULL +.br +POSIX_TRACE_LOOP +.br +POSIX_TRACE_NO_OVERRUN +.br +.sp +POSIX_TRACE_NOT_FLUSHING +.br +.sp +POSIX_TRACE_NOT_FULL +.br +.sp +POSIX_TRACE_INHERITED +.br +.sp +POSIX_TRACE_NOT_TRUNCATED +.br +POSIX_TRACE_OVERFLOW +.br +POSIX_TRACE_OVERRUN +.br +POSIX_TRACE_RESUME +.br +POSIX_TRACE_RUNNING +.br +POSIX_TRACE_START +.br +POSIX_TRACE_STOP +.br +POSIX_TRACE_SUSPENDED +.br +POSIX_TRACE_SYSTEM_EVENTS +.br +POSIX_TRACE_TRUNCATED_READ +.br +POSIX_TRACE_TRUNCATED_RECORD +.br +POSIX_TRACE_UNNAMED_USER_EVENT +.br +POSIX_TRACE_UNTIL_FULL +.br +POSIX_TRACE_WOPID_EVENTS +.br +.LP +The following types shall be defined as described in \fI\fP +: +.LP +.sp +\fBtrace_attr_t\fP +.br +\fBtrace_id_t\fP +.br +\fBtrace_event_id_t\fP +.br +.sp +\fBtrace_event_set_t\fP +.br +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint posix_trace_attr_destroy(trace_attr_t *); +int posix_trace_attr_getclockres(const trace_attr_t *, + struct timespec *); +int posix_trace_attr_getcreatetime(const trace_attr_t *, + struct timespec *); +int posix_trace_attr_getgenversion(const trace_attr_t *, char *); + +int posix_trace_attr_getinherited(const trace_attr_t *restrict, + int *restrict); + + +int posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict, + int *restrict); +int posix_trace_attr_getlogsize(const trace_attr_t *restrict, + size_t *restrict); + +int posix_trace_attr_getmaxdatasize(const trace_attr_t *restrict, + size_t *restrict); +int posix_trace_attr_getmaxsystemeventsize(const trace_attr_t *restrict, + size_t *restrict); +int posix_trace_attr_getmaxusereventsize(const trace_attr_t *restrict, + size_t, size_t *restrict); +int posix_trace_attr_getname(const trace_attr_t *, char *); +int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *restrict, + int *restrict); +int posix_trace_attr_getstreamsize(const trace_attr_t *restrict, + size_t *restrict); +int posix_trace_attr_init(trace_attr_t *); + +int posix_trace_attr_setinherited(trace_attr_t *, int); + + +int posix_trace_attr_setlogfullpolicy(trace_attr_t *, int); +int posix_trace_attr_setlogsize(trace_attr_t *, size_t); + +int posix_trace_attr_setmaxdatasize(trace_attr_t *, size_t); +int posix_trace_attr_setname(trace_attr_t *, const char *); +int posix_trace_attr_setstreamsize(trace_attr_t *, size_t); +int posix_trace_attr_setstreamfullpolicy(trace_attr_t *, int); +int posix_trace_clear(trace_id_t); + +int posix_trace_close(trace_id_t); + +int posix_trace_create(pid_t, const trace_attr_t *restrict, + trace_id_t *restrict); + +int posix_trace_create_withlog(pid_t, const trace_attr_t *restrict, + int, trace_id_t *restrict); + +void posix_trace_event(trace_event_id_t, const void *restrict, size_t); +int posix_trace_eventid_equal(trace_id_t, trace_event_id_t, + trace_event_id_t); +int posix_trace_eventid_get_name(trace_id_t, trace_event_id_t, char *); +int posix_trace_eventid_open(const char *restrict, + trace_event_id_t *restrict); + +int posix_trace_eventset_add(trace_event_id_t, trace_event_set_t *); +int posix_trace_eventset_del(trace_event_id_t, trace_event_set_t *); +int posix_trace_eventset_empty(trace_event_set_t *); +int posix_trace_eventset_fill(trace_event_set_t *, int); +int posix_trace_eventset_ismember(trace_event_id_t, + const trace_event_set_t *restrict, int *restrict); + +int posix_trace_eventtypelist_getnext_id(trace_id_t, + trace_event_id_t *restrict, int *restrict); +int posix_trace_eventtypelist_rewind(trace_id_t); + +int posix_trace_flush(trace_id_t); + +int posix_trace_get_attr(trace_id_t, trace_attr_t *); + +int posix_trace_get_filter(trace_id_t, trace_event_set_t *); + +int posix_trace_get_status(trace_id_t, + struct posix_trace_status_info *); +int posix_trace_getnext_event(trace_id_t, + struct posix_trace_event_info *restrict , void *restrict, + size_t, size_t *restrict, int *restrict); + +int posix_trace_open(int, trace_id_t *); +int posix_trace_rewind(trace_id_t); + + +int posix_trace_set_filter(trace_id_t, const trace_event_set_t *, int); + +int posix_trace_shutdown(trace_id_t); +int posix_trace_start(trace_id_t); +int posix_trace_stop(trace_id_t); + +int posix_trace_timedgetnext_event(trace_id_t, + struct posix_trace_event_info *restrict, void *restrict, + size_t, size_t *restrict, int *restrict, + const struct timespec *restrict); + + +int posix_trace_trid_eventid_open(trace_id_t, const char *restrict, + trace_event_id_t *restrict); + +int posix_trace_trygetnext_event(trace_id_t, + struct posix_trace_event_info *restrict, void *restrict, size_t, + size_t *restrict, int *restrict); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +Section 2.11, Tracing, \fIposix_trace_attr_destroy\fP(), \fIposix_trace_attr_getclockres\fP(), +\fIposix_trace_attr_getcreatetime\fP(), \fIposix_trace_attr_getgenversion\fP(), +\fIposix_trace_attr_getinherited\fP(), \fIposix_trace_attr_getlogfullpolicy\fP(), +\fIposix_trace_attr_getlogsize\fP(), \fIposix_trace_attr_getmaxdatasize\fP(), +\fIposix_trace_attr_getmaxsystemeventsize\fP(), \fIposix_trace_attr_getmaxusereventsize\fP(), +\fIposix_trace_attr_getname\fP(), \fIposix_trace_attr_getstreamfullpolicy\fP(), +\fIposix_trace_attr_getstreamsize\fP(), \fIposix_trace_attr_init\fP(), +\fIposix_trace_attr_setinherited\fP(), \fIposix_trace_attr_setlogfullpolicy\fP(), +\fIposix_trace_attr_setlogsize\fP(), \fIposix_trace_attr_setmaxdatasize\fP(), +\fIposix_trace_attr_setname\fP(), \fIposix_trace_attr_setstreamsize\fP(), +\fIposix_trace_attr_setstreamfullpolicy\fP(), \fIposix_trace_clear\fP(), +\fIposix_trace_close\fP(), \fIposix_trace_create\fP(), \fIposix_trace_create_withlog\fP(), +\fIposix_trace_event\fP(), \fIposix_trace_eventid_equal\fP(), \fIposix_trace_eventid_get_name\fP(), +\fIposix_trace_eventid_open\fP(), \fIposix_trace_eventtypelist_getnext_id\fP(), +\fIposix_trace_eventtypelist_rewind\fP(), \fIposix_trace_eventset_add\fP(), +\fIposix_trace_eventset_del\fP(), \fIposix_trace_eventset_empty\fP(), +\fIposix_trace_eventset_fill\fP(), \fIposix_trace_eventset_ismember\fP(), +\fIposix_trace_flush\fP(), \fIposix_trace_get_attr\fP(), \fIposix_trace_get_filter\fP(), +\fIposix_trace_get_status\fP(), \fIposix_trace_getnext_event\fP(), +\fIposix_trace_open\fP(), \fIposix_trace_rewind\fP(), \fIposix_trace_set_filter\fP(), +\fIposix_trace_shutdown\fP(), \fIposix_trace_start\fP(), \fIposix_trace_stop\fP(), +\fIposix_trace_timedgetnext_event\fP(), \fIposix_trace_trid_eventid_open\fP(), +\fIposix_trace_trygetnext_event\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/types.h.0p b/man0p/types.h.0p new file mode 100644 index 000000000..b33c1ff88 --- /dev/null +++ b/man0p/types.h.0p @@ -0,0 +1 @@ +.so man0p/sys_types.h.0p diff --git a/man0p/ucontext.h.0p b/man0p/ucontext.h.0p new file mode 100644 index 000000000..58ad56b8f --- /dev/null +++ b/man0p/ucontext.h.0p @@ -0,0 +1,73 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +ucontext.h \- user context +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fBmcontext_t\fP type +through \fBtypedef\fP. +.LP +The \fI\fP header shall define the \fBucontext_t\fP type +as a structure that shall include at least the +following members: +.sp +.RS +.nf + +\fBucontext_t *uc_link \fP Pointer to the context that is resumed \fB + \fP when this context returns. \fB +sigset_t uc_sigmask \fP The set of signals that are blocked when this \fB + \fP context is active. \fB +stack_t uc_stack \fP The stack used by this context. \fB +mcontext_t uc_mcontext\fP A machine-specific representation of the saved \fB + \fP context. \fB +\fP +.fi +.RE +.LP +The types \fBsigset_t\fP and \fBstack_t\fP shall be defined as in +\fI\fP . +.LP +The following shall be declared as functions and may also be defined +as macros, Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint getcontext(ucontext_t *); +int setcontext(const ucontext_t *); +void makecontext(ucontext_t *, void (*)(void), int, ...); +int swapcontext(ucontext_t *restrict, const ucontext_t *restrict); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIgetcontext\fP(), \fImakecontext\fP(), \fIsigaction\fP(), \fIsigprocmask\fP(), +\fIsigaltstack\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/uio.h.0p b/man0p/uio.h.0p new file mode 100644 index 000000000..78a3ab886 --- /dev/null +++ b/man0p/uio.h.0p @@ -0,0 +1 @@ +.so man0p/sys_uio.h.0p diff --git a/man0p/ulimit.h.0p b/man0p/ulimit.h.0p new file mode 100644 index 000000000..cca8dfecd --- /dev/null +++ b/man0p/ulimit.h.0p @@ -0,0 +1,56 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +ulimit.h \- ulimit commands +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the symbolic constants used +by the \fIulimit\fP() function. +.LP +Symbolic constants: +.TP 7 +UL_GETFSIZE +Get maximum file size. +.TP 7 +UL_SETFSIZE +Set maximum file size. +.sp +.LP +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS +.nf + +\fBlong ulimit(int, ...); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIulimit\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/un.h.0p b/man0p/un.h.0p new file mode 100644 index 000000000..f2165645a --- /dev/null +++ b/man0p/un.h.0p @@ -0,0 +1 @@ +.so man0p/sys_un.h.0p diff --git a/man0p/unistd.h.0p b/man0p/unistd.h.0p new file mode 100644 index 000000000..dfda92426 --- /dev/null +++ b/man0p/unistd.h.0p @@ -0,0 +1,1396 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +unistd.h \- standard symbolic constants and types +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header defines miscellaneous symbolic constants +and types, and declares miscellaneous functions. The +actual values of the constants are unspecified except as shown. The +contents of this header are shown below. +.SS Version Test Macros +.LP +The following symbolic constants shall be defined: +.TP 7 +_POSIX_VERSION +Integer value indicating version of IEEE\ Std\ 1003.1 (C-language +binding) to which the implementation conforms. For +implementations conforming to IEEE\ Std\ 1003.1-2001, the value shall +be 200112L. +.TP 7 +_POSIX2_VERSION +Integer value indicating version of the Shell and Utilities volume +of IEEE\ Std\ 1003.1 to which the implementation +conforms. For implementations conforming to IEEE\ Std\ 1003.1-2001, +the value shall be 200112L. +.sp +.LP +The following symbolic constant shall be defined only if the implementation +supports the XSI option; see \fIXSI Conformance\fP . +.TP 7 +_XOPEN_VERSION +.sp +Integer value indicating version of the X/Open Portability Guide to +which the implementation conforms. The value shall be 600. +.sp +.SS Constants for Options and Option Groups +.LP +The following symbolic constants, if defined in \fI\fP, +shall have a value of -1, 0, or greater, unless +otherwise specified below. If these are undefined, the \fIfpathconf\fP(), +\fIpathconf\fP(), or \fIsysconf\fP() functions can be +used to determine whether the option is provided for a particular +invocation of the application. +.LP +If a symbolic constant is defined with the value -1, the option is +not supported. Headers, data types, and function interfaces +required only for the option need not be supplied. An application +that attempts to use anything associated only with the option is +considered to be requiring an extension. +.LP +If a symbolic constant is defined with a value greater than zero, +the option shall always be supported when the application is +executed. All headers, data types, and functions shall be present +and shall operate as specified. +.LP +If a symbolic constant is defined with the value zero, all headers, +data types, and functions shall be present. The application +can check at runtime to see whether the option is supported by calling +\fIfpathconf\fP(), \fIpathconf\fP(), or \fIsysconf\fP() with the indicated +\fIname\fP parameter. +.LP +Unless explicitly specified otherwise, the behavior of functions associated +with an unsupported option is unspecified, and an +application that uses such functions without first checking \fIfpathconf\fP(), +\fIpathconf\fP(), or \fIsysconf\fP() is considered to be +requiring an extension. +.LP +For conformance requirements, refer to \fIConformance\fP . +.TP 7 +_POSIX_ADVISORY_INFO +.sp +The implementation supports the Advisory Information option. If this +symbol has a value other than -1 or 0, it shall have the value +200112L. +.TP 7 +_POSIX_ASYNCHRONOUS_IO +.sp +The implementation supports the Asynchronous Input and Output option. +If this symbol has a value other than -1 or 0, it shall have +the value 200112L. +.TP 7 +_POSIX_BARRIERS +.sp +The implementation supports the Barriers option. If this symbol has +a value other than -1 or 0, it shall have the value 200112L. +.TP 7 +_POSIX_CHOWN_RESTRICTED +The use of \fIchown\fP() and \fIfchown\fP() is +restricted to a process with appropriate privileges, and to changing +the group ID of a file only to the effective group ID of the +process or to one of its supplementary group IDs. This symbol shall +always be set to a value other than -1. +.TP 7 +_POSIX_CLOCK_SELECTION +.sp +The implementation supports the Clock Selection option. If this symbol +has a value other than -1 or 0, it shall have the value +200112L. +.TP 7 +_POSIX_CPUTIME +.sp +The implementation supports the Process CPU-Time Clocks option. If +this symbol has a value other than -1 or 0, it shall have the +value 200112L. +.TP 7 +_POSIX_FSYNC +.sp +The implementation supports the File Synchronization option. If this +symbol has a value other than -1 or 0, it shall have the value +200112L. +.TP 7 +_POSIX_IPV6 +The implementation supports the IPv6 option. If this symbol has a +value other than -1 or 0, it shall have the value 200112L. +.TP 7 +_POSIX_JOB_CONTROL +The implementation supports job control. This symbol shall always +be set to a value greater than zero. +.TP 7 +_POSIX_MAPPED_FILES +.sp +The implementation supports the Memory Mapped Files option. If this +symbol has a value other than -1 or 0, it shall have the value +200112L. +.TP 7 +_POSIX_MEMLOCK +.sp +The implementation supports the Process Memory Locking option. If +this symbol has a value other than -1 or 0, it shall have the +value 200112L. +.TP 7 +_POSIX_MEMLOCK_RANGE +.sp +The implementation supports the Range Memory Locking option. If this +symbol has a value other than -1 or 0, it shall have the value +200112L. +.TP 7 +_POSIX_MEMORY_PROTECTION +.sp +The implementation supports the Memory Protection option. If this +symbol has a value other than -1 or 0, it shall have the value +200112L. +.TP 7 +_POSIX_MESSAGE_PASSING +.sp +The implementation supports the Message Passing option. If this symbol +has a value other than -1 or 0, it shall have the value +200112L. +.TP 7 +_POSIX_MONOTONIC_CLOCK +.sp +The implementation supports the Monotonic Clock option. If this symbol +has a value other than -1 or 0, it shall have the value +200112L. +.TP 7 +_POSIX_NO_TRUNC +Pathname components longer than {NAME_MAX} generate an error. This +symbol shall always be set to a value other than -1. +.TP 7 +_POSIX_PRIORITIZED_IO +.sp +The implementation supports the Prioritized Input and Output option. +If this symbol has a value other than -1 or 0, it shall have +the value 200112L. +.TP 7 +_POSIX_PRIORITY_SCHEDULING +.sp +The implementation supports the Process Scheduling option. If this +symbol has a value other than -1 or 0, it shall have the value +200112L. +.TP 7 +_POSIX_RAW_SOCKETS +.sp +The implementation supports the Raw Sockets option. If this symbol +has a value other than -1 or 0, it shall have the value 200112L. +.TP 7 +_POSIX_READER_WRITER_LOCKS +.sp +The implementation supports the Read-Write Locks option. This is always +set to a value greater than zero if the Threads option is +supported. If this symbol has a value other than -1 or 0, it shall +have the value 200112L. +.TP 7 +_POSIX_REALTIME_SIGNALS +.sp +The implementation supports the Realtime Signals Extension option. +If this symbol has a value other than -1 or 0, it shall have the +value 200112L. +.TP 7 +_POSIX_REGEXP +The implementation supports the Regular Expression Handling option. +This symbol shall always be set to a value greater than +zero. +.TP 7 +_POSIX_SAVED_IDS +Each process has a saved set-user-ID and a saved set-group-ID. This +symbol shall always be set to a value greater than zero. +.TP 7 +_POSIX_SEMAPHORES +.sp +The implementation supports the Semaphores option. If this symbol +has a value other than -1 or 0, it shall have the value 200112L. +.TP 7 +_POSIX_SHARED_MEMORY_OBJECTS +.sp +The implementation supports the Shared Memory Objects option. If this +symbol has a value other than -1 or 0, it shall have the +value 200112L. +.TP 7 +_POSIX_SHELL +The implementation supports the POSIX shell. This symbol shall always +be set to a value greater than zero. +.TP 7 +_POSIX_SPAWN +.sp +The implementation supports the Spawn option. If this symbol has a +value other than -1 or 0, it shall have the value 200112L. +.TP 7 +_POSIX_SPIN_LOCKS +.sp +The implementation supports the Spin Locks option. If this symbol +has a value other than -1 or 0, it shall have the value 200112L. +.TP 7 +_POSIX_SPORADIC_SERVER +.sp +The implementation supports the Process Sporadic Server option. If +this symbol has a value other than -1 or 0, it shall have the +value 200112L. +.TP 7 +_POSIX_SYNCHRONIZED_IO +.sp +The implementation supports the Synchronized Input and Output option. +If this symbol has a value other than -1 or 0, it shall have +the value 200112L. +.TP 7 +_POSIX_THREAD_ATTR_STACKADDR +.sp +The implementation supports the Thread Stack Address Attribute option. +If this symbol has a value other than -1 or 0, it shall have +the value 200112L. +.TP 7 +_POSIX_THREAD_ATTR_STACKSIZE +.sp +The implementation supports the Thread Stack Size Attribute option. +If this symbol has a value other than -1 or 0, it shall have +the value 200112L. +.TP 7 +_POSIX_THREAD_CPUTIME +.sp +The implementation supports the Thread CPU-Time Clocks option. If +this symbol has a value other than -1 or 0, it shall have the +value 200112L. +.TP 7 +_POSIX_THREAD_PRIO_INHERIT +.sp +The implementation supports the Thread Priority Inheritance option. +If this symbol has a value other than -1 or 0, it shall have +the value 200112L. +.TP 7 +_POSIX_THREAD_PRIO_PROTECT +.sp +The implementation supports the Thread Priority Protection option. +If this symbol has a value other than -1 or 0, it shall have the +value 200112L. +.TP 7 +_POSIX_THREAD_PRIORITY_SCHEDULING +.sp +The implementation supports the Thread Execution Scheduling option. +If this symbol has a value other than -1 or 0, it shall have +the value 200112L. +.TP 7 +_POSIX_THREAD_PROCESS_SHARED +.sp +The implementation supports the Thread Process-Shared Synchronization +option. If this symbol has a value other than -1 or 0, it +shall have the value 200112L. +.TP 7 +_POSIX_THREAD_SAFE_FUNCTIONS +.sp +The implementation supports the Thread-Safe Functions option. If this +symbol has a value other than -1 or 0, it shall have the +value 200112L. +.TP 7 +_POSIX_THREAD_SPORADIC_SERVER +.sp +The implementation supports the Thread Sporadic Server option. If +this symbol has a value other than -1 or 0, it shall have the +value 200112L. +.TP 7 +_POSIX_THREADS +.sp +The implementation supports the Threads option. If this symbol has +a value other than -1 or 0, it shall have the value 200112L. +.TP 7 +_POSIX_TIMEOUTS +.sp +The implementation supports the Timeouts option. If this symbol has +a value other than -1 or 0, it shall have the value 200112L. +.TP 7 +_POSIX_TIMERS +.sp +The implementation supports the Timers option. If this symbol has +a value other than -1 or 0, it shall have the value 200112L. +.TP 7 +_POSIX_TRACE +.sp +The implementation supports the Trace option. If this symbol has a +value other than -1 or 0, it shall have the value 200112L. +.TP 7 +_POSIX_TRACE_EVENT_FILTER +.sp +The implementation supports the Trace Event Filter option. If this +symbol has a value other than -1 or 0, it shall have the value +200112L. +.TP 7 +_POSIX_TRACE_INHERIT +.sp +The implementation supports the Trace Inherit option. If this symbol +has a value other than -1 or 0, it shall have the value +200112L. +.TP 7 +_POSIX_TRACE_LOG +.sp +The implementation supports the Trace Log option. If this symbol has +a value other than -1 or 0, it shall have the value 200112L. +.TP 7 +_POSIX_TYPED_MEMORY_OBJECTS +.sp +The implementation supports the Typed Memory Objects option. If this +symbol has a value other than -1 or 0, it shall have the value +200112L. +.TP 7 +_POSIX_VDISABLE +This symbol shall be defined to be the value of a character that shall +disable terminal special character handling as described in +\fI\fP . This symbol shall always be set to a value other +than -1. +.TP 7 +_POSIX2_C_BIND +The implementation supports the C-Language Binding option. This symbol +shall always have the value 200112L. +.TP 7 +_POSIX2_C_DEV +.sp +The implementation supports the C-Language Development Utilities option. +If this symbol has a value other than -1 or 0, it shall +have the value 200112L. +.TP 7 +_POSIX2_CHAR_TERM +The implementation supports at least one terminal type. +.TP 7 +_POSIX2_FORT_DEV +.sp +The implementation supports the FORTRAN Development Utilities option. +If this symbol has a value other than -1 or 0, it shall have +the value 200112L. +.TP 7 +_POSIX2_FORT_RUN +.sp +The implementation supports the FORTRAN Runtime Utilities option. +If this symbol has a value other than -1 or 0, it shall have the +value 200112L. +.TP 7 +_POSIX2_LOCALEDEF +The implementation supports the creation of locales by the \fIlocaledef\fP +utility. If +this symbol has a value other than -1 or 0, it shall have the value +200112L. +.TP 7 +_POSIX2_PBS +.sp +The implementation supports the Batch Environment Services and Utilities +option. If this symbol has a value other than -1 or 0, it +shall have the value 200112L. +.TP 7 +_POSIX2_PBS_ACCOUNTING +.sp +The implementation supports the Batch Accounting option. If this symbol +has a value other than -1 or 0, it shall have the value +200112L. +.TP 7 +_POSIX2_PBS_CHECKPOINT +.sp +The implementation supports the Batch Checkpoint/Restart option. If +this symbol has a value other than -1 or 0, it shall have the +value 200112L. +.TP 7 +_POSIX2_PBS_LOCATE +.sp +The implementation supports the Locate Batch Job Request option. If +this symbol has a value other than -1 or 0, it shall have the +value 200112L. +.TP 7 +_POSIX2_PBS_MESSAGE +.sp +The implementation supports the Batch Job Message Request option. +If this symbol has a value other than -1 or 0, it shall have the +value 200112L. +.TP 7 +_POSIX2_PBS_TRACK +.sp +The implementation supports the Track Batch Job Request option. If +this symbol has a value other than -1 or 0, it shall have the +value 200112L. +.TP 7 +_POSIX2_SW_DEV +.sp +The implementation supports the Software Development Utilities option. +If this symbol has a value other than -1 or 0, it shall have +the value 200112L. +.TP 7 +_POSIX2_UPE +.sp +The implementation supports the User Portability Utilities option. +If this symbol has a value other than -1 or 0, it shall have the +value 200112L. +.TP 7 +_V6_ILP32_OFF32 +The implementation provides a C-language compilation environment with +32-bit \fBint\fP, \fBlong\fP, \fBpointer\fP, and +\fBoff_t\fP types. +.TP 7 +_V6_ILP32_OFFBIG +The implementation provides a C-language compilation environment with +32-bit \fBint\fP, \fBlong\fP, and \fBpointer\fP types and +an \fBoff_t\fP type using at least 64 bits. +.TP 7 +_V6_LP64_OFF64 +The implementation provides a C-language compilation environment with +32-bit \fBint\fP and 64-bit \fBlong\fP, \fBpointer\fP, and +\fBoff_t\fP types. +.TP 7 +_V6_LPBIG_OFFBIG +The implementation provides a C-language compilation environment with +an \fBint\fP type using at least 32 bits and \fBlong\fP, +\fBpointer\fP, and \fBoff_t\fP types using at least 64 bits. +.TP 7 +_XBS5_ILP32_OFF32 (\fBLEGACY\fP) +.sp +The implementation provides a C-language compilation environment with +32-bit \fBint\fP, \fBlong\fP, \fBpointer\fP, and +\fBoff_t\fP types. +.TP 7 +_XBS5_ILP32_OFFBIG (\fBLEGACY\fP) +.sp +The implementation provides a C-language compilation environment with +32-bit \fBint\fP, \fBlong\fP, and \fBpointer\fP types and +an \fBoff_t\fP type using at least 64 bits. +.TP 7 +_XBS5_LP64_OFF64 (\fBLEGACY\fP) +.sp +The implementation provides a C-language compilation environment with +32-bit \fBint\fP and 64-bit \fBlong\fP, \fBpointer\fP, and +\fBoff_t\fP types. +.TP 7 +_XBS5_LPBIG_OFFBIG (\fBLEGACY\fP) +.sp +The implementation provides a C-language compilation environment with +an \fBint\fP type using at least 32 bits and \fBlong\fP, +\fBpointer\fP, and \fBoff_t\fP types using at least 64 bits. +.TP 7 +_XOPEN_CRYPT +.sp +The implementation supports the X/Open Encryption Option Group. +.TP 7 +_XOPEN_ENH_I18N +The implementation supports the Issue 4, Version 2 Enhanced Internationalization +Option Group. This symbol shall always be set to a +value other than -1. +.TP 7 +_XOPEN_LEGACY +The implementation supports the Legacy Option Group. +.TP 7 +_XOPEN_REALTIME +The implementation supports the X/Open Realtime Option Group. +.TP 7 +_XOPEN_REALTIME_THREADS +The implementation supports the X/Open Realtime Threads Option Group. +.TP 7 +_XOPEN_SHM +The implementation supports the Issue 4, Version 2 Shared Memory Option +Group. This symbol shall always be set to a value other +than -1. +.TP 7 +_XOPEN_STREAMS +The implementation supports the XSI STREAMS Option Group. +.TP 7 +_XOPEN_UNIX +.sp +The implementation supports the XSI extension. +.sp +.SS Execution-Time Symbolic Constants +.LP +If any of the following constants are not defined in the \fI\fP +header, the value shall vary depending on the +file to which it is applied. +.LP +If any of the following constants are defined to have value -1 in +the \fI\fP header, the implementation shall +not provide the option on any file; if any are defined to have a value +other than -1 in the \fI\fP header, the +implementation shall provide the option on all applicable files. +.LP +All of the following constants, whether defined in \fI\fP +or not, may be queried with respect to a specific +file using the \fIpathconf\fP() or \fIfpathconf\fP() functions: +.TP 7 +_POSIX_ASYNC_IO +Asynchronous input or output operations may be performed for the associated +file. +.TP 7 +_POSIX_PRIO_IO +Prioritized input or output operations may be performed for the associated +file. +.TP 7 +_POSIX_SYNC_IO +Synchronized input or output operations may be performed for the associated +file. +.sp +.SS Constants for Functions +.LP +The following symbolic constant shall be defined: +.TP 7 +NULL +Null pointer +.sp +.LP +The following symbolic constants shall be defined for the \fIaccess\fP() +function: +.TP 7 +F_OK +Test for existence of file. +.TP 7 +R_OK +Test for read permission. +.TP 7 +W_OK +Test for write permission. +.TP 7 +X_OK +Test for execute (search) permission. +.sp +.LP +The constants F_OK, R_OK, W_OK, and X_OK and the expressions \fIR_OK\fP|\fIW_OK\fP, +\fIR_OK\fP|\fIX_OK\fP, and +\fIR_OK\fP|\fIW_OK\fP|\fIX_OK\fP shall all have distinct values. +.LP +The following symbolic constants shall be defined for the \fIconfstr\fP() +function: +.TP 7 +_CS_PATH +This is the value for the \fIPATH\fP environment variable that finds +all standard utilities. +.TP 7 +_CS_POSIX_V6_ILP32_OFF32_CFLAGS +If \fIsysconf\fP(_SC_V6_ILP32_OFF32) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of +initial options to be given to the \fIc99\fP utility to build an application +using a +programming model with 32-bit \fBint\fP, \fBlong\fP, \fBpointer\fP, +and \fBoff_t\fP types. +.TP 7 +_CS_POSIX_V6_ILP32_OFF32_LDFLAGS +If \fIsysconf\fP(_SC_V6_ILP32_OFF32) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of +final options to be given to the \fIc99\fP utility to build an application +using a programming +model with 32-bit \fBint\fP, \fBlong\fP, \fBpointer\fP, and \fBoff_t\fP +types. +.TP 7 +_CS_POSIX_V6_ILP32_OFF32_LIBS +If \fIsysconf\fP(_SC_V6_ILP32_OFF32) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of +libraries to be given to the \fIc99\fP utility to build an application +using a programming +model with 32-bit \fBint\fP, \fBlong\fP, \fBpointer\fP, and \fBoff_t\fP +types. +.TP 7 +_CS_POSIX_V6_ILP32_OFFBIG_CFLAGS +If \fIsysconf\fP(_SC_V6_ILP32_OFFBIG) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of +initial options to be given to the \fIc99\fP utility to build an application +using a +programming model with 32-bit \fBint\fP, \fBlong\fP, and \fBpointer\fP +types, and an \fBoff_t\fP type using at least 64 +bits. +.TP 7 +_CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS +If \fIsysconf\fP(_SC_V6_ILP32_OFFBIG) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of +final options to be given to the \fIc99\fP utility to build an application +using a programming +model with 32-bit \fBint\fP, \fBlong\fP, and \fBpointer\fP types, +and an \fBoff_t\fP type using at least 64 bits. +.TP 7 +_CS_POSIX_V6_ILP32_OFFBIG_LIBS +If \fIsysconf\fP(_SC_V6_ILP32_OFFBIG) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of +libraries to be given to the \fIc99\fP utility to build an application +using a programming +model with 32-bit \fBint\fP, \fBlong\fP, and \fBpointer\fP types, +and an \fBoff_t\fP type using at least 64 bits. +.TP 7 +_CS_POSIX_V6_LP64_OFF64_CFLAGS +If \fIsysconf\fP(_SC_V6_LP64_OFF64) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of +initial options to be given to the \fIc99\fP utility to build an application +using a +programming model with 32-bit \fBint\fP and 64-bit \fBlong\fP, \fBpointer\fP, +and \fBoff_t\fP types. +.TP 7 +_CS_POSIX_V6_LP64_OFF64_LDFLAGS +If \fIsysconf\fP(_SC_V6_LP64_OFF64) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of +final options to be given to the \fIc99\fP utility to build an application +using a programming +model with 32-bit \fBint\fP and 64-bit \fBlong\fP, \fBpointer\fP, +and \fBoff_t\fP types. +.TP 7 +_CS_POSIX_V6_LP64_OFF64_LIBS +If \fIsysconf\fP(_SC_V6_LP64_OFF64) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of +libraries to be given to the \fIc99\fP utility to build an application +using a programming +model with 32-bit \fBint\fP and 64-bit \fBlong\fP, \fBpointer\fP, +and \fBoff_t\fP types. +.TP 7 +_CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS +If \fIsysconf\fP(_SC_V6_LPBIG_OFFBIG) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of +initial options to be given to the \fIc99\fP utility to build an application +using a +programming model with an \fBint\fP type using at least 32 bits and +\fBlong\fP, \fBpointer\fP, and \fBoff_t\fP types using at +least 64 bits. +.TP 7 +_CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS +If \fIsysconf\fP(_SC_V6_LPBIG_OFFBIG) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of +final options to be given to the \fIc99\fP utility to build an application +using a programming +model with an \fBint\fP type using at least 32 bits and \fBlong\fP, +\fBpointer\fP, and \fBoff_t\fP types using at least 64 +bits. +.TP 7 +_CS_POSIX_V6_LPBIG_OFFBIG_LIBS +If \fIsysconf\fP(_SC_V6_LPBIG_OFFBIG) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of +libraries to be given to the \fIc99\fP utility to build an application +using a programming +model with an \fBint\fP type using at least 32 bits and \fBlong\fP, +\fBpointer\fP, and \fBoff_t\fP types using at least 64 +bits. +.TP 7 +_CS_POSIX_V6_WIDTH_RESTRICTED_ENVS +This value is a -separated list of names of programming environments +supported by the implementation in which the +widths of the \fBblksize_t\fP, \fBcc_t\fP, \fBmode_t\fP, \fBnfds_t\fP, +\fBpid_t\fP, \fBptrdiff_t\fP, \fBsize_t\fP, +\fBspeed_t\fP, \fBssize_t\fP, \fBsuseconds_t\fP, \fBtcflag_t\fP, \fBuseconds_t\fP, +\fBwchar_t\fP, and \fBwint_t\fP types are +no greater than the width of type \fBlong\fP. +.sp +.LP +The following symbolic constants are reserved for compatibility with +Issue 5: +.LP +.sp +_CS_XBS5_ILP32_OFF32_CFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_ILP32_OFF32_LDFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_ILP32_OFF32_LIBS (\fBLEGACY\fP) +.br +_CS_XBS5_ILP32_OFF32_LINTFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_ILP32_OFFBIG_CFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_ILP32_OFFBIG_LDFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_ILP32_OFFBIG_LIBS (\fBLEGACY\fP) +.br +_CS_XBS5_ILP32_OFFBIG_LINTFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_LP64_OFF64_CFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_LP64_OFF64_LDFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_LP64_OFF64_LIBS (\fBLEGACY\fP) +.br +_CS_XBS5_LP64_OFF64_LINTFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_LPBIG_OFFBIG_CFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_LPBIG_OFFBIG_LDFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_LPBIG_OFFBIG_LIBS (\fBLEGACY\fP) +.br +_CS_XBS5_LPBIG_OFFBIG_LINTFLAGS (\fBLEGACY\fP) +.br +.sp +.LP +The following symbolic constants shall be defined for the \fIlseek\fP() +and \fIfcntl\fP() functions and shall have distinct values: +.TP 7 +SEEK_CUR +Set file offset to current plus \fIoffset\fP. +.TP 7 +SEEK_END +Set file offset to EOF plus \fIoffset\fP. +.TP 7 +SEEK_SET +Set file offset to \fIoffset\fP. +.sp +.LP +The following symbolic constants shall be defined as possible values +for the \fIfunction\fP argument to the \fIlockf\fP() function: +.TP 7 +F_LOCK +Lock a section for exclusive use. +.TP 7 +F_TEST +Test section for locks by other processes. +.TP 7 +F_TLOCK +Test and lock a section for exclusive use. +.TP 7 +F_ULOCK +Unlock locked sections. +.sp +.LP +The following symbolic constants shall be defined for \fIpathconf\fP(): +.LP +.sp +_PC_ALLOC_SIZE_MIN +.br +_PC_ASYNC_IO +.br +_PC_CHOWN_RESTRICTED +.br +_PC_FILESIZEBITS +.br +_PC_LINK_MAX +.br +_PC_MAX_CANON +.br +_PC_MAX_INPUT +.br +_PC_NAME_MAX +.br +_PC_NO_TRUNC +.br +_PC_PATH_MAX +.br +_PC_PIPE_BUF +.br +_PC_PRIO_IO +.br +_PC_REC_INCR_XFER_SIZE +.br +_PC_REC_MIN_XFER_SIZE +.br +_PC_REC_XFER_ALIGN +.br +_PC_SYMLINK_MAX +.br +_PC_SYNC_IO +.br +_PC_VDISABLE +.br +.LP +The following symbolic constants shall be defined for \fIsysconf\fP(): +.LP +.sp +_SC_2_C_BIND +.br +_SC_2_C_DEV +.br +_SC_2_C_VERSION +.br +_SC_2_CHAR_TERM +.br +_SC_2_FORT_DEV +.br +_SC_2_FORT_RUN +.br +_SC_2_LOCALEDEF +.br +_SC_2_PBS +.br +_SC_2_PBS_ACCOUNTING +.br +_SC_2_PBS_CHECKPOINT +.br +_SC_2_PBS_LOCATE +.br +_SC_2_PBS_MESSAGE +.br +_SC_2_PBS_TRACK +.br +_SC_2_SW_DEV +.br +_SC_2_UPE +.br +_SC_2_VERSION +.br +_SC_ADVISORY_INFO +.br +_SC_ARG_MAX +.br +_SC_AIO_LISTIO_MAX +.br +_SC_AIO_MAX +.br +_SC_AIO_PRIO_DELTA_MAX +.br +_SC_ASYNCHRONOUS_IO +.br +_SC_ATEXIT_MAX +.br +_SC_BARRIERS +.br +_SC_BC_BASE_MAX +.br +_SC_BC_DIM_MAX +.br +_SC_BC_SCALE_MAX +.br +_SC_BC_STRING_MAX +.br +_SC_CHILD_MAX +.br +_SC_CLK_TCK +.br +_SC_CLOCK_SELECTION +.br +_SC_COLL_WEIGHTS_MAX +.br +_SC_CPUTIME +.br +_SC_DELAYTIMER_MAX +.br +_SC_EXPR_NEST_MAX +.br +_SC_FILE_LOCKING +.br +_SC_FSYNC +.br +_SC_GETGR_R_SIZE_MAX +.br +_SC_GETPW_R_SIZE_MAX +.br +_SC_HOST_NAME_MAX +.br +_SC_IOV_MAX +.br +_SC_IPV6 +.br +_SC_JOB_CONTROL +.br +_SC_LINE_MAX +.br +_SC_LOGIN_NAME_MAX +.br +_SC_MAPPED_FILES +.br +_SC_MEMLOCK +.br +_SC_MEMLOCK_RANGE +.br +_SC_MEMORY_PROTECTION +.br +_SC_MESSAGE_PASSING +.br +_SC_MONOTONIC_CLOCK +.br +_SC_MQ_OPEN_MAX +.br +_SC_MQ_PRIO_MAX +.br +_SC_NGROUPS_MAX +.br +_SC_OPEN_MAX +.br +_SC_PAGE_SIZE +.br +_SC_PAGESIZE +.br +_SC_PRIORITIZED_IO +.br +_SC_PRIORITY_SCHEDULING +.br +_SC_RAW_SOCKETS +.br +_SC_RE_DUP_MAX +.br +_SC_READER_WRITER_LOCKS +.br +_SC_REALTIME_SIGNALS +.br +_SC_REGEXP +.br +_SC_RTSIG_MAX +.br +_SC_SAVED_IDS +.br +_SC_SEMAPHORES +.br +_SC_SEM_NSEMS_MAX +.br +_SC_SEM_VALUE_MAX +.br +_SC_SHARED_MEMORY_OBJECTS +.br +_SC_SHELL +.br +_SC_SIGQUEUE_MAX +.br +_SC_SPAWN +.br +_SC_SPIN_LOCKS +.br +_SC_SPORADIC_SERVER +.br +_SC_STREAM_MAX +.br +_SC_SYMLOOP_MAX +.br +_SC_SYNCHRONIZED_IO +.br +_SC_THREAD_ATTR_STACKADDR +.br +_SC_THREAD_ATTR_STACKSIZE +.br +_SC_THREAD_CPUTIME +.br +_SC_THREAD_DESTRUCTOR_ITERATIONS +.br +_SC_THREAD_KEYS_MAX +.br +_SC_THREAD_PRIO_INHERIT +.br +_SC_THREAD_PRIO_PROTECT +.br +_SC_THREAD_PRIORITY_SCHEDULING +.br +_SC_THREAD_PROCESS_SHARED +.br +_SC_THREAD_SAFE_FUNCTIONS +.br +_SC_THREAD_SPORADIC_SERVER +.br +_SC_THREAD_STACK_MIN +.br +_SC_THREAD_THREADS_MAX +.br +_SC_TIMEOUTS +.br +_SC_THREADS +.br +_SC_TIMER_MAX +.br +_SC_TIMERS +.br +_SC_TRACE +.br +_SC_TRACE_EVENT_FILTER +.br +_SC_TRACE_INHERIT +.br +_SC_TRACE_LOG +.br +_SC_TTY_NAME_MAX +.br +_SC_TYPED_MEMORY_OBJECTS +.br +_SC_TZNAME_MAX +.br +_SC_V6_ILP32_OFF32 +.br +_SC_V6_ILP32_OFFBIG +.br +_SC_V6_LP64_OFF64 +.br +_SC_V6_LPBIG_OFFBIG +.br +_SC_VERSION +.br +_SC_XBS5_ILP32_OFF32 (\fBLEGACY\fP) +.br +_SC_XBS5_ILP32_OFFBIG (\fBLEGACY\fP) +.br +_SC_XBS5_LP64_OFF64 (\fBLEGACY\fP) +.br +_SC_XBS5_LPBIG_OFFBIG (\fBLEGACY\fP) +.br +_SC_XOPEN_CRYPT +.br +_SC_XOPEN_ENH_I18N +.br +_SC_XOPEN_LEGACY +.br +_SC_XOPEN_REALTIME +.br +_SC_XOPEN_REALTIME_THREADS +.br +_SC_XOPEN_SHM +.br +_SC_XOPEN_STREAMS +.br +_SC_XOPEN_UNIX +.br +_SC_XOPEN_VERSION +.br +_SC_XOPEN_XCU_VERSION +.br +.LP +The two constants _SC_PAGESIZE and _SC_PAGE_SIZE may be defined to +have the same value. +.LP +The following symbolic constants shall be defined for file streams: +.TP 7 +STDERR_FILENO +File number of \fIstderr\fP; 2. +.TP 7 +STDIN_FILENO +File number of \fIstdin\fP; 0. +.TP 7 +STDOUT_FILENO +File number of \fIstdout\fP; 1. +.sp +.SS Type Definitions +.LP +The \fBsize_t\fP, \fBssize_t\fP, \fBuid_t\fP, \fBgid_t\fP, \fBoff_t\fP, +\fBpid_t\fP, and \fBuseconds_t\fP types shall be +defined as described in \fI\fP. +.LP +The \fBintptr_t\fP type shall be defined as described in \fI\fP. +.SS Declarations +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint access(const char *, int); +unsigned alarm(unsigned); +int chdir(const char *); +int chown(const char *, uid_t, gid_t); +int close(int); +size_t confstr(int, char *, size_t); +.sp + + +char *crypt(const char *, const char *); +char *ctermid(char *); + +int dup(int); +.sp + +int dup2(int, int); + +void encrypt(char[64], int); + +int execl(const char *, const char *, ...); +int execle(const char *, const char *, ...); +int execlp(const char *, const char *, ...); +int execv(const char *, char *const []); +int execve(const char *, char *const [], char *const []); +int execvp(const char *, char *const []); +void _exit(int); +int fchown(int, uid_t, gid_t); + +int fchdir(int); + + +int fdatasync(int); + +pid_t fork(void); +long fpathconf(int, int); + +int fsync(int); + +int ftruncate(int, off_t); +char *getcwd(char *, size_t); +gid_t getegid(void); +uid_t geteuid(void); +gid_t getgid(void); +int getgroups(int, gid_t []); + +long gethostid(void); + +int gethostname(char *, size_t); +char *getlogin(void); +int getlogin_r(char *, size_t); +int getopt(int, char * const [], const char *); + +pid_t getpgid(pid_t); + +pid_t getpgrp(void); +pid_t getpid(void); +pid_t getppid(void); + +pid_t getsid(pid_t); + +uid_t getuid(void); + +char *getwd(char *); (\fP\fBLEGACY\fP \fB) + +int isatty(int); + +int lchown(const char *, uid_t, gid_t); + +int link(const char *, const char *); + +int lockf(int, int, off_t); + +off_t lseek(int, off_t, int); + +int nice(int); + +long pathconf(const char *, int); +int pause(void); +int pipe(int [2]); + +ssize_t pread(int, void *, size_t, off_t); +ssize_t pwrite(int, const void *, size_t, off_t); + +ssize_t read(int, void *, size_t); +ssize_t readlink(const char *restrict, char *restrict, size_t); +int rmdir(const char *); +int setegid(gid_t); +int seteuid(uid_t); +int setgid(gid_t); +.sp + +int setpgid(pid_t, pid_t); + +pid_t setpgrp(void); +int setregid(gid_t, gid_t); +int setreuid(uid_t, uid_t); + +pid_t setsid(void); +int setuid(uid_t); +unsigned sleep(unsigned); + +void swab(const void *restrict, void *restrict, ssize_t); +int symlink(const char *, const char *); +void sync(void); + +long sysconf(int); +pid_t tcgetpgrp(int); +int tcsetpgrp(int, pid_t); + +int truncate(const char *, off_t); + +char *ttyname(int); +int ttyname_r(int, char *, size_t); + +useconds_t ualarm(useconds_t, useconds_t); + +int unlink(const char *); + +int usleep(useconds_t); +pid_t vfork(void); + +ssize_t write(int, const void *, size_t); +\fP +.fi +.RE +.LP +Implementations may also include the \fIpthread_atfork\fP() prototype +as defined +in \fI\fP . +.LP +The following external variables shall be declared: +.sp +.RS +.nf + +\fBextern char *optarg; +extern int optind, opterr, optopt; +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +IEEE\ Std\ 1003.1-2001 only describes the behavior of systems that +claim conformance to it. However, application +developers who want to write applications that adapt to other versions +of IEEE\ Std\ 1003.1 (or to systems that do not +conform to any POSIX standard) may find it useful to code them so +as to conditionally compile different code depending on the value +of _POSIX_VERSION, for example: +.sp +.RS +.nf + +\fB#if _POSIX_VERSION >= 200112L +/* Use the newer function that copes with large files. */ +off_t pos=ftello(fp); +#else +/* Either this is an old version of POSIX, or _POSIX_VERSION is + not even defined, so use the traditional function. */ +long pos=ftell(fp); +#endif +\fP +.fi +.RE +.LP +Earlier versions of IEEE\ Std\ 1003.1 and of the Single UNIX Specification +can be identified by the following +macros: +.TP 7 +POSIX.1-1988 standard +_POSIX_VERSION==198808L +.TP 7 +POSIX.1-1990 standard +_POSIX_VERSION==199009L +.TP 7 +ISO\ POSIX-1:1996 standard +_POSIX_VERSION==199506L +.TP 7 +Single UNIX Specification, Version 1 +_XOPEN_UNIX and _XOPEN_VERSION==4 +.TP 7 +Single UNIX Specification, Version 2 +_XOPEN_UNIX and _XOPEN_VERSION==500 +.sp +.LP +IEEE\ Std\ 1003.1-2001 does not make any attempt to define application +binary interaction with the underlying operating +system. However, application developers may find it useful to query +_SC_VERSION at runtime via \fIsysconf\fP() to determine whether the +current version of the operating system supports the +necessary functionality as in the following program fragment: +.sp +.RS +.nf + +\fBif (sysconf(_SC_VERSION) < 200112L) { + fprintf(stderr, "POSIX.1-2001 system required, terminating \\n"); + exit(1); +} +\fP +.fi +.RE +.LP +New applications should not use _XOPEN_SHM or _XOPEN_ENH_I18N. +.SH RATIONALE +.LP +As IEEE\ Std\ 1003.1-2001 evolved, certain options became sufficiently +standardized that it was concluded that simply +requiring one of the option choices was simpler than retaining the +option. However, for backwards-compatibility, the option flags +(with required constant values) are retained. +.SS Version Test Macros +.LP +The standard developers considered altering the definition of _POSIX_VERSION +and removing _SC_VERSION from the specification of +\fIsysconf\fP() since the utility to an application was deemed by +some to be minimal, and +since the implementation of the functionality is potentially problematic. +However, they recognized that support for existing +application binaries is a concern to manufacturers, application developers, +and the users of implementations conforming to +IEEE\ Std\ 1003.1-2001. +.LP +While the example using _SC_VERSION in the APPLICATION USAGE section +does not provide the greatest degree of imaginable utility +to the application developer or user, it is arguably better than a +\fBcore\fP file or some other equally obscure result. (It is +also possible for implementations to encode and recognize application +binaries compiled in various POSIX.1-conforming environments, +and modify the semantics of the underlying system to conform to the +expectations of the application.) For the reasons outlined in +the preceding paragraphs and in the APPLICATION USAGE section, the +standard developers elected to retain the _POSIX_VERSION and +_SC_VERSION functionality. +.SS Compile-Time Symbolic Constants for System-Wide Options +.LP +IEEE\ Std\ 1003.1-2001 now includes support in certain areas for the +newly adopted policy governing options and +stubs. +.LP +This policy provides flexibility for implementations in how they support +options. It also specifies how conforming applications +can adapt to different implementations that support different sets +of options. It allows the following: +.IP " 1." 4 +If an implementation has no interest in supporting an option, it does +not have to provide anything associated with that option +beyond the announcement that it does not support it. +.LP +.IP " 2." 4 +An implementation can support a partial or incompatible version of +an option (as a non-standard extension) as long as it does +not claim to support the option. +.LP +.IP " 3." 4 +An application can determine whether the option is supported. A strictly +conforming application must check this announcement +mechanism before first using anything associated with the option. +.LP +.LP +There is an important implication of this policy. IEEE\ Std\ 1003.1-2001 +cannot dictate the behavior of interfaces +associated with an option when the implementation does not claim to +support the option. In particular, it cannot require that a +function associated with an unsupported option will fail if it does +not perform as specified. However, this policy does not prevent +a standard from requiring certain functions to always be present, +but that they shall always fail on some implementations. The \fIsetpgid\fP() +function in the POSIX.1-1990 standard, for example, is considered +appropriate. +.LP +The POSIX standards include various options, and the C-language binding +support for an option implies that the implementation +must supply data types and function interfaces. An application must +be able to discover whether the implementation supports each +option. +.LP +Any application must consider the following three cases for each option: +.IP " 1." 4 +Option never supported. +.LP +The implementation advertises at compile time that the option will +never be supported. In this case, it is not necessary for the +implementation to supply any of the data types or function interfaces +that are provided only as part of the option. The +implementation might provide data types and functions that are similar +to those defined by IEEE\ Std\ 1003.1-2001, but +there is no guarantee for any particular behavior. +.LP +.IP " 2." 4 +Option always supported. +.LP +The implementation advertises at compile time that the option will +always be supported. In this case, all data types and +function interfaces shall be available and shall operate as specified. +.LP +.IP " 3." 4 +Option might or might not be supported. +.LP +Some implementations might not provide a mechanism to specify support +of options at compile time. In addition, the +implementation might be unable or unwilling to specify support or +non-support at compile time. In either case, any application that +might use the option at runtime must be able to compile and execute. +The implementation must provide, at compile time, all data +types and function interfaces that are necessary to allow this. In +this situation, there must be a mechanism that allows the +application to query, at runtime, whether the option is supported. +If the application attempts to use the option when it is not +supported, the result is unspecified unless explicitly specified otherwise +in IEEE\ Std\ 1003.1-2001. +.LP +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , \fI\fP , \fI\fP +, \fI\fP , \fI\fP , the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, \fIaccess\fP(), \fIalarm\fP(), \fIchdir\fP(), +\fIchown\fP(), \fIclose\fP(), \fIcrypt\fP(), \fIctermid\fP(), \fIdup\fP(), +\fIencrypt\fP(), \fIenviron\fP, \fIexec\fP, \fIexit\fP(), \fIfchdir\fP(), +\fIfchown\fP(), \fIfcntl\fP(), \fIfork\fP(), \fIfpathconf\fP(), \fIfsync\fP(), +\fIftruncate\fP(), \fIgetcwd\fP(), \fIgetegid\fP(), \fIgeteuid\fP(), +\fIgetgid\fP(), \fIgetgroups\fP(), \fIgethostid\fP(), \fIgethostname\fP(), +\fIgetlogin\fP(), \fIgetpgid\fP(), \fIgetpgrp\fP(), \fIgetpid\fP(), +\fIgetppid\fP(), \fIgetsid\fP(), \fIgetuid\fP(), \fIisatty\fP(), \fIlchown\fP(), +\fIlink\fP(), \fIlockf\fP(), \fIlseek\fP(), \fInice\fP(), \fIpathconf\fP(), +\fIpause\fP(), \fIpipe\fP(), \fIread\fP(), \fIreadlink\fP(), \fIrmdir\fP(), +\fIsetgid\fP(), \fIsetpgid\fP(), \fIsetpgrp\fP(), \fIsetregid\fP(), +\fIsetreuid\fP(), \fIsetsid\fP(), \fIsetuid\fP(), \fIsleep\fP(), \fIswab\fP(), +\fIsymlink\fP(), \fIsync\fP(), \fIsysconf\fP(), \fItcgetpgrp\fP(), +\fItcsetpgrp\fP(), \fItruncate\fP(), \fIttyname\fP(), \fIualarm\fP(), +\fIunlink\fP(), \fIusleep\fP(), \fIvfork\fP(), \fIwrite\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/utime.h.0p b/man0p/utime.h.0p new file mode 100644 index 000000000..7fef5bdb5 --- /dev/null +++ b/man0p/utime.h.0p @@ -0,0 +1,62 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +utime.h \- access and modification times structure +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall declare the structure \fButimbuf\fP, +which shall include the following members: +.sp +.RS +.nf + +\fBtime_t actime \fP Access time. \fB +time_t modtime \fP Modification time. \fB +\fP +.fi +.RE +.LP +The times shall be measured in seconds since the Epoch. +.LP +The type \fBtime_t\fP shall be defined as described in \fI\fP +\&. +.LP +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS +.nf + +\fBint utime(const char *, const struct utimbuf *); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIutime\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/utmpx.h.0p b/man0p/utmpx.h.0p new file mode 100644 index 000000000..16d3a78b9 --- /dev/null +++ b/man0p/utmpx.h.0p @@ -0,0 +1,104 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +utmpx.h \- user accounting database definitions +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the \fButmpx\fP structure +that shall include at least the following members: +.sp +.RS +.nf + +\fBchar ut_user[] \fP User login name. \fB +char ut_id[] \fP Unspecified initialization process identifier. \fB +char ut_line[] \fP Device name. \fB +pid_t ut_pid \fP Process ID. \fB +short ut_type \fP Type of entry. \fB +struct timeval ut_tv \fP Time entry was made. \fB +\fP +.fi +.RE +.LP +The \fBpid_t\fP type shall be defined through \fBtypedef\fP as described +in \fI\fP . +.LP +The \fBtimeval\fP structure shall be defined as described in \fI\fP +\&. +.LP +Inclusion of the \fI\fP header may also make visible all +symbols from \fI\fP. +.LP +The following symbolic constants shall be defined as possible values +for the \fIut_type\fP member of the \fButmpx\fP +structure: +.TP 7 +EMPTY +No valid user accounting information. +.TP 7 +BOOT_TIME +Identifies time of system boot. +.TP 7 +OLD_TIME +Identifies time when system clock changed. +.TP 7 +NEW_TIME +Identifies time after system clock changed. +.TP 7 +USER_PROCESS +Identifies a process. +.TP 7 +INIT_PROCESS +Identifies a process spawned by the init process. +.TP 7 +LOGIN_PROCESS +Identifies the session leader of a logged-in user. +.TP 7 +DEAD_PROCESS +Identifies a session leader who has exited. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBvoid endutxent(void); +struct utmpx *getutxent(void); +struct utmpx *getutxid(const struct utmpx *); +struct utmpx *getutxline(const struct utmpx *); +struct utmpx *pututxline(const struct utmpx *); +void setutxent(void); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIendutxent\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/utsname.h.0p b/man0p/utsname.h.0p new file mode 100644 index 000000000..ee3a17616 --- /dev/null +++ b/man0p/utsname.h.0p @@ -0,0 +1 @@ +.so man0p/sys_utsname.h.0p diff --git a/man0p/wait.h.0p b/man0p/wait.h.0p new file mode 100644 index 000000000..e3122241f --- /dev/null +++ b/man0p/wait.h.0p @@ -0,0 +1 @@ +.so man0p/sys_wait.h.0p diff --git a/man0p/wchar.h.0p b/man0p/wchar.h.0p new file mode 100644 index 000000000..36d1f500a --- /dev/null +++ b/man0p/wchar.h.0p @@ -0,0 +1,242 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +wchar.h \- wide-character handling +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +Some of the functionality described on this reference page extends +the ISO\ C standard. Applications shall define +the appropriate feature test macro (see the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, Section 2.2, The Compilation Environment) +to enable the visibility of these symbols in this +header. +.LP +The \fI\fP header shall define the following types: +.TP 7 +\fBwchar_t\fP +As described in \fI\fP . +.TP 7 +\fBwint_t\fP +An integer type capable of storing any valid value of \fBwchar_t\fP +or WEOF. +.TP 7 +\fBwctype_t\fP +A scalar type of a data object that can hold values which represent +locale-specific character classification. +.TP 7 +\fBmbstate_t\fP +An object type other than an array type that can hold the conversion +state information necessary to convert between sequences +of (possibly multi-byte) characters and wide characters. \ If a +codeset is being used such that an \fBmbstate_t\fP needs to +preserve more than 2 levels of reserved state, the results are unspecified. +.TP 7 +\fBFILE\fP +As described in \fI\fP . +.TP 7 +\fBsize_t\fP +As described in \fI\fP . +.TP 7 +\fBva_list\fP +As described in \fI\fP . +.sp +.LP +The implementation shall support one or more programming environments +in which the width of \fBwint_t\fP is no greater than the +width of type \fBlong\fP. The names of these programming environments +can be obtained using the \fIconfstr\fP() function or the \fIgetconf\fP +utility. +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBwint_t btowc(int); +wint_t fgetwc(FILE *); +wchar_t *fgetws(wchar_t *restrict, int, FILE *restrict); +wint_t fputwc(wchar_t, FILE *); +int fputws(const wchar_t *restrict, FILE *restrict); +int fwide(FILE *, int); +int fwprintf(FILE *restrict, const wchar_t *restrict, ...); +int fwscanf(FILE *restrict, const wchar_t *restrict, ...); +wint_t getwc(FILE *); +wint_t getwchar(void); + +int iswalnum(wint_t); +int iswalpha(wint_t); +int iswcntrl(wint_t); +int iswctype(wint_t, wctype_t); +int iswdigit(wint_t); +int iswgraph(wint_t); +int iswlower(wint_t); +int iswprint(wint_t); +int iswpunct(wint_t); +int iswspace(wint_t); +int iswupper(wint_t); +int iswxdigit(wint_t); + +size_t mbrlen(const char *restrict, size_t, mbstate_t *restrict); +size_t mbrtowc(wchar_t *restrict, const char *restrict, size_t, + mbstate_t *restrict); +int mbsinit(const mbstate_t *); +size_t mbsrtowcs(wchar_t *restrict, const char **restrict, size_t, + mbstate_t *restrict); +wint_t putwc(wchar_t, FILE *); +wint_t putwchar(wchar_t); +int swprintf(wchar_t *restrict, size_t, + const wchar_t *restrict, ...); +int swscanf(const wchar_t *restrict, + const wchar_t *restrict, ...); + +wint_t towlower(wint_t); +wint_t towupper(wint_t); + +wint_t ungetwc(wint_t, FILE *); +int vfwprintf(FILE *restrict, const wchar_t *restrict, va_list); +int vfwscanf(FILE *restrict, const wchar_t *restrict, va_list); +int vwprintf(const wchar_t *restrict, va_list); +int vswprintf(wchar_t *restrict, size_t, + const wchar_t *restrict, va_list); +int vswscanf(const wchar_t *restrict, const wchar_t *restrict, + va_list); +int vwscanf(const wchar_t *restrict, va_list); +size_t wcrtomb(char *restrict, wchar_t, mbstate_t *restrict); +wchar_t *wcscat(wchar_t *restrict, const wchar_t *restrict); +wchar_t *wcschr(const wchar_t *, wchar_t); +int wcscmp(const wchar_t *, const wchar_t *); +int wcscoll(const wchar_t *, const wchar_t *); +wchar_t *wcscpy(wchar_t *restrict, const wchar_t *restrict); +size_t wcscspn(const wchar_t *, const wchar_t *); +size_t wcsftime(wchar_t *restrict, size_t, + const wchar_t *restrict, const struct tm *restrict); +size_t wcslen(const wchar_t *); +wchar_t *wcsncat(wchar_t *restrict, const wchar_t *restrict, size_t); +int wcsncmp(const wchar_t *, const wchar_t *, size_t); +wchar_t *wcsncpy(wchar_t *restrict, const wchar_t *restrict, size_t); +wchar_t *wcspbrk(const wchar_t *, const wchar_t *); +wchar_t *wcsrchr(const wchar_t *, wchar_t); +size_t wcsrtombs(char *restrict, const wchar_t **restrict, + size_t, mbstate_t *restrict); +size_t wcsspn(const wchar_t *, const wchar_t *); +wchar_t *wcsstr(const wchar_t *restrict, const wchar_t *restrict); +double wcstod(const wchar_t *restrict, wchar_t **restrict); +float wcstof(const wchar_t *restrict, wchar_t **restrict); +wchar_t *wcstok(wchar_t *restrict, const wchar_t *restrict, + wchar_t **restrict); +long wcstol(const wchar_t *restrict, wchar_t **restrict, int); +long double wcstold(const wchar_t *restrict, wchar_t **restrict); +long long wcstoll(const wchar_t *restrict, wchar_t **restrict, int); +unsigned long wcstoul(const wchar_t *restrict, wchar_t **restrict, int); +unsigned long long + wcstoull(const wchar_t *restrict, wchar_t **restrict, int); + +wchar_t *wcswcs(const wchar_t *, const wchar_t *); +int wcswidth(const wchar_t *, size_t); + +size_t wcsxfrm(wchar_t *restrict, const wchar_t *restrict, size_t); +int wctob(wint_t); + +wctype_t wctype(const char *); +int wcwidth(wchar_t); + +wchar_t *wmemchr(const wchar_t *, wchar_t, size_t); +int wmemcmp(const wchar_t *, const wchar_t *, size_t); +wchar_t *wmemcpy(wchar_t *restrict, const wchar_t *restrict, size_t); +wchar_t *wmemmove(wchar_t *, const wchar_t *, size_t); +wchar_t *wmemset(wchar_t *, wchar_t, size_t); +int wprintf(const wchar_t *restrict, ...); +int wscanf(const wchar_t *restrict, ...); +\fP +.fi +.RE +.LP +The \fI\fP header shall define the following macros: +.TP 7 +WCHAR_MAX +The maximum value representable by an object of type \fBwchar_t\fP. +.TP 7 +WCHAR_MIN +The minimum value representable by an object of type \fBwchar_t\fP. +.TP 7 +WEOF +Constant expression of type \fBwint_t\fP that is returned by several +WP functions to indicate end-of-file. +.TP 7 +NULL +As described in \fI\fP . +.sp +.LP +The tag \fBtm\fP shall be declared as naming an incomplete structure +type, the contents of which are described in the header \fI\fP +\&. +.LP +Inclusion of the \fI\fP header may make visible all symbols +from the headers \fI\fP, \fI\fP, \fI\fP, +\fI\fP, \fI\fP, \fI\fP, and \fI\fP. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fIiswblank\fP() function was a late addition to the ISO\ C standard +and was +introduced at the same time as the ISO\ C standard introduced \fI\fP, +which contains all of the \fIisw*\fP() functions. The Open Group Base +Specifications had +previously aligned with the MSE working draft and had introduced the +rest of the \fIisw*\fP() +functions into \fI\fP. For backwards-compatibility, the original +set of +\fIisw*\fP() functions, without \fIiswblank\fP(), are +permitted (as an XSI extension) in \fI\fP. For maximum portability, +applications should include \fI\fP in order to obtain declarations +for the +\fIisw*\fP() functions. +.SH RATIONALE +.LP +In the ISO\ C standard, the symbols referenced as XSI extensions are +in \fI\fP. Their presence here is thus an extension. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , \fI\fP , \fI\fP +, \fI\fP , \fI\fP , \fI\fP , \fI\fP +, the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIbtowc\fP(), \fIconfstr\fP(), \fIfgetwc\fP(), +\fIfgetws\fP(), \fIfputwc\fP(), \fIfputws\fP(), \fIfwide\fP(), \fIfwprintf\fP(), +\fIfwscanf\fP(), \fIgetwc\fP(), \fIgetwchar\fP(), \fIiswalnum\fP(), +\fIiswalpha\fP(), \fIiswcntrl\fP(), \fIiswctype\fP(), \fIiswdigit\fP(), +\fIiswgraph\fP(), \fIiswlower\fP(), \fIiswprint\fP(), \fIiswpunct\fP(), +\fIiswspace\fP(), \fIiswupper\fP(), \fIiswxdigit\fP(), \fIiswctype\fP(), +\fImbsinit\fP(), \fImbrlen\fP(), \fImbrtowc\fP(), \fImbsrtowcs\fP(), +\fIputwc\fP(), \fIputwchar\fP(), \fIswprintf\fP(), \fIswscanf\fP(), +\fItowlower\fP(), \fItowupper\fP(), \fIungetwc\fP(), \fIvfwprintf\fP(), +\fIvfwscanf\fP(), \fIvswprintf\fP(), \fIvswscanf\fP(), \fIvwscanf\fP(), +\fIwcrtomb\fP(), \fIwcsrtombs\fP(), \fIwcscat\fP(), \fIwcschr\fP(), +\fIwcscmp\fP(), \fIwcscoll\fP(), \fIwcscpy\fP(), \fIwcscspn\fP(), +\fIwcsftime\fP(), \fIwcslen\fP(), \fIwcsncat\fP(), \fIwcsncmp\fP(), +\fIwcsncpy\fP(), \fIwcspbrk\fP(), \fIwcsrchr\fP(), \fIwcsspn\fP(), +\fIwcsstr\fP(), \fIwcstod\fP(), \fIwcstof\fP(), \fIwcstok\fP(), \fIwcstol\fP(), +\fIwcstold\fP(), \fIwcstoll\fP(), \fIwcstoul\fP(), \fIwcstoull\fP(), +\fIwcswcs\fP(), \fIwcswidth\fP(), \fIwcsxfrm\fP(), \fIwctob\fP(), +\fIwctype\fP(), \fIwcwidth\fP(), \fIwmemchr\fP(), \fIwmemcmp\fP(), +\fIwmemcpy\fP(), \fIwmemmove\fP(), \fIwmemset\fP(), \fIwprintf\fP(), +\fIwscanf\fP(), the Shell and Utilities volume of IEEE\ Std\ 1003.1-2001, +\fIgetconf\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/wctype.h.0p b/man0p/wctype.h.0p new file mode 100644 index 000000000..7da721e8d --- /dev/null +++ b/man0p/wctype.h.0p @@ -0,0 +1,108 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +wctype.h \- wide-character classification and mapping utilities +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +Some of the functionality described on this reference page extends +the ISO\ C standard. Applications shall define +the appropriate feature test macro (see the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, Section 2.2, The Compilation Environment) +to enable the visibility of these symbols in this +header. +.LP +The \fI\fP header shall define the following types: +.TP 7 +\fBwint_t\fP +As described in \fI\fP . +.TP 7 +\fBwctrans_t\fP +A scalar type that can hold values which represent locale-specific +character mappings. +.TP 7 +\fBwctype_t\fP +As described in \fI\fP . +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint iswalnum(wint_t); +int iswalpha(wint_t); +int iswblank(wint_t); +int iswcntrl(wint_t); +int iswdigit(wint_t); +int iswgraph(wint_t); +int iswlower(wint_t); +int iswprint(wint_t); +int iswpunct(wint_t); +int iswspace(wint_t); +int iswupper(wint_t); +int iswxdigit(wint_t); +int iswctype(wint_t, wctype_t); +wint_t towctrans(wint_t, wctrans_t); +wint_t towlower(wint_t); +wint_t towupper(wint_t); +wctrans_t wctrans(const char *); +wctype_t wctype(const char *); +\fP +.fi +.RE +.LP +The \fI\fP header shall define the following macro name: +.TP 7 +WEOF +Constant expression of type \fBwint_t\fP that is returned by several +MSE functions to indicate end-of-file. +.sp +.LP +For all functions described in this header that accept an argument +of type \fBwint_t\fP, the value is representable as a +\fBwchar_t\fP or equals the value of WEOF. If this argument has any +other value, the behavior is undefined. +.LP +The behavior of these functions shall be affected by the \fILC_CTYPE\fP +category of the current locale. +.LP +Inclusion of the \fI\fP header may make visible all symbols +from the headers \fI\fP, \fI\fP, \fI\fP, +\fI\fP, \fI\fP, \fI\fP, \fI\fP, +and \fI\fP. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , \fI\fP , \fI\fP , \fI\fP +, \fI\fP , \fI\fP , \fI\fP , \fI\fP +, \fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIiswalnum\fP(), \fIiswalpha\fP(), \fIiswblank\fP(), \fIiswcntrl\fP(), +\fIiswctype\fP(), \fIiswdigit\fP(), \fIiswgraph\fP(), \fIiswlower\fP(), +\fIiswprint\fP(), \fIiswpunct\fP(), \fIiswspace\fP(), \fIiswupper\fP(), +\fIiswxdigit\fP(), \fIsetlocale\fP(), \fItowctrans\fP(), \fItowlower\fP(), +\fItowupper\fP(), \fIwctrans\fP(), \fIwctype\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man0p/wordexp.h.0p b/man0p/wordexp.h.0p new file mode 100644 index 000000000..12e69cd5e --- /dev/null +++ b/man0p/wordexp.h.0p @@ -0,0 +1,124 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH NAME +wordexp.h \- word-expansion types +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The \fI\fP header shall define the structures and symbolic +constants used by the \fIwordexp\fP() and \fIwordfree\fP() functions. +.LP +The structure type \fBwordexp_t\fP shall contain at least the following +members: +.sp +.RS +.nf + +\fBsize_t we_wordc \fP Count of words matched by \fIwords.\fP \fB +char **we_wordv \fP Pointer to list of expanded words. \fB +size_t we_offs \fP Slots to reserve at the beginning of \fIwe_wordv.\fP \fB +\fP +.fi +.RE +.LP +The \fIflags\fP argument to the \fIwordexp\fP() function shall be +the +bitwise-inclusive OR of the following flags: +.TP 7 +WRDE_APPEND +Append words to those previously generated. +.TP 7 +WRDE_DOOFFS +Number of null pointers to prepend to \fIwe_wordv\fP. +.TP 7 +WRDE_NOCMD +Fail if command substitution is requested. +.TP 7 +WRDE_REUSE +The \fIpwordexp\fP argument was passed to a previous successful call +to \fIwordexp\fP(), and has not been passed to \fIwordfree\fP(). The +result is the same as if the application had called \fIwordfree\fP() +and then called \fIwordexp\fP() without +WRDE_REUSE. +.TP 7 +WRDE_SHOWERR +Do not redirect \fIstderr\fP to \fB/dev/null\fP. +.TP 7 +WRDE_UNDEF +Report error on an attempt to expand an undefined shell variable. +.sp +.LP +The following constants shall be defined as error return values: +.TP 7 +WRDE_BADCHAR +One of the unquoted characters- , \fB'|'\fP , \fB'&'\fP , +\fB';'\fP , \fB'<'\fP , +\fB'>'\fP , \fB'('\fP , \fB')'\fP , \fB'{'\fP , \fB'}'\fP - appears +in \fIwords\fP in an inappropriate +context. +.TP 7 +WRDE_BADVAL +Reference to undefined shell variable when WRDE_UNDEF is set in \fIflags\fP. +.TP 7 +WRDE_CMDSUB +Command substitution requested when WRDE_NOCMD was set in \fIflags\fP. +.TP 7 +WRDE_NOSPACE +Attempt to allocate memory failed. +.TP 7 +WRDE_NOSYS +Reserved. +.TP 7 +WRDE_SYNTAX +Shell syntax error, such as unbalanced parentheses or unterminated +string. +.sp +.LP +The \fI\fP header shall define the following type: +.TP 7 +\fBsize_t\fP +As described in \fI\fP . +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint wordexp(const char *restrict, wordexp_t *restrict, int); +void wordfree(wordexp_t *); +\fP +.fi +.RE +.LP +The implementation may define additional macros or constants using +names beginning with WRDE_. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fI\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIwordexp\fP(), the Shell and Utilities volume of IEEE\ Std\ 1003.1-2001 +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1/README b/man1/README new file mode 100644 index 000000000..31db496fa --- /dev/null +++ b/man1/README @@ -0,0 +1,22 @@ +In his wisdom RMS decided that people need no man pages +when they can use GNU's beautiful info system. +Unfortunately, everybody I know greatly prefers man pages. + +Since GNU actively non-maintains man pages, and inserts +text to the effect that you should not be reading them +in each man page that they already have, it seems that +outside maintenance of man pages for the GNU utilities +is required. + +The fileutils-3.16 man pages found here have been derived +from those in fileutils-3.16-man-0.4.tar.gz +(as produced by Ragnar Hojland Espinosa and A. Wik, and +found on ftp://mail1.bet1.puv.fi/incoming/) +by adding information on what POSIX says about these +utilities. This is very useful if you have to write +scripts that should be portable. + +There is also a time.1 man page here, inspired by +kromJx@crosswinds.net. + +Andries diff --git a/man1/chgrp.1 b/man1/chgrp.1 new file mode 100644 index 000000000..131eedb61 --- /dev/null +++ b/man1/chgrp.1 @@ -0,0 +1,121 @@ +.\" Copyright Andries Brouwer, 2000 +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.TH CHGRP 1 2000-08 "GNU fileutils 4.0" +.SH NAME +chgrp \- change group ownership of files +.SH SYNOPSIS +.BI "chgrp [" options "] " "group file..." +.sp +POSIX options: +.B "[\-R] [\-\-]" +.sp +POSIX 1003.1-2001 options: +.B [\-hHLPR] +.sp +GNU group denotation: +.BI [\-\-reference= rfile ] +.sp +GNU options (shortest form): +.B [\-cfvR] +.B "[\-\-help] [\-\-version] [\-\-]" +.SH DESCRIPTION +.B chgrp +changes the group ownership of each given +.I file +to +.IR group , +which can be either a group name or a numeric group ID. +.SH "POSIX OPTIONS" +.TP +.B \-R +Recursively change the group ownership of directories and their contents. +(And continue even when errors are encountered.) +.TP +.B "\-\-" +Terminate option list. +.SH "AUSTIN DRAFT OPTIONS" +.TP +.B \-h +For each file operand given that is a symlink, change the group ownership +of the symlink itself, rather than the object it points to. If the system +does not support a group ownership for symlinks, do nothing for a symlink. +.TP +.BR \-H " (half-logical)" +(When given together with +.BR \-R .) +For each file operand given that is a symlink to a directory, +change the group ownership of the directory and all files in the +file hierarchy below it. +.TP +.BR \-L " (logical)" +(When given together with +.BR \-R .) +For each file, either command line operand or encountered during +the tree walk, that is a symlink to a directory, +change the group ownership of the directory and all files in the +file hierarchy below it. +.TP +.BR \-P " (physical)" +(When given together with +.BR \-R .) +For each file, either command line operand or encountered during +the tree walk, that is a symlink, change the group ownership +of the symlink itself, rather than the object it points to. +If the system does not support a group ownership for symlinks, +do nothing for a symlink. This is the default. +.TP +.BR \-R +Recursively change the group ownership of directories and their contents. +.SH "ADDITIONAL GNU DESCRIPTION" +A GNU extension (new in fileutils 4.0) allows one to use +.BI "\-\-reference=" "rfile" +as a group description: the same group as that of +.IR rfile . +.SH "GNU OPTIONS" +.TP +.B "\-c, \-\-changes" +Verbosely describe the action for each +.I file +whose group actually changes. +.TP +.B "\-f, \-\-silent, \-\-quiet" +Do not print error messages about files whose group cannot be changed. +.TP +.B "\-h, \-\-no\-dereference" +Act on symbolic links themselves instead of what they point to. +Only available if the +.B lchown +system call is provided. +.TP +.B "\-v, \-\-verbose" +Verbosely describe the action or non-action taken for every +.IR file . +.TP +.B "\-R, \-\-recursive" +Recursively change the group ownership of directories and their contents. +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variables LANG, LC_ALL, LC_CTYPE and LC_MESSAGES have the +usual meaning. For an XSI-conforming system: NLSPATH has the +usual meaning. +.SH "CONFORMING TO" +POSIX 1003.2 only requires the \-R option. Use of other options +may not be portable. +.SH NOTES +This page describes +.B chgrp +as found in the fileutils-4.0 package; +other versions may differ slightly. diff --git a/man1/chmod.1 b/man1/chmod.1 new file mode 100644 index 000000000..4f047aad7 --- /dev/null +++ b/man1/chmod.1 @@ -0,0 +1,160 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.\" Modified 2004-06-17, Michael Kerrisk +.\" +.TH CHMOD 1 2004-06-17 "GNU fileutils 4.0" +.SH NAME +chmod \- change access permissions of files +.SH SYNOPSIS +.BI "chmod [" options "] " "mode file..." +.sp +POSIX options: +.B "[\-R] [\-\-]" +.sp +GNU mode denotation: +.BI [\-\-reference= rfile ] +.sp +GNU options (shortest form): +.B [\-cfvR] +.B "[\-\-help] [\-\-version] [\-\-]" +.SH DESCRIPTION +.B chmod +changes the permissions of each given +.I file +according to +.IR mode , +which can be either a symbolic representation of changes to make, or +an octal number representing the bit pattern for the new permissions. +.PP +The format of a symbolic mode change argument is +.br +\&`[ugoa...][[+\-=][rwxXstugo...]...][,...]'. +.PP +Such an argument is a list of symbolic mode change commands, +separated by commas. +Each symbolic mode change command starts with zero or more +of the letters `ugoa'; these control which users' access to +the file will be changed: the user who owns it (u), other users in the +file's group (g), other users not in the file's group (o), or all +users (a). Thus, `a' is here equivalent to `ugo'. +If none of these are given, the effect is as if `a' were +given, but bits that are set in the umask are not affected. +.PP +The operator `+' causes the permissions selected to be added to the +existing permissions of each file; `\-' causes them to be removed; +and `=' causes them to be the only permissions that the file has. +.PP +The letters `rwxXstugo' select the new permissions for the affected +users: read (r), write (w), execute (or access for directories) (x), +execute only if the file is a directory or already has execute +permission for some user (X), set user or group ID on execution (s), +sticky bit (t), the permissions that the user +who owns the file currently has for it (u), the permissions that other +users in the file's group have for it (g), and the permissions that +other users not in the file's group have for it (o). +(Thus, `chmod g\-s file' removes the set-group-ID (sgid) bit, +\&`chmod ug+s file' sets both the suid and sgid bits, while +\&`chmod o+s file' does nothing.) +.PP +The name of the `sticky bit' derives from the original meaning: +keep program text on swap device. +These days, when set for a directory, it means that +only the owner of the file and the owner of that directory +may remove the file from that directory. +(This is commonly used on directories like /tmp that have +general write permission.) +.PP +A numeric mode is from one to four octal digits (0-7), derived by +adding up the bits with values 4, 2, and 1. Any omitted digits are +assumed to be leading zeros. The first digit selects the set user ID +(4) and set group ID (2) and save text image [`sticky'] (1) attributes. +The second digit selects permissions for the user who owns the file: read +(4), write (2), and execute (1); the third selects permissions for +other users in the file's group, with the same values; and the fourth +for other users not in the file's group, with the same values. +.PP +.B chmod +never changes the permissions of symbolic links, since the +.B chmod +system call cannot change their permissions. This is not a problem +since the permissions of symbolic links are never used. However, for +each symbolic link listed on the command line, +.B chmod +changes the permissions of the pointed-to file. In contrast, +.B chmod +ignores symbolic links encountered during recursive directory traversals. +.SH "POSIX OPTIONS" +.TP +.B "\-R" +Recursively change permissions of directories and their contents. +.TP +.B "\-\-" +Terminate option list. +.SH "ADDITIONAL GNU DESCRIPTION" +A GNU extension (new in fileutils 4.0) allows one to use +.BI "\-\-reference=" "rfile" +as a mode description: the same mode as that of +.IR rfile . +.SH "GNU OPTIONS" +.TP +.B "\-c, \-\-changes" +Verbosely describe the action for each +.I file +whose permissions actually changes. +.TP +.B "\-f, \-\-silent, \-\-quiet" +Do not print error messages about files whose permissions cannot be changed. +.TP +.B "\-v, \-\-verbose" +Verbosely describe the action or non-action taken for every +.IR file . +.TP +.B "\-R, \-\-recursive" +Recursively change permissions of directories and their contents. +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variables LANG, LC_ALL, LC_CTYPE and LC_MESSAGES have the +usual meaning. For an XSI-conforming system: NLSPATH has the +usual meaning. +.SH "CONFORMING TO" +POSIX 1003.2 only requires the \-R option. Use of other options +may not be portable. This standard does not describe the 't' permission +bit. This standard does not specify whether \fBchmod\fP must preserve +consistency by clearing or refusing to set the suid and sgid +bits, e.g., when all execute bits are cleared, or whether \fBchmod\fP +honors the `s' bit at all. +.SH "NONSTANDARD MODES" +Above we described the use of the `t' bit on directories. +Various systems attach special meanings to otherwise +meaningless combinations of mode bits. +In particular, Linux, following System V (see +System V Interface Definition (SVID) Version 3), +lets the sgid bit for files without group execute permission +mark the file for mandatory locking. For more details, see +the file +.IR /usr/src/linux/Documentation/mandatory.txt . +.SH NOTES +This page describes +.B chmod +as found in the fileutils-4.0 package; +other versions may differ slightly. +.SH "SEE ALSO" +.BR chattr (1), +.BR chown (1), +.BR install (1), +.BR chmod (2), +.BR stat (2), +.BR umask (2) diff --git a/man1/chown.1 b/man1/chown.1 new file mode 100644 index 000000000..02c89b406 --- /dev/null +++ b/man1/chown.1 @@ -0,0 +1,103 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.TH CHOWN 1 1998-11 "GNU fileutils 4.0" +.SH NAME +chown \- change file owner and group +.SH SYNOPSIS +.BI "chown [" options "] " user "[:" group "] " file... +.sp +POSIX options: +.B "[\-R] [\-\-]" +.sp +GNU options (shortest form): +.B "[\-cfhvR] [\-\-dereference]" +.BI [\-\-reference= rfile ] +.B "[\-\-help] [\-\-version] [\-\-]" +.SH DESCRIPTION +.B chown +changes the user and/or group ownership of each given +.I file +as specified by the first non-option argument +as follows: if only a user name (or numeric user ID) is given, +that user is made the owner of each given file, and the files' group is +not changed. If the user name is followed by a colon and a group +name (or numeric group ID), with no spaces between them, the group ownership +of the files is changed as well. +.SH "GNU DETAILS" +The GNU version allows a dot instead of a colon (following BSD). +[This was not allowed by POSIX since a dot is a valid character +in a user name.] +If a colon or dot but no group name follows +the user name, that user is made the owner of the files and the group of the +files is changed to that user's login group. If the colon or dot and group +are given, but the user name is omitted, only the group of the files is +changed; in this case, +.B chown +performs the same function as +.BR chgrp . +.SH "POSIX OPTIONS" +.TP +.B "\-R" +Recursively change ownership of directories and their contents. +.TP +.B "\-\-" +Terminate option list. +.SH "GNU OPTIONS" +.TP +.B "\-c, \-\-changes" +Verbosely describe the action for each +.I file +whose ownership actually changes. +.TP +.B "\-f, \-\-silent, \-\-quiet" +Do not print error messages about files whose ownership cannot be changed. +.TP +.B "\-h, \-\-no\-dereference" +Act on symbolic links themselves instead of what they point to. +Only available if the +.B lchown +system call is provided. +.TP +.B "\-v, \-\-verbose" +Verbosely describe the action (or non-action) taken for every +.IR file . +.TP +.B "\-R, \-\-recursive" +Recursively change ownership of directories and their contents. +.TP +.B \-\-dereference +Change the ownership of the target of a symbolic link instead of the +symbolic link itself. +(New in file\%utils-4.0.) +.TP +.BI "\-\-reference=" "rfile" +(New in file\%utils 4.0.) +Change the ownership of +.I file +to that of +.IR rfile . +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variables LANG, LC_ALL, LC_CTYPE and LC_MESSAGES have the +usual meaning. +.SH "CONFORMING TO" +POSIX 1003.2 does not allow use of the dot as separator +between user name and group name. +.SH NOTES +This page describes +.B chown +as found in the fileutils-4.0 package; +other versions may differ slightly. diff --git a/man1/cp.1 b/man1/cp.1 new file mode 100644 index 000000000..0f95c4e69 --- /dev/null +++ b/man1/cp.1 @@ -0,0 +1,392 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" Distributed under GPL. +.\" +.TH CP 1 2003-11 "GNU fileutils 4.1" +.SH NAME +cp \- copy files and directories +.SH SYNOPSIS +.BI "cp [" "options" "] " "file path" +.br +.BI "cp [" "options" "] " "file... directory" +.sp +POSIX options: +.B "[\-fiprR] [\-\-]" +.sp +Additional POSIX 1003.1-2003 options: +.B "[\-HLP] +.sp +GNU file-utils 4.0 options (shortest form): +.br +.B [\-abdfilprsuvxPR] +.BI "[\-S " SUFFIX ] +.B "[\-V {numbered,existing,simple}]" +.BI [\-\-backup= CONTROL ] +.BI [\-\-sparse= WHEN ] +.B "[\-\-help] [\-\-version] [\-\-]" +.sp +Additional GNU file-utils 4.1 options (shortest form): +.br +.B [\-HLP] +.B [\-\-copy\-contents] +.B [\-\-no\-preserve] +.BI [\-\-reply= HOW ] +.B [\-\-remove\-destination] +.B [\-\-strip\-trailing\-slashes] +.BI [\-\-target\-directory= DIR ] +.SH DESCRIPTION +.B cp +copies files (or, optionally, directories). +You can either copy one file to a given destination, +or copy arbitrarily many files to a destination directory. +.PP +If the last argument names an existing directory, +.B cp +copies each source +.I file +into that directory (retaining the same name). Otherwise, +if only two files are given, it copies the first onto the second. It +is an error if the last argument is not a directory and more than two +non-option arguments are given. +.PP +(Thus, if /a is a directory, then `cp \-r /a /b' will copy /a to /b/a +and /a/x to /b/a/x in case a directory /b existed already, but it will +copy /a to /b and /a/x to /b/x if there was no /b beforehand, +while it will fail in case there was an ordinary file /b.) +.PP +The modes of the files and directories created will be the same +as those of the original files, ANDed by 0777, and modified by +the user's umask (unless the \-p option was specified). +(But during the recursive copy of directories, newly created +directories will temporarily get their final mode ORed with +S_IRWXU (0700), so as to allow the process to read, write +and search the newly created directory.) +.PP +Nothing is done when copying a file to itself (except possibly +producing an error message). +When copying to a different existing file, it is opened +using `open(path, O_WRONLY | O_TRUNC)'. +When copying to a new file it is created +using `open(path, O_WRONLY | O_CREAT, mode)'. +If this fails, the file existed, and the \-f option was given, +.B cp +tries to delete (unlink) the existing file, and if this succeeds +proceeds as for a new file. + +.SH "POSIX OPTIONS" +POSIX recognizes four options and a half: +.TP +.B \-f +Remove existing destination files if required. (See above.) +.TP +.B \-i +Prompt whether to overwrite existing regular destination files. +(Write a question on stderr, and read the answer from stdin. +Only copy upon an affirmative answer.) +.TP +.B \-p +Preserve the original files' owner, group, permissions +(including the setuid and setgid bits), time of last modification +and time of last access. +In case duplication of owner or group fails, the setuid and setgid +bits are cleared. +(Note that afterwards source and copy may well have different +times of last access, since the copy operation is an access +to the source file.) +.TP +.B \-R +Copy directories recursively, and do the right thing when +objects other than ordinary files or directories are encountered. +(Thus, the copy of a FIFO or special file is a FIFO or special file.) +.TP +.B \-r +Copy directories recursively, and do something unspecified +with objects other than ordinary files or directories. +(Thus, it is allowed, in fact encouraged, to have the \-r option +a synonym for \-R. However, silly behaviour, like that of the +GNU 4.0 version of +.BR cp +is not forbidden.) +.TP +.B "\-\-" +Terminate option list. +.SH "ADDITIONAL POSIX 2003 OPTIONS" +POSIX 1003.1-2003 adds three options that specify how to handle +symbolic links. When doing a non-recursive copy, symbolic links +are followed. When doing a recursive copy using the \-r option, +the results are implementation-defined. When doing a recursive +copy using the \-R option: +.TP +.B \-H +Follow the symbolic links given in the parameter list. +Do not follow symbolic links encountered during the recursive copy, +but just copy them as symbolic link. +.TP +.B \-L +Follow all symbolic links, both those that occur in the parameter list +and those encountered during the recursive copy. +.TP +.B \-P +Do not follow any symbolic links, neither those that occur +in the parameter list nor those encountered during the recursive copy. +Just copy them as symbolic link. +.LP +There is no default - one should specify the desired behaviour. +.SH "GNU DETAILS" +.PP +Generally, files are written just as they are read. For exceptions, +see the +.B "\-\-sparse" +option below. +.PP +By default, `cp' does not copy directories (see +.B "\-r" +below). +.PP +.B cp +generally refuses to copy a file onto itself, with the following +exception: if +.B "\-\-force \-\-backup" +is specified with +.I source +and +.I dest +identical, and referring to a regular file, +.B cp +will make a backup file, either regular or numbered, as specified in +the usual ways. This is useful when you simply want to make a backup +of an existing file before changing it. +.PP +By default, symbolic links are not followed. +.SH "GNU OPTIONS" +.TP +.B "\-a, \-\-archive" +Preserve as much as possible of the structure and attributes of the +original files in the copy (but do not preserve directory structure). +Equivalent to +.BR "\-dpPR" . +.TP +.B "\-b" +See the discussion of backups below. +.TP +.BR "\-\-copy\-contents" " (since file-utils 4.1)" +Do the silly things file-utils 4.0 did, +trying to copy the contents of device files and FIFOs during +a recursive copy. Never use this option. With it, `cp' may well hang +indefinitely reading a FIFO or /dev/tty, or fill the destination disk +copying /dev/zero. +.TP +.B "\-d" +Copy symbolic links as symbolic links rather than copying the +files that they point to, and preserve hard links between source +files in the copies. + +With file-utils 4.0 the long option \-\-no\-dereference was a +synonym for \-d, with file-utils 4.1 it is a synonym for \-P, +while \-d is equivalent to \-\-no\-dereference \-\-preserve=links. +.TP +.B "\-f, \-\-force" +Remove existing destination files in case an open for writing fails, +and never prompt before doing so. +(Thus since file-utils 4.1. With file-utils 4.0 this option was +equivalent to the new \-\-remove\-destination.) +.TP +.BR "\-H" " (since file-utils 4.1)" +See POSIX description above. +.TP +.B "\-i, \-\-interactive" +Prompt whether to overwrite existing regular destination files. +.TP +.B "\-l, \-\-link" +Make hard links instead of copies of non-directories. +.TP +.BR "\-L, \-\-dereference" " (since file-utils 4.1)" +See POSIX description above. +.TP +.BR "\-\-no\-preserve=\fIATTRIBUTES\fP" " (since file-utils 4.1)" +Do not preserve the specified attributes. +See the \-\-preserve option below. +.TP +.B "\-p, \-\-preserve" +Preserve the original files' owner, group, permissions, and timestamps. +.TP +.BR "\-\-preserve=\fIATTRIBUTES\fP" " (since file-utils 4.1)" +Here ATTRIBUTES can be one of "mode" (permissions), "ownership" (owner +and group), "timestamps", "links", "all" (all of the foregoing). +.TP +.BR "\-P, \-\-no\-dereference" " (since file-utils 4.1)" +See POSIX description above. +This replaces the file-utils 4.0 meaning of the \-P option, that +was a synonym for \-\-parents. See also \-d above. +.TP +.BR "\-\-parents" " (in file-utils 4.0 also \-P)" +Form the name of each destination file by appending to the target +directory a slash and the specified name of the source file. The +last argument given to +.B cp +must be the name of an existing directory. For example, the command: +.br +.nf + cp \-\-parents a/b/c existing_dir +.br +.fi +copies the file `a/b/c' to `existing_dir/a/b/c', creating any +missing intermediate directories. +.TP +.B "\-r" +In file-utils 4.1: synonym of \-R. +In file-utils 4.0: +Copy directories recursively, copying any non-directories and +non-symbolic links (that is, FIFOs and special files) as if they +were regular files. This silly behaviour is obtained in file-utils 4.1 +if the \-\-copy\-contents option is given. +.TP +.B "\-R, \-\-recursive" +Copy directories recursively, preserving non-directories. +.TP +.BR "\-\-reply=\fIHOW\fP" " (since file-utils 4.1)" +Here HOW can be one of "yes", "no", "query", specifying that +to all questions the answer is yes, or is no, or must be obtained +by querying the user, respectively. +.TP +.BR "\-\-remove\-destination" " (since file-utils 4.1)" +Remove each existing destination file before copying. +With file-utils 4.0 this option was implied by \-f. +.TP +.BI "\-\-sparse=" "WHEN" +A `sparse file' contains `holes' - sequences of zero bytes that +do not occupy any physical disk blocks; the `read' system call +reads these as zeroes. This can both save considerable disk space +and increase speed, since many binary files contain lots of +consecutive zero bytes. By default, +.B cp +detects holes in input source files via a crude heuristic +and makes the corresponding output file sparse as well. +.RS +.PP +The +.I WHEN +value can be one of the following: +.TP +.B auto +The default behavior: the output file is sparse if the input +file is sparse. +.TP +.B always +Always make the output file sparse. This is useful when the +input file resides on a filesystem that does not support +sparse files, but the output file is on a filesystem that does. +.TP +.B never +Never make the output file sparse. If you find an application for +this option, let us know. +.RE +.TP +.BR "\-\-strip\-trailing\-slashes" " (since file-utils 4.1)" +Remove any trailing slashes from each source argument. +(This can change the interpretation in case of a symbolic link +to a directory.) +.TP +.B "\-s, \-\-symbolic\-link" +Make symbolic links instead of copies of non-directories. All +source file names must be absolute (starting with `/') unless the +destination files are in the current directory. This option merely +results in an error message on systems that do not support +symbolic links. +.TP +.B "\-S" +Backup suffix, see below. +.TP +.BR "\-\-target\-directory=\fIDIR\fP" " (since file-utils 4.1)" +Specify the destination directory. Meant for use with +.BR xargs (1), +as in "ls | xargs cp --target-directory=../d". +.TP +.B "\-u, \-\-update" +Do not copy a nondirectory that has an existing destination with +the same or newer modification time. +.TP +.B "\-v, \-\-verbose" +Print the name of each file before copying it. +.TP +.B "\-x, \-\-one\-file\-system" +Skip subdirectories that are on different filesystems from the one +that the copy started on. +.SH "GNU BACKUP OPTIONS" +The GNU versions of programs like +.BR cp , +.BR mv , +.BR ln , +.B install +and +.B patch +will make a backup of files about to be overwritten, changed or destroyed +if that is desired. That backup files are desired is indicated by +the \-b option. How they should be named is specified by the \-V option. +In case the name of the backup file is given by the name of the file +extended by a suffix, this suffix is specified by the \-S option. +.TP +.B "\-b, \-\-backup" +Make backups of files that are about to be overwritten or removed. +.TP +.BI \-\-backup= CONTROL +(Since fileutils-4.1.) +.TP +.BI "\-S " SUFFIX ", \-\-suffix=" SUFFIX +Append +.I SUFFIX +to each backup file made. +If this option is not specified, the value of the +.B SIMPLE_BACKUP_SUFFIX +environment variable is used. And if +.B SIMPLE_BACKUP_SUFFIX +is not set, the default is `~'. +.TP +.BI "\-V " METHOD ", \-\-version\-control=" METHOD +.RS +Specify how backup files are named. The +.I METHOD +argument can be `numbered' (or `t'), `existing' (or `nil'), or `never' (or +`simple'). +If this option is not specified, the value of the +.B VERSION_CONTROL +environment variable is used. And if +.B VERSION_CONTROL +is not set, the default backup type is `existing'. +.PP +This option corresponds to the Emacs variable `version-control'. +The valid +.IR METHOD s +are (unique abbreviations are accepted): +.TP +.BR t ", " numbered +Always make numbered backups. +.TP +.BR nil ", " existing +Make numbered backups of files that already have them, simple +backups of the others. +.TP +.BR never ", " simple +Always make simple backups. +.RE +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variables LANG, LC_ALL, LC_COLLATE, LC_CTYPE and LC_MESSAGES have the +usual meaning. For the GNU version, the variables SIMPLE_BACKUP_SUFFIX +and VERSION_CONTROL control backup file naming, as described above. +.SH "CONFORMING TO" +POSIX 1003.2 +.SH NOTES +This page describes +.B cp +as found in the fileutils-4.1 package; +other versions may differ slightly. diff --git a/man1/dd.1 b/man1/dd.1 new file mode 100644 index 000000000..f186b7faf --- /dev/null +++ b/man1/dd.1 @@ -0,0 +1,220 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.TH DD 1 1998-11 "GNU fileutils 4.0" +.SH NAME +dd \- convert and copy a file +.SH SYNOPSIS +.B dd +.B [\-\-help] [\-\-version] +.BI [if= file ] +.BI [of= file ] +.BI [ibs= bytes ] +.BI [obs= bytes ] +.BI [bs= bytes ] +.BI [cbs= bytes ] +.BI [skip= blocks ] +.BI [seek= blocks ] +.BI [count= blocks ] +.B "[conv={ascii, ebcdic, ibm, block, unblock, lcase, ucase, swab, noerror, notrunc, sync}]" +.SH DESCRIPTION +.B dd +copies a file (from standard input to standard output, by +default) using specific input and output blocksizes, +while optionally performing conversions on it. +.PP +It reads the input one block at a time, using the specified input +block size (the default is 512 bytes). +If the +.BI bs= bytes +option was given, and no conversion other than +.BR sync ", " noerror ", or " notrunc +was specified, it writes the amount of data read (which could be smaller +than what was requested) in a separate output block. This output block +has precisely the same length as was read unless the +.B sync +conversion was specified, in which case the data is padded with NULs +(or spaces, see below). +.PP +Otherwise, the input, read one block at a time, is processed +and the resulting output is collected and written in blocks +of the specified output block size. The final output block +may be shorter. +.PP +The numeric-valued options below (bytes and blocks) can be followed +by a multiplier: `k'=1024, `b'=512, `w'=2, `c'=1 +(`w' and `c' are GNU extensions; `w' should never be used - +it means 2 in System V and 4 in 4.2BSD). +Two or more of such numeric expressions can be multiplied +by putting `x' in between. +The GNU fileutils-4.0 version also allows the following multiplicative suffixes +in the specification of blocksizes (in bs=, cbs=, ibs=, obs=): +M=1048576, G=1073741824, and so on for T, P, E, Z, Y. +A `D' suffix makes them decimal: +kD=1000, MD=1000000, GD=1000000000, etc. +(Note that for ls, df, du the size of M etc. is determined by environment +variables, but for dd it is fixed.) +.SH OPTIONS +.TP +.BI "if=" file +Read from +.I file +instead of standard input. +.TP +.BI "of=" file +Write to +.I file +instead of standard output. Unless +.B conv=notrunc +is given, +.B dd +truncates +.I file +to zero bytes (or the size specified with +.BR seek= ")." +.TP +.BI "ibs=" bytes +Read +.I bytes +bytes at a time. The default is 512. +.TP +.BI "obs=" bytes +Write +.I bytes +bytes at a time. The default is 512. +.TP +.BI "bs=" bytes +Both read and write +.I bytes +bytes at a time. This overrides +.B ibs +and +.BR obs . +(And setting +.B bs +is not equivalent with setting both +.B ibs +and +.B obs +to this same value, at least when no conversion other than +.BR sync , +.B noerror +and +.B notrunc +is specified, since it stipulates that each input block +shall be copied to the output as a single block +without aggregating short blocks.) +.TP +.BI "cbs=" bytes +Specify the conversion block size for +.B block +and +.BR unblock . +.TP +.BI "skip=" blocks +Skip +.I blocks +.BR ibs -byte +blocks in the input file before copying. +.TP +.BI "seek=" blocks +Skip +.I blocks +.BR obs -byte +blocks in the output file before copying. +.TP +.BI "count=" blocks +Copy +.I blocks +.BR ibs -byte +blocks from the input file, instead of everything +until the end of the file. +.TP +.BI "conv=" CONVERSION "[," CONVERSION "]..." +Convert the file as specified by the +.I CONVERSION +argument(s). (No spaces around any comma(s).) +.RS +.PP +Conversions: +.PP +.TP +.B ascii +Convert EBCDIC to ASCII. +.TP +.B ebcdic +Convert ASCII to EBCDIC. +.TP +.B ibm +Convert ASCII to alternate EBCDIC. +.TP +.B block +For each line in the input, output +.B cbs +bytes, replacing the input newline with a space and padding +with spaces as necessary. +.TP +.B unblock +Replace trailing spaces in each +.BR cbs -sized +input block with a newline. +.TP +.B lcase +Change uppercase letters to lowercase. +.TP +.B ucase +Change lowercase letters to uppercase. +.TP +.B swab +Swap every pair of input bytes. +If an odd number of bytes are read the last byte +is simply copied (since there is nothing to swap it with). +[POSIX 1003.2b, PASC interpretations 1003.2 #3 and #4] +.TP +.B noerror +Continue after read errors. +.TP +.B notrunc +Do not truncate the output file. +.TP +.B sync +Pad every input block to size of +.B ibs +with trailing zero bytes. +.RE +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variables LANG, LC_ALL, LC_CTYPE and LC_MESSAGES have the +usual meaning. +.SH "CONFORMING TO" +POSIX 1003.2 +.SH EXAMPLE +Often a tape drive will not accept arbitrarily sized blocks, and +.B dd +would get an I/O error for the last fragment of data that does not +fill an entire block. Use `dd if=myfile of=/dev/mytape conv=sync' +to get everything on tape. Of course, reading it back will now +produce a slightly larger file, with nulls added at the end. +.SH BUGS +Commands like `dd if=myfile of=/dev/fd0 bs=1k seek=172' fail +on some systems because +.B dd +tries to truncate the output file, but truncation of a block device +is not possible. In such cases, add the `conv=notrunc' option. +.SH NOTES +This page describes +.B dd +as found in the fileutils-4.0 package; +other versions may differ slightly. diff --git a/man1/df.1 b/man1/df.1 new file mode 100644 index 000000000..3c5a32693 --- /dev/null +++ b/man1/df.1 @@ -0,0 +1,195 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.TH DF 1 1998-11 "GNU fileutils 4.0" +.SH NAME +df \- report filesystem disk space usage +.SH SYNOPSIS +.BI "df [" options "] [" file... ] +.sp +POSIX options: +.B "[\-kP] [\-\-]" +.sp +GNU options (shortest form): +.B [\-ahHiklmPv] +.BI "[\-t " fstype ] +.BI "[\-x " fstype ] +.BI "[\-\-block\-size=" size ] +.B [\-\-print\-type] +.B [\-\-no\-sync] +.B [\-\-sync] +.B "[\-\-help] [\-\-version] [\-\-]" +.SH DESCRIPTION +.B df +reports the amount of disk space used and available on +filesystems. +.PP +With no arguments, +.B df +reports the space used and available on all +currently mounted filesystems (of all types). +Otherwise, +.B df +reports on the filesystem containing each argument +.IR file . +.SH "POSIX DETAILS" +The output is in 512-byte units by default, but in +1024-byte units when the \-k option is given. +The output format is undefined, unless the \-P option is given. +If +.I file +is not a regular file, a directory or a FIFO, the result +is unspecified. +.SH "GNU DETAILS" +The output is in 1024-byte units (when no units are +specified by options), unless the environment variable +.B POSIXLY_CORRECT +is set, in which case POSIX is followed. +.PP +If an argument +.I file +is a disk device file containing a mounted filesystem, +.B df +shows the space available on that filesystem rather +than on the filesystem containing the device node. +.SH "POSIX OPTIONS" +.TP +.B "\-k" +Use 1024-byte units instead of the default 512-byte units. +.TP +.B "\-P" +Output in six columns, with heading `Filesystem N-blocks +Used Available Capacity Mounted on' (with N=512, but N=1024 +when the \-k option is given). +.TP +.B "\-\-" +Terminate option list. +.SH "GNU OPTIONS" +.TP +.B "\-a, \-\-all" +Include in the listing filesystems that have a size of 0 blocks, +which are omitted by default. Such filesystems are typically +special-purpose pseudo-filesystems, such as automounter entries. +Also, filesystems of type "ignore" or "auto", supported by some +operating systems, are only included if this option is specified. +.TP +.BI "\-\-block\-size=" size +Print sizes in blocks of +.I size +bytes. (New but broken in fileutils-4.0.) +.TP +.B "\-h, \-\-human\-readable" +Append a size letter such as +.B M +for binary megabytes (`mebibytes') to each size. +.TP +.B "\-H, \-\-si" +Do the same as for +.BR \-h , +but use the official SI units (with powers of 1000 instead of 1024, +so that M stands for 1000000 instead of 1048576). +(New in fileutils-4.0.) +.TP +.B "\-i, \-\-inodes" +List inode usage information instead of block usage. An inode +(short for index node) contains information about a file such +as its owner, permissions, timestamps, and location on the disk. +.TP +.B "\-k, \-\-kilobytes" +Print sizes in 1024-byte blocks. +.TP +.B "\-l, \-\-local" +Limit the output to local filesystems only. +(New in fileutils-4.0.) +.TP +.B "\-m, \-\-megabytes" +Print sizes in binary megabyte (that's 1048576 bytes) blocks. +Note that the four options \-h, \-H, \-k, \-m are mutually exclusive +and only the last one is effective; for example, it is not the case +that giving both the \-\-si and \-m options would result in output +in (actual, 1000000-byte) megabytes. [The interpretation of blocksizes +is also influenced by the environment variable BLOCK_SIZE, but this +does not work in the fileutils-4.0 version.] +.TP +.B "\-\-no\-sync" +Do not invoke the +.B sync +system call before getting any usage data. +This may make +.B df +run significantly faster, but on some systems (notably SunOS) +the results may be slightly out of date. This is the default. +.TP +.B "\-P, \-\-portability" +Use the +.SM POSIX +output format. This is like the default format +except that the information about each filesystem is always +printed on exactly one line; a mount device is never put on a line +by itself. This means that if the mount device name is more than +20 characters long (e.g., for some network mounts), the columns +are misaligned. +.TP +.B "\-\-sync" +Invoke the +.B sync +system call before getting any usage data. On some systems +(notably SunOS), doing this yields more up to date results, +but in general this option makes +.B df +much slower, especially when there are many or very busy filesystems. +.TP +.BI "\-t " "fstype, " "\-\-type=" "fstype" +Limit the listing to filesystems of type +.IR fstype . +Multiple filesystem types can be specified by giving multiple +.B \-t +options. By default, nothing is omitted. +.TP +.B "\-T, \-\-print\-type" +Print each filesystem's type. +The types given are those reported by the system +(and are found in a system-dependent way, for example by reading +.IR /etc/mtab ). +See also +.BR mount (8). +.TP +.BI "\-x " "fstype, " "\-\-exclude\-type=" "fstype" +Limit the listing to filesystems not of type +.I fstype. +Multiple filesystem types can be eliminated by giving multiple +.B "\-x" +options. By default, no filesystem types are omitted. +.TP +.B "\-v" +Ignored; for compatibility with System V versions of +.B df. +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variable POSIXLY_CORRECT determines the choice of unit. +If it is not set, and the variable BLOCKSIZE has a value starting +with `HUMAN', then behaviour is as for the \-h option, +unless overridden by \-k or \-m options. +The variables LANG, LC_ALL, LC_CTYPE and LC_MESSAGES have the +usual meaning. +.SH "CONFORMING TO" +POSIX 1003.2 +.SH "SEE ALSO" +.BR mount (8) +.SH NOTES +This page describes +.B df +as found in the fileutils-4.0 package; +other versions may differ slightly. diff --git a/man1/diff.1 b/man1/diff.1 new file mode 100644 index 000000000..3a68af4e1 --- /dev/null +++ b/man1/diff.1 @@ -0,0 +1,478 @@ +.\" Date: Fri, 11 Sep 1998 19:13:45 +0100 +.\" From: Edward Betts +.\" +.\" Derived from the GNU diff info page. +.\" May be distributed under the GPL. +.TH DIFF 1 1993-09-22 "GNU Tools" "GNU Tools" +.SH NAME +diff \- find differences between two files +.SH SYNOPSIS +.B diff +[options] from-file to-file +.SH DESCRIPTION +In the simplest case, +.I diff +compares the contents of the two files +.I from-file +and +.IR to-file . +A file name of +.B \- +stands for +text read from the standard input. As a special case, +.B "diff \- \-" +compares a copy of standard input to itself. + +If +.I from-file +is a directory and +.I to-file +is not, +.I diff +compares the file in +.I from-file +whose file name is that of +.IR to-file , +and vice versa. The non-directory file must not be +.BR \- . + +If both +.I from-file +and +.I to-file +are directories, +.I diff +compares corresponding files in both directories, in +alphabetical order; this comparison is not recursive unless the +.B \-r +or +.B \-\-recursive +option is given. +.I diff +never +compares the actual contents of a directory as if it were a file. The +file that is fully specified may not be standard input, because standard +input is nameless and the notion of ``file with the same name'' does not +apply. + +.B diff +options begin with +.BR \- , +so normally +.I from-file +and +.I to-file +may not begin with +.BR \- . +However, +.B \-\- +as an +argument by itself treats the remaining arguments as file names even if +they begin with +.BR \- . +.SS Options +Below is a summary of all of the options that GNU +.I diff +accepts. +Most options have two equivalent names, one of which is a single letter +preceded by +.BR \- , +and the other of which is a long name preceded by +.BR \-\- . +Multiple single letter options (unless they take an +argument) can be combined into a single command line word: +.B \-ac +is +equivalent to +.BR "\-a \-c" . +Long named options can be abbreviated to +any unique prefix of their name. Brackets +.RB ( [ +and +.BR ] ) +indicate that an +option takes an optional argument. +.TP +.BI \- lines +Show +.I lines +(an integer) lines of context. This option does not +specify an output format by itself; it has no effect unless it is +combined with +.B \-c +or +.BR \-u . +This option is obsolete. For proper +operation, +.I patch +typically needs at least two lines of context. +.TP +.B \-a +Treat all files as text and compare them line-by-line, even if they +do not seem to be text. +.TP +.B \-b +Ignore changes in amount of white space. +.TP +.B \-B +Ignore changes that just insert or delete blank lines. +.TP +.B \-\-brief +Report only whether the files differ, not the details of the +differences. +.TP +.B \-c +Use the context output format. +.TP +.BI "\-C " lines +.br +.ns +.TP +.BI \-\-context[= lines ] +Use the context output format, showing +.I lines +(an integer) lines of +context, or three if +.I lines +is not given. +For proper operation, +.I patch +typically needs at least two lines of +context. +.TP +.BI \-\-changed\-group\-format= format +Use +.I format +to output a line group containing differing lines from +both files in if-then-else format. +.TP +.B \-d +Change the algorithm to perhaps find a smaller set of changes. This makes +.I diff +slower (sometimes much slower). +.TP +.BI "\-D " name +Make merged if-then-else format output, conditional on the preprocessor +macro +.IR name . +.TP +.B \-e +.br +.ns +.TP +.B \-\-ed +Make output that is a valid +.I ed +script. +.TP +.BI \-\-exclude= pattern +When comparing directories, ignore files and subdirectories whose basenames +match +.IR pattern . +.TP +.BI \-\-exclude\-from= file +When comparing directories, ignore files and subdirectories whose basenames +match any pattern contained in +.IR file . +.TP +.B \-\-expand\-tabs +Expand tabs to spaces in the output, to preserve the alignment of tabs +in the input files. +.TP +.B \-f +Make output that looks vaguely like an +.I ed +script but has changes +in the order they appear in the file. +.TP +.BI "\-F " regexp +In context and unified format, for each hunk of differences, show some +of the last preceding line that matches +.IR regexp . +.TP +.B \-\-forward\-ed +Make output that looks vaguely like an +.B ed +script but has changes +in the order they appear in the file. +.TP +.B \-h +This option currently has no effect; it is present for Unix +compatibility. +.TP +.B \-H +Use heuristics to speed handling of large files that have numerous +scattered small changes. +.TP +.BI \-\-horizon\-lines= lines +Do not discard the last +.I lines +lines of the common prefix +and the first +.I lines +lines of the common suffix. +.TP +.B \-i +Ignore changes in case; consider upper- and lower-case letters +equivalent. +.TP +.BI "\-I " regexp +Ignore changes that just insert or delete lines that match +.IR regexp . +.TP +.BI \-\-ifdef= name +Make merged if-then-else format output, conditional on the preprocessor +macro +.IR name . +.TP +.B \-\-ignore\-all\-space +Ignore white space when comparing lines. +.TP +.B \-\-ignore\-blank\-lines +Ignore changes that just insert or delete blank lines. +.TP +.B \-\-ignore\-case +Ignore changes in case; consider upper- and lower-case to be the same. +.TP +.BI \-\-ignore\-matching\-lines= regexp +Ignore changes that just insert or delete lines that match +.IR regexp . +.TP +.B \-\-ignore\-space\-change +Ignore changes in amount of white space. +.TP +.B \-\-initial\-tab +Output a tab rather than a space before the text of a line in normal or +context format. This causes the alignment of tabs in the line to look +normal. +.TP +.B \-l +Pass the output through +.I pr +to paginate it. +.TP +.BI "\-L " label +.br +.ns +.TP +.BI \-\-label= label +Use +.I label +instead of the file name in the context format +and unified format +headers. +.TP +.B \-\-left\-column +Print only the left column of two common lines in side by side format. +.TP +.BI \-\-line\-format= format +Use +.I format +to output all input lines in in-then-else format. +.TP +.B \-\-minimal +Change the algorithm to perhaps find a smaller set of changes. This +makes +.I diff +slower (sometimes much slower). +.TP +.B \-n +Output RCS-format diffs; like +.B \-f +except that each command +specifies the number of lines affected. +.TP +.B \-N +.br +.ns +.TP +.B \-\-new\-file +In directory comparison, if a file is found in only one directory, +treat it as present but empty in the other directory. +.TP +.BI \-\-new\-group\-format= format +Use +.I format +to output a group of lines taken from just the second +file in if-then-else format. +.TP +.BI \-\-new\-line\-format= format +Use +.I format +to output a line taken from just the second file in +if-then-else format. +.TP +.BI \-\-old\-group\-format= format +Use +.I format +to output a group of lines taken from just the first +file in if-then-else format. +.TP +.BI \-\-old\-line\-format= format +Use +.I format +to output a line taken from just the first file in +if-then-else format. +.TP +.B \-p +Show which C function each change is in. +.TP +.B \-P +When comparing directories, if a file appears only in the second +directory of the two, treat it as present but empty in the other. +.TP +.B \-\-paginate +Pass the output through +.I pr +to paginate it. +.TP +.B \-q +Report only whether the files differ, not the details of the +differences. +.TP +.B \-r +When comparing directories, recursively compare any subdirectories +found. +.TP +.B \-\-rcs +Output RCS-format diffs; like +.B \-f +except that each command +specifies the number of lines affected. +.TP +.B \-\-recursive +When comparing directories, recursively compare any subdirectories +found. +.TP +.B \-\-report\-identical\-files +.br +.ns +.TP +.B \-s +Report when two files are the same. +.TP +.BI "\-S " file +When comparing directories, start with the file +.IR file . +This is +used for resuming an aborted comparison. +.TP +.B \-\-sdiff\-merge\-assist +Print extra information to help +.IR sdiff . +.I sdiff +uses this +option when it runs +.IR diff . +This option is not intended for users +to use directly. +.TP +.B \-\-show\-c\-function +Show which C function each change is in. +.TP +.BI \-\-show\-function\-line= regexp +In context and unified format, for each hunk of differences, show some +of the last preceding line that matches +.IR regexp . +.TP +.B \-\-side\-by\-side +Use the side by side output format. +.TP +.B \-\-speed\-large\-files +Use heuristics to speed handling of large files that have numerous +scattered small changes. +.TP +.BI \-\-starting\-file= file +When comparing directories, start with the file +.IR file . +This is +used for resuming an aborted comparison. +.TP +.B \-\-suppress\-common\-lines +Do not print common lines in side by side format. +.TP +.B \-t +Expand tabs to spaces in the output, to preserve the alignment of tabs +in the input files. +.TP +.B \-T +Output a tab rather than a space before the text of a line in normal or +context format. This causes the alignment of tabs in the line to look +normal. +.TP +.B \-\-text +Treat all files as text and compare them line-by-line, even if they +do not appear to be text. +.TP +.B \-u +Use the unified output format. +.TP +.BI \-\-unchanged\-group\-format= format +Use +.I format +to output a group of common lines taken from both files +in if-then-else format. +.TP +.BI \-\-unchanged\-line\-format= format +Use +.I format +to output a line common to both files in if-then-else +format. +.TP +.B \-\-unidirectional\-new\-file +When comparing directories, if a file appears only in the second +directory of the two, treat it as present but empty in the other. +.TP +.BI "\-U " lines +.br +.ns +.TP +.BI \-\-unified[= lines ] +Use the unified output format, showing +.I lines +(an integer) lines of +context, or three if +.I lines +is not given. +For proper operation, +.I patch +typically needs at least two lines of +context. +.TP +.B \-v +.br +.ns +.TP +.B \-\-version +Output the version number of +.IR diff . +.TP +.B \-w +Ignore white space when comparing lines. +.TP +.BI "\-W " columns +.br +.ns +.TP +.BI \-\-width= columns +Use an output width of +.I columns +in side by side format. +.TP +.BI "\-x " pattern +When comparing directories, ignore files and subdirectories whose basenames +match +.IR pattern . +.TP +.BI "\-X " file +When comparing directories, ignore files and subdirectories whose basenames +match any pattern contained in +.IR file . +.TP +.B \-y +Use the side by side output format. +.SH "SEE ALSO" +cmp(1), comm(1), diff3(1), ed(1), patch(1), pr(1), sdiff(1). +.SH DIAGNOSTICS +An exit status of 0 means no differences were found, 1 means some +differences were found, and 2 means trouble. diff --git a/man1/dir.1 b/man1/dir.1 new file mode 100644 index 000000000..a85b838f9 --- /dev/null +++ b/man1/dir.1 @@ -0,0 +1 @@ +.so man1/ls.1 diff --git a/man1/dircolors.1 b/man1/dircolors.1 new file mode 100644 index 000000000..5670e608c --- /dev/null +++ b/man1/dircolors.1 @@ -0,0 +1,122 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.\" Modified, James Sneeringer , Wed Sep 22 23:21:19 1999 +.\" +.TH DIRCOLORS 1 1998-11 "GNU fileutils 4.0" +.SH NAME +dircolors \- color setup for `ls' +.SH SYNOPSIS +.B dircolors +.B [\-b] [\-\-sh] [\-\-bourne\-shell] +.B [\-c] [\-\-csh] [\-\-c\-shell] +.B [\-p] [\-\-print\-database] +.B [\-\-help] [\-\-version] +.BI [ FILE ] +.SH DESCRIPTION +.B dircolors +outputs a sequence of shell commands to define the desired +color output from +.B ls +(and +.BR dir , +etc.). Typical usage: +.br +.RS +eval `dircolors [OPTION]... [FILE]` +.RE +.PP +If +.I FILE +is specified, +.B dircolors +reads it to determine which colors to use for which file types and +extensions. Otherwise, a compiled-in database is used. For details +on the format of these files, run `dircolors \-p'. +.PP +The output is a shell command to set the +.B LS_COLORS +environment variable. You can specify the shell syntax to use on the +command line, or +.B dircolors +will guess it from the value of the +.B SHELL +environment variable. +.PP +After execution of this command, `ls \-\-color' (which one might alias to ls) +will list files in the desired colors. +.PP +.SH OPTIONS +.TP +.B "\-b, \-\-sh, \-\-bourne\-shell" +Output Bourne shell commands. This is the default if the +.B SHELL +environment variable is set and does not end with +.I csh +or +.IR tcsh . +.TP +.B "\-c, \-\-csh, \-\-c\-shell" +Output C shell commands. This is the default if +.B SHELL +ends with +.I csh +or +.IR tcsh . +.TP +.B "\-p, \-\-print\-database" +Print the (compiled-in) default color configuration database. This +output is itself a valid configuration file, and is fairly +descriptive of the possibilities. +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variables SHELL and TERM are used to find the proper form +of the shell command. +The variables LANG, LC_ALL, LC_CTYPE and LC_MESSAGES have the +usual meaning. +The variable LS_COLORS is used to transfer information to +.BR ls . +.SH "CONFORMING TO" +Coloured output for +.BR ls (1) +is a GNU extension. +This implementation is not entirely compatible with the original +.BR dircolors / color-ls +package distributed with Slackware Linux. Notably, specific support +for the Z shell and Korn shell is not present. Users of these shells +should use the Bourne shell (-b) mode. +.SH "SEE ALSO" +.BR ls (1), +.BR dir_colors (5) +.SH FILES +The program +.B dircolors +itself does not use any configuration files. However, +customarily the shell initialization scripts invoke +.B dircolors +with one of the following. +.TP +.I /etc/DIR_COLORS +System-wide configuration file for +.BR dircolors . +.TP +.I ~/.dir_colors +Per-user configuration file for +.BR dircolors . +.SH NOTES +This page describes +.B dircolors +as found in the file\%utils-4.0 package; +other versions may differ slightly. diff --git a/man1/du.1 b/man1/du.1 new file mode 100644 index 000000000..73682b218 --- /dev/null +++ b/man1/du.1 @@ -0,0 +1,184 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.TH DU 1 1998-11 "GNU fileutils 4.0" +.SH NAME +du \- estimate file space usage +.SH SYNOPSIS +.BI "du [" options "] [" file... ] +.sp +POSIX options: +.B "[\-askx] [\-\-]" +.sp +GNU options (shortest form): +.B [\-abcDhHklLmsSxX] +.BI "[\-\-block\-size=" size ] +.BI "[\-\-exclude=" pattern ] +.BI "[\-\-max\-depth=" n ] +.B "[\-\-help] [\-\-version] [\-\-]" +.SH DESCRIPTION +.B du +reports the amount of disk space used by the specified files, +and by each directory in the hierarchies rooted at the +specified files. +Here `disk space used' means space used for the entire +file hierarchy below the specified file. +.PP +With no arguments, +.B du +reports the disk space for the current directory. +.SH "POSIX DETAILS" +The output is in 512-byte units by default, but in +1024-byte units when the \-k option is given. +.SH "GNU DETAILS" +The output is in 1024-byte units (when no units are +specified by options), unless the environment variable +.B POSIXLY_CORRECT +is set, in which case POSIX is followed. +.SH "POSIX OPTIONS" +.TP +.B "\-a" +Show counts for all files encountered, not just directories. +.TP +.B "\-k" +Use 1024-byte units instead of the default 512-byte units. +.TP +.B "\-s" +Only output space usage for the actual arguments given, +not for their subdirectories. +.TP +.B "\-x" +Only count space on the same device as the argument given. +.TP +.B "\-\-" +Terminate option list. +.SH "GNU OPTIONS" +.TP +.B "\-a, \-\-all" +Show counts for all files, not just directories. +.TP +.B "\-b, \-\-bytes" +Print sizes in bytes, instead of kilobytes. +.TP +.BI "\-\-block\-size=" size +Print sizes in blocks of +.I size +bytes. +(New in file\%utils-4.0.) +.TP +.B "\-c, \-\-total" +Print a grand total of all arguments after all arguments have been +processed. This can be used to find out the total disk usage of a +given set of files or directories. +.TP +.B "\-D, \-\-dereference\-args" +Dereference symbolic links that are command line arguments. Does +not affect other symbolic links. This is helpful for finding out +the disk usage of directories, such as +.IR /usr/tmp , +which are often symbolic links. +.TP +.BI "\-\-exclude=" pattern +When recursing, skip subdirectories or files matching +.IR pattern . +The +.I pattern +may be any standard Bourne shell file glob pattern. +(New in file\%utils-4.0.) +.TP +.B "\-h, \-\-human\-readable" +Append a size letter, such as +.B M +for binary megabytes (`mebibytes'), to each size. +.TP +.B "\-H, \-\-si" +Do the same as for +.BR \-h , +but use the official SI units (with powers of 1000 instead of 1024, +so that M stands for 1000000 instead of 1048576). +(New in file\%utils-4.0.) +.TP +.B "\-k, \-\-kilobytes" +Print sizes in KiB (binary kilobytes, 1024 bytes). +.TP +.B "\-l, \-\-count\-links" +Count the size of all files, even if they have appeared already +(as a hard link). +.TP +.B "\-L, \-\-dereference" +Dereference symbolic links (show the disk space used by the file +or directory that the link points to instead of the space used by +the link). +.TP +.B "\-m, \-\-megabytes" +Print sizes in MiB (binary megabytes, 1048576 bytes). +.TP +.BI "\-\-max\-depth=" n +Print the total for a directory (or file, with the +.B \-a +flag) only if it is +.I n +or fewer levels below the command line argument; +.BI "\-\-max\-depth=" 0 +is the same as the +.B \-s +flag. +(New in file\%utils-4.0.) +.TP +.B "\-s, \-\-summarize" +Display only a total for each argument. +.TP +.B "\-S, \-\-separate\-dirs" +Report the size of each directory separately, not including the +sizes of subdirectories. +.TP +.B "\-x, \-\-one\-file\-system" +Skip directories that are on different filesystems from the one +that the argument being processed is on. +.TP +.BI "\-X " "file, " "\-\-exclude\-from=" "file" +Like +.BR \-\-exclude , +except take the patterns to exclude from the specified +.IR file . +Patterns are listed one per line. If +.I file +is given as `\-', patterns are read from standard input. +(New in file\%utils-4.0.) +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH BUGS +On BSD systems, +.B du +reports sizes that are half the correct values +for files that are NFS-mounted from HP-UX systems. On HP-UX systems, +it reports sizes that are twice the correct values for files that are +NFS-mounted from BSD systems. This is due to a flaw in HP-UX; it also +affects the HP-UX +.B du +program. +.SH ENVIRONMENT +The variable POSIXLY_CORRECT determines the choice of unit. +If it is not set, and the variable BLOCKSIZE has a value starting +with `HUMAN', then behaviour is as for the \-h option, +unless overridden by \-k or \-m options. +The variables LANG, LC_ALL, LC_CTYPE and LC_MESSAGES have the +usual meaning. +.SH "CONFORMING TO" +POSIX 1003.2 +.SH NOTES +This page describes +.B du +as found in the file\%utils-4.0 package; +other versions may differ slightly. diff --git a/man1/install.1 b/man1/install.1 new file mode 100644 index 000000000..7151b69dd --- /dev/null +++ b/man1/install.1 @@ -0,0 +1,186 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.TH INSTALL 1 1998-11 "GNU fileutils 4.0" +.SH NAME +install \- copy files and set attributes +.SH SYNOPSIS +.B install +.BI [ options ] +.B [\-s] [\-\-strip] +.I source dest +.br +.B install +.BI [ options ] +.B [\-s] [\-\-strip] +.I source... directory +.br +.B install +.BI [ options ] +.B [\-d,\-\-directory] +.I directory... +.sp +Options (shortest form): +.br +.B [\-b] +.B [\-c] +.B [\-D] +.BI "[\-g " group ] +.BI "[\-m " mode ] +.BI "[\-o " owner ] +.BI "[\-S " SUFFIX ] +.B [\-V {numbered,existing,simple}] +.B [\-\-help] [\-\-version] [\-\-] +.SH DESCRIPTION +.B install +copies files while setting their permission modes and, if +possible, their owner and group. +.PP +In the first of these invocation forms, the +.I source +file is copied to the +.I dest +target file. In the second, each of the +.I source +files are copied to the destination +.IR directory . +In the last, each +.I directory +(and any missing parent directories) is created. +.PP +.B install +is similar to +.BR cp , +but allows you to control the attributes of destination files. +It is typically used in Makefiles to copy programs into their +destination directories. It refuses to copy files onto themselves. +.PP +.SH OPTIONS +.TP +.B "\-c" +Ignored; for compatibility with old Unix versions of +.BR install . +.TP +.B "\-d, \-\-directory" +Create each given directory and any missing parent directories, +setting the owner, group and mode as given on the command line or +to the defaults. It also gives any parent directories it creates +those attributes. (This is different from the SunOS 4.x +.BR install , +which gives directories that it creates the default attributes.) +.TP +.B "\-D" +Create all leading components of the +.I dest +except the last, then copy +.I source +to +.IR dest . +This option is useful in the first format in the synopsis, above. +(New in file\%utils-4.0.) +.TP +.BI "\-g " "group" ", \-\-group=" "group" +Set the group ownership of installed files or directories to +.IR group . +The default is the process's current group. +.I group +may be either a group name or a numeric group id. +.TP +.BI "\-m " "mode" ", \-\-mode=" "mode" +Set the permissions for the installed file or directory to +.IR mode , +which can be either an octal number, or a symbolic mode as in +.BR chmod , +with 0 as the point of departure. The default mode is 0755 - read, +write, and execute for the owner, and read and execute for group and other. +.TP +.BI "\-o " "owner" ", \-\-owner=" "owner" +If +.B install +has appropriate privileges (is run as root), set the ownership of +installed files or directories to +.IR owner . +The default is `root'. +.I owner +may be either a user name or a numeric user ID. +.TP +.B "\-s, \-\-strip" +Strip the symbol tables from installed binary executables. +.SH "GNU BACKUP OPTIONS" +The GNU versions of programs like +.BR cp , +.BR mv , +.BR ln , +.B install +and +.B patch +will make a backup of files about to be overwritten, changed or destroyed +if that is desired. That backup files are desired is indicated by +the \-b option. How they should be named is specified by the \-V option. +In case the name of the backup file is given by the name of the file +extended by a suffix, this suffix is specified by the \-S option. +.TP +.B "\-b, \-\-backup" +Make backups of files that are about to be overwritten or removed. +.TP +.BI "\-S " SUFFIX ", \-\-suffix=" SUFFIX +Append +.I SUFFIX +to each backup file made. +If this option is not specified, the value of the +.B SIMPLE_BACKUP_SUFFIX +environment variable is used. And if +.B SIMPLE_BACKUP_SUFFIX +is not set, the default is `~'. +.TP +.BI "\-V " METHOD ", \-\-version\-control=" METHOD +.RS +Specify how backup files are named. The +.I METHOD +argument can be `numbered' (or `t'), `existing' (or `nil'), or `never' (or +`simple'). +If this option is not specified, the value of the +.B VERSION_CONTROL +environment variable is used. And if +.B VERSION_CONTROL +is not set, the default backup type is `existing'. +.PP +This option corresponds to the Emacs variable `version-control'. +The valid +.IR METHOD s +are (unique abbreviations are accepted): +.TP +.BR t ", " numbered +Always make numbered backups. +.TP +.BR nil ", " existing +Make numbered backups of files that already have them, simple +backups of the others. +.TP +.BR never ", " simple +Always make simple backups. +.RE +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variables LANG, LC_ALL, LC_CTYPE and LC_MESSAGES have the +usual meaning. For the GNU version, the variables SIMPLE_BACKUP_SUFFIX +and VERSION_CONTROL control backup file naming, as described above. +.SH "CONFORMING TO" +BSD 4.2 (which had the \-c, \-m, \-o, \-g and \-s options). +.SH NOTES +This page describes +.B install +as found in the fileutils-4.0 package; +other versions may differ slightly. diff --git a/man1/intro.1 b/man1/intro.1 new file mode 100644 index 000000000..a4790c2f3 --- /dev/null +++ b/man1/intro.1 @@ -0,0 +1,258 @@ +.\" Copyright (c) 2002 Andries Brouwer +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH INTRO 1 2002-08-06 "Linux" "Linux Programmer's Manual" +.SH NAME +intro \- Introduction to user commands +.SH DESCRIPTION +Linux is a flavour of Unix, and as a first approximation +all user commands under Unix work precisely the same under +Linux (and FreeBSD and lots of other Unix-like systems). +.LP +Under Linux there are GUIs (graphical user interfaces), where you +can point and click and drag, and hopefully get work done without +first reading lots of documentation. The traditional Unix environment +is a CLI (command line interface), where you type commands to +tell the computer what to do. That is faster and more powerful, +but requires finding out what the commands are. +Below a bare minimum, to get started. +.SS "Login" +In order to start working, you probably first have to login, +that is, give your username and password. See also +.BR login (1). +The program +.I login +now starts a +.I shell +(command interpreter) for you. +In case of a graphical login, you get a screen with menus or icons +and a mouse click will start a shell in a window. See also +.BR xterm (1). +.SS "The shell" +One types commands to the +.IR shell , +the command interpreter. It is not built-in, but is just a program +and you can change your shell. Everybody has her own favourite one. +The standard one is called +.IR sh . +See also +.BR ash (1), +.BR bash (1), +.BR csh (1), +.BR zsh (1), +.BR chsh (1). +.LP +A session might go like + +.RS +.nf +.BI "knuth login: " aeb +.BI "Password: " ******** +.BI "% " date +Tue Aug 6 23:50:44 CEST 2002 +.BI "% " cal + August 2002 +Su Mo Tu We Th Fr Sa + 1 2 3 + 4 5 6 7 8 9 10 +11 12 13 14 15 16 17 +18 19 20 21 22 23 24 +25 26 27 28 29 30 31 + +.BI "% " ls +bin tel +.BI "% " "ls -l" +total 2 +drwxrwxr-x 2 aeb 1024 Aug 6 23:51 bin +-rw-rw-r-- 1 aeb 37 Aug 6 23:52 tel +.BI "% " "cat tel" +maja 0501-1136285 +peter 0136-7399214 +.BI "% " "cp tel tel2" +.BI "% " "ls -l" +total 3 +drwxr-xr-x 2 aeb 1024 Aug 6 23:51 bin +-rw-r--r-- 1 aeb 37 Aug 6 23:52 tel +-rw-r--r-- 1 aeb 37 Aug 6 23:53 tel2 +.BI "% " "mv tel tel1" +.BI "% " "ls -l" +total 3 +drwxr-xr-x 2 aeb 1024 Aug 6 23:51 bin +-rw-r--r-- 1 aeb 37 Aug 6 23:52 tel1 +-rw-r--r-- 1 aeb 37 Aug 6 23:53 tel2 +.BI "% " "diff tel1 tel2" +.BI "% " "rm tel1" +.BI "% " "grep maja tel2" +maja 0501-1136285 +.BI "% " +.fi +.RE +and here typing Control-D ended the session. +The +.B "% " +here was the command prompt - it is the shell's way of indicating +that it is ready for the next command. The prompt can be customized +in lots of ways, and one might include stuff like user name, +machine name, current directory, time, etc. +An assignment PS1="What next, master? " +would change the prompt as indicated. +.LP +We see that there are commands +.I date +(that gives date and time), and +.I cal +(that gives a calendar). +.LP +The command +.I ls +lists the contents of the current directory - it tells you what +files you have. With a \-l option it gives a long listing, +that includes the owner and size and date of the file, and the +permissions people have for reading and/or changing the file. +For example, the file "tel" here is 37 bytes long, owned by aeb +and the owner can read and write it, others can only read it. +Owner and permissions can be changed by the commands +.I chown +and +.IR chmod . +.LP +The command +.I cat +will show the contents of a file. +(The name is from "concatenate and print": all files given as +parameters are concatenated and sent to "standard output", here +the terminal screen.) +.LP +The command +.I cp +(from "copy") will copy a file. +On the other hand, the command +.I mv +(from "move") only renames it. +.LP +The command +.I diff +lists the differences between two files. +Here there was no output because there were no differences. +.LP +The command +.I rm +(from "remove") deletes the file, and be careful! it is gone. +No wastepaper basket or anything. Deleted means lost. +.LP +The command +.I grep +(from "g/re/p") finds occurrences of a string in one or more files. +Here it finds Maja's telephone number. +.SS "Path names and the current directory" +Files live in a large tree, the file hierarchy. +Each has a +.I "path name" +describing the path from the root of the tree (which is called /) +to the file. For example, such a full path name might be /home/aeb/tel. +Always using full path names would be inconvenient, and the name +of a file in the current directory may be abbreviated by only giving +the last component. That is why "/home/aeb/tel" can be abbreviated +to "tel" when the current directory is "/home/aeb". +.LP +The command +.I pwd +prints the current directory. +.LP +The command +.I cd +changes the current directory. +Try "cd /" and "pwd" and "cd" and "pwd". +.SS "Directories" +The command +.I mkdir +makes a new directory. +.LP +The command +.I rmdir +removes a directory if it is empty, and complains otherwise. +.LP +The command +.I find +(with a rather baroque syntax) will find files with given name +or other properties. For example, "find . -name tel" would find +the file "tel" starting in the present directory (which is called "."). +And "find / -name tel" would do the same, but starting at the root +of the tree. Large searches on a multi-GB disk will be time-consuming, +and it may be better to use +.BR locate (1). +.SS "Disks and Filesystems" +The command +.I mount +will attach the filesystem found on some disk (or floppy, or CDROM or so) +to the big filesystem hierarchy. And +.I umount +detaches it again. +The command +.I df +will tell you how much of your disk is still free. +.SS "Processes" +On a Unix system many user and system processes run simultaneously. +The one you are talking to runs in the +.IR foreground , +the others in the +.IR background . +The command +.I ps +will show you which processes are active and what numbers these +processes have. +The command +.I kill +allows you to get rid of them. Without option this is a friendly +request: please go away. And "kill -9" followed by the number +of the process is an immediate kill. +Foreground processes can often be killed by typing Control-C. +.SS "Getting information" +There are thousands of commands, each with many options. +Traditionally commands are documented on +.IR "man pages" , +(like this one), so that the command "man kill" will document +the use of the command "kill" (and "man man" document the command "man"). +The program +.I man +sends the text through some +.IR pager , +usually +.IR less . +Hit the space bar to get the next page, hit q to quit. +.LP +In documentation it is custumary to refer to man pages +by giving the name and section number, as in +.BR man (1). +Man pages are terse, and allow you to find quickly some forgotten +detail. For newcomers an introductory text with more examples +and explanations is useful. +.LP +A lot of GNU/FSF software is provided with info files. Type "info info" +for an introduction on the use of the program "info". +.LP +Special topics are often treated in HOWTOs. Look in +.I /usr/share/doc/howto/en +and use a browser if you find HTML files there. +.\" +.\" Actual examples? Separate section for each of cat, cp, ...? +.\" gzip, bzip2, tar, rpm diff --git a/man1/ldd.1 b/man1/ldd.1 new file mode 100644 index 000000000..014f12fc8 --- /dev/null +++ b/man1/ldd.1 @@ -0,0 +1,71 @@ +.\" Copyright 1995-2000 David Engel (david@ods.com) +.\" Copyright 1995 Rickard E. Faith (faith@cs.unc.edu) +.\" Copyright 2000 Ben Collins (bcollins@debian.org) +.\" Redone for GLibc 2.2 +.\" Copyright 2000 Jakub Jelinek (jakub@redhat.com) +.\" Corrected. +.\" Most of this was copied from the README file. +.\" Do not restrict distribution. +.\" May be distributed under the GNU General Public License +.TH LDD 1 "30 October 2000" "Linux Programmer's Manual" +.SH NAME +ldd \- print shared library dependencies +.SH SYNOPSIS +.B ldd +.RB [OPTION]... +FILE... +.SH DESCRIPTION +.B ldd +prints the shared libraries required by each program or shared library +specified on the command line. +.SH OPTIONS +.TP +.B \-V\ \-\-version +Print the version number of +.BR ldd . +.TP +.B \-v\ \-\-verbose +Print all information, including e.g. symbol versioning information. +.TP +.B \-d\ \-\-data\-relocs +Perform relocations and report any missing objects (ELF only). +.TP +.B \-r\ \-\-function\-relocs +Perform relocations for both data objects and functions, and +report any missing objects or functions (ELF only). +.TP +.B \-\-help +Usage information. +.SH NOTES +The standard version of +.B ldd +comes with glibc2. Libc5 came with an older version, still present +on some systems. The long options are not supported by the libc5 version. +On the other hand, the glibc2 version does not support +.B \-V +and only has the equivalent +.BR \-\-version . +.LP +The libc5 version of this program will use the name of a library given +on the command line as-is when it contains a '/'; otherwise it +searches for the library in the standard locations. To run it +on a shared library in the current directory, prefix the name with "./". +.SH BUGS +.B ldd +does not work on a.out shared libraries. +.PP +.B ldd +does not work with some extremely old a.out programs which were +built before +.B ldd +support was added to the compiler releases. +If you use +.B ldd +on one of these programs, the program will attempt to run with +\fIargc\fP = 0 and the results will be unpredictable. +.\" .SH AUTHOR +.\" David Engel. +.\" Roland McGrath and Ulrich Drepper. +.SH SEE ALSO +.BR ld.so (8), +.BR ldconfig (8) diff --git a/man1/ln.1 b/man1/ln.1 new file mode 100644 index 000000000..3a8d2e73f --- /dev/null +++ b/man1/ln.1 @@ -0,0 +1,228 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.TH LN 1 1998-11 "GNU fileutils 4.0" +.SH NAME +ln \- make links between files +.SH SYNOPSIS +.B ln [options] +.IB source " [" dest ] +.br +.B ln [options] +.I source... directory +.sp +POSIX options: +.B "[\-f] [\-\-]" +.sp +GNU options (shortest form): +.B [\-bdfinsvF] +.BI "[\-S " backup-suffix ] +.B "[\-V {numbered,existing,simple}]" +.B "[\-\-help] [\-\-version] [\-\-]" +.SH DESCRIPTION +There are two concepts of `link' in Unix, usually called +hard link and soft link. A hard link is just a name for a file. +(And a file can have several names. It is deleted from disk only +when the last name is removed. The number of names is given by +.BR ls (1). +There is no such thing as an `original' name: all names have the +same status. Usually, but not necessarily, all names of a file +are found in the filesystem that also contains its data.) +.PP +A soft link (or symbolic link, or symlink) is an entirely different +animal: it is a small special file that contains a pathname. +Thus, soft links can point at files on different filesystems +(possibly NFS mounted from different machines), and need not point +to actually existing files. +When accessed (with the +.BR open (2) +or +.BR stat (2) +system calls), a reference to a symlink is replaced by the operating +system kernel with a reference to the file named by the path name. +(However, with +.BR rm (1) +and +.BR unlink (2) +the link itself is removed, not the file it points to. +There are special system calls +.BR lstat (2) +and +.BR readlink (2) +that read the status of a symlink and the filename it points to. +For various other system calls there is some uncertainty +and variation between operating systems as to whether +the operation acts on the symlink itself, or on the file pointed to.) +.PP +.B ln +makes links between files. By default, it makes hard links; +with the +.B "\-s" +option, it makes symbolic (or `soft') links. +.PP +If only one file is given, it links that file into +the current directory, that is, creates a link to that file +in the current directory, with name equal to (the last component of) +the name of that file. (This is a GNU extension.) +Otherwise, if the last argument names an existing directory, +.B ln +will create links to each mentioned +.I source +file in that directory, with a name equal to (the last component of) +the name of that +.I source +file. (But see the description of the +.B "\-\-no\-dereference" +option below.) +Otherwise, if only two files are given, it creates a link named +.I dest +to the file +.IR source . +It is an error if the last argument is not a directory and +more than two files are given. +.PP +By default, +.B ln +does not remove existing files or existing symbolic links. +(Thus, it can be used for locking purposes: it will succeed only if +.I dest +did not exist already.) +But it can be forced to do so with the option \-f. +.PP +On existing implementations, if it is at all possible to make a hard link +to a directory, this may be done by the superuser only. POSIX forbids +the system call +.BR link (2) +and the utility +.B ln +to make hard links to directories (but does not forbid +hard links to cross filesystem boundaries). +.SH "POSIX OPTIONS" +.TP +.B "\-f" +Remove existing destination files. +.TP +.B "\-\-" +Terminate option list. +.SH "GNU OPTIONS" +.TP +.B "\-d, \-F, \-\-directory" +Allow the super-user to make hard links to directories. +.TP +.B "\-f, \-\-force" +Remove existing destination files. +.TP +.B "\-i, \-\-interactive" +Prompt whether to remove existing destination files. +.TP +.B "\-n, \-\-no\-dereference" +When given an explicit destination that is a symlink to a +directory, treat that destination as if it were a normal file. + +When the destination is an actual directory (not a symlink to one), +there is no ambiguity. The link is created in that directory. +But when the specified destination is a symlink to a directory, +there are two ways to treat the user's request. +.B ln +can treat the destination just as it would a normal directory and +create the link in it. On the other hand, the destination can be +viewed as a non-directory - as the symlink itself. In that case, +.B ln +must delete or backup that symlink before creating the new link. +The default is to treat a destination that is a symlink to a directory +just like a directory. +.TP +.B "\-s, \-\-symbolic" +Make symbolic links instead of hard links. This option merely +produces an error message on systems that do not support symbolic links. +.TP +.B "\-v, \-\-verbose" +Print the name of each file before linking it. +.SH "GNU BACKUP OPTIONS" +The GNU versions of programs like +.BR cp , +.BR mv , +.BR ln , +.B install +and +.B patch +will make a backup of files about to be overwritten, changed or destroyed +if that is desired. That backup files are desired is indicated by +the \-b option. How they should be named is specified by the \-V option. +In case the name of the backup file is given by the name of the file +extended by a suffix, this suffix is specified by the \-S option. +.TP +.B "\-b, \-\-backup" +Make backups of files that are about to be overwritten or removed. +.TP +.BI "\-S " SUFFIX ", \-\-suffix=" SUFFIX +Append +.I SUFFIX +to each backup file made. +If this option is not specified, the value of the +.B SIMPLE_BACKUP_SUFFIX +environment variable is used. And if +.B SIMPLE_BACKUP_SUFFIX +is not set, the default is `~'. +.TP +.BI "\-V " METHOD ", \-\-version\-control=" METHOD +.RS +Specify how backup files are named. The +.I METHOD +argument can be `numbered' (or `t'), `existing' (or `nil'), or `never' (or +`simple'). +If this option is not specified, the value of the +.B VERSION_CONTROL +environment variable is used. And if +.B VERSION_CONTROL +is not set, the default backup type is `existing'. +.PP +This option corresponds to the Emacs variable `version-control'. +The valid +.IR METHOD s +are (unique abbreviations are accepted): +.TP +.BR t ", " numbered +Always make numbered backups. +.TP +.BR nil ", " existing +Make numbered backups of files that already have them, simple +backups of the others. +.TP +.BR never ", " simple +Always make simple backups. +.RE +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variables LANG, LC_ALL, LC_CTYPE and LC_MESSAGES have the +usual meaning. +.SH "CONFORMING TO" +POSIX 1003.2. However, POSIX 1003.2 (1996) does not discuss soft links. +Soft links were introduced by BSD, and do not occur in System V release 3 +(and older) systems. +.SH "SEE ALSO" +.BR ls (1), +.BR rm (1), +.BR link (2), +.BR lstat (2), +.BR open (2), +.BR readlink (2), +.BR stat (2), +.BR unlink (2) +.SH NOTES +This page describes +.B ln +as found in the fileutils-4.0 package; +other versions may differ slightly. diff --git a/man1/ls.1 b/man1/ls.1 new file mode 100644 index 000000000..7a4ca35d8 --- /dev/null +++ b/man1/ls.1 @@ -0,0 +1,573 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.TH LS 1 1998-11 "GNU fileutils 4.0" +.SH NAME +ls, dir, vdir \- list directory contents +.SH SYNOPSIS +.BI "ls [" options "] [" file... ] +.br +.BI "dir [" file... ] +.br +.BI "vdir [" file... ] +.sp +POSIX options: +.BI "[\-CFRacdilqrtu1] [\-\-]" +.sp +GNU options (shortest form): +.B [\-1abcdfghiklmnopqrstuvwxABCDFGHLNQRSUX] +.BI "[\-w " cols ] +.BI "[\-T " cols ] +.BI "[\-I " pattern ] +.B [\-\-full\-time] +.B [\-\-show\-control\-chars] +.BI "[\-\-block\-size=" size ] +.B [\-\-format={long,verbose,commas,across,vertical,single\-column}] +.B [\-\-sort={none,time,size,extension}] +.B [\-\-time={atime,access,use,ctime,status}] +.B [\-\-color[={none,auto,always}]] +.B "[\-\-help] [\-\-version] [\-\-]" +.SH DESCRIPTION +The program +.B ls +lists first its non-directory +.I file +arguments, and then for each directory argument all listable files +contained within that directory. If no non-option arguments are present, +a default argument `.' (the current directory) is assumed. +The \-d option causes directories to be treated as non-directory arguments. +A file is listable when either its name does not start with `.', +or the \-a option is given. +.PP +Each of the lists of files (that of non-directory files, and for +each directory the list of files inside) is sorted separately +according to the collating sequence in the current locale. +When the \-l option is given, each list is preceded by a summary +line giving the total size of all files in the list, measured +in 512-byte or 1024-byte blocks. +.\" POSIX: 512, GNU: 1024 +.\" rumoured: early AIX 3.1: 1024, later AIX: 512 +.PP +The output is to stdout, one entry per line, unless multicolumn +output is requested by the \-C option. However, for output to a +terminal, it is undefined whether the output will be single-column +or multi-column. The options \-1 and \-C can be used to force +single-column and multi-column output, respectively. +.SH "POSIX OPTIONS" +.TP +.B "\-C" +List files in columns, sorted vertically. +.TP +.B "\-F" +Suffix each directory name with `/', each FIFO name with `|', and +each name of an executable with `*'. +.TP +.B "\-R" +Recursively list subdirectories encountered. +.TP +.B "\-a" +Include files with a name starting with `.' in the listing. +.TP +.B "\-c" +Use the status change time instead of the modification time +for sorting (with \-t) or listing (with \-l). +.TP +.B "\-d" +List names of directories like other files, rather than +listing their contents. +.TP +.B "\-i" +Precede the output for the file by the file serial number (i-node number). +.TP +.B "\-l" +Write (in single-column format) the file mode, the number of links +to the file, the owner name, the group name, the size of the file (in bytes), +the timestamp, and the filename. The summary line uses 512-byte units. + +The file types are as follows: +.B \- +for an ordinary file, +.B d +for a directory, +.B b +for a block special device, +.B c +for a character special device, +.B l +for a symbolic link, +.B p +for a fifo, +.B s +for a socket. + +By default, the timestamp shown is that of the last modification; the +options \-c and \-u select the other two timestamps. +For device special files the size field is commonly replaced +by the major and minor device numbers. +.TP +.B "\-q" +Output nonprintable characters in a filename as question marks. +(This is permitted to be the default for output to a terminal.) +.TP +.B "\-r" +Reverse the order of the sort. +.TP +.B "\-t" +Sort by the timestamp shown. +.TP +.B "\-u" +Use the time of last access instead of the modification time +for sorting (with \-t) or listing (with \-l). +.TP +.B "\-1" +For single-column output. +.TP +.B "\-\-" +Terminate option list. +.SH "GNU DETAILS" +If standard output is a terminal, the output is in columns (sorted vertically). +.PP +.B dir +(also installed as +.BR d ) +is equivalent to `ls\ \-C\ \-b'; that is, files are by default listed +in columns, sorted vertically. +.B vdir +(also installed as +.BR v ) +is equivalent to `ls\ \-l\ \-b'; that is, files are by default listed +in long format. +.SH "GNU OPTIONS" +.TP +.B "\-1, \-\-format=single\-column" +List one file per line. This is the default for when standard output is +not a terminal. +.TP +.B "\-a, \-\-all" +List all files in directories, including all files that start with `.'. +.TP +.B "\-b, \-\-escape, \-\-quoting\-style=escape" +Quote nongraphic characters in file names using alphabetic and octal +backslash sequences like those used in C. This option is the same as +.B "\-Q" +except that filenames are not surrounded by double\-quotes. +.TP +.B "\-c, \-\-time=ctime, \-\-time=status" +Sort directory contents according to the files' status change time (the +`ctime' in the inode). If the long listing format is being +.RB "used (" \-l ) +print the status change time instead of the modification time. +.TP +.B "\-d, \-\-directory" +List names of directories like other files, rather than listing their contents. +.TP +.B "\-f" +Do not sort directory contents; list them in whatever order they are +stored on the disk. +Also enables +.B \-a +and +.BR \-U +and disables +.BR \-l , +.BR \-\-color , +.BR \-s , +and +.B \-t +if they were specified before the +.BR \-f . +.TP +.B \-g +Ignored; for Unix compatibility. +.TP +.B "\-h, \-\-human\-readable" +Append a size letter, such as +.B M +for binary megabytes (`mebibytes'), to each size. +(New in file\%utils-4.0.) +.TP +.B "\-i, \-\-inode" +Print the inode number (also called the file serial number and index +number) of each file to the left of the file name. (This number uniquely +identifies each file within a particular filesystem) +.TP +.B "\-k, \-\-kilobytes" +If file sizes are being listed, print them in kilobytes. +.TP +.B "\-l, \-\-format=long, \-\-format=verbose" +In addition to the name of each file, print the file type, +permissions, number of hard links, owner name, group name, size in +bytes, and timestamp (the modification time unless other times are +selected). For files with a time that is more than 6 months old or +more than 1 hour into the future, the timestamp contains the year +instead of the time of day. + +For each directory that is listed, preface the files with a line +`total +.IR blocks "', where " blocks " is the total disk space used by all" +files in that directory. By default, 1024-byte blocks are used; +if the environment variable +.B POSIXLY_CORRECT +is set, 512-byte blocks are used (unless the +.B \-k +.RI "option is given). The " blocks +computed counts each hard link separately; this is arguably a deficiency. + +The permissions listed are similar to symbolic mode specifications but +.B ls +combines multiple bits into the third character of each set of permissions +.RS +.TP +.B s +If the setuid or setgid bit and the corresponding executable bit are +both set. +.TP +.B S +If the setuid or setgid bit is set but the corresponding executable bit +is not set. +.TP +.B t +If the sticky bit and the other-executable bit are both set. +.TP +.B T +If the sticky bit is set but the other-executable bit is not set. +.TP +.B x +If the executable bit is set and none of the above apply. +.TP +.B \- +Otherwise. +.RE +.TP +.B "\-m, \-\-format=commas" +List files horizontally, with as many as will fit on each line, +each separated by a comma and a space. +.TP +.B "\-n, \-\-numeric\-uid\-gid" +List the numeric UID and GID instead of the names. +.TP +.B \-o +Produce long format directory listings, but don't display group +information. It is equivalent to using +.BR "\-\-format=long \-\-no\-group" . +This option is provided for compatibility with other versions of +.BR ls . +.TP +.B "\-p, \-\-file\-type, \-\-indicator\-style=file\-type" +Append a character to each file name indicating the file type. This is like +.B \-F +except that executables aren't marked. +(In fact fileutils-4.0 treats the --file-type option like --classify.) +.TP +.B "\-q, \-\-hide\-control\-chars" +Print question marks instead of nongraphic characters in file names. This +is the default. +.TP +.B "\-r, \-\-reverse" +Sort directory contents in reverse order. +.TP +.B "\-s, \-\-size" +Print the size of each file in 1024-byte blocks to the left of the file name. +If the environment variable +.B POSIXLY_CORRECT +is set, 512-byte blocks are used instead, unless the +.B \-k +option is given. +.TP +.B "\-t, \-\-sort=time" +Sort by modification time (the `mtime' in the inode) instead of +alphabetically, with the newest files listed first. +.TP +.B "\-u, \-\-time=atime, \-\-time=access, \-\-time=use" +Sort directory contents according to the files' last access time +instead of the modification time (the `atime' in the inode). If the long +listing format is being used, print the last access time instead of the +modification time. +.TP +.B "\-v" +Sort directory contents according to the files' version. This takes into +account the fact that filenames frequently include indices or version +numbers. Standard sorting functions usually do not produce the ordering +that people expect because comparisons are made on a +character\-by\-character basis. The version sort addresses this problem, +and is especially useful when browsing directories that contain many +files with indices/version numbers in their names. For example: + +.nf + > ls -1 > ls -1v + foo.zml-1.gz foo.zml-1.gz + foo.zml-100.gz foo.zml-12.gz + foo.zml-12.gz foo.zml-25.gz + foo.zml-25.gz foo.zml-100.gz +.fi + +Note also that numeric parts with leading zeroes are considered as +fractional: + +.nf + > ls -1 > ls -1v + abc-1.007.tgz abc-1.007.tgz + abc-1.012b.tgz abc-1.01a.tgz + abc-1.01a.tgz abc-1.012b.tgz +.fi + +(New in file\%utils-4.0.) +.TP +.BI "\-w, \-\-width " cols +Assume the screen is +.I cols +columns wide. The default is taken from the terminal driver if +possible; otherwise the environment variable +.B COLUMNS +is used if it is set; otherwise the default is 80. +.TP +.B "\-x, \-\-format=across, \-\-format=horizontal" +List the files in columns, sorted horizontally. +.TP +.B "\-A, \-\-almost\-all" +List all files in directories, except for `.' and `..'. +.TP +.B "\-B, \-\-ignore\-backups" +Do not list files that end with `~', unless they are given on the +command line. +.TP +.B "\-C, \-\-format=vertical" +List files in columns, sorted vertically. This is the default if standard +output is a terminal. It is always the default for +.BR dir " and " d . +.TP +.B "\-D, \-\-dired" +With the long listing +.RB ( \-l ) +format, print an additional line after the main output: +.br +.B //DIRED// +.I BEG1 END1 BEG2 END2 ... +.br + +The +.IR BEGn " and " ENDn +are unsigned integers which record the byte position of +the beginning and end of each file name in the output. This makes it easy +for Emacs to find the names, even when they contain unusual characters +such as space or newline, without fancy searching. + +If directories are being listed recursively +.RB ( \-R ), +output a similar line after each subdirectory: +.br +.B //SUBDIRED// +.I BEG1 END1 ... +.TP +.B "\-F, \-\-classify, \-\-indicator\-style=classify" +Append a character to each file name indicating the file type. For +regular files that are executable, append a `*'. The file type +indicators are `/' for directories, `@' for symbolic links, `|' for +FIFOs, `=' for sockets, and nothing for regular files. +.TP +.B "\-G, \-\-no\-group" +Inhibit display of group information in a long format directory listing. +.TP +.B "\-H, \-\-si" +Do the same as for +.BR \-h , +but use the official SI units (with powers of 1000 instead of 1024, +so that M stands for 1000000 instead of 1048576). +(New in fileutils-4.0.) +.TP +.BI "\-I, \-\-ignore=" pattern +Do not list files whose names match the shell pattern +.I pattern +(not regular expression) unless they are given on the command line. As +in the shell, an initial `.' in a filename does not match a wildcard at +the start of +.I pattern. +For simple-minded root-kits: add LS_OPTIONS="$LS_OPTIONS -I mystuff" +in /etc/profile or so, to hide your directories. +.TP +.B "\-L, \-\-dereference" +List the file information corresponding to the referrents of symbolic +links rather for the links themselves. +.TP +.B "\-N, \-\-literal" +Do not quote file names. +.TP +.B "\-Q, \-\-quote\-name, \-\-quoting\-style=c" +Enclose file names in double quotes and quote nongraphic characters as +in C. +.TP +.B "\-R, \-\-recursive" +List the contents of all directories recursively. +.TP +.B "\-S, \-\-sort=size" +Sort directory contents by file size instead of alphabetically, with +the largest files listed first. +.TP +.BI "\-T, \-\-tabsize " cols +Assume that each tabstop is +.I cols +columns wide. The default is 8 and can be overridden by +the environment variable TABSIZE when POSIXLY_CORRECT is not set. +.B ls +uses tabs where possible in the output, for efficiency. If +.I cols +is zero, do not use tabs at all. +.TP +.B "\-U, \-\-sort=none" +Do not sort directory contents; list them in whatever order they are +stored on the disk. (The difference between +.BR \-U " and " \-f +is that the former doesn't disable or enable options.) This is especially +useful when listing very large directories, since not doing any sorting +can be noticeably faster. +.TP +.B "\-X, \-\-sort=extension" +Sort directory contents alphabetically by file extension (characters +after the last `.'); files with no extension are sorted first. +.TP +.BI "\-\-block\-size=" size +Print sizes in blocks of +.I size +bytes. +(New in file\%utils-4.0.) +.TP +.BI "\-\-color[=" when ] +Specify whether to use color for distinguishing file types. +Colors are specified using the LS_COLORS environment variable. +For information on how to set this variable, see +.BR dircolors (1). +.I when +may be omitted, or one of: +.RS +.TP +.B none +Do not use color at all. This is the default. +.TP +.B auto +Only use color if standard output is a terminal. +.TP +.B always +Always use color. Specifying +.B \-\-color +and no +.I when +is equivalent to +.BR "\-\-color=always" . +.RE +.TP +.B "\-\-full\-time" +List times in full, rather than using the standard abbreviation +heuristics. The format is the same as +.BR date (1)'s +default; it's not possible to change this, but you can extract out the +date string with +.BR cut (1) +and then pass the result to `date \-d'. + +This is most useful because the time output includes the seconds. +(Unix filesystems store file timestamps only to the nearest +second, so this option shows all the information there is.) For +example, this can help when you have a Makefile that is not +regenerating files properly. +.TP +.BI "\-\-quoting\-style=" word +Use style +.I word +to quote output names. The +.I word +should be one of the following: +.RS +.TP +.B literal +Output names as\-is. This is the default behavior of +.BR ls . +.TP +.B shell +Quote names for the shell if they contain shell metacharacters or +would cause ambiguous output. +.TP +.B "shell\-always" +Quote names for the shell, even if they would normally not +require quoting. +.TP +.B c +Quote names as for a C language string; this is the same as the +.B "\-Q" +option. +.TP +.B escape +Quote as with +.I c +except omit the surrounding double\-quote characters; this is the same +as the +.B "\-b" +option. +.PD +.PP +A default value for this option can be specified with the environment +variable QUOTING_STYLE. (See +.B ENVIRONMENT +below.) +.RE +.TP +.B "\-\-show\-control\-chars" +Print nongraphic characters as-is in file names. This is the +default unless the output is a terminal and the program is +.BR ls . +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variable POSIXLY_CORRECT determines the choice of unit. +If it is not set, then the variable TABSIZE determines the +number of chars per tab stop. +The variable COLUMNS (when it contains the representation of a decimal +integer) determines the output column width (for use with the \-C option). +Filenames must not be truncated to make them fit a multi-column output. +.PP +The variables LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES and LC_TIME +have the usual meaning. +The variable TZ gives the time zone for time strings written by +.BR ls . +The variable LS_COLORS is used to specify the colors used. +The variable LS_OPTIONS gives default options. +.\" Since which ls version? +.PP +The variable QUOTING_STYLE is used to specify the default value for the +.B "\-\-quoting\-style" +option. It currently defaults to +.BR literal , +though the authors have warned that this default may change to +.B shell +in some future version of +.BR ls . +.SH BUGS +On BSD systems, the +.B "\-s" +option reports sizes that are half the correct values for files that are +NFS-mounted from HP-UX systems. On HP-UX systems, +.B ls +reports sizes that +are twice the correct values for files that are NFS-mounted from BSD +systems. This is due to a flaw in HP-UX; it also affects the HP-UX +.B ls +program. +.SH "CONFORMING TO" +POSIX 1003.2 +.SH "SEE ALSO" +.BR dircolors (1) +.SH NOTES +This page describes +.B ls +as found in the fileutils-4.0 package; +other versions may differ slightly. diff --git a/man1/mkdir.1 b/man1/mkdir.1 new file mode 100644 index 000000000..d696cf35e --- /dev/null +++ b/man1/mkdir.1 @@ -0,0 +1,69 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.TH MKDIR 1 1998-11 "GNU fileutils 4.0" +.SH NAME +mkdir \- make directories +.SH SYNOPSIS +.BI "mkdir [" options "] " directory... +.sp +POSIX options: +.BI "[\-p] [\-m " mode "] [\-\-]" +.sp +GNU options (shortest form): +.BI "[\-p] [\-m " mode "] [\-\-verbose]" +.BI "[\-\-help] [\-\-version] [\-\-]" +.SH DESCRIPTION +.B mkdir +creates directories with the specified names. +.PP +By default, the mode of created directories is 0777 (`a+rwx') +minus the bits set in the umask. +.SH OPTIONS +.TP +.BI "\-m " mode ", \-\-mode=" mode +Set the mode of created directories to +.IR mode , +which may be symbolic as in +.BR chmod (1) +and then uses the default mode as the point of departure. +.TP +.B "\-p, \-\-parents" +Make any missing parent directories for each +.I directory +argument. The mode +for parent directories is set to the umask modified by `u+wx'. +Ignore arguments corresponding to existing directories. +(Thus, if a directory /a exists, then `mkdir /a' is an error, +but `mkdir \-p /a' is not.) +.TP +.B "\-\-verbose" +Print a message for each created directory. This is most useful +with +.BR "\-\-parents" . +.TP +.B "\-\-" +Terminate option list. +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variables LANG, LC_ALL, LC_CTYPE and LC_MESSAGES have the +usual meaning. +.SH "CONFORMING TO" +POSIX 1003.2 +.SH NOTES +This page describes +.B mkdir +as found in the fileutils-4.0 package; +other versions may differ slightly. diff --git a/man1/mkfifo.1 b/man1/mkfifo.1 new file mode 100644 index 000000000..c4912d91b --- /dev/null +++ b/man1/mkfifo.1 @@ -0,0 +1,60 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.TH MKFIFO 1 1998-11 "GNU fileutils 4.0" +.SH NAME +mkfifo \- make FIFOs (named pipes) +.SH SYNOPSIS +.BI "mkfifo [" options "] " file... +.sp +POSIX options: +.BI "[\-m " mode "] [\-\-]" +.sp +GNU options (shortest form): +.BI "[\-m " mode "] [\-\-help] [\-\-version] [\-\-]" +.SH DESCRIPTION +.B mkfifo +creates FIFOs (also called "named pipes") with the +specified filenames. +.PP +A "FIFO" is a special file type that permits independent processes +to communicate. One process opens the FIFO file for writing, and +another for reading, after which data can flow as with the usual +anonymous pipe in shells or elsewhere. +.PP +By default, the mode of created FIFOs is 0666 (`a+rw') minus the bits set +in the umask. +.SH OPTIONS +.TP +.BI "\-m " mode ", \-\-mode=" mode +Set the mode of created FIFOs to +.IR mode , +which can be symbolic as in +.BR chmod (1) +and uses the default mode as the point of departure. +.TP +.B "\-\-" +Terminate option list. +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variables LANG, LC_ALL, LC_CTYPE and LC_MESSAGES have the +usual meaning. +.SH "CONFORMING TO" +POSIX 1003.2 +.SH NOTES +This page describes +.B mkfifo +as found in the fileutils-4.0 package; +other versions may differ slightly. diff --git a/man1/mknod.1 b/man1/mknod.1 new file mode 100644 index 000000000..7a98fb7c2 --- /dev/null +++ b/man1/mknod.1 @@ -0,0 +1,112 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.TH MKNOD 1 1998-11 "GNU fileutils 4.0" +.SH NAME +mknod \- make block or character special files +.SH SYNOPSIS +.BI "mknod [" options "] " name " {bc} " "major minor" +.br +.BI "mknod [" options "] " name " p" +.sp +GNU options (shortest form): +.BI "[\-m " mode "] [\-\-help] [\-\-version] [\-\-]" +.SH DESCRIPTION +.B mknod +creates a FIFO (named pipe), character special file, or block special +file with the specified +.IR name . +.PP +A special file is a triple (boolean, integer, integer) +stored in the filesystem. +The boolean chooses between character special file and +block special file. The two integers are the major and minor +device number. +.PP +Thus, a special file takes almost no place on disk, and is used +only for communication with the operating system, not for data +storage. Often special files refer to hardware devices (disk, tape, tty, +printer) or to operating system services (/dev/null, /dev/random). +.PP +Block special files usually are disk-like devices +(where data can be accessed given a block number, +and e.g. it is meaningful to have a block cache). +All other devices are character special files. +(Long ago the distinction was a different one: I/O to +a character special file would be unbuffered, to a block +special file buffered.) +.PP +The +.B mknod +command is what creates files of this type. +.PP +The argument following +.I name +specifies the type of file to make: +.RS +.TP +.B p +for a FIFO +.TP +.B b +for a block (buffered) special file +.TP +.B c +for a character (unbuffered) special file +.RE +.PP +The GNU version of +.B mknod +allows +.B u +(`unbuffered') as a synonym for +.BR c . +.PP +When making a block or character special file, the major and minor +device numbers must be given after the file type (in decimal, or +in octal with leading 0; the GNU version also allows hexadecimal +with leading 0x). +By default, the mode of created files is 0666 (`a+rw') minus the bits +set in the umask. +.SH OPTIONS +.TP +.BI "\-m " mode ", \-\-mode=" mode +Set the mode of created files to +.IR mode , +which can be symbolic as in +.BR chmod (1) +and then uses the default mode as the point of departure. +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH "CONFORMING TO" +POSIX does not describe this command as it is nonportable, +and recommends using +.BR mkfifo (1) +to make FIFOs. +SVID has a command +.I /etc/mknod +with the above syntax, but without the mode option. +.SH NOTES +On a Linux system (version 1.3.22 or newer) the file +.I /usr/src/linux/Documentation/devices.tex +contains a list of devices with device name, type, major and minor number. +.LP +The present page describes +.B mknod +as found in the fileutils-4.0 package; +other versions may differ slightly. +.SH "SEE ALSO" +.BR chmod (1), +.BR mkfifo (1), +.BR mknod (2) diff --git a/man1/mv.1 b/man1/mv.1 new file mode 100644 index 000000000..dd812a801 --- /dev/null +++ b/man1/mv.1 @@ -0,0 +1,168 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.TH MV 1 1998-11 "GNU fileutils 4.0" +.SH NAME +mv \- move (rename) files +.SH SYNOPSIS +.BI "mv [" "option..." "] " "source target" +.br +.BI "mv [" "option..." "] " "source... target" +.sp +POSIX options: +.B "[\-fi] [\-\-]" +.sp +GNU options (shortest form): +.BI "[\-bfiuv] [\-S " suffix "] [\-V {numbered,existing,simple}] " +.B "[\-\-help] [\-\-version] [\-\-]" +.SH DESCRIPTION +.B mv +moves or renames files or directories. +.PP +If the last argument names an existing directory, +.B mv +moves each other given file into a file with the same name in that +directory. Otherwise, if only two files are given, it renames the +first as the second. It is an error if the last argument is not a +directory and more than two files are given. +.PP +Thus, `mv /a/x/y /b' will rename the file /a/x/y into /b/y if /b +was an existing directory, and into /b otherwise. +.PP +Let us call the file a given file is going to be moved into its +.IR destination . +If +.I destination +exists, and either the \-i option is given, or +.I destination +is unwritable, standard input is a terminal, and the +.B "\-f" +option is not given, +.B mv +prompts the user for whether to replace the file, writing a question +to stderr and reading an answer from stdin. If the response +is not affirmative, the file is skipped. +.PP +When both +.I source +and +.I destination +are on the same filesystem, they are the same file (just the name is +changed; owner, mode, timestamps remain unchanged). +When they are on different filesystems, the source file is copied +and then deleted. +.B mv +will copy modification time, access time, user and group ID, and mode +if possible. When copying user and/or group ID fails, the setuid and +setgid bits are cleared in the copy. +.SH "POSIX OPTIONS" +.TP +.B "\-f" +Do not prompt for confirmation. +.TP +.B "\-i" +Prompt for confirmation when +.I destination +exists. +(In case both \-f and \-i are given, the last one given takes effect.) +.TP +.B "\-\-" +Terminate option list. +.SH "GNU DETAILS" +The GNU implementation (in fileutils-3.16) is broken in the sense that +.B mv +can move only regular files across filesystems. +.SH "GNU OPTIONS" +.TP +.B "\-f, \-\-force" +Remove existing destination files and never prompt the user. +.TP +.B "\-i, \-\-interactive" +Prompt whether to overwrite existing regular destination files. +If the response is not affirmative, the file is skipped. +.TP +.B "\-u, \-\-update" +Do not move a nondirectory that has an existing destination with +the same or newer modification time. +.TP +.B "\-v, \-\-verbose" +Print the name of each file before moving it. +.SH "GNU BACKUP OPTIONS" +The GNU versions of programs like +.BR cp , +.BR mv , +.BR ln , +.B install +and +.B patch +will make a backup of files about to be overwritten, changed or destroyed +if that is desired. That backup files are desired is indicated by +the \-b option. How they should be named is specified by the \-V option. +In case the name of the backup file is given by the name of the file +extended by a suffix, this suffix is specified by the \-S option. +.TP +.B "\-b, \-\-backup" +Make backups of files that are about to be overwritten or removed. +.TP +.BI "\-S " SUFFIX ", \-\-suffix=" SUFFIX +Append +.I SUFFIX +to each backup file made. +If this option is not specified, the value of the +.B SIMPLE_BACKUP_SUFFIX +environment variable is used. And if +.B SIMPLE_BACKUP_SUFFIX +is not set, the default is `~'. +.TP +.BI "\-V " METHOD ", \-\-version\-control=" METHOD +.RS +Specify how backup files are named. The +.I METHOD +argument can be `numbered' (or `t'), `existing' (or `nil'), or `never' (or +`simple'). +If this option is not specified, the value of the +.B VERSION_CONTROL +environment variable is used. And if +.B VERSION_CONTROL +is not set, the default backup type is `existing'. +.PP +This option corresponds to the Emacs variable `version-control'. +The valid +.IR METHOD s +are (unique abbreviations are accepted): +.TP +.BR t ", " numbered +Always make numbered backups. +.TP +.BR nil ", " existing +Make numbered backups of files that already have them, simple +backups of the others. +.TP +.BR never ", " simple +Always make simple backups. +.RE +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variables LANG, LC_ALL, LC_COLLATE, LC_CTYPE and LC_MESSAGES have the +usual meaning. For the GNU version, the variables SIMPLE_BACKUP_SUFFIX +and VERSION_CONTROL control backup file naming, as described above. +.SH "CONFORMING TO" +POSIX 1003.2, except that directory hierarchies cannot be moved +across filesystems. +.SH NOTES +This page describes +.B mv +as found in the fileutils-4.0 package; +other versions may differ slightly. diff --git a/man1/rm.1 b/man1/rm.1 new file mode 100644 index 000000000..93235ce5e --- /dev/null +++ b/man1/rm.1 @@ -0,0 +1,116 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.TH RM 1 1998-11 "GNU fileutils 4.0" +.SH NAME +rm \- remove files or directories +.SH SYNOPSIS +.BI "rm [" options "] " file... +.sp +POSIX options: +.B "[\-fiRr] [\-\-]" +.sp +GNU options (shortest form): +.B [\-dfirvR] +.B "[\-\-help] [\-\-version] [\-\-]" +.SH DESCRIPTION +.B rm +removes each given +.IR file . +By default, it does not remove directories. +But when the \-r or \-R option is given, the entire directory tree +below the specified directory is removed (and there are no limitations +on the depth of directory trees that can be removed by `rm \-r'). +It is an error when the last path component of +.I file +is either . or .. +(so as to avoid unpleasant surprises with `rm \-r .*' or so). +.PP +If the \-i option is given, or +if a file is unwritable, standard input is a terminal, and the +.B "\-f" +option is not given, +.B rm +prompts the user for whether to remove the file, writing a question +to stderr and reading an answer from stdin. If the response +is not affirmative, the file is skipped. +.SH "POSIX OPTIONS" +.TP +.B "\-f" +Do not prompt for confirmation. Do not write diagnostic messages. +Do not produce an error return status if the only errors were +nonexisting files. +.TP +.B "\-i" +Prompt for confirmation. +(In case both \-f and \-i are given, the last one given takes effect.) +.TP +.BR "\-r" " or " "\-R" +Recursively remove directory trees. +.TP +.B "\-\-" +Terminate option list. +.SH "SVID DETAILS" +The System V Interface Definition forbids removal of the +last link to an executable binary file that is being executed. +.SH "GNU DETAILS" +The GNU implementation (in fileutils-3.16) is broken in the sense +that there is an upper limit to the depth of hierarchies that can be +removed. (If necessary, a utility `deltree' can be used to remove +very deep trees.) +.SH "GNU OPTIONS" +.TP +.B "\-d, \-\-directory" +Remove directories with +.BR unlink (2) +instead of +.BR rmdir (2), +and don't +require a directory to be empty before trying to unlink it. Only +works if you have appropriate privileges. Because unlinking a +directory causes any files in the deleted directory to become +unreferenced, it is wise to +.BR fsck (8) +the filesystem after doing this. +.TP +.B "\-f, \-\-force" +Ignore nonexistent files and never prompt the user. +.TP +.B "\-i, \-\-interactive" +Prompt whether to remove each file. If the response is not affirmative, +the file is skipped. +.TP +.B "\-r, \-R, \-\-recursive" +Remove the contents of directories recursively. +.TP +.B "\-v, \-\-verbose" +Print the name of each file before removing it. +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variables LANG, LC_ALL, LC_COLLATE, LC_CTYPE and LC_MESSAGES have the +usual meaning. +.SH "CONFORMING TO" +POSIX 1003.2, except for the limitation on file hierarchy depth. +.SH NOTES +This page describes +.B rm +as found in the fileutils-4.0 package; +other versions may differ slightly. +.LP +Sometimes one wishes to recover deleted files. +It helps to have backups. It helps to use a trash directory, +so that removed files are only moved to the trash. But actually +removed files, although gone in principle, can sometimes be recovered. +For details for the ext2 filesystem, see the Ext2fs-Undeletion mini-Howto. diff --git a/man1/rmdir.1 b/man1/rmdir.1 new file mode 100644 index 000000000..f4a9310aa --- /dev/null +++ b/man1/rmdir.1 @@ -0,0 +1,76 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.TH RMDIR 1 1998-11 "GNU fileutils 4.0" +.SH NAME +rmdir \- remove empty directories +.SH SYNOPSIS +.BI "rmdir [" options "] " directory... +.sp +POSIX options: +.B "[\-p] [\-\-]" +.sp +GNU options (shortest form): +.B [\-p] +.B [\-\-ignore\-fail\-on\-non\-empty] +.B "[\-\-help] [\-\-version] [\-\-]" +.SH DESCRIPTION +.B rmdir +removes empty directories. +.PP +If any +.I directory +argument does not refer to an existing empty directory, it is an error. +.SH "POSIX OPTIONS" +.TP +.B "\-p" +If +.I directory +includes more than one pathname component, remove it, then strip +the last component and remove the resulting directory, etc., until +all components have been removed. Thus, `rmdir \-p a/b/c' is +equivalent to `rmdir a/b/c; rmdir a/b; rmdir a'. +.TP +.B "\-\-" +Terminate option list. +.SH "GNU OPTIONS" +.TP +.B "\-\-ignore\-fail\-on\-non\-empty" +Normally +.B rmdir +will refuse to remove a directory that is not empty. This option +causes +.B rmdir +to ignore the failure to remove a directory, if that failure is due +to the directory being non-empty. +(New in file\%utils-4.0.) +.TP +.B "\-p, \-\-parents" +As above. +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variables LANG, LC_ALL, LC_CTYPE and LC_MESSAGES have the +usual meaning. +.SH "CONFORMING TO" +POSIX 1003.2 +.SH "EXAMPLE OF USE" +The command `\fIrmdir foo\fP' will remove the directory \fIfoo\fP +if it is empty. To remove a nonempty directory, together with everything +below, use `\fIrm -r foo\fP'. +.SH NOTES +This page describes +.B rmdir +as found in the fileutils-4.0 package; +other versions may differ slightly. diff --git a/man1/time.1 b/man1/time.1 new file mode 100644 index 000000000..e7a537bea --- /dev/null +++ b/man1/time.1 @@ -0,0 +1,270 @@ +.\" Copyright Andries Brouwer, 2000 +.\" +.\" This page is distributed under GPL. +.\" Some fragments of text came from the time-1.7 info file. +.\" Inspired by kromJx@crosswinds.net. +.\" +.TH TIME 1 2000-12-11 "" "" +.SH NAME +time \- time a simple command or give resource usage +.SH SYNOPSIS +.BI "time [" options "] " command " [" arguments... "] " +.SH DESCRIPTION +The +.B time +command runs the specified program +.I command +with the given arguments. +When +.I command +finishes, +.B time +writes a message to standard output giving timing statistics +about this program run. +These statistics consist of (i) the elapsed real time +between invocation and termination, (ii) the user CPU time +(the sum of the +.I tms_utime +and +.I tms_cutime +values in a +.I "struct tms" +as returned by +.BR times (2)), +and (iii) the system CPU time (the sum of the +.I tms_stime +and +.I tms_cstime +values in a +.I "struct tms" +as returned by +.BR times (2)). +.SH OPTION +.TP +.B \-p +When in the POSIX locale, use the precise traditional format +.br +.in +5 +"real %f\enuser %f\ensys %f\en" +.in -5 +.br +(with numbers in seconds) +where the number of decimals in the output for %f is unspecified +but is sufficient to express the clock tick accuracy, and at least one. +.SH ENVIRONMENT +The variables LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, LC_NUMERIC, +NLSPATH and PATH are used. The last one to search for +.IR command . +The remaining ones for the text and formatting of the output. +.SH "EXIT STATUS" +If +.I command +was invoked, the exit status is that of +.IR command . +Otherwise it is 127 if +.I command +could not be found, 126 if it could be found but could not be invoked, +and some other nonzero value (1-125) if something else went wrong. +.SH "SEE ALSO" +.BR times (2) +.sp 2 +.SH "GNU VERSION" +Below a description of the GNU 1.7 version of +.BR time . +Disregarding the name of the utility, GNU makes it output lots of +useful information, not only about time used, but also on other +resources like memory, I/O and IPC calls (where available). +The output is formatted using a format string that can be specified +using the \-f option or the TIME environment variable. +.LP +The default format string is +.br +.in +3 +%Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k +.br +%Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps +.br +.in -3 +.LP +When the \-p option is given the (portable) output format +.br +.in +3 +real %e +.br +user %U +.br +sys %S +.br +.in -3 +is used. +.SS "The format string" +The format is interpreted in the usual printf-like way. +Ordinary characters are directly copied, tab, newline +and backslash are escaped using \et, \en and \e\e, +a percent sign is represented by %%, and otherwise % +indicates a conversion. The program +.B time +will always add a trailing newline itself. +The conversions follow. All of those used by +.BR tcsh (1) +are supported. +.LP +.B "Time" +.TP +.B %E +Elapsed real time (in [hours:]minutes:seconds). +.TP +.B %e +(Not in tcsh.) Elapsed real time (in seconds). +.TP +.B %S +Total number of CPU-seconds that the process spent in kernel mode. +.TP +.B %U +Total number of CPU-seconds that the process spent in user mode. +.TP +.B %P +Percentage of the CPU that this job got, computed as (%U + %S) / %E. +.LP +.B "Memory" +.TP +.B %M +Maximum resident set size of the process during its lifetime, in Kbytes. +.TP +.B %t +(Not in tcsh.) Average resident set size of the process, in Kbytes. +.TP +.B %K +Average total (data+stack+text) memory use of the process, +in Kbytes. +.TP +.B %D +Average size of the process's unshared data area, in Kbytes. +.TP +.B %p +(Not in tcsh.) Average size of the process's unshared stack space, in Kbytes. +.TP +.B %X +Average size of the process's shared text space, in Kbytes. +.TP +.B %Z +(Not in tcsh.) System's page size, in bytes. +This is a per-system constant, but varies between systems. +.TP +.B %F +Number of major page faults that occurred while the process was running. +These are faults where the page has to be read in from disk. +.TP +.B %R +Number of minor, or recoverable, page faults. +These are faults for pages that are not valid but which have +not yet been claimed by other virtual pages. Thus the data +in the page is still valid but the system tables must be updated. +.TP +.B %W +Number of times the process was swapped out of main memory. +.TP +.B %c +Number of times the process was context-switched involuntarily +(because the time slice expired). +.TP +.B %w +Number of waits: times that the program was context-switched voluntarily, +for instance while waiting for an I/O operation to complete. +.LP +.B "I/O" +.TP +.B %I +Number of file system inputs by the process. +.TP +.B %O +Number of file system outputs by the process. +.TP +.B %r +Number of socket messages received by the process. +.TP +.B %s +Number of socket messages sent by the process. +.TP +.B %k +Number of signals delivered to the process. +.TP +.B %C +(Not in tcsh.) Name and command line arguments of the command being timed. +.TP +.B %x +(Not in tcsh.) Exit status of the command. +.SH "GNU OPTIONS" +.TP +.BI "\-f " FORMAT ", \-\-format=" FORMAT +Specify output format, possibly overriding the format specified +in the environment variable TIME. +.TP +.B "\-p, \-\-portability" +Use the portable output format. +.TP +.BI "\-o " FILE ", \-\-output=" FILE +Do not send the results to stderr, but overwrite the specified file. +.TP +.B "\-a, \-\-append" +(Used together with \-o.) Do not overwrite but append. +.TP +.B "\-v, \-\-verbose" +Give very verbose output about all the program knows about. +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-V, \-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH BUGS +Not all resources are measured by all versions of Unix, +so some of the values might be reported as zero. +The present selection was mostly inspired by the data +provided by 4.2 or 4.3BSD. +.LP +GNU time version 1.7 is not yet localized. +Thus, it does not implement the POSIX requirements. +.LP +The environment variable TIME was badly chosen. +It is not unusual for systems like autoconf or make +to use environment variables with the name of a utility to override +the utility to be used. Uses like MORE or TIME for options to programs +(instead of program path names) tend to lead to difficulties. +.LP +It seems unfortunate that \-o overwrites instead of appends. +(That is, the \-a option should be the default.) +.LP +Mail suggestions and bug reports for GNU +.B time +to +.br +.I bug-utils@prep.ai.mit.edu +.br +Please include the version of +.B time , +which you can get by running +.br +.I time --version +.br +and the operating system +and C compiler you used. +.SH "SEE ALSO" +.BR tcsh (1), +.BR times (2), +.BR wait3 (2) +.SH AUTHORS +.TP +.IP "David Keppel" +Original version +.IP "David MacKenzie" +POSIXization, autoconfiscation, GNU getoptization, +documentation, other bug fixes and improvements. +.IP "Arne Henrik Juul" +Helped with portability +.IP "Francois Pinard" +Helped with portability diff --git a/man1/touch.1 b/man1/touch.1 new file mode 100644 index 000000000..0b0304654 --- /dev/null +++ b/man1/touch.1 @@ -0,0 +1,170 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.TH TOUCH 1 1998-11 "GNU fileutils 4.0" +.SH NAME +touch \- change file timestamps +.SH SYNOPSIS +.B touch +.BI "[\-acm][\-r " ref_file "|\-t " time "] [\-\-] " file... +.sp +Obsolescent version: +.br +.B touch +.BI "[\-acm][" ugly_time "] " file... +.sp +GNU version: +.br +.B touch +.BI "[\-acfm] [\-r " file "] [\-t " decimtime ] +.BI "[\-d " time "] [\-\-time={atime,access,use,mtime,modify}]" +.BI "[\-\-date=" time "] [\-\-reference=" file ] +.BI "[\-\-no\-create] [\-\-help] [\-\-version] [\-\-] " file... +.SH DESCRIPTION +.B touch +changes the access and/or modification timestamps of each +specified +.IR file . +These timestamps are changed to the current time, unless +the \-r option is specified, in which case they are changed +to the corresponding timestamps of the file +.IR ref_file , +or the \-t option is specified, in which case they are changed +to the specified +.IR time . +Both times are changed when neither or both of the \-a and \-m +options are given. Only the access or only the modification time +is changed when one of the options \-a and \-m is given. +If the file did not exist yet, it is created (as an empty file +with mode 0666, modified by the umask), unless the \-c option is given. +.SH "POSIX OPTIONS" +.TP +.B \-a +Change the access time of +.IR file . +.TP +.B \-c +Do not create +.IR file . +.TP +.B \-m +Change the modification time of +.IR file . +.TP +.BI "\-r " ref_file +Use the corresponding timestamp of +.I ref_file +as the new value for the changed timestamp(s). +.TP +.BI "\-t " time +Use the specified time as the new value for the changed timestamp(s). +The argument is a decimal number of the form +.br +.nf + [[CC]YY]MMDDhhmm[.SS] +.br +.fi +with the obvious meaning. If CC is not specified, the year CCYY +is taken to be in the range 1969-2068. +If SS is not specified, it is taken to be 0. It may be specified +in the range 0-61 so that it is possible to refer to leap seconds. +The resulting time is taken as a time for the time zone specified by +the environment variable TZ. It is an error if the resulting time +precedes 1 January 1970. +.TP +.B "\-\-" +Terminate option list. +.SH "POSIX DETAILS" +The second form of invocation has the disadvantage that there is +some ambiguity as to whether +.I ugly_time +is a time or a file argument. It is taken to be a time when +no \-r or \-t option is present, there are at least two arguments, +and the first argument is an eight- or ten-digit decimal integer. +The format of +.I ugly_time +is MMDDhhmm[yy], where an yy in the range 69-99 denotes a year +in the range 1969-1999, and an unspecified yy denotes the current year. +This form is obsolete. +.SH "GNU DETAILS" +If the first +.I file +would be a valid argument to the +.B "\-t" +option and no timestamp is given with any of the +.BR "\-d" , +.BR "\-r" +or +.B "\-t" +options and the `\-\-' argument is not given, that argument is +interpreted as the time for the other files instead of as a file name. +.PP +If changing both the access and modification times to the current +time, +.B touch +can change the timestamps for files that the user running it does +not own but has write permission for. Otherwise, the user must +own the files. +.SH "GNU OPTIONS" +.TP +.B "\-a, \-\-time=atime, \-\-time=access, \-\-time=use" +Change the access time only. +.TP +.B "\-c, \-\-no\-create" +Do not create files that do not exist. +.TP +.BI "\-d, \-\-date=" time +Use +.I time +instead of the current time. It can contain month names, +time zones, `am' and `pm', etc. +.TP +.B "\-f" +Ignored; for compatibility with BSD versions of +.BR touch (1). +.TP +.B "\-m, \-\-time=mtime, \-\-time=modify" +Change the modification time only. +.TP +.BI "\-r " file ", \-\-reference=" file +Use the times of the reference +.I file +instead of the current time. +.TP +.BI "\-t " decimtime +Here +.I decimtime +has the format MMDDhhmm[[CC]YY][.ss] +Use the argument (months, days, hours, minutes, optional century +and years, optional seconds) instead of the current time. +Note that this format violates the POSIX specification. +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variable TZ is used to interpret explicitly given times. +The variables LANG, LC_ALL, LC_CTYPE and LC_MESSAGES have the +usual meaning. +.SH "CONFORMING TO" +POSIX 1003.2 describes a syntax for the argument of the \-t option +that differs from that used by the GNU implementation. +.SH "EXAMPLE OF USE" +The command `\fItouch foo\fP' will create the file \fIfoo\fP +if it didn't exist, and change the time of last modification to now. +It is often used to guide the actions of +.BR make . +.SH NOTES +This page describes +.B touch +as found in the fileutils-4.0 package; +other versions may differ slightly. diff --git a/man1/vdir.1 b/man1/vdir.1 new file mode 100644 index 000000000..a85b838f9 --- /dev/null +++ b/man1/vdir.1 @@ -0,0 +1 @@ +.so man1/ls.1 diff --git a/man1p/admin.1p b/man1p/admin.1p new file mode 100644 index 000000000..28fe5afb5 --- /dev/null +++ b/man1p/admin.1p @@ -0,0 +1,436 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ADMIN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" admin +.SH NAME +admin \- create and administer SCCS files (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBadmin -i\fP\fB[\fP\fIname\fP\fB][\fP\fB-n\fP\fB][\fP\fB-a\fP +\fIlogin\fP\fB][\fP\fB-d\fP \fIflag\fP\fB][\fP\fB-e\fP \fIlogin\fP\fB][\fP\fB-f\fP +\fIflag\fP\fB][\fP\fB-m\fP +\fImrlist\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-r\fP +\fIrel\fP\fB][\fP\fB-t\fP\fB[\fP\fIname\fP\fB][\fP\fB-y\fP\fB[\fP\fIcomment\fP\fB]]\fP +\fInewfile\fP\fB +.br +.sp +admin -n\fP\fB[\fP\fB-a\fP \fIlogin\fP\fB][\fP\fB-d\fP \fIflag\fP\fB][\fP\fB-e\fP +\fIlogin\fP\fB][\fP\fB-f\fP +\fIflag\fP\fB][\fP\fB-m\fP \fImrlist\fP\fB][\fP\fB-t\fP\fB[\fP\fIname\fP\fB]]\fP\fB +.br +\ \ \ \ \ \ \fP \fB[\fP\fB-y\fP\fB[\fP\fIcomment\fP\fB]]\fP \fInewfile\fP +\fB\&... +.br +.sp +admin\fP \fB[\fP\fB-a\fP \fIlogin\fP\fB][\fP\fB-d\fP \fIflag\fP\fB][\fP\fB-m\fP +\fImrlist\fP\fB][\fP\fB-r\fP +\fIrel\fP\fB][\fP\fB-t\fP\fB[\fP\fIname\fP\fB]]\fP \fB\fP\fIfile\fP +\fB\&... +.br +.sp +admin -h\fP \fIfile\fP \fB... +.br +.sp +admin -z\fP \fIfile\fP \fB... \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIadmin\fP utility shall create new SCCS files or change parameters +of existing ones. If a named file does not exist, it +shall be created, and its parameters shall be initialized according +to the specified options. Parameters not initialized by an +option shall be assigned a default value. If a named file does exist, +parameters corresponding to specified options shall be +changed, and other parameters shall be left as is. +.LP +All SCCS filenames supplied by the application shall be of the form +s.\fIfilename\fP. New SCCS files shall be given read-only +permission mode. Write permission in the parent directory is required +to create a file. All writing done by \fIadmin\fP shall be +to a temporary \fIx-file\fP, named x.\fIfilename\fP (see \fIget\fP +) created with read-only mode if +\fIadmin\fP is creating a new SCCS file, or created with the same +mode as that of the SCCS file if the file already exists. After +successful execution of \fIadmin\fP, the SCCS file shall be removed +(if it exists), and the \fIx-file\fP shall be renamed with +the name of the SCCS file. This ensures that changes are made to the +SCCS file only if no errors occur. +.LP +The \fIadmin\fP utility shall also use a transient lock file (named +z.\fIfilename\fP), which is used to prevent simultaneous +updates to the SCCS file; see \fIget\fP . +.SH OPTIONS +.LP +The \fIadmin\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that the \fB-i\fP, \fB-t\fP, and +\fB-y\fP options have optional option-arguments. These optional option-arguments +shall not be presented as separate arguments. The +following options are supported: +.TP 7 +\fB-n\fP +Create a new SCCS file. When \fB-n\fP is used without \fB-i\fP, the +SCCS file shall be created with control information but +without any file data. +.TP 7 +\fB-i[\fP\fIname\fP\fB]\fP +Specify the \fIname\fP of a file from which the text for a new SCCS +file shall be taken. The text constitutes the first delta +of the file (see the \fB-r\fP option for the delta numbering scheme). +If the \fB-i\fP option is used, but the \fIname\fP +option-argument is omitted, the text shall be obtained by reading +the standard input. If this option is omitted, the SCCS file +shall be created with control information but without any file data. +The \fB-i\fP option implies the \fB-n\fP option. +.TP 7 +\fB-r\ \fP \fISID\fP +Specify the SID of the initial delta to be inserted. This SID shall +be a trunk SID; that is, the branch and sequence numbers +shall be zero or missing. The level number is optional, and defaults +to 1. +.TP 7 +\fB-t[\fP\fIname\fP\fB]\fP +Specify the \fIname\fP of a file from which descriptive text for the +SCCS file shall be taken. In the case of existing SCCS +files (neither \fB-i\fP nor \fB-n\fP is specified): +.RS +.IP " *" 3 +A \fB-t\fP option without a \fIname\fP option-argument shall cause +the removal of descriptive text (if any) currently in the +SCCS file. +.LP +.IP " *" 3 +A \fB-t\fP option with a \fIname\fP option-argument shall cause the +text (if any) in the named file to replace the descriptive +text (if any) currently in the SCCS file. +.LP +.RE +.TP 7 +\fB-f\ \fP \fIflag\fP +Specify a \fIflag\fP, and, possibly, a value for the \fIflag\fP, to +be placed in the SCCS file. Several \fB-f\fP options may +be supplied on a single \fIadmin\fP command line. Implementations +shall recognize the following flags and associated values: +.TP 7 +\fBb\fP +.RS +Allow use of the \fB-b\fP option on a \fIget\fP command to create +branch deltas. +.RE +.TP 7 +\fBc\fP\fIceil\fP +.RS +Specify the highest release (that is, ceiling), a number less than +or equal to 9999, which may be retrieved by a \fIget\fP command for +editing. The default value for an unspecified \fBc\fP flag shall be +9999. +.RE +.TP 7 +\fBf\fP\fIfloor\fP +.RS +Specify the lowest release (that is, floor), a number greater than +0 but less than 9999, which may be retrieved by a \fIget\fP command +for editing. The default value for an unspecified \fBf\fP flag shall +be 1. +.RE +.TP 7 +\fBd\fP\fISID\fP +.RS +Specify the default delta number (SID) to be used by a \fIget\fP command. +.RE +.TP 7 +\fBi\fP\fIstr\fP +.RS +Treat the "No ID keywords" message issued by \fIget\fP or \fIdelta\fP +as a fatal error. In the absence of this flag, the message is only +a warning. The +message is issued if no SCCS identification keywords (see \fIget\fP +) are found in the text retrieved or +stored in the SCCS file. If a value is supplied, the application shall +ensure that the keywords exactly match the given string; +however, the string shall contain a keyword, and no embedded s. +.RE +.TP 7 +\fBj\fP +.RS +Allow concurrent \fIget\fP commands for editing on the same SID of +an SCCS file. This +allows multiple concurrent updates to the same version of the SCCS +file. +.RE +.TP 7 +\fBl\fP\fIlist\fP +.RS +Specify a \fIlist\fP of releases to which deltas can no longer be +made (that is, \fIget\fP \fB-e\fP against one of these locked releases +fails). Conforming applications shall use the +following syntax to specify a \fIlist\fP. Implementations may accept +additional forms as an extension: +.sp +.RS +.nf + +\fB ::= a | + ::= | , + ::= +\fP +.fi +.RE +.LP +The character \fIa\fP in the \fIlist\fP shall be equivalent to specifying +all releases for the named SCCS file. The +non-terminal <\fISID\fP> in range shall be the delta number of an +existing delta associated with the SCCS file. +.RE +.TP 7 +\fBn\fP +.RS +Cause \fIdelta\fP to create a null delta in each of those releases +(if any) being +skipped when a delta is made in a new release (for example, in making +delta 5.1 after delta 2.7, releases 3 and 4 are skipped). +These null deltas shall serve as anchor points so that branch deltas +may later be created from them. The absence of this flag shall +cause skipped releases to be nonexistent in the SCCS file, preventing +branch deltas from being created from them in the future. +During the initial creation of an SCCS file, the \fBn\fP flag may +be ignored; that is, if the \fB-r\fP option is used to set the +release number of the initial SID to a value greater than 1, null +deltas need not be created for the "skipped" releases. +.RE +.TP 7 +\fBq\fP\fItext\fP +.RS +Substitute user-definable \fItext\fP for all occurrences of the %\fBQ\fP% +keyword in the SCCS file text retrieved by \fIget\fP. +.RE +.TP 7 +\fBm\fP\fImod\fP +.RS +Specify the module name of the SCCS file substituted for all occurrences +of the %\fBM\fP% keyword in the SCCS file text +retrieved by \fIget\fP. If the \fBm\fP flag is not specified, the +value assigned shall be the +name of the SCCS file with the leading \fB'.'\fP removed. +.RE +.TP 7 +\fBt\fP\fItype\fP +.RS +Specify the \fItype\fP of module in the SCCS file substituted for +all occurrences of the %\fBY\fP% keyword in the SCCS file +text retrieved by \fIget\fP. +.RE +.TP 7 +\fBv\fP\fIpgm\fP +.RS +Cause \fIdelta\fP to prompt for modification request (MR) numbers +as the reason for +creating a delta. The optional value specifies the name of an MR number +validation program. (If this flag is set when creating an +SCCS file, the application shall ensure that the \fBm\fP option is +also used even if its value is null.) +.RE +.sp +.TP 7 +\fB-d\ \fP \fIflag\fP +Remove (delete) the specified \fIflag\fP from an SCCS file. Several +\fB-d\fP options may be supplied on a single \fIadmin\fP +command. See the \fB-f\fP option for allowable \fIflag\fP names. (The +\fBl\fP \fIlist\fP flag gives a \fIlist\fP of releases +to be unlocked. See the \fB-f\fP option for further description of +the \fBl\fP flag and the syntax of a \fIlist\fP.) +.TP 7 +\fB-a\ \fP \fIlogin\fP +Specify a \fIlogin\fP name, or numerical group ID, to be added to +the list of users who may make deltas (changes) to the SCCS +file. A group ID shall be equivalent to specifying all \fIlogin\fP +names common to that group ID. Several \fB-a\fP options may be +used on a single \fIadmin\fP command line. As many \fIlogin\fPs, or +numerical group IDs, as desired may be on the list +simultaneously. If the list of users is empty, then anyone may add +deltas. If \fIlogin\fP or group ID is preceded by a +\fB'!'\fP , the users so specified shall be denied permission to make +deltas. +.TP 7 +\fB-e\ \fP \fIlogin\fP +Specify a \fIlogin\fP name, or numerical group ID, to be erased from +the list of users allowed to make deltas (changes) to the +SCCS file. Specifying a group ID is equivalent to specifying all \fIlogin\fP +names common to that group ID. Several \fB-e\fP +options may be used on a single \fIadmin\fP command line. +.TP 7 +\fB-y[\fP\fIcomment\fP\fB]\fP +Insert the \fIcomment\fP text into the SCCS file as a comment for +the initial delta in a manner identical to that of \fIdelta\fP. In +the POSIX locale, omission of the \fB-y\fP option shall result in +a default comment +line being inserted in the form: +.sp +.RS +.nf + +\fB"date and time created %s %s by %s", <\fP\fIdate\fP\fB>, <\fP\fItime\fP\fB>, <\fP\fIlogin\fP\fB> +\fP +.fi +.RE +.LP +where <\fIdate\fP> is expressed in the format of the \fIdate\fP utility's +\fB%y\fP / \fB%m\fP / \fB%d\fP conversion specification, <\fItime\fP> +in the format of the \fIdate\fP utility's \fB%T\fP conversion specification +format, and <\fIlogin\fP> is the +login name of the user creating the file. +.TP 7 +\fB-m\ \fP \fImrlist\fP +Insert the list of modification request (MR) numbers into the SCCS +file as the reason for creating the initial delta in a +manner identical to \fIdelta\fP. The application shall ensure that +the \fBv\fP flag is set +and the MR numbers are validated if the \fBv\fP flag has a value (the +name of an MR number validation program). A diagnostic +message shall be written if the \fBv\fP flag is not set or MR validation +fails. +.TP 7 +\fB-h\fP +Check the structure of the SCCS file and compare the newly computed +checksum with the checksum that is stored in the SCCS file. +If the newly computed checksum does not match the checksum in the +SCCS file, a diagnostic message shall be written. +.TP 7 +\fB-z\fP +Recompute the SCCS file checksum and store it in the first line of +the SCCS file (see the \fB-h\fP option above). Note that +use of this option on a truly corrupted file may prevent future detection +of the corruption. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile\fP +A pathname of an existing SCCS file or a directory. If \fIfile\fP +is a directory, the \fIadmin\fP utility shall behave as +though each file in the directory were specified as a named file, +except that non-SCCS files (last component of the pathname does +not begin with \fBs.\fP) and unreadable files shall be silently ignored. +.TP 7 +\fInewfile\fP +A pathname of an SCCS file to be created. +.sp +.LP +If exactly one \fIfile\fP or \fInewfile\fP operand appears, and it +is \fB'-'\fP , the standard input shall be read; each +line of the standard input shall be taken to be the name of an SCCS +file to be processed. Non-SCCS files and unreadable files shall +be silently ignored. +.SH STDIN +.LP +The standard input shall be a text file used only if \fB-i\fP is specified +without an option-argument or if a \fIfile\fP or +\fInewfile\fP operand is specified as \fB'-'\fP . If the first character +of any standard input line is in the POSIX +locale, the results are unspecified. +.SH INPUT FILES +.LP +The existing SCCS files shall be text files of an unspecified format. +.LP +The application shall ensure that the file named by the \fB-i\fP option's +\fIname\fP option-argument shall be a text file; if +the first character of any line in this file is in the POSIX +locale, the results are unspecified. If this file contains +more than 99999 lines, the number of lines recorded in the header +for this file shall be 99999 for this delta. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIadmin\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +the contents of the default \fB-y\fP comment. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +Any SCCS files created shall be text files of an unspecified format. +During processing of a \fIfile\fP, a locking +\fIz-file\fP, as described in \fIget\fP , may be created and deleted. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +It is recommended that directories containing SCCS files be writable +by the owner only, and that SCCS files themselves be +read-only. The mode of the directories should allow only the owner +to modify SCCS files contained in the directories. The mode of +the SCCS files prevents any modification at all except by SCCS commands. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIdelta\fP , \fIget\fP , \fIprs\fP , \fIwhat\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/alias.1p b/man1p/alias.1p new file mode 100644 index 000000000..a5fb510f7 --- /dev/null +++ b/man1p/alias.1p @@ -0,0 +1,212 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ALIAS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" alias +.SH NAME +alias \- define or display aliases +.SH SYNOPSIS +.LP +\fBalias\fP \fB[\fP\fIalias-name\fP\fB[\fP\fB=\fP\fIstring\fP\fB]\fP +\fB\&...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIalias\fP utility shall create or redefine alias definitions +or write the values of existing alias definitions to +standard output. An alias definition provides a string value that +shall replace a command name when it is encountered; see \fIAlias +Substitution\fP . +.LP +An alias definition shall affect the current shell execution environment +and the execution environments of the subshells of the +current shell. When used as specified by this volume of IEEE\ Std\ 1003.1-2001, +the alias definition shall not affect the +parent process of the current shell nor any utility environment invoked +by the shell; see \fIShell Execution Environment\fP . +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIalias-name\fP +Write the alias definition to standard output. +.TP 7 +\fIalias-name\fP=\fIstring\fP +.sp +Assign the value of \fIstring\fP to the alias \fIalias-name\fP. +.sp +.LP +If no operands are given, all alias definitions shall be written to +standard output. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIalias\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The format for displaying aliases (when no operands or only \fIname\fP +operands are specified) shall be: +.sp +.RS +.nf + +\fB"%s=%s\\n",\fP \fIname\fP\fB,\fP \fIvalue\fP +.fi +.RE +.LP +The \fIvalue\fP string shall be written with appropriate quoting so +that it is suitable for reinput to the shell. See the +description of shell quoting in \fIQuoting\fP . +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +One of the \fIname\fP operands specified did not have an alias definition, +or an error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.IP " 1." 4 +Change \fIls\fP to give a columnated, more annotated output: +.sp +.RS +.nf + +\fBalias ls="ls -CF" +\fP +.fi +.RE +.LP +.IP " 2." 4 +Create a simple "redo" command to repeat previous entries in the command +history file: +.sp +.RS +.nf + +\fBalias r='fc -s' +\fP +.fi +.RE +.LP +.IP " 3." 4 +Use 1K units for \fIdu\fP: +.sp +.RS +.nf + +\fBalias du=du\\ -k +\fP +.fi +.RE +.LP +.IP " 4." 4 +Set up \fInohup\fP so that it can deal with an argument that is itself +an alias name: +.sp +.RS +.nf + +\fBalias nohup="nohup " +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +The \fIalias\fP description is based on historical KornShell implementations. +Known differences exist between that and the C +shell. The KornShell version was adopted to be consistent with all +the other KornShell features in this volume of +IEEE\ Std\ 1003.1-2001, such as command line editing. +.LP +Since \fIalias\fP affects the current shell execution environment, +it is generally provided as a shell regular built-in. +.LP +Historical versions of the KornShell have allowed aliases to be exported +to scripts that are invoked by the same shell. This is +triggered by the \fIalias\fP \fB-x\fP flag; it is allowed by this +volume of IEEE\ Std\ 1003.1-2001 only when an explicit +extension such as \fB-x\fP is used. The standard developers considered +that aliases were of use primarily to interactive users and +that they should normally not affect shell scripts called by those +users; functions are available to such scripts. +.LP +Historical versions of the KornShell had not written aliases in a +quoted manner suitable for reentry to the shell, but this +volume of IEEE\ Std\ 1003.1-2001 has made this a requirement for all +similar output. Therefore, consistency with this +volume of IEEE\ Std\ 1003.1-2001 was chosen over this detail of historical +practice. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIFunction Definition Command\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/ar.1p b/man1p/ar.1p new file mode 100644 index 000000000..bf9db7100 --- /dev/null +++ b/man1p/ar.1p @@ -0,0 +1,603 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "AR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ar +.SH NAME +ar \- create and maintain library archives +.SH SYNOPSIS +.LP +\fBar -d\fP\fB[\fP\fB-v\fP\fB]\fP \fIarchive file\fP \fB... \fP +\fB +.br +.sp +\fP +.LP +\fBar -m\fP \fB[\fP\fB-v\fP\fB]\fP \fIarchive file\fP \fB... +.br +.sp +ar -m -a\fP\fB[\fP\fB-v\fP\fB]\fP \fIposname archive file\fP \fB... +.br +.sp +ar -m -b\fP\fB[\fP\fB-v\fP\fB]\fP \fIposname archive file\fP \fB... +.br +.sp +ar -m -i\fP\fB[\fP\fB-v\fP\fB]\fP \fIposname archive file\fP \fB... +\fP +\fB +.br +.sp +ar -p\fP\fB[\fP\fB-v\fP\fB][\fP\fB-s\fP\fB]\fP\fIarchive\fP \fB[\fP\fIfile\fP +\fB\&...\fP\fB]\fP\fB +.br +.sp +\fP +.LP +\fBar -q\fP\fB[\fP\fB-cv\fP\fB]\fP \fIarchive file\fP \fB... \fP +\fB +.br +.sp +ar -r\fP\fB[\fP\fB-cuv\fP\fB]\fP \fIarchive file\fP \fB... +.br +.sp +\fP +.LP +\fBar -r -a\fP\fB[\fP\fB-cuv\fP\fB]\fP \fIposname archive file\fP +\fB\&... +.br +.sp +ar -r -b\fP\fB[\fP\fB-cuv\fP\fB]\fP \fIposname archive file\fP \fB... +.br +.sp +ar -r -i\fP\fB[\fP\fB-cuv\fP\fB]\fP \fIposname archive file\fP \fB... +\fP +\fB +.br +.sp +ar -t\fP\fB[\fP\fB-v\fP\fB][\fP\fB-s\fP\fB]\fP\fIarchive\fP \fB[\fP\fIfile\fP +\fB\&...\fP\fB]\fP\fB +.br +.sp +ar -x\fP\fB[\fP\fB-v\fP\fB][\fP\fB-sCT\fP\fB]\fP\fIarchive\fP \fB[\fP\fIfile\fP +\fB\&...\fP\fB]\fP\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIar\fP utility is part of the Software Development Utilities +option. +.LP +The \fIar\fP utility can be used to create and maintain groups of +files combined into an archive. Once an archive has been +created, new files can be added, and existing files in an archive +can be extracted, deleted, or replaced. When an archive consists +entirely of valid object files, the implementation shall format the +archive so that it is usable as a library for link editing (see +\fIc99\fP and \fIfort77\fP). When some of the archived +files are not valid object files, the suitability of the archive for +library use is undefined. \ If an +archive consists entirely of printable files, the entire archive shall +be printable. +.LP +When \fIar\fP creates an archive, it creates administrative information +indicating whether a symbol table is present in the +archive. When there is at least one object file that \fIar\fP recognizes +as such in the archive, an archive symbol table shall be +created in the archive and maintained by \fIar\fP; it is used by the +link editor to search the archive. Whenever the \fIar\fP +utility is used to create or update the contents of such an archive, +the symbol table shall be rebuilt. The \fB-s\fP option shall +force the symbol table to be rebuilt. +.LP +All \fIfile\fP operands can be pathnames. However, files within archives +shall be named by a filename, which is the last +component of the pathname used when the file was entered into the +archive. The comparison of \fIfile\fP operands to the names of +files in archives shall be performed by comparing the last component +of the operand to the name of the file in the archive. +.LP +It is unspecified whether multiple files in the archive may be identically +named. In the case of such files, however, each +\fIfile\fP \ and \fIposname\fP operand shall match only the +first file in the archive having a name that is the same as the last +component of the operand. +.SH OPTIONS +.LP +The \fIar\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-a\fP +Position new files in the archive after the file named by the \fIposname\fP +operand. +.TP 7 +\fB-b\fP +Position new files in the archive before the file named by the \fIposname\fP +operand. +.TP 7 +\fB-c\fP +Suppress the diagnostic message that is written to standard error +by default when the archive \fIarchive\fP is created. +.TP 7 +\fB-C\fP +Prevent extracted files from replacing like-named files in the file +system. This option is useful when \fB-T\fP is also used, to +prevent truncated filenames from replacing files with the same prefix. +.TP 7 +\fB-d\fP +Delete one or more \fIfile\fPs from \fIarchive\fP. +.TP 7 +\fB-i\fP +Position new files in the archive before the file in the archive named +by the \fIposname\fP operand (equivalent to \fB-b\fP). +.TP 7 +\fB-m\fP +Move the named files in the archive. The \fB-a\fP, \fB-b\fP, or \fB-i\fP +options with the \fIposname\fP operand indicate the +position; otherwise, move the names files in the archive to the end +of the archive. +.TP 7 +\fB-p\fP +Write the contents of the \fIfile\fPs in the archive named by \fIfile\fP +operands from \fIarchive\fP to the standard output. +If no \fIfile\fP operands are specified, the contents of all files +in the archive shall be written in the order of the +archive. +.TP 7 +\fB-q\fP +Append the named files to the end of the archive. In this case \fIar\fP +does not check whether the added files are already in the +archive. This is useful to bypass the searching otherwise done when +creating a large archive piece by piece. +.TP 7 +\fB-r\fP +Replace or add \fIfile\fPs to \fIarchive\fP. If the archive named +by \fIarchive\fP does not exist, a new archive shall be +created and a diagnostic message shall be written to standard error +(unless the \fB-c\fP option is specified). If no \fIfile\fPs +are specified and the \fIarchive\fP exists, the results are undefined. +Files that replace existing files in the archive shall not +change the order of the archive. Files that do not replace existing +files in the archive shall be appended to the archive \ unless +a \fB-a\fP, \fB-b\fP, or \fB-i\fP option specifies another position. +.TP 7 +\fB-s\fP +Force the regeneration of the archive symbol table even if \fIar\fP +is not invoked with an option that modifies the archive +contents. This option is useful to restore the archive symbol table +after it has been stripped; see \fIstrip\fP. +.TP 7 +\fB-t\fP +Write a table of contents of \fIarchive\fP to the standard output. +The files specified by the \fIfile\fP operands shall be +included in the written list. If no \fIfile\fP operands are specified, +all files in \fIarchive\fP shall be included in the order +of the archive. +.TP 7 +\fB-T\fP +Allow filename truncation of extracted files whose archive names are +longer than the file system can support. By default, +extracting a file with a name that is too long shall be an error; +a diagnostic message shall be written and the file shall not be +extracted. +.TP 7 +\fB-u\fP +Update older files in the archive. When used with the \fB-r\fP option, +files in the archive shall be replaced only if the +corresponding \fIfile\fP has a modification time that is at least +as new as the modification time of the file in the archive. +.TP 7 +\fB-v\fP +Give verbose output. When used with the option characters \fB-d\fP, +\fB-r\fP, or \fB-x\fP, write a detailed file-by-file +description of the archive creation and maintenance activity, as described +in the STDOUT section. +.LP +When used with \fB-p\fP, write the name of the file in the archive +to the standard output before writing the file in the +archive itself to the standard output, as described in the STDOUT +section. +.LP +When used with \fB-t\fP, include a long listing of information about +the files in the archive, as described in the STDOUT +section. +.TP 7 +\fB-x\fP +Extract the files in the archive named by the \fIfile\fP operands +from \fIarchive\fP. The contents of the archive shall not +be changed. If no \fIfile\fP operands are given, all files in the +archive shall be extracted. The modification time of each file +extracted shall be set to the time the file is extracted from the +archive. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIarchive\fP +A pathname of the archive. +.TP 7 +\fIfile\fP +A pathname. Only the last component shall be used when comparing against +the names of files in the archive. If two or more +\fIfile\fP operands have the same last pathname component (basename), +the results are unspecified. The implementation's archive +format shall not truncate valid filenames of files added to or replaced +in the archive. +.TP 7 +\fIposname\fP +The name of a file in the archive, used for relative positioning; +see options \fB-m\fP and \fB-r\fP. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +The archive named by \fIarchive\fP shall be a file in the format created +by \fIar\fP \fB-r\fP. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIar\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILC_TIME\fP +Determine the format and content for date and time strings written +by \fIar\fP \fB-tv\fP. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITMPDIR\fP +Determine the pathname that overrides the default directory for temporary +files, if any. +.TP 7 +\fITZ\fP +Determine the timezone used to calculate date and time strings written +by \fIar\fP \fB-tv\fP. If \fITZ\fP is unset or null, +an unspecified default timezone shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If the \fB-d\fP option is used with the \fB-v\fP option, the standard +output format shall be: +.sp +.RS +.nf + +\fB"d - %s\\n", <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +where \fIfile\fP is the operand specified on the command line. +.LP +If the \fB-p\fP option is used with the \fB-v\fP option, \fIar\fP +shall precede the contents of each file with: +.sp +.RS +.nf + +\fB"\\n<%s>\\n\\n", <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +where \fIfile\fP is the operand specified on the command line, if +\fIfile\fP operands were specified, and the name of the file +in the archive if they were not. +.LP +If the \fB-r\fP option is used with the \fB-v\fP option: +.IP " *" 3 +If \fIfile\fP is already in the archive, the standard output format +shall be: +.sp +.RS +.nf + +\fB"r - %s\\n", <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +where <\fIfile\fP> is the operand specified on the command line. +.LP +.IP " *" 3 +If \fIfile\fP is not already in the archive, the standard output format +shall be: +.sp +.RS +.nf + +\fB"a - %s\\n", <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +where <\fIfile\fP> is the operand specified on the command line. +.LP +.LP +If the \fB-t\fP option is used, \fIar\fP shall write the names of +the files in the archive to the standard output in the +format: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +where \fIfile\fP is the operand specified on the command line, if +\fIfile\fP operands were specified, or the name of the file +in the archive if they were not. +.LP +If the \fB-t\fP option is used with the \fB-v\fP option, the standard +output format shall be: +.sp +.RS +.nf + +\fB"%s %u/%u %u %s %d %d:%d %d %s\\n", <\fP\fImember mode\fP\fB>, <\fP\fIuser ID\fP\fB>, + <\fP\fIgroup ID\fP\fB>, <\fP\fInumber of bytes in member\fP\fB>, + <\fP\fIabbreviated month\fP\fB>, <\fP\fIday-of-month\fP\fB>, <\fP\fIhour\fP\fB>, + <\fP\fIminute\fP\fB>, <\fP\fIyear\fP\fB>, <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +where: +.TP 7 +<\fIfile\fP> +Shall be the operand specified on the command line, if \fIfile\fP +operands were specified, or the name of the file in the +archive if they were not. +.TP 7 +<\fImember\ mode\fP> +.sp +Shall be formatted the same as the <\fIfile\ mode\fP> string defined +in the STDOUT section of \fIls\fP, except that the first character, +the <\fIentry\ type\fP>, is not used; the string +represents the file mode of the file in the archive at the time it +was added to or replaced in the archive. +.sp +.LP +The following represent the last-modification time of a file when +it was most recently added to or replaced in the archive: +.TP 7 +<\fIabbreviated\ month\fP> +.sp +Equivalent to the format of the \fB%b\fP conversion specification +format in \fIdate\fP. +.TP 7 +<\fIday-of-month\fP> +.sp +Equivalent to the format of the \fB%e\fP conversion specification +format in \fIdate\fP. +.TP 7 +<\fIhour\fP> +Equivalent to the format of the \fB%H\fP conversion specification +format in \fIdate\fP. +.TP 7 +<\fIminute\fP> +Equivalent to the format of the \fB%M\fP conversion specification +format in \fIdate\fP. +.TP 7 +<\fIyear\fP> +Equivalent to the format of the \fB%Y\fP conversion specification +format in \fIdate\fP. +.sp +.LP +When \fILC_TIME\fP does not specify the POSIX locale, a different +format and order of presentation of these fields relative to +each other may be used in a format appropriate in the specified locale. +.LP +If the \fB-x\fP option is used with the \fB-v\fP option, the standard +output format shall be: +.sp +.RS +.nf + +\fB"x - %s\\n", <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +where \fIfile\fP is the operand specified on the command line, if +\fIfile\fP operands were specified, or the name of the file +in the archive if they were not. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. The +diagnostic message about creating a new archive when +\fB-c\fP is not specified shall not modify the exit status. +.SH OUTPUT FILES +.LP +Archives are files with unspecified formats. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The archive format is not described. It is recognized that there are +several known \fIar\fP formats, which are not compatible. +The \fIar\fP utility is included, however, to allow creation of archives +that are intended for use only on one machine. The +archive is specified as a file, and it can be moved as a file. This +does allow an archive to be moved from one machine to another +machine that uses the same implementation of \fIar\fP. +.LP +Utilities such as \fIpax\fP (and its forebears \fItar\fP and \fIcpio\fP) +also provide +portable "archives". This is a not a duplication; the \fIar\fP utility +is included to provide an interface primarily for \fImake\fP and the +compilers, based on a historical model. +.LP +In historical implementations, the \fB-q\fP option (available on XSI-conforming +systems) is known to execute quickly because +\fIar\fP does not check on whether the added members are already in +the archive. This is useful to bypass the searching otherwise +done when creating a large archive piece-by-piece. These remarks may +but need not remain true for a brand new implementation of +this utility; hence, these remarks have been moved into the RATIONALE. +.LP +BSD implementations historically required applications to provide +the \fB-s\fP option whenever the archive was supposed to +contain a symbol table. As in this volume of IEEE\ Std\ 1003.1-2001, +System V historically creates or updates an archive +symbol table whenever an object file is removed from, added to, or +updated in the archive. +.LP +The OPERANDS section requires what might seem to be true without specifying +it: the archive cannot truncate the filenames below +{NAME_MAX}. Some historical implementations do so, however, causing +unexpected results for the application. Therefore, this volume +of IEEE\ Std\ 1003.1-2001 makes the requirement explicit to avoid +misunderstandings. +.LP +According to the System V documentation, the options \fB-dmpqrtx\fP +are not required to begin with a hyphen ( \fB'-'\fP ). +This volume of IEEE\ Std\ 1003.1-2001 requires that a conforming application +use the leading hyphen. +.LP +The archive format used by the 4.4 BSD implementation is documented +in this RATIONALE as an example: +A file created by \fIar\fP begins with the "magic" string \fB"!\\n"\fP +\&. The rest of the archive is +made up of objects, each of which is composed of a header for a file, +a possible filename, and the file contents. The header is +portable between machine architectures, and, if the file contents +are printable, the archive is itself printable. +.LP +The header is made up of six ASCII fields, followed by a two-character +trailer. The fields are the object name (16 characters), +the file last modification time (12 characters), the user and group +IDs (each 6 characters), the file mode (8 characters), and the +file size (10 characters). All numeric fields are in decimal, except +for the file mode, which is in octal. +.LP +The modification time is the file \fIst_mtime\fP field. The user and +group IDs are the file \fIst_uid\fP and \fIst_gid\fP +fields. The file mode is the file \fIst_mode\fP field. The file size +is the file \fIst_size\fP field. The two-byte trailer is the +string \fB"`"\fP . +.LP +Only the name field has any provision for overflow. If any filename +is more than 16 characters in length or contains an embedded +space, the string \fB"#1/"\fP followed by the ASCII length of the +name is written in the name field. The file size (stored in +the archive header) is incremented by the length of the name. The +name is then written immediately following the archive +header. +.LP +Any unused characters in any of these fields are written as s. +If any fields are their particular maximum number of +characters in length, there is no separation between the fields. +.LP +Objects in the archive are always an even number of bytes long; files +that are an odd number of bytes long are padded with a +, although the size in the header does not reflect this. +.LP +The \fIar\fP utility description requires that (when all its members +are valid object files) \fIar\fP produce an object code +library, which the linkage editor can use to extract object modules. +If the linkage editor needs a symbol table to permit random +access to the archive, \fIar\fP must provide it; however, \fIar\fP +does not require a symbol table. +.LP +The BSD \fB-o\fP option was omitted. It is a rare conforming application +that uses \fIar\fP to extract object code from a +library with concern for its modification time, since this can only +be of importance to \fImake\fP. Hence, since this functionality is +not deemed important for applications portability, the +modification time of the extracted files is set to the current time. +.LP +There is at least one known implementation (for a small computer) +that can accommodate only object files for that system, +disallowing mixed object and other files. The ability to handle any +type of file is not only historical practice for most +implementations, but is also a reasonable expectation. +.LP +Consideration was given to changing the output format of \fIar\fP +\fB-tv\fP to the same format as the output of \fIls\fP \fB-l\fP. This +would have made parsing the output of \fIar\fP the same as that of +\fIls\fP. This was rejected in part because the current \fIar\fP format +is commonly used and changes +would break historical usage. Second, \fIar\fP gives the user ID and +group ID in numeric format separated by a slash. Changing +this to be the user name and group name would not be correct if the +archive were moved to a machine that contained a different user +database. Since \fIar\fP cannot know whether the archive was generated +on the same machine, it cannot tell what to report. +.LP +The text on the \fB-ur\fP option combination is historical practice-since +one filename can easily represent two different files +(for example, \fB/a/foo\fP and \fB/b/foo\fP), it is reasonable to +replace the file in the archive even when the modification time +in the archive is identical to that in the file system. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIc99\fP , \fIdate\fP , \fIfort77\fP , \fIpax\fP , \fIstrip\fP the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 13, Headers, +\fI\fP +description of {POSIX_NO_TRUNC} +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/asa.1p b/man1p/asa.1p new file mode 100644 index 000000000..73537f04d --- /dev/null +++ b/man1p/asa.1p @@ -0,0 +1,187 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ASA" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" asa +.SH NAME +asa \- interpret carriage-control characters +.SH SYNOPSIS +.LP +\fBasa\fP \fB[\fP \fIfile\fP \fB...\fP \fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIasa\fP utility shall write its input files to standard output, +mapping carriage-control characters from the text files +to line-printer control sequences in an implementation-defined manner. +.LP +The first character of every line shall be removed from the input, +and the following actions are performed. +.LP +If the character removed is: +.TP 7 + +The rest of the line is output without change. +.TP 7 +0 +A is output, then the rest of the input line. +.TP 7 +1 +One or more implementation-defined characters that causes an advance +to the next page shall be output, followed by the rest of +the input line. +.TP 7 +\fB+\fP +The of the previous line shall be replaced with one or more +implementation-defined characters that causes +printing to return to column position 1, followed by the rest of the +input line. If the \fB'+'\fP is the first character in the +input, it shall be equivalent to . +.sp +.LP +The action of the \fIasa\fP utility is unspecified upon encountering +any character other than those listed above as the first +character in a line. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.TP 7 +\fIfile\fP +A pathname of a text file used for input. If no \fIfile\fP operands +are specified, the standard input shall be used. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified; see the INPUT FILES section. +.SH INPUT FILES +.LP +The input files shall be text files. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIasa\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall be the text from the input file modified +as described in the DESCRIPTION section. +.SH STDERR +.LP +None. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All input files were output successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.IP " 1." 4 +The following command: +.sp +.RS +.nf + +\fBasa\fP \fIfile\fP +.fi +.RE +.LP +permits the viewing of \fIfile\fP (created by a program using FORTRAN-style +carriage-control characters) on a terminal. +.LP +.IP " 2." 4 +The following command: +.sp +.RS +.nf + +\fBa.out | asa | lp +\fP +.fi +.RE +.LP +formats the FORTRAN output of \fBa.out\fP and directs it to the printer. +.LP +.SH RATIONALE +.LP +The \fIasa\fP utility is needed to map "standard" FORTRAN 77 output +into a form acceptable to contemporary printers. Usually, +\fIasa\fP is used to pipe data to the \fIlp\fP utility; see \fIlp\fP. +.LP +This utility is generally used only by FORTRAN programs. The standard +developers decided to retain \fIasa\fP to avoid breaking +the historical large base of FORTRAN applications that put carriage-control +characters in their output files. There is no +requirement that a system have a FORTRAN compiler in order to run +applications that need \fIasa\fP. +.LP +Historical implementations have used an ASCII in response +to a 1 and an ASCII in +response to a \fB'+'\fP . It is suggested that implementations treat +characters other than 0, 1, and \fB'+'\fP as + in the absence of any compelling reason to do otherwise. However, +the action is listed here as "unspecified", +permitting an implementation to provide extensions to access fast +multiple-line slewing and channel seeking in a non-portable +manner. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfort77\fP , \fIlp\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/at.1p b/man1p/at.1p new file mode 100644 index 000000000..db3af841f --- /dev/null +++ b/man1p/at.1p @@ -0,0 +1,706 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "AT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" at +.SH NAME +at \- execute commands at a later time +.SH SYNOPSIS +.LP +\fBat\fP \fB[\fP\fB-m\fP\fB][\fP\fB-f\fP \fIfile\fP\fB][\fP\fB-q\fP +\fIqueuename\fP\fB]\fP \fB-t\fP \fItime_arg\fP\fB +.br +.sp +at\fP \fB[\fP\fB-m\fP\fB][\fP\fB-f\fP \fIfile\fP\fB][\fP\fB-q\fP \fIqueuename\fP\fB]\fP +\fItimespec\fP +\fB\&... +.br +.sp +at -r\fP \fIat_job_id\fP \fB... +.br +.sp +at -l -q\fP \fIqueuename\fP\fB +.br +.sp +at -l\fP \fB[\fP\fIat_job_id\fP \fB...\fP\fB]\fP\fB\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIat\fP utility shall read commands from standard input and group +them together as an \fIat-job\fP, to be executed at a +later time. +.LP +The at-job shall be executed in a separate invocation of the shell, +running in a separate process group with no controlling +terminal, except that the environment variables, current working directory, +file creation mask, and other implementation-defined +execution-time attributes in effect when the \fIat\fP utility is executed +shall be retained and used when the at-job is +executed. +.LP +When the at-job is submitted, the \fIat_job_id\fP and scheduled time +shall be written to standard error. The \fIat_job_id\fP +is an identifier that shall be a string consisting solely of alphanumeric +characters and the period character. The \fIat_job_id\fP +shall be assigned by the system when the job is scheduled such that +it uniquely identifies a particular job. +.LP +User notification and the processing of the job's standard output +and standard error are described under the \fB-m\fP +option. +.LP +Users shall be permitted to use \fIat\fP if their name appears in +the file \fB/usr/lib/cron/at.allow\fP. If that file does not +exist, the file \fB/usr/lib/cron/at.deny\fP shall be checked to determine +whether the user shall be denied access to \fIat\fP. If +neither file exists, only a process with the appropriate privileges +shall be allowed to submit a job. If only \fBat.deny\fP exists +and is empty, global usage shall be permitted. The \fBat.allow\fP +and \fBat.deny\fP files shall consist of one user name per +line. +.SH OPTIONS +.LP +The \fIat\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-f\ \fP \fIfile\fP +Specify the pathname of a file to be used as the source of the at-job, +instead of standard input. +.TP 7 +\fB-l\fP +(The letter ell.) Report all jobs scheduled for the invoking user +if no \fIat_job_id\fP operands are specified. If +\fIat_job_id\fPs are specified, report only information for these +jobs. The output shall be written to standard output. +.TP 7 +\fB-m\fP +Send mail to the invoking user after the at-job has run, announcing +its completion. Standard output and standard error produced +by the at-job shall be mailed to the user as well, unless redirected +elsewhere. Mail shall be sent even if the job produces no +output. +.LP +If \fB-m\fP is not used, the job's standard output and standard error +shall be provided to the user by means of mail, unless +they are redirected elsewhere; if there is no such output to provide, +the implementation need not notify the user of the job's +completion. +.TP 7 +\fB-q\ \fP \fIqueuename\fP +.sp +Specify in which queue to schedule a job for submission. When used +with the \fB-l\fP option, limit the search to that particular +queue. By default, at-jobs shall be scheduled in queue \fIa\fP. In +contrast, queue \fIb\fP shall be reserved for batch jobs; see +\fIbatch\fP. The meanings of all other \fIqueuename\fPs are implementation-defined. +If +\fB-q\fP is specified along with either of the \fB-t\fP \fItime_arg\fP +or \fItimespec\fP arguments, the results are +unspecified. +.TP 7 +\fB-r\fP +Remove the jobs with the specified \fIat_job_id\fP operands that were +previously scheduled by the \fIat\fP utility. +.TP 7 +\fB-t\ \fP \fItime_arg\fP +Submit the job to be run at the time specified by the \fItime\fP option-argument, +which the application shall ensure has the +format as specified by the \fItouch\fP \fB-t\fP \fItime\fP utility. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIat_job_id\fP +The name reported by a previous invocation of the \fIat\fP utility +at the time the job was scheduled. +.TP 7 +\fItimespec\fP +Submit the job to be run at the date and time specified. All of the +\fItimespec\fP operands are interpreted as if they were +separated by s and concatenated, and shall be parsed as described +in the grammar at the end of this section. The date +and time shall be interpreted as being in the timezone of the user +(as determined by the \fITZ\fP variable), unless a timezone +name appears as part of \fItime\fP, below. +.LP +In the POSIX locale, the following describes the three parts of the +time specification string. All of the values from the +\fILC_TIME\fP categories in the POSIX locale shall be recognized in +a case-insensitive manner. +.TP 7 +\fItime\fP +.RS +The time can be specified as one, two, or four digits. One-digit and +two-digit numbers shall be taken to be hours; four-digit +numbers to be hours and minutes. The time can alternatively be specified +as two numbers separated by a colon, meaning +\fIhour\fP:\fIminute\fP. An AM/PM indication (one of the values from +the \fBam_pm\fP keywords in the \fILC_TIME\fP locale +category) can follow the time; otherwise, a 24-hour clock time shall +be understood. A timezone name can also follow to further +qualify the time. The acceptable timezone names are implementation-defined, +except that they shall be case-insensitive and the +string \fButc\fP is supported to indicate the time is in Coordinated +Universal Time. In the POSIX locale, the \fItime\fP field +can also be one of the following tokens: +.TP 7 +\fBmidnight\fP +.RS +Indicates the time 12:00 am (00:00). +.RE +.TP 7 +\fBnoon\fP +.RS +Indicates the time 12:00 pm. +.RE +.TP 7 +\fBnow\fP +.RS +Indicates the current day and time. Invoking \fIat\fP <\fBnow\fP> +shall submit an at-job for potentially immediate +execution (that is, subject only to unspecified scheduling delays). +.RE +.sp +.RE +.TP 7 +\fIdate\fP +.RS +An optional \fIdate\fP can be specified as either a month name (one +of the values from the \fBmon\fP or \fBabmon\fP keywords +in the \fILC_TIME\fP locale category) followed by a day number (and +possibly year number preceded by a comma), or a day of the +week (one of the values from the \fBday\fP or \fBabday\fP keywords +in the \fILC_TIME\fP locale category). In the POSIX locale, +two special days shall be recognized: +.TP 7 +\fBtoday\fP +.RS +Indicates the current day. +.RE +.TP 7 +\fBtomorrow\fP +.RS +Indicates the day following the current day. +.RE +.sp +.LP +If no \fIdate\fP is given, \fBtoday\fP shall be assumed if the given +time is greater than the current time, and +\fBtomorrow\fP shall be assumed if it is less. If the given month +is less than the current month (and no year is given), next year +shall be assumed. +.RE +.TP 7 +\fIincrement\fP +.RS +The optional \fIincrement\fP shall be a number preceded by a plus +sign ( \fB'+'\fP ) and suffixed by one of the following: +\fBminutes\fP, \fBhours\fP, \fBdays\fP, \fBweeks\fP, \fBmonths\fP, +or \fByears\fP. (The singular forms shall also be +accepted.) The keyword \fBnext\fP shall be equivalent to an increment +number of +1. For example, the following are equivalent +commands: +.sp +.RS +.nf + +\fBat 2pm + 1 week +at 2pm next week +\fP +.fi +.RE +.RE +.sp +.sp +.LP +The following grammar describes the precise format of \fItimespec\fP +in the POSIX locale. The general conventions for this +style of grammar are described in \fIGrammar Conventions\fP . This +formal syntax shall +take precedence over the preceding text syntax description. The longest +possible token or delimiter shall be recognized at a given +point. When used in a \fItimespec\fP, white space shall also delimit +tokens. +.sp +.RS +.nf + +\fB%token hr24clock_hr_min +%token hr24clock_hour +/* + An hr24clock_hr_min is a one, two, or four-digit number. A one-digit + or two-digit number constitutes an hr24clock_hour. An hr24clock_hour + may be any of the single digits [0,9], or may be double digits, ranging + from [00,23]. If an hr24clock_hr_min is a four-digit number, the + first two digits shall be a valid hr24clock_hour, while the last two + represent the number of minutes, from [00,59]. +*/ +.sp + +%token wallclock_hr_min +%token wallclock_hour +/* + A wallclock_hr_min is a one, two-digit, or four-digit number. + A one-digit or two-digit number constitutes a wallclock_hour. + A wallclock_hour may be any of the single digits [1,9], or may + be double digits, ranging from [01,12]. If a wallclock_hr_min + is a four-digit number, the first two digits shall be a valid + wallclock_hour, while the last two represent the number of + minutes, from [00,59]. +*/ +.sp + +%token minute +/* + A minute is a one or two-digit number whose value can be [0,9] + or [00,59]. +*/ +.sp + +%token day_number +/* + A day_number is a number in the range appropriate for the particular + month and year specified by month_name and year_number, respectively. + If no year_number is given, the current year is assumed if the given + date and time are later this year. If no year_number is given and + the date and time have already occurred this year and the month is + not the current month, next year is the assumed year. +*/ +.sp + +%token year_number +/* + A year_number is a four-digit number representing the year A.D., in + which the at_job is to be run. +*/ +.sp + +%token inc_number +/* + The inc_number is the number of times the succeeding increment + period is to be added to the specified date and time. +*/ +.sp + +%token timezone_name +/* + The name of an optional timezone suffix to the time field, in an + implementation-defined format. +*/ +.sp + +%token month_name +/* + One of the values from the mon or abmon keywords in the LC_TIME + locale category. +*/ +.sp + +%token day_of_week +/* + One of the values from the day or abday keywords in the LC_TIME + locale category. +*/ +.sp + +%token am_pm +/* + One of the values from the am_pm keyword in the LC_TIME locale + category. +*/ +.sp + +%start timespec +%% +timespec : time + | time date + | time increment + | time date increment + | nowspec + ; +.sp + +nowspec : "now" + | "now" increment + ; +.sp + +time : hr24clock_hr_min + | hr24clock_hr_min timezone_name + | hr24clock_hour ":" minute + | hr24clock_hour ":" minute timezone_name + | wallclock_hr_min am_pm + | wallclock_hr_min am_pm timezone_name + | wallclock_hour ":" minute am_pm + | wallclock_hour ":" minute am_pm timezone_name + | "noon" + | "midnight" + ; +.sp + +date : month_name day_number + | month_name day_number "," year_number + | day_of_week + | "today" + | "tomorrow" + ; +.sp + +increment : "+" inc_number inc_period + | "next" inc_period + ; +.sp + +inc_period : "minute" | "minutes" + | "hour" | "hours" + | "day" | "days" + | "week" | "weeks" + | "month" | "months" + | "year" | "years" + ; +\fP +.fi +.RE +.SH STDIN +.LP +The standard input shall be a text file consisting of commands acceptable +to the shell command language described in \fIShell Command Language\fP +\&. The standard input shall only be used if no \fB-f\fP \fIfile\fP +option is specified. +.SH INPUT FILES +.LP +See the STDIN section. +.LP +The text files \fB/usr/lib/cron/at.allow\fP and \fB/usr/lib/cron/at.deny\fP +shall contain zero or more user names, one per line, +of users who are, respectively, authorized or denied access to the +\fIat\fP and \fIbatch\fP +utilities. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIat\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fILC_TIME\fP +Determine the format and contents for date and time strings written +and accepted by \fIat\fP. +.TP 7 +\fISHELL\fP +Determine a name of a command interpreter to be used to invoke the +at-job. If the variable is unset or null, \fIsh\fP shall be used. +If it is set to a value other than a name for \fIsh\fP, the implementation +shall do one of the following: use that shell; use \fIsh\fP; use the +login shell from the user database; or any of the preceding accompanied +by a warning +diagnostic about which was chosen. +.TP 7 +\fITZ\fP +Determine the timezone. The job shall be submitted for execution at +the time specified by \fItimespec\fP or \fB-t\fP +\fItime\fP relative to the timezone specified by the \fITZ\fP variable. +If \fItimespec\fP specifies a timezone, it shall +override \fITZ .\fP If \fItimespec\fP does not specify a timezone +and \fITZ\fP is unset or null, an unspecified default timezone +shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +When standard input is a terminal, prompts of unspecified format for +each line of the user input described in the STDIN section +may be written to standard output. +.LP +In the POSIX locale, the following shall be written to the standard +output for each job when jobs are listed in response to the +\fB-l\fP option: +.sp +.RS +.nf + +\fB"%s\\t%s\\n",\fP \fIat_job_id\fP\fB, <\fP\fIdate\fP\fB> +\fP +.fi +.RE +.LP +where \fIdate\fP shall be equivalent in format to the output of: +.sp +.RS +.nf + +\fBdate +"%a %b %e %T %Y" +\fP +.fi +.RE +.LP +The date and time written shall be adjusted so that they appear in +the timezone of the user (as determined by the \fITZ\fP +variable). +.SH STDERR +.LP +In the POSIX locale, the following shall be written to standard error +when a job has been successfully submitted: +.sp +.RS +.nf + +\fB"job %s at %s\\n",\fP \fIat_job_id\fP\fB, <\fP\fIdate\fP\fB> +\fP +.fi +.RE +.LP +where \fIdate\fP has the same format as that described in the STDOUT +section. Neither this, nor warning messages concerning the +selection of the command interpreter, shall be considered a diagnostic +that changes the exit status. +.LP +Diagnostic messages, if any, shall be written to standard error. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The \fIat\fP utility successfully submitted, removed, or listed a +job or jobs. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +The job shall not be scheduled, removed, or listed. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The format of the \fIat\fP command line shown here is guaranteed only +for the POSIX locale. Other cultures may be supported +with substantially different interfaces, although implementations +are encouraged to provide comparable levels of functionality. +.LP +Since the commands run in a separate shell invocation, running in +a separate process group with no controlling terminal, open +file descriptors, traps, and priority inherited from the invoking +environment are lost. +.LP +Some implementations do not allow substitution of different shells +using \fISHELL .\fP System V systems, for example, have used +the login shell value for the user in \fB/etc/passwd\fP. To select +reliably another command interpreter, the user must include it +as part of the script, such as: +.sp +.RS +.nf + +\fB$\fP \fBat 1800 +myshell myscript +EOT +\fP\fBjob ... at ... +$\fP +.fi +.RE +.SH EXAMPLES +.IP " 1." 4 +This sequence can be used at a terminal: +.sp +.RS +.nf + +\fBat -m 0730 tomorrow +sort < file >outfile +EOT +\fP +.fi +.RE +.LP +.IP " 2." 4 +This sequence, which demonstrates redirecting standard error to a +pipe, is useful in a command procedure (the sequence of output +redirection specifications is significant): +.sp +.RS +.nf + +\fBat now + 1 hour <&1 >outfile | mailx mygroup +! +\fP +.fi +.RE +.LP +.IP " 3." 4 +To have a job reschedule itself, \fIat\fP can be invoked from within +the at-job. For example, this daily processing script +named \fBmy.daily\fP runs every day (although \fIcrontab\fP is a more +appropriate vehicle +for such work): +.sp +.RS +.nf + +\fB# my.daily runs every day +\fP\fIdaily processing\fP\fBat now tomorrow < my.daily +\fP +.fi +.RE +.LP +.IP " 4." 4 +The spacing of the three portions of the POSIX locale \fItimespec\fP +is quite flexible as long as there are no ambiguities. +Examples of various times and operand presentation include: +.sp +.RS +.nf + +\fBat 0815am Jan 24 +at 8 :15amjan24 +at now "+ 1day" +at 5 pm FRIday +at '17 + utc+ + 30minutes' +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +The \fIat\fP utility reads from standard input the commands to be +executed at a later time. It may be useful to redirect +standard output and standard error within the specified commands. +.LP +The \fB-t\fP \fItime\fP option was added as a new capability to support +an internationalized way of specifying a time for +execution of the submitted job. +.LP +Early proposals added a "jobname" concept as a way of giving submitted +jobs names that are meaningful to the user submitting +them. The historical, system-specified \fIat_job_id\fP gives no indication +of what the job is. Upon further reflection, it was +decided that the benefit of this was not worth the change in historical +interface. The \fIat\fP functionality is useful in simple +environments, but in large or complex situations, the functionality +provided by the Batch Services option is more suitable. +.LP +The \fB-q\fP option historically has been an undocumented option, +used mainly by the \fIbatch\fP utility. +.LP +The System V \fB-m\fP option was added to provide a method for informing +users that an at-job had completed. Otherwise, users +are only informed when output to standard error or standard output +are not redirected. +.LP +The behavior of \fIat\fP <\fBnow\fP> was changed in an early proposal +from being unspecified to submitting a job for +potentially immediate execution. Historical BSD \fIat\fP implementations +support this. Historical System V implementations give an +error in that case, but a change to the System V versions should have +no backwards-compatibility ramifications. +.LP +On BSD-based systems, a \fB-u\fP \fIuser\fP option has allowed those +with appropriate privileges to access the work of other +users. Since this is primarily a system administration feature and +is not universally implemented, it has been omitted. Similarly, +a specification for the output format for a user with appropriate +privileges viewing the queues of other users has been +omitted. +.LP +The \fB-f\fP \fIfile\fP option from System V is used instead of the +BSD method of using the last operand as the pathname. The +BSD method is ambiguous-does: +.sp +.RS +.nf + +\fBat 1200 friday +\fP +.fi +.RE +.LP +mean the same thing if there is a file named \fBfriday\fP in the current +directory? +.LP +The \fIat_job_id\fP is composed of a limited character set in historical +practice, and it is mandated here to invalidate +systems that might try using characters that require shell quoting +or that could not be easily parsed by shell scripts. +.LP +The \fIat\fP utility varies between System V and BSD systems in the +way timezones are used. On System V systems, the \fITZ\fP +variable affects the at-job submission times and the times displayed +for the user. On BSD systems, \fITZ\fP is not taken into +account. The BSD behavior is easily achieved with the current specification. +If the user wishes to have the timezone default to +that of the system, they merely need to issue the \fIat\fP command +immediately following an unsetting or null assignment to \fITZ +\&.\fP For example: +.sp +.RS +.nf + +\fBTZ= at noon ... +\fP +.fi +.RE +.LP +gives the desired BSD result. +.LP +While the \fIyacc\fP-like grammar specified in the OPERANDS section +is lexically +unambiguous with respect to the digit strings, a lexical analyzer +would probably be written to look for and return digit strings in +those cases. The parser could then check whether the digit string +returned is a valid \fIday_number\fP, \fIyear_number\fP, and so +on, based on the context. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIbatch\fP , \fIcrontab\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/awk.1p b/man1p/awk.1p new file mode 100644 index 000000000..b05fb641a --- /dev/null +++ b/man1p/awk.1p @@ -0,0 +1,2984 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "AWK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" awk +.SH NAME +awk \- pattern scanning and processing language +.SH SYNOPSIS +.LP +\fBawk\fP \fB[\fP\fB-F\fP \fIERE\fP\fB][\fP\fB-v\fP \fIassignment\fP\fB]\fP +\fB\&...\fP \fIprogram\fP +\fB[\fP\fIargument\fP \fB...\fP\fB]\fP\fB +.br +.sp +awk\fP \fB[\fP\fB-F\fP \fIERE\fP\fB]\fP \fB-f\fP \fIprogfile\fP \fB...\fP +\fB[\fP\fB-v\fP +\fIassignment\fP\fB]\fP \fB...\fP\fB[\fP\fIargument\fP \fB...\fP\fB]\fP\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIawk\fP utility shall execute programs written in the \fIawk\fP +programming language, which is specialized for textual +data manipulation. An \fIawk\fP program is a sequence of patterns +and corresponding actions. When input is read that matches a +pattern, the action associated with that pattern is carried out. +.LP +Input shall be interpreted as a sequence of records. By default, a +record is a line, less its terminating , but +this can be changed by using the \fBRS\fP built-in variable. Each +record of input shall be matched in turn against each pattern in +the program. For each pattern matched, the associated action shall +be executed. +.LP +The \fIawk\fP utility shall interpret each input record as a sequence +of fields where, by default, a field is a string of non- +s. This default white-space field delimiter can be changed +by using the \fBFS\fP built-in variable or \fB-F\fP +\fIERE\fP. The \fIawk\fP utility shall denote the first field in a +record $1, the second $2, and so on. The symbol $0 shall refer +to the entire record; setting any other field causes the re-evaluation +of $0. Assigning to $0 shall reset the values of all other +fields and the \fBNF\fP built-in variable. +.SH OPTIONS +.LP +The \fIawk\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-F\ \fP \fIERE\fP +Define the input field separator to be the extended regular expression +\fIERE\fP, before any input is read; see Regular Expressions . +.TP 7 +\fB-f\ \fP \fIprogfile\fP +Specify the pathname of the file \fIprogfile\fP containing an \fIawk\fP +program. If multiple instances of this option are +specified, the concatenation of the files specified as \fIprogfile\fP +in the order specified shall be the \fIawk\fP program. The +\fIawk\fP program can alternatively be specified in the command line +as a single argument. +.TP 7 +\fB-v\ \fP \fIassignment\fP +The application shall ensure that the \fIassignment\fP argument is +in the same form as an \fIassignment\fP operand. The specified +variable assignment shall occur prior to executing the \fIawk\fP program, +including the actions associated with \fBBEGIN\fP +patterns (if any). Multiple occurrences of this option can be specified. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIprogram\fP +If no \fB-f\fP option is specified, the first operand to \fIawk\fP +shall be the text of the \fIawk\fP program. The +application shall supply the \fIprogram\fP operand as a single argument +to \fIawk\fP. If the text does not end in a +, \fIawk\fP shall interpret the text as if it did. +.TP 7 +\fIargument\fP +Either of the following two types of \fIargument\fP can be intermixed: +.TP 7 +\fIfile\fP +.RS +A pathname of a file that contains the input to be read, which is +matched against the set of patterns in the program. If no +\fIfile\fP operands are specified, or if a \fIfile\fP operand is \fB'-'\fP +, the standard input shall be used. +.RE +.TP 7 +\fIassignment\fP +.RS +An operand that begins with an underscore or alphabetic character +from the portable character set (see the table in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable +Character Set), followed by a sequence of underscores, digits, and +alphabetics from the portable character set, followed by the +\fB'='\fP character, shall specify a variable assignment rather than +a pathname. The characters before the \fB'='\fP +represent the name of an \fIawk\fP variable; if that name is an \fIawk\fP +reserved word (see Grammar ) the behavior is undefined. The characters +following the equal sign shall be interpreted as if they +appeared in the \fIawk\fP program preceded and followed by a double-quote +( \fB' )'\fP character, as a \fBSTRING\fP token (see +Grammar ), except that if the last character is an unescaped backslash, +it shall be interpreted as a +literal backslash rather than as the first character of the sequence +\fB"\\""\fP . The variable shall be assigned the value of +that \fBSTRING\fP token and, if appropriate, shall be considered a +\fInumeric string\fP (see Expressions in awk ), the variable shall +also be assigned its numeric value. Each such variable assignment +shall occur just prior to the processing of the following \fIfile\fP, +if any. Thus, an assignment before the first \fIfile\fP +argument shall be executed after the \fBBEGIN\fP actions (if any), +while an assignment after the last \fIfile\fP argument shall +occur before the \fBEND\fP actions (if any). If there are no \fIfile\fP +arguments, assignments shall be executed before +processing the standard input. +.RE +.sp +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified, or if a \fIfile\fP operand is \fB'-'\fP ; +see the INPUT FILES section. If the \fIawk\fP program contains no +actions and no patterns, but is otherwise a valid \fIawk\fP +program, standard input and any \fIfile\fP operands shall not be read +and \fIawk\fP shall exit with a return status of zero. +.SH INPUT FILES +.LP +Input files to the \fIawk\fP program from any of the following sources +shall be text files: +.IP " *" 3 +Any \fIfile\fP operands or their equivalents, achieved by modifying +the \fIawk\fP variables \fBARGV\fP and \fBARGC\fP +.LP +.IP " *" 3 +Standard input in the absence of any \fIfile\fP operands +.LP +.IP " *" 3 +Arguments to the \fBgetline\fP function +.LP +.LP +Whether the variable \fBRS\fP is set to a value other than a +or not, for these files, implementations shall +support records terminated with the specified separator up to {LINE_MAX} +bytes and may support longer records. +.LP +If \fB-f\fP \fIprogfile\fP is specified, the application shall ensure +that the files named by each of the \fIprogfile\fP +option-arguments are text files and their concatenation, in the same +order as they appear in the arguments, is an \fIawk\fP +program. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIawk\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular +expressions and in comparisons of string values. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), the +behavior of character classes within regular expressions, the +identification of characters as letters, and the mapping of uppercase +and lowercase characters for the \fBtoupper\fP and +\fBtolower\fP functions. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILC_NUMERIC\fP +Determine the radix character used when interpreting numeric input, +performing conversions between numeric and string values, and +formatting numeric output. Regardless of locale, the period character +(the decimal-point character of the POSIX locale) is the +decimal-point character recognized in processing \fIawk\fP programs +(including assignments in command line arguments). +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPATH\fP +Determine the search path when looking for commands executed by \fIsystem\fP(\fIexpr\fP), +or input and output pipes; see the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment +Variables. +.sp +.LP +In addition, all environment variables shall be visible via the \fIawk\fP +variable \fBENVIRON\fP. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The nature of the output files depends on the \fIawk\fP program. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +The nature of the output files depends on the \fIawk\fP program. +.SH EXTENDED DESCRIPTION +.SS Overall Program Structure +.LP +An \fIawk\fP program is composed of pairs of the form: +.sp +.RS +.nf + +\fIpattern\fP \fB{\fP \fIaction\fP \fB} +\fP +.fi +.RE +.LP +Either the pattern or the action (including the enclosing brace characters) +can be omitted. +.LP +A missing pattern shall match any record of input, and a missing action +shall be equivalent to: +.sp +.RS +.nf + +\fB{ print } +\fP +.fi +.RE +.LP +Execution of the \fIawk\fP program shall start by first executing +the actions associated with all \fBBEGIN\fP patterns in the +order they occur in the program. Then each \fIfile\fP operand (or +standard input if no files were specified) shall be processed in +turn by reading data from the file until a record separator is seen +( by default). Before the first reference to a +field in the record is evaluated, the record shall be split into fields, +according to the rules in Regular Expressions , using the value of +\fBFS\fP that was current at the time the record was read. Each +pattern in the program then shall be evaluated in the order of occurrence, +and the action associated with each pattern that matches +the current record executed. The action for a matching pattern shall +be executed before evaluating subsequent patterns. Finally, +the actions associated with all \fBEND\fP patterns shall be executed +in the order they occur in the program. +.SS Expressions in awk +.LP +Expressions describe computations used in \fIpatterns\fP and \fIactions\fP. +In the following table, valid expression +operations are given in groups from highest precedence first to lowest +precedence last, with equal-precedence operators grouped +between horizontal lines. In expression evaluation, where the grammar +is formally ambiguous, higher precedence operators shall be +evaluated before lower precedence operators. In this table \fIexpr\fP, +\fIexpr1\fP, \fIexpr2\fP, and \fIexpr3\fP represent any +expression, while lvalue represents any entity that can be assigned +to (that is, on the left side of an assignment operator). The +precise syntax of expressions is given in Grammar . +.sp +.ce 1 +\fBTable: Expressions in Decreasing Precedence in \fIawk\fP\fP +.TS C +center; l1 l1 l1 l. +\fBSyntax\fP \fBName\fP \fBType of Result\fP \fBAssociativity\fP +( \fIexpr\fP ) Grouping Type of \fIexpr\fP N/A +$\fIexpr\fP Field reference String N/A +++ lvalue Pre-increment Numeric N/A +-- lvalue Pre-decrement Numeric N/A +lvalue ++ Post-increment Numeric N/A +lvalue -- Post-decrement Numeric N/A +\fIexpr\fP ^ \fIexpr\fP Exponentiation Numeric Right +! \fIexpr\fP Logical not Numeric N/A ++ \fIexpr\fP Unary plus Numeric N/A +- \fIexpr\fP Unary minus Numeric N/A +\fIexpr\fP * \fIexpr\fP Multiplication Numeric Left +\fIexpr\fP / \fIexpr\fP Division Numeric Left +\fIexpr\fP % \fIexpr\fP Modulus Numeric Left +\fIexpr\fP + \fIexpr\fP Addition Numeric Left +\fIexpr\fP - \fIexpr\fP Subtraction Numeric Left +\fIexpr\fP \fIexpr\fP String concatenation String Left +\fIexpr\fP < \fIexpr\fP Less than Numeric None +\fIexpr\fP <= \fIexpr\fP Less than or equal to Numeric None +\fIexpr\fP != \fIexpr\fP Not equal to Numeric None +\fIexpr\fP == \fIexpr\fP Equal to Numeric None +\fIexpr\fP > \fIexpr\fP Greater than Numeric None +\fIexpr\fP >= \fIexpr\fP Greater than or equal to Numeric None +\fIexpr\fP ~ \fIexpr\fP ERE match Numeric None +\fIexpr\fP !~ \fIexpr\fP ERE non-match Numeric None +\fIexpr\fP in array Array membership Numeric Left +( \fIindex\fP ) in \fIarray\fP Multi-dimension array Numeric Left +\ membership \ \ +\fIexpr\fP && \fIexpr\fP Logical AND Numeric Left +\fIexpr\fP || \fIexpr\fP Logical OR Numeric Left +\fIexpr1\fP ? \fIexpr2\fP : \fIexpr3\fP Conditional expression Type of selected Right +\ \ \fIexpr2\fP or \fIexpr3\fP \ +lvalue ^= \fIexpr\fP Exponentiation assignment Numeric Right +lvalue %= \fIexpr\fP Modulus assignment Numeric Right +lvalue *= \fIexpr\fP Multiplication assignment Numeric Right +lvalue /= \fIexpr\fP Division assignment Numeric Right +lvalue += \fIexpr\fP Addition assignment Numeric Right +lvalue -= \fIexpr\fP Subtraction assignment Numeric Right +lvalue = \fIexpr\fP Assignment Type of \fIexpr\fP Right +.TE +.LP +Each expression shall have either a string value, a numeric value, +or both. Except as stated for specific contexts, the value of +an expression shall be implicitly converted to the type needed for +the context in which it is used. A string value shall be +converted to a numeric value by the equivalent of the following calls +to functions defined by the ISO\ C standard: +.sp +.RS +.nf + +\fBsetlocale(LC_NUMERIC, ""); +\fP\fInumeric_value\fP \fB= atof(\fP\fIstring_value\fP\fB); +\fP +.fi +.RE +.LP +A numeric value that is exactly equal to the value of an integer (see +\fIConcepts Derived +from the ISO C Standard\fP ) shall be converted to a string by the +equivalent of a call to the \fBsprintf\fP function (see String Functions +) with the string \fB"%d"\fP as the \fIfmt\fP argument and the numeric +value being +converted as the first and only \fIexpr\fP argument. Any other numeric +value shall be converted to a string by the equivalent of a +call to the \fBsprintf\fP function with the value of the variable +\fBCONVFMT\fP as the \fIfmt\fP argument and the numeric value +being converted as the first and only \fIexpr\fP argument. The result +of the conversion is unspecified if the value of +\fBCONVFMT\fP is not a floating-point format specification. This volume +of IEEE\ Std\ 1003.1-2001 specifies no explicit +conversions between numbers and strings. An application can force +an expression to be treated as a number by adding zero to it, or +can force it to be treated as a string by concatenating the null string +( \fB""\fP ) to it. +.LP +A string value shall be considered a \fInumeric string\fP if it comes +from one of the following: +.IP " 1." 4 +Field variables +.LP +.IP " 2." 4 +Input from the \fIgetline\fP() function +.LP +.IP " 3." 4 +\fBFILENAME\fP +.LP +.IP " 4." 4 +\fBARGV\fP array elements +.LP +.IP " 5." 4 +\fBENVIRON\fP array elements +.LP +.IP " 6." 4 +Array elements created by the \fIsplit\fP() function +.LP +.IP " 7." 4 +A command line variable assignment +.LP +.IP " 8." 4 +Variable assignment from another numeric string variable +.LP +.LP +and after all the following conversions have been applied, the resulting +string would lexically be recognized as a \fBNUMBER\fP +token as described by the lexical conventions in Grammar : +.IP " *" 3 +All leading and trailing s are discarded. +.LP +.IP " *" 3 +If the first non- is \fB'+'\fP or \fB'-'\fP , it is discarded. +.LP +.IP " *" 3 +Changing each occurrence of the decimal point character from the current +locale to a period. +.LP +.LP +If a \fB'-'\fP character is ignored in the preceding description, +the numeric value of the \fInumeric string\fP shall be the +negation of the numeric value of the recognized \fBNUMBER\fP token. +Otherwise, the numeric value of the \fInumeric string\fP +shall be the numeric value of the recognized \fBNUMBER\fP token. Whether +or not a string is a \fInumeric string\fP shall be +relevant only in contexts where that term is used in this section. +.LP +When an expression is used in a Boolean context, if it has a numeric +value, a value of zero shall be treated as false and any +other value shall be treated as true. Otherwise, a string value of +the null string shall be treated as false and any other value +shall be treated as true. A Boolean context shall be one of the following: +.IP " *" 3 +The first subexpression of a conditional expression +.LP +.IP " *" 3 +An expression operated on by logical NOT, logical AND, or logical +OR +.LP +.IP " *" 3 +The second expression of a \fBfor\fP statement +.LP +.IP " *" 3 +The expression of an \fBif\fP statement +.LP +.IP " *" 3 +The expression of the \fBwhile\fP clause in either a \fBwhile\fP or +\fBdo\fP... \fBwhile\fP statement +.LP +.IP " *" 3 +An expression used as a pattern (as in Overall Program Structure) +.LP +.LP +All arithmetic shall follow the semantics of floating-point arithmetic +as specified by the ISO\ C standard (see \fIConcepts Derived from +the ISO C Standard\fP ). +.LP +The value of the expression: +.sp +.RS +.nf + +\fIexpr1\fP \fB^\fP \fIexpr2\fP +.fi +.RE +.LP +shall be equivalent to the value returned by the ISO\ C standard function +call: +.sp +.RS +.nf + +\fBpow(\fP\fIexpr1\fP\fB,\fP \fIexpr2\fP\fB) +\fP +.fi +.RE +.LP +The expression: +.sp +.RS +.nf + +\fBlvalue ^=\fP \fIexpr\fP +.fi +.RE +.LP +shall be equivalent to the ISO\ C standard expression: +.sp +.RS +.nf + +\fBlvalue = pow(lvalue,\fP \fIexpr\fP\fB) +\fP +.fi +.RE +.LP +except that lvalue shall be evaluated only once. The value of the +expression: +.sp +.RS +.nf + +\fIexpr1\fP \fB%\fP \fIexpr2\fP +.fi +.RE +.LP +shall be equivalent to the value returned by the ISO\ C standard function +call: +.sp +.RS +.nf + +\fBfmod(\fP\fIexpr1\fP\fB,\fP \fIexpr2\fP\fB) +\fP +.fi +.RE +.LP +The expression: +.sp +.RS +.nf + +\fBlvalue %=\fP \fIexpr\fP +.fi +.RE +.LP +shall be equivalent to the ISO\ C standard expression: +.sp +.RS +.nf + +\fBlvalue = fmod(lvalue,\fP \fIexpr\fP\fB) +\fP +.fi +.RE +.LP +except that lvalue shall be evaluated only once. +.LP +Variables and fields shall be set by the assignment statement: +.sp +.RS +.nf + +\fBlvalue =\fP \fIexpression\fP +.fi +.RE +.LP +and the type of \fIexpression\fP shall determine the resulting variable +type. The assignment includes the arithmetic +assignments ( \fB"+="\fP , \fB"-="\fP , \fB"*="\fP , \fB"/="\fP , +\fB"%="\fP , \fB"^="\fP , \fB"++"\fP , +\fB"--"\fP ) all of which shall produce a numeric result. The left-hand +side of an assignment and the target of increment and +decrement operators can be one of a variable, an array with index, +or a field selector. +.LP +The \fIawk\fP language supplies arrays that are used for storing numbers +or strings. Arrays need not be declared. They shall +initially be empty, and their sizes shall change dynamically. The +subscripts, or element identifiers, are strings, providing a type +of associative array capability. An array name followed by a subscript +within square brackets can be used as an lvalue and thus as +an expression, as described in the grammar; see Grammar . Unsubscripted +array names can be used in +only the following contexts: +.IP " *" 3 +A parameter in a function definition or function call +.LP +.IP " *" 3 +The \fBNAME\fP token following any use of the keyword \fBin\fP as +specified in the grammar (see Grammar ); if the name used in this +context is not an array name, the behavior is undefined +.LP +.LP +A valid array \fIindex\fP shall consist of one or more comma-separated +expressions, similar to the way in which +multi-dimensional arrays are indexed in some programming languages. +Because \fIawk\fP arrays are really one-dimensional, such a +comma-separated list shall be converted to a single string by concatenating +the string values of the separate expressions, each +separated from the other by the value of the \fBSUBSEP\fP variable. +Thus, the following two index operations shall be +equivalent: +.sp +.RS +.nf + +\fIvar\fP\fB[\fP\fIexpr1\fP\fB,\fP \fIexpr2\fP\fB, ...\fP \fIexprn\fP\fB] +.sp + +\fP\fIvar\fP\fB[\fP\fIexpr1\fP \fBSUBSEP\fP \fIexpr2\fP \fBSUBSEP ... SUBSEP\fP \fIexprn\fP\fB]\fP +.fi +.RE +.LP +The application shall ensure that a multi-dimensioned \fIindex\fP +used with the \fBin\fP operator is parenthesized. The +\fBin\fP operator, which tests for the existence of a particular array +element, shall not cause that element to exist. Any other +reference to a nonexistent array element shall automatically create +it. +.LP +Comparisons (with the \fB'<'\fP , \fB"<="\fP , \fB"!="\fP , \fB"=="\fP +, \fB'>'\fP , and +\fB">="\fP operators) shall be made numerically if both operands are +numeric, if one is numeric and the other has a string +value that is a numeric string, or if one is numeric and the other +has the uninitialized value. Otherwise, operands shall be +converted to strings as required and a string comparison shall be +made using the locale-specific collation sequence. The value of +the comparison expression shall be 1 if the relation is true, or 0 +if the relation is false. +.SS Variables and Special Variables +.LP +Variables can be used in an \fIawk\fP program by referencing them. +With the exception of function parameters (see User-Defined Functions +), they are not explicitly declared. Function parameter names shall +be local to the +function; all other variable names shall be global. The same name +shall not be used as both a function parameter name and as the +name of a function or a special \fIawk\fP variable. The same name +shall not be used both as a variable name with global scope and +as the name of a function. The same name shall not be used within +the same scope both as a scalar variable and as an array. +Uninitialized variables, including scalar variables, array elements, +and field variables, shall have an uninitialized value. An +uninitialized value shall have both a numeric value of zero and a +string value of the empty string. Evaluation of variables with an +uninitialized value, to either string or numeric, shall be determined +by the context in which they are used. +.LP +Field variables shall be designated by a \fB'$'\fP followed by a number +or numerical expression. The effect of the field +number \fIexpression\fP evaluating to anything other than a non-negative +integer is unspecified; uninitialized variables or string +values need not be converted to numeric values in this context. New +field variables can be created by assigning a value to them. +References to nonexistent fields (that is, fields after $\fBNF\fP), +shall evaluate to the uninitialized value. Such references +shall not create new fields. However, assigning to a nonexistent field +(for example, $(\fBNF\fP+2)=5) shall increase the value of +\fBNF\fP; create any intervening fields with the uninitialized value; +and cause the value of $0 to be recomputed, with the fields +being separated by the value of \fBOFS\fP. Each field variable shall +have a string value or an uninitialized value when created. +Field variables shall have the uninitialized value when created from +$0 using \fBFS\fP and the variable does not contain any +characters. If appropriate, the field variable shall be considered +a numeric string (see Expressions in +awk ). +.LP +Implementations shall support the following other special variables +that are set by \fIawk\fP: +.TP 7 +\fBARGC\fP +The number of elements in the \fBARGV\fP array. +.TP 7 +\fBARGV\fP +An array of command line arguments, excluding options and the \fIprogram\fP +argument, numbered from zero to \fBARGC\fP-1. +.LP +The arguments in \fBARGV\fP can be modified or added to; \fBARGC\fP +can be altered. As each input file ends, \fIawk\fP shall +treat the next non-null element of \fBARGV\fP, up to the current value +of \fBARGC\fP-1, inclusive, as the name of the next input +file. Thus, setting an element of \fBARGV\fP to null means that it +shall not be treated as an input file. The name \fB'-'\fP +indicates the standard input. If an argument matches the format of +an \fIassignment\fP operand, this argument shall be treated as +an \fIassignment\fP rather than a \fIfile\fP argument. +.TP 7 +\fBCONVFMT\fP +The \fBprintf\fP format for converting numbers to strings (except +for output statements, where \fBOFMT\fP is used); +\fB"%.6g"\fP by default. +.TP 7 +\fBENVIRON\fP +An array representing the value of the environment, as described in +the \fIexec\fP functions defined in the System Interfaces +volume of IEEE\ Std\ 1003.1-2001. The indices of the array shall be +strings consisting of the names of the environment +variables, and the value of each array element shall be a string consisting +of the value of that variable. If appropriate, the +environment variable shall be considered a \fInumeric string\fP (see +Expressions in awk ); the +array element shall also have its numeric value. +.LP +In all cases where the behavior of \fIawk\fP is affected by environment +variables (including the environment of any commands +that \fIawk\fP executes via the \fBsystem\fP function or via pipeline +redirections with the \fBprint\fP statement, the +\fBprintf\fP statement, or the \fBgetline\fP function), the environment +used shall be the environment at the time \fIawk\fP +began executing; it is implementation-defined whether any modification +of \fBENVIRON\fP affects this environment. +.TP 7 +\fBFILENAME\fP +A pathname of the current input file. Inside a \fBBEGIN\fP action +the value is undefined. Inside an \fBEND\fP action the +value shall be the name of the last input file processed. +.TP 7 +\fBFNR\fP +The ordinal number of the current record in the current file. Inside +a \fBBEGIN\fP action the value shall be zero. Inside an +\fBEND\fP action the value shall be the number of the last record +processed in the last file processed. +.TP 7 +\fBFS\fP +Input field separator regular expression; a by default. +.TP 7 +\fBNF\fP +The number of fields in the current record. Inside a \fBBEGIN\fP action, +the use of \fBNF\fP is undefined unless a +\fBgetline\fP function without a \fIvar\fP argument is executed previously. +Inside an \fBEND\fP action, \fBNF\fP shall retain +the value it had for the last record read, unless a subsequent, redirected, +\fBgetline\fP function without a \fIvar\fP argument +is performed prior to entering the \fBEND\fP action. +.TP 7 +\fBNR\fP +The ordinal number of the current record from the start of input. +Inside a \fBBEGIN\fP action the value shall be zero. Inside +an \fBEND\fP action the value shall be the number of the last record +processed. +.TP 7 +\fBOFMT\fP +The \fBprintf\fP format for converting numbers to strings in output +statements (see Output +Statements ); \fB"%.6g"\fP by default. The result of the conversion +is unspecified if the value of \fBOFMT\fP is not a +floating-point format specification. +.TP 7 +\fBOFS\fP +The \fBprint\fP statement output field separation; by default. +.TP 7 +\fBORS\fP +The \fBprint\fP statement output record separator; a by +default. +.TP 7 +\fBRLENGTH\fP +The length of the string matched by the \fBmatch\fP function. +.TP 7 +\fBRS\fP +The first character of the string value of \fBRS\fP shall be the input +record separator; a by default. If +\fBRS\fP contains more than one character, the results are unspecified. +If \fBRS\fP is null, then records are separated by +sequences consisting of a plus one or more blank lines, +leading or trailing blank lines shall not result in empty +records at the beginning or end of the input, and a shall +always be a field separator, no matter what the value of +\fBFS\fP is. +.TP 7 +\fBRSTART\fP +The starting position of the string matched by the \fBmatch\fP function, +numbering from 1. This shall always be equivalent to +the return value of the \fBmatch\fP function. +.TP 7 +\fBSUBSEP\fP +The subscript separator string for multi-dimensional arrays; the default +value is implementation-defined. +.sp +.SS Regular Expressions +.LP +The \fIawk\fP utility shall make use of the extended regular expression +notation (see the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 9.4, Extended Regular Expressions) +except that it shall allow the use of C-language conventions for escaping +special characters within the EREs, as specified in the +table in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter +5, File +Format Notation ( \fB'\\\\'\fP , \fB'\\a'\fP , \fB'\\b'\fP , \fB'\\f'\fP +, \fB'\\n'\fP , \fB'\\r'\fP , \fB'\\t'\fP +, \fB'\\v'\fP ) and the following table; these escape sequences shall +be recognized both inside and outside bracket expressions. +Note that records need not be separated by s and string constants +can contain s, so even the +\fB"\\n"\fP sequence is valid in \fIawk\fP EREs. Using a slash character +within an ERE requires the escaping shown in the +following table. +.br +.sp +.ce 1 +\fBTable: Escape Sequences in \fIawk\fP\fP +.TS C +center; l1 lw(30)1 lw(30). +\fBEscape\fP T{ +.na +\fB\ \fP +.ad +T} T{ +.na +\fB\ \fP +.ad +T} +\fBSequence\fP T{ +.na +\fBDescription\fP +.ad +T} T{ +.na +\fBMeaning\fP +.ad +T} +\\" T{ +.na +Backslash quotation-mark +.ad +T} T{ +.na +Quotation-mark character +.ad +T} +\\/ T{ +.na +Backslash slash +.ad +T} T{ +.na +Slash character +.ad +T} +\\ddd T{ +.na +A backslash character followed by the longest sequence of one, two, or three octal-digit characters (01234567). If all of the digits are 0 (that is, representation of the NUL character), the behavior is undefined. +.ad +T} T{ +.na +The character whose encoding is represented by the one, two, or three-digit octal integer. Multi-byte characters require multiple, concatenated escape sequences of this type, including the leading \fB'\\'\fP for each byte. +.ad +T} +\\c T{ +.na +A backslash character followed by any character not described in this table or in the table in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 5, File Format Notation ( \fB'\\\\'\fP , \fB'\\a'\fP , \fB'\\b'\fP , \fB'\\f'\fP , \fB'\\n'\fP , \fB'\\r'\fP , \fB'\\t'\fP , \fB'\\v'\fP ). +.ad +T} T{ +.na +Undefined +.ad +T} +.TE +.LP +A regular expression can be matched against a specific field or string +by using one of the two regular expression matching +operators, \fB'~'\fP and \fB"!~"\fP . These operators shall interpret +their right-hand operand as a regular +expression and their left-hand operand as a string. If the regular +expression matches the string, the \fB'~'\fP expression +shall evaluate to a value of 1, and the \fB"!~"\fP expression shall +evaluate to a value of 0. (The regular expression +matching operation is as defined by the term matched in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 9.1, Regular Expression +Definitions, where a match occurs on any part of the +string unless the regular expression is limited with the circumflex +or dollar sign special characters.) If the regular expression +does not match the string, the \fB'~'\fP expression shall evaluate +to a value of 0, and the \fB"!~"\fP expression +shall evaluate to a value of 1. If the right-hand operand is any expression +other than the lexical token \fBERE\fP, the string +value of the expression shall be interpreted as an extended regular +expression, including the escape conventions described above. +Note that these same escape conventions shall also be applied in determining +the value of a string literal (the lexical token +\fBSTRING\fP), and thus shall be applied a second time when a string +literal is used in this context. +.LP +When an \fBERE\fP token appears as an expression in any context other +than as the right-hand of the \fB'~'\fP or +\fB"!~"\fP operator or as one of the built-in function arguments described +below, the value of the resulting expression +shall be the equivalent of: +.sp +.RS +.nf + +\fB$0 ~ /\fP\fIere\fP\fB/ +\fP +.fi +.RE +.LP +The \fIere\fP argument to the \fBgsub\fP, \fBmatch\fP, \fBsub\fP functions, +and the \fIfs\fP argument to the \fBsplit\fP +function (see String Functions ) shall be interpreted as extended +regular expressions. These can be +either \fBERE\fP tokens or arbitrary expressions, and shall be interpreted +in the same manner as the right-hand side of the +\fB'~'\fP or \fB"!~"\fP operator. +.LP +An extended regular expression can be used to separate fields by using +the \fB-F\fP \fIERE\fP option or by assigning a string +containing the expression to the built-in variable \fBFS\fP. The default +value of the \fBFS\fP variable shall be a single +. The following describes \fBFS\fP behavior: +.IP " 1." 4 +If \fBFS\fP is a null string, the behavior is unspecified. +.LP +.IP " 2." 4 +If \fBFS\fP is a single character: +.RS +.IP " a." 4 +If \fBFS\fP is , skip leading and trailing s; fields +shall be delimited by sets of one or more +s. +.LP +.IP " b." 4 +Otherwise, if \fBFS\fP is any other character \fIc\fP, fields shall +be delimited by each single occurrence of \fIc\fP. +.LP +.RE +.LP +.IP " 3." 4 +Otherwise, the string value of \fBFS\fP shall be considered to be +an extended regular expression. Each occurrence of a sequence +matching the extended regular expression shall delimit fields. +.LP +.LP +Except for the \fB'~'\fP and \fB"!~"\fP operators, and in the \fBgsub\fP, +\fBmatch\fP, \fBsplit\fP, and +\fBsub\fP built-in functions, ERE matching shall be based on input +records; that is, record separator characters (the first +character of the value of the variable \fBRS\fP, by default) +cannot be embedded in the expression, and no +expression shall match the record separator character. If the record +separator is not , s embedded in +the expression can be matched. For the \fB'~'\fP and \fB"!~"\fP operators, +and in those four built-in functions, +ERE matching shall be based on text strings; that is, any character +(including and the record separator) can be +embedded in the pattern, and an appropriate pattern shall match any +character. However, in all \fIawk\fP ERE matching, the use of +one or more NUL characters in the pattern, input record, or text string +produces undefined results. +.SS Patterns +.LP +A \fIpattern\fP is any valid \fIexpression\fP, a range specified by +two expressions separated by a comma, or one of the two +special patterns \fBBEGIN\fP or \fBEND\fP. +.SS Special Patterns +.LP +The \fIawk\fP utility shall recognize two special patterns, \fBBEGIN\fP +and \fBEND\fP. Each \fBBEGIN\fP pattern shall be +matched once and its associated action executed before the first record +of input is read (except possibly by use of the +\fBgetline\fP function-see Input/Output and General Functions - in +a prior \fBBEGIN\fP action) and +before command line assignment is done. Each \fBEND\fP pattern shall +be matched once and its associated action executed after the +last record of input has been read. These two patterns shall have +associated actions. +.LP +\fBBEGIN\fP and \fBEND\fP shall not combine with other patterns. Multiple +\fBBEGIN\fP and \fBEND\fP patterns shall be +allowed. The actions associated with the \fBBEGIN\fP patterns shall +be executed in the order specified in the program, as are the +\fBEND\fP actions. An \fBEND\fP pattern can precede a \fBBEGIN\fP +pattern in a program. +.LP +If an \fIawk\fP program consists of only actions with the pattern +\fBBEGIN\fP, and the \fBBEGIN\fP action contains no +\fBgetline\fP function, \fIawk\fP shall exit without reading its input +when the last statement in the last \fBBEGIN\fP action is +executed. If an \fIawk\fP program consists of only actions with the +pattern \fBEND\fP or only actions with the patterns +\fBBEGIN\fP and \fBEND\fP, the input shall be read before the statements +in the \fBEND\fP actions are executed. +.SS Expression Patterns +.LP +An expression pattern shall be evaluated as if it were an expression +in a Boolean context. If the result is true, the pattern +shall be considered to match, and the associated action (if any) shall +be executed. If the result is false, the action shall not be +executed. +.SS Pattern Ranges +.LP +A pattern range consists of two expressions separated by a comma; +in this case, the action shall be performed for all records +between a match of the first expression and the following match of +the second expression, inclusive. At this point, the pattern +range can be repeated starting at input records subsequent to the +end of the matched range. +.SS Actions +.LP +An action is a sequence of statements as shown in the grammar in Grammar +\&. Any single statement +can be replaced by a statement list enclosed in braces. The application +shall ensure that statements in a statement list are +separated by s or semicolons. Statements in a statement list +shall be executed sequentially in the order that they +appear. +.LP +The \fIexpression\fP acting as the conditional in an \fBif\fP statement +shall be evaluated and if it is non-zero or non-null, +the following statement shall be executed; otherwise, if \fBelse\fP +is present, the statement following the \fBelse\fP shall be +executed. +.LP +The \fBif\fP, \fBwhile\fP, \fBdo\fP... \fBwhile\fP, \fBfor\fP, \fBbreak\fP, +and \fBcontinue\fP statements are based on +the ISO\ C standard (see \fIConcepts Derived from the ISO C Standard\fP +), except +that the Boolean expressions shall be treated as described in Expressions +in awk , and except in the +case of: +.sp +.RS +.nf + +\fBfor (\fP\fIvariable\fP \fBin\fP \fIarray\fP\fB) +\fP +.fi +.RE +.LP +which shall iterate, assigning each \fIindex\fP of \fIarray\fP to +\fIvariable\fP in an unspecified order. The results of +adding new elements to \fIarray\fP within such a \fBfor\fP loop are +undefined. If a \fBbreak\fP or \fBcontinue\fP statement +occurs outside of a loop, the behavior is undefined. +.LP +The \fBdelete\fP statement shall remove an individual array element. +Thus, the following code deletes an entire array: +.sp +.RS +.nf + +\fBfor (index in array) + delete array[index] +\fP +.fi +.RE +.LP +The \fBnext\fP statement shall cause all further processing of the +current input record to be abandoned. The behavior is +undefined if a \fBnext\fP statement appears or is invoked in a \fBBEGIN\fP +or \fBEND\fP action. +.LP +The \fBexit\fP statement shall invoke all \fBEND\fP actions in the +order in which they occur in the program source and then +terminate the program without reading further input. An \fBexit\fP +statement inside an \fBEND\fP action shall terminate the +program without further execution of \fBEND\fP actions. If an expression +is specified in an \fBexit\fP statement, its numeric +value shall be the exit status of \fIawk\fP, unless subsequent errors +are encountered or a subsequent \fBexit\fP statement with +an expression is executed. +.SS Output Statements +.LP +Both \fBprint\fP and \fBprintf\fP statements shall write to standard +output by default. The output shall be written to the +location specified by \fIoutput_redirection\fP if one is supplied, +as follows: +.sp +.RS +.nf + +\fB>\fP \fIexpression\fP\fB>>\fP \fIexpression\fP\fB|\fP \fIexpression\fP +.fi +.RE +.LP +In all cases, the \fIexpression\fP shall be evaluated to produce a +string that is used as a pathname into which to write (for +\fB'>'\fP or \fB">>"\fP ) or as a command to be executed (for \fB'|'\fP +). Using the first two forms, if the file +of that name is not currently open, it shall be opened, creating it +if necessary and using the first form, truncating the file. The +output then shall be appended to the file. As long as the file remains +open, subsequent calls in which \fIexpression\fP evaluates +to the same string value shall simply append output to the file. The +file remains open until the \fBclose\fP function (see Input/Output +and General Functions ) is called with an expression that evaluates +to the same string +value. +.LP +The third form shall write output onto a stream piped to the input +of a command. The stream shall be created if no stream is +currently open with the value of \fIexpression\fP as its command name. +The stream created shall be equivalent to one created by a +call to the \fIpopen\fP() function defined in the System Interfaces +volume of +IEEE\ Std\ 1003.1-2001 with the value of \fIexpression\fP as the \fIcommand\fP +argument and a value of \fIw\fP as the +\fImode\fP argument. As long as the stream remains open, subsequent +calls in which \fIexpression\fP evaluates to the same string +value shall write output to the existing stream. The stream shall +remain open until the \fBclose\fP function (see Input/Output and General +Functions ) is called with an expression that evaluates to the same +string value. +At that time, the stream shall be closed as if by a call to the \fIpclose\fP() +function +defined in the System Interfaces volume of IEEE\ Std\ 1003.1-2001. +.LP +As described in detail by the grammar in Grammar , these output statements +shall take a +comma-separated list of \fIexpression\fPs referred to in the grammar +by the non-terminal symbols \fBexpr_list\fP, +\fBprint_expr_list\fP, or \fBprint_expr_list_opt\fP. This list is +referred to here as the \fIexpression list\fP, and each member +is referred to as an \fIexpression argument\fP. +.LP +The \fBprint\fP statement shall write the value of each expression +argument onto the indicated output stream separated by the +current output field separator (see variable \fBOFS\fP above), and +terminated by the output record separator (see variable +\fBORS\fP above). All expression arguments shall be taken as strings, +being converted if necessary; this conversion shall be as +described in Expressions in awk , with the exception that the \fBprintf\fP +format in \fBOFMT\fP +shall be used instead of the value in \fBCONVFMT\fP. An empty expression +list shall stand for the whole input record ($0). +.LP +The \fBprintf\fP statement shall produce output based on a notation +similar to the File Format Notation used to describe file +formats in this volume of IEEE\ Std\ 1003.1-2001 (see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 5, File Format Notation). +Output shall be produced as specified with the first +\fIexpression\fP argument as the string \fIformat\fP and subsequent +\fIexpression\fP arguments as the strings \fIarg1\fP to +\fIargn\fP, inclusive, with the following exceptions: +.IP " 1." 4 +The \fIformat\fP shall be an actual character string rather than a +graphical representation. Therefore, it cannot contain empty +character positions. The in the \fIformat\fP string, in any +context other than a \fIflag\fP of a conversion +specification, shall be treated as an ordinary character that is copied +to the output. +.LP +.IP " 2." 4 +If the character set contains a \fB' '\fP character and that character +appears in +the \fIformat\fP string, it shall be treated as an ordinary character +that is copied to the output. +.LP +.IP " 3." 4 +The \fIescape sequences\fP beginning with a backslash character shall +be treated as sequences of ordinary characters that are +copied to the output. Note that these same sequences shall be interpreted +lexically by \fIawk\fP when they appear in literal +strings, but they shall not be treated specially by the \fBprintf\fP +statement. +.LP +.IP " 4." 4 +A \fIfield width\fP or \fIprecision\fP can be specified as the \fB'*'\fP +character instead of a digit string. In this case +the next argument from the expression list shall be fetched and its +numeric value taken as the field width or precision. +.LP +.IP " 5." 4 +The implementation shall not precede or follow output from the \fBd\fP +or \fBu\fP conversion specifier characters with +s not specified by the \fIformat\fP string. +.LP +.IP " 6." 4 +The implementation shall not precede output from the \fBo\fP conversion +specifier character with leading zeros not specified +by the \fIformat\fP string. +.LP +.IP " 7." 4 +For the \fBc\fP conversion specifier character: if the argument has +a numeric value, the character whose encoding is that +value shall be output. If the value is zero or is not the encoding +of any character in the character set, the behavior is +undefined. If the argument does not have a numeric value, the first +character of the string value shall be output; if the string +does not contain any characters, the behavior is undefined. +.LP +.IP " 8." 4 +For each conversion specification that consumes an argument, the next +expression argument shall be evaluated. With the exception +of the \fBc\fP conversion specifier character, the value shall be +converted (according to the rules specified in Expressions in awk +) to the appropriate type for the conversion specification. +.LP +.IP " 9." 4 +If there are insufficient expression arguments to satisfy all the +conversion specifications in the \fIformat\fP string, the +behavior is undefined. +.LP +.IP "10." 4 +If any character sequence in the \fIformat\fP string begins with a +\fB'%'\fP character, but does not form a valid conversion +specification, the behavior is unspecified. +.LP +.LP +Both \fBprint\fP and \fBprintf\fP can output at least {LINE_MAX} bytes. +.SS Functions +.LP +The \fIawk\fP language has a variety of built-in functions: arithmetic, +string, input/output, and general. +.SS Arithmetic Functions +.LP +The arithmetic functions, except for \fBint\fP, shall be based on +the ISO\ C standard (see \fIConcepts Derived from the ISO C Standard\fP +). The behavior is undefined in cases where the +ISO\ C standard specifies that an error be returned or that the behavior +is undefined. Although the grammar (see Grammar ) permits built-in +functions to appear with no arguments or parentheses, unless the argument +or +parentheses are indicated as optional in the following list (by displaying +them within the \fB"[]"\fP brackets), such use is +undefined. +.TP 7 +\fBatan2\fP(\fIy\fP,\fIx\fP) +Return arctangent of \fIy\fP/\fIx\fP in radians in the range [-pi,pi]. +.TP 7 +\fBcos\fP(\fIx\fP) +Return cosine of \fIx\fP, where \fIx\fP is in radians. +.TP 7 +\fBsin\fP(\fIx\fP) +Return sine of \fIx\fP, where \fIx\fP is in radians. +.TP 7 +\fBexp\fP(\fIx\fP) +Return the exponential function of \fIx\fP. +.TP 7 +\fBlog\fP(\fIx\fP) +Return the natural logarithm of \fIx\fP. +.TP 7 +\fBsqrt\fP(\fIx\fP) +Return the square root of \fIx\fP. +.TP 7 +\fBint\fP(\fIx\fP) +Return the argument truncated to an integer. Truncation shall be toward +0 when \fIx\fP>0. +.TP 7 +\fBrand\fP() +Return a random number \fIn\fP, such that 0<=\fIn\fP<1. +.TP 7 +\fBsrand\fP(\fB[\fP\fIexpr\fP\fB]\fP) +Set the seed value for \fIrand\fP to \fIexpr\fP or use the time of +day if \fIexpr\fP is omitted. The previous seed value +shall be returned. +.sp +.SS String Functions +.LP +The string functions in the following list shall be supported. Although +the grammar (see Grammar +) permits built-in functions to appear with no arguments or parentheses, +unless the argument or parentheses are indicated as +optional in the following list (by displaying them within the \fB"[]"\fP +brackets), such use is undefined. +.TP 7 +\fBgsub\fP(\fIere\fP,\ \fIrepl\fP\fB[\fP,\ \fIin\fP\fB]\fP) +Behave like \fBsub\fP (see below), except that it shall replace all +occurrences of the regular expression (like the \fIed\fP utility global +substitute) in $0 or in the \fIin\fP argument, when specified. +.TP 7 +\fBindex\fP(\fIs\fP,\ \fIt\fP) +Return the position, in characters, numbering from 1, in string \fIs\fP +where string \fIt\fP first occurs, or zero if it does +not occur at all. +.TP 7 +\fBlength[\fP(\fB[\fP\fIs\fP\fB]\fP)\fB]\fP +Return the length, in characters, of its argument taken as a string, +or of the whole record, $0, if there is no argument. +.TP 7 +\fBmatch\fP(\fIs\fP,\ \fIere\fP) +Return the position, in characters, numbering from 1, in string \fIs\fP +where the extended regular expression \fIere\fP +occurs, or zero if it does not occur at all. RSTART shall be set to +the starting position (which is the same as the returned +value), zero if no match is found; RLENGTH shall be set to the length +of the matched string, -1 if no match is found. +.TP 7 +\fBsplit\fP(\fIs\fP,\ \fIa\fP\fB[\fP,\ \fIfs\ \fP \fB]\fP) +Split the string \fIs\fP into array elements \fIa\fP[1], \fIa\fP[2], +\&..., \fIa\fP[\fIn\fP], and return \fIn\fP. All elements +of the array shall be deleted before the split is performed. The separation +shall be done with the ERE \fIfs\fP or with the field +separator \fBFS\fP if \fIfs\fP is not given. Each array element shall +have a string value when created and, if appropriate, the +array element shall be considered a numeric string (see Expressions +in awk ). The effect of a null +string as the value of \fIfs\fP is unspecified. +.TP 7 +\fBsprintf\fP(\fIfmt\fP,\ \fIexpr\fP,\ \fIexpr\fP,\ ...) +Format the expressions according to the \fBprintf\fP format given +by \fIfmt\fP and return the resulting string. +.TP 7 +\fBsub(\fP\fIere\fP,\ \fIrepl\fP\fB[\fP,\ \fIin\ \fP \fB]\fP) +Substitute the string \fIrepl\fP in place of the first instance of +the extended regular expression \fIERE\fP in string \fIin\fP +and return the number of substitutions. An ampersand ( \fB'&'\fP ) +appearing in the string \fIrepl\fP shall be replaced by +the string from \fIin\fP that matches the ERE. An ampersand preceded +with a backslash ( \fB'\\'\fP ) shall be interpreted as the +literal ampersand character. An occurrence of two consecutive backslashes +shall be interpreted as just a single literal backslash +character. Any other occurrence of a backslash (for example, preceding +any other character) shall be treated as a literal backslash +character. Note that if \fIrepl\fP is a string literal (the lexical +token \fBSTRING\fP; see Grammar ), the handling of the ampersand character +occurs after any lexical processing, including any +lexical backslash escape sequence processing. If \fIin\fP is specified +and it is not an lvalue (see Expressions in awk ), the behavior is +undefined. If \fIin\fP is omitted, \fIawk\fP shall use the current +record ($0) in its place. +.TP 7 +\fBsubstr\fP(\fIs\fP,\ \fIm\fP\fB[\fP,\ \fIn\ \fP \fB]\fP) +Return the at most \fIn\fP-character substring of \fIs\fP that begins +at position \fIm\fP, numbering from 1. If \fIn\fP is +omitted, or if \fIn\fP specifies more characters than are left in +the string, the length of the substring shall be limited by the +length of the string \fIs\fP. +.TP 7 +\fBtolower\fP(\fIs\fP) +Return a string based on the string \fIs\fP. Each character in \fIs\fP +that is an uppercase letter specified to have a +\fBtolower\fP mapping by the \fILC_CTYPE\fP category of the current +locale shall be replaced in the returned string by the +lowercase letter specified by the mapping. Other characters in \fIs\fP +shall be unchanged in the returned string. +.TP 7 +\fBtoupper\fP(\fIs\fP) +Return a string based on the string \fIs\fP. Each character in \fIs\fP +that is a lowercase letter specified to have a +\fBtoupper\fP mapping by the \fILC_CTYPE\fP category of the current +locale is replaced in the returned string by the uppercase +letter specified by the mapping. Other characters in \fIs\fP are unchanged +in the returned string. +.sp +.LP +All of the preceding functions that take \fIERE\fP as a parameter +expect a pattern or a string valued expression that is a +regular expression as defined in Regular Expressions . +.SS Input/Output and General Functions +.LP +The input/output and general functions are: +.TP 7 +\fBclose\fP(\fIexpression\fP) +Close the file or pipe opened by a \fBprint\fP or \fBprintf\fP statement +or a call to \fBgetline\fP with the same string-valued +\fIexpression\fP. The limit on the number of open \fIexpression\fP +arguments is implementation-defined. If the close was +successful, the function shall return zero; otherwise, it shall return +non-zero. +.TP 7 +\fIexpression\ |\ \fP \fBgetline\ [\fP\fIvar\fP\fB]\fP +Read a record of input from a stream piped from the output of a command. +The stream shall be created if no stream is currently open +with the value of \fIexpression\fP as its command name. The stream +created shall be equivalent to one created by a call to the \fIpopen\fP() +function with the value of \fIexpression\fP as the \fIcommand\fP argument +and a +value of \fIr\fP as the \fImode\fP argument. As long as the stream +remains open, subsequent calls in which \fIexpression\fP +evaluates to the same string value shall read subsequent records from +the stream. The stream shall remain open until the +\fBclose\fP function is called with an expression that evaluates to +the same string value. At that time, the stream shall be +closed as if by a call to the \fIpclose\fP() function. If \fIvar\fP +is omitted, $0 and +\fBNF\fP shall be set; otherwise, \fIvar\fP shall be set and, if appropriate, +it shall be considered a numeric string (see Expressions in awk ). +.LP +The \fBgetline\fP operator can form ambiguous constructs when there +are unparenthesized operators (including concatenate) to +the left of the \fB'|'\fP (to the beginning of the expression containing +\fBgetline\fP). In the context of the \fB'$'\fP +operator, \fB'|'\fP shall behave as if it had a lower precedence than +\fB'$'\fP . The result of evaluating other operators is +unspecified, and conforming applications shall parenthesize properly +all such usages. +.TP 7 +\fBgetline\fP +Set $0 to the next input record from the current input file. This +form of \fBgetline\fP shall set the \fBNF\fP, \fBNR\fP, +and \fBFNR\fP variables. +.TP 7 +\fBgetline\ \fP \fIvar\fP +Set variable \fIvar\fP to the next input record from the current input +file and, if appropriate, \fIvar\fP shall be +considered a numeric string (see Expressions in awk ). This form of +\fBgetline\fP shall set the +\fBFNR\fP and \fBNR\fP variables. +.TP 7 +\fBgetline\ [\fP\fIvar\fP\fB]\ \fP <\ \fIexpression\fP +Read the next record of input from a named file. The \fIexpression\fP +shall be evaluated to produce a string that is used as a +pathname. If the file of that name is not currently open, it shall +be opened. As long as the stream remains open, subsequent calls +in which \fIexpression\fP evaluates to the same string value shall +read subsequent records from the file. The file shall remain +open until the \fBclose\fP function is called with an expression that +evaluates to the same string value. If \fIvar\fP is +omitted, $0 and \fBNF\fP shall be set; otherwise, \fIvar\fP shall +be set and, if appropriate, it shall be considered a numeric +string (see Expressions in awk ). +.LP +The \fBgetline\fP operator can form ambiguous constructs when there +are unparenthesized binary operators (including +concatenate) to the right of the \fB'<'\fP (up to the end of the expression +containing the \fBgetline\fP). The result of +evaluating such a construct is unspecified, and conforming applications +shall parenthesize properly all such usages. +.TP 7 +\fBsystem\fP(\fIexpression\fP) +Execute the command given by \fIexpression\fP in a manner equivalent +to the \fIsystem\fP() +function defined in the System Interfaces volume of IEEE\ Std\ 1003.1-2001 +and return the exit status of the command. +.sp +.LP +All forms of \fBgetline\fP shall return 1 for successful input, zero +for end-of-file, and -1 for an error. +.LP +Where strings are used as the name of a file or pipeline, the application +shall ensure that the strings are textually identical. +The terminology "same string value" implies that "equivalent strings", +even those that differ only by s, represent +different files. +.SS User-Defined Functions +.LP +The \fIawk\fP language also provides user-defined functions. Such +functions can be defined as: +.sp +.RS +.nf + +\fBfunction\fP \fIname\fP\fB(\fP\fB[\fP\fIparameter\fP\fB, ...\fP\fB]\fP\fB) {\fP \fIstatements\fP \fB} +\fP +.fi +.RE +.LP +A function can be referred to anywhere in an \fIawk\fP program; in +particular, its use can precede its definition. The scope of +a function is global. +.LP +Function parameters, if present, can be either scalars or arrays; +the behavior is undefined if an array name is passed as a +parameter that the function uses as a scalar, or if a scalar expression +is passed as a parameter that the function uses as an +array. Function parameters shall be passed by value if scalar and +by reference if array name. +.LP +The number of parameters in the function definition need not match +the number of parameters in the function call. Excess formal +parameters can be used as local variables. If fewer arguments are +supplied in a function call than are in the function definition, +the extra parameters that are used in the function body as scalars +shall evaluate to the uninitialized value until they are +otherwise initialized, and the extra parameters that are used in the +function body as arrays shall be treated as uninitialized +arrays where each element evaluates to the uninitialized value until +otherwise initialized. +.LP +When invoking a function, no white space can be placed between the +function name and the opening parenthesis. Function calls can +be nested and recursive calls can be made upon functions. Upon return +from any nested or recursive function call, the values of all +of the calling function's parameters shall be unchanged, except for +array parameters passed by reference. The \fBreturn\fP +statement can be used to return a value. If a \fBreturn\fP statement +appears outside of a function definition, the behavior is +undefined. +.LP +In the function definition, s shall be optional before the +opening brace and after the closing brace. Function +definitions can appear anywhere in the program where a \fIpattern-action\fP +pair is allowed. +.SS Grammar +.LP +The grammar in this section and the lexical conventions in the following +section shall together describe the syntax for +\fIawk\fP programs. The general conventions for this style of grammar +are described in \fIGrammar Conventions\fP . A valid program can be +represented as the non-terminal symbol +\fIprogram\fP in the grammar. This formal syntax shall take precedence +over the preceding text syntax description. +.sp +.RS +.nf + +\fB%token NAME NUMBER STRING ERE +%token FUNC_NAME /* Name followed by '(' without white space. */ +.sp + +/* Keywords */ +%token Begin End +/* 'BEGIN' 'END' */ +.sp + +%token Break Continue Delete Do Else +/* 'break' 'continue' 'delete' 'do' 'else' */ +.sp + +%token Exit For Function If In +/* 'exit' 'for' 'function' 'if' 'in' */ +.sp + +%token Next Print Printf Return While +/* 'next' 'print' 'printf' 'return' 'while' */ +.sp + +/* Reserved function names */ +%token BUILTIN_FUNC_NAME + /* One token for the following: + * atan2 cos sin exp log sqrt int rand srand + * gsub index length match split sprintf sub + * substr tolower toupper close system + */ +%token GETLINE + /* Syntactically different from other built-ins. */ +.sp + +/* Two-character tokens. */ +%token ADD_ASSIGN SUB_ASSIGN MUL_ASSIGN DIV_ASSIGN MOD_ASSIGN POW_ASSIGN +/* '+=' '-=' '*=' '/=' '%=' '^=' */ +.sp + +%token OR AND NO_MATCH EQ LE GE NE INCR DECR APPEND +/* '||' '&&' '!~' '==' '<=' '>=' '!=' '++' '--' '>>' */ +.sp + +/* One-character tokens. */ +%token '{' '}' '(' ')' '[' ']' ',' ';' NEWLINE +%token '+' '-' '*' '%' '^' '!' '>' '<' '|' '?' ':' '~' '$' '=' +.sp + +%start program +%% +.sp + +program : item_list + | actionless_item_list + ; +.sp + +item_list : newline_opt + | actionless_item_list item terminator + | item_list item terminator + | item_list action terminator + ; +.sp + +actionless_item_list : item_list pattern terminator + | actionless_item_list pattern terminator + ; +.sp + +item : pattern action + | Function NAME '(' param_list_opt ')' + newline_opt action + | Function FUNC_NAME '(' param_list_opt ')' + newline_opt action + ; +.sp + +param_list_opt : /* empty */ + | param_list + ; +.sp + +param_list : NAME + | param_list ',' NAME + ; +.sp + +pattern : Begin + | End + | expr + | expr ',' newline_opt expr + ; +.sp + +action : '{' newline_opt '}' + | '{' newline_opt terminated_statement_list '}' + | '{' newline_opt unterminated_statement_list '}' + ; +.sp + +terminator : terminator ';' + | terminator NEWLINE + | ';' + | NEWLINE + ; +.sp + +terminated_statement_list : terminated_statement + | terminated_statement_list terminated_statement + ; +.sp + +unterminated_statement_list : unterminated_statement + | terminated_statement_list unterminated_statement + ; +.sp + +terminated_statement : action newline_opt + | If '(' expr ')' newline_opt terminated_statement + | If '(' expr ')' newline_opt terminated_statement + Else newline_opt terminated_statement + | While '(' expr ')' newline_opt terminated_statement + | For '(' simple_statement_opt ';' + expr_opt ';' simple_statement_opt ')' newline_opt + terminated_statement + | For '(' NAME In NAME ')' newline_opt + terminated_statement + | ';' newline_opt + | terminatable_statement NEWLINE newline_opt + | terminatable_statement ';' newline_opt + ; +.sp + +unterminated_statement : terminatable_statement + | If '(' expr ')' newline_opt unterminated_statement + | If '(' expr ')' newline_opt terminated_statement + Else newline_opt unterminated_statement + | While '(' expr ')' newline_opt unterminated_statement + | For '(' simple_statement_opt ';' + expr_opt ';' simple_statement_opt ')' newline_opt + unterminated_statement + | For '(' NAME In NAME ')' newline_opt + unterminated_statement + ; +.sp + +terminatable_statement : simple_statement + | Break + | Continue + | Next + | Exit expr_opt + | Return expr_opt + | Do newline_opt terminated_statement While '(' expr ')' + ; +.sp + +simple_statement_opt : /* empty */ + | simple_statement + ; +.sp + +simple_statement : Delete NAME '[' expr_list ']' + | expr + | print_statement + ; +.sp + +print_statement : simple_print_statement + | simple_print_statement output_redirection + ; +.sp + +simple_print_statement : Print print_expr_list_opt + | Print '(' multiple_expr_list ')' + | Printf print_expr_list + | Printf '(' multiple_expr_list ')' + ; +.sp + +output_redirection : '>' expr + | APPEND expr + | '|' expr + ; +.sp + +expr_list_opt : /* empty */ + | expr_list + ; +.sp + +expr_list : expr + | multiple_expr_list + ; +.sp + +multiple_expr_list : expr ',' newline_opt expr + | multiple_expr_list ',' newline_opt expr + ; +.sp + +expr_opt : /* empty */ + | expr + ; +.sp + +expr : unary_expr + | non_unary_expr + ; +.sp + +unary_expr : '+' expr + | '-' expr + | unary_expr '^' expr + | unary_expr '*' expr + | unary_expr '/' expr + | unary_expr '%' expr + | unary_expr '+' expr + | unary_expr '-' expr + | unary_expr non_unary_expr + | unary_expr '<' expr + | unary_expr LE expr + | unary_expr NE expr + | unary_expr EQ expr + | unary_expr '>' expr + | unary_expr GE expr + | unary_expr '~' expr + | unary_expr NO_MATCH expr + | unary_expr In NAME + | unary_expr AND newline_opt expr + | unary_expr OR newline_opt expr + | unary_expr '?' expr ':' expr + | unary_input_function + ; +.sp + +non_unary_expr : '(' expr ')' + | '!' expr + | non_unary_expr '^' expr + | non_unary_expr '*' expr + | non_unary_expr '/' expr + | non_unary_expr '%' expr + | non_unary_expr '+' expr + | non_unary_expr '-' expr + | non_unary_expr non_unary_expr + | non_unary_expr '<' expr + | non_unary_expr LE expr + | non_unary_expr NE expr + | non_unary_expr EQ expr + | non_unary_expr '>' expr + | non_unary_expr GE expr + | non_unary_expr '~' expr + | non_unary_expr NO_MATCH expr + | non_unary_expr In NAME + | '(' multiple_expr_list ')' In NAME + | non_unary_expr AND newline_opt expr + | non_unary_expr OR newline_opt expr + | non_unary_expr '?' expr ':' expr + | NUMBER + | STRING + | lvalue + | ERE + | lvalue INCR + | lvalue DECR + | INCR lvalue + | DECR lvalue + | lvalue POW_ASSIGN expr + | lvalue MOD_ASSIGN expr + | lvalue MUL_ASSIGN expr + | lvalue DIV_ASSIGN expr + | lvalue ADD_ASSIGN expr + | lvalue SUB_ASSIGN expr + | lvalue '=' expr + | FUNC_NAME '(' expr_list_opt ')' + /* no white space allowed before '(' */ + | BUILTIN_FUNC_NAME '(' expr_list_opt ')' + | BUILTIN_FUNC_NAME + | non_unary_input_function + ; +.sp + +print_expr_list_opt : /* empty */ + | print_expr_list + ; +.sp + +print_expr_list : print_expr + | print_expr_list ',' newline_opt print_expr + ; +.sp + +print_expr : unary_print_expr + | non_unary_print_expr + ; +.sp + +unary_print_expr : '+' print_expr + | '-' print_expr + | unary_print_expr '^' print_expr + | unary_print_expr '*' print_expr + | unary_print_expr '/' print_expr + | unary_print_expr '%' print_expr + | unary_print_expr '+' print_expr + | unary_print_expr '-' print_expr + | unary_print_expr non_unary_print_expr + | unary_print_expr '~' print_expr + | unary_print_expr NO_MATCH print_expr + | unary_print_expr In NAME + | unary_print_expr AND newline_opt print_expr + | unary_print_expr OR newline_opt print_expr + | unary_print_expr '?' print_expr ':' print_expr + ; +.sp + +non_unary_print_expr : '(' expr ')' + | '!' print_expr + | non_unary_print_expr '^' print_expr + | non_unary_print_expr '*' print_expr + | non_unary_print_expr '/' print_expr + | non_unary_print_expr '%' print_expr + | non_unary_print_expr '+' print_expr + | non_unary_print_expr '-' print_expr + | non_unary_print_expr non_unary_print_expr + | non_unary_print_expr '~' print_expr + | non_unary_print_expr NO_MATCH print_expr + | non_unary_print_expr In NAME + | '(' multiple_expr_list ')' In NAME + | non_unary_print_expr AND newline_opt print_expr + | non_unary_print_expr OR newline_opt print_expr + | non_unary_print_expr '?' print_expr ':' print_expr + | NUMBER + | STRING + | lvalue + | ERE + | lvalue INCR + | lvalue DECR + | INCR lvalue + | DECR lvalue + | lvalue POW_ASSIGN print_expr + | lvalue MOD_ASSIGN print_expr + | lvalue MUL_ASSIGN print_expr + | lvalue DIV_ASSIGN print_expr + | lvalue ADD_ASSIGN print_expr + | lvalue SUB_ASSIGN print_expr + | lvalue '=' print_expr + | FUNC_NAME '(' expr_list_opt ')' + /* no white space allowed before '(' */ + | BUILTIN_FUNC_NAME '(' expr_list_opt ')' + | BUILTIN_FUNC_NAME + ; +.sp + +lvalue : NAME + | NAME '[' expr_list ']' + | '$' expr + ; +.sp + +non_unary_input_function : simple_get + | simple_get '<' expr + | non_unary_expr '|' simple_get + ; +.sp + +unary_input_function : unary_expr '|' simple_get + ; +.sp + +simple_get : GETLINE + | GETLINE lvalue + ; +.sp + +newline_opt : /* empty */ + | newline_opt NEWLINE + ; +\fP +.fi +.RE +.LP +This grammar has several ambiguities that shall be resolved as follows: +.IP " *" 3 +Operator precedence and associativity shall be as described in Expressions +in Decreasing Precedence in \fIawk\fP . +.LP +.IP " *" 3 +In case of ambiguity, an \fBelse\fP shall be associated with the most +immediately preceding \fBif\fP that would satisfy the +grammar. +.LP +.IP " *" 3 +In some contexts, a slash ( \fB'/'\fP ) that is used to surround an +ERE could also be the division operator. This shall be +resolved in such a way that wherever the division operator could appear, +a slash is assumed to be the division operator. (There is +no unary division operator.) +.LP +.LP +One convention that might not be obvious from the formal grammar is +where s are acceptable. There are several +obvious placements such as terminating a statement, and a backslash +can be used to escape s between any lexical +tokens. In addition, s without backslashes can follow a comma, +an open brace, logical AND operator ( +\fB"&&"\fP ), logical OR operator ( \fB"||"\fP ), the \fBdo\fP keyword, +the \fBelse\fP keyword, and the closing +parenthesis of an \fBif\fP, \fBfor\fP, or \fBwhile\fP statement. For +example: +.sp +.RS +.nf + +\fB{ print $1, + $2 } +\fP +.fi +.RE +.SS Lexical Conventions +.LP +The lexical conventions for \fIawk\fP programs, with respect to the +preceding grammar, shall be as follows: +.IP " 1." 4 +Except as noted, \fIawk\fP shall recognize the longest possible token +or delimiter beginning at a given point. +.LP +.IP " 2." 4 +A comment shall consist of any characters beginning with the number +sign character and terminated by, but excluding the next +occurrence of, a . Comments shall have no effect, except +to delimit lexical tokens. +.LP +.IP " 3." 4 +The shall be recognized as the token \fBNEWLINE\fP. +.LP +.IP " 4." 4 +A backslash character immediately followed by a shall have +no effect. +.LP +.IP " 5." 4 +The token \fBSTRING\fP shall represent a string constant. A string +constant shall begin with the character \fB' .'\fP Within +a string constant, a backslash character shall be considered to begin +an escape sequence as specified in the table in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 5, File Format +Notation ( +\fB'\\\\'\fP , \fB'\\a'\fP , \fB'\\b'\fP , \fB'\\f'\fP , \fB'\\n'\fP +, \fB'\\r'\fP , \fB'\\t'\fP , \fB'\\v'\fP ). In +addition, the escape sequences in Expressions in Decreasing Precedence +in \fIawk\fP shall be recognized. A shall not +occur within a string constant. A string constant shall be terminated +by the first unescaped occurrence of the character +\fB''\fP after the one that begins the string constant. The value +of the string shall be the sequence of all unescaped +characters and values of escape sequences between, but not including, +the two delimiting \fB''\fP characters. +.LP +.IP " 6." 4 +The token \fBERE\fP represents an extended regular expression constant. +An ERE constant shall begin with the slash character. +Within an ERE constant, a backslash character shall be considered +to begin an escape sequence as specified in the table in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 5, File Format +Notation. In +addition, the escape sequences in Expressions in Decreasing Precedence +in \fIawk\fP shall be recognized. The application shall +ensure that a does not occur within an ERE constant. An +ERE constant shall be terminated by the first unescaped +occurrence of the slash character after the one that begins the ERE +constant. The extended regular expression represented by the +ERE constant shall be the sequence of all unescaped characters and +values of escape sequences between, but not including, the two +delimiting slash characters. +.LP +.IP " 7." 4 +A shall have no effect, except to delimit lexical tokens or +within \fBSTRING\fP or \fBERE\fP tokens. +.LP +.IP " 8." 4 +The token \fBNUMBER\fP shall represent a numeric constant. Its form +and numeric value shall be equivalent to either of the +tokens \fBfloating-constant\fP or \fBinteger-constant\fP as specified +by the ISO\ C standard, with the following +exceptions: +.RS +.IP " a." 4 +An integer constant cannot begin with 0x or include the hexadecimal +digits \fB'a'\fP , \fB'b'\fP , \fB'c'\fP , +\fB'd'\fP , \fB'e'\fP , \fB'f'\fP , \fB'A'\fP , \fB'B'\fP , \fB'C'\fP +, \fB'D'\fP , \fB'E'\fP , or +\fB'F'\fP . +.LP +.IP " b." 4 +The value of an integer constant beginning with 0 shall be taken in +decimal rather than octal. +.LP +.IP " c." 4 +An integer constant cannot include a suffix ( \fB'u'\fP , \fB'U'\fP +, \fB'l'\fP , or \fB'L'\fP ). +.LP +.IP " d." 4 +A floating constant cannot include a suffix ( \fB'f'\fP , \fB'F'\fP +, \fB'l'\fP , or \fB'L'\fP ). +.LP +.RE +.LP +If the value is too large or too small to be representable (see \fIConcepts +Derived from +the ISO C Standard\fP ), the behavior is undefined. +.LP +.IP " 9." 4 +A sequence of underscores, digits, and alphabetics from the portable +character set (see the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 6.1, Portable Character Set), beginning +with an underscore or alphabetic, shall be considered a word. +.LP +.IP "10." 4 +The following words are keywords that shall be recognized as individual +tokens; the name of the token is the same as the +keyword: +.TS C +center; lw(13) lw(13) lw(13) lw(13) lw(13) lw(13). +T{ +\fB +.br +BEGIN +.br +break +.br +continue +.br +\fP +T} T{ +\fB +.br +delete +.br +do +.br +else +.br +\fP +T} T{ +\fB +.br +END +.br +exit +.br +for +.br +\fP +T} T{ +\fB +.br +function +.br +getline +.br +if +.br +\fP +T} T{ +\fB +.br +in +.br +next +.br +print +.br +\fP +T} T{ +\fB +.br +printf +.br +return +.br +while +.br +\fP +T} +.TE +.LP +.IP "11." 4 +The following words are names of built-in functions and shall be recognized +as the token \fBBUILTIN_FUNC_NAME\fP: +.TS C +center; lw(13) lw(13) lw(13) lw(13) lw(13) lw(13). +T{ +\fB +.br +atan2 +.br +close +.br +cos +.br +exp +.br +\fP +T} T{ +\fB +.br +gsub +.br +index +.br +int +.br +length +.br +\fP +T} T{ +\fB +.br +log +.br +match +.br +rand +.br +sin +.br +\fP +T} T{ +\fB +.br +split +.br +sprintf +.br +sqrt +.br +srand +.br +\fP +T} T{ +\fB +.br +sub +.br +substr +.br +system +.br +tolower +.br +\fP +T} T{ +\fB +.br +toupper +.br +\fP +T} +.TE +.LP +The above-listed keywords and names of built-in functions are considered +reserved words. +.LP +.IP "12." 4 +The token \fBNAME\fP shall consist of a word that is not a keyword +or a name of a built-in function and is not followed +immediately (without any delimiters) by the \fB'('\fP character. +.LP +.IP "13." 4 +The token \fBFUNC_NAME\fP shall consist of a word that is not a keyword +or a name of a built-in function, followed immediately +(without any delimiters) by the \fB'('\fP character. The \fB'('\fP +character shall not be included as part of the token. +.LP +.IP "14." 4 +The following two-character sequences shall be recognized as the named +tokens: +.TS C +center; l l l l. +\fBToken Name\fP \fBSequence\fP \fBToken Name\fP \fBSequence\fP +\fBADD_ASSIGN\fP += \fBNO_MATCH\fP !~ +\fBSUB_ASSIGN\fP -= \fBEQ\fP == +\fBMUL_ASSIGN\fP *= \fBLE\fP <= +\fBDIV_ASSIGN\fP /= \fBGE\fP >= +\fBMOD_ASSIGN\fP %= \fBNE\fP != +\fBPOW_ASSIGN\fP ^= \fBINCR\fP ++ +\fBOR\fP || \fBDECR\fP -- +\fBAND\fP && \fBAPPEND\fP >> +.TE +.LP +.IP "15." 4 +The following single characters shall be recognized as tokens whose +names are the character: +.sp +.RS +.nf + +\fB { } ( ) [ ] , ; + - * % ^ ! > < | ? : ~ $ = +\fP +.fi +.RE +.LP +.LP +There is a lexical ambiguity between the token \fBERE\fP and the tokens +\fB'/'\fP and \fBDIV_ASSIGN\fP. When an input +sequence begins with a slash character in any syntactic context where +the token \fB'/'\fP or \fBDIV_ASSIGN\fP could appear as +the next token in a valid program, the longer of those two tokens +that can be recognized shall be recognized. In any other +syntactic context where the token \fBERE\fP could appear as the next +token in a valid program, the token \fBERE\fP shall be +recognized. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All input files were processed successfully. +.TP 7 +>0 +An error occurred. +.sp +.LP +The exit status can be altered within the program by using an \fBexit\fP +expression. +.SH CONSEQUENCES OF ERRORS +.LP +If any \fIfile\fP operand is specified and the named file cannot be +accessed, \fIawk\fP shall write a diagnostic message to +standard error and terminate without any further action. +.LP +If the program specified by either the \fIprogram\fP operand or a +\fIprogfile\fP operand is not a valid \fIawk\fP program (as +specified in the EXTENDED DESCRIPTION section), the behavior is undefined. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fBindex\fP, \fBlength\fP, \fBmatch\fP, and \fBsubstr\fP functions +should not be confused with similar functions in the +ISO\ C standard; the \fIawk\fP versions deal with characters, while +the ISO\ C standard deals with bytes. +.LP +Because the concatenation operation is represented by adjacent expressions +rather than an explicit operator, it is often +necessary to use parentheses to enforce the proper evaluation precedence. +.SH EXAMPLES +.LP +The \fIawk\fP program specified in the command line is most easily +specified within single-quotes (for example, +'\fIprogram\fP') for applications using \fIsh\fP, because \fIawk\fP +programs commonly contain +characters that are special to the shell, including double-quotes. +In the cases where an \fIawk\fP program contains single-quote +characters, it is usually easiest to specify most of the program as +strings within single-quotes concatenated by the shell with +quoted single-quote characters. For example: +.sp +.RS +.nf + +\fBawk '/'\\''/ { print "quote:", $0 }' +\fP +.fi +.RE +.LP +prints all lines from the standard input containing a single-quote +character, prefixed with \fIquote\fP:. +.LP +The following are examples of simple \fIawk\fP programs: +.IP " 1." 4 +Write to the standard output all input lines for which field 3 is +greater than 5: +.sp +.RS +.nf + +\fB$3 > 5 +\fP +.fi +.RE +.LP +.IP " 2." 4 +Write every tenth line: +.sp +.RS +.nf + +\fB(NR % 10) == 0 +\fP +.fi +.RE +.LP +.IP " 3." 4 +Write any line with a substring matching the regular expression: +.sp +.RS +.nf + +\fB/(G|D)(2[0-9][[:alpha:]]*)/ +\fP +.fi +.RE +.LP +.IP " 4." 4 +Print any line with a substring containing a \fB'G'\fP or \fB'D'\fP +, followed by a sequence of digits and characters. +This example uses character classes \fBdigit\fP and \fBalpha\fP to +match language-independent digit and alphabetic characters +respectively: +.sp +.RS +.nf + +\fB/(G|D)([[:digit:][:alpha:]]*)/ +\fP +.fi +.RE +.LP +.IP " 5." 4 +Write any line in which the second field matches the regular expression +and the fourth field does not: +.sp +.RS +.nf + +\fB$2 ~ /xyz/ && $4 !~ /xyz/ +\fP +.fi +.RE +.LP +.IP " 6." 4 +Write any line in which the second field contains a backslash: +.sp +.RS +.nf + +\fB$2 ~ /\\\\/ +\fP +.fi +.RE +.LP +.IP " 7." 4 +Write any line in which the second field contains a backslash. Note +that backslash escapes are interpreted twice; once in +lexical processing of the string and once in processing the regular +expression: +.sp +.RS +.nf + +\fB$2 ~ "\\\\\\\\" +\fP +.fi +.RE +.LP +.IP " 8." 4 +Write the second to the last and the last field in each line. Separate +the fields by a colon: +.sp +.RS +.nf + +\fB{OFS=":";print $(NF-1), $NF} +\fP +.fi +.RE +.LP +.IP " 9." 4 +Write the line number and number of fields in each line. The three +strings representing the line number, the colon, and the +number of fields are concatenated and that string is written to standard +output: +.sp +.RS +.nf + +\fB{print NR ":" NF} +\fP +.fi +.RE +.LP +.IP "10." 4 +Write lines longer than 72 characters: +.sp +.RS +.nf + +\fBlength($0) > 72 +\fP +.fi +.RE +.LP +.IP "11." 4 +Write the first two fields in opposite order separated by \fBOFS\fP: +.sp +.RS +.nf + +\fB{ print $2, $1 } +\fP +.fi +.RE +.LP +.IP "12." 4 +Same, with input fields separated by a comma or s and s, +or both: +.sp +.RS +.nf + +\fBBEGIN { FS = ",[ \\t]*|[ \\t]+" } + { print $2, $1 } +\fP +.fi +.RE +.LP +.IP "13." 4 +Add up the first column, print sum, and average: +.sp +.RS +.nf + +\fB {s += $1 } +END {print "sum is ", s, " average is", s/NR} +\fP +.fi +.RE +.LP +.IP "14." 4 +Write fields in reverse order, one per line (many lines out for each +line in): +.sp +.RS +.nf + +\fB{ for (i = NF; i > 0; --i) print $i } +\fP +.fi +.RE +.LP +.IP "15." 4 +Write all lines between occurrences of the strings \fBstart\fP and +\fBstop\fP: +.sp +.RS +.nf + +\fB/start/, /stop/ +\fP +.fi +.RE +.LP +.IP "16." 4 +Write all lines whose first field is different from the previous one: +.sp +.RS +.nf + +\fB$1 != prev { print; prev = $1 } +\fP +.fi +.RE +.LP +.IP "17." 4 +Simulate \fIecho\fP: +.sp +.RS +.nf + +\fBBEGIN { + for (i = 1; i < ARGC; ++i) + printf("%s%s", ARGV[i], i==ARGC-1?"\\n":" ") +} +\fP +.fi +.RE +.LP +.IP "18." 4 +Write the path prefixes contained in the \fIPATH\fP environment variable, +one per line: +.sp +.RS +.nf + +\fBBEGIN { + n = split (ENVIRON["PATH"], path, ":") + for (i = 1; i <= n; ++i) + print path[i] +} +\fP +.fi +.RE +.LP +.IP "19." 4 +If there is a file named \fBinput\fP containing page headers of the +form: +.sp +.RS +.nf + +Page # +.fi +.RE +.LP +and a file named \fBprogram\fP that contains: +.sp +.RS +.nf + +\fB/Page/ { $2 = n++; } + { print } +\fP +.fi +.RE +.LP +then the command line: +.sp +.RS +.nf + +\fBawk -f program n=5 input +\fP +.fi +.RE +.LP +prints the file \fBinput\fP, filling in page numbers starting at 5. +.LP +.SH RATIONALE +.LP +This description is based on the new \fIawk\fP, "nawk", (see the referenced +\fIThe AWK Programming Language\fP), which +introduced a number of new features to the historical \fIawk\fP: +.IP " 1." 4 +New keywords: \fBdelete\fP, \fBdo\fP, \fBfunction\fP, \fBreturn\fP +.LP +.IP " 2." 4 +New built-in functions: \fBatan2\fP, \fBclose\fP, \fBcos\fP, \fBgsub\fP, +\fBmatch\fP, \fBrand\fP, \fBsin\fP, +\fBsrand\fP, \fBsub\fP, \fBsystem\fP +.LP +.IP " 3." 4 +New predefined variables: \fBFNR\fP, \fBARGC\fP, \fBARGV\fP, \fBRSTART\fP, +\fBRLENGTH\fP, \fBSUBSEP\fP +.LP +.IP " 4." 4 +New expression operators: \fB?\fP, \fB:\fP, \fB,\fP, \fB^\fP +.LP +.IP " 5." 4 +The \fBFS\fP variable and the third argument to \fBsplit\fP, now treated +as extended regular expressions. +.LP +.IP " 6." 4 +The operator precedence, changed to more closely match the C language. +Two examples of code that operate differently are: +.sp +.RS +.nf + +\fBwhile ( n /= 10 > 1) ... +if (!"wk" ~ /bwk/) ... +\fP +.fi +.RE +.LP +.LP +Several features have been added based on newer implementations of +\fIawk\fP: +.IP " *" 3 +Multiple instances of \fB-f\fP \fIprogfile\fP are permitted. +.LP +.IP " *" 3 +The new option \fB-v\fP \fIassignment.\fP +.LP +.IP " *" 3 +The new predefined variable \fBENVIRON\fP. +.LP +.IP " *" 3 +New built-in functions \fBtoupper\fP and \fBtolower\fP. +.LP +.IP " *" 3 +More formatting capabilities are added to \fBprintf\fP to match the +ISO\ C standard. +.LP +.LP +The overall \fIawk\fP syntax has always been based on the C language, +with a few features from the shell command language and +other sources. Because of this, it is not completely compatible with +any other language, which has caused confusion for some users. +It is not the intent of the standard developers to address such issues. +A few relatively minor changes toward making the language +more compatible with the ISO\ C standard were made; most of these +changes are based on similar changes in recent +implementations, as described above. There remain several C-language +conventions that are not in \fIawk\fP. One of the notable +ones is the comma operator, which is commonly used to specify multiple +expressions in the C language \fBfor\fP statement. Also, +there are various places where \fIawk\fP is more restrictive than +the C language regarding the type of expression that can be used +in a given context. These limitations are due to the different features +that the \fIawk\fP language does provide. +.LP +Regular expressions in \fIawk\fP have been extended somewhat from +historical implementations to make them a pure superset of +extended regular expressions, as defined by IEEE\ Std\ 1003.1-2001 +(see the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 9.4, Extended Regular Expressions). +The +main extensions are internationalization features and interval expressions. +Historical implementations of \fIawk\fP have long +supported backslash escape sequences as an extension to extended regular +expressions, and this extension has been retained despite +inconsistency with other utilities. The number of escape sequences +recognized in both extended regular expressions and strings has +varied (generally increasing with time) among implementations. The +set specified by IEEE\ Std\ 1003.1-2001 includes most +sequences known to be supported by popular implementations and by +the ISO\ C standard. One sequence that is not supported is +hexadecimal value escapes beginning with \fB'\\x'\fP . This would +allow values expressed in more than 9 bits to be used within +\fIawk\fP as in the ISO\ C standard. However, because this syntax +has a non-deterministic length, it does not permit the +subsequent character to be a hexadecimal digit. This limitation can +be dealt with in the C language by the use of lexical string +concatenation. In the \fIawk\fP language, concatenation could also +be a solution for strings, but not for extended regular +expressions (either lexical ERE tokens or strings used dynamically +as regular expressions). Because of this limitation, the feature +has not been added to IEEE\ Std\ 1003.1-2001. +.LP +When a string variable is used in a context where an extended regular +expression normally appears (where the lexical token ERE +is used in the grammar) the string does not contain the literal slashes. +.LP +Some versions of \fIawk\fP allow the form: +.sp +.RS +.nf + +\fBfunc name(args, ... ) { statements } +\fP +.fi +.RE +.LP +This has been deprecated by the authors of the language, who asked +that it not be specified. +.LP +Historical implementations of \fIawk\fP produce an error if a \fBnext\fP +statement is executed in a \fBBEGIN\fP action, and +cause \fIawk\fP to terminate if a \fBnext\fP statement is executed +in an \fBEND\fP action. This behavior has not been +documented, and it was not believed that it was necessary to standardize +it. +.LP +The specification of conversions between string and numeric values +is much more detailed than in the documentation of historical +implementations or in the referenced \fIThe AWK Programming Language\fP. +Although most of the behavior is designed to be +intuitive, the details are necessary to ensure compatible behavior +from different implementations. This is especially important in +relational expressions since the types of the operands determine whether +a string or numeric comparison is performed. From the +perspective of an application writer, it is usually sufficient to +expect intuitive behavior and to force conversions (by adding +zero or concatenating a null string) when the type of an expression +does not obviously match what is needed. The intent has been to +specify historical practice in almost all cases. The one exception +is that, in historical implementations, variables and constants +maintain both string and numeric values after their original value +is converted by any use. This means that referencing a variable +or constant can have unexpected side effects. For example, with historical +implementations the following program: +.sp +.RS +.nf + +\fB{ + a = "+2" + b = 2 + if (NR % 2) + c = a + b + if (a == b) + print "numeric comparison" + else + print "string comparison" +} +\fP +.fi +.RE +.LP +would perform a numeric comparison (and output numeric comparison) +for each odd-numbered line, but perform a string comparison +(and output string comparison) for each even-numbered line. IEEE\ Std\ 1003.1-2001 +ensures that comparisons will be numeric +if necessary. With historical implementations, the following program: +.sp +.RS +.nf + +\fBBEGIN { + OFMT = "%e" + print 3.14 + OFMT = "%f" + print 3.14 +} +\fP +.fi +.RE +.LP +would output \fB"3.140000e+00"\fP twice, because in the second \fBprint\fP +statement the constant \fB"3.14"\fP would have +a string value from the previous conversion. IEEE\ Std\ 1003.1-2001 +requires that the output of the second \fBprint\fP +statement be \fB"3.140000"\fP . The behavior of historical implementations +was seen as too unintuitive and unpredictable. +.LP +It was pointed out that with the rules contained in early drafts, +the following script would print nothing: +.sp +.RS +.nf + +\fBBEGIN { + y[1.5] = 1 + OFMT = "%e" + print y[1.5] +} +\fP +.fi +.RE +.LP +Therefore, a new variable, \fBCONVFMT\fP, was introduced. The \fBOFMT\fP +variable is now restricted to affecting output +conversions of numbers to strings and \fBCONVFMT\fP is used for internal +conversions, such as comparisons or array indexing. The +default value is the same as that for \fBOFMT\fP, so unless a program +changes \fBCONVFMT\fP (which no historical program would +do), it will receive the historical behavior associated with internal +string conversions. +.LP +The POSIX \fIawk\fP lexical and syntactic conventions are specified +more formally than in other sources. Again the intent has +been to specify historical practice. One convention that may not be +obvious from the formal grammar as in other verbal descriptions +is where s are acceptable. There are several obvious placements +such as terminating a statement, and a backslash can +be used to escape s between any lexical tokens. In addition, +s without backslashes can follow a +comma, an open brace, a logical AND operator ( \fB"&&"\fP ), a logical +OR operator ( \fB"||"\fP ), the \fBdo\fP +keyword, the \fBelse\fP keyword, and the closing parenthesis of an +\fBif\fP, \fBfor\fP, or \fBwhile\fP statement. For +example: +.sp +.RS +.nf + +\fB{ print $1, + $2 } +\fP +.fi +.RE +.LP +The requirement that \fIawk\fP add a trailing to the program +argument text is to simplify the grammar, making +it match a text file in form. There is no way for an application or +test suite to determine whether a literal is +added or whether \fIawk\fP simply acts as if it did. +.LP +IEEE\ Std\ 1003.1-2001 requires several changes from historical implementations +in order to support +internationalization. Probably the most subtle of these is the use +of the decimal-point character, defined by the \fILC_NUMERIC\fP +category of the locale, in representations of floating-point numbers. +This locale-specific character is used in recognizing numeric +input, in converting between strings and numeric values, and in formatting +output. However, regardless of locale, the period +character (the decimal-point character of the POSIX locale) is the +decimal-point character recognized in processing \fIawk\fP +programs (including assignments in command line arguments). This is +essentially the same convention as the one used in the +ISO\ C standard. The difference is that the C language includes the +\fIsetlocale\fP() function, which permits an application to modify +its locale. Because of this +capability, a C application begins executing with its locale set to +the C locale, and only executes in the environment-specified +locale after an explicit call to \fIsetlocale\fP(). However, adding +such an elaborate +new feature to the \fIawk\fP language was seen as inappropriate for +IEEE\ Std\ 1003.1-2001. It is possible to execute an +\fIawk\fP program explicitly in any desired locale by setting the +environment in the shell. +.LP +The undefined behavior resulting from NULs in extended regular expressions +allows future extensions for the GNU \fIgawk\fP +program to process binary data. +.LP +The behavior in the case of invalid \fIawk\fP programs (including +lexical, syntactic, and semantic errors) is undefined because +it was considered overly limiting on implementations to specify. In +most cases such errors can be expected to produce a diagnostic +and a non-zero exit status. However, some implementations may choose +to extend the language in ways that make use of certain +invalid constructs. Other invalid constructs might be deemed worthy +of a warning, but otherwise cause some reasonable behavior. +Still other constructs may be very difficult to detect in some implementations. +Also, different implementations might detect a +given error during an initial parsing of the program (before reading +any input files) while others might detect it when executing +the program after reading some input. Implementors should be aware +that diagnosing errors as early as possible and producing useful +diagnostics can ease debugging of applications, and thus make an implementation +more usable. +.LP +The unspecified behavior from using multi-character \fBRS\fP values +is to allow possible future extensions based on extended +regular expressions used for record separators. Historical implementations +take the first character of the string and ignore the +others. +.LP +Unspecified behavior when \fIsplit\fP( \fIstring\fP, \fIarray\fP, +) is used +is to allow a proposed future extension that would split up a string +into an array of individual characters. +.LP +In the context of the \fBgetline\fP function, equally good arguments +for different precedences of the \fB|\fP and \fB<\fP +operators can be made. Historical practice has been that: +.sp +.RS +.nf + +\fBgetline < "a" "b" +\fP +.fi +.RE +.LP +is parsed as: +.sp +.RS +.nf + +\fB( getline < "a" ) "b" +\fP +.fi +.RE +.LP +although many would argue that the intent was that the file \fBab\fP +should be read. However: +.sp +.RS +.nf + +\fBgetline < "x" + 1 +\fP +.fi +.RE +.LP +parses as: +.sp +.RS +.nf + +\fBgetline < ( "x" + 1 ) +\fP +.fi +.RE +.LP +Similar problems occur with the \fB|\fP version of \fBgetline\fP, +particularly in combination with \fB$\fP. For example: +.sp +.RS +.nf + +\fB$"echo hi" | getline +\fP +.fi +.RE +.LP +(This situation is particularly problematic when used in a \fBprint\fP +statement, where the \fB|getline\fP part might be a +redirection of the \fBprint\fP.) +.LP +Since in most cases such constructs are not (or at least should not) +be used (because they have a natural ambiguity for which +there is no conventional parsing), the meaning of these constructs +has been made explicitly unspecified. (The effect is that a +conforming application that runs into the problem must parenthesize +to resolve the ambiguity.) There appeared to be few if any +actual uses of such constructs. +.LP +Grammars can be written that would cause an error under these circumstances. +Where backwards-compatibility is not a large +consideration, implementors may wish to use such grammars. +.LP +Some historical implementations have allowed some built-in functions +to be called without an argument list, the result being a +default argument list chosen in some "reasonable" way. Use of \fBlength\fP +as a synonym for \fBlength($0)\fP is the only one of +these forms that is thought to be widely known or widely used; this +particular form is documented in various places (for example, +most historical \fIawk\fP reference pages, although not in the referenced +\fIThe AWK Programming Language\fP) as legitimate +practice. With this exception, default argument lists have always +been undocumented and vaguely defined, and it is not at all clear +how (or if) they should be generalized to user-defined functions. +They add no useful functionality and preclude possible future +extensions that might need to name functions without calling them. +Not standardizing them seems the simplest course. The standard +developers considered that \fBlength\fP merited special treatment, +however, since it has been documented in the past and sees +possibly substantial use in historical programs. Accordingly, this +usage has been made legitimate, but Issue\ 5 removed the +obsolescent marking for XSI-conforming implementations and many otherwise +conforming applications depend on this feature. +.LP +In \fBsub\fP and \fBgsub\fP, if \fIrepl\fP is a string literal (the +lexical token \fBSTRING\fP), then two consecutive +backslash characters should be used in the string to ensure a single +backslash will precede the ampersand when the resultant string +is passed to the function. (For example, to specify one literal ampersand +in the replacement string, use \fBgsub\fP( \fBERE\fP, +\fB"\\\\&"\fP ).) +.LP +Historically the only special character in the \fIrepl\fP argument +of \fBsub\fP and \fBgsub\fP string functions was the +ampersand ( \fB'&'\fP ) character and preceding it with the backslash +character was used to turn off its special +meaning. +.LP +The description in the ISO\ POSIX-2:1993 standard introduced behavior +such that the backslash character was another special +character and it was unspecified whether there were any other special +characters. This description introduced several portability +problems, some of which are described below, and so it has been replaced +with the more historical description. Some of the problems +include: +.IP " *" 3 +Historically, to create the replacement string, a script could use +\fBgsub\fP( \fBERE\fP, \fB"\\\\&"\fP ), but with the +ISO\ POSIX-2:1993 standard wording, it was necessary to use \fBgsub\fP( +\fBERE\fP, \fB"\\\\\\\\&"\fP ). Backslash +characters are doubled here because all string literals are subject +to lexical analysis, which would reduce each pair of backslash +characters to a single backslash before being passed to \fBgsub\fP. +.LP +.IP " *" 3 +Since it was unspecified what the special characters were, for portable +scripts to guarantee that characters are printed +literally, each character had to be preceded with a backslash. (For +example, a portable script had to use \fBgsub\fP( \fBERE\fP, +\fB"\\\\h\\\\i"\fP ) to produce a replacement string of \fB"hi"\fP +\&.) +.LP +.LP +The description for comparisons in the ISO\ POSIX-2:1993 standard +did not properly describe historical practice because of +the way numeric strings are compared as numbers. The current rules +cause the following code: +.sp +.RS +.nf + +\fBif (0 == "000") + print "strange, but true" +else + print "not true" +\fP +.fi +.RE +.LP +to do a numeric comparison, causing the \fBif\fP to succeed. It should +be intuitively obvious that this is incorrect behavior, +and indeed, no historical implementation of \fIawk\fP actually behaves +this way. +.LP +To fix this problem, the definition of \fInumeric string\fP was enhanced +to include only those values obtained from specific +circumstances (mostly external sources) where it is not possible to +determine unambiguously whether the value is intended to be a +string or a numeric. +.LP +Variables that are assigned to a numeric string shall also be treated +as a numeric string. (For example, the notion of a numeric +string can be propagated across assignments.) In comparisons, all +variables having the uninitialized value are to be treated as a +numeric operand evaluating to the numeric value zero. +.LP +Uninitialized variables include all types of variables including scalars, +array elements, and fields. The definition of an +uninitialized value in Variables and Special Variables is necessary +to describe the value placed on +uninitialized variables and on fields that are valid (for example, +\fB<\fP \fB$NF\fP) but have no characters in them and to +describe how these variables are to be used in comparisons. A valid +field, such as \fB$1\fP, that has no characters in it can be +obtained from an input line of \fB"\\t\\t"\fP when \fBFS=\fP \fB'\\t'\fP +\&. Historically, the comparison ( \fB$1<\fP10) was +done numerically after evaluating \fB$1\fP to the value zero. +.LP +The phrase "... also shall have the numeric value of the numeric string" +was removed from several sections of the +ISO\ POSIX-2:1993 standard because is specifies an unnecessary implementation +detail. It is not necessary for +IEEE\ Std\ 1003.1-2001 to specify that these objects be assigned two +different values. It is only necessary to specify that +these objects may evaluate to two different values depending on context. +.LP +The description of numeric string processing is based on the behavior +of the \fIatof\fP() +function in the ISO\ C standard. While it is not a requirement for +an implementation to use this function, many historical +implementations of \fIawk\fP do. In the ISO\ C standard, floating-point +constants use a period as a decimal point character +for the language itself, independent of the current locale, but the +\fIatof\fP() function and +the associated \fIstrtod\fP() function use the decimal point character +of the current +locale when converting strings to numeric values. Similarly in \fIawk\fP, +floating-point constants in an \fIawk\fP script use a +period independent of the locale, but input strings use the decimal +point character of the locale. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIGrammar Conventions\fP , \fIgrep\fP , \fIlex\fP , \fIsed\fP , the +System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIatof\fP(), +\fIexec\fP, \fIpopen\fP(), \fIsetlocale\fP(), \fIstrtod\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/basename.1p b/man1p/basename.1p new file mode 100644 index 000000000..f8956e4e3 --- /dev/null +++ b/man1p/basename.1p @@ -0,0 +1,239 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "BASENAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" basename +.SH NAME +basename \- return non-directory portion of a pathname +.SH SYNOPSIS +.LP +\fBbasename\fP \fIstring\fP \fB[\fP\fIsuffix\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIstring\fP operand shall be treated as a pathname, as defined +in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 3.266, Pathname. The string +\fIstring\fP shall be converted to the filename corresponding to the +last pathname component in \fIstring\fP and then the suffix +string \fIsuffix\fP, if present, shall be removed. This shall be done +by performing actions equivalent to the following steps in +order: +.IP " 1." 4 +If \fIstring\fP is a null string, it is unspecified whether the resulting +string is \fB'.'\fP or a null string. In either +case, skip steps 2 through 6. +.LP +.IP " 2." 4 +If \fIstring\fP is \fB"//"\fP , it is implementation-defined whether +steps 3 to 6 are skipped or processed. +.LP +.IP " 3." 4 +If \fIstring\fP consists entirely of slash characters, \fIstring\fP +shall be set to a single slash character. In this case, +skip steps 4 to 6. +.LP +.IP " 4." 4 +If there are any trailing slash characters in \fIstring\fP, they shall +be removed. +.LP +.IP " 5." 4 +If there are any slash characters remaining in \fIstring\fP, the prefix +of \fIstring\fP up to and including the last slash +character in \fIstring\fP shall be removed. +.LP +.IP " 6." 4 +If the \fIsuffix\fP operand is present, is not identical to the characters +remaining in \fIstring\fP, and is identical to a +suffix of the characters remaining in \fIstring\fP, the suffix \fIsuffix\fP +shall be removed from \fIstring\fP. Otherwise, +\fIstring\fP is not modified by this step. It shall not be considered +an error if \fIsuffix\fP is not found in \fIstring\fP. +.LP +.LP +The resulting string shall be written to standard output. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIstring\fP +A string. +.TP 7 +\fIsuffix\fP +A string. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIbasename\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fIbasename\fP utility shall write a line to the standard output +in the following format: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIresulting string\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The definition of \fIpathname\fP specifies implementation-defined +behavior for pathnames starting with two slash characters. +Therefore, applications shall not arbitrarily add slashes to the beginning +of a pathname unless they can ensure that there are more +or less than two or are prepared to deal with the implementation-defined +consequences. +.SH EXAMPLES +.LP +If the string \fIstring\fP is a valid pathname: +.sp +.RS +.nf + +\fB$(basename "\fP\fIstring\fP\fB") +\fP +.fi +.RE +.LP +produces a filename that could be used to open the file named by \fIstring\fP +in the directory returned by: +.sp +.RS +.nf + +\fB$(dirname "\fP\fIstring\fP\fB") +\fP +.fi +.RE +.LP +If the string \fIstring\fP is not a valid pathname, the same algorithm +is used, but the result need not be a valid filename. +The \fIbasename\fP utility is not expected to make any judgements +about the validity of \fIstring\fP as a pathname; it just +follows the specified algorithm to produce a result string. +.LP +The following shell script compiles \fB/usr/src/cmd/cat.c\fP and moves +the output to a file named \fBcat\fP in the current +directory when invoked with the argument \fB/usr/src/cmd/cat\fP or +with the argument \fB/usr/src/cmd/cat.c\fP: +.sp +.RS +.nf + +\fBc99 $(dirname "$1")/$(basename "$1" .c).c +mv a.out $(basename "$1" .c) +\fP +.fi +.RE +.SH RATIONALE +.LP +The behaviors of \fIbasename\fP and \fIdirname\fP have been coordinated +so that when +\fIstring\fP is a valid pathname: +.sp +.RS +.nf + +\fB$(basename "\fP\fIstring\fP\fB") +\fP +.fi +.RE +.LP +would be a valid filename for the file in the directory: +.sp +.RS +.nf + +\fB$(dirname "\fP\fIstring\fP\fB") +\fP +.fi +.RE +.LP +This would not work for the early proposal versions of these utilities +due to the way it specified handling of trailing +slashes. +.LP +Since the definition of \fIpathname\fP specifies implementation-defined +behavior for pathnames starting with two slash +characters, this volume of IEEE\ Std\ 1003.1-2001 specifies similar +implementation-defined behavior for the \fIbasename\fP +and \fIdirname\fP utilities. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIParameters and Variables\fP , \fIdirname\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/batch.1p b/man1p/batch.1p new file mode 100644 index 000000000..c8c984520 --- /dev/null +++ b/man1p/batch.1p @@ -0,0 +1,238 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "BATCH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" batch +.SH NAME +batch \- schedule commands to be executed in a batch queue +.SH SYNOPSIS +.LP +\fB\fP \fIbatch\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIbatch\fP utility shall read commands from standard input and +schedule them for execution in a batch queue. It shall be +the equivalent of the command: +.sp +.RS +.nf + +\fBat -q b -m now +\fP +.fi +.RE +.LP +where queue \fIb\fP is a special \fIat\fP queue, specifically for +batch jobs. Batch jobs +shall be submitted to the batch queue with no time constraints and +shall be run by the system using algorithms, based on +unspecified factors, that may vary with each invocation of \fIbatch\fP. +.LP +Users shall be permitted to use \fIbatch\fP if their name appears +in the file \fB/usr/lib/cron/at.allow\fP. If that file does not +exist, the file \fB/usr/lib/cron/at.deny\fP shall be checked to determine +whether the user shall be denied access to \fIbatch\fP. +If neither file exists, only a process with the appropriate privileges +shall be allowed to submit a job. If only \fBat.deny\fP +exists and is empty, global usage shall be permitted. The \fBat.allow\fP +and \fBat.deny\fP files shall consist of one user name +per line. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +None. +.SH STDIN +.LP +The standard input shall be a text file consisting of commands acceptable +to the shell command language described in \fIShell Command Language\fP +\&. +.SH INPUT FILES +.LP +The text files \fB/usr/lib/cron/at.allow\fP and \fB/usr/lib/cron/at.deny\fP +shall contain zero or more user names, one per line, +of users who are, respectively, authorized or denied access to the +\fIat\fP and \fIbatch\fP +utilities. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIbatch\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fILC_TIME\fP +Determine the format and contents for date and time strings written +by \fIbatch\fP. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fISHELL\fP +Determine the name of a command interpreter to be used to invoke the +at-job. If the variable is unset or null, \fIsh\fP shall be used. +If it is set to a value other than a name for \fIsh\fP, the implementation +shall do one of the following: use that shell; use \fIsh\fP; use the +login shell from the user database; any of the preceding accompanied +by a warning +diagnostic about which was chosen. +.TP 7 +\fITZ\fP +Determine the timezone. The job shall be submitted for execution at +the time specified by \fItimespec\fP or \fB-t\fP +\fItime\fP relative to the timezone specified by the \fITZ\fP variable. +If \fItimespec\fP specifies a timezone, it overrides +\fITZ .\fP If \fItimespec\fP does not specify a timezone and \fITZ\fP +is unset or null, an unspecified default timezone shall be +used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +When standard input is a terminal, prompts of unspecified format for +each line of the user input described in the STDIN section +may be written to standard output. +.SH STDERR +.LP +The following shall be written to standard error when a job has been +successfully submitted: +.sp +.RS +.nf + +\fB"job %s at %s\\n",\fP \fIat_job_id\fP\fB, <\fP\fIdate\fP\fB> +\fP +.fi +.RE +.LP +where \fIdate\fP shall be equivalent in format to the output of: +.sp +.RS +.nf + +\fBdate +"%a %b %e %T %Y" +\fP +.fi +.RE +.LP +The date and time written shall be adjusted so that they appear in +the timezone of the user (as determined by the \fITZ\fP +variable). +.LP +Neither this, nor warning messages concerning the selection of the +command interpreter, are considered a diagnostic that changes +the exit status. +.LP +Diagnostic messages, if any, shall be written to standard error. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +The job shall not be scheduled. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +It may be useful to redirect standard output within the specified +commands. +.SH EXAMPLES +.IP " 1." 4 +This sequence can be used at a terminal: +.sp +.RS +.nf + +\fBbatch +sort < file >outfile +EOT +\fP +.fi +.RE +.LP +.IP " 2." 4 +This sequence, which demonstrates redirecting standard error to a +pipe, is useful in a command procedure (the sequence of output +redirection specifications is significant): +.sp +.RS +.nf + +\fBbatch << +! diff file1 file2 2>&1 >outfile | mailx mygroup +! +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +Early proposals described \fIbatch\fP in a manner totally separated +from \fIat\fP, even +though the historical model treated it almost as a synonym for \fIat\fP +\fB-qb\fP. A number of +features were added to list and control batch work separately from +those in \fIat\fP. Upon +further reflection, it was decided that the benefit of this did not +merit the change to the historical interface. +.LP +The \fB-m\fP option was included on the equivalent \fIat\fP command +because it is +historical practice to mail results to the submitter, even if all +job-produced output is redirected. As explained in the RATIONALE +for \fIat\fP, the \fBnow\fP keyword submits the job for immediate +execution (after scheduling +delays), despite some historical systems where \fIat\fP \fBnow\fP +would have been considered +an error. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIat\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/bc.1p b/man1p/bc.1p new file mode 100644 index 000000000..a2860dc69 --- /dev/null +++ b/man1p/bc.1p @@ -0,0 +1,1354 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "BC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" bc +.SH NAME +bc \- arbitrary-precision arithmetic language +.SH SYNOPSIS +.LP +\fBbc\fP \fB[\fP\fB-l\fP\fB] [\fP\fIfile\fP \fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIbc\fP utility shall implement an arbitrary precision calculator. +It shall take input from any files given, then read +from the standard input. If the standard input and standard output +to \fIbc\fP are attached to a terminal, the invocation of +\fIbc\fP shall be considered to be \fIinteractive\fP, causing behavioral +constraints described in the following sections. +.SH OPTIONS +.LP +The \fIbc\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-l\fP +(The letter ell.) Define the math functions and initialize \fIscale\fP +to 20, instead of the default zero; see the EXTENDED +DESCRIPTION section. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a text file containing \fIbc\fP program statements. +After all \fIfile\fPs have been read, \fIbc\fP shall read +the standard input. +.sp +.SH STDIN +.LP +See the INPUT FILES section. +.SH INPUT FILES +.LP +Input files shall be text files containing a sequence of comments, +statements, and function definitions that shall be executed +as they are read. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIbc\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The output of the \fIbc\fP utility shall be controlled by the program +read, and consist of zero or more lines containing the +value of all executed expressions without assignments. The radix and +precision of the output shall be controlled by the values of +the \fBobase\fP and \fBscale\fP variables; see the EXTENDED DESCRIPTION +section. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.SS Grammar +.LP +The grammar in this section and the lexical conventions in the following +section shall together describe the syntax for +\fIbc\fP programs. The general conventions for this style of grammar +are described in \fIGrammar Conventions\fP . A valid program can be +represented as the non-terminal symbol +\fBprogram\fP in the grammar. This formal syntax shall take precedence +over the text syntax description. +.sp +.RS +.nf + +\fB%token EOF NEWLINE STRING LETTER NUMBER +.sp + +%token MUL_OP +/* '*', '/', '%' */ +.sp + +%token ASSIGN_OP +/* '=', '+=', '-=', '*=', '/=', '%=', '^=' */ +.sp + +%token REL_OP +/* '==', '<=', '>=', '!=', '<', '>' */ +.sp + +%token INCR_DECR +/* '++', '--' */ +.sp + +%token Define Break Quit Length +/* 'define', 'break', 'quit', 'length' */ +.sp + +%token Return For If While Sqrt +/* 'return', 'for', 'if', 'while', 'sqrt' */ +.sp + +%token Scale Ibase Obase Auto +/* 'scale', 'ibase', 'obase', 'auto' */ +.sp + +%start program +.sp + +%% +.sp + +program : EOF + | input_item program + ; +.sp + +input_item : semicolon_list NEWLINE + | function + ; +.sp + +semicolon_list : /* empty */ + | statement + | semicolon_list ';' statement + | semicolon_list ';' + ; +.sp + +statement_list : /* empty */ + | statement + | statement_list NEWLINE + | statement_list NEWLINE statement + | statement_list ';' + | statement_list ';' statement + ; +.sp + +statement : expression + | STRING + | Break + | Quit + | Return + | Return '(' return_expression ')' + | For '(' expression ';' + relational_expression ';' + expression ')' statement + | If '(' relational_expression ')' statement + | While '(' relational_expression ')' statement + | '{' statement_list '}' + ; +.sp + +function : Define LETTER '(' opt_parameter_list ')' + '{' NEWLINE opt_auto_define_list + statement_list '}' + ; +.sp + +opt_parameter_list : /* empty */ + | parameter_list + ; +.sp + +parameter_list : LETTER + | define_list ',' LETTER + ; +.sp + +opt_auto_define_list : /* empty */ + | Auto define_list NEWLINE + | Auto define_list ';' + ; +.sp + +define_list : LETTER + | LETTER '[' ']' + | define_list ',' LETTER + | define_list ',' LETTER '[' ']' + ; +.sp + +opt_argument_list : /* empty */ + | argument_list + ; +.sp + +argument_list : expression + | LETTER '[' ']' ',' argument_list + ; +.sp + +relational_expression : expression + | expression REL_OP expression + ; +.sp + +return_expression : /* empty */ + | expression + ; +.sp + +expression : named_expression + | NUMBER + | '(' expression ')' + | LETTER '(' opt_argument_list ')' + | '-' expression + | expression '+' expression + | expression '-' expression + | expression MUL_OP expression + | expression '^' expression + | INCR_DECR named_expression + | named_expression INCR_DECR + | named_expression ASSIGN_OP expression + | Length '(' expression ')' + | Sqrt '(' expression ')' + | Scale '(' expression ')' + ; +.sp + +named_expression : LETTER + | LETTER '[' expression ']' + | Scale + | Ibase + | Obase + ; +\fP +.fi +.RE +.SS Lexical Conventions in bc +.LP +The lexical conventions for \fIbc\fP programs, with respect to the +preceding grammar, shall be as follows: +.IP " 1." 4 +Except as noted, \fIbc\fP shall recognize the longest possible token +or delimiter beginning at a given point. +.LP +.IP " 2." 4 +A comment shall consist of any characters beginning with the two adjacent +characters \fB"/*"\fP and terminated by the next +occurrence of the two adjacent characters \fB"*/"\fP . Comments shall +have no effect except to delimit lexical tokens. +.LP +.IP " 3." 4 +The shall be recognized as the token \fBNEWLINE\fP. +.LP +.IP " 4." 4 +The token \fBSTRING\fP shall represent a string constant; it shall +consist of any characters beginning with the double-quote +character ( \fB' )'\fP and terminated by another occurrence of the +double-quote character. The value of the string is the +sequence of all characters between, but not including, the two double-quote +characters. All characters shall be taken literally +from the input, and there is no way to specify a string containing +a double-quote character. The length of the value of each string +shall be limited to {BC_STRING_MAX} bytes. +.LP +.IP " 5." 4 +A shall have no effect except as an ordinary character if +it appears within a \fBSTRING\fP token, or to delimit a +lexical token other than \fBSTRING\fP. +.LP +.IP " 6." 4 +The combination of a backslash character immediately followed by a + shall have no effect other than to delimit +lexical tokens with the following exceptions: +.RS +.IP " *" 3 +It shall be interpreted as the character sequence \fB"\\"\fP +in \fBSTRING\fP tokens. +.LP +.IP " *" 3 +It shall be ignored as part of a multi-line \fBNUMBER\fP token. +.LP +.RE +.LP +.IP " 7." 4 +The token \fBNUMBER\fP shall represent a numeric constant. It shall +be recognized by the following grammar: +.sp +.RS +.nf + +\fBNUMBER : integer + | '.' integer + | integer '.' + | integer '.' integer + ; +.sp + +integer : digit + | integer digit + ; +.sp + +digit : 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 + | 8 | 9 | A | B | C | D | E | F + ; +\fP +.fi +.RE +.LP +.IP " 8." 4 +The value of a \fBNUMBER\fP token shall be interpreted as a numeral +in the base specified by the value of the internal register +\fBibase\fP (described below). Each of the \fBdigit\fP characters +shall have the value from 0 to 15 in the order listed here, and +the period character shall represent the radix point. The behavior +is undefined if digits greater than or equal to the value of +\fBibase\fP appear in the token. However, note the exception for single-digit +values being assigned to \fBibase\fP and +\fBobase\fP themselves, in Operations in bc . +.LP +.IP " 9." 4 +The following keywords shall be recognized as tokens: +.TS C +center; lw(15) lw(15) lw(15) lw(15) lw(15). +T{ +\fB +.br +auto +.br +break +.br +define +.br +\fP +T} T{ +\fB +.br +ibase +.br +if +.br +for +.br +\fP +T} T{ +\fB +.br +length +.br +obase +.br +quit +.br +\fP +T} T{ +\fB +.br +return +.br +scale +.br +sqrt +.br +\fP +T} T{ +\fB +.br +while +.br +\fP +T} +.TE +.LP +.IP "10." 4 +Any of the following characters occurring anywhere except within a +keyword shall be recognized as the token \fBLETTER\fP: +.sp +.RS +.nf + +\fBa b c d e f g h i j k l m n o p q r s t u v w x y z +\fP +.fi +.RE +.LP +.IP "11." 4 +The following single-character and two-character sequences shall be +recognized as the token \fBASSIGN_OP\fP: +.sp +.RS +.nf + +\fB= += -= *= /= %= ^= +\fP +.fi +.RE +.LP +.IP "12." 4 +If an \fB'='\fP character, as the beginning of a token, is followed +by a \fB'-'\fP character with no intervening +delimiter, the behavior is undefined. +.LP +.IP "13." 4 +The following single-characters shall be recognized as the token \fBMUL_OP\fP: +.sp +.RS +.nf + +\fB* / % +\fP +.fi +.RE +.LP +.IP "14." 4 +The following single-character and two-character sequences shall be +recognized as the token \fBREL_OP\fP: +.sp +.RS +.nf + +\fB== <= >= != < > +\fP +.fi +.RE +.LP +.IP "15." 4 +The following two-character sequences shall be recognized as the token +\fBINCR_DECR\fP: +.sp +.RS +.nf + +\fB++ -- +\fP +.fi +.RE +.LP +.IP "16." 4 +The following single characters shall be recognized as tokens whose +names are the character: +.sp +.RS +.nf + +\fB ( ) , + - ; [ ] ^ { } +\fP +.fi +.RE +.LP +.IP "17." 4 +The token \fBEOF\fP is returned when the end of input is reached. +.LP +.SS Operations in bc +.LP +There are three kinds of identifiers: ordinary identifiers, array +identifiers, and function identifiers. All three types consist +of single lowercase letters. Array identifiers shall be followed by +square brackets ( \fB"[]"\fP ). An array subscript is +required except in an argument or auto list. Arrays are singly dimensioned +and can contain up to {BC_DIM_MAX} elements. Indexing +shall begin at zero so an array is indexed from 0 to {BC_DIM_MAX}-1. +Subscripts shall be truncated to integers. The application +shall ensure that function identifiers are followed by parentheses, +possibly enclosing arguments. The three types of identifiers do +not conflict. +.LP +The following table summarizes the rules for precedence and associativity +of all operators. Operators on the same line shall +have the same precedence; rows are in order of decreasing precedence. +.sp +.ce 1 +\fBTable: Operators in \fIbc\fP\fP +.TS C +center; l l. +\fBOperator\fP \fBAssociativity\fP +++, -- N/A +unary - N/A +^ Right to left +*, /, % Left to right ++, binary - Left to right +=, +=, -=, *=, /=, %=, ^= Right to left +==, <=, >=, !=, <, > None +.TE +.LP +Each expression or named expression has a \fIscale\fP, which is the +number of decimal digits that shall be maintained as the +fractional portion of the expression. +.LP +\fINamed expressions\fP are places where values are stored. Named +expressions shall be valid on the left side of an assignment. +The value of a named expression shall be the value stored in the place +named. Simple identifiers and array elements are named +expressions; they have an initial value of zero and an initial scale +of zero. +.LP +The internal registers \fBscale\fP, \fBibase\fP, and \fBobase\fP are +all named expressions. The scale of an expression +consisting of the name of one of these registers shall be zero; values +assigned to any of these registers are truncated to +integers. The \fBscale\fP register shall contain a global value used +in computing the scale of expressions (as described below). +The value of the register \fBscale\fP is limited to 0 <= \fBscale\fP +<= {BC_SCALE_MAX} and shall have a default value of +zero. The \fBibase\fP and \fBobase\fP registers are the input and +output number radix, respectively. The value of \fBibase\fP +shall be limited to: +.sp +.RS +.nf + +\fB2 <= ibase <= 16 +\fP +.fi +.RE +.LP +The value of \fBobase\fP shall be limited to: +.sp +.RS +.nf + +\fB2 <= obase <= {BC_BASE_MAX} +\fP +.fi +.RE +.LP +When either \fBibase\fP or \fBobase\fP is assigned a single \fBdigit\fP +value from the list in Lexical Conventions in bc , the value shall +be assumed in hexadecimal. (For example, \fBibase\fP=A sets to +base ten, regardless of the current \fBibase\fP value.) Otherwise, +the behavior is undefined when digits greater than or equal to +the value of \fBibase\fP appear in the input. Both \fBibase\fP and +\fBobase\fP shall have initial values of 10. +.LP +Internal computations shall be conducted as if in decimal, regardless +of the input and output bases, to the specified number of +decimal digits. When an exact result is not achieved (for example, +\fBscale\fP=0;\ 3.2/1)\fB,\fP the result shall be +truncated. +.LP +For all values of \fBobase\fP specified by this volume of IEEE\ Std\ 1003.1-2001, +\fIbc\fP shall output numeric values +by performing each of the following steps in order: +.IP " 1." 4 +If the value is less than zero, a hyphen ( \fB'-'\fP ) character shall +be output. +.LP +.IP " 2." 4 +One of the following is output, depending on the numerical value: +.RS +.IP " *" 3 +If the absolute value of the numerical value is greater than or equal +to one, the integer portion of the value shall be output +as a series of digits appropriate to \fBobase\fP (as described below), +most significant digit first. The most significant non-zero +digit shall be output next, followed by each successively less significant +digit. +.LP +.IP " *" 3 +If the absolute value of the numerical value is less than one but +greater than zero and the scale of the numerical value is +greater than zero, it is unspecified whether the character 0 is output. +.LP +.IP " *" 3 +If the numerical value is zero, the character 0 shall be output. +.LP +.RE +.LP +.IP " 3." 4 +If the scale of the value is greater than zero and the numeric value +is not zero, a period character shall be output, followed +by a series of digits appropriate to \fBobase\fP (as described below) +representing the most significant portion of the fractional +part of the value. If \fIs\fP represents the scale of the value being +output, the number of digits output shall be \fIs\fP if +\fBobase\fP is 10, less than or equal to \fIs\fP if \fBobase\fP is +greater than 10, or greater than or equal to \fIs\fP if +\fBobase\fP is less than 10. For \fBobase\fP values other than 10, +this should be the number of digits needed to represent a +precision of 10**\fIs\fP. +.LP +.LP +For \fBobase\fP values from 2 to 16, valid digits are the first \fBobase\fP +of the single characters: +.sp +.RS +.nf + +\fB0 1 2 3 4 5 6 7 8 9 A B C D E F +\fP +.fi +.RE +.LP +which represent the values zero to 15, inclusive, respectively. +.LP +For bases greater than 16, each digit shall be written as a separate +multi-digit decimal number. Each digit except the most +significant fractional digit shall be preceded by a single . +For bases from 17 to 100, \fIbc\fP shall write two-digit +decimal numbers; for bases from 101 to 1000, three-digit decimal strings, +and so on. For example, the decimal number 1024 in base +25 would be written as: +.sp +.RS +.nf + +\fB 01 15 24 +\fP +.fi +.RE +.LP +and in base 125, as: +.sp +.RS +.nf + +\fB 008 024 +\fP +.fi +.RE +.LP +Very large numbers shall be split across lines with 70 characters +per line in the POSIX locale; other locales may split at +different character boundaries. Lines that are continued shall end +with a backslash ( \fB'\\'\fP ). +.LP +A function call shall consist of a function name followed by parentheses +containing a comma-separated list of expressions, which +are the function arguments. A whole array passed as an argument shall +be specified by the array name followed by empty square +brackets. All function arguments shall be passed by value. As a result, +changes made to the formal parameters shall have no effect +on the actual arguments. If the function terminates by executing a +\fBreturn\fP statement, the value of the function shall be the +value of the expression in the parentheses of the \fBreturn\fP statement +or shall be zero if no expression is provided or if there +is no \fBreturn\fP statement. +.LP +The result of \fBsqrt\fP( \fIexpression\fP) shall be the square root +of the expression. The result shall be truncated in the +least significant decimal place. The scale of the result shall be +the scale of the expression or the value of \fBscale\fP, +whichever is larger. +.LP +The result of \fBlength\fP( \fIexpression\fP) shall be the total number +of significant decimal digits in the expression. The +scale of the result shall be zero. +.LP +The result of \fBscale\fP( \fIexpression\fP) shall be the scale of +the expression. The scale of the result shall be zero. +.LP +A numeric constant shall be an expression. The scale shall be the +number of digits that follow the radix point in the input +representing the constant, or zero if no radix point appears. +.LP +The sequence (\ \fIexpression\fP\ ) shall be an expression with the +same value and scale as \fIexpression\fP. The +parentheses can be used to alter the normal precedence. +.LP +The semantics of the unary and binary operators are as follows: +.TP 7 +-\fIexpression\fP +.sp +The result shall be the negative of the \fIexpression\fP. The scale +of the result shall be the scale of \fIexpression\fP. +.sp +.LP +The unary increment and decrement operators shall not modify the scale +of the named expression upon which they operate. The +scale of the result shall be the scale of that named expression. +.TP 7 +++\fInamed-expression\fP +.sp +The named expression shall be incremented by one. The result shall +be the value of the named expression after incrementing. +.TP 7 +--\fInamed-expression\fP +.sp +The named expression shall be decremented by one. The result shall +be the value of the named expression after decrementing. +.TP 7 +\fInamed-expression\fP++ +.sp +The named expression shall be incremented by one. The result shall +be the value of the named expression before incrementing. +.TP 7 +\fInamed-expression\fP-- +.sp +The named expression shall be decremented by one. The result shall +be the value of the named expression before decrementing. +.sp +.LP +The exponentiation operator, circumflex ( \fB'^'\fP ), shall bind +right to left. +.TP 7 +\fIexpression\fP^\fIexpression\fP +.sp +The result shall be the first \fIexpression\fP raised to the power +of the second \fIexpression\fP. If the second expression is +not an integer, the behavior is undefined. If \fIa\fP is the scale +of the left expression and \fIb\fP is the absolute value of +the right expression, the scale of the result shall be: +.sp +.RS +.nf + +\fBif b >= 0 min(a * b, max(scale, a)) if b < 0 scale +\fP +.fi +.RE +.sp +The multiplicative operators ( \fB'*'\fP , \fB'/'\fP , \fB'%'\fP ) +shall bind left to right. +.TP 7 +\fIexpression\fP*\fIexpression\fP +.sp +The result shall be the product of the two expressions. If \fIa\fP +and \fIb\fP are the scales of the two expressions, then the +scale of the result shall be: +.sp +.RS +.nf + +\fBmin(a+b,max(scale,a,b)) +\fP +.fi +.RE +.TP 7 +\fIexpression\fP/\fIexpression\fP +.sp +The result shall be the quotient of the two expressions. The scale +of the result shall be the value of \fBscale\fP. +.TP 7 +\fIexpression\fP%\fIexpression\fP +.sp +For expressions \fIa\fP and \fIb\fP, \fIa\fP% \fIb\fP shall be evaluated +equivalent to the steps: +.RS +.IP " 1." 4 +Compute \fIa\fP/ \fIb\fP to current scale. +.LP +.IP " 2." 4 +Use the result to compute: +.sp +.RS +.nf + +\fBa - (a / b) * b +\fP +.fi +.RE +.LP +to scale: +.sp +.RS +.nf + +\fBmax(scale + scale(b), scale(a)) +\fP +.fi +.RE +.LP +.RE +The scale of the result shall be: +.sp +.RS +.nf + +\fBmax(scale + scale(b), scale(a)) +\fP +.fi +.RE +.LP +When \fBscale\fP is zero, the \fB'%'\fP operator is the mathematical +remainder operator. +.sp +.LP +The additive operators ( \fB'+'\fP , \fB'-'\fP ) shall bind left to +right. +.TP 7 +\fIexpression\fP+\fIexpression\fP +.sp +The result shall be the sum of the two expressions. The scale of the +result shall be the maximum of the scales of the +expressions. +.TP 7 +\fIexpression\fP-\fIexpression\fP +.sp +The result shall be the difference of the two expressions. The scale +of the result shall be the maximum of the scales of the +expressions. +.sp +.LP +The assignment operators ( \fB'='\fP , \fB"+="\fP , \fB"-="\fP , \fB"*="\fP +, \fB"/="\fP , \fB"%="\fP , +\fB"^="\fP ) shall bind right to left. +.TP 7 +\fInamed-expression\fP=\fIexpression\fP +.sp +This expression shall result in assigning the value of the expression +on the right to the named expression on the left. The scale +of both the named expression and the result shall be the scale of +\fIexpression\fP. +.sp +.LP +The compound assignment forms: +.sp +.RS +.nf + +\fInamed-expression\fP \fB<\fP\fIoperator\fP\fB>=\fP \fIexpression\fP +.fi +.RE +.LP +shall be equivalent to: +.sp +.RS +.nf + +\fInamed-expression\fP\fB=\fP\fInamed-expression\fP \fB<\fP\fIoperator\fP\fB>\fP \fIexpression\fP +.fi +.RE +.LP +except that the \fInamed-expression\fP shall be evaluated only once. +.LP +Unlike all other operators, the relational operators ( \fB'<'\fP , +\fB'>'\fP , \fB"<="\fP , \fB">="\fP , +\fB"=="\fP , \fB"!="\fP ) shall be only valid as the object of an +\fBif\fP, \fBwhile\fP, or inside a \fBfor\fP +statement. +.TP 7 +\fIexpression1\fP<\fIexpression2\fP +.sp +The relation shall be true if the value of \fIexpression1\fP is strictly +less than the value of \fIexpression2\fP. +.TP 7 +\fIexpression1\fP>\fIexpression2\fP +.sp +The relation shall be true if the value of \fIexpression1\fP is strictly +greater than the value of \fIexpression2\fP. +.TP 7 +\fIexpression1\fP<=\fIexpression2\fP +.sp +The relation shall be true if the value of \fIexpression1\fP is less +than or equal to the value of \fIexpression2\fP. +.TP 7 +\fIexpression1\fP>=\fIexpression2\fP +.sp +The relation shall be true if the value of \fIexpression1\fP is greater +than or equal to the value of \fIexpression2\fP. +.TP 7 +\fIexpression1\fP==\fIexpression2\fP +.sp +The relation shall be true if the values of \fIexpression1\fP and +\fIexpression2\fP are equal. +.TP 7 +\fIexpression1\fP!=\fIexpression2\fP +.sp +The relation shall be true if the values of \fIexpression1\fP and +\fIexpression2\fP are unequal. +.sp +.LP +There are only two storage classes in \fIbc\fP: global and automatic +(local). Only identifiers that are local to a function +need be declared with the \fBauto\fP command. The arguments to a function +shall be local to the function. All other identifiers +are assumed to be global and available to all functions. All identifiers, +global and local, have initial values of zero. +Identifiers declared as auto shall be allocated on entry to the function +and released on returning from the function. They +therefore do not retain values between function calls. Auto arrays +shall be specified by the array name followed by empty square +brackets. On entry to a function, the old values of the names that +appear as parameters and as automatic variables shall be pushed +onto a stack. Until the function returns, reference to these names +shall refer only to the new values. +.LP +References to any of these names from other functions that are called +from this function also refer to the new value until one +of those functions uses the same name for a local variable. +.LP +When a statement is an expression, unless the main operator is an +assignment, execution of the statement shall write the value +of the expression followed by a . +.LP +When a statement is a string, execution of the statement shall write +the value of the string. +.LP +Statements separated by semicolons or s shall be executed +sequentially. In an interactive invocation of +\fIbc\fP, each time a is read that satisfies the grammatical +production: +.sp +.RS +.nf + +\fBinput_item : semicolon_list NEWLINE +\fP +.fi +.RE +.LP +the sequential list of statements making up the \fBsemicolon_list\fP +shall be executed immediately and any output produced by +that execution shall be written without any delay due to buffering. +.LP +In an \fBif\fP statement ( \fBif\fP( \fIrelation\fP) \fIstatement\fP), +the \fIstatement\fP shall be executed if the +relation is true. +.LP +The \fBwhile\fP statement ( \fBwhile\fP( \fIrelation\fP) \fIstatement\fP) +implements a loop in which the \fIrelation\fP is +tested; each time the \fIrelation\fP is true, the \fIstatement\fP +shall be executed and the \fIrelation\fP retested. When the +\fIrelation\fP is false, execution shall resume after \fIstatement\fP. +.LP +A \fBfor\fP statement( \fBfor\fP( \fIexpression\fP; \fIrelation\fP; +\fIexpression\fP) \fIstatement\fP) shall be the same +as: +.sp +.RS +.nf + +\fIfirst-expression\fP\fBwhile (\fP\fIrelation\fP\fB) { + \fP \fIstatement\fP \fB \fP \fIlast-expression\fP\fB} +\fP +.fi +.RE +The application shall ensure that all three expressions are present. +.LP +The \fBbreak\fP statement shall cause termination of a \fBfor\fP or +\fBwhile\fP statement. +.LP +The \fBauto\fP statement ( \fBauto\fP \fIidentifier\fP \fB[\fP, \fIidentifier\fP +\fB]\fP ...) shall cause the values of +the identifiers to be pushed down. The identifiers can be ordinary +identifiers or array identifiers. Array identifiers shall be +specified by following the array name by empty square brackets. The +application shall ensure that the \fBauto\fP statement is the +first statement in a function definition. +.LP +A \fBdefine\fP statement: +.sp +.RS +.nf + +\fBdefine\fP \fILETTER\fP \fB(\fP \fIopt_parameter_list\fP \fB) { + \fP \fIopt_auto_define_list\fP \fB \fP \fIstatement_list\fP\fB} +\fP +.fi +.RE +.LP +defines a function named \fBLETTER\fP. If a function named \fBLETTER\fP +was previously defined, the \fBdefine\fP statement +shall replace the previous definition. The expression: +.sp +.RS +.nf + +\fBLETTER (\fP \fIopt_argument_list\fP \fB) +\fP +.fi +.RE +.LP +shall invoke the function named \fBLETTER\fP. The behavior is undefined +if the number of arguments in the invocation does not +match the number of parameters in the definition. Functions shall +be defined before they are invoked. A function shall be +considered to be defined within its own body, so recursive calls are +valid. The values of numeric constants within a function shall +be interpreted in the base specified by the value of the \fBibase\fP +register when the function is invoked. +.LP +The \fBreturn\fP statements ( \fBreturn\fP and \fBreturn\fP( \fIexpression\fP)) +shall cause termination of a function, +popping of its auto variables, and specification of the result of +the function. The first form shall be equivalent to +\fBreturn\fP(0). The value and scale of the result returned by the +function shall be the value and scale of the expression +returned. +.LP +The \fBquit\fP statement ( \fBquit\fP) shall stop execution of a \fIbc\fP +program at the point where the statement occurs in +the input, even if it occurs in a function definition, or in an \fBif\fP, +\fBfor\fP, or \fBwhile\fP statement. +.LP +The following functions shall be defined when the \fB-l\fP option +is specified: +.TP 7 +\fBs\fP(\ \fIexpression\fP\ ) +.sp +Sine of argument in radians. +.TP 7 +\fBc\fP(\ \fIexpression\fP\ ) +.sp +Cosine of argument in radians. +.TP 7 +\fBa\fP(\ \fIexpression\fP\ ) +.sp +Arctangent of argument. +.TP 7 +\fBl\fP(\ \fIexpression\fP\ ) +.sp +Natural logarithm of argument. +.TP 7 +\fBe\fP(\ \fIexpression\fP\ ) +.sp +Exponential function of argument. +.TP 7 +\fBj\fP(\ \fIexpression\fP,\ \fIexpression\fP\ ) +.sp +Bessel function of integer order. +.sp +.LP +The scale of the result returned by these functions shall be the value +of the \fBscale\fP register at the time the function is +invoked. The value of the \fBscale\fP register after these functions +have completed their execution shall be the same value it had +upon invocation. The behavior is undefined if any of these functions +is invoked with an argument outside the domain of the +mathematical function. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +0 +All input files were processed successfully. +.TP 7 +\fIunspecified\fP +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If any \fIfile\fP operand is specified and the named file cannot be +accessed, \fIbc\fP shall write a diagnostic message to +standard error and terminate without any further action. +.LP +In an interactive invocation of \fIbc\fP, the utility should print +an error message and recover following any error in the +input. In a non-interactive invocation of \fIbc\fP, invalid input +causes undefined behavior. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Automatic variables in \fIbc\fP do not work in exactly the same way +as in either C or PL/1. +.LP +For historical reasons, the exit status from \fIbc\fP cannot be relied +upon to indicate that an error has occurred. Returning +zero after an error is possible. Therefore, \fIbc\fP should be used +primarily by interactive users (who can react to error +messages) or by application programs that can somehow validate the +answers returned as not including error messages. +.LP +The \fIbc\fP utility always uses the period ( \fB'.'\fP ) character +to represent a radix point, regardless of any +decimal-point character specified as part of the current locale. In +languages like C or \fIawk\fP, the period character is used in program +source, so it can be portable and unambiguous, +while the locale-specific character is used in input and output. Because +there is no distinction between source and input in +\fIbc\fP, this arrangement would not be possible. Using the locale-specific +character in \fIbc\fP's input would introduce +ambiguities into the language; consider the following example in a +locale with a comma as the decimal-point character: +.sp +.RS +.nf + +\fBdefine f(a,b) { + ... +} +\&... +.sp + +f(1,2,3) +\fP +.fi +.RE +.LP +Because of such ambiguities, the period character is used in input. +Having input follow different conventions from output would +be confusing in either pipeline usage or interactive usage, so the +period is also used in output. +.SH EXAMPLES +.LP +In the shell, the following assigns an approximation of the first +ten digits of \fB'pi'\fP to the variable \fIx\fP: +.sp +.RS +.nf + +\fBx=$(printf "%s\\n" 'scale = 10; 104348/33215' | bc) +\fP +.fi +.RE +.LP +The following \fIbc\fP program prints the same approximation of \fB'pi'\fP +, with a +label, to standard output: +.sp +.RS +.nf + +\fBscale = 10 +"pi equals " +104348 / 33215 +\fP +.fi +.RE +.LP +The following defines a function to compute an approximate value of +the exponential function (note that such a function is +predefined if the \fB-l\fP option is specified): +.sp +.RS +.nf + +\fBscale = 20 +define e(x){ + auto a, b, c, i, s + a = 1 + b = 1 + s = 1 + for (i = 1; 1 == 1; i++){ + a = a*x + b = b*i + c = a/b + if (c == 0) { + return(s) + } + s = s+c + } +} +\fP +.fi +.RE +.LP +The following prints approximate values of the exponential function +of the first ten integers: +.sp +.RS +.nf + +\fBfor (i = 1; i <= 10; ++i) { + e(i) +} +\fP +.fi +.RE +.SH RATIONALE +.LP +The \fIbc\fP utility is implemented historically as a front-end processor +for \fIdc\fP; \fIdc\fP was not selected to be part +of this volume of IEEE\ Std\ 1003.1-2001 because \fIbc\fP was thought +to have a more intuitive programmatic interface. +Current implementations that implement \fIbc\fP using \fIdc\fP are +expected to be compliant. +.LP +The exit status for error conditions has been left unspecified for +several reasons: +.IP " *" 3 +The \fIbc\fP utility is used in both interactive and non-interactive +situations. Different exit codes may be appropriate for +the two uses. +.LP +.IP " *" 3 +It is unclear when a non-zero exit should be given; divide-by-zero, +undefined functions, and syntax errors are all +possibilities. +.LP +.IP " *" 3 +It is not clear what utility the exit status has. +.LP +.IP " *" 3 +In the 4.3 BSD, System V, and Ninth Edition implementations, \fIbc\fP +works in conjunction with \fIdc\fP. The \fIdc\fP +utility is the parent, \fIbc\fP is the child. This was done to cleanly +terminate \fIbc\fP if \fIdc\fP aborted. +.LP +.LP +The decision to have \fIbc\fP exit upon encountering an inaccessible +input file is based on the belief that \fIbc\fP +\fIfile1\fP \fIfile2\fP is used most often when at least \fIfile1\fP +contains data/function declarations/initializations. Having +\fIbc\fP continue with prerequisite files missing is probably not +useful. There is no implication in the CONSEQUENCES OF ERRORS +section that \fIbc\fP must check all its files for accessibility before +opening any of them. +.LP +There was considerable debate on the appropriateness of the language +accepted by \fIbc\fP. Several reviewers preferred to see +either a pure subset of the C language or some changes to make the +language more compatible with C. While the \fIbc\fP language +has some obvious similarities to C, it has never claimed to be compatible +with any version of C. An interpreter for a subset of C +might be a very worthwhile utility, and it could potentially make +\fIbc\fP obsolete. However, no such utility is known in +historical practice, and it was not within the scope of this volume +of IEEE\ Std\ 1003.1-2001 to define such a language and +utility. If and when they are defined, it may be appropriate to include +them in a future version of IEEE\ Std\ 1003.1. This +left the following alternatives: +.IP " 1." 4 +Exclude any calculator language from this volume of IEEE\ Std\ 1003.1-2001. +.LP +The consensus of the standard developers was that a simple programmatic +calculator language is very useful for both applications +and interactive users. The only arguments for excluding any calculator +were that it would become obsolete if and when a +C-compatible one emerged, or that the absence would encourage the +development of such a C-compatible one. These arguments did not +sufficiently address the needs of current application writers. +.LP +.IP " 2." 4 +Standardize the historical \fIdc\fP, possibly with minor modifications. +.LP +The consensus of the standard developers was that \fIdc\fP is a fundamentally +less usable language and that that would be far +too severe a penalty for avoiding the issue of being similar to but +incompatible with C. +.LP +.IP " 3." 4 +Standardize the historical \fIbc\fP, possibly with minor modifications. +.LP +This was the approach taken. Most of the proponents of changing the +language would not have been satisfied until most or all of +the incompatibilities with C were resolved. Since most of the changes +considered most desirable would break historical applications +and require significant modification to historical implementations, +almost no modifications were made. The one significant +modification that was made was the replacement of the historical \fIbc\fP +assignment operators \fB"=+"\fP , and so on, with the +more modern \fB"+="\fP , and so on. The older versions are considered +to be fundamentally flawed because of the lexical +ambiguity in uses like \fIa\fP=-1. +.LP +In order to permit implementations to deal with backwards-compatibility +as they see fit, the behavior of this one ambiguous +construct was made undefined. (At least three implementations have +been known to support this change already, so the degree of +change involved should not be great.) +.LP +.LP +The \fB'%'\fP operator is the mathematical remainder operator when +\fBscale\fP is zero. The behavior of this operator for +other values of \fBscale\fP is from historical implementations of +\fIbc\fP, and has been maintained for the sake of historical +applications despite its non-intuitive nature. +.LP +Historical implementations permit setting \fBibase\fP and \fBobase\fP +to a broader range of values. This includes values less +than 2, which were not seen as sufficiently useful to standardize. +These implementations do not interpret input properly for values +of \fBibase\fP that are greater than 16. This is because numeric constants +are recognized syntactically, rather than lexically, as +described in this volume of IEEE\ Std\ 1003.1-2001. They are built +from lexical tokens of single hexadecimal digits and +periods. Since s between tokens are not visible at the syntactic +level, it is not possible to recognize the +multi-digit "digits" used in the higher bases properly. The ability +to recognize input in these bases was not considered useful +enough to require modifying these implementations. Note that the recognition +of numeric constants at the syntactic level is not a +problem with conformance to this volume of IEEE\ Std\ 1003.1-2001, +as it does not impact the behavior of conforming +applications (and correct \fIbc\fP programs). Historical implementations +also accept input with all of the digits \fB'0'\fP - +\fB'9'\fP and \fB'A'\fP - \fB'F'\fP regardless of the value of \fBibase\fP; +since digits with value greater than or equal +to \fBibase\fP are not really appropriate, the behavior when they +appear is undefined, except for the common case of: +.sp +.RS +.nf + +\fBibase=8; + /* Process in octal base. */ +\&... +ibase=A + /* Restore decimal base. */ +\fP +.fi +.RE +.LP +In some historical implementations, if the expression to be written +is an uninitialized array element, a leading +and/or up to four leading 0 characters may be output before the character +zero. This behavior is considered a bug; it is unlikely +that any currently conforming application relies on: +.sp +.RS +.nf + +\fBecho 'b[3]' | bc +\fP +.fi +.RE +.LP +returning 00000 rather than 0. +.LP +Exact calculation of the number of fractional digits to output for +a given value in a base other than 10 can be computationally +expensive. Historical implementations use a faster approximation, +and this is permitted. Note that the requirements apply only to +values of \fBobase\fP that this volume of IEEE\ Std\ 1003.1-2001 requires +implementations to support (in particular, not +to 1, 0, or negative bases, if an implementation supports them as +an extension). +.LP +Historical implementations of \fIbc\fP did not allow array parameters +to be passed as the last parameter to a function. New +implementations are encouraged to remove this restriction even though +it is not required by the grammar. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIGrammar Conventions\fP , \fIawk\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/bg.1p b/man1p/bg.1p new file mode 100644 index 000000000..5fbf2fac3 --- /dev/null +++ b/man1p/bg.1p @@ -0,0 +1,205 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "BG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" bg +.SH NAME +bg \- run jobs in the background +.SH SYNOPSIS +.LP +\fBbg\fP \fB[\fP\fIjob_id\fP \fB...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +If job control is enabled (see the description of \fIset\fP \fB-m\fP), +the +\fIbg\fP utility shall resume suspended jobs from the current environment +(see \fIShell +Execution Environment\fP ) by running them as background jobs. If +the job specified by \fIjob_id\fP is already a running +background job, the \fIbg\fP utility shall have no effect and shall +exit successfully. +.LP +Using \fIbg\fP to place a job into the background shall cause its +process ID to become "known in the current shell execution +environment", as if it had been started as an asynchronous list; see +\fIAsynchronous +Lists\fP . +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIjob_id\fP +Specify the job to be resumed as a background job. If no \fIjob_id\fP +operand is given, the most recently suspended job shall +be used. The format of \fIjob_id\fP is described in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 3.203, Job Control Job ID. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIbg\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The output of \fIbg\fP shall consist of a line in the format: +.sp +.RS +.nf + +\fB"[%d] %s\\n", <\fP\fIjob-number\fP\fB>, <\fP\fIcommand\fP\fB> +\fP +.fi +.RE +.LP +where the fields are as follows: +.TP 7 +<\fIjob-number\fP> +A number that can be used to identify the job to the \fIwait\fP, \fIfg\fP, +and \fIkill\fP utilities. Using these utilities, the +job can be identified by prefixing the job number with \fB'%'\fP . +.TP 7 +<\fIcommand\fP> +The associated command that was given to the shell. +.sp +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If job control is disabled, the \fIbg\fP utility shall exit with an +error and no job shall be placed in the background. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +A job is generally suspended by typing the SUSP character (-Z +on most systems); see the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +At that +point, \fIbg\fP can put the job into the background. This is most +effective when the job is expecting no terminal input and its +output has been redirected to non-terminal files. A background job +can be forced to stop when it has terminal output by issuing the +command: +.sp +.RS +.nf + +\fBstty tostop +\fP +.fi +.RE +.LP +A background job can be stopped with the command: +.sp +.RS +.nf + +\fBkill -s stop\fP \fIjob ID\fP +.fi +.RE +.LP +The \fIbg\fP utility does not work as expected when it is operating +in its own utility execution environment because that +environment has no suspended jobs. In the following examples: +.sp +.RS +.nf + +\fB\&... | xargs bg +(bg) +\fP +.fi +.RE +.LP +each \fIbg\fP operates in a different environment and does not share +its parent shell's understanding of jobs. For this reason, +\fIbg\fP is generally implemented as a shell regular built-in. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The extensions to the shell specified in this volume of IEEE\ Std\ 1003.1-2001 +have mostly been based on features +provided by the KornShell. The job control features provided by \fIbg\fP, +\fIfg\fP, and \fIjobs\fP are also based on the KornShell. The standard +developers examined the characteristics +of the C shell versions of these utilities and found that differences +exist. Despite widespread use of the C shell, the KornShell +versions were selected for this volume of IEEE\ Std\ 1003.1-2001 to +maintain a degree of uniformity with the rest of the +KornShell features selected (such as the very popular command line +editing features). +.LP +The \fIbg\fP utility is expected to wrap its output if the output +exceeds the number of display columns. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIAsynchronous Lists\fP , \fIfg\fP , \fIkill\fP() , \fIjobs\fP , +\fIwait\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/break.1p b/man1p/break.1p new file mode 100644 index 000000000..75c5ef623 --- /dev/null +++ b/man1p/break.1p @@ -0,0 +1,120 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "BREAK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" break +.SH NAME +break \- exit from for, while, or until loop +.SH SYNOPSIS +.LP +\fBbreak\fP \fB[\fP\fIn\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIbreak\fP utility shall exit from the smallest enclosing \fBfor\fP, +\fBwhile\fP, or \fBuntil\fP loop, if any; or from +the \fIn\fPth enclosing loop if \fIn\fP is specified. The value of +\fIn\fP is an unsigned decimal integer greater than or equal +to 1. The default shall be equivalent to \fIn\fP=1. If \fIn\fP is +greater than the number of enclosing loops, the outermost +enclosing loop shall be exited. Execution shall continue with the +command immediately following the loop. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +See the DESCRIPTION. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +None. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +The \fIn\fP value was not an unsigned decimal integer greater than +or equal to 1. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.sp +.RS +.nf + +\fBfor i in * do + if test -d "$i" then break fi done +\fP +.fi +.RE +.SH RATIONALE +.LP +In early proposals, consideration was given to expanding the syntax +of \fIbreak\fP and \fIcontinue\fP to refer to a label associated with +the appropriate loop as a preferable +alternative to the \fIn\fP method. However, this volume of IEEE\ Std\ 1003.1-2001 +does reserve the name space of command +names ending with a colon. It is anticipated that a future implementation +could take advantage of this and provide something +like: +.sp +.RS +.nf + +\fBoutofloop: for i in a b c d e +do + for j in 0 1 2 3 4 5 6 7 8 9 + do + if test -r "${i}${j}" + then break outofloop + fi + done +done +\fP +.fi +.RE +.LP +and that this might be standardized after implementation experience +is achieved. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISpecial Built-In Utilities\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/c99.1p b/man1p/c99.1p new file mode 100644 index 000000000..58b2b2352 --- /dev/null +++ b/man1p/c99.1p @@ -0,0 +1,745 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "C99" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" c99 +.SH NAME +c99 \- compile standard C programs +.SH SYNOPSIS +.LP +\fBc99\fP \fB[\fP\fB-c\fP\fB][\fP\fB-D\fP +\fIname\fP\fB[\fP\fB=\fP\fIvalue\fP\fB]]\fP\fB...\fP\fB[\fP\fB-E\fP\fB][\fP\fB-g\fP\fB][\fP\fB-I\fP +\fIdirectory\fP\fB]\fP \fB...\fP \fB[\fP\fB-L\fP \fIdirectory\fP\fB]\fP\fB +.br +\ \ \ \ \ \ ...\fP \fB[\fP\fB-o\fP +\fIoutfile\fP\fB][\fP\fB-O\fP\fIoptlevel\fP\fB][\fP\fB-s\fP\fB][\fP\fB-U\fP +\fIname\fP\fB]\fP\fB...\fP +\fIoperand\fP \fB... \fP +.SH DESCRIPTION +.LP +The \fIc99\fP utility is an interface to the standard C compilation +system; it shall accept source code conforming to the +ISO\ C standard. The system conceptually consists of a compiler and +link editor. The files referenced by \fIoperand\fPs shall +be compiled and linked to produce an executable file. (It is unspecified +whether the linking occurs entirely within the operation +of \fIc99\fP; some implementations may produce objects that are not +fully resolved until the file is executed.) +.LP +If the \fB-c\fP option is specified, for all pathname operands of +the form \fIfile\fP \fB.c\fP, the files: +.sp +.RS +.nf + +\fB$(basename\fP \fIpathname\fP \fB.c).o +\fP +.fi +.RE +.LP +shall be created as the result of successful compilation. If the \fB-c\fP +option is not specified, it is unspecified whether +such \fB.o\fP files are created or deleted for the \fIfile\fP \fB.c\fP +operands. +.LP +If there are no options that prevent link editing (such as \fB-c\fP +or \fB-E\fP), and all operands compile and link without +error, the resulting executable file shall be written according to +the \fB-o\fP \fIoutfile\fP option (if present) or to the file +\fBa.out\fP. +.LP +The executable file shall be created as specified in \fIFile Read, +Write, and +Creation\fP , except that the file permission bits shall be set to: +.sp +.RS +.nf + +S_IRWXO | S_IRWXG | S_IRWXU +.fi +.RE +.LP +and the bits specified by the \fIumask\fP of the process shall be +cleared. +.SH OPTIONS +.LP +The \fIc99\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that: +.IP " *" 3 +The \fB-l\fP \fIlibrary\fP operands have the format of options, but +their position within a list of operands affects the order +in which libraries are searched. +.LP +.IP " *" 3 +The order of specifying the \fB-I\fP and \fB-L\fP options is significant. +.LP +.IP " *" 3 +Conforming applications shall specify each option separately; that +is, grouping option letters (for example, \fB-cO\fP) need +not be recognized by all implementations. +.LP +.LP +The following options shall be supported: +.TP 7 +\fB-c\fP +Suppress the link-edit phase of the compilation, and do not remove +any object files that are produced. +.TP 7 +\fB-g\fP +Produce symbolic information in the object or executable files; the +nature of this information is unspecified, and may be +modified by implementation-defined interactions with other options. +.TP 7 +\fB-s\fP +Produce object or executable files, or both, from which symbolic and +other information not required for proper execution using +the \fIexec\fP family defined in the System Interfaces volume of IEEE\ Std\ 1003.1-2001 +has been removed (stripped). If +both \fB-g\fP and \fB-s\fP options are present, the action taken is +unspecified. +.TP 7 +\fB-o\ \fP \fIoutfile\fP +Use the pathname \fIoutfile\fP, instead of the default \fBa.out\fP, +for the executable file produced. If the \fB-o\fP option +is present with \fB-c\fP or \fB-E\fP, the result is unspecified. +.TP 7 +\fB-D\ \fP \fIname\fP\fB[=\fP\fIvalue\fP\fB]\fP +.sp +Define \fIname\fP as if by a C-language \fB#define\fP directive. If +no = \fIvalue\fP is given, a value of 1 shall be used. The +\fB-D\fP option has lower precedence than the \fB-U\fP option. That +is, if \fIname\fP is used in both a \fB-U\fP and a +\fB-D\fP option, \fIname\fP shall be undefined regardless of the order +of the options. Additional implementation-defined +\fIname\fPs may be provided by the compiler. Implementations shall +support at least 2048 bytes of \fB-D\fP definitions and 256 +\fInames\fP. +.TP 7 +\fB-E\fP +Copy C-language source files to standard output, expanding all preprocessor +directives; no compilation shall be performed. If +any operand is not a text file, the effects are unspecified. +.TP 7 +\fB-I\ \fP \fIdirectory\fP +Change the algorithm for searching for headers whose names are not +absolute pathnames to look in the directory named by the +\fIdirectory\fP pathname before looking in the usual places. Thus, +headers whose names are enclosed in double-quotes ( \fB""\fP +) shall be searched for first in the directory of the file with the +\fB#include\fP line, then in directories named in \fB-I\fP +options, and last in the usual places. For headers whose names are +enclosed in angle brackets ( \fB"<>"\fP ), the header +shall be searched for only in directories named in \fB-I\fP options +and then in the usual places. Directories named in \fB-I\fP +options shall be searched in the order specified. Implementations +shall support at least ten instances of this option in a single +\fIc99\fP command invocation. +.TP 7 +\fB-L\ \fP \fIdirectory\fP +Change the algorithm of searching for the libraries named in the \fB-l\fP +objects to look in the directory named by the +\fIdirectory\fP pathname before looking in the usual places. Directories +named in \fB-L\fP options shall be searched in the order +specified. Implementations shall support at least ten instances of +this option in a single \fIc99\fP command invocation. If a +directory specified by a \fB-L\fP option contains files named \fBlibc.a\fP, +\fBlibm.a\fP, \fBlibl.a\fP, or \fBliby.a\fP, the +results are unspecified. +.TP 7 +\fB-O\ \fP \fIoptlevel\fP +Specify the level of code optimization. If the \fIoptlevel\fP option-argument +is the digit \fB'0'\fP , all special code +optimizations shall be disabled. If it is the digit \fB'1'\fP , the +nature of the optimization is unspecified. If the \fB-O\fP +option is omitted, the nature of the system's default optimization +is unspecified. It is unspecified whether code generated in the +presence of the \fB-O\fP 0 option is the same as that generated when +\fB-O\fP is omitted. Other \fIoptlevel\fP values may be +supported. +.TP 7 +\fB-U\ \fP \fIname\fP +Remove any initial definition of \fIname\fP. +.sp +.LP +Multiple instances of the \fB-D\fP, \fB-I\fP, \fB-U\fP, and \fB-L\fP +options can be specified. +.SH OPERANDS +.LP +An \fIoperand\fP is either in the form of a pathname or the form \fB-l\fP +\fIlibrary\fP. The application shall ensure that at +least one operand of the pathname form is specified. The following +operands shall be supported: +.TP 7 +\fIfile.\fP\fBc\fP +A C-language source file to be compiled and optionally linked. The +application shall ensure that the operand is of this form if +the \fB-c\fP option is used. +.TP 7 +\fIfile.\fP\fBa\fP +A library of object files typically produced by the \fIar\fP utility, +and passed directly +to the link editor. Implementations may recognize implementation-defined +suffixes other than \fB.a\fP as denoting object file +libraries. +.TP 7 +\fIfile.\fP\fBo\fP +An object file produced by \fIc99\fP \fB-c\fP and passed directly +to the link editor. Implementations may recognize +implementation-defined suffixes other than \fB.o\fP as denoting object +files. +.sp +.LP +The processing of other files is implementation-defined. +.TP 7 +\fI-l\ library\fP +(The letter ell.) Search the library named: +.sp +.RS +.nf + +\fBlib\fP\fIlibrary\fP\fB.a +\fP +.fi +.RE +.LP +A library shall be searched when its name is encountered, so the placement +of a \fB-l\fP operand is significant. Several +standard libraries can be specified in this manner, as described in +the EXTENDED DESCRIPTION section. Implementations may recognize +implementation-defined suffixes other than \fB.a\fP as denoting libraries. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +The input file shall be one of the following: a text file containing +a C-language source program, an object file in the format +produced by \fIc99\fP \fB-c\fP, or a library of object files, in the +format produced by archiving zero or more object files, +using \fIar\fP. Implementations may supply additional utilities that +produce files in these +formats. Additional input file formats are implementation-defined. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIc99\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITMPDIR\fP +Provide a pathname that should override the default directory for +temporary files, if any. \ On +XSI-conforming systems, provide a pathname that shall override the +default directory for temporary files, if any. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If more than one \fIfile\fP operand ending in \fB.c\fP (or possibly +other unspecified suffixes) is given, for each such +file: +.sp +.RS +.nf + +\fB"%s:\\n", <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +may be written. These messages, if written, shall precede the processing +of each input file; they shall not be written to the +standard output if they are written to the standard error, as described +in the STDERR section. +.LP +If the \fB-E\fP option is specified, the standard output shall be +a text file that represents the results of the preprocessing +stage of the language; it may contain extra information appropriate +for subsequent compilation passes. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. If +more than one \fIfile\fP operand ending in \fB.c\fP (or +possibly other unspecified suffixes) is given, for each such file: +.sp +.RS +.nf + +\fB"%s:\\n", <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +may be written to allow identification of the diagnostic and warning +messages with the appropriate input file. These messages, +if written, shall precede the processing of each input file; they +shall not be written to the standard error if they are written to +the standard output, as described in the STDOUT section. +.LP +This utility may produce warning messages about certain conditions +that do not warrant returning an error (non-zero) exit +value. +.SH OUTPUT FILES +.LP +Object files or executable files or both are produced in unspecified +formats. +.SH EXTENDED DESCRIPTION +.SS Standard Libraries +.LP +The \fIc99\fP utility shall recognize the following \fB-l\fP operands +for standard libraries: +.TP 7 +\fB-l\ c\fP +This operand shall make visible all functions referenced in the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, +with the possible exception of those functions listed as residing +in \fI\fP, \fI\fP, \fI\fP, \fI\fP, +\fI\fP, \fI\fP, \fI\fP, \fI\fP, +\fI\fP, \fI\fP, \fI\fP, \fI\fP, +\fI\fP, \fIpthread_kill\fP(), and \fIpthread_sigmask\fP() +in \fI\fP, \fI\fP, functions +marked as extensions other than as part of the MF or MPR extensions +in \fI\fP, functions marked as ADV in \fI\fP, +and functions marked as CS, CPT, and TMR in \fI\fP. This operand +shall not be required to be present to cause a search of this +library. +.TP 7 +\fB-l\ l\fP +This operand shall make visible all functions required by the C-language +output of \fIlex\fP that are not made available through the \fB-l\ c\fP +operand. +.TP 7 +\fB-l\ pthread\fP +This operand shall make visible all functions referenced in \fI\fP +and \fIpthread_kill\fP() and \fIpthread_sigmask\fP() referenced in +\fI\fP. An implementation may search this library in the +absence of this +operand. +.TP 7 +\fB-l\ m\fP +This operand shall make visible all functions referenced in \fI\fP, +\fI\fP, and \fI\fP. An +implementation may search this library in the absence of this operand. +.TP 7 +\fB-l\ rt\fP +This operand shall make visible all functions referenced in \fI\fP, +\fI\fP, \fI\fP, \fI\fP, and \fI\fP, +functions marked as extensions other than as part of the MF or MPR +extensions in \fI\fP, functions marked as ADV in \fI\fP, +and functions marked as CS, CPT, and TMR in \fI\fP. An implementation +may search this library in the absence of this operand. +.TP 7 +\fB-l\ trace\fP +This operand shall make visible all functions referenced in \fI\fP. +An +implementation may search this library in the absence of this operand. +.TP 7 +\fB-l\ xnet\fP +This operand makes visible all functions referenced in \fI\fP, +\fI\fP, \fI\fP, and \fI\fP. An +implementation may search this library in the absence of this +operand. +.TP 7 +\fB-l\ y\fP +This operand shall make visible all functions required by the C-language +output of \fIyacc\fP that are not made available through the \fB-l\ c\fP +operand. +.sp +.LP +In the absence of options that inhibit invocation of the link editor, +such as \fB-c\fP or \fB-E\fP, the \fIc99\fP utility +shall cause the equivalent of a \fB-l\ c\fP operand to be passed to +the link editor as the last \fB-l\fP operand, causing it +to be searched after all other object files and libraries are loaded. +.LP +It is unspecified whether the libraries \fBlibc.a\fP, \fBlibm.a\fP, +\fBlibrt.a\fP, \fBlibpthread.a\fP, \fBlibl.a\fP, +\fBliby.a\fP, or \fBlibxnet.a\fP exist as regular files. The implementation +may accept as \fB-l\fP operands names of objects +that do not exist as regular files. +.SS External Symbols +.LP +The C compiler and link editor shall support the significance of external +symbols up to a length of at least 31 bytes; the +action taken upon encountering symbols exceeding the implementation-defined +maximum symbol length is unspecified. +.LP +The compiler and link editor shall support a minimum of 511 external +symbols per source or object file, and a minimum of 4095 +external symbols in total. A diagnostic message shall be written to +the standard output if the implementation-defined limit is +exceeded; other actions are unspecified. +.SS Programming Environments +.LP +All implementations shall support one of the following programming +environments as a default. Implementations may support more +than one of the following programming environments. Applications can +use \fIsysconf\fP() +or \fIgetconf\fP to determine which programming environments are supported. +.br +.sp +.ce 1 +\fBTable: Programming Environments: Type Sizes\fP +.TS C +center; l2 l2 l2 l2 l. +\fBProgramming Environment\fP \fBBits in\fP \fBBits in\fP \fBBits in\fP \fBBits in\fP +\fB\fIgetconf\fP Name\fP \fBint\fP \fBlong\fP \fBpointer\fP \fBoff_t\fP +_POSIX_V6_ILP32_OFF32 32 32 32 32 +_POSIX_V6_ILP32_OFFBIG 32 32 32 >=64 +_POSIX_V6_LP64_OFF64 32 64 64 64 +_POSIX_V6_LPBIG_OFFBIG >=32 >=64 >=64 >=64 +.TE +.LP +All implementations shall support one or more environments where the +widths of the following types are no greater than the width +of type \fBlong\fP: +\fBblksize_t\fP, \fBcc_t\fP, \fBmode_t\fP, \fBnfds_t\fP, \fBpid_t\fP, +\fBptrdiff_t\fP, \fBsize_t\fP, +\fBspeed_t\fP, \fBssize_t\fP, \fBsuseconds_t\fP, \fBtcflag_t\fP, \fBuseconds_t\fP, +\fBwchar_t\fP, \fBwint_t\fP +.LP +The executable files created when these environments are selected +shall be in a proper format for execution by the \fIexec\fP +family of functions. Each environment may be one of the ones in Programming +Environments: Type Sizes , or +it may be another environment. The names for the environments that +meet this requirement shall be output by a \fIgetconf\fP command using +the _POSIX_V6_WIDTH_RESTRICTED_ENVS argument. If more than one +environment meets the requirement, the names of all such environments +shall be output on separate lines. Any of these names can +then be used in a subsequent \fIgetconf\fP command to obtain the flags +specific to that +environment with the following suffixes added as appropriate: +.TP 7 +_CFLAGS +To get the C compiler flags. +.TP 7 +_LDFLAGS +To get the linker/loader flags. +.TP 7 +_LIBS +To get the libraries. +.sp +.LP +This requirement may be removed in a future version of IEEE\ Std\ 1003.1. +.LP +When this utility processes a file containing a function called \fImain\fP(), +it shall be defined with a return type equivalent +to \fBint\fP. Using return from the initial call to \fImain\fP() shall +be equivalent (other than with respect to language scope +issues) to calling \fIexit\fP() with the returned value. Reaching +the end of the initial call +to \fImain\fP() shall be equivalent to calling \fIexit\fP(0). The +implementation shall not declare a prototype for this +function. +.LP +Implementations provide configuration strings for C compiler flags, +linker/loader flags, and libraries for each supported +environment. When an application needs to use a specific programming +environment rather than the implementation default programming +environment while compiling, the application shall first verify that +the implementation supports the desired environment. If the +desired programming environment is supported, the application shall +then invoke \fIc99\fP with the appropriate C compiler flags as +the first options for the compile, the appropriate linker/loader flags +after any other options but before any operands, and the +appropriate libraries at the end of the operands. +.LP +Conforming applications shall not attempt to link together object +files compiled for different programming models. Applications +shall also be aware that binary data placed in shared memory or in +files might not be recognized by applications built for other +programming models. +.br +.sp +.ce 1 +\fBTable: Programming Environments: \fIc99\fP and \fIcc\fP Arguments\fP +.TS C +center; l1 l1 l. +\fBProgramming Environment\fP \fB\ \fP \fB\fIc99\fP and \fIcc\fP Arguments\fP +\fB\fIgetconf\fP Name\fP \fBUse\fP \fB\fIgetconf\fP Name\fP +_POSIX_V6_ILP32_OFF32 C Compiler Flags POSIX_V6_ILP32_OFF32_CFLAGS +\ Linker/Loader Flags POSIX_V6_ILP32_OFF32_LDFLAGS +\ Libraries POSIX_V6_ILP32_OFF32_LIBS +_POSIX_V6_ILP32_OFFBIG C Compiler Flags POSIX_V6_ILP32_OFFBIG_CFLAGS +\ Linker/Loader Flags POSIX_V6_ILP32_OFFBIG_LDFLAGS +\ Libraries POSIX_V6_ILP32_OFFBIG_LIBS +_POSIX_V6_LP64_OFF64 C Compiler Flags POSIX_V6_LP64_OFF64_CFLAGS +\ Linker/Loader Flags POSIX_V6_LP64_OFF64_LDFLAGS +\ Libraries POSIX_V6_LP64_OFF64_LIBS +_POSIX_V6_LPBIG_OFFBIG C Compiler Flags POSIX_V6_LPBIG_OFFBIG_CFLAGS +\ Linker/Loader Flags POSIX_V6_LPBIG_OFFBIG_LDFLAGS +\ Libraries POSIX_V6_LPBIG_OFFBIG_LIBS +.TE +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful compilation or link edit. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +When \fIc99\fP encounters a compilation error that causes an object +file not to be created, it shall write a diagnostic to +standard error and continue to compile other source code operands, +but it shall not perform the link phase and return a non-zero +exit status. If the link edit is unsuccessful, a diagnostic message +shall be written to standard error and \fIc99\fP exits with a +non-zero status. A conforming application shall rely on the exit status +of \fIc99\fP, rather than on the existence or mode of the +executable file. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Since the \fIc99\fP utility usually creates files in the current directory +during the compilation process, it is typically +necessary to run the \fIc99\fP utility in a directory in which a file +can be created. +.LP +On systems providing POSIX Conformance (see the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Chapter 2, Conformance), \fIc99\fP is required +only with the C-Language Development +option; XSI-conformant systems always provide \fIc99\fP. +.LP +Some historical implementations have created \fB.o\fP files when \fB-c\fP +is not specified and more than one source file is +given. Since this area is left unspecified, the application cannot +rely on \fB.o\fP files being created, but it also must be +prepared for any related \fB.o\fP files that already exist being deleted +at the completion of the link edit. +.LP +Some historical implementations have permitted \fB-L\fP options to +be interspersed with \fB-l\fP operands on the command line. +For an application to compile consistently on systems that do not +behave like this, it is necessary for a conforming application to +supply all \fB-L\fP options before any of the \fB-l\fP options. +.LP +There is the possible implication that if a user supplies versions +of the standard functions (before they would be encountered +by an implicit \fB-l\ c\fP or explicit \fB-l\ m\fP), that those versions +would be used in place of the standard versions. +There are various reasons this might not be true (functions defined +as macros, manipulations for clean name space, and so on), so +the existence of files named in the same manner as the standard libraries +within the \fB-L\fP directories is explicitly stated to +produce unspecified behavior. +.LP +All of the functions specified in the System Interfaces volume of +IEEE\ Std\ 1003.1-2001 may be made visible by +implementations when the Standard C Library is searched. Conforming +applications must explicitly request searching the other +standard libraries when functions made visible by those libraries +are used. +.SH EXAMPLES +.IP " 1." 4 +The following usage example compiles \fBfoo.c\fP and creates the executable +file \fBfoo\fP: +.sp +.RS +.nf + +\fBc99 -o foo foo.c +\fP +.fi +.RE +.LP +The following usage example compiles \fBfoo.c\fP and creates the object +file \fBfoo.o\fP: +.sp +.RS +.nf + +\fBc99 -c foo.c +\fP +.fi +.RE +.LP +The following usage example compiles \fBfoo.c\fP and creates the executable +file \fBa.out\fP: +.sp +.RS +.nf + +\fBc99 foo.c +\fP +.fi +.RE +.LP +The following usage example compiles \fBfoo.c\fP, links it with \fBbar.o\fP, +and creates the executable file \fBa.out\fP. It +may also create and leave \fBfoo.o\fP: +.sp +.RS +.nf + +\fBc99 foo.c bar.o +\fP +.fi +.RE +.LP +.IP " 2." 4 +The following example shows how an application using threads interfaces +can test for support of and use a programming +environment supporting 32-bit \fBint\fP, \fBlong\fP, and \fBpointer\fP +types and an \fBoff_t\fP type using at least 64 +bits: +.sp +.RS +.nf + +\fBif [ $(getconf _POSIX_V6_ILP32_OFFBIG) != "-1" ] +then + c99 $(getconf POSIX_V6_ILP32_OFFBIG_CFLAGS) -D_XOPEN_SOURCE=600 \\ + $(getconf POSIX_V6_ILP32_OFFBIG_LDFLAGS) foo.c -o foo \\ + $(getconf POSIX_V6_ILP32_OFFBIG_LIBS) -l pthread +else + echo ILP32_OFFBIG programming environment not supported + exit 1 +fi +\fP +.fi +.RE +.LP +.IP " 3." 4 +The following examples clarify the use and interactions of \fB-L\fP +options and \fB-l\fP operands. +.LP +Consider the case in which module \fBa.c\fP calls function \fIf\fP() +in library \fBlibQ.a\fP, and module \fBb.c\fP calls +function \fIg\fP() in library \fBlibp.a\fP. Assume that both libraries +reside in \fB/a/b/c\fP. The command line to compile and +link in the desired way is: +.sp +.RS +.nf + +\fBc99 -L /a/b/c main.o a.c -l Q b.c -l p +\fP +.fi +.RE +.LP +In this case the \fB-l\ Q\fP operand need only precede the first \fB-l\ p\fP +operand, since both \fBlibQ.a\fP and +\fBlibp.a\fP reside in the same directory. +.LP +Multiple \fB-L\fP operands can be used when library name collisions +occur. Building on the previous example, suppose that the +user wants to use a new \fBlibp.a\fP, in \fB/a/a/a\fP, but still wants +\fIf\fP() from \fB/a/b/c/libQ.a\fP: +.sp +.RS +.nf + +\fBc99 -L /a/a/a -L /a/b/c main.o a.c -l Q b.c -l p +\fP +.fi +.RE +.LP +In this example, the linker searches the \fB-L\fP options in the order +specified, and finds \fB/a/a/a/libp.a\fP before +\fB/a/b/c/libp.a\fP when resolving references for \fBb.c\fP. The order +of the \fB-l\fP operands is still important, however. +.LP +.IP " 4." 4 +The following example shows how an application can use a programming +environment where the widths of the following types: +\fBblksize_t\fP, \fBcc_t\fP, \fBmode_t\fP, \fBnfds_t\fP, \fBpid_t\fP, +\fBptrdiff_t\fP, \fBsize_t\fP, +\fBspeed_t\fP, \fBssize_t\fP, \fBsuseconds_t\fP, \fBtcflag_t\fP, \fBuseconds_t\fP, +\fBwchar_t\fP, \fBwint_t\fP +.LP +are no greater than the width of type \fBlong\fP: +.sp +.RS +.nf + +\fB# First choose one of the listed environments ... +.sp + +# ... if there are no additional constraints, the first one will do: +CENV=$(getconf _POSIX_V6_WIDTH_RESTRICTED_ENVS | head -n l) +.sp + +# ... or, if an environment that supports large files is preferred, +# look for names that contain "OFF64" or "OFFBIG". (This chooses +# the last one in the list if none match.) +for CENV in $(getconf _POSIX_V6_WIDTH_RESTRICTED_ENVS) +do + case $CENV in + *OFF64*|*OFFBIG*) break ;; + esac +done +.sp + +# The chosen environment name can now be used like this: +.sp + +c99 $(getconf ${CENV}_CFLAGS) -D _POSIX_C_SOURCE=200112L \\ +$(getconf ${CENV}_LDFLAGS) foo.c -o foo \\ +$(getconf ${CENV}_LIBS) +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +The \fIc99\fP utility is based on the \fIc89\fP utility originally +introduced in the ISO\ POSIX-2:1993 standard. +.LP +Some of the changes from \fIc89\fP include the modification to the +contents of the Standard Libraries section to account for +new headers and options; for example, \fI\fP added to the +\fB-l\ rt\fP +operand, and the \fB-l\fP trace operand added for the Tracing functions. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIFile Read, Write, and Creation\fP , \fIar\fP , \fIgetconf\fP , +\fImake\fP , \fInm\fP , \fIstrip\fP , \fIumask\fP() , the System Interfaces +volume of +IEEE\ Std\ 1003.1-2001, \fIexec\fP, \fIsysconf\fP(), the Base Definitions +volume +of IEEE\ Std\ 1003.1-2001, Chapter 13, Headers +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/cal.1p b/man1p/cal.1p new file mode 100644 index 000000000..6ac3eaf41 --- /dev/null +++ b/man1p/cal.1p @@ -0,0 +1,144 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CAL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cal +.SH NAME +cal \- print a calendar +.SH SYNOPSIS +.LP +\fBcal\fP \fB[[\fP\fImonth\fP\fB]\fP \fIyear\fP \fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIcal\fP utility shall write a calendar to standard output using +the Julian calendar for dates from January 1, 1 through +September 2, 1752 and the Gregorian calendar for dates from September +14, 1752 through December 31, 9999 as though the Gregorian +calendar had been adopted on September 14, 1752. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fImonth\fP +Specify the month to be displayed, represented as a decimal integer +from 1 (January) to 12 (December). The default shall be the +current month. +.TP 7 +\fIyear\fP +Specify the year for which the calendar is displayed, represented +as a decimal integer from 1 to 9999. The default shall be the +current year. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIcal\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, +and informative messages written to standard output. +.TP 7 +\fILC_TIME\fP +Determine the format and contents of the calendar. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITZ\fP +Determine the timezone used to calculate the value of the current +month. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall be used to display the calendar, in an unspecified +format. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Note that: +.sp +.RS +.nf + +\fBcal 83 +\fP +.fi +.RE +.LP +refers to A.D. 83, not 1983. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +A future version of IEEE\ Std\ 1003.1-2001 may support locale-specific +recognition of the date of adoption of the +Gregorian calendar. +.SH SEE ALSO +.LP +None. +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/cat.1p b/man1p/cat.1p new file mode 100644 index 000000000..c2184a1be --- /dev/null +++ b/man1p/cat.1p @@ -0,0 +1,276 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cat +.SH NAME +cat \- concatenate and print files +.SH SYNOPSIS +.LP +\fBcat\fP \fB[\fP\fB-u\fP\fB][\fP\fIfile\fP \fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIcat\fP utility shall read files in sequence and shall write +their contents to the standard output in the same +sequence. +.SH OPTIONS +.LP +The \fIcat\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-u\fP +Write bytes from the input file to the standard output without delay +as each is read. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of an input file. If no \fIfile\fP operands are specified, +the standard input shall be used. If a \fIfile\fP is +\fB'-'\fP , the \fIcat\fP utility shall read from the standard input +at that point in the sequence. The \fIcat\fP utility +shall not close and reopen standard input when it is referenced in +this way, but shall accept multiple occurrences of \fB'-'\fP +as a \fIfile\fP operand. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified, or if a \fIfile\fP operand is \fB'-'\fP . +See the INPUT FILES section. +.SH INPUT FILES +.LP +The input files can be any file type. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIcat\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall contain the sequence of bytes read from +the input files. Nothing else shall be written to the standard +output. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All input files were output successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fB-u\fP option has value in prototyping non-blocking reads from +FIFOs. The intent is to support the following +sequence: +.sp +.RS +.nf + +\fBmkfifo foo +cat -u foo > /dev/tty13 & +cat -u > foo +\fP +.fi +.RE +.LP +It is unspecified whether standard output is or is not buffered in +the default case. This is sometimes of interest when standard +output is associated with a terminal, since buffering may delay the +output. The presence of the \fB-u\fP option guarantees that +unbuffered I/O is available. It is implementation-defined whether +the \fIcat\fP utility buffers output if the \fB-u\fP option is +not specified. Traditionally, the \fB-u\fP option is implemented using +the equivalent of the \fIsetvbuf\fP() function defined in the System +Interfaces volume of +IEEE\ Std\ 1003.1-2001. +.SH EXAMPLES +.LP +The following command: +.sp +.RS +.nf + +\fBcat myfile +\fP +.fi +.RE +.LP +writes the contents of the file \fBmyfile\fP to standard output. +.LP +The following command: +.sp +.RS +.nf + +\fBcat doc1 doc2 > doc.all +\fP +.fi +.RE +.LP +concatenates the files \fBdoc1\fP and \fBdoc2\fP and writes the result +to \fBdoc.all\fP. +.LP +Because of the shell language mechanism used to perform output redirection, +a command such as this: +.sp +.RS +.nf + +\fBcat doc doc.end > doc +\fP +.fi +.RE +.LP +causes the original data in \fBdoc\fP to be lost. +.LP +The command: +.sp +.RS +.nf + +\fBcat start - middle - end > file +\fP +.fi +.RE +.LP +when standard input is a terminal, gets two arbitrary pieces of input +from the terminal with a single invocation of \fIcat\fP. +Note, however, that if standard input is a regular file, this would +be equivalent to the command: +.sp +.RS +.nf + +\fBcat start - middle /dev/null end > file +\fP +.fi +.RE +.LP +because the entire contents of the file would be consumed by \fIcat\fP +the first time \fB'-'\fP was used as a \fIfile\fP +operand and an end-of-file condition would be detected immediately +when \fB'-'\fP was referenced the second time. +.SH RATIONALE +.LP +Historical versions of the \fIcat\fP utility include the options \fB-e\fP, +\fB-t\fP, and \fB-v\fP, which permit the ends of +lines, s, and invisible characters, respectively, to be rendered +visible in the output. The standard developers omitted +these options because they provide too fine a degree of control over +what is made visible, and similar output can be obtained using +a command such as: +.sp +.RS +.nf + +\fBsed -n -e 's/$/$/' -e l pathname +\fP +.fi +.RE +.LP +The \fB-s\fP option was omitted because it corresponds to different +functions in BSD and System V-based systems. The BSD +\fB-s\fP option to squeeze blank lines can be accomplished by the +shell script shown in the following example: +.sp +.RS +.nf + +\fBsed -n ' +# Write non-empty lines. +/./ { + p + d + } +# Write a single empty line, then look for more empty lines. +/^$/ p +# Get next line, discard the held (empty line), +# and look for more empty lines. +:Empty +/^$/ { + N + s/.// + b Empty + } +# Write the non-empty line before going back to search +# for the first in a set of empty lines. + p +' +\fP +.fi +.RE +.LP +The System V \fB-s\fP option to silence error messages can be accomplished +by redirecting the standard error. Note that the BSD +documentation for \fIcat\fP uses the term "blank line" to mean the +same as the POSIX "empty line'': a line consisting only of a +. +.LP +The BSD \fB-n\fP option was omitted because similar functionality +can be obtained from the \fB-n\fP option of the \fIpr\fP utility. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImore\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIsetvbuf\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/cd.1p b/man1p/cd.1p new file mode 100644 index 000000000..4729ac48a --- /dev/null +++ b/man1p/cd.1p @@ -0,0 +1,350 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cd +.SH NAME +cd \- change the working directory +.SH SYNOPSIS +.LP +\fBcd\fP \fB[\fP\fB-L | -P\fP\fB] [\fP\fIdirectory\fP\fB]\fP\fB +.br +.sp +cd - +.br +\fP +.SH DESCRIPTION +.LP +The \fIcd\fP utility shall change the working directory of the current +shell execution environment (see \fIShell Execution Environment\fP +) by executing the following steps in sequence. (In the +following steps, the symbol \fBcurpath\fP represents an intermediate +value used to simplify the description of the algorithm used +by \fIcd\fP. There is no requirement that \fBcurpath\fP be made visible +to the application.) +.IP " 1." 4 +If no \fIdirectory\fP operand is given and the \fIHOME\fP environment +variable is empty or undefined, the default behavior is +implementation-defined and no further steps shall be taken. +.LP +.IP " 2." 4 +If no \fIdirectory\fP operand is given and the \fIHOME\fP environment +variable is set to a non-empty value, the \fIcd\fP +utility shall behave as if the directory named in the \fIHOME\fP environment +variable was specified as the \fIdirectory\fP +operand. +.LP +.IP " 3." 4 +If the \fIdirectory\fP operand begins with a slash character, set +\fBcurpath\fP to the operand and proceed to step 7. +.LP +.IP " 4." 4 +If the first component of the \fIdirectory\fP operand is dot or dot-dot, +proceed to step 6. +.LP +.IP " 5." 4 +Starting with the first pathname in the colon-separated pathnames +of \fICDPATH\fP (see the ENVIRONMENT VARIABLES section) if +the pathname is non-null, test if the concatenation of that pathname, +a slash character, and the \fIdirectory\fP operand names a +directory. If the pathname is null, test if the concatenation of dot, +a slash character, and the operand names a directory. In +either case, if the resulting string names an existing directory, +set \fBcurpath\fP to that string and proceed to step 7. +Otherwise, repeat this step with the next pathname in \fICDPATH\fP +until all pathnames have been tested. +.LP +.IP " 6." 4 +Set \fBcurpath\fP to the string formed by the concatenation of the +value of \fIPWD ,\fP a slash character, and the +operand. +.LP +.IP " 7." 4 +If the \fB-P\fP option is in effect, the \fIcd\fP utility shall perform +actions equivalent to the \fIchdir\fP() function, called with \fBcurpath\fP +as the \fIpath\fP argument. If these actions +succeed, the \fIPWD\fP environment variable shall be set to an absolute +pathname for the current working directory and shall not +contain filename components that, in the context of pathname resolution, +refer to a file of type symbolic link. If there is +insufficient permission on the new directory, or on any parent of +that directory, to determine the current working directory, the +value of the \fIPWD\fP environment variable is unspecified. If the +actions equivalent to \fIchdir\fP() fail for any reason, the \fIcd\fP +utility shall display an appropriate error message +and not alter the \fIPWD\fP environment variable. Whether the actions +equivalent to \fIchdir\fP() succeed or fail, no further steps shall +be taken. +.LP +.IP " 8." 4 +The \fBcurpath\fP value shall then be converted to canonical form +as follows, considering each component from beginning to end, +in sequence: +.RS +.IP " a." 4 +Dot components and any slashes that separate them from the next component +shall be deleted. +.LP +.IP " b." 4 +For each dot-dot component, if there is a preceding component and +it is neither root nor dot-dot, the preceding component, all +slashes separating the preceding component from dot-dot, dot-dot and +all slashes separating dot-dot from the following component +shall be deleted. +.LP +.IP " c." 4 +An implementation may further simplify \fBcurpath\fP by removing any +trailing slash characters that are not also leading +slashes, replacing multiple non-leading consecutive slashes with a +single slash, and replacing three or more leading slashes with a +single slash. If, as a result of this canonicalization, the \fBcurpath\fP +variable is null, no further steps shall be taken. +.LP +.RE +.LP +.IP " 9." 4 +The \fIcd\fP utility shall then perform actions equivalent to the +\fIchdir\fP() function +called with \fBcurpath\fP as the \fIpath\fP argument. If these actions +failed for any reason, the \fIcd\fP utility shall display +an appropriate error message and no further steps shall be taken. +The \fIPWD\fP environment variable shall be set to +\fBcurpath\fP. +.LP +.LP +If, during the execution of the above steps, the \fIPWD\fP environment +variable is changed, the \fIOLDPWD\fP environment +variable shall also be changed to the value of the old working directory +(that is the current working directory immediately prior +to the call to \fIcd\fP). +.SH OPTIONS +.LP +The \fIcd\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported by the implementation: +.TP 7 +\fB-L\fP +Handle the operand dot-dot logically; symbolic link components shall +not be resolved before dot-dot components are processed +(see steps 8. and 9. in the DESCRIPTION). +.TP 7 +\fB-P\fP +Handle the operand dot-dot physically; symbolic link components shall +be resolved before dot-dot components are processed (see +step 7. in the DESCRIPTION). +.sp +.LP +If both \fB-L\fP and \fB-P\fP options are specified, the last of these +options shall be used and all others ignored. If +neither \fB-L\fP nor \fB-P\fP is specified, the operand shall be handled +dot-dot logically; see the DESCRIPTION. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIdirectory\fP +An absolute or relative pathname of the directory that shall become +the new working directory. The interpretation of a relative +pathname by \fIcd\fP depends on the \fB-L\fP option and the \fICDPATH\fP +and \fIPWD\fP environment variables. If +\fIdirectory\fP is an empty string, the results are unspecified. +.TP 7 +- +When a hyphen is used as the operand, this shall be equivalent to +the command: +.sp +.RS +.nf + +\fBcd "$OLDPWD" && pwd +\fP +.fi +.RE +.LP +which changes to the previous working directory and then writes its +name. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIcd\fP: +.TP 7 +\fICDPATH\fP +A colon-separated list of pathnames that refer to directories. The +\fIcd\fP utility shall use this list in its attempt to +change the directory, as described in the DESCRIPTION. An empty string +in place of a directory pathname represents the current +directory. If \fICDPATH\fP is not set, it shall be treated as if it +were an empty string. +.TP 7 +\fIHOME\fP +The name of the directory, used when no \fIdirectory\fP operand is +specified. +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIOLDPWD\fP +A pathname of the previous working directory, used by \fIcd\fP \fB-\fP. +.TP 7 +\fIPWD\fP +This variable shall be set as specified in the DESCRIPTION. If an +application sets or unsets the value of \fIPWD ,\fP the +behavior of \fIcd\fP is unspecified. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If a non-empty directory name from \fICDPATH\fP is used, or if \fIcd\fP +\fB-\fP is used, an absolute pathname of the new +working directory shall be written to the standard output as follows: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fInew directory\fP\fB> +\fP +.fi +.RE +.LP +Otherwise, there shall be no output. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The directory was successfully changed. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +The working directory shall remain unchanged. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Since \fIcd\fP affects the current shell execution environment, it +is always provided as a shell regular built-in. If it is +called in a subshell or separate utility execution environment, such +as one of the following: +.sp +.RS +.nf + +\fB(cd /tmp) +nohup cd +find . -exec cd {} \\; +\fP +.fi +.RE +.LP +it does not affect the working directory of the caller's environment. +.LP +The user must have execute (search) permission in \fIdirectory\fP +in order to change to it. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The use of the \fICDPATH\fP was introduced in the System V shell. +Its use is analogous to the use of the \fIPATH\fP variable +in the shell. The BSD C shell used a shell parameter \fIcdpath\fP +for this purpose. +.LP +A common extension when \fIHOME\fP is undefined is to get the login +directory from the user database for the invoking user. +This does not occur on System V implementations. +.LP +Some historical shells, such as the KornShell, took special actions +when the directory name contained a dot-dot component, +selecting the logical parent of the directory, rather than the actual +parent directory; that is, it moved up one level toward the +\fB'/'\fP in the pathname, remembering what the user typed, rather +than performing the equivalent of: +.sp +.RS +.nf + +\fBchdir(".."); +\fP +.fi +.RE +.LP +In such a shell, the following commands would not necessarily produce +equivalent output for all directories: +.sp +.RS +.nf + +\fBcd .. && ls ls .. +\fP +.fi +.RE +.LP +This behavior is now the default. It is not consistent with the definition +of dot-dot in most historical practice; that is, +while this behavior has been optionally available in the KornShell, +other shells have historically not supported this +functionality. The logical pathname is stored in the \fIPWD\fP environment +variable when the \fIcd\fP utility completes and this +value is used to construct the next directory name if \fIcd\fP is +invoked with the \fB-L\fP option. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Execution Environment\fP , \fIpwd\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIchdir\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/cflow.1p b/man1p/cflow.1p new file mode 100644 index 000000000..2e64995ff --- /dev/null +++ b/man1p/cflow.1p @@ -0,0 +1,250 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CFLOW" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cflow +.SH NAME +cflow \- generate a C-language flowgraph (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBcflow\fP \fB[\fP\fB-r\fP\fB][\fP\fB-d\fP \fInum\fP\fB][\fP\fB-D\fP +\fIname\fP\fB[\fP\fB=\fP\fIdef\fP\fB]]\fP \fB...\fP \fB[\fP\fB-i\fP +\fIincl\fP\fB][\fP\fB-I\fP +\fIdir\fP\fB]\fP \fB... +.br +\ \ \ \ \ \ \fP \fB[\fP\fB-U\fP \fIdir\fP\fB]\fP \fB...\fP \fIfile\fP +\fB\&... \fP +.SH DESCRIPTION +.LP +The \fIcflow\fP utility shall analyze a collection of object files +or assembler, C-language, \fIlex\fP, or \fIyacc\fP source files, and +attempt to build a +graph, written to standard output, charting the external references. +.SH OPTIONS +.LP +The \fIcflow\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that the order of the \fB-D\fP, +\fB-I\fP, and \fB-U\fP options (which are identical to their interpretation +by \fIc99\fP) is +significant. +.LP +The following options shall be supported: +.TP 7 +\fB-d\ \fP \fInum\fP +Indicate the depth at which the flowgraph is cut off. The application +shall ensure that the argument \fInum\fP is a decimal +integer. By default this is a very large number (typically greater +than 32000). Attempts to set the cut-off depth to a non-positive +integer shall be ignored. +.TP 7 +\fB-i\ \fP \fIincl\fP +Increase the number of included symbols. The \fIincl\fP option-argument +is one of the following characters: +.TP 7 +\fIx\fP +.RS +Include external and static data symbols. The default shall be to +include only functions in the flowgraph. +.RE +.TP 7 +\fB_\fP +.RS +(Underscore) Include names that begin with an underscore. The default +shall be to exclude these functions (and data if +\fB-i\ x\fP is used). +.RE +.sp +.TP 7 +\fB-r\fP +Reverse the caller:callee relationship, producing an inverted listing +showing the callers of each function. The listing shall +also be sorted in lexicographical order by callee. +.sp +.SH OPERANDS +.LP +The following operand is supported: +.TP 7 +\fIfile\fP +The pathname of a file for which a graph is to be generated. Filenames +suffixed by \fB.l\fP shall shall be taken to be \fIlex\fP input, \fB.y\fP +as \fIyacc\fP input, \fB.c\fP +as \fIc99\fP input, and \fB.i\fP as the output of \fIc99\fP \fB-E\fP. +Such files shall be processed as appropriate, determined by their +suffix. +.LP +Files suffixed by \fB.s\fP (conventionally assembler source) may have +more limited information extracted from them. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +The input files shall be object files or assembler, C-language, \fIlex\fP, +or \fIyacc\fP source files. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIcflow\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the ordering of the output when the \fB-r\fP +option is used. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The flowgraph written to standard output shall be formatted as follows: +.sp +.RS +.nf + +\fB"%d %s:%s\\n", <\fP\fIreference number\fP\fB>, <\fP\fIglobal\fP\fB>, <\fP\fIdefinition\fP\fB> +\fP +.fi +.RE +.LP +Each line of output begins with a reference (that is, line) number, +followed by indentation of at least one column position per +level. This is followed by the name of the global, a colon, and its +definition. Normally globals are only functions not defined as +an external or beginning with an underscore; see the OPTIONS section +for the \fB-i\fP inclusion option. For information extracted +from C-language source, the definition consists of an abstract type +declaration (for example, \fBchar *\fP) and, delimited by +angle brackets, the name of the source file and the line number where +the definition was found. Definitions extracted from object +files indicate the filename and location counter under which the symbol +appeared (for example, \fItext\fP). +.LP +Once a definition of a name has been written, subsequent references +to that name contain only the reference number of the line +where the definition can be found. For undefined references, only +\fB"<>"\fP shall be written. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Files produced by \fIlex\fP and \fIyacc\fP cause the +reordering of line number declarations, and this can confuse \fIcflow\fP. +To obtain proper results, the input of \fIyacc\fP or \fIlex\fP must +be directed to \fIcflow\fP. +.SH EXAMPLES +.LP +Given the following in \fBfile.c\fP: +.sp +.RS +.nf + +\fBint i; +int f(); +int g(); +int h(); +int +main() +{ + f(); + g(); + f(); +} +int +f() +{ + i = h(); +} +\fP +.fi +.RE +.LP +The command: +.sp +.RS +.nf + +\fBcflow -i x file.c +\fP +.fi +.RE +.LP +produces the output: +.sp +.RS +.nf + +\fB1 main: int(), +2 f: int(), +3 h: <> +4 i: int, +5 g: <> +\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIc99\fP , \fIlex\fP , \fIyacc\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/chgrp.1p b/man1p/chgrp.1p new file mode 100644 index 000000000..25c91f557 --- /dev/null +++ b/man1p/chgrp.1p @@ -0,0 +1,212 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CHGRP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" chgrp +.SH NAME +chgrp \- change the file group ownership +.SH SYNOPSIS +.LP +\fBchgrp\fP \fB[\fP\fB-hR\fP\fB]\fP \fIgroup file\fP \fB... +.br +.sp +chgrp -R\fP \fB[\fP\fB-H | -L | -P\fP \fB]\fP \fIgroup file\fP \fB... +.br +\fP +.SH DESCRIPTION +.LP +The \fIchgrp\fP utility shall set the group ID of the file named by +each \fIfile\fP operand to the group ID specified by the +\fIgroup\fP operand. +.LP +For each \fIfile\fP operand, or, if the \fB-R\fP option is used, each +file encountered while walking the directory trees +specified by the \fIfile\fP operands, the \fIchgrp\fP utility shall +perform actions equivalent to the \fIchown\fP() function defined in +the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +called with the following arguments: +.IP " *" 3 +The \fIfile\fP operand shall be used as the \fIpath\fP argument. +.LP +.IP " *" 3 +The user ID of the file shall be used as the \fIowner\fP argument. +.LP +.IP " *" 3 +The specified group ID shall be used as the \fIgroup\fP argument. +.LP +.LP +Unless \fIchgrp\fP is invoked by a process with appropriate privileges, +the set-user-ID and set-group-ID bits of a regular file +shall be cleared upon successful completion; the set-user-ID and set-group-ID +bits of other file types may be cleared. +.SH OPTIONS +.LP +The \fIchgrp\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported by the implementation: +.TP 7 +\fB-h\fP +If the system supports group IDs for symbolic links, for each \fIfile\fP +operand that names a file of type symbolic link, +\fIchgrp\fP shall attempt to set the group ID of the symbolic link +instead of the file referenced by the symbolic link. If the +system does not support group IDs for symbolic links, for each \fIfile\fP +operand that names a file of type symbolic link, +\fIchgrp\fP shall do nothing more with the current file and shall +go on to any remaining files. +.TP 7 +\fB-H\fP +If the \fB-R\fP option is specified and a symbolic link referencing +a file of type directory is specified on the command line, +\fIchgrp\fP shall change the group of the directory referenced by +the symbolic link and all files in the file hierarchy below +it. +.TP 7 +\fB-L\fP +If the \fB-R\fP option is specified and a symbolic link referencing +a file of type directory is specified on the command line +or encountered during the traversal of a file hierarchy, \fIchgrp\fP +shall change the group of the directory referenced by the +symbolic link and all files in the file hierarchy below it. +.TP 7 +\fB-P\fP +If the \fB-R\fP option is specified and a symbolic link is specified +on the command line or encountered during the traversal +of a file hierarchy, \fIchgrp\fP shall change the group ID of the +symbolic link if the system supports this operation. The +\fIchgrp\fP utility shall not follow the symbolic link to any other +part of the file hierarchy. +.TP 7 +\fB-R\fP +Recursively change file group IDs. For each \fIfile\fP operand that +names a directory, \fIchgrp\fP shall change the group of +the directory and all files in the file hierarchy below it. Unless +a \fB-H\fP, \fB-L\fP, or \fB-P\fP option is specified, it is +unspecified which of these options will be used as the default. +.sp +.LP +Specifying more than one of the mutually-exclusive options \fB-H\fP, +\fB-L\fP, and \fB-P\fP shall not be considered an error. +The last option specified shall determine the behavior of the utility. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIgroup\fP +A group name from the group database or a numeric group ID. Either +specifies a group ID to be given to each file named by one +of the \fIfile\fP operands. If a numeric \fIgroup\fP operand exists +in the group database as a group name, the group ID number +associated with that group name is used as the group ID. +.TP 7 +\fIfile\fP +A pathname of a file whose group ID is to be modified. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIchgrp\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The utility executed successfully and all requested changes were made. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Only the owner of a file or the user with appropriate privileges may +change the owner or group of a file. +.LP +Some implementations restrict the use of \fIchgrp\fP to a user with +appropriate privileges when the \fIgroup\fP specified is +not the effective group ID or one of the supplementary group IDs of +the calling process. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The System V and BSD versions use different exit status codes. Some +implementations used the exit status as a count of the +number of errors that occurred; this practice is unworkable since +it can overflow the range of valid exit status values. The +standard developers chose to mask these by specifying only 0 and >0 +as exit values. +.LP +The functionality of \fIchgrp\fP is described substantially through +references to \fIchown\fP(). In this way, there is no duplication +of effort required for describing the +interactions of permissions, multiple groups, and so on. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchmod\fP() , \fIchown\fP() , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIchown\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/chmod.1p b/man1p/chmod.1p new file mode 100644 index 000000000..e5438eb24 --- /dev/null +++ b/man1p/chmod.1p @@ -0,0 +1,488 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CHMOD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" chmod +.SH NAME +chmod \- change the file modes +.SH SYNOPSIS +.LP +\fBchmod\fP \fB[\fP\fB-R\fP\fB]\fP \fImode file\fP \fB...\fP +.SH DESCRIPTION +.LP +The \fIchmod\fP utility shall change any or all of the file mode bits +of the file named by each \fIfile\fP operand in the way +specified by the \fImode\fP operand. +.LP +It is implementation-defined whether and how the \fIchmod\fP utility +affects any alternate or additional file access control +mechanism (see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 4.4, File Access Permissions) being used for the specified +file. +.LP +Only a process whose effective user ID matches the user ID of the +file, or a process with the appropriate privileges, shall be +permitted to change the file mode bits of a file. +.SH OPTIONS +.LP +The \fIchmod\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-R\fP +Recursively change file mode bits. For each \fIfile\fP operand that +names a directory, \fIchmod\fP shall change the file mode +bits of the directory and all files in the file hierarchy below it. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fImode\fP +Represents the change to be made to the file mode bits of each file +named by one of the \fIfile\fP operands; see the EXTENDED +DESCRIPTION section. +.TP 7 +\fIfile\fP +A pathname of a file whose file mode bits shall be modified. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIchmod\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +The \fImode\fP operand shall be either a \fIsymbolic_mode\fP expression +or a non-negative octal integer. The +\fIsymbolic_mode\fP form is described by the grammar later in this +section. +.LP +Each \fBclause\fP shall specify an operation to be performed on the +current file mode bits of each \fIfile\fP. The operations +shall be performed on each \fIfile\fP in the order in which the \fBclause\fPs +are specified. +.LP +The \fBwho\fP symbols \fBu\fP, \fBg\fP, and \fBo\fP shall specify +the \fIuser\fP, \fIgroup\fP, and \fIother\fP parts of +the file mode bits, respectively. A \fBwho\fP consisting of the symbol +\fBa\fP shall be equivalent to \fBugo\fP. +.LP +The \fBperm\fP symbols \fBr\fP, \fBw\fP, and \fBx\fP represent the +\fIread\fP, \fIwrite\fP, and \fIexecute\fP/ +\fIsearch\fP portions of file mode bits, respectively. The \fBperm\fP +symbol \fBs\fP shall represent the +\fIset-user-ID-on-execution\fP (when \fBwho\fP contains or implies +\fBu\fP) and \fIset-group-ID-on-execution\fP (when +\fBwho\fP contains or implies \fBg\fP) bits. +.LP +The \fBperm\fP symbol \fBX\fP shall represent the execute/search portion +of the file mode bits if the file is a directory or +if the current (unmodified) file mode bits have at least one of the +execute bits (S_IXUSR, S_IXGRP, or S_IXOTH) set. It shall be +ignored if the file is not a directory and none of the execute bits +are set in the current file mode bits. +.LP +The \fBpermcopy\fP symbols \fBu\fP, \fBg\fP, and \fBo\fP shall represent +the current permissions associated with the user, +group, and other parts of the file mode bits, respectively. For the +remainder of this section, \fBperm\fP refers to the +non-terminals \fBperm\fP and \fBpermcopy\fP in the grammar. +.LP +If multiple \fBactionlist\fPs are grouped with a single \fBwholist\fP +in the grammar, each \fBactionlist\fP shall be applied +in the order specified with that \fBwholist\fP. The \fIop\fP symbols +shall represent the operation performed, as follows: +.TP 7 +\fB+\fP +If \fBperm\fP is not specified, the \fB'+'\fP operation shall not +change the file mode bits. +.LP +If \fBwho\fP is not specified, the file mode bits represented by \fBperm\fP +for the owner, group, and other permissions, +except for those with corresponding bits in the file mode creation +mask of the invoking process, shall be set. +.LP +Otherwise, the file mode bits represented by the specified \fBwho\fP +and \fBperm\fP values shall be set. +.TP 7 +\fB-\fP +If \fBperm\fP is not specified, the \fB'-'\fP operation shall not +change the file mode bits. +.LP +If \fBwho\fP is not specified, the file mode bits represented by \fBperm\fP +for the owner, group, and other permissions, +except for those with corresponding bits in the file mode creation +mask of the invoking process, shall be cleared. +.LP +Otherwise, the file mode bits represented by the specified \fBwho\fP +and \fBperm\fP values shall be cleared. +.TP 7 +\fB=\fP +Clear the file mode bits specified by the \fBwho\fP value, or, if +no \fBwho\fP value is specified, all of the file mode bits +specified in this volume of IEEE\ Std\ 1003.1-2001. +.LP +If \fBperm\fP is not specified, the \fB'='\fP operation shall make +no further modifications to the file mode bits. +.LP +If \fBwho\fP is not specified, the file mode bits represented by \fBperm\fP +for the owner, group, and other permissions, +except for those with corresponding bits in the file mode creation +mask of the invoking process, shall be set. +.LP +Otherwise, the file mode bits represented by the specified \fBwho\fP +and \fBperm\fP values shall be set. +.sp +.LP +When using the symbolic mode form on a regular file, it is implementation-defined +whether or not: +.IP " *" 3 +Requests to set the set-user-ID-on-execution or set-group-ID-on-execution +bit when all execute bits are currently clear and none +are being set are ignored. +.LP +.IP " *" 3 +Requests to clear all execute bits also clear the set-user-ID-on-execution +and set-group-ID-on-execution bits. +.LP +.IP " *" 3 +Requests to clear the set-user-ID-on-execution or set-group-ID-on-execution +bits when all execute bits are currently clear are +ignored. However, if the command \fIls\fP \fB-l\fP \fIfile\fP writes +an \fIs\fP in the +position indicating that the set-user-ID-on-execution or set-group-ID-on-execution +is set, the commands \fIchmod\fP \fBu-s\fP +\fIfile\fP or \fIchmod\fP \fBg-s\fP \fIfile\fP, respectively, shall +not be ignored. +.LP +.LP +When using the symbolic mode form on other file types, it is implementation-defined +whether or not requests to set or clear the +set-user-ID-on-execution or set-group-ID-on-execution bits are honored. +.LP +If the \fBwho\fP symbol \fBo\fP is used in conjunction with the \fBperm\fP +symbol \fBs\fP with no other \fBwho\fP symbols +being specified, the set-user-ID-on-execution and set-group-ID-on-execution +bits shall not be modified. It shall not be an error to +specify the \fBwho\fP symbol \fBo\fP in conjunction with the \fBperm\fP +symbol \fBs\fP. +.LP +The \fBperm\fP symbol \fBt\fP shall specify the S_ISVTX bit. When +used with a file of type directory, it can be used with the +\fBwho\fP symbol \fBa\fP, or with no \fBwho\fP symbol. It shall not +be an error to specify a \fBwho\fP symbol of \fBu\fP, +\fBg\fP, or \fBo\fP in conjunction with the \fBperm\fP symbol \fBt\fP, +but the meaning of these combinations is unspecified. +The effect when using the \fBperm\fP symbol \fBt\fP with any file +type other than directory is unspecified. +.LP +For an octal integer \fImode\fP operand, the file mode bits shall +be set absolutely. +.LP +For each bit set in the octal number, the corresponding file permission +bit shown in the following table shall be set; all other +file permission bits shall be cleared. For regular files, for each +bit set in the octal number corresponding to the +set-user-ID-on-execution or the set-group-ID-on-execution, bits shown +in the following table shall be set; if these bits are not +set in the octal number, they are cleared. For other file types, it +is implementation-defined whether or not requests to set or +clear the set-user-ID-on-execution or set-group-ID-on-execution bits +are honored. +.TS C +center; l1 l1 l1 l1 l1 l1 l1 l. +\fBOctal\fP \fBMode Bit\fP \fBOctal\fP \fBMode Bit\fP \fBOctal\fP \fBMode Bit\fP \fBOctal\fP \fBMode Bit\fP +\fB4000\fP S_ISUID \fB0400\fP S_IRUSR \fB0040\fP S_IRGRP \fB0004\fP S_IROTH +\fB2000\fP S_ISGID \fB0200\fP S_IWUSR \fB0020\fP S_IWGRP \fB0002\fP S_IWOTH +\fB1000\fP S_ISVTX \fB0100\fP S_IXUSR \fB0010\fP S_IXGRP \fB0001\fP S_IXOTH +.TE +.LP +When bits are set in the octal number other than those listed in the +table above, the behavior is unspecified. +.SS Grammar for chmod +.LP +The grammar and lexical conventions in this section describe the syntax +for the \fIsymbolic_mode\fP operand. The general +conventions for this style of grammar are described in \fIGrammar +Conventions\fP . A valid +\fIsymbolic_mode\fP can be represented as the non-terminal symbol +\fIsymbolic_mode\fP in the grammar. This formal syntax shall +take precedence over the preceding text syntax description. +.LP +The lexical processing is based entirely on single characters. Implementations +need not allow s within the single +argument being processed. +.sp +.RS +.nf + +\fB%start symbolic_mode +%% +.sp + +symbolic_mode : clause + | symbolic_mode ',' clause + ; +.sp + +clause : actionlist + | wholist actionlist + ; +.sp + +wholist : who + | wholist who + ; +.sp + +who : 'u' | 'g' | 'o' | 'a' + ; +.sp + +actionlist : action + | actionlist action + ; +.sp + +action : op + | op permlist + | op permcopy + ; +.sp + +permcopy : 'u' | 'g' | 'o' + ; +.sp + +op : '+' | '-' | '=' + ; +.sp + +permlist : perm + | perm permlist + ; +.sp + + +perm : 'r' | 'w' | 'x' | 'X' | 's' | 't' + ; +\fP +.fi +.RE +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The utility executed successfully and all requested changes were made. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Some implementations of the \fIchmod\fP utility change the mode of +a directory before the files in the directory when +performing a recursive ( \fB-R\fP option) change; others change the +directory mode after the files in the directory. If an +application tries to remove read or search permission for a file hierarchy, +the removal attempt fails if the directory is changed +first; on the other hand, trying to re-enable permissions to a restricted +hierarchy fails if directories are changed last. Users +should not try to make a hierarchy inaccessible to themselves. +.LP +Some implementations of \fIchmod\fP never used the process' \fIumask\fP +when changing +modes; systems conformant with this volume of IEEE\ Std\ 1003.1-2001 +do so when \fBwho\fP is not specified. Note the +difference between: +.sp +.RS +.nf + +\fBchmod a-w file +\fP +.fi +.RE +.LP +which removes all write permissions, and: +.sp +.RS +.nf + +\fBchmod -- -w file +\fP +.fi +.RE +.LP +which removes write permissions that would be allowed if \fBfile\fP +was created with the same \fIumask\fP. +.LP +Conforming applications should never assume that they know how the +set-user-ID and set-group-ID bits on directories are +interpreted. +.SH EXAMPLES +.TS C +center; l lw(40). +\fBMode\fP T{ +.na +\fBResults\fP +.ad +T} +\fIa\fP+= T{ +.na +Equivalent to \fIa\fP+, \fIa\fP=; clears all file mode bits. +.ad +T} +\fIgo\fP+-w T{ +.na +Equivalent to \fIgo\fP+, \fIgo\fP- \fIw\fP; clears group and other write bits. +.ad +T} +\fIg\fP=\fIo\fP-\fIw\fP T{ +.na +Equivalent to \fIg\fP= \fIo\fP, \fIg\fP- \fIw\fP; sets group bit to match other bits and then clears group write bit. +.ad +T} +\fIg\fP-\fIr\fP+\fIw\fP T{ +.na +Equivalent to \fIg\fP- \fIr\fP, \fIg\fP+ \fIw\fP; clears group read bit and sets group write bit. +.ad +T} +\fIuo\fP=\fIg\fP T{ +.na +Sets owner bits to match group bits and sets other bits to match group bits. +.ad +T} +.TE +.SH RATIONALE +.LP +The functionality of \fIchmod\fP is described substantially through +references to concepts defined in the System Interfaces +volume of IEEE\ Std\ 1003.1-2001. In this way, there is less duplication +of effort required for describing the interactions +of permissions. However, the behavior of this utility is not described +in terms of the \fIchmod\fP() function from the System Interfaces +volume of IEEE\ Std\ 1003.1-2001 because +that specification requires certain side effects upon alternate file +access control mechanisms that might not be appropriate, +depending on the implementation. +.LP +Implementations that support mandatory file and record locking as +specified by the 1984 /usr/group standard historically used +the combination of set-group-ID bit set and group execute bit clear +to indicate mandatory locking. This condition is usually set or +cleared with the symbolic mode \fBperm\fP symbol \fBl\fP instead of +the \fBperm\fP symbols \fBs\fP and \fBx\fP so that the +mandatory locking mode is not changed without explicit indication +that that was what the user intended. Therefore, the details on +how the implementation treats these conditions must be defined in +the documentation. This volume of IEEE\ Std\ 1003.1-2001 +does not require mandatory locking (nor does the System Interfaces +volume of IEEE\ Std\ 1003.1-2001), but does allow it as +an extension. However, this volume of IEEE\ Std\ 1003.1-2001 does +require that the \fIls\fP and \fIchmod\fP utilities work consistently +in this area. If \fIls\fP \fB-l\fP \fIfile\fP indicates that the set-group-ID +bit is set, \fIchmod\fP \fBg-s\fP +\fIfile\fP must clear it (assuming appropriate privileges exist to +change modes). +.LP +The System V and BSD versions use different exit status codes. Some +implementations used the exit status as a count of the +number of errors that occurred; this practice is unworkable since +it can overflow the range of valid exit status values. This +problem is avoided here by specifying only 0 and >0 as exit values. +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001 indicates that +implementation-defined restrictions may cause the +S_ISUID and S_ISGID bits to be ignored. This volume of IEEE\ Std\ 1003.1-2001 +allows the \fIchmod\fP utility to choose to +modify these bits before calling \fIchmod\fP() (or some function providing +equivalent +capabilities) for non-regular files. Among other things, this allows +implementations that use the set-user-ID and set-group-ID bits +on directories to enable extended features to handle these extensions +in an intelligent manner. +.LP +The \fBX\fP \fBperm\fP symbol was adopted from BSD-based systems because +it provides commonly desired functionality when doing +recursive ( \fB-R\fP option) modifications. Similar functionality +is not provided by the \fIfind\fP utility. Historical BSD versions +of \fIchmod\fP, however, only supported \fBX\fP with +\fIop\fP+; it has been extended in this volume of IEEE\ Std\ 1003.1-2001 +because it is also useful with \fIop\fP=. (It +has also been added for \fIop\fP- even though it duplicates \fBx\fP, +in this case, because it is intuitive and easier to +explain.) +.LP +The grammar was extended with the \fIpermcopy\fP non-terminal to allow +historical-practice forms of symbolic modes like +\fBo\fP= \fBu\fP \fB-g\fP (that is, set the "other" permissions to +the permissions of "owner" minus the permissions of +"group"). +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIls\fP , \fIumask\fP , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIchmod\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/chown.1p b/man1p/chown.1p new file mode 100644 index 000000000..e4075b83b --- /dev/null +++ b/man1p/chown.1p @@ -0,0 +1,264 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CHOWN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" chown +.SH NAME +chown \- change the file ownership +.SH SYNOPSIS +.LP +\fBchown\fP \fB[\fP\fB-hR\fP\fB]\fP \fIowner\fP\fB[\fP\fB:\fP\fIgroup\fP\fB]\fP +\fIfile\fP \fB... +.br +.sp +chown -R\fP \fB[\fP\fB-H | -L | -P\fP \fB]\fP \fIowner\fP\fB[\fP\fB:\fP\fIgroup\fP\fB]\fP +\fIfile\fP \fB... +.br +\fP +.SH DESCRIPTION +.LP +The \fIchown\fP utility shall set the user ID of the file named by +each \fIfile\fP operand to the user ID specified by the +\fIowner\fP operand. +.LP +For each \fIfile\fP operand, or, if the \fB-R\fP option is used, each +file encountered while walking the directory trees +specified by the \fIfile\fP operands, the \fIchown\fP utility shall +perform actions equivalent to the \fIchown\fP() function defined in +the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +called with the following arguments: +.IP " 1." 4 +The \fIfile\fP operand shall be used as the \fIpath\fP argument. +.LP +.IP " 2." 4 +The user ID indicated by the \fIowner\fP portion of the first operand +shall be used as the \fIowner\fP argument. +.LP +.IP " 3." 4 +If the \fIgroup\fP portion of the first operand is given, the group +ID indicated by it shall be used as the \fIgroup\fP +argument; otherwise, the group ownership shall not be changed. +.LP +.LP +Unless \fIchown\fP is invoked by a process with appropriate privileges, +the set-user-ID and set-group-ID bits of a regular file +shall be cleared upon successful completion; the set-user-ID and set-group-ID +bits of other file types may be cleared. +.SH OPTIONS +.LP +The \fIchown\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported by the implementation: +.TP 7 +\fB-h\fP +If the system supports user IDs for symbolic links, for each \fIfile\fP +operand that names a file of type symbolic link, +\fIchown\fP shall attempt to set the user ID of the symbolic link. +If the system supports group IDs for symbolic links, and a +group ID was specified, for each \fIfile\fP operand that names a file +of type symbolic link, \fIchown\fP shall attempt to set the +group ID of the symbolic link. If the system does not support user +or group IDs for symbolic links, for each \fIfile\fP operand +that names a file of type symbolic link, \fIchown\fP shall do nothing +more with the current file and shall go on to any remaining +files. +.TP 7 +\fB-H\fP +If the \fB-R\fP option is specified and a symbolic link referencing +a file of type directory is specified on the command line, +\fIchown\fP shall change the user ID (and group ID, if specified) +of the directory referenced by the symbolic link and all files +in the file hierarchy below it. +.TP 7 +\fB-L\fP +If the \fB-R\fP option is specified and a symbolic link referencing +a file of type directory is specified on the command line +or encountered during the traversal of a file hierarchy, \fIchown\fP +shall change the user ID (and group ID, if specified) of the +directory referenced by the symbolic link and all files in the file +hierarchy below it. +.TP 7 +\fB-P\fP +If the \fB-R\fP option is specified and a symbolic link is specified +on the command line or encountered during the traversal +of a file hierarchy, \fIchown\fP shall change the owner ID (and group +ID, if specified) of the symbolic link if the system +supports this operation. The \fIchown\fP utility shall not follow +the symbolic link to any other part of the file hierarchy. +.TP 7 +\fB-R\fP +Recursively change file user and group IDs. For each \fIfile\fP operand +that names a directory, \fIchown\fP shall change the +user ID (and group ID, if specified) of the directory and all files +in the file hierarchy below it. Unless a \fB-H\fP, \fB-L\fP, +or \fB-P\fP option is specified, it is unspecified which of these +options will be used as the default. +.sp +.LP +Specifying more than one of the mutually-exclusive options \fB-H\fP, +\fB-L\fP, and \fB-P\fP shall not be considered an error. +The last option specified shall determine the behavior of the utility. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIowner\fP\fB[\fP:\fIgroup\fP\fB]\fP +A user ID and optional group ID to be assigned to \fIfile\fP. The +\fIowner\fP portion of this operand shall be a user name +from the user database or a numeric user ID. Either specifies a user +ID which shall be given to each file named by one of the +\fIfile\fP operands. If a numeric \fIowner\fP operand exists in the +user database as a user name, the user ID number associated +with that user name shall be used as the user ID. Similarly, if the +\fIgroup\fP portion of this operand is present, it shall be a +group name from the group database or a numeric group ID. Either specifies +a group ID which shall be given to each file. If a +numeric group operand exists in the group database as a group name, +the group ID number associated with that group name shall be +used as the group ID. +.TP 7 +\fIfile\fP +A pathname of a file whose user ID is to be modified. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIchown\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The utility executed successfully and all requested changes were made. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Only the owner of a file or the user with appropriate privileges may +change the owner or group of a file. +.LP +Some implementations restrict the use of \fIchown\fP to a user with +appropriate privileges. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The System V and BSD versions use different exit status codes. Some +implementations used the exit status as a count of the +number of errors that occurred; this practice is unworkable since +it can overflow the range of valid exit status values. These are +masked by specifying only 0 and >0 as exit values. +.LP +The functionality of \fIchown\fP is described substantially through +references to functions in the System Interfaces volume of +IEEE\ Std\ 1003.1-2001. In this way, there is no duplication of effort +required for describing the interactions of +permissions, multiple groups, and so on. +.LP +The 4.3 BSD method of specifying both owner and group was included +in this volume of IEEE\ Std\ 1003.1-2001 because: +.IP " *" 3 +There are cases where the desired end condition could not be achieved +using the \fIchgrp\fP and \fIchown\fP (that only changed the user +ID) utilities. (If the current owner is not +a member of the desired group and the desired owner is not a member +of the current group, the \fIchown\fP() function could fail unless +both owner and group are changed at the same time.) +.LP +.IP " *" 3 +Even if they could be changed independently, in cases where both are +being changed, there is a 100% performance penalty caused +by being forced to invoke both utilities. +.LP +.LP +The BSD syntax \fIuser\fP[. \fIgroup\fP] was changed to \fIuser\fP[: +\fIgroup\fP] in this volume of +IEEE\ Std\ 1003.1-2001 because the period is a valid character in +login names (as specified by the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, login names consist of characters in the +portable filename character set). The colon character +was chosen as the replacement for the period character because it +would never be allowed as a character in a user name or group +name on historical implementations. +.LP +The \fB-R\fP option is considered by some observers as an undesirable +departure from the historical UNIX system tools approach; +since a tool, \fIfind\fP, already exists to recurse over directories, +there seemed to be no +good reason to require other tools to have to duplicate that functionality. +However, the \fB-R\fP option was deemed an important +user convenience, is far more efficient than forking a separate process +for each element of the directory hierarchy, and is in +widespread historical use. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchmod\fP , \fIchgrp\fP , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIchown\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/cksum.1p b/man1p/cksum.1p new file mode 100644 index 000000000..f88581a98 --- /dev/null +++ b/man1p/cksum.1p @@ -0,0 +1,351 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CKSUM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cksum +.SH NAME +cksum \- write file checksums and sizes +.SH SYNOPSIS +.LP +\fBcksum\fP \fB[\fP\fIfile\fP \fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIcksum\fP utility shall calculate and write to standard output +a cyclic redundancy check (CRC) for each input file, and +also write to standard output the number of octets in each file. The +CRC used is based on the polynomial used for CRC error +checking in the ISO/IEC\ 8802-3:1996 standard (Ethernet). +.LP +The encoding for the CRC checksum is defined by the generating polynomial: +.sp +.RS +.nf + +\fIG\fP\fB(\fP\fIx\fP\fB)=\fP\fIx\fP\fB**32+\fP\fIx\fP\fB**26+\fP\fIx\fP\fB**23+\fP\fIx\fP\fB**22+\fP\fIx\fP\fB**16+\fP\fIx\fP\fB**12+\fP\fIx\fP\fB**11+\fP\fIx\fP\fB**10+\fP\fIx\fP\fB**8+\fP\fIx\fP\fB**7+\fP\fIx\fP\fB**5+\fP\fIx\fP\fB**4+\fP\fIx\fP\fB**2+\fP\fIx\fP\fB+1 +\fP +.fi +.RE +.LP +Mathematically, the CRC value corresponding to a given file shall +be defined by the following procedure: +.IP " 1." 4 +The \fIn\fP bits to be evaluated are considered to be the coefficients +of a mod 2 polynomial \fIM\fP( \fIx\fP) of degree +\fIn\fP-1. These \fIn\fP bits are the bits from the file, with the +most significant bit being the most significant bit of the +first octet of the file and the last bit being the least significant +bit of the last octet, padded with zero bits (if necessary) to +achieve an integral number of octets, followed by one or more octets +representing the length of the file as a binary value, least +significant octet first. The smallest number of octets capable of +representing this integer shall be used. +.LP +.IP " 2." 4 +\fIM\fP( \fIx\fP) is multiplied by \fIx\fP**32 (that is, shifted left +32 bits) and divided by +\fIG\fP( \fIx\fP) using mod 2 division, producing a remainder \fIR\fP( +\fIx\fP) of degree <= 31. +.LP +.IP " 3." 4 +The coefficients of \fIR\fP( \fIx\fP) are considered to be a 32-bit +sequence. +.LP +.IP " 4." 4 +The bit sequence is complemented and the result is the CRC. +.LP +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a file to be checked. If no \fIfile\fP operands are +specified, the standard input shall be used. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified. See the INPUT FILES section. +.SH INPUT FILES +.LP +The input files can be any file type. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIcksum\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +For each file processed successfully, the \fIcksum\fP utility shall +write in the following format: +.sp +.RS +.nf + +\fB"%u %d %s\\n", <\fP\fIchecksum\fP\fB>, <\fP\fI# of octets\fP\fB>, <\fP\fIpathname\fP\fB> +\fP +.fi +.RE +.LP +If no \fIfile\fP operand was specified, the pathname and its leading + shall be omitted. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All files were processed successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fIcksum\fP utility is typically used to quickly compare a suspect +file against a trusted version of the same, such as to +ensure that files transmitted over noisy media arrive intact. However, +this comparison cannot be considered cryptographically +secure. The chances of a damaged file producing the same CRC as the +original are small; deliberate deception is difficult, but +probably not impossible. +.LP +Although input files to \fIcksum\fP can be any type, the results need +not be what would be expected on character special device +files or on file types not described by the System Interfaces volume +of IEEE\ Std\ 1003.1-2001. Since this volume of +IEEE\ Std\ 1003.1-2001 does not specify the block size used when doing +input, checksums of character special files need not +process all of the data in those files. +.LP +The algorithm is expressed in terms of a bitstream divided into octets. +If a file is transmitted between two systems and +undergoes any data transformation (such as changing little-endian +byte ordering to big-endian), identical CRC values cannot be +expected. Implementations performing such transformations may extend +\fIcksum\fP to handle such situations. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The following C-language program can be used as a model to describe +the algorithm. It assumes that a \fBchar\fP is one octet. +It also assumes that the entire file is available for one pass through +the function. This was done for simplicity in demonstrating +the algorithm, rather than as an implementation model. +.sp +.RS +.nf + +\fBstatic unsigned long crctab[] = { +0x00000000, +0x04c11db7, 0x09823b6e, 0x0d4326d9, 0x130476dc, 0x17c56b6b, +0x1a864db2, 0x1e475005, 0x2608edb8, 0x22c9f00f, 0x2f8ad6d6, +0x2b4bcb61, 0x350c9b64, 0x31cd86d3, 0x3c8ea00a, 0x384fbdbd, +0x4c11db70, 0x48d0c6c7, 0x4593e01e, 0x4152fda9, 0x5f15adac, +0x5bd4b01b, 0x569796c2, 0x52568b75, 0x6a1936c8, 0x6ed82b7f, +0x639b0da6, 0x675a1011, 0x791d4014, 0x7ddc5da3, 0x709f7b7a, +0x745e66cd, 0x9823b6e0, 0x9ce2ab57, 0x91a18d8e, 0x95609039, +0x8b27c03c, 0x8fe6dd8b, 0x82a5fb52, 0x8664e6e5, 0xbe2b5b58, +0xbaea46ef, 0xb7a96036, 0xb3687d81, 0xad2f2d84, 0xa9ee3033, +0xa4ad16ea, 0xa06c0b5d, 0xd4326d90, 0xd0f37027, 0xddb056fe, +0xd9714b49, 0xc7361b4c, 0xc3f706fb, 0xceb42022, 0xca753d95, +0xf23a8028, 0xf6fb9d9f, 0xfbb8bb46, 0xff79a6f1, 0xe13ef6f4, +0xe5ffeb43, 0xe8bccd9a, 0xec7dd02d, 0x34867077, 0x30476dc0, +0x3d044b19, 0x39c556ae, 0x278206ab, 0x23431b1c, 0x2e003dc5, +0x2ac12072, 0x128e9dcf, 0x164f8078, 0x1b0ca6a1, 0x1fcdbb16, +0x018aeb13, 0x054bf6a4, 0x0808d07d, 0x0cc9cdca, 0x7897ab07, +0x7c56b6b0, 0x71159069, 0x75d48dde, 0x6b93dddb, 0x6f52c06c, +0x6211e6b5, 0x66d0fb02, 0x5e9f46bf, 0x5a5e5b08, 0x571d7dd1, +0x53dc6066, 0x4d9b3063, 0x495a2dd4, 0x44190b0d, 0x40d816ba, +0xaca5c697, 0xa864db20, 0xa527fdf9, 0xa1e6e04e, 0xbfa1b04b, +0xbb60adfc, 0xb6238b25, 0xb2e29692, 0x8aad2b2f, 0x8e6c3698, +0x832f1041, 0x87ee0df6, 0x99a95df3, 0x9d684044, 0x902b669d, +0x94ea7b2a, 0xe0b41de7, 0xe4750050, 0xe9362689, 0xedf73b3e, +0xf3b06b3b, 0xf771768c, 0xfa325055, 0xfef34de2, 0xc6bcf05f, +0xc27dede8, 0xcf3ecb31, 0xcbffd686, 0xd5b88683, 0xd1799b34, +0xdc3abded, 0xd8fba05a, 0x690ce0ee, 0x6dcdfd59, 0x608edb80, +0x644fc637, 0x7a089632, 0x7ec98b85, 0x738aad5c, 0x774bb0eb, +0x4f040d56, 0x4bc510e1, 0x46863638, 0x42472b8f, 0x5c007b8a, +0x58c1663d, 0x558240e4, 0x51435d53, 0x251d3b9e, 0x21dc2629, +0x2c9f00f0, 0x285e1d47, 0x36194d42, 0x32d850f5, 0x3f9b762c, +0x3b5a6b9b, 0x0315d626, 0x07d4cb91, 0x0a97ed48, 0x0e56f0ff, +0x1011a0fa, 0x14d0bd4d, 0x19939b94, 0x1d528623, 0xf12f560e, +0xf5ee4bb9, 0xf8ad6d60, 0xfc6c70d7, 0xe22b20d2, 0xe6ea3d65, +0xeba91bbc, 0xef68060b, 0xd727bbb6, 0xd3e6a601, 0xdea580d8, +0xda649d6f, 0xc423cd6a, 0xc0e2d0dd, 0xcda1f604, 0xc960ebb3, +0xbd3e8d7e, 0xb9ff90c9, 0xb4bcb610, 0xb07daba7, 0xae3afba2, +0xaafbe615, 0xa7b8c0cc, 0xa379dd7b, 0x9b3660c6, 0x9ff77d71, +0x92b45ba8, 0x9675461f, 0x8832161a, 0x8cf30bad, 0x81b02d74, +0x857130c3, 0x5d8a9099, 0x594b8d2e, 0x5408abf7, 0x50c9b640, +0x4e8ee645, 0x4a4ffbf2, 0x470cdd2b, 0x43cdc09c, 0x7b827d21, +0x7f436096, 0x7200464f, 0x76c15bf8, 0x68860bfd, 0x6c47164a, +0x61043093, 0x65c52d24, 0x119b4be9, 0x155a565e, 0x18197087, +0x1cd86d30, 0x029f3d35, 0x065e2082, 0x0b1d065b, 0x0fdc1bec, +0x3793a651, 0x3352bbe6, 0x3e119d3f, 0x3ad08088, 0x2497d08d, +0x2056cd3a, 0x2d15ebe3, 0x29d4f654, 0xc5a92679, 0xc1683bce, +0xcc2b1d17, 0xc8ea00a0, 0xd6ad50a5, 0xd26c4d12, 0xdf2f6bcb, +0xdbee767c, 0xe3a1cbc1, 0xe760d676, 0xea23f0af, 0xeee2ed18, +0xf0a5bd1d, 0xf464a0aa, 0xf9278673, 0xfde69bc4, 0x89b8fd09, +0x8d79e0be, 0x803ac667, 0x84fbdbd0, 0x9abc8bd5, 0x9e7d9662, +0x933eb0bb, 0x97ffad0c, 0xafb010b1, 0xab710d06, 0xa6322bdf, +0xa2f33668, 0xbcb4666d, 0xb8757bda, 0xb5365d03, 0xb1f740b4 +}; +.sp + +unsigned long memcrc(const unsigned char *b, size_t n) +{ +/* Input arguments: + * const char* b == byte sequence to checksum + * size_t n == length of sequence + */ +.sp + + register unsigned i, c, s = 0; +.sp + + for (i = n; i > 0; --i) { + c = (unsigned)(*b++); + s = (s << 8) ^ crctab[(s >> 24) ^ c]; + } +.sp + + /* Extend with the length of the string. */ + while (n != 0) { + c = n & 0377; + n >>= 8; + s = (s << 8) ^ crctab[(s >> 24) ^ c]; + } +.sp + + return ~s; +} +\fP +.fi +.RE +.LP +The historical practice of writing the number of "blocks" has been +changed to writing the number of octets, since the latter +is not only more useful, but also since historical implementations +have not been consistent in defining what a "block" meant. +Octets are used instead of bytes because bytes can differ in size +between systems. +.LP +The algorithm used was selected to increase the operational robustness +of \fIcksum\fP. Neither the System V nor BSD \fIsum\fP +algorithm was selected. Since each of these was different and each +was the default behavior on those systems, no realistic +compromise was available if either were selected-some set of historical +applications would break. Therefore, the name was changed +to \fIcksum\fP. Although the historical \fIsum\fP commands will probably +continue to be provided for many years, programs +designed for portability across systems should use the new name. +.LP +The algorithm selected is based on that used by the ISO/IEC\ 8802-3:1996 +standard (Ethernet) for the frame check sequence +field. The algorithm used does not match the technical definition +of a \fIchecksum\fP; the term is used for historical reasons. +The length of the file is included in the CRC calculation because +this parallels inclusion of a length field by Ethernet in its +CRC, but also because it guards against inadvertent collisions between +files that begin with different series of zero octets. The +chance that two different files produce identical CRCs is much greater +when their lengths are not considered. Keeping the length +and the checksum of the file itself separate would yield a slightly +more robust algorithm, but historical usage has always been +that a single number (the checksum as printed) represents the signature +of the file. It was decided that historical usage was the +more important consideration. +.LP +Early proposals contained modifications to the Ethernet algorithm +that involved extracting table values whenever an intermediate +result became zero. This was demonstrated to be less robust than the +current method and mathematically difficult to describe or +justify. +.LP +The calculation used is identical to that given in pseudo-code in +the referenced Sarwate article. The pseudo-code rendition +is: +.sp +.RS +.nf + +\fBX <- 0; Y <- 0; +for i <- m -1 step -1 until 0 do + begin + T <- X(1) ^ A[i]; + X(1) <- X(0); X(0) <- Y(1); Y(1) <- Y(0); Y(0) <- 0; + comment: f[T] and f'[T] denote the T-th words in the + table f and f' ; + X <- X ^ f[T]; Y <- Y ^ f'[T]; + end +\fP +.fi +.RE +.LP +The pseudo-code is reproduced exactly as given; however, note that +in the case of \fIcksum\fP, \fBA[i]\fP represents a byte of +the file, the words \fBX\fP and \fBY\fP are treated as a single 32-bit +value, and the tables \fBf\fP and \fBf'\fP are a single +table containing 32-bit values. +.LP +The referenced Sarwate article also discusses generating the table. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +None. +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/cmp.1p b/man1p/cmp.1p new file mode 100644 index 000000000..89003c13b --- /dev/null +++ b/man1p/cmp.1p @@ -0,0 +1,241 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cmp +.SH NAME +cmp \- compare two files +.SH SYNOPSIS +.LP +\fBcmp\fP \fB[\fP \fB-l | -s\fP \fB]\fP \fIfile1 file2\fP +.SH DESCRIPTION +.LP +The \fIcmp\fP utility shall compare two files. The \fIcmp\fP utility +shall write no output if the files are the same. Under +default options, if they differ, it shall write to standard output +the byte and line number at which the first difference occurred. +Bytes and lines shall be numbered beginning with 1. +.SH OPTIONS +.LP +The \fIcmp\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-l\fP +(Lowercase ell.) Write the byte number (decimal) and the differing +bytes (octal) for each difference. +.TP 7 +\fB-s\fP +Write nothing for differing files; return exit status only. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile1\fP +A pathname of the first file to be compared. If \fIfile1\fP is \fB'-'\fP +, the standard input shall be used. +.TP 7 +\fIfile2\fP +A pathname of the second file to be compared. If \fIfile2\fP is \fB'-'\fP +, the standard input shall be used. +.sp +.LP +If both \fIfile1\fP and \fIfile2\fP refer to standard input or refer +to the same FIFO special, block special, or character +special file, the results are undefined. +.SH STDIN +.LP +The standard input shall be used only if the \fIfile1\fP or \fIfile2\fP +operand refers to standard input. See the INPUT FILES +section. +.SH INPUT FILES +.LP +The input files can be any file type. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIcmp\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +In the POSIX locale, results of the comparison shall be written to +standard output. When no options are used, the format shall +be: +.sp +.RS +.nf + +\fB"%s %s differ: char %d, line %d\\n",\fP \fIfile1\fP\fB,\fP \fIfile2\fP\fB, + <\fP\fIbyte number\fP\fB>, <\fP\fIline number\fP\fB> +\fP +.fi +.RE +.LP +When the \fB-l\fP option is used, the format shall be: +.sp +.RS +.nf + +\fB"%d %o %o\\n", <\fP\fIbyte number\fP\fB>, <\fP\fIdiffering byte\fP\fB>, + <\fP\fIdiffering byte\fP\fB> +\fP +.fi +.RE +.LP +for each byte that differs. The first <\fIdiffering\ byte\fP> number +is from \fIfile1\fP while the second is from +\fIfile2\fP. In both cases, <\fIbyte\ number\fP> shall be relative +to the beginning of the file, beginning with 1. +.LP +No output shall be written to standard output when the \fB-s\fP option +is used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. If +\fIfile1\fP and \fIfile2\fP are identical for the entire +length of the shorter file, in the POSIX locale the following diagnostic +message shall be written, unless the \fB-s\fP option is +specified: +.sp +.RS +.nf + +\fB"cmp: EOF on %s%s\\n", <\fP\fIname of shorter file\fP\fB>, <\fP\fIadditional info\fP\fB> +\fP +.fi +.RE +.LP +The <\fIadditional\ info\fP> field shall either be null or a string +that starts with a and contains no +s. Some implementations report on the number of lines in +this case. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The files are identical. +.TP 7 +\ 1 +The files are different; this includes the case where one file is +identical to the first part of the other. +.TP 7 +>1 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Although input files to \fIcmp\fP can be any type, the results might +not be what would be expected on character special device +files or on file types not described by the System Interfaces volume +of IEEE\ Std\ 1003.1-2001. Since this volume of +IEEE\ Std\ 1003.1-2001 does not specify the block size used when doing +input, comparisons of character special files need +not compare all of the data in those files. +.LP +For files which are not text files, line numbers simply reflect the +presence of a , without any implication that +the file is organized into lines. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The global language in \fIUtility Description Defaults\fP indicates +that using two +mutually-exclusive options together produces unspecified results. +Some System V implementations consider the option usage: +.sp +.RS +.nf + +\fBcmp -l -s ... +\fP +.fi +.RE +.LP +to be an error. They also treat: +.sp +.RS +.nf + +\fBcmp -s -l ... +\fP +.fi +.RE +.LP +as if no options were specified. Both of these behaviors are considered +bugs, but are allowed. +.LP +The word \fBchar\fP in the standard output format comes from historical +usage, even though it is actually a byte number. When +\fIcmp\fP is supported in other locales, implementations are encouraged +to use the word \fIbyte\fP or its equivalent in another +language. Users should not interpret this difference to indicate that +the functionality of the utility changed between locales. +.LP +Some implementations report on the number of lines in the identical-but-shorter +file case. This is allowed by the inclusion of +the <\fIadditional\ info\fP> fields in the output format. The restriction +on having a leading and no +s is to make parsing for the filename easier. It is recognized +that some filenames containing white-space characters +make parsing difficult anyway, but the restriction does aid programs +used on systems where the names are predominantly well +behaved. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcomm\fP , \fIdiff\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/colon.1p b/man1p/colon.1p new file mode 100644 index 000000000..cb3f9f2ee --- /dev/null +++ b/man1p/colon.1p @@ -0,0 +1,102 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "COLON" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" colon +.SH NAME +colon \- null utility +.SH SYNOPSIS +.LP +\fB:\fP \fB[\fP\fIargument\fP \fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +This utility shall only expand command \fIargument\fPs. It is used +when a command is needed, as in the \fBthen\fP condition of +an \fBif\fP command, but nothing is to be done by the command. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +See the DESCRIPTION. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +None. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +Zero. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.sp +.RS +.nf + +\fB: ${X=abc} +if false +then : +else echo $X +fi +\fP\fBabc\fP +.fi +.RE +.LP +As with any of the special built-ins, the null utility can also have +variable assignments and redirections associated with it, +such as: +.sp +.RS +.nf + +\fBx=y : > z +\fP +.fi +.RE +.LP +which sets variable \fIx\fP to the value \fIy\fP (so that it persists +after the null utility completes) and creates or +truncates file \fBz\fP. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISpecial Built-In Utilities\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/comm.1p b/man1p/comm.1p new file mode 100644 index 000000000..77848a4da --- /dev/null +++ b/man1p/comm.1p @@ -0,0 +1,252 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "COMM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" comm +.SH NAME +comm \- select or reject lines common to two files +.SH SYNOPSIS +.LP +\fBcomm\fP \fB[\fP\fB-123\fP\fB]\fP \fIfile1 file2\fP +.SH DESCRIPTION +.LP +The \fIcomm\fP utility shall read \fIfile1\fP and \fIfile2\fP, which +should be ordered in the current collating sequence, and +produce three text columns as output: lines only in \fIfile1\fP, lines +only in \fIfile2\fP, and lines in both files. +.LP +If the lines in both files are not ordered according to the collating +sequence of the current locale, the results are +unspecified. +.SH OPTIONS +.LP +The \fIcomm\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-1\fP +Suppress the output column of lines unique to \fIfile1\fP. +.TP 7 +\fB-2\fP +Suppress the output column of lines unique to \fIfile2\fP. +.TP 7 +\fB-3\fP +Suppress the output column of lines duplicated in \fIfile1\fP and +\fIfile2\fP. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile1\fP +A pathname of the first file to be compared. If \fIfile1\fP is \fB'-'\fP +, the standard input shall be used. +.TP 7 +\fIfile2\fP +A pathname of the second file to be compared. If \fIfile2\fP is \fB'-'\fP +, the standard input shall be used. +.sp +.LP +If both \fIfile1\fP and \fIfile2\fP refer to standard input or to +the same FIFO special, block special, or character special +file, the results are undefined. +.SH STDIN +.LP +The standard input shall be used only if one of the \fIfile1\fP or +\fIfile2\fP operands refers to standard input. See the +INPUT FILES section. +.SH INPUT FILES +.LP +The input files shall be text files. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIcomm\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the collating sequence \fIcomm\fP expects +to have been used when the input files were sorted. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fIcomm\fP utility shall produce output depending on the options +selected. If the \fB-1\fP, \fB-2\fP, and \fB-3\fP +options are all selected, \fIcomm\fP shall write nothing to standard +output. +.LP +If the \fB-1\fP option is not selected, lines contained only in \fIfile1\fP +shall be written using the format: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIline in file1\fP\fB> +\fP +.fi +.RE +.LP +If the \fB-2\fP option is not selected, lines contained only in \fIfile2\fP +are written using the format: +.sp +.RS +.nf + +\fB"%s%s\\n", <\fP\fIlead\fP\fB>, <\fP\fIline in file2\fP\fB> +\fP +.fi +.RE +.LP +where the string <\fIlead\fP> is as follows: +.TP 7 + +The \fB-1\fP option is not selected. +.TP 7 +null\ string +The \fB-1\fP option is selected. +.sp +.LP +If the \fB-3\fP option is not selected, lines contained in both files +shall be written using the format: +.sp +.RS +.nf + +\fB"%s%s\\n", <\fP\fIlead\fP\fB>, <\fP\fIline in both\fP\fB> +\fP +.fi +.RE +.LP +where the string <\fIlead\fP> is as follows: +.TP 7 + +Neither the \fB-1\fP nor the \fB-2\fP option is selected. +.TP 7 + +Exactly one of the \fB-1\fP and \fB-2\fP options is selected. +.TP 7 +null\ string +Both the \fB-1\fP and \fB-2\fP options are selected. +.sp +.LP +If the input files were ordered according to the collating sequence +of the current locale, the lines written shall be in the +collating sequence of the original lines. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All input files were successfully output as specified. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +If the input files are not properly presorted, the output of \fIcomm\fP +might not be useful. +.SH EXAMPLES +.LP +If a file named \fBxcu\fP contains a sorted list of the utilities +in this volume of IEEE\ Std\ 1003.1-2001, a file +named \fBxpg3\fP contains a sorted list of the utilities specified +in the X/Open Portability Guide, Issue 3, and a file named +\fBsvid89\fP contains a sorted list of the utilities in the System +V Interface Definition Third Edition: +.sp +.RS +.nf + +\fBcomm -23 xcu xpg3 | comm -23 - svid89 +\fP +.fi +.RE +.LP +would print a list of utilities in this volume of IEEE\ Std\ 1003.1-2001 +not specified by either of the other +documents: +.sp +.RS +.nf + +\fBcomm -12 xcu xpg3 | comm -12 - svid89 +\fP +.fi +.RE +.LP +would print a list of utilities specified by all three documents, +and: +.sp +.RS +.nf + +\fBcomm -12 xpg3 svid89 | comm -23 - xcu +\fP +.fi +.RE +.LP +would print a list of utilities specified by both XPG3 and the SVID, +but not specified in this volume of +IEEE\ Std\ 1003.1-2001. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcmp\fP , \fIdiff\fP , \fIsort\fP , \fIuniq\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/command.1p b/man1p/command.1p new file mode 100644 index 000000000..7b33799b7 --- /dev/null +++ b/man1p/command.1p @@ -0,0 +1,484 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "COMMAND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" command +.SH NAME +command \- execute a simple command +.SH SYNOPSIS +.LP +\fBcommand\fP \fB[\fP\fB-p\fP\fB]\fP \fIcommand_name\fP \fB[\fP\fIargument\fP +\fB\&...\fP\fB]\fP\fB +.br +.sp +\fP +.LP +\fBcommand\fP \fB[\fP \fB-v | -V\fP \fB]\fP \fIcommand_name\fP\fB\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIcommand\fP utility shall cause the shell to treat the arguments +as a simple command, suppressing the shell function +lookup that is described in \fICommand Search and Execution\fP , item +1b. +.LP +If the \fIcommand_name\fP is the same as the name of one of the special +built-in utilities, the special properties in the +enumerated list at the beginning of \fISpecial Built-In Utilities\fP +shall not occur. In +every other respect, if \fIcommand_name\fP is not the name of a function, +the effect of \fIcommand\fP (with no options) shall be +the same as omitting \fIcommand\fP. +.LP +On systems supporting the User Portability Utilities option, the \fIcommand\fP +utility also shall provide information +concerning how a command name is interpreted by the shell; see \fB-v\fP +and \fB-V\fP. +.SH OPTIONS +.LP +The \fIcommand\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-p\fP +Perform the command search using a default value for \fIPATH\fP that +is guaranteed to find all of the standard utilities. +.TP 7 +\fB-v\fP +(On systems supporting the User Portability Utilities option.) Write +a string to standard output that indicates the pathname or +command that will be used by the shell, in the current shell execution +environment (see \fIShell Execution Environment\fP ), to invoke \fIcommand_name\fP, +but do not invoke +\fIcommand_name\fP. +.RS +.IP " *" 3 +Utilities, regular built-in utilities, \fIcommand_name\fPs including +a slash character, and any implementation-defined +functions that are found using the \fIPATH\fP variable (as described +in \fICommand +Search and Execution\fP ), shall be written as absolute pathnames. +.LP +.IP " *" 3 +Shell functions, special built-in utilities, regular built-in utilities +not associated with a \fIPATH\fP search, and shell +reserved words shall be written as just their names. +.LP +.IP " *" 3 +An alias shall be written as a command line that represents its alias +definition. +.LP +.IP " *" 3 +Otherwise, no output shall be written and the exit status shall reflect +that the name was not found. +.LP +.RE +.TP 7 +\fB-V\fP +(On systems supporting the User Portability Utilities option.) Write +a string to standard output that indicates how the name +given in the \fIcommand_name\fP operand will be interpreted by the +shell, in the current shell execution environment (see \fIShell Execution +Environment\fP ), but do not invoke \fIcommand_name\fP. Although the +format of +this string is unspecified, it shall indicate in which of the following +categories \fIcommand_name\fP falls and shall include the +information stated: +.RS +.IP " *" 3 +Utilities, regular built-in utilities, and any implementation-defined +functions that are found using the \fIPATH\fP variable +(as described in \fICommand Search and Execution\fP ), shall be identified +as such +and include the absolute pathname in the string. +.LP +.IP " *" 3 +Other shell functions shall be identified as functions. +.LP +.IP " *" 3 +Aliases shall be identified as aliases and their definitions included +in the string. +.LP +.IP " *" 3 +Special built-in utilities shall be identified as special built-in +utilities. +.LP +.IP " *" 3 +Regular built-in utilities not associated with a \fIPATH\fP search +shall be identified as regular built-in utilities. (The term +"regular" need not be used.) +.LP +.IP " *" 3 +Shell reserved words shall be identified as reserved words. +.LP +.RE +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIargument\fP +One of the strings treated as an argument to \fIcommand_name\fP. +.TP 7 +\fIcommand_name\fP +.sp +The name of a utility or a special built-in utility. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIcommand\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPATH\fP +Determine the search path used during the command search described +in \fICommand +Search and Execution\fP , except as described under the \fB-p\fP option. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +When the \fB-v\fP option is specified, standard output shall be formatted +as: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIpathname or command\fP\fB> +\fP +.fi +.RE +.LP +When the \fB-V\fP option is specified, standard output shall be formatted +as: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIunspecified\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +When the \fB-v\fP or \fB-V\fP options are specified, the following +exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +The \fIcommand_name\fP could not be found or an error occurred. +.sp +.LP +Otherwise, the following exit values shall be returned: +.TP 7 +126 +The utility specified by \fIcommand_name\fP was found but could not +be invoked. +.TP 7 +127 +An error occurred in the \fIcommand\fP utility or the utility specified +by \fIcommand_name\fP could not be found. +.sp +.LP +Otherwise, the exit status of \fIcommand\fP shall be that of the simple +command specified by the arguments to +\fIcommand\fP. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The order for command search allows functions to override regular +built-ins and path searches. This utility is necessary to +allow functions that have the same name as a utility to call the utility +(instead of a recursive call to the function). +.LP +The system default path is available using \fIgetconf\fP; however, +since \fIgetconf\fP may need to have the \fIPATH\fP set up before +it can be called itself, the +following can be used: +.sp +.RS +.nf + +\fBcommand -p getconf _CS_PATH +\fP +.fi +.RE +.LP +There are some advantages to suppressing the special characteristics +of special built-ins on occasion. For example: +.sp +.RS +.nf + +\fBcommand exec >\fP \fIunwritable-file\fP +.fi +.RE +.LP +does not cause a non-interactive script to abort, so that the output +status can be checked by the script. +.LP +The \fIcommand\fP, \fIenv\fP, \fInohup\fP, \fItime\fP, and \fIxargs\fP +utilities have been specified to +use exit code 127 if an error occurs so that applications can distinguish +"failure to find a utility" from "invoked utility +exited with an error indication". The value 127 was chosen because +it is not commonly used for other meanings; most utilities use +small values for "normal error conditions" and the values above 128 +can be confused with termination due to receipt of a signal. +The value 126 was chosen in a similar manner to indicate that the +utility could be found, but not invoked. Some scripts produce +meaningful error messages differentiating the 126 and 127 cases. The +distinction between exit codes 126 and 127 is based on +KornShell practice that uses 127 when all attempts to \fIexec\fP the +utility fail with [ENOENT], and uses 126 when any attempt to +\fIexec\fP the utility fails for any other reason. +.LP +Since the \fB-v\fP and \fB-V\fP options of \fIcommand\fP produce output +in relation to the current shell execution +environment, \fIcommand\fP is generally provided as a shell regular +built-in. If it is called in a subshell or separate utility +execution environment, such as one of the following: +.sp +.RS +.nf + +\fB(PATH=foo command -v) + nohup command -v +\fP +.fi +.RE +.LP +it does not necessarily produce correct results. For example, when +called with \fInohup\fP or an \fIexec\fP function, in a separate utility +execution environment, most +implementations are not able to identify aliases, functions, or special +built-ins. +.LP +Two types of regular built-ins could be encountered on a system and +these are described separately by \fIcommand\fP. The +description of command search in \fICommand Search and Execution\fP +allows for a +standard utility to be implemented as a regular built-in as long as +it is found in the appropriate place in a \fIPATH\fP search. +So, for example, \fIcommand\fP \fB-v\fP \fItrue\fP might yield \fB/bin/true\fP +or some similar pathname. Other +implementation-defined utilities that are not defined by this volume +of IEEE\ Std\ 1003.1-2001 might exist only as +built-ins and have no pathname associated with them. These produce +output identified as (regular) built-ins. Applications +encountering these are not able to count on \fIexec\fPing them, using +them with \fInohup\fP, overriding them with a different \fIPATH ,\fP +and so on. +.SH EXAMPLES +.IP " 1." 4 +Make a version of \fIcd\fP that always prints out the new working +directory exactly +once: +.sp +.RS +.nf + +\fBcd() { + command cd "$@" >/dev/null + pwd +} +\fP +.fi +.RE +.LP +.IP " 2." 4 +Start off a "secure shell script" in which the script avoids being +spoofed by its parent: +.sp +.RS +.nf + +\fBIFS=' +' +# The preceding value should be . +# Set IFS to its default value. +.sp + +\\unalias -a +# Unset all possible aliases. +# Note that unalias is escaped to prevent an alias +# being used for unalias. +.sp + +unset -f command +# Ensure command is not a user function. +.sp + +PATH="$(command -p getconf _CS_PATH):$PATH" +# Put on a reliable PATH prefix. +.sp + +# ... +\fP +.fi +.RE +.LP +At this point, given correct permissions on the directories called +by \fIPATH ,\fP the script has the ability to ensure that +any utility it calls is the intended one. It is being very cautious +because it assumes that implementation extensions may be +present that would allow user functions to exist when it is invoked; +this capability is not specified by this volume of +IEEE\ Std\ 1003.1-2001, but it is not prohibited as an extension. +For example, the \fIENV\fP variable precedes the +invocation of the script with a user start-up script. Such a script +could define functions to spoof the application. +.LP +.SH RATIONALE +.LP +Since \fIcommand\fP is a regular built-in utility it is always found +prior to the \fIPATH\fP search. +.LP +There is nothing in the description of \fIcommand\fP that implies +the command line is parsed any differently from that of any +other simple command. For example: +.sp +.RS +.nf + +\fBcommand a | b ; c +\fP +.fi +.RE +.LP +is not parsed in any special way that causes \fB'|'\fP or \fB';'\fP +to be treated other than a pipe operator or semicolon +or that prevents function lookup on \fBb\fP or \fBc\fP. +.LP +The \fIcommand\fP utility is somewhat similar to the Eighth Edition +shell \fIbuiltin\fP command, but since \fIcommand\fP also +goes to the file system to search for utilities, the name \fIbuiltin\fP +would not be intuitive. +.LP +The \fIcommand\fP utility is most likely to be provided as a regular +built-in. It is not listed as a special built-in for the +following reasons: +.IP " *" 3 +The removal of exportable functions made the special precedence of +a special built-in unnecessary. +.LP +.IP " *" 3 +A special built-in has special properties (see \fISpecial Built-In +Utilities\fP ) that +were inappropriate for invoking other utilities. For example, two +commands such as: +.sp +.RS +.nf + +\fBdate >\fP \fIunwritable-file\fP\fB +.br + +command date >\fP \fIunwritable-file\fP +.fi +.RE +.LP +would have entirely different results; in a non-interactive script, +the former would continue to execute the next command, the +latter would abort. Introducing this semantic difference along with +suppressing functions was seen to be non-intuitive. +.LP +.LP +The \fB-p\fP option is present because it is useful to be able to +ensure a safe path search that finds all the standard +utilities. This search might not be identical to the one that occurs +through one of the \fIexec\fP functions (as defined in the +System Interfaces volume of IEEE\ Std\ 1003.1-2001) when \fIPATH\fP +is unset. At the very least, this feature is required +to allow the script to access the correct version of \fIgetconf\fP +so that the value of +the default path can be accurately retrieved. +.LP +The \fIcommand\fP \fB-v\fP and \fB-V\fP options were added to satisfy +requirements from users that are currently accomplished +by three different historical utilities: \fItype\fP in the System +V shell, \fIwhence\fP in +the KornShell, and \fIwhich\fP in the C shell. Since there is no historical +agreement on how and what to accomplish here, the +POSIX \fIcommand\fP utility was enhanced and the historical utilities +were left unmodified. The C shell \fIwhich\fP merely +conducts a path search. The KornShell \fIwhence\fP is more elaborate-in +addition to the categories required by POSIX, it also +reports on tracked aliases, exported aliases, and undefined functions. +.LP +The output format of \fB-V\fP was left mostly unspecified because +human users are its only audience. Applications should not be +written to care about this information; they can use the output of +\fB-v\fP to differentiate between various types of commands, +but the additional information that may be emitted by the more verbose +\fB-V\fP is not needed and should not be arbitrarily +constrained in its verbosity or localization for application parsing +reasons. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fICommand Search and Execution\fP , \fIShell +Execution Environment\fP , \fISpecial Built-In Utilities\fP , \fIsh\fP +, \fItype\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIexec\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/compress.1p b/man1p/compress.1p new file mode 100644 index 000000000..ed7f5d231 --- /dev/null +++ b/man1p/compress.1p @@ -0,0 +1,216 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "COMPRESS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" compress +.SH NAME +compress \- compress data +.SH SYNOPSIS +.LP +\fBcompress\fP \fB[\fP\fB-fv\fP\fB][\fP\fB-b\fP \fIbits\fP\fB][\fP\fIfile\fP +\fB\&...\fP\fB]\fP\fB +.br +.sp +compress\fP \fB[\fP\fB-cfv\fP\fB][\fP\fB-b\fP \fIbits\fP\fB][\fP\fIfile\fP\fB]\fP\fB\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIcompress\fP utility shall attempt to reduce the size of the +named files by using adaptive Lempel-Ziv coding algorithm. +.TP 7 +\fBNote:\fP +Lempel-Ziv is US Patent 4464650, issued to William Eastman, Abraham +Lempel, Jacob Ziv, Martin Cohn on August 7th, 1984, and +assigned to Sperry Corporation. +.LP +Lempel-Ziv-Welch compression is covered by US Patent 4558302, issued +to Terry A. Welch on December 10th, 1985, and assigned to +Sperry Corporation. +.sp +On systems not supporting adaptive Lempel-Ziv coding algorithm, the +input files shall not be changed and an +error value greater than two shall be returned. Except when the output +is to the standard output, each file shall be replaced by +one with the extension \fB.Z\fP. If the invoking process has appropriate +privileges, the ownership, modes, access time, and +modification time of the original file are preserved. If appending +the \fB.Z\fP to the filename would make the name exceed +{NAME_MAX} bytes, the command shall fail. If no files are specified, +the standard input shall be compressed to the standard +output. +.SH OPTIONS +.LP +The \fIcompress\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-b\ \fP \fIbits\fP +Specify the maximum number of bits to use in a code. For a conforming +application, the \fIbits\fP argument shall be: +.sp +.RS +.nf + +\fB9 <=\fP \fIbits\fP \fB<= 14 +\fP +.fi +.RE +.LP +The implementation may allow \fIbits\fP values of greater than 14. +The default is 14, 15, or 16. +.TP 7 +\fB-c\fP +Cause \fIcompress\fP to write to the standard output; the input file +is not changed, and no \fB.Z\fP files are created. +.TP 7 +\fB-f\fP +Force compression of \fIfile\fP, even if it does not actually reduce +the size of the file, or if the corresponding \fIfile\fP +\fB\&.Z\fP file already exists. If the \fB-f\fP option is not given, +and the process is not running in the background, the user is +prompted as to whether an existing \fIfile\fP \fB.Z\fP file should +be overwritten. +.TP 7 +\fB-v\fP +Write the percentage reduction of each file to standard error. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a file to be compressed. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified, or if a \fIfile\fP operand is \fB'-'\fP +\&. +.SH INPUT FILES +.LP +If \fIfile\fP operands are specified, the input files contain the +data to be compressed. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIcompress\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If no \fIfile\fP operands are specified, or if a \fIfile\fP operand +is \fB'-'\fP , or if the \fB-c\fP option is specified, +the standard output contains the compressed output. +.SH STDERR +.LP +The standard error shall be used only for diagnostic and prompt messages +and the output from \fB-v\fP. +.SH OUTPUT FILES +.LP +The output files shall contain the compressed output. The format of +compressed files is unspecified and interchange of such +files between implementations (including access via unspecified file +sharing mechanisms) is not required by +IEEE\ Std\ 1003.1-2001. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +\ 1 +An error occurred. +.TP 7 +\ 2 +One or more files were not compressed because they would have increased +in size (and the \fB-f\fP option was not +specified). +.TP 7 +>2 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +The input file shall remain unmodified. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The amount of compression obtained depends on the size of the input, +the number of \fIbits\fP per code, and the distribution of +common substrings. Typically, text such as source code or English +is reduced by 50-60%. Compression is generally much better than +that achieved by Huffman coding or adaptive Huffman coding ( \fIcompact\fP), +and takes less time to compute. +.LP +Although \fIcompress\fP strictly follows the default actions upon +receipt of a signal or when an error occurs, some unexpected +results may occur. In some implementations it is likely that a partially +compressed file is left in place, alongside its +uncompressed input file. Since the general operation of \fIcompress\fP +is to delete the uncompressed file only after the \fB.Z\fP +file has been successfully filled, an application should always carefully +check the exit status of \fIcompress\fP before +arbitrarily deleting files that have like-named neighbors with \fB.Z\fP +suffixes. +.LP +The limit of 14 on the \fIbits\fP option-argument is to achieve portability +to all systems (within the restrictions imposed by +the lack of an explicit published file format). Some implementations +based on 16-bit architectures cannot support 15 or 16-bit +uncompression. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIuncompress\fP , \fIzcat\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/continue.1p b/man1p/continue.1p new file mode 100644 index 000000000..b9fa7cd35 --- /dev/null +++ b/man1p/continue.1p @@ -0,0 +1,102 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CONTINUE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" continue +.SH NAME +continue \- continue for, while, or until loop +.SH SYNOPSIS +.LP +\fBcontinue\fP \fB[\fP\fIn\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIcontinue\fP utility shall return to the top of the smallest +enclosing \fBfor\fP, \fBwhile\fP, or \fBuntil\fP loop, or +to the top of the \fIn\fPth enclosing loop, if \fIn\fP is specified. +This involves repeating the condition list of a \fBwhile\fP +or \fBuntil\fP loop or performing the next assignment of a \fBfor\fP +loop, and re-executing the loop if appropriate. +.LP +The value of \fIn\fP is a decimal integer greater than or equal to +1. The default shall be equivalent to \fIn\fP=1. If +\fIn\fP is greater than the number of enclosing loops, the outermost +enclosing loop shall be used. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +See the DESCRIPTION. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +None. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +The \fIn\fP value was not an unsigned decimal integer greater than +or equal to 1. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.sp +.RS +.nf + +\fBfor i in * +do + if test -d "$i" + then continue + fi + echo "\\"$i\\"" is not a directory. +done +\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISpecial Built-In Utilities\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/cp.1p b/man1p/cp.1p new file mode 100644 index 000000000..2cb597da9 --- /dev/null +++ b/man1p/cp.1p @@ -0,0 +1,634 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cp +.SH NAME +cp \- copy files +.SH SYNOPSIS +.LP +\fBcp\fP \fB[\fP\fB-fip\fP\fB]\fP \fIsource_file target_file\fP\fB +.br +.sp +cp\fP \fB[\fP\fB-fip\fP\fB]\fP \fIsource_file\fP \fB...\fP \fItarget\fP\fB +.br +.sp +cp -R\fP \fB[\fP\fB-H | -L | -P\fP\fB][\fP\fB-fip\fP\fB]\fP \fIsource_file\fP +\fB\&...\fP \fItarget\fP\fB +.br +.sp +cp -r\fP \fB[\fP\fB-H | -L | -P\fP\fB][\fP\fB-fip\fP\fB]\fP \fIsource_file\fP +\fB\&...\fP \fItarget\fP\fB +.br +\fP +.SH DESCRIPTION +.LP +The first synopsis form is denoted by two operands, neither of which +are existing files of type directory. The \fIcp\fP utility +shall copy the contents of \fIsource_file\fP (or, if \fIsource_file\fP +is a file of type symbolic link, the contents of the file +referenced by \fIsource_file\fP) to the destination path named by +\fItarget_file.\fP +.LP +The second synopsis form is denoted by two or more operands where +the \fB-R\fP or \fB-r\fP options are not specified and the +first synopsis form is not applicable. It shall be an error if any +\fIsource_file\fP is a file of type directory, if \fItarget\fP +does not exist, or if \fItarget\fP is a file of a type defined by +the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +but is not a file of type directory. The \fIcp\fP utility shall copy +the contents of each \fIsource_file\fP (or, if +\fIsource_file\fP is a file of type symbolic link, the contents of +the file referenced by \fIsource_file\fP) to the destination +path named by the concatenation of \fItarget\fP, a slash character, +and the last component of \fIsource_file\fP. +.LP +The third and fourth synopsis forms are denoted by two or more operands +where the \fB-R\fP or \fB-r\fP options are specified. +The \fIcp\fP utility shall copy each file in the file hierarchy rooted +in each \fIsource_file\fP to a destination path named as +follows: +.IP " *" 3 +If \fItarget\fP exists and is a file of type directory, the name of +the corresponding destination path for each file in the +file hierarchy shall be the concatenation of \fItarget\fP, a slash +character, and the pathname of the file relative to the +directory containing \fIsource_file\fP. +.LP +.IP " *" 3 +If \fItarget\fP does not exist and two operands are specified, the +name of the corresponding destination path for +\fIsource_file\fP shall be \fItarget\fP; the name of the corresponding +destination path for all other files in the file hierarchy +shall be the concatenation of \fItarget\fP, a slash character, and +the pathname of the file relative to \fIsource_file\fP. +.LP +.LP +It shall be an error if \fItarget\fP does not exist and more than +two operands are specified, or if \fItarget\fP exists and is +a file of a type defined by the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +but is not a file of type +directory. +.LP +In the following description, the term \fIdest_file\fP refers to the +file named by the destination path. The term +\fIsource_file\fP refers to the file that is being copied, whether +specified as an operand or a file in a file hierarchy rooted in +a \fIsource_file\fP operand. If \fIsource_file\fP is a file of type +symbolic link: +.IP " *" 3 +If neither the \fB-R\fP nor \fB-r\fP options were specified, \fIcp\fP +shall take actions based on the type and contents of +the file referenced by the symbolic link, and not by the symbolic +link itself. +.LP +.IP " *" 3 +If the \fB-R\fP option was specified: +.RS +.IP " *" 3 +If none of the options \fB-H\fP, \fB-L\fP, nor \fB-P\fP were specified, +it is unspecified which of \fB-H\fP, \fB-L\fP, or +\fB-P\fP will be used as a default. +.LP +.IP " *" 3 +If the \fB-H\fP option was specified, \fIcp\fP shall take actions +based on the type and contents of the file referenced by any +symbolic link specified as a \fIsource_file\fP operand. +.LP +.IP " *" 3 +If the \fB-L\fP option was specified, \fIcp\fP shall take actions +based on the type and contents of the file referenced by any +symbolic link specified as a \fIsource_file\fP operand or any symbolic +links encountered during traversal of a file hierarchy. +.LP +.IP " *" 3 +If the \fB-P\fP option was specified, \fIcp\fP shall copy any symbolic +link specified as a \fIsource_file\fP operand and any +symbolic links encountered during traversal of a file hierarchy, and +shall not follow any symbolic links. +.LP +.RE +.LP +.IP " *" 3 +If the \fB-r\fP option was specified, the behavior is implementation-defined. +.LP +.LP +For each \fIsource_file\fP, the following steps shall be taken: +.IP " 1." 4 +If \fIsource_file\fP references the same file as \fIdest_file\fP, +\fIcp\fP may write a diagnostic message to standard error; +it shall do nothing more with \fIsource_file\fP and shall go on to +any remaining files. +.LP +.IP " 2." 4 +If \fIsource_file\fP is of type directory, the following steps shall +be taken: +.RS +.IP " a." 4 +If neither the \fB-R\fP or \fB-r\fP options were specified, \fIcp\fP +shall write a diagnostic message to standard error, do +nothing more with \fIsource_file\fP, and go on to any remaining files. +.LP +.IP " b." 4 +If \fIsource_file\fP was not specified as an operand and \fIsource_file\fP +is dot or dot-dot, \fIcp\fP shall do nothing more +with \fIsource_file\fP and go on to any remaining files. +.LP +.IP " c." 4 +If \fIdest_file\fP exists and it is a file type not specified by the +System Interfaces volume of +IEEE\ Std\ 1003.1-2001, the behavior is implementation-defined. +.LP +.IP " d." 4 +If \fIdest_file\fP exists and it is not of type directory, \fIcp\fP +shall write a diagnostic message to standard error, do +nothing more with \fIsource_file\fP or any files below \fIsource_file\fP +in the file hierarchy, and go on to any remaining +files. +.LP +.IP " e." 4 +If the directory \fIdest_file\fP does not exist, it shall be created +with file permission bits set to the same value as those +of \fIsource_file\fP, modified by the file creation mask of the user +if the \fB-p\fP option was not specified, and then +bitwise-inclusively OR'ed with S_IRWXU. If \fIdest_file\fP cannot +be created, \fIcp\fP shall write a diagnostic message to +standard error, do nothing more with \fIsource_file\fP, and go on +to any remaining files. It is unspecified if \fIcp\fP attempts +to copy files in the file hierarchy rooted in \fIsource_file\fP. +.LP +.IP " f." 4 +The files in the directory \fIsource_file\fP shall be copied to the +directory \fIdest_file\fP, taking the four steps (1 to 4) +listed here with the files as \fIsource_file\fPs. +.LP +.IP " g." 4 +If \fIdest_file\fP was created, its file permission bits shall be +changed (if necessary) to be the same as those of +\fIsource_file\fP, modified by the file creation mask of the user +if the \fB-p\fP option was not specified. +.LP +.IP " h." 4 +The \fIcp\fP utility shall do nothing more with \fIsource_file\fP +and go on to any remaining files. +.LP +.RE +.LP +.IP " 3." 4 +If \fIsource_file\fP is of type regular file, the following steps +shall be taken: +.RS +.IP " a." 4 +If \fIdest_file\fP exists, the following steps shall be taken: +.RS +.IP "i. " 5 +If the \fB-i\fP option is in effect, the \fIcp\fP utility shall write +a prompt to the standard error and read a line from the +standard input. If the response is not affirmative, \fIcp\fP shall +do nothing more with \fIsource_file\fP and go on to any +remaining files. +.LP +.IP "ii." 5 +A file descriptor for \fIdest_file\fP shall be obtained by performing +actions equivalent to the \fIopen\fP() function defined in the System +Interfaces volume of IEEE\ Std\ 1003.1-2001 +called using \fIdest_file\fP as the \fIpath\fP argument, and the bitwise-inclusive +OR of O_WRONLY and O_TRUNC as the \fIoflag\fP +argument. +.LP +.IP "iii." 5 +If the attempt to obtain a file descriptor fails and the \fB-f\fP +option is in effect, \fIcp\fP shall attempt to remove the +file by performing actions equivalent to the \fIunlink\fP() function +defined in the System +Interfaces volume of IEEE\ Std\ 1003.1-2001 called using \fIdest_file\fP +as the \fIpath\fP argument. If this attempt +succeeds, \fIcp\fP shall continue with step 3b. +.LP +.RE +.LP +.IP " b." 4 +If \fIdest_file\fP does not exist, a file descriptor shall be obtained +by performing actions equivalent to the \fIopen\fP() function defined +in the System Interfaces volume of IEEE\ Std\ 1003.1-2001 +called using \fIdest_file\fP as the \fIpath\fP argument, and the bitwise-inclusive +OR of O_WRONLY and O_CREAT as the \fIoflag\fP +argument. The file permission bits of \fIsource_file\fP shall be the +\fImode\fP argument. +.LP +.IP " c." 4 +If the attempt to obtain a file descriptor fails, \fIcp\fP shall write +a diagnostic message to standard error, do nothing more +with \fIsource_file\fP, and go on to any remaining files. +.LP +.IP " d." 4 +The contents of \fIsource_file\fP shall be written to the file descriptor. +Any write errors shall cause \fIcp\fP to write a +diagnostic message to standard error and continue to step 3e. +.LP +.IP " e." 4 +The file descriptor shall be closed. +.LP +.IP " f." 4 +The \fIcp\fP utility shall do nothing more with \fIsource_file\fP. +If a write error occurred in step 3d, it is unspecified if +\fIcp\fP continues with any remaining files. If no write error occurred +in step 3d, \fIcp\fP shall go on to any remaining +files. +.LP +.RE +.LP +.IP " 4." 4 +Otherwise, the following steps shall be taken: +.RS +.IP " a." 4 +If the \fB-r\fP option was specified, the behavior is implementation-defined. +.LP +.IP " b." 4 +If the \fB-R\fP option was specified, the following steps shall be +taken: +.RS +.IP "i. " 5 +The \fIdest_file\fP shall be created with the same file type as \fIsource_file\fP. +.LP +.IP "ii." 5 +If \fIsource_file\fP is a file of type FIFO, the file permission bits +shall be the same as those of \fIsource_file,\fP +modified by the file creation mask of the user if the \fB-p\fP option +was not specified. Otherwise, the permissions, owner ID, and +group ID of \fIdest_file\fP are implementation-defined. +.LP +If this creation fails for any reason, \fIcp\fP shall write a diagnostic +message to standard error, do nothing more with +\fIsource_file\fP, and go on to any remaining files. +.LP +.IP "iii." 5 +If \fIsource_file\fP is a file of type symbolic link, the pathname +contained in \fIdest_file\fP shall be the same as the +pathname contained in \fIsource_file\fP. +.LP +If this fails for any reason, \fIcp\fP shall write a diagnostic message +to standard error, do nothing more with +\fIsource_file\fP, and go on to any remaining files. +.LP +.RE +.LP +.RE +.LP +.LP +If the implementation provides additional or alternate access control +mechanisms (see the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.4, File Access Permissions), their +effect on copies of files is implementation-defined. +.SH OPTIONS +.LP +The \fIcp\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-f\fP +If a file descriptor for a destination file cannot be obtained, as +described in step 3.a.ii., attempt to unlink the destination +file and proceed. +.TP 7 +\fB-H\fP +Take actions based on the type and contents of the file referenced +by any symbolic link specified as a \fIsource_file\fP +operand. +.TP 7 +\fB-i\fP +Write a prompt to standard error before copying to any existing destination +file. If the response from the standard input is +affirmative, the copy shall be attempted; otherwise, it shall not. +.TP 7 +\fB-L\fP +Take actions based on the type and contents of the file referenced +by any symbolic link specified as a \fIsource_file\fP +operand or any symbolic links encountered during traversal of a file +hierarchy. +.TP 7 +\fB-P\fP +Take actions on any symbolic link specified as a \fIsource_file\fP +operand or any symbolic link encountered during traversal +of a file hierarchy. +.TP 7 +\fB-p\fP +Duplicate the following characteristics of each source file in the +corresponding destination file: +.RS +.IP " 1." 4 +The time of last data modification and time of last access. If this +duplication fails for any reason, \fIcp\fP shall write a +diagnostic message to standard error. +.LP +.IP " 2." 4 +The user ID and group ID. If this duplication fails for any reason, +it is unspecified whether \fIcp\fP writes a diagnostic +message to standard error. +.LP +.IP " 3." 4 +The file permission bits and the S_ISUID and S_ISGID bits. Other, +implementation-defined, bits may be duplicated as well. If +this duplication fails for any reason, \fIcp\fP shall write a diagnostic +message to standard error. +.LP +.RE +.LP +If the user ID or the group ID cannot be duplicated, the file permission +bits S_ISUID and S_ISGID shall be cleared. If these +bits are present in the source file but are not duplicated in the +destination file, it is unspecified whether \fIcp\fP writes a +diagnostic message to standard error. +.LP +The order in which the preceding characteristics are duplicated is +unspecified. The \fIdest_file\fP shall not be deleted if +these characteristics cannot be preserved. +.TP 7 +\fB-R\fP +Copy file hierarchies. +.TP 7 +\fB-r\fP +Copy file hierarchies. The treatment of special files is implementation-defined. +.sp +.LP +Specifying more than one of the mutually-exclusive options \fB-H\fP, +\fB-L\fP, and \fB-P\fP shall not be considered an error. +The last option specified shall determine the behavior of the utility. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIsource_file\fP +A pathname of a file to be copied. +.TP 7 +\fItarget_file\fP +A pathname of an existing or nonexistent file, used for the output +when a single file is copied. +.TP 7 +\fItarget\fP +A pathname of a directory to contain the copied files. +.sp +.SH STDIN +.LP +The standard input shall be used to read an input line in response +to each prompt specified in the STDERR section. Otherwise, +the standard input shall not be used. +.SH INPUT FILES +.LP +The input files specified as operands may be of any file type. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIcp\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended +regular expression defined for the \fByesexpr\fP locale keyword in +the \fILC_MESSAGES\fP category. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and +the behavior of character classes used in the extended regular +expression defined for the \fByesexpr\fP locale keyword in the \fILC_MESSAGES\fP +category. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale for the processing of affirmative responses that +should be used to affect the format and contents of +diagnostic messages written to standard error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +A prompt shall be written to standard error under the conditions specified +in the DESCRIPTION section. The prompt shall contain +the destination pathname, but its format is otherwise unspecified. +Otherwise, the standard error shall be used only for diagnostic +messages. +.SH OUTPUT FILES +.LP +The output files may be of any type. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All files were copied successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If \fIcp\fP is prematurely terminated by a signal or error, files +or file hierarchies may be only partially copied and files +and directories may have incorrect permissions or access and modification +times. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The difference between \fB-R\fP and \fB-r\fP is in the treatment by +\fIcp\fP of file types other than regular and directory. +The original \fB-r\fP flag, for historic reasons, does not handle +special files any differently from regular files, but always +reads the file and copies its contents. This has obvious problems +in the presence of special file types; for example, character +devices, FIFOs, and sockets. The \fB-R\fP option is intended to recreate +the file hierarchy and the \fB-r\fP option supports +historical practice. It was anticipated that a future version of this +volume of IEEE\ Std\ 1003.1-2001 would deprecate the +\fB-r\fP option, and for that reason, there has been no attempt to +fix its behavior with respect to FIFOs or other file types +where copying the file is clearly wrong. However, some implementations +support \fB-r\fP with the same abilities as the \fB-R\fP +defined in this volume of IEEE\ Std\ 1003.1-2001. To accommodate them +as well as systems that do not, the differences +between \fB-r\fP and \fB-R\fP are implementation-defined. Implementations +may make them identical. The \fB-r\fP option is marked +obsolescent. +.LP +The set-user-ID and set-group-ID bits are explicitly cleared when +files are created. This is to prevent users from creating +programs that are set-user-ID or set-group-ID to them when copying +files or to make set-user-ID or set-group-ID files accessible to +new groups of users. For example, if a file is set-user-ID and the +copy has a different group ID than the source, a new group of +users has execute permission to a set-user-ID program than did previously. +In particular, this is a problem for superusers copying +users' trees. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fB-i\fP option exists on BSD systems, giving applications and +users a way to avoid accidentally removing files when +copying. Although the 4.3 BSD version does not prompt if the standard +input is not a terminal, the standard developers decided that +use of \fB-i\fP is a request for interaction, so when the destination +path exists, the utility takes instructions from whatever +responds on standard input. +.LP +The exact format of the interactive prompts is unspecified. Only the +general nature of the contents of prompts are specified +because implementations may desire more descriptive prompts than those +used on historical implementations. Therefore, an +application using the \fB-i\fP option relies on the system to provide +the most suitable dialog directly with the user, based on +the behavior specified. +.LP +The \fB-p\fP option is historical practice on BSD systems, duplicating +the time of last data modification and time of last +access. This volume of IEEE\ Std\ 1003.1-2001 extends it to preserve +the user and group IDs, as well as the file +permissions. This requirement has obvious problems in that the directories +are almost certainly modified after being copied. This +volume of IEEE\ Std\ 1003.1-2001 requires that the modification times +be preserved. The statement that the order in which +the characteristics are duplicated is unspecified is to permit implementations +to provide the maximum amount of security for the +user. Implementations should take into account the obvious security +issues involved in setting the owner, group, and mode in the +wrong order or creating files with an owner, group, or mode different +from the final value. +.LP +It is unspecified whether \fIcp\fP writes diagnostic messages when +the user and group IDs cannot be set due to the widespread +practice of users using \fB-p\fP to duplicate some portion of the +file characteristics, indifferent to the duplication of others. +Historic implementations only write diagnostic messages on errors +other than [EPERM]. +.LP +The \fB-r\fP option is historical practice on BSD and BSD-derived +systems, copying file hierarchies as opposed to single files. +This functionality is used heavily in historical applications, and +its loss would significantly decrease consensus. The \fB-R\fP +option was added as a close synonym to the \fB-r\fP option, selected +for consistency with all other options in this volume of +IEEE\ Std\ 1003.1-2001 that do recursive directory descent. +.LP +When a failure occurs during the copying of a file hierarchy, \fIcp\fP +is required to attempt to copy files that are on the +same level in the hierarchy or above the file where the failure occurred. +It is unspecified if \fIcp\fP shall attempt to copy +files below the file where the failure occurred (which cannot succeed +in any case). +.LP +Permissions, owners, and groups of created special file types have +been deliberately left as implementation-defined. This is to +allow systems to satisfy special requirements (for example, allowing +users to create character special devices, but requiring them +to be owned by a certain group). In general, it is strongly suggested +that the permissions, owner, and group be the same as if the +user had run the historical \fImknod\fP, \fIln\fP, or other utility +to create the file. It is +also probable that additional privileges are required to create block, +character, or other implementation-defined special file +types. +.LP +Additionally, the \fB-p\fP option explicitly requires that all set-user-ID +and set-group-ID permissions be discarded if any of +the owner or group IDs cannot be set. This is to keep users from unintentionally +giving away special privilege when copying +programs. +.LP +When creating regular files, historical versions of \fIcp\fP use the +mode of the source file as modified by the file mode +creation mask. Other choices would have been to use the mode of the +source file unmodified by the creation mask or to use the same +mode as would be given to a new file created by the user (plus the +execution bits of the source file) and then modify it by the +file mode creation mask. In the absence of any strong reason to change +historic practice, it was in large part retained. +.LP +When creating directories, historical versions of \fIcp\fP use the +mode of the source directory, plus read, write, and search +bits for the owner, as modified by the file mode creation mask. This +is done so that \fIcp\fP can copy trees where the user has +read permission, but the owner does not. A side effect is that if +the file creation mask denies the owner permissions, \fIcp\fP +fails. Also, once the copy is done, historical versions of \fIcp\fP +set the permissions on the created directory to be the same as +the source directory, unmodified by the file creation mask. +.LP +This behavior has been modified so that \fIcp\fP is always able to +create the contents of the directory, regardless of the file +creation mask. After the copy is done, the permissions are set to +be the same as the source directory, as modified by the file +creation mask. This latter change from historical behavior is to prevent +users from accidentally creating directories with +permissions beyond those they would normally set and for consistency +with the behavior of \fIcp\fP in creating files. +.LP +It is not a requirement that \fIcp\fP detect attempts to copy a file +to itself; however, implementations are strongly +encouraged to do so. Historical implementations have detected the +attempt in most cases. +.LP +There are two methods of copying subtrees in this volume of IEEE\ Std\ 1003.1-2001. +The other method is described as +part of the \fIpax\fP utility (see \fIpax\fP ). Both methods are +historical practice. The \fIcp\fP utility provides a simpler, more +intuitive interface, while \fIpax\fP offers a finer granularity of +control. Each provides additional functionality to the other; +in particular, \fIpax\fP maintains the hard-link structure of the +hierarchy, while \fIcp\fP +does not. It is the intention of the standard developers that the +results be similar (using appropriate option combinations in both +utilities). The results are not required to be identical; there seemed +insufficient gain to applications to balance the difficulty +of implementations having to guarantee that the results would be exactly +identical. +.LP +The wording allowing \fIcp\fP to copy a directory to implementation-defined +file types not specified by the System Interfaces +volume of IEEE\ Std\ 1003.1-2001 is provided so that implementations +supporting symbolic links are not required to prohibit +copying directories to symbolic links. Other extensions to the System +Interfaces volume of IEEE\ Std\ 1003.1-2001 file +types may need to use this loophole as well. +.SH FUTURE DIRECTIONS +.LP +The \fB-r\fP option may be removed; use \fB-R\fP instead. +.SH SEE ALSO +.LP +\fImv\fP , \fIfind\fP , \fIln\fP , \fIpax\fP , the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, \fIopen\fP(), \fIunlink\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/crontab.1p b/man1p/crontab.1p new file mode 100644 index 000000000..49353d7c6 --- /dev/null +++ b/man1p/crontab.1p @@ -0,0 +1,321 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CRONTAB" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" crontab +.SH NAME +crontab \- schedule periodic background work +.SH SYNOPSIS +.LP +\fBcrontab\fP \fB[\fP\fIfile\fP\fB]\fP\fB +.br +.sp +crontab\fP \fB[\fP \fB-e | -l | -r\fP \fB]\fP\fB\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIcrontab\fP utility shall create, replace, or edit a user's +crontab entry; a crontab entry is a list of commands and the +times at which they shall be executed. The new crontab entry can be +input by specifying \fIfile\fP or input from standard input if +no \fIfile\fP operand is specified, or by using an editor, if \fB-e\fP +is specified. +.LP +Upon execution of a command from a crontab entry, the implementation +shall supply a default environment, defining at least the +following environment variables: +.TP 7 +\fIHOME\fP +A pathname of the user's home directory. +.TP 7 +\fILOGNAME\fP +The user's login name. +.TP 7 +\fIPATH\fP +A string representing a search path guaranteed to find all of the +standard utilities. +.TP 7 +\fISHELL\fP +A pathname of the command interpreter. When \fIcrontab\fP is invoked +as specified by this volume of +IEEE\ Std\ 1003.1-2001, the value shall be a pathname for \fIsh\fP. +.sp +.LP +The values of these variables when \fIcrontab\fP is invoked as specified +by this volume of IEEE\ Std\ 1003.1-2001 shall +not affect the default values provided when the scheduled command +is run. +.LP +If standard output and standard error are not redirected by commands +executed from the crontab entry, any generated output or +errors shall be mailed, via an implementation-defined method, to the +user. +.LP +Users shall be permitted to use \fIcrontab\fP if their names appear +in the file \fB/usr/lib/cron/cron.allow\fP. If that file does +not exist, the file \fB/usr/lib/cron/cron.deny\fP shall be checked +to determine whether the user shall be denied access to +\fIcrontab\fP. If neither file exists, only a process with appropriate +privileges shall be allowed to submit a job. If only +\fBcron.deny\fP exists and is empty, global usage shall be permitted. +The \fBcron.allow\fP and \fBcron.deny\fP files shall +consist of one user name per line. +.SH OPTIONS +.LP +The \fIcrontab\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-e\fP +Edit a copy of the invoking user's crontab entry, or create an empty +entry to edit if the crontab entry does not exist. When +editing is complete, the entry shall be installed as the user's crontab +entry. +.TP 7 +\fB-l\fP +(The letter ell.) List the invoking user's crontab entry. +.TP 7 +\fB-r\fP +Remove the invoking user's crontab entry. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +The pathname of a file that contains specifications, in the format +defined in the INPUT FILES section, for crontab +entries. +.sp +.SH STDIN +.LP +See the INPUT FILES section. +.SH INPUT FILES +.LP +In the POSIX locale, the user or application shall ensure that a crontab +entry is a text file consisting of lines of six fields +each. The fields shall be separated by s. The first five fields +shall be integer patterns that specify the +following: +.IP " 1." 4 +Minute [0,59] +.LP +.IP " 2." 4 +Hour [0,23] +.LP +.IP " 3." 4 +Day of the month [1,31] +.LP +.IP " 4." 4 +Month of the year [1,12] +.LP +.IP " 5." 4 +Day of the week ([0,6] with 0=Sunday) +.LP +.LP +Each of these patterns can be either an asterisk (meaning all valid +values), an element, or a list of elements separated by +commas. An element shall be either a number or two numbers separated +by a hyphen (meaning an inclusive range). The specification of +days can be made by two fields (day of the month and day of the week). +If month, day of month, and day of week are all asterisks, +every day shall be matched. If either the month or day of month is +specified as an element or list, but the day of week is an +asterisk, the month and day of month fields shall specify the days +that match. If both month and day of month are specified as an +asterisk, but day of week is an element or list, then only the specified +days of the week match. Finally, if either the month or +day of month is specified as an element or list, and the day of week +is also specified as an element or list, then any day matching +either the month and day of month, or the day of week, shall be matched. +.LP +The sixth field of a line in a crontab entry is a string that shall +be executed by \fIsh\fP +at the specified times. A percent sign character in this field shall +be translated to a . Any character preceded by +a backslash (including the \fB'%'\fP ) shall cause that character +to be treated literally. Only the first line (up to a +\fB'%'\fP or end-of-line) of the command field shall be executed by +the command interpreter. The other lines shall be made +available to the command as standard input. +.LP +Blank lines and those whose first non- is \fB'#'\fP shall +be ignored. +.LP +The text files \fB/usr/lib/cron/cron.allow\fP and \fB/usr/lib/cron/cron.deny\fP +shall contain zero or more user names, one per +line, of users who are, respectively, authorized or denied access +to the service underlying the \fIcrontab\fP utility. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIcrontab\fP: +.TP 7 +\fIEDITOR\fP +Determine the editor to be invoked when the \fB-e\fP option is specified. +The default editor shall be \fIvi\fP. +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If the \fB-l\fP option is specified, the crontab entry shall be written +to the standard output. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +The user's crontab entry is not submitted, removed, edited, or listed. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The format of the crontab entry shown here is guaranteed only for +the POSIX locale. Other cultures may be supported with +substantially different interfaces, although implementations are encouraged +to provide comparable levels of functionality. +.LP +The default settings of the \fIHOME ,\fP \fILOGNAME ,\fP \fIPATH ,\fP +and \fISHELL\fP variables that are given to the +scheduled job are not affected by the settings of those variables +when \fIcrontab\fP is run; as stated, they are defaults. The +text about "invoked as specified by this volume of IEEE\ Std\ 1003.1-2001" +means that the implementation may provide +extensions that allow these variables to be affected at runtime, but +that the user has to take explicit action in order to access +the extension, such as give a new option flag or modify the format +of the crontab entry. +.LP +A typical user error is to type only \fIcrontab\fP; this causes the +system to wait for the new crontab entry on standard input. +If end-of-file is typed (generally -D), the crontab entry +is replaced by an empty file. In this case, the user +should type the interrupt character, which prevents the crontab entry +from being replaced. +.SH EXAMPLES +.IP " 1." 4 +Clean up \fBcore\fP files every weekday morning at 3:15 am: +.sp +.RS +.nf + +\fB15 3 * * 1-5 find $HOME -name core 2>/dev/null | xargs rm -f +\fP +.fi +.RE +.LP +.IP " 2." 4 +Mail a birthday greeting: +.sp +.RS +.nf + +\fB0 12 14 2 * mailx john%Happy Birthday!%Time for lunch. +\fP +.fi +.RE +.LP +.IP " 3." 4 +As an example of specifying the two types of days: +.sp +.RS +.nf + +\fB0 0 1,15 * 1 +\fP +.fi +.RE +.LP +would run a command on the first and fifteenth of each month, as well +as on every Monday. To specify days by only one field, the +other field should be set to \fB'*'\fP ; for example: +.sp +.RS +.nf + +\fB0 0 * * 1 +\fP +.fi +.RE +.LP +would run a command only on Mondays. +.LP +.SH RATIONALE +.LP +All references to a \fIcron\fP daemon and to \fIcron\fP \fIfiles\fP +have been omitted. Although historical implementations +have used this arrangement, there is no reason to limit future implementations. +.LP +This description of \fIcrontab\fP is designed to support only users +with normal privileges. The format of the input is based on +the System V \fIcrontab\fP; however, there is no requirement here +that the actual system database used by the \fIcron\fP daemon +(or a similar mechanism) use this format internally. For example, +systems derived from BSD are likely to have an additional field +appended that indicates the user identity to be used when the job +is submitted. +.LP +The \fB-e\fP option was adopted from the SVID as a user convenience, +although it does not exist in all historical +implementations. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIat\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/csplit.1p b/man1p/csplit.1p new file mode 100644 index 000000000..b80d6bfb9 --- /dev/null +++ b/man1p/csplit.1p @@ -0,0 +1,269 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CSPLIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" csplit +.SH NAME +csplit \- split files based on context +.SH SYNOPSIS +.LP +\fBcsplit\fP \fB[\fP\fB-ks\fP\fB][\fP\fB-f\fP \fIprefix\fP\fB][\fP\fB-n\fP +\fInumber\fP\fB]\fP \fIfile arg1\fP \fB...\fP\fIargn\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIcsplit\fP utility shall read the file named by the \fIfile\fP +operand, write all or part of that file into other files +as directed by the \fIarg\fP operands, and write the sizes of the +files. +.SH OPTIONS +.LP +The \fIcsplit\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-f\ \fP \fIprefix\fP +Name the created files \fIprefix\fP \fB00\fP, \fIprefix\fP \fB01\fP, +\&..., \fIprefixn\fP. The default is \fBxx00\fP ... +\fBxx\fP \fIn\fP. If the \fIprefix\fP argument would create a filename +exceeding {NAME_MAX} bytes, an error shall result, +\fIcsplit\fP shall exit with a diagnostic message, and no files shall +be created. +.TP 7 +\fB-k\fP +Leave previously created files intact. By default, \fIcsplit\fP shall +remove created files if an error occurs. +.TP 7 +\fB-n\ \fP \fInumber\fP +Use \fInumber\fP decimal digits to form filenames for the file pieces. +The default shall be 2. +.TP 7 +\fB-s\fP +Suppress the output of file size messages. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile\fP +The pathname of a text file to be split. If \fIfile\fP is \fB'-'\fP +, the standard input shall be used. +.sp +.LP +The operands \fIarg1\fP ... \fIargn\fP can be a combination of the +following: +.TP 7 +/\fIrexp\fP/\fB[\fP\fIoffset\fP\fB]\fP +.sp +A file shall be created using the content of the lines from the current +line up to, but not including, the line that results from +the evaluation of the regular expression with \fIoffset\fP, if any, +applied. The regular expression \fIrexp\fP shall follow the +rules for basic regular expressions described in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 9.3, Basic Regular Expressions. +The application shall use the sequence +\fB"\\/"\fP to specify a slash character within the \fIrexp\fP. The +optional offset shall be a positive or negative integer +value representing a number of lines. A positive integer value can +be preceded by \fB'+'\fP . If the selection of lines from an +\fIoffset\fP expression of this type would create a file with zero +lines, or one with greater than the number of lines left in the +input file, the results are unspecified. After the section is created, +the current line shall be set to the line that results from +the evaluation of the regular expression with any offset applied. +If the current line is the first line in the file and a regular +expression operation has not yet been performed, the pattern match +of \fIrexp\fP shall be applied from the current line to the end +of the file. Otherwise, the pattern match of \fIrexp\fP shall be applied +from the line following the current line to the end of +the file. +.TP 7 +%\fIrexp\fP%\fB[\fP\fIoffset\fP\fB]\fP +.sp +Equivalent to /\fIrexp\fP/\fB[\fP\fIoffset\fP\fB]\fP, except that +no file shall be created for the selected section of the +input file. The application shall use the sequence \fB"\\%"\fP to +specify a percent-sign character within the \fIrexp\fP. +.TP 7 +\fIline_no\fP +Create a file from the current line up to (but not including) the +line number \fIline_no\fP. Lines in the file shall be +numbered starting at one. The current line becomes \fIline_no\fP. +.TP 7 +{\fInum\fP} +Repeat operand. This operand can follow any of the operands described +previously. If it follows a \fIrexp\fP type operand, +that operand shall be applied \fInum\fP more times. If it follows +a \fIline_no\fP operand, the file shall be split every +\fIline_no\fP lines, \fInum\fP times, from that point. +.sp +.LP +An error shall be reported if an operand does not reference a line +between the current position and the end of the file. +.SH STDIN +.LP +See the INPUT FILES section. +.SH INPUT FILES +.LP +The input file shall be a text file. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIcsplit\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular +expressions. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and +the behavior of character classes within regular +expressions. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +If the \fB-k\fP option is specified, created files shall be retained. +Otherwise, the default action occurs. +.SH STDOUT +.LP +Unless the \fB-s\fP option is used, the standard output shall consist +of one line per file created, with a format as +follows: +.sp +.RS +.nf + +\fB"%d\\n", <\fP\fIfile size in bytes\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +The output files shall contain portions of the original input file; +otherwise, unchanged. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +By default, created files shall be removed if an error occurs. When +the \fB-k\fP option is specified, created files shall not +be removed if an error occurs. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.IP " 1." 4 +This example creates four files, \fBcobol00\fP ... \fBcobol03\fP: +.sp +.RS +.nf + +\fBcsplit -f cobol file '/procedure division/' /par5./ /par16./ +\fP +.fi +.RE +.LP +After editing the split files, they can be recombined as follows: +.sp +.RS +.nf + +\fBcat cobol0[0-3] > file +\fP +.fi +.RE +.LP +Note that this example overwrites the original file. +.LP +.IP " 2." 4 +This example would split the file after the first 99 lines, and every +100 lines thereafter, up to 9999 lines; this is because +lines in the file are numbered from 1 rather than zero, for historical +reasons: +.sp +.RS +.nf + +\fBcsplit -k file 100 {99} +\fP +.fi +.RE +.LP +.IP " 3." 4 +Assuming that \fBprog.c\fP follows the C-language coding convention +of ending routines with a \fB'}'\fP at the beginning of +the line, this example creates a file containing each separate C routine +(up to 21) in \fBprog.c\fP: +.sp +.RS +.nf + +\fBcsplit -k prog.c '%main(%' '/^}/+1' {20} +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +The \fB-n\fP option was added to extend the range of filenames that +could be handled. +.LP +Consideration was given to adding a \fB-a\fP flag to use the alphabetic +filename generation used by the historical \fIsplit\fP utility, but +the functionality added by the \fB-n\fP option was deemed to make +alphabetic naming unnecessary. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsed\fP , \fIsplit\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/ctags.1p b/man1p/ctags.1p new file mode 100644 index 000000000..14526c528 --- /dev/null +++ b/man1p/ctags.1p @@ -0,0 +1,414 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CTAGS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ctags +.SH NAME +ctags \- create a tags file (\fBDEVELOPMENT\fP, \fBFORTRAN\fP) +.SH SYNOPSIS +.LP +\fBctags\fP \fB[\fP\fB-a\fP\fB][\fP\fB-f\fP \fItagsfile\fP\fB]\fP +\fIpathname\fP \fB... +.br +.sp +ctags -x\fP \fIpathname\fP \fB... \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIctags\fP utility shall be provided on systems that support +the User Portability Utilities option, the Software +Development Utilities option, and either or both of the C-Language +Development Utilities option and FORTRAN Development Utilities +option. On other systems, it is optional. +.LP +The \fIctags\fP utility shall write a \fItagsfile\fP or an index of +objects from C-language or FORTRAN source files specified +by the \fIpathname\fP operands. The \fItagsfile\fP shall list the +locators of language-specific objects within the source files. +A locator consists of a name, pathname, and either a search pattern +or a line number that can be used in searching for the object +definition. The objects that shall be recognized are specified in +the EXTENDED DESCRIPTION section. +.SH OPTIONS +.LP +The \fIctags\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-a\fP +Append to \fItagsfile\fP. +.TP 7 +\fB-f\ \fP \fItagsfile\fP +Write the object locator lists into \fItagsfile\fP instead of the +default file named \fBtags\fP in the current +directory. +.TP 7 +\fB-x\fP +Produce a list of object names, the line number, and filename in which +each is defined, as well as the text of that line, and +write this to the standard output. A \fItagsfile\fP shall not be created +when \fB-x\fP is specified. +.sp +.SH OPERANDS +.LP +The following \fIpathname\fP operands are supported: +.TP 7 +\fIfile\fP\fB.c\fP +Files with basenames ending with the \fB.c\fP suffix shall be treated +as C-language source code. Such files that are not valid +input to \fIc99\fP produce unspecified results. +.TP 7 +\fIfile\fP\fB.h\fP +Files with basenames ending with the \fB.h\fP suffix shall be treated +as C-language source code. Such files that are not valid +input to \fIc99\fP produce unspecified results. +.TP 7 +\fIfile\fP\fB.f\fP +Files with basenames ending with the \fB.f\fP suffix shall be treated +as FORTRAN-language source code. Such files that are not +valid input to \fIfort77\fP produce unspecified results. +.sp +.LP +The handling of other files is implementation-defined. +.SH STDIN +.LP +See the INPUT FILES section. +.SH INPUT FILES +.LP +The input files shall be text files containing source code in the +language indicated by the operand filename suffixes. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIctags\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the order in which output is sorted for the \fB-x\fP option. +The POSIX locale determines the order in which the +\fItagsfile\fP is written. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). When +processing C-language source code, if the locale is not +compatible with the C locale described by the ISO\ C standard, the +results are unspecified. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The list of object name information produced by the \fB-x\fP option +shall be written to standard output in the following +format: +.sp +.RS +.nf + +\fB"%s %d %s %s", <\fP\fIobject-name\fP\fB>, <\fP\fIline-number\fP\fB>, <\fP\fIfilename\fP\fB>, <\fP\fItext\fP\fB> +\fP +.fi +.RE +.LP +where <\fItext\fP> is the text of line <\fIline-number\fP> of file +<\fIfilename\fP>. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +When the \fB-x\fP option is not specified, the format of the output +file shall be: +.sp +.RS +.nf + +\fB"%s\\t%s\\t/%s/\\n", <\fP\fIidentifier\fP\fB>, <\fP\fIfilename\fP\fB>, <\fP\fIpattern\fP\fB> +\fP +.fi +.RE +.LP +where <\fIpattern\fP> is a search pattern that could be used by an +editor to find the defining instance of +<\fIidentifier\fP> in <\fIfilename\fP> (where \fIdefining instance\fP +is indicated by the declarations listed in the +EXTENDED DESCRIPTION). +.LP +An optional circumflex ( \fB'^'\fP ) can be added as a prefix to <\fIpattern\fP>, +and an optional dollar sign can be +appended to <\fIpattern\fP> to indicate that the pattern is anchored +to the beginning (end) of a line of text. Any slash or +backslash characters in <\fIpattern\fP> shall be preceded by a backslash +character. The anchoring circumflex, dollar sign, +and escaping backslash characters shall not be considered part of +the search pattern. All other characters in the search pattern +shall be considered literal characters. +.br +.LP +An alternative format is: +.sp +.RS +.nf + +\fB"%s\\t%s\\t?%s?\\n", <\fP\fIidentifier\fP\fB>, <\fP\fIfilename\fP\fB>, <\fP\fIpattern\fP\fB> +\fP +.fi +.RE +.LP +which is identical to the first format except that slashes in <\fIpattern\fP> +shall not be preceded by escaping backslash +characters, and question mark characters in <\fIpattern\fP> shall +be preceded by backslash characters. +.LP +A second alternative format is: +.sp +.RS +.nf + +\fB"%s\\t%s\\t%d\\n", <\fP\fIidentifier\fP\fB>, <\fP\fIfilename\fP\fB>, <\fP\fIlineno\fP\fB> +\fP +.fi +.RE +.LP +where <\fIlineno\fP> is a decimal line number that could be used by +an editor to find <\fIidentifier\fP> in +<\fIfilename\fP>. +.LP +Neither alternative format shall be produced by \fIctags\fP when it +is used as described by IEEE\ Std\ 1003.1-2001, but +the standard utilities that process tags files shall be able to process +those formats as well as the first format. +.LP +In any of these formats, the file shall be sorted by identifier, based +on the collation sequence in the POSIX locale. +.SH EXTENDED DESCRIPTION +.LP +If the operand identifies C-language source, the \fIctags\fP utility +shall attempt to produce an output line for each of the +following objects: +.IP " *" 3 +Function definitions +.LP +.IP " *" 3 +Type definitions +.LP +.IP " *" 3 +Macros with arguments +.LP +.LP +It may also produce output for any of the following objects: +.IP " *" 3 +Function prototypes +.LP +.IP " *" 3 +Structures +.LP +.IP " *" 3 +Unions +.LP +.IP " *" 3 +Global variable definitions +.LP +.IP " *" 3 +Enumeration types +.LP +.IP " *" 3 +Macros without arguments +.LP +.IP " *" 3 +\fB#define\fP statements +.LP +.IP " *" 3 +\fB#line\fP statements +.LP +.LP +Any \fB#if\fP and \fB#ifdef\fP statements shall produce no output. +The tag \fBmain\fP is treated specially in C programs. The +tag formed shall be created by prefixing \fBM\fP to the name of the +file, with the trailing \fB.c\fP, and leading pathname +components (if any) removed. +.LP +On systems that do not support the C-Language Development Utilities +option, \fIctags\fP produces unspecified results for +C-language source code files. It should write to standard error a +message identifying this condition and cause a non-zero exit +status to be produced. +.LP +If the operand identifies FORTRAN source, the \fIctags\fP utility +shall produce an output line for each function definition. It +may also produce output for any of the following objects: +.IP " *" 3 +Subroutine definitions +.LP +.IP " *" 3 +COMMON statements +.LP +.IP " *" 3 +PARAMETER statements +.LP +.IP " *" 3 +DATA and BLOCK DATA statements +.LP +.IP " *" 3 +Statement numbers +.LP +.LP +On systems that do not support the FORTRAN Development Utilities option, +\fIctags\fP produces unspecified results for FORTRAN +source code files. It should write to standard error a message identifying +this condition and cause a non-zero exit status to be +produced. +.LP +It is implementation-defined what other objects (including duplicate +identifiers) produce output. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The output with \fB-x\fP is meant to be a simple index that can be +written out as an off-line readable function index. If the +input files to \fIctags\fP (such as \fB.c\fP files) were not created +using the same locale as that in effect when \fIctags\fP +\fB-x\fP is run, results might not be as expected. +.LP +The description of C-language processing says "attempts to" because +the C language can be greatly confused, especially through +the use of \fB#define\fPs, and this utility would be of no use if +the real C preprocessor were run to identify them. The output +from \fIctags\fP may be fooled and incorrect for various constructs. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The option list was significantly reduced from that provided by historical +implementations. The \fB-F\fP option was omitted as +redundant, since it is the default. The \fB-B\fP option was omitted +as being of very limited usefulness. The \fB-t\fP option was +omitted since the recognition of \fBtypedef\fPs is now required for +C source files. The \fB-u\fP option was omitted because the +update function was judged to be not only inefficient, but also rarely +needed. +.LP +An early proposal included a \fB-w\fP option to suppress warning diagnostics. +Since the types of such diagnostics could not be +described, the option was omitted as being not useful. +.LP +The text for \fILC_CTYPE\fP about compatibility with the C locale +acknowledges that the ISO\ C standard imposes +requirements on the locale used to process C source. This could easily +be a superset of that known as "the C locale" by way of +implementation extensions, or one of a few alternative locales for +systems supporting different codesets. No statement is made for +FORTRAN because the ANSI\ X3.9-1978 standard (FORTRAN 77) does not +(yet) define a similar locale concept. However, a general +rule in this volume of IEEE\ Std\ 1003.1-2001 is that any time that +locales do not match (preparing a file for one locale +and processing it in another), the results are suspect. +.LP +The collation sequence of the tags file is not affected by \fILC_COLLATE\fP +because it is typically not used by human readers, +but only by programs such as \fIvi\fP to locate the tag within the +source files. Using the +POSIX locale eliminates some of the problems of coordinating locales +between the \fIctags\fP file creator and the \fIvi\fP file reader. +.LP +Historically, the tags file has been used only by \fIex\fP and \fIvi\fP. +However, the format of the tags file has been published to encourage +other programs to use +the tags in new ways. The format allows either patterns or line numbers +to find the identifiers because the historical \fIvi\fP recognizes +either. The \fIctags\fP utility does not produce the format using +line numbers +because it is not useful following any source file changes that add +or delete lines. The documented search patterns match +historical practice. It should be noted that literal leading circumflex +or trailing dollar-sign characters in the search pattern +will only behave correctly if anchored to the beginning of the line +or end of the line by an additional circumflex or dollar-sign +character. +.LP +Historical implementations also understand the objects used by the +languages Pascal and sometimes LISP, and they understand the +C source output by \fIlex\fP and \fIyacc\fP. The +\fIctags\fP utility is not required to accommodate these languages, +although implementors are encouraged to do so. +.LP +The following historical option was not specified, as \fIvgrind\fP +is not included in this volume of +IEEE\ Std\ 1003.1-2001: +.TP 7 +\fB-v\fP +If the \fB-v\fP flag is given, an index of the form expected by \fIvgrind\fP +is produced on the standard output. This listing +contains the function name, filename, and page number (assuming 64-line +pages). Since the output is sorted into lexicographic +order, it may be desired to run the output through \fIsort\fP \fB-f\fP. +Sample use: +.sp +.RS +.nf + +\fBctags -v files | sort -f > index vgrind -x index +\fP +.fi +.RE +.sp +.LP +The special treatment of the tag \fBmain\fP makes the use of \fIctags\fP +practical in directories with more than one +program. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIc99\fP , \fIfort77\fP , \fIvi\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/cut.1p b/man1p/cut.1p new file mode 100644 index 000000000..61ed475a3 --- /dev/null +++ b/man1p/cut.1p @@ -0,0 +1,362 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CUT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cut +.SH NAME +cut \- cut out selected fields of each line of a file +.SH SYNOPSIS +.LP +\fBcut -b\fP \fIlist\fP \fB[\fP\fB-n\fP\fB] [\fP\fIfile\fP \fB...\fP\fB]\fP\fB +.br +.sp +cut -c\fP \fIlist\fP \fB[\fP\fIfile\fP \fB...\fP\fB]\fP\fB +.br +.sp +cut -f\fP \fIlist\fP \fB[\fP\fB-d\fP \fIdelim\fP\fB][\fP\fB-s\fP\fB][\fP\fIfile\fP +\fB\&...\fP\fB]\fP\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIcut\fP utility shall cut out bytes ( \fB-b\fP option), characters +( \fB-c\fP option), or character-delimited fields ( +\fB-f\fP option) from each line in one or more files, concatenate +them, and write them to standard output. +.SH OPTIONS +.LP +The \fIcut\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The application shall ensure that the option-argument \fIlist\fP (see +options \fB-b\fP, \fB-c\fP, and \fB-f\fP below) is a +comma-separated list or -separated list of positive numbers +and ranges. Ranges can be in three forms. The first is two +positive numbers separated by a hyphen ( \fIlow\fP- \fIhigh\fP), which +represents all fields from the first number to the second +number. The second is a positive number preceded by a hyphen (- \fIhigh\fP), +which represents all fields from field number 1 to +that number. The third is a positive number followed by a hyphen ( +\fIlow\fP-), which represents that number to the last field, +inclusive. The elements in \fIlist\fP can be repeated, can overlap, +and can be specified in any order, but the bytes, characters, +or fields selected shall be written in the order of the input data. +If an element appears in the selection list more than once, it +shall be written exactly once. +.LP +The following options shall be supported: +.TP 7 +\fB-b\ \fP \fIlist\fP +Cut based on a \fIlist\fP of bytes. Each selected byte shall be output +unless the \fB-n\fP option is also specified. It shall +not be an error to select bytes not present in the input line. +.TP 7 +\fB-c\ \fP \fIlist\fP +Cut based on a \fIlist\fP of characters. Each selected character shall +be output. It shall not be an error to select +characters not present in the input line. +.TP 7 +\fB-d\ \fP \fIdelim\fP +Set the field delimiter to the character \fIdelim\fP. The default +is the . +.TP 7 +\fB-f\ \fP \fIlist\fP +Cut based on a \fIlist\fP of fields, assumed to be separated in the +file by a delimiter character (see \fB-d\fP). Each +selected field shall be output. Output fields shall be separated by +a single occurrence of the field delimiter character. Lines +with no field delimiters shall be passed through intact, unless \fB-s\fP +is specified. It shall not be an error to select fields +not present in the input line. +.TP 7 +\fB-n\fP +Do not split characters. When specified with the \fB-b\fP option, +each element in \fIlist\fP of the form \fIlow\fP- +\fIhigh\fP (hyphen-separated numbers) shall be modified as follows: +.RS +.IP " *" 3 +If the byte selected by \fIlow\fP is not the first byte of a character, +\fIlow\fP shall be decremented to select the first +byte of the character originally selected by \fIlow\fP. If the byte +selected by \fIhigh\fP is not the last byte of a character, +\fIhigh\fP shall be decremented to select the last byte of the character +prior to the character originally selected by +\fIhigh\fP, or zero if there is no prior character. If the resulting +range element has \fIhigh\fP equal to zero or \fIlow\fP +greater than \fIhigh\fP, the list element shall be dropped from \fIlist\fP +for that input line without causing an error. +.LP +.RE +.LP +Each element in \fIlist\fP of the form \fIlow\fP- shall be treated +as above with \fIhigh\fP set to the number of bytes in the +current line, not including the terminating . Each element +in \fIlist\fP of the form - \fIhigh\fP shall be treated +as above with \fIlow\fP set to 1. Each element in \fIlist\fP of the +form \fInum\fP (a single number) shall be treated as above +with \fIlow\fP set to \fInum\fP and \fIhigh\fP set to \fInum\fP. +.TP 7 +\fB-s\fP +Suppress lines with no delimiter characters, when used with the \fB-f\fP +option. Unless specified, lines with no delimiters +shall be passed through untouched. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of an input file. If no \fIfile\fP operands are specified, +or if a \fIfile\fP operand is \fB'-'\fP , the +standard input shall be used. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified, or if a \fIfile\fP operand is \fB'-'\fP . +See the INPUT FILES section. +.SH INPUT FILES +.LP +The input files shall be text files, except that line lengths shall +be unlimited. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIcut\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fIcut\fP utility output shall be a concatenation of the selected +bytes, characters, or fields (one of the following): +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIconcatenation of bytes\fP\fB> +.sp + +"%s\\n", <\fP\fIconcatenation of characters\fP\fB> +.sp + +"%s\\n", <\fP\fIconcatenation of fields and field delimiters\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All input files were output successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Earlier versions of the \fIcut\fP utility worked in an environment +where bytes and characters were considered equivalent +(modulo and processing in some implementations). +In the extended world of multi-byte characters, the +new \fB-b\fP option has been added. The \fB-n\fP option (used with +\fB-b\fP) allows it to be used to act on bytes rounded to +character boundaries. The algorithm specified for \fB-n\fP guarantees +that: +.sp +.RS +.nf + +\fBcut -b 1-500 -n file > file1 +cut -b 501- -n file > file2 +\fP +.fi +.RE +.LP +ends up with all the characters in \fBfile\fP appearing exactly once +in \fBfile1\fP or \fBfile2\fP. (There is, however, a + in both \fBfile1\fP and \fBfile2\fP for each in +\fBfile\fP.) +.SH EXAMPLES +.LP +Examples of the option qualifier list: +.TP 7 +1,4,7 +Select the first, fourth, and seventh bytes, characters, or fields +and field delimiters. +.TP 7 +1-3,8 +Equivalent to 1,2,3,8. +.TP 7 +-5,10 +Equivalent to 1,2,3,4,5,10. +.TP 7 +3- +Equivalent to third to last, inclusive. +.sp +.LP +The \fIlow\fP- \fIhigh\fP forms are not always equivalent when used +with \fB-b\fP and \fB-n\fP and multi-byte characters; +see the description of \fB-n\fP. +.LP +The following command: +.sp +.RS +.nf + +\fBcut -d : -f 1,6 /etc/passwd +\fP +.fi +.RE +.LP +reads the System V password file (user database) and produces lines +of the form: +.sp +.RS +.nf + +\fB<\fP\fIuser ID\fP\fB>:<\fP\fIhome directory\fP\fB> +\fP +.fi +.RE +.LP +Most utilities in this volume of IEEE\ Std\ 1003.1-2001 work on text +files. The \fIcut\fP utility can be used to turn +files with arbitrary line lengths into a set of text files containing +the same data. The \fIpaste\fP utility can be used to create (or recreate) +files with arbitrary line lengths. For +example, if \fBfile\fP contains long lines: +.sp +.RS +.nf + +\fBcut -b 1-500 -n file > file1 +cut -b 501- -n file > file2 +\fP +.fi +.RE +.LP +creates \fBfile1\fP (a text file) with lines no longer than 500 bytes +(plus the ) and \fBfile2\fP that contains +the remainder of the data from \fBfile\fP. (Note that \fBfile2\fP +is not a text file if there are lines in \fBfile\fP that are +longer than 500 + {LINE_MAX} bytes.) The original file can be recreated +from \fBfile1\fP and \fBfile2\fP using the command: +.sp +.RS +.nf + +\fBpaste -d "\\0" file1 file2 > file +\fP +.fi +.RE +.SH RATIONALE +.LP +Some historical implementations do not count s in determining +character counts with the \fB-c\fP option. This +may be useful for using \fIcut\fP for processing \fInroff\fP output. +It was deliberately decided not to have the \fB-c\fP option +treat either s or s in any special fashion. The \fIfold\fP +utility does treat these characters specially. +.LP +Unlike other utilities, some historical implementations of \fIcut\fP +exit after not finding an input file, rather than +continuing to process the remaining \fIfile\fP operands. This behavior +is prohibited by this volume of +IEEE\ Std\ 1003.1-2001, where only the exit status is affected by +this problem. +.LP +The behavior of \fIcut\fP when provided with either mutually-exclusive +options or options that do not work logically together +has been deliberately left unspecified in favor of global wording +in \fIUtility Description +Defaults\fP . +.LP +The OPTIONS section was changed in response to IEEE PASC Interpretation +1003.2 #149. The change represents historical practice +on all known systems. The original standard was ambiguous on the nature +of the output. +.LP +The \fIlist\fP option-arguments are historically used to select the +portions of the line to be written, but do not affect the +order of the data. For example: +.sp +.RS +.nf + +\fBecho abcdefghi | cut -c6,2,4-7,1 +\fP +.fi +.RE +.LP +yields \fB"abdefg"\fP . +.LP +A proposal to enhance \fIcut\fP with the following option: +.TP 7 +\fB-o\fP +Preserve the selected field order. When this option is specified, +each byte, character, or field (or ranges of such) shall be +written in the order specified by the \fIlist\fP option-argument, +even if this requires multiple outputs of the same bytes, +characters, or fields. +.sp +.LP +was rejected because this type of enhancement is outside the scope +of the IEEE\ P1003.2b draft standard. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgrep\fP , \fIpaste\fP , \fIParameters +and Variables\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/cxref.1p b/man1p/cxref.1p new file mode 100644 index 000000000..49e1b79cc --- /dev/null +++ b/man1p/cxref.1p @@ -0,0 +1,181 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CXREF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cxref +.SH NAME +cxref \- generate a C-language program cross-reference table (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBcxref\fP \fB[\fP\fB-cs\fP\fB][\fP\fB-o\fP \fIfile\fP\fB][\fP\fB-w\fP +\fInum\fP\fB] +[\fP\fB-D\fP \fIname\fP\fB[\fP\fB=\fP\fIdef\fP\fB]]\fP\fB...\fP\fB[\fP\fB-I\fP +\fIdir\fP\fB]\fP\fB... +.br +\ \ \ \ \ \ \fP \fB[\fP\fB-U\fP \fIname\fP\fB]\fP\fB...\fP \fIfile\fP +\fB\&... \fP +.SH DESCRIPTION +.LP +The \fIcxref\fP utility shall analyze a collection of C-language \fIfile\fPs +and attempt to build a cross-reference table. +Information from \fB#define\fP lines shall be included in the symbol +table. A sorted listing shall be written to standard output +of all symbols (auto, static, and global) in each \fIfile\fP separately, +or with the \fB-c\fP option, in combination. Each symbol +shall contain an asterisk before the declaring reference. +.SH OPTIONS +.LP +The \fIcxref\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that the order of the \fB-D\fP, +\fB-I\fP, and \fB-U\fP options (which are identical to their interpretation +by \fIc99\fP) is +significant. The following options shall be supported: +.TP 7 +\fB-c\fP +Write a combined cross-reference of all input files. +.TP 7 +\fB-s\fP +Operate silently; do not print input filenames. +.TP 7 +\fB-o\ \fP \fIfile\fP +Direct output to named \fIfile\fP. +.TP 7 +\fB-w\ \fP \fInum\fP +Format output no wider than \fInum\fP (decimal) columns. This option +defaults to 80 if \fInum\fP is not specified or is less +than 51. +.TP 7 +\fB-D\fP +Equivalent to \fIc99\fP. +.TP 7 +\fB-I\fP +Equivalent to \fIc99\fP. +.TP 7 +\fB-U\fP +Equivalent to \fIc99\fP. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a C-language source file. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +The input files are C-language source files. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIcxref\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the ordering of the output. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall be used for the cross-reference listing, +unless the \fB-o\fP option is used to select a different +output file. +.LP +The format of standard output is unspecified, except that the following +information shall be included: +.IP " *" 3 +If the \fB-c\fP option is not specified, each portion of the listing +shall start with the name of the input file on a separate +line. +.LP +.IP " *" 3 +The name line shall be followed by a sorted list of symbols, each +with its associated location pathname, the name of the +function in which it appears (if it is not a function name itself), +and line number references. +.LP +.IP " *" 3 +Each line number may be preceded by an asterisk ( \fB'*'\fP ) flag, +meaning that this is the declaring reference. Other +single-character flags, with implementation-defined meanings, may +be included. +.LP +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +The output file named by the \fB-o\fP option shall be used instead +of standard output. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIc99\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/date.1p b/man1p/date.1p new file mode 100644 index 000000000..0fa9828a5 --- /dev/null +++ b/man1p/date.1p @@ -0,0 +1,572 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" date +.SH NAME +date \- write the date and time +.SH SYNOPSIS +.LP +\fBdate\fP \fB[\fP\fB-u\fP\fB] [\fP\fB+\fP\fIformat\fP\fB]\fP\fB +.br +.sp +\fP +.LP +\fBdate\fP \fB[\fP\fB-u\fP\fB]\fP +\fImmddhhmm\fP\fB[[\fP\fIcc\fP\fB]\fP\fIyy\fP\fB]\fP\fB\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIdate\fP utility shall write the date and time to standard output +\ or attempt +to set the system date and time. By default, the current date and +time shall be written. If an operand beginning with \fB'+'\fP is specified, +the output format of \fIdate\fP shall be controlled +by the conversion specifications and other text in the operand. +.SH OPTIONS +.LP +The \fIdate\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-u\fP +Perform operations as if the \fITZ\fP environment variable was set +to the string \fB"UTC0"\fP , or its equivalent +historical value of \fB"GMT0"\fP . Otherwise, \fIdate\fP shall use +the timezone indicated by the \fITZ\fP environment variable +or the system default if that variable is unset or null. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 ++\fIformat\fP +When the format is specified, each conversion specifier shall be replaced +in the standard output by its corresponding value. +All other characters shall be copied to the output without change. +The output shall always be terminated with a +. +.sp +.SS Conversion Specifications +.TP 7 +\fB%a\fP +Locale's abbreviated weekday name. +.TP 7 +\fB%A\fP +Locale's full weekday name. +.TP 7 +\fB%b\fP +Locale's abbreviated month name. +.TP 7 +\fB%B\fP +Locale's full month name. +.TP 7 +\fB%c\fP +Locale's appropriate date and time representation. +.TP 7 +\fB%C\fP +Century (a year divided by 100 and truncated to an integer) as a decimal +number [00,99]. +.TP 7 +\fB%d\fP +Day of the month as a decimal number [01,31]. +.TP 7 +\fB%D\fP +Date in the format \fImm\fP/\fIdd\fP/\fIyy\fP. +.TP 7 +\fB%e\fP +Day of the month as a decimal number [1,31] in a two-digit field with +leading space character fill. +.TP 7 +\fB%h\fP +A synonym for \fB%b\fP . +.TP 7 +\fB%H\fP +Hour (24-hour clock) as a decimal number [00,23]. +.TP 7 +\fB%I\fP +Hour (12-hour clock) as a decimal number [01,12]. +.TP 7 +\fB%j\fP +Day of the year as a decimal number [001,366]. +.TP 7 +\fB%m\fP +Month as a decimal number [01,12]. +.TP 7 +\fB%M\fP +Minute as a decimal number [00,59]. +.TP 7 +\fB%n\fP +A . +.TP 7 +\fB%p\fP +Locale's equivalent of either AM or PM. +.TP 7 +\fB%r\fP +12-hour clock time [01,12] using the AM/PM notation; in the POSIX +locale, this shall be equivalent to \fB%I\fP : \fB%M\fP +: \fB%S\fP \fB%p\fP . +.TP 7 +\fB%S\fP +Seconds as a decimal number [00,60]. +.TP 7 +\fB%t\fP +A . +.TP 7 +\fB%T\fP +24-hour clock time [00,23] in the format \fIHH\fP:\fIMM\fP:\fISS\fP. +.TP 7 +\fB%u\fP +Weekday as a decimal number [1,7] (1=Monday). +.TP 7 +\fB%U\fP +Week of the year (Sunday as the first day of the week) as a decimal +number [00,53]. All days in a new year preceding the first +Sunday shall be considered to be in week 0. +.TP 7 +\fB%V\fP +Week of the year (Monday as the first day of the week) as a decimal +number [01,53]. If the week containing January 1 has four +or more days in the new year, then it shall be considered week 1; +otherwise, it shall be the last week of the previous year, and +the next week shall be week 1. +.TP 7 +\fB%w\fP +Weekday as a decimal number [0,6] (0=Sunday). +.TP 7 +\fB%W\fP +Week of the year (Monday as the first day of the week) as a decimal +number [00,53]. All days in a new year preceding the first +Monday shall be considered to be in week 0. +.TP 7 +\fB%x\fP +Locale's appropriate date representation. +.TP 7 +\fB%X\fP +Locale's appropriate time representation. +.TP 7 +\fB%y\fP +Year within century [00,99]. +.TP 7 +\fB%Y\fP +Year with century as a decimal number. +.TP 7 +\fB%Z\fP +Timezone name, or no characters if no timezone is determinable. +.TP 7 +\fB%%\fP +A percent sign character. +.sp +.LP +See the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section +7.3.5, LC_TIME for the conversion specifier values in the POSIX locale. +.SS Modified Conversion Specifications +.LP +Some conversion specifiers can be modified by the \fBE\fP and \fBO\fP +modifier characters to indicate a different format +or specification as specified in the \fILC_TIME\fP locale description +(see the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 7.3.5, LC_TIME). If the +corresponding keyword (see \fBera\fP, \fBera_year\fP, \fBera_d_fmt\fP, +and \fBalt_digits\fP in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 7.3.5, LC_TIME) is not specified or +not supported for the current locale, the unmodified conversion specifier +value shall be used. +.TP 7 +\fB%Ec\fP +Locale's alternative appropriate date and time representation. +.TP 7 +\fB%EC\fP +The name of the base year (period) in the locale's alternative representation. +.TP 7 +\fB%Ex\fP +Locale's alternative date representation. +.TP 7 +\fB%EX\fP +Locale's alternative time representation. +.TP 7 +\fB%Ey\fP +Offset from \fB%EC\fP (year only) in the locale's alternative representation. +.TP 7 +\fB%EY\fP +Full alternative year representation. +.TP 7 +\fB%Od\fP +Day of month using the locale's alternative numeric symbols. +.TP 7 +\fB%Oe\fP +Day of month using the locale's alternative numeric symbols. +.TP 7 +\fB%OH\fP +Hour (24-hour clock) using the locale's alternative numeric symbols. +.TP 7 +\fB%OI\fP +Hour (12-hour clock) using the locale's alternative numeric symbols. +.TP 7 +\fB%Om\fP +Month using the locale's alternative numeric symbols. +.TP 7 +\fB%OM\fP +Minutes using the locale's alternative numeric symbols. +.TP 7 +\fB%OS\fP +Seconds using the locale's alternative numeric symbols. +.TP 7 +\fB%Ou\fP +Weekday as a number in the locale's alternative representation (Monday += 1). +.TP 7 +\fB%OU\fP +Week number of the year (Sunday as the first day of the week) using +the locale's alternative numeric symbols. +.TP 7 +\fB%OV\fP +Week number of the year (Monday as the first day of the week, rules +corresponding to \fB%V\fP ), using the locale's +alternative numeric symbols. +.TP 7 +\fB%Ow\fP +Weekday as a number in the locale's alternative representation (Sunday += 0). +.TP 7 +\fB%OW\fP +Week number of the year (Monday as the first day of the week) using +the locale's alternative numeric symbols. +.TP 7 +\fB%Oy\fP +Year (offset from \fB%C\fP ) in alternative representation. +.sp +.sp +.TP 7 +\fImmddhhmm\fP\fB[[\fP\fIcc\fP\fB]\fP\fIyy\fP\fB]\fP +.sp +Attempt to set the system date and time from the value given in the +operand. This is only possible if the user has appropriate +privileges and the system permits the setting of the system date and +time. The first \fImm\fP is the month (number); \fIdd\fP is +the day (number); \fIhh\fP is the hour (number, 24-hour system); the +second \fImm\fP is the minute (number); \fIcc\fP is the +century and is the first two digits of the year (this is optional); +\fIyy\fP is the last two digits of the year and is optional. +If century is not specified, then values in the range [69,99] shall +refer to years 1969 to 1999 inclusive, and values in the range +[00,68] shall refer to years 2000 to 2068 inclusive. The current year +is the default if \fIyy\fP is omitted. +.TP 7 +\fBNote:\fP +.RS +It is expected that in a future version of IEEE\ Std\ 1003.1-2001 +the default century inferred from a 2-digit year will +change. (This would apply to all commands accepting a 2-digit year +as input.) +.RE +.sp +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIdate\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILC_TIME\fP +Determine the format and contents of date and time strings written +by \fIdate\fP. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITZ\fP +Determine the timezone in which the time and date are written, unless +the \fB-u\fP option is specified. If the \fITZ\fP +variable is unset or null and \fB-u\fP is not specified, an unspecified +system default timezone is used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +When no formatting operand is specified, the output in the POSIX locale +shall be equivalent to specifying: +.sp +.RS +.nf + +\fBdate "+%a %b %e %H:%M:%S %Z %Y" +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The date was written successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Conversion specifiers are of unspecified format when not in the POSIX +locale. Some of them can contain s in some +locales, so it may be difficult to use the format shown in standard +output for parsing the output of \fIdate\fP in those +locales. +.LP +The range of values for \fB%S\fP extends from 0 to 60 seconds to accommodate +the occasional leap second. +.LP +Although certain of the conversion specifiers in the POSIX locale +(such as the name of the month) are shown with initial capital +letters, this need not be the case in other locales. Programs using +these fields may need to adjust the capitalization if the +output is going to be used at the beginning of a sentence. +.LP +The date string formatting capabilities are intended for use in Gregorian-style +calendars, possibly with a different starting +year (or years). The \fB%x\fP and \fB%c\fP conversion specifications, +however, are intended for local representation; these +may be based on a different, non-Gregorian calendar. +.LP +The \fB%C\fP conversion specification was introduced to allow a fallback +for the \fB%EC\fP (alternative year format base +year); it can be viewed as the base of the current subdivision in +the Gregorian calendar. The century number is calculated as the +year divided by 100 and truncated to an integer; it should not be +confused with the use of ordinal numbers for centuries (for +example, "twenty-first century".) Both the \fB%Ey\fP and \fB%y\fP +can then be viewed as the offset from \fB%EC\fP and +\fB%C\fP , respectively. +.LP +The \fBE\fP and \fBO\fP modifiers modify the traditional conversion +specifiers, so that they can always be used, even if +the implementation (or the current locale) does not support the modifier. +.LP +The \fBE\fP modifier supports alternative date formats, such as the +Japanese Emperor's Era, as long as these are based on the +Gregorian calendar system. Extending the \fBE\fP modifiers to other +date elements may provide an implementation-defined +extension capable of supporting other calendar systems, especially +in combination with the \fBO\fP modifier. +.LP +The \fBO\fP modifier supports time and date formats using the locale's +alternative numerical symbols, such as Kanji or Hindi +digits or ordinal number representation. +.LP +Non-European locales, whether they use Latin digits in computational +items or not, often have local forms of the digits for use +in date formats. This is not totally unknown even in Europe; a variant +of dates uses Roman numerals for the months: the third day +of September 1991 would be written as 3.IX.1991. In Japan, Kanji digits +are regularly used for dates; in Arabic-speaking countries, +Hindi digits are used. The \fB%d\fP , \fB%e\fP , \fB%H\fP , \fB%I\fP +, \fB%m\fP , \fB%S\fP , \fB%U\fP , +\fB%w\fP , \fB%W\fP , and \fB%y\fP conversion specifications always +return the date and time field in Latin digits (that +is, 0 to 9). The \fB%O\fP modifier was introduced to support the use +for display purposes of non-Latin digits. In the +\fILC_TIME\fP category in \fIlocaledef\fP, the optional \fBalt_digits\fP +keyword is +intended for this purpose. As an example, assume the following (partial) +\fIlocaledef\fP +source: +.sp +.RS +.nf + +\fBalt_digits "";"I";"II";"III";"IV";"V";"VI";"VII";"VIII" \\ + "IX";"X";"XI";"XII" +d_fmt "%e.%Om.%Y" +\fP +.fi +.RE +.LP +With the above date, the command: +.sp +.RS +.nf + +\fBdate "+%x" +\fP +.fi +.RE +.LP +would yield 3.IX.1991. With the same \fBd_fmt\fP, but without the +\fBalt_digits\fP, the command would yield 3.9.1991. +.SH EXAMPLES +.IP " 1." 4 +The following are input/output examples of \fIdate\fP used at arbitrary +times in the POSIX locale: +.sp +.RS +.nf + +\fB$\fP \fBdate +\fP\fBTue Jun 26 09:58:10 PDT 1990 +.sp + +$\fP \fBdate "+DATE: %m/%d/%y%nTIME: %H:%M:%S" +\fP\fBDATE: 11/02/91 +TIME: 13:36:16 +.sp + +$\fP \fBdate "+TIME: %r" +\fP\fBTIME: 01:36:32 PM\fP +.fi +.RE +.LP +.IP " 2." 4 +Examples for Denmark, where the default date and time format is \fB%a\fP +\fB%d\fP \fB%b\fP \fB%Y\fP \fB%T\fP +\fB%Z\fP : +.sp +.RS +.nf + +\fB$\fP \fBLANG=da_DK.iso_8859-1 date +\fP\fBons 02 okt 1991 15:03:32 CET +.sp + +$\fP \fBLANG=da_DK.iso_8859-1 \\ + date "+DATO: %A den %e. %B %Y%nKLOKKEN: %H:%M:%S" +\fP\fBDATO: onsdag den 2. oktober 1991 +KLOKKEN: 15:03:56\fP +.fi +.RE +.LP +.IP " 3." 4 +Examples for Germany, where the default date and time format is \fB%a\fP +\fB%d\fP . \fB%h\fP . \fB%Y\fP , +\fB%T\fP \fB%Z\fP : +.sp +.RS +.nf + +\fB$\fP \fBLANG=De_DE.88591 date +\fP\fBMi 02.Okt.1991, 15:01:21 MEZ +.sp + +$\fP \fBLANG=De_DE.88591 date "+DATUM: %A, %d. %B %Y%nZEIT: %H:%M:%S" +\fP\fBDATUM: Mittwoch, 02. Oktober 1991 +ZEIT: 15:02:02\fP +.fi +.RE +.LP +.IP " 4." 4 +Examples for France, where the default date and time format is \fB%a\fP +\fB%d\fP \fB%h\fP \fB%Y\fP \fB%Z\fP +\fB%T\fP : +.sp +.RS +.nf + +\fB$\fP \fBLANG=Fr_FR.88591 date +\fP\fBMer 02 oct 1991 MET 15:03:32 +.sp + +$\fP \fBLANG=Fr_FR.88591 date "+JOUR: %A %d %B %Y%nHEURE: %H:%M:%S" +\fP\fBJOUR: Mercredi 02 octobre 1991 +HEURE: 15:03:56\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +Some of the new options for formatting are from the ISO\ C standard. +The \fB-u\fP option was introduced to allow portable +access to Coordinated Universal Time (UTC). The string \fB"GMT0"\fP +is allowed as an equivalent \fITZ\fP value to be compatible +with all of the systems using the BSD implementation, where this option +originated. +.LP +The \fB%e\fP format conversion specification (adopted from System +V) was added because the ISO\ C standard conversion +specifications did not provide any way to produce the historical default +\fIdate\fP output during the first nine days of any +month. +.LP +There are two varieties of day and week numbering supported (in addition +to any others created with the locale-dependent +\fB%E\fP and \fB%O\fP modifier characters): +.IP " *" 3 +The historical variety in which Sunday is the first day of the week +and the weekdays preceding the first Sunday of the year are +considered week 0. These are represented by \fB%w\fP and \fB%U\fP +\&. A variant of this is \fB%W\fP , using Monday as the +first day of the week, but still referring to week 0. This view of +the calendar was retained because so many historical +applications depend on it and the ISO\ C standard \fIstrftime\fP() +function, on which +many \fIdate\fP implementations are based, was defined in this way. +.LP +.IP " *" 3 +The international standard, based on the ISO\ 8601:2000 standard where +Monday is the first weekday and the algorithm for the +first week number is more complex: If the week (Monday to Sunday) +containing January 1 has four or more days in the new year, then +it is week 1; otherwise, it is week 53 of the previous year, and the +next week is week 1. These are represented by the new +conversion specifications \fB%u\fP and \fB%V\fP , added as a result +of international comments. +.LP +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIprintf\fP(), +\fIstrftime\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/dd.1p b/man1p/dd.1p new file mode 100644 index 000000000..3a40d4682 --- /dev/null +++ b/man1p/dd.1p @@ -0,0 +1,588 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" dd +.SH NAME +dd \- convert and copy a file +.SH SYNOPSIS +.LP +\fBdd\fP \fB[\fP\fIoperand\fP \fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIdd\fP utility shall copy the specified input file to the specified +output file with possible conversions using specific +input and output block sizes. It shall read the input one block at +a time, using the specified input block size; it shall then +process the block of data actually returned, which could be smaller +than the requested block size. It shall apply any conversions +that have been specified and write the resulting data to the output +in blocks of the specified output block size. If the \fBbs\fP= +\fIexpr\fP operand is specified and no conversions other than \fBsync\fP, +\fBnoerror\fP, or \fBnotrunc\fP are requested, the +data returned from each input block shall be written as a separate +output block; if the read returns less than a full block and the +\fBsync\fP conversion is not specified, the resulting output block +shall be the same size as the input block. If the \fBbs\fP= +\fIexpr\fP operand is not specified, or a conversion other than \fBsync\fP, +\fBnoerror\fP, or \fBnotrunc\fP is requested, the +input shall be processed and collected into full-sized output blocks +until the end of the input is reached. +.LP +The processing order shall be as follows: +.IP " 1." 4 +An input block is read. +.LP +.IP " 2." 4 +If the input block is shorter than the specified input block size +and the \fBsync\fP conversion is specified, null bytes shall +be appended to the input data up to the specified size. (If either +\fBblock\fP or \fBunblock\fP is also specified, s +shall be appended instead of null bytes.) The remaining conversions +and output shall include the pad characters as if they had been +read from the input. +.LP +.IP " 3." 4 +If the \fBbs\fP= \fIexpr\fP operand is specified and no conversion +other than \fBsync\fP or \fBnoerror\fP is requested, the +resulting data shall be written to the output as a single block, and +the remaining steps are omitted. +.LP +.IP " 4." 4 +If the \fBswab\fP conversion is specified, each pair of input data +bytes shall be swapped. If there is an odd number of bytes +in the input block, the last byte in the input record shall not be +swapped. +.LP +.IP " 5." 4 +Any remaining conversions ( \fBblock\fP, \fBunblock\fP, \fBlcase\fP, +and \fBucase\fP) shall be performed. These conversions +shall operate on the input data independently of the input blocking; +an input or output fixed-length record may span block +boundaries. +.LP +.IP " 6." 4 +The data resulting from input or conversion or both shall be aggregated +into output blocks of the specified size. After the end +of input is reached, any remaining output shall be written as a block +without padding if \fBconv\fP= \fBsync\fP is not specified; +thus, the final output block may be shorter than the output block +size. +.LP +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +All of the operands shall be processed before any input is read. The +following operands shall be supported: +.TP 7 +\fBif\fP=\fIfile\fP +Specify the input pathname; the default is standard input. +.TP 7 +\fBof\fP=\fIfile\fP +Specify the output pathname; the default is standard output. If the +\fBseek\fP= \fIexpr\fP conversion is not also specified, +the output file shall be truncated before the copy begins if an explicit +\fBof\fP= \fIfile\fP operand is specified, unless +\fBconv\fP= \fBnotrunc\fP is specified. If \fBseek\fP= \fIexpr\fP +is specified, but \fBconv\fP= \fBnotrunc\fP is not, the +effect of the copy shall be to preserve the blocks in the output file +over which \fIdd\fP seeks, but no other portion of the +output file shall be preserved. (If the size of the seek plus the +size of the input file is less than the previous size of the +output file, the output file shall be shortened by the copy.) +.TP 7 +\fBibs\fP=\fIexpr\fP +Specify the input block size, in bytes, by \fIexpr\fP (default is +512). +.TP 7 +\fBobs\fP=\fIexpr\fP +Specify the output block size, in bytes, by \fIexpr\fP (default is +512). +.TP 7 +\fBbs\fP=\fIexpr\fP +Set both input and output block sizes to \fIexpr\fP bytes, superseding +\fBibs\fP= and \fBobs\fP=. If no conversion other +than \fBsync\fP, \fBnoerror\fP, and \fBnotrunc\fP is specified, each +input block shall be copied to the output as a single block +without aggregating short blocks. +.TP 7 +\fBcbs\fP=\fIexpr\fP +Specify the conversion block size for \fBblock\fP and \fBunblock\fP +in bytes by \fIexpr\fP (default is zero). If \fBcbs\fP= +is omitted or given a value of zero, using \fBblock\fP or \fBunblock\fP +produces unspecified results. +.LP +The application shall ensure that this operand is also specified if +the \fBconv\fP= operand is specified with a value of +\fBascii\fP, \fBebcdic\fP, or \fBibm\fP. For a \fBconv\fP= operand +with an \fBascii\fP value, the input is handled as +described for the \fBunblock\fP value, except that characters are +converted to ASCII before any trailing s are +deleted. For \fBconv\fP= operands with \fBebcdic\fP or \fBibm\fP values, +the input is handled as described for the \fBblock\fP +value except that the characters are converted to EBCDIC or IBM EBCDIC, +respectively, after any trailing s are added. +.TP 7 +\fBskip\fP=\fIn\fP +Skip \fIn\fP input blocks (using the specified input block size) before +starting to copy. On seekable files, the +implementation shall read the blocks or seek past them; on non-seekable +files, the blocks shall be read and the data shall be +discarded. +.TP 7 +\fBseek\fP=\fIn\fP +Skip \fIn\fP blocks (using the specified output block size) from the +beginning of the output file before copying. On +non-seekable files, existing blocks shall be read and space from the +current end-of-file to the specified offset, if any, filled +with null bytes; on seekable files, the implementation shall seek +to the specified offset or read the blocks as described for +non-seekable files. +.TP 7 +\fBcount\fP=\fIn\fP +Copy only \fIn\fP input blocks. +.TP 7 +\fBconv\fP=\fIvalue\fP\fB[\fP,\fIvalue\fP\ ...\fB]\fP +.sp +Where \fIvalue\fPs are comma-separated symbols from the following +list: +.TP 7 +\fBascii\fP +.RS +Convert EBCDIC to ASCII; see ASCII to EBCDIC Conversion . +.RE +.TP 7 +\fBebcdic\fP +.RS +Convert ASCII to EBCDIC; see ASCII to EBCDIC Conversion . +.RE +.TP 7 +\fBibm\fP +.RS +Convert ASCII to a different EBCDIC set; see ASCII to IBM EBCDIC Conversion +\&. +.RE +.sp +.LP +The \fBascii\fP, \fBebcdic\fP, and \fBibm\fP values are mutually-exclusive. +.TP 7 +\fBblock\fP +.RS +Treat the input as a sequence of -terminated or end-of-file-terminated +variable-length records independent of +the input block boundaries. Each record shall be converted to a record +with a fixed length specified by the conversion block size. +Any shall be removed from the input line; s shall +be appended to lines that are shorter than their +conversion block size to fill the block. Lines that are longer than +the conversion block size shall be truncated to the largest +number of characters that fit into that size; the number of truncated +lines shall be reported (see the STDERR section). +.LP +The \fBblock\fP and \fBunblock\fP values are mutually-exclusive. +.RE +.TP 7 +\fBunblock\fP +.RS +Convert fixed-length records to variable length. Read a number of +bytes equal to the conversion block size (or the number of +bytes remaining in the input, if less than the conversion block size), +delete all trailing s, and append a +. +.RE +.TP 7 +\fBlcase\fP +.RS +Map uppercase characters specified by the \fILC_CTYPE\fP keyword \fBtolower\fP +to the corresponding lowercase character. +Characters for which no mapping is specified shall not be modified +by this conversion. +.LP +The \fBlcase\fP and \fBucase\fP symbols are mutually-exclusive. +.RE +.TP 7 +\fBucase\fP +.RS +Map lowercase characters specified by the \fILC_CTYPE\fP keyword \fBtoupper\fP +to the corresponding uppercase character. +Characters for which no mapping is specified shall not be modified +by this conversion. +.RE +.TP 7 +\fBswab\fP +.RS +Swap every pair of input bytes. +.RE +.TP 7 +\fBnoerror\fP +.RS +Do not stop processing on an input error. When an input error occurs, +a diagnostic message shall be written on standard error, +followed by the current input and output block counts in the same +format as used at completion (see the STDERR section). If the +\fBsync\fP conversion is specified, the missing input shall be replaced +with null bytes and processed normally; otherwise, the +input block shall be omitted from the output. +.RE +.TP 7 +\fBnotrunc\fP +.RS +Do not truncate the output file. Preserve blocks in the output file +not explicitly written by this invocation of the \fIdd\fP +utility. (See also the preceding \fBof\fP= \fIfile\fP operand.) +.RE +.TP 7 +\fBsync\fP +.RS +Pad every input block to the size of the \fBibs\fP= buffer, appending +null bytes. (If either \fBblock\fP or \fBunblock\fP is +also specified, append s, rather than null bytes.) +.RE +.sp +.sp +.LP +The behavior is unspecified if operands other than \fBconv\fP= are +specified more than once. +.LP +For the \fBbs\fP=, \fBcbs\fP=, \fBibs\fP=, and \fBobs\fP= operands, +the application shall supply an expression specifying a +size in bytes. The expression, \fIexpr\fP, can be: +.IP " 1." 4 +A positive decimal number +.LP +.IP " 2." 4 +A positive decimal number followed by \fIk\fP, specifying multiplication +by 1024 +.LP +.IP " 3." 4 +A positive decimal number followed by \fIb\fP, specifying multiplication +by 512 +.LP +.IP " 4." 4 +Two or more positive decimal numbers (with or without \fIk\fP or \fIb\fP) +separated by \fIx\fP, specifying the product of the +indicated values +.LP +.LP +All of the operands are processed before any input is read. +.LP +The following two tables display the octal number character values +used for the \fBascii\fP and \fBebcdic\fP conversions (first +table) and for the \fBibm\fP conversion (second table). In both tables, +the ASCII values are the row and column headers and the +EBCDIC values are found at their intersections. For example, ASCII +0012 (LF) is the second row, third column, yielding 0045 in +EBCDIC. The inverted tables (for EBCDIC to ASCII conversion) are not +shown, but are in one-to-one correspondence with these tables. +The differences between the two tables are highlighted by small boxes +drawn around five entries. +.br +.sp +.ce 1 +\fBTable: ASCII to EBCDIC Conversion\fP +.sp +.sp +.ce 1 +\fBTable: ASCII to IBM EBCDIC Conversion\fP +.SH STDIN +.LP +If no \fBif\fP= operand is specified, the standard input shall be +used. See the INPUT FILES section. +.SH INPUT FILES +.LP +The input file can be any file type. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIdd\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), the +classification of characters as uppercase or lowercase, and the +mapping of characters from one case to the other. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +For SIGINT, the \fIdd\fP utility shall interrupt its current processing, +write status information to standard error, and exit +as though terminated by SIGINT. It shall take the standard action +for all other signals; see the ASYNCHRONOUS EVENTS section in \fIUtility +Description Defaults\fP . +.SH STDOUT +.LP +If no \fBof\fP= operand is specified, the standard output shall be +used. The nature of the output depends on the operands +selected. +.SH STDERR +.LP +On completion, \fIdd\fP shall write the number of input and output +blocks to standard error. In the POSIX locale the following +formats shall be used: +.sp +.RS +.nf + +\fB"%u+%u records in\\n", <\fP\fInumber of whole input blocks\fP\fB>, + <\fP\fInumber of partial input blocks\fP\fB> +.sp + +"%u+%u records out\\n", <\fP\fInumber of whole output blocks\fP\fB>, + <\fP\fInumber of partial output blocks\fP\fB> +\fP +.fi +.RE +.LP +A partial input block is one for which \fIread\fP() returned less +than the input block +size. A partial output block is one that was written with fewer bytes +than specified by the output block size. +.LP +In addition, when there is at least one truncated block, the number +of truncated blocks shall be written to standard error. In +the POSIX locale, the format shall be: +.sp +.RS +.nf + +\fB"%u truncated %s\\n", <\fP\fInumber of truncated blocks\fP\fB>, "record" (if + <\fP\fInumber of truncated blocks\fP\fB> is one) "records" (otherwise) +\fP +.fi +.RE +.LP +Diagnostic messages may also be written to standard error. +.SH OUTPUT FILES +.LP +If the \fBof\fP= operand is used, the output shall be the same as +described in the STDOUT section. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The input file was copied successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If an input error is detected and the \fBnoerror\fP conversion has +not been specified, any partial output block shall be +written to the output file, a diagnostic message shall be written, +and the copy operation shall be discontinued. If some other +error is detected, a diagnostic message shall be written and the copy +operation shall be discontinued. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The input and output block size can be specified to take advantage +of raw physical I/O. +.LP +There are many different versions of the EBCDIC codesets. The ASCII +and EBCDIC conversions specified for the \fIdd\fP utility +perform conversions for the version specified by the tables. +.SH EXAMPLES +.LP +The following command: +.sp +.RS +.nf + +\fBdd if=/dev/rmt0h of=/dev/rmt1h +\fP +.fi +.RE +.LP +copies from tape drive 0 to tape drive 1, using a common historical +device naming convention. +.LP +The following command: +.sp +.RS +.nf + +\fBdd ibs=10 skip=1 +\fP +.fi +.RE +.LP +strips the first 10 bytes from standard input. +.LP +This example reads an EBCDIC tape blocked ten 80-byte EBCDIC card +images per block into the ASCII file \fBx\fP: +.sp +.RS +.nf + +\fBdd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase +\fP +.fi +.RE +.SH RATIONALE +.LP +The OPTIONS section is listed as "None" because there are no options +recognized by historical \fIdd\fP utilities. Certainly, +many of the operands could have been designed to use the Utility Syntax +Guidelines, which would have resulted in the classic +hyphenated option letters. In this version of this volume of IEEE\ Std\ 1003.1-2001, +\fIdd\fP retains its curious JCL-like +syntax due to the large number of applications that depend on the +historical implementation. +.LP +A suggested implementation technique for \fBconv\fP= \fBnoerror\fP, +\fBsync\fP is to zero (or -fill, if +\fBblock\fPing or \fBunblock\fPing) the input buffer before each read +and to write the contents of the input buffer to the output +even after an error. In this manner, any data transferred to the input +buffer before the error was detected is preserved. Another +point is that a failed read on a regular file or a disk generally +does not increment the file offset, and \fIdd\fP must then seek +past the block on which the error occurred; otherwise, the input error +occurs repetitively. When the input is a magnetic tape, +however, the tape normally has passed the block containing the error +when the error is reported, and thus no seek is necessary. +.LP +The default \fBibs\fP= and \fBobs\fP= sizes are specified as 512 bytes +because there are historical (largely portable) scripts +that assume these values. If they were left unspecified, unusual results +could occur if an implementation chose an odd block +size. +.LP +Historical implementations of \fIdd\fP used \fIcreat\fP() when processing +\fBof\fP= +\fIfile\fP. This makes the \fBseek\fP= operand unusable except on +special files. The \fBconv\fP= \fBnotrunc\fP feature was +added because more recent BSD-based implementations use \fIopen\fP() +(without O_TRUNC) +instead of \fIcreat\fP(), but they fail to delete output file contents +after the data +copied. +.LP +The \fIw\fP multiplier (historically meaning \fIword\fP), is used +in System V to mean 2 and in 4.2 BSD to mean 4. Since +\fIword\fP is inherently non-portable, its use is not supported by +this volume of IEEE\ Std\ 1003.1-2001. +.LP +Standard EBCDIC does not have the characters \fB'['\fP and \fB']'\fP +\&. The values used in the table are taken from a +common print train that does contain them. Other than those characters, +the print train values are not filled in, but appear to +provide some of the motivation for the historical choice of translations +reflected here. +.LP +The Standard EBCDIC table provides a 1:1 translation for all 256 bytes. +.LP +The IBM EBCDIC table does not provide such a translation. The marked +cells in the tables differ in such a way that: +.IP " 1." 4 +EBCDIC 0112 ( \fB'cent'\fP ) and 0152 (broken pipe) do not appear +in the table. +.LP +.IP " 2." 4 +EBCDIC 0137 ( \fB'not'\fP ) translates to/from ASCII 0236 ( \fB'^'\fP +). In the standard table, EBCDIC 0232 (no graphic) +is used. +.LP +.IP " 3." 4 +EBCDIC 0241 ( \fB'~'\fP ) translates to/from ASCII 0176 ( \fB'~'\fP +). In the standard table, EBCDIC 0137 ( +\fB'not'\fP ) is used. +.LP +.IP " 4." 4 +0255 ( \fB'['\fP ) and 0275 ( \fB']'\fP ) appear twice, once in the +same place as for the standard table and once in place +of 0112 ( \fB'cent'\fP ) and 0241 ( \fB'~'\fP ). +.LP +.LP +In net result: +EBCDIC 0275 ( \fB']'\fP ) displaced EBCDIC 0241 ( \fB'~'\fP ) in cell +0345. +.LP +\ \ \ \ That displaced EBCDIC 0137 ( \fB'not'\fP ) in cell 0176. +.LP +\ \ \ \ That displaced EBCDIC 0232 (no graphic) in cell 0136. +.LP +\ \ \ \ That replaced EBCDIC 0152 (broken pipe) in cell 0313. +.LP +EBCDIC 0255 ( \fB'['\fP ) replaced EBCDIC 0112 ( \fB'cent'\fP ). +.LP +This translation, however, reflects historical practice that (ASCII) +\fB'~'\fP and \fB'not'\fP were often mapped to +each other, as were \fB'['\fP and \fB'cent'\fP ; and \fB']'\fP and +(EBCDIC) \fB'~'\fP . +.LP +The \fBcbs\fP operand is required if any of the \fBascii\fP, \fBebcdic\fP, +or \fBibm\fP operands are specified. For the +\fBascii\fP operand, the input is handled as described for the \fBunblock\fP +operand except that characters are converted to +ASCII before the trailing s are deleted. For the \fBebcdic\fP +and \fBibm\fP operands, the input is handled as +described for the \fBblock\fP operand except that the characters are +converted to EBCDIC or IBM EBCDIC after the trailing +s are added. +.LP +The \fBblock\fP and \fBunblock\fP keywords are from historical BSD +practice. +.LP +The consistent use of the word \fBrecord\fP in standard error messages +matches most historical practice. An earlier version of +System V used \fBblock\fP, but this has been updated in more recent +releases. +.LP +Early proposals only allowed two numbers separated by \fBx\fP to be +used in a product when specifying \fBbs\fP=, \fBcbs\fP=, +\fBibs\fP=, and \fBobs\fP= sizes. This was changed to reflect the +historical practice of allowing multiple numbers in the product +as provided by Version 7 and all releases of System V and BSD. +.LP +A change to the \fBswab\fP conversion is required to match historical +practice and is the result of IEEE PASC Interpretations +1003.2 #03 and #04, submitted for the ISO\ POSIX-2:1993 standard. +.LP +A change to the handling of SIGINT is required to match historical +practice and is the result of IEEE PASC Interpretation 1003.2 +#06 submitted for the ISO\ POSIX-2:1993 standard. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIUtility Description Defaults\fP , \fIsed\fP , \fItr\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/delta.1p b/man1p/delta.1p new file mode 100644 index 000000000..3863f282b --- /dev/null +++ b/man1p/delta.1p @@ -0,0 +1,272 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DELTA" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" delta +.SH NAME +delta \- make a delta (change) to an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBdelta\fP \fB[\fP\fB-nps\fP\fB][\fP\fB-g\fP \fIlist\fP\fB][\fP\fB-m\fP +\fImrlist\fP\fB][\fP\fB-r\fP \fISID\fP\fB][\fP\fB-y\fP\fB[\fP\fIcomment\fP\fB]]\fP +\fIfile\fP\fB... \fP +.SH DESCRIPTION +.LP +The \fIdelta\fP utility shall be used to permanently introduce into +the named SCCS files changes that were made to the files +retrieved by \fIget\fP (called the \fIg-files\fP, or generated files). +.SH OPTIONS +.LP +The \fIdelta\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that the \fB-y\fP option has an +optional option-argument. This optional option-argument shall not +be presented as a separate argument. +.LP +The following options shall be supported: +.TP 7 +\fB-r\ \fP \fISID\fP +Uniquely identify which delta is to be made to the SCCS file. The +use of this option shall be necessary only if two or more +outstanding \fIget\fP commands for editing ( \fIget\fP +\fB-e\fP) on the same SCCS file were done by the same person (login +name). The SID value specified with the \fB-r\fP option can +be either the SID specified on the \fIget\fP command line or the SID +to be made as reported by +the \fIget\fP utility; see \fIget\fP . +.TP 7 +\fB-s\fP +Suppress the report to standard output of the activity associated +with each \fIfile\fP. See the STDOUT section. +.TP 7 +\fB-n\fP +Specify retention of the edited \fIg-file\fP (normally removed at +completion of delta processing). +.TP 7 +\fB-g\ \fP \fIlist\fP +Specify a \fIlist\fP (see \fIget\fP for the definition of \fIlist\fP) +of deltas that shall be ignored +when the file is accessed at the change level (SID) created by this +delta. +.TP 7 +\fB-m\ \fP \fImrlist\fP +Specify a modification request (MR) number that the application shall +supply as the reason for creating the new delta. This +shall be used if the SCCS file has the \fBv\fP flag set; see \fIadmin\fP +\&. +.LP +If \fB-m\fP is not used and \fB'-'\fP is not specified as a file argument, +and the standard input is a terminal, the prompt +described in the STDOUT section shall be written to standard output +before the standard input is read; if the standard input is not +a terminal, no prompt shall be issued. +.LP +MRs in a list shall be separated by s or escaped s. +An unescaped shall terminate the +MR list. The escape character is . +.LP +If the \fBv\fP flag has a value, it shall be taken to be the name +of a program which validates the correctness of the MR +numbers. If a non-zero exit status is returned from the MR number +validation program, the \fIdelta\fP utility shall terminate. (It +is assumed that the MR numbers were not all valid.) +.TP 7 +\fB-y[\fP\fIcomment\fP\fB]\fP +Describe the reason for making the delta. The \fIcomment\fP shall +be an arbitrary group of lines that would meet the +definition of a text file. Implementations shall support \fIcomment\fPs +from zero to 512 bytes and may support longer values. A +null string (specified as either \fB-y\fP, \fB-y\fP \fB""\fP , or +in response to a prompt for a comment) shall be considered a +valid \fIcomment\fP. +.LP +If \fB-y\fP is not specified and \fB'-'\fP is not specified as a file +argument, and the standard input is a terminal, the +prompt described in the STDOUT section shall be written to standard +output before the standard input is read; if the standard input +is not a terminal, no prompt shall be issued. An unescaped +shall terminate the comment text. The escape character +is . +.LP +The \fB-y\fP option shall be required if the \fIfile\fP operand is +specified as \fB'-'\fP . +.TP 7 +\fB-p\fP +Write (to standard output) the SCCS file differences before and after +the delta is applied in \fIdiff\fP format; see \fIdiff\fP . +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of an existing SCCS file or a directory. If \fIfile\fP +is a directory, the \fIdelta\fP utility shall behave as +though each file in the directory were specified as a named file, +except that non-SCCS files (last component of the pathname does +not begin with \fBs.\fP) and unreadable files shall be silently ignored. +.LP +If exactly one \fIfile\fP operand appears, and it is \fB'-'\fP , the +standard input shall be read; each line of the standard +input shall be taken to be the name of an SCCS file to be processed. +Non-SCCS files and unreadable files shall be silently +ignored. +.sp +.SH STDIN +.LP +The standard input shall be a text file used only in the following +cases: +.IP " *" 3 +To read an \fImrlist\fP or a \fIcomment\fP (see the \fB-m\fP and \fB-y\fP +options). +.LP +.IP " *" 3 +A \fIfile\fP operand shall be specified as \fB'-'\fP . In this case, +the \fB-y\fP option must be used to specify the +comment, and if the SCCS file has the \fBv\fP flag set, the \fB-m\fP +option must also be used to specify the MR list. +.LP +.SH INPUT FILES +.LP +Input files shall be text files whose data is to be included in the +SCCS files. If the first character of any line of an input +file is in the POSIX locale, the results are unspecified. If +this file contains more than 99999 lines, the number of +lines recorded in the header for this file shall be 99999 for this +delta. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIdelta\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, +and informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITZ\fP +Determine the timezone in which the time and date are written in the +SCCS file. If the \fITZ\fP variable is unset or NULL, an +unspecified system default timezone is used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +If SIGINT is caught, temporary files shall be cleaned up and \fIdelta\fP +shall exit with a non-zero exit code. The standard +action shall be taken for all other signals; see \fIUtility Description +Defaults\fP . +.SH STDOUT +.LP +The standard output shall be used only for the following messages +in the POSIX locale: +.IP " *" 3 +Prompts (see the \fB-m\fP and \fB-y\fP options) in the following formats: +.sp +.RS +.nf + +\fB"MRs? " +.sp + +"comments? " +\fP +.fi +.RE +.LP +The MR prompt, if written, shall always precede the comments prompt. +.LP +.IP " *" 3 +A report of each file's activities (unless the \fB-s\fP option is +specified) in the following format: +.sp +.RS +.nf + +\fB"%s\\n%d inserted\\n%d deleted\\n%d unchanged\\n", <\fP\fINew SID\fP\fB>, + <\fP\fInumber of lines inserted\fP\fB>, <\fP\fInumber of lines deleted\fP\fB>, + <\fP\fInumber of lines unchanged\fP\fB> +\fP +.fi +.RE +.LP +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +Any SCCS files updated shall be files of an unspecified format. +.SH EXTENDED DESCRIPTION +.SS System Date and Time +.LP +When a delta is added to an SCCS file, the system date and time shall +be recorded for the new delta. If a \fIget\fP is performed using an +SCCS file with a date recorded apparently in the future, the behavior +is unspecified. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Problems can arise if the system date and time have been modified +(for example, put forward and then back again, or +unsynchronized clocks across a network) and can also arise when different +values of the \fITZ\fP environment variable are +used. +.LP +Problems of a similar nature can also arise for the operation of the +\fIget\fP utility, +which records the date and time in the file body. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIUtility Description Defaults\fP , \fIadmin\fP , \fIdiff\fP , \fIget\fP +, \fIprs\fP , \fIrmdel\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/df.1p b/man1p/df.1p new file mode 100644 index 000000000..fb283d0c3 --- /dev/null +++ b/man1p/df.1p @@ -0,0 +1,296 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" df +.SH NAME +df \- report free disk space +.SH SYNOPSIS +.LP +\fBdf\fP \fB[\fP\fB-k\fP\fB][\fP\fB-P|-t\fP\fB][\fP\fIfile\fP\fB...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIdf\fP utility shall write the amount of available space \ and +file slots for file systems on which the invoking user has appropriate +read access. File systems shall be specified +by the \fIfile\fP operands; when none are specified, information shall +be written for all file systems. The format of the default +output from \fIdf\fP is unspecified, but all space figures are reported +in 512-byte units, unless the \fB-k\fP option is +specified. This output shall contain at least the file system names, +amount of available space on each of these file systems, +\ and the number of free file slots, or \fIinodes\fP, available; when +\fB-t\fP is specified, the output shall contain the +total allocated space as well. +.SH OPTIONS +.LP +The \fIdf\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-k\fP +Use 1024-byte units, instead of the default 512-byte units, when writing +space figures. +.TP 7 +\fB-P\fP +Produce output in the format described in the STDOUT section. +.TP 7 +\fB-t\fP +Include total allocated-space figures in the output. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a file within the hierarchy of the desired file system. +If a file other than a FIFO, a regular file, a directory, +\ or a special file representing the device containing the file system +(for example, \fB/dev/dsk/0s1\fP) is specified, the results are unspecified. +Otherwise, \fIdf\fP shall write +the amount of free space in the file system containing the specified +\fIfile\fP operand. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIdf\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +When both the \fB-k\fP and \fB-P\fP options are specified, the following +header line shall be written (in the POSIX +locale): +.sp +.RS +.nf + +\fB"Filesystem 1024-blocks Used Available Capacity Mounted on\\n" +\fP +.fi +.RE +.LP +When the \fB-P\fP option is specified without the \fB-k\fP option, +the following header line shall be written (in the POSIX +locale): +.sp +.RS +.nf + +\fB"Filesystem 512-blocks Used Available Capacity Mounted on\\n" +\fP +.fi +.RE +.LP +The implementation may adjust the spacing of the header line and the +individual data lines so that the information is presented +in orderly columns. +.LP +The remaining output with \fB-P\fP shall consist of one line of information +for each specified file system. These lines shall +be formatted as follows: +.sp +.RS +.nf + +\fB"%s %d %d %d %d%% %s\\n", <\fP\fIfile system name\fP\fB>, <\fP\fItotal space\fP\fB>, + <\fP\fIspace used\fP\fB>, <\fP\fIspace free\fP\fB>, <\fP\fIpercentage used\fP\fB>, + <\fP\fIfile system root\fP\fB> +\fP +.fi +.RE +.LP +In the following list, all quantities expressed in 512-byte units +(1024-byte when \fB-k\fP is specified) shall be rounded up to +the next higher unit. The fields are: +.TP 7 +<\fIfile\ system\ name\fP> +.sp +The name of the file system, in an implementation-defined format. +.TP 7 +<\fItotal\ space\fP> +The total size of the file system in 512-byte units. The exact meaning +of this figure is implementation-defined, but should +include <\fIspace\ used\fP>, <\fIspace\ free\fP>, plus any space reserved +by the system not normally +available to a user. +.TP 7 +<\fIspace\ used\fP> +The total amount of space allocated to existing files in the file +system, in 512-byte units. +.TP 7 +<\fIspace\ free\fP> +The total amount of space available within the file system for the +creation of new files by unprivileged users, in 512-byte +units. When this figure is less than or equal to zero, it shall not +be possible to create any new files on the file system without +first deleting others, unless the process has appropriate privileges. +The figure written may be less than zero. +.TP 7 +<\fIpercentage\ used\fP> +.sp +The percentage of the normally available space that is currently allocated +to all files on the file system. This shall be +calculated using the fraction: +.sp +.RS +.nf + +\fB<\fP\fIspace used\fP\fB>/( <\fP\fIspace used\fP\fB>+ <\fP\fIspace free\fP\fB>) +\fP +.fi +.RE +.LP +expressed as a percentage. This percentage may be greater than 100 +if <\fIspace\ free\fP> is less than zero. The +percentage value shall be expressed as a positive integer, with any +fractional result causing it to be rounded to the next highest +integer. +.TP 7 +<\fIfile\ system\ root\fP> +.sp +The directory below which the file system hierarchy appears. +.sp +.LP +The output format is unspecified when \fB-t\fP is used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +On most systems, the "name of the file system, in an implementation-defined +format" is the special file on which the file +system is mounted. +.LP +On large file systems, the calculation specified for percentage used +can create huge rounding errors. +.SH EXAMPLES +.IP " 1." 4 +The following example writes portable information about the \fB/usr\fP +file system: +.sp +.RS +.nf + +\fBdf -P /usr +\fP +.fi +.RE +.LP +.IP " 2." 4 +Assuming that \fB/usr/src\fP is part of the \fB/usr\fP file system, +the following produces the same output as the previous +example: +.sp +.RS +.nf + +\fBdf -P /usr/src +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +The behavior of \fIdf\fP with the \fB-P\fP option is the default action +of the 4.2 BSD \fIdf\fP utility. The uppercase +\fB-P\fP was selected to avoid collision with a known industry extension +using \fB-p\fP. +.LP +Historical \fIdf\fP implementations vary considerably in their default +output. It was therefore necessary to describe the +default output in a loose manner to accommodate all known historical +implementations and to add a portable option ( \fB-P\fP) to +provide information in a portable format. +.LP +The use of 512-byte units is historical practice and maintains compatibility +with \fIls\fP +and other utilities in this volume of IEEE\ Std\ 1003.1-2001. This +does not mandate that the file system itself be based on +512-byte blocks. The \fB-k\fP option was added as a compromise measure. +It was agreed by the standard developers that 512 bytes +was the best default unit because of its complete historical consistency +on System V (\fIversus\fP the mixed 512/1024-byte usage +on BSD systems), and that a \fB-k\fP option to switch to 1024-byte +units was a good compromise. Users who prefer the more logical +1024-byte quantity can easily alias \fIdf\fP to \fIdf\fP \fB-k\fP +without breaking many historical scripts relying on the +512-byte units. +.LP +It was suggested that \fIdf\fP and the various related utilities be +modified to access a \fIBLOCKSIZE\fP environment variable +to achieve consistency and user acceptance. Since this is not historical +practice on any system, it is left as a possible area for +system extensions and will be re-evaluated in a future version if +it is widely implemented. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfind\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/diff.1p b/man1p/diff.1p new file mode 100644 index 000000000..27598b9ab --- /dev/null +++ b/man1p/diff.1p @@ -0,0 +1,646 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DIFF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" diff +.SH NAME +diff \- compare two files +.SH SYNOPSIS +.LP +\fBdiff\fP \fB[\fP\fB-c| -e| -f| -C\fP \fIn\fP\fB][\fP\fB-br\fP\fB]\fP +\fIfile1 file2\fP +.SH DESCRIPTION +.LP +The \fIdiff\fP utility shall compare the contents of \fIfile1\fP and +\fIfile2\fP and write to standard output a list of +changes necessary to convert \fIfile1\fP into \fIfile2\fP. This list +should be minimal. No output shall be produced if the files +are identical. +.SH OPTIONS +.LP +The \fIdiff\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-b\fP +Cause any amount of white space at the end of a line to be treated +as a single (that is, the white-space +characters preceding the are ignored) and other strings +of white-space characters, not including s, +to compare equal. +.TP 7 +\fB-c\fP +Produce output in a form that provides three lines of context. +.TP 7 +\fB-C\ n\fP +Produce output in a form that provides \fIn\fP lines of context (where +\fIn\fP shall be interpreted as a positive decimal +integer). +.TP 7 +\fB-e\fP +Produce output in a form suitable as input for the \fIed\fP utility, +which can then be used +to convert \fIfile1\fP into \fIfile2\fP. +.TP 7 +\fB-f\fP +Produce output in an alternative form, similar in format to \fB-e\fP, +but not intended to be suitable as input for the \fIed\fP utility, +and in the opposite order. +.TP 7 +\fB-r\fP +Apply \fIdiff\fP recursively to files and directories of the same +name when \fIfile1\fP and \fIfile2\fP are both +directories. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile1\fP,\ \fIfile2\fP +A pathname of a file to be compared. If either the \fIfile1\fP or +\fIfile2\fP operand is \fB'-'\fP , the standard input +shall be used in its place. +.sp +.LP +If both \fIfile1\fP and \fIfile2\fP are directories, \fIdiff\fP shall +not compare block special files, character special +files, or FIFO special files to any files and shall not compare regular +files to directories. Further details are as specified in +Diff Directory Comparison Format . The behavior of \fIdiff\fP on other +file types is +implementation-defined when found in directories. +.LP +If only one of \fIfile1\fP and \fIfile2\fP is a directory, \fIdiff\fP +shall be applied to the non-directory file and the file +contained in the directory file with a filename that is the same as +the last component of the non-directory file. +.SH STDIN +.LP +The standard input shall be used only if one of the \fIfile1\fP or +\fIfile2\fP operands references standard input. See the +INPUT FILES section. +.SH INPUT FILES +.LP +The input files may be of any type. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIdiff\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fILC_TIME\fP +Determine the locale for affecting the format of file timestamps written +with the \fB-C\fP and \fB-c\fP options. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITZ\fP +Determine the timezone used for calculating file timestamps written +with the \fB-C\fP and \fB-c\fP options. If \fITZ\fP is +unset or null, an unspecified default timezone shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.SS Diff Directory Comparison Format +.LP +If both \fIfile1\fP and \fIfile2\fP are directories, the following +output formats shall be used. +.LP +In the POSIX locale, each file that is present in only one directory +shall be reported using the following format: +.sp +.RS +.nf + +\fB"Only in %s: %s\\n", <\fP\fIdirectory pathname\fP\fB>, <\fP\fIfilename\fP\fB> +\fP +.fi +.RE +.LP +In the POSIX locale, subdirectories that are common to the two directories +may be reported with the following format: +.sp +.RS +.nf + +\fB"Common subdirectories: %s and %s\\n", <\fP\fIdirectory1 pathname\fP\fB>, + <\fP\fIdirectory2 pathname\fP\fB> +\fP +.fi +.RE +.LP +For each file common to the two directories if the two files are not +to be compared, the following format shall be used in the +POSIX locale: +.sp +.RS +.nf + +\fB"File %s is a %s while file %s is a %s\\n", <\fP\fIdirectory1 pathname\fP\fB>, + <\fP\fIfile type of directory1 pathname\fP\fB>, <\fP\fIdirectory2 pathname\fP\fB>, + <\fP\fIfile type of directory2 pathname\fP\fB> +\fP +.fi +.RE +.LP +For each file common to the two directories, if the files are compared +and are identical, no output shall be written. If the two +files differ, the following format is written: +.sp +.RS +.nf + +\fB"diff %s %s %s\\n", <\fP\fIdiff_options\fP\fB>, <\fP\fIfilename1\fP\fB>, <\fP\fIfilename2\fP\fB> +\fP +.fi +.RE +.LP +where <\fIdiff_options\fP> are the options as specified on the command +line. +.LP +All directory pathnames listed in this section shall be relative to +the original command line arguments. All other names of +files listed in this section shall be filenames (pathname components). +.SS Diff Binary Output Format +.LP +In the POSIX locale, if one or both of the files being compared are +not text files, an unspecified format shall be used that +contains the pathnames of two files being compared and the string +\fB"differ"\fP . +.LP +If both files being compared are text files, depending on the options +specified, one of the following formats shall be used to +write the differences. +.SS Diff Default Output Format +.LP +The default (without \fB-e\fP, \fB-f\fP, \fB-c\fP, or \fB-C\fP options) +\fIdiff\fP utility output shall contain lines of +these forms: +.sp +.RS +.nf + +\fB"%da%d\\n", <\fP\fInum1\fP\fB>, <\fP\fInum2\fP\fB> +.sp + +"%da%d,%d\\n", <\fP\fInum1\fP\fB>, <\fP\fInum2\fP\fB>, <\fP\fInum3\fP\fB> +.sp + +"%dd%d\\n", <\fP\fInum1\fP\fB>, <\fP\fInum2\fP\fB> +.sp + +"%d,%dd%d\\n", <\fP\fInum1\fP\fB>, <\fP\fInum2\fP\fB>, <\fP\fInum3\fP\fB> +.sp + +"%dc%d\\n", <\fP\fInum1\fP\fB>, <\fP\fInum2\fP\fB> +.sp + +"%d,%dc%d\\n", <\fP\fInum1\fP\fB>, <\fP\fInum2\fP\fB>, <\fP\fInum3\fP\fB> +.sp + +"%dc%d,%d\\n", <\fP\fInum1\fP\fB>, <\fP\fInum2\fP\fB>, <\fP\fInum3\fP\fB> +.sp + +"%d,%dc%d,%d\\n", <\fP\fInum1\fP\fB>, <\fP\fInum2\fP\fB>, <\fP\fInum3\fP\fB>, <\fP\fInum4\fP\fB> +\fP +.fi +.RE +.LP +These lines resemble \fIed\fP subcommands to convert \fIfile1\fP into +\fIfile2\fP. The +line numbers before the action letters shall pertain to \fIfile1\fP; +those after shall pertain to \fIfile2\fP. Thus, by +exchanging \fIa\fP for \fId\fP and reading the line in reverse order, +one can also determine how to convert \fIfile2\fP into +\fIfile1\fP. As in \fIed\fP, identical pairs (where \fInum1\fP= \fInum2\fP) +are abbreviated +as a single number. +.LP +Following each of these lines, \fIdiff\fP shall write to standard +output all lines affected in the first file using the +format: +.sp +.RS +.nf + +\fB"< %s", <\fP\fIline\fP\fB> +\fP +.fi +.RE +.LP +and all lines affected in the second file using the format: +.sp +.RS +.nf + +\fB"> %s", <\fP\fIline\fP\fB> +\fP +.fi +.RE +.LP +If there are lines affected in both \fIfile1\fP and \fIfile2\fP (as +with the \fBc\fP subcommand), the changes are separated +with a line consisting of three hyphens: +.sp +.RS +.nf + +\fB"---\\n" +\fP +.fi +.RE +.SS Diff -e Output Format +.LP +With the \fB-e\fP option, a script shall be produced that shall, when +provided as input to \fIed\fP, along with an appended \fBw\fP (write) +command, convert \fIfile1\fP into \fIfile2\fP. Only +the \fBa\fP (append), \fBc\fP (change), \fBd\fP (delete), \fBi\fP +(insert), and \fBs\fP (substitute) commands of \fIed\fP shall be used +in this script. Text lines, except those consisting of the single +character +period ( \fB'.'\fP ), shall be output as they appear in the file. +.SS Diff -f Output Format +.LP +With the \fB-f\fP option, an alternative format of script shall be +produced. It is similar to that produced by \fB-e\fP, with +the following differences: +.IP " 1." 4 +It is expressed in reverse sequence; the output of \fB-e\fP orders +changes from the end of the file to the beginning; the +\fB-f\fP from beginning to end. +.LP +.IP " 2." 4 +The command form <\fIlines\fP> <\fIcommand-letter\fP> used by \fB-e\fP +is reversed. For example, 10\fIc\fP with +\fB-e\fP would be \fIc\fP10 with \fB-f\fP. +.LP +.IP " 3." 4 +The form used for ranges of line numbers is -separated, rather +than comma-separated. +.LP +.SS Diff -c or -C Output Format +.LP +With the \fB-c\fP or \fB-C\fP option, the output format shall consist +of affected lines along with surrounding lines of +context. The affected lines shall show which ones need to be deleted +or changed in \fIfile1\fP, and those added from \fIfile2\fP. +With the \fB-c\fP option, three lines of context, if available, shall +be written before and after the affected lines. With the +\fB-C\fP option, the user can specify how many lines of context are +written. The exact format follows. +.LP +The name and last modification time of each file shall be output in +the following format: +.sp +.RS +.nf + +\fB"*** %s %s\\n",\fP \fIfile1\fP\fB, <\fP\fIfile1 timestamp\fP\fB> +"--- %s %s\\n",\fP \fIfile2\fP\fB, <\fP\fIfile2 timestamp\fP\fB> +\fP +.fi +.RE +.LP +Each <\fIfile\fP> field shall be the pathname of the corresponding +file being compared. The pathname written for standard +input is unspecified. +.LP +In the POSIX locale, each <\fItimestamp\fP> field shall be equivalent +to the output from the following command: +.sp +.RS +.nf + +\fBdate "+%a %b %e %T %Y" +\fP +.fi +.RE +.LP +without the trailing , executed at the time of last modification +of the corresponding file (or the current time, +if the file is standard input). +.LP +Then, the following output formats shall be applied for every set +of changes. +.LP +First, a line shall be written in the following format: +.sp +.RS +.nf + +\fB"***************\\n" +\fP +.fi +.RE +.LP +Next, the range of lines in \fIfile1\fP shall be written in the following +format if the range contains two or more lines: +.sp +.RS +.nf + +\fB"*** %d,%d ****\\n", <\fP\fIbeginning line number\fP\fB>, <\fP\fIending line number\fP\fB> +\fP +.fi +.RE +.LP +and the following format otherwise: +.sp +.RS +.nf + +\fB"*** %d ****\\n", <\fP\fIending line number\fP\fB> +\fP +.fi +.RE +.LP +The ending line number of an empty range shall be the number of the +preceding line, or 0 if the range is at the start of the +file. +.LP +Next, the affected lines along with lines of context (unaffected lines) +shall be written. Unaffected lines shall be written in +the following format: +.sp +.RS +.nf + +\fB" %s", <\fP\fIunaffected_line\fP\fB> +\fP +.fi +.RE +.LP +Deleted lines shall be written as: +.sp +.RS +.nf + +\fB"- %s", <\fP\fIdeleted_line\fP\fB> +\fP +.fi +.RE +.LP +Changed lines shall be written as: +.sp +.RS +.nf + +\fB"! %s", <\fP\fIchanged_line\fP\fB> +\fP +.fi +.RE +.LP +Next, the range of lines in \fIfile2\fP shall be written in the following +format if the range contains two or more lines: +.sp +.RS +.nf + +\fB"--- %d,%d ----\\n", <\fP\fIbeginning line number\fP\fB>, <\fP\fIending line number\fP\fB> +\fP +.fi +.RE +.LP +and the following format otherwise: +.sp +.RS +.nf + +\fB"--- %d ----\\n", <\fP\fIending line number\fP\fB> +\fP +.fi +.RE +.LP +Then, lines of context and changed lines shall be written as described +in the previous formats. Lines added from \fIfile2\fP +shall be written in the following format: +.sp +.RS +.nf + +\fB"+ %s", <\fP\fIadded_line\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +No differences were found. +.TP 7 +\ 1 +Differences were found. +.TP 7 +>1 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +If lines at the end of a file are changed and other lines are added, +\fIdiff\fP output may show this as a delete and add, as a +change, or as a change and add; \fIdiff\fP is not expected to know +which happened and users should not care about the difference +in output as long as it clearly shows the differences between the +files. +.SH EXAMPLES +.LP +If \fBdir1\fP is a directory containing a directory named \fBx\fP, +\fBdir2\fP is a directory containing a directory named +\fBx\fP, \fBdir1/x\fP and \fBdir2/x\fP both contain files named \fBdate.out\fP, +and \fBdir2/x\fP contains a file named +\fBy\fP, the command: +.sp +.RS +.nf + +\fBdiff -r dir1 dir2 +\fP +.fi +.RE +.LP +could produce output similar to: +.sp +.RS +.nf + +\fBCommon subdirectories: dir1/x and dir2/x +Only in dir2/x: y +diff -r dir1/x/date.out dir2/x/date.out +1c1 +< Mon Jul 2 13:12:16 PDT 1990 +--- +> Tue Jun 19 21:41:39 PDT 1990 +\fP +.fi +.RE +.SH RATIONALE +.LP +The \fB-h\fP option was omitted because it was insufficiently specified +and does not add to applications portability. +.LP +Historical implementations employ algorithms that do not always produce +a minimum list of differences; the current language +about making every effort is the best this volume of IEEE\ Std\ 1003.1-2001 +can do, as there is no metric that could be +employed to judge the quality of implementations against any and all +file contents. The statement "This list should be minimal'' +clearly implies that implementations are not expected to provide the +following output when comparing two 100-line files that differ +in only one character on a single line: +.sp +.RS +.nf + +\fB1,100c1,100 +all 100 lines from file1 preceded with "< " +--- +all 100 lines from file2 preceded with "> " +\fP +.fi +.RE +.LP +The "Only in" messages required when the \fB-r\fP option is specified +are not used by most historical implementations if the +\fB-e\fP option is also specified. It is required here because it +provides useful information that must be provided to update a +target directory hierarchy to match a source hierarchy. The "Common +subdirectories" messages are written by System V and 4.3 BSD +when the \fB-r\fP option is specified. They are allowed here but are +not required because they are reporting on something that is +the same, not reporting a difference, and are not needed to update +a target hierarchy. +.LP +The \fB-c\fP option, which writes output in a format using lines of +context, has been included. The format is useful for a +variety of reasons, among them being much improved readability and +the ability to understand difference changes when the target +file has line numbers that differ from another similar, but slightly +different, copy. The \fIpatch\fP utility is most valuable when working +with difference listings using the context format. +The BSD version of \fB-c\fP takes an optional argument specifying +the amount of context. Rather than overloading \fB-c\fP and +breaking the Utility Syntax Guidelines for \fIdiff\fP, the standard +developers decided to add a separate option for specifying a +context diff with a specified amount of context ( \fB-C\fP). Also, +the format for context \fIdiff\fPs was extended slightly in +4.3 BSD to allow multiple changes that are within context lines from +each other to be merged together. The output format contains +an additional four asterisks after the range of affected lines in +the first filename. This was to provide a flag for old programs +(like old versions of \fIpatch\fP) that only understand the old context +format. The version +of context described here does not require that multiple changes within +context lines be merged, but it does not prohibit it +either. The extension is upwards-compatible, so any vendors that wish +to retain the old version of \fIdiff\fP can do so by adding +the extra four asterisks (that is, utilities that currently use \fIdiff\fP +and understand the new merged format will also +understand the old unmerged format, but not \fIvice versa\fP). +.LP +The substitute command was added as an additional format for the \fB-e\fP +option. This was added to provide implementations +with a way to fix the classic "dot alone on a line" bug present in +many versions of \fIdiff\fP. Since many implementations have +fixed this bug, the standard developers decided not to standardize +broken behavior, but rather to provide the necessary tool for +fixing the bug. One way to fix this bug is to output two periods whenever +a lone period is needed, then terminate the append +command with a period, and then use the substitute command to convert +the two periods into one period. +.LP +The BSD-derived \fB-r\fP option was added to provide a mechanism for +using \fIdiff\fP to compare two file system trees. This +behavior is useful, is standard practice on all BSD-derived systems, +and is not easily reproducible with the \fIfind\fP utility. +.LP +The requirement that \fIdiff\fP not compare files in some circumstances, +even though they have the same name, is based on the +actual output of historical implementations. The message specified +here is already in use when a directory is being compared to a +non-directory. It is extended here to preclude the problems arising +from running into FIFOs and other files that would cause +\fIdiff\fP to hang waiting for input with no indication to the user +that \fIdiff\fP was hung. In most common usage, \fIdiff\fP +\fB-r\fP should indicate differences in the file hierarchies, not +the difference of contents of devices pointed to by the +hierarchies. +.LP +Many early implementations of \fIdiff\fP require seekable files. Since +the System Interfaces volume of +IEEE\ Std\ 1003.1-2001 supports named pipes, the standard developers +decided that such a restriction was unreasonable. Note +also that the allowed filename \fB-\fP almost always refers to a pipe. +.LP +No directory search order is specified for \fIdiff\fP. The historical +ordering is, in fact, not optimal, in that it prints out +all of the differences at the current level, including the statements +about all common subdirectories before recursing into those +subdirectories. +.LP +The message: +.sp +.RS +.nf + +\fB"diff %s %s %s\\n", <\fP\fIdiff_options\fP\fB>, <\fP\fIfilename1\fP\fB>, <\fP\fIfilename2\fP\fB> +\fP +.fi +.RE +.LP +does not vary by locale because it is the representation of a command, +not an English sentence. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcmp\fP , \fIcomm\fP , \fIed\fP , \fIfind\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/dirname.1p b/man1p/dirname.1p new file mode 100644 index 000000000..3b4b292ce --- /dev/null +++ b/man1p/dirname.1p @@ -0,0 +1,214 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DIRNAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" dirname +.SH NAME +dirname \- return the directory portion of a pathname +.SH SYNOPSIS +.LP +\fBdirname\fP \fIstring\fP +.SH DESCRIPTION +.LP +The \fIstring\fP operand shall be treated as a pathname, as defined +in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 3.266, Pathname. The string +\fIstring\fP shall be converted to the name of the directory containing +the filename corresponding to the last pathname component +in \fIstring\fP, performing actions equivalent to the following steps +in order: +.IP " 1." 4 +If \fIstring\fP is \fB//\fP, skip steps 2 to 5. +.LP +.IP " 2." 4 +If \fIstring\fP consists entirely of slash characters, \fIstring\fP +shall be set to a single slash character. In this case, +skip steps 3 to 8. +.LP +.IP " 3." 4 +If there are any trailing slash characters in \fIstring\fP, they shall +be removed. +.LP +.IP " 4." 4 +If there are no slash characters remaining in \fIstring\fP, \fIstring\fP +shall be set to a single period character. In this +case, skip steps 5 to 8. +.LP +.IP " 5." 4 +If there are any trailing non-slash characters in \fIstring\fP, they +shall be removed. +.LP +.IP " 6." 4 +If the remaining \fIstring\fP is \fB//\fP, it is implementation-defined +whether steps 7 and 8 are skipped or processed. +.LP +.IP " 7." 4 +If there are any trailing slash characters in \fIstring\fP, they shall +be removed. +.LP +.IP " 8." 4 +If the remaining \fIstring\fP is empty, \fIstring\fP shall be set +to a single slash character. +.LP +.LP +The resulting string shall be written to standard output. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIstring\fP +A string. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIdirname\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fIdirname\fP utility shall write a line to the standard output +in the following format: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIresulting string\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The definition of \fIpathname\fP specifies implementation-defined +behavior for pathnames starting with two slash characters. +Therefore, applications shall not arbitrarily add slashes to the beginning +of a pathname unless they can ensure that there are more +or less than two or are prepared to deal with the implementation-defined +consequences. +.SH EXAMPLES +.TS C +center; l l. +\fBCommand\fP \fBResults\fP +\fIdirname\fP / / +\fIdirname\fP // / or // +\fIdirname\fP /\fIa\fP/\fIb\fP/ /\fIa\fP +\fIdirname\fP //\fIa\fP//\fIb\fP// //\fIa\fP +\fIdirname\fP Unspecified +\fIdirname a\fP . ($? = 0) +\fIdirname\fP "" . ($? = 0) +\fIdirname\fP /\fIa\fP / +\fIdirname\fP /\fIa\fP/\fIb\fP /\fIa\fP +\fIdirname\fP \fIa\fP/\fIb\fP \fIa\fP +.TE +.SH RATIONALE +.LP +The \fIdirname\fP utility originated in System III. It has evolved +through the System V releases to a version that matches the +requirements specified in this description in System V Release 3. +4.3 BSD and earlier versions did not include \fIdirname\fP. +.LP +The behaviors of \fIbasename\fP and \fIdirname\fP in this volume of +IEEE\ Std\ 1003.1-2001 have been coordinated so that when \fIstring\fP +is a valid pathname: +.sp +.RS +.nf + +\fB$(basename "\fP\fIstring\fP\fB") +\fP +.fi +.RE +.LP +would be a valid filename for the file in the directory: +.sp +.RS +.nf + +\fB$(dirname "\fP\fIstring\fP\fB") +\fP +.fi +.RE +.LP +This would not work for the versions of these utilities in early proposals +due to the way processing of trailing slashes was +specified. Consideration was given to leaving processing unspecified +if there were trailing slashes, but this cannot be done; the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 3.266, +Pathname allows trailing slashes. The \fIbasename\fP and \fIdirname\fP +utilities +have to specify consistent handling for all valid pathnames. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIbasename\fP() , \fIParameters and Variables\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/dot.1p b/man1p/dot.1p new file mode 100644 index 000000000..2c790bb82 --- /dev/null +++ b/man1p/dot.1p @@ -0,0 +1,103 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DOT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" dot +.SH NAME +dot \- execute commands in the current environment +.SH SYNOPSIS +.LP +\fB\&.\fP \fIfile\fP +.SH DESCRIPTION +.LP +The shell shall execute commands from the \fIfile\fP in the current +environment. +.LP +If \fIfile\fP does not contain a slash, the shell shall use the search +path specified by \fIPATH\fP to find the directory +containing \fIfile\fP. Unlike normal command search, however, the +file searched for by the \fIdot\fP utility need not be +executable. If no readable file is found, a non-interactive shell +shall abort; an interactive shell shall write a diagnostic +message to standard error, but this condition shall not be considered +a syntax error. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +See the DESCRIPTION. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +See the DESCRIPTION. +.SH ENVIRONMENT VARIABLES +.LP +See the DESCRIPTION. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +Returns the value of the last command executed, or a zero exit status +if no command is executed. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.sp +.RS +.nf + +\fBcat foobar +\fP\fBfoo=hello bar=world\fP\fB. foobar +echo $foo $bar +\fP\fBhello world\fP +.fi +.RE +.SH RATIONALE +.LP +Some older implementations searched the current directory for the +\fIfile\fP, even if the value of \fIPATH\fP disallowed it. +This behavior was omitted from this volume of IEEE\ Std\ 1003.1-2001 +due to concerns about introducing the susceptibility +to trojan horses that the user might be trying to avoid by leaving +\fBdot\fP out of \fIPATH .\fP +.LP +The KornShell version of \fIdot\fP takes optional arguments that are +set to the positional parameters. This is a valid +extension that allows a \fIdot\fP script to behave identically to +a function. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISpecial Built-In Utilities\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/du.1p b/man1p/du.1p new file mode 100644 index 000000000..3f34004f8 --- /dev/null +++ b/man1p/du.1p @@ -0,0 +1,244 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DU" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" du +.SH NAME +du \- estimate file space usage +.SH SYNOPSIS +.LP +\fBdu\fP \fB[\fP\fB-a | -s\fP\fB][\fP\fB-kx\fP\fB][\fP\fB-H | -L\fP\fB][\fP\fIfile\fP +\fB\&...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +By default, the \fIdu\fP utility shall write to standard output the +size of the file space allocated to, and the size of the +file space allocated to each subdirectory of, the file hierarchy rooted +in each of the specified files. By default, when a symbolic +link is encountered on the command line or in the file hierarchy, +\fIdu\fP shall count the size of the symbolic link (rather than +the file referenced by the link), and shall not follow the link to +another portion of the file hierarchy. The size of the file +space allocated to a file of type directory shall be defined as the +sum total of space allocated to all files in the file hierarchy +rooted in the directory plus the space allocated to the directory +itself. +.LP +When \fIdu\fP cannot \fIstat\fP() files or \fIstat\fP() or read directories, +it shall report an error condition and the final exit status is +affected. Files with multiple links shall be counted and written for +only one entry. The directory entry that is selected in the +report is unspecified. By default, file sizes shall be written in +512-byte units, rounded up to the next 512-byte unit. +.SH OPTIONS +.LP +The \fIdu\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-a\fP +In addition to the default output, report the size of each file not +of type directory in the file hierarchy rooted in the +specified file. Regardless of the presence of the \fB-a\fP option, +non-directories given as \fIfile\fP operands shall always be +listed. +.TP 7 +\fB-H\fP +If a symbolic link is specified on the command line, \fIdu\fP shall +count the size of the file or file hierarchy referenced by +the link. +.TP 7 +\fB-k\fP +Write the files sizes in units of 1024 bytes, rather than the default +512-byte units. +.TP 7 +\fB-L\fP +If a symbolic link is specified on the command line or encountered +during the traversal of a file hierarchy, \fIdu\fP shall +count the size of the file or file hierarchy referenced by the link. +.TP 7 +\fB-s\fP +Instead of the default output, report only the total sum for each +of the specified files. +.TP 7 +\fB-x\fP +When evaluating file sizes, evaluate only those files that have the +same device as the file specified by the \fIfile\fP +operand. +.sp +.LP +Specifying more than one of the mutually-exclusive options \fB-H\fP +and \fB-L\fP shall not be considered an error. The last +option specified shall determine the behavior of the utility. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +The pathname of a file whose size is to be written. If no \fIfile\fP +is specified, the current directory shall be used. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIdu\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The output from \fIdu\fP shall consist of the amount of space allocated +to a file and the name of the file, in the following +format: +.sp +.RS +.nf + +\fB"%d %s\\n", <\fP\fIsize\fP\fB>, <\fP\fIpathname\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The use of 512-byte units is historical practice and maintains compatibility +with \fIls\fP +and other utilities in this volume of IEEE\ Std\ 1003.1-2001. This +does not mandate that the file system itself be based on +512-byte blocks. The \fB-k\fP option was added as a compromise measure. +It was agreed by the standard developers that 512 bytes +was the best default unit because of its complete historical consistency +on System V (\fIversus\fP the mixed 512/1024-byte usage +on BSD systems), and that a \fB-k\fP option to switch to 1024-byte +units was a good compromise. Users who prefer the 1024-byte +quantity can easily alias \fIdu\fP to \fIdu\fP \fB-k\fP without breaking +the many historical scripts relying on the 512-byte +units. +.LP +The \fB-b\fP option was added to an early proposal to provide a resolution +to the situation where System V and BSD systems give +figures for file sizes in \fIblocks\fP, which is an implementation-defined +concept. (In common usage, the block size is 512 bytes +for System V and 1024 bytes for BSD systems.) However, \fB-b\fP was +later deleted, since the default was eventually decided as +512-byte units. +.LP +Historical file systems provided no way to obtain exact figures for +the space allocation given to files. There are two known +areas of inaccuracies in historical file systems: cases of \fIindirect +blocks\fP being used by the file system or \fIsparse\fP +files yielding incorrectly high values. An indirect block is space +used by the file system in the storage of the file, but that +need not be counted in the space allocated to the file. A \fIsparse\fP +file is one in which an \fIlseek\fP() call has been made to a position +beyond the end of the file and data has subsequently +been written at that point. A file system need not allocate all the +intervening zero-filled blocks to such a file. It is up to the +implementation to define exactly how accurate its methods are. +.LP +The \fB-a\fP and \fB-s\fP options were mutually-exclusive in the original +version of \fIdu\fP. The POSIX Shell and Utilities +description is implied by the language in the SVID where \fB-s\fP +is described as causing "only the grand total" to be reported. +Some systems may produce output for \fB-sa\fP, but a Strictly Conforming +POSIX Shell and Utilities Application cannot use that +combination. +.LP +The \fB-a\fP and \fB-s\fP options were adopted from the SVID except +that the System V behavior of not listing non-directories +explicitly given as operands, unless the \fB-a\fP option is specified, +was considered a bug; the BSD-based behavior (report for +all operands) is mandated. The default behavior of \fIdu\fP in the +SVID with regard to reporting the failure to read files (it +produces no messages) was considered counter-intuitive, and thus it +was specified that the POSIX Shell and Utilities default +behavior shall be to produce such messages. These messages can be +turned off with shell redirection to achieve the System V +behavior. +.LP +The \fB-x\fP option is historical practice on recent BSD systems. +It has been adopted by this volume of +IEEE\ Std\ 1003.1-2001 because there was no other historical method +of limiting the \fIdu\fP search to a single file +hierarchy. This limitation of the search is necessary to make it possible +to obtain file space usage information about a file +system on which other file systems are mounted, without having to +resort to a lengthy \fIfind\fP and \fIawk\fP script. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIls\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIstat\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/echo.1p b/man1p/echo.1p new file mode 100644 index 000000000..4a371bf1b --- /dev/null +++ b/man1p/echo.1p @@ -0,0 +1,246 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ECHO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" echo +.SH NAME +echo \- write arguments to standard output +.SH SYNOPSIS +.LP +\fBecho\fP \fB[\fP\fIstring\fP \fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIecho\fP utility writes its arguments to standard output, followed +by a . If there are no arguments, only +the is written. +.SH OPTIONS +.LP +The \fIecho\fP utility shall not recognize the \fB"--"\fP argument +in the manner specified by Guideline 10 of the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility +Syntax +Guidelines; \fB"--"\fP shall be recognized as a string operand. +.LP +Implementations shall not support any options. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIstring\fP +A string to be written to standard output. If the first operand is +\fB-n\fP, or if any of the operands contain a backslash ( +\fB'\\'\fP ) character, the results are implementation-defined. +.LP +On XSI-conformant systems, if the first operand is \fB-n\fP, it shall +be treated as a string, not an option. The following +character sequences shall be recognized on XSI-conformant systems +within any of the arguments: +.TP 7 +\fB\\a\fP +.RS +Write an . +.RE +.TP 7 +\fB\\b\fP +.RS +Write a . +.RE +.TP 7 +\fB\\c\fP +.RS +Suppress the that otherwise follows the final argument in +the output. All characters following the +\fB'\\c'\fP in the arguments shall be ignored. +.RE +.TP 7 +\fB\\f\fP +.RS +Write a . +.RE +.TP 7 +\fB\\n\fP +.RS +Write a . +.RE +.TP 7 +\fB\\r\fP +.RS +Write a . +.RE +.TP 7 +\fB\\t\fP +.RS +Write a . +.RE +.TP 7 +\fB\\v\fP +.RS +Write a . +.RE +.TP 7 +\fB\\\\\fP +.RS +Write a backslash character. +.RE +.TP 7 +\fB\\0\fP\fInum\fP +.RS +Write an 8-bit value that is the zero, one, two, or three-digit octal +number \fInum\fP. +.RE +.sp +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIecho\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as opposed +to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fIecho\fP utility arguments shall be separated by single s +and a shall follow the last +argument. \ Output transformations shall occur based on the escape +sequences in the input. See the OPERANDS section. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +It is not possible to use \fIecho\fP portably across all POSIX systems +unless both \fB-n\fP (as the first argument) and escape +sequences are omitted. +.LP +The \fIprintf\fP utility can be used portably to emulate any of the +traditional +behaviors of the \fIecho\fP utility as follows (assuming that \fIIFS\fP +has its standard value or is unset): +.IP " *" 3 +The historic System V \fIecho\fP and the requirements on XSI implementations +in this volume of IEEE\ Std\ 1003.1-2001 +are equivalent to: +.sp +.RS +.nf + +\fBprintf "%b\\n" "$*" +\fP +.fi +.RE +.LP +.IP " *" 3 +The BSD \fIecho\fP is equivalent to: +.sp +.RS +.nf + +\fBif [ "X$1" = "X-n" ] +then + shift + printf "%s" "$*" +else + printf "%s\\n" "$*" +fi +\fP +.fi +.RE +.LP +.LP +New applications are encouraged to use \fIprintf\fP instead of \fIecho\fP. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIecho\fP utility has not been made obsolescent because of its +extremely widespread use in historical applications. +Conforming applications that wish to do prompting without s +or that could possibly be expecting to echo a \fB-n\fP, +should use the \fIprintf\fP utility derived from the Ninth Edition +system. +.LP +As specified, \fIecho\fP writes its arguments in the simplest of ways. +The two different historical versions of \fIecho\fP +vary in fatally incompatible ways. +.LP +The BSD \fIecho\fP checks the first argument for the string \fB-n\fP +which causes it to suppress the that +would otherwise follow the final argument in the output. +.LP +The System V \fIecho\fP does not support any options, but allows escape +sequences within its operands, as described for XSI +implementations in the OPERANDS section. +.LP +The \fIecho\fP utility does not support Utility Syntax Guideline 10 +because historical applications depend on \fIecho\fP to +echo \fIall\fP of its arguments, except for the \fB-n\fP option in +the BSD version. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIprintf\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/ed.1p b/man1p/ed.1p new file mode 100644 index 000000000..b7817a257 --- /dev/null +++ b/man1p/ed.1p @@ -0,0 +1,1462 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ed +.SH NAME +ed \- edit text +.SH SYNOPSIS +.LP +\fBed\fP \fB[\fP\fB-p\fP \fIstring\fP\fB][\fP\fB-s\fP\fB][\fP\fIfile\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIed\fP utility is a line-oriented text editor that uses two +modes: \fIcommand mode\fP and \fIinput mode\fP. In command +mode the input characters shall be interpreted as commands, and in +input mode they shall be interpreted as text. See the EXTENDED +DESCRIPTION section. +.SH OPTIONS +.LP +The \fIed\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-p\ \fP \fIstring\fP +Use \fIstring\fP as the prompt string when in command mode. By default, +there shall be no prompt string. +.TP 7 +\fB-s\fP +Suppress the writing of byte counts by \fBe\fP, \fBE\fP, \fBr\fP, +and \fBw\fP commands and of the \fB'!'\fP prompt after +a !\fIcommand\fP. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +If the \fIfile\fP argument is given, \fIed\fP shall simulate an \fBe\fP +command on the file named by the pathname, +\fIfile\fP, before accepting commands from the standard input. If +the \fIfile\fP operand is \fB'-'\fP , the results are +unspecified. +.sp +.SH STDIN +.LP +The standard input shall be a text file consisting of commands, as +described in the EXTENDED DESCRIPTION section. +.SH INPUT FILES +.LP +The input files shall be text files. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIed\fP: +.TP 7 +\fIHOME\fP +Determine the pathname of the user's home directory. +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular +expressions. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and +the behavior of character classes within regular +expressions. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +The \fIed\fP utility shall take the standard action for all signals +(see the ASYNCHRONOUS EVENTS section in \fIUtility Description Defaults\fP +) with the following exceptions: +.TP 7 +SIGINT +The \fIed\fP utility shall interrupt its current activity, write the +string \fB"?\\n"\fP to standard output, and return to +command mode (see the EXTENDED DESCRIPTION section). +.TP 7 +SIGHUP +If the buffer is not empty and has changed since the last write, the +\fIed\fP utility shall attempt to write a copy of the +buffer in a file. First, the file named \fBed.hup\fP in the current +directory shall be used; if that fails, the file named +\fBed.hup\fP in the directory named by the \fIHOME\fP environment +variable shall be used. In any case, the \fIed\fP utility +shall exit without returning to command mode. +.TP 7 +SIGQUIT +The \fIed\fP utility shall ignore this event. +.sp +.SH STDOUT +.LP +Various editing commands and the prompting feature (see \fB-p\fP) +write to standard output, as described in the EXTENDED +DESCRIPTION section. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +The output files shall be text files whose formats are dependent on +the editing commands given. +.SH EXTENDED DESCRIPTION +.LP +The \fIed\fP utility shall operate on a copy of the file it is editing; +changes made to the copy shall have no effect on the +file until a \fBw\fP (write) command is given. The copy of the text +is called the \fIbuffer\fP. +.LP +Commands to \fIed\fP have a simple and regular structure: zero, one, +or two \fIaddresses\fP followed by a single-character +\fIcommand\fP, possibly followed by parameters to that command. These +addresses specify one or more lines in the buffer. Every +command that requires addresses has default addresses, so that the +addresses very often can be omitted. If the \fB-p\fP option is +specified, the prompt string shall be written to standard output before +each command is read. +.LP +In general, only one command can appear on a line. Certain commands +allow text to be input. This text is placed in the +appropriate place in the buffer. While \fIed\fP is accepting text, +it is said to be in \fIinput mode\fP. In this mode, no +commands shall be recognized; all input is merely collected. Input +mode is terminated by entering a line consisting of two +characters: a period ( \fB'.'\fP ) followed by a . This line +is not considered part of the input text. +.SS Regular Expressions in ed +.LP +The \fIed\fP utility shall support basic regular expressions, as described +in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 9.3, Basic Regular Expressions. Since +regular expressions in \fIed\fP are always matched against single +lines (excluding the terminating s), never +against any larger section of text, there is no way for a regular +expression to match a . +.LP +A null RE shall be equivalent to the last RE encountered. +.LP +Regular expressions are used in addresses to specify lines, and in +some commands (for example, the \fBs\fP substitute command) +to specify portions of a line to be substituted. +.SS Addresses in ed +.LP +Addressing in \fIed\fP relates to the current line. Generally, the +current line is the last line affected by a command. The +current line number is the address of the current line. If the edit +buffer is not empty, the initial value for the current line +shall be the last line in the edit buffer; otherwise, zero. +.LP +Addresses shall be constructed as follows: +.IP " 1." 4 +The period character ( \fB'.'\fP ) shall address the current line. +.LP +.IP " 2." 4 +The dollar sign character ( \fB'$'\fP ) shall address the last line +of the edit buffer. +.LP +.IP " 3." 4 +The positive decimal number \fIn\fP shall address the \fIn\fPth line +of the edit buffer. +.LP +.IP " 4." 4 +The apostrophe-x character pair ( \fB"'x"\fP ) shall address the line +marked with the mark name character \fIx\fP, which +shall be a lowercase letter from the portable character set. It shall +be an error if the character has not been set to mark a line +or if the line that was marked is not currently present in the edit +buffer. +.LP +.IP " 5." 4 +A BRE enclosed by slash characters ( \fB'/'\fP ) shall address the +first line found by searching forwards from the line +following the current line toward the end of the edit buffer and stopping +at the first line for which the line excluding the +terminating matches the BRE. The BRE consisting of a null +BRE delimited by a pair of slash characters shall address +the next line for which the line excluding the terminating +matches the last BRE encountered. In addition, the +second slash can be omitted at the end of a command line. Within the +BRE, a backslash-slash pair ( \fB"\\/"\fP ) shall represent +a literal slash instead of the BRE delimiter. If necessary, the search +shall wrap around to the beginning of the buffer and +continue up to and including the current line, so that the entire +buffer is searched. +.LP +.IP " 6." 4 +A BRE enclosed by question-mark characters ( \fB'?'\fP ) shall address +the first line found by searching backwards from the +line preceding the current line toward the beginning of the edit buffer +and stopping at the first line for which the line excluding +the terminating matches the BRE. The BRE consisting of a +null BRE delimited by a pair of question-mark characters ( +\fB"??"\fP ) shall address the previous line for which the line excluding +the terminating matches the last BRE +encountered. In addition, the second question-mark can be omitted +at the end of a command line. Within the BRE, a +backslash-question-mark pair ( \fB"\\?"\fP ) shall represent a literal +question mark instead of the BRE delimiter. If necessary, +the search shall wrap around to the end of the buffer and continue +up to and including the current line, so that the entire buffer +is searched. +.LP +.IP " 7." 4 +A plus-sign ( \fB'+'\fP ) or hyphen character ( \fB'-'\fP ) followed +by a decimal number shall address the current line +plus or minus the number. A plus-sign or hyphen character not followed +by a decimal number shall address the current line plus or +minus 1. +.LP +.LP +Addresses can be followed by zero or more address offsets, optionally +-separated. Address offsets are constructed +as follows: +.IP " *" 3 +A plus-sign or hyphen character followed by a decimal number shall +add or subtract, respectively, the indicated number of lines +to or from the address. A plus-sign or hyphen character not followed +by a decimal number shall add or subtract 1 to or from the +address. +.LP +.IP " *" 3 +A decimal number shall add the indicated number of lines to the address. +.LP +.LP +It shall not be an error for an intermediate address value to be less +than zero or greater than the last line in the edit +buffer. It shall be an error for the final address value to be less +than zero or greater than the last line in the edit buffer. It +shall be an error if a search for a BRE fails to find a matching line. +.LP +Commands accept zero, one, or two addresses. If more than the required +number of addresses are provided to a command that +requires zero addresses, it shall be an error. Otherwise, if more +than the required number of addresses are provided to a command, +the addresses specified first shall be evaluated and then discarded +until the maximum number of valid addresses remain, for the +specified command. +.LP +Addresses shall be separated from each other by a comma ( \fB','\fP +) or semicolon character ( \fB';'\fP ). In the case of +a semicolon separator, the current line ( \fB'.'\fP ) shall be set +to the first address, and only then will the second address +be calculated. This feature can be used to determine the starting +line for forwards and backwards searches; see rules 5. and 6. +.LP +Addresses can be omitted on either side of the comma or semicolon +separator, in which case the resulting address pairs shall be +as follows: +.TS C +center; l l. +\fBSpecified\fP \fBResulting\fP +, 1 , $ +, addr 1 , addr +addr , addr , addr +; . ; $ +; addr . ; addr +addr ; addr ; addr +.TE +.LP +Any s included between addresses, address separators, or address +offsets shall be ignored. +.SS Commands in ed +.LP +In the following list of \fIed\fP commands, the default addresses +are shown in parentheses. The number of addresses shown in +the default shall be the number expected by the command. The parentheses +are not part of the address; they show that the given +addresses are the default. +.LP +It is generally invalid for more than one command to appear on a line. +However, any command (except \fBe\fP, \fBE\fP, +\fBf\fP, \fBq\fP, \fBQ\fP, \fBr\fP, \fBw\fP, and \fB!\fP) can be suffixed +by the letter \fBl\fP, \fBn\fP, or \fBp\fP; in +which case, except for the \fBl\fP, \fBn\fP, and \fBp\fP commands, +the command shall be executed and then the new current line +shall be written as described below under the \fBl\fP, \fBn\fP, and +\fBp\fP commands. When an \fBl\fP, \fBn\fP, or \fBp\fP +suffix is used with an \fBl\fP, \fBn\fP, or \fBp\fP command, the command +shall write to standard output as described below, but +it is unspecified whether the suffix writes the current line again +in the requested format or whether the suffix has no effect. For +example, the \fBpl\fP command (base \fBp\fP command with an \fBl\fP +suffix) shall either write just the current line or write it +twice-once as specified for \fBp\fP and once as specified for \fBl\fP. +Also, the \fBg\fP, \fBG\fP, \fBv\fP, and \fBV\fP +commands shall take a command as a parameter. +.LP +Each address component can be preceded by zero or more s. The +command letter can be preceded by zero or more +s. If a suffix letter ( \fBl\fP, \fBn\fP, or \fBp\fP) is given, +the application shall ensure that it immediately +follows the command. +.LP +The \fBe\fP, \fBE\fP, \fBf\fP, \fBr\fP, and \fBw\fP commands shall +take an optional \fIfile\fP parameter, separated from +the command letter by one or more s. +.LP +If changes have been made in the buffer since the last \fBw\fP command +that wrote the entire buffer, \fIed\fP shall warn the +user if an attempt is made to destroy the editor buffer via the \fBe\fP +or \fBq\fP commands. The \fIed\fP utility shall write +the string: +.sp +.RS +.nf + +\fB"?\\n" +\fP +.fi +.RE +.LP +(followed by an explanatory message if \fIhelp mode\fP has been enabled +via the \fBH\fP command) to standard output and shall +continue in command mode with the current line number unchanged. If +the \fBe\fP or \fBq\fP command is repeated with no +intervening command, it shall take effect. +.LP +If a terminal disconnect is detected: +.IP " *" 3 +If the buffer is not empty and has changed since the last write, the +\fIed\fP utility shall attempt to write a copy of the +buffer to a file named \fBed.hup\fP in the current directory. If this +write fails, \fIed\fP shall attempt to write a copy of the +buffer to a filename \fBed.hup\fP in the directory named by the \fIHOME\fP +environment variable. If both these attempts fail, +\fIed\fP shall exit without saving the buffer. +.LP +.IP " *" 3 +The \fIed\fP utility shall not write the file to the currently remembered +pathname or return to command mode, and shall +terminate with a non-zero exit status. +.LP +.LP +If an end-of-file is detected on standard input: +.IP " *" 3 +If the \fIed\fP utility is in input mode, \fIed\fP shall terminate +input mode and return to command mode. It is unspecified if +any partially entered lines (that is, input text without a terminating +) are discarded from the input text. +.LP +.IP " *" 3 +If the \fIed\fP utility is in command mode, it shall act as if a \fBq\fP +command had been entered. +.LP +.LP +If the closing delimiter of an RE or of a replacement string (for +example, \fB'/'\fP ) in a \fBg\fP, \fBG\fP, \fBs\fP, +\fBv\fP, or \fBV\fP command would be the last character before a , +that delimiter can be omitted, in which case +the addressed line shall be written. For example, the following pairs +of commands are equivalent: +.sp +.RS +.nf + +\fBs/s1/s2 s/s1/s2/p +g/s1 g/s1/p +?s1 ?s1? +\fP +.fi +.RE +.LP +If an invalid command is entered, \fIed\fP shall write the string: +.sp +.RS +.nf + +\fB"?\\n" +\fP +.fi +.RE +.LP +(followed by an explanatory message if \fIhelp mode\fP has been enabled +via the \fBH\fP command) to standard output and shall +continue in command mode with the current line number unchanged. +.SS Append Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(.)a +<\fP\fItext\fP\fB> +\&. +\fP +.fi +.RE +.sp +.LP +The \fBa\fP command shall read the given text and append it after +the addressed line; the current line number shall become the +address of the last inserted line or, if there were none, the addressed +line. Address 0 shall be valid for this command; it shall +cause the appended text to be placed at the beginning of the buffer. +.SS Change Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(.,.)c +<\fP\fItext\fP\fB> +\&. +\fP +.fi +.RE +.sp +.LP +The \fBc\fP command shall delete the addressed lines, then accept +input text that replaces these lines; the current line shall +be set to the address of the last line input; or, if there were none, +at the line after the last line deleted; if the lines deleted +were originally at the end of the buffer, the current line number +shall be set to the address of the new last line; if no lines +remain in the buffer, the current line number shall be set to zero. +Address 0 shall be valid for this command; it shall be +interpreted as if address 1 were specified. +.SS Delete Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(.,.)d +\fP +.fi +.RE +.sp +.LP +The \fBd\fP command shall delete the addressed lines from the buffer. +The address of the line after the last line deleted shall +become the current line number; if the lines deleted were originally +at the end of the buffer, the current line number shall be set +to the address of the new last line; if no lines remain in the buffer, +the current line number shall be set to zero. +.SS Edit Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBe\fP \fB[\fP\fIfile\fP\fB]\fP +.fi +.RE +.sp +.LP +The \fBe\fP command shall delete the entire contents of the buffer +and then read in the file named by the pathname \fIfile\fP. +The current line number shall be set to the address of the last line +of the buffer. If no pathname is given, the currently +remembered pathname, if any, shall be used (see the \fBf\fP command). +The number of bytes read shall be written to standard +output, unless the \fB-s\fP option was specified, in the following +format: +.sp +.RS +.nf + +\fB"%d\\n", <\fP\fInumber of bytes read\fP\fB> +\fP +.fi +.RE +.LP +The name \fIfile\fP shall be remembered for possible use as a default +pathname in subsequent \fBe\fP, \fBE\fP, \fBr\fP, and +\fBw\fP commands. If \fIfile\fP is replaced by \fB'!'\fP , the rest +of the line shall be taken to be a shell command line +whose output is to be read. Such a shell command line shall not be +remembered as the current \fIfile\fP. All marks shall be +discarded upon the completion of a successful \fBe\fP command. If +the buffer has changed since the last time the entire buffer was +written, the user shall be warned, as described previously. +.SS Edit Without Checking Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBE\fP \fB[\fP\fIfile\fP\fB]\fP +.fi +.RE +.sp +.LP +The \fBE\fP command shall possess all properties and restrictions +of the \fBe\fP command except that the editor shall not +check to see whether any changes have been made to the buffer since +the last \fBw\fP command. +.SS Filename Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBf\fP \fB[\fP\fIfile\fP\fB]\fP +.fi +.RE +.sp +.LP +If \fIfile\fP is given, the \fBf\fP command shall change the currently +remembered pathname to \fIfile\fP; whether the name is +changed or not, it shall then write the (possibly new) currently remembered +pathname to the standard output in the following +format: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIpathname\fP\fB> +\fP +.fi +.RE +.LP +The current line number shall be unchanged. +.SS Global Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(1,$)g/\fP\fIRE\fP\fB/\fP\fIcommand list\fP +.fi +.RE +.sp +.LP +In the \fBg\fP command, the first step shall be to mark every line +for which the line excluding the terminating +matches the given RE. Then, going sequentially from the beginning +of the file to the end of the file, the given \fIcommand list\fP +shall be executed for each marked line, with the current line number +set to the address of that line. Any line modified by the +\fIcommand list\fP shall be unmarked. When the \fBg\fP command completes, +the current line number shall have the value assigned +by the last command in the \fIcommand list\fP. If there were no matching +lines, the current line number shall not be changed. A +single command or the first of a list of commands shall appear on +the same line as the global command. All lines of a multi-line +list except the last line shall be ended with a backslash preceding +the terminating ; the \fBa\fP, \fBi\fP, and +\fBc\fP commands and associated input are permitted. The \fB'.'\fP +terminating input mode can be omitted if it would be the +last line of the \fIcommand list\fP. An empty \fIcommand list\fP shall +be equivalent to the \fBp\fP command. The use of the +\fBg\fP, \fBG\fP, \fBv\fP, \fBV\fP, and \fB!\fP commands in the \fIcommand +list\fP produces undefined results. Any character +other than or can be used instead of a slash to +delimit the RE. Within the RE, the RE delimiter +itself can be used as a literal character if it is preceded by a backslash. +.SS Interactive Global Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(1,$)G/\fP\fIRE\fP\fB/ +\fP +.fi +.RE +.sp +.LP +In the \fBG\fP command, the first step shall be to mark every line +for which the line excluding the terminating +matches the given RE. Then, for every such line, that line shall be +written, the current line number shall be set to the address of +that line, and any one command (other than one of the \fBa\fP, \fBc\fP, +\fBi\fP, \fBg\fP, \fBG\fP, \fBv\fP, and \fBV\fP +commands) shall be read and executed. A shall act as a null +command (causing no action to be taken on the current +line); an \fB'&'\fP shall cause the re-execution of the most recent +non-null command executed within the current invocation +of \fBG\fP. Note that the commands input as part of the execution +of the \fBG\fP command can address and affect any lines in the +buffer. Any line modified by the command shall be unmarked. The final +value of the current line number shall be the value set by +the last command successfully executed. (Note that the last command +successfully executed shall be the \fBG\fP command itself if a +command fails or the null command is specified.) If there were no +matching lines, the current line number shall not be changed. The +\fBG\fP command can be terminated by a SIGINT signal. Any character +other than or can be used +instead of a slash to delimit the RE and the replacement. Within the +RE, the RE delimiter itself can be used as a literal character +if it is preceded by a backslash. +.SS Help Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBh +\fP +.fi +.RE +.sp +.LP +The \fBh\fP command shall write a short message to standard output +that explains the reason for the most recent \fB'?'\fP +notification. The current line number shall be unchanged. +.SS Help-Mode Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBH +\fP +.fi +.RE +.sp +.LP +The \fBH\fP command shall cause \fIed\fP to enter a mode in which +help messages (see the \fBh\fP command) shall be written to +standard output for all subsequent \fB'?'\fP notifications. The \fBH\fP +command alternately shall turn this mode on and off; it +is initially off. If the help-mode is being turned on, the \fBH\fP +command also explains the previous \fB'?'\fP notification, +if there was one. The current line number shall be unchanged. +.SS Insert Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(.)i +<\fP\fItext\fP\fB> +\&. +\fP +.fi +.RE +.sp +.LP +The \fBi\fP command shall insert the given text before the addressed +line; the current line is set to the last inserted line +or, if there was none, to the addressed line. This command differs +from the \fBa\fP command only in the placement of the input +text. Address 0 shall be valid for this command; it shall be interpreted +as if address 1 were specified. +.SS Join Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(.,.+1)j +\fP +.fi +.RE +.sp +.LP +The \fBj\fP command shall join contiguous lines by removing the appropriate +s. If exactly one address is given, +this command shall do nothing. If lines are joined, the current line +number shall be set to the address of the joined line; +otherwise, the current line number shall be unchanged. +.SS Mark Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(.)k\fP\fIx\fP +.fi +.RE +.sp +.LP +The \fBk\fP command shall mark the addressed line with name \fIx\fP, +which the application shall ensure is a lowercase letter +from the portable character set. The address \fB"'x"\fP shall then +refer to this line; the current line number shall be +unchanged. +.SS List Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(.,.)l +\fP +.fi +.RE +.sp +.LP +The \fBl\fP command shall write to standard output the addressed lines +in a visually unambiguous form. The characters listed in +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Table 5-1, +Escape Sequences and Associated Actions ( \fB'\\\\'\fP , +\fB'\\a'\fP , \fB'\\b'\fP , \fB'\\f'\fP , \fB'\\r'\fP , \fB'\\t'\fP +, \fB'\\v'\fP ) shall be written as the +corresponding escape sequence; the \fB'\\n'\fP in that table is not +applicable. Non-printable characters not in the table shall +be written as one three-digit octal number (with a preceding backslash +character) for each byte in the character (most significant +byte first). If the size of a byte on the system is greater than nine +bits, the format used for non-printable characters is +implementation-defined. +.LP +Long lines shall be folded, with the point of folding indicated by + preceded by a backslash; the length at which +folding occurs is unspecified, but should be appropriate for the output +device. The end of each line shall be marked with a +\fB'$'\fP , and \fB'$'\fP characters within the text shall be written +with a preceding backslash. An \fBl\fP command can be +appended to any other command other than \fBe\fP, \fBE\fP, \fBf\fP, +\fBq\fP, \fBQ\fP, \fBr\fP, \fBw\fP, or \fB!\fP. The +current line number shall be set to the address of the last line written. +.SS Move Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(.,.)m\fP\fIaddress\fP +.fi +.RE +.sp +.LP +The \fBm\fP command shall reposition the addressed lines after the +line addressed by \fIaddress\fP. Address 0 shall be valid +for \fIaddress\fP and cause the addressed lines to be moved to the +beginning of the buffer. It shall be an error if address +\fIaddress\fP falls within the range of moved lines. The current line +number shall be set to the address of the last line +moved. +.SS Number Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(.,.)n +\fP +.fi +.RE +.sp +.LP +The \fBn\fP command shall write to standard output the addressed lines, +preceding each line by its line number and a +; the current line number shall be set to the address of the +last line written. The \fBn\fP command can be appended to +any command other than \fBe\fP, \fBE\fP, \fBf\fP, \fBq\fP, \fBQ\fP, +\fBr\fP, \fBw\fP, or \fB!\fP. +.SS Print Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(.,.)p +\fP +.fi +.RE +.sp +.LP +The \fBp\fP command shall write to standard output the addressed lines; +the current line number shall be set to the address of +the last line written. The \fBp\fP command can be appended to any +command other than \fBe\fP, \fBE\fP, \fBf\fP, \fBq\fP, +\fBQ\fP, \fBr\fP, \fBw\fP, or \fB!\fP. +.SS Prompt Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBP +\fP +.fi +.RE +.sp +.LP +The \fBP\fP command shall cause \fIed\fP to prompt with an asterisk +( \fB'*'\fP ) (or \fIstring\fP, if \fB-p\fP is +specified) for all subsequent commands. The \fBP\fP command alternatively +shall turn this mode on and off; it shall be initially +on if the \fB-p\fP option is specified; otherwise, off. The current +line number shall be unchanged. +.SS Quit Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBq +\fP +.fi +.RE +.sp +.LP +The \fBq\fP command shall cause \fIed\fP to exit. If the buffer has +changed since the last time the entire buffer was written, +the user shall be warned, as described previously. +.SS Quit Without Checking Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBQ +\fP +.fi +.RE +.sp +.LP +The \fBQ\fP command shall cause \fIed\fP to exit without checking +whether changes have been made in the buffer since the last +\fBw\fP command. +.SS Read Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB($)r\fP \fB[\fP\fIfile\fP\fB]\fP +.fi +.RE +.sp +.LP +The \fBr\fP command shall read in the file named by the pathname \fIfile\fP +and append it after the addressed line. If no +\fIfile\fP argument is given, the currently remembered pathname, if +any, shall be used (see the \fBe\fP and \fBf\fP commands). +The currently remembered pathname shall not be changed unless there +is no remembered pathname. Address 0 shall be valid for +\fBr\fP and shall cause the file to be read at the beginning of the +buffer. If the read is successful, and \fB-s\fP was not +specified, the number of bytes read shall be written to standard output +in the following format: +.sp +.RS +.nf + +\fB"%d\\n", <\fP\fInumber of bytes read\fP\fB> +\fP +.fi +.RE +.LP +The current line number shall be set to the address of the last line +read in. If \fIfile\fP is replaced by \fB'!'\fP , the +rest of the line shall be taken to be a shell command line whose output +is to be read. Such a shell command line shall not be +remembered as the current pathname. +.SS Substitute Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(.,.)s/\fP\fIRE\fP\fB/\fP\fIreplacement\fP\fB/\fP\fIflags\fP +.fi +.RE +.sp +.LP +The \fBs\fP command shall search each addressed line for an occurrence +of the specified RE and replace either the first or all +(non-overlapped) matched strings with the \fIreplacement\fP; see the +following description of the \fBg\fP suffix. It is an error +if the substitution fails on every addressed line. Any character other +than or can be used instead of +a slash to delimit the RE and the replacement. Within the RE, the +RE delimiter itself can be used as a literal character if it is +preceded by a backslash. The current line shall be set to the address +of the last line on which a substitution occurred. +.LP +An ampersand ( \fB'&'\fP ) appearing in the \fIreplacement\fP shall +be replaced by the string matching the RE on the +current line. The special meaning of \fB'&'\fP in this context can +be suppressed by preceding it by backslash. As a more +general feature, the characters \fB'\\n'\fP , where \fIn\fP is a digit, +shall be replaced by the text matched by the +corresponding back-reference expression. When the character \fB'%'\fP +is the only character in the \fIreplacement\fP, the +\fIreplacement\fP used in the most recent substitute command shall +be used as the \fIreplacement\fP in the current substitute +command; if there was no previous substitute command, the use of \fB'%'\fP +in this manner shall be an error. The \fB'%'\fP +shall lose its special meaning when it is in a replacement string +of more than one character or is preceded by a backslash. For +each backslash ( \fB'\\'\fP ) encountered in scanning \fIreplacement\fP +from beginning to end, the following character shall +lose its special meaning (if any). It is unspecified what special +meaning is given to any character other than \fB'&'\fP , +\fB'\\'\fP , \fB'%'\fP , or digits. +.LP +A line can be split by substituting a into it. The application +shall ensure it escapes the in +the \fIreplacement\fP by preceding it by backslash. Such substitution +cannot be done as part of a \fBg\fP or \fBv\fP \fIcommand +list\fP. The current line number shall be set to the address of the +last line on which a substitution is performed. If no +substitution is performed, the current line number shall be unchanged. +If a line is split, a substitution shall be considered to +have been performed on each of the new lines for the purpose of determining +the new current line number. A substitution shall be +considered to have been performed even if the replacement string is +identical to the string that it replaces. +.LP +The application shall ensure that the value of \fIflags\fP is zero +or more of: +.TP 7 +\fIcount\fP +Substitute for the \fIcount\fPth occurrence only of the RE found on +each addressed line. +.TP 7 +\fBg\fP +Globally substitute for all non-overlapping instances of the RE rather +than just the first one. If both \fBg\fP and +\fIcount\fP are specified, the results are unspecified. +.TP 7 +\fBl\fP +Write to standard output the final line in which a substitution was +made. The line shall be written in the format specified for +the \fBl\fP command. +.TP 7 +\fBn\fP +Write to standard output the final line in which a substitution was +made. The line shall be written in the format specified for +the \fBn\fP command. +.TP 7 +\fBp\fP +Write to standard output the final line in which a substitution was +made. The line shall be written in the format specified for +the \fBp\fP command. +.sp +.SS Copy Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(.,.)t\fP\fIaddress\fP +.fi +.RE +.sp +.LP +The \fBt\fP command shall be equivalent to the \fBm\fP command, except +that a copy of the addressed lines shall be placed +after address \fIaddress\fP (which can be 0); the current line number +shall be set to the address of the last line added. +.SS Undo Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBu +\fP +.fi +.RE +.sp +.LP +The \fBu\fP command shall nullify the effect of the most recent command +that modified anything in the buffer, namely the most +recent \fBa\fP, \fBc\fP, \fBd\fP, \fBg\fP, \fBi\fP, \fBj\fP, \fBm\fP, +\fBr\fP, \fBs\fP, \fBt\fP, \fBu\fP, \fBv\fP, +\fBG\fP, or \fBV\fP command. All changes made to the buffer by a \fBg\fP, +\fBG\fP, \fBv\fP, or \fBV\fP global command shall +be undone as a single change; if no changes were made by the global +command (such as with \fBg\fP/RE/ \fBp\fP), the \fBu\fP +command shall have no effect. The current line number shall be set +to the value it had immediately before the command being undone +started. +.SS Global Non-Matched Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(1,$)v/\fP\fIRE\fP\fB/\fP\fIcommand list\fP +.fi +.RE +.sp +.LP +This command shall be equivalent to the global command \fBg\fP except +that the lines that are marked during the first step +shall be those for which the line excluding the terminating +does not match the RE. +.SS Interactive Global Not-Matched Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(1,$)V/\fP\fIRE\fP\fB/ +\fP +.fi +.RE +.sp +.LP +This command shall be equivalent to the interactive global command +\fBG\fP except that the lines that are marked during the +first step shall be those for which the line excluding the terminating + does not match the RE. +.SS Write Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(1,$)w\fP \fB[\fP\fIfile\fP\fB] +\fP +.fi +.RE +.sp +.LP +The \fBw\fP command shall write the addressed lines into the file +named by the pathname \fIfile\fP. The command shall create +the file, if it does not exist, or shall replace the contents of the +existing file. The currently remembered pathname shall not be +changed unless there is no remembered pathname. If no pathname is +given, the currently remembered pathname, if any, shall be used +(see the \fBe\fP and \fBf\fP commands); the current line number shall +be unchanged. If the command is successful, the number of +bytes written shall be written to standard output, unless the \fB-s\fP +option was specified, in the following format: +.sp +.RS +.nf + +\fB"%d\\n", <\fP\fInumber of bytes written\fP\fB> +\fP +.fi +.RE +.LP +If \fIfile\fP begins with \fB'!'\fP , the rest of the line shall be +taken to be a shell command line whose standard input +shall be the addressed lines. Such a shell command line shall not +be remembered as the current pathname. This usage of the write +command with \fB'!'\fP shall not be considered as a "last \fBw\fP +command that wrote the entire buffer", as described +previously; thus, this alone shall not prevent the warning to the +user if an attempt is made to destroy the editor buffer via the +\fBe\fP or \fBq\fP commands. +.SS Line Number Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB($)= +\fP +.fi +.RE +.sp +.LP +The line number of the addressed line shall be written to standard +output in the following format: +.sp +.RS +.nf + +\fB"%d\\n", <\fP\fIline number\fP\fB> +\fP +.fi +.RE +.LP +The current line number shall be unchanged by this command. +.SS Shell Escape Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB!\fP\fIcommand\fP +.fi +.RE +.sp +.LP +The remainder of the line after the \fB'!'\fP shall be sent to the +command interpreter to be interpreted as a shell command +line. Within the text of that shell command line, the unescaped character +\fB'%'\fP shall be replaced with the remembered +pathname; if a \fB'!'\fP appears as the first character of the command, +it shall be replaced with the text of the previous shell +command executed via \fB'!'\fP . Thus, \fB"!!"\fP shall repeat the +previous !\fIcommand\fP. If any replacements of +\fB'%'\fP or \fB'!'\fP are performed, the modified line shall be written +to the standard output before \fIcommand\fP is +executed. The \fB!\fP command shall write: +.sp +.RS +.nf + +\fB"!\\n" +\fP +.fi +.RE +.LP +to standard output upon completion, unless the \fB-s\fP option is +specified. The current line number shall be unchanged. +.SS Null Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB(.+1) +\fP +.fi +.RE +.sp +.LP +An address alone on a line shall cause the addressed line to be written. +A alone shall be equivalent to +\fB"+1p"\fP . The current line number shall be set to the address +of the written line. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion without any file or command errors. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +When an error in the input script is encountered, or when an error +is detected that is a consequence of the data (not) present +in the file or due to an external condition such as a read or write +error: +.IP " *" 3 +If the standard input is a terminal device file, all input shall be +flushed, and a new command read. +.LP +.IP " *" 3 +If the standard input is a regular file, \fIed\fP shall terminate +with a non-zero exit status. +.LP +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Because of the extremely terse nature of the default error messages, +the prudent script writer begins the \fIed\fP input +commands with an \fBH\fP command, so that if any errors do occur at +least some clue as to the cause is made available. +.LP +In previous versions, an obsolescent \fB-\fP option was described. +This is no longer specified. Applications should use the +\fB-s\fP option. Using \fB-\fP as a \fIfile\fP operand now produces +unspecified results. This allows implementations to continue +to support the former required behavior. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The initial description of this utility was adapted from the SVID. +It contains some features not found in Version 7 or +BSD-derived systems. Some of the differences between the POSIX and +BSD \fIed\fP utilities include, but need not be limited to: +.IP " *" 3 +The BSD \fB-\fP option does not suppress the \fB'!'\fP prompt after +a \fB!\fP command. +.LP +.IP " *" 3 +BSD does not support the special meanings of the \fB'%'\fP and \fB'!'\fP +characters within a \fB!\fP command. +.LP +.IP " *" 3 +BSD does not support the \fIaddresses\fP \fB';'\fP and \fB','\fP . +.LP +.IP " *" 3 +BSD allows the command/suffix pairs \fBpp\fP, \fBll\fP, and so on, +which are unspecified in this volume of +IEEE\ Std\ 1003.1-2001. +.LP +.IP " *" 3 +BSD does not support the \fB'!'\fP character part of the \fBe\fP, +\fBr\fP, or \fBw\fP commands. +.LP +.IP " *" 3 +A failed \fBg\fP command in BSD sets the line number to the last line +searched if there are no matches. +.LP +.IP " *" 3 +BSD does not default the \fIcommand list\fP to the \fBp\fP command. +.LP +.IP " *" 3 +BSD does not support the \fBG\fP, \fBh\fP, \fBH\fP, \fBn\fP, or \fBV\fP +commands. +.LP +.IP " *" 3 +On BSD, if there is no inserted text, the insert command changes the +current line to the referenced line -1; that is, the line +before the specified line. +.LP +.IP " *" 3 +On BSD, the \fIjoin\fP command with only a single address changes +the current line to that +address. +.LP +.IP " *" 3 +BSD does not support the \fBP\fP command; moreover, in BSD it is synonymous +with the \fBp\fP command. +.LP +.IP " *" 3 +BSD does not support the \fIundo\fP of the commands \fBj\fP, \fBm\fP, +\fBr\fP, \fBs\fP, or \fBt\fP. +.LP +.IP " *" 3 +The Version 7 \fIed\fP command \fBW\fP, and the BSD \fIed\fP commands +\fBW\fP, \fBwq\fP, and \fBz\fP are not present in +this volume of IEEE\ Std\ 1003.1-2001. +.LP +.LP +The \fB-s\fP option was added to allow the functionality of the now +withdrawn \fB-\fP option in a manner compatible with the +Utility Syntax Guidelines. +.LP +In early proposals there was a limit, {ED_FILE_MAX}, that described +the historical limitations of some \fIed\fP utilities in +their handling of large files; some of these have had problems with +files larger than 100000 bytes. It was this limitation that +prompted much of the desire to include a \fIsplit\fP command in this +volume of +IEEE\ Std\ 1003.1-2001. Since this limit was removed, this volume +of IEEE\ Std\ 1003.1-2001 requires that +implementations document the file size limits imposed by \fIed\fP +in the conformance document. The limit {ED_LINE_MAX} was also +removed; therefore, the global limit {LINE_MAX} is used for input +and output lines. +.LP +The manner in which the \fBl\fP command writes non-printable characters +was changed to avoid the historical +backspace-overstrike method. On video display terminals, the overstrike +is ambiguous because most terminals simply replace +overstruck characters, making the \fBl\fP format not useful for its +intended purpose of unambiguously understanding the content of +the line. The historical backslash escapes were also ambiguous. (The +string \fB"a\\0011"\fP could represent a line containing +those six characters or a line containing the three characters \fB'a'\fP +, a byte with a binary value of 1, and a 1.) In the +format required here, a backslash appearing in the line is written +as \fB"\\\\"\fP so that the output is truly unambiguous. The +method of marking the ends of lines was adopted from the \fIex\fP +editor and is required for +any line ending in s; the \fB'$'\fP is placed on all lines +so that a real \fB'$'\fP at the end of a line cannot +be misinterpreted. +.LP +Systems with bytes too large to fit into three octal digits must devise +other means of displaying non-printable characters. +Consideration was given to requiring that the number of octal digits +be large enough to hold a byte, but this seemed to be too +confusing for applications on the vast majority of systems where three +digits are adequate. It would be theoretically possible for +the application to use the \fIgetconf\fP utility to find out the CHAR_BIT +value and deal +with such an algorithm; however, there is really no portable way that +an application can use the octal values of the bytes across +various coded character sets, so the additional specification was +not worthwhile. +.LP +The description of how a NUL is written was removed. The NUL character +cannot be in text files, and this volume of +IEEE\ Std\ 1003.1-2001 should not dictate behavior in the case of +undefined, erroneous input. +.LP +Unlike some of the other editing utilities, the filenames accepted +by the \fBE\fP, \fBe\fP, \fBR\fP, and \fBr\fP commands +are not patterns. +.LP +Early proposals stated that the \fB-p\fP option worked only when standard +input was associated with a terminal device. This has +been changed to conform to historical implementations, thereby allowing +applications to interpose themselves between a user and the +\fIed\fP utility. +.LP +The form of the substitute command that uses the \fBn\fP suffix was +limited in some historical documentation (where this was +described incorrectly as "backreferencing"). This limit has been omitted +because there is no reason why an editor processing +lines of {LINE_MAX} length should have this restriction. The command +\fBs/x/X/2047\fP should be able to substitute the 2047th +occurrence of \fB'x'\fP on a line. +.LP +The use of printing commands with printing suffixes (such as \fBpn\fP, +\fBlp\fP, and so on) was made unspecified because +BSD-based systems allow this, whereas System V does not. +.LP +Some BSD-based systems exit immediately upon receipt of end-of-file +if all of the lines in the file have been deleted. Since +this volume of IEEE\ Std\ 1003.1-2001 refers to the \fBq\fP command +in this instance, such behavior is not allowed. +.LP +Some historical implementations returned exit status zero even if +command errors had occurred; this is not allowed by this +volume of IEEE\ Std\ 1003.1-2001. +.LP +Some historical implementations contained a bug that allowed a single +period to be entered in input mode as + . This is not allowed by \fIed\fP because there +is no description of escaping any of the characters +in input mode; backslashes are entered into the buffer exactly as +typed. The typical method of entering a single period has been to +precede it with another character and then use the substitute command +to delete that character. +.LP +It is difficult under some modes of some versions of historical operating +system terminal drivers to distinguish between an +end-of-file condition and terminal disconnect. IEEE\ Std\ 1003.1-2001 +does not require implementations to distinguish +between the two situations, which permits historical implementations +of the \fIed\fP utility on historical platforms to conform. +Implementations are encouraged to distinguish between the two, if +possible, and take appropriate action on terminal disconnect. +.LP +Historically, \fIed\fP accepted a zero address for the \fBa\fP and +\fBr\fP commands in order to insert text at the start of +the edit buffer. When the buffer was empty the command \fB.=\fP returned +zero. IEEE\ Std\ 1003.1-2001 requires conformance +to historical practice. +.LP +For consistency with the \fBa\fP and \fBr\fP commands and better user +functionality, the \fBi\fP and \fBc\fP commands must +also accept an address of 0, in which case 0\fIi\fP is treated as +1\fIi\fP and likewise for the \fBc\fP command. +.LP +All of the following are valid addresses: +.TP 7 +\fB+++\fP +Three lines after the current line. +.TP 7 +\fB/\fP\fIpattern\fP\fB/-\fP +One line before the next occurrence of pattern. +.TP 7 +\fB-2\fP +Two lines before the current line. +.TP 7 +\fB3\ ----\ 2\fP +Line one (note the intermediate negative address). +.TP 7 +\fB1\ 2\ 3\fP +Line six. +.sp +.LP +Any number of addresses can be provided to commands taking addresses; +for example, \fB"1,2,3,4,5p"\fP prints lines 4 and 5, +because two is the greatest valid number of addresses accepted by +the \fBprint\fP command. This, in combination with the semicolon +delimiter, permits users to create commands based on ordered patterns +in the file. For example, the command \fB"3;/foo/;+2p"\fP +will display the first line after line 3 that contains the pattern +\fIfoo\fP, plus the next two lines. Note that the address +\fB"3;"\fP must still be evaluated before being discarded, because +the search origin for the \fB"/foo/"\fP command depends on +this. +.LP +Historically, \fIed\fP disallowed address chains, as discussed above, +consisting solely of comma or semicolon separators; for +example, \fB",,,"\fP or \fB";;;"\fP were considered an error. For +consistency of address specification, this restriction is +removed. The following table lists some of the address forms now possible: +.TS C +center; l2 l2 l2 l2 l. +\fBAddress\fP \fBAddr1\fP \fBAddr2\fP \fBStatus\fP \fBComment\fP +7, 7 7 Historical \ +7,5, 5 5 Historical \ +7,5,9 5 9 Historical \ +7,9 7 9 Historical \ +7,+ 7 8 Historical \ +, 1 $ Historical \ +,7 1 7 Extension \ +,, $ $ Extension \ +,; $ $ Extension \ +7; 7 7 Historical \ +7;5; 5 5 Historical \ +7;5;9 5 9 Historical \ +7;5,9 5 9 Historical \ +7;$;4 $ 4 Historical Valid, but erroneous. +7;9 7 9 Historical \ +7;+ 7 8 Historical \ +; . $ Historical \ +;7 . 7 Extension \ +;; $ $ Extension \ +;, $ $ Extension \ +.TE +.LP +Historically, values could be added to addresses by including them +after one or more s; for example, +\fB"3\ -\ 5p"\fP wrote the seventh line of the file, and \fB"/foo/\ 5"\fP +was the same as \fB"5\ /foo/"\fP +\&. However, only absolute values could be added; for example, \fB"5\ /foo/"\fP +was an error. IEEE\ Std\ 1003.1-2001 +requires conformance to historical practice. +.LP +Historically, \fIed\fP accepted the \fB'^'\fP character as an address, +in which case it was identical to the hyphen +character. IEEE\ Std\ 1003.1-2001 does not require or prohibit this +behavior. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIUtility Description Defaults\fP , \fIex\fP , \fIsed\fP , \fIsh\fP +, \fIvi\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/env.1p b/man1p/env.1p new file mode 100644 index 000000000..96a833213 --- /dev/null +++ b/man1p/env.1p @@ -0,0 +1,233 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ENV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" env +.SH NAME +env \- set the environment for command invocation +.SH SYNOPSIS +.LP +\fBenv\fP \fB[\fP\fB-i\fP\fB][\fP\fIname\fP\fB=\fP\fIvalue\fP\fB]\fP\fB...\fP +\fB[\fP\fIutility\fP +\fB[\fP\fIargument\fP\fB...\fP\fB]]\fP +.SH DESCRIPTION +.LP +The \fIenv\fP utility shall obtain the current environment, modify +it according to its arguments, then invoke the utility named +by the \fIutility\fP operand with the modified environment. +.LP +Optional arguments shall be passed to \fIutility\fP. +.LP +If no \fIutility\fP operand is specified, the resulting environment +shall be written to the standard output, with one +\fIname\fP= \fIvalue\fP pair per line. +.SH OPTIONS +.LP +The \fIenv\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-i\fP +Invoke \fIutility\fP with exactly the environment specified by the +arguments; the inherited environment shall be ignored +completely. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIname\fP=\fIvalue\fP +Arguments of the form \fIname\fP= \fIvalue\fP shall modify the execution +environment, and shall be placed into the inherited +environment before the \fIutility\fP is invoked. +.TP 7 +\fIutility\fP +The name of the utility to be invoked. If the \fIutility\fP operand +names any of the special built-in utilities in \fISpecial Built-In +Utilities\fP , the results are undefined. +.TP 7 +\fIargument\fP +A string to pass as an argument for the invoked utility. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIenv\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPATH\fP +Determine the location of the \fIutility\fP, as described in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment +Variables. If \fIPATH\fP is specified as a \fIname\fP= \fIvalue\fP +operand to \fIenv\fP, the \fIvalue\fP given shall be used in the search +for \fIutility\fP. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If no \fIutility\fP operand is specified, each \fIname\fP= \fIvalue\fP +pair in the resulting environment shall be written in +the form: +.sp +.RS +.nf + +\fB"%s=%s\\n", <\fP\fIname\fP\fB>, <\fP\fIvalue\fP\fB> +\fP +.fi +.RE +.LP +If the \fIutility\fP operand is specified, the \fIenv\fP utility shall +not write to standard output. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +If \fIutility\fP is invoked, the exit status of \fIenv\fP shall be +the exit status of \fIutility\fP; otherwise, the +\fIenv\fP utility shall exit with one of the following values: +.TP 7 +\ \ \ \ 0 +The \fIenv\fP utility completed successfully. +.TP 7 +1-125 +An error occurred in the \fIenv\fP utility. +.TP 7 +\ \ 126 +The utility specified by \fIutility\fP was found but could not be +invoked. +.TP 7 +\ \ 127 +The utility specified by \fIutility\fP could not be found. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fIcommand\fP, \fIenv\fP, \fInice\fP, \fInohup\fP, \fItime\fP, +and \fIxargs\fP utilities have been specified to use exit code 127 +if an error occurs so that +applications can distinguish "failure to find a utility" from "invoked +utility exited with an error indication". The value 127 +was chosen because it is not commonly used for other meanings; most +utilities use small values for "normal error conditions" and +the values above 128 can be confused with termination due to receipt +of a signal. The value 126 was chosen in a similar manner to +indicate that the utility could be found, but not invoked. Some scripts +produce meaningful error messages differentiating the 126 +and 127 cases. The distinction between exit codes 126 and 127 is based +on KornShell practice that uses 127 when all attempts to +\fIexec\fP the utility fail with [ENOENT], and uses 126 when any attempt +to \fIexec\fP the utility fails for any other +reason. +.LP +Historical implementations of the \fIenv\fP utility use the \fIexecvp\fP() +or \fIexeclp\fP() functions defined in the System Interfaces volume +of IEEE\ Std\ 1003.1-2001 +to invoke the specified utility; this provides better performance +and keeps users from having to escape characters with special +meaning to the shell. Therefore, shell functions, special built-ins, +and built-ins that are only provided by the shell are not +found. +.SH EXAMPLES +.LP +The following command: +.sp +.RS +.nf + +\fBenv -i PATH=/mybin mygrep xyz myfile +\fP +.fi +.RE +.LP +invokes the command \fImygrep\fP with a new \fIPATH\fP value as the +only entry in its environment. In this case, \fIPATH\fP +is used to locate \fImygrep\fP, which then must reside in \fB/mybin\fP. +.SH RATIONALE +.LP +As with all other utilities that invoke other utilities, this volume +of IEEE\ Std\ 1003.1-2001 only specifies what +\fIenv\fP does with standard input, standard output, standard error, +input files, and output files. If a utility is executed, it +is not constrained by the specification of input and output by \fIenv\fP. +.LP +The \fB-i\fP option was added to allow the functionality of the withdrawn +\fB-\fP option in a manner compatible with the +Utility Syntax Guidelines. +.LP +Some have suggested that \fIenv\fP is redundant since the same effect +is achieved by: +.sp +.RS +.nf + +\fBname=value ... utility\fP \fB[\fP \fBargument ...\fP \fB]\fP +.fi +.RE +.LP +The example is equivalent to \fIenv\fP when an environment variable +is being added to the environment of the command, but not +when the environment is being set to the given value. The \fIenv\fP +utility also writes out the current environment if invoked +without arguments. There is sufficient functionality beyond what the +example provides to justify inclusion of \fIenv\fP. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIParameters and Variables\fP , \fISpecial +Built-In Utilities\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/eval.1p b/man1p/eval.1p new file mode 100644 index 000000000..c38b1b985 --- /dev/null +++ b/man1p/eval.1p @@ -0,0 +1,90 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "EVAL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" eval +.SH NAME +eval \- construct command by concatenating arguments +.SH SYNOPSIS +.LP +\fBeval\fP \fB[\fP\fIargument\fP \fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIeval\fP utility shall construct a command by concatenating +\fIargument\fPs together, separating each with a +. The constructed command shall be read and executed by the +shell. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +See the DESCRIPTION. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +None. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +If there are no \fIargument\fPs, or only null arguments, \fIeval\fP +shall return a zero exit status; otherwise, it shall +return the exit status of the command defined by the string of concatenated +\fIargument\fPs separated by s. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.sp +.RS +.nf + +\fBfoo=10 x=foo +y='$'$x +echo $y +\fP\fB$foo\fP\fBeval y='$'$x +echo $y +\fP\fB10\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISpecial Built-In Utilities\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/ex.1p b/man1p/ex.1p new file mode 100644 index 000000000..9c29dc3f9 --- /dev/null +++ b/man1p/ex.1p @@ -0,0 +1,6056 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "EX" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ex +.SH NAME +ex \- text editor +.SH SYNOPSIS +.LP +\fBex\fP \fB[\fP\fB-rR\fP\fB][\fP\fB-s | -v\fP\fB][\fP\fB-c\fP +\fIcommand\fP\fB][\fP\fB-t\fP \fItagstring\fP\fB][\fP\fB-w\fP \fIsize\fP\fB][\fP\fIfile\fP +\fB\&...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIex\fP utility is a line-oriented text editor. There are two +other modes of the editor-open and visual-in which +screen-oriented editing is available. This is described more fully +by the \fIex\fP \fBopen\fP and \fBvisual\fP commands and in +\fIvi\fP . +.LP +This section uses the term \fIedit buffer\fP to describe the current +working text. No specific implementation is implied by +this term. All editing changes are performed on the edit buffer, and +no changes to it shall affect any file until an editor command +writes the file. +.LP +Certain terminals do not have all the capabilities necessary to support +the complete \fIex\fP definition, such as the +full-screen editing commands ( \fIvisual mode\fP or \fIopen mode\fP). +When these commands cannot be supported on such terminals, +this condition shall not produce an error message such as "not an +editor command" or report a syntax error. The implementation +may either accept the commands and produce results on the screen that +are the result of an unsuccessful attempt to meet the +requirements of this volume of IEEE\ Std\ 1003.1-2001 or report an +error describing the terminal-related deficiency. +.SH OPTIONS +.LP +The \fIex\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-c\ \fP \fIcommand\fP +Specify an initial command to be executed in the first edit buffer +loaded from an existing file (see the EXTENDED DESCRIPTION +section). Implementations may support more than a single \fB-c\fP +option. In such implementations, the specified commands shall be +executed in the order specified on the command line. +.TP 7 +\fB-r\fP +Recover the named files (see the EXTENDED DESCRIPTION section). Recovery +information for a file shall be saved during an editor +or system crash (for example, when the editor is terminated by a signal +which the editor can catch), or after the use of an +\fIex\fP \fBpreserve\fP command. +.LP +A \fIcrash\fP in this context is an unexpected failure of the system +or utility that requires restarting the failed system or +utility. A system crash implies that any utilities running at the +time also crash. In the case of an editor or system crash, the +number of changes to the edit buffer (since the most recent \fBpreserve\fP +command) that will be recovered is unspecified. +.LP +If no \fIfile\fP operands are given and the \fB-t\fP option is not +specified, all other options, the \fIEXINIT\fP variable, +and any \fB.exrc\fP files shall be ignored; a list of all recoverable +files available to the invoking user shall be written, and +the editor shall exit normally without further action. +.TP 7 +\fB-R\fP +Set \fBreadonly\fP edit option. +.TP 7 +\fB-s\fP +Prepare \fIex\fP for batch use by taking the following actions: +.RS +.IP " *" 3 +Suppress writing prompts and informational (but not diagnostic) messages. +.LP +.IP " *" 3 +Ignore the value of \fITERM\fP and any implementation default terminal +type and assume the terminal is a type incapable of +supporting open or visual modes; see the \fBvisual\fP command and +the description of \fIvi\fP . +.LP +.IP " *" 3 +Suppress the use of the \fIEXINIT\fP environment variable and the +reading of any \fB.exrc\fP file; see the EXTENDED +DESCRIPTION section. +.LP +.IP " *" 3 +Suppress autoindentation, ignoring the value of the \fBautoindent\fP +edit option. +.LP +.RE +.TP 7 +\fB-t\ \fP \fItagstring\fP +Edit the file containing the specified \fItagstring\fP; see \fIctags\fP +\&. The tags feature +represented by \fB-t\fP \fItagstring\fP and the \fBtag\fP command +is optional. It shall be provided on any system that also +provides a conforming implementation of \fIctags\fP; otherwise, the +use of \fB-t\fP +produces undefined results. On any system, it shall be an error to +specify more than a single \fB-t\fP option. +.TP 7 +\fB-v\fP +Begin in visual mode (see \fIvi\fP ). +.TP 7 +\fB-w\ \fP \fIsize\fP +Set the value of the \fIwindow\fP editor option to \fIsize\fP. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a file to be edited. +.sp +.SH STDIN +.LP +The standard input consists of a series of commands and input text, +as described in the EXTENDED DESCRIPTION section. The +implementation may limit each line of standard input to a length of +{LINE_MAX}. +.LP +If the standard input is not a terminal device, it shall be as if +the \fB-s\fP option had been specified. +.LP +If a read from the standard input returns an error, or if the editor +detects an end-of-file condition from the standard input, +it shall be equivalent to a SIGHUP asynchronous event. +.SH INPUT FILES +.LP +Input files shall be text files or files that would be text files +except for an incomplete last line that is not longer than +{LINE_MAX}-1 bytes in length and contains no NUL characters. By default, +any incomplete last line shall be treated as if it had a +trailing . The editing of other forms of files may optionally +be allowed by \fIex\fP implementations. +.LP +The \fB.exrc\fP files and source files shall be text files consisting +of \fIex\fP commands; see the EXTENDED DESCRIPTION +section. +.LP +By default, the editor shall read lines from the files to be edited +without interpreting any of those lines as any form of +editor command. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIex\fP: +.TP 7 +\fICOLUMNS\fP +Override the system-selected horizontal screen size. See the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment +Variables for valid values and results when it is unset or null. +.TP 7 +\fIEXINIT\fP +Determine a list of \fIex\fP commands that are executed on editor +start-up. See the EXTENDED DESCRIPTION section for more +details of the initialization phase. +.TP 7 +\fIHOME\fP +Determine a pathname of a directory that shall be searched for an +editor start-up file named \fB.exrc\fP; see the EXTENDED +DESCRIPTION section. +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular +expressions. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), the +behavior of character classes within regular expressions, the +classification of characters as uppercase or lowercase letters, the +case conversion of letters, and the detection of word +boundaries. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILINES\fP +Override the system-selected vertical screen size, used as the number +of lines in a screenful and the vertical screen size in +visual mode. See the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 8, +Environment Variables for valid values and results when it is unset +or null. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPATH\fP +Determine the search path for the shell command specified in the \fIex\fP +editor commands \fB!\fP, \fBshell\fP, \fBread\fP, +and \fBwrite\fP, and the open and visual mode command \fB!\fP; see +the description of command search and execution in \fICommand Search +and Execution\fP . +.TP 7 +\fISHELL\fP +Determine the preferred command line interpreter for use as the default +value of the \fBshell\fP edit option. +.TP 7 +\fITERM\fP +Determine the name of the terminal type. If this variable is unset +or null, an unspecified default terminal type shall be +used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +The following term is used in this and following sections to specify +command and asynchronous event actions: +.TP 7 +\fIcomplete\ write\fP +.sp +A complete write is a write of the entire contents of the edit buffer +to a file of a type other than a terminal device, or the +saving of the edit buffer caused by the user executing the \fIex\fP +\fBpreserve\fP command. Writing the contents of the edit +buffer to a temporary file that will be removed when the editor exits +shall not be considered a complete write. +.sp +.LP +The following actions shall be taken upon receipt of signals: +.TP 7 +SIGINT +If the standard input is not a terminal device, \fIex\fP shall not +write the file or return to command or text input mode, and +shall exit with a non-zero exit status. +.LP +Otherwise, if executing an open or visual text input mode command, +\fIex\fP in receipt of SIGINT shall behave identically to +its receipt of the character. +.LP +Otherwise: +.RS +.IP " 1." 4 +If executing an \fIex\fP text input mode command, all input lines +that have been completely entered shall be resolved into the +edit buffer, and any partially entered line shall be discarded. +.LP +.IP " 2." 4 +If there is a currently executing command, it shall be aborted and +a message displayed. Unless otherwise specified by the +\fIex\fP or \fIvi\fP command descriptions, it is unspecified whether +any lines modified by the +executing command appear modified, or as they were before being modified +by the executing command, in the buffer. +.LP +If the currently executing command was a motion command, its associated +command shall be discarded. +.LP +.IP " 3." 4 +If in open or visual command mode, the terminal shall be alerted. +.LP +.IP " 4." 4 +The editor shall then return to command mode. +.LP +.RE +.TP 7 +SIGCONT +The screen shall be refreshed if in open or visual mode. +.TP 7 +SIGHUP +If the edit buffer has been modified since the last complete write, +\fIex\fP shall attempt to save the edit buffer so that it +can be recovered later using the \fB-r\fP option or the \fIex\fP \fBrecover\fP +command. The editor shall not write the file or +return to command or text input mode, and shall terminate with a non-zero +exit status. +.TP 7 +SIGTERM +Refer to SIGHUP. +.sp +.LP +The action taken for all other signals is unspecified. +.SH STDOUT +.LP +The standard output shall be used only for writing prompts to the +user, for informational messages, and for writing lines from +the file. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +The output from \fIex\fP shall be text files. +.SH EXTENDED DESCRIPTION +.LP +Only the \fIex\fP mode of the editor is described in this section. +See \fIvi\fP for additional editing +capabilities available in \fIex\fP. +.LP +When an error occurs, \fIex\fP shall write a message. If the terminal +supports a standout mode (such as inverse video), the +message shall be written in standout mode. If the terminal does not +support a standout mode, and the edit option \fBerrorbells\fP +is set, an alert action shall precede the error message. +.LP +By default, \fIex\fP shall start in command mode, which shall be indicated +by a \fB:\fP prompt; see the \fBprompt\fP command. +Text input mode can be entered by the \fBappend\fP, \fBinsert\fP, +or \fBchange\fP commands; it can be exited (and command mode +re-entered) by typing a period ( \fB'.'\fP ) alone at the beginning +of a line. +.SS Initialization in ex and vi +.LP +The following symbols are used in this and following sections to specify +locations in the edit buffer: +.TP 7 +\fIalternate\ and\ current\ pathnames\fP +.sp +Two pathnames, named \fIcurrent\fP and \fIalternate\fP, are maintained +by the editor. Any \fIex\fP commands that take filenames +as arguments shall set them as follows: +.RS +.IP " 1." 4 +If a \fIfile\fP argument is specified to the \fIex\fP \fBedit\fP, +\fBex\fP, or \fBrecover\fP commands, or if an \fIex\fP +\fBtag\fP command replaces the contents of the edit buffer. +.RS +.IP " a." 4 +If the command replaces the contents of the edit buffer, the current +pathname shall be set to the \fIfile\fP argument or the +file indicated by the tag, and the alternate pathname shall be set +to the previous value of the current pathname. +.LP +.IP " b." 4 +Otherwise, the alternate pathname shall be set to the \fIfile\fP argument. +.LP +.RE +.LP +.IP " 2." 4 +If a \fIfile\fP argument is specified to the \fIex\fP \fBnext\fP command: +.RS +.IP " a." 4 +If the command replaces the contents of the edit buffer, the current +pathname shall be set to the first \fIfile\fP argument, +and the alternate pathname shall be set to the previous value of the +current pathname. +.LP +.RE +.LP +.IP " 3." 4 +If a \fIfile\fP argument is specified to the \fIex\fP \fBfile\fP command, +the current pathname shall be set to the +\fIfile\fP argument, and the alternate pathname shall be set to the +previous value of the current pathname. +.LP +.IP " 4." 4 +If a \fIfile\fP argument is specified to the \fIex\fP \fBread\fP and +\fBwrite\fP commands (that is, when reading or writing +a file, and not to the program named by the \fBshell\fP edit option), +or a \fIfile\fP argument is specified to the \fIex\fP +\fBxit\fP command: +.RS +.IP " a." 4 +If the current pathname has no value, the current pathname shall be +set to the \fIfile\fP argument. +.LP +.IP " b." 4 +Otherwise, the alternate pathname shall be set to the \fIfile\fP argument. +.LP +.RE +.LP +.RE +.LP +If the alternate pathname is set to the previous value of the current +pathname when the current pathname had no previous value, +then the alternate pathname shall have no value as a result. +.TP 7 +\fIcurrent\ line\fP +.sp +The line of the edit buffer referenced by the cursor. Each command +description specifies the current line after the command has +been executed, as the \fIcurrent line value\fP. When the edit buffer +contains no lines, the current line shall be zero; see Addressing +in ex . +.TP 7 +\fIcurrent\ column\fP +.sp +The current display line column occupied by the cursor. (The columns +shall be numbered beginning at 1.) Each command description +specifies the current column after the command has been executed, +as the \fIcurrent column\fP value. This column is an +\fIideal\fP column that is remembered over the lifetime of the editor. +The actual display line column upon which the cursor rests +may be different from the current column; see the cursor positioning +discussion in \fICommand +Descriptions in vi\fP . +.TP 7 +\fIset\ to\ non-\fP +.sp +A description for a current column value, meaning that the current +column shall be set to the last display line column on which is +displayed any part of the first non- of the line. If the line +has no non- non- s, the +current column shall be set to the last display line column on which +is displayed any part of the last non- in the +line. If the line is empty, the current column shall be set to column +position 1. +.sp +.LP +The length of lines in the edit buffer may be limited to {LINE_MAX} +bytes. In open and visual mode, the length of lines in the +edit buffer may be limited to the number of characters that will fit +in the display. If either limit is exceeded during editing, an +error message shall be written. If either limit is exceeded by a line +read in from a file, an error message shall be written and +the edit session may be terminated. +.LP +If the editor stops running due to any reason other than a user command, +and the edit buffer has been modified since the last +complete write, it shall be equivalent to a SIGHUP asynchronous event. +If the system crashes, it shall be equivalent to a SIGHUP +asynchronous event. +.LP +During initialization (before the first file is copied into the edit +buffer or any user commands from the terminal are +processed) the following shall occur: +.IP " 1." 4 +If the environment variable \fIEXINIT\fP is set, the editor shall +execute the \fIex\fP commands contained in that +variable. +.LP +.IP " 2." 4 +If the \fIEXINIT\fP variable is not set, and all of the following +are true: +.RS +.IP " a." 4 +The \fIHOME\fP environment variable is not null and not empty. +.LP +.IP " b." 4 +The file \fB.exrc\fP in the directory referred to by the \fIHOME\fP +environment variable: +.RS +.IP " 1." 4 +Exists +.LP +.IP " 2." 4 +Is owned by the same user ID as the real user ID of the process or +the process has appropriate privileges +.LP +.IP " 3." 4 +Is not writable by anyone other than the owner +.LP +.RE +.LP +.RE +.LP +the editor shall execute the \fIex\fP commands contained in that file. +.LP +.IP " 3." 4 +If and only if all of the following are true: +.RS +.IP " a." 4 +The current directory is not referred to by the \fIHOME\fP environment +variable. +.LP +.IP " b." 4 +A command in the \fIEXINIT\fP environment variable or a command in +the \fB.exrc\fP file in the directory referred to by the +\fIHOME\fP environment variable sets the editor option \fBexrc\fP. +.LP +.IP " c." 4 +The \fB.exrc\fP file in the current directory: +.RS +.IP " 1." 4 +Exists +.LP +.IP " 2." 4 +Is owned by the same user ID as the real user ID of the process, or +by one of a set of implementation-defined user IDs +.LP +.IP " 3." 4 +Is not writable by anyone other than the owner +.LP +.RE +.LP +.RE +.LP +the editor shall attempt to execute the \fIex\fP commands contained +in that file. +.LP +.LP +Lines in any \fB.exrc\fP file that are blank lines shall be ignored. +If any \fB.exrc\fP file exists, but is not read for +ownership or permission reasons, it shall be an error. +.LP +After the \fIEXINIT\fP variable and any \fB.exrc\fP files are processed, +the first file specified by the user shall be edited, +as follows: +.IP " 1." 4 +If the user specified the \fB-t\fP option, the effect shall be as +if the \fIex\fP \fBtag\fP command was entered with the +specified argument, with the exception that if tag processing does +not result in a file to edit, the effect shall be as described +in step 3. below. +.LP +.IP " 2." 4 +Otherwise, if the user specified any command line \fIfile\fP arguments, +the effect shall be as if the \fIex\fP \fBedit\fP +command was entered with the first of those arguments as its \fIfile\fP +argument. +.LP +.IP " 3." 4 +Otherwise, the effect shall be as if the \fIex\fP \fBedit\fP command +was entered with a nonexistent filename as its +\fIfile\fP argument. It is unspecified whether this action shall set +the current pathname. In an implementation where this action +does not set the current pathname, any editor command using the current +pathname shall fail until an editor command sets the +current pathname. +.LP +.LP +If the \fB-r\fP option was specified, the first time a file in the +initial argument list or a file specified by the \fB-t\fP +option is edited, if recovery information has previously been saved +about it, that information shall be recovered and the editor +shall behave as if the contents of the edit buffer have already been +modified. If there are multiple instances of the file to be +recovered, the one most recently saved shall be recovered, and an +informational message that there are previous versions of the +file that can be recovered shall be written. If no recovery information +about a file is available, an informational message to this +effect shall be written, and the edit shall proceed as usual. +.LP +If the \fB-c\fP option was specified, the first time a file that already +exists (including a file that might not exist but for +which recovery information is available, when the \fB-r\fP option +is specified) replaces or initializes the contents of the edit +buffer, the current line shall be set to the last line of the edit +buffer, the current column shall be set to non- , +and the \fIex\fP commands specified with the \fB-c\fP option shall +be executed. In this case, the current line and current column +shall not be set as described for the command associated with the +replacement or initialization of the edit buffer contents. +However, if the \fB-t\fP option or a \fBtag\fP command is associated +with this action, the \fB-c\fP option commands shall be +executed and then the movement to the tag shall be performed. +.LP +The current argument list shall initially be set to the filenames +specified by the user on the command line. If no filenames are +specified by the user, the current argument list shall be empty. If +the \fB-t\fP option was specified, it is unspecified whether +any filename resulting from tag processing shall be prepended to the +current argument list. In the case where the filename is added +as a prefix to the current argument list, the current argument list +reference shall be set to that filename. In the case where the +filename is not added as a prefix to the current argument list, the +current argument list reference shall logically be located +before the first of the filenames specified on the command line (for +example, a subsequent \fIex\fP \fBnext\fP command shall edit +the first filename from the command line). If the \fB-t\fP option +was not specified, the current argument list reference shall be +to the first of the filenames on the command line. +.SS Addressing in ex +.LP +Addressing in \fIex\fP relates to the current line and the current +column; the address of a line is its 1-based line number, +the address of a column is its 1-based count from the beginning of +the line. Generally, the current line is the last line affected +by a command. The current line number is the address of the current +line. In each command description, the effect of the command on +the current line number and the current column is described. +.LP +Addresses are constructed as follows: +.IP " 1." 4 +The character \fB'.'\fP (period) shall address the current line. +.LP +.IP " 2." 4 +The character \fB'$'\fP shall address the last line of the edit buffer. +.LP +.IP " 3." 4 +The positive decimal number \fIn\fP shall address the \fIn\fPth line +of the edit buffer. +.LP +.IP " 4." 4 +The address \fB"'x"\fP refers to the line marked with the mark name +character \fB'x'\fP , which shall be a lowercase +letter from the portable character set or one of the characters \fB'`'\fP +or \fB'"\fP . It shall be an error if the line +that was marked is not currently present in the edit buffer or the +mark has not been set. Lines can be marked with the \fIex\fP +\fBmark\fP or \fBk\fP commands, or the \fIvi\fP \fBm\fP command. +.LP +.IP " 5." 4 +A regular expression enclosed by slashes ( \fB'/'\fP ) shall address +the first line found by searching forwards from the line +following the current line toward the end of the edit buffer and stopping +at the first line for which the line excluding the +terminating matches the regular expression. As stated in +Regular Expressions in ex , +an address consisting of a null regular expression delimited by slashes +\fB"//"\fP shall address the next line for which the +line excluding the terminating matches the last regular +expression encountered. In addition, the second slash can +be omitted at the end of a command line. If the \fBwrapscan\fP edit +option is set, the search shall wrap around to the beginning +of the edit buffer and continue up to and including the current line, +so that the entire edit buffer is searched. Within the +regular expression, the sequence \fB"\\/"\fP shall represent a literal +slash instead of the regular expression delimiter. +.LP +.IP " 6." 4 +A regular expression enclosed in question marks ( \fB'?'\fP ) shall +address the first line found by searching backwards from +the line preceding the current line toward the beginning of the edit +buffer and stopping at the first line for which the line +excluding the terminating matches the regular expression. +An address consisting of a null regular expression +delimited by question marks \fB"??"\fP shall address the previous +line for which the line excluding the terminating + matches the last regular expression encountered. In addition, +the second question mark can be omitted at the end of +a command line. If the \fBwrapscan\fP edit option is set, the search +shall wrap around from the beginning of the edit buffer to +the end of the edit buffer and continue up to and including the current +line, so that the entire edit buffer is searched. Within +the regular expression, the sequence \fB"\\?"\fP shall represent a +literal question mark instead of the RE delimiter. +.LP +.IP " 7." 4 +A plus sign ( \fB'+'\fP ) or a minus sign ( \fB'-'\fP ) followed by +a decimal number shall address the current line plus +or minus the number. A \fB'+'\fP or \fB'-'\fP not followed by a decimal +number shall address the current line plus or minus +1. +.LP +.LP +Addresses can be followed by zero or more address offsets, optionally +-separated. Address offsets are constructed +as follows: +.IP " 1." 4 +A \fB'+'\fP or \fB'-'\fP immediately followed by a decimal number +shall add (subtract) the indicated number of lines to +(from) the address. A \fB'+'\fP or \fB'-'\fP not followed by a decimal +number shall add (subtract) 1 to (from) the +address. +.LP +.IP " 2." 4 +A decimal number shall add the indicated number of lines to the address. +.LP +.LP +It shall not be an error for an intermediate address value to be less +than zero or greater than the last line in the edit +buffer. It shall be an error for the final address value to be less +than zero or greater than the last line in the edit buffer. +.LP +Commands take zero, one, or two addresses; see the descriptions of +\fI1addr\fP and \fI2addr\fP in Command Descriptions in ex . If more +than the required number of addresses are provided to a command that +requires zero addresses, it shall be an error. Otherwise, if more +than the required number of addresses are provided to a command, +the addresses specified first shall be evaluated and then discarded +until the maximum number of valid addresses remain. +.LP +Addresses shall be separated from each other by a comma ( \fB','\fP +) or a semicolon ( \fB';'\fP ). If no address is +specified before or after a comma or semicolon separator, it shall +be as if the address of the current line was specified before or +after the separator. In the case of a semicolon separator, the current +line ( \fB'.'\fP ) shall be set to the first address, and +only then will the next address be calculated. This feature can be +used to determine the starting line for forwards and backwards +searches (see rules 5. and 6.). +.LP +A percent sign ( \fB'%'\fP ) shall be equivalent to entering the two +addresses \fB"1,$"\fP . +.LP +Any delimiting s between addresses, address separators, or +address offsets shall be discarded. +.SS Command Line Parsing in ex +.LP +The following symbol is used in this and following sections to describe +parsing behavior: +.TP 7 +\fIescape\fP +If a character is referred to as "backslash-escaped" or " -V-escaped," +it shall mean that the character +acquired or lost a special meaning by virtue of being preceded, respectively, +by a backslash or -V character. Unless +otherwise specified, the escaping character shall be discarded at +that time and shall not be further considered for any +purpose. +.sp +.LP +Command-line parsing shall be done in the following steps. For each +step, characters already evaluated shall be ignored; that +is, the phrase "leading character" refers to the next character that +has not yet been evaluated. +.IP " 1." 4 +Leading colon characters shall be skipped. +.LP +.IP " 2." 4 +Leading s shall be skipped. +.LP +.IP " 3." 4 +If the leading character is a double-quote character, the characters +up to and including the next non-backslash-escaped + shall be discarded, and any subsequent characters shall +be parsed as a separate command. +.LP +.IP " 4." 4 +Leading characters that can be interpreted as addresses shall be evaluated; +see Addressing in ex +\&. +.LP +.IP " 5." 4 +Leading s shall be skipped. +.LP +.IP " 6." 4 +If the next character is a vertical-line character or a : +.RS +.IP " a." 4 +If the next character is a : +.RS +.IP " 1." 4 +If \fIex\fP is in open or visual mode, the current line shall be set +to the last address specified, if any. +.LP +.IP " 2." 4 +Otherwise, if the last command was terminated by a vertical-line character, +no action shall be taken; for example, the command +\fB"||"\fP shall execute two implied commands, not three. +.LP +.IP " 3." 4 +Otherwise, step 6.b. shall apply. +.LP +.RE +.LP +.IP " b." 4 +Otherwise, the implied command shall be the \fBprint\fP command. The +last \fB#\fP, \fBp\fP, and \fBl\fP flags specified to +any \fIex\fP command shall be remembered and shall apply to this implied +command. Executing the \fIex\fP \fBnumber\fP, +\fBprint\fP, or \fBlist\fP command shall set the remembered flags +to \fB#\fP, nothing, and \fBl\fP, respectively, plus any +other flags specified for that execution of the \fBnumber\fP, \fBprint\fP, +or \fBlist\fP command. +.LP +If \fIex\fP is not currently performing a \fBglobal\fP or \fBv\fP +command, and no address or count is specified, the current +line shall be incremented by 1 before the command is executed. If +incrementing the current line would result in an address past the +last line in the edit buffer, the command shall fail, and the increment +shall not happen. +.LP +.IP " c." 4 +The or vertical-line character shall be discarded and any +subsequent characters shall be parsed as a separate +command. +.LP +.RE +.LP +.IP " 7." 4 +The command name shall be comprised of the next character (if the +character is not alphabetic), or the next character and any +subsequent alphabetic characters (if the character is alphabetic), +with the following exceptions: +.RS +.IP " a." 4 +Commands that consist of any prefix of the characters in the command +name \fBdelete\fP, followed immediately by any of the +characters \fB'l'\fP , \fB'p'\fP , \fB'+'\fP , \fB'-'\fP , or \fB'#'\fP +shall be interpreted as a \fBdelete\fP +command, followed by a , followed by the characters that were +not part of the prefix of the \fBdelete\fP command. The +maximum number of characters shall be matched to the command name +\fBdelete\fP; for example, \fB"del"\fP shall not be treated +as \fB"de"\fP followed by the flag \fBl\fP. +.LP +.IP " b." 4 +Commands that consist of the character \fB'k'\fP , followed by a character +that can be used as the name of a mark, shall be +equivalent to the mark command followed by a , followed by +the character that followed the \fB'k'\fP . +.LP +.IP " c." 4 +Commands that consist of the character \fB's'\fP , followed by characters +that could be interpreted as valid options to the +\fBs\fP command, shall be the equivalent of the \fBs\fP command, without +any pattern or replacement values, followed by a +, followed by the characters after the \fB's'\fP . +.LP +.RE +.LP +.IP " 8." 4 +The command name shall be matched against the possible command names, +and a command name that contains a prefix matching the +characters specified by the user shall be the executed command. In +the case of commands where the characters specified by the user +could be ambiguous, the executed command shall be as follows: +.TS C +center; l l l l l l l l. +\fBa\fP \fBappend\fP n \fBnext\fP \fBt\fP t \fB\ \fP \fB\ \fP +\fBc\fP \fBchange\fP p \fBprint\fP \fBu\fP undo \fB\ \fP \fB\ \fP +\fBch\fP \fBchange\fP pr \fBprint\fP \fBun\fP undo \fB\ \fP \fB\ \fP +\fBe\fP \fBedit\fP r \fBread\fP \fBv\fP v \fB\ \fP \fB\ \fP +\fBm\fP \fBmove\fP re \fBread\fP \fBw\fP write \fB\ \fP \fB\ \fP +\fBma\fP \fBmark\fP s \fBs\fP \fB\ \fP \ \fB\ \fP \fB\ \fP +.TE +.LP +Implementation extensions with names causing similar ambiguities shall +not be checked for a match until all possible matches for +commands specified by IEEE\ Std\ 1003.1-2001 have been checked. +.LP +.IP " 9." 4 +If the command is a \fB!\fP command, or if the command is a \fBread\fP +command followed by zero or more s and a +\fB!\fP, or if the command is a \fBwrite\fP command followed by one +or more s and a \fB!\fP, the rest of the +command shall include all characters up to a non-backslash-escaped +. The shall be discarded and any +subsequent characters shall be parsed as a separate \fIex\fP command. +.LP +.IP "10." 4 +Otherwise, if the command is an \fBedit\fP, \fBex\fP, or \fBnext\fP +command, or a \fBvisual\fP command while in open or +visual mode, the next part of the command shall be parsed as follows: +.RS +.IP " a." 4 +Any \fB'!'\fP character immediately following the command shall be +skipped and be part of the command. +.LP +.IP " b." 4 +Any leading s shall be skipped and be part of the command. +.LP +.IP " c." 4 +If the next character is a \fB'+'\fP , characters up to the first +non-backslash-escaped or +non-backslash-escaped shall be skipped and be part of the +command. +.LP +.IP " d." 4 +The rest of the command shall be determined by the steps specified +in paragraph 12. +.LP +.RE +.LP +.IP "11." 4 +Otherwise, if the command is a \fBglobal\fP, \fBopen\fP, \fBs\fP, +or \fBv\fP command, the next part of the command shall be +parsed as follows: +.RS +.IP " a." 4 +Any leading s shall be skipped and be part of the command. +.LP +.IP " b." 4 +If the next character is not an alphanumeric, double-quote, , +backslash, or vertical-line character: +.RS +.IP " 1." 4 +The next character shall be used as a command delimiter. +.LP +.IP " 2." 4 +If the command is a \fBglobal\fP, \fBopen\fP, or \fBv\fP command, +characters up to the first non-backslash-escaped +, or first non-backslash-escaped delimiter character, shall +be skipped and be part of the command. +.LP +.IP " 3." 4 +If the command is an \fBs\fP command, characters up to the first non-backslash-escaped +, or second +non-backslash-escaped delimiter character, shall be skipped and be +part of the command. +.LP +.RE +.LP +.IP " c." 4 +If the command is a \fBglobal\fP or \fBv\fP command, characters up +to the first non-backslash-escaped shall be +skipped and be part of the command. +.LP +.IP " d." 4 +Otherwise, the rest of the command shall be determined by the steps +specified in paragraph 12. +.LP +.RE +.LP +.IP "12." 4 +Otherwise: +.RS +.IP " a." 4 +If the command was a \fBmap\fP, \fBunmap\fP, \fBabbreviate\fP, or +\fBunabbreviate\fP command, characters up to the first +non- -V-escaped , vertical-line, or double-quote +character shall be skipped and be part of the +command. +.LP +.IP " b." 4 +Otherwise, characters up to the first non-backslash-escaped , +vertical-line, or double-quote character shall be +skipped and be part of the command. +.LP +.IP " c." 4 +If the command was an \fBappend\fP, \fBchange\fP, or \fBinsert\fP +command, and the step 12.b. ended at a vertical-line +character, any subsequent characters, up to the next non-backslash-escaped + shall be used as input text to the +command. +.LP +.IP " d." 4 +If the command was ended by a double-quote character, all subsequent +characters, up to the next non-backslash-escaped +, shall be discarded. +.LP +.IP " e." 4 +The terminating or vertical-line character shall be discarded +and any subsequent characters shall be parsed as a +separate \fIex\fP command. +.LP +.RE +.LP +.LP +Command arguments shall be parsed as described by the Synopsis and +Description of each individual \fIex\fP command. This +parsing shall not be -sensitive, except for the \fB!\fP argument, +which must follow the command name without +intervening s, and where it would otherwise be ambiguous. For +example, \fIcount\fP and \fIflag\fP arguments need not +be -separated because \fB"d22p"\fP is not ambiguous, but \fIfile\fP +arguments to the \fIex\fP \fBnext\fP command +must be separated by one or more s. Any in command +arguments for the \fBabbreviate\fP, +\fBunabbreviate\fP, \fBmap\fP, and \fBunmap\fP commands can be -V-escaped, +in which case the shall +not be used as an argument delimiter. Any in the command argument +for any other command can be backslash-escaped, in +which case that shall not be used as an argument delimiter. +.LP +Within command arguments for the \fBabbreviate\fP, \fBunabbreviate\fP, +\fBmap\fP, and \fBunmap\fP commands, any character +can be -V-escaped. All such escaped characters shall be treated +literally and shall have no special meaning. Within +command arguments for all other \fIex\fP commands that are not regular +expressions or replacement strings, any character that +would otherwise have a special meaning can be backslash-escaped. Escaped +characters shall be treated literally, without special +meaning as shell expansion characters or \fB'!'\fP , \fB'%'\fP , and +\fB'#'\fP expansion characters. See Regular Expressions in ex and +Replacement Strings in ex for descriptions of +command arguments that are regular expressions or replacement strings. +.LP +Non-backslash-escaped \fB'%'\fP characters appearing in \fIfile\fP +arguments to any \fIex\fP command shall be replaced by +the current pathname; unescaped \fB'#'\fP characters shall be replaced +by the alternate pathname. It shall be an error if +\fB'%'\fP or \fB'#'\fP characters appear unescaped in an argument +and their corresponding values are not set. +.LP +Non-backslash-escaped \fB'!'\fP characters in the arguments to either +the \fIex\fP \fB!\fP command or the open and visual +mode \fB!\fP command, or in the arguments to the \fIex\fP \fBread\fP +command, where the first non- after the +command name is a \fB'!'\fP character, or in the arguments to the +\fIex\fP \fBwrite\fP command where the command name is +followed by one or more s and the first non- after +the command name is a \fB'!'\fP character, shall +be replaced with the arguments to the last of those three commands +as they appeared after all unescaped \fB'%'\fP , \fB'#'\fP +, and \fB'!'\fP characters were replaced. It shall be an error if +\fB'!'\fP characters appear unescaped in one of these +commands and there has been no previous execution of one of these +commands. +.LP +If an error occurs during the parsing or execution of an \fIex\fP +command: +.IP " *" 3 +An informational message to this effect shall be written. Execution +of the \fIex\fP command shall stop, and the cursor (for +example, the current line and column) shall not be further modified. +.LP +.IP " *" 3 +If the \fIex\fP command resulted from a map expansion, all characters +from that map expansion shall be discarded, except as +otherwise specified by the \fBmap\fP command. +.LP +.IP " *" 3 +Otherwise, if the \fIex\fP command resulted from the processing of +an \fIEXINIT\fP environment variable, a \fB.exrc\fP file, +a \fB:source\fP command, a \fB-c\fP option, or a \fB+\fP \fIcommand\fP +specified to an \fIex\fP \fBedit\fP, \fBex\fP, +\fBnext\fP, or \fBvisual\fP command, no further commands from the +source of the commands shall be executed. +.LP +.IP " *" 3 +Otherwise, if the \fIex\fP command resulted from the execution of +a buffer or a \fBglobal\fP or \fBv\fP command, no further +commands caused by the execution of the buffer or the \fBglobal\fP +or \fBv\fP command shall be executed. +.LP +.IP " *" 3 +Otherwise, if the \fIex\fP command was not terminated by a , +all characters up to and including the next +non-backslash-escaped shall be discarded. +.LP +.SS Input Editing in ex +.LP +The following symbol is used in this and the following sections to +specify command actions: +.TP 7 +\fIword\fP +In the POSIX locale, a word consists of a maximal sequence of letters, +digits, and underscores, delimited at both ends by +characters other than letters, digits, or underscores, or by the beginning +or end of a line or the edit buffer. +.sp +.LP +When accepting input characters from the user, in either \fIex\fP +command mode or \fIex\fP text input mode, \fIex\fP shall +enable canonical mode input processing, as defined in the System Interfaces +volume of IEEE\ Std\ 1003.1-2001. +.LP +If in \fIex\fP text input mode: +.IP " 1." 4 +If the \fBnumber\fP edit option is set, \fIex\fP shall prompt for +input using the line number that would be assigned to the +line if it is entered, in the format specified for the \fIex\fP \fBnumber\fP +command. +.LP +.IP " 2." 4 +If the \fBautoindent\fP edit option is set, \fIex\fP shall prompt +for input using \fBautoindent\fP characters, as described +by the \fBautoindent\fP edit option. \fBautoindent\fP characters shall +follow the line number, if any. +.LP +.LP +If in \fIex\fP command mode: +.IP " 1." 4 +If the \fBprompt\fP edit option is set, input shall be prompted for +using a single \fB':'\fP character; otherwise, there +shall be no prompt. +.LP +.LP +The input characters in the following sections shall have the following +effects on the input line. +.SS Scroll +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBeof +\fP +.fi +.RE +.sp +.LP +See the description of the \fIstty\fP \fIeof\fP character in \fIstty\fP +\&. +.LP +If in \fIex\fP command mode: +If the \fIeof\fP character is the first character entered on the line, +the line shall be evaluated as if it contained +two characters: a -D and a . +.LP +Otherwise, the \fIeof\fP character shall have no special meaning. +.sp +.LP +If in \fIex\fP text input mode: +If the cursor follows an \fBautoindent\fP character, the \fBautoindent\fP +characters in the line shall be modified so +that a part of the next text input character will be displayed on +the first column in the line after the previous \fBshiftwidth\fP +edit option column boundary, and the user shall be prompted again +for input for the same line. +.LP +Otherwise, if the cursor follows a \fB'0'\fP , which follows an \fBautoindent\fP +character, and the \fB'0'\fP was the +previous text input character, the \fB'0'\fP and all \fBautoindent\fP +characters in the line shall be discarded, and the user +shall be prompted again for input for the same line. +.LP +Otherwise, if the cursor follows a \fB'^'\fP , which follows an \fBautoindent\fP +character, and the \fB'^'\fP was the +previous text input character, the \fB'^'\fP and all \fBautoindent\fP +characters in the line shall be discarded, and the user +shall be prompted again for input for the same line. In addition, +the \fBautoindent\fP level for the next input line shall be +derived from the same line from which the \fBautoindent\fP level for +the current input line was derived. +.LP +Otherwise, if there are no \fBautoindent\fP or text input characters +in the line, the \fIeof\fP character shall be +discarded. +.LP +Otherwise, the \fIeof\fP character shall have no special meaning. +.SS +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB +.sp + +-J +\fP +.fi +.RE +.sp +.LP +If in \fIex\fP command mode: +Cause the command line to be parsed; -J shall be mapped to +the for this +purpose. +.LP +If in \fIex\fP text input mode: +Terminate the current line. If there are no characters other than +\fBautoindent\fP characters on the line, all +characters on the line shall be discarded. +.LP +Prompt for text input on a new line after the current line. If the +\fBautoindent\fP edit option is set, an appropriate number +of \fBautoindent\fP characters shall be added as a prefix to the line +as described by the \fIex\fP \fBautoindent\fP edit +option. +.SS +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB +\fP +.fi +.RE +.sp +.LP +Allow the entry of a subsequent or -J as a literal +character, removing any special meaning that +it may have to the editor during text input mode. The backslash character +shall be retained and evaluated when the command line is +parsed, or retained and included when the input text becomes part +of the edit buffer. +.SS -V +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB-V +\fP +.fi +.RE +.sp +.LP +Allow the entry of any subsequent character as a literal character, +removing any special meaning that it may have to the editor +during text input mode. The -V character shall be discarded +before the command line is parsed or the input text +becomes part of the edit buffer. +.LP +If the "literal next" functionality is performed by the underlying +system, it is implementation-defined whether a character +other than -V performs this function. +.SS -W +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB-W +\fP +.fi +.RE +.sp +.LP +Discard the -W, and the word previous to it in the input +line, including any s following the word +and preceding the -W. If the "word erase" functionality is +performed by the underlying system, it is +implementation-defined whether a character other than -W +performs this function. +.SS Command Descriptions in ex +.LP +The following symbols are used in this section to represent command +modifiers. Some of these modifiers can be omitted, in which +case the specified defaults shall be used. +.TP 7 +\fI1addr\fP +A single line address, given in any of the forms described in Addressing +in ex ; the default +shall be the current line ( \fB'.'\fP ), unless otherwise specified. +.LP +If the line address is zero, it shall be an error, unless otherwise +specified in the following command descriptions. +.LP +If the edit buffer is empty, and the address is specified with a command +other than \fB=\fP, \fBappend\fP, \fBinsert\fP, +\fBopen\fP, \fBput\fP, \fBread\fP, or \fBvisual\fP, or the address +is not zero, it shall be an error. +.TP 7 +\fI2addr\fP +Two addresses specifying an inclusive range of lines. If no addresses +are specified, the default for \fI2addr\fP shall be the +current line only ( \fB".,."\fP ), unless otherwise specified in the +following command descriptions. If one address is +specified, \fI2addr\fP shall specify that line only, unless otherwise +specified in the following command descriptions. +.LP +It shall be an error if the first address is greater than the second +address. +.LP +If the edit buffer is empty, and the two addresses are specified with +a command other than the \fB!\fP, \fBwrite\fP, +\fBwq\fP, or \fBxit\fP commands, or either address is not zero, it +shall be an error. +.TP 7 +\fIcount\fP +A positive decimal number. If \fIcount\fP is specified, it shall be +equivalent to specifying an additional address to the +command, unless otherwise specified by the following command descriptions. +The additional address shall be equal to the last +address specified to the command (either explicitly or by default) +plus \fIcount\fP-1. +.LP +If this would result in an address greater than the last line of the +edit buffer, it shall be corrected to equal the last line +of the edit buffer. +.TP 7 +\fIflags\fP +One or more of the characters \fB'+'\fP , \fB'-'\fP , \fB'#'\fP , +\fB'p'\fP , or \fB'l'\fP (ell). The flag +characters can be -separated, and in any order or combination. +The characters \fB'#'\fP , \fB'p'\fP , and +\fB'l'\fP shall cause lines to be written in the format specified +by the \fBprint\fP command with the specified \fIflags\fP. +.LP +The lines to be written are as follows: +.RS +.IP " 1." 4 +All edit buffer lines written during the execution of the \fIex\fP +\fB&\fP, \fB~\fP, \fBlist\fP, \fBnumber\fP, +\fBopen\fP, \fBprint\fP, \fBs\fP, \fBvisual\fP, and \fBz\fP commands +shall be written as specified by \fIflags\fP. +.LP +.IP " 2." 4 +After the completion of an \fIex\fP command with a flag as an argument, +the current line shall be written as specified by +\fIflags\fP, unless the current line was the last line written by +the command. +.LP +.RE +.LP +The characters \fB'+'\fP and \fB'-'\fP cause the value of the current +line after the execution of the \fIex\fP command to +be adjusted by the offset address as described in Addressing in ex +\&. This adjustment shall occur +before the current line is written as described in 2. above. +.LP +The default for \fIflags\fP shall be none. +.TP 7 +\fIbuffer\fP +One of a number of named areas for holding text. The named buffers +are specified by the alphanumeric characters of the POSIX +locale. There shall also be one "unnamed" buffer. When no buffer is +specified for editor commands that use a buffer, the unnamed +buffer shall be used. Commands that store text into buffers shall +store the text as it was before the command took effect, and +shall store text occurring earlier in the file before text occurring +later in the file, regardless of how the text region was +specified. Commands that store text into buffers shall store the text +into the unnamed buffer as well as any specified buffer. +.LP +In \fIex\fP commands, buffer names are specified as the name by itself. +In open or visual mode commands the name is preceded by +a double quote ( \fB' )'\fP character. +.LP +If the specified buffer name is an uppercase character, and the buffer +contents are to be modified, the buffer shall be appended +to rather than being overwritten. If the buffer is not being modified, +specifying the buffer name in lowercase and uppercase shall +have identical results. +.LP +There shall also be buffers named by the numbers 1 through 9. In open +and visual mode, if a region of text including characters +from more than a single line is being modified by the \fIvi\fP \fBc\fP +or \fBd\fP commands, +the motion character associated with the \fBc\fP or \fBd\fP commands +specifies that the buffer text shall be in line mode, or the +commands \fB%\fP, \fB`\fP, \fB/\fP, \fB?\fP, \fB(\fP, \fB)\fP, \fBN\fP, +\fBn\fP, \fB{\fP, or \fB}\fP are used to define a +region of text for the \fBc\fP or \fBd\fP commands, the contents of +buffers 1 through 8 shall be moved into the buffer named by +the next numerically greater value, the contents of buffer 9 shall +be discarded, and the region of text shall be copied into buffer +1. This shall be in addition to copying the text into a user-specified +buffer or unnamed buffer, or both. Numeric buffers can be +specified as a source buffer for open and visual mode commands; however, +specifying a numeric buffer as the write target of an open +or visual mode command shall have unspecified results. +.LP +The text of each buffer shall have the characteristic of being in +either line or character mode. Appending text to a non-empty +buffer shall set the mode to match the characteristic of the text +being appended. Appending text to a buffer shall cause the +creation of at least one additional line in the buffer. All text stored +into buffers by \fIex\fP commands shall be in line mode. +The \fIex\fP commands that use buffers as the source of text specify +individually how buffers of different modes are handled. Each +open or visual mode command that uses buffers for any purpose specifies +individually the mode of the text stored into the buffer +and how buffers of different modes are handled. +.TP 7 +\fIfile\fP +Command text used to derive a pathname. The default shall be the current +pathname, as defined previously, in which case, if no +current pathname has yet been established it shall be an error, except +where specifically noted in the individual command +descriptions that follow. If the command text contains any of the +characters \fB'~'\fP , \fB'{'\fP , \fB'['\fP , +\fB'*'\fP , \fB'?'\fP , \fB'$'\fP , \fB'`'\fP , \fB'"\fP , \fB' ,'\fP +and \fB'\\'\fP , it shall be subjected +to the process of "shell expansions", as described below; if more +than a single pathname results and the command expects only +one, it shall be an error. +.LP +The process of shell expansions in the editor shall be done as follows. +The \fIex\fP utility shall pass two arguments to the +program named by the shell edit option; the first shall be \fB-c\fP, +and the second shall be the string \fB"echo"\fP and the +command text as a single argument. The standard output and standard +error of that command shall replace the command text. +.TP 7 +\fB!\fP +A character that can be appended to the command name to modify its +operation, as detailed in the individual command +descriptions. With the exception of the \fIex\fP \fBread\fP, \fBwrite\fP, +and \fB!\fP commands, the \fB'!'\fP character +shall only act as a modifier if there are no s between it and +the command name. +.TP 7 +\fIremembered\ search\ direction\fP +.sp +The \fIvi\fP commands \fBN\fP and \fBn\fP begin searching in a forwards +or backwards +direction in the edit buffer based on a remembered search direction, +which is initially unset, and is set by the \fIex\fP +\fBglobal\fP, \fBv\fP, \fBs\fP, and \fBtag\fP commands, and the \fIvi\fP +\fB/\fP and +\fB?\fP commands. +.sp +.SS Abbreviate +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBab\fP\fB[\fP\fIbreviate\fP\fB][\fP\fIlhs rhs\fP\fB]\fP +.fi +.RE +.sp +.LP +If \fIlhs\fP and \fIrhs\fP are not specified, write the current list +of abbreviations and do nothing more. +.LP +Implementations may restrict the set of characters accepted in \fIlhs\fP +or \fIrh\fP, except that printable characters and +s shall not be restricted. Additional restrictions shall be +implementation-defined. +.LP +In both \fIlhs\fP and \fIrhs\fP, any character may be escaped with +a -V, in which case the character shall not +be used to delimit \fIlhs\fP from \fIrhs\fP, and the escaping -V +shall be discarded. +.LP +In open and visual text input mode, if a non-word or character +that is not escaped by a -V character +is entered after a word character, a check shall be made for a set +of characters matching \fIlhs\fP, in the text input entered +during this command. If it is found, the effect shall be as if \fIrhs\fP +was entered instead of \fIlhs\fP. +.LP +The set of characters that are checked is defined as follows: +.IP " 1." 4 +If there are no characters inserted before the word and non-word or + characters that triggered the check, the set of +characters shall consist of the word character. +.LP +.IP " 2." 4 +If the character inserted before the word and non-word or characters +that triggered the check is a word character, +the set of characters shall consist of the characters inserted immediately +before the triggering characters that are word +characters, plus the triggering word character. +.LP +.IP " 3." 4 +If the character inserted before the word and non-word or characters +that triggered the check is not a word +character, the set of characters shall consist of the characters that +were inserted before the triggering characters that are +neither s nor word characters, plus the triggering word character. +.LP +.LP +It is unspecified whether the \fIlhs\fP argument entered for the \fIex\fP +\fBabbreviate\fP and \fBunabbreviate\fP commands +is replaced in this fashion. Regardless of whether or not the replacement +occurs, the effect of the command shall be as if the +replacement had not occurred. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Append +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI1addr\fP\fB]\fP \fBa\fP\fB[\fP\fBppend\fP\fB][\fP\fB!\fP\fB]\fP +.fi +.RE +.sp +.LP +Enter \fIex\fP text input mode; the input text shall be placed after +the specified line. If line zero is specified, the text +shall be placed at the beginning of the edit buffer. +.LP +This command shall be affected by the \fBnumber\fP and \fBautoindent\fP +edit options; following the command name with +\fB'!'\fP shall cause the \fBautoindent\fP edit option setting to +be toggled for the duration of this command only. +.LP +\fICurrent line\fP: Set to the last input line; if no lines were input, +set to the specified line, or to the first line of the +edit buffer if a line of zero was specified, or zero if the edit buffer +is empty. +.LP +\fICurrent column\fP: Set to non- . +.SS Arguments +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBar\fP\fB[\fP\fIgs\fP\fB]\fP +.fi +.RE +.sp +.LP +Write the current argument list, with the current argument-list entry, +if any, between \fB'['\fP and \fB']'\fP +characters. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Change +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fBc\fP\fB[\fP\fBhange\fP\fB][\fP\fB!\fP\fB][\fP\fIcount\fP\fB]\fP +.fi +.RE +.sp +.LP +Enter \fIex\fP text input mode; the input text shall replace the specified +lines. The specified lines shall be copied into the +unnamed buffer, which shall become a line mode buffer. +.LP +This command shall be affected by the \fBnumber\fP and \fBautoindent\fP +edit options; following the command name with +\fB'!'\fP shall cause the \fBautoindent\fP edit option setting to +be toggled for the duration of this command only. +.LP +\fICurrent line\fP: Set to the last input line; if no lines were input, +set to the line before the first address, or to the +first line of the edit buffer if there are no lines preceding the +first address, or to zero if the edit buffer is empty. +.LP +\fICurrent column\fP: Set to non- . +.SS Change Directory +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBchd\fP\fB[\fP\fBir\fP\fB][\fP\fB!\fP\fB][\fP\fIdirectory\fP\fB]\fP\fBcd\fP\fB[\fP\fB!\fP\fB][\fP\fIdirectory\fP\fB]\fP +.fi +.RE +.sp +.LP +Change the current working directory to \fIdirectory\fP. +.LP +If no \fIdirectory\fP argument is specified, and the \fIHOME\fP environment +variable is set to a non-null and non-empty value, +\fIdirectory\fP shall default to the value named in the \fIHOME\fP +environment variable. If the \fIHOME\fP environment variable +is empty or is undefined, the default value of \fIdirectory\fP is +implementation-defined. +.LP +If no \fB'!'\fP is appended to the command name, and the edit buffer +has been modified since the last complete write, and the +current pathname does not begin with a \fB'/'\fP , it shall be an +error. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Copy +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fBco\fP\fB[\fP\fBpy\fP\fB]\fP \fI1addr\fP \fB[\fP\fIflags\fP\fB] +[\fP\fI2addr\fP\fB]\fP \fBt\fP \fI1addr\fP \fB[\fP\fIflags\fP\fB]\fP +.fi +.RE +.sp +.LP +Copy the specified lines after the specified destination line; line +zero specifies that the lines shall be placed at the +beginning of the edit buffer. +.LP +\fICurrent line\fP: Set to the last line copied. +.LP +\fICurrent column\fP: Set to non- . +.SS Delete +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fBd\fP\fB[\fP\fBelete\fP\fB][\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP +.fi +.RE +.sp +.LP +Delete the specified lines into a buffer (defaulting to the unnamed +buffer), which shall become a line-mode buffer. +.LP +Flags can immediately follow the command name; see Command Line Parsing +in ex . +.LP +\fICurrent line\fP: Set to the line following the deleted lines, or +to the last line in the edit buffer if that line is past +the end of the edit buffer, or to zero if the edit buffer is empty. +.LP +\fICurrent column\fP: Set to non- . +.SS Edit +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBe\fP\fB[\fP\fBdit\fP\fB][\fP\fB!\fP\fB][\fP\fB+\fP\fIcommand\fP\fB][\fP\fIfile\fP\fB]\fP\fBex\fP\fB[\fP\fB!\fP\fB][\fP\fB+\fP\fIcommand\fP\fB][\fP\fIfile\fP\fB]\fP +.fi +.RE +.sp +.LP +If no \fB'!'\fP is appended to the command name, and the edit buffer +has been modified since the last complete write, it +shall be an error. +.LP +If \fIfile\fP is specified, replace the current contents of the edit +buffer with the current contents of \fIfile\fP, and set +the current pathname to \fIfile\fP. If \fIfile\fP is not specified, +replace the current contents of the edit buffer with the +current contents of the file named by the current pathname. If for +any reason the current contents of the file cannot be accessed, +the edit buffer shall be empty. +.LP +The \fB+\fP \fIcommand\fP option shall be -delimited; s +within \fB+\fP \fIcommand\fP can be +escaped by preceding them with a backslash character. The \fB+\fP +\fIcommand\fP shall be interpreted as an \fIex\fP command +immediately after the contents of the edit buffer have been replaced +and the current line and column have been set. +.LP +If the edit buffer is empty: +.LP +\fICurrent line\fP: Set to 0. +.LP +\fICurrent column\fP: Set to 1. +.LP +Otherwise, if executed while in \fIex\fP command mode or if the \fB+\fP +\fIcommand\fP argument is specified: +.LP +\fICurrent line\fP: Set to the last line of the edit buffer. +.LP +\fICurrent column\fP: Set to non- . +.LP +Otherwise, if \fIfile\fP is omitted or results in the current pathname: +.LP +\fICurrent line\fP: Set to the first line of the edit buffer. +.LP +\fICurrent column\fP: Set to non- . +.LP +Otherwise, if \fIfile\fP is the same as the last file edited, the +line and column shall be set as follows; if the file was +previously edited, the line and column may be set as follows: +.LP +\fICurrent line\fP: Set to the last value held when that file was +last edited. If this value is not a valid line in the new +edit buffer, set to the first line of the edit buffer. +.LP +\fICurrent column\fP: If the current line was set to the last value +held when the file was last edited, set to the last value +held when the file was last edited. Otherwise, or if the last value +is not a valid column in the new edit buffer, set to non- +. +.LP +Otherwise: +.LP +\fICurrent line\fP: Set to the first line of the edit buffer. +.LP +\fICurrent column\fP: Set to non- . +.SS File +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBf\fP\fB[\fP\fBile\fP\fB][\fP\fIfile\fP\fB]\fP +.fi +.RE +.sp +.LP +If a \fIfile\fP argument is specified, the alternate pathname shall +be set to the current pathname, and the current pathname +shall be set to \fIfile\fP. +.LP +Write an informational message. If the file has a current pathname, +it shall be included in this message; otherwise, the message +shall indicate that there is no current pathname. If the edit buffer +contains lines, the current line number and the number of +lines in the edit buffer shall be included in this message; otherwise, +the message shall indicate that the edit buffer is empty. If +the edit buffer has been modified since the last complete write, this +fact shall be included in this message. If the +\fBreadonly\fP edit option is set, this fact shall be included in +this message. The message may contain other unspecified +information. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Global +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fBg\fP\fB[\fP\fBlobal\fP\fB]\fP \fB/\fP\fIpattern\fP\fB/\fP \fB[\fP\fIcommands\fP\fB] +[\fP\fI2addr\fP\fB]\fP \fBv /\fP\fIpattern\fP\fB/\fP \fB[\fP\fIcommands\fP\fB]\fP +.fi +.RE +.sp +.LP +The optional \fB'!'\fP character after the \fBglobal\fP command shall +be the same as executing the \fBv\fP command. +.LP +If \fIpattern\fP is empty (for example, \fB"//"\fP ) or not specified, +the last regular expression used in the editor +command shall be used as the \fIpattern\fP. The \fIpattern\fP can +be delimited by slashes (shown in the Synopsis), as well as any +non-alphanumeric or non- other than backslash, vertical line, +double quote, or . +.LP +If no lines are specified, the lines shall default to the entire file. +.LP +The \fBglobal\fP and \fBv\fP commands are logically two-pass operations. +First, mark the lines within the specified lines for +which the line excluding the terminating matches ( \fBglobal\fP) +or does not match ( \fBv\fP or \fBglobal!\fP) +the specified pattern. Second, execute the \fIex\fP commands given +by \fIcommands\fP, with the current line ( \fB'.'\fP ) set +to each marked line. If an error occurs during this process, or the +contents of the edit buffer are replaced (for example, by the +\fIex\fP \fB:edit\fP command) an error message shall be written and +no more commands resulting from the execution of this command +shall be processed. +.LP +Multiple \fIex\fP commands can be specified by entering multiple commands +on a single line using a vertical line to delimit +them, or one per line, by escaping each with a backslash. +.LP +If no commands are specified: +.IP " 1." 4 +If in \fIex\fP command mode, it shall be as if the \fBprint\fP command +were specified. +.LP +.IP " 2." 4 +Otherwise, no command shall be executed. +.LP +.LP +For the \fBappend\fP, \fBchange\fP, and \fBinsert\fP commands, the +input text shall be included as part of the command, and +the terminating period can be omitted if the command ends the list +of commands. The \fBopen\fP and \fBvisual\fP commands can be +specified as one of the commands, in which case each marked line shall +cause the editor to enter open or visual mode. If open or +visual mode is exited using the \fIvi\fP \fBQ\fP command, the current +line shall be set to the +next marked line, and open or visual mode reentered, until the list +of marked lines is exhausted. +.LP +The \fBglobal\fP, \fBv\fP, and \fBundo\fP commands cannot be used +in \fIcommands\fP. Marked lines may be deleted by commands +executed for lines occurring earlier in the file than the marked lines. +In this case, no commands shall be executed for the deleted +lines. +.LP +If the remembered search direction is not set, the \fBglobal\fP and +\fBv\fP commands shall set it to forward. +.LP +The \fBautoprint\fP and \fBautoindent\fP edit options shall be inhibited +for the duration of the \fBg\fP or \fBv\fP +command. +.LP +\fICurrent line\fP: If no commands executed, set to the last marked +line. Otherwise, as specified for the executed \fIex\fP +commands. +.LP +\fICurrent column\fP: If no commands are executed, set to non- ; +otherwise, as specified for the individual +\fIex\fP commands. +.SS Insert +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI1addr\fP\fB]\fP \fBi\fP\fB[\fP\fBnsert\fP\fB][\fP\fB!\fP\fB]\fP +.fi +.RE +.sp +.LP +Enter \fIex\fP text input mode; the input text shall be placed before +the specified line. If the line is zero or 1, the text +shall be placed at the beginning of the edit buffer. +.LP +This command shall be affected by the \fBnumber\fP and \fBautoindent\fP +edit options; following the command name with +\fB'!'\fP shall cause the \fBautoindent\fP edit option setting to +be toggled for the duration of this command only. +.LP +\fICurrent line\fP: Set to the last input line; if no lines were input, +set to the line before the specified line, or to the +first line of the edit buffer if there are no lines preceding the +specified line, or zero if the edit buffer is empty. +.LP +\fICurrent column\fP: Set to non- . +.SS Join +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fBj\fP\fB[\fP\fBoin\fP\fB][\fP\fB!\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP +.fi +.RE +.sp +.LP +If \fIcount\fP is specified: +If no address was specified, the \fBjoin\fP command shall behave as +if \fI2addr\fP were the current line and the +current line plus \fIcount\fP (.,. + \fIcount\fP). +.LP +If one address was specified, the \fBjoin\fP command shall behave +as if \fI2addr\fP were the specified address and the +specified address plus \fIcount\fP ( \fIaddr\fP, \fIaddr\fP + \fIcount\fP). +.LP +If two addresses were specified, the \fBjoin\fP command shall behave +as if an additional address, equal to the last address +plus \fIcount\fP -1 ( \fIaddr1\fP, \fIaddr2\fP, \fIaddr2\fP + \fIcount\fP +-1), was specified. +.LP +If this would result in a second address greater than the last line +of the edit buffer, it shall be corrected to be equal to the +last line of the edit buffer. +.LP +If no \fIcount\fP is specified: +If no address was specified, the \fBjoin\fP command shall behave as +if \fI2addr\fP were the current line and the next +line (.,. +1). +.LP +If one address was specified, the \fBjoin\fP command shall behave +as if \fI2addr\fP were the specified address and the next +line ( \fIaddr\fP, \fIaddr\fP +1). +.LP +Join the text from the specified lines together into a single line, +which shall replace the specified lines. +.LP +If a \fB'!'\fP character is appended to the command name, the \fBjoin\fP +shall be without modification of any line, +independent of the current locale. +.LP +Otherwise, in the POSIX locale, set the current line to the first +of the specified lines, and then, for each subsequent line, +proceed as follows: +.IP " 1." 4 +Discard leading s from the line to be joined. +.LP +.IP " 2." 4 +If the line to be joined is now empty, delete it, and skip steps 3 +through 5. +.LP +.IP " 3." 4 +If the current line ends in a , or the first character of the +line to be joined is a \fB')'\fP character, join +the lines without further modification. +.LP +.IP " 4." 4 +If the last character of the current line is a \fB'.'\fP , join the +lines with two s between them. +.LP +.IP " 5." 4 +Otherwise, join the lines with a single between them. +.LP +.LP +\fICurrent line\fP: Set to the first line specified. +.LP +\fICurrent column\fP: Set to non- . +.SS List +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fBl\fP\fB[\fP\fBist\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP +.fi +.RE +.sp +.LP +This command shall be equivalent to the \fIex\fP command: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fBp\fP\fB[\fP\fBrint\fP\fB][\fP\fIcount\fP\fB]\fP \fBl\fP\fB[\fP\fIflags\fP\fB]\fP +.fi +.RE +.LP +See Print . +.SS Map +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBmap\fP\fB[\fP\fB!\fP\fB][\fP\fIlhs rhs\fP\fB]\fP +.fi +.RE +.sp +.LP +If \fIlhs\fP and \fIrhs\fP are not specified: +.IP " 1." 4 +If \fB'!'\fP is specified, write the current list of text input mode +maps. +.LP +.IP " 2." 4 +Otherwise, write the current list of command mode maps. +.LP +.IP " 3." 4 +Do nothing more. +.LP +.LP +Implementations may restrict the set of characters accepted in \fIlhs\fP +or \fIrhs\fP, except that printable characters and +s shall not be restricted. Additional restrictions shall be +implementation-defined. In both \fIlhs\fP and \fIrhs\fP, +any character can be escaped with a -V, in which case the +character shall not be used to delimit \fIlhs\fP from +\fIrhs\fP, and the escaping -V shall be discarded. +.LP +If the character \fB'!'\fP is appended to the \fBmap\fP command name, +the mapping shall be effective during open or visual +text input mode rather than \fBopen\fP or \fBvisual\fP command mode. +This allows \fIlhs\fP to have two different \fBmap\fP +definitions at the same time: one for command mode and one for text +input mode. +.LP +For command mode mappings: +When the \fIlhs\fP is entered as any part of a \fIvi\fP command in +open or visual +mode (but not as part of the arguments to the command), the action +shall be as if the corresponding \fIrhs\fP had been entered. +.LP +If any character in the command, other than the first, is escaped +using a -V character, that character shall not +be part of a match to an \fIlhs\fP. +.LP +It is unspecified whether implementations shall support \fBmap\fP +commands where the \fIlhs\fP is more than a single character +in length, where the first character of the \fIlhs\fP is printable. +.LP +If \fIlhs\fP contains more than one character and the first character +is \fB'#'\fP , followed by a sequence of digits +corresponding to a numbered function key, then when this function +key is typed it shall be mapped to \fIrhs\fP. Characters other +than digits following a \fB'#'\fP character also represent the function +key named by the characters in the \fIlhs\fP following +the \fB'#'\fP and may be mapped to \fIrhs\fP. It is unspecified how +function keys are named or what function keys are +supported. +.LP +For text input mode mappings: +When the \fIlhs\fP is entered as any part of text entered in open +or visual text input modes, the action shall be as +if the corresponding \fIrhs\fP had been entered. +.LP +If any character in the input text is escaped using a -V +character, that character shall not be part of a match +to an \fIlhs\fP. +.LP +It is unspecified whether the \fIlhs\fP text entered for subsequent +\fBmap\fP or \fBunmap\fP commands is replaced with the +\fIrhs\fP text for the purposes of the screen display; regardless +of whether or not the display appears as if the corresponding +\fIrhs\fP text was entered, the effect of the command shall be as +if the \fIlhs\fP text was entered. +.LP +If only part of the \fIlhs\fP is entered, it is unspecified how long +the editor will wait for additional, possibly matching +characters before treating the already entered characters as not matching +the \fIlhs\fP. +.LP +The \fIrhs\fP characters shall themselves be subject to remapping, +unless otherwise specified by the \fBremap\fP edit option, +except that if the characters in \fIlhs\fP occur as prefix characters +in \fIrhs\fP, those characters shall not be remapped. +.LP +On block-mode terminals, the mapping need not occur immediately (for +example, it may occur after the terminal transmits a group +of characters to the system), but it shall achieve the same results +as if it occurred immediately. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Mark +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI1addr\fP\fB]\fP \fBma\fP\fB[\fP\fBrk\fP\fB]\fP \fIcharacter +\fP\fB[\fP\fI1addr\fP\fB]\fP \fBk\fP \fIcharacter\fP +.fi +.RE +.sp +.LP +Implementations shall support \fIcharacter\fP values of a single lowercase +letter of the POSIX locale and the characters +\fB'`'\fP and \fB'"\fP ; support of other characters is implementation-defined. +.LP +If executing the \fIvi\fP \fBm\fP command, set the specified mark +to the current line and +1-based numbered character referenced by the current column, if any; +otherwise, column position 1. +.LP +Otherwise, set the specified mark to the specified line and 1-based +numbered first non- non- in +the line, if any; otherwise, the last non- in the line, +if any; otherwise, column position 1. +.LP +The mark shall remain associated with the line until the mark is reset +or the line is deleted. If a deleted line is restored by +a subsequent \fBundo\fP command, any marks previously associated with +the line, which have not been reset, shall be restored as +well. Any use of a mark not associated with a current line in the +edit buffer shall be an error. +.LP +The marks \fB`\fP and \fB'\fP shall be set as described previously, +immediately before the following events occur in the +editor: +.IP " 1." 4 +The use of \fB'$'\fP as an \fIex\fP address +.LP +.IP " 2." 4 +The use of a positive decimal number as an \fIex\fP address +.LP +.IP " 3." 4 +The use of a search command as an \fIex\fP address +.LP +.IP " 4." 4 +The use of a mark reference as an \fIex\fP address +.LP +.IP " 5." 4 +The use of the following open and visual mode commands: -], +\fB%\fP, \fB(\fP, \fB)\fP, \fB[\fP, \fB]\fP, +\fB{\fP, \fB}\fP +.LP +.IP " 6." 4 +The use of the following open and visual mode commands: \fB'\fP, \fBG\fP, +\fBH\fP, \fBL\fP, \fBM\fP, \fBz\fP if the +current line will change as a result of the command +.LP +.IP " 7." 4 +The use of the open and visual mode commands: \fB/\fP, \fB?\fP, \fBN\fP, +\fB`\fP, \fBn\fP if the current line or column +will change as a result of the command +.LP +.IP " 8." 4 +The use of the \fIex\fP mode commands: \fBz\fP, \fBundo\fP, \fBglobal\fP, +\fBv\fP +.LP +.LP +For rules 1., 2., 3., and 4., the \fB`\fP and \fB'\fP marks shall +not be set if the \fIex\fP command is parsed as specified +by rule 6.a. in Command Line Parsing in ex . +.LP +For rules 5., 6., and 7., the \fB`\fP and \fB'\fP marks shall not +be set if the commands are used as motion commands in open +and visual mode. +.LP +For rules 1., 2., 3., 4., 5., 6., 7., and 8., the \fB`\fP and \fB'\fP +marks shall not be set if the command fails. +.LP +The \fB`\fP and \fB'\fP marks shall be set as described previously, +each time the contents of the edit buffer are replaced +(including the editing of the initial buffer), if in open or visual +mode, or if in \fBex\fP mode and the edit buffer is not empty, +before any commands or movements (including commands or movements +specified by the \fB-c\fP or \fB-t\fP options or the \fB+\fP +\fIcommand\fP argument) are executed on the edit buffer. If in open +or visual mode, the marks shall be set as if executing the \fIvi\fP +\fBm\fP command; otherwise, as if executing the \fIex\fP \fBmark\fP +command. +.LP +When changing from \fBex\fP mode to open or visual mode, if the \fB`\fP +and \fB'\fP marks are not already set, the \fB`\fP +and \fB'\fP marks shall be set as described previously. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Move +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fBm\fP\fB[\fP\fBove\fP\fB]\fP \fI1addr\fP \fB\fP\fB[\fP\fIflags\fP\fB]\fP +.fi +.RE +.sp +.LP +Move the specified lines after the specified destination line. A destination +of line zero specifies that the lines shall be +placed at the beginning of the edit buffer. It shall be an error if +the destination line is within the range of lines to be +moved. +.LP +\fICurrent line\fP: Set to the last of the moved lines. +.LP +\fICurrent column\fP: Set to non- . +.SS Next +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBn\fP\fB[\fP\fBext\fP\fB][\fP\fB!\fP\fB][\fP\fB+\fP\fIcommand\fP\fB][\fP\fIfile\fP \fB...\fP\fB]\fP +.fi +.RE +.sp +.LP +If no \fB'!'\fP is appended to the command name, and the edit buffer +has been modified since the last complete write, it +shall be an error, unless the file is successfully written as specified +by the \fBautowrite\fP option. +.LP +If one or more files is specified: +.IP " 1." 4 +Set the argument list to the specified filenames. +.LP +.IP " 2." 4 +Set the current argument list reference to be the first entry in the +argument list. +.LP +.IP " 3." 4 +Set the current pathname to the first filename specified. +.LP +.LP +Otherwise: +.IP " 1." 4 +It shall be an error if there are no more filenames in the argument +list after the filename currently referenced. +.LP +.IP " 2." 4 +Set the current pathname and the current argument list reference to +the filename after the filename currently referenced in the +argument list. +.LP +.LP +Replace the contents of the edit buffer with the contents of the file +named by the current pathname. If for any reason the +contents of the file cannot be accessed, the edit buffer shall be +empty. +.LP +This command shall be affected by the \fBautowrite\fP and \fBwriteany\fP +edit options. +.LP +The \fB+\fP \fIcommand\fP option shall be -delimited; s +can be escaped by preceding them with a +backslash character. The \fB+\fP \fIcommand\fP shall be interpreted +as an \fIex\fP command immediately after the contents of the +edit buffer have been replaced and the current line and column have +been set. +.LP +\fICurrent line\fP: Set as described for the \fBedit\fP command. +.LP +\fICurrent column\fP: Set as described for the \fBedit\fP command. +.SS Number +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fBnu\fP\fB[\fP\fBmber\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB] +[\fP\fI2addr\fP\fB]\fP \fB#\fP\fB[\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP +.fi +.RE +.sp +.LP +These commands shall be equivalent to the \fIex\fP command: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fBp\fP\fB[\fP\fBrint\fP\fB][\fP\fIcount\fP\fB]\fP \fB#\fP\fB[\fP\fIflags\fP\fB]\fP +.fi +.RE +.LP +See Print . +.SS Open +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI1addr\fP\fB]\fP \fBo\fP\fB[\fP\fBpen\fP\fB]\fP \fB/\fP\fIpattern\fP\fB/\fP \fB[\fP\fIflags\fP\fB]\fP +.fi +.RE +.sp +.LP +This command need not be supported on block-mode terminals or terminals +with insufficient capabilities. If standard input, +standard output, or standard error are not terminal devices, the results +are unspecified. +.LP +Enter open mode. +.LP +The trailing delimiter can be omitted from \fIpattern\fP at the end +of the command line. If \fIpattern\fP is empty (for +example, \fB"//"\fP ) or not specified, the last regular expression +used in the editor shall be used as the pattern. The pattern +can be delimited by slashes (shown in the Synopsis), as well as any +alphanumeric, or non- other than backslash, +vertical line, double quote, or . +.LP +\fICurrent line\fP: Set to the specified line. +.LP +\fICurrent column\fP: Set to non- . +.SS Preserve +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBpre\fP\fB[\fP\fBserve\fP\fB]\fP +.fi +.RE +.sp +.LP +Save the edit buffer in a form that can later be recovered by using +the \fB-r\fP option or by using the \fIex\fP +\fBrecover\fP command. After the file has been preserved, a mail message +shall be sent to the user. This message shall be readable +by invoking the \fImailx\fP utility. The message shall contain the +name of the file, the +time of preservation, and an \fIex\fP command that could be used to +recover the file. Additional information may be included in +the mail message. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Print +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fBp\fP\fB[\fP\fBrint\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP +.fi +.RE +.sp +.LP +Write the addressed lines. The behavior is unspecified if the number +of columns on the display is less than the number of +columns required to write any single character in the lines being +written. +.LP +Non-printable characters, except for the , shall be written as +implementation-defined multi-character sequences. +.LP +If the \fB#\fP flag is specified or the \fBnumber\fP edit option is +set, each line shall be preceded by its line number in the +following format: +.sp +.RS +.nf + +\fB"%6d ", <\fP\fIline number\fP\fB> +\fP +.fi +.RE +.LP +If the \fBl\fP flag is specified or the \fBlist\fP edit option is +set: +.IP " 1." 4 +The characters listed in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Table 5-1, Escape Sequences and +Associated Actions shall be written as the corresponding escape sequence. +.LP +.IP " 2." 4 +Non-printable characters not in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Table 5-1, Escape Sequences and +Associated Actions shall be written as one three-digit octal number +(with a preceding backslash) for each byte in the character +(most significant byte first). If the size of a byte on the system +is greater than 9 bits, the format used for non-printable +characters is implementation-defined. +.LP +.IP " 3." 4 +The end of each line shall be marked with a \fB'$'\fP , and literal +\fB'$'\fP characters within the line shall be written +with a preceding backslash. +.LP +.LP +Long lines shall be folded; the length at which folding occurs is +unspecified, but should be appropriate for the output +terminal, considering the number of columns of the terminal. +.LP +If a line is folded, and the \fBl\fP flag is not specified and the +\fBlist\fP edit option is not set, it is unspecified +whether a multi-column character at the folding position is separated; +it shall not be discarded. +.LP +\fICurrent line\fP: Set to the last written line. +.LP +\fICurrent column\fP: Unchanged if the current line is unchanged; +otherwise, set to non- . +.SS Put +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI1addr\fP\fB]\fP \fBpu\fP\fB[\fP\fBt\fP\fB][\fP\fIbuffer\fP\fB]\fP +.fi +.RE +.sp +.LP +Append text from the specified buffer (by default, the unnamed buffer) +to the specified line; line zero specifies that the text +shall be placed at the beginning of the edit buffer. Each portion +of a line in the buffer shall become a new line in the edit +buffer, regardless of the mode of the buffer. +.LP +\fICurrent line\fP: Set to the last line entered into the edit buffer. +.LP +\fICurrent column\fP: Set to non- . +.SS Quit +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBq\fP\fB[\fP\fBuit\fP\fB][\fP\fB!\fP\fB]\fP +.fi +.RE +.sp +.LP +If no \fB'!'\fP is appended to the command name: +.IP " 1." 4 +If the edit buffer has been modified since the last complete write, +it shall be an error. +.LP +.IP " 2." 4 +If there are filenames in the argument list after the filename currently +referenced, and the last command was not a \fBquit\fP, +\fBwq\fP, \fBxit\fP, or \fBZZ\fP (see \fIExit\fP ) command, it shall +be an error. +.LP +.LP +Otherwise, terminate the editing session. +.SS Read +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI1addr\fP\fB]\fP \fBr\fP\fB[\fP\fBead\fP\fB][\fP\fB!\fP\fB][\fP\fIfile\fP\fB]\fP +.fi +.RE +.sp +.LP +If \fB'!'\fP is not the first non- to follow the command name, +a copy of the specified file shall be appended +into the edit buffer after the specified line; line zero specifies +that the copy shall be placed at the beginning of the edit +buffer. The number of lines and bytes read shall be written. If no +\fIfile\fP is named, the current pathname shall be the default. +If there is no current pathname, then \fIfile\fP shall become the +current pathname. If there is no current pathname or \fIfile\fP +operand, it shall be an error. Specifying a \fIfile\fP that is not +of type regular shall have unspecified results. +.LP +Otherwise, if \fIfile\fP is preceded by \fB'!'\fP , the rest of the +line after the \fB'!'\fP shall have \fB'%'\fP , +\fB'#'\fP , and \fB'!'\fP characters expanded as described in Command +Line Parsing in ex . +.LP +The \fIex\fP utility shall then pass two arguments to the program +named by the shell edit option; the first shall be \fB-c\fP +and the second shall be the expanded arguments to the \fBread\fP command +as a single argument. The standard input of the program +shall be set to the standard input of the \fIex\fP program when it +was invoked. The standard error and standard output of the +program shall be appended into the edit buffer after the specified +line. +.LP +Each line in the copied file or program output (as delimited by s +or the end of the file or output if it is not +immediately preceded by a ), shall be a separate line in +the edit buffer. Any occurrences of +and pairs in the output shall be treated as single s. +.LP +The special meaning of the \fB'!'\fP following the \fBread\fP command +can be overridden by escaping it with a backslash +character. +.LP +\fICurrent line\fP: If no lines are added to the edit buffer, unchanged. +Otherwise, if in open or visual mode, set to the first +line entered into the edit buffer. Otherwise, set to the last line +entered into the edit buffer. +.LP +\fICurrent column\fP: Set to non- . +.SS Recover +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBrec\fP\fB[\fP\fBover\fP\fB][\fP\fB!\fP\fB]\fP \fIfile\fP +.fi +.RE +.sp +.LP +If no \fB'!'\fP is appended to the command name, and the edit buffer +has been modified since the last complete write, it +shall be an error. +.LP +If no \fIfile\fP operand is specified, then the current pathname shall +be used. If there is no current pathname or \fIfile\fP +operand, it shall be an error. +.LP +If no recovery information has previously been saved about \fIfile\fP, +the \fBrecover\fP command shall behave identically to +the \fBedit\fP command, and an informational message to this effect +shall be written. +.LP +Otherwise, set the current pathname to \fIfile\fP, and replace the +current contents of the edit buffer with the recovered +contents of \fIfile\fP. If there are multiple instances of the file +to be recovered, the one most recently saved shall be +recovered, and an informational message that there are previous versions +of the file that can be recovered shall be written. The +editor shall behave as if the contents of the edit buffer have already +been modified. +.LP +\fICurrent file\fP: Set as described for the \fBedit\fP command. +.LP +\fICurrent column\fP: Set as described for the \fBedit\fP command. +.SS Rewind +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBrew\fP\fB[\fP\fBind\fP\fB][\fP\fB!\fP\fB]\fP +.fi +.RE +.sp +.LP +If no \fB'!'\fP is appended to the command name, and the edit buffer +has been modified since the last complete write, it +shall be an error, unless the file is successfully written as specified +by the \fBautowrite\fP option. +.LP +If the argument list is empty, it shall be an error. +.LP +The current argument list reference and the current pathname shall +be set to the first filename in the argument list. +.LP +Replace the contents of the edit buffer with the contents of the file +named by the current pathname. If for any reason the +contents of the file cannot be accessed, the edit buffer shall be +empty. +.LP +This command shall be affected by the \fBautowrite\fP and \fBwriteany\fP +edit options. +.LP +\fICurrent line\fP: Set as described for the \fBedit\fP command. +.LP +\fICurrent column\fP: Set as described for the \fBedit\fP command. +.SS Set +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBse\fP\fB[\fP\fBt\fP\fB][\fP\fIoption\fP\fB[\fP\fB=\fP\fB[\fP\fIvalue\fP\fB]]\fP \fB...\fP\fB][\fP\fBno\fP\fIoption\fP \fB...\fP\fB][\fP\fIoption\fP\fB? ...\fP\fB][\fP\fBall\fP\fB]\fP +.fi +.RE +.sp +.LP +When no arguments are specified, write the value of the \fBterm\fP +edit option and those options whose values have been changed +from the default settings; when the argument \fIall\fP is specified, +write all of the option values. +.LP +Giving an option name followed by the character \fB'?'\fP shall cause +the current value of that option to be written. The +\fB'?'\fP can be separated from the option name by zero or more s. +The \fB'?'\fP shall be necessary only for +Boolean valued options. Boolean options can be given values by the +form \fBset\fP \fIoption\fP to turn them on or \fBset\fP +\fBno\fP \fIoption\fP to turn them off; string and numeric options +can be assigned by the form \fBset\fP \fIoption\fP= +\fIvalue\fP. Any s in strings can be included as is by preceding +each with an escaping backslash. More +than one option can be set or listed by a single set command by specifying +multiple arguments, each separated from the next by one +or more s. +.LP +See Edit Options in ex for details about specific options. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Shell +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBsh\fP\fB[\fP\fBell\fP\fB]\fP +.fi +.RE +.sp +.LP +Invoke the program named in the \fBshell\fP edit option with the single +argument \fB-i\fP (interactive mode). Editing shall be +resumed when the program exits. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Source +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBso\fP\fB[\fP\fBurce\fP\fB]\fP \fIfile\fP +.fi +.RE +.sp +.LP +Read and execute \fIex\fP commands from \fIfile\fP. Lines in the file +that are blank lines shall be ignored. +.LP +\fICurrent line\fP: As specified for the individual \fIex\fP commands. +.LP +\fICurrent column\fP: As specified for the individual \fIex\fP commands. +.SS Substitute +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fBs\fP\fB[\fP\fBubstitute\fP\fB][\fP\fB/\fP\fIpattern\fP\fB/\fP\fIrepl\fP\fB/\fP\fB[\fP\fIoptions\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]]\fP\fB +.br + +\fP\fB[\fP\fI2addr\fP\fB]\fP \fB&\fP\fB[\fP\fIoptions\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]]\fP\fB +.br + +\fP\fB[\fP\fI2addr\fP\fB]\fP \fB~\fP\fB[\fP\fIoptions\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]]\fP +.fi +.RE +.sp +.LP +Replace the first instance of the pattern \fIpattern\fP by the string +\fIrepl\fP on each specified line. (See Regular Expressions in ex +and Replacement Strings in ex .) Any +non-alphabetic, non- delimiter other than \fB'\\'\fP , \fB'|'\fP +, double quote, or can be used +instead of \fB'/'\fP . Backslash characters can be used to escape +delimiters, backslash characters, and other special +characters. +.LP +The trailing delimiter can be omitted from \fIpattern\fP or from \fIrepl\fP +at the end of the command line. If both +\fIpattern\fP and \fIrepl\fP are not specified or are empty (for example, +\fB"//"\fP ), the last \fBs\fP command shall be +repeated. If only \fIpattern\fP is not specified or is empty, the +last regular expression used in the editor shall be used as the +pattern. If only \fIrepl\fP is not specified or is empty, the pattern +shall be replaced by nothing. If the entire replacement +pattern is \fB'%'\fP , the last replacement pattern to an \fBs\fP +command shall be used. +.LP +Entering a in \fIrepl\fP (which requires an escaping +backslash in \fIex\fP mode and an escaping +-V in open or \fIvi\fP mode) shall split the line at that +point, creating a new +line in the edit buffer. The shall be discarded. +.LP +If \fIoptions\fP includes the letter \fB'g'\fP ( \fBglobal\fP), all +non-overlapping instances of the pattern in the line +shall be replaced. +.LP +If \fIoptions\fP includes the letter \fB'c'\fP ( \fBconfirm\fP), then +before each substitution the line shall be written; +the written line shall reflect all previous substitutions. On the +following line, s shall be written beneath the +characters from the line that are before the \fIpattern\fP to be replaced, +and \fB'^'\fP characters written beneath the +characters included in the \fIpattern\fP to be replaced. The \fIex\fP +utility shall then wait for a response from the user. An +affirmative response shall cause the substitution to be done, while +any other input shall not make the substitution. An affirmative +response shall consist of a line with the affirmative response (as +defined by the current locale) at the beginning of the line. +This line shall be subject to editing in the same way as the \fIex\fP +command line. +.LP +If interrupted (see the ASYNCHRONOUS EVENTS section), any modifications +confirmed by the user shall be preserved in the edit +buffer after the interrupt. +.LP +If the remembered search direction is not set, the \fBs\fP command +shall set it to forward. +.LP +In the second Synopsis, the \fB&\fP command shall repeat the previous +substitution, as if the \fB&\fP command were +replaced by: +.sp +.RS +.nf + +\fBs/\fP\fIpattern\fP\fB/\fP\fIrepl\fP\fB/ +\fP +.fi +.RE +.LP +where \fIpattern\fP and \fIrepl\fP are as specified in the previous +\fBs\fP, \fB&\fP, or \fB~\fP command. +.LP +In the third Synopsis, the \fB~\fP command shall repeat the previous +substitution, as if the \fB'~'\fP were +replaced by: +.sp +.RS +.nf + +\fBs/\fP\fIpattern\fP\fB/\fP\fIrepl\fP\fB/ +\fP +.fi +.RE +.LP +where \fIpattern\fP shall be the last regular expression specified +to the editor, and \fIrepl\fP shall be from the previous +substitution (including \fB&\fP and \fB~\fP) command. +.LP +These commands shall be affected by the \fILC_MESSAGES\fP environment +variable. +.LP +\fICurrent line\fP: Set to the last line in which a substitution occurred, +or, unchanged if no substitution occurred. +.LP +\fICurrent column\fP: Set to non- . +.SS Suspend +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBsu\fP\fB[\fP\fBspend\fP\fB][\fP\fB!\fP\fB]\fP\fBst\fP\fB[\fP\fBop\fP\fB][\fP\fB!\fP\fB]\fP +.fi +.RE +.sp +.LP +Allow control to return to the invoking process; \fIex\fP shall suspend +itself as if it had received the SIGTSTP signal. The +suspension shall occur only if job control is enabled in the invoking +shell (see the description of \fIset\fP \fB-m\fP). +.LP +These commands shall be affected by the \fBautowrite\fP and \fBwriteany\fP +edit options. +.LP +The current \fBsusp\fP character (see \fIstty\fP ) shall be equivalent +to the \fBsuspend\fP +command. +.SS Tag +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBta\fP\fB[\fP\fBg\fP\fB][\fP\fB!\fP\fB]\fP \fItagstring\fP +.fi +.RE +.sp +.LP +The results are unspecified if the format of a tags file is not as +specified by the \fIctags\fP utility (see \fIctags\fP ) description. +.LP +The \fBtag\fP command shall search for \fItagstring\fP in the tag +files referred to by the \fBtag\fP edit option, in the +order they are specified, until a reference to \fItagstring\fP is +found. Files shall be searched from beginning to end. If no +reference is found, it shall be an error and an error message to this +effect shall be written. If the reference is not found, or if +an error occurs while processing a file referred to in the \fBtag\fP +edit option, it shall be an error, and an error message shall +be written at the first occurrence of such an error. +.LP +Otherwise, if the tags file contained a pattern, the pattern shall +be treated as a regular expression used in the editor; for +example, for the purposes of the \fBs\fP command. +.LP +If the \fItagstring\fP is in a file with a different name than the +current pathname, set the current pathname to the name of +that file, and replace the contents of the edit buffer with the contents +of that file. In this case, if no \fB'!'\fP is appended +to the command name, and the edit buffer has been modified since the +last complete write, it shall be an error, unless the file is +successfully written as specified by the \fBautowrite\fP option. +.LP +This command shall be affected by the \fBautowrite\fP, \fBtag\fP, +\fBtaglength\fP, and \fBwriteany\fP edit options. +.LP +\fICurrent line\fP: If the tags file contained a line number, set +to that line number. If the line number is larger than the +last line in the edit buffer, an error message shall be written and +the current line shall be set as specified for the \fBedit\fP +command. +.LP +If the tags file contained a pattern, set to the first occurrence +of the pattern in the file. If no matching pattern is found, +an error message shall be written and the current line shall be set +as specified for the \fBedit\fP command. +.LP +\fICurrent column\fP: If the tags file contained a line-number reference +and that line-number was not larger than the last line +in the edit buffer, or if the tags file contained a pattern and that +pattern was found, set to non- . Otherwise, set +as specified for the \fBedit\fP command. +.SS Unabbreviate +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBuna\fP\fB[\fP\fBbbrev\fP\fB]\fP \fIlhs\fP +.fi +.RE +.sp +.LP +If \fIlhs\fP is not an entry in the current list of abbreviations +(see Abbreviate ), it shall be +an error. Otherwise, delete \fIlhs\fP from the list of abbreviations. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Undo +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBu\fP\fB[\fP\fBndo\fP\fB]\fP +.fi +.RE +.sp +.LP +Reverse the changes made by the last command that modified the contents +of the edit buffer, including \fBundo\fP. For this +purpose, the \fBglobal\fP, \fBv\fP, \fBopen\fP, and \fBvisual\fP commands, +and commands resulting from buffer executions and +mapped character expansions, are considered single commands. +.LP +If no action that can be undone preceded the \fBundo\fP command, it +shall be an error. +.LP +If the \fBundo\fP command restores lines that were marked, the mark +shall also be restored unless it was reset subsequent to +the deletion of the lines. +.LP +\fICurrent line\fP: +.IP " 1." 4 +If lines are added or changed in the file, set to the first line added +or changed. +.LP +.IP " 2." 4 +Set to the line before the first line deleted, if it exists. +.LP +.IP " 3." 4 +Set to 1 if the edit buffer is not empty. +.LP +.IP " 4." 4 +Set to zero. +.LP +.LP +\fICurrent column\fP: Set to non- . +.SS Unmap +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBunm\fP\fB[\fP\fBap\fP\fB][\fP\fB!\fP\fB]\fP \fIlhs\fP +.fi +.RE +.sp +.LP +If \fB'!'\fP is appended to the command name, and if \fIlhs\fP is +not an entry in the list of text input mode map +definitions, it shall be an error. Otherwise, delete \fIlhs\fP from +the list of text input mode map definitions. +.LP +If no \fB'!'\fP is appended to the command name, and if \fIlhs\fP +is not an entry in the list of command mode map +definitions, it shall be an error. Otherwise, delete \fIlhs\fP from +the list of command mode map definitions. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Version +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBve\fP\fB[\fP\fBrsion\fP\fB]\fP +.fi +.RE +.sp +.LP +Write a message containing version information for the editor. The +format of the message is unspecified. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Visual +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI1addr\fP\fB]\fP \fBvi\fP\fB[\fP\fBsual\fP\fB][\fP\fItype\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP +.fi +.RE +.sp +.LP +If \fIex\fP is currently in open or visual mode, the Synopsis and +behavior of the visual command shall be the same as the +\fBedit\fP command, as specified by Edit . +.LP +Otherwise, this command need not be supported on block-mode terminals +or terminals with insufficient capabilities. If standard +input, standard output, or standard error are not terminal devices, +the results are unspecified. +.LP +If \fIcount\fP is specified, the value of the \fBwindow\fP edit option +shall be set to \fIcount\fP (as described in window ). If the \fB'^'\fP +type character was also specified, the \fBwindow\fP edit option shall +be set +before being used by the type character. +.LP +Enter visual mode. If \fItype\fP is not specified, it shall be as +if a \fItype\fP of \fB'+'\fP was specified. The +\fItype\fP shall cause the following effects: +.TP 7 +\fB+\fP +Place the beginning of the specified line at the top of the display. +.TP 7 +\fB-\fP +Place the end of the specified line at the bottom of the display. +.TP 7 +\fB\&.\fP +Place the beginning of the specified line in the middle of the display. +.TP 7 +\fB^\fP +If the specified line is less than or equal to the value of the \fBwindow\fP +edit option, set the line to 1; otherwise, +decrement the line by the value of the \fBwindow\fP edit option minus +1. Place the beginning of this line as close to the bottom +of the displayed lines as possible, while still displaying the value +of the \fBwindow\fP edit option number of lines. +.sp +.LP +\fICurrent line\fP: Set to the specified line. +.LP +\fICurrent column\fP: Set to non- . +.SS Write +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fBw\fP\fB[\fP\fBrite\fP\fB][\fP\fB!\fP\fB][\fP\fB>>\fP\fB][\fP\fIfile\fP\fB] +[\fP\fI2addr\fP\fB]\fP \fBw\fP\fB[\fP\fBrite\fP\fB][\fP\fB!\fP\fB][\fP\fIfile\fP\fB] +[\fP\fI2addr\fP\fB]\fP \fBwq\fP\fB[\fP\fB!\fP\fB][\fP\fB>>\fP\fB][\fP\fIfile\fP\fB]\fP +.fi +.RE +.sp +.LP +If no lines are specified, the lines shall default to the entire file. +.LP +The command \fBwq\fP shall be equivalent to a \fBwrite\fP command +followed by a \fBquit\fP command; \fBwq!\fP shall be +equivalent to \fBwrite!\fP followed by \fBquit\fP. In both cases, +if the \fBwrite\fP command fails, the \fBquit\fP shall not be +attempted. +.LP +If the command name is not followed by one or more s, or \fIfile\fP +is not preceded by a \fB'!'\fP character, +the \fBwrite\fP shall be to a file. +.IP " 1." 4 +If the \fB>>\fP argument is specified, and the file already exists, +the lines shall be appended to the file instead of +replacing its contents. If the \fB>>\fP argument is specified, and +the file does not already exist, it is unspecified +whether the write shall proceed as if the \fB>>\fP argument had not +been specified or if the write shall fail. +.LP +.IP " 2." 4 +If the \fBreadonly\fP edit option is set (see readonly ), the \fBwrite\fP +shall fail. +.LP +.IP " 3." 4 +If \fIfile\fP is specified, and is not the current pathname, and the +file exists, the \fBwrite\fP shall fail. +.LP +.IP " 4." 4 +If \fIfile\fP is not specified, the current pathname shall be used. +If there is no current pathname, the \fBwrite\fP command +shall fail. +.LP +.IP " 5." 4 +If the current pathname is used, and the current pathname has been +changed by the \fBfile\fP or \fBread\fP commands, and the +file exists, the \fBwrite\fP shall fail. If the \fBwrite\fP is successful, +subsequent \fBwrite\fPs shall not fail for this +reason (unless the current pathname is changed again). +.LP +.IP " 6." 4 +If the whole edit buffer is not being written, and the file to be +written exists, the \fBwrite\fP shall fail. +.LP +.LP +For rules 1., 2., 4., and 5., the \fBwrite\fP can be forced by appending +the character \fB'!'\fP to the command name. +.LP +For rules 2., 4., and 5., the \fBwrite\fP can be forced by setting +the \fBwriteany\fP edit option. +.LP +Additional, implementation-defined tests may cause the \fBwrite\fP +to fail. +.LP +If the edit buffer is empty, a file without any contents shall be +written. +.LP +An informational message shall be written noting the number of lines +and bytes written. +.LP +Otherwise, if the command is followed by one or more s, and +the file is preceded by \fB'!'\fP , the rest of the +line after the \fB'!'\fP shall have \fB'%'\fP , \fB'#'\fP , and \fB'!'\fP +characters expanded as described in Command Line Parsing in ex . +.LP +The \fIex\fP utility shall then pass two arguments to the program +named by the \fBshell\fP edit option; the first shall be +\fB-c\fP and the second shall be the expanded arguments to the \fBwrite\fP +command as a single argument. The specified lines +shall be written to the standard input of the command. The standard +error and standard output of the program, if any, shall be +written as described for the \fBprint\fP command. If the last character +in that output is not a , a +shall be written at the end of the output. +.LP +The special meaning of the \fB'!'\fP following the \fBwrite\fP command +can be overridden by escaping it with a backslash +character. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Write and Exit +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fBx\fP\fB[\fP\fBit\fP\fB][\fP\fB!\fP\fB][\fP\fIfile\fP\fB]\fP +.fi +.RE +.sp +.LP +If the edit buffer has not been modified since the last complete \fBwrite\fP, +\fBxit\fP shall be equivalent to the \fBquit\fP +command, or if a \fB'!'\fP is appended to the command name, to \fBquit!\fP. +.LP +Otherwise, \fBxit\fP shall be equivalent to the \fBwq\fP command, +or if a \fB'!'\fP is appended to the command name, to +\fBwq!\fP. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Yank +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fBya\fP\fB[\fP\fBnk\fP\fB][\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB]\fP +.fi +.RE +.sp +.LP +Copy the specified lines to the specified buffer (by default, the +unnamed buffer), which shall become a line-mode buffer. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Adjust Window +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI1addr\fP\fB]\fP \fBz\fP\fB[\fP\fB!\fP\fB][\fP\fItype\fP \fB...\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP +.fi +.RE +.sp +.LP +If no line is specified, the current line shall be the default; if +\fItype\fP is omitted as well, the current line value shall +first be incremented by 1. If incrementing the current line would +cause it to be greater than the last line in the edit buffer, it +shall be an error. +.LP +If there are s between the \fItype\fP argument and the preceding +\fBz\fP command name or optional \fB'!'\fP +character, it shall be an error. +.LP +If \fIcount\fP is specified, the value of the \fBwindow\fP edit option +shall be set to \fIcount\fP (as described in window ). If \fIcount\fP +is omitted, it shall default to 2 times the value of the \fBscroll\fP +edit +option, or if \fB!\fP was specified, the number of lines in the display +minus 1. +.LP +If \fItype\fP is omitted, then \fIcount\fP lines starting with the +specified line shall be written. Otherwise, \fIcount\fP +lines starting with the line specified by the \fItype\fP argument +shall be written. +.LP +The \fItype\fP argument shall change the lines to be written. The +possible values of \fItype\fP are as follows: +.TP 7 +\fB-\fP +The specified line shall be decremented by the following value: +.sp +.RS +.nf + +\fB(((number of "-" characters) x\fP \fIcount\fP\fB) -1) +\fP +.fi +.RE +.LP +If the calculation would result in a number less than 1, it shall +be an error. Write lines from the edit buffer, starting at the +new value of line, until \fIcount\fP lines or the last line in the +edit buffer has been written. +.TP 7 +\fB+\fP +The specified line shall be incremented by the following value: +.sp +.RS +.nf + +\fB(((number of "+" characters) -1) x\fP \fIcount\fP\fB) +1 +\fP +.fi +.RE +.LP +If the calculation would result in a number greater than the last +line in the edit buffer, it shall be an error. Write lines +from the edit buffer, starting at the new value of line, until \fIcount\fP +lines or the last line in the edit buffer has been +written. +.TP 7 +\fB=\fP,\fB.\fP +If more than a single \fB'.'\fP or \fB'='\fP is specified, it shall +be an error. The following steps shall be taken: +.RS +.IP " 1." 4 +If \fIcount\fP is zero, nothing shall be written. +.LP +.IP " 2." 4 +Write as many of the \fIN\fP lines before the current line in the +edit buffer as exist. If \fIcount\fP or \fB'!'\fP was +specified, \fIN\fP shall be: +.sp +.RS +.nf + +\fB(\fP\fIcount\fP \fB-1) /2 +\fP +.fi +.RE +.LP +Otherwise, \fIN\fP shall be: +.sp +.RS +.nf + +\fB(\fP\fIcount\fP \fB-3) /2 +\fP +.fi +.RE +.LP +If \fIN\fP is a number less than 3, no lines shall be written. +.LP +.IP " 3." 4 +If \fB'='\fP was specified as the type character, write a line consisting +of the smaller of the number of columns in the +display divided by two, or 40 \fB'-'\fP characters. +.LP +.IP " 4." 4 +Write the current line. +.LP +.IP " 5." 4 +Repeat step 3. +.LP +.IP " 6." 4 +Write as many of the \fIN\fP lines after the current line in the edit +buffer as exist. \fIN\fP shall be defined as in step 2. +If \fIN\fP is a number less than 3, no lines shall be written. If +\fIcount\fP is less than 3, no lines shall be written. +.LP +.RE +.TP 7 +\fB^\fP +The specified line shall be decremented by the following value: +.sp +.RS +.nf + +\fB(((number of "^" characters) +1) x\fP \fIcount\fP\fB) -1 +\fP +.fi +.RE +.LP +If the calculation would result in a number less than 1, it shall +be an error. Write lines from the edit buffer, starting at the +new value of line, until \fIcount\fP lines or the last line in the +edit buffer has been written. +.sp +.LP +\fICurrent line\fP: Set to the last line written, unless the type +is \fB=\fP, in which case, set to the specified line. +.LP +\fICurrent column\fP: Set to non- . +.SS Escape +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB!\fP \fIcommand +\fP\fB[\fP\fIaddr\fP\fB]\fP\fB!\fP \fIcommand\fP +.fi +.RE +.sp +.LP +The contents of the line after the \fB'!'\fP shall have \fB'%'\fP +, \fB'#'\fP , and \fB'!'\fP characters expanded as +described in Command Line Parsing in ex . If the expansion causes +the text of the line to change, it +shall be redisplayed, preceded by a single \fB'!'\fP character. +.LP +The \fIex\fP utility shall execute the program named by the \fBshell\fP +edit option. It shall pass two arguments to the +program; the first shall be \fB-c\fP, and the second shall be the +expanded arguments to the \fB!\fP command as a single +argument. +.LP +If no lines are specified, the standard input, standard output, and +standard error of the program shall be set to the standard +input, standard output, and standard error of the \fIex\fP program +when it was invoked. In addition, a warning message shall be +written if the edit buffer has been modified since the last complete +write, and the \fBwarn\fP edit option is set. +.LP +If lines are specified, they shall be passed to the program as standard +input, and the standard output and standard error of the +program shall replace those lines in the edit buffer. Each line in +the program output (as delimited by s or the end +of the output if it is not immediately preceded by a ), shall +be a separate line in the edit buffer. Any occurrences +of and pairs in the output shall be treated +as single s. The specified lines +shall be copied into the unnamed buffer before they are replaced, +and the unnamed buffer shall become a line-mode buffer. +.LP +If in \fIex\fP mode, a single \fB'!'\fP character shall be written +when the program completes. +.LP +This command shall be affected by the \fBshell\fP and \fBwarn\fP edit +options. If no lines are specified, this command shall +be affected by the \fBautowrite\fP and \fBwriteany\fP edit options. +If lines are specified, this command shall be affected by the +\fBautoprint\fP edit option. +.LP +\fICurrent line\fP: +.IP " 1." 4 +If no lines are specified, unchanged. +.LP +.IP " 2." 4 +Otherwise, set to the last line read in, if any lines are read in. +.LP +.IP " 3." 4 +Otherwise, set to the line before the first line of the lines specified, +if that line exists. +.LP +.IP " 4." 4 +Otherwise, set to the first line of the edit buffer if the edit buffer +is not empty. +.LP +.IP " 5." 4 +Otherwise, set to zero. +.LP +.LP +\fICurrent column\fP: If no lines are specified, unchanged. Otherwise, +set to non- . +.SS Shift Left +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fB<\fP\fB[\fP\fB< ...\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP +.fi +.RE +.sp +.LP +Shift the specified lines to the start of the line; the number of +column positions to be shifted shall be the number of command +characters times the value of the \fBshiftwidth\fP edit option. Only +leading s shall be deleted or changed into other +s in shifting; other characters shall not be affected. +.LP +Lines to be shifted shall be copied into the unnamed buffer, which +shall become a line-mode buffer. +.LP +This command shall be affected by the \fBautoprint\fP edit option. +.LP +\fICurrent line\fP: Set to the last line in the lines specified. +.LP +\fICurrent column\fP: Set to non- . +.SS Shift Right +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fB>\fP\fB[\fP\fB> ...\fP\fB][\fP\fIcount\fP\fB][\fP\fIflags\fP\fB]\fP +.fi +.RE +.sp +.LP +Shift the specified lines away from the start of the line; the number +of column positions to be shifted shall be the number of +command characters times the value of the \fBshiftwidth\fP edit option. +The shift shall be accomplished by adding s +as a prefix to the line or changing leading s into other s. +Empty lines shall not be changed. +.LP +Lines to be shifted shall be copied into the unnamed buffer, which +shall become a line-mode buffer. +.LP +This command shall be affected by the \fBautoprint\fP edit option. +.LP +\fICurrent line\fP: Set to the last line in the lines specified. +.LP +\fICurrent column\fP: Set to non- . +.SS -D +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB-D +\fP +.fi +.RE +.sp +.LP +Write the next \fIn\fP lines, where \fIn\fP is the minimum of the +values of the \fBscroll\fP edit option and the number of +lines after the current line in the edit buffer. If the current line +is the last line of the edit buffer it shall be an error. +.LP +\fICurrent line\fP: Set to the last line written. +.LP +\fICurrent column\fP: Set to non- . +.SS Write Line Number +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI1addr\fP\fB]\fP \fB=\fP \fB[\fP\fIflags\fP\fB]\fP +.fi +.RE +.sp +.LP +If \fIline\fP is not specified, it shall default to the last line +in the edit buffer. Write the line number of the specified +line. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Execute +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fI2addr\fP\fB]\fP \fB@\fP \fIbuffer\fP\fB[\fP\fI2addr\fP\fB]\fP \fB*\fP \fIbuffer\fP +.fi +.RE +.sp +.LP +If no buffer is specified or is specified as \fB'@'\fP or \fB'*'\fP +, the last buffer executed shall be used. If no +previous buffer has been executed, it shall be an error. +.LP +For each line specified by the addresses, set the current line ( \fB'.'\fP +) to the specified line, and execute the contents +of the named \fIbuffer\fP (as they were at the time the \fB@\fP command +was executed) as \fIex\fP commands. For each line of a +line-mode buffer, and all but the last line of a character-mode buffer, +the \fIex\fP command parser shall behave as if the line +was terminated by a . +.LP +If an error occurs during this process, or a line specified by the +addresses does not exist when the current line would be set +to it, or more than a single line was specified by the addresses, +and the contents of the edit buffer are replaced (for example, by +the \fIex\fP \fB:edit\fP command) an error message shall be written, +and no more commands resulting from the execution of this +command shall be processed. +.LP +\fICurrent line\fP: As specified for the individual \fIex\fP commands. +.LP +\fICurrent column\fP: As specified for the individual \fIex\fP commands. +.SS Regular Expressions in ex +.LP +The \fIex\fP utility shall support regular expressions that are a +superset of the basic regular expressions described in the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 9.3, Basic +Regular Expressions. A null regular expression ( \fB"//"\fP ) shall +be equivalent to the last regular expression +encountered. +.LP +Regular expressions can be used in addresses to specify lines and, +in some commands (for example, the \fBsubstitute\fP +command), to specify portions of a line to be substituted. +.LP +The following constructs can be used to enhance the basic regular +expressions: +.TP 7 +\fB\\<\fP +Match the beginning of a \fIword\fP. (See the definition of \fIword\fP +at the beginning of Command +Descriptions in ex .) +.TP 7 +\fB\\>\fP +Match the end of a \fIword\fP. +.TP 7 +\fB~\fP +Match the replacement part of the last \fBsubstitute\fP command. The +tilde ( \fB'~'\fP ) character can be escaped in a +regular expression to become a normal character with no special meaning. +The backslash shall be discarded. +.sp +.LP +When the editor option \fBmagic\fP is not set, the only characters +with special meanings shall be \fB'^'\fP at the beginning +of a pattern, \fB'$'\fP at the end of a pattern, and \fB'\\'\fP . +The characters \fB'.'\fP , \fB'*'\fP , \fB'['\fP , +and \fB'~'\fP shall be treated as ordinary characters unless preceded +by a \fB'\\'\fP ; when preceded by a \fB'\\'\fP +they shall regain their special meaning, or in the case of backslash, +be handled as a single backslash. Backslashes used to escape +other characters shall be discarded. +.SS Replacement Strings in ex +.LP +The character \fB'&'\fP ( \fB'\\&'\fP if the editor option \fBmagic\fP +is not set) in the replacement string shall +stand for the text matched by the pattern to be replaced. The character +\fB'~'\fP ( \fB'\\~'\fP if \fBmagic\fP is +not set) shall be replaced by the replacement part of the previous +\fBsubstitute\fP command. The sequence \fB'\\n'\fP , where +\fIn\fP is an integer, shall be replaced by the text matched by the +pattern enclosed in the \fIn\fPth set of parentheses +\fB'\\('\fP and \fB'\\)'\fP . +.LP +The strings \fB'\\l'\fP , \fB'\\u'\fP , \fB'\\L'\fP , and \fB'\\U'\fP +can be used to modify the case of elements in the +replacement string (using the \fB'\\&'\fP or \fB"\\"\fP digit) notation. +The string \fB'\\l'\fP ( \fB'\\u'\fP ) shall +cause the character that follows to be converted to lowercase (uppercase). +The string \fB'\\L'\fP ( \fB'\\U'\fP ) shall cause +all characters subsequent to it to be converted to lowercase (uppercase) +as they are inserted by the substitution until the string +\fB'\\e'\fP or \fB'\\E'\fP , or the end of the replacement string, +is encountered. +.LP +Otherwise, any character following a backslash shall be treated as +that literal character, and the escaping backslash shall be +discarded. +.LP +An example of case conversion with the \fBs\fP command is as follows: +.sp +.RS +.nf + +\fB:\fP\fBp +\fP\fBThe cat sat on the mat. +:\fP\fBs/\\<.at\\>/\\u&/gp +\fP\fBThe Cat Sat on the Mat. +:\fP\fBs/S\\(.*\\)M/S\\U\\1\\eM/p +\fP\fBThe Cat SAT ON THE Mat.\fP +.fi +.RE +.SS Edit Options in ex +.LP +The \fIex\fP utility has a number of options that modify its behavior. +These options have default settings, which can be +changed using the \fBset\fP command. +.LP +Options are Boolean unless otherwise specified. +.SS autoindent, ai +.LP +[Default \fIunset\fP] +.LP +If \fBautoindent\fP is set, each line in input mode shall be indented +(using first as many s as possible, as +determined by the editor option \fBtabstop\fP, and then using s) +to align with another line, as follows: +.IP " 1." 4 +If in open or visual mode and the text input is part of a line-oriented +command (see the EXTENDED DESCRIPTION in \fIvi\fP ), align to the +first column. +.LP +.IP " 2." 4 +Otherwise, if in open or visual mode, indentation for each line shall +be set as follows: +.RS +.IP " a." 4 +If a line was previously inserted as part of this command, it shall +be set to the indentation of the last inserted line by +default, or as otherwise specified for the -D character in +\fIInput Mode Commands +in vi\fP . +.LP +.IP " b." 4 +Otherwise, it shall be set to the indentation of the previous current +line, if any; otherwise, to the first column. +.LP +.RE +.LP +.IP " 3." 4 +For the \fIex\fP \fBa\fP, \fBi\fP, and \fBc\fP commands, indentation +for each line shall be set as follows: +.RS +.IP " a." 4 +If a line was previously inserted as part of this command, it shall +be set to the indentation of the last inserted line by +default, or as otherwise specified for the \fIeof\fP character in +Scroll . +.LP +.IP " b." 4 +Otherwise, if the command is the \fIex\fP \fBa\fP command, it shall +be set to the line appended after, if any; otherwise to +the first column. +.LP +.IP " c." 4 +Otherwise, if the command is the \fIex\fP \fBi\fP command, it shall +be set to the line inserted before, if any; otherwise to +the first column. +.LP +.IP " d." 4 +Otherwise, if the command is the \fIex\fP \fBc\fP command, it shall +be set to the indentation of the line replaced. +.LP +.RE +.LP +.SS autoprint, ap +.LP +[Default \fIset\fP] +.LP +If \fBautoprint\fP is set, the current line shall be written after +each \fIex\fP command that modifies the contents of the +current edit buffer, and after each \fBtag\fP command for which the +tag search pattern was found or tag line number was valid, +unless: +.IP " 1." 4 +The command was executed while in open or visual mode. +.LP +.IP " 2." 4 +The command was executed as part of a \fBglobal\fP or \fBv\fP command +or \fB@\fP buffer execution. +.LP +.IP " 3." 4 +The command was the form of the \fBread\fP command that reads a file +into the edit buffer. +.LP +.IP " 4." 4 +The command was the \fBappend\fP, \fBchange\fP, or \fBinsert\fP command. +.LP +.IP " 5." 4 +The command was not terminated by a . +.LP +.IP " 6." 4 +The current line shall be written by a flag specified to the command; +for example, \fBdelete #\fP shall write the current line +as specified for the flag modifier to the \fBdelete\fP command, and +not as specified by the \fBautoprint\fP edit option. +.LP +.SS autowrite, aw +.LP +[Default \fIunset\fP] +.LP +If \fBautowrite\fP is set, and the edit buffer has been modified since +it was last completely written to any file, the contents +of the edit buffer shall be written as if the \fIex\fP \fBwrite\fP +command had been specified without arguments, before each +command affected by the \fBautowrite\fP edit option is executed. Appending +the character \fB'!'\fP to the command name of any +of the \fIex\fP commands except \fB'!'\fP shall prevent the write. +If the write fails, it shall be an error and the command +shall not be executed. +.SS beautify, bf +.LP +[Default \fIunset\fP] +.LP +If \fBbeautify\fP is set, all non-printable characters, other than +s, s, and s, +shall be discarded from text read in from files. +.SS directory, dir +.LP +[Default \fIimplementation-defined\fP] +.LP +The value of this option specifies the directory in which the editor +buffer is to be placed. If this directory is not writable +by the user, the editor shall quit. +.SS edcompatible, ed +.LP +[Default \fIunset\fP] +.LP +Causes the presence of \fBg\fP and \fBc\fP suffixes on substitute +commands to be remembered, and toggled by repeating the +suffixes. +.SS errorbells, eb +.LP +[Default \fIunset\fP] +.LP +If the editor is in \fIex\fP mode, and the terminal does not support +a standout mode (such as inverse video), and +\fBerrorbells\fP is set, error messages shall be preceded by alerting +the terminal. +.SS exrc +.LP +[Default \fIunset\fP] +.LP +If \fBexrc\fP is set, \fIex\fP shall access any \fB.exrc\fP file in +the current directory, as described in Initialization in ex and vi +\&. If \fBexrc\fP is not set, \fIex\fP shall ignore any \fB.exrc\fP +file in the +current directory during initialization, unless the current directory +is that named by the \fIHOME\fP environment variable. +.SS ignorecase, ic +.LP +[Default \fIunset\fP] +.LP +If \fBignorecase\fP is set, characters that have uppercase and lowercase +representations shall have those representations +considered as equivalent for purposes of regular expression comparison. +.LP +The \fBignorecase\fP edit option shall affect all remembered regular +expressions; for example, unsetting the \fBignorecase\fP +edit option shall cause a subsequent \fIvi\fP \fBn\fP command to search +for the last basic +regular expression in a case-sensitive fashion. +.SS list +.LP +[Default \fIunset\fP] +.LP +If \fBlist\fP is set, edit buffer lines written while in \fIex\fP +command mode shall be written as specified for the +\fBprint\fP command with the \fBl\fP flag specified. In open or visual +mode, each edit buffer line shall be displayed as +specified for the \fIex\fP \fBprint\fP command with the \fBl\fP flag +specified. In open or visual text input mode, when the +cursor does not rest on any character in the line, it shall rest on +the \fB'$'\fP marking the end of the line. +.SS magic +.LP +[Default \fIset\fP] +.LP +If \fBmagic\fP is set, modify the interpretation of characters in +regular expressions and substitution replacement strings (see +Regular Expressions in ex and Replacement Strings in ex ). +.SS mesg +.LP +[Default \fIset\fP] +.LP +If \fBmesg\fP is set, the permission for others to use the \fBwrite\fP +or \fBtalk\fP commands to write to the terminal shall +be turned on while in open or visual mode. The shell-level command +\fImesg\fP \fBn\fP shall +take precedence over any setting of the \fIex\fP \fBmesg\fP option; +that is, if \fBmesg y\fP was issued before the editor +started (or in a shell escape), such as: +.sp +.RS +.nf + +\fB:!mesg y +\fP +.fi +.RE +.LP +the \fBmesg\fP option in \fIex\fP shall suppress incoming messages, +but the \fBmesg\fP option shall not enable incoming +messages if \fBmesg n\fP was issued. +.SS number, nu +.LP +[Default \fIunset\fP] +.LP +If \fBnumber\fP is set, edit buffer lines written while in \fIex\fP +command mode shall be written with line numbers, in the +format specified by the \fBprint\fP command with the \fB#\fP flag +specified. In \fIex\fP text input mode, each line shall be +preceded by the line number it will have in the file. +.LP +In open or visual mode, each edit buffer line shall be displayed with +a preceding line number, in the format specified by the +\fIex\fP \fBprint\fP command with the \fB#\fP flag specified. This +line number shall not be considered part of the line for the +purposes of evaluating the current column; that is, column position +1 shall be the first column position after the format specified +by the \fBprint\fP command. +.SS paragraphs, para +.LP +[Default in the POSIX locale \fBIPLPPPQPP LIpplpipbp\fP] +.LP +The \fBparagraphs\fP edit option shall define additional paragraph +boundaries for the open and visual mode commands. The +\fBparagraphs\fP edit option can be set to a character string consisting +of zero or more character pairs. It shall be an error to +set it to an odd number of characters. +.SS prompt +.LP +[Default \fIset\fP] +.LP +If \fBprompt\fP is set, \fIex\fP command mode input shall be prompted +for with a colon ( \fB':'\fP ); when unset, no prompt +shall be written. +.SS readonly +.LP +[Default \fIsee text\fP] +.LP +If the \fBreadonly\fP edit option is set, read-only mode shall be +enabled (see Write ). The +\fBreadonly\fP edit option shall be initialized to set if either of +the following conditions are true: +.IP " *" 3 +The command-line option -R was specified. +.LP +.IP " *" 3 +Performing actions equivalent to the \fIaccess\fP() function called +with the following +arguments indicates that the file lacks write permission: +.RS +.IP " 1." 4 +The current pathname is used as the \fIpath\fP argument. +.LP +.IP " 2." 4 +The constant \fBW_OK\fP is used as the \fIamode\fP argument. +.LP +.RE +.LP +.LP +The \fBreadonly\fP edit option may be initialized to set for other, +implementation-defined reasons. The \fBreadonly\fP edit +option shall not be initialized to unset based on any special privileges +of the user or process. The \fBreadonly\fP edit option +shall be reinitialized each time that the contents of the edit buffer +are replaced (for example, by an \fBedit\fP or \fBnext\fP +command) unless the user has explicitly set it, in which case it shall +remain set until the user explicitly unsets it. Once unset, +it shall again be reinitialized each time that the contents of the +edit buffer are replaced. +.SS redraw +.LP +[Default \fIunset\fP] +.LP +The editor simulates an intelligent terminal on a dumb terminal. (Since +this is likely to require a large amount of output to +the terminal, it is useful only at high transmission speeds.) +.SS remap +.LP +[Default \fIset\fP] +.LP +If \fBremap\fP is set, map translation shall allow for maps defined +in terms of other maps; translation shall continue until a +final product is obtained. If unset, only a one-step translation shall +be done. +.SS report +.LP +[Default 5] +.LP +The value of this \fBreport\fP edit option specifies what number of +lines being added, copied, deleted, or modified in the edit +buffer will cause an informational message to be written to the user. +The following conditions shall cause an informational +message. The message shall contain the number of lines added, copied, +deleted, or modified, but is otherwise unspecified. +.IP " *" 3 +An \fIex\fP or \fIvi\fP editor command, other than \fBopen\fP, \fBundo\fP, +or +\fBvisual\fP, that modifies at least the value of the \fBreport\fP +edit option number of lines, and which is not part of an +\fIex\fP \fBglobal\fP or \fBv\fP command, or \fIex\fP or \fIvi\fP +buffer execution, shall +cause an informational message to be written. +.LP +.IP " *" 3 +An \fIex\fP \fByank\fP or \fIvi\fP \fBy\fP or \fBY\fP command, that +copies at least the +value of the \fBreport\fP edit option plus 1 number of lines, and +which is not part of an \fIex\fP \fBglobal\fP or \fBv\fP +command, or \fIex\fP or \fIvi\fP buffer execution, shall cause an +informational message to be +written. +.LP +.IP " *" 3 +An \fIex\fP \fBglobal\fP, \fBv\fP, \fBopen\fP, \fBundo\fP, or \fBvisual\fP +command or \fIex\fP or \fIvi\fP buffer execution, that adds or deletes +a total of at least the value of the \fBreport\fP edit +option number of lines, and which is not part of an \fIex\fP \fBglobal\fP +or \fBv\fP command, or \fIex\fP or \fIvi\fP buffer execution, shall +cause an informational message to be written. (For example, if 3 lines +were added and 8 lines deleted during an \fIex\fP \fBvisual\fP command, +5 would be the number compared against the \fBreport\fP +edit option after the command completed.) +.LP +.SS scroll, scr +.LP +[Default (number of lines in the display -1)/2] +.LP +The value of the \fBscroll\fP edit option shall determine the number +of lines scrolled by the \fIex\fP -D and +\fBz\fP commands. For the \fIvi\fP -D and -U commands, +it shall +be the initial number of lines to scroll when no previous -D +or -U command has been executed. +.SS sections +.LP +[Default in the POSIX locale \fBNHSHH HUnhsh\fP] +.LP +The \fBsections\fP edit option shall define additional section boundaries +for the open and visual mode commands. The +\fBsections\fP edit option can be set to a character string consisting +of zero or more character pairs; it shall be an error to +set it to an odd number of characters. +.SS shell, sh +.LP +[Default from the environment variable \fISHELL ]\fP +.LP +The value of this option shall be a string. The default shall be taken +from the \fISHELL\fP environment variable. If the +\fISHELL\fP environment variable is null or empty, the \fIsh\fP (see +\fIsh\fP ) utility shall be the default. +.SS shiftwidth, sw +.LP +[Default 8] +.LP +The value of this option shall give the width in columns of an indentation +level used during autoindentation and by the shift +commands ( \fB<\fP and \fB>\fP). +.SS showmatch, sm +.LP +[Default \fIunset\fP] +.LP +The functionality described for the \fBshowmatch\fP edit option need +not be supported on block-mode terminals or terminals with +insufficient capabilities. +.LP +If \fBshowmatch\fP is set, in open or visual mode, when a \fB')'\fP +or \fB'}'\fP is typed, if the matching \fB'('\fP +or \fB'{'\fP is currently visible on the display, the matching \fB'('\fP +or \fB'{'\fP shall be flagged moving the cursor +to its location for an unspecified amount of time. +.SS showmode +.LP +[Default \fIunset\fP] +.LP +If \fBshowmode\fP is set, in open or visual mode, the current mode +that the editor is in shall be displayed on the last line of +the display. Command mode and text input mode shall be differentiated; +other unspecified modes and implementation-defined +information may be displayed. +.SS slowopen +.LP +[Default \fIunset\fP] +.LP +If \fBslowopen\fP is set during open and visual text input modes, +the editor shall not update portions of the display other +than those display line columns that display the characters entered +by the user (see \fIInput +Mode Commands in vi\fP ). +.SS tabstop, ts +.LP +[Default 8] +.LP +The value of this edit option shall specify the column boundary used +by a in the display (see autoprint, ap and \fIInput Mode Commands +in vi\fP ). +.SS taglength, tl +.LP +[Default zero] +.LP +The value of this edit option shall specify the maximum number of +characters that are considered significant in the +user-specified tag name and in the tag name from the tags file. If +the value is zero, all characters in both tag names shall be +significant. +.SS tags +.LP +[Default \fIsee text\fP] +.LP +The value of this edit option shall be a string of -delimited +pathnames of files used by the \fBtag\fP command. +The default value is unspecified. +.SS term +.LP +[Default from the environment variable \fITERM ]\fP +.LP +The value of this edit option shall be a string. The default shall +be taken from the \fITERM\fP variable in the environment. If +the \fITERM\fP environment variable is empty or null, the default +is unspecified. The editor shall use the value of this edit +option to determine the type of the display device. +.LP +The results are unspecified if the user changes the value of the term +edit option after editor initialization. +.SS terse +.LP +[Default \fIunset\fP] +.LP +If \fBterse\fP is set, error messages may be less verbose. However, +except for this caveat, error messages are unspecified. +Furthermore, not all error messages need change for different settings +of this option. +.SS warn +.LP +[Default \fIset\fP] +.LP +If \fBwarn\fP is set, and the contents of the edit buffer have been +modified since they were last completely written, the +editor shall write a warning message before certain \fB!\fP commands +(see Escape ). +.SS window +.LP +[Default \fIsee text\fP] +.LP +A value used in open and visual mode, by the -B and -F +commands, and, in visual mode, to specify +the number of lines displayed when the screen is repainted. +.LP +If the \fB-w\fP command-line option is not specified, the default +value shall be set to the value of the \fILINES\fP +environment variable. If the \fILINES\fP environment variable is empty +or null, the default shall be the number of lines in the +display minus 1. +.LP +Setting the \fBwindow\fP edit option to zero or to a value greater +than the number of lines in the display minus 1 (either +explicitly or based on the \fB-w\fP option or the \fILINES\fP environment +variable) shall cause the \fBwindow\fP edit option to +be set to the number of lines in the display minus 1. +.LP +The baud rate of the terminal line may change the default in an implementation-defined +manner. +.SS wrapmargin, wm +.LP +[Default 0] +.LP +If the value of this edit option is zero, it shall have no effect. +.LP +If not in the POSIX locale, the effect of this edit option is implementation-defined. +.LP +Otherwise, it shall specify a number of columns from the ending margin +of the terminal. +.LP +During open and visual text input modes, for each character for which +any part of the character is displayed in a column that is +less than \fBwrapmargin\fP columns from the ending margin of the display +line, the editor shall behave as follows: +.IP " 1." 4 +If the character triggering this event is a , it, and all immediately +preceding s on the current line +entered during the execution of the current text input command, shall +be discarded, and the editor shall behave as if the user had +entered a single instead. In addition, if the next user-entered +character is a , it shall be discarded +as well. +.LP +.IP " 2." 4 +Otherwise, if there are one or more s on the current line immediately +preceding the last group of inserted non- +s which was entered during the execution of the current text +input command, the s shall be replaced as if +the user had entered a single instead. +.LP +.LP +If the \fBautoindent\fP edit option is set, and the events described +in 1. or 2. are performed, any s at or after +the cursor in the current line shall be discarded. +.LP +The ending margin shall be determined by the system or overridden +by the user, as described for \fICOLUMNS\fP in the +ENVIRONMENT VARIABLES section and the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 8, Environment Variables. +.SS wrapscan, ws +.LP +[Default \fIset\fP] +.LP +If \fBwrapscan\fP is set, searches (the \fIex\fP \fB/\fP or \fB?\fP +addresses, or open and visual mode \fB/\fP, \fB?\fP, +\fBN\fP, and \fBn\fP commands) shall wrap around the beginning or +end of the edit buffer; when unset, searches shall stop at the +beginning or end of the edit buffer. +.SS writeany, wa +.LP +[Default \fIunset\fP] +.LP +If \fBwriteany\fP is set, some of the checks performed when executing +the \fIex\fP \fBwrite\fP commands shall be inhibited, +as described in editor option \fBautowrite\fP. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +When any error is encountered and the standard input is not a terminal +device file, \fIex\fP shall not write the file or return +to command or text input mode, and shall terminate with a non-zero +exit status. +.LP +Otherwise, when an unrecoverable error is encountered, it shall be +equivalent to a SIGHUP asynchronous event. +.LP +Otherwise, when an error is encountered, the editor shall behave as +specified in Command Line Parsing +in ex . +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +If a SIGSEGV signal is received while \fIex\fP is saving a file, the +file might not be successfully saved. +.LP +The \fBnext\fP command can accept more than one file, so usage such +as: +.sp +.RS +.nf + +\fBnext `ls [abc]*` +\fP +.fi +.RE +.LP +is valid; it would not be valid for the \fBedit\fP or \fBread\fP commands, +for example, because they expect only one file and +unspecified results occur. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIex\fP/ \fIvi\fP specification is based on the historical practice +found in the 4 BSD +and System V implementations of \fIex\fP and \fIvi\fP. A freely redistributable +implementation +of \fIex\fP/ \fIvi\fP, which is tracking IEEE\ Std\ 1003.1-2001 fairly +closely, and +demonstrates the intended changes between historical implementations +and IEEE\ Std\ 1003.1-2001, may be obtained by +anonymous FTP from: +.sp +.RS +.nf + +\fBftp://ftp.rdg.opengroup.org/pub/mirrors/nvi +\fP +.fi +.RE +.LP +A \fIrestricted editor\fP (both the historical \fIred\fP utility and +modifications to \fIex\fP) were considered and rejected +for inclusion. Neither option provided the level of security that +users might expect. +.LP +It is recognized that \fIex\fP visual mode and related features would +be difficult, if not impossible, to implement +satisfactorily on a block-mode terminal, or a terminal without any +form of cursor addressing; thus, it is not a mandatory +requirement that such features should work on all terminals. It is +the intention, however, that an \fIex\fP implementation should +provide the full set of capabilities on all terminals capable of supporting +them. +.SS Options +.LP +The \fB-c\fP replacement for \fB+\fP \fIcommand\fP was inspired by +the \fB-e\fP option of \fIsed\fP. Historically, all such commands +(see \fBedit\fP and \fBnext\fP as well) were executed +from the last line of the edit buffer. This meant, for example, that +\fB"+/pattern"\fP would fail unless the \fBwrapscan\fP +option was set. IEEE\ Std\ 1003.1-2001 requires conformance to historical +practice. Historically, some implementations +restricted the \fIex\fP commands that could be listed as part of the +command line arguments. For consistency, +IEEE\ Std\ 1003.1-2001 does not permit these restrictions. +.LP +In historical implementations of the editor, the \fB-R\fP option (and +the \fBreadonly\fP edit option) only prevented +overwriting of files; appending to files was still permitted, mapping +loosely into the \fIcsh\fP \fBnoclobber\fP variable. Some +implementations, however, have not followed this semantic, and \fBreadonly\fP +does not permit appending either. +IEEE\ Std\ 1003.1-2001 follows the latter practice, believing that +it is a more obvious and intuitive meaning of +\fBreadonly\fP. +.LP +The \fB-s\fP option suppresses all interactive user feedback and is +useful for editing scripts in batch jobs. The list of +specific effects is historical practice. The terminal type "incapable +of supporting open and visual modes" has historically been +named "dumb". +.LP +The \fB-t\fP option was required because the \fIctags\fP utility appears +in +IEEE\ Std\ 1003.1-2001 and the option is available in all historical +implementations of \fIex\fP. +.LP +Historically, the \fIex\fP and \fIvi\fP utilities accepted a \fB-x\fP +option, which did +encryption based on the algorithm found in the historical \fIcrypt\fP +utility. The \fB-x\fP option for encryption, and the +associated \fIcrypt\fP utility, were omitted because the algorithm +used was not specifiable and the export control laws of some +nations make it difficult to export cryptographic technology. In addition, +it did not historically provide the level of security +that users might expect. +.SS Standard Input +.LP +An end-of-file condition is not equivalent to an end-of-file character. +A common end-of-file character, -D, is +historically an \fIex\fP command. +.LP +There was no maximum line length in historical implementations of +\fIex\fP. Specifically, as it was parsed in chunks, the +addresses had a different maximum length than the filenames. Further, +the maximum line buffer size was declared as BUFSIZ, which +was different lengths on different systems. This version selected +the value of {LINE_MAX} to impose a reasonable restriction on +portable usage of \fIex\fP and to aid test suite writers in their +development of realistic tests that exercise this limit. +.SS Input Files +.LP +It was an explicit decision by the standard developers that a +be added to any file lacking one. It was believed +that this feature of \fIex\fP and \fIvi\fP was relied on by users +in order to make text files +lacking a trailing more portable. It is recognized that +this will require a user-specified option or extension for +implementations that permit \fIex\fP and \fIvi\fP to edit files of +type other than text if +such files are not otherwise identified by the system. It was agreed +that the ability to edit files of arbitrary type can be +useful, but it was not considered necessary to mandate that an \fIex\fP +or \fIvi\fP +implementation be required to handle files other than text files. +.LP +The paragraph in the INPUT FILES section, "By default, ...", is intended +to close a long-standing security problem in +\fIex\fP and \fIvi\fP; that of the "modeline" or "modelines" edit +option. This feature +allows any line in the first or last five lines of the file containing +the strings \fB"ex:"\fP or \fB"vi:"\fP (and, +apparently, \fB"ei:"\fP or \fB"vx:"\fP ) to be a line containing editor +commands, and \fIex\fP interprets all the text up to +the next \fB':'\fP or as a command. Consider the consequences, +for example, of an unsuspecting user using +\fIex\fP or \fIvi\fP as the editor when replying to a mail message +in which a line such +as: +.sp +.RS +.nf + +\fBex:! rm -rf : +\fP +.fi +.RE +.LP +appeared in the signature lines. The standard developers believed +strongly that an editor should not by default interpret any +lines of a file. Vendors are strongly urged to delete this feature +from their implementations of \fIex\fP and \fIvi\fP. +.SS Asynchronous Events +.LP +The intention of the phrase "complete write" is that the entire edit +buffer be written to stable storage. The note regarding +temporary files is intended for implementations that use temporary +files to back edit buffers unnamed by the user. +.LP +Historically, SIGQUIT was ignored by \fIex\fP, but was the equivalent +of the \fBQ\fP command in visual mode; that is, it +exited visual mode and entered \fIex\fP mode. IEEE\ Std\ 1003.1-2001 +permits, but does not require, this behavior. +Historically, SIGINT was often used by \fIvi\fP users to terminate +text input mode ( +-C is often easier to enter than ). Some implementations +of \fIvi\fP +alerted the terminal on this event, and some did not. IEEE\ Std\ 1003.1-2001 +requires that SIGINT behave identically to +, and that the terminal not be alerted. +.LP +Historically, suspending the \fIex\fP editor during text input mode +was similar to SIGINT, as completed lines were retained, +but any partial line discarded, and the editor returned to command +mode. IEEE\ Std\ 1003.1-2001 is silent on this issue; +implementations are encouraged to follow historical practice, where +possible. +.LP +Historically, the \fIvi\fP editor did not treat SIGTSTP as an asynchronous +event, and it was +therefore impossible to suspend the editor in visual text input mode. +There are two major reasons for this. The first is that +SIGTSTP is a broadcast signal on UNIX systems, and the chain of events +where the shell \fIexec\fPs an application that then \fIexec\fPs \fIvi\fP +usually caused confusion for the +terminal state if SIGTSTP was delivered to the process group in the +default manner. The second was that most implementations of the +UNIX \fIcurses\fP package are not reentrant, and the receipt of SIGTSTP +at the wrong time will cause them to crash. +IEEE\ Std\ 1003.1-2001 is silent on this issue; implementations are +encouraged to treat suspension as an asynchronous event +if possible. +.LP +Historically, modifications to the edit buffer made before SIGINT +interrupted an operation were retained; that is, anywhere from +zero to all of the lines to be modified might have been modified by +the time the SIGINT arrived. These changes were not discarded +by the arrival of SIGINT. IEEE\ Std\ 1003.1-2001 permits this behavior, +noting that the \fBundo\fP command is required to +be able to undo these partially completed commands. +.LP +The action taken for signals other than SIGINT, SIGCONT, SIGHUP, and +SIGTERM is unspecified because some implementations attempt +to save the edit buffer in a useful state when other signals are received. +.SS Standard Error +.LP +For \fIex\fP/ \fIvi\fP, diagnostic messages are those messages reported +as a result of a +failed attempt to invoke \fIex\fP or \fIvi\fP, such as invalid options +or insufficient +resources, or an abnormal termination condition. Diagnostic messages +should not be confused with the error messages generated by +inappropriate or illegal user commands. +.SS Initialization in ex and vi +.LP +If an \fIex\fP command (other than \fBcd\fP, \fBchdir\fP, or \fBsource\fP) +has a filename argument, one or both of the +alternate and current pathnames will be set. Informally, they are +set as follows: +.IP " 1." 4 +If the \fIex\fP command is one that replaces the contents of the edit +buffer, and it succeeds, the current pathname will be set +to the filename argument (the first filename argument in the case +of the \fBnext\fP command) and the alternate pathname will be +set to the previous current pathname, if there was one. +.LP +.IP " 2." 4 +In the case of the file read/write forms of the \fBread\fP and \fBwrite\fP +commands, if there is no current pathname, the +current pathname will be set to the filename argument. +.LP +.IP " 3." 4 +Otherwise, the alternate pathname will be set to the filename argument. +.LP +.LP +For example, \fB:edit foo\fP and \fB:recover foo\fP, when successful, +set the current pathname, and, if there was a previous +current pathname, the alternate pathname. The commands \fB:write\fP, +\fB!command\fP, and \fB:edit\fP set neither the current or +alternate pathnames. If the \fB:edit foo\fP command were to fail for +some reason, the alternate pathname would be set. The +\fBread\fP and \fBwrite\fP commands set the alternate pathname to +their \fIfile\fP argument, unless the current pathname is not +set, in which case they set the current pathname to their \fIfile\fP +arguments. The alternate pathname was not historically set by +the \fB:source\fP command. IEEE\ Std\ 1003.1-2001 requires conformance +to historical practice. Implementations adding +commands that take filenames as arguments are encouraged to set the +alternate pathname as described here. +.LP +Historically, \fIex\fP and \fIvi\fP read the \fB.exrc\fP file in the +\fI$HOME\fP +directory twice, if the editor was executed in the \fI$HOME\fP directory. +IEEE\ Std\ 1003.1-2001 prohibits this +behavior. +.LP +Historically, the 4 BSD \fIex\fP and \fIvi\fP read the \fI$HOME\fP +and local \fB.exrc\fP +files if they were owned by the real ID of the user, or the \fBsourceany\fP +option was set, regardless of other considerations. +This was a security problem because it is possible to put normal UNIX +system commands inside a \fB.exrc\fP file. +IEEE\ Std\ 1003.1-2001 does not specify the \fBsourceany\fP option, +and historical implementations are encouraged to +delete it. +.LP +The \fB.exrc\fP files must be owned by the real ID of the user, and +not writable by anyone other than the owner. The +appropriate privileges exception is intended to permit users to acquire +special privileges, but continue to use the \fB.exrc\fP +files in their home directories. +.LP +System V Release 3.2 and later \fIvi\fP implementations added the +option \fB[no]exrc\fP. +The behavior is that local \fB.exrc\fP files are read-only if the +\fBexrc\fP option is set. The default for the \fBexrc\fP +option was off, so by default, local \fB.exrc\fP files were not read. +The problem this was intended to solve was that System V +permitted users to give away files, so there is no possible ownership +or writeability test to ensure that the file is safe. This is +still a security problem on systems where users can give away files, +but there is nothing additional that +IEEE\ Std\ 1003.1-2001 can do. The implementation-defined exception +is intended to permit groups to have local \fB.exrc\fP +files that are shared by users, by creating pseudo-users to own the +shared files. +.LP +IEEE\ Std\ 1003.1-2001 does not mention system-wide \fIex\fP and \fIvi\fP +start-up +files. While they exist in several implementations of \fIex\fP and +\fIvi\fP, they are not +present in any implementations considered historical practice by IEEE\ Std\ 1003.1-2001. +Implementations that have such +files should use them only if they are owned by the real user ID or +an appropriate user (for example, root on UNIX systems) and if +they are not writable by any user other than their owner. System-wide +start-up files should be read before the \fIEXINIT\fP +variable, \fB$HOME/.exrc\fP, or local \fB.exrc\fP files are evaluated. +.LP +Historically, any \fIex\fP command could be entered in the \fIEXINIT\fP +variable or the \fB.exrc\fP file, although ones +requiring that the edit buffer already contain lines of text generally +caused historical implementations of the editor to drop +\fBcore\fP. IEEE\ Std\ 1003.1-2001 requires that any \fIex\fP command +be permitted in the \fIEXINIT\fP variable and +\fB\&.exrc\fP files, for simplicity of specification and consistency, +although many of them will obviously fail under many +circumstances. +.LP +The initialization of the contents of the edit buffer uses the phrase +"the effect shall be" with regard to various \fIex\fP +commands. The intent of this phrase is that edit buffer contents loaded +during the initialization phase not be lost; that is, +loading the edit buffer should fail if the \fB.exrc\fP file read in +the contents of a file and did not subsequently write the edit +buffer. An additional intent of this phrase is to specify that the +initial current line and column is set as specified for the +individual \fIex\fP commands. +.LP +Historically, the \fB-t\fP option behaved as if the tag search were +a \fB+\fP \fIcommand\fP; that is, it was executed from +the last line of the file specified by the tag. This resulted in the +search failing if the pattern was a forward search pattern and +the \fBwrapscan\fP edit option was not set. IEEE\ Std\ 1003.1-2001 +does not permit this behavior, requiring that the +search for the tag pattern be performed on the entire file, and, if +not found, that the current line be set to a more reasonable +location in the file. +.LP +Historically, the empty edit buffer presented for editing when a file +was not specified by the user was unnamed. This is +permitted by IEEE\ Std\ 1003.1-2001; however, implementations are +encouraged to provide users a temporary filename for this +buffer because it permits them the use of \fIex\fP commands that use +the current pathname during temporary edit sessions. +.LP +Historically, the file specified using the \fB-t\fP option was not +part of the current argument list. This practice is +permitted by IEEE\ Std\ 1003.1-2001; however, implementations are +encouraged to include its name in the current argument +list for consistency. +.LP +Historically, the \fB-c\fP command was generally not executed until +a file that already exists was edited. +IEEE\ Std\ 1003.1-2001 requires conformance to this historical practice. +Commands that could cause the \fB-c\fP command to +be executed include the \fIex\fP commands \fBedit\fP, \fBnext\fP, +\fBrecover\fP, \fBrewind\fP, and \fBtag\fP, and the \fIvi\fP commands +-^ and -]. Historically, reading a file into an +edit buffer did not cause the \fB-c\fP command to be executed (even +though it might set the current pathname) with the exception +that it did cause the \fB-c\fP command to be executed if: the editor +was in \fIex\fP mode, the edit buffer had no current +pathname, the edit buffer was empty, and no read commands had yet +been attempted. For consistency and simplicity of specification, +IEEE\ Std\ 1003.1-2001 does not permit this behavior. +.LP +Historically, the \fB-r\fP option was the same as a normal edit session +if there was no recovery information available for the +file. This allowed users to enter: +.sp +.RS +.nf + +\fBvi -r *.c +\fP +.fi +.RE +.LP +and recover whatever files were recoverable. In some implementations, +recovery was attempted only on the first file named, and +the file was not entered into the argument list; in others, recovery +was attempted for each file named. In addition, some +historical implementations ignored \fB-r\fP if \fB-t\fP was specified +or did not support command line \fIfile\fP arguments with +the \fB-t\fP option. For consistency and simplicity of specification, +IEEE\ Std\ 1003.1-2001 disallows these special +cases, and requires that recovery be attempted the first time each +file is edited. +.LP +Historically, \fIvi\fP initialized the \fB`\fP and \fB'\fP marks, +but \fIex\fP did not. +This meant that if the first command in \fIex\fP mode was \fBvisual\fP +or if an \fIex\fP command was executed first (for +example, \fIvi\fP +10 \fIfile\fP), \fIvi\fP was entered +without the marks being initialized. Because the standard developers +believed the marks to be generally useful, and for consistency +and simplicity of specification, IEEE\ Std\ 1003.1-2001 requires that +they always be initialized if in open or visual mode, +or if in \fIex\fP mode and the edit buffer is not empty. Not initializing +it in \fIex\fP mode if the edit buffer is empty is +historical practice; however, it has always been possible to set (and +use) marks in empty edit buffers in open and visual mode edit +sessions. +.SS Addressing +.LP +Historically, \fIex\fP and \fIvi\fP accepted the additional addressing +forms \fB'\\/'\fP +and \fB'\\?'\fP . They were equivalent to \fB"//"\fP and \fB"??"\fP +, respectively. They are not required by +IEEE\ Std\ 1003.1-2001, mostly because nobody can remember whether +they ever did anything different historically. +.LP +Historically, \fIex\fP and \fIvi\fP permitted an address of zero for +several commands, and +permitted the \fB%\fP address in empty files for others. For consistency, +IEEE\ Std\ 1003.1-2001 requires support for the +former in the few commands where it makes sense, and disallows it +otherwise. In addition, because IEEE\ Std\ 1003.1-2001 +requires that \fB%\fP be logically equivalent to \fB"1,$"\fP , it +is also supported where it makes sense and disallowed +otherwise. +.LP +Historically, the \fB%\fP address could not be followed by further +addresses. For consistency and simplicity of specification, +IEEE\ Std\ 1003.1-2001 requires that additional addresses be supported. +.LP +All of the following are valid \fIaddresses\fP: +.TP 7 +\fB+++\fP +Three lines after the current line. +.TP 7 +\fB/\fP\fIre\fP\fB/-\fP +One line before the next occurrence of \fIre\fP. +.TP 7 +\fB-2\fP +Two lines before the current line. +.TP 7 +\fB3\ ----\ 2\fP +Line one (note intermediate negative address). +.TP 7 +\fB1\ 2\ 3\fP +Line six. +.sp +.LP +Any number of addresses can be provided to commands taking addresses; +for example, \fB"1,2,3,4,5p"\fP prints lines 4 and 5, +because two is the greatest valid number of addresses accepted by +the \fBprint\fP command. This, in combination with the semicolon +delimiter, permits users to create commands based on ordered patterns +in the file. For example, the command \fB3;/foo/;+2print\fP +will display the first line after line 3 that contains the pattern +\fIfoo\fP, plus the next two lines. Note that the address +\fB3;\fP must be evaluated before being discarded because the search +origin for the \fB/foo/\fP command depends on this. +.LP +Historically, values could be added to addresses by including them +after one or more s; for example, +\fB3\ -\ 5p\fP wrote the seventh line of the file, and \fB/foo/\ 5\fP +was the same as \fB/foo/+5\fP. However, only +absolute values could be added; for example, \fB5\ /foo/\fP was an +error. IEEE\ Std\ 1003.1-2001 requires conformance +to historical practice. Address offsets are separately specified from +addresses because they could historically be provided to +visual mode search commands. +.LP +Historically, any missing addresses defaulted to the current line. +This was true for leading and trailing comma-delimited +addresses, and for trailing semicolon-delimited addresses. For consistency, +IEEE\ Std\ 1003.1-2001 requires it for leading +semicolon addresses as well. +.LP +Historically, \fIex\fP and \fIvi\fP accepted the \fB'^'\fP character +as both an address +and as a flag offset for commands. In both cases it was identical +to the \fB'-'\fP character. IEEE\ Std\ 1003.1-2001 +does not require or prohibit this behavior. +.LP +Historically, the enhancements to basic regular expressions could +be used in addressing; for example, \fB'~'\fP , +\fB'\\<'\fP , and \fB'\\>'\fP . IEEE\ Std\ 1003.1-2001 requires conformance +to historical practice; that is, that +regular expression usage be consistent, and that regular expression +enhancements be supported wherever regular expressions are +used. +.SS Command Line Parsing in ex +.LP +Historical \fIex\fP command parsing was even more complex than that +described here. IEEE\ Std\ 1003.1-2001 requires the +subset of the command parsing that the standard developers believed +was documented and that users could reasonably be expected to +use in a portable fashion, and that was historically consistent between +implementations. (The discarded functionality is obscure, +at best.) Historical implementations will require changes in order +to comply with IEEE\ Std\ 1003.1-2001; however, users +are not expected to notice any of these changes. Most of the complexity +in \fIex\fP parsing is to handle three special termination +cases: +.IP " 1." 4 +The \fB!\fP, \fBglobal\fP, \fBv\fP, and the filter versions of the +\fBread\fP and \fBwrite\fP commands are delimited by +s (they can contain vertical-line characters that are usually +shell pipes). +.LP +.IP " 2." 4 +The \fBex\fP, \fBedit\fP, \fBnext\fP, and \fBvisual\fP in open and +visual mode commands all take \fIex\fP commands, +optionally containing vertical-line characters, as their first arguments. +.LP +.IP " 3." 4 +The \fBs\fP command takes a regular expression as its first argument, +and uses the delimiting characters to delimit the +command. +.LP +.LP +Historically, vertical-line characters in the \fB+\fP \fIcommand\fP +argument of the \fBex\fP, \fBedit\fP, \fBnext\fP, +\fBvi\fP, and \fBvisual\fP commands, and in the \fIpattern\fP and +\fIreplacement\fP parts of the \fBs\fP command, did not +delimit the command, and in the filter cases for \fBread\fP and \fBwrite\fP, +and the \fB!\fP, \fBglobal\fP, and \fBv\fP +commands, they did not delimit the command at all. For example, the +following commands are all valid: +.sp +.RS +.nf + +\fB:\fP\fBedit +25 | s/abc/ABC/ file.c +\fP\fB:\fP\fBs/ | /PIPE/ +\fP\fB:\fP\fBread !spell % | columnate +\fP\fB:\fP\fBglobal/pattern/p | l +\fP\fB:\fP\fBs/a/b/ | s/c/d | set +\fP +.fi +.RE +.LP +Historically, empty or filled lines in \fB.exrc\fP files and +\fBsource\fPd files (as well as \fIEXINIT\fP +variables and \fIex\fP command scripts) were treated as default commands; +that is, \fBprint\fP commands. +IEEE\ Std\ 1003.1-2001 specifically requires that they be ignored +when encountered in \fB.exrc\fP and \fBsource\fPd files +to eliminate a common source of new user error. +.LP +Historically, \fIex\fP commands with multiple adjacent (or -separated) +vertical lines were handled oddly when +executed from \fIex\fP mode. For example, the command \fB|||\fP , +when the cursor was on line 1, displayed +lines 2, 3, and 5 of the file. In addition, the command \fB|\fP would +only display the line after the next line, instead of the +next two lines. The former worked more logically when executed from +\fIvi\fP mode, and +displayed lines 2, 3, and 4. IEEE\ Std\ 1003.1-2001 requires the \fIvi\fP +behavior; +that is, a single default command and line number increment for each +command separator, and trailing s after +vertical-line separators are discarded. +.LP +Historically, \fIex\fP permitted a single extra colon as a leading +command character; for example, \fB:g/pattern/:p\fP was a +valid command. IEEE\ Std\ 1003.1-2001 generalizes this to require +that any number of leading colon characters be +stripped. +.LP +Historically, any prefix of the \fBdelete\fP command could be followed +without intervening s by a flag character +because in the command \fBd\ p\fP, \fIp\fP is interpreted as the buffer +\fIp\fP. IEEE\ Std\ 1003.1-2001 requires +conformance to historical practice. +.LP +Historically, the \fBk\fP command could be followed by the mark name +without intervening s. +IEEE\ Std\ 1003.1-2001 requires conformance to historical practice. +.LP +Historically, the \fBs\fP command could be immediately followed by +flag and option characters; for example, +\fBs/e/E/|s|sgc3p\fP was a valid command. However, flag characters +could not stand alone; for example, the commands \fBsp\fP and +\fBs\ l\fP would fail, while the command \fBsgp\fP and \fBs\ gl\fP +would succeed. (Obviously, the \fB'#'\fP flag +character was used as a delimiter character if it followed the command.) +Another issue was that option characters had to precede +flag characters even when the command was fully specified; for example, +the command \fBs/e/E/pg\fP would fail, while the command +\fBs/e/E/gp\fP would succeed. IEEE\ Std\ 1003.1-2001 requires conformance +to historical practice. +.LP +Historically, the first command name that had a prefix matching the +input from the user was the executed command; for example, +\fBve\fP, \fBver\fP, and \fBvers\fP all executed the \fBversion\fP +command. Commands were in a specific order, however, so that +\fBa\fP matched \fBappend\fP, not \fBabbreviate\fP. IEEE\ Std\ 1003.1-2001 +requires conformance to historical practice. +The restriction on command search order for implementations with extensions +is to avoid the addition of commands such that the +historical prefixes would fail to work portably. +.LP +Historical implementations of \fIex\fP and \fIvi\fP did not correctly +handle multiple +\fIex\fP commands, separated by vertical-line characters, that entered +or exited visual mode or the editor. Because +implementations of \fIvi\fP exist that do not exhibit this failure +mode, +IEEE\ Std\ 1003.1-2001 does not permit it. +.LP +The requirement that alphabetic command names consist of all following +alphabetic characters up to the next non-alphabetic +character means that alphabetic command names must be separated from +their arguments by one or more non-alphabetic characters, +normally a or \fB'!'\fP character, except as specified for +the exceptions, the \fBdelete\fP, \fBk\fP, and +\fBs\fP commands. +.LP +Historically, the repeated execution of the \fIex\fP default \fBprint\fP +commands ( -D, \fIeof\fP, +, ) erased any prompting character and displayed +the next lines without scrolling the +terminal; that is, immediately below any previously displayed lines. +This provided a cleaner presentation of the lines in the file +for the user. IEEE\ Std\ 1003.1-2001 does not require this behavior +because it may be impossible in some situations; +however, implementations are strongly encouraged to provide this semantic +if possible. +.LP +Historically, it was possible to change files in the middle of a command, +and have the rest of the command executed in the new +file; for example: +.sp +.RS +.nf + +\fB:edit +25 file.c | s/abc/ABC/ | 1 +\fP +.fi +.RE +.LP +was a valid command, and the substitution was attempted in the newly +edited file. IEEE\ Std\ 1003.1-2001 requires +conformance to historical practice. The following commands are examples +that exercise the \fIex\fP parser: +.sp +.RS +.nf + +\fBecho 'foo | bar' > file1; echo 'foo/bar' > file2; +vi +:edit +1 | s/|/PIPE/ | w file1 | e file2 | 1 | s/\\//SLASH/ | wq +\fP +.fi +.RE +.LP +Historically, there was no protection in editor implementations to +avoid \fIex\fP \fBglobal\fP, \fBv\fP, \fB@\fP, or +\fB*\fP commands changing edit buffers during execution of their associated +commands. Because this would almost invariably result +in catastrophic failure of the editor, and implementations exist that +do exhibit these problems, IEEE\ Std\ 1003.1-2001 +requires that changing the edit buffer during a \fBglobal\fP or \fBv\fP +command, or during a \fB@\fP or \fB*\fP command for +which there will be more than a single execution, be an error. Implementations +supporting multiple edit buffers simultaneously are +strongly encouraged to apply the same semantics to switching between +buffers as well. +.LP +The \fIex\fP command quoting required by IEEE\ Std\ 1003.1-2001 is +a superset of the quoting in historical +implementations of the editor. For example, it was not historically +possible to escape a in a filename; for example, +\fB:edit\ foo\\\\\\\ bar\fP would report that too many filenames had +been entered for the edit command, and there was no +method of escaping a in the first argument of an \fBedit\fP, +\fBex\fP, \fBnext\fP, or \fBvisual\fP command at +all. IEEE\ Std\ 1003.1-2001 extends historical practice, requiring +that quoting behavior be made consistent across all +\fIex\fP commands, except for the \fBmap\fP, \fBunmap\fP, \fBabbreviate\fP, +and \fBunabbreviate\fP commands, which +historically used -V instead of backslashes for quoting. +For those four commands, IEEE\ Std\ 1003.1-2001 +requires conformance to historical practice. +.LP +Backslash quoting in \fIex\fP is non-intuitive. Backslash escapes +are ignored unless they escape a special character; for +example, when performing \fIfile\fP argument expansion, the string +\fB"\\\\%"\fP is equivalent to \fB'\\%'\fP , not +\fB"\\<\fP\fIcurrent\ pathname\fP\fB>"\fP. This can be confusing for +users because backslash is usually one of the +characters that causes shell expansion to be performed, and therefore +shell quoting rules must be taken into consideration. +Generally, quoting characters are only considered if they escape a +special character, and a quoting character must be provided for +each layer of parsing for which the character is special. As another +example, only a single backslash is necessary for the +\fB'\\l'\fP sequence in substitute replacement patterns, because the +character \fB'l'\fP is not special to any parsing layer +above it. +.LP +-V quoting in \fIex\fP is slightly different from backslash +quoting. In the four commands where +-V quoting applies ( \fBabbreviate\fP, \fBunabbreviate\fP, +\fBmap\fP, and \fBunmap\fP), any character may be +escaped by a -V whether it would have a special meaning or +not. IEEE\ Std\ 1003.1-2001 requires conformance +to historical practice. +.LP +Historical implementations of the editor did not require delimiters +within character classes to be escaped; for example, the +command \fB:s/[/]//\fP on the string \fB"xxx/yyy"\fP would delete +the \fB'/'\fP from the string. +IEEE\ Std\ 1003.1-2001 disallows this historical practice for consistency +and because it places a large burden on +implementations by requiring that knowledge of regular expressions +be built into the editor parser. +.LP +Historically, quoting s in \fIex\fP commands was handled +inconsistently. In most cases, the +always terminated the command, regardless of any preceding escape +character, because backslash characters did not escape +s for most \fIex\fP commands. However, some \fIex\fP commands +(for example, \fBs\fP, \fBmap\fP, and +\fBabbreviation\fP) permitted s to be escaped (although in +the case of \fBmap\fP and \fBabbreviation\fP, +-V characters escaped them instead of backslashes). This +was true in not only the command line, but also +\fB\&.exrc\fP and \fBsource\fPd files. For example, the command: +.sp +.RS +.nf + +\fBmap = foobar +\fP +.fi +.RE +.LP +would succeed, although it was sometimes difficult to get the -V +and the inserted passed to the +\fIex\fP parser. For consistency and simplicity of specification, +IEEE\ Std\ 1003.1-2001 requires that it be possible to +escape s in \fIex\fP commands at all times, using backslashes +for most \fIex\fP commands, and using +-V characters for the \fBmap\fP and \fBabbreviation\fP commands. +For example, the command \fBprint\fP + \fBlist\fP is required to be parsed as the single command +\fBprint\fP \fBlist\fP. While this +differs from historical practice, IEEE\ Std\ 1003.1-2001 developers +believed it unlikely that any script or user depended +on the historical behavior. +.LP +Historically, an error in a command specified using the \fB-c\fP option +did not cause the rest of the \fB-c\fP commands to be +discarded. IEEE\ Std\ 1003.1-2001 disallows this for consistency with +mapped keys, the \fB@\fP, \fBglobal\fP, +\fBsource\fP, and \fBv\fP commands, the \fIEXINIT\fP environment variable, +and the \fB.exrc\fP files. +.SS Input Editing in ex +.LP +One of the common uses of the historical \fIex\fP editor is over slow +network connections. Editors that run in canonical mode +can require far less traffic to and from, and far less processing +on, the host machine, as well as more easily supporting +block-mode terminals. For these reasons, IEEE\ Std\ 1003.1-2001 requires +that \fIex\fP be implemented using canonical mode +input processing, as was done historically. +.LP +IEEE\ Std\ 1003.1-2001 does not require the historical 4 BSD input +editing characters "word erase" or "literal +next". For this reason, it is unspecified how they are handled by +\fIex\fP, although they must have the required effect. +Implementations that resolve them after the line has been ended using +a or -M character, and +implementations that rely on the underlying system terminal support +for this processing, are both conforming. Implementations are +strongly urged to use the underlying system functionality, if at all +possible, for compatibility with other system text input +interfaces. +.LP +Historically, when the \fIeof\fP character was used to decrement the +\fBautoindent\fP level, the cursor moved to display the +new end of the \fBautoindent\fP characters, but did not move the cursor +to a new line, nor did it erase the -D +character from the line. IEEE\ Std\ 1003.1-2001 does not specify that +the cursor remain on the same line or that the rest +of the line is erased; however, implementations are strongly encouraged +to provide the best possible user interface; that is, the +cursor should remain on the same line, and any -D character +on the line should be erased. +.LP +IEEE\ Std\ 1003.1-2001 does not require the historical 4 BSD input +editing character "reprint", traditionally +-R, which redisplayed the current input from the user. For +this reason, and because the functionality cannot be +implemented after the line has been terminated by the user, IEEE\ Std\ 1003.1-2001 +makes no requirements about this +functionality. Implementations are strongly urged to make this historical +functionality available, if possible. +.LP +Historically, -Q did not perform a literal next function +in \fIex\fP, as it did in \fIvi\fP. IEEE\ Std\ 1003.1-2001 requires +conformance to historical practice to avoid breaking +historical \fIex\fP scripts and \fB.exrc\fP files. +.SS eof +.LP +Whether the \fIeof\fP character immediately modifies the \fBautoindent\fP +characters in the prompt is left unspecified so that +implementations can conform in the presence of systems that do not +support this functionality. Implementations are encouraged to +modify the line and redisplay it immediately, if possible. +.LP +The specification of the handling of the \fIeof\fP character differs +from historical practice only in that \fIeof\fP +characters are not discarded if they follow normal characters in the +text input. Historically, they were always discarded. +.SS Command Descriptions in ex +.LP +Historically, several commands (for example, \fBglobal\fP, \fBv\fP, +\fBvisual\fP, \fBs\fP, \fBwrite\fP, \fBwq\fP, +\fByank\fP, \fB!\fP, \fB<\fP, \fB>\fP, \fB&\fP, and \fB~\fP) were +executable in empty files (that is, the +default address(es) were 0), or permitted explicit addresses of 0 +(for example, 0 was a valid address, or 0,0 was a valid range). +Addresses of 0, or command execution in an empty file, make sense +only for commands that add new text to the edit buffer or write +commands (because users may wish to write empty files). IEEE\ Std\ 1003.1-2001 +requires this behavior for such commands and +disallows it otherwise, for consistency and simplicity of specification. +.LP +A count to an \fIex\fP command has been historically corrected to +be no greater than the last line in a file; for example, in a +five-line file, the command \fB1,6print\fP would fail, but the command +\fB1print300\fP would succeed. +IEEE\ Std\ 1003.1-2001 requires conformance to historical practice. +.LP +Historically, the use of flags in \fIex\fP commands could be obscure. +General historical practice was as described by +IEEE\ Std\ 1003.1-2001, but there were some special cases. For instance, +the \fBlist\fP, \fBnumber\fP, and \fBprint\fP +commands ignored trailing address offsets; for example, \fB3p\ +++#\fP +would display line 3, and 3 would be the current line +after the execution of the command. The \fBopen\fP and \fBvisual\fP +commands ignored both the trailing offsets and the trailing +flags. Also, flags specified to the \fBopen\fP and \fBvisual\fP commands +interacted badly with the \fBlist\fP edit option, and +setting and then unsetting it during the open/visual session would +cause \fIvi\fP to stop +displaying lines in the specified format. For consistency and simplicity +of specification, IEEE\ Std\ 1003.1-2001 does not +permit any of these exceptions to the general rule. +.LP +IEEE\ Std\ 1003.1-2001 uses the word \fIcopy\fP in several places +when discussing buffers. This is not intended to +imply implementation. +.LP +Historically, \fIex\fP users could not specify numeric buffers because +of the ambiguity this would cause; for example, in the +command \fB3\ delete\ 2\fP, it is unclear whether 2 is a buffer name +or a \fIcount\fP. IEEE\ Std\ 1003.1-2001 +requires conformance to historical practice by default, but does not +preclude extensions. +.LP +Historically, the contents of the unnamed buffer were frequently discarded +after commands that did not explicitly affect it; for +example, when using the \fBedit\fP command to switch files. For consistency +and simplicity of specification, +IEEE\ Std\ 1003.1-2001 does not permit this behavior. +.LP +The \fIex\fP utility did not historically have access to the numeric +buffers, and, furthermore, deleting lines in \fIex\fP did +not modify their contents. For example, if, after doing a delete in +\fIvi\fP, the user switched +to \fIex\fP, did another delete, and then switched back to \fIvi\fP, +the contents of the +numeric buffers would not have changed. IEEE\ Std\ 1003.1-2001 requires +conformance to historical practice. Numeric buffers +are described in the \fIex\fP utility in order to confine the description +of buffers to a single location in +IEEE\ Std\ 1003.1-2001. +.LP +The metacharacters that trigger shell expansion in \fIfile\fP arguments +match historical practice, as does the method for doing +shell expansion. Implementations wishing to provide users with the +flexibility to alter the set of metacharacters are encouraged to +provide a \fBshellmeta\fP string edit option. +.LP +Historically, \fIex\fP commands executed from \fIvi\fP refreshed the +screen when it did not +strictly need to do so; for example, \fB:!date\ >\ /dev/null\fP does +not require a screen refresh because the output of +the UNIX \fIdate\fP command requires only a single line of the screen. +IEEE\ Std\ 1003.1-2001 requires that the screen be refreshed if it +has been overwritten, but makes no requirements as to +how an implementation should make that determination. Implementations +may prompt and refresh the screen regardless. +.SS Abbreviate +.LP +Historical practice was that characters that were entered as part +of an abbreviation replacement were subject to \fBmap\fP +expansions, the \fBshowmatch\fP edit option, further abbreviation +expansions, and so on; that is, they were logically pushed onto +the terminal input queue, and were not a simple replacement. IEEE\ Std\ 1003.1-2001 +requires conformance to historical +practice. Historical practice was that whenever a non-word character +(that had not been escaped by a -V) was entered +after a word character, \fIvi\fP would check for abbreviations. The +check was based on the type +of the character entered before the word character of the word/non-word +pair that triggered the check. The word character of the +word/non-word pair that triggered the check and all characters entered +before the trigger pair that were of that type were included +in the check, with the exception of s, which always delimited +the abbreviation. +.LP +This means that, for the abbreviation to work, the \fIlhs\fP must +end with a word character, there can be no transitions from +word to non-word characters (or \fIvice versa\fP) other than between +the last and next-to-last characters in the \fIlhs\fP, and +there can be no s in the \fIlhs\fP. In addition, because of +the historical quoting rules, it was impossible to enter +a literal -V in the \fIlhs\fP. IEEE\ Std\ 1003.1-2001 requires +conformance to historical practice. +Historical implementations did not inform users when abbreviations +that could never be used were entered; implementations are +strongly encouraged to do so. +.LP +For example, the following abbreviations will work: +.sp +.RS +.nf + +\fB:ab (p REPLACE +:ab p REPLACE +:ab ((p REPLACE +\fP +.fi +.RE +.LP +The following abbreviations will not work: +.sp +.RS +.nf + +\fB:ab ( REPLACE +:ab (pp REPLACE +\fP +.fi +.RE +.LP +Historical practice is that words on the \fIvi\fP colon command line +were subject to +abbreviation expansion, including the arguments to the \fBabbrev\fP +(and more interestingly) the \fBunabbrev\fP command. Because +there are implementations that do not do abbreviation expansion for +the first argument to those commands, this is permitted, but +not required, by IEEE\ Std\ 1003.1-2001. However, the following sequence: +.sp +.RS +.nf + +\fB:ab foo bar +:ab foo baz +\fP +.fi +.RE +.LP +resulted in the addition of an abbreviation of \fB"baz"\fP for the +string \fB"bar"\fP in historical \fIex\fP/ \fIvi\fP, and the sequence: +.sp +.RS +.nf + +\fB:ab foo1 bar +:ab foo2 bar +:unabbreviate foo2 +\fP +.fi +.RE +.LP +deleted the abbreviation \fB"foo1"\fP , not \fB"foo2"\fP . These behaviors +are not permitted by +IEEE\ Std\ 1003.1-2001 because they clearly violate the expectations +of the user. +.LP +It was historical practice that -V, not backslash, characters +be interpreted as escaping subsequent characters in +the \fBabbreviate\fP command. IEEE\ Std\ 1003.1-2001 requires conformance +to historical practice; however, it should be +noted that an abbreviation containing a will never work. +.SS Append +.LP +Historically, any text following a vertical-line command separator +after an \fBappend\fP, \fBchange\fP, or \fBinsert\fP +command became part of the insert text. For example, in the command: +.sp +.RS +.nf + +\fB:g/pattern/append|stuff1 +\fP +.fi +.RE +.LP +a line containing the text \fB"stuff1"\fP would be appended to each +line matching pattern. It was also historically valid to +enter: +.sp +.RS +.nf + +\fB:append|stuff1 +stuff2 +\&. +\fP +.fi +.RE +.LP +and the text on the \fIex\fP command line would be appended along +with the text inserted after it. There was an historical bug, +however, that the user had to enter two terminating lines (the \fB'.'\fP +lines) to terminate text input mode in this case. +IEEE\ Std\ 1003.1-2001 requires conformance to historical practice, +but disallows the historical need for multiple +terminating lines. +.SS Change +.LP +See the RATIONALE for the \fBappend\fP command. Historical practice +for cursor positioning after the change command when no +text is input, is as described in IEEE\ Std\ 1003.1-2001. However, +one System V implementation is known to have been +modified such that the cursor is positioned on the first address specified, +and not on the line before the first address. +IEEE\ Std\ 1003.1-2001 disallows this modification for consistency. +.LP +Historically, the \fBchange\fP command did not support buffer arguments, +although some implementations allow the specification +of an optional buffer. This behavior is neither required nor disallowed +by IEEE\ Std\ 1003.1-2001. +.SS Change Directory +.LP +A common extension in \fIex\fP implementations is to use the elements +of a \fBcdpath\fP edit option as prefix directories for +\fIpath\fP arguments to \fBchdir\fP that are relative pathnames and +that do not have \fB'.'\fP or \fB".."\fP as their first +component. Elements in the \fBcdpath\fP edit option are colon-separated. +The initial value of the \fBcdpath\fP edit option is the +value of the shell \fICDPATH\fP environment variable. This feature +was not included in IEEE\ Std\ 1003.1-2001 because it +does not exist in any of the implementations considered historical +practice. +.SS Copy +.LP +Historical implementations of \fIex\fP permitted copies to lines inside +of the specified range; for example, \fB:2,5copy3\fP +was a valid command. IEEE\ Std\ 1003.1-2001 requires conformance to +historical practice. +.SS Delete +.LP +IEEE\ Std\ 1003.1-2001 requires support for the historical parsing +of a \fBdelete\fP command followed by flags, without +any intervening s. For example: +.TP 7 +\fB1dp\fP +Deletes the first line and prints the line that was second. +.TP 7 +\fB1delep\fP +As for \fB1dp\fP. +.TP 7 +\fB1d\fP +Deletes the first line, saving it in buffer \fIp\fP. +.TP 7 +\fB1d\ p1l\fP +(Pee-one-ell.) Deletes the first line, saving it in buffer \fIp\fP, +and listing the line that was second. +.sp +.SS Edit +.LP +Historically, any \fIex\fP command could be entered as a \fB+\fP \fIcommand\fP +argument to the \fBedit\fP command, although +some (for example, \fBinsert\fP and \fBappend\fP) were known to confuse +historical implementations. For consistency and +simplicity of specification, IEEE\ Std\ 1003.1-2001 requires that +any command be supported as an argument to the +\fBedit\fP command. +.LP +Historically, the command argument was executed with the current line +set to the last line of the file, regardless of whether +the \fBedit\fP command was executed from visual mode or not. IEEE\ Std\ 1003.1-2001 +requires conformance to historical +practice. +.LP +Historically, the \fB+\fP \fIcommand\fP specified to the \fBedit\fP +and \fBnext\fP commands was delimited by the first +, and there was no way to quote them. For consistency, IEEE\ Std\ 1003.1-2001 +requires that the usual +\fIex\fP backslash quoting be provided. +.LP +Historically, specifying the \fB+\fP \fIcommand\fP argument to the +edit command required a filename to be specified as well; +for example, \fB:edit\ +100\fP would always fail. For consistency +and simplicity of specification, +IEEE\ Std\ 1003.1-2001 does not permit this usage to fail for that +reason. +.LP +Historically, only the cursor position of the last file edited was +remembered by the editor. IEEE\ Std\ 1003.1-2001 +requires that this be supported; however, implementations are permitted +to remember and restore the cursor position for any file +previously edited. +.SS File +.LP +Historical versions of the \fIex\fP editor \fBfile\fP command displayed +a current line and number of lines in the edit buffer +of 0 when the file was empty, while the \fIvi\fP -G command +displayed a current +line and number of lines in the edit buffer of 1 in the same situation. +IEEE\ Std\ 1003.1-2001 does not permit this +discrepancy, instead requiring that a message be displayed indicating +that the file is empty. +.SS Global +.LP +The two-pass operation of the \fBglobal\fP and \fBv\fP commands is +not intended to imply implementation, only the required +result of the operation. +.LP +The current line and column are set as specified for the individual +\fIex\fP commands. This requirement is cumulative; that is, +the current line and column must track across all the commands executed +by the \fBglobal\fP or \fBv\fP commands. +.SS Insert +.LP +See the RATIONALE for the \fBappend\fP command. +.LP +Historically, \fBinsert\fP could not be used with an address of zero; +that is, not when the edit buffer was empty. +IEEE\ Std\ 1003.1-2001 requires that this command behave consistently +with the \fBappend\fP command. +.SS Join +.LP +The action of the \fBjoin\fP command in relation to the special characters +is only defined for the POSIX locale because the +correct amount of white space after a period varies; in Japanese none +is required, in French only a single space, and so on. +.SS List +.LP +The historical output of the \fBlist\fP command was potentially ambiguous. +The standard developers believed correcting this to +be more important than adhering to historical practice, and IEEE\ Std\ 1003.1-2001 +requires unambiguous output. +.SS Map +.LP +Historically, command mode maps only applied to command names; for +example, if the character \fB'x'\fP was mapped to +\fB'y'\fP , the command \fBfx\fP searched for the \fB'x'\fP character, +not the \fB'y'\fP character. +IEEE\ Std\ 1003.1-2001 requires this behavior. Historically, entering +-V as the first character of a \fIvi\fP command was an error. +Several implementations have extended the semantics of \fIvi\fP such +that -V means that the subsequent command character is not +mapped. This is +permitted, but not required, by IEEE\ Std\ 1003.1-2001. Regardless, +using -V to escape the second or later +character in a sequence of characters that might match a \fBmap\fP +command, or any character in text input mode, is historical +practice, and stops the entered keys from matching a map. IEEE\ Std\ 1003.1-2001 +requires conformance to historical +practice. +.LP +Historical implementations permitted digits to be used as a \fBmap\fP +command \fIlhs\fP, but then ignored the map. +IEEE\ Std\ 1003.1-2001 requires that the mapped digits not be ignored. +.LP +The historical implementation of the \fBmap\fP command did not permit +\fBmap\fP commands that were more than a single +character in length if the first character was printable. This behavior +is permitted, but not required, by +IEEE\ Std\ 1003.1-2001. +.LP +Historically, mapped characters were remapped unless the \fBremap\fP +edit option was not set, or the prefix of the mapped +characters matched the mapping characters; for example, in the \fBmap\fP: +.sp +.RS +.nf + +\fB:map ab abcd +\fP +.fi +.RE +.LP +the characters \fB"ab"\fP were used as is and were not remapped, but +the characters \fB"cd"\fP were mapped if appropriate. +This can cause infinite loops in the \fIvi\fP mapping mechanisms. +IEEE\ Std\ 1003.1-2001 requires conformance to historical practice, +and that such loops be interruptible. +.LP +Text input maps had the same problems with expanding the \fIlhs\fP +for the \fIex\fP \fBmap!\fP and \fBunmap!\fP command as +did the \fIex\fP \fBabbreviate\fP and \fBunabbreviate\fP commands. +See the RATIONALE for the \fIex\fP \fBabbreviate\fP +command. IEEE\ Std\ 1003.1-2001 requires similar modification of some +historical practice for the \fBmap\fP and +\fBunmap\fP commands, as described for the \fBabbreviate\fP and \fBunabbreviate\fP +commands. +.LP +Historically, \fBmap\fPs that were subsets of other \fBmap\fPs behaved +differently depending on the order in which they were +defined. For example: +.sp +.RS +.nf + +\fB:map! ab short +:map! abc long +\fP +.fi +.RE +.LP +would always translate the characters \fB"ab"\fP to \fB"short"\fP +, regardless of how fast the characters \fB"abc"\fP +were entered. If the entry order was reversed: +.sp +.RS +.nf + +\fB:map! abc long +:map! ab short +\fP +.fi +.RE +.LP +the characters \fB"ab"\fP would cause the editor to pause, waiting +for the completing \fB'c'\fP character, and the +characters might never be mapped to \fB"short"\fP . For consistency +and simplicity of specification, +IEEE\ Std\ 1003.1-2001 requires that the shortest match be used at +all times. +.LP +The length of time the editor spends waiting for the characters to +complete the \fIlhs\fP is unspecified because the timing +capabilities of systems are often inexact and variable, and it may +depend on other factors such as the speed of the connection. The +time should be long enough for the user to be able to complete the +sequence, but not long enough for the user to have to wait. Some +implementations of \fIvi\fP have added a \fBkeytime\fP option, which +permits users to set the +number of 0,1 seconds the editor waits for the completing characters. +Because mapped terminal function and cursor keys tend to +start with an character, and is the key ending \fIvi\fP +text input +mode, \fBmap\fPs starting with characters are generally exempted +from this timeout period, or, at least timed out +differently. +.SS Mark +.LP +Historically, users were able to set the "previous context" marks +explicitly. In addition, the \fIex\fP commands \fB"\fP +and \fB'`\fP and the \fIvi\fP commands \fB"\fP, \fB``\fP, \fB`'\fP, +and \fB'`\fP all +referred to the same mark. In addition, the previous context marks +were not set if the command, with which the address setting the +mark was associated, failed. IEEE\ Std\ 1003.1-2001 requires conformance +to historical practice. Historically, if marked +lines were deleted, the mark was also deleted, but would reappear +if the change was undone. IEEE\ Std\ 1003.1-2001 requires +conformance to historical practice. +.LP +The description of the special events that set the \fB`\fP and \fB'\fP +marks matches historical practice. For example, +historically the command \fB/a/,/b/\fP did not set the \fB`\fP and +\fB'\fP marks, but the command \fB/a/,/b/delete\fP did. +.SS Next +.LP +Historically, any \fIex\fP command could be entered as a \fB+\fP \fIcommand\fP +argument to the \fBnext\fP command, although +some (for example, \fBinsert\fP and \fBappend\fP) were known to confuse +historical implementations. +IEEE\ Std\ 1003.1-2001 requires that any command be permitted and +that it behave as specified. The \fBnext\fP command can +accept more than one file, so usage such as: +.sp +.RS +.nf + +\fBnext `ls [abc] ` +\fP +.fi +.RE +.LP +is valid; it need not be valid for the \fBedit\fP or \fBread\fP commands, +for example, because they expect only one +filename. +.LP +Historically, the \fBnext\fP command behaved differently from the +\fB:rewind\fP command in that it ignored the force flag if +the \fBautowrite\fP flag was set. For consistency, IEEE\ Std\ 1003.1-2001 +does not permit this behavior. +.LP +Historically, the \fBnext\fP command positioned the cursor as if the +file had never been edited before, regardless. +IEEE\ Std\ 1003.1-2001 does not permit this behavior, for consistency +with the \fBedit\fP command. +.LP +Implementations wanting to provide a counterpart to the \fBnext\fP +command that edited the previous file have used the command +\fBprev[ious],\fP which takes no \fIfile\fP argument. IEEE\ Std\ 1003.1-2001 +does not require this command. +.SS Open +.LP +Historically, the \fBopen\fP command would fail if the \fBopen\fP +edit option was not set. IEEE\ Std\ 1003.1-2001 does +not mention the \fBopen\fP edit option and does not require this behavior. +Some historical implementations do not permit entering +open mode from open or visual mode, only from \fIex\fP mode. For consistency, +IEEE\ Std\ 1003.1-2001 does not permit this +behavior. +.LP +Historically, entering open mode from the command line (that is, \fIvi\fP +\fB+open\fP) +resulted in anomalous behaviors; for example, the \fIex\fP file and +\fIset\fP +commands, and the \fIvi\fP command -G did not work. For consistency, +IEEE\ Std\ 1003.1-2001 does not permit this behavior. +.LP +Historically, the \fBopen\fP command only permitted \fB'/'\fP characters +to be used as the search pattern delimiter. For +consistency, IEEE\ Std\ 1003.1-2001 requires that the search delimiters +used by the \fBs\fP, \fBglobal\fP, and \fBv\fP +commands be accepted as well. +.SS Preserve +.LP +The \fBpreserve\fP command does not historically cause the file to +be considered unmodified for the purposes of future commands +that may exit the editor. IEEE\ Std\ 1003.1-2001 requires conformance +to historical practice. +.LP +Historical documentation stated that mail was not sent to the user +when preserve was executed; however, historical +implementations did send mail in this case. IEEE\ Std\ 1003.1-2001 +requires conformance to the historical +implementations. +.SS Print +.LP +The writing of NUL by the \fBprint\fP command is not specified as +a special case because the standard developers did not want +to require \fIex\fP to support NUL characters. Historically, characters +were displayed using the ARPA standard mappings, which are +as follows: +.IP " 1." 4 +Printable characters are left alone. +.LP +.IP " 2." 4 +Control characters less than \\177 are represented as \fB'^'\fP followed +by the character offset from the \fB'@'\fP +character in the ASCII map; for example, \\007 is represented as \fB'^G'\fP +\&. +.LP +.IP " 3." 4 +\\177 is represented as \fB'^'\fP followed by \fB'?'\fP . +.LP +.LP +The display of characters having their eighth bit set was less standard. +Existing implementations use hex (0x00), octal (\\000), +and a meta-bit display. (The latter displayed bytes that had their +eighth bit set as the two characters \fB"M-"\fP followed by +the seven-bit display as described above.) The latter probably has +the best claim to historical practice because it was used for +the \fB-v\fP option of 4 BSD and 4 BSD-derived versions of the \fIcat\fP +utility since +1980. +.LP +No specific display format is required by IEEE\ Std\ 1003.1-2001. +.LP +Explicit dependence on the ASCII character set has been avoided where +possible, hence the use of the phrase an +"implementation-defined multi-character sequence" for the display +of non-printable characters in preference to the historical +usage of, for instance, \fB"^I"\fP for the . Implementations +are encouraged to conform to historical practice in the +absence of any strong reason to diverge. +.LP +Historically, all \fIex\fP commands beginning with the letter \fB'p'\fP +could be entered using capitalized versions of the +commands; for example, \fBP[rint]\fP, \fBPre[serve]\fP, and \fBPu[t]\fP +were all valid command names. +IEEE\ Std\ 1003.1-2001 permits, but does not require, this historical +practice because capital forms of the commands are +used by some implementations for other purposes. +.SS Put +.LP +Historically, an \fIex\fP \fBput\fP command, executed from open or +visual mode, was the same as the open or visual mode +\fBP\fP command, if the buffer was named and was cut in character +mode, and the same as the \fBp\fP command if the buffer was +named and cut in line mode. If the unnamed buffer was the source of +the text, the entire line from which the text was taken was +usually \fBput\fP, and the buffer was handled as if in line mode, +but it was possible to get extremely anomalous behavior. In +addition, using the \fBQ\fP command to switch into \fIex\fP mode, +and then doing a \fBput\fP often resulted in errors as well, +such as appending text that was unrelated to the (supposed) contents +of the buffer. For consistency and simplicity of +specification, IEEE\ Std\ 1003.1-2001 does not permit these behaviors. +All \fIex\fP \fBput\fP commands are required to +operate in line mode, and the contents of the buffers are not altered +by changing the mode of the editor. +.SS Read +.LP +Historically, an \fIex\fP \fBread\fP command executed from open or +visual mode, executed in an empty file, left an empty line +as the first line of the file. For consistency and simplicity of specification, +IEEE\ Std\ 1003.1-2001 does not permit this +behavior. Historically, a \fBread\fP in open or visual mode from a +program left the cursor at the last line read in, not the +first. For consistency, IEEE\ Std\ 1003.1-2001 does not permit this +behavior. +.LP +Historical implementations of \fIex\fP were unable to undo \fBread\fP +commands that read from the output of a program. For +consistency, IEEE\ Std\ 1003.1-2001 does not permit this behavior. +.LP +Historically, the \fIex\fP and \fIvi\fP message after a successful +\fBread\fP or +\fBwrite\fP command specified "characters", not "bytes". IEEE\ Std\ 1003.1-2001 +requires that the number of bytes be +displayed, not the number of characters, because it may be difficult +in multi-byte implementations to determine the number of +characters read. Implementations are encouraged to clarify the message +displayed to the user. +.LP +Historically, reads were not permitted on files other than type regular, +except that FIFO files could be read (probably only +because they did not exist when \fIex\fP and \fIvi\fP were originally +written). Because the +historical \fIex\fP evaluated \fBread!\fP and \fBread\ !\fP equivalently, +there can be no optional way to force the read. +IEEE\ Std\ 1003.1-2001 permits, but does not require, this behavior. +.SS Recover +.LP +Some historical implementations of the editor permitted users to recover +the edit buffer contents from a previous edit session, +and then exit without saving those contents (or explicitly discarding +them). The intent of IEEE\ Std\ 1003.1-2001 in +requiring that the edit buffer be treated as already modified is to +prevent this user error. +.SS Rewind +.LP +Historical implementations supported the \fBrewind\fP command when +the user was editing the first file in the list; that is, +the file that the \fBrewind\fP command would edit. IEEE\ Std\ 1003.1-2001 +requires conformance to historical practice. +.SS Substitute +.LP +Historically, \fIex\fP accepted an \fBr\fP option to the \fBs\fP command. +The effect of the \fBr\fP option was to use the +last regular expression used in any command as the pattern, the same +as the \fB~\fP command. The \fBr\fP option is not +required by IEEE\ Std\ 1003.1-2001. Historically, the \fBc\fP and +\fBg\fP options were toggled; for example, the command +\fB:s/abc/def/\fP was the same as \fBs/abc/def/ccccgggg\fP. For simplicity +of specification, IEEE\ Std\ 1003.1-2001 does +not permit this behavior. +.LP +The tilde command is often used to replace the last search RE. For +example, in the sequence: +.sp +.RS +.nf + +\fBs/red/blue/ +/green +~ +\fP +.fi +.RE +.LP +the \fB~\fP command is equivalent to: +.sp +.RS +.nf + +\fBs/green/blue/ +\fP +.fi +.RE +.LP +Historically, \fIex\fP accepted all of the following forms: +.sp +.RS +.nf + +\fBs/abc/def/ +s/abc/def +s/abc/ +s/abc +\fP +.fi +.RE +.LP +IEEE\ Std\ 1003.1-2001 requires conformance to this historical practice. +.LP +The \fBs\fP command presumes that the \fB'^'\fP character only occupies +a single column in the display. Much of the +\fIex\fP and \fIvi\fP specification presumes that the only +occupies a single +column in the display. There are no known character sets for which +this is not true. +.LP +Historically, the final column position for the substitute commands +was based on previous column movements; a search for a +pattern followed by a substitution would leave the column position +unchanged, while a 0 command followed by a substitution would +change the column position to the first non- . For consistency +and simplicity of specification, +IEEE\ Std\ 1003.1-2001 requires that the final column position always +be set to the first non- . +.SS Set +.LP +Historical implementations redisplayed all of the options for each +occurrence of the \fBall\fP keyword. +IEEE\ Std\ 1003.1-2001 permits, but does not require, this behavior. +.SS Tag +.LP +No requirement is made as to where \fIex\fP and \fIvi\fP shall look +for the file referenced +by the tag entry. Historical practice has been to look for the path +found in the \fBtags\fP file, based on the current directory. +A useful extension found in some implementations is to look based +on the directory containing the tags file that held the entry, as +well. No requirement is made as to which reference for the tag in +the tags file is used. This is deliberate, in order to permit +extensions such as multiple entries in a tags file for a tag. +.LP +Because users often specify many different tags files, some of which +need not be relevant or exist at any particular time, +IEEE\ Std\ 1003.1-2001 requires that error messages about problem +tags files be displayed only if the requested tag is not +found, and then, only once for each time that the \fBtag\fP edit option +is changed. +.LP +The requirement that the current edit buffer be unmodified is only +necessary if the file indicated by the tag entry is not the +same as the current file (as defined by the current pathname). Historically, +the file would be reloaded if the filename had +changed, as well as if the filename was different from the current +pathname. For consistency and simplicity of specification, +IEEE\ Std\ 1003.1-2001 does not permit this behavior, requiring that +the name be the only factor in the decision. +.LP +Historically, \fIvi\fP only searched for tags in the current file +from the current cursor to +the end of the file, and therefore, if the \fBwrapscan\fP option was +not set, tags occurring before the current cursor were not +found. IEEE\ Std\ 1003.1-2001 considers this a bug, and implementations +are required to search for the first occurrence in +the file, regardless. +.SS Undo +.LP +The \fBundo\fP description deliberately uses the word "modified". +The \fBundo\fP command is not intended to undo commands +that replace the contents of the edit buffer, such as \fBedit\fP, +\fBnext\fP, \fBtag\fP, or \fBrecover\fP. +.LP +Cursor positioning after the \fBundo\fP command was inconsistent in +the historical \fIvi\fP, sometimes attempting to restore the original +cursor position ( \fBglobal\fP, \fBundo\fP, +and \fBv\fP commands), and sometimes, in the presence of maps, placing +the cursor on the last line added or changed instead of the +first. IEEE\ Std\ 1003.1-2001 requires a simplified behavior for consistency +and simplicity of specification. +.SS Version +.LP +The \fBversion\fP command cannot be exactly specified since there +is no widely-accepted definition of what the version +information should contain. Implementations are encouraged to do something +reasonably intelligent. +.SS Write +.LP +Historically, the \fIex\fP and \fIvi\fP message after a successful +\fBread\fP or +\fBwrite\fP command specified "characters", not "bytes". IEEE\ Std\ 1003.1-2001 +requires that the number of bytes be +displayed, not the number of characters because it may be difficult +in multi-byte implementations to determine the number of +characters written. Implementations are encouraged to clarify the +message displayed to the user. +.LP +Implementation-defined tests are permitted so that implementations +can make additional checks; for example, for locks or file +modification times. +.LP +Historically, attempting to append to a nonexistent file caused an +error. It has been left unspecified in +IEEE\ Std\ 1003.1-2001 to permit implementations to let the \fBwrite\fP +succeed, so that the append semantics are similar +to those of the historical \fIcsh\fP. +.LP +Historical \fIvi\fP permitted empty edit buffers to be written. However, +since the way \fIvi\fP got around dealing with "empty" files was to +always have a line in the edit buffer, no +matter what, it wrote them as files of a single, empty line. IEEE\ Std\ 1003.1-2001 +does not permit this behavior. +.LP +Historically, \fIex\fP restored standard output and standard error +to their values as of when \fIex\fP was invoked, before +writes to programs were performed. This could disturb the terminal +configuration as well as be a security issue for some terminals. +IEEE\ Std\ 1003.1-2001 does not permit this, requiring that the program +output be captured and displayed as if by the +\fIex\fP \fBprint\fP command. +.SS Adjust Window +.LP +Historically, the line count was set to the value of the \fBscroll\fP +option if the type character was end-of-file. This +feature was broken on most historical implementations long ago, however, +and is not documented anywhere. For this reason, +IEEE\ Std\ 1003.1-2001 is resolutely silent. +.LP +Historically, the \fBz\fP command was -sensitive and \fBz\ +\fP +and \fBz\ -\fP did different things than +\fBz+\fP and \fBz-\fP because the type could not be distinguished +from a flag. (The commands \fBz\ .\fP and \fBz\ =\fP +were historically invalid.) IEEE\ Std\ 1003.1-2001 requires conformance +to this historical practice. +.LP +Historically, the \fBz\fP command was further -sensitive in +that the \fIcount\fP could not be +-delimited; for example, the commands \fBz=\ 5\fP and \fBz-\ 5\fP +were also invalid. Because the +\fIcount\fP is not ambiguous with respect to either the type character +or the flags, this is not permitted by +IEEE\ Std\ 1003.1-2001. +.SS Escape +.LP +Historically, \fIex\fP filter commands only read the standard output +of the commands, letting standard error appear on the +terminal as usual. The \fIvi\fP utility, however, read both standard +output and standard error. +IEEE\ Std\ 1003.1-2001 requires the latter behavior for both \fIex\fP +and \fIvi\fP, +for consistency. +.SS Shift Left and Shift Right +.LP +Historically, it was possible to add shift characters to increase +the effect of the command; for example, \fB<<<\fP +outdented (or \fB>>>\fP indented) the lines 3 levels of indentation +instead of the default 1. +IEEE\ Std\ 1003.1-2001 requires conformance to historical practice. +.SS -D +.LP +Historically, the -D command erased the prompt, providing +the user with an unbroken presentation of lines from +the edit buffer. This is not required by IEEE\ Std\ 1003.1-2001; implementations +are encouraged to provide it if possible. +Historically, the -D command took, and then ignored, a \fIcount\fP. +IEEE\ Std\ 1003.1-2001 does not permit +this behavior. +.SS Write Line Number +.LP +Historically, the \fIex\fP \fB=\fP command, when executed in \fIex\fP +mode in an empty edit buffer, reported 0, and from open +or visual mode, reported 1. For consistency and simplicity of specification, +IEEE\ Std\ 1003.1-2001 does not permit this +behavior. +.SS Execute +.LP +Historically, \fIex\fP did not correctly handle the inclusion of text +input commands (that is, \fBappend\fP, \fBinsert\fP, +and \fBchange\fP) in executed buffers. IEEE\ Std\ 1003.1-2001 does +not permit this exclusion for consistency. +.LP +Historically, the logical contents of the buffer being executed did +not change if the buffer itself were modified by the +commands being executed; that is, buffer execution did not support +self-modifying code. IEEE\ Std\ 1003.1-2001 requires +conformance to historical practice. +.LP +Historically, the \fB@\fP command took a range of lines, and the \fB@\fP +buffer was executed once per line, with the current +line ( \fB'.'\fP ) set to each specified line. IEEE\ Std\ 1003.1-2001 +requires conformance to historical practice. +.LP +Some historical implementations did not notice if errors occurred +during buffer execution. This, coupled with the ability to +specify a range of lines for the \fIex\fP \fB@\fP command, makes it +trivial to cause them to drop \fBcore\fP. +IEEE\ Std\ 1003.1-2001 requires that implementations stop buffer execution +if any error occurs, if the specified line +doesn't exist, or if the contents of the edit buffer itself are replaced +(for example, the buffer executes the \fIex\fP +\fB:edit\fP command). +.SS Regular Expressions in ex +.LP +Historical practice is that the characters in the replacement part +of the last \fBs\fP command-that is, those matched by +entering a \fB'~'\fP in the regular expression-were not further expanded +by the regular expression engine. So, if the +characters contained the string \fB"a.,"\fP they would match \fB'a'\fP +followed by \fB".,"\fP and not \fB'a'\fP +followed by any character. IEEE\ Std\ 1003.1-2001 requires conformance +to historical practice. +.SS Edit Options in ex +.LP +The following paragraphs describe the historical behavior of some +edit options that were not, for whatever reason, included in +IEEE\ Std\ 1003.1-2001. Implementations are strongly encouraged to +only use these names if the functionality described here +is fully supported. +.TP 7 +\fBextended\fP +The \fBextended\fP edit option has been used in some implementations +of \fIvi\fP to +provide extended regular expressions instead of basic regular expressions +This option was omitted from +IEEE\ Std\ 1003.1-2001 because it is not widespread historical practice. +.TP 7 +\fBflash\fP +The \fBflash\fP edit option historically caused the screen to flash +instead of beeping on error. This option was omitted from +IEEE\ Std\ 1003.1-2001 because it is not found in some historical +implementations. +.TP 7 +\fBhardtabs\fP +The \fBhardtabs\fP edit option historically defined the number of +columns between hardware tab settings. This option was +omitted from IEEE\ Std\ 1003.1-2001 because it was believed to no +longer be generally useful. +.TP 7 +\fBmodeline\fP +The \fBmodeline\fP (sometimes named \fBmodelines\fP) edit option historically +caused \fIex\fP or \fIvi\fP to read the five first and last lines +of the file for editor commands. This option is a +security problem, and vendors are strongly encouraged to delete it +from historical implementations. +.TP 7 +\fBopen\fP +The \fBopen\fP edit option historically disallowed the \fIex\fP \fBopen\fP +and \fBvisual\fP commands. This edit option was +omitted because these commands are required by IEEE\ Std\ 1003.1-2001. +.TP 7 +\fBoptimize\fP +The \fBoptimize\fP edit option historically expedited text throughput +by setting the terminal to not do automatic +s when printing more than one logical line of output. +This option was omitted from +IEEE\ Std\ 1003.1-2001 because it was intended for terminals without +addressable cursors, which are rarely, if ever, still +used. +.TP 7 +\fBruler\fP +The \fBruler\fP edit option has been used in some implementations +of \fIvi\fP to present a +current row/column ruler for the user. This option was omitted from +IEEE\ Std\ 1003.1-2001 because it is not widespread +historical practice. +.TP 7 +\fBsourceany\fP +The \fBsourceany\fP edit option historically caused \fIex\fP or \fIvi\fP +to source +start-up files that were owned by users other than the user running +the editor. This option is a security problem, and vendors are +strongly encouraged to remove it from their implementations. +.TP 7 +\fBtimeout\fP +The \fBtimeout\fP edit option historically enabled the (now standard) +feature of only waiting for a short period before +returning keys that could be part of a macro. This feature was omitted +from IEEE\ Std\ 1003.1-2001 because its behavior is +now standard, it is not widely useful, and it was rarely documented. +.TP 7 +\fBverbose\fP +The \fBverbose\fP edit option has been used in some implementations +of \fIvi\fP to cause +\fIvi\fP to output error messages for common errors; for example, +attempting to move the cursor +past the beginning or end of the line instead of only alerting the +screen. (The historical \fIvi\fP only alerted the terminal and presented +no message for such errors. The historical editor +option \fBterse\fP did not select when to present error messages, +it only made existing error messages more or less verbose.) This +option was omitted from IEEE\ Std\ 1003.1-2001 because it is not widespread +historical practice; however, implementors are +encouraged to use it if they wish to provide error messages for naive +users. +.TP 7 +\fBwraplen\fP +The \fBwraplen\fP edit option has been used in some implementations +of \fIvi\fP to specify +an automatic margin measured from the left margin instead of from +the right margin. This is useful when multiple screen sizes are +being used to edit a single file. This option was omitted from IEEE\ Std\ 1003.1-2001 +because it is not widespread +historical practice; however, implementors are encouraged to use it +if they add this functionality. +.sp +.SS autoindent, ai +.LP +Historically, the command \fB0a\fP did not do any autoindentation, +regardless of the current indentation of line 1. +IEEE\ Std\ 1003.1-2001 requires that any indentation present in line +1 be used. +.SS autoprint, ap +.LP +Historically, the \fBautoprint\fP edit option was not completely consistent +or based solely on modifications to the edit +buffer. Exceptions were the \fBread\fP command (when reading from +a file, but not from a filter), the \fBappend\fP, +\fBchange\fP, \fBinsert\fP, \fBglobal\fP, and \fBv\fP commands, all +of which were not affected by \fBautoprint\fP, and the +\fBtag\fP command, which was affected by \fBautoprint\fP. IEEE\ Std\ 1003.1-2001 +requires conformance to historical +practice. +.LP +Historically, the \fBautoprint\fP option only applied to the last +of multiple commands entered using vertical-bar delimiters; +for example, \fBdelete\fP was affected by \fBautoprint\fP, +but \fBdelete|version\fP was not. +IEEE\ Std\ 1003.1-2001 requires conformance to historical practice. +.SS autowrite, aw +.LP +Appending the \fB'!'\fP character to the \fIex\fP \fBnext\fP command +to avoid performing an automatic write was not +supported in historical implementations. IEEE\ Std\ 1003.1-2001 requires +that the behavior match the other \fIex\fP +commands for consistency. +.SS ignorecase, ic +.LP +Historical implementations of case-insensitive matching (the \fBignorecase\fP +edit option) lead to counterintuitive situations +when uppercase characters were used in range expressions. Historically, +the process was as follows: +.IP " 1." 4 +Take a line of text from the edit buffer. +.LP +.IP " 2." 4 +Convert uppercase to lowercase in text line. +.LP +.IP " 3." 4 +Convert uppercase to lowercase in regular expressions, except in character +class specifications. +.LP +.IP " 4." 4 +Match regular expressions against text. +.LP +.LP +This would mean that, with \fBignorecase\fP in effect, the text: +.sp +.RS +.nf + +\fBThe cat sat on the mat +\fP +.fi +.RE +.LP +would be matched by +.sp +.RS +.nf + +\fB/^the/ +\fP +.fi +.RE +.LP +but not by: +.sp +.RS +.nf + +\fB/^[A-Z]he/ +\fP +.fi +.RE +.LP +For consistency with other commands implementing regular expressions, +IEEE\ Std\ 1003.1-2001 does not permit this +behavior. +.SS paragraphs, para +.LP +The ISO\ POSIX-2:1993 standard made the default \fBparagraphs\fP and +\fBsections\fP edit options implementation-defined, +arguing they were historically oriented to the UNIX system \fItroff\fP +text formatter, and a "portable user" could use the +\fB{\fP, \fB}\fP, \fB[[\fP, \fB]]\fP, \fB(\fP, and \fB)\fP commands +in open or visual mode and have the cursor stop in +unexpected places. IEEE\ Std\ 1003.1-2001 specifies their values in +the POSIX locale because the unusual grouping (they +only work when grouped into two characters at a time) means that they +cannot be used for general-purpose movement, regardless. +.SS readonly +.LP +Implementations are encouraged to provide the best possible information +to the user as to the read-only status of the file, with +the exception that they should not consider the current special privileges +of the process. This provides users with a safety net +because they must force the overwrite of read-only files, even when +running with additional privileges. +.LP +The \fBreadonly\fP edit option specification largely conforms to historical +practice. The only difference is that historical +implementations did not notice that the user had set the \fBreadonly\fP +edit option in cases where the file was already marked +read-only for some reason, and would therefore reinitialize the \fBreadonly\fP +edit option the next time the contents of the edit +buffer were replaced. This behavior is disallowed by IEEE\ Std\ 1003.1-2001. +.SS report +.LP +The requirement that lines copied to a buffer interact differently +than deleted lines is historical practice. For example, if +the \fBreport\fP edit option is set to 3, deleting 3 lines will cause +a report to be written, but 4 lines must be copied before a +report is written. +.LP +The requirement that the \fIex\fP \fBglobal\fP, \fBv\fP, \fBopen\fP, +\fBundo\fP, and \fBvisual\fP commands present reports +based on the total number of lines added or deleted during the command +execution, and that commands executed by the \fBglobal\fP +and \fBv\fP commands not present reports, is historical practice. +IEEE\ Std\ 1003.1-2001 extends historical practice by +requiring that buffer execution be treated similarly. The reasons +for this are two-fold. Historically, only the report by the last +command executed from the buffer would be seen by the user, as each +new report would overwrite the last. In addition, the standard +developers believed that buffer execution had more in common with +\fBglobal\fP and \fBv\fP commands than it did with other +\fIex\fP commands, and should behave similarly, for consistency and +simplicity of specification. +.SS showmatch, sm +.LP +The length of time the cursor spends on the matching character is +unspecified because the timing capabilities of systems are +often inexact and variable. The time should be long enough for the +user to notice, but not long enough for the user to become +annoyed. Some implementations of \fIvi\fP have added a \fBmatchtime\fP +option that permits +users to set the number of 0,1 second intervals the cursor pauses +on the matching character. +.SS showmode +.LP +The \fBshowmode\fP option has been used in some historical implementations +of \fIex\fP and \fIvi\fP to display the current editing mode when +in open or visual mode. The editing modes have +generally included "command" and "input", and sometimes other modes +such as "replace" and "change". The string was usually +displayed on the bottom line of the screen at the far right-hand corner. +In addition, a preceding \fB'*'\fP character often +denoted whether the contents of the edit buffer had been modified. +The latter display has sometimes been part of the +\fBshowmode\fP option, and sometimes based on another option. This +option was not available in the 4 BSD historical implementation +of \fIvi\fP, but was viewed as generally useful, particularly to novice +users, and is required +by IEEE\ Std\ 1003.1-2001. +.LP +The \fBsmd\fP shorthand for the \fBshowmode\fP option was not present +in all historical implementations of the editor. +IEEE\ Std\ 1003.1-2001 requires it, for consistency. +.LP +Not all historical implementations of the editor displayed a mode +string for command mode, differentiating command mode from +text input mode by the absence of a mode string. IEEE\ Std\ 1003.1-2001 +permits this behavior for consistency with +historical practice, but implementations are encouraged to provide +a display string for both modes. +.SS slowopen +.LP +Historically the \fBslowopen\fP option was automatically set if the +terminal baud rate was less than 1200 baud, or if the baud +rate was 1200 baud and the \fBredraw\fP option was not set. The \fBslowopen\fP +option had two effects. First, when inserting +characters in the middle of a line, characters after the cursor would +not be pushed ahead, but would appear to be overwritten. +Second, when creating a new line of text, lines after the current +line would not be scrolled down, but would appear to be +overwritten. In both cases, ending text input mode would cause the +screen to be refreshed to match the actual contents of the edit +buffer. Finally, terminals that were sufficiently intelligent caused +the editor to ignore the \fBslowopen\fP option. +IEEE\ Std\ 1003.1-2001 permits most historical behavior, extending +historical practice to require \fBslowopen\fP behaviors +if the edit option is set by the user. +.SS tags +.LP +The default path for tags files is left unspecified as implementations +may have their own \fBtags\fP implementations that do +not correspond to the historical ones. The default \fBtags\fP option +value should probably at least include the file +\fB\&./tags\fP. +.SS term +.LP +Historical implementations of \fIex\fP and \fIvi\fP ignored changes +to the \fBterm\fP edit +option after the initial terminal information was loaded. This is +permitted by IEEE\ Std\ 1003.1-2001; however, +implementations are encouraged to permit the user to modify their +terminal type at any time. +.SS terse +.LP +Historically, the \fBterse\fP edit option optionally provided a shorter, +less descriptive error message, for some error +messages. This is permitted, but not required, by IEEE\ Std\ 1003.1-2001. +Historically, most common visual mode errors (for +example, trying to move the cursor past the end of a line) did not +result in an error message, but simply alerted the terminal. +Implementations wishing to provide messages for novice users are urged +to do so based on the \fBedit\fP option \fBverbose\fP, and +not \fBterse\fP. +.SS window +.LP +In historical implementations, the default for the \fBwindow\fP edit +option was based on the baud rate as follows: +.IP " 1." 4 +If the baud rate was less than 1200, the \fBedit\fP option \fBw300\fP +set the window value; for example, the line: +.sp +.RS +.nf + +\fBset w300=12 +\fP +.fi +.RE +.LP +would set the window option to 12 if the baud rate was less than 1200. +.LP +.IP " 2." 4 +If the baud rate was equal to 1200, the \fBedit\fP option \fBw1200\fP +set the window value. +.LP +.IP " 3." 4 +If the baud rate was greater than 1200, the \fBedit\fP option \fBw9600\fP +set the window value. +.LP +.LP +The \fBw300\fP, \fBw1200\fP, and \fBw9600\fP options do not appear +in IEEE\ Std\ 1003.1-2001 because of their +dependence on specific baud rates. +.LP +In historical implementations, the size of the window displayed by +various commands was related to, but not necessarily the same +as, the \fBwindow\fP edit option. For example, the size of the window +was set by the \fIex\fP command \fBvisual 10\fP, but it +did not change the value of the \fBwindow\fP edit option. However, +changing the value of the \fBwindow\fP edit option did change +the number of lines that were displayed when the screen was repainted. +IEEE\ Std\ 1003.1-2001 does not permit this behavior +in the interests of consistency and simplicity of specification, and +requires that all commands that change the number of lines +that are displayed do it by setting the value of the \fBwindow\fP +edit option. +.SS wrapmargin, wm +.LP +Historically, the \fBwrapmargin\fP option did not affect maps inserting +characters that also had associated \fIcount\fPs; for +example \fB:map\ K\ 5aABC\ DEF\fP. Unfortunately, there are widely +used maps that depend on this behavior. For +consistency and simplicity of specification, IEEE\ Std\ 1003.1-2001 +does not permit this behavior. +.LP +Historically, \fBwrapmargin\fP was calculated using the column display +width of all characters on the screen. For example, an +implementation using \fB"^I"\fP to represent s when the \fBlist\fP +edit option was set, where \fB'^'\fP and +\fB'I'\fP each took up a single column on the screen, would calculate +the \fBwrapmargin\fP based on a value of 2 for each +. The \fBnumber\fP edit option similarly changed the effective +length of the line as well. +IEEE\ Std\ 1003.1-2001 requires conformance to historical practice. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fICommand Search and Execution\fP , \fIctags\fP , \fIed\fP , \fIsed\fP +, \fIsh\fP , \fIstty\fP , \fIvi\fP , the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, \fIaccess\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/exec.1p b/man1p/exec.1p new file mode 100644 index 000000000..69f732928 --- /dev/null +++ b/man1p/exec.1p @@ -0,0 +1,157 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "EXEC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" exec +.SH NAME +exec \- execute commands and open, close, or copy file descriptors +.SH SYNOPSIS +.LP +\fBexec\fP \fB[\fP\fIcommand\fP \fB[\fP\fIargument\fP \fB...\fP\fB]]\fP +.SH DESCRIPTION +.LP +The \fIexec\fP utility shall open, close, and/or copy file descriptors +as specified by any redirections as part of the +command. +.LP +If \fIexec\fP is specified without \fIcommand\fP or \fIargument\fPs, +and any file descriptors with numbers greater than 2 are +opened with associated redirection statements, it is unspecified whether +those file descriptors remain open when the shell invokes +another utility. Scripts concerned that child shells could misuse +open file descriptors can always close them explicitly, as shown +in one of the following examples. +.LP +If \fIexec\fP is specified with \fIcommand\fP, it shall replace the +shell with \fIcommand\fP without creating a new process. +If \fIargument\fPs are specified, they shall be arguments to \fIcommand\fP. +Redirection affects the current shell execution +environment. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +See the DESCRIPTION. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +None. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +If \fIcommand\fP is specified, \fIexec\fP shall not return to the +shell; rather, the exit status of the process shall be the +exit status of the program implementing \fIcommand\fP, which overlaid +the shell. If \fIcommand\fP is not found, the exit status +shall be 127. If \fIcommand\fP is found, but it is not an executable +utility, the exit status shall be 126. If a redirection error +occurs (see \fIConsequences of Shell Errors\fP ), the shell shall +exit with a value in +the range 1-125. Otherwise, \fIexec\fP shall return a zero exit status. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +Open \fIreadfile\fP as file descriptor 3 for reading: +.sp +.RS +.nf + +\fBexec 3< readfile +\fP +.fi +.RE +.LP +Open \fIwritefile\fP as file descriptor 4 for writing: +.sp +.RS +.nf + +\fBexec 4> writefile +\fP +.fi +.RE +.LP +Make file descriptor 5 a copy of file descriptor 0: +.sp +.RS +.nf + +\fBexec 5<&0 +\fP +.fi +.RE +.LP +Close file descriptor 3: +.sp +.RS +.nf + +\fBexec 3<&- +\fP +.fi +.RE +.LP +Cat the file \fBmaggie\fP by replacing the current shell with the +\fIcat\fP utility: +.sp +.RS +.nf + +\fBexec cat maggie +\fP +.fi +.RE +.SH RATIONALE +.LP +Most historical implementations were not conformant in that: +.sp +.RS +.nf + +\fBfoo=bar exec cmd +\fP +.fi +.RE +.LP +did not pass \fBfoo\fP to \fBcmd\fP. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISpecial Built-In Utilities\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/exit.1p b/man1p/exit.1p new file mode 100644 index 000000000..19924ae45 --- /dev/null +++ b/man1p/exit.1p @@ -0,0 +1,118 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "EXIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" exit +.SH NAME +exit \- cause the shell to exit +.SH SYNOPSIS +.LP +\fBexit\fP \fB[\fP\fIn\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIexit\fP utility shall cause the shell to exit with the exit +status specified by the unsigned decimal integer \fIn\fP. +If \fIn\fP is specified, but its value is not between 0 and 255 inclusively, +the exit status is undefined. +.LP +A \fItrap\fP on \fBEXIT\fP shall be executed before the shell terminates, +except when the +\fIexit\fP utility is invoked in that \fItrap\fP itself, in which +case the shell shall exit +immediately. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +See the DESCRIPTION. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +None. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The exit status shall be \fIn\fP, if specified. Otherwise, the value +shall be the exit value of the last command executed, or +zero if no command was executed. When \fIexit\fP is executed in a +\fItrap\fP action, the +last command is considered to be the command that executed immediately +preceding the \fItrap\fP action. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +Exit with a \fItrue\fP value: +.sp +.RS +.nf + +\fBexit 0 +\fP +.fi +.RE +.LP +Exit with a \fIfalse\fP value: +.sp +.RS +.nf + +\fBexit 1 +\fP +.fi +.RE +.SH RATIONALE +.LP +As explained in other sections, certain exit status values have been +reserved for special uses and should be used by +applications only for those purposes: +.TP 7 +\ 126 +A file to be executed was found, but it was not an executable utility. +.TP 7 +\ 127 +A utility to be executed was not found. +.TP 7 +>128 +A command was interrupted by a signal. +.sp +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISpecial Built-In Utilities\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/expand.1p b/man1p/expand.1p new file mode 100644 index 000000000..673cc26ff --- /dev/null +++ b/man1p/expand.1p @@ -0,0 +1,161 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "EXPAND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" expand +.SH NAME +expand \- convert tabs to spaces +.SH SYNOPSIS +.LP +\fBexpand\fP \fB[\fP\fB-t\fP \fItablist\fP\fB][\fP\fIfile\fP \fB...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIexpand\fP utility shall write files or the standard input to +the standard output with s replaced with one or +more s needed to pad to the next tab stop. Any s +shall be copied to the output and cause the column +position count for tab stop calculations to be decremented; the column +position count shall not be decremented below zero. +.SH OPTIONS +.LP +The \fIexpand\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-t\ \fP \fItablist\fP +Specify the tab stops. The application shall ensure that the argument +\fItablist\fP consists of either a single positive +decimal integer or a list of tabstops. If a single number is given, +tabs shall be set that number of column positions apart instead +of the default 8. +.LP +If a list of tabstops is given, the application shall ensure that +it consists of a list of two or more positive decimal +integers, separated by s or commas, in ascending order. The +tabs shall be set at those specific column positions. Each +tab stop \fIN\fP shall be an integer value greater than zero, and +the list is in strictly ascending order. This is taken to mean +that, from the start of a line of output, tabbing to position \fIN\fP +shall cause the next character output to be in the ( +\fIN\fP+1)th column position on that line. +.LP +In the event of \fIexpand\fP having to process a at a position +beyond the last of those specified in a multiple +tab-stop list, the shall be replaced by a single in +the output. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +The pathname of a text file to be used as input. +.sp +.SH STDIN +.LP +See the INPUT FILES section. +.SH INPUT FILES +.LP +Input files shall be text files. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIexpand\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), the +processing of s and s, and for the +determination of the width in column positions each character would +occupy on an output device. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall be equivalent to the input files with s +converted into the appropriate number of +s. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +The \fIexpand\fP utility shall terminate with an error message and +non-zero exit status upon encountering difficulties +accessing one of the \fIfile\fP operands. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIexpand\fP utility is useful for preprocessing text files (before +sorting, looking at specific columns, and so on) that +contain s. +.LP +See the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section +3.103, Column Position. +.LP +The \fItablist\fP option-argument consists of integers in ascending +order. Utility Syntax Guideline 8 mandates that +\fIexpand\fP shall accept the integers (within the single argument) +separated using either commas or s. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fItabs\fP , \fIunexpand\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/export.1p b/man1p/export.1p new file mode 100644 index 000000000..74a248b6c --- /dev/null +++ b/man1p/export.1p @@ -0,0 +1,160 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "EXPORT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" export +.SH NAME +export \- set the export attribute for variables +.SH SYNOPSIS +.LP +\fBexport name\fP\fB[\fP\fB=\fP\fIword\fP\fB]\fP\fB... +.br +.sp +export -p +.br +\fP +.SH DESCRIPTION +.LP +The shell shall give the \fIexport\fP attribute to the variables corresponding +to the specified \fIname\fPs, which shall cause +them to be in the environment of subsequently executed commands. If +the name of a variable is followed by = \fIword\fP, then the +value of that variable shall be set to \fIword\fP. +.LP +The \fIexport\fP special built-in shall support the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +When \fB-p\fP is specified, \fIexport\fP shall write to the standard +output the names and values of all exported variables, in +the following format: +.sp +.RS +.nf + +\fB"export %s=%s\\n", <\fP\fIname\fP\fB>, <\fP\fIvalue\fP\fB> +\fP +.fi +.RE +.LP +if \fIname\fP is set, and: +.sp +.RS +.nf + +\fB"export %s\\n", <\fP\fIname\fP\fB> +\fP +.fi +.RE +.LP +if \fIname\fP is unset. +.LP +The shell shall format the output, including the proper use of quoting, +so that it is suitable for reinput to the shell as +commands that achieve the same exporting results, except: +.IP " 1." 4 +Read-only variables with values cannot be reset. +.LP +.IP " 2." 4 +Variables that were unset at the time they were output need not be +reset to the unset state if a value is assigned to the +variable between the time the state was saved and the time at which +the saved output is reinput to the shell. +.LP +.LP +When no arguments are given, the results are unspecified. +.SH OPTIONS +.LP +See the DESCRIPTION. +.SH OPERANDS +.LP +See the DESCRIPTION. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +None. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +See the DESCRIPTION. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +Zero. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +Export \fIPWD\fP and \fIHOME\fP variables: +.sp +.RS +.nf + +\fBexport PWD HOME +\fP +.fi +.RE +.LP +Set and export the \fIPATH\fP variable: +.sp +.RS +.nf + +\fBexport PATH=/local/bin:$PATH +\fP +.fi +.RE +.LP +Save and restore all exported variables: +.sp +.RS +.nf + +\fBexport -p >\fP \fItemp-file\fP\fBunset\fP \fIa lot of variables\fP\fB...\fP \fIprocessing\fP\fB.\fP \fItemp-file\fP +.fi +.RE +.SH RATIONALE +.LP +Some historical shells use the no-argument case as the functional +equivalent of what is required here with \fB-p\fP. This +feature was left unspecified because it is not historical practice +in all shells, and some scripts may rely on the now-unspecified +results on their implementations. Attempts to specify the \fB-p\fP +output as the default case were unsuccessful in achieving +consensus. The \fB-p\fP option was added to allow portable access +to the values that can be saved and then later restored using; +for example, a \fIdot\fP script. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISpecial Built-In Utilities\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/expr.1p b/man1p/expr.1p new file mode 100644 index 000000000..2e16fde1c --- /dev/null +++ b/man1p/expr.1p @@ -0,0 +1,411 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "EXPR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" expr +.SH NAME +expr \- evaluate arguments as an expression +.SH SYNOPSIS +.LP +\fBexpr\fP \fIoperand\fP +.SH DESCRIPTION +.LP +The \fIexpr\fP utility shall evaluate an expression and write the +result to standard output. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The single expression evaluated by \fIexpr\fP shall be formed from +the operands, as described in the EXTENDED DESCRIPTION +section. The application shall ensure that each of the expression +operator symbols: +.sp +.RS +.nf + +\fB( ) | & = > >= < <= != + - * / % : +\fP +.fi +.RE +.LP +and the symbols \fIinteger\fP and \fIstring\fP in the table are provided +as separate arguments to \fIexpr\fP. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIexpr\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular +expressions and by the string comparison operators. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments) and the behavior of +character classes within regular expressions. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fIexpr\fP utility shall evaluate the expression and write the +result, followed by a , to standard +output. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +The formation of the expression to be evaluated is shown in the following +table. The symbols \fIexpr\fP, \fIexpr1\fP, and +\fIexpr2\fP represent expressions formed from \fIinteger\fP and \fIstring\fP +symbols and the expression operator symbols (all +separate arguments) by recursive application of the constructs described +in the table. The expressions are listed in order of +increasing precedence, with equal-precedence operators grouped between +horizontal lines. All of the operators shall be +left-associative. +.TS C +center; l lw(40). +\fBExpression\fP T{ +.na +\fBDescription\fP +.ad +T} +\fIexpr1\fP\ |\ \fIexpr2\fP T{ +.na +Returns the evaluation of \fIexpr1\fP if it is neither null nor zero; otherwise, returns the evaluation of \fIexpr2\fP if it is not null; otherwise, zero. +.ad +T} +\fIexpr1\fP\ &\ \fIexpr2\fP T{ +.na +Returns the evaluation of \fIexpr1\fP if neither expression evaluates to null or zero; otherwise, returns zero. +.ad +T} +\ T{ +.na +Returns the result of a decimal integer comparison if both arguments are integers; otherwise, returns the result of a string comparison using the locale-specific collation sequence. The result of each comparison is 1 if the specified relationship is true, or 0 if the relationship is false. +.ad +T} +\fIexpr1\fP\ =\ \fIexpr2\fP T{ +.na +Equal. +.ad +T} +\fIexpr1\fP\ >\ \fIexpr2\fP T{ +.na +Greater than. +.ad +T} +\fIexpr1\fP\ >=\ \fIexpr2\fP T{ +.na +Greater than or equal. +.ad +T} +\fIexpr1\fP\ <\ \fIexpr2\fP T{ +.na +Less than. +.ad +T} +\fIexpr1\fP\ <=\ \fIexpr2\fP T{ +.na +Less than or equal. +.ad +T} +\fIexpr1\fP\ !=\ \fIexpr2\fP T{ +.na +Not equal. +.ad +T} +\fIexpr1\fP\ +\ \fIexpr2\fP T{ +.na +Addition of decimal integer-valued arguments. +.ad +T} +\fIexpr1\fP\ -\ \fIexpr2\fP T{ +.na +Subtraction of decimal integer-valued arguments. +.ad +T} +\fIexpr1\fP\ *\ \fIexpr2\fP T{ +.na +Multiplication of decimal integer-valued arguments. +.ad +T} +\fIexpr1\fP\ /\ \fIexpr2\fP T{ +.na +Integer division of decimal integer-valued arguments, producing an integer result. +.ad +T} +\fIexpr1\fP\ %\ \fIexpr2\fP T{ +.na +Remainder of integer division of decimal integer-valued arguments. +.ad +T} +\fIexpr1\fP\ :\ \fIexpr2\fP T{ +.na +Matching expression; see below. +.ad +T} +(\ \fIexpr\fP\ ) T{ +.na +Grouping symbols. Any expression can be placed within parentheses. Parentheses can be nested to a depth of {EXPR_NEST_MAX}. +.ad +T} +\fIinteger\fP T{ +.na +An argument consisting only of an (optional) unary minus followed by digits. +.ad +T} +\fIstring\fP T{ +.na +A string argument; see below. +.ad +T} +.TE +.SS Matching Expression +.LP +The \fB':'\fP matching operator shall compare the string resulting +from the evaluation of \fIexpr1\fP with the regular +expression pattern resulting from the evaluation of \fIexpr2\fP. Regular +expression syntax shall be that defined in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 9.3, Basic Regular +Expressions, except that all patterns are anchored to the beginning +of the string (that is, only sequences starting at the +first character of a string are matched by the regular expression) +and, therefore, it is unspecified whether \fB'^'\fP is a +special character in that context. Usually, the matching operator +shall return a string representing the number of characters +matched ( \fB'0'\fP on failure). Alternatively, if the pattern contains +at least one regular expression subexpression +\fB"[\\(...\\)]"\fP , the string corresponding to \fB"\\1"\fP shall +be returned. +.SS String Operand +.LP +A string argument is an argument that cannot be identified as an \fIinteger\fP +argument or as one of the expression operator +symbols shown in the OPERANDS section. +.LP +The use of string arguments \fBlength\fP, \fBsubstr\fP, \fBindex\fP, +or \fBmatch\fP produces unspecified results. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The \fIexpression\fP evaluates to neither null nor zero. +.TP 7 +\ 1 +The \fIexpression\fP evaluates to null or zero. +.TP 7 +\ 2 +Invalid \fIexpression\fP. +.TP 7 +>2 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +After argument processing by the shell, \fIexpr\fP is not required +to be able to tell the difference between an operator and an +operand except by the value. If \fB"$a"\fP is \fB'='\fP , the command: +.sp +.RS +.nf + +\fBexpr $a = '=' +\fP +.fi +.RE +.LP +looks like: +.sp +.RS +.nf + +\fBexpr = = = +\fP +.fi +.RE +.LP +as the arguments are passed to \fIexpr\fP (and they all may be taken +as the \fB'='\fP operator). The following works +reliably: +.sp +.RS +.nf + +\fBexpr X$a = X= +\fP +.fi +.RE +.LP +Also note that this volume of IEEE\ Std\ 1003.1-2001 permits implementations +to extend utilities. The \fIexpr\fP +utility permits the integer arguments to be preceded with a unary +minus. This means that an integer argument could look like an +option. Therefore, the conforming application must employ the \fB"--"\fP +construct of Guideline 10 of the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax +Guidelines to protect its operands if there is any chance the first +operand might be a negative integer (or any string with a +leading minus). +.SH EXAMPLES +.LP +The \fIexpr\fP utility has a rather difficult syntax: +.IP " *" 3 +Many of the operators are also shell control operators or reserved +words, so they have to be escaped on the command line. +.LP +.IP " *" 3 +Each part of the expression is composed of separate arguments, so +liberal usage of s is required. For example: +.TS C +center; l l. +\fBInvalid\fP \fBValid\fP +\fIexpr\fP 1+2 \fIexpr\fP 1 + 2 +\fIexpr\fP "1 + 2" \fIexpr\fP 1 + 2 +\fIexpr\fP 1 + (2 * 3) \fIexpr\fP 1 + \\( 2 \\* 3 \\) +.TE +.LP +.LP +In many cases, the arithmetic and string features provided as part +of the shell command language are easier to use than their +equivalents in \fIexpr\fP. Newly written scripts should avoid \fIexpr\fP +in favor of the new features within the shell; see \fIParameters and +Variables\fP and \fIArithmetic +Expansion\fP . +.LP +The following command: +.sp +.RS +.nf + +\fBa=$(expr $a + 1) +\fP +.fi +.RE +.LP +adds 1 to the variable \fIa\fP. +.LP +The following command, for \fB"$a"\fP equal to either \fB/usr/abc/file\fP +or just \fBfile\fP: +.sp +.RS +.nf + +\fBexpr $a : '.*/\\(.*\\)' \\| $a +\fP +.fi +.RE +.LP +returns the last segment of a pathname (that is, \fBfile\fP). Applications +should avoid the character \fB'/'\fP used alone +as an argument; \fIexpr\fP may interpret it as the division operator. +.LP +The following command: +.sp +.RS +.nf + +\fBexpr "//$a" : '.*/\\(.*\\)' +\fP +.fi +.RE +.LP +is a better representation of the previous example. The addition of +the \fB"//"\fP characters eliminates any ambiguity about +the division operator and simplifies the whole expression. Also note +that pathnames may contain characters contained in the +\fIIFS\fP variable and should be quoted to avoid having \fB"$a"\fP +expand into multiple arguments. +.LP +The following command: +.sp +.RS +.nf + +\fBexpr "$VAR" : '.*' +\fP +.fi +.RE +.LP +returns the number of characters in \fIVAR\fP. +.SH RATIONALE +.LP +In an early proposal, EREs were used in the matching expression syntax. +This was changed to BREs to avoid breaking historical +applications. +.LP +The use of a leading circumflex in the BRE is unspecified because +many historical implementations have treated it as a special +character, despite their system documentation. For example: +.sp +.RS +.nf + +\fBexpr foo : ^foo expr ^foo : ^foo +\fP +.fi +.RE +.LP +return 3 and 0, respectively, on those systems; their documentation +would imply the reverse. Thus, the anchoring condition is +left unspecified to avoid breaking historical scripts relying on this +undocumented feature. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIParameters and Variables\fP , \fIArithmetic +Expansion\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/false.1p b/man1p/false.1p new file mode 100644 index 000000000..e4db60194 --- /dev/null +++ b/man1p/false.1p @@ -0,0 +1,75 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FALSE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" false +.SH NAME +false \- return false value +.SH SYNOPSIS +.LP +\fBfalse\fP +.SH DESCRIPTION +.LP +The \fIfalse\fP utility shall return with a non-zero exit code. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +None. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +None. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +Not used. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The \fIfalse\fP utility shall always exit with a value other than +zero. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fItrue\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/fc.1p b/man1p/fc.1p new file mode 100644 index 000000000..fdd8ccadb --- /dev/null +++ b/man1p/fc.1p @@ -0,0 +1,476 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fc +.SH NAME +fc \- process the command history list +.SH SYNOPSIS +.LP +\fBfc\fP \fB[\fP\fB-r\fP\fB][\fP\fB-e\fP \fIeditor\fP\fB] +[\fP\fIfirst\fP\fB[\fP\fIlast\fP\fB]]\fP\fB +.br +.sp +fc -l\fP\fB[\fP\fB-nr\fP\fB] [\fP\fIfirst\fP\fB[\fP\fIlast\fP\fB]]\fP\fB +.br +.sp +fc -s\fP\fB[\fP\fIold\fP\fB=\fP\fInew\fP\fB][\fP\fIfirst\fP\fB]\fP\fB\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIfc\fP utility shall list, or shall edit and re-execute, commands +previously entered to an interactive \fIsh\fP. +.LP +The command history list shall reference commands by number. The first +number in the list is selected arbitrarily. The +relationship of a number to its command shall not change except when +the user logs in and no other process is accessing the list, +at which time the system may reset the numbering to start the oldest +retained command at another number (usually 1). When the +number reaches an implementation-defined upper limit, which shall +be no smaller than the value in \fIHISTSIZE\fP or 32767 +(whichever is greater), the shell may wrap the numbers, starting the +next command with a lower number (usually 1). However, despite +this optional wrapping of numbers, \fIfc\fP shall maintain the time-ordering +sequence of the commands. For example, if four +commands in sequence are given the numbers 32766, 32767, 1 (wrapped), +and 2 as they are executed, command 32767 is considered the +command previous to 1, even though its number is higher. +.LP +When commands are edited (when the \fB-l\fP option is not specified), +the resulting lines shall be entered at the end of the +history list and then re-executed by \fIsh\fP. The \fIfc\fP command +that caused the editing +shall not be entered into the history list. If the editor returns +a non-zero exit status, this shall suppress the entry into the +history list and the command re-execution. Any command line variable +assignments or redirection operators used with \fIfc\fP shall +affect both the \fIfc\fP command itself as well as the command that +results; for example: +.sp +.RS +.nf + +\fBfc -s -- -1 2>/dev/null +\fP +.fi +.RE +.LP +reinvokes the previous command, suppressing standard error for both +\fIfc\fP and the previous command. +.SH OPTIONS +.LP +The \fIfc\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-e\ \fP \fIeditor\fP +Use the editor named by \fIeditor\fP to edit the commands. The \fIeditor\fP +string is a utility name, subject to search via +the \fIPATH\fP variable (see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 8, Environment Variables). The value in the \fIFCEDIT\fP variable +shall be used as a +default when \fB-e\fP is not specified. If \fIFCEDIT\fP is null or +unset, \fIed\fP shall be +used as the editor. +.TP 7 +\fB-l\fP +(The letter ell.) List the commands rather than invoking an editor +on them. The commands shall be written in the sequence +indicated by the \fIfirst\fP and \fIlast\fP operands, as affected +by \fB-r\fP, with each command preceded by the command +number. +.TP 7 +\fB-n\fP +Suppress command numbers when listing with \fB-l\fP. +.TP 7 +\fB-r\fP +Reverse the order of the commands listed (with \fB-l\fP) or edited +(with neither \fB-l\fP nor \fB-s\fP). +.TP 7 +\fB-s\fP +Re-execute the command without invoking an editor. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfirst\fP,\ \fIlast\fP +Select the commands to list or edit. The number of previous commands +that can be accessed shall be determined by the value of +the \fIHISTSIZE\fP variable. The value of \fIfirst\fP or \fIlast\fP +or both shall be one of the following: +.TP 7 +\fB[+]\fP\fInumber\fP +.RS +A positive number representing a command number; command numbers can +be displayed with the \fB-l\fP option. +.RE +.TP 7 +\fB-\fP\fInumber\fP +.RS +A negative decimal number representing the command that was executed +\fInumber\fP of commands previously. For example, -1 is +the immediately previous command. +.RE +.TP 7 +\fIstring\fP +.RS +A string indicating the most recently entered command that begins +with that string. If the \fIold\fP= \fInew\fP operand is +not also specified with \fB-s\fP, the string form of the \fIfirst\fP +operand cannot contain an embedded equal sign. +.RE +.sp +.LP +When the synopsis form with \fB-s\fP is used: +.RS +.IP " *" 3 +If \fIfirst\fP is omitted, the previous command shall be used. +.LP +.RE +.LP +For the synopsis forms without \fB-s\fP: +.RS +.IP " *" 3 +If \fIlast\fP is omitted, \fIlast\fP shall default to the previous +command when \fB-l\fP is specified; otherwise, it shall +default to \fIfirst\fP. +.LP +.IP " *" 3 +If \fIfirst\fP and \fIlast\fP are both omitted, the previous 16 commands +shall be listed or the previous single command shall +be edited (based on the \fB-l\fP option). +.LP +.IP " *" 3 +If \fIfirst\fP and \fIlast\fP are both present, all of the commands +from \fIfirst\fP to \fIlast\fP shall be edited (without +\fB-l\fP) or listed (with \fB-l\fP). Editing multiple commands shall +be accomplished by presenting to the editor all of the +commands at one time, each command starting on a new line. If \fIfirst\fP +represents a newer command than \fIlast\fP, the +commands shall be listed or edited in reverse sequence, equivalent +to using \fB-r\fP. For example, the following commands on the +first line are equivalent to the corresponding commands on the second: +.sp +.RS +.nf + +\fBfc -r 10 20 fc 30 40 +fc 20 10 fc -r 40 30 +\fP +.fi +.RE +.LP +.IP " *" 3 +When a range of commands is used, it shall not be an error to specify +\fIfirst\fP or \fIlast\fP values that are not in the +history list; \fIfc\fP shall substitute the value representing the +oldest or newest command in the list, as appropriate. For +example, if there are only ten commands in the history list, numbered +1 to 10: +.sp +.RS +.nf + +\fBfc -l +fc 1 99 +\fP +.fi +.RE +.LP +shall list and edit, respectively, all ten commands. +.LP +.RE +.TP 7 +\fIold\fP=\fInew\fP +Replace the first occurrence of string \fIold\fP in the commands to +be re-executed by the string \fInew\fP. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIfc\fP: +.TP 7 +\fIFCEDIT\fP +This variable, when expanded by the shell, shall determine the default +value for the \fB-e\fP \fIeditor\fP option's +\fIeditor\fP option-argument. If \fIFCEDIT\fP is null or unset, \fIed\fP +shall be used as the +editor. +.TP 7 +\fIHISTFILE\fP +Determine a pathname naming a command history file. If the \fIHISTFILE\fP +variable is not set, the shell may attempt to access +or create a file \fB.sh_history\fP in the directory referred to by +the \fIHOME\fP environment variable. If the shell cannot +obtain both read and write access to, or create, the history file, +it shall use an unspecified mechanism that allows the history to +operate properly. (References to history "file" in this section shall +be understood to mean this unspecified mechanism in such +cases.) An implementation may choose to access this variable only +when initializing the history file; this initialization shall +occur when \fIfc\fP or \fIsh\fP first attempt to retrieve entries +from, or add entries to, the +file, as the result of commands issued by the user, the file named +by the \fIENV\fP variable, or implementation-defined system +start-up files. In some historical shells, the history file is initialized +just after the \fIENV\fP file has been processed. +Therefore, it is implementation-defined whether changes made to \fIHISTFILE\fP +after the history file has been initialized are +effective. Implementations may choose to disable the history list +mechanism for users with appropriate privileges who do not set +\fIHISTFILE ;\fP the specific circumstances under which this occurs +are implementation-defined. If more than one instance of the +shell is using the same history file, it is unspecified how updates +to the history file from those shells interact. As entries are +deleted from the history file, they shall be deleted oldest first. +It is unspecified when history file entries are physically +removed from the history file. +.TP 7 +\fIHISTSIZE\fP +Determine a decimal number representing the limit to the number of +previous commands that are accessible. If this variable is +unset, an unspecified default greater than or equal to 128 shall be +used. The maximum number of commands in the history list is +unspecified, but shall be at least 128. An implementation may choose +to access this variable only when initializing the history +file, as described under \fIHISTFILE .\fP Therefore, it is unspecified +whether changes made to \fIHISTSIZE\fP after the history +file has been initialized are effective. +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +When the \fB-l\fP option is used to list commands, the format of each +command in the list shall be as follows: +.sp +.RS +.nf + +\fB"%d\\t%s\\n", <\fP\fIline number\fP\fB>, <\fP\fIcommand\fP\fB> +\fP +.fi +.RE +.LP +If both the \fB-l\fP and \fB-n\fP options are specified, the format +of each command shall be: +.sp +.RS +.nf + +\fB"\\t%s\\n", <\fP\fIcommand\fP\fB> +\fP +.fi +.RE +.LP +If the <\fIcommand\fP> consists of more than one line, the lines after +the first shall be displayed as: +.sp +.RS +.nf + +\fB"\\t%s\\n", <\fP\fIcontinued-command\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion of the listing. +.TP 7 +>0 +An error occurred. +.sp +.LP +Otherwise, the exit status shall be that of the commands executed +by \fIfc\fP. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Since editors sometimes use file descriptors as integral parts of +their editing, redirecting their file descriptors as part of +the \fIfc\fP command can produce unexpected results. For example, +if \fIvi\fP is the +\fIFCEDIT\fP editor, the command: +.sp +.RS +.nf + +\fBfc -s | more +\fP +.fi +.RE +.LP +does not work correctly on many systems. +.LP +Users on windowing systems may want to have separate history files +for each window by setting \fIHISTFILE\fP as follows: +.sp +.RS +.nf + +\fBHISTFILE=$HOME/.sh_hist$$ +\fP +.fi +.RE +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +This utility is based on the \fIfc\fP built-in of the KornShell. +.LP +An early proposal specified the \fB-e\fP option as \fB[-e\fP \fIeditor\fP +\fB[\fP \fIold\fP = \fInew\fP \fB]]\fP, which +is not historical practice. Historical practice in \fIfc\fP of either +\fB[-e\fP \fIeditor\fP \fB]\fP or \fB[-e - [\fP +\fIold\fP = \fInew\fP \fB]]\fP is acceptable, but not both together. +To clarify this, a new option \fB-s\fP was introduced +replacing the \fB[-e -]\fP. This resolves the conflict and makes \fIfc\fP +conform to the Utility Syntax Guidelines. +.TP 7 +\fIHISTFILE\fP +Some implementations of the KornShell check for the superuser and +do not create a history file unless \fIHISTFILE\fP is set. +This is done primarily to avoid creating unlinked files in the root +file system when logging in during single-user mode. +\fIHISTFILE\fP must be set for the superuser to have history. +.TP 7 +\fIHISTSIZE\fP +Needed to limit the size of history files. It is the intent of the +standard developers that when two shells share the same +history file, commands that are entered in one shell shall be accessible +by the other shell. Because of the difficulties of +synchronization over a network, the exact nature of the interaction +is unspecified. +.sp +.LP +The initialization process for the history file can be dependent on +the system start-up files, in that they may contain commands +that effectively preempt the settings the user has for \fIHISTFILE\fP +and \fIHISTSIZE .\fP For example, function definition +commands are recorded in the history file. If the system administrator +includes function definitions in some system start-up file +called before the \fIENV\fP file, the history file is initialized +before the user can influence its characteristics. In some +historical shells, the history file is initialized just after the +\fIENV\fP file has been processed. Because of these situations, +the text requires the initialization process to be implementation-defined. +.LP +Consideration was given to omitting the \fIfc\fP utility in favor +of the command line editing feature in \fIsh\fP. For example, in \fIvi\fP +editing mode, typing +\fB" v"\fP is equivalent to: +.sp +.RS +.nf + +\fBEDITOR=vi fc +\fP +.fi +.RE +.LP +However, the \fIfc\fP utility allows the user the flexibility to edit +multiple commands simultaneously (such as \fIfc\fP 10 +20) and to use editors other than those supported by \fIsh\fP for +command line editing. +.LP +In the KornShell, the alias \fBr\fP (``re-do") is preset to \fIfc\fP +\fB-e -\fP (equivalent to the POSIX \fIfc\fP +\fB-s\fP). This is probably an easier command name to remember than +\fIfc\fP (``fix command"), but it does not meet the Utility +Syntax Guidelines. Renaming \fIfc\fP to \fIhist\fP or \fIredo\fP was +considered, but since this description closely matches +historical KornShell practice already, such a renaming was seen as +gratuitous. Users are free to create aliases whenever odd +historical names such as \fIfc\fP, \fIawk\fP, \fIcat\fP, +\fIgrep\fP, or \fIyacc\fP are standardized by +POSIX. +.LP +Command numbers have no ordering effects; they are like serial numbers. +The \fB-r\fP option and -\fInumber\fP operand address +the sequence of command execution, regardless of serial numbers. So, +for example, if the command number wrapped back to 1 at some +arbitrary point, there would be no ambiguity associated with traversing +the wrap point. For example, if the command history +were: +.sp +.RS +.nf + +\fB32766: echo 1 +32767: echo 2 +1: echo 3 +\fP +.fi +.RE +.LP +the number -2 refers to command 32767 because it is the second previous +command, regardless of serial number. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsh\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/fg.1p b/man1p/fg.1p new file mode 100644 index 000000000..19100195f --- /dev/null +++ b/man1p/fg.1p @@ -0,0 +1,152 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fg +.SH NAME +fg \- run jobs in the foreground +.SH SYNOPSIS +.LP +\fBfg\fP \fB[\fP\fIjob_id\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +If job control is enabled (see the description of \fIset\fP \fB-m\fP), +the +\fIfg\fP utility shall move a background job from the current environment +(see \fIShell +Execution Environment\fP ) into the foreground. +.LP +Using \fIfg\fP to place a job into the foreground shall remove its +process ID from the list of those "known in the current +shell execution environment''; see \fIAsynchronous Lists\fP . +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIjob_id\fP +Specify the job to be run as a foreground job. If no \fIjob_id\fP +operand is given, the \fIjob_id\fP for the job that was +most recently suspended, placed in the background, or run as a background +job shall be used. The format of \fIjob_id\fP is +described in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 3.203, Job Control Job ID. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIfg\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fIfg\fP utility shall write the command line of the job to standard +output in the following format: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIcommand\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If job control is disabled, the \fIfg\fP utility shall exit with an +error and no job shall be placed in the foreground. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fIfg\fP utility does not work as expected when it is operating +in its own utility execution environment because that +environment has no applicable jobs to manipulate. See the APPLICATION +USAGE section for \fIbg\fP . For this +reason, \fIfg\fP is generally implemented as a shell regular built-in. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The extensions to the shell specified in this volume of IEEE\ Std\ 1003.1-2001 +have mostly been based on features +provided by the KornShell. The job control features provided by \fIbg\fP, +\fIfg\fP, and \fIjobs\fP are also based on the KornShell. The standard +developers examined the characteristics +of the C shell versions of these utilities and found that differences +exist. Despite widespread use of the C shell, the KornShell +versions were selected for this volume of IEEE\ Std\ 1003.1-2001 to +maintain a degree of uniformity with the rest of the +KornShell features selected (such as the very popular command line +editing features). +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIAsynchronous Lists\fP , \fIShell Execution +Environment\fP , \fIbg\fP , \fIkill\fP() , \fIjobs\fP +, \fIwait\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/file.1p b/man1p/file.1p new file mode 100644 index 000000000..4a33fab19 --- /dev/null +++ b/man1p/file.1p @@ -0,0 +1,786 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FILE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" file +.SH NAME +file \- determine file type +.SH SYNOPSIS +.LP +\fBfile\fP \fB[\fP\fB-dh\fP\fB][\fP\fB-M\fP \fIfile\fP\fB][\fP\fB-m\fP +\fIfile\fP\fB]\fP +\fIfile\fP \fB... +.br +.sp +file -i\fP \fB[\fP\fB-h\fP\fB]\fP \fIfile\fP \fB... \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIfile\fP utility shall perform a series of tests in sequence +on each specified \fIfile\fP in an attempt to classify +it: +.IP " 1." 4 +If \fIfile\fP does not exist, cannot be read, or its file status could +not be determined, the output shall indicate that the +file was processed, but that its type could not be determined. +.LP +.IP " 2." 4 +If the file is not a regular file, its file type shall be identified. +The file types directory, FIFO, socket, block special, and +character special shall be identified as such. Other implementation-defined +file types may also be identified. If \fIfile\fP is a +symbolic link, by default the link shall be resolved and \fIfile\fP +shall test the type of file referenced by the symbolic link. +(See the \fB-h\fP and \fB-i\fP options below.) +.LP +.IP " 3." 4 +If the length of \fIfile\fP is zero, it shall be identified as an +empty file. +.LP +.IP " 4." 4 +The \fIfile\fP utility shall examine an initial segment of \fIfile\fP +and shall make a guess at identifying its contents based +on position-sensitive tests. (The answer is not guaranteed to be correct; +see the \fB-d\fP, \fB-M\fP, and \fB-m\fP options +below.) +.LP +.IP " 5." 4 +The \fIfile\fP utility shall examine \fIfile\fP and make a guess at +identifying its contents based on context-sensitive +default system tests. (The answer is not guaranteed to be correct.) +.LP +.IP " 6." 4 +The file shall be identified as a data file. +.LP +.LP +If \fIfile\fP does not exist, cannot be read, or its file status could +not be determined, the output shall indicate that the +file was processed, but that its type could not be determined. +.LP +If \fIfile\fP is a symbolic link, by default the link shall be resolved +and \fIfile\fP shall test the type of file referenced +by the symbolic link. +.SH OPTIONS +.LP +The \fIfile\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that the order of the \fB-m\fP, +\fB-d\fP, and \fB-M\fP options shall be significant. +.LP +The following options shall be supported by the implementation: +.TP 7 +\fB-d\fP +Apply any position-sensitive default system tests and context-sensitive +default system tests to the file. This is the default +if no \fB-M\fP or \fB-m\fP option is specified. +.TP 7 +\fB-h\fP +When a symbolic link is encountered, identify the file as a symbolic +link. If \fB-h\fP is not specified and \fIfile\fP is a +symbolic link that refers to a nonexistent file, \fIfile\fP shall +identify the file as a symbolic link, as if \fB-h\fP had been +specified. +.TP 7 +\fB-i\fP +If a file is a regular file, do not attempt to classify the type of +the file further, but identify the file as specified in the +STDOUT section. +.TP 7 +\fB-M\ \fP \fIfile\fP +Specify the name of a file containing position-sensitive tests that +shall be applied to a file in order to classify it (see the +EXTENDED DESCRIPTION). No position-sensitive default system tests +nor context-sensitive default system tests shall be applied +unless the \fB-d\fP option is also specified. +.TP 7 +\fB-m\ \fP \fIfile\fP +Specify the name of a file containing position-sensitive tests that +shall be applied to a file in order to classify it (see the +EXTENDED DESCRIPTION). +.sp +.LP +If the \fB-m\fP option is specified without specifying the \fB-d\fP +option or the \fB-M\fP option, position-sensitive default +system tests shall be applied after the position-sensitive tests specified +by the \fB-m\fP option. If the \fB-M\fP option is +specified with the \fB-d\fP option, the \fB-m\fP option, or both, +or the \fB-m\fP option is specified with the \fB-d\fP option, +the concatenation of the position-sensitive tests specified by these +options shall be applied in the order specified by the +appearance of these options. If a \fB-M\fP or \fB-m\fP \fIfile\fP +option-argument is \fB-\fP, the results are unspecified. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a file to be tested. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +The \fIfile\fP can be any file type. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIfile\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +In the POSIX locale, the following format shall be used to identify +each operand, \fIfile\fP specified: +.sp +.RS +.nf + +\fB"%s: %s\\n", <\fP\fIfile\fP\fB>, <\fP\fItype\fP\fB> +\fP +.fi +.RE +.LP +The values for <\fItype\fP> are unspecified, except that in the POSIX +locale, if \fIfile\fP is identified as one of the +types listed in the following table, <\fItype\fP> shall contain (but +is not limited to) the corresponding string, unless the +file is identified by a position-sensitive test specified by a \fB-M\fP +or \fB-m\fP option. Each space shown in the strings shall +be exactly one . +.br +.sp +.ce 1 +\fBTable: File Utility Output Strings\fP +.TS C +center; lw(40)1 lw(25)1 l. +T{ +.na +\fBIf \fIfile\fP is:\fP +.ad +T} T{ +.na +\fB<\fItype\fP> shall contain the string:\fP +.ad +T} \fBNotes\fP +T{ +.na +Nonexistent +.ad +T} T{ +.na +cannot open +.ad +T} \ +T{ +.na +Block special +.ad +T} T{ +.na +block special +.ad +T} 1 +T{ +.na +Character special +.ad +T} T{ +.na +character special +.ad +T} 1 +T{ +.na +Directory +.ad +T} T{ +.na +directory +.ad +T} 1 +T{ +.na +FIFO +.ad +T} T{ +.na +fifo +.ad +T} 1 +T{ +.na +Socket +.ad +T} T{ +.na +socket +.ad +T} 1 +T{ +.na +Symbolic link +.ad +T} T{ +.na +symbolic link to +.ad +T} 1 +T{ +.na +Regular file +.ad +T} T{ +.na +regular file +.ad +T} 1,2 +T{ +.na +Empty regular file +.ad +T} T{ +.na +empty +.ad +T} 3 +T{ +.na +Regular file that cannot be read +.ad +T} T{ +.na +cannot open +.ad +T} 3 +T{ +.na +Executable binary +.ad +T} T{ +.na +executable +.ad +T} 4,6 +T{ +.na +\fIar\fP archive library (see \fIar\fP) +.ad +T} T{ +.na +archive +.ad +T} 4,6 +T{ +.na +Extended \fIcpio\fP format (see \fIpax\fP) +.ad +T} T{ +.na +cpio archive +.ad +T} 4,6 +T{ +.na +Extended \fItar\fP format (see \fBustar\fP in \fIpax\fP) +.ad +T} T{ +.na +tar archive +.ad +T} 4,6 +T{ +.na +Shell script +.ad +T} T{ +.na +commands text +.ad +T} 5,6 +T{ +.na +C-language source +.ad +T} T{ +.na +c program text +.ad +T} 5,6 +T{ +.na +FORTRAN source +.ad +T} T{ +.na +fortran program text +.ad +T} 5,6 +T{ +.na +Regular file whose type cannot be determined +.ad +T} T{ +.na +data +.ad +T} \ +.TE +.TP 7 +\fBNotes:\fP +.RS +.IP " 1." 4 +This is a file type test. +.LP +.IP " 2." 4 +This test is applied only if the \fB-i\fP option is specified. +.LP +.IP " 3." 4 +This test is applied only if the \fB-i\fP option is not specified. +.LP +.IP " 4." 4 +This is a position-sensitive default system test. +.LP +.IP " 5." 4 +This is a context-sensitive default system test. +.LP +.IP " 6." 4 +Position-sensitive default system tests and context-sensitive default +system tests are not applied if the \fB-M\fP option is +specified unless the \fB-d\fP option is also specified. +.LP +.RE +.sp +.LP +In the POSIX locale, if \fIfile\fP is identified as a symbolic link +(see the \fB-h\fP option), the following alternative +output format shall be used: +.sp +.RS +.nf + +\fB"%s: %s %s\\n", <\fP\fIfile\fP\fB>, <\fP\fItype\fP\fB>, <\fP\fIcontents of link\fP\fB>" +\fP +.fi +.RE +.LP +If the file named by the \fIfile\fP operand does not exist, cannot +be read, or the type of the file named by the \fIfile\fP +operand cannot be determined, this shall not be considered an error +that affects the exit status. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +A file specified as an option-argument to the \fB-m\fP or \fB-M\fP +options shall contain one position-sensitive test per line, +which shall be applied to the file. If the test succeeds, the message +field of the line shall be printed and no further tests shall +be applied, with the exception that tests on immediately following +lines beginning with a single \fB'>'\fP character shall be +applied. +.LP +Each line shall be composed of the following four -separated +fields: +.TP 7 +\fIoffset\fP +An unsigned number (optionally preceded by a single \fB'>'\fP character) +specifying the \fIoffset\fP, in bytes, of the +value in the file that is to be compared against the \fIvalue\fP field +of the line. If the file is shorter than the specified +offset, the test shall fail. +.LP +If the \fIoffset\fP begins with the character \fB'>'\fP , the test +contained in the line shall not be applied to the file +unless the test on the last line for which the \fIoffset\fP did not +begin with a \fB'>'\fP was successful. By default, the +\fIoffset\fP shall be interpreted as an unsigned decimal number. With +a leading 0x or 0X, the \fIoffset\fP shall be interpreted +as a hexadecimal number; otherwise, with a leading 0, the \fIoffset\fP +shall be interpreted as an octal number. +.TP 7 +\fItype\fP +The type of the value in the file to be tested. The type shall consist +of the type specification characters \fBc\fP , +\fBd\fP , \fBf\fP , \fBs\fP , and \fBu\fP , specifying character, +signed decimal, floating point, string, and unsigned +decimal, respectively. +.LP +The \fItype\fP string shall be interpreted as the bytes from the file +starting at the specified \fIoffset\fP and including the +same number of bytes specified by the \fIvalue\fP field. If insufficient +bytes remain in the file past the \fIoffset\fP to match +the \fIvalue\fP field, the test shall fail. +.LP +The type specification characters \fBd\fP , \fBf\fP , and \fBu\fP +can be followed by an optional unsigned decimal +integer that specifies the number of bytes represented by the type. +The type specification character \fBf\fP can be followed by +an optional \fBF\fP , \fBD\fP , or \fBL\fP , indicating that the value +is of type \fBfloat\fP, \fBdouble\fP, or \fBlong +double\fP, respectively. The type specification characters \fBd\fP +and \fBu\fP can be followed by an optional \fBC\fP , +\fBS\fP , \fBI\fP , or \fBL\fP , indicating that the value is of type +\fBchar\fP, \fBshort\fP, \fBint\fP, or +\fBlong\fP, respectively. +.LP +The default number of bytes represented by the type specifiers \fBd\fP +, \fBf\fP , and \fBu\fP shall correspond to +their respective C-language types as follows. If the system claims +conformance to the C-Language Development Utilities option, +those specifiers shall correspond to the default sizes used in the +\fIc99\fP utility. +Otherwise, the default sizes shall be implementation-defined. +.LP +For the type specifier characters \fBd\fP and \fBu\fP , the default +number of bytes shall correspond to the size of a +basic integer type of the implementation. For these specifier characters, +the implementation shall support values of the optional +number of bytes to be converted corresponding to the number of bytes +in the C-language types \fBchar\fP, \fBshort\fP, \fBint\fP, +or \fBlong\fP. These numbers can also be specified by an application +as the characters \fBC\fP , \fBS\fP , \fBI\fP , and +\fBL\fP , respectively. The byte order used when interpreting numeric +values is implementation-defined, but shall correspond to +the order in which a constant of the corresponding type is stored +in memory on the system. +.LP +For the type specifier \fBf\fP , the default number of bytes shall +correspond to the number of bytes in the basic double +precision floating-point data type of the underlying implementation. +The implementation shall support values of the optional number +of bytes to be converted corresponding to the number of bytes in the +C-language types \fBfloat\fP, \fBdouble\fP, and \fBlong +double\fP. These numbers can also be specified by an application as +the characters \fBF\fP , \fBD\fP , and \fBL\fP , +respectively. +.LP +All type specifiers, except for \fBs\fP , can be followed by a mask +specifier of the form &\fInumber\fP. The mask value +shall be AND'ed with the value of the input file before the comparison +with the \fIvalue\fP field of the line is made. By default, +the mask shall be interpreted as an unsigned decimal number. With +a leading 0x or 0X, the mask shall be interpreted as an unsigned +hexadecimal number; otherwise, with a leading 0, the mask shall be +interpreted as an unsigned octal number. +.LP +The strings \fBbyte\fP, \fBshort\fP, \fBlong\fP, and \fBstring\fP +shall also be supported as type fields, being interpreted +as \fBdC\fP , \fBdS\fP , \fBdL\fP , and \fBs\fP , respectively. +.TP 7 +\fIvalue\fP +The \fIvalue\fP to be compared with the value from the file. +.LP +If the specifier from the type field is \fBs\fP or \fBstring\fP, then +interpret the value as a string. Otherwise, interpret +it as a number. If the value is a string, then the test shall succeed +only when a string value exactly matches the bytes from the +file. +.LP +If the \fIvalue\fP is a string, it can contain the following sequences: +.TP 7 +\\\fIcharacter\fP +.RS +The backslash-escape sequences as specified in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Table 5-1, Escape +Sequences and Associated Actions ( \fB'\\\\'\fP , \fB'\\a'\fP , \fB'\\b'\fP +, \fB'\\f'\fP , \fB'\\n'\fP , \fB'\\r'\fP , +\fB'\\t'\fP , \fB'\\v'\fP ). The results of using any other character, +other than an octal digit, following the backslash are +unspecified. +.RE +.TP 7 +\\\fIoctal\fP +.RS +Octal sequences that can be used to represent characters with specific +coded values. An octal sequence shall consist of a +backslash followed by the longest sequence of one, two, or three octal-digit +characters (01234567). If the size of a byte on the +system is greater than 9 bits, the valid escape sequence used to represent +a byte is implementation-defined. +.RE +.sp +.LP +By default, any value that is not a string shall be interpreted as +a signed decimal number. Any such value, with a leading 0x or +0X, shall be interpreted as an unsigned hexadecimal number; otherwise, +with a leading zero, the value shall be interpreted as an +unsigned octal number. +.LP +If the value is not a string, it can be preceded by a character indicating +the comparison to be performed. Permissible +characters and the comparisons they specify are as follows: +.TP 7 +\fB=\fP +.RS +The test shall succeed if the value from the file equals the \fIvalue\fP +field. +.RE +.TP 7 +\fB<\fP +.RS +The test shall succeed if the value from the file is less than the +\fIvalue\fP field. +.RE +.TP 7 +\fB>\fP +.RS +The test shall succeed if the value from the file is greater than +the \fIvalue\fP field. +.RE +.TP 7 +\fB&\fP +.RS +The test shall succeed if all of the set bits in the \fIvalue\fP field +are set in the value from the file. +.RE +.TP 7 +\fB^\fP +.RS +The test shall succeed if at least one of the set bits in the \fIvalue\fP +field is not set in the value from the file. +.RE +.TP 7 +\fBx\fP +.RS +The test shall succeed if the file is large enough to contain a value +of the type specified starting at the offset +specified. +.RE +.sp +.TP 7 +\fImessage\fP +The \fImessage\fP to be printed if the test succeeds. The \fImessage\fP +shall be interpreted using the notation for the \fIprintf\fP formatting +specification; see \fIprintf\fP() . If the +\fIvalue\fP field was a string, then the value from the file shall +be the argument for the \fIprintf\fP formatting specification; otherwise, +the value from the file shall be the +argument. +.sp +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fIfile\fP utility can only be required to guess at many of the +file types because only exhaustive testing can determine +some types with certainty. For example, binary data on some implementations +might match the initial segment of an executable or a +\fItar\fP archive. +.LP +Note that the table indicates that the output contains the stated +string. Systems may add text before or after the string. For +executables, as an example, the machine architecture and various facts +about how the file was link-edited may be included. Note +also that on systems that recognize shell script files starting with +\fB"#!"\fP as executable files, these may be identified as +executable binary files rather than as shell scripts. +.SH EXAMPLES +.LP +Determine whether an argument is a binary executable file: +.sp +.RS +.nf + +\fBfile "$1" | grep -Fq executable && + printf "%s is executable.\\n" "$1" +\fP +.fi +.RE +.SH RATIONALE +.LP +The \fB-f\fP option was omitted because the same effect can (and should) +be obtained using the \fIxargs\fP utility. +.LP +Historical versions of the \fIfile\fP utility attempt to identify +the following types of files: symbolic link, directory, +character special, block special, socket, \fItar\fP archive, \fIcpio\fP +archive, SCCS archive, archive library, empty, \fIcompress\fP output, +\fIpack\fP output, binary data, C source, FORTRAN source, assembler +source, \fInroff\fP/ \fItroff\fP/ \fIeqn\fP/ \fItbl\fP source \fItroff\fP +output, shell script, C shell script, English text, +ASCII text, various executables, APL workspace, compiled terminfo +entries, and CURSES screen images. Only those types that are +reasonably well specified in POSIX or are directly related to POSIX +utilities are listed in the table. +.LP +Historical systems have used a "magic file" named \fB/etc/magic\fP +to help identify file types. Because it is generally +useful for users and scripts to be able to identify special file types, +the \fB-m\fP flag and a portable format for user-created +magic files has been specified. No requirement is made that an implementation +of \fIfile\fP use this method of identifying files, +only that users be permitted to add their own classifying tests. +.LP +In addition, three options have been added to historical practice. +The \fB-d\fP flag has been added to permit users to cause +their tests to follow any default system tests. The \fB-i\fP flag +has been added to permit users to test portably for regular +files in shell scripts. The \fB-M\fP flag has been added to permit +users to ignore any default system tests. +.LP +The IEEE\ Std\ 1003.1-2001 description of default system tests and +the interaction between the \fB-d\fP, \fB-M\fP, and +\fB-m\fP options did not clearly indicate that there were two types +of "default system tests". The "position-sensitive tests'' +determine file types by looking for certain string or binary values +at specific offsets in the file being examined. These +position-sensitive tests were implemented in historical systems using +the magic file described above. Some of these tests are now +built into the \fIfile\fP utility itself on some implementations so +the output can provide more detail than can be provided by +magic files. For example, a magic file can easily identify a \fBcore\fP +file on most implementations, but cannot name the program +file that dropped the core. A magic file could produce output such +as: +.sp +.RS +.nf + +\fB/home/dwc/core: ELF 32-bit MSB core file SPARC Version 1 +\fP +.fi +.RE +.LP +but by building the test into the \fIfile\fP utility, you could get +output such as: +.sp +.RS +.nf + +\fB/home/dwc/core: ELF 32-bit MSB core file SPARC Version 1, from 'testprog' +\fP +.fi +.RE +.LP +These extended built-in tests are still to be treated as position-sensitive +default system tests even if they are not listed in +\fB/etc/magic\fP or any other magic file. +.LP +The context-sensitive default system tests were always built into +the \fIfile\fP utility. These tests looked for language +constructs in text files trying to identify shell scripts, C, FORTRAN, +and other computer language source files, and even plain +text files. With the addition of the \fB-m\fP and \fB-M\fP options +the distinction between position-sensitive and +context-sensitive default system tests became important because the +order of testing is important. The context-sensitive system +default tests should never be applied before any position-sensitive +tests even if the \fB-d\fP option is specified before a +\fB-m\fP option or \fB-M\fP option due to the high probability that +the context-sensitive system default tests will incorrectly +identify arbitrary text files as text files before position-sensitive +tests specified by the \fB-m\fP or \fB-M\fP option would be +applied to give a more accurate identification. +.LP +Leaving the meaning of \fB-M -\fP and \fB-m -\fP unspecified allows +an existing prototype of these options to continue to work +in a backwards-compatible manner. (In that implementation, \fB-M -\fP +was roughly equivalent to \fB-d\fP in +IEEE\ Std\ 1003.1-2001.) +.LP +The historical \fB-c\fP option was omitted as not particularly useful +to users or portable shell scripts. In addition, a +reasonable implementation of the \fIfile\fP utility would report any +errors found each time the magic file is read. +.LP +The historical format of the magic file was the same as that specified +by the Rationale in the ISO\ POSIX-2:1993 standard +for the \fIoffset\fP, \fIvalue\fP, and \fImessage\fP fields; however, +it used less precise type fields than the format specified +by the current normative text. The new type field values are a superset +of the historical ones. +.LP +The following is an example magic file: +.sp +.RS +.nf + +\fB0 short 070707 cpio archive +0 short 0143561 Byte-swapped cpio archive +0 string 070707 ASCII cpio archive +0 long 0177555 Very old archive +0 short 0177545 Old archive +0 short 017437 Old packed data +0 string \\037\\036 Packed data +0 string \\377\\037 Compacted data +0 string \\037\\235 Compressed data +>2 byte&0x80 >0 Block compressed +>2 byte&0x1f x %d bits +0 string \\032\\001 Compiled Terminfo Entry +0 short 0433 Curses screen image +0 short 0434 Curses screen image +0 string System V Release 1 archive +0 string !\\n__.SYMDEF Archive random library +0 string ! Archive +0 string ARF_BEGARF PHIGS clear text archive +0 long 0x137A2950 Scalable OpenFont binary +0 long 0x137A2951 Encrypted scalable OpenFont binary +\fP +.fi +.RE +.LP +The use of a basic integer data type is intended to allow the implementation +to choose a word size commonly used by applications +on that architecture. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIar\fP , \fIls\fP , \fIpax\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/find.1p b/man1p/find.1p new file mode 100644 index 000000000..6dbca5e73 --- /dev/null +++ b/man1p/find.1p @@ -0,0 +1,696 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FIND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" find +.SH NAME +find \- find files +.SH SYNOPSIS +.LP +\fBfind\fP \fB[\fP\fB-H | -L\fP\fB]\fP \fIpath\fP \fB...\fP \fB[\fP\fIoperand_expression\fP +\fB\&...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIfind\fP utility shall recursively descend the directory hierarchy +from each file specified by \fIpath\fP, evaluating a +Boolean expression composed of the primaries described in the OPERANDS +section for each file encountered. +.LP +The \fIfind\fP utility shall be able to descend to arbitrary depths +in a file hierarchy and shall not fail due to path length +limitations (unless a \fIpath\fP operand specified by the application +exceeds {PATH_MAX} requirements). +.LP +The \fIfind\fP utility shall detect infinite loops; that is, entering +a previously visited directory that is an ancestor of the +last file encountered. When it detects an infinite loop, \fIfind\fP +shall write a diagnostic message to standard error and shall +either recover its position in the hierarchy or terminate. +.SH OPTIONS +.LP +The \fIfind\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported by the implementation: +.TP 7 +\fB-H\fP +Cause the file information and file type evaluated for each symbolic +link encountered on the command line to be those of the +file referenced by the link, and not the link itself. If the referenced +file does not exist, the file information and type shall be +for the link itself. File information for all symbolic links not on +the command line shall be that of the link itself. +.TP 7 +\fB-L\fP +Cause the file information and file type evaluated for each symbolic +link to be those of the file referenced by the link, and +not the link itself. +.sp +.LP +Specifying more than one of the mutually-exclusive options \fB-H\fP +and \fB-L\fP shall not be considered an error. The last +option specified shall determine the behavior of the utility. +.SH OPERANDS +.LP +The following operands shall be supported: +.LP +The \fIpath\fP operand is a pathname of a starting point in the directory +hierarchy. +.LP +The first argument that starts with a \fB'-'\fP , or is a \fB'!'\fP +or a \fB'('\fP , and all subsequent arguments shall +be interpreted as an \fIexpression\fP made up of the following primaries +and operators. In the descriptions, wherever \fIn\fP is +used as a primary argument, it shall be interpreted as a decimal integer +optionally preceded by a plus ( \fB'+'\fP ) or minus ( +\fB'-'\fP ) sign, as follows: +.TP 7 ++\fIn\fP +More than \fIn\fP. +.TP 7 +\fIn\fP +Exactly \fIn\fP. +.TP 7 +-\fIn\fP +Less than \fIn\fP. +.sp +.LP +The following primaries shall be supported: +.TP 7 +\fB-name\ \fP \fIpattern\fP +.sp +The primary shall evaluate as true if the basename of the filename +being examined matches \fIpattern\fP using the pattern matching +notation described in \fIPattern Matching Notation\fP . +.TP 7 +\fB-nouser\fP +The primary shall evaluate as true if the file belongs to a user ID +for which the \fIgetpwuid\fP() function defined in the System Interfaces +volume of +IEEE\ Std\ 1003.1-2001 (or equivalent) returns NULL. +.TP 7 +\fB-nogroup\fP +The primary shall evaluate as true if the file belongs to a group +ID for which the \fIgetgrgid\fP() function defined in the System Interfaces +volume of +IEEE\ Std\ 1003.1-2001 (or equivalent) returns NULL. +.TP 7 +\fB-xdev\fP +The primary shall always evaluate as true; it shall cause \fIfind\fP +not to continue descending past directories that have a +different device ID ( \fIst_dev\fP, see the \fIstat\fP() function +defined in the System +Interfaces volume of IEEE\ Std\ 1003.1-2001). If any \fB-xdev\fP primary +is specified, it shall apply to the entire +expression even if the \fB-xdev\fP primary would not normally be evaluated. +.TP 7 +\fB-prune\fP +The primary shall always evaluate as true; it shall cause \fIfind\fP +not to descend the current pathname if it is a directory. +If the \fB-depth\fP primary is specified, the \fB-prune\fP primary +shall have no effect. +.TP 7 +\fB-perm\ [-]\fP\fImode\fP +.sp +The \fImode\fP argument is used to represent file mode bits. It shall +be identical in format to the \fIsymbolic_mode\fP operand +described in \fIchmod\fP() , and shall be interpreted as follows. +To start, a template shall be assumed +with all file mode bits cleared. An \fIop\fP symbol of \fB'+'\fP shall +set the appropriate mode bits in the template; +\fB'-'\fP shall clear the appropriate bits; \fB'='\fP shall set the +appropriate mode bits, without regard to the contents of +process' file mode creation mask. The \fIop\fP symbol of \fB'-'\fP +cannot be the first character of \fImode\fP; this avoids +ambiguity with the optional leading hyphen. Since the initial mode +is all bits off, there are not any symbolic modes that need to +use \fB'-'\fP as the first character. +.LP +If the hyphen is omitted, the primary shall evaluate as true when +the file permission bits exactly match the value of the +resulting template. +.LP +Otherwise, if \fImode\fP is prefixed by a hyphen, the primary shall +evaluate as true if at least all the bits in the resulting +template are set in the file permission bits. +.TP 7 +\fB-perm\ [-]\fP\fIonum\fP +.sp +If the hyphen is omitted, the primary shall evaluate as true when +the file permission bits exactly match the value of the octal +number \fIonum\fP and only the bits corresponding to the octal mask +07777 shall be compared. (See the description of the octal +\fImode\fP in \fIchmod\fP() .) Otherwise, if \fIonum\fP is prefixed +by a hyphen, the primary shall +evaluate as true if at least all of the bits specified in \fIonum\fP +that are also set in the octal mask 07777 are set. +.TP 7 +\fB-type\ \fP \fIc\fP +The primary shall evaluate as true if the type of the file is \fIc\fP, +where \fIc\fP is \fB'b'\fP , \fB'c'\fP , +\fB'd'\fP , \fB'l'\fP , \fB'p'\fP , \fB'f'\fP , or \fB's'\fP for block +special file, character special file, +directory, symbolic link, FIFO, regular file, or socket, respectively. +.TP 7 +\fB-links\ \fP \fIn\fP +The primary shall evaluate as true if the file has \fIn\fP links. +.TP 7 +\fB-user\ \fP \fIuname\fP +The primary shall evaluate as true if the file belongs to the user +\fIuname.\fP If \fIuname\fP is a decimal integer and the +\fIgetpwnam\fP() (or equivalent) function does not return a valid +user name, \fIuname\fP +shall be interpreted as a user ID. +.TP 7 +\fB-group\ \fP \fIgname\fP +.sp +The primary shall evaluate as true if the file belongs to the group +\fIgname\fP. If \fIgname\fP is a decimal integer and the \fIgetgrnam\fP() +(or equivalent) function does not return a valid group name, \fIgname\fP +shall be interpreted as a group ID. +.TP 7 +\fB-size\ \fP \fIn\fP\fB[c]\fP +The primary shall evaluate as true if the file size in bytes, divided +by 512 and rounded up to the next integer, is \fIn\fP. +If \fIn\fP is followed by the character \fB'c'\fP , the size shall +be in bytes. +.TP 7 +\fB-atime\ \fP \fIn\fP +The primary shall evaluate as true if the file access time subtracted +from the initialization time, divided by 86400 (with any +remainder discarded), is \fIn\fP. +.TP 7 +\fB-ctime\ \fP \fIn\fP +The primary shall evaluate as true if the time of last change of file +status information subtracted from the initialization +time, divided by 86400 (with any remainder discarded), is \fIn\fP. +.TP 7 +\fB-mtime\ \fP \fIn\fP +The primary shall evaluate as true if the file modification time subtracted +from the initialization time, divided by 86400 +(with any remainder discarded), is \fIn\fP. +.TP 7 +\fB-exec\ \fP \fIutility_name\ \fP \fB[\fP\fIargument\fP\ ...\fB]\ ;\fP +.TP 7 +\fB-exec\ \fP \fIutility_name\ \fP \fB[\fP\fIargument\fP\ ...\fB]\ \ \fP +{}\ + +.sp +The end of the primary expression shall be punctuated by a semicolon +or by a plus sign. Only a plus sign that follows an argument +containing the two characters \fB"{}"\fP shall punctuate the end of +the primary expression. Other uses of the plus sign shall +not be treated as special. +.LP +If the primary expression is punctuated by a semicolon, the utility +\fIutility_name\fP shall be invoked once for each pathname +and the primary shall evaluate as true if the utility returns a zero +value as exit status. A \fIutility_name\fP or \fIargument\fP +containing only the two characters \fB"{}"\fP shall be replaced by +the current pathname. +.LP +If the primary expression is punctuated by a plus sign, the primary +shall always evaluate as true, and the pathnames for which +the primary is evaluated shall be aggregated into sets. The utility +\fIutility_name\fP shall be invoked once for each set of +aggregated pathnames. Each invocation shall begin after the last pathname +in the set is aggregated, and shall be completed before +the \fIfind\fP utility exits and before the first pathname in the +next set (if any) is aggregated for this primary, but it is +otherwise unspecified whether the invocation occurs before, during, +or after the evaluations of other primaries. If any invocation +returns a non-zero value as exit status, the \fIfind\fP utility shall +return a non-zero exit status. An argument containing only +the two characters \fB"{}"\fP shall be replaced by the set of aggregated +pathnames, with each pathname passed as a separate +argument to the invoked utility in the same order that it was aggregated. +The size of any set of two or more pathnames shall be +limited such that execution of the utility does not cause the system's +{ARG_MAX} limit to be exceeded. If more than one argument +containing only the two characters \fB"{}"\fP is present, the behavior +is unspecified. +.LP +If a \fIutility_name\fP or \fIargument\fP string contains the two +characters \fB"{}"\fP , but not just the two characters +\fB"{}"\fP , it is implementation-defined whether \fIfind\fP replaces +those two characters or uses the string without change. +The current directory for the invocation of \fIutility_name\fP shall +be the same as the current directory when the \fIfind\fP +utility was started. If the \fIutility_name\fP names any of the special +built-in utilities (see \fISpecial Built-In Utilities\fP ), the results +are undefined. +.TP 7 +\fB-ok\ \fP \fIutility_name\ \fP \fB[\fP\fIargument\fP\ ...\fB]\ ;\fP +.sp +The \fB-ok\fP primary shall be equivalent to \fB-exec\fP, except that +the use of a plus sign to punctuate the end of the primary +expression need not be supported, and \fIfind\fP shall request affirmation +of the invocation of \fIutility_name\fP using the +current file as an argument by writing to standard error as described +in the STDERR section. If the response on standard input is +affirmative, the utility shall be invoked. Otherwise, the command +shall not be invoked and the value of the \fB-ok\fP operand +shall be false. +.TP 7 +\fB-print\fP +The primary shall always evaluate as true; it shall cause the current +pathname to be written to standard output. +.TP 7 +\fB-newer\ \fP \fIfile\fP +The primary shall evaluate as true if the modification time of the +current file is more recent than the modification time of +the file named by the pathname \fIfile\fP. +.TP 7 +\fB-depth\fP +The primary shall always evaluate as true; it shall cause descent +of the directory hierarchy to be done so that all entries in +a directory are acted on before the directory itself. If a \fB-depth\fP +primary is not specified, all entries in a directory shall +be acted on after the directory itself. If any \fB-depth\fP primary +is specified, it shall apply to the entire expression even if +the \fB-depth\fP primary would not normally be evaluated. +.sp +.LP +The primaries can be combined using the following operators (in order +of decreasing precedence): +.TP 7 +(\ \fIexpression\fP\ ) +True if \fIexpression\fP is true. +.TP 7 +\fB!\ \fP \fIexpression\fP +Negation of a primary; the unary NOT operator. +.TP 7 +\fIexpression\ \fP \fB[-a]\ \fP \fIexpression\fP +.sp +Conjunction of primaries; the AND operator is implied by the juxtaposition +of two primaries or made explicit by the optional +\fB-a\fP operator. The second expression shall not be evaluated if +the first expression is false. +.TP 7 +\fIexpression\ \fP \fB-o\ \fP \fIexpression\fP +.sp +Alternation of primaries; the OR operator. The second expression shall +not be evaluated if the first expression is true. +.sp +.LP +If no \fIexpression\fP is present, \fB-print\fP shall be used as the +expression. Otherwise, if the given expression does not +contain any of the primaries \fB-exec\fP, \fB-ok\fP, or \fB-print\fP, +the given expression shall be effectively replaced by: +.sp +.RS +.nf + +\fB(\fP \fIgiven_expression\fP \fB) -print +\fP +.fi +.RE +.LP +The \fB-user\fP, \fB-group\fP, and \fB-newer\fP primaries each shall +evaluate their respective arguments only once. +.SH STDIN +.LP +If the \fB-ok\fP primary is used, the response shall be read from +the standard input. An entire line shall be read as the +response. Otherwise, the standard input shall not be used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIfind\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the pattern +matching notation for the \fB-n\fP option and in the extended regular +expression defined for the \fByesexpr\fP locale keyword in +the \fILC_MESSAGES\fP category. +.TP 7 +\fILC_CTYPE\fP +This variable determines the locale for the interpretation of sequences +of bytes of text data as characters (for example, +single-byte as opposed to multi-byte characters in arguments), the +behavior of character classes within the pattern matching +notation used for the \fB-n\fP option, and the behavior of character +classes within regular expressions used in the extended +regular expression defined for the \fByesexpr\fP locale keyword in +the \fILC_MESSAGES\fP category. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale for the processing of affirmative responses that +should be used to affect the format and contents of +diagnostic messages written to standard error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPATH\fP +Determine the location of the \fIutility_name\fP for the \fB-exec\fP +and \fB-ok\fP primaries, as described in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment +Variables. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fB-print\fP primary shall cause the current pathnames to be written +to standard output. The format shall be: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIpath\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The \fB-ok\fP primary shall write a prompt to standard error containing +at least the \fIutility_name\fP to be invoked and the +current pathname. In the POSIX locale, the last non- in the +prompt shall be \fB'?'\fP . The exact format used is +unspecified. +.LP +Otherwise, the standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All \fIpath\fP operands were traversed successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +When used in operands, pattern matching notation, semicolons, opening +parentheses, and closing parentheses are special to the +shell and must be quoted (see \fIQuoting\fP ). +.LP +The bit that is traditionally used for sticky (historically 01000) +is specified in the \fB-perm\fP primary using the octal +number argument form. Since this bit is not defined by this volume +of IEEE\ Std\ 1003.1-2001, applications must not assume +that it actually refers to the traditional sticky bit. +.SH EXAMPLES +.IP " 1." 4 +The following commands are equivalent: +.sp +.RS +.nf + +\fBfind . +find . -print +\fP +.fi +.RE +.LP +They both write out the entire directory hierarchy from the current +directory. +.LP +.IP " 2." 4 +The following command: +.sp +.RS +.nf + +\fBfind / \\( -name tmp -o -name '*.xx' \\) -atime +7 -exec rm {} \\; +\fP +.fi +.RE +.LP +removes all files named \fBtmp\fP or ending in \fB.xx\fP that have +not been accessed for seven or more 24-hour periods. +.LP +.IP " 3." 4 +The following command: +.sp +.RS +.nf + +\fBfind . -perm -o+w,+s +\fP +.fi +.RE +.LP +prints ( \fB-print\fP is assumed) the names of all files in or below +the current directory, with all of the file permission +bits S_ISUID, S_ISGID, and S_IWOTH set. +.LP +.IP " 4." 4 +The following command: +.sp +.RS +.nf + +\fBfind . -name SCCS -prune -o -print +\fP +.fi +.RE +.LP +recursively prints pathnames of all files in the current directory +and below, but skips directories named SCCS and files in +them. +.LP +.IP " 5." 4 +The following command: +.sp +.RS +.nf + +\fBfind . -print -name SCCS -prune +\fP +.fi +.RE +.LP +behaves as in the previous example, but prints the names of the SCCS +directories. +.LP +.IP " 6." 4 +The following command is roughly equivalent to the \fB-nt\fP extension +to \fItest\fP: +.sp +.RS +.nf + +\fBif [ -n "$(find file1 -prune -newer file2)" ]; then + printf %s\\\\n "file1 is newer than file2" +fi +\fP +.fi +.RE +.LP +.IP " 7." 4 +The descriptions of \fB-atime\fP, \fB-ctime\fP, and \fB-mtime\fP use +the terminology \fIn\fP "86400 second periods +(days)". For example, a file accessed at 23:59 is selected by: +.sp +.RS +.nf + +\fBfind . -atime -1 -print +\fP +.fi +.RE +.LP +at 00:01 the next day (less than 24 hours later, not more than one +day ago); the midnight boundary between days has no effect on +the 24-hour calculation. +.LP +.SH RATIONALE +.LP +The \fB-a\fP operator was retained as an optional operator for compatibility +with historical shell scripts, even though it is +redundant with expression concatenation. +.LP +The descriptions of the \fB'-'\fP modifier on the \fImode\fP and \fIonum\fP +arguments to the \fB-perm\fP primary agree +with historical practice on BSD and System V implementations. System +V and BSD documentation both describe it in terms of checking +additional bits; in fact, it uses the same bits, but checks for having +at least all of the matching bits set instead of having +exactly the matching bits set. +.LP +The exact format of the interactive prompts is unspecified. Only the +general nature of the contents of prompts are specified +because: +.IP " *" 3 +Implementations may desire more descriptive prompts than those used +on historical implementations. +.LP +.IP " *" 3 +Since the historical prompt strings do not terminate with s, +there is no portable way for another program to +interact with the prompts of this utility via pipes. +.LP +.LP +Therefore, an application using this prompting option relies on the +system to provide the most suitable dialog directly with the +user, based on the general guidelines specified. +.LP +The \fB-name\fP \fIfile\fP operand was changed to use the shell pattern +matching notation so that \fIfind\fP is consistent +with other utilities using pattern matching. +.LP +The \fB-size\fP operand refers to the size of a file, rather than +the number of blocks it may occupy in the file system. The +intent is that the \fIst_size\fP field defined in the System Interfaces +volume of IEEE\ Std\ 1003.1-2001 should be used, +not the \fIst_blocks\fP found in historical implementations. There +are at least two reasons for this: +.IP " 1." 4 +In both System V and BSD, \fIfind\fP only uses \fIst_size\fP in size +calculations for the operands specified by this volume of +IEEE\ Std\ 1003.1-2001. (BSD uses \fIst_blocks\fP only when processing +the \fB-ls\fP primary.) +.LP +.IP " 2." 4 +Users usually think of file size in terms of bytes, which is also +the unit used by the \fIls\fP utility for the output from the \fB-l\fP +option. (In both System V and BSD, \fIls\fP uses \fIst_size\fP for +the \fB-l\fP option size field and uses \fIst_blocks\fP for the \fIls\fP +\fB-s\fP calculations. This volume of IEEE\ Std\ 1003.1-2001 does +not specify \fIls\fP \fB-s\fP.) +.LP +.LP +The descriptions of \fB-atime\fP, \fB-ctime\fP, and \fB-mtime\fP were +changed from the SVID description of \fIn\fP "days'' +to "24-hour periods". The description is also different in terms of +the exact timeframe for the \fIn\fP case (\fIversus\fP the +\fI+n\fP or \fI-n\fP), but it matches all known historical implementations. +It refers to one 86400 second period in the past, not +any time from the beginning of that period to the current time. For +example, \fB-atime\fP 3 is true if the file was accessed any +time in the period from 72 hours to 48 hours ago. +.LP +Historical implementations do not modify \fB"{}"\fP when it appears +as a substring of an \fB-exec\fP or \fB-ok\fP +\fIutility_name\fP or argument string. There have been numerous user +requests for this extension, so this volume of +IEEE\ Std\ 1003.1-2001 allows the desired behavior. At least one recent +implementation does support this feature, but +encountered several problems in managing memory allocation and dealing +with multiple occurrences of \fB"{}"\fP in a string while +it was being developed, so it is not yet required behavior. +.LP +Assuming the presence of \fB-print\fP was added to correct a historical +pitfall that plagues novice users, it is entirely +upwards-compatible from the historical System V \fIfind\fP utility. +In its simplest form ( \fIfind\fP \fIdirectory\fP), it could +be confused with the historical BSD fast \fIfind\fP. The BSD developers +agreed that adding \fB-print\fP as a default expression +was the correct decision and have added the fast \fIfind\fP functionality +within a new utility called \fIlocate\fP. +.LP +Historically, the \fB-L\fP option was implemented using the primary +\fB-follow\fP. The \fB-H\fP and \fB-L\fP options were +added for two reasons. First, they offer a finer granularity of control +and consistency with other programs that walk file +hierarchies. Second, the \fB-follow\fP primary always evaluated to +true. As they were historically really global variables that +took effect before the traversal began, some valid expressions had +unexpected results. An example is the expression \fB-print\fP +\fB-o\fP \fB-follow\fP. Because \fB-print\fP always evaluates to true, +the standard order of evaluation implies that +\fB-follow\fP would never be evaluated. This was never the case. Historical +practice for the \fB-follow\fP primary, however, is +not consistent. Some implementations always follow symbolic links +on the command line whether \fB-follow\fP is specified or not. +Others follow symbolic links on the command line only if \fB-follow\fP +is specified. Both behaviors are provided by the \fB-H\fP +and \fB-L\fP options, but scripts using the current \fB-follow\fP +primary would be broken if the \fB-follow\fP option is +specified to work either way. +.LP +Since the \fB-L\fP option resolves all symbolic links and the \fB-type\fP +\fIl\fP primary is true for symbolic links that +still exist after symbolic links have been resolved, the command: +.sp +.RS +.nf + +\fBfind -L . -type l +\fP +.fi +.RE +.LP +prints a list of symbolic links reachable from the current directory +that do not resolve to accessible files. +.LP +A feature of SVR4's \fIfind\fP utility was the \fB-exec\fP primary's +\fB+\fP terminator. This allowed filenames containing +special characters (especially s) to be grouped together +without the problems that occur if such filenames are piped +to \fIxargs\fP. Other implementations have added other ways to get +around this problem, +notably a \fB-print0\fP primary that wrote filenames with a null byte +terminator. This was considered here, but not adopted. Using +a null terminator meant that any utility that was going to process +\fIfind\fP's \fB-print0\fP output had to add a new option to +parse the null terminators it would now be reading. +.LP +The \fB"-exec ... {} +"\fP syntax adopted was a result of IEEE PASC +Interpretation 1003.2 #210. It should be noted that this +is an incompatible change to the ISO/IEC\ 9899:1999 standard. For +example, the following command prints all files with a +\fB'-'\fP after their name if they are regular files, and a \fB'+'\fP +otherwise: +.sp +.RS +.nf + +\fBfind / -type f -exec echo {} - ';' -o -exec echo {} + ';' +\fP +.fi +.RE +.LP +The change invalidates usage like this. Even though the previous standard +stated that this usage would work, in practice many +did not support it and the standard developers felt it better to now +state that this was not allowable. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIQuoting\fP , \fIPattern Matching +Notation\fP , \fISpecial Built-In Utilities\fP , \fIchmod\fP() , \fIpax\fP +, \fIsh\fP , \fItest\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIgetgrgid\fP(), \fIgetpwuid\fP(), \fIstat\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/fold.1p b/man1p/fold.1p new file mode 100644 index 000000000..888061ec8 --- /dev/null +++ b/man1p/fold.1p @@ -0,0 +1,225 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FOLD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fold +.SH NAME +fold \- filter for folding lines +.SH SYNOPSIS +.LP +\fBfold\fP \fB[\fP\fB-bs\fP\fB][\fP\fB-w\fP \fIwidth\fP\fB][\fP\fIfile\fP\fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIfold\fP utility is a filter that shall fold lines from its +input files, breaking the lines to have a maximum of +\fIwidth\fP column positions (or bytes, if the \fB-b\fP option is +specified). Lines shall be broken by the insertion of a + such that each output line (referred to later in this section +as a \fIsegment\fP) is the maximum width possible +that does not exceed the specified number of column positions (or +bytes). A line shall not be broken in the middle of a character. +The behavior is undefined if \fIwidth\fP is less than the number of +columns any single character in the input would occupy. +.LP +If the s, s, or s are encountered +in the input, and the \fB-b\fP option is +not specified, they shall be treated specially: +.TP 7 + +The current count of line width shall be decremented by one, although +the count never shall become negative. The \fIfold\fP +utility shall not insert a immediately before or after any +. +.TP 7 + +.sp +The current count of line width shall be set to zero. The \fIfold\fP +utility shall not insert a immediately before +or after any . +.TP 7 + +Each encountered shall advance the column position pointer to +the next tab stop. Tab stops shall be at each column +position \fIn\fP such that \fIn\fP modulo 8 equals 1. +.sp +.SH OPTIONS +.LP +The \fIfold\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-b\fP +Count \fIwidth\fP in bytes rather than column positions. +.TP 7 +\fB-s\fP +If a segment of a line contains a within the first \fIwidth\fP +column positions (or bytes), break the line after +the last such meeting the width constraints. If there is no + meeting the requirements, the \fB-s\fP +option shall have no effect for that output segment of the input line. +.TP 7 +\fB-w\ \fP \fIwidth\fP +Specify the maximum line length, in column positions (or bytes if +\fB-b\fP is specified). The results are unspecified if +\fIwidth\fP is not a positive decimal number. The default value shall +be 80. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a text file to be folded. If no \fIfile\fP operands +are specified, the standard input shall be used. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified. See the INPUT FILES section. +.SH INPUT FILES +.LP +If the \fB-b\fP option is specified, the input files shall be text +files except that the lines are not limited to {LINE_MAX} +bytes in length. If the \fB-b\fP option is not specified, the input +files shall be text files. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIfold\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), and +for the determination of the width in column positions each +character would occupy on a constant-width font output device. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall be a file containing a sequence of characters +whose order shall be preserved from the input files, +possibly with inserted s. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All input files were processed successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fIcut\fP and \fIfold\fP utilities can be used to create text +files out of files with +arbitrary line lengths. The \fIcut\fP utility should be used when +the number of lines (or +records) needs to remain constant. The \fIfold\fP utility should be +used when the contents of long lines need to be kept +contiguous. +.LP +The \fIfold\fP utility is frequently used to send text files to printers +that truncate, rather than fold, lines wider than the +printer is able to print (usually 80 or 132 column positions). +.SH EXAMPLES +.LP +An example invocation that submits a file of possibly long lines to +the printer (under the assumption that the user knows the +line width of the printer to be assigned by \fIlp\fP): +.sp +.RS +.nf + +\fBfold -w 132 bigfile | lp +\fP +.fi +.RE +.SH RATIONALE +.LP +Although terminal input in canonical processing mode requires the +erase character (frequently set to ) to erase +the previous character (not byte or column position), terminal output +is not buffered and is extremely difficult, if not +impossible, to parse correctly; the interpretation depends entirely +on the physical device that actually displays/prints/stores the +output. In all known internationalized implementations, the utilities +producing output for mixed column-width output assume that a + backs up one column position and outputs enough s +to return to the start of the character when + is used to provide local line motions to support underlining +and emboldening operations. Since \fIfold\fP +without the \fB-b\fP option is dealing with these same constraints, + is always treated as backing up one column +position rather than backing up one character. +.LP +Historical versions of the \fIfold\fP utility assumed 1 byte was one +character and occupied one column position when written +out. This is no longer always true. Since the most common usage of +\fIfold\fP is believed to be folding long lines for output to +limited-length output devices, this capability was preserved as the +default case. The \fB-b\fP option was added so that +applications could \fIfold\fP files with arbitrary length lines into +text files that could then be processed by the standard +utilities. Note that although the width for the \fB-b\fP option is +in bytes, a line is never split in the middle of a character. +(It is unspecified what happens if a width is specified that is too +small to hold a single character found in the input followed by +a .) +.LP +The tab stops are hardcoded to be every eighth column to meet historical +practice. No new method of specifying other tab stops +was invented. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcut\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/fort77.1p b/man1p/fort77.1p new file mode 100644 index 000000000..b860f70ca --- /dev/null +++ b/man1p/fort77.1p @@ -0,0 +1,500 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FORT77" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fort77 +.SH NAME +fort77 \- FORTRAN compiler (\fBFORTRAN\fP) +.SH SYNOPSIS +.LP +\fBfort77\fP \fB[\fP\fB-c\fP\fB][\fP\fB-g\fP\fB][\fP\fB-L\fP +\fIdirectory\fP\fB]\fP\fB...\fP \fB[\fP\fB-O\fP \fIoptlevel\fP\fB][\fP\fB-o\fP +\fIoutfile\fP\fB][\fP\fB-s\fP\fB][\fP\fB-w\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB\fP\fIoperand\fP\fB... \fP +.SH DESCRIPTION +.LP +The \fIfort77\fP utility is the interface to the FORTRAN compilation +system; it shall accept the full FORTRAN-77 language +defined by the ANSI\ X3.9-1978 standard. The system conceptually consists +of a compiler and link editor. The files referenced +by \fIoperand\fPs are compiled and linked to produce an executable +file. It is unspecified whether the linking occurs entirely +within the operation of \fIfort77\fP; some implementations may produce +objects that are not fully resolved until the file is +executed. +.LP +If the \fB-c\fP option is present, for all pathname operands of the +form \fIfile\fP \fB.f\fP, the files: +.sp +.RS +.nf + +\fB$(basename\fP \fIpathname\fP\fB.f).o +\fP +.fi +.RE +.LP +shall be created or overwritten as the result of successful compilation. +If the \fB-c\fP option is not specified, it is +unspecified whether such \fB.o\fP files are created or deleted for +the \fIfile\fP \fB.f\fP operands. +.LP +If there are no options that prevent link editing (such as \fB-c\fP) +and all operands compile and link without error, the +resulting executable file shall be written into the file named by +the \fB-o\fP option (if present) or to the file \fBa.out\fP. +The executable file shall be created as specified in the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, except that +the file permissions shall be set to: +.sp +.RS +.nf + +S_IRWXO | S_IRWXG | S_IRWXU +.fi +.RE +.LP +and that the bits specified by the \fIumask\fP of the process shall +be cleared. +.SH OPTIONS +.LP +The \fIfort77\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that: +.IP " *" 3 +The \fB-l\fP \fIlibrary\fP operands have the format of options, but +their position within a list of operands affects the order +in which libraries are searched. +.LP +.IP " *" 3 +The order of specifying the multiple \fB-L\fP options is significant. +.LP +.IP " *" 3 +Conforming applications shall specify each option separately; that +is, grouping option letters (for example, \fB-cg\fP) need +not be recognized by all implementations. +.LP +.LP +The following options shall be supported: +.TP 7 +\fB-c\fP +Suppress the link-edit phase of the compilation, and do not remove +any object files that are produced. +.TP 7 +\fB-g\fP +Produce symbolic information in the object or executable files; the +nature of this information is unspecified, and may be +modified by implementation-defined interactions with other options. +.TP 7 +\fB-s\fP +Produce object or executable files, or both, from which symbolic and +other information not required for proper execution using +the \fIexec\fP family of functions defined in the System Interfaces +volume of IEEE\ Std\ 1003.1-2001 has been removed +(stripped). If both \fB-g\fP and \fB-s\fP options are present, the +action taken is unspecified. +.TP 7 +\fB-o\ \fP \fIoutfile\fP +Use the pathname \fIoutfile\fP, instead of the default \fBa.out\fP, +for the executable file produced. If the \fB-o\fP option +is present with \fB-c\fP, the result is unspecified. +.TP 7 +\fB-L\ \fP \fIdirectory\fP +Change the algorithm of searching for the libraries named in \fB-l\fP +operands to look in the directory named by the +\fIdirectory\fP pathname before looking in the usual places. Directories +named in \fB-L\fP options shall be searched in the +specified order. At least ten instances of this option shall be supported +in a single \fIfort77\fP command invocation. If a +directory specified by a \fB-L\fP option contains a file named \fBlibf.a\fP, +the results are unspecified. +.TP 7 +\fB-O\ \fP \fIoptlevel\fP +Specify the level of code optimization. If the \fIoptlevel\fP option-argument +is the digit \fB'0'\fP , all special code +optimizations shall be disabled. If it is the digit \fB'1'\fP , the +nature of the optimization is unspecified. If the \fB-O\fP +option is omitted, the nature of the system's default optimization +is unspecified. It is unspecified whether code generated in the +presence of the \fB-O\fP 0 option is the same as that generated when +\fB-O\fP is omitted. Other \fIoptlevel\fP values may be +supported. +.TP 7 +\fB-w\fP +Suppress warnings. +.sp +.LP +Multiple instances of \fB-L\fP options can be specified. +.SH OPERANDS +.LP +An \fIoperand\fP is either in the form of a pathname or the form \fB-l\fP +\fIlibrary\fP. At least one operand of the pathname +form shall be specified. The following operands shall be supported: +.TP 7 +\fIfile.\fP\fBf\fP +The pathname of a FORTRAN source file to be compiled and optionally +passed to the link editor. The filename operand shall be of +this form if the \fB-c\fP option is used. +.TP 7 +\fIfile.\fP\fBa\fP +A library of object files typically produced by \fIar\fP, and passed +directly to the link +editor. Implementations may recognize implementation-defined suffixes +other than \fB.a\fP as denoting object file libraries. +.TP 7 +\fIfile.\fP\fBo\fP +An object file produced by \fIfort77\fP \fB-c\fP and passed directly +to the link editor. Implementations may recognize +implementation-defined suffixes other than \fB.o\fP as denoting object +files. +.sp +.LP +The processing of other files is implementation-defined. +.TP 7 +\fB-l\ \fP \fIlibrary\fP +(The letter ell.) Search the library named: +.sp +.RS +.nf + +\fBlib\fP\fIlibrary\fP\fB.a +\fP +.fi +.RE +.LP +A library is searched when its name is encountered, so the placement +of a \fB-l\fP operand is significant. Several standard +libraries can be specified in this manner, as described in the EXTENDED +DESCRIPTION section. Implementations may recognize +implementation-defined suffixes other than \fB.a\fP as denoting libraries. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +The input file shall be one of the following: a text file containing +FORTRAN source code; an object file in the format produced +by \fIfort77\fP \fB-c\fP; or a library of object files, in the format +produced by archiving zero or more object files, using \fIar\fP. Implementations +may supply additional utilities that produce files in these formats. +Additional input files are implementation-defined. +.LP +A encountered within the first six characters on a line of source +code shall cause the compiler to interpret the +following character as if it were the seventh character on the line +(that is, in column 7). +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIfort77\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITMPDIR\fP +Determine the pathname that should override the default directory +for temporary files, if any. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. If +more than one \fIfile\fP operand ending in \fB.f\fP (or +possibly other unspecified suffixes) is given, for each such file: +.sp +.RS +.nf + +\fB"%s:\\n", <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +may be written to allow identification of the diagnostic message with +the appropriate input file. +.LP +This utility may produce warning messages about certain conditions +that do not warrant returning an error (non-zero) exit +value. +.SH OUTPUT FILES +.LP +Object files, listing files, and executable files shall be produced +in unspecified formats. +.SH EXTENDED DESCRIPTION +.SS Standard Libraries +.LP +The \fIfort77\fP utility shall recognize the following \fB-l\fP operand +for the standard library: +.TP 7 +\fB-l\ f\fP +This library contains all functions referenced in the ANSI\ X3.9-1978 +standard. This operand shall not be required to be +present to cause a search of this library. +.sp +.LP +In the absence of options that inhibit invocation of the link editor, +such as \fB-c\fP, the \fIfort77\fP utility shall cause +the equivalent of a \fB-l\ f\fP operand to be passed to the link editor +as the last \fB-l\fP operand, causing it to be +searched after all other object files and libraries are loaded. +.LP +It is unspecified whether the library \fBlibf.a\fP exists as a regular +file. The implementation may accept as \fB-l\fP +operands names of objects that do not exist as regular files. +.SS External Symbols +.LP +The FORTRAN compiler and link editor shall support the significance +of external symbols up to a length of at least 31 bytes; +case folding is permitted. The action taken upon encountering symbols +exceeding the implementation-defined maximum symbol length is +unspecified. +.LP +The compiler and link editor shall support a minimum of 511 external +symbols per source or object file, and a minimum of 4095 +external symbols total. A diagnostic message is written to standard +output if the implementation-defined limit is exceeded; other +actions are unspecified. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful compilation or link edit. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +When \fIfort77\fP encounters a compilation error, it shall write a +diagnostic to standard error and continue to compile other +source code operands. It shall return a non-zero exit status, but +it is implementation-defined whether an object module is created. +If the link edit is unsuccessful, a diagnostic message shall be written +to standard error, and \fIfort77\fP shall exit with a +non-zero status. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +The following usage example compiles \fBxyz.f\fP and creates the executable +file \fBfoo\fP: +.sp +.RS +.nf + +\fBfort77 -o foo xyz.f +\fP +.fi +.RE +.LP +The following example compiles \fBxyz.f\fP and creates the object +file \fBxyz.o\fP: +.sp +.RS +.nf + +\fBfort77 -c xyz.f +\fP +.fi +.RE +.LP +The following example compiles \fBxyz.f\fP and creates the executable +file \fBa.out\fP: +.sp +.RS +.nf + +\fBfort77 xyz.f +\fP +.fi +.RE +.LP +The following example compiles \fBxyz.f\fP, links it with \fBb.o\fP, +and creates the executable \fBa.out\fP: +.sp +.RS +.nf + +\fBfort77 xyz.f b.o +\fP +.fi +.RE +.SH RATIONALE +.LP +The name of this utility was chosen as \fIfort77\fP to parallel the +renaming of the C compiler. The name \fIf77\fP was not +chosen to avoid problems with historical implementations. The ANSI\ X3.9-1978 +standard was selected as a normative reference +because the ISO/IEC version of FORTRAN-77 has been superseded by the +ISO/IEC\ 1539:1990 standard (Fortran-90). +.LP +The file inclusion and symbol definition \fB#define\fP mechanisms +used by the \fIc99\fP +utility were not included in this volume of IEEE\ Std\ 1003.1-2001-even +though they are commonly implemented-since there is +no requirement that the FORTRAN compiler use the C preprocessor. +.LP +The \fB-onetrip\fP option was not included in this volume of IEEE\ Std\ 1003.1-2001, +even though many historical +compilers support it, because it is derived from FORTRAN-66; it is +an anachronism that should not be perpetuated. +.LP +Some implementations produce compilation listings. This aspect of +FORTRAN has been left unspecified because there was +controversy concerning the various methods proposed for implementing +it: a \fB-V\fP option overlapped with historical vendor +practice and a naming convention of creating files with \fB.l\fP suffixes +collided with historical \fIlex\fP file naming practice. +.LP +There is no \fB-I\fP option in this version of this volume of IEEE\ Std\ 1003.1-2001 +to specify a directory for file +inclusion. An INCLUDE directive has been a part of the Fortran-90 +discussions, but an interface supporting that standard is not in +the current scope. +.LP +It is noted that many FORTRAN compilers produce an object module even +when compilation errors occur; during a subsequent +compilation, the compiler may patch the object module rather than +recompiling all the code. Consequently, it is left to the +implementor whether or not an object file is created. +.LP +A reference to MIL-STD-1753 was removed from an early proposal in +response to a request from the POSIX FORTRAN-binding standard +developers. It was not the intention of the standard developers to +require certification of the FORTRAN compiler, and +IEEE\ Std\ 1003.9-1992 does not specify the military standard or any +special preprocessing requirements. Furthermore, use +of that document would have been inappropriate for an international +standard. +.LP +The specification of optimization has been subject to changes through +early proposals. At one time, \fB-O\fP and \fB-N\fP were +Booleans: optimize and do not optimize (with an unspecified default). +Some historical practice led this to be changed to: +.TP 7 +\fB-O\fP\ 0 +No optimization. +.TP 7 +\fB-O\fP\ 1 +Some level of optimization. +.TP 7 +\fB-O\ \fP \fIn\fP +Other, unspecified levels of optimization. +.sp +.LP +It is not always clear whether "good code generation" is the same +thing as optimization. Simple optimizations of local actions +do not usually affect the semantics of a program. The \fB-O\fP 0 option +has been included to accommodate the very particular +nature of scientific calculations in a highly optimized environment; +compilers make errors. Some degree of optimization is +expected, even if it is not documented here, and the ability to shut +it off completely could be important when porting an +application. An implementation may treat \fB-O\fP 0 as "do less than +normal" if it wishes, but this is only meaningful if any of +the operations it performs can affect the semantics of a program. +It is highly dependent on the implementation whether doing less +than normal is logical. It is not the intent of the \fB-O\fP 0 option +to ask for inefficient code generation, but rather to assure +that any semantically visible optimization is suppressed. +.LP +The specification of standard library access is consistent with the +C compiler specification. Implementations are not required +to have \fB/usr/lib/libf.a\fP, as many historical implementations +do, but if not they are required to recognize \fBf\fP as a +token. +.LP +External symbol size limits are in normative text; conforming applications +need to know these limits. However, the minimum +maximum symbol length should be taken as a constraint on a conforming +application, not on an implementation, and consequently the +action taken for a symbol exceeding the limit is unspecified. The +minimum size for the external symbol table was added for similar +reasons. +.LP +The CONSEQUENCES OF ERRORS section clearly specifies the behavior +of the compiler when compilation or link-edit errors occur. +The behavior of several historical implementations was examined, and +the choice was made to be silent on the status of the +executable, or \fBa.out\fP, file in the face of compiler or linker +errors. If a linker writes the executable file, then links it +on disk with \fIlseek\fP()s and \fIwrite\fP()s, the +partially linked executable file can be left on disk and its execute +bits turned off if the link edit fails. However, if the linker +links the image in memory before writing the file to disk, it need +not touch the executable file (if it already exists) because the +link edit fails. Since both approaches are historical practice, a +conforming application shall rely on the exit status of +\fIfort77\fP, rather than on the existence or mode of the executable +file. +.LP +The \fB-g\fP and \fB-s\fP options are not specified as mutually-exclusive. +Historically these two options have been +mutually-exclusive, but because both are so loosely specified, it +seemed appropriate to leave their interaction unspecified. +.LP +The requirement that conforming applications specify compiler options +separately is to reserve the multi-character option name +space for vendor-specific compiler options, which are known to exist +in many historical implementations. Implementations are not +required to recognize, for example, \fB-gc\fP as if it were \fB-g\fP +\fB-c\fP; nor are they forbidden from doing so. The +SYNOPSIS shows all of the options separately to highlight this requirement +on applications. +.LP +Echoing filenames to standard error is considered a diagnostic message +because it would otherwise be difficult to associate an +error message with the erring file. They are described with "may" +to allow implementations to use other methods of identifying +files and to parallel the description in \fIc99\fP. +.SH FUTURE DIRECTIONS +.LP +A compilation system based on the ISO/IEC\ 1539:1990 standard (Fortran-90) +may be considered for a future version; it may +have a different utility name from \fIfort77\fP. +.SH SEE ALSO +.LP +\fIar\fP , \fIasa\fP , \fIc99\fP , \fIumask\fP() , the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, \fIexec\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/fuser.1p b/man1p/fuser.1p new file mode 100644 index 000000000..fcaf5a2df --- /dev/null +++ b/man1p/fuser.1p @@ -0,0 +1,200 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FUSER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fuser +.SH NAME +fuser \- list process IDs of all processes that have one or more files +open +.SH SYNOPSIS +.LP +\fBfuser\fP \fB[\fP \fB-cfu\fP \fB]\fP \fIfile\fP \fB... \fP +.SH DESCRIPTION +.LP +The \fIfuser\fP utility shall write to standard output the process +IDs of processes running on the local system that have one +or more named files open. For block special devices, all processes +using any file on that device are listed. +.LP +The \fIfuser\fP utility shall write to standard error additional information +about the named files indicating how the file is +being used. +.LP +Any output for processes running on remote systems that have a named +file open is unspecified. +.LP +A user may need appropriate privilege to invoke the \fIfuser\fP utility. +.SH OPTIONS +.LP +The \fIfuser\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-c\fP +The file is treated as a mount point and the utility shall report +on any files open in the file system. +.TP 7 +\fB-f\fP +The report shall be only for the named files. +.TP 7 +\fB-u\fP +The user name, in parentheses, associated with each process ID written +to standard output shall be written to standard +error. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname on which the file or file system is to be reported. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +The user database. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIfuser\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fIfuser\fP utility shall write the process ID for each process +using each file given as an operand to standard output in +the following format: +.sp +.RS +.nf + +\fB"%d", <\fP\fIprocess_id\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The \fIfuser\fP utility shall write diagnostic messages to standard +error. +.LP +The \fIfuser\fP utility also shall write the following to standard +error: +.IP " *" 3 +The pathname of each named file is written followed immediately by +a colon. +.LP +.IP " *" 3 +For each process ID written to standard output, the character \fB'c'\fP +shall be written to standard error if the process is +using the file as its current directory and the character \fB'r'\fP +shall be written to standard error if the process is using +the file as its root directory. Implementations may write other alphabetic +characters to indicate other uses of files. +.LP +.IP " *" 3 +When the \fB-u\fP option is specified, characters indicating the use +of the file shall be followed immediately by the user +name, in parentheses, corresponding to the process' real user ID. +If the user name cannot be resolved from the process' real user +ID, the process' real user ID shall be written instead of the user +name. +.LP +.LP +When standard output and standard error are directed to the same file, +the output shall be interleaved so that the filename +appears at the start of each line, followed by the process ID and +characters indicating the use of the file. Then, if the \fB-u\fP +option is specified, the user name or user ID for each process using +that file shall be written. +.LP +A shall be written to standard error after the last output +described above for each \fIfile\fP operand. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +The command: +.sp +.RS +.nf + +\fBfuser -fu . +\fP +.fi +.RE +.LP +writes to standard output the process IDs of processes that are using +the current directory and writes to standard error an +indication of how those processes are using the directory and the +user names associated with the processes that are using the +current directory. +.SH RATIONALE +.LP +The definition of the \fIfuser\fP utility follows existing practice. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +None. +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/gencat.1p b/man1p/gencat.1p new file mode 100644 index 000000000..243137c3d --- /dev/null +++ b/man1p/gencat.1p @@ -0,0 +1,237 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GENCAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" gencat +.SH NAME +gencat \- generate a formatted message catalog +.SH SYNOPSIS +.LP +\fBgencat\fP \fIcatfile msgfile\fP\fB... \fP +.SH DESCRIPTION +.LP +The \fIgencat\fP utility shall merge the message text source file +\fImsgfile\fP into a formatted message catalog +\fIcatfile\fP. The file \fIcatfile\fP shall be created if it does +not already exist. If \fIcatfile\fP does exist, its messages +shall be included in the new \fIcatfile\fP. If set and message numbers +collide, the new message text defined in \fImsgfile\fP +shall replace the old message text currently contained in \fIcatfile\fP. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIcatfile\fP +A pathname of the formatted message catalog. If \fB'-'\fP is specified, +standard output shall be used. The format of the +message catalog produced is unspecified. +.TP 7 +\fImsgfile\fP +A pathname of a message text source file. If \fB'-'\fP is specified +for an instance of \fImsgfile\fP, standard input shall +be used. The format of message text source files is defined in the +EXTENDED DESCRIPTION section. +.sp +.SH STDIN +.LP +The standard input shall not be used unless a \fImsgfile\fP operand +is specified as \fB'-'\fP . +.SH INPUT FILES +.LP +The input files shall be text files. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIgencat\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall not be used unless the \fIcatfile\fP operand +is specified as \fB'-'\fP . +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +The content of a message text file shall be in the format defined +as follows. Note that the fields of a message text source line +are separated by a single . Any other s are considered +to be part of the subsequent field. +.TP 7 +\fB$set\ \fP \fIn\ comment\fP +.sp +This line specifies the set identifier of the following messages until +the next \fB$set\fP or end-of-file appears. The \fIn\fP +denotes the set identifier, which is defined as a number in the range +[1, {NL_SETMAX}] (see the \fI\fP header defined in the Base +Definitions volume of +IEEE\ Std\ 1003.1-2001). The application shall ensure that set identifiers +are presented in ascending order within a single +source file, but need not be contiguous. Any string following the +set identifier shall be treated as a comment. If no \fB$set\fP +directive is specified in a message text source file, all messages +shall be located in an implementation-defined default message +set NL_SETD (see the \fI\fP header defined in the Base +Definitions +volume of IEEE\ Std\ 1003.1-2001). +.TP 7 +\fB$delset\ \fP \fIn\ comment\fP +.sp +This line deletes message set \fIn\fP from an existing message catalog. +The \fIn\fP denotes the set number [1, {NL_SETMAX}]. Any +string following the set number shall be treated as a comment. +.TP 7 +\fB$\ \fP \fIcomment\fP +A line beginning with \fB'$'\fP followed by a shall be treated +as a comment. +.TP 7 +\fIm\ message-text\fP +.sp +The \fIm\fP denotes the message identifier, which is defined as a +number in the range [1, {NL_MSGMAX}] (see the \fI\fP header). +The \fImessage-text\fP shall be stored in the message catalog +with the set identifier specified by the last \fB$set\fP directive, +and with message identifier \fIm\fP. If the +\fImessage-text\fP is empty, and a field separator is present, +an empty string shall be stored in the message +catalog. If a message source line has a message number, but neither +a field separator nor \fImessage-text\fP, the existing message +with that number (if any) shall be deleted from the catalog. The application +shall ensure that message identifiers are in ascending +order within a single set, but need not be contiguous. The application +shall ensure that the length of \fImessage-text\fP is in +the range [0, {NL_TEXTMAX}] (see the \fI\fP header). +.TP 7 +\fB$quote\ \fP \fIn\fP +This line specifies an optional quote character \fIc\fP, which can +be used to surround \fImessage-text\fP so that trailing +spaces or null (empty) messages are visible in a message source line. +By default, or if an empty \fB$quote\fP directive is +supplied, no quoting of \fImessage-text\fP shall be recognized. +.sp +.LP +Empty lines in a message text source file shall be ignored. The effects +of lines starting with any character other than those +defined above are implementation-defined. +.LP +Text strings can contain the special characters and escape sequences +defined in the following table: +.TS C +center; l l l. +\fBDescription\fP \fBSymbol\fP \fBSequence\fP + NL(LF) \\n +Horizontal-tab HT \\t + VT \\v + BS \\b + CR \\r + FF \\f +Backslash \fB\\\fP \\\\ +Bit pattern \fBddd\fP \\ddd +.TE +.LP +The escape sequence \fB"\\ddd"\fP consists of backslash followed by +one, two, or three octal digits, which shall be taken to +specify the value of the desired character. If the character following +a backslash is not one of those specified, the backslash +shall be ignored. +.LP +Backslash ( \fB'\\'\fP ) followed by a is also used to continue +a string on the following line. Thus, the +following two lines describe a single message string: +.sp +.RS +.nf + +\fB1 This line continues \\ +to the next line +\fP +.fi +.RE +.LP +which shall be equivalent to: +.sp +.RS +.nf + +\fB1 This line continues to the next line +\fP +.fi +.RE +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Message catalogs produced by \fIgencat\fP are binary encoded, meaning +that their portability cannot be guaranteed between +different types of machine. Thus, just as C programs need to be recompiled +for each type of machine, so message catalogs must be +recreated via \fIgencat\fP. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiconv\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/get.1p b/man1p/get.1p new file mode 100644 index 000000000..9d0d31b1b --- /dev/null +++ b/man1p/get.1p @@ -0,0 +1,737 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" get +.SH NAME +get \- get a version of an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBget\fP \fB[\fP\fB-begkmnlLpst\fP\fB][\fP\fB-c\fP \fIcutoff\fP\fB][\fP\fB-i\fP +\fIlist\fP\fB][\fP\fB-r\fP \fISID\fP\fB][\fP\fB-x\fP \fIlist\fP\fB]\fP +\fIfile\fP\fB... \fP +.SH DESCRIPTION +.LP +The \fIget\fP utility shall generate a text file from each named SCCS +\fIfile\fP according to the specifications given by its +options. +.LP +The generated text shall normally be written into a file called the +\fBg-file\fP whose name is derived from the SCCS filename +by simply removing the leading \fB"s."\fP . +.SH OPTIONS +.LP +The \fIget\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-r\ \fP \fISID\fP +Indicate the SCCS Identification String (SID) of the version (delta) +of an SCCS file to be retrieved. The table shows, for the +most useful cases, what version of an SCCS file is retrieved (as well +as the SID of the version to be eventually created by \fIdelta\fP +if the \fB-e\fP option is also used), as a function of the SID specified. +.TP 7 +\fB-c\ \fP \fIcutoff\fP +Indicate the \fIcutoff\fP date-time, in the form: +.sp +.RS +.nf + +\fIYY\fP\fB[\fP\fIMM\fP\fB[\fP\fIDD\fP\fB[\fP\fIHH\fP\fB[\fP\fIMM\fP\fB[\fP\fISS\fP\fB]]]]]\fP +.fi +.RE +.LP +For the \fIYY\fP component, values in the range [69,99] shall refer +to years 1969 to 1999 inclusive, and values in the range +[00,68] shall refer to years 2000 to 2068 inclusive. +.TP 7 +\fBNote:\fP +.RS +It is expected that in a future version of IEEE\ Std\ 1003.1-2001 +the default century inferred from a 2-digit year will +change. (This would apply to all commands accepting a 2-digit year +as input.) +.RE +.sp +.LP +No changes (deltas) to the SCCS file that were created after the specified +\fIcutoff\fP date-time shall be included in the +generated text file. Units omitted from the date-time default to their +maximum possible values; for example, \fB-c\fP 7502 is +equivalent to \fB-c\fP 750228235959. +.LP +Any number of non-numeric characters may separate the various 2-digit +pieces of the \fIcutoff\fP date-time. This feature allows +the user to specify a \fIcutoff\fP date in the form: \fB-c\fP "77/2/2\ 9:22:25". +.TP 7 +\fB-e\fP +Indicate that the \fIget\fP is for the purpose of editing or making +a change (delta) to the SCCS file via a subsequent use of +\fIdelta\fP. The \fB-e\fP option used in a \fIget\fP for a particular +version (SID) of the +SCCS file shall prevent further \fIget\fP commands from editing on +the same SID until \fIdelta\fP is executed or the \fBj\fP (joint edit) +flag is set in the SCCS file. Concurrent use of +\fIget\fP \fB-e\fP for different SIDs is always allowed. +.LP +If the \fBg-file\fP generated by \fIget\fP with a \fB-e\fP option +is accidentally ruined in the process of editing, it may be +regenerated by re-executing the \fIget\fP command with the \fB-k\fP +option in place of the \fB-e\fP option. +.LP +SCCS file protection specified via the ceiling, floor, and authorized +user list stored in the SCCS file shall be enforced when +the \fB-e\fP option is used. +.TP 7 +\fB-b\fP +Use with the \fB-e\fP option to indicate that the new delta should +have an SID in a new branch as shown in the table below. +This option shall be ignored if the \fBb\fP flag is not present in +the file or if the retrieved delta is not a leaf delta. (A leaf +delta is one that has no successors on the SCCS file tree.) +.TP 7 +\fBNote:\fP +.RS +A branch delta may always be created from a non-leaf delta. +.RE +.sp +.TP 7 +\fB-i\ \fP \fIlist\fP +Indicate a \fIlist\fP of deltas to be included (forced to be applied) +in the creation of the generated file. The \fIlist\fP +has the following syntax: +.sp +.RS +.nf + +\fB ::= | , + ::= SID | SID - SID +\fP +.fi +.RE +.LP +SID, the SCCS Identification of a delta, may be in any form shown +in the "SID Specified" column of the table in the EXTENDED +DESCRIPTION section, except that the result of supplying a partial +SID is unspecified. A diagnostic message shall be written if the +first SID in the range is not an ancestor of the second SID in the +range. +.TP 7 +\fB-x\ \fP \fIlist\fP +Indicate a \fIlist\fP of deltas to be excluded (forced not to be applied) +in the creation of the generated file. See the +\fB-i\fP option for the \fIlist\fP format. +.TP 7 +\fB-k\fP +Suppress replacement of identification keywords (see below) in the +retrieved text by their value. The \fB-k\fP option shall be +implied by the \fB-e\fP option. +.TP 7 +\fB-l\fP +Write a delta summary into an \fBl-file\fP. +.TP 7 +\fB-L\fP +Write a delta summary to standard output. All informative output that +normally is written to standard output shall be written +to standard error instead, unless the \fB-s\fP option is used, in +which case it shall be suppressed. +.TP 7 +\fB-p\fP +Write the text retrieved from the SCCS file to the standard output. +No \fBg-file\fP shall be created. All informative output +that normally goes to the standard output shall go to standard error +instead, unless the \fB-s\fP option is used, in which case it +shall disappear. +.TP 7 +\fB-s\fP +Suppress all informative output normally written to standard output. +However, fatal error messages (which shall always be +written to the standard error) shall remain unaffected. +.TP 7 +\fB-m\fP +Precede each text line retrieved from the SCCS file by the SID of +the delta that inserted the text line in the SCCS file. The +format shall be: +.sp +.RS +.nf + +\fB"%s\\t%s", <\fP\fISID\fP\fB>, <\fP\fItext line\fP\fB> +\fP +.fi +.RE +.TP 7 +\fB-n\fP +Precede each generated text line with the %\fBM\fP% identification +keyword value (see below). The format shall be: +.sp +.RS +.nf + +\fB"%s\\t%s", <\fP\fI%M% value\fP\fB>, <\fP\fItext line\fP\fB> +\fP +.fi +.RE +.LP +When both the \fB-m\fP and \fB-n\fP options are used, the <\fItext\ line\fP> +shall be replaced by the \fB-m\fP +option-generated format. +.TP 7 +\fB-g\fP +Suppress the actual retrieval of text from the SCCS file. It is primarily +used to generate an \fBl-file\fP, or to verify the +existence of a particular SID. +.TP 7 +\fB-t\fP +Use to access the most recently created (top) delta in a given release +(for example, \fB-r 1\fP), or release and level (for +example, \fB-r 1.2\fP). +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile\fP +A pathname of an existing SCCS file or a directory. If \fIfile\fP +is a directory, the \fIget\fP utility shall behave as +though each file in the directory were specified as a named file, +except that non-SCCS files (last component of the pathname does +not begin with \fBs.\fP) and unreadable files shall be silently ignored. +.LP +If exactly one \fIfile\fP operand appears, and it is \fB'-'\fP , the +standard input shall be read; each line of the standard +input is taken to be the name of an SCCS file to be processed. Non-SCCS +files and unreadable files shall be silently ignored. +.sp +.SH STDIN +.LP +The standard input shall be a text file used only if the \fIfile\fP +operand is specified as \fB'-'\fP . Each line of the +text file shall be interpreted as an SCCS pathname. +.SH INPUT FILES +.LP +The SCCS files shall be files of an unspecified format. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIget\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, +and informative messages written to standard output (or standard error, +if the \fB-p\fP option is used). +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITZ\fP +Determine the timezone in which the times and dates written in the +SCCS file are evaluated. If the \fITZ\fP variable is unset +or NULL, an unspecified system default timezone is used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +For each file processed, \fIget\fP shall write to standard output +the SID being accessed and the number of lines retrieved from +the SCCS file, in the following format: +.sp +.RS +.nf + +\fB"%s\\n%d lines\\n", <\fP\fISID\fP\fB>, <\fP\fInumber of lines\fP\fB> +\fP +.fi +.RE +.LP +If the \fB-e\fP option is used, the SID of the delta to be made shall +appear after the SID accessed and before the number of +lines generated, in the POSIX locale: +.sp +.RS +.nf + +\fB"%s\\nnew delta %s\\n%d lines\\n", <\fP\fISID accessed\fP\fB>, + <\fP\fISID to be made\fP\fB>, <\fP\fInumber of lines\fP\fB> +\fP +.fi +.RE +.LP +If there is more than one named file or if a directory or standard +input is named, each pathname shall be written before each of +the lines shown in one of the preceding formats: +.sp +.RS +.nf + +\fB"\\n%s:\\n", <\fP\fIpathname\fP\fB> +\fP +.fi +.RE +.LP +If the \fB-L\fP option is used, a delta summary shall be written following +the format specified below for \fBl-files\fP. +.LP +If the \fB-i\fP option is used, included deltas shall be listed following +the notation, in the POSIX locale: +.sp +.RS +.nf + +\fB"Included:\\n" +\fP +.fi +.RE +.LP +If the \fB-x\fP option is used, excluded deltas shall be listed following +the notation, in the POSIX locale: +.sp +.RS +.nf + +\fB"Excluded:\\n" +\fP +.fi +.RE +.LP +If the \fB-p\fP or \fB-L\fP options are specified, the standard output +shall consist of the text retrieved from the SCCS +file. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages, except +if the \fB-p\fP or \fB-L\fP options are specified, it +shall include all informative messages normally sent to standard output. +.SH OUTPUT FILES +.LP +Several auxiliary files may be created by \fIget\fP. These files are +known generically as the \fBg-file\fP, \fBl-file\fP, +\fBp-file\fP, and \fBz-file\fP. The letter before the hyphen is called +the \fItag\fP. An auxiliary filename shall be formed from +the SCCS filename: the application shall ensure that the last component +of all SCCS filenames is of the form \fBs.\fP +\fImodule-name\fP; the auxiliary files shall be named by replacing +the leading \fBs\fP with the tag. The \fBg-file\fP shall be +an exception to this scheme: the \fBg-file\fP is named by removing +the \fBs.\fP prefix. For example, for \fBs.xyz.c\fP, the +auxiliary filenames would be \fBxyz.c\fP, \fBl.xyz.c\fP, \fBp.xyz.c\fP, +and \fBz.xyz.c\fP, respectively. +.LP +The \fBg-file\fP, which contains the generated text, shall be created +in the current directory (unless the \fB-p\fP option is +used). A \fBg-file\fP shall be created in all cases, whether or not +any lines of text were generated by the \fIget\fP. It shall +be owned by the real user. If the \fB-k\fP option is used or implied, +the \fBg-file\fP shall be writable by the owner only +(read-only for everyone else); otherwise, it shall be read-only. Only +the real user need have write permission in the current +directory. +.LP +The \fBl-file\fP shall contain a table showing which deltas were applied +in generating the retrieved text. The \fBl-file\fP +shall be created in the current directory if the \fB-l\fP option is +used; it shall be read-only and it is owned by the real user. +Only the real user need have write permission in the current directory. +.LP +Lines in the \fBl-file\fP shall have the following format: +.sp +.RS +.nf + +\fB"%c%c%c %s\\t%s %s\\n", <\fP\fIcode1\fP\fB>, <\fP\fIcode2\fP\fB>, <\fP\fIcode3\fP\fB>, + <\fP\fISID\fP\fB>, <\fP\fIdate-time\fP\fB>, <\fP\fIlogin\fP\fB> +\fP +.fi +.RE +.LP +where the entries are: +.TP 7 +<\fIcode1\fP> +A if the delta was applied; \fB'*'\fP otherwise. +.TP 7 +<\fIcode2\fP> +A if the delta was applied or was not applied and ignored; +\fB'*'\fP if the delta was not applied and was not +ignored. +.TP 7 +<\fIcode3\fP> +A character indicating a special reason why the delta was or was not +applied: +.TP 7 +\fBI\fP +.RS +Included. +.RE +.TP 7 +\fBX\fP +.RS +Excluded. +.RE +.TP 7 +\fBC\fP +.RS +Cut off (by a \fB-c\fP option). +.RE +.sp +.TP 7 +<\fIdate-time\fP> +Date and time (using the format of the \fIdate\fP utility's \fB%y\fP +/ \fB%m\fP / +\fB%d\fP \fB%T\fP conversion specification format) of creation. +.TP 7 +<\fIlogin\fP> +Login name of person who created \fIdelta\fP. +.sp +.LP +The comments and MR data shall follow on subsequent lines, indented +one . A blank line shall terminate each +entry. +.LP +The \fBp-file\fP shall be used to pass information resulting from +a \fIget\fP with a \fB-e\fP option along to \fIdelta\fP. Its contents +shall also be used to prevent a subsequent execution of \fIget\fP +with a +\fB-e\fP option for the same SID until \fIdelta\fP is executed or +the joint edit flag, +\fBj\fP, is set in the SCCS file. The \fBp-file\fP shall be created +in the directory containing the SCCS file and the application +shall ensure that the effective user has write permission in that +directory. It shall be writable by owner only, and owned by the +effective user. Each line in the \fBp-file\fP shall have the following +format: +.sp +.RS +.nf + +\fB"%s %s %s %s%s%s\\n", <\fP\fIg-file SID\fP\fB>, + <\fP\fISID of new delta\fP\fB>, <\fP\fIlogin-name of real user\fP\fB>, + <\fP\fIdate-time\fP\fB>, <\fP\fIi-value\fP\fB>, <\fP\fIx-value\fP\fB> +\fP +.fi +.RE +.LP +where <\fIi-value\fP> uses the format \fB""\fP if no \fB-i\fP option +was specified, and shall use the format: +.sp +.RS +.nf + +\fB" -i%s", <-i option\fP \fIoption-argument\fP\fB> +\fP +.fi +.RE +.LP +if a \fB-i\fP option was specified and <\fIx-value\fP> uses the format +\fB""\fP if no \fB-x\fP option was specified, +and shall use the format: +.sp +.RS +.nf + +\fB" -x%s", <-x option\fP \fIoption-argument\fP\fB> +\fP +.fi +.RE +.LP +if a \fB-x\fP option was specified. There can be an arbitrary number +of lines in the \fBp-file\fP at any time; no two lines +shall have the same new delta SID. +.LP +The \fBz-file\fP shall serve as a lock-out mechanism against simultaneous +updates. Its contents shall be the binary process ID +of the command (that is, \fIget\fP) that created it. The \fBz-file\fP +shall be created in the directory containing the SCCS file +for the duration of \fIget\fP. The same protection restrictions as +those for the \fBp-file\fP shall apply for the \fBz-file\fP. +The \fBz-file\fP shall be created read-only. +.br +.SH EXTENDED DESCRIPTION +.TS C +center;c1 s1 s1 s1 s. +\fBDetermination of SCCS Identification String\fP +.T& + l1 l1 lw(22)1 l1 l. +\fBSID*\fP \fB-b Keyletter\fP T{ +.na +\fBOther\fP +.ad +T} \fBSID\fP \fBSID of Delta\fP +\fBSpecified\fP \fBUsed&\fP T{ +.na +\fBConditions\fP +.ad +T} \fBRetrieved\fP \fBto be Created\fP +none&& no T{ +.na +R defaults to mR +.ad +T} mR.mL mR.(mL+1) +none&& yes T{ +.na +R defaults to mR +.ad +T} mR.mL mR.mL.(mB+1).1 +R no T{ +.na +R > mR +.ad +T} mR.mL R.1*** +R no T{ +.na +R = mR +.ad +T} mR.mL mR.(mL+1) +R yes T{ +.na +R > mR +.ad +T} mR.mL mR.mL.(mB+1).1 +R yes T{ +.na +R = mR +.ad +T} mR.mL mR.mL.(mB+1).1 +R - T{ +.na +R < mR and R does not exist +.ad +T} hR.mL** hR.mL.(mB+1).1 +R - T{ +.na +Trunk successor in release > R and R exists +.ad +T} R.mL R.mL.(mB+1).1 +R.L no T{ +.na +No trunk successor +.ad +T} R.L R.(L+1) +R.L yes T{ +.na +No trunk successor +.ad +T} R.L R.L.(mB+1).1 +R.L - T{ +.na +Trunk successor in release >= R +.ad +T} R.L R.L.(mB+1).1 +R.L.B no T{ +.na +No branch successor +.ad +T} R.L.B.mS R.L.B.(mS+1) +R.L.B yes T{ +.na +No branch successor +.ad +T} R.L.B.mS R.L.(mB+1).1 +R.L.B.S no T{ +.na +No branch successor +.ad +T} R.L.B.S R.L.B.(S+1) +R.L.B.S yes T{ +.na +No branch successor +.ad +T} R.L.B.S R.L.(mB+1).1 +R.L.B.S - T{ +.na +Branch successor +.ad +T} R.L.B.S R.L.(mB+1).1 +.TE +.TP 7 +* +R, L, B, and S are the release, level, branch, and sequence components +of the SID, respectively; m means maximum. Thus, for +example, R.mL means "the maximum level number within release R''; +R.L.(mB+1).1 means "the first sequence number on the new branch +(that is, maximum branch number plus one) of level L within release +R". Note that if the SID specified is of the form R.L, R.L.B, +or R.L.B.S, each of the specified components shall exist. +.TP 7 +** +hR is the highest existing release that is lower than the specified, +nonexistent, release R. +.TP 7 +*** +This is used to force creation of the first delta in a new release. +.TP 7 +& +The \fB-b\fP option is effective only if the \fBb\fP flag is present +in the file. An entry of \fB'-'\fP means +"irrelevant". +.TP 7 +&& +This case applies if the \fBd\fP (default SID) flag is not present +in the file. If the \fBd\fP flag is present in the file, +then the SID obtained from the \fBd\fP flag is interpreted as if it +had been specified on the command line. Thus, one of the other +cases in this table applies. +.sp +.SS System Date and Time +.LP +When a \fBg-file\fP is generated, the creation time of deltas in the +SCCS file may be taken into account. If any of these times +are apparently in the future, the behavior is unspecified. +.SS Identification Keywords +.LP +Identifying information shall be inserted into the text retrieved +from the SCCS file by replacing identification keywords with +their value wherever they occur. The following keywords may be used +in the text stored in an SCCS file: +.TP 7 +%\fBM\fP% +Module name: either the value of the \fBm\fP flag in the file, or +if absent, the name of the SCCS file with the leading +\fBs.\fP removed. +.TP 7 +%\fBI\fP% +SCCS identification (SID) (%\fBR\fP%.%\fBL\fP% or %\fBR\fP%.%\fBL\fP%.%\fBB\fP%.%\fBS\fP%) +of the retrieved text. +.TP 7 +%\fBR\fP% +Release. +.TP 7 +%\fBL\fP% +Level. +.TP 7 +%\fBB\fP% +Branch. +.TP 7 +%\fBS\fP% +Sequence. +.TP 7 +%\fBD\fP% +Current date (\fIYY\fP/\fIMM\fP/\fIDD\fP). +.TP 7 +%\fBH\fP% +Current date (\fIMM\fP/\fIDD\fP/\fIYY\fP). +.TP 7 +%\fBT\fP% +Current time (\fIHH\fP:\fIMM\fP:\fISS\fP). +.TP 7 +%\fBE\fP% +Date newest applied delta was created (\fIYY\fP/\fIMM\fP/\fIDD\fP). +.TP 7 +%\fBG\fP% +Date newest applied delta was created (\fIMM\fP/\fIDD\fP/\fIYY\fP). +.TP 7 +%\fBU\fP% +Time newest applied delta was created (\fIHH\fP:\fIMM\fP:\fISS\fP). +.TP 7 +%\fBY\fP% +Module type: value of the \fBt\fP flag in the SCCS file. +.TP 7 +%\fBF\fP% +SCCS filename. +.TP 7 +%\fBP\fP% +SCCS absolute pathname. +.TP 7 +%\fBQ\fP% +The value of the \fBq\fP flag in the file. +.TP 7 +%\fBC\fP% +Current line number. This keyword is intended for identifying messages +output by the program, such as "this should not have +happened" type errors. It is not intended to be used on every line +to provide sequence numbers. +.TP 7 +%\fBZ\fP% +The four-character string \fB"@(#)"\fP recognizable by \fIwhat\fP. +.TP 7 +%\fBW\fP% +A shorthand notation for constructing \fIwhat\fP strings: +.sp +.RS +.nf + +\fB%W%=%Z%%M%%I% +\fP +.fi +.RE +.TP 7 +%\fBA\fP% +Another shorthand notation for constructing \fIwhat\fP strings: +.sp +.RS +.nf + +\fB%A%=%Z%%Y%%M%%I%%Z% +\fP +.fi +.RE +.sp +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Problems can arise if the system date and time have been modified +(for example, put forward and then back again, or +unsynchronized clocks across a network) and can also arise when different +values of the \fITZ\fP environment variable are +used. +.LP +Problems of a similar nature can also arise for the operation of the +\fIdelta\fP utility, +which compares the previous file body against the working file as +part of its normal operation. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +The \fB-lp\fP option may be withdrawn in a future version. +.SH SEE ALSO +.LP +\fIadmin\fP , \fIdelta\fP , \fIprs\fP , \fIwhat\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/getconf.1p b/man1p/getconf.1p new file mode 100644 index 000000000..a1ce37e61 --- /dev/null +++ b/man1p/getconf.1p @@ -0,0 +1,459 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETCONF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getconf +.SH NAME +getconf \- get configuration values +.SH SYNOPSIS +.LP +\fBgetconf\fP \fB[\fP \fB-v specification\fP \fB]\fP \fIsystem_var\fP\fB +.br +.sp +getconf\fP \fB[\fP \fB-v specification\fP \fB]\fP \fIpath_var pathname\fP\fB +.br +\fP +.SH DESCRIPTION +.LP +In the first synopsis form, the \fIgetconf\fP utility shall write +to the standard output the value of the variable specified by +the \fIsystem_var\fP operand. +.LP +In the second synopsis form, the \fIgetconf\fP utility shall write +to the standard output the value of the variable specified +by the \fIpath_var\fP operand for the path specified by the \fIpathname\fP +operand. +.LP +The value of each configuration variable shall be determined as if +it were obtained by calling the function from which it is +defined to be available by this volume of IEEE\ Std\ 1003.1-2001 or +by the System Interfaces volume of +IEEE\ Std\ 1003.1-2001 (see the OPERANDS section). The value shall +reflect conditions in the current operating +environment. +.SH OPTIONS +.LP +The \fIgetconf\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-v\ \fP \fIspecification\fP +.sp +Indicate a specific specification and version for which configuration +variables shall be determined. If this option is not +specified, the values returned correspond to an implementation default +conforming compilation environment. +.LP +If the command: +.sp +.RS +.nf + +\fBgetconf _POSIX_V6_ILP32_OFF32 +\fP +.fi +.RE +.LP +does not write \fB"-1\\n"\fP or \fB"undefined\\n"\fP to standard output, +then commands of the form: +.sp +.RS +.nf + +\fBgetconf -v POSIX_V6_ILP32_OFF32 ... +\fP +.fi +.RE +.LP +determine values for configuration variables corresponding to the +POSIX_V6_ILP32_OFF32 compilation environment specified in \fIc99\fP +, the EXTENDED DESCRIPTION. +.LP +If the command: +.sp +.RS +.nf + +\fBgetconf _POSIX_V6_ILP32_OFFBIG +\fP +.fi +.RE +.LP +does not write \fB"-1\\n"\fP or \fB"undefined\\n"\fP to standard output, +then commands of the form: +.sp +.RS +.nf + +\fBgetconf -v POSIX_V6_ILP32_OFFBIG ... +\fP +.fi +.RE +.LP +determine values for configuration variables corresponding to the +POSIX_V6_ILP32_OFFBIG compilation environment specified in \fIc99\fP +, the EXTENDED DESCRIPTION. +.LP +If the command: +.sp +.RS +.nf + +\fBgetconf _POSIX_V6_LP64_OFF64 +\fP +.fi +.RE +.LP +does not write \fB"-1\\n"\fP or \fB"undefined\\n"\fP to standard output, +then commands of the form: +.sp +.RS +.nf + +\fBgetconf -v POSIX_V6_LP64_OFF64 ... +\fP +.fi +.RE +.LP +determine values for configuration variables corresponding to the +POSIX_V6_LP64_OFF64 compilation environment specified in \fIc99\fP +, the EXTENDED DESCRIPTION. +.LP +If the command: +.sp +.RS +.nf + +\fBgetconf _POSIX_V6_LPBIG_OFFBIG +\fP +.fi +.RE +.LP +does not write \fB"-1\\n"\fP or \fB"undefined\\n"\fP to standard output, +then commands of the form: +.sp +.RS +.nf + +\fBgetconf -v POSIX_V6_LPBIG_OFFBIG ... +\fP +.fi +.RE +.LP +determine values for configuration variables corresponding to the +POSIX_V6_LPBIG_OFFBIG compilation environment specified in \fIc99\fP +, the EXTENDED DESCRIPTION. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIpath_var\fP +A name of a configuration variable. All of the variables in the Variable +column of the table in the DESCRIPTION of the \fIfpathconf\fP() function +defined in the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, without the enclosing braces, shall be supported. +The implementation may add other local +variables. +.TP 7 +\fIpathname\fP +A pathname for which the variable specified by \fIpath_var\fP is to +be determined. +.TP 7 +\fIsystem_var\fP +A name of a configuration variable. All of the following variables +shall be supported: +.RS +.IP " *" 3 +The names in the Variable column of the table in the DESCRIPTION of +the \fIsysconf\fP() +function in the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +except for the entries corresponding to _SC_CLK_TCK, +_SC_GETGR_R_SIZE_MAX, and _SC_GETPW_R_SIZE_MAX, without the enclosing +braces. +.LP +For compatibility with earlier versions, the following variable names +shall also be supported: +.sp +.RS +.nf + +POSIX2_C_BIND +POSIX2_C_DEV +POSIX2_CHAR_TERM +POSIX2_FORT_DEV +POSIX2_FORT_RUN +POSIX2_LOCALEDEF +POSIX2_SW_DEV +POSIX2_UPE +POSIX2_VERSION +.fi +.RE +.LP +and shall be equivalent to the same name prefixed with an underscore. +This requirement may be removed in a future version. +.LP +.IP " *" 3 +The names of the symbolic constants used as the \fIname\fP argument +of the \fIconfstr\fP() function in the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, +without the _CS_ prefix. +.LP +.IP " *" 3 +The names of the symbolic constants listed under the headings ``Maximum +Values'' and ``Minimum Values'' in the description of +the \fI\fP header in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, without the enclosing braces. +.LP +For compatibility with earlier versions, the following variable names +shall also be supported: +.sp +.RS +.nf + +POSIX2_BC_BASE_MAX +POSIX2_BC_DIM_MAX +POSIX2_BC_SCALE_MAX +POSIX2_BC_STRING_MAX +POSIX2_COLL_WEIGHTS_MAX +POSIX2_EXPR_NEST_MAX +POSIX2_LINE_MAX +POSIX2_RE_DUP_MAX +.fi +.RE +.LP +and shall be equivalent to the same name prefixed with an underscore. +This requirement may be removed in a future version. +.LP +.RE +.LP +The implementation may add other local values. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIgetconf\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If the specified variable is defined on the system and its value is +described to be available from the \fIconfstr\fP() function defined +in the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, its value shall be written in the following +format: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIvalue\fP\fB> +\fP +.fi +.RE +.LP +Otherwise, if the specified variable is defined on the system, its +value shall be written in the following format: +.sp +.RS +.nf + +\fB"%d\\n", <\fP\fIvalue\fP\fB> +\fP +.fi +.RE +.LP +If the specified variable is valid, but is undefined on the system, +\fIgetconf\fP shall write using the following format: +.sp +.RS +.nf + +\fB"undefined\\n" +\fP +.fi +.RE +.LP +If the variable name is invalid or an error occurs, nothing shall +be written to standard output. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The specified variable is valid and information about its current +state was written successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +The following example illustrates the value of {NGROUPS_MAX}: +.sp +.RS +.nf + +\fBgetconf NGROUPS_MAX +\fP +.fi +.RE +.LP +The following example illustrates the value of {NAME_MAX} for a specific +directory: +.sp +.RS +.nf + +\fBgetconf NAME_MAX /usr +\fP +.fi +.RE +.LP +The following example shows how to deal more carefully with results +that might be unspecified: +.sp +.RS +.nf + +\fBif value=$(getconf PATH_MAX /usr); then + if [ "$value" = "undefined" ]; then + echo PATH_MAX in /usr is infinite. + else + echo PATH_MAX in /usr is $value. + fi +else + echo Error in getconf. +fi +\fP +.fi +.RE +.LP +Note that: +.sp +.RS +.nf + +\fBsysconf(_SC_POSIX_C_BIND); +\fP +.fi +.RE +.LP +and: +.sp +.RS +.nf + +\fBsystem("getconf POSIX2_C_BIND"); +\fP +.fi +.RE +.LP +in a C program could give different answers. The \fIsysconf\fP() call +supplies a value +that corresponds to the conditions when the program was either compiled +or executed, depending on the implementation; the \fIsystem\fP() call +to \fIgetconf\fP always supplies a value corresponding to conditions +when the +program is executed. +.SH RATIONALE +.LP +The original need for this utility, and for the \fIconfstr\fP() function, +was to +provide a way of finding the configuration-defined default value for +the \fIPATH\fP environment variable. Since \fIPATH\fP can be +modified by the user to include directories that could contain utilities +replacing the standard utilities, shell scripts need a way +to determine the system-supplied \fIPATH\fP environment variable value +that contains the correct search path for the standard +utilities. It was later suggested that access to the other variables +described in this volume of IEEE\ Std\ 1003.1-2001 +could also be useful to applications. +.LP +This functionality of \fIgetconf\fP would not be adequately subsumed +by another command such as: +.sp +.RS +.nf + +\fBgrep\fP \fIvar\fP \fB/etc/conf +\fP +.fi +.RE +.LP +because such a strategy would provide correct values for neither those +variables that can vary at runtime, nor those that can +vary depending on the path. +.LP +Early proposal versions of \fIgetconf\fP specified exit status 1 when +the specified variable was valid, but not defined on the +system. The output string \fB"undefined"\fP is now used to specify +this case with exit code 0 because so many things depend on +an exit code of zero when an invoked utility is successful. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIc99\fP , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIconfstr\fP(), \fIpathconf\fP(), \fIsysconf\fP(), \fIsystem\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/getopts.1p b/man1p/getopts.1p new file mode 100644 index 000000000..8c96c5730 --- /dev/null +++ b/man1p/getopts.1p @@ -0,0 +1,349 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETOPTS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getopts +.SH NAME +getopts \- parse utility options +.SH SYNOPSIS +.LP +\fBgetopts\fP \fIoptstring name\fP \fB[\fP\fIarg\fP\fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIgetopts\fP utility shall retrieve options and option-arguments +from a list of parameters. It shall support the Utility +Syntax Guidelines 3 to 10, inclusive, described in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +Each time it is invoked, the \fIgetopts\fP utility shall place the +value of the next option in the shell variable specified by +the \fIname\fP operand and the index of the next argument to be processed +in the shell variable \fIOPTIND .\fP Whenever the shell +is invoked, \fIOPTIND\fP shall be initialized to 1. +.LP +When the option requires an option-argument, the \fIgetopts\fP utility +shall place it in the shell variable \fIOPTARG .\fP If +no option was found, or if the option that was found does not have +an option-argument, \fIOPTARG\fP shall be unset. +.LP +If an option character not contained in the \fIoptstring\fP operand +is found where an option character is expected, the shell +variable specified by \fIname\fP shall be set to the question-mark +( \fB'?'\fP ) character. In this case, if the first +character in \fIoptstring\fP is a colon ( \fB':'\fP ), the shell variable +\fIOPTARG\fP shall be set to the option character +found, but no output shall be written to standard error; otherwise, +the shell variable \fIOPTARG\fP shall be unset and a +diagnostic message shall be written to standard error. This condition +shall be considered to be an error detected in the way +arguments were presented to the invoking application, but shall not +be an error in \fIgetopts\fP processing. +.LP +If an option-argument is missing: +.IP " *" 3 +If the first character of \fIoptstring\fP is a colon, the shell variable +specified by \fIname\fP shall be set to the colon +character and the shell variable \fIOPTARG\fP shall be set to the +option character found. +.LP +.IP " *" 3 +Otherwise, the shell variable specified by \fIname\fP shall be set +to the question-mark character, the shell variable +\fIOPTARG\fP shall be unset, and a diagnostic message shall be written +to standard error. This condition shall be considered to be +an error detected in the way arguments were presented to the invoking +application, but shall not be an error in \fIgetopts\fP +processing; a diagnostic message shall be written as stated, but the +exit status shall be zero. +.LP +.LP +When the end of options is encountered, the \fIgetopts\fP utility +shall exit with a return value greater than zero; the shell +variable \fIOPTIND\fP shall be set to the index of the first non-option-argument, +where the first \fB"--"\fP argument is +considered to be an option-argument if there are no other non-option-arguments +appearing before it, or the value \fB"$#"\fP +1 +if there are no non-option-arguments; the \fIname\fP variable shall +be set to the question-mark character. Any of the following +shall identify the end of options: the special option \fB"--"\fP , +finding an argument that does not begin with a \fB'-'\fP , +or encountering an error. +.LP +The shell variables \fIOPTIND\fP and \fIOPTARG\fP shall be local to +the caller of \fIgetopts\fP and shall not be exported by +default. +.LP +The shell variable specified by the \fIname\fP operand, \fIOPTIND +,\fP and \fIOPTARG\fP shall affect the current shell +execution environment; see \fIShell Execution Environment\fP . +.LP +If the application sets \fIOPTIND\fP to the value 1, a new set of +parameters can be used: either the current positional +parameters or new \fIarg\fP values. Any other attempt to invoke \fIgetopts\fP +multiple times in a single shell execution +environment with parameters (positional parameters or \fIarg\fP operands) +that are not the same in all invocations, or with an +\fIOPTIND\fP value modified to be a value other than 1, produces unspecified +results. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIoptstring\fP +A string containing the option characters recognized by the utility +invoking \fIgetopts\fP. If a character is followed by a +colon, the option shall be expected to have an argument, which should +be supplied as a separate argument. Applications should +specify an option character and its option-argument as separate arguments, +but \fIgetopts\fP shall interpret the characters +following an option character requiring arguments as an argument whether +or not this is done. An explicit null option-argument need +not be recognized if it is not supplied as a separate argument when +\fIgetopts\fP is invoked. (See also the \fIgetopt\fP() function defined +in the System Interfaces volume of IEEE\ Std\ 1003.1-2001.) +The characters question-mark and colon shall not be used as option +characters by an application. The use of other option characters +that are not alphanumeric produces unspecified results. If the option-argument +is not supplied as a separate argument from the +option character, the value in \fIOPTARG\fP shall be stripped of the +option character and the \fB'-'\fP . The first character +in \fIoptstring\fP determines how \fIgetopts\fP behaves if an option +character is not known or an option-argument is +missing. +.TP 7 +\fIname\fP +The name of a shell variable that shall be set by the \fIgetopts\fP +utility to the option character that was found. +.sp +.LP +The \fIgetopts\fP utility by default shall parse positional parameters +passed to the invoking shell procedure. If \fIarg\fPs +are given, they shall be parsed instead of the positional parameters. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIgetopts\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIOPTIND\fP +This variable shall be used by the \fIgetopts\fP utility as the index +of the next argument to be processed. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +Whenever an error is detected and the first character in the \fIoptstring\fP +operand is not a colon ( \fB':'\fP ), a +diagnostic message shall be written to standard error with the following +information in an unspecified format: +.IP " *" 3 +The invoking program name shall be identified in the message. The +invoking program name shall be the value of the shell special +parameter 0 (see \fISpecial Parameters\fP ) at the time the \fIgetopts\fP +utility is +invoked. A name equivalent to: +.sp +.RS +.nf + +\fBbasename "$0" +\fP +.fi +.RE +.LP +may be used. +.LP +.IP " *" 3 +If an option is found that was not specified in \fIoptstring\fP, this +error is identified and the invalid option character +shall be identified in the message. +.LP +.IP " *" 3 +If an option requiring an option-argument is found, but an option-argument +is not found, this error shall be identified and the +invalid option character shall be identified in the message. +.LP +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +An option, specified or unspecified by \fIoptstring\fP, was found. +.TP 7 +>0 +The end of options was encountered or an error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Since \fIgetopts\fP affects the current shell execution environment, +it is generally provided as a shell regular built-in. If +it is called in a subshell or separate utility execution environment, +such as one of the following: +.sp +.RS +.nf + +\fB(getopts abc value "$@") +nohup getopts ... +find . -exec getopts ... \\; +\fP +.fi +.RE +.LP +it does not affect the shell variables in the caller's environment. +.LP +Note that shell functions share \fIOPTIND\fP with the calling shell +even though the positional parameters are changed. If the +calling shell and any of its functions uses \fIgetopts\fP to parse +arguments, the results are unspecified. +.SH EXAMPLES +.LP +The following example script parses and displays its arguments: +.sp +.RS +.nf + +\fBaflag= +bflag= +while getopts ab: name +do + case $name in + a) aflag=1;; + b) bflag=1 + bval="$OPTARG";; + ?) printf "Usage: %s: [-a] [-b value] args\\n" $0 + exit 2;; + esac +done +if [ ! -z "$aflag" ]; then + printf "Option -a specified\\n" +fi +if [ ! -z "$bflag" ]; then + printf 'Option -b "%s" specified\\n' "$bval" +fi +shift $(($OPTIND - 1)) +printf "Remaining arguments are: %s\\n" "$*" +\fP +.fi +.RE +.SH RATIONALE +.LP +The \fIgetopts\fP utility was chosen in preference to the System V +\fIgetopt\fP utility because \fIgetopts\fP handles +option-arguments containing s. +.LP +The \fIOPTARG\fP variable is not mentioned in the ENVIRONMENT VARIABLES +section because it does not affect the execution of +\fIgetopts\fP; it is one of the few "output-only" variables used by +the standard utilities. +.LP +The colon is not allowed as an option character because that is not +historical behavior, and it violates the Utility Syntax +Guidelines. The colon is now specified to behave as in the KornShell +version of the \fIgetopts\fP utility; when used as the first +character in the \fIoptstring\fP operand, it disables diagnostics +concerning missing option-arguments and unexpected option +characters. This replaces the use of the \fIOPTERR\fP variable that +was specified in an early proposal. +.LP +The formats of the diagnostic messages produced by the \fIgetopts\fP +utility and the \fIgetopt\fP() function are not fully specified because +implementations with superior +(``friendlier") formats objected to the formats used by some historical +implementations. The standard developers considered it +important that the information in the messages used be uniform between +\fIgetopts\fP and \fIgetopt\fP(). Exact duplication of the messages +might not be possible, particularly if a utility +is built on another system that has a different \fIgetopt\fP() function, +but the messages +must have specific information included so that the program name, +invalid option character, and type of error can be distinguished +by a user. +.LP +Only a rare application program intercepts a \fIgetopts\fP standard +error message and wants to parse it. Therefore, +implementations are free to choose the most usable messages they can +devise. The following formats are used by many historical +implementations: +.sp +.RS +.nf + +\fB"%s: illegal option -- %c\\n", <\fP\fIprogram name\fP\fB>, <\fP\fIoption character\fP\fB> +.sp + +"%s: option requires an argument -- %c\\n", <\fP\fIprogram name\fP\fB>, \\ + <\fP\fIoption character\fP\fB> +\fP +.fi +.RE +.LP +Historical shells with built-in versions of \fIgetopt\fP() or \fIgetopts\fP +have used +different formats, frequently not even indicating the option character +found in error. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISpecial Parameters\fP , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIgetopt\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/grep.1p b/man1p/grep.1p new file mode 100644 index 000000000..5031592a3 --- /dev/null +++ b/man1p/grep.1p @@ -0,0 +1,450 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GREP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" grep +.SH NAME +grep \- search a file for a pattern +.SH SYNOPSIS +.LP +\fBgrep\fP \fB[\fP\fB-E| -F\fP\fB][\fP\fB-c| -l| -q\fP\fB][\fP\fB-insvx\fP\fB]\fP +\fB-e\fP +\fIpattern_list... +.br +\fP \fB\ \ \ \ \ \ \fP \fI\fP\fB[\fP\fB-f\fP +\fIpattern_file\fP\fB]\fP\fB...\fP\fB[\fP\fIfile\fP\fB...\fP\fB]\fP\fB +.br +.sp +grep\fP \fB[\fP\fB-E| -F\fP\fB][\fP\fB-c| -l| -q\fP\fB][\fP\fB-insvx\fP\fB][\fP\fB-e\fP +\fIpattern_list\fP\fB]... +.br +\fP \fB\ \ \ \ \ \ \fP \fB\fP\fB-f\fP +\fIpattern_file\fP\fB...\fP\fB[\fP\fIfile\fP\fB...\fP\fB]\fP\fB +.br +.sp +grep\fP \fB[\fP\fB-E| -F\fP\fB][\fP\fB-c| -l| -q\fP\fB][\fP\fB-insvx\fP\fB]\fP +\fIpattern_list\fP\fB[\fP\fIfile\fP\fB...\fP\fB]\fP\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgrep\fP utility shall search the input files, selecting lines +matching one or more patterns; the types of patterns are +controlled by the options specified. The patterns are specified by +the \fB-e\fP option, \fB-f\fP option, or the +\fIpattern_list\fP operand. The \fIpattern_list\fP's value shall consist +of one or more patterns separated by s; +the \fIpattern_file\fP's contents shall consist of one or more patterns +terminated by . By default, an input line +shall be selected if any pattern, treated as an entire basic regular +expression (BRE) as described in the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 9.3, Basic Regular Expressions, +matches any part of the line excluding the terminating ; +a null BRE shall match every line. By default, each +selected input line shall be written to the standard output. +.LP +Regular expression matching shall be based on text lines. Since a + separates or terminates patterns (see the +\fB-e\fP and \fB-f\fP options below), regular expressions cannot contain +a . Similarly, since patterns are matched +against individual lines (excluding the terminating s) of +the input, there is no way for a pattern to match a + found in the input. +.SH OPTIONS +.LP +The \fIgrep\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-E\fP +Match using extended regular expressions. Treat each pattern specified +as an ERE, as described in the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 9.4, Extended Regular Expressions. +If any entire ERE pattern matches some part of an input line excluding +the terminating , the line shall be matched. +A null ERE shall match every line. +.TP 7 +\fB-F\fP +Match using fixed strings. Treat each pattern specified as a string +instead of a regular expression. If an input line contains +any of the patterns as a contiguous sequence of bytes, the line shall +be matched. A null string shall match every line. +.TP 7 +\fB-c\fP +Write only a count of selected lines to standard output. +.TP 7 +\fB-e\ \fP \fIpattern_list\fP +.sp +Specify one or more patterns to be used during the search for input. +The application shall ensure that patterns in +\fIpattern_list\fP are separated by a . A null pattern can +be specified by two adjacent s in +\fIpattern_list\fP. Unless the \fB-E\fP or \fB-F\fP option is also +specified, each pattern shall be treated as a BRE, as +described in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section +9.3, Basic Regular Expressions. Multiple \fB-e\fP and \fB-f\fP options +shall be accepted by the \fIgrep\fP utility. All of +the specified patterns shall be used when matching lines, but the +order of evaluation is unspecified. +.TP 7 +\fB-f\ \fP \fIpattern_file\fP +.sp +Read one or more patterns from the file named by the pathname \fIpattern_file\fP. +Patterns in \fIpattern_file\fP shall be +terminated by a . A null pattern can be specified by an empty +line in \fIpattern_file\fP. Unless the \fB-E\fP or +\fB-F\fP option is also specified, each pattern shall be treated as +a BRE, as described in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 9.3, Basic Regular Expressions. +.TP 7 +\fB-i\fP +Perform pattern matching in searches without regard to case; see the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 9.2, Regular Expression General Requirements. +.TP 7 +\fB-l\fP +(The letter ell.) Write only the names of files containing selected +lines to standard output. Pathnames shall be written once +per file searched. If the standard input is searched, a pathname of +\fB"(standard input)"\fP shall be written, in the POSIX +locale. In other locales, \fB"standard input"\fP may be replaced by +something more appropriate in those locales. +.TP 7 +\fB-n\fP +Precede each output line by its relative line number in the file, +each file starting at line 1. The line number counter shall +be reset for each file processed. +.TP 7 +\fB-q\fP +Quiet. Nothing shall be written to the standard output, regardless +of matching lines. Exit with zero status if an input line is +selected. +.TP 7 +\fB-s\fP +Suppress the error messages ordinarily written for nonexistent or +unreadable files. Other error messages shall not be +suppressed. +.TP 7 +\fB-v\fP +Select lines not matching any of the specified patterns. If the \fB-v\fP +option is not specified, selected lines shall be +those that match any of the specified patterns. +.TP 7 +\fB-x\fP +Consider only input lines that use all characters in the line excluding +the terminating to match an entire +fixed string or regular expression to be matching lines. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIpattern_list\fP +Specify one or more patterns to be used during the search for input. +This operand shall be treated as if it were specified as +\fB-e\fP \fIpattern_list\fP. +.TP 7 +\fIfile\fP +A pathname of a file to be searched for the patterns. If no \fIfile\fP +operands are specified, the standard input shall be +used. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified. See the INPUT FILES section. +.SH INPUT FILES +.LP +The input files shall be text files. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIgrep\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular +expressions. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and +the behavior of character classes within regular +expressions. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If the \fB-l\fP option is in effect, and the \fB-q\fP option is not, +the following shall be written for each file containing +at least one selected input line: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +Otherwise, if more than one \fIfile\fP argument appears, and \fB-q\fP +is not specified, the \fIgrep\fP utility shall prefix +each output line by: +.sp +.RS +.nf + +\fB"%s:", <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +The remainder of each output line shall depend on the other options +specified: +.IP " *" 3 +If the \fB-c\fP option is in effect, the remainder of each output +line shall contain: +.sp +.RS +.nf + +\fB"%d\\n", <\fP\fIcount\fP\fB> +\fP +.fi +.RE +.LP +.IP " *" 3 +Otherwise, if \fB-c\fP is not in effect and the \fB-n\fP option is +in effect, the following shall be written to standard +output: +.sp +.RS +.nf + +\fB"%d:", <\fP\fIline number\fP\fB> +\fP +.fi +.RE +.LP +.IP " *" 3 +Finally, the following shall be written to standard output: +.sp +.RS +.nf + +\fB"%s", <\fP\fIselected-line contents\fP\fB> +\fP +.fi +.RE +.LP +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +One or more lines were selected. +.TP 7 +\ 1 +No lines were selected. +.TP 7 +>1 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If the \fB-q\fP option is specified, the exit status shall be zero +if an input line is selected, even if an error was detected. +Otherwise, default actions shall be performed. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Care should be taken when using characters in \fIpattern_list\fP that +may also be meaningful to the command interpreter. It is +safest to enclose the entire \fIpattern_list\fP argument in single +quotes: +.sp +.RS +.nf + +\fB'...' +\fP +.fi +.RE +.LP +The \fB-e\fP \fIpattern_list\fP option has the same effect as the +\fIpattern_list\fP operand, but is useful when +\fIpattern_list\fP begins with the hyphen delimiter. It is also useful +when it is more convenient to provide multiple patterns as +separate arguments. +.LP +Multiple \fB-e\fP and \fB-f\fP options are accepted and \fIgrep\fP +uses all of the patterns it is given while matching input +text lines. (Note that the order of evaluation is not specified. If +an implementation finds a null string as a pattern, it is +allowed to use that pattern first, matching every line, and effectively +ignore any other patterns.) +.LP +The \fB-q\fP option provides a means of easily determining whether +or not a pattern (or string) exists in a group of files. +When searching several files, it provides a performance improvement +(because it can quit as soon as it finds the first match) and +requires less care by the user in choosing the set of files to supply +as arguments (because it exits zero if it finds a match even +if \fIgrep\fP detected an access or read error on earlier \fIfile\fP +operands). +.SH EXAMPLES +.IP " 1." 4 +To find all uses of the word \fB"Posix"\fP (in any case) in file \fBtext.mm\fP +and write with line numbers: +.sp +.RS +.nf + +\fBgrep -i -n posix text.mm +\fP +.fi +.RE +.LP +.IP " 2." 4 +To find all empty lines in the standard input: +.sp +.RS +.nf + +\fBgrep ^$ +\fP +.fi +.RE +.LP +or: +.sp +.RS +.nf + +\fBgrep -v . +\fP +.fi +.RE +.LP +.IP " 3." 4 +Both of the following commands print all lines containing strings +\fB"abc"\fP or \fB"def"\fP or both: +.sp +.RS +.nf + +\fBgrep -E 'abc|def' +.sp + +grep -F 'abc +def' +\fP +.fi +.RE +.LP +.IP " 4." 4 +Both of the following commands print all lines matching exactly \fB"abc"\fP +or \fB"def"\fP : +.sp +.RS +.nf + +\fBgrep -E '^abc$|^def$' +.sp + +grep -F -x 'abc +def' +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +This \fIgrep\fP has been enhanced in an upwards-compatible way to +provide the exact functionality of the historical +\fIegrep\fP and \fIfgrep\fP commands as well. It was the clear intention +of the standard developers to consolidate the three +\fIgrep\fPs into a single command. +.LP +The old \fIegrep\fP and \fIfgrep\fP commands are likely to be supported +for many years to come as implementation extensions, +allowing historical applications to operate unmodified. +.LP +Historical implementations usually silently ignored all but one of +multiply-specified \fB-e\fP and \fB-f\fP options, but were +not consistent as to which specification was actually used. +.LP +The \fB-b\fP option was omitted from the OPTIONS section because block +numbers are implementation-defined. +.LP +The System V restriction on using \fB-\fP to mean standard input was +omitted. +.LP +A definition of action taken when given a null BRE or ERE is specified. +This is an error condition in some historical +implementations. +.LP +The \fB-l\fP option previously indicated that its use was undefined +when no files were explicitly named. This behavior was +historical and placed an unnecessary restriction on future implementations. +It has been removed. +.LP +The historical BSD \fIgrep\fP \fB-s\fP option practice is easily duplicated +by redirecting standard output to +\fB/dev/null\fP. The \fB-s\fP option required here is from System +V. +.LP +The \fB-x\fP option, historically available only with \fIfgrep\fP, +is available here for all of the non-obsolescent +versions. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsed\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/hash.1p b/man1p/hash.1p new file mode 100644 index 000000000..4213d0525 --- /dev/null +++ b/man1p/hash.1p @@ -0,0 +1,184 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "HASH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" hash +.SH NAME +hash \- remember or report utility locations +.SH SYNOPSIS +.LP +\fBhash\fP \fB[\fP\fIutility\fP\fB...\fP\fB]\fP\fB +.br +.sp +hash -r \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIhash\fP utility shall affect the way the current shell environment +remembers the locations of utilities found as +described in \fICommand Search and Execution\fP . Depending on the +arguments +specified, it shall add utility locations to its list of remembered +locations or it shall purge the contents of the list. When no +arguments are specified, it shall report on the contents of the list. +.LP +Utilities provided as built-ins to the shell shall not be reported +by \fIhash\fP. +.SH OPTIONS +.LP +The \fIhash\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-r\fP +Forget all previously remembered utility locations. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIutility\fP +The name of a utility to be searched for and added to the list of +remembered locations. If \fIutility\fP contains one or more +slashes, the results are unspecified. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIhash\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPATH\fP +Determine the location of \fIutility\fP, as described in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment +Variables. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output of \fIhash\fP shall be used when no arguments +are specified. Its format is unspecified, but includes the +pathname of each utility in the list of remembered locations for the +current shell environment. This list shall consist of those +utilities named in previous \fIhash\fP invocations that have been +invoked, and may contain those invoked and found through the +normal command search process. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Since \fIhash\fP affects the current shell execution environment, +it is always provided as a shell regular built-in. If it is +called in a separate utility execution environment, such as one of +the following: +.sp +.RS +.nf + +\fBnohup hash -r +find . -type f | xargs hash +\fP +.fi +.RE +.LP +it does not affect the command search process of the caller's environment. +.LP +The \fIhash\fP utility may be implemented as an alias-for example, +\fIalias\fP +\fB-t\ -\fP, in which case utilities found through normal command +search are not listed by the \fIhash\fP command. +.LP +The effects of \fIhash\fP \fB-r\fP can also be achieved portably by +resetting the value of \fIPATH ;\fP in the simplest form, +this can be: +.sp +.RS +.nf + +\fBPATH="$PATH" +\fP +.fi +.RE +.LP +The use of \fIhash\fP with \fIutility\fP names is unnecessary for +most applications, but may provide a performance improvement +on a few implementations; normally, the hashing process is included +by default. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fICommand Search and Execution\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/head.1p b/man1p/head.1p new file mode 100644 index 000000000..c9bb3d50e --- /dev/null +++ b/man1p/head.1p @@ -0,0 +1,176 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "HEAD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" head +.SH NAME +head \- copy the first part of files +.SH SYNOPSIS +.LP +\fBhead\fP \fB[\fP\fB-n\fP \fInumber\fP\fB][\fP\fIfile\fP\fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIhead\fP utility shall copy its input files to the standard +output, ending the output for each file at a designated +point. +.LP +Copying shall end at the point in each input file indicated by the +\fB-n\fP \fInumber\fP option. The option-argument +\fInumber\fP shall be counted in units of lines. +.SH OPTIONS +.LP +The \fIhead\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-n\ \fP \fInumber\fP +The first \fInumber\fP lines of each input file shall be copied to +standard output. The application shall ensure that the +\fInumber\fP option-argument is a positive decimal integer. +.sp +.LP +When a file contains less than \fInumber\fP lines, it shall be copied +to standard output in its entirety. This shall not be an +error. +.LP +If no options are specified, \fIhead\fP shall act as if \fB-n 10\fP +had been specified. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of an input file. If no \fIfile\fP operands are specified, +the standard input shall be used. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified. See the INPUT FILES section. +.SH INPUT FILES +.LP +Input files shall be text files, but the line length is not restricted +to {LINE_MAX} bytes. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIhead\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall contain designated portions of the input +files. +.LP +If multiple \fIfile\fP operands are specified, \fIhead\fP shall precede +the output for each with the header: +.sp +.RS +.nf + +\fB"\\n==> %s <==\\n", <\fP\fIpathname\fP\fB> +\fP +.fi +.RE +.LP +except that the first header written shall not include the initial +. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The obsolescent \fB-\fP \fInumber\fP form is withdrawn in this version. +Applications should use the \fB-n\fP \fInumber\fP +option. +.SH EXAMPLES +.LP +To write the first ten lines of all files (except those with a leading +period) in the directory: +.sp +.RS +.nf + +\fBhead * +\fP +.fi +.RE +.SH RATIONALE +.LP +Although it is possible to simulate \fIhead\fP with \fIsed\fP 10q +for a single file, the +standard developers decided that the popularity of \fIhead\fP on historical +BSD systems warranted its inclusion alongside \fItail\fP. +.LP +This standard version of \fIhead\fP follows the Utility Syntax Guidelines. +The \fB-n\fP option was added to this new interface +so that \fIhead\fP and \fItail\fP would be more logically related. +.LP +There is no \fB-c\fP option (as there is in \fItail\fP) because it +is not historical +practice and because other utilities in this volume of IEEE\ Std\ 1003.1-2001 +provide similar functionality. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsed\fP , \fItail\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/iconv.1p b/man1p/iconv.1p new file mode 100644 index 000000000..ec0ef527e --- /dev/null +++ b/man1p/iconv.1p @@ -0,0 +1,258 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ICONV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iconv +.SH NAME +iconv \- codeset conversion +.SH SYNOPSIS +.LP +\fBiconv\fP \fB[\fP\fB-cs\fP\fB]\fP \fB-f\fP \fIfrommap\fP \fB-t\fP +\fItomap\fP \fB[\fP\fIfile\fP +\fB\&...\fP\fB]\fP\fB +.br +.sp +iconv -f\fP \fIfromcode\fP \fB[\fP\fB-cs\fP\fB] [\fP\fB-t\fP \fItocode\fP +\fB[\fP\fIfile\fP +\fB\&...\fP\fB]\fP\fB +.br +.sp +iconv -t\fP \fItocode\fP \fB[\fP\fB-cs\fP\fB] [\fP\fB-f\fP \fIfromcode\fP\fB] +[\fP\fIfile\fP +\fB\&...\fP\fB]\fP\fB +.br +.sp +iconv -l +.br +\fP +.SH DESCRIPTION +.LP +The \fIiconv\fP utility shall convert the encoding of characters in +\fIfile\fP from one codeset to another and write the +results to standard output. +.LP +When the options indicate that charmap files are used to specify the +codesets (see OPTIONS), the codeset conversion shall be +accomplished by performing a logical join on the symbolic character +names in the two charmaps. The implementation need not support +the use of charmap files for codeset conversion unless the POSIX2_LOCALEDEF +symbol is defined on the system. +.SH OPTIONS +.LP +The \fIiconv\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-c\fP +Omit any characters that are invalid in the codeset of the input file +from the output. When \fB-c\fP is not used, the results +of encountering invalid characters in the input stream (either those +that are not characters in the codeset of the input file or +that have no corresponding character in the codeset of the output +file) shall be specified in the system documentation. The +presence or absence of \fB-c\fP shall not affect the exit status of +\fIiconv\fP. +.TP 7 +\fB-f\ \fP \fIfromcodeset\fP +.sp +Identify the codeset of the input file. The implementation shall recognize +the following two forms of the \fIfromcodeset\fP +option-argument: +.TP 7 +\fIfromcode\fP +.RS +The \fIfromcode\fP option-argument must not contain a slash character. +It shall be interpreted as the name of one of the +codeset descriptions provided by the implementation in an unspecified +format. Valid values of \fIfromcode\fP are +implementation-defined. +.RE +.TP 7 +\fIfrommap\fP +.RS +The \fIfrommap\fP option-argument must contain a slash character. +It shall be interpreted as the pathname of a charmap file as +defined in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section +6.4, Character Set Description File. If the pathname does not represent +a valid, readable charmap file, the results are +undefined. +.RE +.sp +.LP +If this option is omitted, the codeset of the current locale shall +be used. +.TP 7 +\fB-l\fP +Write all supported \fIfromcode\fP and \fItocode\fP values to standard +output in an unspecified format. +.TP 7 +\fB-s\fP +Suppress any messages written to standard error concerning invalid +characters. When \fB-s\fP is not used, the results of +encountering invalid characters in the input stream (either those +that are not valid characters in the codeset of the input file or +that have no corresponding character in the codeset of the output +file) shall be specified in the system documentation. The +presence or absence of \fB-s\fP shall not affect the exit status of +\fIiconv\fP. +.TP 7 +\fB-t\ \fP \fItocodeset\fP +Identify the codeset to be used for the output file. The implementation +shall recognize the following two forms of the +\fItocodeset\fP option-argument: +.TP 7 +\fItocode\fP +.RS +The semantics shall be equivalent to the \fB-f\fP \fIfromcode\fP option. +.RE +.TP 7 +\fItomap\fP +.RS +The semantics shall be equivalent to the \fItomap\fP option. +.RE +.sp +.LP +If this option is omitted, the codeset of the current locale shall +be used. +.sp +.LP +If either \fB-f\fP or \fB-t\fP represents a charmap file, but the +other does not (or is omitted), or both \fB-f\fP and +\fB-t\fP are omitted, the results are undefined. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of an input file. If no \fIfile\fP operands are specified, +or if a \fIfile\fP operand is \fB'-'\fP , the +standard input shall be used. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified, or if a \fIfile\fP operand is \fB'-'\fP +\&. +.SH INPUT FILES +.LP +The input file shall be a text file. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIiconv\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). During translation +of the file, this variable is superseded by the use of the +\fIfromcode\fP option-argument. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +When the \fB-l\fP option is used, the standard output shall contain +all supported \fIfromcode\fP and \fItocode\fP values, +written in an unspecified format. +.LP +When the \fB-l\fP option is not used, the standard output shall contain +the sequence of characters read from the input files, +translated to the specified codeset. Nothing else shall be written +to the standard output. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The user must ensure that both charmap files use the same symbolic +names for characters the two codesets have in common. +.SH EXAMPLES +.LP +The following example converts the contents of file \fBmail.x400\fP +from the ISO/IEC\ 6937:1994 standard codeset to the +ISO/IEC\ 8859-1:1998 standard codeset, and stores the results in file +\fBmail.local\fP: +.sp +.RS +.nf + +\fBiconv -f IS6937 -t IS8859 mail.x400 > mail.local +\fP +.fi +.RE +.SH RATIONALE +.LP +The \fIiconv\fP utility can be used portably only when the user provides +two charmap files as option-arguments. This is because +a single charmap provided by the user cannot reliably be joined with +the names in a system-provided character set description. The +valid values for \fIfromcode\fP and \fItocode\fP are implementation-defined +and do not have to have any relation to the charmap +mechanisms. As an aid to interactive users, the \fB-l\fP option was +adopted from the Plan 9 operating system. It writes +information concerning these implementation-defined values. The format +is unspecified because there are many possible useful +formats that could be chosen, such as a matrix of valid combinations +of \fIfromcode\fP and \fItocode\fP. The \fB-l\fP option is +not intended for shell script usage; conforming applications will +have to use charmaps. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgencat\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/id.1p b/man1p/id.1p new file mode 100644 index 000000000..ed9df18bb --- /dev/null +++ b/man1p/id.1p @@ -0,0 +1,323 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" id +.SH NAME +id \- return user identity +.SH SYNOPSIS +.LP +\fBid\fP \fB[\fP\fIuser\fP\fB]\fP\fB +.br +.sp +id -G\fP\fB[\fP\fB-n\fP\fB] [\fP\fIuser\fP\fB]\fP\fB +.br +.sp +id -g\fP\fB[\fP\fB-nr\fP\fB] [\fP\fIuser\fP\fB]\fP\fB +.br +.sp +id -u\fP\fB[\fP\fB-nr\fP\fB] [\fP\fIuser\fP\fB]\fP\fB +.br +\fP +.SH DESCRIPTION +.LP +If no \fIuser\fP operand is provided, the \fIid\fP utility shall write +the user and group IDs and the corresponding user and +group names of the invoking process to standard output. If the effective +and real IDs do not match, both shall be written. If +multiple groups are supported by the underlying system (see the description +of {NGROUPS_MAX} in the System Interfaces volume of +IEEE\ Std\ 1003.1-2001), the supplementary group affiliations of the +invoking process shall also be written. +.LP +If a \fIuser\fP operand is provided and the process has the appropriate +privileges, the user and group IDs of the selected user +shall be written. In this case, effective IDs shall be assumed to +be identical to real IDs. If the selected user has more than one +allowable group membership listed in the group database, these shall +be written in the same manner as the supplementary groups +described in the preceding paragraph. +.SH OPTIONS +.LP +The \fIid\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-G\fP +Output all different group IDs (effective, real, and supplementary) +only, using the format \fB"%u\\n"\fP . If there is more +than one distinct group affiliation, output each such affiliation, +using the format \fB"\ %u"\fP , before the + is output. +.TP 7 +\fB-g\fP +Output only the effective group ID, using the format \fB"%u\\n"\fP +\&. +.TP 7 +\fB-n\fP +Output the name in the format \fB"%s"\fP instead of the numeric ID +using the format \fB"%u"\fP . +.TP 7 +\fB-r\fP +Output the real ID instead of the effective ID. +.TP 7 +\fB-u\fP +Output only the effective user ID, using the format \fB"%u\\n"\fP +\&. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIuser\fP +The login name for which information is to be written. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIid\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The following formats shall be used when the \fILC_MESSAGES\fP locale +category specifies the POSIX locale. In other locales, +the strings \fIuid\fP, \fIgid\fP, \fIeuid\fP, \fIegid\fP, and \fIgroups\fP +may be replaced with more appropriate strings +corresponding to the locale. +.sp +.RS +.nf + +\fB"uid=%u(%s) gid=%u(%s)\\n", <\fP\fIreal user ID\fP\fB>, <\fP\fIuser-name\fP\fB>, + <\fP\fIreal group ID\fP\fB>, <\fP\fIgroup-name\fP\fB> +\fP +.fi +.RE +.LP +If the effective and real user IDs do not match, the following shall +be inserted immediately before the \fB'\\n'\fP character +in the previous format: +.sp +.RS +.nf + +\fB" euid=%u(%s)" +\fP +.fi +.RE +.LP +with the following arguments added at the end of the argument list: +.sp +.RS +.nf + +\fB<\fP\fIeffective user ID\fP\fB>, <\fP\fIeffective user-name\fP\fB> +\fP +.fi +.RE +.LP +If the effective and real group IDs do not match, the following shall +be inserted directly before the \fB'\\n'\fP character in +the format string (and after any addition resulting from the effective +and real user IDs not matching): +.sp +.RS +.nf + +\fB" egid=%u(%s)" +\fP +.fi +.RE +.LP +with the following arguments added at the end of the argument list: +.sp +.RS +.nf + +\fB<\fP\fIeffective group-ID\fP\fB>, <\fP\fIeffective group name\fP\fB> +\fP +.fi +.RE +.LP +If the process has supplementary group affiliations or the selected +user is allowed to belong to multiple groups, the first +shall be added directly before the in the format string: +.sp +.RS +.nf + +\fB" groups=%u(%s)" +\fP +.fi +.RE +.LP +with the following arguments added at the end of the argument list: +.sp +.RS +.nf + +\fB<\fP\fIsupplementary group ID\fP\fB>, <\fP\fIsupplementary group name\fP\fB> +\fP +.fi +.RE +.LP +and the necessary number of the following added after that for any +remaining supplementary group IDs: +.sp +.RS +.nf + +\fB",%u(%s)" +\fP +.fi +.RE +.LP +and the necessary number of the following arguments added at the end +of the argument list: +.sp +.RS +.nf + +\fB<\fP\fIsupplementary group ID\fP\fB>, <\fP\fIsupplementary group name\fP\fB> +\fP +.fi +.RE +.LP +If any of the user ID, group ID, effective user ID, effective group +ID, or supplementary/multiple group IDs cannot be mapped by +the system into printable user or group names, the corresponding \fB"(%s)"\fP +and \fIname\fP argument shall be omitted from the +corresponding format string. +.LP +When any of the options are specified, the output format shall be +as described in the OPTIONS section. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Output produced by the \fB-G\fP option and by the default case could +potentially produce very long lines on systems that +support large numbers of supplementary groups. (On systems with user +and group IDs that are 32-bit integers and with group names +with a maximum of 8 bytes per name, 93 supplementary groups plus distinct +effective and real group and user IDs could theoretically +overflow the 2048-byte {LINE_MAX} text file line limit on the default +output case. It would take about 186 supplementary groups to +overflow the 2048-byte barrier using \fIid\fP \fB-G\fP). This is not +expected to be a problem in practice, but in cases where it +is a concern, applications should consider using \fIfold\fP \fB-s\fP +before postprocessing +the output of \fIid\fP. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The functionality provided by the 4 BSD \fIgroups\fP utility can be +simulated using: +.sp +.RS +.nf + +\fBid -Gn [ user ] +\fP +.fi +.RE +.LP +The 4 BSD command \fIgroups\fP was considered, but it was not included +because it did not provide the functionality of the +\fIid\fP utility of the SVID. Also, it was thought that it would be +easier to modify \fIid\fP to provide the additional +functionality necessary to systems with multiple groups than to invent +another command. +.LP +The options \fB-u\fP, \fB-g\fP, \fB-n\fP, and \fB-r\fP were added +to ease the use of \fIid\fP with shell commands +substitution. Without these options it is necessary to use some preprocessor +such as \fIsed\fP +to select the desired piece of information. Since output such as that +produced by: +.sp +.RS +.nf + +\fBid -u -n +\fP +.fi +.RE +.LP +is frequently wanted, it seemed desirable to add the options. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfold\fP , \fIlogname\fP , \fIwho\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIgetgid\fP(), \fIgetgroups\fP(), +\fIgetuid\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/ipcrm.1p b/man1p/ipcrm.1p new file mode 100644 index 000000000..f58733406 --- /dev/null +++ b/man1p/ipcrm.1p @@ -0,0 +1,154 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "IPCRM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ipcrm +.SH NAME +ipcrm \- remove an XSI message queue, semaphore set, or shared memory +segment identifier +.SH SYNOPSIS +.LP +\fBipcrm\fP \fB[\fP \fB-q msgid | -Q msgkey | -s semid | -S semkey +| +.br +\ \ \ \ \ \ -m shmid | -M shmkey\fP \fB]\fP \fB... \fP +.SH DESCRIPTION +.LP +The \fIipcrm\fP utility shall remove zero or more message queues, +semaphore sets, or shared memory segments. The interprocess +communication facilities to be removed are specified by the options. +.LP +Only a user with appropriate privilege shall be allowed to remove +an interprocess communication facility that was not created by +or owned by the user invoking \fIipcrm\fP. +.SH OPTIONS +.LP +The \fIipcrm\fP facility supports the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-q\ \fP \fImsgid\fP +Remove the message queue identifier \fImsgid\fP from the system and +destroy the message queue and data structure associated +with it. +.TP 7 +\fB-m\ \fP \fIshmid\fP +Remove the shared memory identifier \fIshmid\fP from the system. The +shared memory segment and data structure associated with +it shall be destroyed after the last detach. +.TP 7 +\fB-s\ \fP \fIsemid\fP +Remove the semaphore identifier \fIsemid\fP from the system and destroy +the set of semaphores and data structure associated +with it. +.TP 7 +\fB-Q\ \fP \fImsgkey\fP +Remove the message queue identifier, created with key \fImsgkey\fP, +from the system and destroy the message queue and data +structure associated with it. +.TP 7 +\fB-M\ \fP \fIshmkey\fP +Remove the shared memory identifier, created with key \fIshmkey\fP, +from the system. The shared memory segment and data +structure associated with it shall be destroyed after the last detach. +.TP 7 +\fB-S\ \fP \fIsemkey\fP +Remove the semaphore identifier, created with key \fIsemkey\fP, from +the system and destroy the set of semaphores and data +structure associated with it. +.sp +.SH OPERANDS +.LP +None. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIipcrm\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIipcs\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fImsgctl\fP(), \fIsemctl\fP(), \fIshmctl\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/ipcs.1p b/man1p/ipcs.1p new file mode 100644 index 000000000..43c719c25 --- /dev/null +++ b/man1p/ipcs.1p @@ -0,0 +1,559 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "IPCS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ipcs +.SH NAME +ipcs \- report XSI interprocess communication facilities status +.SH SYNOPSIS +.LP +\fBipcs\fP \fB[\fP\fB-qms\fP\fB][\fP\fB-a | -bcopt\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIipcs\fP utility shall write information about active interprocess +communication facilities. +.LP +Without options, information shall be written in short format for +message queues, shared memory segments, and semaphore sets +that are currently active in the system. Otherwise, the information +that is displayed is controlled by the options specified. +.SH OPTIONS +.LP +The \fIipcs\fP facility supports the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 12.2, Utility Syntax Guidelines. +.LP +The \fIipcs\fP utility accepts the following options: +.TP 7 +\fB-q\fP +Write information about active message queues. +.TP 7 +\fB-m\fP +Write information about active shared memory segments. +.TP 7 +\fB-s\fP +Write information about active semaphore sets. +.sp +.LP +If \fB-q\fP, \fB-m\fP, or \fB-s\fP are specified, only information +about those facilities shall be written. If none of these +three are specified, information about all three shall be written +subject to the following options: +.TP 7 +\fB-a\fP +Use all print options. (This is a shorthand notation for \fB-b\fP, +\fB-c\fP, \fB-o\fP, \fB-p\fP, and \fB-t\fP.) +.TP 7 +\fB-b\fP +Write information on maximum allowable size. (Maximum number of bytes +in messages on queue for message queues, size of segments +for shared memory, and number of semaphores in each set for semaphores.) +.TP 7 +\fB-c\fP +Write creator's user name and group name; see below. +.TP 7 +\fB-o\fP +Write information on outstanding usage. (Number of messages on queue +and total number of bytes in messages on queue for message +queues, and number of processes attached to shared memory segments.) +.TP 7 +\fB-p\fP +Write process number information. (Process ID of the last process +to send a message and process ID of the last process to +receive a message on message queues, process ID of the creating process, +and process ID of the last process to attach or detach on +shared memory segments.) +.TP 7 +\fB-t\fP +Write time information. (Time of the last control operation that changed +the access permissions for all facilities, time of the +last \fImsgsnd\fP() and \fImsgrcv\fP() operations +on message queues, time of the last \fIshmat\fP() and \fIshmdt\fP() +operations on shared memory, and time of the last \fIsemop\fP() operation +on semaphores.) +.sp +.SH OPERANDS +.LP +None. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.IP " *" 3 +The group database +.LP +.IP " *" 3 +The user database +.LP +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIipcs\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITZ\fP +Determine the timezone for the date and time strings written by \fIipcs\fP. +If \fITZ\fP is unset or null, an unspecified +default timezone shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +An introductory line shall be written with the format: +.sp +.RS +.nf + +\fB"IPC status from %s as of %s\\n", <\fP\fIsource\fP\fB>, <\fP\fIdate\fP\fB> +\fP +.fi +.RE +.LP +where <\fIsource\fP> indicates the source used to gather the statistics +and <\fIdate\fP> is the information that +would be produced by the \fIdate\fP command when invoked in the POSIX +locale. +.LP +The \fIipcs\fP utility then shall create up to three reports depending +upon the \fB-q\fP, \fB-m\fP, and \fB-s\fP options. +The first report shall indicate the status of message queues, the +second report shall indicate the status of shared memory +segments, and the third report shall indicate the status of semaphore +sets. +.LP +If the corresponding facility is not installed or has not been used +since the last reboot, then the report shall be written out +in the format: +.sp +.RS +.nf + +\fB"%s facility not in system.\\n", <\fP\fIfacility\fP\fB> +\fP +.fi +.RE +.LP +where <\fIfacility\fP> is \fIMessage Queue\fP, \fIShared Memory\fP, +or \fISemaphore\fP, as appropriate. If the +facility has been installed and has been used since the last reboot, +column headings separated by one or more spaces and followed +by a shall be written as indicated below followed by the +facility name written out using the format: +.sp +.RS +.nf + +\fB"%s:\\n", <\fP\fIfacility\fP\fB> +\fP +.fi +.RE +.LP +where <\fIfacility\fP> is \fIMessage Queues\fP, \fIShared Memory\fP, +or \fISemaphores\fP, as appropriate. On the +second and third reports the column headings need not be written if +the last column headings written already provide column +headings for all information in that report. +.LP +The column headings provided in the first column below and the meaning +of the information in those columns shall be given in +order below; the letters in parentheses indicate the options that +shall cause the corresponding column to appear; "all" means +that the column shall always appear. Each column is separated by one +or more s. Note that these options only determine +what information is provided for each report; they do not determine +which reports are written. +.TP 7 +T (all) +Type of facility: +.TP 7 +\fBq\fP +.RS +Message queue. +.RE +.TP 7 +\fBm\fP +.RS +Shared memory segment. +.RE +.TP 7 +\fBs\fP +.RS +Semaphore. +.RE +.sp +.LP +This field is a single character written using the format \fB%c\fP +\&. +.TP 7 +ID (all) +The identifier for the facility entry. This field shall be written +using the format \fB%d\fP . +.TP 7 +KEY (all) +The key used as an argument to \fImsgget\fP(), \fIsemget\fP(), or +\fIshmget\fP() to create the facility +entry. +.TP 7 +\fBNote:\fP +.RS +The key of a shared memory segment is changed to IPC_PRIVATE when +the segment has been removed until all processes attached to +the segment detach it. +.RE +.sp +This field shall be written using the format \fB0x%x\fP. +.TP 7 +MODE (all) +The facility access modes and flags. The mode shall consist of 11 +characters that are interpreted as follows. +.LP +The first character shall be: +.TP 7 +\fBS\fP +.RS +If a process is waiting on a \fImsgsnd\fP() operation. +.RE +.TP 7 +\fB-\fP +.RS +If the above is not true. +.RE +.sp +.LP +The second character shall be: +.TP 7 +\fBR\fP +.RS +If a process is waiting on a \fImsgrcv\fP() operation. +.RE +.TP 7 +\fBC\fP\ or\ \fB-\fP +.RS +If the associated shared memory segment is to be cleared when the +first attach operation is executed. +.RE +.TP 7 +\fB-\fP +.RS +If none of the above is true. +.RE +.sp +.LP +The next nine characters shall be interpreted as three sets of three +bits each. The first set refers to the owner's permissions; +the next to permissions of others in the usergroup of the facility +entry; and the last to all others. Within each set, the first +character indicates permission to read, the second character indicates +permission to write or alter the facility entry, and the +last character is a minus sign ( \fB'-'\fP ). +.LP +The permissions shall be indicated as follows: +.TP 7 +\fIr\fP +.RS +If read permission is granted. +.RE +.TP 7 +\fIw\fP +.RS +If write permission is granted. +.RE +.TP 7 +\fIa\fP +.RS +If alter permission is granted. +.RE +.TP 7 +\fB-\fP +.RS +If the indicated permission is not granted. +.RE +.sp +.LP +The first character following the permissions specifies if there is +an alternate or additional access control method associated +with the facility. If there is no alternate or additional access control +method associated with the facility, a single + shall be written; otherwise, another printable character is +written. +.TP 7 +OWNER (all) +The user name of the owner of the facility entry. If the user name +of the owner is found in the user database, at least the +first eight column positions of the name shall be written using the +format \fB%s\fP . Otherwise, the user ID of the owner shall +be written using the format \fB%d\fP . +.TP 7 +GROUP (all) +The group name of the owner of the facility entry. If the group name +of the owner is found in the group database, at least the +first eight column positions of the name shall be written using the +format \fB%s\fP . Otherwise, the group ID of the owner shall +be written using the format \fB%d\fP . +.sp +.LP +The following nine columns shall be only written out for message queues: +.TP 7 +CREATOR (\fBa\fP,\fBc\fP) +The user name of the creator of the facility entry. If the user name +of the creator is found in the user database, at least the +first eight column positions of the name shall be written using the +format \fB%s\fP . Otherwise, the user ID of the creator +shall be written using the format \fB%d\fP . +.TP 7 +CGROUP (\fBa\fP,\fBc\fP) +The group name of the creator of the facility entry. If the group +name of the creator is found in the group database, at least +the first eight column positions of the name shall be written using +the format \fB%s\fP . Otherwise, the group ID of the creator +shall be written using the format \fB%d\fP . +.TP 7 +CBYTES (\fBa\fP,\fBo\fP) +The number of bytes in messages currently outstanding on the associated +message queue. This field shall be written using the +format \fB%d\fP . +.TP 7 +QNUM (\fBa\fP,\fBo\fP) +The number of messages currently outstanding on the associated message +queue. This field shall be written using the format +\fB%d\fP . +.TP 7 +QBYTES (\fBa\fP,\fBb\fP) +The maximum number of bytes allowed in messages outstanding on the +associated message queue. This field shall be written using +the format \fB%d\fP . +.TP 7 +LSPID (\fBa\fP,\fBp\fP) +The process ID of the last process to send a message to the associated +queue. This field shall be written using the format: +.sp +.RS +.nf + +\fB"%d", <\fP\fIpid\fP\fB> +\fP +.fi +.RE +.LP +where <\fIpid\fP> is 0 if no message has been sent to the corresponding +message queue; otherwise, <\fIpid\fP> +shall be the process ID of the last process to send a message to the +queue. +.TP 7 +LRPID (\fBa\fP,\fBp\fP) +The process ID of the last process to receive a message from the associated +queue. This field shall be written using the +format: +.sp +.RS +.nf + +\fB"%d", <\fP\fIpid\fP\fB> +\fP +.fi +.RE +.LP +where <\fIpid\fP> is 0 if no message has been received from the corresponding +message queue; otherwise, +<\fIpid\fP> shall be the process ID of the last process to receive +a message from the queue. +.TP 7 +STIME (\fBa\fP,\fBt\fP) +The time the last message was sent to the associated queue. If a message +has been sent to the corresponding message queue, the +hour, minute, and second of the last time a message was sent to the +queue shall be written using the format \fB%d\fP : +\fB%2.2d\fP : \fB%2.2d\fP . Otherwise, the format \fB"\ no-entry"\fP +shall be written. +.TP 7 +RTIME (\fBa\fP,\fBt\fP) +The time the last message was received from the associated queue. +If a message has been received from the corresponding message +queue, the hour, minute, and second of the last time a message was +received from the queue shall be written using the format +\fB%d\fP : \fB%2.2d\fP : \fB%2.2d\fP . Otherwise, the format \fB"\ no-entry"\fP +shall be written. +.sp +.LP +The following eight columns shall be only written out for shared memory +segments. +.TP 7 +CREATOR (\fBa\fP,\fBc\fP) +The user of the creator of the facility entry. If the user name of +the creator is found in the user database, at least the +first eight column positions of the name shall be written using the +format \fB%s\fP . Otherwise, the user ID of the creator +shall be written using the format \fB%d\fP . +.TP 7 +CGROUP (\fBa\fP,\fBc\fP) +The group name of the creator of the facility entry. If the group +name of the creator is found in the group database, at least +the first eight column positions of the name shall be written using +the format \fB%s\fP . Otherwise, the group ID of the creator +shall be written using the format \fB%d\fP . +.TP 7 +NATTCH (\fBa\fP,\fBo\fP) +The number of processes attached to the associated shared memory segment. +This field shall be written using the format +\fB%d\fP . +.TP 7 +SEGSZ (\fBa\fP,\fBb\fP) +The size of the associated shared memory segment. This field shall +be written using the format \fB%d\fP . +.TP 7 +CPID (\fBa\fP,\fBp\fP) +The process ID of the creator of the shared memory entry. This field +shall be written using the format \fB%d\fP . +.TP 7 +LPID (\fBa\fP,\fBp\fP) +The process ID of the last process to attach or detach the shared +memory segment. This field shall be written using the format: +.sp +.RS +.nf + +\fB"%d", <\fP\fIpid\fP\fB> +\fP +.fi +.RE +.LP +where <\fIpid\fP> is 0 if no process has attached the corresponding +shared memory segment; otherwise, <\fIpid\fP> +shall be the process ID of the last process to attach or detach the +segment. +.TP 7 +ATIME (\fBa\fP,\fBt\fP) +The time the last attach on the associated shared memory segment was +completed. If the corresponding shared memory segment has +ever been attached, the hour, minute, and second of the last time +the segment was attached shall be written using the format +\fB%d\fP : \fB%2.2d\fP : \fB%2.2d\fP . Otherwise, the format \fB"\ no-entry"\fP +shall be written. +.TP 7 +DTIME (\fBa\fP,\fBt\fP) +The time the last detach on the associated shared memory segment was +completed. If the corresponding shared memory segment has +ever been detached, the hour, minute, and second of the last time +the segment was detached shall be written using the format +\fB%d\fP : \fB%2.2d\fP : \fB%2.2d\fP . Otherwise, the format \fB"\ no-entry"\fP +shall be written. +.sp +.LP +The following four columns shall be only written out for semaphore +sets: +.TP 7 +CREATOR (\fBa\fP,\fBc\fP) +The user of the creator of the facility entry. If the user name of +the creator is found in the user database, at least the +first eight column positions of the name shall be written using the +format \fB%s\fP . Otherwise, the user ID of the creator +shall be written using the format \fB%d\fP . +.TP 7 +CGROUP (\fBa\fP,\fBc\fP) +The group name of the creator of the facility entry. If the group +name of the creator is found in the group database, at least +the first eight column positions of the name shall be written using +the format \fB%s\fP . Otherwise, the group ID of the creator +shall be written using the format \fB%d\fP . +.TP 7 +NSEMS (\fBa\fP,\fBb\fP) +The number of semaphores in the set associated with the semaphore +entry. This field shall be written using the format +\fB%d\fP . +.TP 7 +OTIME (\fBa\fP,\fBt\fP) +The time the last semaphore operation on the set associated with the +semaphore entry was completed. If a semaphore operation +has ever been performed on the corresponding semaphore set, the hour, +minute, and second of the last semaphore operation on the +semaphore set shall be written using the format \fB%d\fP : \fB%2.2d\fP +: \fB%2.2d\fP . Otherwise, the format +\fB"\ no-entry"\fP shall be written. +.sp +.LP +The following column shall be written for all three reports when it +is requested: +.TP 7 +CTIME (\fBa\fP,\fBt\fP) +The time the associated entry was created or changed. The hour, minute, +and second of the time when the associated entry was +created shall be written using the format \fB%d\fP : \fB%2.2d\fP : +\fB%2.2d\fP . +.sp +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Things can change while \fIipcs\fP is running; the information it +gives is guaranteed to be accurate only when it was +retrieved. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fImsgrcv\fP(), +\fImsgsnd\fP(), \fIsemget\fP(), \fIsemop\fP(), \fIshmat\fP(), \fIshmdt\fP(), +\fIshmget\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/jobs.1p b/man1p/jobs.1p new file mode 100644 index 000000000..3dac15e59 --- /dev/null +++ b/man1p/jobs.1p @@ -0,0 +1,313 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "JOBS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" jobs +.SH NAME +jobs \- display status of jobs in the current session +.SH SYNOPSIS +.LP +\fBjobs\fP \fB[\fP\fB-l| -p\fP\fB][\fP\fIjob_id\fP\fB...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIjobs\fP utility shall display the status of jobs that were +started in the current shell environment; see \fIShell Execution Environment\fP +\&. +.LP +When \fIjobs\fP reports the termination status of a job, the shell +shall remove its process ID from the list of those "known +in the current shell execution environment''; see \fIAsynchronous +Lists\fP . +.SH OPTIONS +.LP +The \fIjobs\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-l\fP +(The letter ell.) Provide more information about each job listed. +This information shall include the job number, current job, +process group ID, state, and the command that formed the job. +.TP 7 +\fB-p\fP +Display only the process IDs for the process group leaders of the +selected jobs. +.sp +.LP +By default, the \fIjobs\fP utility shall display the status of all +stopped jobs, running background jobs and all jobs whose +status has changed and have not been reported by the shell. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIjob_id\fP +Specifies the jobs for which the status is to be displayed. If no +\fIjob_id\fP is given, the status information for all jobs +shall be displayed. The format of \fIjob_id\fP is described in the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 3.203, +Job Control Job ID. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIjobs\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If the \fB-p\fP option is specified, the output shall consist of one +line for each process ID: +.sp +.RS +.nf + +\fB"%d\\n", <\fP\fIprocess ID\fP\fB> +\fP +.fi +.RE +.LP +Otherwise, if the \fB-l\fP option is not specified, the output shall +be a series of lines of the form: +.sp +.RS +.nf + +\fB"[%d] %c %s %s\\n", <\fP\fIjob-number\fP\fB>, <\fP\fIcurrent\fP\fB>, <\fP\fIstate\fP\fB>, <\fP\fIcommand\fP\fB> +\fP +.fi +.RE +.LP +where the fields shall be as follows: +.TP 7 +<\fIcurrent\fP> +The character \fB'+'\fP identifies the job that would be used as a +default for the \fIfg\fP or \fIbg\fP utilities; this job can also +be specified +using the \fIjob_id\fP %+ or \fB"%%"\fP . The character \fB'-'\fP +identifies the job that would become the default if the +current default job were to exit; this job can also be specified using +the \fIjob_id\fP %-. For other jobs, this field is a +. At most one job can be identified with \fB'+'\fP and at most +one job can be identified with \fB'-'\fP . If +there is any suspended job, then the current job shall be a suspended +job. If there are at least two suspended jobs, then the +previous job also shall be a suspended job. +.TP 7 +<\fIjob-number\fP> +A number that can be used to identify the process group to the \fIwait\fP, +\fIfg\fP, \fIbg\fP, and \fIkill\fP utilities. Using these utilities, +the job can be identified by prefixing the job number +with \fB'%'\fP . +.TP 7 +<\fIstate\fP> +One of the following strings (in the POSIX locale): +.TP 7 +\fBRunning\fP +.RS +Indicates that the job has not been suspended by a signal and has +not exited. +.RE +.TP 7 +\fBDone\fP +.RS +Indicates that the job completed and returned exit status zero. +.RE +.TP 7 +\fBDone\fP(\fIcode\fP) +.RS +Indicates that the job completed normally and that it exited with +the specified non-zero exit status, \fIcode\fP, expressed as +a decimal number. +.RE +.TP 7 +\fBStopped\fP +.RS +Indicates that the job was suspended by the SIGTSTP signal. +.RE +.TP 7 +\fBStopped\fP\ (\fBSIGTSTP\fP) +.RS +.sp +Indicates that the job was suspended by the SIGTSTP signal. +.RE +.TP 7 +\fBStopped\fP\ (\fBSIGSTOP\fP) +.RS +.sp +Indicates that the job was suspended by the SIGSTOP signal. +.RE +.TP 7 +\fBStopped\fP\ (\fBSIGTTIN\fP) +.RS +.sp +Indicates that the job was suspended by the SIGTTIN signal. +.RE +.TP 7 +\fBStopped\fP\ (\fBSIGTTOU\fP) +.RS +.sp +Indicates that the job was suspended by the SIGTTOU signal. +.RE +.sp +.LP +The implementation may substitute the string \fBSuspended\fP in place +of \fBStopped\fP. If the job was terminated by a signal, +the format of <\fIstate\fP> is unspecified, but it shall be visibly +distinct from all of the other <\fIstate\fP> +formats shown here and shall indicate the name or description of the +signal causing the termination. +.TP 7 +<\fIcommand\fP> +The associated command that was given to the shell. +.sp +.LP +If the \fB-l\fP option is specified, a field containing the process +group ID shall be inserted before the <\fIstate\fP> +field. Also, more processes in a process group may be output on separate +lines, using only the process ID and +<\fIcommand\fP> fields. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fB-p\fP option is the only portable way to find out the process +group of a job because different implementations have +different strategies for defining the process group of the job. Usage +such as $( \fIjobs\fP \fB-p\fP) provides a way of referring +to the process group of the job in an implementation-independent way. +.LP +The \fIjobs\fP utility does not work as expected when it is operating +in its own utility execution environment because that +environment has no applicable jobs to manipulate. See the APPLICATION +USAGE section for \fIbg\fP . For this +reason, \fIjobs\fP is generally implemented as a shell regular built-in. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +Both \fB"%%"\fP and \fB"%+"\fP are used to refer to the current job. +Both forms are of equal validity-the \fB"%%"\fP +mirroring \fB"$$"\fP and \fB"%+"\fP mirroring the output of \fIjobs\fP. +Both forms reflect historical practice of the +KornShell and the C shell with job control. +.LP +The job control features provided by \fIbg\fP, \fIfg\fP, +and \fIjobs\fP are based on the KornShell. The standard developers +examined the characteristics of the C shell versions of these +utilities and found that differences exist. Despite widespread use +of the C shell, the KornShell versions were selected for this +volume of IEEE\ Std\ 1003.1-2001 to maintain a degree of uniformity +with the rest of the KornShell features selected (such +as the very popular command line editing features). +.LP +The \fIjobs\fP utility is not dependent on the job control option, +as are the seemingly related \fIbg\fP and \fIfg\fP utilities because +\fIjobs\fP is useful for +examining background jobs, regardless of the condition of job control. +When the user has invoked a \fIset\fP \fB+m\fP command and job control +has been turned off, \fIjobs\fP can still be +used to examine the background jobs associated with that current session. +Similarly, \fIkill\fP can then be used to kill background jobs with +\fIkill\fP% <\fIbackground job number\fP>. +.LP +The output for terminated jobs is left unspecified to accommodate +various historical systems. The following formats have been +witnessed: +.IP " 1." 4 +\fBKilled\fP( \fIsignal name\fP) +.LP +.IP " 2." 4 +\fIsignal name\fP +.LP +.IP " 3." 4 +\fIsignal name\fP( \fBcoredump\fP) +.LP +.IP " 4." 4 +\fIsignal description\fP- \fBcore dumped\fP +.LP +.LP +Most users should be able to understand these formats, although it +means that applications have trouble parsing them. +.LP +The calculation of job IDs was not described since this would suggest +an implementation, which may impose unnecessary +restrictions. +.LP +In an early proposal, a \fB-n\fP option was included to "Display the +status of jobs that have changed, exited, or stopped +since the last status report". It was removed because the shell always +writes any changed status of jobs before each prompt. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Execution Environment\fP , \fIbg\fP , \fIfg\fP , \fIkill\fP() +, \fIwait\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/join.1p b/man1p/join.1p new file mode 100644 index 000000000..22351f302 --- /dev/null +++ b/man1p/join.1p @@ -0,0 +1,410 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "JOIN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" join +.SH NAME +join \- relational database operator +.SH SYNOPSIS +.LP +\fBjoin\fP \fB[\fP\fB-a\fP \fIfile_number\fP \fB| -v\fP \fIfile_number\fP\fB][\fP\fB-e\fP +\fIstring\fP\fB][\fP\fB-o\fP \fIlist\fP\fB][\fP\fB-t\fP \fIchar\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-1\fP \fIfield\fP\fB][\fP\fB-2\fP +\fIfield\fP\fB]\fP +\fIfile1 file2\fP +.SH DESCRIPTION +.LP +The \fIjoin\fP utility shall perform an equality join on the files +\fIfile1\fP and \fIfile2\fP. The joined files shall be +written to the standard output. +.LP +The join field is a field in each file on which the files are compared. +The \fIjoin\fP utility shall write one line in the +output for each pair of lines in \fIfile1\fP and \fIfile2\fP that +have identical join fields. The output line by default shall +consist of the join field, then the remaining fields from \fIfile1\fP, +then the remaining fields from \fIfile2\fP. This format +can be changed by using the \fB-o\fP option (see below). The \fB-a\fP +option can be used to add unmatched lines to the output. +The \fB-v\fP option can be used to output only unmatched lines. +.LP +The files \fIfile1\fP and \fIfile2\fP shall be ordered in the collating +sequence of \fIsort\fP \fB-b\fP on the fields on which they shall +be joined, by default the first in each line. +All selected output shall be written in the same collating sequence. +.LP +The default input field separators shall be s. In this case, +multiple separators shall count as one field +separator, and leading separators shall be ignored. The default output +field separator shall be a . +.LP +The field separator and collating sequence can be changed by using +the \fB-t\fP option (see below). +.LP +If the same key appears more than once in either file, all combinations +of the set of remaining fields in \fIfile1\fP and the +set of remaining fields in \fIfile2\fP are output in the order of +the lines encountered. +.LP +If the input files are not in the appropriate collating sequence, +the results are unspecified. +.SH OPTIONS +.LP +The \fIjoin\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-a\ \fP \fIfile_number\fP +.sp +Produce a line for each unpairable line in file \fIfile_number\fP, +where \fIfile_number\fP is 1 or 2, in addition to the default +output. If both \fB-a\fP1 and \fB-a\fP2 are specified, all unpairable +lines shall be output. +.TP 7 +\fB-e\ \fP \fIstring\fP +Replace empty output fields in the list selected by \fB-o\fP with +the string \fIstring\fP. +.TP 7 +\fB-o\ \fP \fIlist\fP +Construct the output line to comprise the fields specified in \fIlist\fP, +each element of which shall have one of the +following two forms: +.RS +.IP " 1." 4 +\fIfile_number.field\fP, where \fIfile_number\fP is a file number +and \fIfield\fP is a decimal integer field number +.LP +.IP " 2." 4 +0 (zero), representing the join field +.LP +.RE +.LP +The elements of \fIlist\fP shall be either comma-separated or -separated, +as specified in Guideline 8 of the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility +Syntax +Guidelines. The fields specified by \fIlist\fP shall be written for +all selected output lines. Fields selected by \fIlist\fP +that do not appear in the input shall be treated as empty output fields. +(See the \fB-e\fP option.) Only specifically requested +fields shall be written. The application shall ensure that \fIlist\fP +is a single command line argument. +.TP 7 +\fB-t\ \fP \fIchar\fP +Use character \fIchar\fP as a separator, for both input and output. +Every appearance of \fIchar\fP in a line shall be +significant. When this option is specified, the collating sequence +shall be the same as \fIsort\fP without the \fB-b\fP option. +.TP 7 +\fB-v\ \fP \fIfile_number\fP +.sp +Instead of the default output, produce a line only for each unpairable +line in \fIfile_number\fP, where \fIfile_number\fP is 1 or +2. If both \fB-v\fP1 and \fB-v\fP2 are specified, all unpairable lines +shall be output. +.TP 7 +\fB-1\ \fP \fIfield\fP +Join on the \fIfield\fPth field of file 1. Fields are decimal integers +starting with 1. +.TP 7 +\fB-2\ \fP \fIfield\fP +Join on the \fIfield\fPth field of file 2. Fields are decimal integers +starting with 1. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile1\fP,\ \fIfile2\fP +A pathname of a file to be joined. If either of the \fIfile1\fP or +\fIfile2\fP operands is \fB'-'\fP , the standard input +shall be used in its place. +.sp +.SH STDIN +.LP +The standard input shall be used only if the \fIfile1\fP or \fIfile2\fP +operand is \fB'-'\fP . See the INPUT FILES +section. +.SH INPUT FILES +.LP +The input files shall be text files. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIjoin\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale of the collating sequence \fIjoin\fP expects +to have been used when the input files were sorted. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fIjoin\fP utility output shall be a concatenation of selected +character fields. When the \fB-o\fP option is not +specified, the output shall be: +.sp +.RS +.nf + +\fB"%s%s%s\\n", <\fP\fIjoin field\fP\fB>, <\fP\fIother file1 fields\fP\fB>, + <\fP\fIother file2 fields\fP\fB> +\fP +.fi +.RE +.LP +If the join field is not the first field in a file, the <\fIother\ file\ fields\fP> +for that file shall be: +.sp +.RS +.nf + +\fB<\fP\fIfields preceding join field\fP\fB>, <\fP\fIfields following join field\fP\fB> +\fP +.fi +.RE +.LP +When the \fB-o\fP option is specified, the output format shall be: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIconcatenation of fields\fP\fB> +\fP +.fi +.RE +.LP +where the concatenation of fields is described by the \fB-o\fP option, +above. +.LP +For either format, each field (except the last) shall be written with +its trailing separator character. If the separator is the +default ( s), a single shall be written after each +field (except the last). +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All input files were output successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Pathnames consisting of numeric digits or of the form \fIstring.string\fP +should not be specified directly following the +\fB-o\fP list. +.SH EXAMPLES +.LP +The \fB-o\fP 0 field essentially selects the union of the join fields. +For example, given file \fBphone\fP: +.sp +.RS +.nf + +\fB!Name Phone Number +Don +1 123-456-7890 +Hal +1 234-567-8901 +Yasushi +2 345-678-9012 +\fP +.fi +.RE +.LP +and file \fBfax\fP: +.sp +.RS +.nf + +\fB!Name Fax Number +Don +1 123-456-7899 +Keith +1 456-789-0122 +Yasushi +2 345-678-9011 +\fP +.fi +.RE +.LP +(where the large expanses of white space are meant to each represent +a single ), the command: +.sp +.RS +.nf + +\fBjoin -t "" -a 1 -a 2 -e '(unknown)' -o 0,1.2,2.2 phone fax +\fP +.fi +.RE +.LP +would produce: +.sp +.RS +.nf + +\fB!Name Phone Number Fax Number +Don +1 123-456-7890 +1 123-456-7899 +Hal +1 234-567-8901 (unknown) +Keith (unknown) +1 456-789-0122 +Yasushi +2 345-678-9012 +2 345-678-9011 +\fP +.fi +.RE +.LP +Multiple instances of the same key will produce combinatorial results. +The following: +.sp +.RS +.nf + +\fBfa: + a x + a y + a z +fb: + a p +\fP +.fi +.RE +.LP +will produce: +.sp +.RS +.nf + +\fBa x p +a y p +a z p +\fP +.fi +.RE +.LP +And the following: +.sp +.RS +.nf + +\fBfa: + a b c + a d e +fb: + a w x + a y z + a o p +\fP +.fi +.RE +.LP +will produce: +.sp +.RS +.nf + +\fBa b c w x +a b c y z +a b c o p +a d e w x +a d e y z +a d e o p +\fP +.fi +.RE +.SH RATIONALE +.LP +The \fB-e\fP option is only effective when used with \fB-o\fP because, +unless specific fields are identified using \fB-o\fP, +\fIjoin\fP is not aware of what fields might be empty. The exception +to this is the join field, but identifying an empty join +field with the \fB-e\fP string is not historical practice and some +scripts might break if this were changed. +.LP +The 0 field in the \fB-o\fP list was adopted from the Tenth Edition +version of \fIjoin\fP to satisfy international objections +that the \fIjoin\fP in the base documents does not support the "full +join" or "outer join" described in relational database +literature. Although it has been possible to include a join field +in the output (by default, or by field number using \fB-o\fP), +the join field could not be included for an unpaired line selected +by \fB-a\fP. The \fB-o\fP 0 field essentially selects the +union of the join fields. +.LP +This sort of outer join was not possible with the \fIjoin\fP commands +in the base documents. The \fB-o\fP 0 field was chosen +because it is an upwards-compatible change for applications. An alternative +was considered: have the join field represent the union +of the fields in the files (where they are identical for matched lines, +and one or both are null for unmatched lines). This was not +adopted because it would break some historical applications. +.LP +The ability to specify \fIfile2\fP as \fB-\fP is not historical practice; +it was added for completeness. +.LP +The \fB-v\fP option is not historical practice, but was considered +necessary because it permitted the writing of \fIonly\fP +those lines that do not match on the join field, as opposed to the +\fB-a\fP option, which prints both lines that do and do not +match. This additional facility is parallel with the \fB-v\fP option +of \fIgrep\fP. +.LP +Some historical implementations have been encountered where a blank +line in one of the input files was considered to be the end +of the file; the description in this volume of IEEE\ Std\ 1003.1-2001 +does not cite this as an allowable case. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIawk\fP , \fIcomm\fP , \fIsort\fP , \fIuniq\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/kill.1p b/man1p/kill.1p new file mode 100644 index 000000000..c494b742b --- /dev/null +++ b/man1p/kill.1p @@ -0,0 +1,393 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "KILL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" kill +.SH NAME +kill \- terminate or signal processes +.SH SYNOPSIS +.LP +\fBkill -s\fP \fIsignal_name pid\fP \fB... +.br +.sp +kill -l\fP \fB[\fP\fIexit_status\fP\fB]\fP\fB +.br +.sp +\fP +.LP +\fBkill\fP \fB[\fP\fB-\fP\fIsignal_name\fP\fB]\fP \fIpid\fP \fB... +.br +.sp +kill\fP \fB[\fP\fB-\fP\fIsignal_number\fP\fB]\fP \fIpid\fP \fB... +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIkill\fP utility shall send a signal to the process or processes +specified by each \fIpid\fP operand. +.LP +For each \fIpid\fP operand, the \fIkill\fP utility shall perform actions +equivalent to the \fIkill\fP() function defined in the System Interfaces +volume of IEEE\ Std\ 1003.1-2001 +called with the following arguments: +.IP " *" 3 +The value of the \fIpid\fP operand shall be used as the \fIpid\fP +argument. +.LP +.IP " *" 3 +The \fIsig\fP argument is the value specified by the \fB-s\fP option, +\fB-\fP \fIsignal_number\fP option, or the \fB-\fP +\fIsignal_name\fP option, or by SIGTERM, if none of these options +is specified. +.LP +.SH OPTIONS +.LP +The \fIkill\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +\ except that +in the last two SYNOPSIS forms, the \fB-\fP \fIsignal_number\fP and +\fB-\fP \fIsignal_name\fP options are usually more than a +single character. +.LP +The following options shall be supported: +.TP 7 +\fB-l\fP +(The letter ell.) Write all values of \fIsignal_name\fP supported +by the implementation, if no operand is given. If an +\fIexit_status\fP operand is given and it is a value of the \fB'?'\fP +shell special parameter (see \fISpecial Parameters\fP and \fIwait\fP() +) corresponding to a process +that was terminated by a signal, the \fIsignal_name\fP corresponding +to the signal that terminated the process shall be written. +If an \fIexit_status\fP operand is given and it is the unsigned decimal +integer value of a signal number, the \fIsignal_name\fP +(the symbolic constant name without the \fBSIG\fP prefix defined in +the Base Definitions volume of IEEE\ Std\ 1003.1-2001) +corresponding to that signal shall be written. Otherwise, the results +are unspecified. +.TP 7 +\fB-s\ \fP \fIsignal_name\fP +.sp +Specify the signal to send, using one of the symbolic names defined +in the \fI\fP header. Values of \fIsignal_name\fP shall +be recognized in a +case-independent fashion, without the \fBSIG\fP prefix. In addition, +the symbolic name 0 shall be recognized, representing the +signal value zero. The corresponding signal shall be sent instead +of SIGTERM. +.TP 7 +\fB-\fP\fIsignal_name\fP +.sp +Equivalent to \fB-s\fP \fIsignal_name\fP. +.TP 7 +\fB-\fP\fIsignal_number\fP +.sp +Specify a non-negative decimal integer, \fIsignal_number\fP, representing +the signal to be used instead of SIGTERM, as the +\fIsig\fP argument in the effective call to \fIkill\fP(). The correspondence +between integer +values and the \fIsig\fP value used is shown in the following table. +.LP +The effects of specifying any \fIsignal_number\fP other than those +listed in the table are undefined. +.sp +.sp +.TS C +center; l l. +\fIsignal_number\fP \fB\fIsig\fP Value\fP +0 0 +1 SIGHUP +2 SIGINT +3 SIGQUIT +6 SIGABRT +9 SIGKILL +14 SIGALRM +15 SIGTERM +.TE +.LP +If the first argument is a negative integer, it shall be interpreted +as a \fB-\fP \fIsignal_number\fP option, not as a +negative \fIpid\fP operand specifying a process group. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIpid\fP +One of the following: +.RS +.IP " 1." 4 +A decimal integer specifying a process or process group to be signaled. +The process or processes selected by positive, negative, +and zero values of the \fIpid\fP operand shall be as described for +the \fIkill\fP() +function. If process number 0 is specified, all processes in the current +process group shall be signaled. For the effects of +negative \fIpid\fP numbers, see the \fIkill\fP() function defined +in the System Interfaces +volume of IEEE\ Std\ 1003.1-2001. If the first \fIpid\fP operand is +negative, it should be preceded by \fB"--"\fP to +keep it from being interpreted as an option. +.LP +.IP " 2." 4 +A job control job ID (see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 3.203, Job Control Job ID) that identifies a background process +group to be +signaled. The job control job ID notation is applicable only for invocations +of \fIkill\fP in the current shell execution +environment; see \fIShell Execution Environment\fP . +.LP +.RE +.TP 7 +\fIexit_status\fP +A decimal integer specifying a signal number or the exit status of +a process terminated by a signal. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIkill\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +When the \fB-l\fP option is not specified, the standard output shall +not be used. +.LP +When the \fB-l\fP option is specified, the symbolic name of each signal +shall be written in the following format: +.sp +.RS +.nf + +\fB"%s%c", <\fP\fIsignal_name\fP\fB>, <\fP\fIseparator\fP\fB> +\fP +.fi +.RE +.LP +where the <\fIsignal_name\fP> is in uppercase, without the \fBSIG\fP +prefix, and the <\fIseparator\fP> shall be +either a or a . For the last signal written, <\fIseparator\fP> +shall be a . +.LP +When both the \fB-l\fP option and \fIexit_status\fP operand are specified, +the symbolic name of the corresponding signal shall +be written in the following format: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIsignal_name\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +At least one matching process was found for each \fIpid\fP operand, +and the specified signal was successfully processed for at +least one matching process. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Process numbers can be found by using \fIps\fP. +.LP +The job control job ID notation is not required to work as expected +when \fIkill\fP is operating in its own utility execution +environment. In either of the following examples: +.sp +.RS +.nf + +\fBnohup kill %1 & +system("kill %1"); +\fP +.fi +.RE +.LP +the \fIkill\fP operates in a different environment and does not share +the shell's understanding of job numbers. +.SH EXAMPLES +.LP +Any of the commands: +.sp +.RS +.nf + +\fBkill -9 100 -165 +kill -s kill 100 -165 +kill -s KILL 100 -165 +\fP +.fi +.RE +.LP +sends the SIGKILL signal to the process whose process ID is 100 and +to all processes whose process group ID is 165, assuming the +sending process has permission to send that signal to the specified +processes, and that they exist. +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001 and this volume +of IEEE\ Std\ 1003.1-2001 do not require +specific signal numbers for any \fIsignal_names\fP. Even the \fB-\fP +\fIsignal_number\fP option provides symbolic (although +numeric) names for signals. If a process is terminated by a signal, +its exit status indicates the signal that killed it, but the +exact values are not specified. The \fIkill\fP \fB-l\fP option, however, +can be used to map decimal signal numbers and exit +status values into the name of a signal. The following example reports +the status of a terminated job: +.sp +.RS +.nf + +\fBjob +stat=$? +if [ $stat -eq 0 ] +then + echo job completed successfully. +elif [ $stat -gt 128 ] +then + echo job terminated by signal SIG$(kill -l $stat). +else + echo job terminated with error code $stat. +fi +\fP +.fi +.RE +.LP +To send the default signal to a process group (say 123), an application +should use a command similar to one of the +following: +.sp +.RS +.nf + +\fBkill -TERM -123 +kill -- -123 +\fP +.fi +.RE +.SH RATIONALE +.LP +The \fB-l\fP option originated from the C shell, and is also implemented +in the KornShell. The C shell output can consist of +multiple output lines because the signal names do not always fit on +a single line on some terminal screens. The KornShell output +also included the implementation-defined signal numbers and was considered +by the standard developers to be too difficult for +scripts to parse conveniently. The specified output format is intended +not only to accommodate the historical C shell output, but +also to permit an entirely vertical or entirely horizontal listing +on systems for which this is appropriate. +.LP +An early proposal invented the name SIGNULL as a \fIsignal_name\fP +for signal 0 (used by the System Interfaces volume of +IEEE\ Std\ 1003.1-2001 to test for the existence of a process without +sending it a signal). Since the \fIsignal_name\fP 0 +can be used in this case unambiguously, SIGNULL has been removed. +.LP +An early proposal also required symbolic \fIsignal_name\fPs to be +recognized with or without the \fBSIG\fP prefix. Historical +versions of \fIkill\fP have not written the \fBSIG\fP prefix for the +\fB-l\fP option and have not recognized the \fBSIG\fP +prefix on \fIsignal_name\fPs. Since neither applications portability +nor ease-of-use would be improved by requiring this +extension, it is no longer required. +.LP +To avoid an ambiguity of an initial negative number argument specifying +either a signal number or a process group, +IEEE\ Std\ 1003.1-2001 mandates that it is always considered the former +by implementations that support the XSI option. It +also requires that conforming applications always use the \fB"--"\fP +options terminator argument when specifying a process +group, unless an option is also specified. +.LP +The \fB-s\fP option was added in response to international interest +in providing some form of \fIkill\fP that meets the +Utility Syntax Guidelines. +.LP +The job control job ID notation is not required to work as expected +when \fIkill\fP is operating in its own utility execution +environment. In either of the following examples: +.sp +.RS +.nf + +\fBnohup kill %1 & +system("kill %1"); +\fP +.fi +.RE +.LP +the \fIkill\fP operates in a different environment and does not understand +how the shell has managed its job numbers. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP , \fIps\fP , \fIwait\fP() , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIkill\fP(), the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/lex.1p b/man1p/lex.1p new file mode 100644 index 000000000..6d84cb9fa --- /dev/null +++ b/man1p/lex.1p @@ -0,0 +1,954 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LEX" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" lex +.SH NAME +lex \- generate programs for lexical tasks (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBlex\fP \fB[\fP\fB-t\fP\fB][\fP\fB-n|-v\fP\fB][\fP\fIfile\fP \fB...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIlex\fP utility shall generate C programs to be used in lexical +processing of character input, and that can be used as an +interface to \fIyacc\fP. The C programs shall be generated from \fIlex\fP +source code and +conform to the ISO\ C standard. Usually, the \fIlex\fP utility shall +write the program it generates to the file +\fBlex.yy.c\fP; the state of this file is unspecified if \fIlex\fP +exits with a non-zero exit status. See the EXTENDED +DESCRIPTION section for a complete description of the \fIlex\fP input +language. +.SH OPTIONS +.LP +The \fIlex\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-n\fP +Suppress the summary of statistics usually written with the \fB-v\fP +option. If no table sizes are specified in the \fIlex\fP +source code and the \fB-v\fP option is not specified, then \fB-n\fP +is implied. +.TP 7 +\fB-t\fP +Write the resulting program to standard output instead of \fBlex.yy.c\fP. +.TP 7 +\fB-v\fP +Write a summary of \fIlex\fP statistics to the standard output. (See +the discussion of \fIlex\fP table sizes in Definitions in lex .) If +the \fB-t\fP option is specified and \fB-n\fP is not specified, this +report shall +be written to standard error. If table sizes are specified in the +\fIlex\fP source code, and if the \fB-n\fP option is not +specified, the \fB-v\fP option may be enabled. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of an input file. If more than one such \fIfile\fP is specified, +all files shall be concatenated to produce a +single \fIlex\fP program. If no \fIfile\fP operands are specified, +or if a \fIfile\fP operand is \fB'-'\fP , the standard +input shall be used. +.sp +.SH STDIN +.LP +The standard input shall be used if no \fIfile\fP operands are specified, +or if a \fIfile\fP operand is \fB'-'\fP . See +INPUT FILES. +.SH INPUT FILES +.LP +The input files shall be text files containing \fIlex\fP source code, +as described in the EXTENDED DESCRIPTION section. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIlex\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular +expressions. If this variable is not set to the POSIX locale, the +results are unspecified. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), and +the behavior of character classes within regular expressions. +If this variable is not set to the POSIX locale, the results are unspecified. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If the \fB-t\fP option is specified, the text file of C source code +output of \fIlex\fP shall be written to standard +output. +.LP +If the \fB-t\fP option is not specified: +.IP " *" 3 +Implementation-defined informational, error, and warning messages +concerning the contents of \fIlex\fP source code input shall +be written to either the standard output or standard error. +.LP +.IP " *" 3 +If the \fB-v\fP option is specified and the \fB-n\fP option is not +specified, \fIlex\fP statistics shall also be written to +either the standard output or standard error, in an implementation-defined +format. These statistics may also be generated if table +sizes are specified with a \fB'%'\fP operator in the \fIDefinitions\fP +section, as long as the \fB-n\fP option is not +specified. +.LP +.SH STDERR +.LP +If the \fB-t\fP option is specified, implementation-defined informational, +error, and warning messages concerning the contents +of \fIlex\fP source code input shall be written to the standard error. +.LP +If the \fB-t\fP option is not specified: +.IP " 1." 4 +Implementation-defined informational, error, and warning messages +concerning the contents of \fIlex\fP source code input shall +be written to either the standard output or standard error. +.LP +.IP " 2." 4 +If the \fB-v\fP option is specified and the \fB-n\fP option is not +specified, \fIlex\fP statistics shall also be written to +either the standard output or standard error, in an implementation-defined +format. These statistics may also be generated if table +sizes are specified with a \fB'%'\fP operator in the \fIDefinitions\fP +section, as long as the \fB-n\fP option is not +specified. +.LP +.SH OUTPUT FILES +.LP +A text file containing C source code shall be written to \fBlex.yy.c\fP, +or to the standard output if the \fB-t\fP option is +present. +.SH EXTENDED DESCRIPTION +.LP +Each input file shall contain \fIlex\fP source code, which is a table +of regular expressions with corresponding actions in the +form of C program fragments. +.LP +When \fBlex.yy.c\fP is compiled and linked with the \fIlex\fP library +(using the \fB-l\ l\fP operand with \fIc99\fP), the resulting program +shall read character input from the standard input and shall +partition it into strings that match the given expressions. +.LP +When an expression is matched, these actions shall occur: +.IP " *" 3 +The input string that was matched shall be left in \fIyytext\fP as +a null-terminated string; \fIyytext\fP shall either be an +external character array or a pointer to a character string. As explained +in Definitions in lex , +the type can be explicitly selected using the \fB%array\fP or \fB%pointer\fP +declarations, but the default is +implementation-defined. +.LP +.IP " *" 3 +The external \fBint\fP \fIyyleng\fP shall be set to the length of +the matching string. +.LP +.IP " *" 3 +The expression's corresponding program fragment, or action, shall +be executed. +.LP +.LP +During pattern matching, \fIlex\fP shall search the set of patterns +for the single longest possible match. Among rules that +match the same number of characters, the rule given first shall be +chosen. +.LP +The general format of \fIlex\fP source shall be: +.sp +.RS +.nf + +\fIDefinitions\fP +\fB%%\fP +\fIRules\fP +\fB%%\fP +\fIUser\fPSubroutines +.fi +.RE +.LP +The first \fB"%%"\fP is required to mark the beginning of the rules +(regular expressions and actions); the second +\fB"%%"\fP is required only if user subroutines follow. +.LP +Any line in the \fIDefinitions\fP section beginning with a +shall be assumed to be a C program fragment and shall +be copied to the external definition area of the \fBlex.yy.c\fP file. +Similarly, anything in the \fIDefinitions\fP section +included between delimiter lines containing only \fB"%{"\fP and \fB"%}"\fP +shall also be copied unchanged to the external +definition area of the \fBlex.yy.c\fP file. +.LP +Any such input (beginning with a or within \fB"%{"\fP and +\fB"%}"\fP delimiter lines) appearing at the +beginning of the \fIRules\fP section before any rules are specified +shall be written to \fBlex.yy.c\fP after the declarations of +variables for the \fIyylex\fP() function and before the first line +of code in \fIyylex\fP(). Thus, user variables local to +\fIyylex\fP() can be declared here, as well as application code to +execute upon entry to \fIyylex\fP(). +.LP +The action taken by \fIlex\fP when encountering any input beginning +with a or within \fB"%{"\fP and +\fB"%}"\fP delimiter lines appearing in the \fIRules\fP section but +coming after one or more rules is undefined. The presence +of such input may result in an erroneous definition of the \fIyylex\fP() +function. +.SS Definitions in lex +.LP +\fIDefinitions\fP appear before the first \fB"%%"\fP delimiter. Any +line in this section not contained between \fB"%{"\fP +and \fB"%}"\fP lines and not beginning with a shall be assumed +to define a \fIlex\fP substitution string. The +format of these lines shall be: +.sp +.RS +.nf + +\fIname substitute\fP +.fi +.RE +.LP +If a \fIname\fP does not meet the requirements for identifiers in +the ISO\ C standard, the result is undefined. The string +\fIsubstitute\fP shall replace the string { \fIname\fP} when it is +used in a rule. The \fIname\fP string shall be recognized in +this context only when the braces are provided and when it does not +appear within a bracket expression or within double-quotes. +.LP +In the \fIDefinitions\fP section, any line beginning with a \fB'%'\fP +(percent sign) character and followed by an +alphanumeric word beginning with either \fB's'\fP or \fB'S'\fP shall +define a set of start conditions. Any line beginning +with a \fB'%'\fP followed by a word beginning with either \fB'x'\fP +or \fB'X'\fP shall define a set of exclusive start +conditions. When the generated scanner is in a \fB%s\fP state, patterns +with no state specified shall be also active; in a +\fB%x\fP state, such patterns shall not be active. The rest of the +line, after the first word, shall be considered to be one or +more -separated names of start conditions. Start condition +names shall be constructed in the same way as definition +names. Start conditions can be used to restrict the matching of regular +expressions to one or more states as described in Regular Expressions +in lex . +.LP +Implementations shall accept either of the following two mutually-exclusive +declarations in the \fIDefinitions\fP section: +.TP 7 +\fB%array\fP +Declare the type of \fIyytext\fP to be a null-terminated character +array. +.TP 7 +\fB%pointer\fP +Declare the type of \fIyytext\fP to be a pointer to a null-terminated +character string. +.sp +.LP +The default type of \fIyytext\fP is implementation-defined. If an +application refers to \fIyytext\fP outside of the scanner +source file (that is, via an \fBextern\fP), the application shall +include the appropriate \fB%array\fP or \fB%pointer\fP +declaration in the scanner source file. +.LP +Implementations shall accept declarations in the \fIDefinitions\fP +section for setting certain internal table sizes. The +declarations are shown in the following table. +.sp +.ce 1 +\fBTable: Table Size Declarations in \fIlex\fP\fP +.TS C +center; l2 l2 l. +\fBDeclaration\fP \fBDescription\fP \fBMinimum Value\fP +%\fBp\fP \fIn\fP Number of positions 2500 +%\fBn\fP \fIn\fP Number of states 500 +%\fBa\fP \fIn\fP Number of transitions 2000 +%\fBe\fP \fIn\fP Number of parse tree nodes 1000 +%\fBk\fP \fIn\fP Number of packed character classes 1000 +%\fBo\fP \fIn\fP Size of the output array 3000 +.TE +.LP +In the table, \fIn\fP represents a positive decimal integer, preceded +by one or more s. The exact meaning of these +table size numbers is implementation-defined. The implementation shall +document how these numbers affect the \fIlex\fP utility and +how they are related to any output that may be generated by the implementation +should limitations be encountered during the +execution of \fIlex\fP. It shall be possible to determine from this +output which of the table size values needs to be modified to +permit \fIlex\fP to successfully generate tables for the input language. +The values in the column Minimum Value represent the +lowest values conforming implementations shall provide. +.SS Rules in lex +.LP +The rules in \fIlex\fP source files are a table in which the left +column contains regular expressions and the right column +contains actions (C program fragments) to be executed when the expressions +are recognized. +.sp +.RS +.nf + +\fIERE action +ERE action\fP\fB... +\fP +.fi +.RE +.LP +The extended regular expression (ERE) portion of a row shall be separated +from \fIaction\fP by one or more s. A +regular expression containing s shall be recognized under one +of the following conditions: +.IP " *" 3 +The entire expression appears within double-quotes. +.LP +.IP " *" 3 +The s appear within double-quotes or square brackets. +.LP +.IP " *" 3 +Each is preceded by a backslash character. +.LP +.SS User Subroutines in lex +.LP +Anything in the user subroutines section shall be copied to \fBlex.yy.c\fP +following \fIyylex\fP(). +.SS Regular Expressions in lex +.LP +The \fIlex\fP utility shall support the set of extended regular expressions +(see the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 9.4, Extended Regular Expressions), +with the following additions and exceptions to the syntax: +.TP 7 +\fB"..."\fP +Any string enclosed in double-quotes shall represent the characters +within the double-quotes as themselves, except that +backslash escapes (which appear in the following table) shall be recognized. +Any backslash-escape sequence shall be terminated by +the closing quote. For example, \fB"\\01"\fP \fB"1"\fP represents +a single string: the octal value 1 followed by the character +\fB'1'\fP . +.TP 7 +<\fIstate\fP>\fIr\fP,\ <\fIstate1,state2,\fP...>\fIr\fP +.sp +The regular expression \fIr\fP shall be matched only when the program +is in one of the start conditions indicated by \fIstate\fP, +\fIstate1\fP, and so on; see Actions in lex . (As an exception to +the typographical conventions of +the rest of this volume of IEEE\ Std\ 1003.1-2001, in this case <\fIstate\fP> +does not represent a metavariable, but +the literal angle-bracket characters surrounding a symbol.) The start +condition shall be recognized as such only at the beginning +of a regular expression. +.TP 7 +\fIr\fP/\fIx\fP +The regular expression \fIr\fP shall be matched only if it is followed +by an occurrence of regular expression \fIx\fP ( +\fIx\fP is the instance of trailing context, further defined below). +The token returned in \fIyytext\fP shall only match +\fIr\fP. If the trailing portion of \fIr\fP matches the beginning +of \fIx\fP, the result is unspecified. The \fIr\fP expression +cannot include further trailing context or the \fB'$'\fP (match-end-of-line) +operator; \fIx\fP cannot include the \fB'^'\fP +(match-beginning-of-line) operator, nor trailing context, nor the +\fB'$'\fP operator. That is, only one occurrence of trailing +context is allowed in a \fIlex\fP regular expression, and the \fB'^'\fP +operator only can be used at the beginning of such an +expression. +.TP 7 +{\fIname\fP} +When \fIname\fP is one of the substitution symbols from the \fIDefinitions\fP +section, the string, including the enclosing +braces, shall be replaced by the \fIsubstitute\fP value. The \fIsubstitute\fP +value shall be treated in the extended regular +expression as if it were enclosed in parentheses. No substitution +shall occur if { \fIname\fP} occurs within a bracket expression +or within double-quotes. +.sp +.LP +Within an ERE, a backslash character shall be considered to begin +an escape sequence as specified in the table in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 5, File Format +Notation ( +\fB'\\\\'\fP , \fB'\\a'\fP , \fB'\\b'\fP , \fB'\\f'\fP , \fB'\\n'\fP +, \fB'\\r'\fP , \fB'\\t'\fP , \fB'\\v'\fP ). In +addition, the escape sequences in the following table shall be recognized. +.LP +A literal cannot occur within an ERE; the escape sequence +\fB'\\n'\fP can be used to represent a +. A shall not be matched by a period operator. +.br +.sp +.ce 1 +\fBTable: Escape Sequences in \fIlex\fP\fP +.TS C +center; l1 lw(30)1 lw(30). +\fBEscape\fP T{ +.na +\fB\ \fP +.ad +T} T{ +.na +\fB\ \fP +.ad +T} +\fBSequence\fP T{ +.na +\fBDescription\fP +.ad +T} T{ +.na +\fBMeaning\fP +.ad +T} +\\\fIdigits\fP T{ +.na +A backslash character followed by the longest sequence of one, two, or three octal-digit characters (01234567). If all of the digits are 0 (that is, representation of the NUL character), the behavior is undefined. +.ad +T} T{ +.na +The character whose encoding is represented by the one, two, or three-digit octal integer. If the size of a byte on the system is greater than nine bits, the valid escape sequence used to represent a byte is implementation-defined. Multi-byte characters require multiple, concatenated escape sequences of this type, including the leading \fB'\\'\fP for each byte. +.ad +T} +\\x\fIdigits\fP T{ +.na +A backslash character followed by the longest sequence of hexadecimal-digit characters (01234567abcdefABCDEF). If all of the digits are 0 (that is, representation of the NUL character), the behavior is undefined. +.ad +T} T{ +.na +The character whose encoding is represented by the hexadecimal integer. +.ad +T} +\\c T{ +.na +A backslash character followed by any character not described in this table or in the table in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 5, File Format Notation ( \fB'\\\\'\fP , \fB'\\a'\fP , \fB'\\b'\fP , \fB'\\f'\fP , \fB'\\n'\fP , \fB'\\r'\fP , \fB'\\t'\fP , \fB'\\v'\fP ). +.ad +T} T{ +.na +The character \fB'c'\fP , unchanged. +.ad +T} +.TE +.TP 7 +\fBNote:\fP +If a \fB'\\x'\fP sequence needs to be immediately followed by a hexadecimal +digit character, a sequence such as +\fB"\\x1"\fP \fB"1"\fP can be used, which represents a character containing +the value 1, followed by the character +\fB'1'\fP . +.sp +.LP +The order of precedence given to extended regular expressions for +\fIlex\fP differs from that specified in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 9.4, Extended Regular +Expressions. The order of precedence for \fIlex\fP shall be as shown +in the following table, from high to low. +.TP 7 +\fBNote:\fP +The escaped characters entry is not meant to imply that these are +operators, but they are included in the table to show their +relationships to the true operators. The start condition, trailing +context, and anchoring notations have been omitted from the +table because of the placement restrictions described in this section; +they can only appear at the beginning or ending of an +ERE. +.sp +.sp +.sp +.ce 1 +\fBTable: ERE Precedence in \fIlex\fP\fP +.TS C +center; l2 l. +\fBExtended Regular Expression\fP \fBPrecedence\fP +collation-related bracket symbols [= =] [: :] [. .] +escaped characters \\<\fIspecial character\fP> +bracket expression [ ] +quoting "..." +grouping ( ) +definition {\fIname\fP} +single-character RE duplication * + ? +concatenation \ +interval expression {m,n} +alternation | +.TE +.LP +The ERE anchoring operators \fB'^'\fP and \fB'$'\fP do not appear +in the table. With \fIlex\fP regular expressions, these +operators are restricted in their use: the \fB'^'\fP operator can +only be used at the beginning of an entire regular expression, +and the \fB'$'\fP operator only at the end. The operators apply to +the entire regular expression. Thus, for example, the pattern +\fB"(^abc)|(def$)"\fP is undefined; it can instead be written as two +separate rules, one with the regular expression +\fB"^abc"\fP and one with \fB"def$"\fP , which share a common action +via the special \fB'|'\fP action (see below). If the +pattern were written \fB"^abc|def$"\fP , it would match either \fB"abc"\fP +or \fB"def"\fP on a line by itself. +.LP +Unlike the general ERE rules, embedded anchoring is not allowed by +most historical \fIlex\fP implementations. An example of +embedded anchoring would be for patterns such as \fB"(^|\ )foo(\ |$)"\fP +to match \fB"foo"\fP when it exists as a +complete word. This functionality can be obtained using existing \fIlex\fP +features: +.sp +.RS +.nf + +\fB^foo/[ \\n] | +" foo"/[ \\n] /* Found foo as a separate word. */ +\fP +.fi +.RE +.LP +Note also that \fB'$'\fP is a form of trailing context (it is equivalent +to \fB"/\\n"\fP ) and as such cannot be used with +regular expressions containing another instance of the operator (see +the preceding discussion of trailing context). +.LP +The additional regular expressions trailing-context operator \fB'/'\fP +can be used as an ordinary character if presented +within double-quotes, \fB"/"\fP ; preceded by a backslash, \fB"\\/"\fP +; or within a bracket expression, \fB"[/]"\fP . The +start-condition \fB'<'\fP and \fB'>'\fP operators shall be special +only in a start condition at the beginning of a +regular expression; elsewhere in the regular expression they shall +be treated as ordinary characters. +.SS Actions in lex +.LP +The action to be taken when an ERE is matched can be a C program fragment +or the special actions described below; the program +fragment can contain one or more C statements, and can also include +special actions. The empty C statement \fB';'\fP shall be a +valid action; any string in the \fBlex.yy.c\fP input that matches +the pattern portion of such a rule is effectively ignored or +skipped. However, the absence of an action shall not be valid, and +the action \fIlex\fP takes in such a condition is +undefined. +.LP +The specification for an action, including C statements and special +actions, can extend across several lines if enclosed in +braces: +.sp +.RS +.nf + +\fIERE\fP \fB<\fP\fIone or more blanks\fP\fB> {\fP \fIprogram statement + program statement\fP \fB} +\fP +.fi +.RE +.LP +The default action when a string in the input to a \fBlex.yy.c\fP +program is not matched by any expression shall be to copy the +string to the output. Because the default behavior of a program generated +by \fIlex\fP is to read the input and copy it to the +output, a minimal \fIlex\fP source program that has just \fB"%%"\fP +shall generate a C program that simply copies the input to +the output unchanged. +.LP +Four special actions shall be available: +.sp +.RS +.nf + +\fB| ECHO; REJECT; BEGIN +\fP +.fi +.RE +.TP 7 +\fB|\fP +The action \fB'|'\fP means that the action for the next rule is the +action for this rule. Unlike the other three actions, +\fB'|'\fP cannot be enclosed in braces or be semicolon-terminated; +the application shall ensure that it is specified alone, with +no other actions. +.TP 7 +\fBECHO;\fP +Write the contents of the string \fIyytext\fP on the output. +.TP 7 +\fBREJECT;\fP +Usually only a single expression is matched by a given string in the +input. \fBREJECT\fP means "continue to the next +expression that matches the current input", and shall cause whatever +rule was the second choice after the current rule to be +executed for the same input. Thus, multiple rules can be matched and +executed for one input string or overlapping input strings. +For example, given the regular expressions \fB"xyz"\fP and \fB"xy"\fP +and the input \fB"xyz"\fP , usually only the regular +expression \fB"xyz"\fP would match. The next attempted match would +start after \fBz.\fP If the last action in the +\fB"xyz"\fP rule is \fBREJECT\fP, both this rule and the \fB"xy"\fP +rule would be executed. The \fBREJECT\fP action may be +implemented in such a fashion that flow of control does not continue +after it, as if it were equivalent to a \fBgoto\fP to another +part of \fIyylex\fP(). The use of \fBREJECT\fP may result in somewhat +larger and slower scanners. +.TP 7 +\fBBEGIN\fP +The action: +.sp +.RS +.nf + +\fBBEGIN\fP \fInewstate\fP\fB; +\fP +.fi +.RE +.LP +switches the state (start condition) to \fInewstate\fP. If the string +\fInewstate\fP has not been declared previously as a +start condition in the \fIDefinitions\fP section, the results are +unspecified. The initial state is indicated by the digit +\fB'0'\fP or the token \fBINITIAL\fP. +.sp +.LP +The functions or macros described below are accessible to user code +included in the \fIlex\fP input. It is unspecified whether +they appear in the C code output of \fIlex\fP, or are accessible only +through the \fB-l\ l\fP operand to \fIc99\fP (the \fIlex\fP library). +.TP 7 +\fBint\ \fP \fIyylex\fP(\fBvoid\fP) +.sp +Performs lexical analysis on the input; this is the primary function +generated by the \fIlex\fP utility. The function shall return +zero when the end of input is reached; otherwise, it shall return +non-zero values (tokens) determined by the actions that are +selected. +.TP 7 +\fBint\ \fP \fIyymore\fP(\fBvoid\fP) +.sp +When called, indicates that when the next input string is recognized, +it is to be appended to the current value of \fIyytext\fP +rather than replacing it; the value in \fIyyleng\fP shall be adjusted +accordingly. +.TP 7 +\fBint\ \fP \fIyyless\fP(\fBint\ \fP \fIn\fP) +.sp +Retains \fIn\fP initial characters in \fIyytext\fP, NUL-terminated, +and treats the remaining characters as if they had not been +read; the value in \fIyyleng\fP shall be adjusted accordingly. +.TP 7 +\fBint\ \fP \fIinput\fP(\fBvoid\fP) +.sp +Returns the next character from the input, or zero on end-of-file. +It shall obtain input from the stream pointer \fIyyin\fP, +although possibly via an intermediate buffer. Thus, once scanning +has begun, the effect of altering the value of \fIyyin\fP is +undefined. The character read shall be removed from the input stream +of the scanner without any processing by the scanner. +.TP 7 +\fBint\ \fP \fIunput\fP(\fBint\ \fP \fIc\fP) +.sp +Returns the character \fB'c'\fP to the input; \fIyytext\fP and \fIyyleng\fP +are undefined until the next expression is +matched. The result of using \fIunput\fP() for more characters than +have been input is unspecified. +.sp +.LP +The following functions shall appear only in the \fIlex\fP library +accessible through the \fB-l\ l\fP operand; they can +therefore be redefined by a conforming application: +.TP 7 +\fBint\ \fP \fIyywrap\fP(\fBvoid\fP) +.sp +Called by \fIyylex\fP() at end-of-file; the default \fIyywrap\fP() +shall always return 1. If the application requires +\fIyylex\fP() to continue processing with another source of input, +then the application can include a function \fIyywrap\fP(), +which associates another file with the external variable \fBFILE *\fP +\fIyyin\fP and shall return a value of zero. +.TP 7 +\fBint\ \fP \fImain\fP(\fBint\ \fP \fIargc\fP, \fBchar *\fP\fIargv\fP[]) +.sp +Calls \fIyylex\fP() to perform lexical analysis, then exits. The user +code can contain \fImain\fP() to perform +application-specific operations, calling \fIyylex\fP() as applicable. +.sp +.LP +Except for \fIinput\fP(), \fIunput\fP(), and \fImain\fP(), all external +and static names generated by \fIlex\fP shall begin +with the prefix \fByy\fP or \fBYY\fP. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Conforming applications are warned that in the \fIRules\fP section, +an ERE without an action is not acceptable, but need not be +detected as erroneous by \fIlex\fP. This may result in compilation +or runtime errors. +.LP +The purpose of \fIinput\fP() is to take characters off the input stream +and discard them as far as the lexical analysis is +concerned. A common use is to discard the body of a comment once the +beginning of a comment is recognized. +.LP +The \fIlex\fP utility is not fully internationalized in its treatment +of regular expressions in the \fIlex\fP source code or +generated lexical analyzer. It would seem desirable to have the lexical +analyzer interpret the regular expressions given in the +\fIlex\fP source according to the environment specified when the lexical +analyzer is executed, but this is not possible with the +current \fIlex\fP technology. Furthermore, the very nature of the +lexical analyzers produced by \fIlex\fP must be closely tied to +the lexical requirements of the input language being described, which +is frequently locale-specific anyway. (For example, writing +an analyzer that is used for French text is not automatically useful +for processing other languages.) +.SH EXAMPLES +.LP +The following is an example of a \fIlex\fP program that implements +a rudimentary scanner for a Pascal-like syntax: +.sp +.RS +.nf + +\fB%{ +/* Need this for the call to atof() below. */ +#include +/* Need this for printf(), fopen(), and stdin below. */ +#include +%} +.sp + +DIGIT [0-9] +ID [a-z][a-z0-9]* +.sp + +%% +.sp + +{DIGIT}+ { + printf("An integer: %s (%d)\\n", yytext, + atoi(yytext)); + } +.sp + +{DIGIT}+"."{DIGIT}* { + printf("A float: %s (%g)\\n", yytext, + atof(yytext)); + } +.sp + +if|then|begin|end|procedure|function { + printf("A keyword: %s\\n", yytext); + } +.sp + +{ID} printf("An identifier: %s\\n", yytext); +.sp + +"+"|"-"|"*"|"/" printf("An operator: %s\\n", yytext); +.sp + +"{"[^}\\n]*"}" /* Eat up one-line comments. */ +.sp + +[ \\t\\n]+ /* Eat up white space. */ +.sp + +\&. printf("Unrecognized character: %s\\n", yytext); +.sp + +%% +.sp + +int main(int argc, char *argv[]) +{ + ++argv, --argc; /* Skip over program name. */ + if (argc > 0) + yyin = fopen(argv[0], "r"); + else + yyin = stdin; +.sp + + yylex(); +} +\fP +.fi +.RE +.SH RATIONALE +.LP +Even though the \fB-c\fP option and references to the C language are +retained in this description, \fIlex\fP may be +generalized to other languages, as was done at one time for EFL, the +Extended FORTRAN Language. Since the \fIlex\fP input +specification is essentially language-independent, versions of this +utility could be written to produce Ada, Modula-2, or Pascal +code, and there are known historical implementations that do so. +.LP +The current description of \fIlex\fP bypasses the issue of dealing +with internationalized EREs in the \fIlex\fP source code or +generated lexical analyzer. If it follows the model used by \fIawk\fP +(the source code is +assumed to be presented in the POSIX locale, but input and output +are in the locale specified by the environment variables), then +the tables in the lexical analyzer produced by \fIlex\fP would interpret +EREs specified in the \fIlex\fP source in terms of the +environment variables specified when \fIlex\fP was executed. The desired +effect would be to have the lexical analyzer interpret +the EREs given in the \fIlex\fP source according to the environment +specified when the lexical analyzer is executed, but this is +not possible with the current \fIlex\fP technology. +.LP +The description of octal and hexadecimal-digit escape sequences agrees +with the ISO\ C standard use of escape sequences. See +the RATIONALE for \fIed\fP for a discussion of bytes larger than 9 +bits being represented by octal values. +Hexadecimal values can represent larger bytes and multi-byte characters +directly, using as many digits as required. +.LP +There is no detailed output format specification. The observed behavior +of \fIlex\fP under four different historical +implementations was that none of these implementations consistently +reported the line numbers for error and warning messages. +Furthermore, there was a desire that \fIlex\fP be allowed to output +additional diagnostic messages. Leaving message formats +unspecified avoids these formatting questions and problems with internationalization. +.LP +Although the \fB%x\fP specifier for \fIexclusive\fP start conditions +is not historical practice, it is believed to be a +minor change to historical implementations and greatly enhances the +usability of \fIlex\fP programs since it permits an +application to obtain the expected functionality with fewer statements. +.LP +The \fB%array\fP and \fB%pointer\fP declarations were added as a compromise +between historical systems. The System V-based +\fIlex\fP copies the matched text to a \fIyytext\fP array. The \fIflex\fP +program, supported in BSD and GNU systems, uses a +pointer. In the latter case, significant performance improvements +are available for some scanners. Most historical programs should +require no change in porting from one system to another because the +string being referenced is null-terminated in both cases. (The +method used by \fIflex\fP in its case is to null-terminate the token +in place by remembering the character that used to come right +after the token and replacing it before continuing on to the next +scan.) Multi-file programs with external references to +\fIyytext\fP outside the scanner source file should continue to operate +on their historical systems, but would require one of the +new declarations to be considered strictly portable. +.LP +The description of EREs avoids unnecessary duplication of ERE details +because their meanings within a \fIlex\fP ERE are the +same as that for the ERE in this volume of IEEE\ Std\ 1003.1-2001. +.LP +The reason for the undefined condition associated with text beginning +with a or within \fB"%{"\fP and +\fB"%}"\fP delimiter lines appearing in the \fIRules\fP section is +historical practice. Both the BSD and System V \fIlex\fP +copy the indented (or enclosed) input in the \fIRules\fP section (except +at the beginning) to unreachable areas of the +\fIyylex\fP() function (the code is written directly after a \fIbreak\fP +statement). In some cases, the System V \fIlex\fP generates an error +message or a syntax error, depending on the form of indented +input. +.LP +The intention in breaking the list of functions into those that may +appear in \fBlex.yy.c\fP \fIversus\fP those that only +appear in \fBlibl.a\fP is that only those functions in \fBlibl.a\fP +can be reliably redefined by a conforming application. +.LP +The descriptions of standard output and standard error are somewhat +complicated because historical \fIlex\fP implementations +chose to issue diagnostic messages to standard output (unless \fB-t\fP +was given). IEEE\ Std\ 1003.1-2001 allows this +behavior, but leaves an opening for the more expected behavior of +using standard error for diagnostics. Also, the System V behavior +of writing the statistics when any table sizes are given is allowed, +while BSD-derived systems can avoid it. The programmer can +always precisely obtain the desired results by using either the \fB-t\fP +or \fB-n\fP options. +.LP +The OPERANDS section does not mention the use of \fB-\fP as a synonym +for standard input; not all historical implementations +support such usage for any of the \fIfile\fP operands. +.LP +A description of the \fItranslation table\fP was deleted from early +proposals because of its relatively low usage in historical +applications. +.LP +The change to the definition of the \fIinput\fP() function that allows +buffering of input presents the opportunity for major +performance gains in some applications. +.LP +The following examples clarify the differences between \fIlex\fP regular +expressions and regular expressions appearing +elsewhere in this volume of IEEE\ Std\ 1003.1-2001. For regular expressions +of the form \fB"r/x"\fP , the string +matching \fIr\fP is always returned; confusion may arise when the +beginning of \fIx\fP matches the trailing portion of \fIr\fP. +For example, given the regular expression \fB"a*b/cc"\fP and the input +\fB"aaabcc"\fP , \fIyytext\fP would contain the +string \fB"aaab"\fP on this match. But given the regular expression +\fB"x*/xy"\fP and the input \fB"xxxy"\fP , the token +\fBxxx\fP, not \fBxx\fP, is returned by some implementations because +\fBxxx\fP matches \fB"x*"\fP . +.LP +In the rule \fB"ab*/bc"\fP , the \fB"b*"\fP at the end of \fIr\fP +extends \fIr\fP's match into the beginning of the +trailing context, so the result is unspecified. If this rule were +\fB"ab/bc"\fP , however, the rule matches the text +\fB"ab"\fP when it is followed by the text \fB"bc"\fP . In this latter +case, the matching of \fIr\fP cannot extend into the +beginning of \fIx\fP, so the result is specified. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIc99\fP , \fIed\fP , \fIyacc\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/link.1p b/man1p/link.1p new file mode 100644 index 000000000..0a6c157e9 --- /dev/null +++ b/man1p/link.1p @@ -0,0 +1,127 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LINK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" link +.SH NAME +link \- call link function +.SH SYNOPSIS +.LP +\fBlink\fP \fIfile1 file2\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIlink\fP utility shall perform the function call: +.sp +.RS +.nf + +\fBlink(\fP\fIfile1\fP\fB,\fP \fIfile2\fP\fB); +\fP +.fi +.RE +.LP +A user may need appropriate privilege to invoke the \fIlink\fP utility. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile1\fP +The pathname of an existing file. +.TP 7 +\fIfile2\fP +The pathname of the new directory entry to be created. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +Not used. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIlink\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +.sp +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +None. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIln\fP , \fIunlink\fP() , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIlink\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/ln.1p b/man1p/ln.1p new file mode 100644 index 000000000..6b2f3eb9d --- /dev/null +++ b/man1p/ln.1p @@ -0,0 +1,262 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ln +.SH NAME +ln \- link files +.SH SYNOPSIS +.LP +\fBln\fP \fB[\fP\fB-fs\fP\fB]\fP \fIsource_file target_file\fP\fB +.br +.sp +ln\fP \fB[\fP\fB-fs\fP\fB]\fP \fIsource_file\fP \fB...\fP \fItarget_dir\fP\fB +.br +\fP +.SH DESCRIPTION +.LP +In the first synopsis form, the \fIln\fP utility shall create a new +directory entry (link) at the destination path specified by +the \fItarget_file\fP operand. If the \fB-s\fP option is specified, +a symbolic link shall be created for the file specified by +the \fIsource_file\fP operand. This first synopsis form shall be assumed +when the final operand does not name an existing +directory; if more than two operands are specified and the final is +not an existing directory, an error shall result. +.LP +In the second synopsis form, the \fIln\fP utility shall create a new +directory entry (link), or if the \fB-s\fP option is +specified a symbolic link, for each file specified by a \fIsource_file\fP +operand, at a destination path in the existing directory +named by \fItarget_dir\fP. +.LP +If the last operand specifies an existing file of a type not specified +by the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, the behavior is implementation-defined. +.LP +The corresponding destination path for each \fIsource_file\fP shall +be the concatenation of the target directory pathname, a +slash character, and the last pathname component of the \fIsource_file\fP. +The second synopsis form shall be assumed when the +final operand names an existing directory. +.LP +For each \fIsource_file\fP: +.IP " 1." 4 +If the destination path exists: +.RS +.IP " a." 4 +If the \fB-f\fP option is not specified, \fIln\fP shall write a diagnostic +message to standard error, do nothing more with the +current \fIsource_file\fP, and go on to any remaining \fIsource_files\fP. +.LP +.IP " b." 4 +Actions shall be performed equivalent to the \fIunlink\fP() function +defined in the +System Interfaces volume of IEEE\ Std\ 1003.1-2001, called using \fIdestination\fP +as the \fIpath\fP argument. If this +fails for any reason, \fIln\fP shall write a diagnostic message to +standard error, do nothing more with the current +\fIsource_file\fP, and go on to any remaining \fIsource_files\fP. +.LP +.RE +.LP +.IP " 2." 4 +If the \fB-s\fP option is specified, \fIln\fP shall create a symbolic +link named by the destination path and containing as its +pathname \fIsource_file\fP. The \fIln\fP utility shall do nothing +more with \fIsource_file\fP and shall go on to any remaining +files. +.LP +.IP " 3." 4 +If \fIsource_file\fP is a symbolic link, actions shall be performed +equivalent to the \fIlink\fP() function using the object that \fIsource_file\fP +references as the \fIpath1\fP +argument and the destination path as the \fIpath2\fP argument. The +\fIln\fP utility shall do nothing more with \fIsource_file\fP +and shall go on to any remaining files. +.LP +.IP " 4." 4 +Actions shall be performed equivalent to the \fIlink\fP() function +defined in the System +Interfaces volume of IEEE\ Std\ 1003.1-2001 using \fIsource_file\fP +as the \fIpath1\fP argument, and the destination path +as the \fIpath2\fP argument. +.LP +.SH OPTIONS +.LP +The \fIln\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-f\fP +Force existing destination pathnames to be removed to allow the link. +.TP 7 +\fB-s\fP +Create symbolic links instead of hard links. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIsource_file\fP +A pathname of a file to be linked. If the \fB-s\fP option is specified, +no restrictions on the type of file or on its +existence shall be made. If the \fB-s\fP option is not specified, +whether a directory can be linked is +implementation-defined. +.TP 7 +\fItarget_file\fP +The pathname of the new directory entry to be created. +.TP 7 +\fItarget_dir\fP +A pathname of an existing directory in which the new directory entries +are created. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIln\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All the specified files were linked successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +Some historic versions of \fIln\fP (including the one specified by +the SVID) unlink the destination file, if it exists, by +default. If the mode does not permit writing, these versions prompt +for confirmation before attempting the unlink. In these +versions the \fB-f\fP option causes \fIln\fP not to attempt to prompt +for confirmation. +.LP +This allows \fIln\fP to succeed in creating links when the target +file already exists, even if the file itself is not writable +(although the directory must be). Early proposals specified this functionality. +.LP +This volume of IEEE\ Std\ 1003.1-2001 does not allow the \fIln\fP +utility to unlink existing destination paths by +default for the following reasons: +.IP " *" 3 +The \fIln\fP utility has historically been used to provide locking +for shell applications, a usage that is incompatible with +\fIln\fP unlinking the destination path by default. There was no corresponding +technical advantage to adding this +functionality. +.LP +.IP " *" 3 +This functionality gave \fIln\fP the ability to destroy the link structure +of files, which changes the historical behavior of +\fIln\fP. +.LP +.IP " *" 3 +This functionality is easily replicated with a combination of \fIrm\fP +and \fIln\fP. +.LP +.IP " *" 3 +It is not historical practice in many systems; BSD and BSD-derived +systems do not support this behavior. Unfortunately, +whichever behavior is selected can cause scripts written expecting +the other behavior to fail. +.LP +.IP " *" 3 +It is preferable that \fIln\fP perform in the same manner as the \fIlink\fP() +function, +which does not permit the target to exist already. +.LP +.LP +This volume of IEEE\ Std\ 1003.1-2001 retains the \fB-f\fP option +to provide support for shell scripts depending on the +SVID semantics. It seems likely that shell scripts would not be written +to handle prompting by \fIln\fP and would therefore have +specified the \fB-f\fP option. +.LP +The \fB-f\fP option is an undocumented feature of many historical +versions of the \fIln\fP utility, allowing linking to +directories. These versions require modification. +.LP +Early proposals of this volume of IEEE\ Std\ 1003.1-2001 also required +a \fB-i\fP option, which behaved like the +\fB-i\fP options in \fIcp\fP and \fImv\fP, prompting for +confirmation before unlinking existing files. This was not historical +practice for the \fIln\fP utility and has been omitted. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchmod\fP() , \fIfind\fP , \fIpax\fP , \fIrm\fP , the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, \fIlink\fP(), \fIunlink\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/locale.1p b/man1p/locale.1p new file mode 100644 index 000000000..da12fdfa6 --- /dev/null +++ b/man1p/locale.1p @@ -0,0 +1,441 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LOCALE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" locale +.SH NAME +locale \- get locale-specific information +.SH SYNOPSIS +.LP +\fBlocale\fP \fB[\fP\fB-a| -m\fP\fB]\fP\fB +.br +.sp +locale\fP \fB[\fP\fB-ck\fP\fB]\fP \fIname\fP\fB... +.br +\fP +.SH DESCRIPTION +.LP +The \fIlocale\fP utility shall write information about the current +locale environment, or all public locales, to the standard +output. For the purposes of this section, a \fIpublic locale\fP is +one provided by the implementation that is accessible to the +application. +.LP +When \fIlocale\fP is invoked without any arguments, it shall summarize +the current locale environment for each locale category +as determined by the settings of the environment variables defined +in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale. +.LP +When invoked with operands, it shall write values that have been assigned +to the keywords in the locale categories, as +follows: +.IP " *" 3 +Specifying a keyword name shall select the named keyword and the category +containing that keyword. +.LP +.IP " *" 3 +Specifying a category name shall select the named category and all +keywords in that category. +.LP +.SH OPTIONS +.LP +The \fIlocale\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-a\fP +Write information about all available public locales. The available +locales shall include \fBPOSIX\fP, representing the POSIX +locale. The manner in which the implementation determines what other +locales are available is implementation-defined. +.TP 7 +\fB-c\fP +Write the names of selected locale categories; see the STDOUT section. +The \fB-c\fP option increases readability when more +than one category is selected (for example, via more than one keyword +name or via a category name). It is valid both with and +without the \fB-k\fP option. +.TP 7 +\fB-k\fP +Write the names and values of selected keywords. The implementation +may omit values for some keywords; see the OPERANDS +section. +.TP 7 +\fB-m\fP +Write names of available charmaps; see the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable Character Set. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIname\fP +The name of a locale category as defined in the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, the name of a keyword +in a locale category, or the reserved name +\fBcharmap\fP. The named category or keyword shall be selected for +output. If a single \fIname\fP represents both a locale +category name and a keyword name in the current locale, the results +are unspecified. Otherwise, both category and keyword names can +be specified as \fIname\fP operands, in any sequence. It is implementation-defined +whether any keyword values are written for the +categories \fILC_CTYPE\fP and \fILC_COLLATE .\fP +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIlocale\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.LP +The application shall ensure that the \fILANG ,\fP \fILC_* ,\fP and +\fINLSPATH\fP \ environment variables specify the current locale +environment to be written out; they shall be used +if the \fB-a\fP option is not specified. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If \fIlocale\fP is invoked without any options or operands, the names +and values of the \fILANG\fP and \fILC_*\fP environment +variables described in this volume of IEEE\ Std\ 1003.1-2001 shall +be written to the standard output, one variable per +line, with \fILANG\fP first, and each line using the following format. +Only those variables set in the environment and not +overridden by \fILC_ALL\fP shall be written using this format: +.sp +.RS +.nf + +\fB"%s=%s\\n", <\fP\fIvariable_name\fP\fB>, <\fP\fIvalue\fP\fB> +\fP +.fi +.RE +.LP +The names of those \fILC_*\fP variables associated with locale categories +defined in this volume of +IEEE\ Std\ 1003.1-2001 that are not set in the environment or are +overridden by \fILC_ALL\fP shall be written in the +following format: +.sp +.RS +.nf + +\fB"%s=\\"%s\\"\\n", <\fP\fIvariable_name\fP\fB>, <\fP\fIimplied value\fP\fB> +\fP +.fi +.RE +.LP +The <\fIimplied\ value\fP> shall be the name of the locale that has +been selected for that category by the +implementation, based on the values in \fILANG\fP and \fILC_ALL ,\fP +as described in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables. +.LP +The <\fIvalue\fP> and <\fIimplied\ value\fP> shown above shall be +properly quoted for possible later reentry +to the shell. The <\fIvalue\fP> shall not be quoted using double-quotes +(so that it can be distinguished by the user from +the <\fIimplied\ value\fP> case, which always requires double-quotes). +.LP +The \fILC_ALL\fP variable shall be written last, using the first format +shown above. If it is not set, it shall be written +as: +.sp +.RS +.nf + +\fB"LC_ALL=\\n" +\fP +.fi +.RE +.LP +If any arguments are specified: +.IP " 1." 4 +If the \fB-a\fP option is specified, the names of all the public locales +shall be written, each in the following format: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIlocale name\fP\fB> +\fP +.fi +.RE +.LP +.IP " 2." 4 +If the \fB-c\fP option is specified, the names of all selected categories +shall be written, each in the following format: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIcategory name\fP\fB> +\fP +.fi +.RE +.LP +If keywords are also selected for writing (see following items), the +category name output shall precede the keyword output for +that category. +.LP +If the \fB-c\fP option is not specified, the names of the categories +shall not be written; only the keywords, as selected by +the <\fIname\fP> operand, shall be written. +.LP +.IP " 3." 4 +If the \fB-k\fP option is specified, the names and values of selected +keywords shall be written. If a value is non-numeric, it +shall be written in the following format: +.sp +.RS +.nf + +\fB"%s=\\"%s\\"\\n", <\fP\fIkeyword name\fP\fB>, <\fP\fIkeyword value\fP\fB> +\fP +.fi +.RE +.LP +If the keyword was \fBcharmap\fP, the name of the charmap (if any) +that was specified via the \fIlocaledef\fP \fB-f\fP option when the +locale was created shall be written, with the word +\fBcharmap\fP as <\fIkeyword\ name\fP>. +.LP +If a value is numeric, it shall be written in one of the following +formats: +.sp +.RS +.nf + +\fB"%s=%d\\n", <\fP\fIkeyword name\fP\fB>, <\fP\fIkeyword value\fP\fB> +.sp + +"%s=%c%o\\n", <\fP\fIkeyword name\fP\fB>, <\fP\fIescape character\fP\fB>, <\fP\fIkeyword value\fP\fB> +.sp + +"%s=%cx%x\\n", <\fP\fIkeyword name\fP\fB>, <\fP\fIescape character\fP\fB>, <\fP\fIkeyword value\fP\fB> +\fP +.fi +.RE +.LP +where the <\fIescape\ character\fP> is that identified by the \fBescape_char\fP +keyword in the current locale; see +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 7.3, +Locale +Definition. +.LP +Compound keyword values (list entries) shall be separated in the output +by semicolons. When included in keyword values, the +semicolon, the double-quote, the backslash, and any control character +shall be preceded (escaped) with the escape character. +.LP +.IP " 4." 4 +If the \fB-k\fP option is not specified, selected keyword values shall +be written, each in the following format: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIkeyword value\fP\fB> +\fP +.fi +.RE +.LP +If the keyword was \fBcharmap\fP, the name of the charmap (if any) +that was specified via the \fIlocaledef\fP \fB-f\fP option when the +locale was created shall be written. +.LP +.IP " 5." 4 +If the \fB-m\fP option is specified, then a list of all available +charmaps shall be written, each in the format: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIcharmap\fP\fB> +\fP +.fi +.RE +.LP +where <\fIcharmap\fP> is in a format suitable for use as the option-argument +to the \fIlocaledef\fP \fB-f\fP option. +.LP +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All the requested information was found and output successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +If the \fILANG\fP environment variable is not set or set to an empty +value, or one of the \fILC_*\fP environment variables is +set to an unrecognized value, the actual locales assumed (if any) +are implementation-defined as described in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables. +.LP +Implementations are not required to write out the actual values for +keywords in the categories \fILC_CTYPE\fP and \fILC_COLLATE +;\fP however, they must write out the categories (allowing an application +to determine, for example, which character classes are +available). +.SH EXAMPLES +.LP +In the following examples, the assumption is that locale environment +variables are set as follows: +.sp +.RS +.nf + +\fBLANG=locale_x +LC_COLLATE=locale_y +\fP +.fi +.RE +.LP +The command \fIlocale\fP would result in the following output: +.sp +.RS +.nf + +\fBLANG=locale_x +LC_CTYPE="locale_x" +LC_COLLATE=locale_y +LC_TIME="locale_x" +LC_NUMERIC="locale_x" +LC_MONETARY="locale_x" +LC_MESSAGES="locale_x" +LC_ALL= +\fP +.fi +.RE +.LP +The order of presentation of the categories is not specified by this +volume of IEEE\ Std\ 1003.1-2001. +.LP +The command: +.sp +.RS +.nf + +\fBLC_ALL=POSIX locale -ck decimal_point +\fP +.fi +.RE +.LP +would produce: +.sp +.RS +.nf + +\fBLC_NUMERIC +decimal_point="." +\fP +.fi +.RE +.LP +The following command shows an application of \fIlocale\fP to determine +whether a user-supplied response is affirmative: +.sp +.RS +.nf + +\fBif printf "%s\\n" "$response" | grep -Eq "$(locale yesexpr)" +then + affirmative processing goes here +else + non-affirmative processing goes here +fi +\fP +.fi +.RE +.SH RATIONALE +.LP +The output for categories \fILC_CTYPE\fP and \fILC_COLLATE\fP has +been made implementation-defined because there is a +questionable value in having a shell script receive an entire array +of characters. It is also difficult to return a logical +collation description, short of returning a complete \fIlocaledef\fP +source. +.LP +The \fB-m\fP option was included to allow applications to query for +the existence of charmaps. The output is a list of the +charmaps (implementation-supplied and user-supplied, if any) on the +system. +.LP +The \fB-c\fP option was included for readability when more than one +category is selected (for example, via more than one +keyword name or via a category name). It is valid both with and without +the \fB-k\fP option. +.LP +The \fBcharmap\fP keyword, which returns the name of the charmap (if +any) that was used when the current locale was created, +was included to allow applications needing the information to retrieve +it. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIlocaledef\fP , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 7.3, Locale Definition +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/localedef.1p b/man1p/localedef.1p new file mode 100644 index 000000000..e15c7dc6e --- /dev/null +++ b/man1p/localedef.1p @@ -0,0 +1,307 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LOCALEDEF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" localedef +.SH NAME +localedef \- define locale environment +.SH SYNOPSIS +.LP +\fBlocaledef\fP \fB[\fP\fB-c\fP\fB][\fP\fB-f\fP \fIcharmap\fP\fB][\fP\fB-i\fP +\fIsourcefile\fP\fB][\fP\fB-u\fP \fIcode_set_name\fP\fB]\fP \fIname\fP +.SH DESCRIPTION +.LP +The \fIlocaledef\fP utility shall convert source definitions for locale +categories into a format usable by the functions and +utilities whose operational behavior is determined by the setting +of the locale environment variables defined in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale. It +is +implementation-defined whether users have the capability to create +new locales, in addition to those supplied by the +implementation. If the symbolic constant POSIX2_LOCALEDEF is defined, +the system supports the creation of new locales. \ On +XSI-conformant systems, the symbolic constant POSIX2_LOCALEDEF shall +be defined. +.LP +The utility shall read source definitions for one or more locale categories +belonging to the same locale from the file named in +the \fB-i\fP option (if specified) or from standard input. +.LP +The \fIname\fP operand identifies the target locale. The utility shall +support the creation of \fIpublic\fP, or generally +accessible locales, as well as \fIprivate\fP, or restricted-access +locales. Implementations may restrict the capability to create +or modify public locales to users with the appropriate privileges. +.LP +Each category source definition shall be identified by the corresponding +environment variable name and terminated by an +\fBEND\fP \fIcategory-name\fP statement. The following categories +shall be supported. In addition, the input may contain source +for implementation-defined categories. +.TP 7 +\fILC_CTYPE\fP +Defines character classification and case conversion. +.TP 7 +\fILC_COLLATE\fP +.sp +Defines collation rules. +.TP 7 +\fILC_MONETARY\fP +.sp +Defines the format and symbols used in formatting of monetary information. +.TP 7 +\fILC_NUMERIC\fP +.sp +Defines the decimal delimiter, grouping, and grouping symbol for non-monetary +numeric editing. +.TP 7 +\fILC_TIME\fP +Defines the format and content of date and time information. +.TP 7 +\fILC_MESSAGES\fP +.sp +Defines the format and values of affirmative and negative responses. +.sp +.SH OPTIONS +.LP +The \fIlocaledef\fP utility shall conform to the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-c\fP +Create permanent output even if warning messages have been issued. +.TP 7 +\fB-f\ \fP \fIcharmap\fP +Specify the pathname of a file containing a mapping of character symbols +and collating element symbols to actual character +encodings. The format of the \fIcharmap\fP is described in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 6.4, Character +Set Description File. The application shall ensure that this +option is specified if symbolic names (other than collating symbols +defined in a \fBcollating-symbol\fP keyword) are used. If the +\fB-f\fP option is not present, an implementation-defined character +mapping shall be used. +.TP 7 +\fB-i\ \fP \fIinputfile\fP +The pathname of a file containing the source definitions. If this +option is not present, source definitions shall be read from +standard input. The format of the \fIinputfile\fP is described in +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 7.3, Locale Definition. +.TP 7 +\fB-u\ \fP \fIcode_set_name\fP +.sp +Specify the name of a codeset used as the target mapping of character +symbols and collating element symbols whose encoding values +are defined in terms of the ISO/IEC\ 10646-1:2000 standard position +constant values. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIname\fP +Identifies the locale; see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, Locale for a description of the use of this name. If the +name contains one or more +slash characters, \fIname\fP shall be interpreted as a pathname where +the created locale definitions shall be stored. If +\fIname\fP does not contain any slash characters, the interpretation +of the name is implementation-defined and the locale shall be +public. This capability may be restricted to users with appropriate +privileges. (As a consequence of specifying one \fIname\fP, +although several categories can be processed in one execution, only +categories belonging to the same locale can be processed.) +.sp +.SH STDIN +.LP +Unless the \fB-i\fP option is specified, the standard input shall +be a text file containing one or more locale category source +definitions, as described in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 7.3, Locale Definition. When lines are continued using the +escape character +mechanism, there is no limit to the length of the accumulated continued +line. +.SH INPUT FILES +.LP +The character set mapping file specified as the \fIcharmap\fP option-argument +is described in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 6.4, Character Set Description File. +If +a locale category source definition contains a \fBcopy\fP statement, +as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, and the \fBcopy\fP statement +names a +valid, existing locale, then \fIlocaledef\fP shall behave as if the +source definition had contained a valid category source +definition for the named locale. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIlocaledef\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +(This variable has no affect on \fIlocaledef\fP; the POSIX locale +is used for this category.) +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). This +variable has no affect on the processing of \fIlocaledef\fP +input data; the POSIX locale is used for this purpose, regardless +of the value of this variable. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The utility shall report all categories successfully processed, in +an unspecified format. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +The format of the created output is unspecified. If the \fIname\fP +operand does not contain a slash, the existence of an output +file for the locale is unspecified. +.SH EXTENDED DESCRIPTION +.LP +When the \fB-u\fP option is used, the \fIcode_set_name\fP option-argument +shall be interpreted as an implementation-defined +name of a codeset to which the ISO/IEC\ 10646-1:2000 standard position +constant values shall be converted via an +implementation-defined method. Both the ISO/IEC\ 10646-1:2000 standard +position constant values and other formats (decimal, +hexadecimal, or octal) shall be valid as encoding values within the +\fIcharmap\fP file. The codeset represented by the +implementation-defined name can be any codeset that is supported by +the implementation. +.LP +When conflicts occur between the \fIcharmap\fP specification of <\fIcode_set_name\fP>, +<\fImb_cur_max\fP>, or +<\fImb_cur_min\fP> and the implementation-defined interpretation of +these respective items for the codeset represented by +the \fB-u\fP option-argument \fIcode_set_name\fP, the result is unspecified. +.LP +When conflicts occur between the \fIcharmap\fP encoding values specified +for symbolic names of characters of the portable +character set and the implementation-defined assignment of character +encoding values, the result is unspecified. +.LP +If a non-printable character in the \fIcharmap\fP has a width specified +that is not \fB-1\fP, \fIlocaledef\fP shall generate +a warning. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +No errors occurred and the locales were successfully created. +.TP 7 +\ 1 +Warnings occurred and the locales were successfully created. +.TP 7 +\ 2 +The locale specification exceeded implementation limits or the coded +character set or sets used were not supported by the +implementation, and no locale was created. +.TP 7 +\ 3 +The capability to create new locales is not supported by the implementation. +.TP 7 +>3 +Warnings or errors occurred and no output was created. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If an error is detected, no permanent output shall be created. +.LP +If warnings occur, permanent output shall be created if the \fB-c\fP +option was specified. The following conditions shall cause +warning messages to be issued: +.IP " *" 3 +If a symbolic name not found in the \fIcharmap\fP file is used for +the descriptions of the \fILC_CTYPE\fP or \fILC_COLLATE\fP +categories (for other categories, this shall be an error condition). +.LP +.IP " *" 3 +If the number of operands to the \fBorder\fP keyword exceeds the {COLL_WEIGHTS_MAX} +limit. +.LP +.IP " *" 3 +If optional keywords not supported by the implementation are present +in the source. +.LP +.IP " *" 3 +If a non-printable character has a width specified other than -1. +.LP +.LP +Other implementation-defined conditions may also cause warnings. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fIcharmap\fP definition is optional, and is contained outside +the locale definition. This allows both completely +self-defined source files, and generic sources (applicable to more +than one codeset). To aid portability, all \fIcharmap\fP +definitions must use the same symbolic names for the portable character +set. As explained in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 6.4, Character Set Description File, +it +is implementation-defined whether or not users or applications can +provide additional character set description files. Therefore, +the \fB-f\fP option might be operable only when an implementation-defined +\fIcharmap\fP is named. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The output produced by the \fIlocaledef\fP utility is implementation-defined. +The \fIname\fP operand is used to identify the +specific locale. (As a consequence, although several categories can +be processed in one execution, only categories belonging to the +same locale can be processed.) +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIlocale\fP , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 7.3, Locale Definition +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/logger.1p b/man1p/logger.1p new file mode 100644 index 000000000..ec1f9d064 --- /dev/null +++ b/man1p/logger.1p @@ -0,0 +1,160 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LOGGER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" logger +.SH NAME +logger \- log messages +.SH SYNOPSIS +.LP +\fBlogger\fP \fIstring\fP \fB...\fP +.SH DESCRIPTION +.LP +The \fIlogger\fP utility saves a message, in an unspecified manner +and format, containing the \fIstring\fP operands provided +by the user. The messages are expected to be evaluated later by personnel +performing system administration tasks. +.LP +It is implementation-defined whether messages written in locales other +than the POSIX locale are effective. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIstring\fP +One of the string arguments whose contents are concatenated together, +in the order specified, separated by single +s. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIlogger\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +(This means diagnostics from \fIlogger\fP to the user or application, +not diagnostic messages that the user is sending to the +system administrator.) +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +Unspecified. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +This utility allows logging of information for later use by a system +administrator or programmer in determining why +non-interactive utilities have failed. The locations of the saved +messages, their format, and retention period are all unspecified. +There is no method for a conforming application to read messages, +once written. +.SH EXAMPLES +.LP +A batch application, running non-interactively, tries to read a configuration +file and fails; it may attempt to notify the +system administrator with: +.sp +.RS +.nf + +\fBlogger myname: unable to read file foo. [timestamp] +\fP +.fi +.RE +.SH RATIONALE +.LP +The standard developers believed strongly that some method of alerting +administrators to errors was necessary. The obvious +example is a batch utility, running non-interactively, that is unable +to read its configuration files or that is unable to create +or write its results file. However, the standard developers did not +wish to define the format or delivery mechanisms as they have +historically been (and will probably continue to be) very system-specific, +as well as involving functionality clearly outside the +scope of this volume of IEEE\ Std\ 1003.1-2001. +.LP +The text with \fILC_MESSAGES\fP about diagnostic messages means diagnostics +from \fIlogger\fP to the user or application, not +diagnostic messages that the user is sending to the system administrator. +.LP +Multiple \fIstring\fP arguments are allowed, similar to \fIecho\fP, +for ease-of-use. +.LP +Like the utilities \fImailx\fP and \fIlp\fP, +\fIlogger\fP is admittedly difficult to test. This was not deemed +sufficient justification to exclude these utilities from this +volume of IEEE\ Std\ 1003.1-2001. It is also arguable that they are, +in fact, testable, but that the tests themselves are +not portable. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIlp\fP , \fImailx\fP , \fIwrite\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/logname.1p b/man1p/logname.1p new file mode 100644 index 000000000..8c3b45246 --- /dev/null +++ b/man1p/logname.1p @@ -0,0 +1,129 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LOGNAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" logname +.SH NAME +logname \- return the user's login name +.SH SYNOPSIS +.LP +\fBlogname\fP +.SH DESCRIPTION +.LP +The \fIlogname\fP utility shall write the user's login name to standard +output. The login name shall be the string that would +be returned by the \fIgetlogin\fP() function defined in the System +Interfaces volume of +IEEE\ Std\ 1003.1-2001. Under the conditions where the \fIgetlogin\fP() +function +would fail, the \fIlogname\fP utility shall write a diagnostic message +to standard error and exit with a non-zero exit status. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +None. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIlogname\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fIlogname\fP utility output shall be a single line consisting +of the user's login name: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIlogin name\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fIlogname\fP utility explicitly ignores the \fILOGNAME\fP environment +variable because environment changes could produce +erroneous results. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fBpasswd\fP file is not listed as required because the implementation +may have other means of mapping login names. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIid\fP , \fIwho\fP , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIgetlogin\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/lp.1p b/man1p/lp.1p new file mode 100644 index 000000000..4f8649413 --- /dev/null +++ b/man1p/lp.1p @@ -0,0 +1,388 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" lp +.SH NAME +lp \- send files to a printer +.SH SYNOPSIS +.LP +\fBlp\fP \fB[\fP\fB-c\fP\fB][\fP\fB-d\fP \fIdest\fP\fB][\fP\fB-n\fP +\fIcopies\fP\fB][\fP\fB-msw\fP\fB][\fP\fB-o\fP \fIoption\fP\fB]\fP\fB...\fP +\fB[\fP\fB-t\fP +\fItitle\fP\fB][\fP\fIfile\fP\fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIlp\fP utility shall copy the input files to an output destination +in an unspecified manner. The default output +destination should be to a hardcopy device, such as a printer or microfilm +recorder, that produces non-volatile, human-readable +documents. If such a device is not available to the application, or +if the system provides no such device, the \fIlp\fP utility +shall exit with a non-zero exit status. +.LP +The actual writing to the output device may occur some time after +the \fIlp\fP utility successfully exits. During the portion +of the writing that corresponds to each input file, the implementation +shall guarantee exclusive access to the device. +.LP +The \fIlp\fP utility shall associate a unique \fIrequest ID\fP with +each request. +.LP +Normally, a banner page is produced to separate and identify each +print job. This page may be suppressed by +implementation-defined conditions, such as an operator command or +one of the \fB-o\fP \fIoption\fP values. +.SH OPTIONS +.LP +The \fIlp\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-c\fP +Exit only after further access to any of the input files is no longer +required. The application can then safely delete or +modify the files without affecting the output operation. Normally, +files are not copied, but are linked whenever possible. If the +\fB-c\fP option is not given, then the user should be careful not +to remove any of the files before the request has been printed +in its entirety. It should also be noted that in the absence of the +\fB-c\fP option, any changes made to the named files after the +request is made but before it is printed may be reflected in the printed +output. On some implementations, \fB-c\fP may be on by +default. +.TP 7 +\fB-d\ \fP \fIdest\fP +Specify a string that names the destination ( \fIdest\fP). If \fIdest\fP +is a printer, the request shall be printed only on +that specific printer. If \fIdest\fP is a class of printers, the request +shall be printed on the first available printer that is a +member of the class. Under certain conditions (printer unavailability, +file space limitation, and so on), requests for specific +destinations need not be accepted. Destination names vary between +systems. +.LP +If \fB-d\fP is not specified, and neither the \fILPDEST\fP nor \fIPRINTER\fP +environment variable is set, an unspecified +destination is used. The \fB-d\fP \fIdest\fP option shall take precedence +over \fILPDEST ,\fP which in turn shall take +precedence over \fIPRINTER .\fP Results are undefined when \fIdest\fP +contains a value that is not a valid destination name. +.TP 7 +\fB-m\fP +Send mail (see \fImailx\fP ) after the files have been printed. By +default, no mail is sent upon +normal completion of the print request. +.TP 7 +\fB-n\ \fP \fIcopies\fP +Write \fIcopies\fP number of copies of the files, where \fIcopies\fP +is a positive decimal integer. The methods for producing +multiple copies and for arranging the multiple copies when multiple +\fIfile\fP operands are used are unspecified, except that each +file shall be output as an integral whole, not interleaved with portions +of other files. +.TP 7 +\fB-o\ \fP \fIoption\fP +Specify printer-dependent or class-dependent \fIoption\fPs. Several +such \fIoption\fPs may be collected by specifying the +\fB-o\fP option more than once. +.TP 7 +\fB-s\fP +Suppress messages from \fIlp\fP. +.TP 7 +\fB-t\ \fP \fItitle\fP +Write \fItitle\fP on the banner page of the output. +.TP 7 +\fB-w\fP +Write a message on the user's terminal after the files have been printed. +If the user is not logged in, then mail shall be sent +instead. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a file to be output. If no \fIfile\fP operands are specified, +or if a \fIfile\fP operand is \fB'-'\fP , the +standard input shall be used. If a \fIfile\fP operand is used, but +the \fB-c\fP option is not specified, the process performing +the writing to the output device may have user and group permissions +that differ from that of the process invoking \fIlp\fP. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified, or if a \fIfile\fP operand is \fB'-'\fP . +See the INPUT FILES section. +.SH INPUT FILES +.LP +The input files shall be text files. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIlp\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fILC_TIME\fP +Determine the format and contents of date and time strings displayed +in the \fIlp\fP banner page, if any. +.TP 7 +\fILPDEST\fP +Determine the destination. If the \fILPDEST\fP environment variable +is not set, the \fIPRINTER\fP environment variable shall +be used. The \fB-d\fP \fIdest\fP option takes precedence over \fILPDEST +\&.\fP Results are undefined when \fB-d\fP is not +specified and \fILPDEST\fP contains a value that is not a valid destination +name. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPRINTER\fP +Determine the output device or destination. If the \fILPDEST\fP and +\fIPRINTER\fP environment variables are not set, an +unspecified output device is used. The \fB-d\fP \fIdest\fP option +and the \fILPDEST\fP environment variable shall take +precedence over \fIPRINTER .\fP Results are undefined when \fB-d\fP +is not specified, \fILPDEST\fP is unset, and \fIPRINTER\fP +contains a value that is not a valid device or destination name. +.TP 7 +\fITZ\fP +Determine the timezone used to calculate date and time strings displayed +in the \fIlp\fP banner page, if any. If \fITZ\fP is +unset or null, an unspecified default timezone shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fIlp\fP utility shall write a \fIrequest ID\fP to the standard +output, unless \fB-s\fP is specified. The format of the +message is unspecified. The request ID can be used on systems supporting +the historical \fIcancel\fP and \fIlpstat\fP +utilities. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All input files were processed successfully. +.TP 7 +>0 +No output device was available, or an error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fIpr\fP and \fIfold\fP utilities can be used to +achieve reasonable formatting for the implementation's default page +size. +.LP +A conforming application can use one of the \fIfile\fP operands only +with the \fB-c\fP option or if the file is publicly +readable and guaranteed to be available at the time of printing. This +is because IEEE\ Std\ 1003.1-2001 gives the +implementation the freedom to queue up the request for printing at +some later time by a different process that might not be able to +access the file. +.SH EXAMPLES +.IP " 1." 4 +To print file \fIfile\fP: +.sp +.RS +.nf + +\fBlp -c\fP \fIfile\fP +.fi +.RE +.LP +.IP " 2." 4 +To print multiple files with headers: +.sp +.RS +.nf + +\fBpr\fP \fIfile1 file2\fP \fB| lp +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +The \fIlp\fP utility was designed to be a basic version of a utility +that is already available in many historical +implementations. The standard developers considered that it should +be implementable simply as: +.sp +.RS +.nf + +\fBcat "$@" > /dev/lp +\fP +.fi +.RE +.LP +after appropriate processing of options, if that is how the implementation +chose to do it and if exclusive access could be +granted (so that two users did not write to the device simultaneously). +Although in the future the standard developers may add +other options to this utility, it should always be able to execute +with no options or operands and send the standard input to an +unspecified output device. +.LP +This volume of IEEE\ Std\ 1003.1-2001 makes no representations concerning +the format of the printed output, except that +it must be "human-readable" and "non-volatile". Thus, writing by default +to a disk or tape drive or a display terminal would +not qualify. (Such destinations are not prohibited when \fB-d\fP \fIdest\fP, +\fILPDEST ,\fP or \fIPRINTER\fP are used, +however.) +.LP +This volume of IEEE\ Std\ 1003.1-2001 is worded such that a "print +job" consisting of multiple input files, possibly +in multiple copies, is guaranteed to print so that any one file is +not intermixed with another, but there is no statement that all +the files or copies have to print out together. +.LP +The \fB-c\fP option may imply a spooling operation, but this is not +required. The utility can be implemented to wait until the +printer is ready and then wait until it is finished. Because of that, +there is no attempt to define a queuing mechanism +(priorities, classes of output, and so on). +.LP +On some historical systems, the request ID reported on the STDOUT +can be used to later cancel or find the status of a request +using utilities not defined in this volume of IEEE\ Std\ 1003.1-2001. +.LP +Although the historical System V \fIlp\fP and BSD \fIlpr\fP utilities +have provided similar functionality, they used different +names for the environment variable specifying the destination printer. +Since the name of the utility here is \fIlp\fP, +\fILPDEST\fP (used by the System V \fIlp\fP utility) was given precedence +over \fIPRINTER\fP (used by the BSD \fIlpr\fP +utility). Since environments of users frequently contain one or the +other environment variable, the \fIlp\fP utility is required +to recognize both. If this was not done, many applications would send +output to unexpected output devices when users moved from +system to system. +.LP +Some have commented that \fIlp\fP has far too little functionality +to make it worthwhile. Requests have proposed additional +options or operands or both that added functionality. The requests +included: +.IP " *" 3 +Wording \fIrequiring\fP the output to be "hardcopy" +.LP +.IP " *" 3 +A requirement for multiple printers +.LP +.IP " *" 3 +Options for supporting various page-description languages +.LP +.LP +Given that a compliant system is not required to even have a printer, +placing further restrictions upon the behavior of the +printer is not useful. Since hardcopy format is so application-dependent, +it is difficult, if not impossible, to select a +reasonable subset of functionality that should be required on all +compliant systems. +.LP +The term \fIunspecified\fP is used in this section in lieu of \fIimplementation-defined\fP +as most known implementations would +not be able to make definitive statements in their conformance documents; +the existence and usage of printers is very dependent on +how the system administrator configures each individual system. +.LP +Since the default destination, device type, queuing mechanisms, and +acceptable forms of input are all unspecified, usage +guidelines for what a conforming application can do are as follows: +.IP " *" 3 +Use the command in a pipeline, or with \fB-c\fP, so that there are +no permission problems and the files can be safely deleted +or modified. +.LP +.IP " *" 3 +Limit output to text files of reasonable line lengths and printable +characters and include no device-specific formatting +information, such as a page description language. The meaning of "reasonable" +in this context can only be answered as a +quality-of-implementation issue, but it should be apparent from historical +usage patterns in the industry and the locale. The \fIpr\fP and \fIfold\fP +utilities can be used to achieve +reasonable formatting for the default page size of the implementation. +.LP +.LP +Alternatively, the application can arrange its installation in such +a way that it requires the system administrator or operator +to provide the appropriate information on \fIlp\fP options and environment +variable values. +.LP +At a minimum, having this utility in this volume of IEEE\ Std\ 1003.1-2001 +tells the industry that conforming +applications require a means to print output and provides at least +a command name and \fILPDEST\fP routing mechanism that can be +used for discussions between vendors, application writers, and users. +The use of "should" in the DESCRIPTION of \fIlp\fP clearly +shows the intent of the standard developers, even if they cannot mandate +that all systems (such as laptops) have printers. +.LP +This volume of IEEE\ Std\ 1003.1-2001 does not specify what the ownership +of the process performing the writing to the +output device may be. If \fB-c\fP is not used, it is unspecified whether +the process performing the writing to the output device +has permission to read \fIfile\fP if there are any restrictions in +place on who may read \fIfile\fP until after it is printed. +Also, if \fB-c\fP is not used, the results of deleting \fIfile\fP +before it is printed are unspecified. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImailx\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/ls.1p b/man1p/ls.1p new file mode 100644 index 000000000..f30dbe421 --- /dev/null +++ b/man1p/ls.1p @@ -0,0 +1,737 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ls +.SH NAME +ls \- list directory contents +.SH SYNOPSIS +.LP +\fBls\fP \fB[\fP\fB-CFRacdilqrtu1\fP\fB][\fP\fB-H | -L\fP +\fB][\fP\fB-fgmnopsx\fP\fB][\fP\fIfile\fP\fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +For each operand that names a file of a type other than directory +or symbolic link to a directory, \fIls\fP shall write the +name of the file as well as any requested, associated information. +For each operand that names a file of type directory, \fIls\fP +shall write the names of files contained within the directory as well +as any requested, associated information. If one of the +\fB-d\fP, \fB-F\fP, or \fB-l\fP options are specified, and one of +the \fB-H\fP or \fB-L\fP options are not specified, for each +operand that names a file of type symbolic link to a directory, \fIls\fP +shall write the name of the file as well as any +requested, associated information. If none of the \fB-d\fP, \fB-F\fP, +or \fB-l\fP options are specified, or the \fB-H\fP or +\fB-L\fP options are specified, for each operand that names a file +of type symbolic link to a directory, \fIls\fP shall write the +names of files contained within the directory as well as any requested, +associated information. +.LP +If no operands are specified, \fIls\fP shall write the contents of +the current directory. If more than one operand is +specified, \fIls\fP shall write non-directory operands first; it shall +sort directory and non-directory operands separately +according to the collating sequence in the current locale. +.LP +The \fIls\fP utility shall detect infinite loops; that is, entering +a previously visited directory that is an ancestor of the +last file encountered. When it detects an infinite loop, \fIls\fP +shall write a diagnostic message to standard error and shall +either recover its position in the hierarchy or terminate. +.SH OPTIONS +.LP +The \fIls\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-C\fP +Write multi-text-column output with entries sorted down the columns, +according to the collating sequence. The number of text +columns and the column separator characters are unspecified, but should +be adapted to the nature of the output device. +.TP 7 +\fB-F\fP +Do not follow symbolic links named as operands unless the \fB-H\fP +or \fB-L\fP options are specified. Write a slash ( +\fB'/'\fP ) immediately after each pathname that is a directory, an +asterisk ( \fB'*'\fP ) after each that is executable, a +vertical bar ( \fB'|'\fP ) after each that is a FIFO, and an at sign +( \fB'@'\fP ) after each that is a symbolic link. For +other file types, other symbols may be written. +.TP 7 +\fB-H\fP +If a symbolic link referencing a file of type directory is specified +on the command line, \fIls\fP shall evaluate the file +information and file type to be those of the file referenced by the +link, and not the link itself; however, \fIls\fP shall write +the name of the link itself and not the file referenced by the link. +.TP 7 +\fB-L\fP +Evaluate the file information and file type for all symbolic links +(whether named on the command line or encountered in a file +hierarchy) to be those of the file referenced by the link, and not +the link itself; however, \fIls\fP shall write the name of the +link itself and not the file referenced by the link. When \fB-L\fP +is used with \fB-l\fP, write the contents of symbolic links in +the long format (see the STDOUT section). +.TP 7 +\fB-R\fP +Recursively list subdirectories encountered. +.TP 7 +\fB-a\fP +Write out all directory entries, including those whose names begin +with a period ( \fB'.'\fP ). Entries beginning with a +period shall not be written out unless explicitly referenced, the +\fB-a\fP option is supplied, or an implementation-defined +condition shall cause them to be written. +.TP 7 +\fB-c\fP +Use time of last modification of the file status information (see +\fI\fP in the System Interfaces volume of IEEE\ Std\ 1003.1-2001) +instead of last modification of the file itself for sorting ( \fB-t\fP) +or writing ( \fB-l\fP). +.TP 7 +\fB-d\fP +Do not follow symbolic links named as operands unless the \fB-H\fP +or \fB-L\fP options are specified. Do not treat +directories differently than other types of files. The use of \fB-d\fP +with \fB-R\fP produces unspecified results. +.TP 7 +\fB-f\fP +Force each argument to be interpreted as a directory and list the +name found in each slot. This option shall turn off \fB-l\fP, +\fB-t\fP, \fB-s\fP, and \fB-r\fP, and shall turn on \fB-a\fP; the +order is the order in which entries appear in the directory. +.TP 7 +\fB-g\fP +The same as \fB-l\fP, except that the owner shall not be written. +.TP 7 +\fB-i\fP +For each file, write the file's file serial number (see \fIstat\fP() +in the System +Interfaces volume of IEEE\ Std\ 1003.1-2001). +.TP 7 +\fB-l\fP +(The letter ell.) Do not follow symbolic links named as operands unless +the \fB-H\fP or \fB-L\fP options are specified. Write +out in long format (see the STDOUT section). When \fB-l\fP (ell) is +specified, -1 (one) shall be assumed. +.TP 7 +\fB-m\fP +Stream output format; list files across the page, separated by commas. +.TP 7 +\fB-n\fP +The same as \fB-l\fP, except that the owner's UID and GID numbers +shall be written, rather than the associated character strings. +.TP 7 +\fB-o\fP +The same as \fB-l\fP, except that the group shall not be written. +.TP 7 +\fB-p\fP +Write a slash ( \fB'/'\fP ) after each filename if that file is a +directory. +.TP 7 +\fB-q\fP +Force each instance of non-printable filename characters and s +to be written as the question-mark ( \fB'?'\fP ) +character. Implementations may provide this option by default if the +output is to a terminal device. +.TP 7 +\fB-r\fP +Reverse the order of the sort to get reverse collating sequence or +oldest first. +.TP 7 +\fB-s\fP +Indicate the total number of file system blocks consumed by each file +displayed. The block size is implementation-defined. +.TP 7 +\fB-t\fP +Sort with the primary key being time modified (most recently modified +first) and the secondary key being filename in the +collating sequence. +.TP 7 +\fB-u\fP +Use time of last access (see \fI\fP) instead of last modification +of the file for sorting ( \fB-t\fP) or writing ( \fB-l\fP). +.TP 7 +\fB-x\fP +The same as \fB-C\fP, except that the multi-text-column output is +produced with entries sorted across, rather than down, the +columns. +.TP 7 +\fB-1\fP +(The numeric digit one.) Force output to be one entry per line. +.sp +.LP +Specifying more than one of the options in the following mutually-exclusive +pairs shall not be considered an error: \fB-C\fP +and \fB-l\fP (ell), \fB-m\fP and \fB-l\fP (ell), \fB-x\fP and \fB-l\fP +(ell), \fB-C\fP and \fB-1\fP (one), \fB-H\fP and \fB-L\fP, \fB-c\fP +and \fB-u\fP. The last option +specified in each pair shall determine the output format. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a file to be written. If the file specified is not found, +a diagnostic message shall be output on standard +error. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIls\fP: +.TP 7 +\fICOLUMNS\fP +Determine the user's preferred column position width for writing multiple +text-column output. If this variable contains a +string representing a decimal integer, the \fIls\fP utility shall +calculate how many pathname text columns to write (see +\fB-C\fP) based on the width provided. If \fICOLUMNS\fP is not set +or invalid, an implementation-defined number of column +positions shall be assumed, based on the implementation's knowledge +of the output device. The column width chosen to write the +names of files in any given directory shall be constant. Filenames +shall not be truncated to fit into the multiple text-column +output. +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for character collation information in determining +the pathname collation sequence. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments) and which characters +are defined as printable (character class \fBprint\fP). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILC_TIME\fP +Determine the format and contents for date and time strings written +by \fIls\fP. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITZ\fP +Determine the timezone for date and time strings written by \fIls\fP. +If \fITZ\fP is unset or null, an unspecified default +timezone shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The default format shall be to list one entry per line to standard +output; the exceptions are to terminals or when one of the +\fB-C\fP, \fB-m\fP, or \fB-x\fP options is specified. If the +output is to a terminal, the format is implementation-defined. +.LP +When \fB-m\fP is specified, the format used shall be: +.sp +.RS +.nf + +\fB"%s, %s, ...\\n", <\fP\fIfilename1\fP\fB>, <\fP\fIfilename2\fP\fB> +\fP +.fi +.RE +.LP +where the largest number of filenames shall be written without exceeding +the length of the line. +.LP +If the \fB-i\fP option is specified, the file's file serial number +(see \fI\fP) shall be written in the following format +before any other output for +the corresponding entry: +.sp +.RS +.nf + +\fB%u ", <\fP\fIfile serial number\fP\fB> +\fP +.fi +.RE +.LP +If the \fB-l\fP option is specified without \fB-L\fP, the following +information shall be written: +.sp +.RS +.nf + +\fB"%s %u %s %s %u %s %s\\n", <\fP\fIfile mode\fP\fB>, <\fP\fInumber of links\fP\fB>, + <\fP\fIowner name\fP\fB>, <\fP\fIgroup name\fP\fB>, <\fP\fInumber of bytes in the file\fP\fB>, + <\fP\fIdate and time\fP\fB>, <\fP\fIpathname\fP\fB> +\fP +.fi +.RE +.LP +If the file is a symbolic link, this information shall be about the +link itself and the <\fIpathname\fP> field shall be +of the form: +.sp +.RS +.nf + +\fB"%s -> %s", <\fP\fIpathname of link\fP\fB>, <\fP\fIcontents of link\fP\fB> +\fP +.fi +.RE +.LP +If both \fB-l\fP and \fB-L\fP are specified, the following information +shall be written: +.sp +.RS +.nf + +\fB"%s %u %s %s %u %s %s\\n", <\fP\fIfile mode\fP\fB>, <\fP\fInumber of links\fP\fB>, + <\fP\fIowner name\fP\fB>, <\fP\fIgroup name\fP\fB>, <\fP\fInumber of bytes in the file\fP\fB>, + <\fP\fIdate and time\fP\fB>, <\fP\fIpathname of link\fP\fB> +\fP +.fi +.RE +.LP +where all fields except <\fIpathname of link\fP> shall be for the +file resolved from the symbolic link. +.LP +The \fB-g\fP, \fB-n\fP, and \fB-o\fP options use the same format as +\fB-l\fP, but with omitted items and their associated +s. See the OPTIONS section. +.LP +In both the preceding \fB-l\fP forms, if <\fIowner name\fP> or <\fIgroup +name\fP> cannot be determined, \ or if +\fB-n\fP is given, they shall be replaced with their associated +numeric values using the format \fB%u\fP . +.LP +The <\fIdate\ and\ time\fP> field shall contain the appropriate date +and timestamp of when the file was last +modified. In the POSIX locale, the field shall be the equivalent of +the output of the following \fIdate\fP command: +.sp +.RS +.nf + +\fBdate "+%b %e %H:%M" +\fP +.fi +.RE +.LP +if the file has been modified in the last six months, or: +.sp +.RS +.nf + +\fBdate "+%b %e %Y" +\fP +.fi +.RE +.LP +(where two s are used between \fB%e\fP and \fB%Y\fP ) if the +file has not been modified in the last six +months or if the modification date is in the future, except that, +in both cases, the final produced by \fIdate\fP shall not +be included and the output shall be as if the \fIdate\fP command were +executed at the time of the last modification date of the file rather +than +the current time. When the \fILC_TIME\fP locale category is not set +to the POSIX locale, a different format and order of +presentation of this field may be used. +.LP +If the file is a character special or block special file, the size +of the file may be replaced with implementation-defined +information associated with the device in question. +.LP +If the pathname was specified as a \fIfile\fP operand, it shall be +written as specified. +.LP +The file mode written under the \fB-l\fP, \fB-g\fP, \fB-n\fP, and +\fB-o\fP options shall consist of the following format: +.sp +.RS +.nf + +\fB"%c%s%s%s%c", <\fP\fIentry type\fP\fB>, <\fP\fIowner permissions\fP\fB>, + <\fP\fIgroup permissions\fP\fB>, <\fP\fIother permissions\fP\fB>, + <\fP\fIoptional alternate access method flag\fP\fB> +\fP +.fi +.RE +.LP +The <\fIoptional\ alternate\ access\ method\ flag\fP> shall be a single + if there is no +alternate or additional access control method associated with the +file; otherwise, a printable character shall be used. +.LP +The <\fIentry\ type\fP> character shall describe the type of file, +as follows: +.TP 7 +\fBd\fP +Directory. +.TP 7 +\fBb\fP +Block special file. +.TP 7 +\fBc\fP +Character special file. +.TP 7 +\fBl\fP\ (ell) +Symbolic link. +.TP 7 +\fBp\fP +FIFO. +.TP 7 +\fB-\fP +Regular file. +.sp +.LP +Implementations may add other characters to this list to represent +other implementation-defined file types. +.LP +The next three fields shall be three characters each: +.TP 7 +<\fIowner permissions\fP> +.sp +Permissions for the file owner class (see the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 4.4, File Access Permissions). +.TP 7 +<\fIgroup permissions\fP> +.sp +Permissions for the file group class. +.TP 7 +<\fIother permissions\fP> +.sp +Permissions for the file other class. +.sp +.LP +Each field shall have three character positions: +.IP " 1." 4 +If \fB'r'\fP , the file is readable; if \fB'-'\fP , the file is not +readable. +.LP +.IP " 2." 4 +If \fB'w'\fP , the file is writable; if \fB'-'\fP , the file is not +writable. +.LP +.IP " 3." 4 +The first of the following that applies: +.TP 7 +\fBS\fP +.RS +If in <\fIowner\ permissions\fP>, the file is not executable and set-user-ID +mode is set. If in +<\fIgroup\ permissions\fP>, the file is not executable and set-group-ID +mode is set. +.RE +.TP 7 +\fBs\fP +.RS +If in <\fIowner\ permissions\fP>, the file is executable and set-user-ID +mode is set. If in +<\fIgroup\ permissions\fP>, the file is executable and set-group-ID +mode is set. +.RE +.TP 7 +\fBT\fP +.RS +If in <\fIother\ permissions\fP> and the file is a directory, search +permission is not granted to others, and the +restricted deletion flag is set. +.RE +.TP 7 +\fBt\fP +.RS +If in <\fIother\ permissions\fP> and the file is a directory, search +permission is granted to others, and the restricted +deletion flag is set. +.RE +.TP 7 +\fBx\fP +.RS +The file is executable or the directory is searchable. +.RE +.TP 7 +\fB-\fP +.RS +None of the attributes of \fB'S'\fP , \fB's'\fP , \fB'T'\fP , \fB't'\fP +, or \fB'x'\fP applies. +.RE +.sp +.LP +Implementations may add other characters to this list for the third +character position. Such additions shall, however, be +written in lowercase if the file is executable or searchable, and +in uppercase if it is not. +.LP +.LP +If any of the \fB-l\fP, \fB-g\fP, \fB-n\fP, \fB-o\fP, or \fB-s\fP +options is specified, each list of files within the directory shall +be preceded by a status line indicating the number +of file system blocks occupied by files in the directory in 512-byte +units, rounded up to the next integral number of units, if +necessary. In the POSIX locale, the format shall be: +.sp +.RS +.nf + +\fB"total %u\\n", <\fP\fInumber of units in the directory\fP\fB> +\fP +.fi +.RE +.LP +If more than one directory, or a combination of non-directory files +and directories are written, either as a result of +specifying multiple operands, or the \fB-R\fP option, each list of +files within a directory shall be preceded by: +.sp +.RS +.nf + +\fB"\\n%s:\\n", <\fP\fIdirectory name\fP\fB> +\fP +.fi +.RE +.LP +If this string is the first thing to be written, the first +shall not be written. This output shall precede the +number of units in the directory. +.LP +If the \fB-s\fP option is given, each file shall be written with the +number of blocks used by the file. Along with \fB-C\fP, +\fB-1\fP, \fB-m\fP, or \fB-x\fP, the number and a shall precede +the filename; with \fB-g\fP, \fB-l\fP, +\fB-n\fP, or \fB-o\fP, they shall precede each line describing a file. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Many implementations use the equal sign ( \fB'='\fP ) to denote sockets +bound to the file system for the \fB-F\fP option. +Similarly, many historical implementations use the \fB's'\fP character +to denote sockets as the entry type characters for the +\fB-l\fP option. +.LP +It is difficult for an application to use every part of the file modes +field of \fIls\fP \fB-l\fP in a portable manner. +Certain file types and executable bits are not guaranteed to be exactly +as shown, as implementations may have extensions. +Applications can use this field to pass directly to a user printout +or prompt, but actions based on its contents should generally +be deferred, instead, to the \fItest\fP utility. +.LP +The output of \fIls\fP (with the \fB-l\fP and related options) contains +information that logically could be used by utilities +such as \fIchmod\fP and \fItouch\fP to restore files +to a known state. However, this information is presented in a format +that cannot be used directly by those utilities or be easily +translated into a format that can be used. A character has been added +to the end of the permissions string so that applications at +least have an indication that they may be working in an area they +do not understand instead of assuming that they can translate the +permissions string into something that can be used. Future issues +or related documents may define one or more specific characters +to be used based on different standard additional or alternative access +control mechanisms. +.LP +As with many of the utilities that deal with filenames, the output +of \fIls\fP for multiple files or in one of the long listing +formats must be used carefully on systems where filenames can contain +embedded white space. Systems and system administrators +should institute policies and user training to limit the use of such +filenames. +.LP +The number of disk blocks occupied by the file that it reports varies +depending on underlying file system type, block size units +reported, and the method of calculating the number of blocks. On some +file system types, the number is the actual number of blocks +occupied by the file (counting indirect blocks and ignoring holes +in the file); on others it is calculated based on the file size +(usually making an allowance for indirect blocks, but ignoring holes). +.SH EXAMPLES +.LP +An example of a small directory tree being fully listed with \fIls\fP +\fB-laRF\ a\fP in the POSIX locale: +.sp +.RS +.nf + +\fBtotal 11 +drwxr-xr-x 3 hlj prog 64 Jul 4 12:07 ./ +drwxrwxrwx 4 hlj prog 3264 Jul 4 12:09 ../ +drwxr-xr-x 2 hlj prog 48 Jul 4 12:07 b/ +-rwxr--r-- 1 hlj prog 572 Jul 4 12:07 foo* +.sp + +a/b: +total 4 +drwxr-xr-x 2 hlj prog 48 Jul 4 12:07 ./ +drwxr-xr-x 3 hlj prog 64 Jul 4 12:07 ../ +-rw-r--r-- 1 hlj prog 700 Jul 4 12:07 bar +\fP +.fi +.RE +.SH RATIONALE +.LP +Some historical implementations of the \fIls\fP utility show all entries +in a directory except dot and dot-dot when a superuser +invokes \fIls\fP without specifying the \fB-a\fP option. When "normal" +users invoke \fIls\fP without specifying \fB-a\fP, +they should not see information about any files with names beginning +with a period unless they were named as \fIfile\fP +operands. +.LP +Implementations are expected to traverse arbitrary depths when processing +the \fB-R\fP option. The only limitation on depth +should be based on running out of physical storage for keeping track +of untraversed directories. +.LP +The \fB-1\fP (one) option was historically found in BSD and BSD-derived +implementations only. It is required in this volume of +IEEE\ Std\ 1003.1-2001 so that conforming applications might ensure +that output is one entry per line, even if the output +is to a terminal. +.LP +Generally, this volume of IEEE\ Std\ 1003.1-2001 is silent about what +happens when options are given multiple times. In +the cases of \fB-C\fP, \fB-l\fP, and \fB-1\fP, however, it does specify +the results of these overlapping options. Since +\fIls\fP is one of the most aliased commands, it is important that +the implementation perform intuitively. For example, if the +alias were: +.sp +.RS +.nf + +\fBalias ls="ls -C" +\fP +.fi +.RE +.LP +and the user typed \fIls\fP \fB-1\fP, single-text-column output should +result, not an error. +.LP +The BSD \fIls\fP provides a \fB-A\fP option (like \fB-a\fP, but dot +and dot-dot are not written out). The small difference +from \fB-a\fP did not seem important enough to require both. +.LP +Implementations may make \fB-q\fP the default for terminals to prevent +trojan horse attacks on terminals with special escape +sequences. This is not required because: +.IP " *" 3 +Some control characters may be useful on some terminals; for example, +a system might write them as \fB"\\001"\fP or +\fB"^A"\fP . +.LP +.IP " *" 3 +Special behavior for terminals is not relevant to applications portability. +.LP +.LP +An early proposal specified that the optional alternate access method +flag had to be \fB'+'\fP if there was an alternate +access method used on the file or if there was not. This was +changed to be if there is not and a single +printable character if there is. This was done for three reasons: +.IP " 1." 4 +There are historical implementations using characters other than \fB'+'\fP +\&. +.LP +.IP " 2." 4 +There are implementations that vary this character used in that position +to distinguish between various alternate access methods +in use. +.LP +.IP " 3." 4 +The standard developers did not want to preclude future specifications +that might need a way to specify more than one alternate +access method. +.LP +.LP +Nonetheless, implementations providing a single alternate access method +are encouraged to use \fB'+'\fP . +.LP +In an early proposal, the units used to specify the number of blocks +occupied by files in a directory in an \fIls\fP \fB-l\fP +listing were implementation-defined. This was because BSD systems +have historically used 1024-byte units and System V systems have +historically used 512-byte units. It was pointed out by BSD developers +that their system has used 512-byte units in some places and +1024-byte units in other places. (System V has consistently used 512.) +Therefore, this volume of IEEE\ Std\ 1003.1-2001 +usually specifies 512. Future releases of BSD are expected to consistently +provide 512 bytes as a default with a way of specifying +1024-byte units where appropriate. +.LP +The <\fIdate\ and\ time\fP> field in the \fB-l\fP format is specified +only for the POSIX locale. As noted, the +format can be different in other locales. No mechanism for defining +this is present in this volume of +IEEE\ Std\ 1003.1-2001, as the appropriate vehicle is a messaging +system; that is, the format should be specified as a +"message". +.SH FUTURE DIRECTIONS +.LP +The \fB-s\fP uses implementation-defined units and cannot be used +portably; it may be withdrawn in a future version. +.SH SEE ALSO +.LP +\fIchmod\fP() , \fIfind\fP , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIstat\fP(), the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/m4.1p b/man1p/m4.1p new file mode 100644 index 000000000..56c3b5882 --- /dev/null +++ b/man1p/m4.1p @@ -0,0 +1,556 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "M4" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" m4 +.SH NAME +m4 \- macro processor (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBm4\fP \fB[\fP\fB-s\fP\fB][\fP\fB-D\fP +\fIname\fP\fB[\fP\fB=\fP\fIval\fP\fB]]\fP\fB...\fP\fB[\fP\fB-U\fP +\fIname\fP\fB]\fP\fB...\fP \fIfile\fP\fB... +\fP +.SH DESCRIPTION +.LP +The \fIm4\fP utility is a macro processor that shall read one or more +text files, process them according to their included +macro statements, and write the results to standard output. +.SH OPTIONS +.LP +The \fIm4\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that the order of the \fB-D\fP and +\fB-U\fP options shall be significant. +.LP +The following options shall be supported: +.TP 7 +\fB-s\fP +Enable line synchronization output for the \fIc99\fP preprocessor +phase (that is, +\fB#line\fP directives). +.TP 7 +\fB-D\ \fP \fIname\fP\fB[\fP=\fIval\fP\fB]\fP +.sp +Define \fIname\fP to \fIval\fP or to null if = \fIval\fP is omitted. +.TP 7 +\fB-U\ \fP \fIname\fP +Undefine \fIname\fP. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a text file to be processed. If no \fIfile\fP is given, +or if it is \fB'-'\fP , the standard input shall be +read. +.sp +.SH STDIN +.LP +The standard input shall be a text file that is used if no \fIfile\fP +operand is given, or if it is \fB'-'\fP . +.SH INPUT FILES +.LP +The input file named by the \fIfile\fP operand shall be a text file. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIm4\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall be the same as the input files, after being +processed for macro expansion. +.SH STDERR +.LP +The standard error shall be used to display strings with the \fBerrprint\fP +macro, macro tracing enabled by the \fBtraceon\fP +macro, the defined text for macros written by the \fBdumpdef\fP macro, +or for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +The \fIm4\fP utility shall compare each token from the input against +the set of built-in and user-defined macros. If the token +matches the name of a macro, then the token shall be replaced by the +macro's defining text, if any, and rescanned for matching +macro names. Once no portion of the token matches the name of a macro, +it shall be written to standard output. Macros may have +arguments, in which case the arguments shall be substituted into the +defining text before it is rescanned. +.LP +Macro calls have the form: +.sp +.RS +.nf + +\fIname\fP\fB(\fP\fIarg1\fP\fB,\fP \fIarg2\fP\fB, ...,\fP \fIargn\fP\fB) +\fP +.fi +.RE +.LP +Macro names shall consist of letters, digits, and underscores, where +the first character is not a digit. Tokens not of this form +shall not be treated as macros. +.LP +The application shall ensure that the left parenthesis immediately +follows the name of the macro. If a token matching the name +of a macro is not followed by a left parenthesis, it is handled as +a use of that macro without arguments. +.LP +If a macro name is followed by a left parenthesis, its arguments are +the comma-separated tokens between the left parenthesis and +the matching right parenthesis. Unquoted s and s preceding +each argument shall be ignored. All other +characters, including trailing s and s, are retained. +Commas enclosed between left and right +parenthesis characters do not delimit arguments. +.LP +Arguments are positionally defined and referenced. The string \fB"$1"\fP +in the defining text shall be replaced by the first +argument. Systems shall support at least nine arguments; only the +first nine can be referenced, using the strings \fB"$1"\fP to +\fB"$9"\fP , inclusive. The string \fB"$0"\fP is replaced with the +name of the macro. The string \fB"$#"\fP is replaced by +the number of arguments as a string. The string \fB"$*"\fP is replaced +by a list of all of the arguments, separated by commas. +The string \fB"$@"\fP is replaced by a list of all of the arguments +separated by commas, and each argument is quoted using the +current left and right quoting strings. +.LP +If fewer arguments are supplied than are in the macro definition, +the omitted arguments are taken to be null. It is not an error +if more arguments are supplied than are in the macro definition. +.LP +No special meaning is given to any characters enclosed between matching +left and right quoting strings, but the quoting strings +are themselves discarded. By default, the left quoting string consists +of a grave accent ( \fB'`'\fP ) and the right quoting +string consists of an acute accent ( \fB'"\fP ); see also the \fBchangequote\fP +macro. +.LP +Comments are written but not scanned for matching macro names; by +default, the begin-comment string consists of the number sign +character and the end-comment string consists of a . See +also the \fBchangecom\fP and \fBdnl\fP macros. +.LP +The \fIm4\fP utility shall make available the following built-in macros. +They can be redefined, but once this is done the +original meaning is lost. Their values shall be null unless otherwise +stated. In the descriptions below, the term \fIdefining +text\fP refers to the value of the macro: the second argument to the +\fBdefine\fP macro, among other things. Except for the first +argument to the \fBeval\fP macro, all numeric arguments to built-in +macros shall be interpreted as decimal values. The string +values produced as the defining text of the \fBdecr\fP, \fBdivnum\fP, +\fBincr\fP, \fBindex\fP, \fBlen\fP, and \fBsysval\fP +built-in macros shall be in the form of a decimal-constant as defined +in the C language. +.TP 7 +\fBchangecom\fP +The \fBchangecom\fP macro shall set the begin-comment and end-comment +strings. With no arguments, the comment mechanism shall +be disabled. With a single argument, that argument shall become the +begin-comment string and the shall become the +end-comment string. With two arguments, the first argument shall become +the begin-comment string and the second argument shall +become the end-comment string. Systems shall support comment strings +of at least five characters. +.TP 7 +\fBchangequote\fP +The \fBchangequote\fP macro shall set the begin-quote and end-quote +strings. With no arguments, the quote strings shall be set +to the default values (that is, \fB`'\fP). With a single argument, +that argument shall become the begin-quote string and the + shall become the end-quote string. With two arguments, the +first argument shall become the begin-quote string and +the second argument shall become the end-quote string. Systems shall +support quote strings of at least five characters. +.TP 7 +\fBdecr\fP +The defining text of the \fBdecr\fP macro shall be its first argument +decremented by 1. It shall be an error to specify an +argument containing any non-numeric characters. +.TP 7 +\fBdefine\fP +The second argument shall become the defining text of the macro whose +name is the first argument. +.TP 7 +\fBdefn\fP +The defining text of the \fBdefn\fP macro shall be the quoted definition +(using the current quoting strings) of its +arguments. +.TP 7 +\fBdivert\fP +The \fIm4\fP utility maintains nine temporary buffers, numbered 1 +to 9, inclusive. When the last of the input has been +processed, any output that has been placed in these buffers shall +be written to standard output in buffer-numerical order. The +\fBdivert\fP macro shall divert future output to the buffer specified +by its argument. Specifying no argument or an argument of 0 +shall resume the normal output process. Output diverted to a stream +other than 0 to 9 shall be discarded. It shall be an error to +specify an argument containing any non-numeric characters. +.TP 7 +\fBdivnum\fP +The defining text of the \fBdivnum\fP macro shall be the number of +the current output stream as a string. +.TP 7 +\fBdnl\fP +The \fBdnl\fP macro shall cause \fIm4\fP to discard all input characters +up to and including the next . +.TP 7 +\fBdumpdef\fP +The \fBdumpdef\fP macro shall write the defined text to standard error +for each of the macros specified as arguments, or, if +no arguments are specified, for all macros. +.TP 7 +\fBerrprint\fP +The \fBerrprint\fP macro shall write its arguments to standard error. +.TP 7 +\fBeval\fP +The \fBeval\fP macro shall evaluate its first argument as an arithmetic +expression, using 32-bit signed integer arithmetic. +All of the C-language operators shall be supported, except for: +.sp +.RS +.nf + +\fB[] +-> +++ +-- +(\fP\fItype\fP\fB) +unary * +\fP\fIsizeof\fP\fB, +\&. +?: +unary & +\fP +.fi +.RE +.LP +and all assignment operators. It shall be an error to specify any +of these operators. Precedence and associativity shall be as +in the ISO\ C standard. Systems shall support octal and hexadecimal +numbers as in the ISO\ C standard. The second argument, +if specified, shall set the radix for the result; the default is 10. +The third argument, if specified, sets the minimum number of +digits in the result. It shall be an error to specify the second or +third argument containing any non-numeric characters. +.TP 7 +\fBifdef\fP +If the first argument to the \fBifdef\fP macro is defined, the defining +text shall be the second argument. Otherwise, the +defining text shall be the third argument, if specified, or the null +string, if not. +.TP 7 +\fBifelse\fP +The \fBifelse\fP macro takes three or more arguments. If the first +two arguments compare as equal strings (after macro +expansion of both arguments), the defining text shall be the third +argument. If the first two arguments do not compare as equal +strings and there are three arguments, the defining text shall be +null. If the first two arguments do not compare as equal strings +and there are four or five arguments, the defining text shall be the +fourth argument. If the first two arguments do not compare as +equal strings and there are six or more arguments, the first three +arguments shall be discarded and processing shall restart with +the remaining arguments. +.TP 7 +\fBinclude\fP +The defining text for the \fBinclude\fP macro shall be the contents +of the file named by the first argument. It shall be an +error if the file cannot be read. +.TP 7 +\fBincr\fP +The defining text of the \fBincr\fP macro shall be its first argument +incremented by 1. It shall be an error to specify an +argument containing any non-numeric characters. +.TP 7 +\fBindex\fP +The defining text of the \fBindex\fP macro shall be the first character +position (as a string) in the first argument where a +string matching the second argument begins (zero origin), or -1 if +the second argument does not occur. +.TP 7 +\fBlen\fP +The defining text of the \fBlen\fP macro shall be the length (as a +string) of the first argument. +.TP 7 +\fBm4exit\fP +Exit from the \fIm4\fP utility. If the first argument is specified, +it is the exit code. The default is zero. It shall be an +error to specify an argument containing any non-numeric characters. +.TP 7 +\fBm4wrap\fP +The first argument shall be processed when EOF is reached. If the +\fBm4wrap\fP macro is used multiple times, the arguments +specified shall be processed in the order in which the \fBm4wrap\fP +macros were processed. +.TP 7 +\fBmaketemp\fP +The defining text shall be the first argument, with any trailing \fB'X'\fP +characters replaced with the current process ID +as a string. +.TP 7 +\fBpopdef\fP +The \fBpopdef\fP macro shall delete the current definition of its +arguments, replacing that definition with the previous one. +If there is no previous definition, the macro is undefined. +.TP 7 +\fBpushdef\fP +The \fBpushdef\fP macro shall be equivalent to the \fBdefine\fP macro +with the exception that it shall preserve any current +definition for future retrieval using the \fBpopdef\fP macro. +.TP 7 +\fBshift\fP +The defining text for the \fBshift\fP macro shall be all of its arguments +except for the first one. +.TP 7 +\fBsinclude\fP +The \fBsinclude\fP macro shall be equivalent to the \fBinclude\fP +macro, except that it shall not be an error if the file is +inaccessible. +.TP 7 +\fBsubstr\fP +The defining text for the \fBsubstr\fP macro shall be the substring +of the first argument beginning at the zero-offset +character position specified by the second argument. The third argument, +if specified, shall be the number of characters to select; +if not specified, the characters from the starting point to the end +of the first argument shall become the defining text. It shall +not be an error to specify a starting point beyond the end of the +first argument and the defining text shall be null. It shall be +an error to specify an argument containing any non-numeric characters. +.TP 7 +\fBsyscmd\fP +The \fBsyscmd\fP macro shall interpret its first argument as a shell +command line. The defining text shall be the string +result of that command. No output redirection shall be performed by +the \fIm4\fP utility. The exit status value from the command +can be retrieved using the \fBsysval\fP macro. +.TP 7 +\fBsysval\fP +The defining text of the \fBsysval\fP macro shall be the exit value +of the utility last invoked by the \fBsyscmd\fP macro (as +a string). +.TP 7 +\fBtraceon\fP +The \fBtraceon\fP macro shall enable tracing for the macros specified +as arguments, or, if no arguments are specified, for all +macros. The trace output shall be written to standard error in an +unspecified format. +.TP 7 +\fBtraceoff\fP +The \fBtraceoff\fP macro shall disable tracing for the macros specified +as arguments, or, if no arguments are specified, for +all macros. +.TP 7 +\fBtranslit\fP +The defining text of the \fBtranslit\fP macro shall be the first argument +with every character that occurs in the second +argument replaced with the corresponding character from the third +argument. +.TP 7 +\fBundefine\fP +The \fBundefine\fP macro shall delete all definitions (including those +preserved using the \fBpushdef\fP macro) of the macros +named by its arguments. +.TP 7 +\fBundivert\fP +The \fBundivert\fP macro shall cause immediate output of any text +in temporary buffers named as arguments, or all temporary +buffers if no arguments are specified. Buffers can be undiverted into +other temporary buffers. Undiverting shall discard the +contents of the temporary buffer. It shall be an error to specify +an argument containing any non-numeric characters. +.sp +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred +.sp +.LP +If the \fBm4exit\fP macro is used, the exit value can be specified +by the input file. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fBdefn\fP macro is useful for renaming macros, especially built-ins. +.SH EXAMPLES +.LP +If the file \fBm4src\fP contains the lines: +.sp +.RS +.nf + +\fBThe value of `VER' is "VER". +ifdef(`VER', "VER" is defined to be VER., VER is not defined.) +ifelse(VER, 1, "VER" is `VER'.) +ifelse(VER, 2, "VER" is `VER'., "VER" is not 2.) +end +\fP +.fi +.RE +.LP +then the command +.sp +.RS +.nf + +\fBm4 m4src +\fP +.fi +.RE +.LP +or the command: +.sp +.RS +.nf + +\fBm4 -U VER m4src +\fP +.fi +.RE +.LP +produces the output: +.sp +.RS +.nf + +\fBThe value of VER is "VER". +VER is not defined. +.sp + +VER is not 2. +end +\fP +.fi +.RE +.LP +The command: +.sp +.RS +.nf + +\fBm4 -D VER m4src +\fP +.fi +.RE +.LP +produces the output: +.sp +.RS +.nf + +\fBThe value of VER is "". +VER is defined to be . +.sp + +VER is not 2. +end +\fP +.fi +.RE +.LP +The command: +.sp +.RS +.nf + +\fBm4 -D VER=1 m4src +\fP +.fi +.RE +.LP +produces the output: +.sp +.RS +.nf + +\fBThe value of VER is "1". +VER is defined to be 1. +VER is 1. +VER is not 2. +end +\fP +.fi +.RE +.LP +The command: +.sp +.RS +.nf + +\fBm4 -D VER=2 m4src +.sp + +produces the output: +The value of VER is "2". +VER is defined to be 2. +.sp + +VER is 2. +end +\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIc99\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/mailx.1p b/man1p/mailx.1p new file mode 100644 index 000000000..2a5aacc23 --- /dev/null +++ b/man1p/mailx.1p @@ -0,0 +1,2208 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MAILX" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mailx +.SH NAME +mailx \- process messages +.SH SYNOPSIS +.SS Send Mode +.sp +.RS +.nf + +\fBmailx\fP \fB[\fP\fB-s\fP \fIsubject\fP\fB]\fP \fIaddress\fP\fB... +\fP +.fi +.RE +.SS Receive Mode +.sp +.RS +.nf + +\fBmailx -e +.sp + +.sp + +mailx\fP \fB[\fP\fB-HiNn\fP\fB][\fP\fB-F\fP\fB][\fP\fB-u\fP \fIuser\fP\fB]\fP\fB +.br + +.sp + +mailx -f\fP\fB[\fP\fB-HiNn\fP\fB][\fP\fB-F\fP\fB][\fP\fIfile\fP\fB]\fP\fB +.br + +\fP +.fi +.RE +.SH DESCRIPTION +.LP +The \fImailx\fP utility provides a message sending and receiving facility. +It has two major modes, selected by the options +used: Send Mode and Receive Mode. +.LP +On systems that do not support the User Portability Utilities option, +an application using \fImailx\fP shall have the ability +to send messages in an unspecified manner (Send Mode). Unless the +first character of one or more lines is tilde ( \fB'~'\fP +), all characters in the input message shall appear in the delivered +message, but additional characters may be inserted in the +message before it is retrieved. +.LP +On systems supporting the User Portability Utilities option, mail-receiving +capabilities and other interactive features, Receive +Mode, described below, also shall be enabled. +.SS Send Mode +.LP +Send Mode can be used by applications or users to send messages from +the text in standard input. +.SS Receive Mode +.LP +Receive Mode is more oriented towards interactive users. Mail can +be read and sent in this interactive mode. +.LP +When reading mail, \fImailx\fP provides commands to facilitate saving, +deleting, and responding to messages. When sending mail, +\fImailx\fP allows editing, reviewing, and other modification of the +message as it is entered. +.LP +Incoming mail shall be stored in one or more unspecified locations +for each user, collectively called the system \fImailbox\fP +for that user. When \fImailx\fP is invoked in Receive Mode, the system +mailbox shall be the default place to find new mail. As +messages are read, they shall be marked to be moved to a secondary +file for storage, unless specific action is taken. This +secondary file is called the \fBmbox\fP and is normally located in +the directory referred to by the \fIHOME\fP environment +variable (see \fIMBOX\fP in the ENVIRONMENT VARIABLES section for +a description of this file). Messages shall remain in this file +until explicitly removed. When the \fB-f\fP option is used to read +mail messages from secondary files, messages shall be retained +in those files unless specifically removed. All three of these locations-system +mailbox, \fBmbox\fP, and secondary file-are +referred to in this section as simply "mailboxes", unless more specific +identification is required. +.SH OPTIONS +.LP +The \fImailx\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported. (Only the \fB-s\fP \fIsubject\fP +option shall be required on all systems. The other +options are required only on systems supporting the User Portability +Utilities option.) +.TP 7 +\fB-e\fP +Test for the presence of mail in the system mailbox. The \fImailx\fP +utility shall write nothing and exit with a successful +return code if there is mail to read. +.TP 7 +\fB-f\fP +Read messages from the file named by the \fIfile\fP operand instead +of the system mailbox. (See also \fBfolder\fP.) If no +\fIfile\fP operand is specified, read messages from \fBmbox\fP instead +of the system mailbox. +.TP 7 +\fB-F\fP +Record the message in a file named after the first recipient. The +name is the login-name portion of the address found first on +the \fBTo:\fP line in the mail header. Overrides the \fBrecord\fP +variable, if set (see Internal +Variables in mailx .) +.TP 7 +\fB-H\fP +Write a header summary only. +.TP 7 +\fB-i\fP +Ignore interrupts. (See also \fBignore\fP.) +.TP 7 +\fB-n\fP +Do not initialize from the system default start-up file. See the EXTENDED +DESCRIPTION section. +.TP 7 +\fB-N\fP +Do not write an initial header summary. +.TP 7 +\fB-s\ \fP \fIsubject\fP +Set the \fBSubject\fP header field to \fIsubject\fP. All characters +in the \fIsubject\fP string shall appear in the +delivered message. The results are unspecified if \fIsubject\fP is +longer than {LINE_MAX} - 10 bytes or contains a +. +.TP 7 +\fB-u\ \fP \fIuser\fP +Read the system mailbox of the login name \fIuser\fP. This shall only +be successful if the invoking user has the appropriate +privileges to read the system mailbox of that user. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIaddress\fP +Addressee of message. When \fB-n\fP is specified and no user start-up +files are accessed (see the EXTENDED DESCRIPTION +section), the user or application shall ensure this is an address +to pass to the mail delivery system. Any system or user start-up +files may enable aliases (see \fBalias\fP under Commands in mailx +) that may modify the form of +\fIaddress\fP before it is passed to the mail delivery system. +.TP 7 +\fIfile\fP +A pathname of a file to be read instead of the system mailbox when +\fB-f\fP is specified. The meaning of the \fIfile\fP +option-argument shall be affected by the contents of the \fBfolder\fP +internal variable; see Internal +Variables in mailx . +.sp +.SH STDIN +.LP +When \fImailx\fP is invoked in Send Mode (the first synopsis line), +standard input shall be the message to be delivered to the +specified addresses. When in Receive Mode, user commands shall be +accepted from \fIstdin\fP. If the User Portability Utilities +option is not supported, standard input lines beginning with a tilde +( \fB'~'\fP ) character produce unspecified +results. +.LP +If the User Portability Utilities option is supported, then in both +Send and Receive Modes, standard input lines beginning with +the escape character (usually tilde ( \fB'~'\fP )) shall affect processing +as described in Command Escapes in mailx . +.SH INPUT FILES +.LP +When \fImailx\fP is used as described by this volume of IEEE\ Std\ 1003.1-2001, +the \fIfile\fP option-argument (see +the \fB-f\fP option) and the \fBmbox\fP shall be text files containing +mail messages, formatted as described in the OUTPUT FILES +section. The nature of the system mailbox is unspecified; it need +not be a file. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fImailx\fP: +.TP 7 +\fIDEAD\fP +Determine the pathname of the file in which to save partial messages +in case of interrupts or delivery errors. The default +shall be \fBdead.letter\fP in the directory named by the \fIHOME\fP +variable. The behavior of \fImailx\fP in saving partial +messages is unspecified if the User Portability Utilities option is +not supported and \fIDEAD\fP is not defined with the value +\fB/dev/null\fP. +.TP 7 +\fIEDITOR\fP +Determine the name of a utility to invoke when the \fBedit\fP (see +Commands in mailx ) or +\fB~e\fP (see Command Escapes in mailx ) command is used. The default +editor is unspecified. +\ On XSI-conformant systems it is \fIed\fP. The effects of this variable +are unspecified if the User Portability Utilities option is not +supported. +.TP 7 +\fIHOME\fP +Determine the pathname of the user's home directory. +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and +the handling of case-insensitive address and header-field +comparisons. +.TP 7 +\fILC_TIME\fP +Determine the format and contents of the date and time strings written +by \fImailx\fP. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fILISTER\fP +Determine a string representing the command for writing the contents +of the \fBfolder\fP directory to standard output when the +\fBfolders\fP command is given (see \fBfolders\fP in Commands in mailx +). Any string acceptable as +a \fIcommand_string\fP operand to the \fIsh\fP \fB-c\fP command shall +be valid. If this +variable is null or not set, the output command shall be \fIls\fP. +The effects of this variable +are unspecified if the User Portability Utilities option is not supported. +.TP 7 +\fIMAILRC\fP +Determine the pathname of the start-up file. The default shall be +\fB\&.mailrc\fP in the directory referred to by the +\fIHOME\fP environment variable. The behavior of \fImailx\fP is unspecified +if the User Portability Utilities option is not +supported and \fIMAILRC\fP is not defined with the value \fB/dev/null\fP. +.TP 7 +\fIMBOX\fP +Determine a pathname of the file to save messages from the system +mailbox that have been read. The \fBexit\fP command shall +override this function, as shall saving the message explicitly in +another file. The default shall be \fBmbox\fP in the directory +named by the \fIHOME\fP variable. The effects of this variable are +unspecified if the User Portability Utilities option is not +supported. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPAGER\fP +Determine a string representing an output filtering or pagination +command for writing the output to the terminal. Any string +acceptable as a \fIcommand_string\fP operand to the \fIsh\fP \fB-c\fP +command shall be valid. +When standard output is a terminal device, the message output shall +be piped through the command if the \fImailx\fP internal +variable \fBcrt\fP is set to a value less the number of lines in the +message; see Internal Variables in +mailx . If the \fIPAGER\fP variable is null or not set, the paginator +shall be either \fImore\fP or another paginator utility documented +in the system documentation. The effects of this +variable are unspecified if the User Portability Utilities option +is not supported. +.TP 7 +\fISHELL\fP +Determine the name of a preferred command interpreter. The default +shall be \fIsh\fP. The +effects of this variable are unspecified if the User Portability Utilities +option is not supported. +.TP 7 +\fITERM\fP +If the internal variable \fBscreen\fP is not specified, determine +the name of the terminal type to indicate in an unspecified +manner the number of lines in a screenful of headers. If \fITERM\fP +is not set or is set to null, an unspecified default terminal +type shall be used and the value of a screenful is unspecified. The +effects of this variable are unspecified if the User +Portability Utilities option is not supported. +.TP 7 +\fITZ\fP +This variable may determine the timezone used to calculate date and +time strings written by \fImailx\fP. If \fITZ\fP is unset +or null, an unspecified default timezone shall be used. +.TP 7 +\fIVISUAL\fP +Determine a pathname of a utility to invoke when the \fBvisual\fP +command (see Commands in +mailx ) or \fB~v\fP command-escape (see Command Escapes in mailx ) +is used. If this +variable is null or not set, the full-screen editor shall be \fIvi\fP. +The effects of this +variable are unspecified if the User Portability Utilities option +is not supported. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +When \fImailx\fP is in Send Mode and standard input is not a terminal, +it shall take the standard action for all signals. +.LP +In Receive Mode, or in Send Mode when standard input is a terminal, +if a SIGINT signal is received: +.IP " 1." 4 +If in command mode, the current command, if there is one, shall be +aborted, and a command-mode prompt shall be written. +.LP +.IP " 2." 4 +If in input mode: +.RS +.IP " a." 4 +If \fBignore\fP is set, \fImailx\fP shall write \fB"@\\n"\fP , discard +the current input line, and continue processing, +bypassing the message-abort mechanism described in item 2b. +.LP +.IP " b." 4 +If the interrupt was received while sending mail, either when in Receive +Mode or in Send Mode, a message shall be written, and +another subsequent interrupt, with no other intervening characters +typed, shall be required to abort the mail message. If in +Receive Mode and another interrupt is received, a command-mode prompt +shall be written. If in Send Mode and another interrupt is +received, \fImailx\fP shall terminate with a non-zero status. +.LP +In both cases listed in item b, if the message is not empty: +.RS +.IP "i. " 5 +If \fBsave\fP is enabled and the file named by \fIDEAD\fP can be created, +the message shall be written to the file named by +\fIDEAD .\fP If the file exists, the message shall be written to replace +the contents of the file. +.LP +.IP "ii." 5 +If \fBsave\fP is not enabled, or the file named by \fIDEAD\fP cannot +be created, the message shall not be saved. +.LP +.RE +.LP +.RE +.LP +.LP +The \fImailx\fP utility shall take the standard action for all other +signals. +.SH STDOUT +.LP +In command and input modes, all output, including prompts and messages, +shall be written to standard output. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +Various \fImailx\fP commands and command escapes can create or add +to files, including the \fBmbox\fP, the dead-letter file, +and secondary mailboxes. When \fImailx\fP is used as described in +this volume of IEEE\ Std\ 1003.1-2001, these files shall +be text files, formatted as follows: +\fBline beginning with\fP \fBFrom +.br +[\fP\fBone or more\fP \fIheader-lines\fP; see Commands in mailx \fB] +.br +\fP \fIempty line +.br +\fP \fB[\fP\fBzero or more\fP \fIbody lines +.br +empty line\fP\fB] +.br +[\fP\fBline beginning with\fP \fBFrom...]\fP +.LP +where each message begins with the \fBFrom\ \fP line shown, +preceded by the beginning of the file or an empty +line. (The \fBFrom \fP line is considered to be part of the +message header, but not one of the header-lines referred +to in Commands in mailx ; thus, it shall not be affected by the \fBdiscard\fP, +\fBignore\fP, or +\fBretain\fP commands.) The formats of the remainder of the \fBFrom +\fP line and any additional header lines are +unspecified, except that none shall be empty. The format of a message +body line is also unspecified, except that no line following +an empty line shall start with \fBFrom \fP; \fImailx\fP shall +modify any such user-entered message body lines +(following an empty line and beginning with \fBFrom \fP) by +adding one or more characters to precede the \fB'F'\fP +; it may add these characters to \fBFrom \fP lines that are +not preceded by an empty line. +.LP +When a message from the system mailbox or entered by the user is not +a text file, it is implementation-defined how such a +message is stored in files written by \fImailx\fP. +.SH EXTENDED DESCRIPTION +.LP +The entire EXTENDED DESCRIPTION section shall apply only to implementations +supporting the User Portability Utilities +option. +.LP +The \fImailx\fP utility cannot guarantee support for all character +encodings in all circumstances. For example, inter-system +mail may be restricted to 7-bit data by the underlying network, 8-bit +data need not be portable to non-internationalized systems, +and so on. Under these circumstances, it is recommended that only +characters defined in the ISO/IEC\ 646:1991 standard +International Reference Version (equivalent to ASCII) 7-bit range +of characters be used. +.LP +When \fImailx\fP is invoked using one of the Receive Mode synopsis +forms, it shall write a page of header-summary lines (if +\fB-N\fP was not specified and there are messages, see below), followed +by a prompt indicating that \fImailx\fP can accept +regular commands (see Commands in mailx ); this is termed \fIcommand +mode\fP. The page of +header-summary lines shall contain the first new message if there +are new messages, or the first unread message if there are unread +messages, or the first message. When \fImailx\fP is invoked using +the Send Mode synopsis and standard input is a terminal, if no +subject is specified on the command line and the \fBasksub\fP variable +is set, a prompt for the subject shall be written. At this +point, \fImailx\fP shall be in input mode. This input mode shall also +be entered when using one of the Receive Mode synopsis forms +and a reply or new message is composed using the \fBreply\fP, \fBReply\fP, +\fBfollowup\fP, \fBFollowup\fP, or \fBmail\fP +commands and standard input is a terminal. When the message is typed +and the end of the message is encountered, the message shall +be passed to the mail delivery software. Commands can be entered by +beginning a line with the escape character (by default, tilde ( +\fB'~'\fP )) followed by a single command letter and optional arguments. +See Commands in +mailx for a summary of these commands. It is unspecified what effect +these commands will have if standard input is not a +terminal when a message is entered using either the Send Mode synopsis, +or the Read Mode commands \fBreply\fP, \fBReply\fP, +\fBfollowup\fP, \fBFollowup\fP, or \fBmail\fP. +.TP 7 +\fBNote:\fP +For notational convenience, this section uses the default escape character, +tilde, in all references and examples. +.sp +.LP +At any time, the behavior of \fImailx\fP shall be governed by a set +of environmental and internal variables. These are flags +and valued parameters that can be set and cleared via the \fImailx\fP +\fBset\fP and \fBunset\fP commands. +.LP +Regular commands are of the form: +.sp +.RS +.nf + +\fB[\fP\fIcommand\fP\fB] [\fP\fImsglist\fP\fB] [\fP\fIargument\fP \fB...\fP\fB] +\fP +.fi +.RE +.LP +If no \fIcommand\fP is specified in command mode, \fBnext\fP shall +be assumed. In input mode, commands shall be recognized by +the escape character, and lines not treated as commands shall be taken +as input for the message. +.LP +In command mode, each message shall be assigned a sequential number, +starting with 1. +.LP +All messages have a state that shall affect how they are displayed +in the header summary and how they are retained or deleted +upon termination of \fImailx\fP. There is at any time the notion of +a \fIcurrent\fP message, which shall be marked by a +\fB'>'\fP at the beginning of a line in the header summary. When \fImailx\fP +is invoked using one of the Receive Mode +synopsis forms, the current message shall be the first new message, +if there is a new message, or the first unread message if there +is an unread message, or the first message if there are any messages, +or unspecified if there are no messages in the mailbox. Each +command that takes an optional list of messages (\fImsglist\fP) or +an optional single message (\fImessage\fP) on which to operate +shall leave the current message set to the highest-numbered message +of the messages specified, unless the command deletes messages, +in which case the current message shall be set to the first undeleted +message (that is, a message not in the deleted state) after +the highest-numbered message deleted by the command, if one exists, +or the first undeleted message before the highest-numbered +message deleted by the command, if one exists, or to an unspecified +value if there are no remaining undeleted messages. All +messages shall be in one of the following states: +.TP 7 +\fInew\fP +The message is present in the system mailbox and has not been viewed +by the user or moved to any other state. Messages in state +\fInew\fP when \fImailx\fP quits shall be retained in the system mailbox. +.TP 7 +\fIunread\fP +The message has been present in the system mailbox for more than one +invocation of \fImailx\fP and has not been viewed by the +user or moved to any other state. Messages in state \fIunread\fP when +\fImailx\fP quits shall be retained in the system +mailbox. +.TP 7 +\fIread\fP +The message has been processed by one of the following commands: \fB~f\fP, +\fB~m\fP, \fB~F\fP, +\fB~M\fP, \fBcopy\fP, \fBmbox\fP, \fBnext\fP, \fBpipe\fP, \fBprint\fP, +\fBPrint\fP, \fBtop\fP, \fBtype\fP, +\fBType\fP, \fBundelete\fP. The \fBdelete\fP, \fBdp\fP, and \fBdt\fP +commands may also cause the next message to be marked as +\fIread\fP, depending on the value of the \fBautoprint\fP variable. +Messages that are in the system mailbox and in state +\fIread\fP when \fImailx\fP quits shall be saved in the \fBmbox\fP, +unless the internal variable \fBhold\fP was set. Messages +that are in the \fBmbox\fP or in a secondary mailbox and in state +\fIread\fP when \fImailx\fP quits shall be retained in their +current location. +.TP 7 +\fIdeleted\fP +The message has been processed by one of the following commands: \fBdelete\fP, +\fBdp\fP, \fBdt\fP. Messages in state +\fIdeleted\fP when \fImailx\fP quits shall be deleted. Deleted messages +shall be ignored until \fImailx\fP quits or changes +mailboxes or they are specified to the undelete command; for example, +the message specification / \fIstring\fP shall only search +the subject lines of messages that have not yet been deleted, unless +the command operating on the list of messages is +\fBundelete\fP. No deleted message or deleted message header shall +be displayed by any \fImailx\fP command other than +\fBundelete\fP. +.TP 7 +\fIpreserved\fP +The message has been processed by a \fBpreserve\fP command. When \fImailx\fP +quits, the message shall be retained in its +current location. +.TP 7 +\fIsaved\fP +The message has been processed by one of the following commands: \fBsave\fP +or \fBwrite\fP. If the current mailbox is the +system mailbox, and the internal variable \fBkeepsave\fP is set, messages +in the state saved shall be saved to the file designated +by the \fIMBOX\fP variable (see the ENVIRONMENT VARIABLES section). +If the current mailbox is the system mailbox, messages in the +state \fIsaved\fP shall be deleted from the current mailbox, when +the \fBquit\fP or \fBfile\fP command is used to exit the +current mailbox. +.sp +.LP +The header-summary line for each message shall indicate the state +of the message. +.LP +Many commands take an optional list of messages ( \fImsglist\fP) on +which to operate, which defaults to the current message. A +\fImsglist\fP is a list of message specifications separated by s, +which can include: +.TP 7 +\fBn\fP +Message number \fIn\fP. +.TP 7 +\fB+\fP +The next undeleted message, or the next deleted message for the \fBundelete\fP +command. +.TP 7 +\fB-\fP +The next previous undeleted message, or the next previous deleted +message for the \fBundelete\fP command. +.TP 7 +\fB\&.\fP +The current message. +.TP 7 +\fB^\fP +The first undeleted message, or the first deleted message for the +\fBundelete\fP command. +.TP 7 +\fB$\fP +The last message. +.TP 7 +\fB*\fP +All messages. +.TP 7 +\fBn-m\fP +An inclusive range of message numbers. +.TP 7 +\fIaddress\fP +All messages from \fIaddress\fP; any address as shown in a header +summary shall be matchable in this form. +.TP 7 +/\fIstring\fP +All messages with \fIstring\fP in the subject line (case ignored). +.TP 7 +\fB:c\fP +All messages of type \fIc\fP, where \fIc\fP shall be one of: +.TP 7 +\fBd\fP +.RS +Deleted messages. +.RE +.TP 7 +\fBn\fP +.RS +New messages. +.RE +.TP 7 +\fBo\fP +.RS +Old messages (any not in state \fIread\fP or \fInew\fP). +.RE +.TP 7 +\fBr\fP +.RS +Read messages. +.RE +.TP 7 +\fBu\fP +.RS +Unread messages. +.RE +.sp +.sp +.LP +Other commands take an optional message ( \fImessage\fP) on which +to operate, which defaults to the current message. All of the +forms allowed for \fImsglist\fP are also allowed for \fImessage\fP, +but if more than one message is specified, only the first +shall be operated on. +.LP +Other arguments are usually arbitrary strings whose usage depends +on the command involved. +.SS Start-Up in mailx +.LP +At start-up time, \fImailx\fP shall take the following steps in sequence: +.IP " 1." 4 +Establish all variables at their stated default values. +.LP +.IP " 2." 4 +Process command line options, overriding corresponding default values. +.LP +.IP " 3." 4 +Import any of the \fIDEAD ,\fP \fIEDITOR ,\fP \fIMBOX ,\fP \fILISTER +,\fP \fIPAGER ,\fP \fISHELL ,\fP or \fIVISUAL\fP +variables that are present in the environment, overriding the corresponding +default values. +.LP +.IP " 4." 4 +Read \fImailx\fP commands from an unspecified system start-up file, +unless the \fB-n\fP option is given, to initialize any +internal \fImailx\fP variables and aliases. +.LP +.IP " 5." 4 +Process the start-up file of \fImailx\fP commands named in the user +\fIMAILRC\fP variable. +.LP +.LP +Most regular \fImailx\fP commands are valid inside start-up files, +the most common use being to set up initial display options +and alias lists. The following commands shall be invalid in the start-up +file: \fB!\fP, \fBedit\fP, \fBhold\fP, \fBmail\fP, +\fBpreserve\fP, \fBreply\fP, \fBReply\fP, \fBshell\fP, \fBvisual\fP, +\fBCopy\fP, \fBfollowup\fP, and \fBFollowup\fP. Any +errors in the start-up file shall either cause \fImailx\fP to terminate +with a diagnostic message and a non-zero status or to +continue after writing a diagnostic message, ignoring the remainder +of the lines in the start-up file. +.LP +A blank line in a start-up file shall be ignored. +.SS Internal Variables in mailx +.LP +The following variables are internal \fImailx\fP variables. Each internal +variable can be set via the \fImailx\fP \fBset\fP +command at any time. The \fBunset\fP and \fBset\ no\fP \fIname\fP +commands can be used to erase variables. +.LP +In the following list, variables shown as: +.sp +.RS +.nf + +\fBvariable +\fP +.fi +.RE +.LP +represent Boolean values. Variables shown as: +.sp +.RS +.nf + +\fBvariable=\fP\fIvalue\fP +.fi +.RE +.LP +shall be assigned string or numeric values. For string values, the +rules in Commands in mailx +concerning filenames and quoting shall also apply. +.LP +The defaults specified here may be changed by the implementation-defined +system start-up file unless the user specifies the +\fB-n\fP option. +.TP 7 +\fBallnet\fP +All network names whose login name components match shall be treated +as identical. This shall cause the \fImsglist\fP message +specifications to behave similarly. The default shall be \fBnoallnet\fP. +See also the \fBalternates\fP command and the +\fBmetoo\fP variable. +.TP 7 +\fBappend\fP +Append messages to the end of the \fBmbox\fP file upon termination +instead of placing them at the beginning. The default shall +be \fBnoappend\fP. This variable shall not affect the \fBsave\fP command +when saving to \fBmbox\fP. +.TP 7 +\fBask\fP,\ \fBasksub\fP +Prompt for a subject line on outgoing mail if one is not specified +on the command line with the \fB-s\fP option. The +\fBask\fP and \fBasksub\fP forms are synonyms; the system shall refer +to \fBasksub\fP and \fBnoasksub\fP in its messages, but +shall accept \fBask\fP and \fBnoask\fP as user input to mean \fBasksub\fP +and \fBnoasksub\fP. It shall not be possible to set +both \fBask\fP and \fBnoasksub\fP, or \fBnoask\fP and \fBasksub\fP. +The default shall be \fBasksub\fP, but no prompting shall +be done if standard input is not a terminal. +.TP 7 +\fBaskbcc\fP +Prompt for the blind copy list. The default shall be \fBnoaskbcc\fP. +.TP 7 +\fBaskcc\fP +Prompt for the copy list. The default shall be \fBnoaskcc\fP. +.TP 7 +\fBautoprint\fP +Enable automatic writing of messages after \fBdelete\fP and \fBundelete\fP +commands. The default shall be +\fBnoautoprint\fP. +.TP 7 +\fBbang\fP +Enable the special-case treatment of exclamation marks ( \fB'!'\fP +) in escape command lines; see the \fBescape\fP command +and Command Escapes in mailx . The default shall be \fBnobang\fP, +disabling the expansion of +\fB'!'\fP in the \fIcommand\fP argument to the \fB~!\fP command and +the \fB~. +.TP 7 +\fBkeep\fP +When a system mailbox, secondary mailbox, or \fBmbox\fP is empty, +truncate it to zero length instead of removing it. The +default shall be \fBnokeep\fP. +.TP 7 +\fBkeepsave\fP +Keep the messages that have been saved from the system mailbox into +other files in the file designated by the variable \fIMBOX +,\fP instead of deleting them. The default shall be \fBnokeepsave\fP. +.TP 7 +\fBmetoo\fP +Suppress the deletion of the login name of the user from the recipient +list when replying to a message or sending to a group. +The default shall be \fBnometoo\fP. +.TP 7 +\fBonehop\fP +When responding to a message that was originally sent to several recipients, +the other recipient addresses are normally forced to +be relative to the originating author's machine for the response. +This flag disables alteration of the recipients' addresses, +improving efficiency in a network where all machines can send directly +to all other machines (that is, one hop away). The default +shall be \fBnoonehop\fP. +.TP 7 +\fBoutfolder\fP +Cause the files used to record outgoing messages to be located in +the directory specified by the \fBfolder\fP variable unless +the pathname is absolute. The default shall be \fBnooutfolder\fP. +See the \fBrecord\fP variable. +.TP 7 +\fBpage\fP +Insert a after each message sent through the pipe created +by the \fBpipe\fP command. The default shall be +\fBnopage\fP. +.TP 7 +\fBprompt\fP=\fIstring\fP +.sp +Set the command-mode prompt to \fIstring\fP. If \fIstring\fP is null +or if \fBnoprompt\fP is set, no prompting shall occur. The +default shall be to prompt with the string \fB"?\ "\fP . +.TP 7 +\fBquiet\fP +Refrain from writing the opening message and version when entering +\fImailx\fP. The default shall be \fBnoquiet\fP. +.TP 7 +\fBrecord\fP=\fIfile\fP +Record all outgoing mail in the file with the pathname \fIfile\fP. +The default shall be \fBnorecord\fP. See also +\fBoutfolder\fP above. +.TP 7 +\fBsave\fP +Enable saving of messages in the dead-letter file on interrupt or +delivery error. See the variable \fIDEAD\fP for the location +of the dead-letter file. The default shall be \fBsave\fP. +.TP 7 +\fBscreen\fP=\fInumber\fP +.sp +Set the number of lines in a screenful of headers for the \fBheaders\fP +and \fBz\fP commands. If \fBscreen\fP is not specified, +a value based on the terminal type identified by the \fITERM\fP environment +variable, the window size, the baud rate, or some +combination of these shall be used. +.TP 7 +\fBsendwait\fP +Wait for the background mailer to finish before returning. The default +shall be \fBnosendwait\fP. +.TP 7 +\fBshowto\fP +When the sender of the message was the user who is invoking \fImailx\fP, +write the information from the \fBTo:\fP line +instead of the \fBFrom:\fP line in the header summary. The default +shall be \fBnoshowto\fP. +.TP 7 +\fBsign\fP=\fIstring\fP +Set the variable inserted into the text of a message when the \fB~a\fP +command escape is given. The default shall be +\fBnosign\fP. The character sequences \fB'\\t'\fP and \fB'\\n'\fP +shall be recognized in the variable as s and +s, respectively. (See also \fB~i\fP in Command Escapes in +mailx .) +.TP 7 +\fBSign\fP=\fIstring\fP +Set the variable inserted into the text of a message when the \fB~A\fP +command escape is given. The default shall be +\fBnoSign\fP. The character sequences \fB'\\t'\fP and \fB'\\n'\fP +shall be recognized in the variable as s and +s, respectively. +.TP 7 +\fBtoplines\fP=\fInumber\fP +.sp +Set the number of lines of the message to write with the \fBtop\fP +command. The default shall be 5. +.sp +.SS Commands in mailx +.LP +The following \fImailx\fP commands shall be provided. In the following +list, header refers to lines from the message header, as +shown in the OUTPUT FILES section. Header-line refers to lines within +the header that begin with one or more non-white-space +characters, immediately followed by a colon and white space and continuing +until the next line beginning with a non-white-space +character or an empty line. Header-field refers to the portion of +a header line prior to the first colon in that line. +.LP +For each of the commands listed below, the command can be entered +as the abbreviation (those characters in the Synopsis command +word preceding the \fB'['\fP ), the full command (all characters shown +for the command word, omitting the \fB'['\fP and +\fB']'\fP ), or any truncation of the full command down to the abbreviation. +For example, the \fBexit\fP command (shown as +\fBex[it]\fP in the Synopsis) can be entered as \fBex\fP, \fBexi\fP, +or \fBexit\fP. +.LP +The arguments to commands can be quoted, using the following methods: +.IP " *" 3 +An argument can be enclosed between paired double-quotes ( \fB""\fP +) or single-quotes ( \fB''\fP ); any white space, +shell word expansion, or backslash characters within the quotes shall +be treated literally as part of the argument. A double-quote +shall be treated literally within single-quotes and \fIvice versa\fP. +These special properties of the quote marks shall occur only +when they are paired at the beginning and end of the argument. +.LP +.IP " *" 3 +A backslash outside of the enclosing quotes shall be discarded and +the following character treated literally as part of the +argument. +.LP +.IP " *" 3 +An unquoted backslash at the end of a command line shall be discarded +and the next line shall continue the command. +.LP +.LP +Filenames, where expected, shall be subjected to the following transformations, +in sequence: +.IP " *" 3 +If the filename begins with an unquoted plus sign, and the \fBfolder\fP +variable is defined (see the \fBfolder\fP variable), +the plus sign shall be replaced by the value of the \fBfolder\fP variable +followed by a slash. If the \fBfolder\fP variable is +unset or is set to null, the filename shall be unchanged. +.LP +.IP " *" 3 +Shell word expansions shall be applied to the filename (see \fIWord +Expansions\fP ). If +more than a single pathname results from this expansion and the command +is expecting one file, the effects are unspecified. +.LP +.SS Declare Aliases +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBa\fP\fB[\fP\fBlias\fP\fB] [\fP\fIalias\fP \fB[\fP\fIaddress\fP\fB...\fP\fB]]\fP\fBg\fP\fB[\fP\fBroup\fP\fB] [\fP\fIalias\fP \fB[\fP\fIaddress\fP\fB...\fP\fB]]\fP +.fi +.RE +.sp +.LP +Add the given addresses to the alias specified by \fIalias\fP. The +names shall be substituted when \fIalias\fP is used as a +recipient address specified by the user in an outgoing message (that +is, other recipients addressed indirectly through the +\fBreply\fP command shall not be substituted in this manner). Mail +address alias substitution shall apply only when the alias +string is used as a full address; for example, when \fBhlj\fP is an +alias, \fIhlj@posix.com\fP does not trigger the alias +substitution. If no arguments are given, write a listing of the current +aliases to standard output. If only an \fIalias\fP +argument is given, write a listing of the specified alias to standard +output. These listings need not reflect the same order of +addresses that were entered. +.SS Declare Alternatives +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBalt\fP\fB[\fP\fBernates\fP\fB]\fP \fIname\fP\fB... +\fP +.fi +.RE +.sp +.LP +(See also the \fBmetoo\fP command.) Declare a list of alternative +names for the user's login. When responding to a message, +these names shall be removed from the list of recipients for the response. +The comparison of names shall be in a case-insensitive +manner. With no arguments, \fBalternates\fP shall write the current +list of alternative names. +.SS Change Current Directory +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBcd\fP \fB[\fP\fIdirectory\fP\fB]\fP\fBch\fP\fB[\fP\fBdir\fP\fB] [\fP\fIdirectory\fP\fB]\fP +.fi +.RE +.sp +.LP +Change directory. If \fIdirectory\fP is not specified, the contents +of \fIHOME\fP shall be used. +.SS Copy Messages +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBc\fP\fB[\fP\fBopy\fP\fB] [\fP\fIfile\fP\fB]\fP\fBc\fP\fB[\fP\fBopy\fP\fB] [\fP\fImsglist\fP\fB]\fP \fIfile\fP\fBC\fP\fB[\fP\fBopy\fP\fB] [\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +Copy messages to the file named by the pathname \fIfile\fP without +marking the messages as saved. Otherwise, it shall be +equivalent to the \fBsave\fP command. +.LP +In the capitalized form, save the specified messages in a file whose +name is derived from the author of the message to be saved, +without marking the messages as saved. Otherwise, it shall be equivalent +to the \fBSave\fP command. +.SS Delete Messages +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBd\fP\fB[\fP\fBelete\fP\fB] [\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +Mark messages for deletion from the mailbox. The deletions shall not +occur until \fImailx\fP quits (see the \fBquit\fP +command) or changes mailboxes (see the \fBfolder\fP command). If \fBautoprint\fP +is set and there are messages remaining after +the \fBdelete\fP command, the current message shall be written as +described for the \fBprint\fP command (see the \fBprint\fP +command); otherwise, the \fImailx\fP prompt shall be written. +.SS Discard Header Fields +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBdi\fP\fB[\fP\fBscard\fP\fB] [\fP\fIheader-field\fP\fB...\fP\fB]\fP\fBig\fP\fB[\fP\fBnore\fP\fB] [\fP\fIheader-field\fP\fB...\fP\fB]\fP +.fi +.RE +.sp +.LP +Suppress the specified header fields when writing messages. Specified +\fIheader-fields\fP shall be added to the list of +suppressed header fields. Examples of header fields to ignore are +\fBstatus\fP and \fBcc\fP. The fields shall be included when +the message is saved. The \fBPrint\fP and \fBType\fP commands shall +override this command. The comparison of header fields shall +be in a case-insensitive manner. If no arguments are specified, write +a list of the currently suppressed header fields to standard +output; the listing need not reflect the same order of header fields +that were entered. +.LP +If both \fBretain\fP and \fBdiscard\fP commands are given, \fBdiscard\fP +commands shall be ignored. +.SS Delete Messages and Display +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBdp\fP \fB[\fP\fImsglist\fP\fB]\fP\fBdt\fP \fB[\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +Delete the specified messages as described for the \fBdelete\fP command, +except that the \fBautoprint\fP variable shall have +no effect, and the current message shall be written only if it was +set to a message after the last message deleted by the command. +Otherwise, an informational message to the effect that there are no +further messages in the mailbox shall be written, followed by +the \fImailx\fP prompt. +.SS Echo a String +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBec\fP\fB[\fP\fBho\fP\fB]\fP \fIstring\fP \fB... +\fP +.fi +.RE +.sp +.LP +Echo the given strings, equivalent to the shell \fIecho\fP utility. +.SS Edit Messages +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBe\fP\fB[\fP\fBdit\fP\fB] [\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +Edit the given messages. The messages shall be placed in a temporary +file and the utility named by the \fIEDITOR\fP variable is +invoked to edit each file in sequence. The default \fIEDITOR\fP is +unspecified. +.LP +The \fBedit\fP command does not modify the contents of those messages +in the mailbox. +.SS Exit +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBex\fP\fB[\fP\fBit\fP\fB]\fP\fBx\fP\fB[\fP\fBit\fP\fB]\fP +.fi +.RE +.sp +.LP +Exit from \fImailx\fP without changing the mailbox. No messages shall +be saved in the \fBmbox\fP (see also \fBquit\fP). +.SS Change Folder +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBfi\fP\fB[\fP\fBle\fP\fB] [\fP\fIfile\fP\fB]\fP\fBfold\fP\fB[\fP\fBer\fP\fB] [\fP\fIfile\fP\fB]\fP +.fi +.RE +.sp +.LP +Quit (see the \fBquit\fP command) from the current file of messages +and read in the file named by the pathname \fIfile\fP. If +no argument is given, the name and status of the current mailbox shall +be written. +.LP +Several unquoted special characters shall be recognized when used +as \fIfile\fP names, with the following substitutions: +.TP 7 +\fB%\fP +The system mailbox for the invoking user. +.TP 7 +\fB%\fP\fIuser\fP +The system mailbox for \fIuser\fP. +.TP 7 +\fB#\fP +The previous file. +.TP 7 +\fB&\fP +The current \fBmbox\fP. +.TP 7 +\fB+\fP\fIfile\fP +The named file in the \fBfolder\fP directory. (See the \fBfolder\fP +variable.) +.sp +.LP +The default file shall be the current mailbox. +.SS Display List of Folders +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBfolders\fP +.fi +.RE +.sp +.LP +Write the names of the files in the directory set by the \fBfolder\fP +variable. The command specified by the \fILISTER\fP +environment variable shall be used (see the ENVIRONMENT VARIABLES +section). +.SS Follow Up Specified Messages +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBfo\fP\fB[\fP\fBllowup\fP\fB] [\fP\fImessage\fP\fB]\fP\fBF\fP\fB[\fP\fBollowup\fP\fB] [\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +In the lowercase form, respond to a message, recording the response +in a file whose name is derived from the author of the +message. See also the \fBsave\fP and \fBcopy\fP commands and \fBoutfolder\fP. +.LP +In the capitalized form, respond to the first message in the \fImsglist\fP, +sending the message to the author of each message +in the \fImsglist\fP. The subject line shall be taken from the first +message and the response shall be recorded in a file whose +name is derived from the author of the first message. See also the +\fBSave\fP and \fBCopy\fP commands and \fBoutfolder\fP. +.LP +Both forms shall override the \fBrecord\fP variable, if set. +.SS Display Header Summary for Specified Messages +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBf\fP\fB[\fP\fBrom\fP\fB] [\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +Write the header summary for the specified messages. +.SS Display Header Summary +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBh\fP\fB[\fP\fBeaders\fP\fB] [\fP\fImessage\fP\fB]\fP +.fi +.RE +.sp +.LP +Write the page of headers that includes the message specified. If +the \fImessage\fP argument is not specified, the current +message shall not change. However, if the \fImessage\fP argument is +specified, the current message shall become the message that +appears at the top of the page of headers that includes the message +specified. The \fBscreen\fP variable sets the number of +headers per page. See also the \fBz\fP command. +.SS Help +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBhel\fP\fB[\fP\fBp\fP\fB]\fP\fB? +\fP +.fi +.RE +.sp +.LP +Write a summary of commands. +.SS Hold Messages +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBho\fP\fB[\fP\fBld\fP\fB] [\fP\fImsglist\fP\fB]\fP\fBpre\fP\fB[\fP\fBserve\fP\fB] [\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +Mark the messages in \fImsglist\fP to be retained in the mailbox when +\fImailx\fP terminates. This shall override any commands +that might previously have marked the messages to be deleted. During +the current invocation of \fImailx\fP, only the +\fBdelete\fP, \fBdp\fP, or \fBdt\fP commands shall remove the \fIpreserve\fP +marking of a message. +.SS Execute Commands Conditionally +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBi\fP\fB[\fP\fBf\fP\fB]\fP \fBs|r +\fP\fImail-command\fP\fBs +el\fP\fB[\fP\fBse\fP\fB] +\fP\fImail-command\fP\fBs +en\fP\fB[\fP\fBdif\fP\fB]\fP +.fi +.RE +.sp +.LP +Execute commands conditionally, where \fBif\ s\fP executes the following +\fImail-command\fPs, up to an \fBelse\fP or +\fBendif\fP, if the program is in Send Mode, and \fBif\ r\fP shall +cause the \fImail-command\fPs to be executed only in +Receive Mode. +.SS List Available Commands +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBl\fP\fB[\fP\fBist\fP\fB]\fP +.fi +.RE +.sp +.LP +Write a list of all commands available. No explanation shall be given. +.SS Mail a Message +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBm\fP\fB[\fP\fBail\fP\fB]\fP \fIaddress\fP\fB... +\fP +.fi +.RE +.sp +.LP +Mail a message to the specified addresses or aliases. +.SS Direct Messages to mbox +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBmb\fP\fB[\fP\fBox\fP\fB] [\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +Arrange for the given messages to end up in the \fBmbox\fP save file +when \fImailx\fP terminates normally. See \fIMBOX .\fP +See also the \fBexit\fP and \fBquit\fP commands. +.SS Process Next Specified Message +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBn\fP\fB[\fP\fBext\fP\fB] [\fP\fImessage\fP\fB]\fP +.fi +.RE +.sp +.LP +If the current message has not been written (for example, by the \fBprint\fP +command) since \fImailx\fP started or since any +other message was the current message, behave as if the \fBprint\fP +command was entered. Otherwise, if there is an undeleted +message after the current message, make it the current message and +behave as if the \fBprint\fP command was entered. Otherwise, an +informational message to the effect that there are no further messages +in the mailbox shall be written, followed by the +\fImailx\fP prompt. +.SS Pipe Message +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBpi\fP\fB[\fP\fBpe\fP\fB] [[\fP\fImsglist\fP\fB]\fP \fIcommand\fP\fB]\fP\fB|\fP \fB[[\fP\fImsglist\fP\fB]\fP \fIcommand\fP\fB]\fP +.fi +.RE +.sp +.LP +Pipe the messages through the given \fIcommand\fP by invoking the +command interpreter specified by \fISHELL\fP with two +arguments: \fB-c\fP and \fIcommand\fP. (See also \fIsh\fP \fB-c\fP.) +The application shall +ensure that the command is given as a single argument. Quoting, described +previously, can be used to accomplish this. If no +arguments are given, the current message shall be piped through the +command specified by the value of the \fBcmd\fP variable. If +the \fBpage\fP variable is set, a shall be inserted after +each message. +.SS Display Message with Headers +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBP\fP\fB[\fP\fBrint\fP\fB] [\fP\fImsglist\fP\fB]\fP\fBT\fP\fB[\fP\fBype\fP\fB] [\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +Write the specified messages, including all header lines, to standard +output. Override suppression of lines by the +\fBdiscard\fP, \fBignore\fP, and \fBretain\fP commands. If \fBcrt\fP +is set, the messages longer than the number of lines +specified by the \fBcrt\fP variable shall be paged through the command +specified by the \fIPAGER\fP environment variable. +.SS Display Message +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBp\fP\fB[\fP\fBrint\fP\fB] [\fP\fImsglist\fP\fB]\fP\fBt\fP\fB[\fP\fBype\fP\fB] [\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +Write the specified messages to standard output. If \fBcrt\fP is set, +the messages longer than the number of lines specified by +the \fBcrt\fP variable shall be paged through the command specified +by the \fIPAGER\fP environment variable. +.SS Quit +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBq\fP\fB[\fP\fBuit\fP\fB] +\fP\fIend-of-file\fP +.fi +.RE +.sp +.LP +Terminate \fImailx\fP, storing messages that were read in \fBmbox\fP +(if the current mailbox is the system mailbox and unless +\fBhold\fP is set), deleting messages that have been explicitly saved +(unless \fBkeepsave\fP is set), discarding messages that +have been deleted, and saving all remaining messages in the mailbox. +.SS Reply to a Message List +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBR\fP\fB[\fP\fBeply\fP\fB] [\fP\fImsglist\fP\fB]\fP\fBR\fP\fB[\fP\fBespond\fP\fB] [\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +Mail a reply message to the sender of each message in the \fImsglist\fP. +The subject line shall be formed by concatenating +\fBRe:\fP (unless it already begins with that string) and +the subject from the first message. If \fBrecord\fP is +set to a filename, the response shall be saved at the end of that +file. +.LP +See also the \fBflipr\fP variable. +.SS Reply to a Message +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBr\fP\fB[\fP\fBeply\fP\fB] [\fP\fImessage\fP\fB]\fP\fBr\fP\fB[\fP\fBespond\fP\fB] [\fP\fImessage\fP\fB]\fP +.fi +.RE +.sp +.LP +Mail a reply message to all recipients included in the header of the +message. The subject line shall be formed by concatenating +\fBRe:\fP (unless it already begins with that string) and +the subject from the message. If \fBrecord\fP is set to a +filename, the response shall be saved at the end of that file. +.LP +See also the \fBflipr\fP variable. +.SS Retain Header Fields +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBret\fP\fB[\fP\fBain\fP\fB] [\fP\fIheader-field\fP\fB...\fP\fB]\fP +.fi +.RE +.sp +.LP +Retain the specified header fields when writing messages. This command +shall override all \fBdiscard\fP and \fBignore\fP +commands. The comparison of header fields shall be in a case-insensitive +manner. If no arguments are specified, write a list of the +currently retained header fields to standard output; the listing need +not reflect the same order of header fields that were +entered. +.SS Save Messages +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBs\fP\fB[\fP\fBave\fP\fB] [\fP\fIfile\fP\fB]\fP\fBs\fP\fB[\fP\fBave\fP\fB] [\fP\fImsglist\fP\fB]\fP \fIfile\fP\fBS\fP\fB[\fP\fBave\fP\fB] [\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +Save the specified messages in the file named by the pathname \fIfile\fP, +or the \fBmbox\fP if the \fIfile\fP argument is +omitted. The file shall be created if it does not exist; otherwise, +the messages shall be appended to the file. The message shall +be put in the state \fIsaved\fP, and shall behave as specified in +the description of the \fIsaved\fP state when the current +mailbox is exited by the \fBquit\fP or \fBfile\fP command. +.LP +In the capitalized form, save the specified messages in a file whose +name is derived from the author of the first message. The +name of the file shall be taken to be the author's name with all network +addressing stripped off. See also the \fBCopy\fP, +\fBfollowup\fP, and \fBFollowup\fP commands and \fBoutfolder\fP variable. +.SS Set Variables +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBse\fP\fB[\fP\fBt\fP\fB] [\fP\fIname\fP\fB[\fP\fB=\fP\fB[\fP\fIstring\fP\fB]]\fP \fB...\fP\fB] [\fP\fIname\fP\fB=\fP\fInumber\fP \fB...\fP\fB] [\fP\fBno\fP\fIname\fP \fB...\fP\fB]\fP +.fi +.RE +.sp +.LP +Define one or more variables called \fIname\fP. The variable can be +given a null, string, or numeric value. Quoting and +backslash escapes can occur anywhere in \fIstring\fP, as described +previously, as if the \fIstring\fP portion of the argument +were the entire argument. The forms \fIname\fP and \fIname\fP= shall +be equivalent to \fIname\fP="" for variables that take +string values. The \fBset\fP command without arguments shall write +a list of all defined variables and their values. The \fBno\fP +\fIname\fP form shall be equivalent to \fBunset\fP \fIname\fP. +.SS Invoke a Shell +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBsh\fP\fB[\fP\fBell\fP\fB]\fP +.fi +.RE +.sp +.LP +Invoke an interactive command interpreter (see also \fISHELL ).\fP +.SS Display Message Size +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBsi\fP\fB[\fP\fBze\fP\fB] [\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +Write the size in bytes of each of the specified messages. +.SS Read mailx Commands From a File +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBso\fP\fB[\fP\fBurce\fP\fB]\fP \fIfile\fP +.fi +.RE +.sp +.LP +Read and execute commands from the file named by the pathname \fIfile\fP +and return to command mode. +.SS Display Beginning of Messages +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBto\fP\fB[\fP\fBp\fP\fB] [\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +Write the top few lines of each of the specified messages. If the +\fBtoplines\fP variable is set, it is taken as the number of +lines to write. The default shall be 5. +.SS Touch Messages +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBtou\fP\fB[\fP\fBch\fP\fB] [\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +Touch the specified messages. If any message in \fImsglist\fP is not +specifically deleted nor saved in a file, it shall be +placed in the \fBmbox\fP upon normal termination. See \fBexit\fP and +\fBquit\fP. +.SS Delete Aliases +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBuna\fP\fB[\fP\fBlias\fP\fB] [\fP\fIalias\fP\fB]\fP\fB... +\fP +.fi +.RE +.sp +.LP +Delete the specified alias names. If a specified alias does not exist, +the results are unspecified. +.SS Undelete Messages +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBu\fP\fB[\fP\fBndelete\fP\fB] [\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +Change the state of the specified messages from deleted to read. If +\fBautoprint\fP is set, the last message of those restored +shall be written. If \fImsglist\fP is not specified, the message shall +be selected as follows: +.IP " *" 3 +If there are any deleted messages that follow the current message, +the first of these shall be chosen. +.LP +.IP " *" 3 +Otherwise, the last deleted message that also precedes the current +message shall be chosen. +.LP +.SS Unset Variables +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBuns\fP\fB[\fP\fBet\fP\fB]\fP \fIname\fP\fB... +\fP +.fi +.RE +.sp +.LP +Cause the specified variables to be erased. +.SS Edit Message with Full-Screen Editor +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBv\fP\fB[\fP\fBisual\fP\fB] [\fP\fImsglist\fP\fB]\fP +.fi +.RE +.sp +.LP +Edit the given messages with a screen editor. Each message shall be +placed in a temporary file, and the utility named by the +\fIVISUAL\fP variable shall be invoked to edit each file in sequence. +The default editor shall be \fIvi\fP. +.LP +The \fBvisual\fP command does not modify the contents of those messages +in the mailbox. +.SS Write Messages to a File +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBw\fP\fB[\fP\fBrite\fP\fB] [\fP\fImsglist\fP\fB]\fP \fIfile\fP +.fi +.RE +.sp +.LP +Write the given messages to the file specified by the pathname \fIfile\fP, +minus the message header. Otherwise, it shall be +equivalent to the \fBsave\fP command. +.SS Scroll Header Display +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBz\fP\fB[\fP\fB+|-\fP\fB]\fP +.fi +.RE +.sp +.LP +Scroll the header display forward (if \fB'+'\fP is specified or if +no option is specified) or backward (if \fB'-'\fP is +specified) one screenful. The number of headers written shall be set +by the \fBscreen\fP variable. +.SS Invoke Shell Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB!\fP\fIcommand\fP +.fi +.RE +.sp +.LP +Invoke the command interpreter specified by \fISHELL\fP with two arguments: +\fB-c\fP and \fIcommand\fP. (See also \fIsh\fP \fB-c\fP.) If the \fBbang\fP +variable is set, each unescaped occurrence of \fB'!'\fP in +\fIcommand\fP shall be replaced with the command executed by the previous +\fB!\fP command or \fB~!\fP command escape. +.SS Null Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB#\fP \fIcomment\fP +.fi +.RE +.sp +.LP +This null command (comment) shall be ignored by \fImailx\fP. +.SS Display Current Message Number +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB= +\fP +.fi +.RE +.sp +.LP +Write the current message number. +.SS Command Escapes in mailx +.LP +The following commands can be entered only from input mode, by beginning +a line with the escape character (by default, tilde ( +\fB'~'\fP )). See the \fBescape\fP variable description for changing +this special character. The format for the commands +shall be: +.sp +.RS +.nf + +\fB<\fP\fIescape-character\fP\fB><\fP\fIcommand-char\fP\fB><\fP\fIseparator\fP\fB>\fP\fB[\fP\fB<\fP\fIarguments\fP\fB>\fP\fB]\fP +.fi +.RE +.LP +where the <\fIseparator\fP> can be zero or more s. +.LP +In the following descriptions, the application shall ensure that the +argument \fIcommand\fP (but not \fImailx-command)\fP is a +shell command string. Any string acceptable to the command interpreter +specified by the \fISHELL\fP variable when it is invoked as +\fISHELL\fP \fB-c\fP \fIcommand_string\fP shall be valid. The command +can be presented as multiple arguments (that is, quoting +is not required). +.LP +Command escapes that are listed with \fImsglist\fP or \fImailx-command\fP +arguments are invalid in Send Mode and produce +unspecified results. +.TP 7 +\fB~!\ \fP \fIcommand\fP +Invoke the command interpreter specified by \fISHELL\fP with two arguments: +\fB-c\fP and \fIcommand\fP; and then return to +input mode. If the \fBbang\fP variable is set, each unescaped occurrence +of \fB'!'\fP in \fIcommand\fP shall be replaced with +the command executed by the previous \fB!\fP command or \fB~!\fP command +escape. +.TP 7 +\fB~.\fP +Simulate end-of-file (terminate message input). +.TP 7 +\fB~:\ \fP \fImailx-command\fP,\ \fB~_\ \fP \fImailx-command\fP +.sp +Perform the command-level request. +.TP 7 +\fB~?\fP +Write a summary of command escapes. +.TP 7 +\fB~A\fP +This shall be equivalent to \fB~i\ Sign\fP. +.TP 7 +\fB~a\fP +This shall be equivalent to \fB~i\ sign\fP. +.TP 7 +\fB~b\ \fP \fIname\fP... +Add the \fIname\fPs to the blind carbon copy ( \fBBcc\fP) list. +.TP 7 +\fB~c\ \fP \fIname\fP... +Add the \fIname\fPs to the carbon copy ( \fBCc\fP) list. +.TP 7 +\fB~d\fP +Read in the dead-letter file. See \fIDEAD\fP for a description of +this file. +.TP 7 +\fB~e\fP +Invoke the editor, as specified by the \fIEDITOR\fP environment variable, +on the partial message. +.TP 7 +\fB~f\ [\fP\fImsglist\fP\fB]\fP +Forward the specified messages. The specified messages shall be inserted +into the current message without alteration. This +command escape also shall insert message headers into the message +with field selection affected by the \fBdiscard\fP, +\fBignore\fP, and \fBretain\fP commands. +.TP 7 +\fB~F\ [\fP\fImsglist\fP\fB]\fP +This shall be the equivalent of the \fB~f\fP command escape, except +that all headers shall be included in the message, +regardless of previous \fBdiscard\fP, \fBignore\fP, and \fBretain\fP +commands. +.TP 7 +\fB~h\fP +If standard input is a terminal, prompt for a \fBSubject\fP line and +the \fBTo\fP, \fBCc\fP, and \fBBcc\fP lists. Other +implementation-defined headers may also be presented for editing. +If the field is written with an initial value, it can be edited +as if it had just been typed. +.TP 7 +\fB~i\ \fP \fIstring\fP +Insert the value of the named variable, followed by a , into +the text of the message. If the string is unset or +null, the message shall not be changed. +.TP 7 +\fB~m\ [\fP\fImsglist\fP\fB]\fP +Insert the specified messages into the message, prefixing non-empty +lines with the string in the \fBindentprefix\fP variable. +This command escape also shall insert message headers into the message, +with field selection affected by the \fBdiscard\fP, +\fBignore\fP, and \fBretain\fP commands. +.TP 7 +\fB~M\ [\fP\fImsglist\fP\fB]\fP +This shall be the equivalent of the \fB~m\fP command escape, except +that all headers shall be included in the message, +regardless of previous \fBdiscard\fP, \fBignore\fP, and \fBretain\fP +commands. +.TP 7 +\fB~p\fP +Write the message being entered. If the message is longer than \fBcrt\fP +lines (see Internal +Variables in mailx ), the output shall be paginated as described for +the \fIPAGER\fP variable. +.TP 7 +\fB~q\fP +Quit (see the \fBquit\fP command) from input mode by simulating an +interrupt. If the body of the message is not empty, the +partial message shall be saved in the dead-letter file. See \fIDEAD\fP +for a description of this file. +.TP 7 +\fB~r\ \fP \fIfile\fP,\ \fB~<\ \fP +\fIfile\fP,\ \fB~r\ !\fP\fIcommand\fP,\ \fB~<\ !\fP\fIcommand\fP +.sp +Read in the file specified by the pathname \fIfile\fP. If the argument +begins with an exclamation mark ( \fB'!'\fP ), the rest +of the string shall be taken as an arbitrary system command; the command +interpreter specified by \fISHELL\fP shall be invoked +with two arguments: \fB-c\fP and \fIcommand\fP. The standard output +of \fIcommand\fP shall be inserted into the message. +.TP 7 +\fB~s\ \fP \fIstring\fP +Set the subject line to \fIstring\fP. +.TP 7 +\fB~t\ \fP \fIname\fP... +Add the given \fIname\fPs to the \fBTo\fP list. +.TP 7 +\fB~v\fP +Invoke the full-screen editor, as specified by the \fIVISUAL\fP environment +variable, on the partial message. +.TP 7 +\fB~w\ \fP \fIfile\fP +Write the partial message, without the header, onto the file named +by the pathname \fIfile\fP. The file shall be created or +the message shall be appended to it if the file exists. +.TP 7 +\fB~x\fP +Exit as with \fB~q\fP, except the message shall not be saved in the +dead-letter file. +.TP 7 +\fB~|\ \fP \fIcommand\fP +Pipe the body of the message through the given \fIcommand\fP by invoking +the command interpreter specified by \fISHELL\fP +with two arguments: \fB-c\fP and \fIcommand\fP. If the \fIcommand\fP +returns a successful exit status, the standard output of +the command shall replace the message. Otherwise, the message shall +remain unchanged. If the \fIcommand\fP fails, an error message +giving the exit status shall be written. +.sp +.SH EXIT STATUS +.LP +When the \fB-e\fP option is specified, the following exit values are +returned: +.TP 7 +\ 0 +Mail was found. +.TP 7 +>0 +Mail was not found or an error occurred. +.sp +.LP +Otherwise, the following exit values are returned: +.TP 7 +\ 0 +Successful completion; note that this status implies that all messages +were \fIsent\fP, but it gives no assurances that any of +them were actually \fIdelivered\fP. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +When in input mode (Receive Mode) or Send Mode: +.IP " *" 3 +If an error is encountered processing a command escape (see Command +Escapes in mailx ), a +diagnostic message shall be written to standard error, and the message +being composed may be modified, but this condition shall not +prevent the message from being sent. +.LP +.IP " *" 3 +Other errors shall prevent the sending of the message. +.LP +.LP +When in command mode: +.IP " *" 3 +Default. +.LP +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Delivery of messages to remote systems requires the existence of communication +paths to such systems. These need not exist. +.LP +Input lines are limited to {LINE_MAX} bytes, but mailers between systems +may impose more severe line-length restrictions. This +volume of IEEE\ Std\ 1003.1-2001 does not place any restrictions on +the length of messages handled by \fImailx\fP, and for +delivery of local messages the only limitations should be the normal +problems of available disk space for the target mail file. +When sending messages to external machines, applications are advised +to limit messages to less than 100000 bytes because some mail +gateways impose message-length restrictions. +.LP +The format of the system mailbox is intentionally unspecified. Not +all systems implement system mailboxes as flat files, +particularly with the advent of multimedia mail messages. Some system +mailboxes may be multiple files, others records in a +database. The internal format of the messages themselves is specified +with the historical format from Version\ 7, but only +after the messages have been saved in some file other than the system +mailbox. This was done so that many historical applications +expecting text-file mailboxes are not broken. +.LP +Some new formats for messages can be expected in the future, probably +including binary data, bit maps, and various multimedia +objects. As described here, \fImailx\fP is not prohibited from handling +such messages, but it must store them as text files in +secondary mailboxes (unless some extension, such as a variable or +command line option, is used to change the stored format). Its +method of doing so is implementation-defined and might include translating +the data into text file-compatible or readable form or +omitting certain portions of the message from the stored output. +.LP +The \fBdiscard\fP and \fBignore\fP commands are not inverses of the +\fBretain\fP command. The \fBretain\fP command discards +all header-fields except those explicitly retained. The \fBdiscard\fP +command keeps all header-fields except those explicitly +discarded. If headers exist on the retained header list, \fBdiscard\fP +and \fBignore\fP commands are ignored. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The standard developers felt strongly that a method for applications +to send messages to specific users was necessary. The +obvious example is a batch utility, running non-interactively, that +wishes to communicate errors or results to a user. However, the +actual format, delivery mechanism, and method of reading the message +are clearly beyond the scope of this volume of +IEEE\ Std\ 1003.1-2001. +.LP +The intent of this command is to provide a simple, portable interface +for sending messages non-interactively. It merely defines +a "front-end" to the historical mail system. It is suggested that +implementations explicitly denote the sender and recipient in +the body of the delivered message. Further specification of formats +for either the message envelope or the message itself were +deliberately not made, as the industry is in the midst of changing +from the current standards to a more internationalized standard +and it is probably incorrect, at this time, to require either one. +.LP +Implementations are encouraged to conform to the various delivery +mechanisms described in the CCITT X.400 standards or to the +equivalent Internet standards, described in Internet Request for Comment +(RFC) documents RFC\ 819, RFC\ 822, RFC\ 920, +RFC\ 921, and RFC\ 1123. +.LP +Many historical systems modified each body line that started with +\fBFrom\ \fP by prefixing the \fB'F'\fP with +\fB'>'\fP . It is unnecessary, but allowed, to do that when the string +does not follow a blank line because it cannot be +confused with the next header. +.LP +The \fBedit\fP and \fBvisual\fP commands merely edit the specified +messages in a temporary file. They do not modify the +contents of those messages in the mailbox; such a capability could +be added as an extension, such as by using different command +names. +.LP +The restriction on a subject line being {LINE_MAX}-10 bytes is based +on the historical format that consumes 10 bytes for +\fBSubject:\ \fP and the trailing . Many historical mailers +that a message may encounter on other systems are +not able to handle lines that long, however. +.LP +Like the utilities \fIlogger\fP and \fIlp\fP, +\fImailx\fP admittedly is difficult to test. This was not deemed sufficient +justification to exclude this utility from this volume +of IEEE\ Std\ 1003.1-2001. It is also arguable that it is, in fact, +testable, but that the tests themselves are not +portable. +.LP +When \fImailx\fP is being used by an application that wishes to receive +the results as if none of the User Portability +Utilities option features were supported, the \fIDEAD\fP environment +variable must be set to \fB/dev/null\fP. Otherwise, it may +be subject to the file creations described in \fImailx\fP ASYNCHRONOUS +EVENTS. Similarly, if the \fIMAILRC\fP environment +variable is not set to \fB/dev/null\fP, historical versions of \fImailx\fP +and \fIMail\fP read initialization commands from a +file before processing begins. Since the initialization that a user +specifies could alter the contents of messages an application +is trying to send, such applications must set \fIMAILRC\fP to \fB/dev/null\fP. +.LP +The description of \fILC_TIME\fP uses "may affect" because many historical +implementations do not or cannot manipulate the +date and time strings in the incoming mail headers. Some headers found +in incoming mail do not have enough information to determine +the timezone in which the mail originated, and, therefore, \fImailx\fP +cannot convert the date and time strings into the internal +form that then is parsed by routines like \fIstrftime\fP() that can +take \fILC_TIME\fP +settings into account. Changing all these times to a user-specified +format is allowed, but not required. +.LP +The paginator selected when \fIPAGER\fP is null or unset is partially +unspecified to allow the System V historical practice of +using \fIpg\fP as the default. Bypassing the pagination function, +such as by declaring that \fIcat\fP is the paginator, would not meet +with the intended meaning of this description. However, any +"portable user" would have to set \fIPAGER\fP explicitly to get his +or her preferred paginator on all systems. The paginator +choice was made partially unspecified, unlike the \fIVISUAL\fP editor +choice (mandated to be \fIvi\fP) because most historical pagers follow +a common theme of user input, whereas editors differ +dramatically. +.LP +Options to specify addresses as \fBcc\fP (carbon copy) or \fBbcc\fP +(blind carbon copy) were considered to be format details +and were omitted. +.LP +A zero exit status implies that all messages were \fIsent\fP, but +it gives no assurances that any of them were actually +\fIdelivered\fP. The reliability of the delivery mechanism is unspecified +and is an appropriate marketing distinction between +systems. +.LP +In order to conform to the Utility Syntax Guidelines, a solution was +required to the optional \fIfile\fP option-argument to +\fB-f\fP. By making \fIfile\fP an operand, the guidelines are satisfied +and users remain portable. However, it does force +implementations to support usage such as: +.sp +.RS +.nf + +\fBmailx -fin mymail.box +\fP +.fi +.RE +.LP +The \fBno\fP \fIname\fP method of unsetting variables is not present +in all historical systems, but it is in System V and +provides a logical set of commands corresponding to the format of +the display of options from the \fImailx\fP \fIset\fP command without +arguments. +.LP +The \fBask\fP and \fBasksub\fP variables are the names selected by +BSD and System V, respectively, for the same feature. They +are synonyms in this volume of IEEE\ Std\ 1003.1-2001. +.LP +The \fImailx\fP \fIecho\fP command was not documented in the BSD version +and has been +omitted here because it is not obviously useful for interactive users. +.LP +The default prompt on the System V \fImailx\fP is a question mark, +on BSD \fIMail\fP an ampersand. Since this volume of +IEEE\ Std\ 1003.1-2001 chose the \fImailx\fP name, it kept the System +V default, assuming that BSD users would not have +difficulty with this minor incompatibility (that they can override). +.LP +The meanings of \fBr\fP and \fBR\fP are reversed between System V +\fImailx\fP and SunOS \fIMail\fP. Once again, since this +volume of IEEE\ Std\ 1003.1-2001 chose the \fImailx\fP name, it kept +the System V default, but allows the SunOS user to +achieve the desired results using \fBflipr\fP, an internal variable +in System V \fImailx\fP, although it has not been documented +in the SVID. +.LP +The \fBindentprefix\fP variable, the \fBretain\fP and \fBunalias\fP +commands, and the \fB~F\fP and \fB~M\fP +command escapes were adopted from 4.3 BSD \fIMail\fP. +.LP +The \fBversion\fP command was not included because no sufficiently +general specification of the version information could be +devised that would still be useful to a portable user. This command +name should be used by suppliers who wish to provide version +information about the \fImailx\fP command. +.LP +The "implementation-specific (unspecified) system start-up file" historically +has been named \fB/etc/mailx.rc\fP, but this +specific name and location are not required. +.LP +The intent of the wording for the \fBnext\fP command is that if any +command has already displayed the current message it should +display a following message, but, otherwise, it should display the +current message. Consider the command sequence: +.sp +.RS +.nf + +\fBnext 3 +delete 3 +next +\fP +.fi +.RE +.LP +where the \fBautoprint\fP option was not set. The normative text specifies +that the second \fBnext\fP command should display a +message following the third message, because even though the current +message has not been displayed since it was set by the +\fBdelete\fP command, it has been displayed since the current message +was anything other than message number 3. This does not +always match historical practice in some implementations, where the +command file address followed by \fBnext\fP (or the default +command) would skip the message for which the user had searched. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP , \fIed\fP , \fIls\fP , \fImore\fP , +\fIvi\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/make.1p b/man1p/make.1p new file mode 100644 index 000000000..1846bf842 --- /dev/null +++ b/man1p/make.1p @@ -0,0 +1,1753 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MAKE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" make +.SH NAME +make \- maintain, update, and regenerate groups of programs (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBmake\fP \fB[\fP\fB-einpqrst\fP\fB][\fP\fB-f\fP \fImakefile\fP\fB]\fP\fB...\fP\fB[\fP +\fB-k| -S\fP\fB][\fP\fImacro\fP\fB=\fP\fIvalue\fP\fB]\fP\fB... +.br +\ \ \ \ \ \ \fP \fB[\fP\fItarget_name\fP\fB...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fImake\fP utility shall update files that are derived from other +files. A typical case is one where object files are +derived from the corresponding source files. The \fImake\fP utility +examines time relationships and shall update those derived +files (called targets) that have modified times earlier than the modified +times of the files (called prerequisites) from which they +are derived. A description file (makefile) contains a description +of the relationships between files, and the commands that need to +be executed to update the targets to reflect changes in their prerequisites. +Each specification, or rule, shall consist of a +target, optional prerequisites, and optional commands to be executed +when a prerequisite is newer than the target. There are two +types of rule: +.IP " 1." 4 +\fIInference rules\fP, which have one target name with at least one +period ( \fB'.'\fP ) and no slash ( \fB'/'\fP ) +.LP +.IP " 2." 4 +\fITarget rules\fP, which can have more than one target name +.LP +.LP +In addition, \fImake\fP shall have a collection of built-in macros +and inference rules that infer prerequisite relationships to +simplify maintenance of programs. +.LP +To receive exactly the behavior described in this section, the user +shall ensure that a portable makefile shall: +.IP " *" 3 +Include the special target \fB.POSIX\fP +.LP +.IP " *" 3 +Omit any special target reserved for implementations (a leading period +followed by uppercase letters) that has not been +specified by this section +.LP +.LP +The behavior of \fImake\fP is unspecified if either or both of these +conditions are not met. +.SH OPTIONS +.LP +The \fImake\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-e\fP +Cause environment variables, including those with null values, to +override macro assignments within makefiles. +.TP 7 +\fB-f\ \fP \fImakefile\fP +Specify a different makefile. The argument \fImakefile\fP is a pathname +of a description file, which is also referred to as +the \fImakefile\fP. A pathname of \fB'-'\fP shall denote the standard +input. There can be multiple instances of this option, +and they shall be processed in the order specified. The effect of +specifying the same option-argument more than once is +unspecified. +.TP 7 +\fB-i\fP +Ignore error codes returned by invoked commands. This mode is the +same as if the special target \fB.IGNORE\fP were specified +without prerequisites. +.TP 7 +\fB-k\fP +Continue to update other targets that do not depend on the current +target if a non-ignored error occurs while executing the +commands to bring a target up-to-date. +.TP 7 +\fB-n\fP +Write commands that would be executed on standard output, but do not +execute them. However, lines with a plus sign ( +\fB'+'\fP ) prefix shall be executed. In this mode, lines with an +at sign ( \fB'@'\fP ) character prefix shall be written to +standard output. +.TP 7 +\fB-p\fP +Write to standard output the complete set of macro definitions and +target descriptions. The output format is unspecified. +.TP 7 +\fB-q\fP +Return a zero exit value if the target file is up-to-date; otherwise, +return an exit value of 1. Targets shall not be updated +if this option is specified. However, a makefile command line (associated +with the targets) with a plus sign ( \fB'+'\fP ) +prefix shall be executed. +.TP 7 +\fB-r\fP +Clear the suffix list and do not use the built-in rules. +.TP 7 +\fB-S\fP +Terminate \fImake\fP if an error occurs while executing the commands +to bring a target up-to-date. This shall be the default +and the opposite of \fB-k\fP. +.TP 7 +\fB-s\fP +Do not write makefile command lines or touch messages (see \fB-t\fP) +to standard output before executing. This mode shall be +the same as if the special target \fB.SILENT\fP were specified without +prerequisites. +.TP 7 +\fB-t\fP +Update the modification time of each target as though a \fItouch\fP +\fItarget\fP had +been executed. Targets that have prerequisites but no commands (see +Target Rules ), or that are +already up-to-date, shall not be touched in this manner. Write messages +to standard output for each target file indicating the name +of the file and that it was touched. Normally, the \fImakefile\fP +command lines associated with each target are not executed. +However, a command line with a plus sign ( \fB'+'\fP ) prefix shall +be executed. +.sp +.LP +Any options specified in the \fIMAKEFLAGS\fP environment variable +shall be evaluated before any options specified on the +\fImake\fP utility command line. If the \fB-k\fP and \fB-S\fP options +are both specified on the \fImake\fP utility command line +or by the \fIMAKEFLAGS\fP environment variable, the last option specified +shall take precedence. If the \fB-f\fP or \fB-p\fP +options appear in the \fIMAKEFLAGS\fP environment variable, the result +is undefined. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fItarget_name\fP +Target names, as defined in the EXTENDED DESCRIPTION section. If no +target is specified, while \fImake\fP is processing the +makefiles, the first target that \fImake\fP encounters that is not +a special target or an inference rule shall be used. +.TP 7 +\fImacro\fP=\fIvalue\fP +Macro definitions, as defined in Macros . +.sp +.LP +If the \fItarget_name\fP and \fImacro\fP= \fIvalue\fP operands are +intermixed on the \fImake\fP utility command line, the +results are unspecified. +.SH STDIN +.LP +The standard input shall be used only if the \fImakefile\fP option-argument +is \fB'-'\fP . See the INPUT FILES section. +.SH INPUT FILES +.LP +The input file, otherwise known as the makefile, is a text file containing +rules, macro definitions, and comments. See the +EXTENDED DESCRIPTION section. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fImake\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fIMAKEFLAGS\fP +.sp +This variable shall be interpreted as a character string representing +a series of option characters to be used as the default +options. The implementation shall accept both of the following formats +(but need not accept them when intermixed): +.RS +.IP " *" 3 +The characters are option letters without the leading hyphens or +separation used on a \fImake\fP utility command +line. +.LP +.IP " *" 3 +The characters are formatted in a manner similar to a portion of the +\fImake\fP utility command line: options are preceded by +hyphens and -separated as described in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +The \fImacro\fP= \fIvalue\fP macro +definition operands can also be included. The difference between the +contents of \fIMAKEFLAGS\fP and the \fImake\fP utility +command line is that the contents of the variable shall not be subjected +to the word expansions (see \fIWord Expansions\fP ) associated with +parsing the command line values. +.LP +.RE +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPROJECTDIR\fP +.sp +Provide a directory to be used to search for SCCS files not found +in the current directory. In all of the following cases, the +search for SCCS files is made in the directory \fBSCCS\fP in the identified +directory. If the value of \fIPROJECTDIR\fP begins +with a slash, it shall be considered an absolute pathname; otherwise, +the value of \fIPROJECTDIR\fP is treated as a user name and +that user's initial working directory shall be examined for a subdirectory +\fBsrc\fP or \fBsource\fP. If such a directory is +found, it shall be used. Otherwise, the value is used as a relative +pathname. +.LP +If \fIPROJECTDIR\fP is not set or has a null value, the search for +SCCS files shall be made in the directory \fBSCCS\fP in the +current directory. +.LP +The setting of \fIPROJECTDIR\fP affects all files listed in the remainder +of this utility description for files with a +component named \fBSCCS\fP. +.sp +.LP +The value of the \fISHELL\fP environment variable shall not be used +as a macro and shall not be modified by defining the +\fBSHELL\fP macro in a makefile or on the command line. All other +environment variables, including those with null values, shall +be used as macros, as defined in Macros . +.SH ASYNCHRONOUS EVENTS +.LP +If not already ignored, \fImake\fP shall trap SIGHUP, SIGTERM, SIGINT, +and SIGQUIT and remove the current target unless the +target is a directory or the target is a prerequisite of the special +target \fB.PRECIOUS\fP or unless one of the \fB-n\fP, +\fB-p\fP, or \fB-q\fP options was specified. Any targets removed in +this manner shall be reported in diagnostic messages of +unspecified format, written to standard error. After this cleanup +process, if any, \fImake\fP shall take the standard action for +all other signals. +.SH STDOUT +.LP +The \fImake\fP utility shall write all commands to be executed to +standard output unless the \fB-s\fP option was specified, +the command is prefixed with an at sign, or the special target \fB.SILENT\fP +has either the current target as a prerequisite or +has no prerequisites. If \fImake\fP is invoked without any work needing +to be done, it shall write a message to standard output +indicating that no action was taken. If the \fB-t\fP option is present +and a file is touched, \fImake\fP shall write to standard +output a message of unspecified format indicating that the file was +touched, including the filename of the file. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +Files can be created when the \fB-t\fP option is present. Additional +files can also be created by the utilities invoked by +\fImake\fP. +.SH EXTENDED DESCRIPTION +.LP +The \fImake\fP utility attempts to perform the actions required to +ensure that the specified targets are up-to-date. A target +is considered out-of-date if it is older than any of its prerequisites +or if it does not exist. The \fImake\fP utility shall treat +all prerequisites as targets themselves and recursively ensure that +they are up-to-date, processing them in the order in which they +appear in the rule. The \fImake\fP utility shall use the modification +times of files to determine whether the corresponding +targets are out-of-date. +.LP +After \fImake\fP has ensured that all of the prerequisites of a target +are up-to-date and if the target is out-of-date, the +commands associated with the target entry shall be executed. If there +are no commands listed for the target, the target shall be +treated as up-to-date. +.SS Makefile Syntax +.LP +A makefile can contain rules, macro definitions (see Macros ), and +comments. There are two kinds +of rules: \fIinference rules\fP and \fItarget rules\fP. The \fImake\fP +utility shall contain a set of built-in inference rules. +If the \fB-r\fP option is present, the built-in rules shall not be +used and the suffix list shall be cleared. Additional rules of +both types can be specified in a makefile. If a rule is defined more +than once, the value of the rule shall be that of the last one +specified. Macros can also be defined more than once, and the value +of the macro is specified in Macros . Comments start with a number +sign ( \fB'#'\fP ) and continue until an unescaped +is reached. +.LP +By default, the following files shall be tried in sequence: \fB./makefile\fP +and \fB./Makefile\fP. If neither +\fB\&./makefile\fP or \fB./Makefile\fP are found, other implementation-defined +files may also be tried. \ On +XSI-conformant systems, the additional files \fB./s.makefile\fP, \fBSCCS/s.makefile\fP, +\fB\&./s.Makefile\fP, and +\fBSCCS/s.Makefile\fP shall also be tried. +.LP +The \fB-f\fP option shall direct \fImake\fP to ignore any of these +default files and use the specified argument as a makefile +instead. If the \fB'-'\fP argument is specified, standard input shall +be used. +.LP +The term \fImakefile\fP is used to refer to any rules provided by +the user, whether in \fB./makefile\fP or its variants, or +specified by the \fB-f\fP option. +.LP +The rules in makefiles shall consist of the following types of lines: +target rules, including special targets (see Target Rules ), inference +rules (see Inference Rules ), macro definitions +(see Macros ), empty lines, and comments. +.LP +When an escaped (one preceded by a backslash) is found anywhere +in the makefile except in a command line, it +shall be replaced, along with any leading white space on the following +line, with a single . When an escaped + is found in a command line in a makefile, the command line +shall contain the backslash, the , and +the next line, except that the first character of the next line shall +not be included if it is a . +.SS Makefile Execution +.LP +Makefile command lines shall be processed one at a time by writing +the makefile command line to the standard output (unless one +of the conditions listed under \fB'@'\fP suppresses the writing) and +executing the command(s) in the line. A may +precede the command to standard output. Command execution shall be +as if the makefile command line were the argument to the \fIsystem\fP() +function. The environment for the command being executed shall contain +all of +the variables in the environment of \fImake\fP. +.LP +By default, when \fImake\fP receives a non-zero status from the execution +of a command, it shall terminate with an error +message to standard error. +.LP +Makefile command lines can have one or more of the following prefixes: +a hyphen ( \fB'-'\fP ), an at sign ( \fB'@'\fP ), +or a plus sign ( \fB'+'\fP ). These shall modify the way in which +\fImake\fP processes the command. When a command is written +to standard output, the prefix shall not be included in the output. +.TP 7 +\fB-\fP +If the command prefix contains a hyphen, or the \fB-i\fP option is +present, or the special target \fB.IGNORE\fP has either +the current target as a prerequisite or has no prerequisites, any +error found while executing the command shall be ignored. +.TP 7 +\fB@\fP +If the command prefix contains an at sign and the \fImake\fP utility +command line \fB-n\fP option is not specified, or the +\fB-s\fP option is present, or the special target \fB.SILENT\fP has +either the current target as a prerequisite or has no +prerequisites, the command shall not be written to standard output +before it is executed. +.TP 7 +\fB+\fP +If the command prefix contains a plus sign, this indicates a makefile +command line that shall be executed even if \fB-n\fP, +\fB-q\fP, or \fB-t\fP is specified. +.sp +.SS Target Rules +.LP +Target rules are formatted as follows: +.sp +.RS +.nf + +\fItarget\fP \fB[\fP\fItarget\fP\fB...\fP\fB]\fP\fB:\fP \fB[\fP\fIprerequisite\fP\fB...\fP\fB][;\fP\fIcommand\fP\fB] +[\fP\fB\fP\fIcommand\fP\fB\fP\fIcommand\fP\fB...\fP\fB]\fP\fB +.br + +\fP\fIline that does not begin with\fP \fB +\fP +.fi +.RE +.LP +Target entries are specified by a -separated, non-null list +of targets, then a colon, then a +-separated, possibly empty list of prerequisites. Text following +a semicolon, if any, and all following lines that +begin with a , are makefile command lines to be executed to update +the target. The first non-empty line that does not +begin with a or \fB'#'\fP shall begin a new entry. An empty +or blank line, or a line beginning with \fB'#'\fP , +may begin a new entry. +.LP +Applications shall select target names from the set of characters +consisting solely of periods, underscores, digits, and +alphabetics from the portable character set (see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable Character +Set). Implementations may allow other characters in +target names as extensions. The interpretation of targets containing +the characters \fB'%'\fP and \fB''\fP is +implementation-defined. +.LP +A target that has prerequisites, but does not have any commands, can +be used to add to the prerequisite list for that target. +Only one target rule for any given target can contain commands. +.LP +Lines that begin with one of the following are called \fIspecial targets\fP +and control the operation of \fImake\fP: +.TP 7 +\fB\&.DEFAULT\fP +If the makefile uses this special target, the application shall ensure +that it is specified with commands, but without +prerequisites. The commands shall be used by \fImake\fP if there are +no other rules available to build a target. +.TP 7 +\fB\&.IGNORE\fP +Prerequisites of this special target are targets themselves; this +shall cause errors from commands associated with them to be +ignored in the same manner as specified by the \fB-i\fP option. Subsequent +occurrences of \fB.IGNORE\fP shall add to the list of +targets ignoring command errors. If no prerequisites are specified, +\fImake\fP shall behave as if the \fB-i\fP option had been +specified and errors from all commands associated with all targets +shall be ignored. +.TP 7 +\fB\&.POSIX\fP +The application shall ensure that this special target is specified +without prerequisites or commands. If it appears as the +first non-comment line in the makefile, \fImake\fP shall process the +makefile as specified by this section; otherwise, the +behavior of \fImake\fP is unspecified. +.TP 7 +\fB\&.PRECIOUS\fP +Prerequisites of this special target shall not be removed if \fImake\fP +receives one of the asynchronous events explicitly +described in the ASYNCHRONOUS EVENTS section. Subsequent occurrences +of \fB.PRECIOUS\fP shall add to the list of precious files. +If no prerequisites are specified, all targets in the makefile shall +be treated as if specified with \fB.PRECIOUS\fP. +.TP 7 +\fB\&.SCCS_GET\fP +The application shall ensure that this special target is specified +without prerequisites. If this special target is included in a +makefile, the commands specified with this target shall replace the +default commands associated with this special target (see Default +Rules ). The commands specified with this target are used to get all +SCCS files that are not +found in the current directory. +.LP +When source files are named in a dependency list, \fImake\fP shall +treat them just like any other target. Because the source +file is presumed to be present in the directory, there is no need +to add an entry for it to the makefile. When a target has no +dependencies, but is present in the directory, \fImake\fP shall assume +that that file is up-to-date. If, however, an SCCS file +named \fBSCCS/s.\fP \fIsource_file\fP is found for a target \fIsource_file\fP, +\fImake\fP compares the timestamp of the target +file with that of the \fBSCCS/s.source_file\fP to ensure the target +is up-to-date. If the target is missing, or if the SCCS file +is newer, \fImake\fP shall automatically issue the commands specified +for the \fB.SCCS_GET\fP special target to retrieve the most +recent version. However, if the target is writable by anyone, \fImake\fP +shall not retrieve a new version. +.TP 7 +\fB\&.SILENT\fP +Prerequisites of this special target are targets themselves; this +shall cause commands associated with them not to be written +to the standard output before they are executed. Subsequent occurrences +of \fB.SILENT\fP shall add to the list of targets with +silent commands. If no prerequisites are specified, \fImake\fP shall +behave as if the \fB-s\fP option had been specified and no +commands or touch messages associated with any target shall be written +to standard output. +.TP 7 +\fB\&.SUFFIXES\fP +Prerequisites of \fB.SUFFIXES\fP shall be appended to the list of +known suffixes and are used in conjunction with the +inference rules (see Inference Rules ). If \fB.SUFFIXES\fP does not +have any prerequisites, the +list of known suffixes shall be cleared. +.sp +.LP +The special targets \fB.IGNORE\fP, \fB.POSIX\fP, \fB.PRECIOUS\fP, +\fB\&.SILENT\fP, and \fB.SUFFIXES\fP shall be specified +without commands. +.LP +Targets with names consisting of a leading period followed by the +uppercase letters \fB"POSIX"\fP and then any other +characters are reserved for future standardization. Targets with names +consisting of a leading period followed by one or more +uppercase letters are reserved for implementation extensions. +.SS Macros +.LP +Macro definitions are in the form: +.sp +.RS +.nf + +\fIstring1\fP \fB=\fP \fB[\fP\fIstring2\fP\fB]\fP +.fi +.RE +.LP +The macro named \fIstring1\fP is defined as having the value of \fIstring2\fP, +where \fIstring2\fP is defined as all +characters, if any, after the equal sign, up to a comment character +( \fB'#'\fP ) or an unescaped . Any +s immediately before or after the equal sign shall be ignored. +.LP +Applications shall select macro names from the set of characters consisting +solely of periods, underscores, digits, and +alphabetics from the portable character set (see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable Character +Set). A macro name shall not contain an equals sign. +Implementations may allow other characters in macro names as extensions. +.LP +Macros can appear anywhere in the makefile. Macro expansions using +the forms $( \fIstring1\fP) or ${ \fIstring1\fP} shall be +replaced by \fIstring2\fP, as follows: +.IP " *" 3 +Macros in target lines shall be evaluated when the target line is +read. +.LP +.IP " *" 3 +Macros in makefile command lines shall be evaluated when the command +is executed. +.LP +.IP " *" 3 +Macros in the string before the equals sign in a macro definition +shall be evaluated when the macro assignment is made. +.LP +.IP " *" 3 +Macros after the equals sign in a macro definition shall not be evaluated +until the defined macro is used in a rule or command, +or before the equals sign in a macro definition. +.LP +.LP +The parentheses or braces are optional if \fIstring1\fP is a single +character. The macro $$ shall be replaced by the single +character \fB'$'\fP . If \fIstring1\fP in a macro expansion contains +a macro expansion, the results are unspecified. +.LP +Macro expansions using the forms $( \fIstring1\fP \fB[:\fP \fIsubst1\fP +\fB=[\fP \fIsubst2\fP \fB]]\fP) or ${ +\fIstring1\fP \fB[:\fP \fIsubst1\fP \fB=[\fP \fIsubst2\fP \fB]]\fP} +can be used to replace all occurrences of \fIsubst1\fP +with \fIsubst2\fP when the macro substitution is performed. The \fIsubst1\fP +to be replaced shall be recognized when it is a +suffix at the end of a word in \fIstring1\fP (where a \fIword\fP, +in this context, is defined to be a string delimited by the +beginning of the line, a , or a ). If \fIstring1\fP +in a macro expansion contains a macro expansion, +the results are unspecified. +.LP +Macro expansions in \fIstring1\fP of macro definition lines shall +be evaluated when read. Macro expansions in \fIstring2\fP of +macro definition lines shall be performed when the macro identified +by \fIstring1\fP is expanded in a rule or command. +.LP +Macro definitions shall be taken from the following sources, in the +following logical order, before the makefile(s) are +read. +.IP " 1." 4 +Macros specified on the \fImake\fP utility command line, in the order +specified on the command line. It is unspecified whether +the internal macros defined in Internal Macros are accepted from this +source. +.LP +.IP " 2." 4 +Macros defined by the \fIMAKEFLAGS\fP environment variable, in the +order specified in the environment variable. It is +unspecified whether the internal macros defined in Internal Macros +are accepted from this +source. +.LP +.IP " 3." 4 +The contents of the environment, excluding the \fIMAKEFLAGS\fP and +\fISHELL\fP variables and including the variables with null +values. +.LP +.IP " 4." 4 +Macros defined in the inference rules built into \fImake\fP. +.LP +.LP +Macro definitions from these sources shall not override macro definitions +from a lower-numbered source. Macro definitions from a +single source (for example, the \fImake\fP utility command line, the +\fIMAKEFLAGS\fP environment variable, or the other +environment variables) shall override previous macro definitions from +the same source. +.LP +Macros defined in the makefile(s) shall override macro definitions +that occur before them in the makefile(s) and macro +definitions from source 4. If the \fB-e\fP option is not specified, +macros defined in the makefile(s) shall override macro +definitions from source 3. Macros defined in the makefile(s) shall +not override macro definitions from source 1 or source 2. +.LP +Before the makefile(s) are read, all of the \fImake\fP utility command +line options (except \fB-f\fP and \fB-p\fP) and +\fImake\fP utility command line macro definitions (except any for +the \fIMAKEFLAGS\fP macro), not already included in the +\fIMAKEFLAGS\fP macro, shall be added to the \fIMAKEFLAGS\fP macro, +quoted in an implementation-defined manner such that when +\fIMAKEFLAGS\fP is read by another instance of the \fImake\fP command, +the original macro's value is recovered. Other +implementation-defined options and macros may also be added to the +\fIMAKEFLAGS\fP macro. If this modifies the value of the +\fIMAKEFLAGS\fP macro, or, if the \fIMAKEFLAGS\fP macro is modified +at any subsequent time, the \fIMAKEFLAGS\fP environment +variable shall be modified to match the new value of the \fIMAKEFLAGS\fP +macro. The result of setting \fIMAKEFLAGS\fP in the +Makefile is unspecified. +.LP +Before the makefile(s) are read, all of the \fImake\fP utility command +line macro definitions (except the \fIMAKEFLAGS\fP +macro or the \fISHELL\fP macro) shall be added to the environment +of \fImake\fP. Other implementation-defined variables may also +be added to the environment of \fImake\fP. +.LP +The \fBSHELL\fP macro shall be treated specially. It shall be provided +by \fImake\fP and set to the pathname of the shell +command language interpreter (see \fIsh\fP ). The \fISHELL\fP environment +variable shall not affect the +value of the \fBSHELL\fP macro. If \fBSHELL\fP is defined in the makefile +or is specified on the command line, it shall replace +the original value of the \fBSHELL\fP macro, but shall not affect +the \fISHELL\fP environment variable. Other effects of defining +\fBSHELL\fP in the makefile or on the command line are implementation-defined. +.SS Inference Rules +.LP +Inference rules are formatted as follows: +.sp +.RS +.nf + +\fItarget\fP\fB: +\fP\fIcommand +\fP\fB[\fP\fB\fP\fIcommand\fP\fB]\fP\fB... +.sp + +\fP\fIline that does not begin with\fP \fB\fP \fIor\fP \fB# +\fP +.fi +.RE +.LP +The application shall ensure that the \fItarget\fP portion is a valid +target name (see Target +Rules ) of the form \fB.s2\fP or \fB.s1.s2\fP (where \fB.s1\fP and +\fB\&.s2\fP are suffixes that have been given as +prerequisites of the \fB.SUFFIXES\fP special target and \fIs1\fP and +\fIs2\fP do not contain any slashes or periods.) If there +is only one period in the target, it is a single-suffix inference +rule. Targets with two periods are double-suffix inference rules. +Inference rules can have only one target before the colon. +.LP +The application shall ensure that the makefile does not specify prerequisites +for inference rules; no characters other than +white space shall follow the colon in the first line, except when +creating the \fIempty rule,\fP described below. Prerequisites +are inferred, as described below. +.LP +Inference rules can be redefined. A target that matches an existing +inference rule shall overwrite the old inference rule. An +empty rule can be created with a command consisting of simply a semicolon +(that is, the rule still exists and is found during +inference rule search, but since it is empty, execution has no effect). +The empty rule can also be formatted as follows: +.sp +.RS +.nf + +\fIrule\fP\fB: ; +\fP +.fi +.RE +.LP +where zero or more s separate the colon and semicolon. +.LP +The \fImake\fP utility uses the suffixes of targets and their prerequisites +to infer how a target can be made up-to-date. A +list of inference rules defines the commands to be executed. By default, +\fImake\fP contains a built-in set of inference rules. +Additional rules can be specified in the makefile. +.LP +The special target \fB.SUFFIXES\fP contains as its prerequisites a +list of suffixes that shall be used by the inference rules. +The order in which the suffixes are specified defines the order in +which the inference rules for the suffixes are used. New +suffixes shall be appended to the current list by specifying a \fB.SUFFIXES\fP +special target in the makefile. A \fB.SUFFIXES\fP +target with no prerequisites shall clear the list of suffixes. An +empty \fB.SUFFIXES\fP target followed by a new \fB.SUFFIXES\fP +list is required to change the order of the suffixes. +.LP +Normally, the user would provide an inference rule for each suffix. +The inference rule to update a target with a suffix +\fB\&.s1\fP from a prerequisite with a suffix \fB.s2\fP is specified +as a target \fB.s2.s1\fP. The internal macros provide the +means to specify general inference rules (see Internal Macros ). +.LP +When no target rule is found to update a target, the inference rules +shall be checked. The suffix of the target ( \fB.s1\fP) to +be built is compared to the list of suffixes specified by the \fB.SUFFIXES\fP +special targets. If the \fB.s1\fP suffix is found +in \fB.SUFFIXES\fP, the inference rules shall be searched in the order +defined for the first \fB.s2.s1\fP rule whose prerequisite +file ( \fB$*.s2\fP) exists. If the target is out-of-date with respect +to this prerequisite, the commands for that inference rule +shall be executed. +.LP +If the target to be built does not contain a suffix and there is no +rule for the target, the single suffix inference rules shall +be checked. The single-suffix inference rules define how to build +a target if a file is found with a name that matches the target +name with one of the single suffixes appended. A rule with one suffix +\fB\&.s2\fP is the definition of how to build \fItarget\fP +from \fBtarget.s2\fP. The other suffix ( \fB.s1\fP) is treated as +null. +.LP +A +tilde ( \fB'~'\fP ) in the above rules refers to an SCCS file in the +current directory. Thus, the rule \fB.c~.o\fP +would transform an SCCS C-language source file into an object file +( \fB.o\fP). Because the \fBs.\fP of the SCCS files is a +prefix, it is incompatible with \fImake\fP's suffix point of view. +Hence, the \fB'~'\fP is a way of changing any file +reference into an SCCS file reference. +.SS Libraries +.LP +If a target or prerequisite contains parentheses, it shall be treated +as a member of an archive library. For the \fIlib\fP( +\fImember\fP \fB.o\fP) expression \fIlib\fP refers to the name of +the archive library and \fImember\fP \fB.o\fP to the member +name. The application shall ensure that the member is an object file +with the \fB.o\fP suffix. The modification time of the +expression is the modification time for the member as kept in the +archive library; see \fIar\fP . The +\fB\&.a\fP suffix shall refer to an archive library. The \fB.s2.a\fP +rule shall be used to update a member in the library from a +file with a suffix \fB.s2\fP. +.SS Internal Macros +.LP +The \fImake\fP utility shall maintain five internal macros that can +be used in target and inference rules. In order to clearly +define the meaning of these macros, some clarification of the terms +\fItarget rule\fP, \fIinference rule\fP, \fItarget\fP, and +\fIprerequisite\fP is necessary. +.LP +Target rules are specified by the user in a makefile for a particular +target. Inference rules are user-specified or +\fImake\fP-specified rules for a particular class of target name. +Explicit prerequisites are those prerequisites specified in a +makefile on target lines. Implicit prerequisites are those prerequisites +that are generated when inference rules are used. +Inference rules are applied to implicit prerequisites or to explicit +prerequisites that do not have target rules defined for them +in the makefile. Target rules are applied to targets specified in +the makefile. +.LP +Before any target in the makefile is updated, each of its prerequisites +(both explicit and implicit) shall be updated. This +shall be accomplished by recursively processing each prerequisite. +Upon recursion, each prerequisite shall become a target itself. +Its prerequisites in turn shall be processed recursively until a target +is found that has no prerequisites, at which point the +recursion stops. The recursion shall then back up, updating each target +as it goes. +.LP +In the definitions that follow, the word \fItarget\fP refers to one +of: +.IP " *" 3 +A target specified in the makefile +.LP +.IP " *" 3 +An explicit prerequisite specified in the makefile that becomes the +target when \fImake\fP processes it during recursion +.LP +.IP " *" 3 +An implicit prerequisite that becomes a target when \fImake\fP processes +it during recursion +.LP +.LP +In the definitions that follow, the word \fIprerequisite\fP refers +to one of the following: +.IP " *" 3 +An explicit prerequisite specified in the makefile for a particular +target +.LP +.IP " *" 3 +An implicit prerequisite generated as a result of locating an appropriate +inference rule and corresponding file that matches the +suffix of the target +.LP +.LP +The five internal macros are: +.TP 7 +$@ +The $@ shall evaluate to the full target name of the current target, +or the archive filename part of a library archive target. +It shall be evaluated for both target and inference rules. +.LP +For example, in the \fB.c.a\fP inference rule, $@ represents the out-of-date +\fB\&.a\fP file to be built. Similarly, in a +makefile target rule to build \fBlib.a\fP from \fBfile.c\fP, $@ represents +the out-of-date \fBlib.a\fP. +.TP 7 +$% +The $% macro shall be evaluated only when the current target is an +archive library member of the form \fIlibname\fP( +\fImember\fP \fB.o\fP). In these cases, $@ shall evaluate to \fIlibname\fP +and $% shall evaluate to \fImember\fP \fB.o\fP. The +$% macro shall be evaluated for both target and inference rules. +.LP +For example, in a makefile target rule to build \fBlib.a\fP( \fBfile.o\fP), +$% represents \fBfile.o\fP, as opposed to $@, +which represents \fBlib.a\fP. +.TP 7 +$? +The $? macro shall evaluate to the list of prerequisites that are +newer than the current target. It shall be evaluated for both +target and inference rules. +.LP +For example, in a makefile target rule to build \fIprog\fP from \fBfile1.o\fP, +\fBfile2.o\fP, and \fBfile3.o\fP, and where +\fIprog\fP is not out-of-date with respect to \fBfile1.o\fP, but is +out-of-date with respect to \fBfile2.o\fP and +\fBfile3.o\fP, $? represents \fBfile2.o\fP and \fBfile3.o\fP. +.TP 7 +$< +In an inference rule, the $< macro shall evaluate to the filename +whose existence allowed the inference rule to be chosen +for the target. In the \fB.DEFAULT\fP rule, the $< macro shall evaluate +to the current target name. The meaning of the $< +macro shall be otherwise unspecified. +.LP +For example, in the \fB.c.a\fP inference rule, $< represents the prerequisite +\fB\&.c\fP file. +.TP 7 +$* +The $* macro shall evaluate to the current target name with its suffix +deleted. It shall be evaluated at least for inference +rules. +.LP +For example, in the \fB.c.a\fP inference rule, $*.o represents the +out-of-date \fB.o\fP file that corresponds to the +prerequisite \fB.c\fP file. +.sp +.LP +Each of the internal macros has an alternative form. When an uppercase +\fB'D'\fP or \fB'F'\fP is appended to any of the +macros, the meaning shall be changed to the \fIdirectory part\fP for +\fB'D'\fP and \fIfilename part\fP for \fB'F'\fP . The +directory part is the path prefix of the file without a trailing slash; +for the current directory, the directory part is +\fB'.'\fP . When the $? macro contains more than one prerequisite +filename, the $(?D) and $(?F) (or ${?D} and ${?F}) macros +expand to a list of directory name parts and filename parts respectively. +.LP +For the target \fIlib\fP( \fImember\fP \fB.o\fP) and the \fBs2.a\fP +rule, the internal macros shall be defined as: +.TP 7 +$< +\fImember\fP \fB.s2\fP +.TP 7 +$* +\fImember\fP +.TP 7 +$@ +\fIlib\fP +.TP 7 +$? +\fImember\fP \fB.s2\fP +.TP 7 +$% +\fImember\fP \fB.o\fP +.sp +.SS Default Rules +.LP +The default rules for \fImake\fP shall achieve results that are the +same as if the following were used. Implementations that do +not support the C-Language Development Utilities option may omit \fBCC\fP, +\fBCFLAGS\fP, \fBYACC\fP, \fBYFLAGS\fP, \fBLEX\fP, +\fBLFLAGS\fP, \fBLDFLAGS\fP, and the \fB.c\fP, \fB.y\fP, and \fB.l\fP +inference rules. Implementations that do not support +FORTRAN may omit \fBFC\fP, \fBFFLAGS\fP, and the \fB.f\fP inference +rules. Implementations may provide additional macros and +rules. +.sp +.RS +.nf + +\fISPECIAL TARGETS\fP\fB +.br + + +\&.SCCS_GET: sccs $(SCCSFLAGS) get $(SCCSGETFLAGS) $@ + +.sp + + +\&.SUFFIXES: .o .c .y .l .a .sh .f .c~ .y~ .l~ .sh~ .f~ +.sp + +\fP\fIMACROS\fP\fB +.br + +MAKE=make +AR=ar +ARFLAGS=-rv +YACC=yacc +YFLAGS= +LEX=lex +LFLAGS= +LDFLAGS= +CC=c99 +CFLAGS=-O +FC=fort77 +FFLAGS=-O 1 + +GET=get +GFLAGS= +SCCSFLAGS= +SCCSGETFLAGS=-s + +.sp + +\fP\fISINGLE SUFFIX RULES\fP\fB +.br + +\&.c: + $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $< +.sp + +\&.f: + $(FC) $(FFLAGS) $(LDFLAGS) -o $@ $< +.sp + +\&.sh: + cp $< $@ + chmod a+x $@ +.sp + + +\&.c~: + $(GET) $(GFLAGS) -p $< > $*.c + $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $*.c +.sp + +\&.f~: + $(GET) $(GFLAGS) -p $< > $*.f + $(FC) $(FFLAGS) $(LDFLAGS) -o $@ $*.f +.sp + +\&.sh~: + $(GET) $(GFLAGS) -p $< > $*.sh + cp $*.sh $@ + chmod a+x $@ + +.sp + +\fP\fIDOUBLE SUFFIX RULES\fP\fB +.br + +\&.c.o: + $(CC) $(CFLAGS) -c $< +.sp + +\&.f.o: + $(FC) $(FFLAGS) -c $< +.sp + +\&.y.o: + $(YACC) $(YFLAGS) $< + $(CC) $(CFLAGS) -c y.tab.c + rm -f y.tab.c + mv y.tab.o $@ +.sp + +\&.l.o: + $(LEX) $(LFLAGS) $< + $(CC) $(CFLAGS) -c lex.yy.c + rm -f lex.yy.c + mv lex.yy.o $@ +.sp + +\&.y.c: + $(YACC) $(YFLAGS) $< + mv y.tab.c $@ +.sp + +\&.l.c: + $(LEX) $(LFLAGS) $< + mv lex.yy.c $@ +.sp + + +\&.c~.o: + $(GET) $(GFLAGS) -p $< > $*.c + $(CC) $(CFLAGS) -c $*.c +.sp + +\&.f~.o: + $(GET) $(GFLAGS) -p $< > $*.f + $(FC) $(FFLAGS) -c $*.f +.sp + +\&.y~.o: + $(GET) $(GFLAGS) -p $< > $*.y + $(YACC) $(YFLAGS) $*.y + $(CC) $(CFLAGS) -c y.tab.c + rm -f y.tab.c + mv y.tab.o $@ +.sp + +\&.l~.o: + $(GET) $(GFLAGS) -p $< > $*.l + $(LEX) $(LFLAGS) $*.l + $(CC) $(CFLAGS) -c lex.yy.c + rm -f lex.yy.c + mv lex.yy.o $@ +.sp + +\&.y~.c: + $(GET) $(GFLAGS) -p $< > $*.y + $(YACC) $(YFLAGS) $*.y + mv y.tab.c $@ +.sp + +\&.l~.c: + $(GET) $(GFLAGS) -p $< > $*.l + $(LEX) $(LFLAGS) $*.l + mv lex.yy.c $@ + +.sp + +\&.c.a: + $(CC) -c $(CFLAGS) $< + $(AR) $(ARFLAGS) $@ $*.o + rm -f $*.o +.sp + +\&.f.a: + $(FC) -c $(FFLAGS) $< + $(AR) $(ARFLAGS) $@ $*.o + rm -f $*.o +\fP +.fi +.RE +.SH EXIT STATUS +.LP +When the \fB-q\fP option is specified, the \fImake\fP utility shall +exit with one of the following values: +.TP 7 +\ 0 +Successful completion. +.TP 7 +\ 1 +The target was not up-to-date. +.TP 7 +>1 +An error occurred. +.sp +.LP +When the \fB-q\fP option is not specified, the \fImake\fP utility +shall exit with one of the following values: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +If there is a source file (such as \fB./source.c\fP) and there are +two SCCS files corresponding to it ( \fB./s.source.c\fP and +\fB\&./SCCS/s.source.c\fP), on XSI-conformant systems \fImake\fP uses +the SCCS file in the current directory. However, users are +advised to use the underlying SCCS utilities ( \fIadmin\fP, \fIdelta\fP, +\fIget\fP, and so on) or the \fIsccs\fP utility for all source files +in a given directory. If both forms are used for a given +source file, future developers are very likely to be confused. +.LP +It is incumbent upon portable makefiles to specify the \fB.POSIX\fP +special target in order to guarantee that they are not +affected by local extensions. +.LP +The \fB-k\fP and \fB-S\fP options are both present so that the relationship +between the command line, the \fIMAKEFLAGS\fP +variable, and the makefile can be controlled precisely. If the \fBk\fP +flag is passed in \fIMAKEFLAGS\fP and a command is of the +form: +.sp +.RS +.nf + +\fB$(MAKE) -S foo +\fP +.fi +.RE +.LP +then the default behavior is restored for the child \fImake\fP. +.LP +When the \fB-n\fP option is specified, it is always added to \fIMAKEFLAGS +\&.\fP This allows a recursive \fImake\fP \fB-n\fP +\fItarget\fP to be used to see all of the action that would be taken +to update \fItarget\fP. +.LP +Because of widespread historical practice, interpreting a \fB'#'\fP +number sign inside a variable as the start of a comment +has the unfortunate side effect of making it impossible to place a +number sign in a variable, thus forbidding something like: +.sp +.RS +.nf + +\fBCFLAGS = "-D COMMENT_CHAR='#'" +\fP +.fi +.RE +.LP +Many historical \fImake\fP utilities stop chaining together inference +rules when an intermediate target is nonexistent. For +example, it might be possible for a \fImake\fP to determine that both +\fB\&.y.c\fP and \fB.c.o\fP could be used to convert a +\fB\&.y\fP to a \fB.o\fP. Instead, in this case, \fImake\fP requires +the use of a \fB.y.o\fP rule. +.LP +The best way to provide portable makefiles is to include all of the +rules needed in the makefile itself. The rules provided use +only features provided by other parts of this volume of IEEE\ Std\ 1003.1-2001. +The default rules include rules for +optional commands in this volume of IEEE\ Std\ 1003.1-2001. Only rules +pertaining to commands that are provided are needed +in an implementation's default set. +.LP +Macros used within other macros are evaluated when the new macro is +used rather than when the new macro is defined. +Therefore: +.sp +.RS +.nf + +\fBMACRO =\fP \fIvalue1\fP\fBNEW = $(MACRO) +MACRO =\fP \fIvalue2\fP\fB +.br + +target: + echo $(NEW) +\fP +.fi +.RE +.LP +would produce \fIvalue2\fP and not \fIvalue1\fP since \fBNEW\fP was +not expanded until it was needed in the \fIecho\fP command line. +.LP +Some historical applications have been known to intermix \fItarget_name\fP +and \fImacro=name\fP operands on the command line, +expecting that all of the macros are processed before any of the targets +are dealt with. Conforming applications do not do this, +although some backwards-compatibility support may be included in some +implementations. +.LP +The following characters in filenames may give trouble: \fB'='\fP +, \fB':'\fP , \fB'`'\fP , \fB'"\fP , and +\fB'@'\fP . For inference rules, the description of $< and $? seem +similar. However, an example shows the minor difference. +In a makefile containing: +.sp +.RS +.nf + +\fBfoo.o: foo.h +\fP +.fi +.RE +.LP +if \fBfoo.h\fP is newer than \fBfoo.o\fP, yet \fBfoo.c\fP is older +than \fBfoo.o\fP, the built-in rule to make \fBfoo.o\fP +from \fBfoo.c\fP is used, with $< equal to \fBfoo.c\fP and $? equal +to \fBfoo.h\fP. If \fBfoo.c\fP is also newer than +\fBfoo.o\fP, $< is equal to \fBfoo.c\fP and $? is equal to \fBfoo.h +foo.c\fP. +.SH EXAMPLES +.IP " 1." 4 +The following command: +.sp +.RS +.nf + +\fBmake +\fP +.fi +.RE +.LP +makes the first target found in the makefile. +.LP +.IP " 2." 4 +The following command: +.sp +.RS +.nf + +\fBmake junk +\fP +.fi +.RE +.LP +makes the target \fBjunk\fP. +.LP +.IP " 3." 4 +The following makefile says that \fBpgm\fP depends on two files, \fBa.o\fP +and \fBb.o\fP, and that they in turn depend on +their corresponding source files ( \fBa.c\fP and \fBb.c\fP), and a +common file \fBincl.h\fP: +.sp +.RS +.nf + +\fBpgm: a.o b.o + c99 a.o b.o -o pgm +a.o: incl.h a.c + c99 -c a.c +b.o: incl.h b.c + c99 -c b.c +\fP +.fi +.RE +.LP +.IP " 4." 4 +An example for making optimized \fB.o\fP files from \fB.c\fP files +is: +.sp +.RS +.nf + +\fB\&.c.o: + c99 -c -O $*.c +\fP +.fi +.RE +.LP +or: +.sp +.RS +.nf + +\fB\&.c.o: + c99 -c -O $< +\fP +.fi +.RE +.LP +.IP " 5." 4 +The most common use of the archive interface follows. Here, it is +assumed that the source files are all C-language source: +.sp +.RS +.nf + +\fBlib: lib(file1.o) lib(file2.o) lib(file3.o) + @echo lib is now up-to-date +\fP +.fi +.RE +.LP +The \fB.c.a\fP rule is used to make \fBfile1.o\fP, \fBfile2.o\fP, +and \fBfile3.o\fP and insert them into \fBlib\fP. +.LP +The treatment of escaped s throughout the makefile is historical +practice. For example, the inference rule: +.sp +.RS +.nf + +\fB\&.c.o\\ +: +\fP +.fi +.RE +.LP +works, and the macro: +.sp +.RS +.nf + +\fBf= bar baz\\ + biz +a: + echo ==$f== +\fP +.fi +.RE +.LP +echoes \fB"==bar\ baz\ biz=="\fP . +.LP +If $? were: +.sp +.RS +.nf + +\fB/usr/include/stdio.h /usr/include/unistd.h foo.h +\fP +.fi +.RE +.LP +then $(?D) would be: +.sp +.RS +.nf + +\fB/usr/include /usr/include . +\fP +.fi +.RE +.LP +and $(?F) would be: +.sp +.RS +.nf + +\fBstdio.h unistd.h foo.h +\fP +.fi +.RE +.LP +.IP " 6." 4 +The contents of the built-in rules can be viewed by running: +.sp +.RS +.nf + +\fBmake -p -f /dev/null 2>/dev/null +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +The \fImake\fP utility described in this volume of IEEE\ Std\ 1003.1-2001 +is intended to provide the means for changing +portable source code into executables that can be run on an IEEE\ Std\ 1003.1-2001-conforming +system. It reflects the most +common features present in System V and BSD \fImake\fPs. +.LP +Historically, the \fImake\fP utility has been an especially fertile +ground for vendor and research organization-specific syntax +modifications and extensions. Examples include: +.IP " *" 3 +Syntax supporting parallel execution (such as from various multi-processor +vendors, GNU, and others) +.LP +.IP " *" 3 +Additional "operators" separating targets and their prerequisites +(System V, BSD, and others) +.LP +.IP " *" 3 +Specifying that command lines containing the strings \fB"${MAKE}"\fP +and \fB"$(MAKE)"\fP are executed when the \fB-n\fP +option is specified (GNU and System V) +.LP +.IP " *" 3 +Modifications of the meaning of internal macros when referencing libraries +(BSD and others) +.LP +.IP " *" 3 +Using a single instance of the shell for all of the command lines +of the target (BSD and others) +.LP +.IP " *" 3 +Allowing spaces as well as tabs to delimit command lines (BSD) +.LP +.IP " *" 3 +Adding C preprocessor-style "include" and "ifdef" constructs (System +V, GNU, BSD, and others) +.LP +.IP " *" 3 +Remote execution of command lines (Sprite and others) +.LP +.IP " *" 3 +Specifying additional special targets (BSD, System V, and most others) +.LP +.LP +Additionally, many vendors and research organizations have rethought +the basic concepts of \fImake\fP, creating vastly +extended, as well as completely new, syntaxes. Each of these versions +of \fImake\fP fulfills the needs of a different community of +users; it is unreasonable for this volume of IEEE\ Std\ 1003.1-2001 +to require behavior that would be incompatible (and +probably inferior) to historical practice for such a community. +.LP +In similar circumstances, when the industry has enough sufficiently +incompatible formats as to make them irreconcilable, this +volume of IEEE\ Std\ 1003.1-2001 has followed one or both of two courses +of action. Commands have been renamed ( \fIcksum\fP, \fIecho\fP, and +\fIpax\fP) and/or command line options have been provided to select +the desired behavior ( \fIgrep\fP, \fIod\fP, and \fIpax\fP). +.LP +Because the syntax specified for the \fImake\fP utility is, by and +large, a subset of the syntaxes accepted by almost all +versions of \fImake\fP, it was decided that it would be counter-productive +to change the name. And since the makefile itself is a +basic unit of portability, it would not be completely effective to +reserve a new option letter, such as \fImake\fP \fB-P\fP, to +achieve the portable behavior. Therefore, the special target \fB.POSIX\fP +was added to the makefile, allowing users to specify +"standard" behavior. This special target does not preclude extensions +in the \fImake\fP utility, nor does it preclude such +extensions being used by the makefile specifying the target; it does, +however, preclude any extensions from being applied that +could alter the behavior of previously valid syntax; such extensions +must be controlled via command line options or new special +targets. It is incumbent upon portable makefiles to specify the \fB.POSIX\fP +special target in order to guarantee that they are +not affected by local extensions. +.LP +The portable version of \fImake\fP described in this reference page +is not intended to be the state-of-the-art software +generation tool and, as such, some newer and more leading-edge features +have not been included. An attempt has been made to +describe the portable makefile in a manner that does not preclude +such extensions as long as they do not disturb the portable +behavior described here. +.LP +When the \fB-n\fP option is specified, it is always added to \fIMAKEFLAGS +\&.\fP This allows a recursive \fImake\fP \fB-n\fP +\fItarget\fP to be used to see all of the action that would be taken +to update \fItarget\fP. +.LP +The definition of \fIMAKEFLAGS\fP allows both the System V letter +string and the BSD command line formats. The two formats are +sufficiently different to allow implementations to support both without +ambiguity. +.LP +Early proposals stated that an "unquoted" number sign was treated +as the start of a comment. The \fImake\fP utility does not +pay any attention to quotes. A number sign starts a comment regardless +of its surroundings. +.LP +The text about "other implementation-defined pathnames may also be +tried" in addition to \fB./makefile\fP and +\fB\&./Makefile\fP is to allow such extensions as \fBSCCS/s.Makefile\fP +and other variations. It was made an implementation-defined +requirement (as opposed to unspecified behavior) to highlight surprising +implementations that might select something unexpected +like \fB/etc/Makefile\fP. XSI-conformant systems also try \fB./s.makefile\fP, +\fBSCCS/s.makefile\fP, \fB./s.Makefile\fP, and +\fBSCCS/s.Makefile\fP. +.LP +Early proposals contained the macro \fBNPROC\fP as a means of specifying +that \fImake\fP should use \fIn\fP processes to do +the work required. While this feature is a valuable extension for +many systems, it is not common usage and could require other +non-trivial extensions to makefile syntax. This extension is not required +by this volume of IEEE\ Std\ 1003.1-2001, but +could be provided as a compatible extension. The macro \fBPARALLEL\fP +is used by some historical systems with essentially the same +meaning (but without using a name that is a common system limit value). +It is suggested that implementors recognize the existing +use of \fBNPROC\fP and/or \fBPARALLEL\fP as extensions to \fImake\fP. +.LP +The default rules are based on System V. The default \fBCC=\fP value +is \fIc99\fP instead +of \fIcc\fP because this volume of IEEE\ Std\ 1003.1-2001 does not +standardize the utility named \fIcc\fP. Thus, every +conforming application would be required to define \fBCC=\fP \fIc99\fP +to expect to run. +There is no advantage conferred by the hope that the makefile might +hit the "preferred" compiler because this cannot be +guaranteed to work. Also, since the portable makescript can only use +the \fIc99\fP options, no +advantage is conferred in terms of what the script can do. It is a +quality-of-implementation issue as to whether \fIc99\fP is as valuable +as \fIcc\fP. +.LP +The \fB-d\fP option to \fImake\fP is frequently used to produce debugging +information, but is too implementation-defined to +add to this volume of IEEE\ Std\ 1003.1-2001. +.LP +The \fB-p\fP option is not passed in \fIMAKEFLAGS\fP on most historical +implementations and to change this would cause many +implementations to break without sufficiently increased portability. +.LP +Commands that begin with a plus sign ( \fB'+'\fP ) are executed even +if the \fB-n\fP option is present. Based on the GNU +version of \fImake\fP, the behavior of \fB-n\fP when the plus-sign +prefix is encountered has been extended to apply to \fB-q\fP +and \fB-t\fP as well. However, the System V convention of forcing +command execution with \fB-n\fP when the command line of a +target contains either of the strings \fB"$(MAKE)"\fP or \fB"${MAKE}"\fP +has not been adopted. This functionality appeared in +early proposals, but the danger of this approach was pointed out with +the following example of a portion of a makefile: +.sp +.RS +.nf + +\fBsubdir: + cd subdir; rm all_the_files; $(MAKE) +\fP +.fi +.RE +.LP +The loss of the System V behavior in this case is well-balanced by +the safety afforded to other makefiles that were not aware of +this situation. In any event, the command line plus-sign prefix can +provide the desired functionality. +.LP +The double colon in the target rule format is supported in BSD systems +to allow more than one target line containing the same +target name to have commands associated with it. Since this is not +functionality described in the SVID or XPG3 it has been allowed +as an extension, but not mandated. +.LP +The default rules are provided with text specifying that the built-in +rules shall be the same as if the listed set were used. +The intent is that implementations should be able to use the rules +without change, but will be allowed to alter them in ways that +do not affect the primary behavior. +.LP +The best way to provide portable makefiles is to include all of the +rules needed in the makefile itself. The rules provided use +only features provided by other portions of this volume of IEEE\ Std\ 1003.1-2001. +The default rules include rules for +optional commands in this volume of IEEE\ Std\ 1003.1-2001. Only rules +pertaining to commands that are provided are needed +in the default set of an implementation. +.LP +One point of discussion was whether to drop the default rules list +from this volume of IEEE\ Std\ 1003.1-2001. They +provide convenience, but do not enhance portability of applications. +The prime benefit is in portability of users who wish to type +\fImake\fP \fIcommand\fP and have the command build from a \fBcommand.c\fP +file. +.LP +The historical \fIMAKESHELL\fP feature was omitted. In some implementations +it is used to let a user override the shell to be +used to run \fImake\fP commands. This was confusing; for a portable +\fImake\fP, the shell should be chosen by the makefile writer +or specified on the \fImake\fP command line and not by a user running +\fImake\fP. +.LP +The \fImake\fP utilities in most historical implementations process +the prerequisites of a target in left-to-right order, and +the makefile format requires this. It supports the standard idiom +used in many makefiles that produce \fIyacc\fP programs; for example: +.sp +.RS +.nf + +\fBfoo: y.tab.o lex.o main.o + $(CC) $(CFLAGS) -o $\fP@ \fBt.tab.o lex.o main.o +\fP +.fi +.RE +.LP +In this example, if \fImake\fP chose any arbitrary order, the \fBlex.o\fP +might not be made with the correct \fBy.tab.h\fP. +Although there may be better ways to express this relationship, it +is widely used historically. Implementations that desire to +update prerequisites in parallel should require an explicit extension +to \fImake\fP or the makefile format to accomplish it, as +described previously. +.LP +The algorithm for determining a new entry for target rules is partially +unspecified. Some historical \fImake\fPs allow blank, +empty, or comment lines within the collection of commands marked by +leading s. A conforming makefile must ensure that +each command starts with a , but implementations are free to +ignore blank, empty, and comment lines without triggering +the start of a new entry. +.LP +The ASYNCHRONOUS EVENTS section includes having SIGTERM and SIGHUP, +along with the more traditional SIGINT and SIGQUIT, remove +the current target unless directed not to do so. SIGTERM and SIGHUP +were added to parallel other utilities that have historically +cleaned up their work as a result of these signals. When \fImake\fP +receives any signal other than SIGQUIT, it is required to +resend itself the signal it received so that it exits with a status +that reflects the signal. The results from SIGQUIT are +partially unspecified because, on systems that create \fBcore\fP files +upon receipt of SIGQUIT, the \fBcore\fP from \fImake\fP +would conflict with a \fBcore\fP file from the command that was running +when the SIGQUIT arrived. The main concern was to prevent +damaged files from appearing up-to-date when \fImake\fP is rerun. +.LP +The \fB.PRECIOUS\fP special target was extended to affect all targets +globally (by specifying no prerequisites). The +\fB\&.IGNORE\fP and \fB.SILENT\fP special targets were extended to allow +prerequisites; it was judged to be more useful in some +cases to be able to turn off errors or echoing for a list of targets +than for the entire makefile. These extensions to \fImake\fP +in System V were made to match historical practice from the BSD \fImake\fP. +.LP +Macros are not exported to the environment of commands to be run. +This was never the case in any historical \fImake\fP and +would have serious consequences. The environment is the same as the +environment to \fImake\fP except that \fIMAKEFLAGS\fP and +macros defined on the \fImake\fP command line are added. +.LP +Some implementations do not use \fIsystem\fP() for all command lines, +as required by the +portable makefile format; as a performance enhancement, they select +lines without shell metacharacters for direct execution by \fIexecve\fP(). +There is no requirement that \fIsystem\fP() be used specifically, +but merely that the same results be achieved. The +metacharacters typically used to bypass the direct \fIexecve\fP() +execution have been any +of: +.sp +.RS +.nf + +\fB= | ^ ( ) ; & < > * ? [ ] : $ ` ' " \\ \\n +\fP +.fi +.RE +.LP +The default in some advanced versions of \fImake\fP is to group all +the command lines for a target and execute them using a +single shell invocation; the System V method is to pass each line +individually to a separate shell. The single-shell method has the +advantages in performance and the lack of a requirement for many continued +lines. However, converting to this newer method has +caused portability problems with many historical makefiles, so the +behavior with the POSIX makefile is specified to be the same as +that of System V. It is suggested that the special target \fB.ONESHELL\fP +be used as an implementation extension to achieve the +single-shell grouping for a target or group of targets. +.LP +Novice users of \fImake\fP have had difficulty with the historical +need to start commands with a . Since it is often +difficult to discern differences between s and s on terminals +or printed listings, confusing bugs can +arise. In early proposals, an attempt was made to correct this problem +by allowing leading s instead of s. +However, implementors reported many makefiles that failed in subtle +ways following this change, and it is difficult to implement a +\fImake\fP that unambiguously can differentiate between macro and +command lines. There is extensive historical practice of +allowing leading spaces before macro definitions. Forcing macro lines +into column 1 would be a significant backwards-compatibility +problem for some makefiles. Therefore, historical practice was restored. +.LP +The System V INCLUDE feature was considered, but not included. This +would treat a line that began in the first column and +contained INCLUDE <\fIfilename\fP> as an indication to read <\fIfilename\fP> +at that point in the makefile. This is +difficult to use in a portable way, and it raises concerns about nesting +levels and diagnostics. System V, BSD, GNU, and others +have used different methods for including files. +.LP +The System V dynamic dependency feature was not included. It would +support: +.sp +.RS +.nf + +\fBcat: $$@.c +\fP +.fi +.RE +.LP +that would expand to; +.sp +.RS +.nf + +\fBcat: cat.c +\fP +.fi +.RE +.LP +This feature exists only in the new version of System V \fImake\fP +and, while useful, is not in wide usage. This means that +macros are expanded twice for prerequisites: once at makefile parse +time and once at target update time. +.LP +Consideration was given to adding metarules to the POSIX \fImake\fP. +This would make \fB%.o:\ %.c\fP the same as +\fB\&.c.o:\fP. This is quite useful and available from some vendors, +but it would cause too many changes to this \fImake\fP to +support. It would have introduced rule chaining and new substitution +rules. However, the rules for target names have been set to +reserve the \fB'%'\fP and \fB''\fP characters. These are traditionally +used to implement metarules and quoting of target +names, respectively. Implementors are strongly encouraged to use these +characters only for these purposes. +.LP +A request was made to extend the suffix delimiter character from a +period to any character. The metarules feature in newer +\fImake\fPs solves this problem in a more general way. This volume +of IEEE\ Std\ 1003.1-2001 is staying with the more +conservative historical definition. +.LP +The standard output format for the \fB-p\fP option is not described +because it is primarily a debugging option and because the +format is not generally useful to programs. In historical implementations +the output is not suitable for use in generating +makefiles. The \fB-p\fP format has been variable across historical +implementations. Therefore, the definition of \fB-p\fP was +only to provide a consistently named option for obtaining \fImake\fP +script debugging information. +.LP +Some historical implementations have not cleared the suffix list with +\fB-r\fP. +.LP +Implementations should be aware that some historical applications +have intermixed \fItarget_name\fP and \fImacro\fP= +\fIvalue\fP operands on the command line, expecting that all of the +macros are processed before any of the targets are dealt with. +Conforming applications do not do this, but some backwards-compatibility +support may be warranted. +.LP +Empty inference rules are specified with a semicolon command rather +than omitting all commands, as described in an early +proposal. The latter case has no traditional meaning and is reserved +for implementation extensions, such as in GNU \fImake\fP. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP , \fIar\fP , \fIc99\fP , \fIget\fP , +\fIlex\fP , \fIsccs\fP , \fIsh\fP , \fIyacc\fP , the System Interfaces +volume +of IEEE\ Std\ 1003.1-2001, \fIexec\fP, \fIsystem\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/man.1p b/man1p/man.1p new file mode 100644 index 000000000..6a7558649 --- /dev/null +++ b/man1p/man.1p @@ -0,0 +1,244 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MAN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" man +.SH NAME +man \- display system documentation +.SH SYNOPSIS +.LP +\fBman\fP \fB[\fP\fB-k\fP\fB]\fP \fIname\fP\fB...\fP +.SH DESCRIPTION +.LP +The \fIman\fP utility shall write information about each of the \fIname\fP +operands. If \fIname\fP is the name of a standard +utility, \fIman\fP at a minimum shall write a message describing the +syntax used by the standard utility, its options, and +operands. If more information is available, the \fIman\fP utility +shall provide it in an implementation-defined manner. +.LP +An implementation may provide information for values of \fIname\fP +other than the standard utilities. Standard utilities that +are listed as optional and that are not supported by the implementation +either shall cause a brief message indicating that fact to +be displayed or shall cause a full display of information as described +previously. +.SH OPTIONS +.LP +The \fIman\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-k\fP +Interpret \fIname\fP operands as keywords to be used in searching +a utilities summary database that contains a brief purpose +entry for each standard utility and write lines from the summary database +that match any of the keywords. The keyword search shall +produce results that are the equivalent of the output of the following +command: +.sp +.RS +.nf + +\fBgrep -Ei ' +\fP\fIname +name\fP\fB... +'\fP \fIsummary-database\fP +.fi +.RE +.LP +This assumes that the \fIsummary-database\fP is a text file with a +single entry per line; this organization is not required and +the example using \fIgrep\fP \fB-Ei\fP is merely illustrative of the +type of search +intended. The purpose entry to be included in the database shall consist +of a terse description of the purpose of the utility. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIname\fP +A keyword or the name of a standard utility. When \fB-k\fP is not +specified and \fIname\fP does not represent one of the +standard utilities, the results are unspecified. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIman\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and in the summary database). +The value of \fILC_CTYPE\fP need not affect the format +of the information written about the \fIname\fP operands. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPAGER\fP +Determine an output filtering command for writing the output to a +terminal. Any string acceptable as a \fIcommand_string\fP +operand to the \fIsh\fP \fB-c\fP command shall be valid. When standard +output is a terminal +device, the reference page output shall be piped through the command. +If the \fIPAGER\fP variable is null or not set, the command +shall be either \fImore\fP or another paginator utility documented +in the system +documentation. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fIman\fP utility shall write text describing the syntax of the +utility \fIname\fP, its options and its operands, or, when +\fB-k\fP is specified, lines from the summary database. The format +of this text is implementation-defined. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +It is recognized that the \fIman\fP utility is only of minimal usefulness +as specified. The opinion of the standard developers +was strongly divided as to how much or how little information \fIman\fP +should be required to provide. They considered, however, +that the provision of some portable way of accessing documentation +would aid user portability. The arguments against a fuller +specification were: +.IP " *" 3 +Large quantities of documentation should not be required on a system +that does not have excess disk space. +.LP +.IP " *" 3 +The current manual system does not present information in a manner +that greatly aids user portability. +.LP +.IP " *" 3 +A "better help system" is currently an area in which vendors feel +that they can add value to their POSIX implementations. +.LP +.LP +The \fB-f\fP option was considered, but due to implementation differences, +it was not included in this volume of +IEEE\ Std\ 1003.1-2001. +.LP +The description was changed to be more specific about what has to +be displayed for a utility. The standard developers considered +it insufficient to allow a display of only the synopsis without giving +a short description of what each option and operand +does. +.LP +The "purpose" entry to be included in the database can be similar +to the section title (less the numeric prefix) from this +volume of IEEE\ Std\ 1003.1-2001 for each utility. These titles are +similar to those used in historical systems for this +purpose. +.LP +See \fImailx\fP for rationale concerning the default paginator. +.LP +The caveat in the \fILC_CTYPE\fP description was added because it +is not a requirement that an implementation provide reference +pages for all of its supported locales on each system; changing \fILC_CTYPE\fP +does not necessarily translate the reference page +into another language. This is equivalent to the current state of +\fILC_MESSAGES\fP in +IEEE\ Std\ 1003.1-2001-locale-specific messages are not yet a requirement. +.LP +The historical \fIMANPATH\fP variable is not included in POSIX because +no attempt is made to specify naming conventions for +reference page files, nor even to mandate that they are files at all. +On some implementations they could be a true database, a +hypertext file, or even fixed strings within the \fIman\fP executable. +The standard developers considered the portability of +reference pages to be outside their scope of work. However, users +should be aware that \fIMANPATH\fP is implemented on a number of +historical systems and that it can be used to tailor the search pattern +for reference pages from the various categories (utilities, +functions, file formats, and so on) when the system administrator +reveals the location and conventions for reference pages on the +system. +.LP +The keyword search can rely on at least the text of the section titles +from these utility descriptions, and the implementation +may add more keywords. The term "section titles" refers to the strings +such as: +.sp +.RS +.nf + +\fBman - Display system documentation +ps - Report process status +\fP +.fi +.RE +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImore\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/mesg.1p b/man1p/mesg.1p new file mode 100644 index 000000000..c317150cf --- /dev/null +++ b/man1p/mesg.1p @@ -0,0 +1,160 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MESG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mesg +.SH NAME +mesg \- permit or deny messages +.SH SYNOPSIS +.LP +\fBmesg\fP \fB[\fP\fBy|n\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fImesg\fP utility shall control whether other users are allowed +to send messages via \fIwrite\fP, \fItalk\fP, or other utilities to +a terminal +device. The terminal device affected shall be determined by searching +for the first terminal in the sequence of devices associated +with standard input, standard output, and standard error, respectively. +With no arguments, \fImesg\fP shall report the current +state without changing it. Processes with appropriate privileges may +be able to send messages to the terminal independent of the +current state. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operands shall be supported in the POSIX locale: +.TP 7 +\fIy\fP +Grant permission to other users to send messages to the terminal device. +.TP 7 +\fIn\fP +Deny permission to other users to send messages to the terminal device. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fImesg\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written (by \fImesg\fP) to +standard error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If no operand is specified, \fImesg\fP shall display the current terminal +state in an unspecified format. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Receiving messages is allowed. +.TP 7 +\ 1 +Receiving messages is not allowed. +.TP 7 +>1 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The mechanism by which the message status of the terminal is changed +is unspecified. Therefore, unspecified actions may cause +the status of the terminal to change after \fImesg\fP has successfully +completed. These actions may include, but are not limited +to: another invocation of the \fImesg\fP utility, login procedures; +invocation of the \fIstty\fP utility, invocation of the \fIchmod\fP +utility or +\fIchmod\fP() function, and so on. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The terminal changed by \fImesg\fP is that associated with the standard +input, output, or error, rather than the controlling +terminal for the session. This is because users logged in more than +once should be able to change any of their login terminals +without having to stop the job running in those sessions. This is +not a security problem involving the terminals of other users +because appropriate privileges would be required to affect the terminal +of another user. +.LP +The method of checking each of the first three file descriptors in +sequence until a terminal is found was adopted from System +V. +.LP +The file \fB/dev/tty\fP is not specified for the terminal device because +it was thought to be too restrictive. Typical +environment changes for the \fIn\fP operand are that write permissions +are removed for \fIothers\fP and \fIgroup\fP from the +appropriate device. It was decided to leave the actual description +of what is done as unspecified because of potential differences +between implementations. +.LP +The format for standard output is unspecified because of differences +between historical implementations. This output is +generally not useful to shell scripts (they can use the exit status), +so exact parsing of the output is unnecessary. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fItalk\fP , \fIwrite\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/mkdir.1p b/man1p/mkdir.1p new file mode 100644 index 000000000..57dd9bafc --- /dev/null +++ b/man1p/mkdir.1p @@ -0,0 +1,194 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MKDIR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mkdir +.SH NAME +mkdir \- make directories +.SH SYNOPSIS +.LP +\fBmkdir\fP \fB[\fP\fB-p\fP\fB][\fP\fB-m\fP \fImode\fP\fB]\fP \fIdir\fP\fB...\fP +.SH DESCRIPTION +.LP +The \fImkdir\fP utility shall create the directories specified by +the operands, in the order specified. +.LP +For each \fIdir\fP operand, the \fImkdir\fP utility shall perform +actions equivalent to the \fImkdir\fP() function defined in the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, +called with the following arguments: +.IP " 1." 4 +The \fIdir\fP operand is used as the \fIpath\fP argument. +.LP +.IP " 2." 4 +The value of the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO +is used as the \fImode\fP argument. (If the \fB-m\fP +option is specified, the \fImode\fP option-argument overrides this +default.) +.LP +.SH OPTIONS +.LP +The \fImkdir\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-m\ \fP \fImode\fP +Set the file permission bits of the newly-created directory to the +specified \fImode\fP value. The \fImode\fP option-argument +shall be the same as the \fImode\fP operand defined for the \fIchmod\fP +utility. In the +\fIsymbolic_mode\fP strings, the \fIop\fP characters \fB'+'\fP and +\fB'-'\fP shall be interpreted relative to an assumed +initial mode of \fIa\fP= \fIrwx\fP; \fB'+'\fP shall add permissions +to the default mode, \fB'-'\fP shall delete permissions +from the default mode. +.TP 7 +\fB-p\fP +Create any missing intermediate pathname components. +.LP +For each \fIdir\fP operand that does not name an existing directory, +effects equivalent to those caused by the following +command shall occur: +.sp +.RS +.nf + +\fBmkdir -p -m $(umask -S),u+wx $(dirname\fP \fIdir\fP\fB) && +mkdir\fP \fB[\fP\fB-m\fP \fImode\fP\fB]\fP \fIdir\fP +.fi +.RE +.LP +where the \fB-m\fP \fImode\fP option represents that option supplied +to the original invocation of \fImkdir\fP, if any. +.LP +Each \fIdir\fP operand that names an existing directory shall be ignored +without error. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIdir\fP +A pathname of a directory to be created. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fImkdir\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All the specified directories were created successfully or the \fB-p\fP +option was specified and all the specified directories +now exist. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The default file mode for directories is \fIa\fP= \fIrwx\fP (777 on +most systems) with selected permissions removed in +accordance with the file mode creation mask. For intermediate pathname +components created by \fImkdir\fP, the mode is the default +modified by \fIu\fP+ \fIwx\fP so that the subdirectories can always +be created regardless of the file mode creation mask; if +different ultimate permissions are desired for the intermediate directories, +they can be changed afterwards with \fIchmod\fP. +.LP +Note that some of the requested directories may have been created +even if an error occurs. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The System V \fB-m\fP option was included to control the file mode. +.LP +The System V \fB-p\fP option was included to create any needed intermediate +directories and to complement the functionality +provided by \fIrmdir\fP for removing directories in the path prefix +as they become empty. +Because no error is produced if any path component already exists, +the \fB-p\fP option is also useful to ensure that a particular +directory exists. +.LP +The functionality of \fImkdir\fP is described substantially through +a reference to the \fImkdir\fP() function in the System Interfaces +volume of IEEE\ Std\ 1003.1-2001. For +example, by default, the mode of the directory is affected by the +file mode creation mask in accordance with the specified behavior +of the \fImkdir\fP() function. In this way, there is less duplication +of effort required for +describing details of the directory creation. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchmod\fP() , \fIrm\fP , \fIrmdir\fP() , \fIumask\fP() , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fImkdir\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/mkfifo.1p b/man1p/mkfifo.1p new file mode 100644 index 000000000..1f85385a9 --- /dev/null +++ b/man1p/mkfifo.1p @@ -0,0 +1,163 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MKFIFO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mkfifo +.SH NAME +mkfifo \- make FIFO special files +.SH SYNOPSIS +.LP +\fBmkfifo\fP \fB[\fP\fB-m\fP \fImode\fP\fB]\fP \fIfile\fP\fB...\fP +.SH DESCRIPTION +.LP +The \fImkfifo\fP utility shall create the FIFO special files specified +by the operands, in the order specified. +.LP +For each \fIfile\fP operand, the \fImkfifo\fP utility shall perform +actions equivalent to the \fImkfifo\fP() function defined in the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, +called with the following arguments: +.IP " 1." 4 +The \fIfile\fP operand is used as the \fIpath\fP argument. +.LP +.IP " 2." 4 +The value of the bitwise-inclusive OR of S_IRUSR, S_IWUSR, S_IRGRP, +S_IWGRP, S_IROTH, and S_IWOTH is used as the \fImode\fP +argument. (If the \fB-m\fP option is specified, the value of the \fImkfifo\fP() +\fImode\fP argument is unspecified, but the FIFO shall at no time +have permissions less restrictive than the \fB-m\fP \fImode\fP +option-argument.) +.LP +.SH OPTIONS +.LP +The \fImkfifo\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-m\ \fP \fImode\fP +Set the file permission bits of the newly-created FIFO to the specified +\fImode\fP value. The \fImode\fP option-argument +shall be the same as the \fImode\fP operand defined for the \fIchmod\fP +utility. In the +\fIsymbolic_mode\fP strings, the \fIop\fP characters \fB'+'\fP and +\fB'-'\fP shall be interpreted relative to an assumed +initial mode of \fIa\fP= \fIrw\fP. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of the FIFO special file to be created. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fImkfifo\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All the specified FIFO special files were created successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +This utility was added to permit shell applications to create FIFO +special files. +.LP +The \fB-m\fP option was added to control the file mode, for consistency +with the similar functionality provided by the \fImkdir\fP utility. +.LP +Early proposals included a \fB-p\fP option similar to the \fImkdir\fP +\fB-p\fP option +that created intermediate directories leading up to the FIFO specified +by the final component. This was removed because it is not +commonly needed and is not common practice with similar utilities. +.LP +The functionality of \fImkfifo\fP is described substantially through +a reference to the \fImkfifo\fP() function in the System Interfaces +volume of IEEE\ Std\ 1003.1-2001. For +example, by default, the mode of the FIFO file is affected by the +file mode creation mask in accordance with the specified behavior +of the \fImkfifo\fP() function. In this way, there is less duplication +of effort required +for describing details of the file creation. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchmod\fP() , \fIumask\fP() , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fImkfifo\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/more.1p b/man1p/more.1p new file mode 100644 index 000000000..22d9a6a7d --- /dev/null +++ b/man1p/more.1p @@ -0,0 +1,1069 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MORE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" more +.SH NAME +more \- display files on a page-by-page basis +.SH SYNOPSIS +.LP +\fBmore\fP \fB[\fP\fB-ceisu\fP\fB][\fP\fB-n\fP \fInumber\fP\fB][\fP\fB-p\fP +\fIcommand\fP\fB][\fP\fB-t\fP \fItagstring\fP\fB][\fP\fIfile\fP \fB...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fImore\fP utility shall read files and either write them to the +terminal on a page-by-page basis or filter them to +standard output. If standard output is not a terminal device, all +input files shall be copied to standard output in their entirety, +without modification, except as specified for the \fB-s\fP option. +If standard output is a terminal device, the files shall be +written a number of lines (one screenful) at a time under the control +of user commands. See the EXTENDED DESCRIPTION section. +.LP +Certain block-mode terminals do not have all the capabilities necessary +to support the complete \fImore\fP definition; they are +incapable of accepting commands that are not terminated with a . +Implementations that support such terminals shall +provide an operating mode to \fImore\fP in which all commands can +be terminated with a on those terminals. This +mode: +.IP " *" 3 +Shall be documented in the system documentation +.LP +.IP " *" 3 +Shall, at invocation, inform the user of the terminal deficiency that +requires the usage and provide +instructions on how this warning can be suppressed in future invocations +.LP +.IP " *" 3 +Shall not be required for implementations supporting only fully capable +terminals +.LP +.IP " *" 3 +Shall not affect commands already requiring s +.LP +.IP " *" 3 +Shall not affect users on the capable terminals from using \fImore\fP +as described in this volume of +IEEE\ Std\ 1003.1-2001 +.LP +.SH OPTIONS +.LP +The \fImore\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-c\fP +If a screen is to be written that has no lines in common with the +current screen, or \fImore\fP is writing its first screen, +\fImore\fP shall not scroll the screen, but instead shall redraw each +line of the screen in turn, from the top of the screen to +the bottom. In addition, if \fImore\fP is writing its first screen, +the screen shall be cleared. This option may be silently +ignored on devices with insufficient terminal capabilities. +.TP 7 +\fB-e\fP +By default, \fImore\fP shall exit immediately after writing the last +line of the last file in the argument list. If the +\fB-e\fP option is specified: +.RS +.IP " 1." 4 +If there is only a single file in the argument list and that file +was completely displayed on a single screen, \fImore\fP shall +exit immediately after writing the last line of that file. +.LP +.IP " 2." 4 +Otherwise, \fImore\fP shall exit only after reaching end-of-file on +the last file in the argument list twice without an +intervening operation. See the EXTENDED DESCRIPTION section. +.LP +.RE +.TP 7 +\fB-i\fP +Perform pattern matching in searches without regard to case; see the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 9.2, Regular Expression General Requirements. +.TP 7 +\fB-n\ \fP \fInumber\fP +Specify the number of lines per screenful. The \fInumber\fP argument +is a positive decimal integer. The \fB-n\fP option shall +override any values obtained from any other source. +.TP 7 +\fB-p\ \fP \fIcommand\fP +Each time a screen from a new file is displayed or redisplayed (including +as a result of \fImore\fP commands; for example, +\fB:p\fP), execute the \fImore\fP command(s) in the command arguments +in the order specified, as if entered by the user after the +first screen has been displayed. No intermediate results shall be +displayed (that is, if the command is a movement to a screen +different from the normal first screen, only the screen resulting +from the command shall be displayed.) If any of the commands fail +for any reason, an informational message to this effect shall be written, +and no further commands specified using the \fB-p\fP +option shall be executed for this file. +.TP 7 +\fB-s\fP +Behave as if consecutive empty lines were a single empty line. +.TP 7 +\fB-t\ \fP \fItagstring\fP +Write the screenful of the file containing the tag named by the \fItagstring\fP +argument. See the \fIctags\fP utility. The tags feature represented +by \fB-t\fP \fItagstring\fP and the \fB:t\fP command is +optional. It shall be provided on any system that also provides a +conforming implementation of \fIctags\fP; otherwise, the use of \fB-t\fP +produces undefined results. +.LP +The filename resulting from the \fB-t\fP option shall be logically +added as a prefix to the list of command line files, as if +specified by the user. If the tag named by the \fItagstring\fP argument +is not found, it shall be an error, and \fImore\fP shall +take no further action. +.LP +If the tag specifies a line number, the first line of the display +shall contain the beginning of that line. If the tag specifies +a pattern, the first line of the display shall contain the beginning +of the matching text from the first line of the file that +contains that pattern. If the line does not exist in the file or matching +text is not found, an informational message to this +effect shall be displayed, and \fImore\fP shall display the default +screen as if \fB-t\fP had not been specified. +.LP +If both the \fB-t\fP \fItagstring\fP and \fB-p\fP \fIcommand\fP options +are given, the \fB-t\fP \fItagstring\fP shall be +processed first; that is, the file and starting line for the display +shall be as specified by \fB-t\fP, and then the \fB-p\fP +\fImore\fP command shall be executed. If the line (matching text) +specified by the \fB-t\fP command does not exist (is not +found), no \fB-p\fP \fImore\fP command shall be executed for this +file at any time. +.TP 7 +\fB-u\fP +Treat a as a printable control character, displayed as +an implementation-defined character sequence (see the +EXTENDED DESCRIPTION section), suppressing backspacing and the special +handling that produces underlined or standout mode text on +some terminal types. Also, do not ignore a at the +end of a line. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of an input file. If no \fIfile\fP operands are specified, +the standard input shall be used. If a \fIfile\fP is +\fB'-'\fP , the standard input shall be read at that point in the +sequence. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified, or if a \fIfile\fP operand is \fB'-'\fP +\&. +.SH INPUT FILES +.LP +The input files being examined shall be text files. If standard output +is a terminal, standard error shall be used to read +commands from the user. If standard output is a terminal, standard +error is not readable, and command input is needed, \fImore\fP +may attempt to obtain user commands from the controlling terminal +(for example, \fB/dev/tty\fP); otherwise, \fImore\fP shall +terminate with an error indicating that it was unable to read user +commands. If standard output is not a terminal, no error shall +result if standard error cannot be opened for reading. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fImore\fP: +.TP 7 +\fICOLUMNS\fP +Override the system-selected horizontal display line size. See the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 8, Environment Variables for valid values and results when +it is unset or +null. +.TP 7 +\fIEDITOR\fP +Used by the \fBv\fP command to select an editor. See the EXTENDED +DESCRIPTION section. +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular +expressions. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and +the behavior of character classes within regular +expressions. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fILINES\fP +Override the system-selected vertical screen size, used as the number +of lines in a screenful. See the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables for valid +values and +results when it is unset or null. The \fB-n\fP option shall take precedence +over the \fILINES\fP variable for determining the +number of lines in a screenful. +.TP 7 +\fIMORE\fP +Determine a string containing options described in the OPTIONS section +preceded with hyphens and -separated as on +the command line. Any command line options shall be processed after +those in the \fIMORE\fP variable, as if the command line were: +.sp +.RS +.nf + +\fBmore $MORE\fP \fIoptions operands\fP +.fi +.RE +.LP +The \fIMORE\fP variable shall take precedence over the \fITERM\fP +and \fILINES\fP variables for determining the number of +lines in a screenful. +.TP 7 +\fITERM\fP +Determine the name of the terminal type. If this variable is unset +or null, an unspecified default terminal type is used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall be used to write the contents of the input +files. +.SH STDERR +.LP +The standard error shall be used for diagnostic messages and user +commands (see the INPUT FILES section), and, if standard +output is a terminal device, to write a prompting string. The prompting +string shall appear on the screen line below the last line +of the file displayed in the current screenful. The prompt shall contain +the name of the file currently being examined and shall +contain an end-of-file indication and the name of the next file, if +any, when prompting at the end-of-file. If an error or +informational message is displayed, it is unspecified whether it is +contained in the prompt. If it is not contained in the prompt, +it shall be displayed and then the user shall be prompted for a continuation +character, at which point another message or the user +prompt may be displayed. The prompt is otherwise unspecified. It is +unspecified whether informational messages are written for +other user commands. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +The following section describes the behavior of \fImore\fP when the +standard output is a terminal device. If the standard +output is not a terminal device, no options other than \fB-s\fP shall +have any effect, and all input files shall be copied to +standard output otherwise unmodified, at which time \fImore\fP shall +exit without further action. +.LP +The number of lines available per screen shall be determined by the +\fB-n\fP option, if present, or by examining values in the +environment (see the ENVIRONMENT VARIABLES section). If neither method +yields a number, an unspecified number of lines shall be +used. +.LP +The maximum number of lines written shall be one less than this number, +because the screen line after the last line written +shall be used to write a user prompt and user input. If the number +of lines in the screen is less than two, the results are +undefined. It is unspecified whether user input is permitted to be +longer than the remainder of the single line where the prompt +has been written. +.LP +The number of columns available per line shall be determined by examining +values in the environment (see the ENVIRONMENT +VARIABLES section), with a default value as described in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment +Variables. +.LP +Lines that are longer than the display shall be folded; the length +at which folding occurs is unspecified, but should be +appropriate for the output device. Folding may occur between glyphs +of single characters that take up multiple display columns. +.LP +When standard output is a terminal and \fB-u\fP is not specified, +\fImore\fP shall treat s and +s specially: +.IP " *" 3 +A character, followed first by a sequence of \fIn\fP s +(where \fIn\fP is the same as the number of column +positions that the character occupies), then by \fIn\fP underscore +characters ( \fB'_'\fP ), shall cause that character to be +written as underlined text, if the terminal type supports that. The +\fIn\fP underscore characters, followed first by \fIn\fP +s, then any character with \fIn\fP column positions, shall +also cause that character to be written as underlined +text, if the terminal type supports that. +.LP +.IP " *" 3 +A sequence of \fIn\fP s (where \fIn\fP is the same as the +number of column positions that the previous +character occupies) that appears between two identical printable characters +shall cause the first of those two characters to be +written as emboldened text (that is, visually brighter, standout mode, +or inverse-video mode), if the terminal type supports that, +and the second to be discarded. Immediately subsequent occurrences +of / character pairs for that same character +shall also be discarded. (For example, the sequence \fB"a\\ba\\ba\\ba"\fP +is interpreted as a single emboldened \fB'a'\fP .) +.LP +.IP " *" 3 +The \fImore\fP utility shall logically discard all other s +from the line as well as the character which +precedes them, if any. +.LP +.IP " *" 3 +A at the end of a line shall be ignored, rather +than being written as a non-printable character, as +described in the next paragraph. +.LP +.LP +It is implementation-defined how other non-printable characters are +written. Implementations should use the same format that +they use for the \fIex\fP \fBprint\fP command; see the OPTIONS section +within the \fIed\fP utility. It is unspecified whether a multi-column +character shall be separated if it crosses a +display line boundary; it shall not be discarded. The behavior is +unspecified if the number of columns on the display is less than +the number of columns any single character in the line being displayed +would occupy. +.LP +When each new file is displayed (or redisplayed), \fImore\fP shall +write the first screen of the file. Once the initial screen +has been written, \fImore\fP shall prompt for a user command. If the +execution of the user command results in a screen that has +lines in common with the current screen, and the device has sufficient +terminal capabilities, \fImore\fP shall scroll the screen; +otherwise, it is unspecified whether the screen is scrolled or redrawn. +.LP +For all files but the last (including standard input if no file was +specified, and for the last file as well, if the \fB-e\fP +option was not specified), when \fImore\fP has written the last line +in the file, \fImore\fP shall prompt for a user command. +This prompt shall contain the name of the next file as well as an +indication that \fImore\fP has reached end-of-file. If the user +command is \fBf\fP, -F, , \fBj\fP, , \fBd\fP, +-D, or \fBs\fP, +\fImore\fP shall display the next file. Otherwise, if displaying the +last file, \fImore\fP shall exit. Otherwise, \fImore\fP +shall execute the user command specified. +.LP +Several of the commands described in this section display a previous +screen from the input stream. In the case that text is +being taken from a non-rewindable stream, such as a pipe, it is implementation-defined +how much backwards motion is supported. If a +command cannot be executed because of a limitation on backwards motion, +an error message to this effect shall be displayed, the +current screen shall not change, and the user shall be prompted for +another command. +.LP +If a command cannot be performed because there are insufficient lines +to display, \fImore\fP shall alert the terminal. If a +command cannot be performed because there are insufficient lines to +display or a \fB/\fP command fails: if the input is the +standard input, the last screen in the file may be displayed; otherwise, +the current file and screen shall not change, and the user +shall be prompted for another command. +.LP +The interactive commands in the following sections shall be supported. +Some commands can be preceded by a decimal integer, +called \fIcount\fP in the following descriptions. If not specified +with the command, \fIcount\fP shall default to 1. In the +following descriptions, \fIpattern\fP is a basic regular expression, +as described in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 9.3, Basic Regular Expressions. The +term "examine" is historical usage meaning "open the file for viewing''; +for example, \fImore\fP \fBfoo\fP would be expressed +as examining file \fBfoo\fP. +.LP +In the following descriptions, unless otherwise specified, \fIline\fP +is a line in the \fImore\fP display, not a line from the +file being examined. +.LP +In the following descriptions, the \fIcurrent position\fP refers to +two things: +.IP " 1." 4 +The position of the current line on the screen +.LP +.IP " 2." 4 +The line number (in the file) of the current line on the screen +.LP +.LP +Usually, the line on the screen corresponding to the current position +is the third line on the screen. If this is not possible +(there are fewer than three lines to display or this is the first +page of the file, or it is the last page of the file), then the +current position is either the first or last line on the screen as +described later. +.SS Help +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBh +\fP +.fi +.RE +.sp +.LP +Write a summary of these commands and other implementation-defined +commands. The behavior shall be as if the \fImore\fP utility +were executed with the \fB-e\fP option on a file that contained the +summary information. The user shall be prompted as described +earlier in this section when end-of-file is reached. If the user command +is one of those specified to continue to the next file, +\fImore\fP shall return to the file and screen state from which the +\fBh\fP command was executed. +.SS Scroll Forward One Screenful +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP\fBf +\fP\fB[\fP\fIcount\fP\fB]\fP\fB-F +\fP +.fi +.RE +.sp +.LP +Scroll forward \fIcount\fP lines, with a default of one screenful. +If \fIcount\fP is more than the screen size, only the final +screenful shall be written. +.SS Scroll Backward One Screenful +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP\fBb +\fP\fB[\fP\fIcount\fP\fB]\fP\fB-B +\fP +.fi +.RE +.sp +.LP +Scroll backward \fIcount\fP lines, with a default of one screenful +(see the \fB-n\fP option). If \fIcount\fP is more than the +screen size, only the final screenful shall be written. +.SS Scroll Forward One Line +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP\fB +\fP\fB[\fP\fIcount\fP\fB]\fP\fBj +\fP\fB[\fP\fIcount\fP\fB]\fP\fB +\fP +.fi +.RE +.sp +.LP +Scroll forward \fIcount\fP lines. The default \fIcount\fP for the + shall be one screenful; for \fBj\fP and +, one line. The entire \fIcount\fP lines shall be written, +even if \fIcount\fP is more than the screen size. +.SS Scroll Backward One Line +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP\fBk +\fP +.fi +.RE +.sp +.LP +Scroll backward \fIcount\fP lines. The entire \fIcount\fP lines shall +be written, even if \fIcount\fP is more than the screen +size. +.SS Scroll Forward One Half Screenful +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP\fBd +\fP\fB[\fP\fIcount\fP\fB]\fP\fB-D +\fP +.fi +.RE +.sp +.LP +Scroll forward \fIcount\fP lines, with a default of one half of the +screen size. If \fIcount\fP is specified, it shall become +the new default for subsequent \fBd\fP, -D, and \fBu\fP commands. +.SS Skip Forward One Line +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP\fBs +\fP +.fi +.RE +.sp +.LP +Display the screenful beginning with the line \fIcount\fP lines after +the last line on the current screen. If \fIcount\fP +would cause the current position to be such that less than one screenful +would be written, the last screenful in the file shall be +written. +.SS Scroll Backward One Half Screenful +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP\fBu +\fP\fB[\fP\fIcount\fP\fB]\fP\fB-U +\fP +.fi +.RE +.sp +.LP +Scroll backward \fIcount\fP lines, with a default of one half of the +screen size. If \fIcount\fP is specified, it shall become +the new default for subsequent \fBd\fP, -D, \fBu\fP, and +-U commands. The entire \fIcount\fP lines +shall be written, even if \fIcount\fP is more than the screen size. +.SS Go to Beginning of File +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP\fBg +\fP +.fi +.RE +.sp +.LP +Display the screenful beginning with line \fIcount\fP. +.SS Go to End-of-File +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP\fBG +\fP +.fi +.RE +.sp +.LP +If \fIcount\fP is specified, display the screenful beginning with +the line \fIcount\fP. Otherwise, display the last screenful +of the file. +.SS Refresh the Screen +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBr +-L +\fP +.fi +.RE +.sp +.LP +Refresh the screen. +.SS Discard and Refresh +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBR +\fP +.fi +.RE +.sp +.LP +Refresh the screen, discarding any buffered input. If the current +file is non-seekable, buffered input shall not be discarded +and the \fBR\fP command shall be equivalent to the \fBr\fP command. +.SS Mark Position +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBm\fP\fIletter\fP +.fi +.RE +.sp +.LP +Mark the current position with the letter named by \fIletter\fP, where +\fIletter\fP represents the name of one of the +lowercase letters of the portable character set. When a new file is +examined, all marks may be lost. +.SS Return to Mark +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB'\fP\fIletter\fP +.fi +.RE +.sp +.LP +Return to the position that was previously marked with the letter +named by \fIletter\fP, making that line the current +position. +.SS Return to Previous Position +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB'' +\fP +.fi +.RE +.sp +.LP +Return to the position from which the last large movement command +was executed (where a "large movement" is defined as any +movement of more than a screenful of lines). If no such movements +have been made, return to the beginning of the file. +.SS Search Forward for Pattern +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP\fB/\fP\fB[\fP\fB!\fP\fB]\fP\fIpattern\fP\fB +\fP +.fi +.RE +.sp +.LP +Display the screenful beginning with the \fIcount\fPth line containing +the pattern. The search shall start after the first line +currently displayed. The null regular expression ( \fB'/'\fP followed +by a ) shall repeat the search using the +previous regular expression, with a default \fIcount\fP. If the character +\fB'!'\fP is included, the matching lines shall be +those that do not contain the \fIpattern\fP. If no match is found +for the \fIpattern\fP, a message to that effect shall be +displayed. +.SS Search Backward for Pattern +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP\fB?\fP\fB[\fP\fB!\fP\fB]\fP\fIpattern\fP\fB +\fP +.fi +.RE +.sp +.LP +Display the screenful beginning with the \fIcount\fPth previous line +containing the pattern. The search shall start on the last +line before the first line currently displayed. The null regular expression +( \fB'?'\fP followed by a ) shall +repeat the search using the previous regular expression, with a default +\fIcount\fP. If the character \fB'!'\fP is included, +matching lines shall be those that do not contain the \fIpattern\fP. +If no match is found for the \fIpattern\fP, a message to +that effect shall be displayed. +.SS Repeat Search +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP\fBn +\fP +.fi +.RE +.sp +.LP +Repeat the previous search for \fIcount\fPth line containing the last +\fIpattern\fP (or not containing the last +\fIpattern\fP, if the previous search was \fB"/!"\fP or \fB"?!"\fP +). +.SS Repeat Search in Reverse +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP\fBN +\fP +.fi +.RE +.sp +.LP +Repeat the search in the opposite direction of the previous search +for the \fIcount\fPth line containing the last +\fIpattern\fP (or not containing the last \fIpattern\fP, if the previous +search was \fB"/!"\fP or \fB"?!"\fP ). +.SS Examine New File +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB:e\fP \fB[\fP\fIfilename\fP\fB]\fP\fB +\fP +.fi +.RE +.sp +.LP +Examine a new file. If the \fIfilename\fP argument is not specified, +the current file (see the \fB:n\fP and \fB:p\fP commands +below) shall be re-examined. The \fIfilename\fP shall be subjected +to the process of shell word expansions (see \fIWord Expansions\fP +); if more than a single pathname results, the effects are unspecified. +If +\fIfilename\fP is a number sign ( \fB'#'\fP ), the previously examined +file shall be re-examined. If \fIfilename\fP is not +accessible for any reason (including that it is a non-seekable file), +an error message to this effect shall be displayed and the +current file and screen shall not change. +.SS Examine Next File +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP\fB:n +\fP +.fi +.RE +.sp +.LP +Examine the next file. If a number \fIcount\fP is specified, the \fIcount\fPth +next file shall be examined. If \fIfilename\fP +refers to a non-seekable file, the results are unspecified. +.SS Examine Previous File +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP\fB:p +\fP +.fi +.RE +.sp +.LP +Examine the previous file. If a number \fIcount\fP is specified, the +\fIcount\fPth previous file shall be examined. If +\fIfilename\fP refers to a non-seekable file, the results are unspecified. +.SS Go to Tag +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB:t\fP \fItagstring\fP\fB +\fP +.fi +.RE +.sp +.LP +If the file containing the tag named by the \fItagstring\fP argument +is not the current file, examine the file, as if the +\fB:e\fP command was executed with that file as the argument. Otherwise, +or in addition, display the screenful beginning with the +tag, as described for the \fB-t\fP option (see the OPTIONS section). +If the \fIctags\fP +utility is not supported by the system, the use of \fB:t\fP produces +undefined results. +.SS Invoke Editor +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBv +\fP +.fi +.RE +.sp +.LP +Invoke an editor to edit the current file being examined. If standard +input is being examined, the results are unspecified. The +name of the editor shall be taken from the environment variable \fIEDITOR +,\fP or shall default to \fIvi\fP. If the last pathname component +in \fIEDITOR\fP is either \fIvi\fP or \fIex\fP, the editor shall be +invoked with a \fB-c\fP +\fIlinenumber\fP command line argument, where \fIlinenumber\fP is +the line number of the file line containing the display line +currently displayed as the first line of the screen. It is implementation-defined +whether line-setting options are passed to +editors other than \fIvi\fP and \fIex\fP. +.LP +When the editor exits, \fImore\fP shall resume with the same file +and screen as when the editor was invoked. +.SS Display Position +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB= +-G +\fP +.fi +.RE +.sp +.LP +Write a message for which the information references the first byte +of the line after the last line of the file on the screen. +This message shall include the name of the file currently being examined, +its number relative to the total number of files there +are to examine, the line number in the file, the byte number and the +total bytes in the file, and what percentage of the file +precedes the current position. If \fImore\fP is reading from standard +input, or the file is shorter than a single screen, the line +number, the byte number, the total bytes, and the percentage need +not be written. +.SS Quit +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBq +:q +ZZ +\fP +.fi +.RE +.sp +.LP +Exit \fImore\fP. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If an error is encountered accessing a file when using the \fB:n\fP +command, \fImore\fP shall attempt to examine the next file +in the argument list, but the final exit status shall be affected. +If an error is encountered accessing a file via the \fB:p\fP +command, \fImore\fP shall attempt to examine the previous file in +the argument list, but the final exit status shall be affected. +If an error is encountered accessing a file via the \fB:e\fP command, +\fImore\fP shall remain in the current file and the final +exit status shall not be affected. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +When the standard output is not a terminal, only the \fB-s\fP filter-modification +option is effective. This is based on +historical practice. For example, a typical implementation of \fIman\fP +pipes its output +through \fImore\fP \fB-s\fP to squeeze excess white space for terminal +users. When \fIman\fP +is piped to \fIlp\fP, however, it is undesirable for this squeezing +to happen. +.SH EXAMPLES +.LP +The \fB-p\fP allows arbitrary commands to be executed at the start +of each file. Examples are: +.TP 7 +\fImore\ \fP \fB-p\ G\ \fP \fIfile1\ file2\fP +.sp +Examine each file starting with its last screenful. +.TP 7 +\fImore\ \fP \fB-p\ \fP 100\ \fIfile1\ file2\fP +.sp +Examine each file starting with line 100 in the current position (usually +the third line, so line 98 would be the first line +written). +.TP 7 +\fImore\ \fP \fB-p\ \fP /100\ \fIfile1\ file2\fP +.sp +Examine each file starting with the first line containing the string +\fB"100"\fP in the current position +.sp +.SH RATIONALE +.LP +The \fImore\fP utility, available in BSD and BSD-derived systems, +was chosen as the prototype for the POSIX file display +program since it is more widely available than either the public-domain +program \fIless\fP or than \fIpg\fP, a pager provided in +System V. The 4.4 BSD \fImore\fP is the model for the features selected; +it is almost fully upwards-compatible from the 4.3 BSD +version in wide use and has become more amenable for \fIvi\fP users. +Several features +originally derived from various file editors, found in both \fIless\fP +and \fIpg\fP, have been added to this volume of +IEEE\ Std\ 1003.1-2001 as they have proved extremely popular with +users. +.LP +There are inconsistencies between \fImore\fP and \fIvi\fP that result +from historical +practice. For example, the single-character commands \fBh\fP, \fBf\fP, +\fBb\fP, and are screen movers in +\fImore\fP, but cursor movers in \fIvi\fP. These inconsistencies were +maintained because the +cursor movements are not applicable to \fImore\fP and the powerful +functionality achieved without the use of the control key +justifies the differences. +.LP +The tags interface has been included in a program that is not a text +editor because it promotes another degree of consistent +operation with \fIvi\fP. It is conceivable that the paging environment +of \fImore\fP would be +superior for browsing source code files in some circumstances. +.LP +The operating mode referred to for block-mode terminals effectively +adds a to each Synopsis line that currently +has none. So, for example, \fBd\fP would page one screenful. +The mode could be triggered by a command line option, +environment variable, or some other method. The details are not imposed +by this volume of IEEE\ Std\ 1003.1-2001 because +there are so few systems known to support such terminals. Nevertheless, +it was considered that all systems should be able to +support \fImore\fP given the exception cited for this small community +of terminals because, in comparison to \fIvi\fP, the cursor movements +are few and the command set relatively amenable to the optional +s. +.LP +Some versions of \fImore\fP provide a shell escaping mechanism similar +to the \fIex\fP +\fB!\fP command. The standard developers did not consider that this +was necessary in a paginator, particularly given the wide +acceptance of multiple window terminals and job control features. +(They chose to retain such features in the editors and \fImailx\fP +because the shell interaction also gives an opportunity to modify +the editing buffer, +which is not applicable to \fImore\fP.) +.LP +The \fB-p\fP (position) option replaces the \fB+\fP command because +of the Utility Syntax Guidelines. In early proposals, it +took a \fIpattern\fP argument, but historical \fIless\fP provided +the \fImore\fP general facility of a command. It would have +been desirable to use the same \fB-c\fP as \fIex\fP and \fIvi\fP, +but the letter was already in use. +.LP +The text stating "from a non-rewindable stream ... implementations +may limit the amount of backwards motion supported" would +allow an implementation that permitted no backwards motion beyond +text already on the screen. It was not possible to require a +minimum amount of backwards motion that would be effective for all +conceivable device types. The implementation should allow the +user to back up as far as possible, within device and reasonable memory +allocation constraints. +.LP +Historically, non-printable characters were displayed using the ARPA +standard mappings, which are as follows: +.IP " 1." 4 +Printable characters are left alone. +.LP +.IP " 2." 4 +Control characters less than \\177 are represented as followed by +the character offset from the \fB'@'\fP character in the +ASCII map; for example, \\007 is represented as \fB'G'\fP . +.LP +.IP " 3." 4 +\\177 is represented as followed by \fB'?'\fP . +.LP +.LP +The display of characters having their eighth bit set was less standard. +Existing implementations use hex (0x00), octal (\\000), +and a meta-bit display. (The latter displayed characters with their +eighth bit set as the two characters \fB"M-"\fP , followed +by the seven-bit display as described previously.) The latter probably +has the best claim to historical practice because it was +used with the \fB-v\fP option of 4 BSD and 4 BSD-derived versions +of the \fIcat\fP utility +since 1980. +.LP +No specific display format is required by IEEE\ Std\ 1003.1-2001. +Implementations are encouraged to conform to historic +practice in the absence of any strong reason to diverge. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP , \fIctags\fP , \fIed\fP , \fIex\fP , +\fIvi\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/mv.1p b/man1p/mv.1p new file mode 100644 index 000000000..e01faddf6 --- /dev/null +++ b/man1p/mv.1p @@ -0,0 +1,376 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mv +.SH NAME +mv \- move files +.SH SYNOPSIS +.LP +\fBmv\fP \fB[\fP\fB-fi\fP\fB]\fP \fIsource_file target_file\fP\fB +.br +.sp +mv\fP \fB[\fP\fB-fi\fP\fB]\fP \fIsource_file\fP\fB...\fP \fItarget_file\fP\fB +.br +\fP +.SH DESCRIPTION +.LP +In the first synopsis form, the \fImv\fP utility shall move the file +named by the \fIsource_file\fP operand to the destination +specified by the \fItarget_file\fP. This first synopsis form is assumed +when the final operand does not name an existing directory +and is not a symbolic link referring to an existing directory. +.LP +In the second synopsis form, \fImv\fP shall move each file named by +a \fIsource_file\fP operand to a destination file in the +existing directory named by the \fItarget_dir\fP operand, or referenced +if \fItarget_dir\fP is a symbolic link referring to an +existing directory. The destination path for each \fIsource_file\fP +shall be the concatenation of the target directory, a single +slash character, and the last pathname component of the \fIsource_file\fP. +This second form is assumed when the final operand +names an existing directory. +.LP +If any operand specifies an existing file of a type not specified +by the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, the behavior is implementation-defined. +.LP +For each \fIsource_file\fP the following steps shall be taken: +.IP " 1." 4 +If the destination path exists, the \fB-f\fP option is not specified, +and either of the following conditions is true: +.RS +.IP " a." 4 +The permissions of the destination path do not permit writing and +the standard input is a terminal. +.LP +.IP " b." 4 +The \fB-i\fP option is specified. +.LP +.RE +.LP +the \fImv\fP utility shall write a prompt to standard error and read +a line from standard input. If the response is not +affirmative, \fImv\fP shall do nothing more with the current \fIsource_file\fP +and go on to any remaining +\fIsource_file\fPs. +.LP +.IP " 2." 4 +The \fImv\fP utility shall perform actions equivalent to the \fIrename\fP() +function +defined in the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +called with the following arguments: +.RS +.IP " a." 4 +The \fIsource_file\fP operand is used as the \fIold\fP argument. +.LP +.IP " b." 4 +The destination path is used as the \fInew\fP argument. +.LP +.RE +.LP +If this succeeds, \fImv\fP shall do nothing more with the current +\fIsource_file\fP and go on to any remaining +\fIsource_file\fPs. If this fails for any reasons other than those +described for the \fIerrno\fP [EXDEV] in the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, \fImv\fP shall write a diagnostic +message to standard error, do nothing more with the +current \fIsource_file\fP, and go on to any remaining \fIsource_file\fPs. +.LP +.IP " 3." 4 +If the destination path exists, and it is a file of type directory +and \fIsource_file\fP is not a file of type directory, or it +is a file not of type directory and \fIsource_file\fP is a file of +type directory, \fImv\fP shall write a diagnostic message to +standard error, do nothing more with the current \fIsource_file\fP, +and go on to any remaining \fIsource_file\fPs. +.LP +.IP " 4." 4 +If the destination path exists, \fImv\fP shall attempt to remove it. +If this fails for any reason, \fImv\fP shall write a +diagnostic message to standard error, do nothing more with the current +\fIsource_file\fP, and go on to any remaining +\fIsource_file\fPs. +.LP +.IP " 5." 4 +The file hierarchy rooted in \fIsource_file\fP shall be duplicated +as a file hierarchy rooted in the destination path. If +\fIsource_file\fP or any of the files below it in the hierarchy are +symbolic links, the links themselves shall be duplicated, +including their contents, rather than any files to which they refer. +The following characteristics of each file in the file +hierarchy shall be duplicated: +.RS +.IP " *" 3 +The time of last data modification and time of last access +.LP +.IP " *" 3 +The user ID and group ID +.LP +.IP " *" 3 +The file mode +.LP +.RE +.LP +If the user ID, group ID, or file mode of a regular file cannot be +duplicated, the file mode bits S_ISUID and S_ISGID shall not +be duplicated. +.LP +When files are duplicated to another file system, the implementation +may require that the process invoking \fImv\fP has read +access to each file being duplicated. +.LP +If the duplication of the file hierarchy fails for any reason, \fImv\fP +shall write a diagnostic message to standard error, do +nothing more with the current \fIsource_file\fP, and go on to any +remaining \fIsource_file\fPs. +.LP +If the duplication of the file characteristics fails for any reason, +\fImv\fP shall write a diagnostic message to standard +error, but this failure shall not cause \fImv\fP to modify its exit +status. +.LP +.IP " 6." 4 +The file hierarchy rooted in \fIsource_file\fP shall be removed. If +this fails for any reason, \fImv\fP shall write a +diagnostic message to the standard error, do nothing more with the +current \fIsource_file\fP, and go on to any remaining +\fIsource_file\fPs. +.LP +.SH OPTIONS +.LP +The \fImv\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-f\fP +Do not prompt for confirmation if the destination path exists. Any +previous occurrence of the \fB-i\fP option is ignored. +.TP 7 +\fB-i\fP +Prompt for confirmation if the destination path exists. Any previous +occurrence of the \fB-f\fP option is ignored. +.sp +.LP +Specifying more than one of the \fB-f\fP or \fB-i\fP options shall +not be considered an error. The last option specified shall +determine the behavior of \fImv\fP. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIsource_file\fP +A pathname of a file or directory to be moved. +.TP 7 +\fItarget_file\fP +A new pathname for the file or directory being moved. +.TP 7 +\fItarget_dir\fP +A pathname of an existing directory into which to move the input files. +.sp +.SH STDIN +.LP +The standard input shall be used to read an input line in response +to each prompt specified in the STDERR section. Otherwise, +the standard input shall not be used. +.SH INPUT FILES +.LP +The input files specified by each \fIsource_file\fP operand can be +of any file type. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fImv\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended +regular expression defined for the \fByesexpr\fP locale keyword in +the \fILC_MESSAGES\fP category. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), the +behavior of character classes used in the extended regular +expression defined for the \fByesexpr\fP locale keyword in the \fILC_MESSAGES\fP +category. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale for the processing of affirmative responses that +should be used to affect the format and contents of +diagnostic messages written to standard error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +Prompts shall be written to the standard error under the conditions +specified in the DESCRIPTION section. The prompts shall +contain the destination pathname, but their format is otherwise unspecified. +Otherwise, the standard error shall be used only for +diagnostic messages. +.SH OUTPUT FILES +.LP +The output files may be of any file type. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All input files were moved successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If the copying or removal of \fIsource_file\fP is prematurely terminated +by a signal or error, \fImv\fP may leave a partial +copy of \fIsource_file\fP at the source or destination. The \fImv\fP +utility shall not modify both \fIsource_file\fP and the +destination path simultaneously; termination at any point shall leave +either \fIsource_file\fP or the destination path +complete. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Some implementations mark for update the \fIst_ctime\fP field of renamed +files and some do not. Applications which make use of +the \fIst_ctime\fP field may behave differently with respect to renamed +files unless they are designed to allow for either +behavior. +.SH EXAMPLES +.LP +If the current directory contains only files \fBa\fP (of any type +defined by the System Interfaces volume of +IEEE\ Std\ 1003.1-2001), \fBb\fP (also of any type), and a directory +\fBc\fP: +.sp +.RS +.nf + +\fBmv a b c +mv c d +\fP +.fi +.RE +.LP +results with the original files \fBa\fP and \fBb\fP residing in the +directory \fBd\fP in the current directory. +.SH RATIONALE +.LP +Early proposals diverged from the SVID and BSD historical practice +in that they required that when the destination path exists, +the \fB-f\fP option is not specified, and input is not a terminal, +\fImv\fP fails. This was done for compatibility with \fIcp\fP. The +current text returns to historical practice. It should be noted that +this is consistent +with the \fIrename\fP() function defined in the System Interfaces +volume of +IEEE\ Std\ 1003.1-2001, which does not require write permission on +the target. +.LP +For absolute clarity, paragraph (1), describing the behavior of \fImv\fP +when prompting for confirmation, should be interpreted +in the following manner: +.sp +.RS +.nf + +\fBif (exists AND (NOT f_option) AND + ((not_writable AND input_is_terminal) OR i_option)) +\fP +.fi +.RE +.LP +The \fB-i\fP option exists on BSD systems, giving applications and +users a way to avoid accidentally unlinking files when +moving others. When the standard input is not a terminal, the 4.3 +BSD \fImv\fP deletes all existing destination paths without +prompting, even when \fB-i\fP is specified; this is inconsistent with +the behavior of the 4.3 BSD \fIcp\fP utility, which always generates +an error when the file is unwritable and the standard input is +not a terminal. The standard developers decided that use of \fB-i\fP +is a request for interaction, so when the destination path +exists, the utility takes instructions from whatever responds to standard +input. +.LP +The \fIrename\fP() function is able to move directories within the +same file system. +Some historical versions of \fImv\fP have been able to move directories, +but not to a different file system. The standard +developers considered that this was an annoying inconsistency, so +this volume of IEEE\ Std\ 1003.1-2001 requires +directories to be able to be moved even across file systems. There +is no \fB-R\fP option to confirm that moving a directory is +actually intended, since such an option was not required for moving +directories in historical practice. Requiring the application +to specify it sometimes, depending on the destination, seemed just +as inconsistent. The semantics of the \fIrename\fP() function were +preserved as much as possible. For example, \fImv\fP is not permitted +to "rename" files to or from directories, even though they might be +empty and removable. +.LP +Historic implementations of \fImv\fP did not exit with a non-zero +exit status if they were unable to duplicate any file +characteristics when moving a file across file systems, nor did they +write a diagnostic message for the user. The former behavior +has been preserved to prevent scripts from breaking; a diagnostic +message is now required, however, so that users are alerted that +the file characteristics have changed. +.LP +The exact format of the interactive prompts is unspecified. Only the +general nature of the contents of prompts are specified +because implementations may desire more descriptive prompts than those +used on historical implementations. Therefore, an +application not using the \fB-f\fP option or using the \fB-i\fP option +relies on the system to provide the most suitable dialog +directly with the user, based on the behavior specified. +.LP +When \fImv\fP is dealing with a single file system and \fIsource_file\fP +is a symbolic link, the link itself is moved as a +consequence of the dependence on the \fIrename\fP() functionality, +per the DESCRIPTION. +Across file systems, this has to be made explicit. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcp\fP , \fIln\fP , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIrename\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/newgrp.1p b/man1p/newgrp.1p new file mode 100644 index 000000000..3452c6d78 --- /dev/null +++ b/man1p/newgrp.1p @@ -0,0 +1,267 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "NEWGRP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" newgrp +.SH NAME +newgrp \- change to a new group +.SH SYNOPSIS +.LP +\fBnewgrp\fP \fB[\fP\fB-l\fP\fB][\fP\fIgroup\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fInewgrp\fP utility shall create a new shell execution environment +with a new real and effective group identification. Of +the attributes listed in \fIShell Execution Environment\fP , the new +shell execution +environment shall retain the working directory, file creation mask, +and exported variables from the previous environment (that is, +open files, traps, unexported variables, alias definitions, shell +functions, and \fIset\fP options may be lost). All other aspects of +the process environment that are +preserved by the \fIexec\fP family of functions defined in the System +Interfaces volume of IEEE\ Std\ 1003.1-2001 shall +also be preserved by \fInewgrp\fP; whether other aspects are preserved +is unspecified. +.LP +A failure to assign the new group identifications (for example, for +security or password-related reasons) shall not prevent the +new shell execution environment from being created. +.LP +The \fInewgrp\fP utility shall affect the supplemental groups for +the process as follows: +.IP " *" 3 +On systems where the effective group ID is normally in the supplementary +group list (or whenever the old effective group ID +actually is in the supplementary group list): +.RS +.IP " *" 3 +If the new effective group ID is also in the supplementary group list, +\fInewgrp\fP shall change the effective group ID. +.LP +.IP " *" 3 +If the new effective group ID is not in the supplementary group list, +\fInewgrp\fP shall add the new effective group ID to the +list, if there is room to add it. +.LP +.RE +.LP +.IP " *" 3 +On systems where the effective group ID is not normally in the supplementary +group list (or whenever the old effective group ID +is not in the supplementary group list): +.RS +.IP " *" 3 +If the new effective group ID is in the supplementary group list, +\fInewgrp\fP shall delete it. +.LP +.IP " *" 3 +If the old effective group ID is not in the supplementary list, \fInewgrp\fP +shall add it if there is room. +.LP +.RE +.LP +.TP 7 +\fBNote:\fP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001 does not specify +whether the effective group ID of a process is +included in its supplementary group list. +.sp +.LP +With no operands, \fInewgrp\fP shall change the effective group back +to the groups identified in the user's user entry, and +shall set the list of supplementary groups to that set in the user's +group database entries. +.LP +If a password is required for the specified group, and the user is +not listed as a member of that group in the group database, +the user shall be prompted to enter the correct password for that +group. If the user is listed as a member of that group, no +password shall be requested. If no password is required for the specified +group, it is implementation-defined whether users not +listed as members of that group can change to that group. Whether +or not a password is required, implementation-defined system +accounting or security mechanisms may impose additional authorization +restrictions that may cause \fInewgrp\fP to write a +diagnostic message and suppress the changing of the group identification. +.SH OPTIONS +.LP +The \fInewgrp\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-l\fP +(The letter ell.) Change the environment to what would be expected +if the user actually logged in again. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIgroup\fP +A group name from the group database or a non-negative numeric group +ID. Specifies the group ID to which the real and effective +group IDs shall be set. If \fIgroup\fP is a non-negative numeric string +and exists in the group database as a group name (see \fIgetgrnam\fP()), +the numeric group ID associated with that group name shall be used +as the +group ID. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +The file \fB/dev/tty\fP shall be used to read a single line of text +for password checking, when one is required. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fInewgrp\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used for diagnostic messages and a prompt +string for a password, if one is required. Diagnostic +messages may be written in cases where the exit status is not available. +See the EXIT STATUS section. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +If \fInewgrp\fP succeeds in creating a new shell execution environment, +whether or not the group identification was changed +successfully, the exit status shall be the exit status of the shell. +Otherwise, the following exit value shall be returned: +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +The invoking shell may terminate. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +There is no convenient way to enter a password into the group database. +Use of group passwords is not encouraged, because by +their very nature they encourage poor security practices. Group passwords +may disappear in the future. +.LP +A common implementation of \fInewgrp\fP is that the current shell +uses \fIexec\fP to overlay itself with \fInewgrp\fP, which +in turn overlays itself with a new shell after changing group. On +some implementations, however, this may not occur and +\fInewgrp\fP may be invoked as a subprocess. +.LP +The \fInewgrp\fP command is intended only for use from an interactive +terminal. It does not offer a useful interface for the +support of applications. +.LP +The exit status of \fInewgrp\fP is generally inapplicable. If \fInewgrp\fP +is used in a script, in most cases it successfully +invokes a new shell and the rest of the original shell script is bypassed +when the new shell exits. Used interactively, +\fInewgrp\fP displays diagnostic messages to indicate problems. But +usage such as: +.sp +.RS +.nf + +\fBnewgrp foo +echo $? +\fP +.fi +.RE +.LP +is not useful because the new shell might not have access to any status +\fInewgrp\fP may have generated (and most historical +systems do not provide this status). A zero status echoed here does +not necessarily indicate that the user has changed to the new +group successfully. Following \fInewgrp\fP with the \fIid\fP command +provides a portable means +of determining whether the group change was successful or not. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +Most historical implementations use one of the \fIexec\fP functions +to implement the behavior of \fInewgrp\fP. Errors detected +before the \fIexec\fP leave the environment unchanged, while errors +detected after the \fIexec\fP leave the user in a changed +environment. While it would be useful to have \fInewgrp\fP issue a +diagnostic message to tell the user that the environment +changed, it would be inappropriate to require this change to some +historical implementations. +.LP +The password mechanism is allowed in the group database, but how this +would be implemented is not specified. +.LP +The \fInewgrp\fP utility was retained in this volume of IEEE\ Std\ 1003.1-2001, +even given the existence of the +multiple group permissions feature in the System Interfaces volume +of IEEE\ Std\ 1003.1-2001, for several reasons. First, +in some implementations, the group ownership of a newly created file +is determined by the group of the directory in which the file +is created, as allowed by the System Interfaces volume of IEEE\ Std\ 1003.1-2001; +on other implementations, the group +ownership of a newly created file is determined by the effective group +ID. On implementations of the latter type, \fInewgrp\fP +allows files to be created with a specific group ownership. Finally, +many implementations use the real group ID in accounting, and +on such systems, \fInewgrp\fP allows the accounting identity of the +user to be changed. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP , \fIsh\fP , the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, \fIexec\fP, \fIgetgrnam\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/nice.1p b/man1p/nice.1p new file mode 100644 index 000000000..adcd4f46a --- /dev/null +++ b/man1p/nice.1p @@ -0,0 +1,253 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "NICE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" nice +.SH NAME +nice \- invoke a utility with an altered nice value +.SH SYNOPSIS +.LP +\fBnice\fP \fB[\fP\fB-n\fP \fIincrement\fP\fB]\fP \fIutility\fP +\fB[\fP\fIargument\fP\fB...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fInice\fP utility shall invoke a utility, requesting that it +be run with a different nice value (see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 3.239, Nice Value). With +no +options and only if the user has appropriate privileges, the executed +utility shall be run with a nice value that is some +implementation-defined quantity less than or equal to the nice value +of the current process. If the user lacks appropriate +privileges to affect the nice value in the requested manner, the \fInice\fP +utility shall not affect the nice value; in this case, +a warning message may be written to standard error, but this shall +not prevent the invocation of \fIutility\fP or affect the exit +status. +.SH OPTIONS +.LP +The \fInice\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option is supported: +.TP 7 +\fB-n\ \fP \fIincrement\fP +A positive or negative decimal integer which shall have the same effect +on the execution of the utility as if the utility had +called the \fInice\fP() function with the numeric value of the \fIincrement\fP +option-argument. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIutility\fP +The name of a utility that is to be invoked. If the \fIutility\fP +operand names any of the special built-in utilities in \fISpecial +Built-In Utilities\fP , the results are undefined. +.TP 7 +\fIargument\fP +Any string to be supplied as an argument when invoking the utility +named by the \fIutility\fP operand. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fInice\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPATH\fP +Determine the search path used to locate the utility to be invoked. +See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +If \fIutility\fP is invoked, the exit status of \fInice\fP shall be +the exit status of \fIutility\fP; otherwise, the +\fInice\fP utility shall exit with one of the following values: +.TP 7 +1-125 +An error occurred in the \fInice\fP utility. +.TP 7 +\ \ 126 +The utility specified by \fIutility\fP was found but could not be +invoked. +.TP 7 +\ \ 127 +The utility specified by \fIutility\fP could not be found. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The only guaranteed portable uses of this utility are: +.TP 7 +\fInice\ utility\fP +.sp +Run \fIutility\fP with the default lower nice value. +.TP 7 +\fInice\ \fP \fB-n\ \fP <\fIpositive\ integer\fP>\fI\ utility\fP +.sp +Run \fIutility\fP with a lower nice value. +.sp +.LP +On some implementations they have no discernible effect on the invoked +utility and on some others they are exactly +equivalent. +.LP +Historical systems have frequently supported the <\fIpositive integer\fP> +up to 20. Since there is no error penalty +associated with guessing a number that is too high, users without +access to the system conformance document (to see what limits are +actually in place) could use the historical 1 to 20 range or attempt +to use very large numbers if the job should be truly low +priority. +.LP +The nice value of a process can be displayed using the command: +.sp +.RS +.nf + +\fBps -o nice +\fP +.fi +.RE +.LP +The \fIcommand\fP, \fIenv\fP, \fInice\fP, \fInohup\fP, \fItime\fP, +and \fIxargs\fP utilities have been specified to use exit code 127 +if an error occurs so that +applications can distinguish "failure to find a utility" from "invoked +utility exited with an error indication". The value 127 +was chosen because it is not commonly used for other meanings; most +utilities use small values for "normal error conditions" and +the values above 128 can be confused with termination due to receipt +of a signal. The value 126 was chosen in a similar manner to +indicate that the utility could be found, but not invoked. Some scripts +produce meaningful error messages differentiating the 126 +and 127 cases. The distinction between exit codes 126 and 127 is based +on KornShell practice that uses 127 when all attempts to +\fIexec\fP the utility fail with [ENOENT], and uses 126 when any attempt +to \fIexec\fP the utility fails for any other +reason. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +Due to the text about the limits of the nice value being implementation-defined, +\fInice\fP is not actually required to change +the nice value of the executed command; the limits could be zero differences +from the system default, although the implementor is +required to document this fact in the conformance document. +.LP +The 4.3 BSD version of \fInice\fP does not check whether \fIincrement\fP +is a valid decimal integer. The command \fInice\fP +\fB-x\fP \fIutility\fP, for example, would be treated the same as +the command \fInice\fP \fB--1\fP \fIutility\fP. If the user +does not have appropriate privileges, this results in a "permission +denied" error. This is considered a bug. +.LP +When a user without appropriate privileges gives a negative \fIincrement\fP, +System V treats it like the command \fInice\fP +\fB-0\fP \fIutility\fP, while 4.3 BSD writes a "permission denied" +message and does not run the utility. Neither was considered +clearly superior, so the behavior was left unspecified. +.LP +The C shell has a built-in version of \fInice\fP that has a different +interface from the one described in this volume of +IEEE\ Std\ 1003.1-2001. +.LP +The term "utility" is used, rather than "command", to highlight the +fact that shell compound commands, pipelines, and so on, +cannot be used. Special built-ins also cannot be used. However, "utility" +includes user application programs and shell scripts, +not just utilities defined in this volume of IEEE\ Std\ 1003.1-2001. +.LP +Historical implementations of \fInice\fP provide a nice value range +of 40 or 41 discrete steps, with the default nice value +being the midpoint of that range. By default, they lower the nice +value of the executed utility by 10. +.LP +Some historical documentation states that the \fIincrement\fP value +must be within a fixed range. This is misleading; the valid +\fIincrement\fP values on any invocation are determined by the current +process nice value, which is not always the default. +.LP +The definition of nice value is not intended to suggest that all processes +in a system have priorities that are comparable. +Scheduling policy extensions such as the realtime priorities in the +System Interfaces volume of IEEE\ Std\ 1003.1-2001 make +the notion of a single underlying priority for all scheduling policies +problematic. Some implementations may implement the +\fInice\fP-related features to affect all processes on the system, +others to affect just the general time-sharing activities +implied by this volume of IEEE\ Std\ 1003.1-2001, and others may have +no effect at all. Because of the use of +"implementation-defined" in \fInice\fP and \fIrenice\fP, a wide range +of implementation +strategies are possible. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP , \fIrenice\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fInice\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/nl.1p b/man1p/nl.1p new file mode 100644 index 000000000..5a76eb1c6 --- /dev/null +++ b/man1p/nl.1p @@ -0,0 +1,285 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "NL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" nl +.SH NAME +nl \- line numbering filter +.SH SYNOPSIS +.LP +\fBnl\fP \fB[\fP\fB-p\fP\fB][\fP\fB-b\fP \fItype\fP\fB][\fP\fB-d\fP +\fIdelim\fP\fB][\fP\fB-f\fP \fItype\fP\fB][\fP\fB-h\fP \fItype\fP\fB][\fP\fB-i\fP +\fIincr\fP\fB][\fP\fB-l\fP +\fInum\fP\fB][\fP\fB-n\fP \fIformat\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-s\fP \fIsep\fP\fB][\fP\fB-v\fP +\fIstartnum\fP\fB][\fP\fB-w\fP \fIwidth\fP\fB][\fP\fIfile\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fInl\fP utility shall read lines from the named \fIfile\fP or +the standard input if no \fIfile\fP is named and shall +reproduce the lines to standard output. Lines shall be numbered on +the left. Additional functionality may be provided in accordance +with the command options in effect. +.LP +The \fInl\fP utility views the text it reads in terms of logical pages. +Line numbering shall be reset at the start of each +logical page. A logical page consists of a header, a body, and a footer +section. Empty sections are valid. Different line numbering +options are independently available for header, body, and footer (for +example, no numbering of header and footer lines while +numbering blank lines only in the body). +.LP +The starts of logical page sections shall be signaled by input lines +containing nothing but the following delimiter +characters: +.TS C +center; l l. +\fBLine\fP \fBStart of\fP +\\:\\:\\: Header +\\:\\: Body +\\: Footer +.TE +.LP +Unless otherwise specified, \fInl\fP shall assume the text being read +is in a single logical page body. +.SH OPTIONS +.LP +The \fInl\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +Only one file can be named. +.LP +The following options shall be supported: +.TP 7 +\fB-b\ \fP \fItype\fP +Specify which logical page body lines shall be numbered. Recognized +\fItypes\fP and their meaning are: +.TP 7 +\fBa\fP +.RS +Number all lines. +.RE +.TP 7 +\fBt\fP +.RS +Number only non-empty lines. +.RE +.TP 7 +\fBn\fP +.RS +No line numbering. +.RE +.TP 7 +\fBp\fP\fIstring\fP +.RS +Number only lines that contain the basic regular expression specified +in \fIstring\fP. +.RE +.sp +.LP +The default \fItype\fP for logical page body shall be \fBt\fP (text +lines numbered). +.TP 7 +\fB-d\ \fP \fIdelim\fP +Specify the delimiter characters that indicate the start of a logical +page section. These can be changed from the default +characters \fB"\\:"\fP to two user-specified characters. If only one +character is entered, the second character shall remain the +default character \fB':'\fP . +.TP 7 +\fB-f\ \fP \fItype\fP +Specify the same as \fBb\fP \fItype\fP except for footer. The default +for logical page footer shall be \fBn\fP (no lines +numbered). +.TP 7 +\fB-h\ \fP \fItype\fP +Specify the same as \fBb\fP \fItype\fP except for header. The default +\fItype\fP for logical page header shall be \fBn\fP +(no lines numbered). +.TP 7 +\fB-i\ \fP \fIincr\fP +Specify the increment value used to number logical page lines. The +default shall be 1. +.TP 7 +\fB-l\ \fP \fInum\fP +Specify the number of blank lines to be considered as one. For example, +\fB-l\ 2\fP results in only the second adjacent +blank line being numbered (if the appropriate \fB-h\ a\fP, \fB-b\ a\fP, +or \fB-f\ a\fP option is set). The default +shall be 1. +.TP 7 +\fB-n\ \fP \fIformat\fP +Specify the line numbering format. Recognized values are: \fBln\fP, +left justified, leading zeros suppressed; \fBrn\fP, right +justified, leading zeros suppressed; \fBrz\fP, right justified, leading +zeros kept. The default \fIformat\fP shall be \fBrn\fP +(right justified). +.TP 7 +\fB-p\fP +Specify that numbering should not be restarted at logical page delimiters. +.TP 7 +\fB-s\ \fP \fIsep\fP +Specify the characters used in separating the line number and the +corresponding text line. The default \fIsep\fP shall be a +. +.TP 7 +\fB-v\ \fP \fIstartnum\fP +Specify the initial value used to number logical page lines. The default +shall be 1. +.TP 7 +\fB-w\ \fP \fIwidth\fP +Specify the number of characters to be used for the line number. The +default \fIwidth\fP shall be 6. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a text file to be line-numbered. +.sp +.SH STDIN +.LP +The standard input is a text file that is used if no \fIfile\fP operand +is given. +.SH INPUT FILES +.LP +The input file named by the \fIfile\fP operand is a text file. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fInl\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular +expressions. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), the +behavior of character classes within regular expressions, and +for deciding which characters are in character class \fBgraph\fP (for +the \fB-b\ t\fP, \fB-f\ t\fP, and \fB-h\ t\fP +options). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall be a text file in the following format: +.sp +.RS +.nf + +\fB"%s%s%s", <\fP\fIline number\fP\fB>, <\fP\fIseparator\fP\fB>, <\fP\fIinput line\fP\fB> +\fP +.fi +.RE +.LP +where <\fIline\ number\fP> is one of the following numeric formats: +.TP 7 +\fB%6d\fP +When the \fBrn\fP format is used (the default; see \fB-n\fP). +.TP 7 +\fB%06d\fP +When the \fBrz\fP format is used. +.TP 7 +\fB%-6d\fP +When the \fBln\fP format is used. +.TP 7 + +When line numbers are suppressed for a portion of the page; the <\fIseparator\fP> +is also suppressed. +.sp +.LP +In the preceding list, the number 6 is the default width; the \fB-w\fP +option can change this value. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +In using the \fB-d\fP \fIdelim\fP option, care should be taken to +escape characters that have special meaning to the command +interpreter. +.SH EXAMPLES +.LP +The command: +.sp +.RS +.nf + +\fBnl -v 10 -i 10 -d \\!+ file1 +\fP +.fi +.RE +.LP +numbers \fIfile1\fP starting at line number 10 with an increment of +10. The logical page delimiter is \fB"!+"\fP . Note that +the \fB'!'\fP has to be escaped when using \fIcsh\fP as a command +interpreter because of its history substitution syntax. For +\fIksh\fP and \fIsh\fP the escape is not necessary, but does not do +any harm. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpr\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/nm.1p b/man1p/nm.1p new file mode 100644 index 000000000..20a1dbb64 --- /dev/null +++ b/man1p/nm.1p @@ -0,0 +1,392 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "NM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" nm +.SH NAME +nm \- write the name list of an object file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBnm\fP \fB[\fP\fB-APv\fP\fB][\fP\fB-efox\fP\fB][\fP \fB-g| -u\fP\fB][\fP\fB-t\fP +\fIformat\fP\fB]\fP \fIfile\fP\fB... \fP +.SH DESCRIPTION +.LP +This utility shall be provided on systems that support both the User +Portability Utilities option and the Software Development +Utilities option. On other systems it is optional. Certain options +are only available on XSI-conformant systems. +.LP +The \fInm\fP utility shall display symbolic information appearing +in the object file, executable file, or object-file library +named by \fIfile\fP. If no symbolic information is available for a +valid input file, the \fInm\fP utility shall report that fact, +but not consider it an error condition. +.LP +The default base used when numeric values are written is unspecified. +\ On XSI-conformant systems, it shall be decimal. +.SH OPTIONS +.LP +The \fInm\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-A\fP +Write the full pathname or library name of an object on each line. +.TP 7 +\fB-e\fP +Write only external (global) and static symbol information. +.TP 7 +\fB-f\fP +Produce full output. Write redundant symbols ( \fB.text\fP, \fB.data\fP, +and \fB.bss\fP), normally suppressed. +.TP 7 +\fB-g\fP +Write only external (global) symbol information. +.TP 7 +\fB-o\fP +Write numeric values in octal (equivalent to \fB-t\ o\fP). +.TP 7 +\fB-P\fP +Write information in a portable output format, as specified in the +STDOUT section. +.TP 7 +\fB-t\ \fP \fIformat\fP +Write each numeric value in the specified format. The format shall +be dependent on the single character used as the +\fIformat\fP option-argument: +.TP 7 +\fBd\fP +.RS +The offset is written in decimal \ (default). +.RE +.TP 7 +\fBo\fP +.RS +The offset is written in octal. +.RE +.TP 7 +\fBx\fP +.RS +The offset is written in hexadecimal. +.RE +.sp +.TP 7 +\fB-u\fP +Write only undefined symbols. +.TP 7 +\fB-v\fP +Sort output by value instead of alphabetically. +.TP 7 +\fB-x\fP +Write numeric values in hexadecimal (equivalent to \fB-t\ x\fP). +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of an object file, executable file, or object-file library. +.sp +.SH STDIN +.LP +See the INPUT FILES section. +.SH INPUT FILES +.LP +The input file shall be an object file, an object-file library whose +format is the same as those produced by the \fIar\fP utility for link +editing, or an executable file. The \fInm\fP utility may accept additional +implementation-defined object library formats for the input file. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fInm\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for character collation information for the symbol-name +and symbol-value collation sequences. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If symbolic information is present in the input files, then for each +file or for each member of an archive, the \fInm\fP +utility shall write the following information to standard output. +By default, the format is unspecified, but the output shall be +sorted alphabetically by symbol name: +.IP " *" 3 +Library or object name, if \fB-A\fP is specified +.LP +.IP " *" 3 +Symbol name +.LP +.IP " *" 3 +Symbol type, which shall either be one of the following single characters +or an implementation-defined type represented by a +single character: +.TP 7 +\fBA\fP +.RS +Global absolute symbol. +.RE +.TP 7 +\fBa\fP +.RS +Local absolute symbol. +.RE +.TP 7 +\fBB\fP +.RS +Global "bss" (that is, uninitialized data space) symbol. +.RE +.TP 7 +\fBb\fP +.RS +Local bss symbol. +.RE +.TP 7 +\fBD\fP +.RS +Global data symbol. +.RE +.TP 7 +\fBd\fP +.RS +Local data symbol. +.RE +.TP 7 +\fBT\fP +.RS +Global text symbol. +.RE +.TP 7 +\fBt\fP +.RS +Local text symbol. +.RE +.TP 7 +\fBU\fP +.RS +Undefined symbol. +.RE +.sp +.LP +.IP " *" 3 +Value of the symbol +.LP +.IP " *" 3 +The size associated with the symbol, if applicable +.LP +.LP +This information may be supplemented by additional information specific +to the implementation. +.LP +If the \fB-P\fP option is specified, the previous information shall +be displayed using the following portable format. The three +versions differ depending on whether \fB-t\ d\fP, \fB-t\ o\fP, or +\fB-t\ x\fP was specified, respectively: +.sp +.RS +.nf + +\fB"%s%s %s %d %d\\n", <\fP\fIlibrary/object name\fP\fB>, <\fP\fIname\fP\fB>, <\fP\fItype\fP\fB>, + <\fP\fIvalue\fP\fB>, <\fP\fIsize\fP\fB> +.sp + +"%s%s %s %o %o\\n", <\fP\fIlibrary/object name\fP\fB>, <\fP\fIname\fP\fB>, <\fP\fItype\fP\fB>, + <\fP\fIvalue\fP\fB>, <\fP\fIsize\fP\fB> +.sp + +"%s%s %s %x %x\\n", <\fP\fIlibrary/object name\fP\fB>, <\fP\fIname\fP\fB>, <\fP\fItype\fP\fB>, + <\fP\fIvalue\fP\fB>, <\fP\fIsize\fP\fB> +\fP +.fi +.RE +where <\fIlibrary/object\ name\fP> shall be formatted as follows: +.IP " *" 3 +If \fB-A\fP is not specified, <\fIlibrary/object\ name\fP> shall be +an empty string. +.LP +.IP " *" 3 +If \fB-A\fP is specified and the corresponding \fIfile\fP operand +does not name a library: +.sp +.RS +.nf + +\fB"%s: ", <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +.IP " *" 3 +If \fB-A\fP is specified and the corresponding \fIfile\fP operand +names a library. In this case, +<\fIobject\ file\fP> shall name the object file in the library containing +the symbol being described: +.sp +.RS +.nf + +\fB"%s[%s]: ", <\fP\fIfile\fP\fB>, <\fP\fIobject file\fP\fB> +\fP +.fi +.RE +.LP +.LP +If \fB-A\fP is not specified, then if more than one \fIfile\fP operand +is specified or if only one \fIfile\fP operand is +specified and it names a library, \fInm\fP shall write a line identifying +the object containing the following symbols before the +lines containing those symbols, in the form: +.IP " *" 3 +If the corresponding \fIfile\fP operand does not name a library: +.sp +.RS +.nf + +\fB"%s:\\n", <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +.IP " *" 3 +If the corresponding \fIfile\fP operand names a library; in this case, +<\fIobject\ file\fP> shall be the name of the +file in the library containing the following symbols: +.sp +.RS +.nf + +\fB"%s[%s]:\\n", <\fP\fIfile\fP\fB>, <\fP\fIobject file\fP\fB> +\fP +.fi +.RE +.LP +.LP +If \fB-P\fP is specified, but \fB-t\fP is not, the format shall be +as if \fB-t\ x\fP had been specified. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Mechanisms for dynamic linking make this utility less meaningful when +applied to an executable file because a dynamically linked +executable may omit numerous library routines that would be found +in a statically linked executable. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +Historical implementations of \fInm\fP have used different bases for +numeric output and supplied different default types of +symbols that were reported. The \fB-t\fP \fIformat\fP option, similar +to that used in \fIod\fP and \fIstrings\fP, can be used to specify +the numeric +base; \fB-g\fP and \fB-u\fP can be used to restrict the amount of +output or the types of symbols included in the output. +.LP +The compromise of using \fB-t\fP \fIformat\fP \fIversus\fP using \fB-d\fP, +\fB-o\fP, and other similar options was +necessary because of differences in the meaning of \fB-o\fP between +implementations. The \fB-o\fP option from BSD has been +provided here as \fB-A\fP to avoid confusion with the \fB-o\fP from +System V (which has been provided here as \fB-t\fP and as +\fB-o\fP on XSI-conformant systems). +.LP +The option list was significantly reduced from that provided by historical +implementations. +.LP +The \fInm\fP description is a subset of both the System V and BSD +\fInm\fP utilities with no specified default output. +.LP +It was recognized that mechanisms for dynamic linking make this utility +less meaningful when applied to an executable file +(because a dynamically linked executable file may omit numerous library +routines that would be found in a statically linked +executable file), but the value of \fInm\fP during software development +was judged to outweigh other limitations. +.LP +The default output format of \fInm\fP is not specified because of +differences in historical implementations. The \fB-P\fP +option was added to allow some type of portable output format. After +a comparison of the different formats used in SunOS, BSD, +SVR3, and SVR4, it was decided to create one that did not match the +current format of any of these four systems. The format devised +is easy to parse by humans, easy to parse in shell scripts, and does +not need to vary depending on locale (because no English +descriptions are included). All of the systems currently have the +information available to use this format. +.LP +The format given in \fInm\fP STDOUT uses spaces between the fields, +which may be any number of s required to align +the columns. The single-character types were selected to match historical +practice, and the requirement that implementation +additions also be single characters made parsing the information easier +for shell scripts. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIar\fP , \fIc99\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/nohup.1p b/man1p/nohup.1p new file mode 100644 index 000000000..893218fd9 --- /dev/null +++ b/man1p/nohup.1p @@ -0,0 +1,215 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "NOHUP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" nohup +.SH NAME +nohup \- invoke a utility immune to hangups +.SH SYNOPSIS +.LP +\fBnohup\fP \fIutility\fP \fB[\fP\fIargument\fP\fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fInohup\fP utility shall invoke the utility named by the \fIutility\fP +operand with arguments supplied as the +\fIargument\fP operands. At the time the named \fIutility\fP is invoked, +the SIGHUP signal shall be set to be ignored. +.LP +If the standard output is a terminal, all output written by the named +\fIutility\fP to its standard output shall be appended to +the end of the file \fBnohup.out\fP in the current directory. If \fBnohup.out\fP +cannot be created or opened for appending, the +output shall be appended to the end of the file \fBnohup.out\fP in +the directory specified by the \fIHOME\fP environment +variable. If neither file can be created or opened for appending, +\fIutility\fP shall not be invoked. If a file is created, the +file's permission bits shall be set to S_IRUSR | S_IWUSR. +.LP +If the standard error is a terminal, all output written by the named +\fIutility\fP to its standard error shall be redirected to +the same file descriptor as the standard output. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIutility\fP +The name of a utility that is to be invoked. If the \fIutility\fP +operand names any of the special built-in utilities in \fISpecial +Built-In Utilities\fP , the results are undefined. +.TP 7 +\fIargument\fP +Any string to be supplied as an argument when invoking the utility +named by the \fIutility\fP operand. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fInohup\fP: +.TP 7 +\fIHOME\fP +Determine the pathname of the user's home directory: if the output +file \fBnohup.out\fP cannot be created in the current +directory, the \fInohup\fP utility shall use the directory named by +\fIHOME\fP to create the file. +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPATH\fP +Determine the search path that is used to locate the utility to be +invoked. See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +The \fInohup\fP utility shall take the standard action for all signals +except that SIGHUP shall be ignored. +.SH STDOUT +.LP +If the standard output is not a terminal, the standard output of \fInohup\fP +shall be the standard output generated by the +execution of the \fIutility\fP specified by the operands. Otherwise, +nothing shall be written to the standard output. +.SH STDERR +.LP +If the standard output is a terminal, a message shall be written to +the standard error, indicating the name of the file to which +the output is being appended. The name of the file shall be either +\fBnohup.out\fP or \fB$HOME/nohup.out\fP. +.SH OUTPUT FILES +.LP +If the standard output is a terminal, all output written by the named +\fIutility\fP to the standard output and standard error +is appended to the file \fBnohup.out\fP, which is created if it does +not already exist. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +126 +The utility specified by \fIutility\fP was found but could not be +invoked. +.TP 7 +127 +An error occurred in the \fInohup\fP utility or the utility specified +by \fIutility\fP could not be found. +.sp +.LP +Otherwise, the exit status of \fInohup\fP shall be that of the utility +specified by the \fIutility\fP operand. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fIcommand\fP, \fIenv\fP, \fInice\fP, \fInohup\fP, \fItime\fP, +and \fIxargs\fP utilities have been specified to use exit code 127 +if an error occurs so that +applications can distinguish "failure to find a utility" from "invoked +utility exited with an error indication". The value 127 +was chosen because it is not commonly used for other meanings; most +utilities use small values for "normal error conditions" and +the values above 128 can be confused with termination due to receipt +of a signal. The value 126 was chosen in a similar manner to +indicate that the utility could be found, but not invoked. Some scripts +produce meaningful error messages differentiating the 126 +and 127 cases. The distinction between exit codes 126 and 127 is based +on KornShell practice that uses 127 when all attempts to +\fIexec\fP the utility fail with [ENOENT], and uses 126 when any attempt +to \fIexec\fP the utility fails for any other +reason. +.SH EXAMPLES +.LP +It is frequently desirable to apply \fInohup\fP to pipelines or lists +of commands. This can be done by placing pipelines and +command lists in a single file; this file can then be invoked as a +utility, and the \fInohup\fP applies to everything in the +file. +.LP +Alternatively, the following command can be used to apply \fInohup\fP +to a complex command: +.sp +.RS +.nf + +\fBnohup sh -c '\fP\fIcomplex-command-line\fP\fB' +\fP +.fi +.RE +.SH RATIONALE +.LP +The 4.3 BSD version ignores SIGTERM and SIGHUP, and if \fB./nohup.out\fP +cannot be used, it fails instead of trying to use +\fB$HOME/nohup.out\fP. +.LP +The \fIcsh\fP utility has a built-in version of \fInohup\fP that acts +differently from the \fInohup\fP defined in this volume +of IEEE\ Std\ 1003.1-2001. +.LP +The term \fIutility\fP is used, rather than \fIcommand\fP, to highlight +the fact that shell compound commands, pipelines, +special built-ins, and so on, cannot be used directly. However, \fIutility\fP +includes user application programs and shell +scripts, not just the standard utilities. +.LP +Historical versions of the \fInohup\fP utility use default file creation +semantics. Some more recent versions use the +permissions specified here as an added security precaution. +.LP +Some historical implementations ignore SIGQUIT in addition to SIGHUP; +others ignore SIGTERM. An early proposal allowed, but did +not require, SIGQUIT to be ignored. Several reviewers objected that +\fInohup\fP should only modify the handling of SIGHUP as +required by this volume of IEEE\ Std\ 1003.1-2001. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP , \fIsh\fP , the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, \fIsignal\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/od.1p b/man1p/od.1p new file mode 100644 index 000000000..dcd16d6b8 --- /dev/null +++ b/man1p/od.1p @@ -0,0 +1,642 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "OD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" od +.SH NAME +od \- dump files in various formats +.SH SYNOPSIS +.LP +\fBod\fP \fB[\fP\fB-v\fP\fB][\fP\fB-A\fP \fIaddress_base\fP\fB][\fP\fB-j\fP +\fIskip\fP\fB][\fP\fB-N\fP +\fIcount\fP\fB][\fP\fB-t\fP \fItype_string\fP\fB]\fP\fB... +.br +\ \ \ \ \ \ \fP \fB[\fP\fIfile\fP\fB...\fP\fB]\fP\fB +.br +.sp +\fP +.LP +\fBod\fP \fB[\fP\fB-bcdosx\fP\fB][\fP\fIfile\fP\fB] +[[\fP\fB+\fP\fB]\fP\fIoffset\fP\fB[\fP\fB.\fP\fB][\fP\fBb\fP\fB]]\fP\fB\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIod\fP utility shall write the contents of its input files to +standard output in a user-specified format. +.SH OPTIONS +.LP +The \fIod\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that the order of presentation of the +\fB-t\fP options \ and the \fB-bcdosx\fP options +is significant. +.LP +The following options shall be supported: +.TP 7 +\fB-A\ \fP \fIaddress_base\fP +.sp +Specify the input offset base. See the EXTENDED DESCRIPTION section. +The application shall ensure that the \fIaddress_base\fP +option-argument is a character. The characters \fB'd'\fP , \fB'o'\fP +, and \fB'x'\fP specify that the offset base shall be +written in decimal, octal, or hexadecimal, respectively. The character +\fB'n'\fP specifies that the offset shall not be +written. +.TP 7 +\fB-b\fP +Interpret bytes in octal. This shall be equivalent to \fB-t\ o1\fP. +.TP 7 +\fB-c\fP +Interpret bytes as characters specified by the current setting of +the \fILC_CTYPE\fP category. Certain non-graphic characters +appear as C escapes: \fB"NUL=\\0"\fP , \fB"BS=\\b"\fP , \fB"FF=\\f"\fP +, \fB"NL=\\n"\fP , \fB"CR=\\r"\fP , +\fB"HT=\\t"\fP ; others appear as 3-digit octal numbers. +.TP 7 +\fB-d\fP +Interpret \fIword\fPs (two-byte units) in unsigned decimal. This shall +be equivalent to \fB-t\ u2\fP. +.TP 7 +\fB-j\ \fP \fIskip\fP +Jump over \fIskip\fP bytes from the beginning of the input. The \fIod\fP +utility shall read or seek past the first +\fIskip\fP bytes in the concatenated input files. If the combined +input is not at least \fIskip\fP bytes long, the \fIod\fP +utility shall write a diagnostic message to standard error and exit +with a non-zero exit status. +.LP +By default, the \fIskip\fP option-argument shall be interpreted as +a decimal number. With a leading 0x or 0X, the offset shall +be interpreted as a hexadecimal number; otherwise, with a leading +\fB'0'\fP , the offset shall be interpreted as an octal +number. Appending the character \fB'b'\fP , \fB'k'\fP , or \fB'm'\fP +to offset shall cause it to be interpreted as a +multiple of 512, 1024, or 1048576 bytes, respectively. If the \fIskip\fP +number is hexadecimal, any appended \fB'b'\fP shall be +considered to be the final hexadecimal digit. +.TP 7 +\fB-N\ \fP \fIcount\fP +Format no more than \fIcount\fP bytes of input. By default, \fIcount\fP +shall be interpreted as a decimal number. With a +leading 0x or 0X, \fIcount\fP shall be interpreted as a hexadecimal +number; otherwise, with a leading \fB'0'\fP , it shall be +interpreted as an octal number. If \fIcount\fP bytes of input (after +successfully skipping, if \fB-j\fP \fIskip\fP is specified) +are not available, it shall not be considered an error; the \fIod\fP +utility shall format the input that is available. +.TP 7 +\fB-o\fP +Interpret \fIword\fPs (two-byte units) in octal. This shall be equivalent +to \fB-t\ o2\fP. +.TP 7 +\fB-s\fP +Interpret \fIword\fPs (two-byte units) in signed decimal. This shall +be equivalent to \fB-t\ d2\fP. +.TP 7 +\fB-t\ \fP \fItype_string\fP +.sp +Specify one or more output types. See the EXTENDED DESCRIPTION section. +The application shall ensure that the \fItype_string\fP +option-argument is a string specifying the types to be used when writing +the input data. The string shall consist of the type +specification characters \fBa\fP , \fBc\fP , \fBd\fP , \fBf\fP , \fBo\fP +, \fBu\fP , and \fBx\fP , specifying +named character, character, signed decimal, floating point, octal, +unsigned decimal, and hexadecimal, respectively. The type +specification characters \fBd\fP , \fBf\fP , \fBo\fP , \fBu\fP , and +\fBx\fP can be followed by an optional unsigned +decimal integer that specifies the number of bytes to be transformed +by each instance of the output type. The type specification +character \fBf\fP can be followed by an optional \fBF\fP , \fBD\fP +, or \fBL\fP indicating that the conversion should +be applied to an item of type \fBfloat\fP, \fBdouble\fP, or \fBlong +double\fP, respectively. The type specification characters +\fBd\fP , \fBo\fP , \fBu\fP , and \fBx\fP can be followed by an optional +\fBC\fP , \fBS\fP , \fBI\fP , or +\fBL\fP indicating that the conversion should be applied to an item +of type \fBchar\fP, \fBshort\fP, \fBint\fP, or +\fBlong\fP, respectively. Multiple types can be concatenated within +the same \fItype_string\fP and multiple \fB-t\fP options can +be specified. Output lines shall be written for each type specified +in the order in which the type specification characters are +specified. +.TP 7 +\fB-v\fP +Write all input data. Without the \fB-v\fP option, any number of groups +of output lines, which would be identical to the +immediately preceding group of output lines (except for the byte offsets), +shall be replaced with a line containing only an +asterisk ( \fB'*'\fP ). +.TP 7 +\fB-x\fP +Interpret \fIword\fPs (two-byte units) in hexadecimal. This shall +be equivalent to \fB-t\ x2\fP. +.sp +.LP +Multiple types can be specified by using multiple \fB-bcdostx\fP options. +Output lines are written for each type specified in the +order in which the types are specified. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile\fP +A pathname of a file to be read. If no \fIfile\fP operands are specified, +the standard input shall be used. +.LP +If there are no more than two operands, none of the \fB-A\fP, \fB-j\fP, +\fB-N\fP, or \fB-t\fP options is specified, and +either of the following is true: the first character of the last operand +is a plus sign ( \fB'+'\fP ), or there are two operands +and the first character of the last operand is numeric; \ the last +operand shall be interpreted as an offset operand on +XSI-conformant systems. Under these conditions, the results are +unspecified on systems that are not XSI-conformant systems. +.TP 7 +\fB[+]\fP\fIoffset\fP\fB[.][b]\fP +The \fIoffset\fP operand specifies the offset in the file where dumping +is to commence. This operand is normally interpreted as +octal bytes. If \fB'.'\fP is appended, the offset shall be interpreted +in decimal. If \fB'b'\fP is appended, the offset shall +be interpreted in units of 512 bytes. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified. See the INPUT FILES section. +.SH INPUT FILES +.LP +The input files can be any file type. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIod\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILC_NUMERIC\fP +.sp +Determine the locale for selecting the radix character used when writing +floating-point formatted output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +See the EXTENDED DESCRIPTION section. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +The \fIod\fP utility shall copy sequentially each input file to standard +output, transforming the input data according to the +output types specified by the \fB-t\fP option \ or the \fB-bcdosx\fP +options. If no output type is specified, the default output shall +be as if \fB-t\ oS\fP had been +specified. +.LP +The number of bytes transformed by the output type specifier \fBc\fP +may be variable depending on the \fILC_CTYPE\fP +category. +.LP +The default number of bytes transformed by output type specifiers +\fBd\fP , \fBf\fP , \fBo\fP , \fBu\fP , and +\fBx\fP corresponds to the various C-language types as follows. If +the \fIc99\fP compiler +is present on the system, these specifiers shall correspond to the +sizes used by default in that compiler. Otherwise, these sizes +may vary among systems that conform to IEEE\ Std\ 1003.1-2001. +.IP " *" 3 +For the type specifier characters \fBd\fP , \fBo\fP , \fBu\fP , and +\fBx\fP , the default number of bytes shall +correspond to the size of the underlying implementation's basic integer +type. For these specifier characters, the implementation +shall support values of the optional number of bytes to be converted +corresponding to the number of bytes in the C-language types +\fBchar\fP, \fBshort\fP, \fBint\fP, and \fBlong\fP. These numbers +can also be specified by an application as the characters +\fB'C'\fP , \fB'S'\fP , \fB'I'\fP , and \fB'L'\fP , respectively. +The implementation shall also support the values 1, +2, 4, and 8, even if it provides no C-Language types of those sizes. +The implementation shall support the decimal value +corresponding to the C-language type \fBlong long\fP. The byte order +used when interpreting numeric values is +implementation-defined, but shall correspond to the order in which +a constant of the corresponding type is stored in memory on the +system. +.LP +.IP " *" 3 +For the type specifier character \fBf\fP , the default number of bytes +shall correspond to the number of bytes in the +underlying implementation's basic double precision floating-point +data type. The implementation shall support values of the +optional number of bytes to be converted corresponding to the number +of bytes in the C-language types \fBfloat,\fP \fBdouble\fP, +and \fBlong double\fP. These numbers can also be specified by an application +as the characters \fB'F'\fP , \fB'D'\fP , and +\fB'L'\fP , respectively. +.LP +.LP +The type specifier character \fBa\fP specifies that bytes shall be +interpreted as named characters from the International +Reference Version (IRV) of the ISO/IEC\ 646:1991 standard. Only the +least significant seven bits of each byte shall be used for +this type specification. Bytes with the values listed in the following +table shall be written using the corresponding names for +those characters. +.br +.sp +.ce 1 +\fBTable: Named Characters in \fIod\fP\fP +.TS C +center; l2 l2 l2 l2 l2 l2 l2 l. +\fBValue\fP \fBName\fP \fBValue\fP \fBName\fP \fBValue\fP \fBName\fP \fBValue\fP \fBName\fP +\\000 \fBnul\fP \\001 \fBsoh\fP \\002 \fBstx\fP \\003 \fBetx\fP +\\004 \fBeot\fP \\005 \fBenq\fP \\006 \fBack\fP \\007 \fBbel\fP +\\010 \fBbs\fP \\011 \fBht\fP \\012 \fBlf or nl\fP \\013 \fBvt\fP +\\014 \fBff\fP \\015 \fBcr\fP \\016 \fBso\fP \\017 \fBsi\fP +\\020 \fBdle\fP \\021 \fBdc1\fP \\022 \fBdc2\fP \\023 \fBdc3\fP +\\024 \fBdc4\fP \\025 \fBnak\fP \\026 \fBsyn\fP \\027 \fBetb\fP +\\030 \fBcan\fP \\031 \fBem\fP \\032 \fBsub\fP \\033 \fBesc\fP +\\034 \fBfs\fP \\035 \fBgs\fP \\036 \fBrs\fP \\037 \fBus\fP +\\040 \fBsp\fP \\177 \fBdel\fP \ \fB\ \fP \ \fB\ \fP +.TE +.TP 7 +\fBNote:\fP +The \fB"\\012"\fP value may be written either as \fBlf\fP or \fBnl\fP. +.sp +.LP +The type specifier character \fBc\fP specifies that bytes shall be +interpreted as characters specified by the current setting +of the \fILC_CTYPE\fP locale category. Characters listed in the table +in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 5, File Format Notation ( \fB'\\\\'\fP +, +\fB'\\a'\fP , \fB'\\b'\fP , \fB'\\f'\fP , \fB'\\n'\fP , \fB'\\r'\fP +, \fB'\\t'\fP , \fB'\\v'\fP ) shall be written as +the corresponding escape sequences, except that backslash shall be +written as a single backslash and a NUL shall be written as +\fB'\\0'\fP . Other non-printable characters shall be written as one +three-digit octal number for each byte in the character. If +the size of a byte on the system is greater than nine bits, the format +used for non-printable characters is implementation-defined. +Printable multi-byte characters shall be written in the area corresponding +to the first byte of the character; the two-character +sequence \fB"**"\fP shall be written in the area corresponding to +each remaining byte in the character, as an indication that +the character is continued. When either the \fB-j\fP \fIskip\fP or +\fB-N\fP \fIcount\fP option is specified along with the +\fBc\fP type specifier, and this results in an attempt to start or +finish in the middle of a multi-byte character, the result is +implementation-defined. +.LP +The input data shall be manipulated in blocks, where a block is defined +as a multiple of the least common multiple of the number +of bytes transformed by the specified output types. If the least common +multiple is greater than 16, the results are unspecified. +Each input block shall be written as transformed by each output type, +one per written line, in the order that the output types were +specified. If the input block size is larger than the number of bytes +transformed by the output type, the output type shall +sequentially transform the parts of the input block, and the output +from each of the transformations shall be separated by one or +more s. +.LP +If, as a result of the specification of the \fB-N\fP option or end-of-file +being reached on the last input file, input data +only partially satisfies an output type, the input shall be extended +sufficiently with null bytes to write the last byte of the +input. +.LP +Unless \fB-A\ n\fP is specified, the first output line produced for +each input block shall be preceded by the input offset, +cumulative across input files, of the next byte to be written. The +format of the input offset is unspecified; however, it shall not +contain any s, shall start at the first character of the output +line, and shall be followed by one or more +s. In addition, the offset of the byte following the last byte +written shall be written after all the input data has +been processed, but shall not be followed by any s. +.LP +If no \fB-A\fP option is specified, the input offset base is unspecified. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All input files were processed successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +XSI-conformant applications are warned not to use filenames starting +with \fB'+'\fP or a first operand starting with a +numeric character so that the old functionality can be maintained +by implementations, unless they specify one of the \fB-A\fP, +\fB-j\fP, or \fB-N\fP options. To guarantee that one of these filenames +is always interpreted as a filename, an application could +always specify the address base format with the \fB-A\fP option. +.SH EXAMPLES +.LP +If a file containing 128 bytes with decimal values zero to 127, in +increasing order, is supplied as standard input to the +command: +.sp +.RS +.nf + +\fBod -A d -t a +\fP +.fi +.RE +.LP +on an implementation using an input block size of 16 bytes, the standard +output, independent of the current locale setting, +would be similar to: +.sp +.RS +.nf + +\fB0000000 nul soh stx etx eot enq ack bel bs ht nl vt ff cr so si +0000016 dle dc1 dc2 dc3 dc4 nak syn etb can em sub esc fs gs rs us +0000032 sp ! " # $ % & ' ( ) * + , - . / +0000048 0 1 2 3 4 5 6 7 8 9 : ; < = > ? +0000064 @ A B C D E F G H I J K L M N O +0000080 P Q R S T U V W X Y Z [ \\ ] ^ _ +0000096 ` a b c d e f g h i j k l m n o +0000112 p q r s t u v w x y z { | } ~ del +0000128 +\fP +.fi +.RE +.LP +Note that this volume of IEEE\ Std\ 1003.1-2001 allows \fBnl\fP or +\fBlf\fP to be used as the name for the +ISO/IEC\ 646:1991 standard IRV character with decimal value 10. The +IRV names this character \fBlf\fP (line feed), but +traditional implementations have referred to this character as newline +( \fBnl\fP) and the POSIX locale character set symbolic +name for the corresponding character is a . +.LP +The command: +.sp +.RS +.nf + +\fBod -A o -t o2x2x -N 18 +\fP +.fi +.RE +.LP +on a system with 32-bit words and an implementation using an input +block size of 16 bytes could write 18 bytes in approximately +the following format: +.sp +.RS +.nf + +\fB0000000 032056 031440 041123 042040 052516 044530 020043 031464 + 342e 3320 4253 4420 554e 4958 2023 3334 + 342e3320 42534420 554e4958 20233334 +0000020 032472 + 353a + 353a0000 +0000022 +\fP +.fi +.RE +.LP +The command: +.sp +.RS +.nf + +\fBod -A d -t f -t o4 -t x4 -N 24 -j 0x15 +\fP +.fi +.RE +.LP +on a system with 64-bit doubles (for example, IEEE\ Std\ 754-1985 +double precision floating-point format) would skip 21 +bytes of input data and then write 24 bytes in approximately the following +format: +.sp +.RS +.nf + +\fB0000000 1.00000000000000e+00 1.57350000000000e+01 + 07774000000 00000000000 10013674121 35341217270 + 3ff00000 00000000 402f3851 eb851eb8 +0000016 1.40668230000000e+02 + 10030312542 04370303230 + 40619562 23e18698 +0000024 +\fP +.fi +.RE +.SH RATIONALE +.LP +The \fIod\fP utility went through several names in early proposals, +including \fIhd\fP, \fIxd\fP, and most recently +\fIhexdump\fP. There were several objections to all of these based +on the following reasons: +.IP " *" 3 +The \fIhd\fP and \fIxd\fP names conflicted with historical utilities +that behaved differently. +.LP +.IP " *" 3 +The \fIhexdump\fP description was much more complex than needed for +a simple dump utility. +.LP +.IP " *" 3 +The \fIod\fP utility has been available on all historical implementations +and there was no need to create a new name for a +utility so similar to the historical \fIod\fP utility. +.LP +.LP +The original reasons for not standardizing historical \fIod\fP were +also fairly widespread. Those reasons are given below along +with rationale explaining why the standard developers believe that +this version does not suffer from the indicated problem: +.IP " *" 3 +The BSD and System V versions of \fIod\fP have diverged, and the intersection +of features provided by both does not meet the +needs of the user community. In fact, the System V version only provides +a mechanism for dumping octal bytes and \fBshort\fPs, +signed and unsigned decimal \fBshort\fPs, hexadecimal \fBshort\fPs, +and ASCII characters. BSD added the ability to dump +\fBfloat\fPs, \fBdouble\fPs, named ASCII characters, and octal, signed +decimal, unsigned decimal, and hexadecimal \fBlong\fPs. +The version presented here provides more normalized forms for dumping +bytes, \fBshort\fPs, \fBint\fPs, and \fBlong\fPs in octal, +signed decimal, unsigned decimal, and hexadecimal; \fBfloat\fP, \fBdouble\fP, +and \fBlong double\fP; and named ASCII as well as +current locale characters. +.LP +.IP " *" 3 +It would not be possible to come up with a compatible superset of +the BSD and System V flags that met the requirements of the +standard developers. The historical default \fIod\fP output is the +specified default output of this utility. None of the option +letters chosen for this version of \fIod\fP conflict with any of the +options to historical versions of \fIod\fP. +.LP +.IP " *" 3 +On systems with different sizes for \fBshort\fP, \fBint\fP, and \fBlong\fP, +there was no way to ask for dumps of \fBint\fPs, +even in the BSD version. Because of the way options are named, the +name space could not be extended to solve these problems. This +is why the \fB-t\fP option was added (with type specifiers more closely +matched to the \fIprintf\fP() formats used in the rest of this volume +of IEEE\ Std\ 1003.1-2001) and the +optional field sizes were added to the \fBd\fP , \fBf\fP , \fBo\fP +, \fBu\fP , and \fBx\fP type specifiers. It is +also one of the reasons why the historical practice was not mandated +as a required obsolescent form of \fIod\fP. (Although the old +versions of \fIod\fP are not listed as an obsolescent form, implementations +are urged to continue to recognize the older forms for +several more years.) The \fBa\fP , \fBc\fP , \fBf\fP , \fBo\fP , and +\fBx\fP types match the meaning of the +corresponding format characters in the historical implementations +of \fIod\fP except for the default sizes of the fields +converted. The \fBd\fP format is signed in this volume of IEEE\ Std\ 1003.1-2001 +to match the \fIprintf\fP() notation. (Historical versions of \fIod\fP +used \fBd\fP as a synonym for +\fBu\fP in this version. The System V implementation uses \fBs\fP +for signed decimal; BSD uses \fBi\fP for signed decimal +and \fBs\fP for null-terminated strings.) Other than \fBd\fP and \fBu\fP +, all of the type specifiers match format +characters in the historical BSD version of \fBod\fP. +.LP +The sizes of the C-language types \fBchar\fP, \fBshort\fP, \fBint\fP, +\fBlong\fP, \fBfloat\fP, \fBdouble\fP, and \fBlong +double\fP are used even though it is recognized that there may be +zero or more than one compiler for the C language on an +implementation and that they may use different sizes for some of these +types. (For example, one compiler might use 2 bytes +\fBshort\fPs, 2 bytes \fBint\fPs, and 4 bytes \fBlong\fPs, while another +compiler (or an option to the same compiler) uses 2 +bytes \fBshort\fPs, 4 bytes \fBint\fPs, and 4 bytes \fBlong\fPs.) +Nonetheless, there has to be a basic size known by the +implementation for these types, corresponding to the values reported +by invocations of the \fIgetconf\fP utility when called with \fIsystem_var\fP +operands {UCHAR_MAX}, {USHORT_MAX}, +{UINT_MAX}, and {ULONG_MAX} for the types \fBchar\fP, \fBshort\fP, +\fBint\fP, and \fBlong\fP, respectively. There are similar +constants required by the ISO\ C standard, but not required by the +System Interfaces volume of IEEE\ Std\ 1003.1-2001 +or this volume of IEEE\ Std\ 1003.1-2001. They are {FLT_MANT_DIG}, +{DBL_MANT_DIG}, and {LDBL_MANT_DIG} for the types +\fBfloat\fP, \fBdouble\fP, and \fBlong double\fP, respectively. If +the optional \fIc99\fP +utility is provided by the implementation and used as specified by +this volume of IEEE\ Std\ 1003.1-2001, these are the +sizes that would be provided. If an option is used that specifies +different sizes for these types, there is no guarantee that the +\fIod\fP utility is able to interpret binary data output by such a +program correctly. +.LP +This volume of IEEE\ Std\ 1003.1-2001 requires that the numeric values +of these lengths be recognized by the \fIod\fP +utility and that symbolic forms also be recognized. Thus, a conforming +application can always look at an array of \fBunsigned +long\fP data elements using \fIod\fP \fB-t\fP \fIuL\fP. +.LP +.IP " *" 3 +The method of specifying the format for the address field based on +specifying a starting offset in a file unnecessarily tied the +two together. The \fB-A\fP option now specifies the address base and +the \fB-S\fP option specifies a starting offset. +.LP +.IP " *" 3 +It would be difficult to break the dependence on U.S. ASCII to achieve +an internationalized utility. It does not seem to be any +harder for \fIod\fP to dump characters in the current locale than +it is for the \fIed\fP or \fIsed\fP \fBl\fP commands. The \fBc\fP +type specifier does this without difficulty and is +completely compatible with the historical implementations of the \fBc\fP +format character when the current locale uses a superset +of the ISO/IEC\ 646:1991 standard as a codeset. The \fBa\fP type specifier +(from the BSD \fBa\fP format character) was left +as a portable means to dump ASCII (or more correctly ISO/IEC\ 646:1991 +standard (IRV)) so that headers produced by \fIpax\fP could be deciphered +even on systems that do not use the ISO/IEC\ 646:1991 standard as +a +subset of their base codeset. +.LP +.LP +The use of \fB"**"\fP as an indication of continuation of a multi-byte +character in \fBc\fP specifier output was chosen +based on seeing an implementation that uses this method. The continuation +bytes have to be marked in a way that is not ambiguous +with another single-byte or multi-byte character. +.LP +An early proposal used \fB-S\fP and \fB-n\fP, respectively, for the +\fB-j\fP and \fB-N\fP options eventually selected. These +were changed to avoid conflicts with historical implementations. +.LP +The original standard specified \fB-t o2\fP as the default when no +output type was given. This was changed to \fB-t oS\fP (the +length of a \fBshort\fP) to accommodate a supercomputer implementation +that historically used 64 bits as its default (and that +defined shorts as 64 bits). This change should not affect conforming +applications. The requirement to support lengths of 1, 2, and +4 was added at the same time to address an historical implementation +that had no two-byte data types in its C compiler. +.LP +The use of a basic integer data type is intended to allow the implementation +to choose a word size commonly used by applications +on that architecture. +.SH FUTURE DIRECTIONS +.LP +All option and operand interfaces marked as extensions may be withdrawn +in a future version. +.SH SEE ALSO +.LP +\fIc99\fP , \fIsed\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/paste.1p b/man1p/paste.1p new file mode 100644 index 000000000..de6c38b39 --- /dev/null +++ b/man1p/paste.1p @@ -0,0 +1,300 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PASTE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" paste +.SH NAME +paste \- merge corresponding or subsequent lines of files +.SH SYNOPSIS +.LP +\fBpaste\fP \fB[\fP\fB-s\fP\fB][\fP\fB-d\fP \fIlist\fP\fB]\fP \fIfile\fP\fB...\fP +.SH DESCRIPTION +.LP +The \fIpaste\fP utility shall concatenate the corresponding lines +of the given input files, and write the resulting lines to +standard output. +.LP +The default operation of \fIpaste\fP shall concatenate the corresponding +lines of the input files. The of every +line except the line from the last input file shall be replaced with +a . +.LP +If an end-of-file condition is detected on one or more input files, +but not all input files, \fIpaste\fP shall behave as though +empty lines were read from the files on which end-of-file was detected, +unless the \fB-s\fP option is specified. +.SH OPTIONS +.LP +The \fIpaste\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-d\ \fP \fIlist\fP +Unless a backslash character appears in \fIlist\fP, each character +in \fIlist\fP is an element specifying a delimiter +character. If a backslash character appears in \fIlist\fP, the backslash +character and one or more characters following it are an +element specifying a delimiter character as described below. These +elements specify one or more delimiters to use, instead of the +default , to replace the of the input lines. The elements +in \fIlist\fP shall be used circularly; that +is, when the list is exhausted the first element from the list is +reused. When the \fB-s\fP option is specified: +.RS +.IP " *" 3 +The last in a file shall not be modified. +.LP +.IP " *" 3 +The delimiter shall be reset to the first element of \fIlist\fP after +each \fIfile\fP operand is processed. +.LP +.RE +.LP +When the \fB-s\fP option is not specified: +.RS +.IP " *" 3 +The s in the file specified by the last \fIfile\fP operand +shall not be modified. +.LP +.IP " *" 3 +The delimiter shall be reset to the first element of list each time +a line is processed from each file. +.LP +.RE +.LP +If a backslash character appears in \fIlist\fP, it and the character +following it shall be used to represent the following +delimiter characters: +.TP 7 +\fB\\n\fP +.RS +. +.RE +.TP 7 +\fB\\t\fP +.RS +. +.RE +.TP 7 +\fB\\\\\fP +.RS +Backslash character. +.RE +.TP 7 +\fB\\0\fP +.RS +Empty string (not a null character). If \fB'\\0'\fP is immediately +followed by the character \fB'x'\fP , the character +\fB'X'\fP , or any character defined by the \fILC_CTYPE\fP \fBdigit\fP +keyword (see the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale), the results are unspecified. +.RE +.sp +.LP +If any other characters follow the backslash, the results are unspecified. +.TP 7 +\fB-s\fP +Concatenate all of the lines of each separate input file in command +line order. The of every line except the +last line in each input file shall be replaced with the , unless +otherwise specified by the \fB-d\fP option. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of an input file. If \fB'-'\fP is specified for one or +more of the \fIfile\fPs, the standard input shall be +used; the standard input shall be read one line at a time, circularly, +for each instance of \fB'-'\fP . Implementations shall +support pasting of at least 12 \fIfile\fP operands. +.sp +.SH STDIN +.LP +The standard input shall be used only if one or more \fIfile\fP operands +is \fB'-'\fP . See the INPUT FILES section. +.SH INPUT FILES +.LP +The input files shall be text files, except that line lengths shall +be unlimited. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIpaste\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Concatenated lines of input files shall be separated by the +(or other characters under the control of the \fB-d\fP +option) and terminated by a . +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If one or more input files cannot be opened when the \fB-s\fP option +is not specified, a diagnostic message shall be written to +standard error, but no output is written to standard output. If the +\fB-s\fP option is specified, the \fIpaste\fP utility shall +provide the default behavior described in \fIUtility Description Defaults\fP +\&. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +When the escape sequences of the \fIlist\fP option-argument are used +in a shell script, they must be quoted; otherwise, the +shell treats the \fB'\\'\fP as a special character. +.LP +Conforming applications should only use the specific backslash escaped +delimiters presented in this volume of +IEEE\ Std\ 1003.1-2001. Historical implementations treat \fB'\\x'\fP +, where \fB'x'\fP is not in this list, as +\fB'x'\fP , but future implementations are free to expand this list +to recognize other common escapes similar to those accepted +by \fIprintf\fP and other standard utilities. +.LP +Most of the standard utilities work on text files. The \fIcut\fP utility +can be used to +turn files with arbitrary line lengths into a set of text files containing +the same data. The \fIpaste\fP utility can be used to +create (or recreate) files with arbitrary line lengths. For example, +if \fIfile\fP contains long lines: +.sp +.RS +.nf + +\fBcut -b 1-500 -n file > file1 +cut -b 501- -n file > file2 +\fP +.fi +.RE +.LP +creates \fBfile1\fP (a text file) with lines no longer than 500 bytes +(plus the ) and \fBfile2\fP that contains +the remainder of the data from \fIfile\fP. Note that \fBfile2\fP is +not a text file if there are lines in \fIfile\fP that are +longer than 500 + {LINE_MAX} bytes. The original file can be recreated +from \fBfile1\fP and \fBfile2\fP using the command: +.sp +.RS +.nf + +\fBpaste -d "\\0" file1 file2 > file +\fP +.fi +.RE +.LP +The commands: +.sp +.RS +.nf + +\fBpaste -d "\\0" ... +paste -d "" ... +\fP +.fi +.RE +.LP +are not necessarily equivalent; the latter is not specified by this +volume of IEEE\ Std\ 1003.1-2001 and may result in +an error. The construct \fB'\\0'\fP is used to mean "no separator" +because historical versions of \fIpaste\fP did not follow +the syntax guidelines, and the command: +.sp +.RS +.nf + +\fBpaste -d"" ... +\fP +.fi +.RE +.LP +could not be handled properly by \fIgetopt\fP(). +.SH EXAMPLES +.IP " 1." 4 +Write out a directory in four columns: +.sp +.RS +.nf + +\fBls | paste - - - - +\fP +.fi +.RE +.LP +.IP " 2." 4 +Combine pairs of lines from a file into single lines: +.sp +.RS +.nf + +\fBpaste -s -d "\\t\\n" file +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIUtility Description Defaults\fP , \fIcut\fP , \fIgrep\fP , \fIpr\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/patch.1p b/man1p/patch.1p new file mode 100644 index 000000000..7bd5bc260 --- /dev/null +++ b/man1p/patch.1p @@ -0,0 +1,509 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PATCH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" patch +.SH NAME +patch \- apply changes to files +.SH SYNOPSIS +.LP +\fBpatch\fP \fB[\fP\fB-blNR\fP\fB][\fP \fB-c| -e| -n\fP\fB][\fP\fB-d\fP +\fIdir\fP\fB][\fP\fB-D\fP \fIdefine\fP\fB][\fP\fB-i\fP \fIpatchfile\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-o\fP \fIoutfile\fP\fB][\fP\fB-p\fP +\fInum\fP\fB][\fP\fB-r\fP \fIrejectfile\fP\fB][\fP\fIfile\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIpatch\fP utility shall read a source (patch) file containing +any of the three forms of difference (diff) listings +produced by the \fIdiff\fP utility (normal, context, or in the style +of \fIed\fP) and apply those differences to a file. By default, \fIpatch\fP +shall read from the standard +input. +.LP +The \fIpatch\fP utility shall attempt to determine the type of the +\fIdiff\fP listing, +unless overruled by a \fB-c\fP, \fB-e\fP, or \fB-n\fP option. +.LP +If the patch file contains more than one patch, \fIpatch\fP shall +attempt to apply each of them as if they came from separate +patch files. (In this case, the application shall ensure that the +name of the patch file is determinable for each \fIdiff\fP listing.) +.SH OPTIONS +.LP +The \fIpatch\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-b\fP +Save a copy of the original contents of each modified file, before +the differences are applied, in a file of the same name with +the suffix \fB.orig\fP appended to it. If the file already exists, +it shall be overwritten; if multiple patches are applied to the +same file, the \fB.orig\fP file shall be written only for the first +patch. When the \fB-o\fP \fIoutfile\fP option is also +specified, \fIfile\fP \fB.orig\fP shall not be created but, if \fIoutfile\fP +already exists, \fIoutfile\fP \fB.orig\fP shall +be created. +.TP 7 +\fB-c\fP +Interpret the patch file as a context difference (the output of the +utility \fIdiff\fP +when the \fB-c\fP or \fB-C\fP options are specified). +.TP 7 +\fB-d\ \fP \fIdir\fP +Change the current directory to \fIdir\fP before processing as described +in the EXTENDED DESCRIPTION section. +.TP 7 +\fB-D\ \fP \fIdefine\fP +Mark changes with one of the following C preprocessor constructs: +.sp +.RS +.nf + +\fB#ifdef define +\&... +#endif +.sp + +#ifndef define +\&... +#endif +\fP +.fi +.RE +.LP +optionally combined with the C preprocessor construct \fB#else\fP. +If the patched file is processed with the C preprocessor, +where the macro \fIdefine\fP is defined, the output shall contain +the changes from the patch file; otherwise, the output shall not +contain the patches specified in the patch file. +.TP 7 +\fB-e\fP +Interpret the patch file as an \fIed\fP script, rather than a \fIdiff\fP +script. +.TP 7 +\fB-i\ \fP \fIpatchfile\fP +Read the patch information from the file named by the pathname \fIpatchfile\fP, +rather than the standard input. +.TP 7 +\fB-l\fP +(The letter ell.) Cause any sequence of s in the difference +script to match any sequence of s in the +input file. Other characters shall be matched exactly. +.TP 7 +\fB-n\fP +Interpret the script as a normal difference. +.TP 7 +\fB-N\fP +Ignore patches where the differences have already been applied to +the file; by default, already-applied patches shall be +rejected. +.TP 7 +\fB-o\ \fP \fIoutfile\fP +Instead of modifying the files (specified by the \fIfile\fP operand +or the difference listings) directly, write a copy of the +file referenced by each patch, with the appropriate differences applied, +to \fIoutfile\fP. Multiple patches for a single file +shall be applied to the intermediate versions of the file created +by any previous patches, and shall result in multiple, +concatenated versions of the file being written to \fIoutfile\fP. +.TP 7 +\fB-p\ \fP \fInum\fP +For all pathnames in the patch file that indicate the names of files +to be patched, delete \fInum\fP pathname components from +the beginning of each pathname. If the pathname in the patch file +is absolute, any leading slashes shall be considered the first +component (that is, \fB-p\ 1\fP shall remove the leading slashes). +Specifying \fB-p\ 0\fP shall cause the full pathname +to be used. If \fB-p\fP is not specified, only the basename (the final +pathname component) shall be used. +.TP 7 +\fB-R\fP +Reverse the sense of the patch script; that is, assume that the difference +script was created from the new version to the old +version. The \fB-R\fP option cannot be used with \fIed\fP scripts. +The \fIpatch\fP utility +shall attempt to reverse each portion of the script before applying +it. Rejected differences shall be saved in swapped format. If +this option is not specified, and until a portion of the patch file +is successfully applied, \fIpatch\fP attempts to apply each +portion in its reversed sense as well as in its normal sense. If the +attempt is successful, the user shall be prompted to determine +whether the \fB-R\fP option should be set. +.TP 7 +\fB-r\ \fP \fIrejectfile\fP +Override the default reject filename. In the default case, the reject +file shall have the same name as the output file, with +the suffix \fB.rej\fP appended to it; see Patch Application . +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a file to patch. +.sp +.SH STDIN +.LP +See the INPUT FILES section. +.SH INPUT FILES +.LP +Input files shall be text files. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIpatch\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fILC_TIME\fP +Determine the locale for recognizing the format of file timestamps +written by the \fIdiff\fP utility in a context-difference input file. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used for diagnostic and informational +messages. +.SH OUTPUT FILES +.LP +The output of the \fIpatch\fP utility, the save files ( \fB.orig\fP +suffixes), and the reject files ( \fB.rej\fP suffixes) +shall be text files. +.SH EXTENDED DESCRIPTION +.LP +A patch file may contain patching instructions for more than one file; +filenames shall be determined as specified in Filename Determination +\&. When the \fB-b\fP option is specified, for each patched file, the +original shall +be saved in a file of the same name with the suffix \fB.orig\fP appended +to it. +.LP +For each patched file, a reject file may also be created as noted +in Patch Application . In the +absence of a \fB-r\fP option, the name of this file shall be formed +by appending the suffix \fB.rej\fP to the original +filename. +.SS Patch File Format +.LP +The patch file shall contain zero or more lines of header information +followed by one or more patches. Each patch shall contain +zero or more lines of filename identification in the format produced +by \fIdiff\fP \fB-c\fP, +and one or more sets of \fIdiff\fP output, which are customarily called +\fIhunks\fP. +.LP +The \fIpatch\fP utility shall recognize the following expression in +the header information: +.TP 7 +\fBIndex:\ \fP \fIpathname\fP +.sp +The file to be patched is named \fIpathname\fP. +.sp +.LP +If all lines (including headers) within a patch begin with the same +leading sequence of s, the \fIpatch\fP utility +shall remove this sequence before proceeding. Within each patch, if +the type of difference is context, the \fIpatch\fP utility +shall recognize the following expressions: +.TP 7 +***\ \fIfilename\ timestamp\fP +.sp +The patches arose from \fIfilename\fP. +.TP 7 +---\ \fIfilename\ timestamp\fP +.sp +The patches should be applied to \fIfilename\fP. +.sp +.LP +Each hunk within a patch shall be the \fIdiff\fP output to change +a line range within the +original file. The line numbers for successive hunks within a patch +shall occur in ascending order. +.SS Filename Determination +.LP +If no \fIfile\fP operand is specified, \fIpatch\fP shall perform the +following steps to determine the filename to use: +.IP " 1." 4 +If the type of \fIdiff\fP is context, the \fIpatch\fP utility shall +delete pathname +components (as specified by the \fB-p\fP option) from the filename +on the line beginning with \fB"***"\fP , then test for the +existence of this file relative to the current directory (or the directory +specified with the \fB-d\fP option). If the file +exists, the \fIpatch\fP utility shall use this filename. +.LP +.IP " 2." 4 +If the type of \fIdiff\fP is context, the \fIpatch\fP utility shall +delete the pathname +components (as specified by the \fB-p\fP option) from the filename +on the line beginning with \fB"---"\fP , then test for the +existence of this file relative to the current directory (or the directory +specified with the \fB-d\fP option). If the file +exists, the \fIpatch\fP utility shall use this filename. +.LP +.IP " 3." 4 +If the header information contains a line beginning with the string +\fBIndex:\fP, the \fIpatch\fP utility shall delete +pathname components (as specified by the \fB-p\fP option) from this +line, then test for the existence of this file relative to the +current directory (or the directory specified with the \fB-d\fP option). +If the file exists, the \fIpatch\fP utility shall use +this filename. +.LP +.IP " 4." 4 +If an \fBSCCS\fP directory exists in the current directory, \fIpatch\fP +shall attempt to perform a \fIget\fP \fB-e\fP \fBSCCS/s.\fP \fIfilename\fP +command to retrieve an editable version of the +file. If the file exists, the \fIpatch\fP utility shall use this filename. +.LP +.IP " 5." 4 +The \fIpatch\fP utility shall write a prompt to standard output and +request a filename interactively from the controlling +terminal (for example, \fB/dev/tty\fP). +.LP +.SS Patch Application +.LP +If the \fB-c\fP, \fB-e\fP, or \fB-n\fP option is present, the \fIpatch\fP +utility shall interpret information within each +hunk as a context difference, an \fIed\fP difference, or a normal +difference, respectively. In +the absence of any of these options, the \fIpatch\fP utility shall +determine the type of difference based on the format of +information within the hunk. +.LP +For each hunk, the \fIpatch\fP utility shall begin to search for the +place to apply the patch at the line number at the +beginning of the hunk, plus or minus any offset used in applying the +previous hunk. If lines matching the hunk context are not +found, \fIpatch\fP shall scan both forwards and backwards at least +1000 bytes for a set of lines that match the hunk context. +.LP +If no such place is found and it is a context difference, then another +scan shall take place, ignoring the first and last line +of context. If that fails, the first two and last two lines of context +shall be ignored and another scan shall be made. +Implementations may search more extensively for installation locations. +.LP +If no location can be found, the \fIpatch\fP utility shall append +the hunk to the reject file. The rejected hunk shall be +written in context-difference format regardless of the format of the +patch file. If the input was a normal or \fIed\fP-style difference, +the reject file may contain differences with zero lines of context. +The line +numbers on the hunks in the reject file may be different from the +line numbers in the patch file since they shall reflect the +approximate locations for the failed hunks in the new file rather +than the old one. +.LP +If the type of patch is an \fIed\fP diff, the implementation may accomplish +the patching by +invoking the \fIed\fP utility. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +\ 1 +One or more lines were written to a reject file. +.TP 7 +>1 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Patches that cannot be correctly placed in the file shall be written +to a reject file. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fB-R\fP option does not work with \fIed\fP scripts because there +is too little +information to reconstruct the reverse operation. +.LP +The \fB-p\fP option makes it possible to customize a patch file to +local user directory structures without manually editing the +patch file. For example, if the filename in the patch file was: +.sp +.RS +.nf + +\fB/curds/whey/src/blurfl/blurfl.c +\fP +.fi +.RE +.LP +Setting \fB-p\ 0\fP gives the entire pathname unmodified; \fB-p\ 1\fP +gives: +.sp +.RS +.nf + +\fBcurds/whey/src/blurfl/blurfl.c +\fP +.fi +.RE +.LP +without the leading slash, \fB-p\ 4\fP gives: +.sp +.RS +.nf + +\fBblurfl/blurfl.c +\fP +.fi +.RE +.LP +and not specifying \fB-p\fP at all gives: +.sp +.RS +.nf + +\fBblurfl.c . +\fP +.fi +.RE +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +Some of the functionality in historical \fIpatch\fP implementations +was not specified. The following documents those features +present in historical implementations that have not been specified. +.LP +A deleted piece of functionality was the \fB'+'\fP pseudo-option allowing +an additional set of options and a patch file +operand to be given. This was seen as being insufficiently useful +to standardize. +.LP +In historical implementations, if the string \fB"Prereq:"\fP appeared +in the header, the \fIpatch\fP utility would search +for the corresponding version information (the string specified in +the header, delimited by s or the beginning or end +of a line or the file) anywhere in the original file. This was deleted +as too simplistic and insufficiently trustworthy a mechanism +to standardize. For example, if: +.sp +.RS +.nf + +\fBPrereq: 1.2 +\fP +.fi +.RE +.LP +were in the header, the presence of a delimited 1.2 anywhere in the +file would satisfy the prerequisite. +.LP +The following options were dropped from historical implementations +of \fIpatch\fP as insufficiently useful to standardize: +.TP 7 +\fB-b\fP +The \fB-b\fP option historically provided a method for changing the +name extension of the backup file from the default +\fB\&.orig\fP. This option has been modified and retained in this volume +of IEEE\ Std\ 1003.1-2001. +.TP 7 +\fB-F\fP +The \fB-F\fP option specified the number of lines of a context diff +to ignore when searching for a place to install a +patch. +.TP 7 +\fB-f\fP +The \fB-f\fP option historically caused \fIpatch\fP not to request +additional information from the user. +.TP 7 +\fB-r\fP +The \fB-r\fP option historically provided a method of overriding the +extension of the reject file from the default +\fB\&.rej\fP. +.TP 7 +\fB-s\fP +The \fB-s\fP option historically caused \fIpatch\fP to work silently +unless an error occurred. +.TP 7 +\fB-x\fP +The \fB-x\fP option historically set internal debugging flags. +.sp +.LP +In some file system implementations, the saving of a \fB.orig\fP file +may produce unwanted results. In the case of 12, 13, or +14-character filenames (on file systems supporting 14-character maximum +filenames), the \fB.orig\fP file overwrites the new file. +The reject file may also exceed this filename limit. It was suggested, +due to some historical practice, that a tilde ( +\fB'~'\fP ) suffix be used instead of \fB.orig\fP and some other character +instead of the \fB.rej\fP suffix. This was +rejected because it is not obvious to the user which file is which. +The suffixes \fB.orig\fP and \fB.rej\fP are clearer and more +understandable. +.LP +The \fB-b\fP option has the opposite sense in some historical implementations-do +not save the \fB.orig\fP file. The default +case here is not to save the files, making \fIpatch\fP behave more +consistently with the other standard utilities. +.LP +The \fB-w\fP option in early proposals was changed to \fB-l\fP to +match historical practice. +.LP +The \fB-N\fP option was included because without it, a non-interactive +application cannot reject previously applied patches. +For example, if a user is piping the output of \fIdiff\fP into the +\fIpatch\fP utility, and +the user only wants to patch a file to a newer version non-interactively, +the \fB-N\fP option is required. +.LP +Changes to the \fB-l\fP option description were proposed to allow +matching across s in addition to just +s. Since this is not historical practice, and since some ambiguities +could result, it is suggested that future +developments in this area utilize another option letter, such as \fB-L\fP. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIed\fP , \fIdiff\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/pathchk.1p b/man1p/pathchk.1p new file mode 100644 index 000000000..394f47d1e --- /dev/null +++ b/man1p/pathchk.1p @@ -0,0 +1,358 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PATHCHK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pathchk +.SH NAME +pathchk \- check pathnames +.SH SYNOPSIS +.LP +\fBpathchk\fP \fB[\fP\fB-p\fP\fB]\fP \fIpathname\fP\fB...\fP +.SH DESCRIPTION +.LP +The \fIpathchk\fP utility shall check that one or more pathnames are +valid (that is, they could be used to access or create a +file without causing syntax errors) and portable (that is, no filename +truncation results). More extensive portability checks are +provided by the \fB-p\fP option. +.LP +By default, the \fIpathchk\fP utility shall check each component of +each \fIpathname\fP operand based on the underlying file +system. A diagnostic shall be written for each \fIpathname\fP operand +that: +.IP " *" 3 +Is longer than {PATH_MAX} bytes (see \fBPathname Variable Values\fP +in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 13, Headers, \fI\fP) +.LP +.IP " *" 3 +Contains any component longer than {NAME_MAX} bytes in its containing +directory +.LP +.IP " *" 3 +Contains any component in a directory that is not searchable +.LP +.IP " *" 3 +Contains any character in any component that is not valid in its containing +directory +.LP +.LP +The format of the diagnostic message is not specified, but shall indicate +the error detected and the corresponding +\fIpathname\fP operand. +.LP +It shall not be considered an error if one or more components of a +\fIpathname\fP operand do not exist as long as a file +matching the pathname specified by the missing components could be +created that does not violate any of the checks specified +above. +.SH OPTIONS +.LP +The \fIpathchk\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-p\fP +Instead of performing checks based on the underlying file system, +write a diagnostic for each \fIpathname\fP operand that: +.RS +.IP " *" 3 +Is longer than {_POSIX_PATH_MAX} bytes (see \fBMinimum Values\fP in +the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 13, Headers, \fI\fP) +.LP +.IP " *" 3 +Contains any component longer than {_POSIX_NAME_MAX} bytes +.LP +.IP " *" 3 +Contains any character in any component that is not in the portable +filename character set +.LP +.RE +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIpathname\fP +A pathname to be checked. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIpathchk\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All \fIpathname\fP operands passed all of the checks. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fItest\fP utility can be used to determine whether a given pathname +names an existing +file; it does not, however, give any indication of whether or not +any component of the pathname was truncated in a directory where +the _POSIX_NO_TRUNC feature is not in effect. The \fIpathchk\fP utility +does not check for file existence; it performs checks to +determine whether a pathname does exist or could be created with no +pathname component truncation. +.LP +The \fInoclobber\fP option in the shell (see the \fIset\fP special +built-in) can be used to +atomically create a file. As with all file creation semantics in the +System Interfaces volume of IEEE\ Std\ 1003.1-2001, it +guarantees atomic creation, but still depends on applications to agree +on conventions and cooperate on the use of files after they +have been created. +.SH EXAMPLES +.LP +To verify that all pathnames in an imported data interchange archive +are legitimate and unambiguous on the current system: +.sp +.RS +.nf + +\fBpax -f archive | sed -e '/ == .*/s///' | xargs pathchk +if [ $? -eq 0 ] +then + pax -r -f archive +else + echo Investigate problems before importing files. + exit 1 +fi +\fP +.fi +.RE +.LP +To verify that all files in the current directory hierarchy could +be moved to any system conforming to the System Interfaces +volume of IEEE\ Std\ 1003.1-2001 that also supports the \fIpax\fP +utility: +.sp +.RS +.nf + +\fBfind . -print | xargs pathchk -p +if [ $? -eq 0 ] +then + pax -w -f archive . +else + echo Portable archive cannot be created. + exit 1 +fi +\fP +.fi +.RE +.LP +To verify that a user-supplied pathname names a readable file and +that the application can create a file extending the given +path without truncation and without overwriting any existing file: +.sp +.RS +.nf + +\fBcase $- in + *C*) reset="";; + *) reset="set +C" + set -C;; +esac +test -r "$path" && pathchk "$path.out" && + rm "$path.out" > "$path.out" +if [ $? -ne 0 ]; then + printf "%s: %s not found or %s.out fails \\ +creation checks.\\n" $0 "$path" "$path" + $reset # Reset the noclobber option in case a trap + # on EXIT depends on it. + exit 1 +fi +$reset +PROCESSING < "$path" > "$path.out" +\fP +.fi +.RE +.LP +The following assumptions are made in this example: +.IP " 1." 4 +\fBPROCESSING\fP represents the code that is used by the application +to use \fB$path\fP once it is verified that +\fB$path.out\fP works as intended. +.LP +.IP " 2." 4 +The state of the \fInoclobber\fP option is unknown when this code +is invoked and should be set on exit to the state it was in +when this code was invoked. (The \fBreset\fP variable is used in this +example to restore the initial state.) +.LP +.IP " 3." 4 +Note the usage of: +.sp +.RS +.nf + +\fBrm "$path.out" > "$path.out" +\fP +.fi +.RE +.RS +.IP " a." 4 +The \fIpathchk\fP command has already verified, at this point, that +\fB$path.out\fP is not truncated. +.LP +.IP " b." 4 +With the \fInoclobber\fP option set, the shell verifies that \fB$path.out\fP +does not already exist before invoking \fIrm\fP. +.LP +.IP " c." 4 +If the shell succeeded in creating \fB$path.out\fP, \fIrm\fP removes +it so that the +application can create the file again in the \fBPROCESSING\fP step. +.LP +.IP " d." 4 +If the \fBPROCESSING\fP step wants the file to exist already when +it is invoked, the: +.sp +.RS +.nf + +\fBrm "$path.out" > "$path.out" +\fP +.fi +.RE +.LP +should be replaced with: +.sp +.RS +.nf + +\fB> "$path.out" +\fP +.fi +.RE +.LP +which verifies that the file did not already exist, but leaves \fB$path.out\fP +in place for use by \fBPROCESSING\fP. +.LP +.RE +.LP +.SH RATIONALE +.LP +The \fIpathchk\fP utility was new for the ISO\ POSIX-2:1993 standard. +It, along with the \fIset\fP \fB-C\fP( \fInoclobber\fP) option added +to the shell, replaces the +\fImktemp\fP, \fIvalidfnam\fP, and \fIcreate\fP utilities that appeared +in early proposals. All of these utilities were attempts +to solve several common problems: +.IP " *" 3 +Verify the validity (for several different definitions of "valid") +of a pathname supplied by a user, generated by an +application, or imported from an external source. +.LP +.IP " *" 3 +Atomically create a file. +.LP +.IP " *" 3 +Perform various string handling functions to generate a temporary +filename. +.LP +.LP +The \fIcreate\fP utility, included in an early proposal, provided +checking and atomic creation in a single invocation of the +utility; these are orthogonal issues and need not be grouped into +a single utility. Note that the \fInoclobber\fP option also +provides a way of creating a lock for process synchronization; since +it provides an atomic \fIcreate\fP, there is no race between +a test for existence and the following creation if it did not exist. +.LP +Having a function like \fItmpnam\fP() in the ISO\ C standard is important +in many +high-level languages. The shell programming language, however, has +built-in string manipulation facilities, making it very easy to +construct temporary filenames. The names needed obviously depend on +the application, but are frequently of a form similar to: +.sp +.RS +.nf + +\fB$TMPDIR/\fP\fIapplication_abbreviation\fP\fB$$.\fP\fIsuffix\fP +.fi +.RE +.LP +In cases where there is likely to be contention for a given suffix, +a simple shell \fBfor\fP or \fBwhile\fP loop can be used +with the shell \fInoclobber\fP option to create a file without risk +of collisions, as long as applications trying to use the same +filename name space are cooperating on the use of files after they +have been created. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIRedirection\fP , \fIset\fP , \fItest\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/pax.1p b/man1p/pax.1p new file mode 100644 index 000000000..8db9e2388 --- /dev/null +++ b/man1p/pax.1p @@ -0,0 +1,2952 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PAX" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pax +.SH NAME +pax \- portable archive interchange +.SH SYNOPSIS +.LP +\fBpax\fP \fB[\fP\fB-cdnv\fP\fB][\fP\fB-H|-L\fP\fB][\fP\fB-f\fP \fIarchive\fP\fB][\fP\fB-s\fP +\fIreplstr\fP\fB]\fP\fB...\fP\fB[\fP\fIpattern\fP\fB...\fP\fB]\fP\fB +.br +.sp +pax -r\fP\fB[\fP\fB-cdiknuv\fP\fB][\fP\fB-H|-L\fP\fB][\fP\fB-f\fP +\fIarchive\fP\fB][\fP\fB-o\fP +\fIoptions\fP\fB]\fP\fB...\fP\fB[\fP\fB-p\fP \fIstring\fP\fB]\fP\fB... +.br +\ \ \ \ \ \ \fP \fB[\fP\fB-s\fP +\fIreplstr\fP\fB]\fP\fB...\fP\fB[\fP\fIpattern\fP\fB...\fP\fB]\fP\fB +.br +.sp +pax -w\fP\fB[\fP\fB-dituvX\fP\fB][\fP\fB-H|-L\fP\fB][\fP\fB-b\fP +\fIblocksize\fP\fB][[\fP\fB-a\fP\fB][\fP\fB-f\fP \fIarchive\fP\fB][\fP\fB-o\fP +\fIoptions\fP\fB]\fP\fB... +.br +\ \ \ \ \ \ \fP \fB[\fP\fB-s\fP \fIreplstr\fP\fB]\fP\fB...\fP\fB[\fP\fB-x\fP +\fIformat\fP\fB][\fP\fIfile\fP\fB...\fP\fB]\fP\fB +.br +.sp +pax -r -w\fP\fB[\fP\fB-diklntuvX\fP\fB][\fP\fB-H|-L\fP\fB][\fP\fB-p\fP +\fIstring\fP\fB]\fP\fB...\fP\fB[\fP\fB-s\fP \fIreplstr\fP\fB]\fP\fB... +.br +\ \ \ \ \ \ \fP \fB[\fP\fIfile\fP\fB...\fP\fB]\fP \fIdirectory\fP\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpax\fP utility shall read, write, and write lists of the members +of archive files and copy directory hierarchies. A +variety of archive formats shall be supported; see the \fB-x\fP \fIformat\fP +option. +.LP +The action to be taken depends on the presence of the \fB-r\fP and +\fB-w\fP options. The four combinations of \fB-r\fP and +\fB-w\fP are referred to as the four modes of operation: \fBlist\fP, +\fBread\fP, \fBwrite\fP, and \fBcopy\fP modes, +corresponding respectively to the four forms shown in the SYNOPSIS +section. +.TP 7 +\fBlist\fP +In \fBlist\fP mode (when neither \fB-r\fP nor \fB-w\fP are specified), +\fIpax\fP shall write the names of the members of +the archive file read from the standard input, with pathnames matching +the specified patterns, to standard output. If a named file +is of type directory, the file hierarchy rooted at that file shall +be listed as well. +.TP 7 +\fBread\fP +In \fBread\fP mode (when \fB-r\fP is specified, but \fB-w\fP is not), +\fIpax\fP shall extract the members of the archive +file read from the standard input, with pathnames matching the specified +patterns. If an extracted file is of type directory, the +file hierarchy rooted at that file shall be extracted as well. The +extracted files shall be created performing pathname resolution +with the directory in which \fIpax\fP was invoked as the current working +directory. +.LP +If an attempt is made to extract a directory when the directory already +exists, this shall not be considered an error. If an +attempt is made to extract a FIFO when the FIFO already exists, this +shall not be considered an error. +.LP +The ownership, access, and modification times, and file mode of the +restored files are discussed under the \fB-p\fP option. +.TP 7 +\fBwrite\fP +In \fBwrite\fP mode (when \fB-w\fP is specified, but \fB-r\fP is not), +\fIpax\fP shall write the contents of the +\fIfile\fP operands to the standard output in an archive format. If +no \fIfile\fP operands are specified, a list of files to +copy, one per line, shall be read from the standard input. A file +of type directory shall include all of the files in the file +hierarchy rooted at the file. +.TP 7 +\fBcopy\fP +In \fBcopy\fP mode (when both \fB-r\fP and \fB-w\fP are specified), +\fIpax\fP shall copy the \fIfile\fP operands to the +destination directory. +.LP +If no \fIfile\fP operands are specified, a list of files to copy, +one per line, shall be read from the standard input. A file +of type directory shall include all of the files in the file hierarchy +rooted at the file. +.LP +The effect of the \fBcopy\fP shall be as if the copied files were +written to an archive file and then subsequently extracted, +except that there may be hard links between the original and the copied +files. If the destination directory is a subdirectory of +one of the files to be copied, the results are unspecified. If the +destination directory is a file of a type not defined by the +System Interfaces volume of IEEE\ Std\ 1003.1-2001, the results are +implementation-defined; otherwise, it shall be an error +for the file named by the \fIdirectory\fP operand not to exist, not +be writable by the user, or not be a file of type +directory. +.sp +.LP +In \fBread\fP or \fBcopy\fP modes, if intermediate directories are +necessary to extract an archive member, \fIpax\fP shall +perform actions equivalent to the \fImkdir\fP() function defined in +the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, called with the following arguments: +.IP " *" 3 +The intermediate directory used as the \fIpath\fP argument +.LP +.IP " *" 3 +The value of the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO +as the \fImode\fP argument +.LP +.LP +If any specified \fIpattern\fP or \fIfile\fP operands are not matched +by at least one file or archive member, \fIpax\fP shall +write a diagnostic message to standard error for each one that did +not match and exit with a non-zero exit status. +.LP +The archive formats described in the EXTENDED DESCRIPTION section +shall be automatically detected on input. The default output +archive format shall be implementation-defined. +.LP +A single archive can span multiple files. The \fIpax\fP utility shall +determine, in an implementation-defined manner, what file +to read or write as the next file. +.LP +If the selected archive format supports the specification of linked +files, it shall be an error if these files cannot be linked +when the archive is extracted. For archive formats that do not store +file contents with each name that causes a hard link, if the +file that contains the data is not extracted during this \fIpax\fP +session, either the data shall be restored from the original +file, or a diagnostic message shall be displayed with the name of +a file that can be used to extract the data. In traversing +directories, \fIpax\fP shall detect infinite loops; that is, entering +a previously visited directory that is an ancestor of the +last file visited. When it detects an infinite loop, \fIpax\fP shall +write a diagnostic message to standard error and shall +terminate. +.SH OPTIONS +.LP +The \fIpax\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that the order of presentation of the +\fB-o\fP, \fB-p\fP, and \fB-s\fP options is significant. +.LP +The following options shall be supported: +.TP 7 +\fB-r\fP +Read an archive file from standard input. +.TP 7 +\fB-w\fP +Write files to the standard output in the specified archive format. +.TP 7 +\fB-a\fP +Append files to the end of the archive. It is implementation-defined +which devices on the system support appending. Additional +file formats unspecified by this volume of IEEE\ Std\ 1003.1-2001 +may impose restrictions on appending. +.TP 7 +\fB-b\ \fP \fIblocksize\fP +Block the output at a positive decimal integer number of bytes per +write to the archive file. Devices and archive formats may +impose restrictions on blocking. Blocking shall be automatically determined +on input. Conforming applications shall not specify a +\fIblocksize\fP value larger than 32256. Default blocking when creating +archives depends on the archive format. (See the \fB-x\fP +option below.) +.TP 7 +\fB-c\fP +Match all file or archive members except those specified by the \fIpattern\fP +or \fIfile\fP operands. +.TP 7 +\fB-d\fP +Cause files of type directory being copied or archived or archive +members of type directory being extracted or listed to match +only the file or archive member itself and not the file hierarchy +rooted at the file. +.TP 7 +\fB-f\ \fP \fIarchive\fP +Specify the pathname of the input or output archive, overriding the +default standard input (in \fBlist\fP or \fBread\fP +modes) or standard output ( \fBwrite\fP mode). +.TP 7 +\fB-H\fP +If a symbolic link referencing a file of type directory is specified +on the command line, \fIpax\fP shall archive the file +hierarchy rooted in the file referenced by the link, using the name +of the link as the root of the file hierarchy. Otherwise, if a +symbolic link referencing a file of any other file type which \fIpax\fP +can normally archive is specified on the command line, +then \fIpax\fP shall archive the file referenced by the link, using +the name of the link. The default behavior shall be to archive +the symbolic link itself. +.TP 7 +\fB-i\fP +Interactively rename files or archive members. For each archive member +matching a \fIpattern\fP operand or file matching a +\fIfile\fP operand, a prompt shall be written to the file \fB/dev/tty\fP. +The prompt shall contain the name of the file or +archive member, but the format is otherwise unspecified. A line shall +then be read from \fB/dev/tty\fP. If this line is blank, the +file or archive member shall be skipped. If this line consists of +a single period, the file or archive member shall be processed +with no modification to its name. Otherwise, its name shall be replaced +with the contents of the line. The \fIpax\fP utility shall +immediately exit with a non-zero exit status if end-of-file is encountered +when reading a response or if \fB/dev/tty\fP cannot be +opened for reading and writing. +.LP +The results of extracting a hard link to a file that has been renamed +during extraction are unspecified. +.TP 7 +\fB-k\fP +Prevent the overwriting of existing files. +.TP 7 +\fB-l\fP +(The letter ell.) In \fBcopy\fP mode, hard links shall be made between +the source and destination file hierarchies whenever +possible. If specified in conjunction with \fB-H\fP or \fB-L\fP, when +a symbolic link is encountered, the hard link created in +the destination file hierarchy shall be to the file referenced by +the symbolic link. If specified when neither \fB-H\fP nor +\fB-L\fP is specified, when a symbolic link is encountered, the implementation +shall create a hard link to the symbolic link in +the source file hierarchy or copy the symbolic link to the destination. +.TP 7 +\fB-L\fP +If a symbolic link referencing a file of type directory is specified +on the command line or encountered during the traversal of +a file hierarchy, \fIpax\fP shall archive the file hierarchy rooted +in the file referenced by the link, using the name of the link +as the root of the file hierarchy. Otherwise, if a symbolic link referencing +a file of any other file type which \fIpax\fP can +normally archive is specified on the command line or encountered during +the traversal of a file hierarchy, \fIpax\fP shall archive +the file referenced by the link, using the name of the link. The default +behavior shall be to archive the symbolic link +itself. +.TP 7 +\fB-n\fP +Select the first archive member that matches each \fIpattern\fP operand. +No more than one archive member shall be matched for +each pattern (although members of type directory shall still match +the file hierarchy rooted at that file). +.TP 7 +\fB-o\ \fP \fIoptions\fP +Provide information to the implementation to modify the algorithm +for extracting or writing files. The value of \fIoptions\fP +shall consist of one or more comma-separated keywords of the form: +.sp +.RS +.nf + +\fIkeyword\fP\fB[[\fP\fB:\fP\fB]\fP\fB=\fP\fIvalue\fP\fB][\fP\fB,\fP\fIkeyword\fP\fB[[\fP\fB:\fP\fB]\fP\fB=\fP\fIvalue\fP\fB]\fP\fB, ...\fP\fB]\fP +.fi +.RE +.LP +Some keywords apply only to certain file formats, as indicated with +each description. Use of keywords that are inapplicable to +the file format being processed produces undefined results. +.LP +Keywords in the \fIoptions\fP argument shall be a string that would +be a valid portable filename as described in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 3.276, Portable +Filename Character Set. +.TP 7 +\fBNote:\fP +.RS +Keywords are not expected to be filenames, merely to follow the same +character composition rules as portable filenames. +.RE +.sp +.LP +Keywords can be preceded with white space. The \fIvalue\fP field shall +consist of zero or more characters; within \fIvalue\fP, +the application shall precede any literal comma with a backslash, +which shall be ignored, but preserves the comma as part of +\fIvalue\fP. A comma as the final character, or a comma followed solely +by white space as the final characters, in \fIoptions\fP +shall be ignored. Multiple \fB-o\fP options can be specified; if keywords +given to these multiple \fB-o\fP options conflict, the +keywords and values appearing later in command line sequence shall +take precedence and the earlier shall be silently ignored. The +following keyword values of \fIoptions\fP shall be supported for the +file formats as indicated: +.TP 7 +\fBdelete\fP=\fIpattern\fP +.RS +.sp +(Applicable only to the \fB-x\fP \fBpax\fP format.) When used in \fBwrite\fP +or \fBcopy\fP mode, \fIpax\fP shall omit from +extended header records that it produces any keywords matching the +string pattern. When used in \fBread\fP or \fBlist\fP mode, +\fIpax\fP shall ignore any keywords matching the string pattern in +the extended header records. In both cases, matching shall be +performed using the pattern matching notation described in \fIPatterns +Matching a Single +Character\fP and \fIPatterns Matching Multiple Characters\fP . For +example: +.sp +.RS +.nf + +\fB-o\fP \fBdelete\fP\fB=\fP\fIsecurity\fP\fB.* +\fP +.fi +.RE +.LP +would suppress security-related information. See pax Extended Header +for extended header record +keyword usage. +.RE +.TP 7 +\fBexthdr.name\fP=\fIstring\fP +.RS +.sp +(Applicable only to the \fB-x\fP \fBpax\fP format.) This keyword allows +user control over the name that is written into the +\fBustar\fP header blocks for the extended header produced under the +circumstances described in pax +Header Block . The name shall be the contents of \fIstring\fP, after +the following character substitutions have been made: +.TS C +center; l lw(40). +\fB\fIstring\fP\fP T{ +.na +\fB\ \fP +.ad +T} +\fBIncludes:\fP T{ +.na +\fBReplaced By:\fP +.ad +T} +%d T{ +.na +The directory name of the file, equivalent to the result of the \fIdirname\fP utility on the translated pathname. +.ad +T} +%f T{ +.na +The filename of the file, equivalent to the result of the \fIbasename\fP utility on the translated pathname. +.ad +T} +%p T{ +.na +The process ID of the \fIpax\fP process. +.ad +T} +%% T{ +.na +A \fB'%'\fP character. +.ad +T} +.TE +.LP +Any other \fB'%'\fP characters in \fIstring\fP produce undefined results. +.LP +If no \fB-o\fP \fBexthdr.name=\fP \fIstring\fP is specified, \fIpax\fP +shall use the following default value: +.sp +.RS +.nf + +\fB%d/PaxHeaders.%p/%f +\fP +.fi +.RE +.RE +.TP 7 +\fBglobexthdr.name\fP=\fIstring\fP +.RS +.sp +(Applicable only to the \fB-x\fP \fBpax\fP format.) When used in \fBwrite\fP +or \fBcopy\fP mode with the appropriate options, +\fIpax\fP shall create global extended header records with \fBustar\fP +header blocks that will be treated as regular files by +previous versions of \fIpax\fP. This keyword allows user control over +the name that is written into the \fBustar\fP header blocks +for global extended header records. The name shall be the contents +of string, after the following character substitutions have been +made: +.TS C +center; l lw(40). +\fB\fIstring\fP\fP T{ +.na +\fB\ \fP +.ad +T} +\fBIncludes:\fP T{ +.na +\fBReplaced By:\fP +.ad +T} +%n T{ +.na +An integer that represents the sequence number of the global extended header record in the archive, starting at 1. +.ad +T} +%p T{ +.na +The process ID of the \fIpax\fP process. +.ad +T} +%% T{ +.na +A \fB'%'\fP character. +.ad +T} +.TE +.LP +Any other \fB'%'\fP characters in \fIstring\fP produce undefined results. +.LP +If no \fB-o\fP \fBglobexthdr.name=\fP \fIstring\fP is specified, \fIpax\fP +shall use the following default value: +.sp +.RS +.nf + +\fB$TMPDIR/GlobalHead.%p.%n +\fP +.fi +.RE +.LP +where $ \fITMPDIR\fP represents the value of the \fITMPDIR\fP environment +variable. If \fITMPDIR\fP is not set, \fIpax\fP +shall use \fB/tmp\fP. +.RE +.TP 7 +\fBinvalid\fP=\fIaction\fP +.RS +.sp +(Applicable only to the \fB-x\fP \fBpax\fP format.) This keyword allows +user control over the action \fIpax\fP takes upon +encountering values in an extended header record that, in \fBread\fP +or \fBcopy\fP mode, are invalid in the destination hierarchy +or, in \fBlist\fP mode, cannot be written in the codeset and current +locale of the implementation. The following are invalid +values that shall be recognized by \fIpax\fP: +.RS +.IP " *" 3 +In \fBread\fP or \fBcopy\fP mode, a filename or link name that contains +character encodings invalid in the destination +hierarchy. (For example, the name may contain embedded NULs.) +.LP +.IP " *" 3 +In \fBread\fP or \fBcopy\fP mode, a filename or link name that is +longer than the maximum allowed in the destination hierarchy +(for either a pathname component or the entire pathname). +.LP +.IP " *" 3 +In \fBlist\fP mode, any character string value (filename, link name, +user name, and so on) that cannot be written in the +codeset and current locale of the implementation. +.LP +.RE +.LP +The following mutually-exclusive values of the \fIaction\fP argument +are supported: +.TP 7 +\fBbypass\fP +.RS +In \fBread\fP or \fBcopy\fP mode, \fIpax\fP shall bypass the file, +causing no change to the destination hierarchy. In +\fBlist\fP mode, \fIpax\fP shall write all requested valid values +for the file, but its method for writing invalid values is +unspecified. +.RE +.TP 7 +\fBrename\fP +.RS +In \fBread\fP or \fBcopy\fP mode, \fIpax\fP shall act as if the \fB-i\fP +option were in effect for each file with invalid +filename or link name values, allowing the user to provide a replacement +name interactively. In \fBlist\fP mode, \fIpax\fP shall +behave identically to the \fBbypass\fP action. +.RE +.TP 7 +\fBUTF-8\fP +.RS +When used in \fBread\fP, \fBcopy\fP, or \fBlist\fP mode and a filename, +link name, owner name, or any other field in an +extended header record cannot be translated from the \fBpax\fP UTF-8 +codeset format to the codeset and current locale of the +implementation, \fIpax\fP shall use the actual UTF-8 encoding for +the name. +.RE +.TP 7 +\fBwrite\fP +.RS +In \fBread\fP or \fBcopy\fP mode, \fIpax\fP shall write the file, +translating or truncating the name, regardless of whether +this may overwrite an existing file with a valid name. In \fBlist\fP +mode, \fIpax\fP shall behave identically to the +\fBbypass\fP action. +.RE +.sp +.LP +If no \fB-o\fP \fBinvalid=\fP option is specified, \fIpax\fP shall +act as if \fB-o\fP \fBinvalid=\fP \fBbypass\fP were +specified. Any overwriting of existing files that may be allowed by +the \fB-o\fP \fBinvalid=\fP actions shall be subject to +permission ( \fB-p\fP) and modification time ( \fB-u\fP) restrictions, +and shall be suppressed if the \fB-k\fP option is also +specified. +.RE +.TP 7 +\fBlinkdata\fP +.RS +.sp +(Applicable only to the \fB-x\fP \fBpax\fP format.) In \fBwrite\fP +mode, \fIpax\fP shall write the contents of a file to the +archive even when that file is merely a hard link to a file whose +contents have already been written to the archive. +.RE +.TP 7 +\fBlistopt\fP=\fIformat\fP +.RS +.sp +This keyword specifies the output format of the table of contents +produced when the \fB-v\fP option is specified in \fBlist\fP +mode. See List Mode Format Specifications . To avoid ambiguity, the +\fBlistopt=\fP \fIformat\fP +shall be the only or final \fBkeyword=\fP \fIvalue\fP pair in a \fB-o\fP +option-argument; all characters in the remainder of the +option-argument shall be considered part of the format string. When +multiple \fB-o\fP \fBlistopt=\fP \fIformat\fP options are +specified, the format strings shall be considered a single, concatenated +string, evaluated in command line order. +.RE +.TP 7 +\fBtimes\fP +.RS +.sp +(Applicable only to the \fB-x\fP \fIpax\fP format.) When used in \fBwrite\fP +or \fBcopy\fP mode, \fIpax\fP shall include +\fBatime\fP, \fBctime\fP, and \fBmtime\fP extended header records +for each file. See pax Extended +Header File Times . +.RE +.sp +.LP +In addition to these keywords, if the \fB-x\fP \fIpax\fP format is +specified, any of the keywords and values defined in pax Extended +Header , including implementation extensions, can be used in \fB-o\fP +option-arguments, +in either of two modes: +.TP 7 +\fBkeyword\fP=\fIvalue\fP +.RS +.sp +When used in \fBwrite\fP or \fBcopy\fP mode, these keyword/value pairs +shall be included at the beginning of the archive as +\fBtypeflag\fP \fBg\fP global extended header records. When used in +\fBread\fP or \fBlist\fP mode, these keyword/value pairs +shall act as if they had been at the beginning of the archive as \fBtypeflag\fP +\fBg\fP global extended header records. +.RE +.TP 7 +\fBkeyword\fP:=\fIvalue\fP +.RS +.sp +When used in \fBwrite\fP or \fBcopy\fP mode, these keyword/value pairs +shall be included as records at the beginning of a +\fBtypeflag\fP \fBx\fP extended header for each file. (This shall +be equivalent to the equal-sign form except that it creates no +\fBtypeflag\fP \fBg\fP global extended header records.) When used +in \fBread\fP or \fBlist\fP mode, these keyword/value pairs +shall act as if they were included as records at the end of each extended +header; thus, they shall override any global or +file-specific extended header record keywords of the same names. For +example, in the command: +.sp +.RS +.nf + +\fBpax -r -o " +gname:=mygroup, +" s. +.LP +Any non-null character can be used as a delimiter ( \fB'/'\fP shown +here). Multiple \fB-s\fP expressions can be specified; +the expressions shall be applied in the order specified, terminating +with the first successful substitution. The optional trailing +\fB'g'\fP is as defined in the \fIed\fP utility. The optional trailing +\fB'p'\fP shall +cause successful substitutions to be written to standard error. File +or archive member names that substitute to the empty string +shall be ignored when reading and writing archives. +.TP 7 +\fB-t\fP +When reading files from the file system, and if the user has the permissions +required by \fIutime\fP() to do so, set the access time of each file +read to the access time that it had before +being read by \fIpax\fP. +.TP 7 +\fB-u\fP +Ignore files that are older (having a less recent file modification +time) than a pre-existing file or archive member with the +same name. In \fBread\fP mode, an archive member with the same name +as a file in the file system shall be extracted if the archive +member is newer than the file. In \fBwrite\fP mode, an archive file +member with the same name as a file in the file system shall +be superseded if the file is newer than the archive member. If \fB-a\fP +is also specified, this is accomplished by appending to +the archive; otherwise, it is unspecified whether this is accomplished +by actual replacement in the archive or by appending to the +archive. In \fBcopy\fP mode, the file in the destination hierarchy +shall be replaced by the file in the source hierarchy or by a +link to the file in the source hierarchy if the file in the source +hierarchy is newer. +.TP 7 +\fB-v\fP +In \fBlist\fP mode, produce a verbose table of contents (see the STDOUT +section). Otherwise, write archive member pathnames to +standard error (see the STDERR section). +.TP 7 +\fB-x\ \fP \fIformat\fP +Specify the output archive format. The \fIpax\fP utility shall support +the following formats: +.TP 7 +\fBcpio\fP +.RS +The \fBcpio\fP interchange format; see the EXTENDED DESCRIPTION section. +The default \fIblocksize\fP for this format for +character special archive files shall be 5120. Implementations shall +support all \fIblocksize\fP values less than or equal to +32256 that are multiples of 512. +.RE +.TP 7 +\fBpax\fP +.RS +The \fBpax\fP interchange format; see the EXTENDED DESCRIPTION section. +The default \fIblocksize\fP for this format for +character special archive files shall be 5120. Implementations shall +support all \fIblocksize\fP values less than or equal to +32256 that are multiples of 512. +.RE +.TP 7 +\fBustar\fP +.RS +The \fBtar\fP interchange format; see the EXTENDED DESCRIPTION section. +The default \fIblocksize\fP for this format for +character special archive files shall be 10240. Implementations shall +support all \fIblocksize\fP values less than or equal to +32256 that are multiples of 512. +.RE +.sp +.LP +Implementation-defined formats shall specify a default block size +as well as any other block sizes supported for character +special archive files. +.LP +Any attempt to append to an archive file in a format different from +the existing archive format shall cause \fIpax\fP to exit +immediately with a non-zero exit status. +.LP +In \fBcopy\fP mode, if no \fB-x\fP format is specified, \fIpax\fP +shall behave as if \fB-x\fP \fIpax\fP were specified. +.TP 7 +\fB-X\fP +When traversing the file hierarchy specified by a pathname, \fIpax\fP +shall not descend into directories that have a different +device ID ( \fIst_dev\fP; see the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIstat\fP()). +.sp +.LP +The options that operate on the names of files or archive members +( \fB-c\fP, \fB-i\fP, \fB-n\fP, \fB-s\fP, \fB-u\fP, and +\fB-v\fP) shall interact as follows. In \fBread\fP mode, the archive +members shall be selected based on the user-specified +\fIpattern\fP operands as modified by the \fB-c\fP, \fB-n\fP, and +\fB-u\fP options. Then, any \fB-s\fP and \fB-i\fP options +shall modify, in that order, the names of the selected files. The +\fB-v\fP option shall write names resulting from these +modifications. +.LP +In \fBwrite\fP mode, the files shall be selected based on the user-specified +pathnames as modified by the \fB-n\fP and +\fB-u\fP options. Then, any \fB-s\fP and \fB-i\fP options shall modify, +in that order, the names of these selected files. The +\fB-v\fP option shall write names resulting from these modifications. +.LP +If both the \fB-u\fP and \fB-n\fP options are specified, \fIpax\fP +shall not consider a file selected unless it is newer than +the file to which it is compared. +.SS List Mode Format Specifications +.LP +In \fBlist\fP mode with the \fB-o\fP \fBlistopt=\fP \fIformat\fP option, +the \fIformat\fP argument shall be applied for +each selected file. The \fIpax\fP utility shall append a +to the \fBlistopt\fP output for each selected file. The +\fIformat\fP argument shall be used as the \fIformat\fP string described +in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 5, File Format Notation, with the +exceptions 1. +through 5. defined in the EXTENDED DESCRIPTION section of \fIprintf\fP, +plus the following +exceptions: +.TP 7 +6. +The sequence ( \fIkeyword\fP) can occur before a format conversion +specifier. The conversion argument is defined by the value +of \fIkeyword\fP. The implementation shall support the following keywords: +.RS +.IP " *" 3 +Any of the Field Name entries in ustar Header Block and Octet-Oriented +cpio +Archive Entry . The implementation may support the \fIcpio\fP keywords +without the leading \fBc_\fP in addition to the form +required by Values for cpio c_mode Field . +.LP +.IP " *" 3 +Any keyword defined for the extended header in pax Extended Header +\&. +.LP +.IP " *" 3 +Any keyword provided as an implementation-defined extension within +the extended header defined in pax Extended Header . +.LP +.RE +.LP +For example, the sequence \fB"%(charset)s"\fP is the string value +of the name of the character set in the extended +header. +.LP +The result of the keyword conversion argument shall be the value from +the applicable header field or extended header, without +any trailing NULs. +.LP +All keyword values used as conversion arguments shall be translated +from the UTF-8 encoding to the character set appropriate for +the local file system, user database, and so on, as applicable. +.TP 7 +7. +An additional conversion specifier character, \fBT\fP , shall be used +to specify time formats. The \fBT\fP conversion +specifier character can be preceded by the sequence ( \fIkeyword=\fP +\fIsubformat\fP), where \fIsubformat\fP is a date format as +defined by \fIdate\fP operands. The default \fIkeyword\fP shall be +\fBmtime\fP and the +default subformat shall be: +.sp +.RS +.nf + +\fB%b %e %H:%M %Y +\fP +.fi +.RE +.TP 7 +8. +An additional conversion specifier character, \fBM\fP , shall be used +to specify the file mode string as defined in \fIls\fP Standard Output. +If ( \fIkeyword\fP) is omitted, the \fBmode\fP keyword shall be used. +For +example, \fB%.1M\fP writes the single character corresponding to the +<\fIentry\ type\fP> field of the \fIls\fP \fB-l\fP command. +.TP 7 +9. +An additional conversion specifier character, \fBD\fP , shall be used +to specify the device for block or special files, if +applicable, in an implementation-defined format. If not applicable, +and ( \fIkeyword\fP) is specified, then this conversion shall +be equivalent to \fB%(\fP\fIkeyword\fP\fB)u\fP. If not applicable, +and ( \fIkeyword\fP) is omitted, then this conversion +shall be equivalent to . +.TP 7 +10. +An additional conversion specifier character, \fBF\fP , shall be used +to specify a pathname. The \fBF\fP conversion +character can be preceded by a sequence of comma-separated keywords: +.sp +.RS +.nf + +\fB(\fP\fIkeyword\fP\fB[\fP\fB,\fP\fIkeyword\fP\fB]\fP \fB... ) +\fP +.fi +.RE +.LP +The values for all the keywords that are non-null shall be concatenated +together, each separated by a \fB'/'\fP . The default +shall be ( \fBpath\fP) if the keyword \fBpath\fP is defined; otherwise, +the default shall be ( \fBprefix\fP, \fBname\fP). +.TP 7 +11. +An additional conversion specifier character, \fBL\fP , shall be used +to specify a symbolic line expansion. If the current +file is a symbolic link, then \fB%L\fP shall expand to: +.sp +.RS +.nf + +\fB"%s -> %s", <\fP\fIvalue of keyword\fP\fB>, <\fP\fIcontents of link\fP\fB> +\fP +.fi +.RE +.LP +Otherwise, the \fB%L\fP conversion specification shall be the equivalent +of \fB%F\fP . +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIdirectory\fP +The destination directory pathname for \fBcopy\fP mode. +.TP 7 +\fIfile\fP +A pathname of a file to be copied or archived. +.TP 7 +\fIpattern\fP +A pattern matching one or more pathnames of archive members. A pattern +must be given in the name-generating notation of the +pattern matching notation in \fIPattern Matching Notation\fP , including +the filename +expansion rules in \fIPatterns Used for Filename Expansion\fP . The +default, if no +\fIpattern\fP is specified, is to select all members in the archive. +.sp +.SH STDIN +.LP +In \fBwrite\fP mode, the standard input shall be used only if no \fIfile\fP +operands are specified. It shall be a text file +containing a list of pathnames, one per line, without leading or trailing +s. +.LP +In \fBlist\fP and \fBread\fP modes, if \fB-f\fP is not specified, +the standard input shall be an archive file. +.LP +Otherwise, the standard input shall not be used. +.SH INPUT FILES +.LP +The input file named by the \fIarchive\fP option-argument, or standard +input when the archive is read from there, shall be a +file formatted according to one of the specifications in the EXTENDED +DESCRIPTION section or some other implementation-defined +format. +.LP +The file \fB/dev/tty\fP shall be used to write prompts and read responses. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIpax\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the pattern +matching expressions for the \fIpattern\fP operand, the basic regular +expression for the \fB-s\fP option, and the extended +regular expression defined for the \fByesexpr\fP locale keyword in +the \fILC_MESSAGES\fP category. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), the +behavior of character classes used in the extended regular +expression defined for the \fByesexpr\fP locale keyword in the \fILC_MESSAGES\fP +category, and pattern matching. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale for the processing of affirmative responses that +should be used to affect the format and contents of +diagnostic messages written to standard error. +.TP 7 +\fILC_TIME\fP +Determine the format and contents of date and time strings when the +\fB-v\fP option is specified. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITMPDIR\fP +Determine the pathname that provides part of the default global extended +header record file, as described for the \fB-o\fP +\fBglobexthdr=\fP keyword in the OPTIONS section. +.TP 7 +\fITZ\fP +Determine the timezone used to calculate date and time strings when +the \fB-v\fP option is specified. If \fITZ\fP is unset or +null, an unspecified default timezone shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +In \fBwrite\fP mode, if \fB-f\fP is not specified, the standard output +shall be the archive formatted according to one of the +specifications in the EXTENDED DESCRIPTION section, or some other +implementation-defined format (see \fB-x\fP \fIformat\fP). +.LP +In \fBlist\fP mode, when the \fB-o\fP \fBlistopt\fP= \fIformat\fP +has been specified, the selected archive members shall be +written to standard output using the format described under List Mode +Format Specifications . In +\fBlist\fP mode without the \fB-o\fP \fBlistopt\fP= \fIformat\fP option, +the table of contents of the selected archive members +shall be written to standard output using the following format: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIpathname\fP\fB> +\fP +.fi +.RE +.LP +If the \fB-v\fP option is specified in \fBlist\fP mode, the table +of contents of the selected archive members shall be written +to standard output using the following formats. +.LP +For pathnames representing hard links to previous members of the archive: +.sp +.RS +.nf + +\fB"%s == %s\\n", <\fP\fIls\fP \fB-l\fP \fIlisting\fP\fB>, <\fP\fIlinkname\fP\fB> +\fP +.fi +.RE +.LP +For all other pathnames: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIls\fP \fB-l\fP \fIlisting\fP\fB> +\fP +.fi +.RE +.LP +where <\fIls\ \fP -l\ \fIlisting\fP> shall be the format specified +by the \fIls\fP utility with the \fB-l\fP option. When writing pathnames +in this format, it is unspecified +what is written for fields for which the underlying archive format +does not have the correct information, although the correct +number of -separated fields shall be written. +.LP +In \fBlist\fP mode, standard output shall not be buffered more than +a line at a time. +.SH STDERR +.LP +If \fB-v\fP is specified in \fBread\fP, \fBwrite\fP, or \fBcopy\fP +modes, \fIpax\fP shall write the pathnames it processes +to the standard error output using the following format: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIpathname\fP\fB> +\fP +.fi +.RE +.LP +These pathnames shall be written as soon as processing is begun on +the file or archive member, and shall be flushed to standard +error. The trailing , which shall not be buffered, is written +when the file has been read or written. +.LP +If the \fB-s\fP option is specified, and the replacement string has +a trailing \fB'p'\fP , substitutions shall be written to +standard error in the following format: +.sp +.RS +.nf + +\fB"%s >> %s\\n", <\fP\fIoriginal pathname\fP\fB>, <\fP\fInew pathname\fP\fB> +\fP +.fi +.RE +.LP +In all operating modes of \fIpax\fP, optional messages of unspecified +format concerning the input archive format and volume +number, the number of files, blocks, volumes, and media parts as well +as other diagnostic messages may be written to standard +error. +.LP +In all formats, for both standard output and standard error, it is +unspecified how non-printable characters in pathnames or link +names are written. +.LP +When \fIpax\fP is in \fBread\fP mode or \fBlist\fP mode, using the +\fB-x\fP \fBpax\fP archive format, and a filename, link +name, owner name, or any other field in an extended header record +cannot be translated from the \fBpax\fP UTF-8 codeset format to +the codeset and current locale of the implementation, \fIpax\fP shall +write a diagnostic message to standard error, shall process +the file as described for the \fB-o\fP \fBinvalid=\fP option, and +then shall process the next file in the archive. +.SH OUTPUT FILES +.LP +In \fBread\fP mode, the extracted output files shall be of the archived +file type. In \fBcopy\fP mode, the copied output files +shall be the type of the file being copied. In either mode, existing +files in the destination hierarchy shall be overwritten only +when all permission ( \fB-p\fP), modification time ( \fB-u\fP), and +invalid-value ( \fB-o\fP \fBinvalid\fP=) tests allow +it. +.LP +In \fBwrite\fP mode, the output file named by the \fB-f\fP option-argument +shall be a file formatted according to one of the +specifications in the EXTENDED DESCRIPTION section, or some other +implementation-defined format. +.SH EXTENDED DESCRIPTION +.SS pax Interchange Format +.LP +A \fIpax\fP archive tape or file produced in the \fB-x\fP \fBpax\fP +format shall contain a series of blocks. The physical +layout of the archive shall be identical to the \fBustar\fP format +described in ustar Interchange +Format . Each file archived shall be represented by the following +sequence: +.IP " *" 3 +An optional header block with extended header records. This header +block is of the form described in pax Header Block , with a \fItypeflag\fP +value of \fBx\fP or \fBg\fP. The extended header records, +described in pax Extended Header , shall be included as the data for +this header block. +.LP +.IP " *" 3 +A header block that describes the file. Any fields in the preceding +optional extended header shall override the associated +fields in this header block for this file. +.LP +.IP " *" 3 +Zero or more blocks that contain the contents of the file. +.LP +.LP +At the end of the archive file there shall be two 512-byte blocks +filled with binary zeros, interpreted as an end-of-archive +indicator. +.LP +A schematic of an example archive with global extended header records +and two actual files is shown in pax +Format Archive Example . In the example, the second file in the archive +has no extended header preceding it, presumably because +it has no need for extended attributes. +.TP 7 +.sp +.sp +.ce 1 +\fBFigure: pax Format Archive Example\fP +.SS pax Header Block +.LP +The \fBpax\fP header block shall be identical to the \fBustar\fP header +block described in ustar +Interchange Format , except that two additional \fItypeflag\fP values +are defined: +.TP 7 +\fBx\fP +Represents extended header records for the following file in the archive +(which shall have its own \fBustar\fP header block). +The format of these extended header records shall be as described +in pax Extended Header . +.TP 7 +\fBg\fP +Represents global extended header records for the following files +in the archive. The format of these extended header records +shall be as described in pax Extended Header . Each value shall affect +all subsequent files that do +not override that value in their own extended header record and until +another global extended header record is reached that +provides another value for the same field. The \fItypeflag\fP \fBg\fP +global headers should not be used with interchange media +that could suffer partial data loss in transporting the archive. +.sp +.LP +For both of these types, the \fIsize\fP field shall be the size of +the extended header records in octets. The other fields in +the header block are not meaningful to this version of the \fIpax\fP +utility. However, if this archive is read by a \fIpax\fP +utility conforming to the ISO\ POSIX-2:1993 standard, the header block +fields are used to create a regular file that contains +the extended header records as data. Therefore, header block field +values should be selected to provide reasonable file access to +this regular file. +.LP +A further difference from the \fBustar\fP header block is that data +blocks for files of \fItypeflag\fP 1 (the digit one) (hard +link) may be included, which means that the size field may be greater +than zero. Archives created by \fIpax\fP \fB-o\fP +\fBlinkdata\fP shall include these data blocks with the hard links. +.SS pax Extended Header +.LP +A \fBpax\fP extended header contains values that are inappropriate +for the \fBustar\fP header block because of limitations in +that format: fields requiring a character encoding other than that +described in the ISO/IEC\ 646:1991 standard, fields +representing file attributes not described in the \fBustar\fP header, +and fields whose format or length do not fit the +requirements of the \fBustar\fP header. The values in an extended +header add attributes to the following file (or files; see the +description of the \fItypeflag\fP \fBg\fP header block) or override +values in the following header block(s), as indicated in the +following list of keywords. +.LP +An extended header shall consist of one or more records, each constructed +as follows: +.sp +.RS +.nf + +\fB"%d %s=%s\\n", <\fP\fIlength\fP\fB>, <\fP\fIkeyword\fP\fB>, <\fP\fIvalue\fP\fB> +\fP +.fi +.RE +.LP +The extended header records shall be encoded according to the ISO/IEC\ 10646-1:2000 +standard (UTF-8). The +<\fIlength\fP> field, , equals sign, and shown shall +be limited to the portable character set, +as encoded in UTF-8. The <\fIkeyword\fP> and <\fIvalue\fP> fields +can be any UTF-8 characters. The +<\fIlength\fP> field shall be the decimal length of the extended header +record in octets, including the trailing +. +.LP +The <\fIkeyword\fP> field shall be one of the entries from the following +list or a keyword provided as an implementation +extension. Keywords consisting entirely of lowercase letters, digits, +and periods are reserved for future standardization. A +keyword shall not include an equals sign. (In the following list, +the notations "file(s)" or "block(s)" is used to acknowledge +that a keyword affects the following single file after a \fItypeflag\fP +\fBx\fP extended header, but possibly multiple files +after \fItypeflag\fP \fBg\fP. Any requirements in the list for \fIpax\fP +to include a record when in \fBwrite\fP or \fBcopy\fP +mode shall apply only when such a record has not already been provided +through the use of the \fB-o\fP option. When used in +\fBcopy\fP mode, \fIpax\fP shall behave as if an archive had been +created with applicable extended header records and then +extracted.) +.TP 7 +\fBatime\fP +The file access time for the following file(s), equivalent to the +value of the \fIst_atime\fP member of the \fBstat\fP +structure for a file, as described by the \fIstat\fP() function. The +access time shall be +restored if the process has the appropriate privilege required to +do so. The format of the <\fIvalue\fP> shall be as +described in pax Extended Header File Times . +.TP 7 +\fBcharset\fP +The name of the character set used to encode the data in the following +file(s). The entries in the following table are defined +to refer to known standards; additional names may be agreed on between +the originator and recipient. +.TS C +center; l2 l. +\fB\fP \fBFormal Standard\fP +ISO-IR 646 1990 ISO/IEC 646:1990 +ISO-IR 8859 1 1998 ISO/IEC 8859-1:1998 +ISO-IR 8859 2 1999 ISO/IEC 8859-2:1999 +ISO-IR 8859 3 1999 ISO/IEC 8859-3:1999 +ISO-IR 8859 4 1998 ISO/IEC 8859-4:1998 +ISO-IR 8859 5 1999 ISO/IEC 8859-5:1999 +ISO-IR 8859 6 1999 ISO/IEC 8859-6:1999 +ISO-IR 8859 7 1987 ISO/IEC 8859-7:1987 +ISO-IR 8859 8 1999 ISO/IEC 8859-8:1999 +ISO-IR 8859 9 1999 ISO/IEC 8859-9:1999 +ISO-IR 8859 10 1998 ISO/IEC 8859-10:1998 +ISO-IR 8859 13 1998 ISO/IEC 8859-13:1998 +ISO-IR 8859 14 1998 ISO/IEC 8859-14:1998 +ISO-IR 8859 15 1999 ISO/IEC 8859-15:1999 +ISO-IR 10646 2000 ISO/IEC 10646:2000 +ISO-IR 10646 2000 UTF-8 ISO/IEC 10646, UTF-8 encoding +BINARY None. +.TE +.LP +The encoding is included in an extended header for information only; +when \fIpax\fP is used as described in +IEEE\ Std\ 1003.1-2001, it shall not translate the file data into +any other encoding. The \fBBINARY\fP entry indicates +unencoded binary data. +.LP +When used in \fBwrite\fP or \fBcopy\fP mode, it is implementation-defined +whether \fIpax\fP includes a \fBcharset\fP +extended header record for a file. +.TP 7 +\fBcomment\fP +A series of characters used as a comment. All characters in the <\fIvalue\fP> +field shall be ignored by \fIpax\fP. +.TP 7 +\fBctime\fP +The file creation time for the following file(s), equivalent to the +value of the \fIst_ctime\fP member of the \fBstat\fP +structure for a file, as described by the \fIstat\fP() function. The +creation time shall be +restored if the process has the appropriate privilege required to +do so. The format of the <\fIvalue\fP> shall be as +described in pax Extended Header File Times . +.TP 7 +\fBgid\fP +The group ID of the group that owns the file, expressed as a decimal +number using digits from the ISO/IEC\ 646:1991 +standard. This record shall override the \fIgid\fP field in the following +header block(s). When used in \fBwrite\fP or +\fBcopy\fP mode, \fIpax\fP shall include a \fIgid\fP extended header +record for each file whose group ID is greater than 2097151 +(octal 7777777). +.TP 7 +\fBgname\fP +The group of the file(s), formatted as a group name in the group database. +This record shall override the \fIgid\fP and +\fIgname\fP fields in the following header block(s), and any \fIgid\fP +extended header record. When used in \fBread\fP, +\fBcopy\fP, or \fBlist\fP mode, \fIpax\fP shall translate the name +from the UTF-8 encoding in the header record to the character +set appropriate for the group database on the receiving system. If +any of the UTF-8 characters cannot be translated, and if the +\fB-o\fP \fBinvalid=\fP UTF-8 option is not specified, the results +are implementation-defined. When used in \fBwrite\fP or +\fBcopy\fP mode, \fIpax\fP shall include a \fBgname\fP extended header +record for each file whose group name cannot be +represented entirely with the letters and digits of the portable character +set. +.TP 7 +\fBlinkpath\fP +The pathname of a link being created to another file, of any type, +previously archived. This record shall override the +\fIlinkname\fP field in the following \fBustar\fP header block(s). +The following \fBustar\fP header block shall determine the +type of link created. If \fItypeflag\fP of the following header block +is 1, it shall be a hard link. If \fItypeflag\fP is 2, it +shall be a symbolic link and the \fBlinkpath\fP value shall be the +contents of the symbolic link. The \fIpax\fP utility shall +translate the name of the link (contents of the symbolic link) from +the UTF-8 encoding to the character set appropriate for the +local file system. When used in \fBwrite\fP or \fBcopy\fP mode, \fIpax\fP +shall include a \fBlinkpath\fP extended header record +for each link whose pathname cannot be represented entirely with the +members of the portable character set other than NUL. +.TP 7 +\fBmtime\fP +The file modification time of the following file(s), equivalent to +the value of the \fIst_mtime\fP member of the \fBstat\fP +structure for a file, as described in the \fIstat\fP() function. This +record shall override +the \fImtime\fP field in the following header block(s). The modification +time shall be restored if the process has the appropriate +privilege required to do so. The format of the <\fIvalue\fP> shall +be as described in pax +Extended Header File Times . +.TP 7 +\fBpath\fP +The pathname of the following file(s). This record shall override +the \fIname\fP and \fIprefix\fP fields in the following +header block(s). The \fIpax\fP utility shall translate the pathname +of the file from the UTF-8 encoding to the character set +appropriate for the local file system. +.LP +When used in \fBwrite\fP or \fBcopy\fP mode, \fIpax\fP shall include +a \fIpath\fP extended header record for each file whose +pathname cannot be represented entirely with the members of the portable +character set other than NUL. +.TP 7 +\fBrealtime.\fP\fIany\fP +The keywords prefixed by "realtime." are reserved for future standardization. +.TP 7 +\fBsecurity.\fP\fIany\fP +The keywords prefixed by "security." are reserved for future standardization. +.TP 7 +\fBsize\fP +The size of the file in octets, expressed as a decimal number using +digits from the ISO/IEC\ 646:1991 standard. This record +shall override the \fIsize\fP field in the following header block(s). +When used in \fBwrite\fP or \fBcopy\fP mode, \fIpax\fP +shall include a \fIsize\fP extended header record for each file with +a size value greater than 8589934591 (octal +77777777777). +.TP 7 +\fBuid\fP +The user ID of the file owner, expressed as a decimal number using +digits from the ISO/IEC\ 646:1991 standard. This record +shall override the \fIuid\fP field in the following header block(s). +When used in \fBwrite\fP or \fBcopy\fP mode, \fIpax\fP +shall include a \fIuid\fP extended header record for each file whose +owner ID is greater than 2097151 (octal 7777777). +.TP 7 +\fBuname\fP +The owner of the following file(s), formatted as a user name in the +user database. This record shall override the \fIuid\fP +and \fIuname\fP fields in the following header block(s), and any \fIuid\fP +extended header record. When used in \fBread\fP, +\fBcopy\fP, or \fBlist\fP mode, \fIpax\fP shall translate the name +from the UTF-8 encoding in the header record to the character +set appropriate for the user database on the receiving system. If +any of the UTF-8 characters cannot be translated, and if the +\fB-o\fP \fBinvalid=\fP UTF-8 option is not specified, the results +are implementation-defined. When used in \fBwrite\fP or +\fBcopy\fP mode, \fIpax\fP shall include a \fBuname\fP extended header +record for each file whose user name cannot be +represented entirely with the letters and digits of the portable character +set. +.sp +.LP +If the <\fIvalue\fP> field is zero length, it shall delete any header +block field, previously entered extended header +value, or global extended header value of the same name. +.LP +If a keyword in an extended header record (or in a \fB-o\fP option-argument) +overrides or deletes a corresponding field in the +\fBustar\fP header block, \fIpax\fP shall ignore the contents of that +header block field. +.LP +Unlike the \fBustar\fP header block fields, NULs shall not delimit +<\fIvalue\fP>s; all characters within the +<\fIvalue\fP> field shall be considered data for the field. None of +the length limitations of the \fBustar\fP header block +fields in ustar Header Block shall apply to the extended header records. +.SS pax Extended Header Keyword Precedence +.LP +This section describes the precedence in which the various header +records and fields and command line options are selected to +apply to a file in the archive. When \fIpax\fP is used in \fBread\fP +or \fBlist\fP modes, it shall determine a file attribute in +the following sequence: +.IP " 1." 4 +If \fB-o\fP \fBdelete=\fP \fIkeyword-prefix\fP is used, the affected +attributes shall be determined from step 7., if +applicable, or ignored otherwise. +.LP +.IP " 2." 4 +If \fB-o\fP \fIkeyword\fP:= is used, the affected attributes shall +be ignored. +.LP +.IP " 3." 4 +If \fB-o\fP \fIkeyword\fP \fB:=\fP \fIvalue\fP is used, the affected +attribute shall be assigned the value. +.LP +.IP " 4." 4 +If there is a \fItypeflag\fP \fBx\fP extended header record, the affected +attribute shall be assigned the +<\fIvalue\fP>. When extended header records conflict, the last one +given in the header shall take precedence. +.LP +.IP " 5." 4 +If \fB-o\fP \fIkeyword\fP \fB=\fP \fIvalue\fP is used, the affected +attribute shall be assigned the value. +.LP +.IP " 6." 4 +If there is a \fItypeflag\fP \fBg\fP global extended header record, +the affected attribute shall be assigned the +<\fIvalue\fP>. When global extended header records conflict, the last +one given in the global header shall take +precedence. +.LP +.IP " 7." 4 +Otherwise, the attribute shall be determined from the \fBustar\fP +header block. +.LP +.SS pax Extended Header File Times +.LP +The \fIpax\fP utility shall write an \fBmtime\fP record for each file +in \fBwrite\fP or \fBcopy\fP modes if the file's +modification time cannot be represented exactly in the \fBustar\fP +header logical record described in ustar Interchange Format . This +can occur if the time is out of \fBustar\fP range, or if the file +system +of the underlying implementation supports non-integer time granularities +and the time is not an integer. All of these time records +shall be formatted as a decimal representation of the time in seconds +since the Epoch. If a period ( \fB'.'\fP ) decimal point +character is present, the digits to the right of the point shall represent +the units of a subsecond timing granularity, where the +first digit is tenths of a second and each subsequent digit is a tenth +of the previous digit. In \fBread\fP or \fBcopy\fP mode, +the \fIpax\fP utility shall truncate the time of a file to the greatest +value that is not greater than the input header file time. +In \fBwrite\fP or \fBcopy\fP mode, the \fIpax\fP utility shall output +a time exactly if it can be represented exactly as a +decimal number, and otherwise shall generate only enough digits so +that the same time shall be recovered if the file is extracted +on a system whose underlying implementation supports the same time +granularity. +.SS ustar Interchange Format +.LP +A \fBustar\fP archive tape or file shall contain a series of logical +records. Each logical record shall be a fixed-size logical +record of 512 octets (see below). Although this format may be thought +of as being stored on 9-track industry-standard 12.7 mm (0.5 +in) magnetic tape, other types of transportable media are not excluded. +Each file archived shall be represented by a header logical +record that describes the file, followed by zero or more logical records +that give the contents of the file. At the end of the +archive file there shall be two 512-octet logical records filled with +binary zeros, interpreted as an end-of-archive indicator. +.LP +The logical records may be grouped for physical I/O operations, as +described under the \fB-b\fP \fIblocksize\fP and \fB-x\fP +\fBustar\fP options. Each group of logical records may be written +with a single operation equivalent to the \fIwrite\fP() function. +On magnetic tape, the result of this write shall be a single tape +physical +block. The last physical block shall always be the full size, so logical +records after the two zero logical records may contain +undefined data. +.LP +The header logical record shall be structured as shown in the following +table. All lengths and offsets are in decimal. +.br +.sp +.ce 1 +\fBTable: ustar Header Block\fP +.TS C +center; l l l. +\fBField Name\fP \fBOctet Offset\fP \fBLength (in Octets)\fP +\fIname\fP 0 100 +\fImode\fP 100 8 +\fIuid\fP 108 8 +\fIgid\fP 116 8 +\fIsize\fP 124 12 +\fImtime\fP 136 12 +\fIchksum\fP 148 8 +\fItypeflag\fP 156 1 +\fIlinkname\fP 157 100 +\fImagic\fP 257 6 +\fIversion\fP 263 2 +\fIuname\fP 265 32 +\fIgname\fP 297 32 +\fIdevmajor\fP 329 8 +\fIdevminor\fP 337 8 +\fIprefix\fP 345 155 +.TE +.LP +All characters in the header logical record shall be represented in +the coded character set of the ISO/IEC\ 646:1991 +standard. For maximum portability between implementations, names should +be selected from characters represented by the portable +filename character set as octets with the most significant bit zero. +If an implementation supports the use of characters outside of +slash and the portable filename character set in names for files, +users, and groups, one or more implementation-defined encodings +of these characters shall be provided for interchange purposes. +.LP +However, the \fIpax\fP utility shall never create filenames on the +local system that cannot be accessed via the procedures +described in IEEE\ Std\ 1003.1-2001. If a filename is found on the +medium that would create an invalid filename, it is +implementation-defined whether the data from the file is stored on +the file hierarchy and under what name it is stored. The +\fIpax\fP utility may choose to ignore these files as long as it produces +an error indicating that the file is being ignored. +.LP +Each field within the header logical record is contiguous; that is, +there is no padding used. Each character on the archive +medium shall be stored contiguously. +.LP +The fields \fImagic\fP, \fIuname\fP, and \fIgname\fP are character +strings each terminated by a NUL character. The fields +\fIname\fP, \fIlinkname\fP, and \fIprefix\fP are NUL-terminated character +strings except when all characters in the array +contain non-NUL characters including the last character. The \fIversion\fP +field is two octets containing the characters +\fB"00"\fP (zero-zero). The \fItypeflag\fP contains a single character. +All other fields are leading zero-filled octal numbers +using digits from the ISO/IEC\ 646:1991 standard IRV. Each numeric +field is terminated by one or more or NUL +characters. +.LP +The \fIname\fP and the \fIprefix\fP fields shall produce the pathname +of the file. A new pathname shall be formed, if +\fIprefix\fP is not an empty string (its first character is not NUL), +by concatenating \fIprefix\fP (up to the first NUL +character), a slash character, and \fIname\fP; otherwise, \fIname\fP +is used alone. In either case, \fIname\fP is terminated at +the first NUL character. If \fIprefix\fP begins with a NUL character, +it shall be ignored. In this manner, pathnames of at most +256 characters can be supported. If a pathname does not fit in the +space provided, \fIpax\fP shall notify the user of the error, +and shall not store any part of the file-header or data-on the medium. +.LP +The \fIlinkname\fP field, described below, shall not use the \fIprefix\fP +to produce a pathname. As such, a \fIlinkname\fP is +limited to 100 characters. If the name does not fit in the space provided, +\fIpax\fP shall notify the user of the error, and shall +not attempt to store the link on the medium. +.LP +The \fImode\fP field provides 12 bits encoded in the ISO/IEC\ 646:1991 +standard octal digit representation. The encoded +bits shall represent the following values: +.br +.sp +.ce 1 +\fBTable: ustar \fImode\fP Field\fP +.TS C +center; l1 l1 lw(37). +\fBBit Value\fP \fBIEEE\ Std\ 1003.1-2001 Bit\fP T{ +.na +\fBDescription\fP +.ad +T} +04000 S_ISUID T{ +.na +Set UID on execution. +.ad +T} +02000 S_ISGID T{ +.na +Set GID on execution. +.ad +T} +01000 T{ +.na +Reserved for future standardization. +.ad +T} +00400 S_IRUSR T{ +.na +Read permission for file owner class. +.ad +T} +00200 S_IWUSR T{ +.na +Write permission for file owner class. +.ad +T} +00100 S_IXUSR T{ +.na +Execute/search permission for file owner class. +.ad +T} +00040 S_IRGRP T{ +.na +Read permission for file group class. +.ad +T} +00020 S_IWGRP T{ +.na +Write permission for file group class. +.ad +T} +00010 S_IXGRP T{ +.na +Execute/search permission for file group class. +.ad +T} +00004 S_IROTH T{ +.na +Read permission for file other class. +.ad +T} +00002 S_IWOTH T{ +.na +Write permission for file other class. +.ad +T} +00001 S_IXOTH T{ +.na +Execute/search permission for file other class. +.ad +T} +.TE +.LP +When appropriate privilege is required to set one of these mode bits, +and the user restoring the files from the archive does not +have the appropriate privilege, the mode bits for which the user does +not have appropriate privilege shall be ignored. Some of the +mode bits in the archive format are not mentioned elsewhere in this +volume of IEEE\ Std\ 1003.1-2001. If the implementation +does not support those bits, they may be ignored. +.LP +The \fIuid\fP and \fIgid\fP fields are the user and group ID of the +owner and group of the file, respectively. +.LP +The \fIsize\fP field is the size of the file in octets. If the \fItypeflag\fP +field is set to specify a file to be of type 1 +(a link) or 2 (a symbolic link), the \fIsize\fP field shall be specified +as zero. If the \fItypeflag\fP field is set to specify a +file of type 5 (directory), the \fIsize\fP field shall be interpreted +as described under the definition of that record type. No +data logical records are stored for types 1, 2, or 5. If the \fItypeflag\fP +field is set to 3 (character special file), 4 (block +special file), or 6 (FIFO), the meaning of the \fIsize\fP field is +unspecified by this volume of IEEE\ Std\ 1003.1-2001, +and no data logical records shall be stored on the medium. Additionally, +for type 6, the \fIsize\fP field shall be ignored when +reading. If the \fItypeflag\fP field is set to any other value, the +number of logical records written following the header shall +be ( \fIsize\fP+511)/512, ignoring any fraction in the result of the +division. +.LP +The \fImtime\fP field shall be the modification time of the file at +the time it was archived. It is the ISO/IEC\ 646:1991 +standard representation of the octal value of the modification time +obtained from the \fIstat\fP() function. +.LP +The \fIchksum\fP field shall be the ISO/IEC\ 646:1991 standard IRV +representation of the octal value of the simple sum of +all octets in the header logical record. Each octet in the header +shall be treated as an unsigned value. These values shall be +added to an unsigned integer, initialized to zero, the precision of +which is not less than 17 bits. When calculating the checksum, +the \fIchksum\fP field is treated as if it were all spaces. +.LP +The \fItypeflag\fP field specifies the type of file archived. If a +particular implementation does not recognize the type, or +the user does not have appropriate privilege to create that type, +the file shall be extracted as if it were a regular file if the +file type is defined to have a meaning for the \fIsize\fP field that +could cause data logical records to be written on the medium +(see the previous description for \fIsize\fP). If conversion to a +regular file occurs, the \fIpax\fP utility shall produce an +error indicating that the conversion took place. All of the \fItypeflag\fP +fields shall be coded in the ISO/IEC\ 646:1991 +standard IRV: +.TP 7 +\fB0\fP +Represents a regular file. For backwards-compatibility, a \fItypeflag\fP +value of binary zero ( \fB'\\0'\fP ) should be +recognized as meaning a regular file when extracting files from the +archive. Archives written with this version of the archive file +format create regular files with a \fItypeflag\fP value of the ISO/IEC\ 646:1991 +standard IRV \fB'0'\fP . +.TP 7 +\fB1\fP +Represents a file linked to another file, of any type, previously +archived. Such files are identified by each file having the +same device and file serial number. The linked-to name is specified +in the \fIlinkname\fP field with a NUL-character terminator if +it is less than 100 octets in length. +.TP 7 +\fB2\fP +Represents a symbolic link. The contents of the symbolic link shall +be stored in the \fIlinkname\fP field. +.TP 7 +\fB3,4\fP +Represent character special files and block special files respectively. +In this case the \fIdevmajor\fP and \fIdevminor\fP +fields shall contain information defining the device, the format of +which is unspecified by this volume of +IEEE\ Std\ 1003.1-2001. Implementations may map the device specifications +to their own local specification or may ignore +the entry. +.TP 7 +\fB5\fP +Specifies a directory or subdirectory. On systems where disk allocation +is performed on a directory basis, the \fIsize\fP +field shall contain the maximum number of octets (which may be rounded +to the nearest disk block allocation unit) that the +directory may hold. A \fIsize\fP field of zero indicates no such limiting. +Systems that do not support limiting in this manner +should ignore the \fIsize\fP field. +.TP 7 +\fB6\fP +Specifies a FIFO special file. Note that the archiving of a FIFO file +archives the existence of this file and not its +contents. +.TP 7 +\fB7\fP +Reserved to represent a file to which an implementation has associated +some high-performance attribute. Implementations without +such extensions should treat this file as a regular file (type 0). +.TP 7 +\fBA-Z\fP +The letters \fB'A'\fP to \fB'Z'\fP , inclusive, are reserved for custom +implementations. All other values are reserved +for future versions of IEEE\ Std\ 1003.1-2001. +.sp +.LP +Attempts to archive a socket using \fBustar\fP interchange format +shall produce a diagnostic message. Handling of other file +types is implementation-defined. +.LP +The \fImagic\fP field is the specification that this archive was output +in this archive format. If this field contains +\fBustar\fP (the five characters from the ISO/IEC\ 646:1991 standard +IRV shown followed by NUL), the \fIuname\fP and +\fIgname\fP fields shall contain the ISO/IEC\ 646:1991 standard IRV +representation of the owner and group of the file, +respectively (truncated to fit, if necessary). When the file is restored +by a privileged, protection-preserving version of the +utility, the user and group databases shall be scanned for these names. +If found, the user and group IDs contained within these +files shall be used rather than the values contained within the \fIuid\fP +and \fIgid\fP fields. +.SS cpio Interchange Format +.LP +The octet-oriented \fBcpio\fP archive format shall be a series of +entries, each comprising a header that describes the file, +the name of the file, and then the contents of the file. +.LP +An archive may be recorded as a series of fixed-size blocks of octets. +This blocking shall be used only to make physical I/O +more efficient. The last group of blocks shall always be at the full +size. +.LP +For the octet-oriented \fBcpio\fP archive format, the individual entry +information shall be in the order indicated and +described by the following table; see also the \fI\fP header. +.br +.sp +.ce 1 +\fBTable: Octet-Oriented cpio Archive Entry\fP +.TS C +center; l2 l2 l. +\fBHeader Field Name\fP \fBLength (in Octets)\fP \fBInterpreted as\fP +\fIc_magic\fP 6 Octal number +\fIc_dev\fP 6 Octal number +\fIc_ino\fP 6 Octal number +\fIc_mode\fP 6 Octal number +\fIc_uid\fP 6 Octal number +\fIc_gid\fP 6 Octal number +\fIc_nlink\fP 6 Octal number +\fIc_rdev\fP 6 Octal number +\fIc_mtime\fP 11 Octal number +\fIc_namesize\fP 6 Octal number +\fIc_filesize\fP 11 Octal number +\fBFilename Field Name\fP \fBLength\fP \fBInterpreted as\fP +\fIc_name\fP \fIc_namesize\fP Pathname string +\fBFile Data Field Name\fP \fBLength\fP \fBInterpreted as\fP +\fIc_filedata\fP \fIc_filesize\fP Data +.TE +.SS cpio Header +.LP +For each file in the archive, a header as defined previously shall +be written. The information in the header fields is written +as streams of the ISO/IEC\ 646:1991 standard characters interpreted +as octal numbers. The octal numbers shall be extended to +the necessary length by appending the ISO/IEC\ 646:1991 standard IRV +zeros at the most-significant-digit end of the number; the +result is written to the most-significant digit of the stream of octets +first. The fields shall be interpreted as follows: +.TP 7 +\fIc_magic\fP +Identify the archive as being a transportable archive by containing +the identifying value \fB"070707"\fP . +.TP 7 +\fIc_dev\fP,\ \fIc_ino\fP +Contains values that uniquely identify the file within the archive +(that is, no files contain the same pair of \fIc_dev\fP and +\fIc_ino\fP values unless they are links to the same file). The values +shall be determined in an unspecified manner. +.TP 7 +\fIc_mode\fP +Contains the file type and access permissions as defined in the following +table. +.br +.sp +.ce 1 +\fBTable: Values for cpio c_mode Field\fP +.TS C +center; l2 l2 l. +\fBFile Permissions Name\fP \fBValue\fP \fBIndicates\fP +C_IRUSR 000400 Read by owner +C_IWUSR 000200 Write by owner +C_IXUSR 000100 Execute by owner +C_IRGRP 000040 Read by group +C_IWGRP 000020 Write by group +C_IXGRP 000010 Execute by group +C_IROTH 000004 Read by others +C_IWOTH 000002 Write by others +C_IXOTH 000001 Execute by others +C_ISUID 004000 Set \fIuid\fP +C_ISGID 002000 Set \fIgid\fP +C_ISVTX 001000 Reserved +\fBFile Type Name\fP \fBValue\fP \fBIndicates\fP +C_ISDIR 040000 Directory +C_ISFIFO 010000 FIFO +C_ISREG 0100000 Regular file +C_ISLNK 0120000 Symbolic link +C_ISBLK 060000 Block special file +C_ISCHR 020000 Character special file +C_ISSOCK 0140000 Socket +C_ISCTG 0110000 Reserved +.TE +.LP +Directories, FIFOs, symbolic links, and regular files shall be supported +on a system conforming to this volume of +IEEE\ Std\ 1003.1-2001; additional values defined previously are reserved +for compatibility with existing systems. +Additional file types may be supported; however, such files should +not be written to archives intended to be transported to other +systems. +.TP 7 +\fIc_uid\fP +Contains the user ID of the owner. +.TP 7 +\fIc_gid\fP +Contains the group ID of the group. +.TP 7 +\fIc_nlink\fP +Contains the number of links referencing the file at the time the +archive was created. +.TP 7 +\fIc_rdev\fP +Contains implementation-defined information for character or block +special files. +.TP 7 +\fIc_mtime\fP +Contains the latest time of modification of the file at the time the +archive was created. +.TP 7 +\fIc_namesize\fP +Contains the length of the pathname, including the terminating NUL +character. +.TP 7 +\fIc_filesize\fP +Contains the length of the file in octets. This shall be the length +of the data section following the header structure. +.sp +.SS cpio Filename +.LP +The \fIc_name\fP field shall contain the pathname of the file. The +length of this field in octets is the value of +\fIc_namesize\fP. +.LP +If a filename is found on the medium that would create an invalid +pathname, it is implementation-defined whether the data from +the file is stored on the file hierarchy and under what name it is +stored. +.LP +All characters shall be represented in the ISO/IEC\ 646:1991 standard +IRV. For maximum portability between implementations, +names should be selected from characters represented by the portable +filename character set as octets with the most significant bit +zero. If an implementation supports the use of characters outside +the portable filename character set in names for files, users, +and groups, one or more implementation-defined encodings of these +characters shall be provided for interchange purposes. However, +the \fIpax\fP utility shall never create filenames on the local system +that cannot be accessed via the procedures described +previously in this volume of IEEE\ Std\ 1003.1-2001. If a filename +is found on the medium that would create an invalid +filename, it is implementation-defined whether the data from the file +is stored on the local file system and under what name it is +stored. The \fIpax\fP utility may choose to ignore these files as +long as it produces an error indicating that the file is being +ignored. +.SS cpio File Data +.LP +Following \fIc_name\fP, there shall be \fIc_filesize\fP octets of +data. Interpretation of such data occurs in a manner +dependent on the file. If \fIc_filesize\fP is zero, no data shall +be contained in \fIc_filedata\fP. +.LP +When restoring from an archive: +.IP " *" 3 +If the user does not have the appropriate privilege to create a file +of the specified type, \fIpax\fP shall ignore the entry +and write an error message to standard error. +.LP +.IP " *" 3 +Only regular files have data to be restored. Presuming a regular file +meets any selection criteria that might be imposed on the +format-reading utility by the user, such data shall be restored. +.LP +.IP " *" 3 +If a user does not have appropriate privilege to set a particular +mode flag, the flag shall be ignored. Some of the mode flags +in the archive format are not mentioned elsewhere in this volume of +IEEE\ Std\ 1003.1-2001. If the implementation does not +support those flags, they may be ignored. +.LP +.SS cpio Special Entries +.LP +FIFO special files, directories, and the trailer shall be recorded +with \fIc_filesize\fP equal to zero. For other special +files, \fIc_filesize\fP is unspecified by this volume of IEEE\ Std\ 1003.1-2001. +The header for the next file entry in the +archive shall be written directly after the last octet of the file +entry preceding it. A header denoting the filename +\fBTRAILER!!!\fP shall indicate the end of the archive; the contents +of octets in the last block of the archive following such a +header are undefined. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All files were processed successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If \fIpax\fP cannot create a file or a link when reading an archive +or cannot find a file when writing an archive, or cannot +preserve the user ID, group ID, or file mode when the \fB-p\fP option +is specified, a diagnostic message shall be written to +standard error and a non-zero exit status shall be returned, but processing +shall continue. In the case where \fIpax\fP cannot +create a link to a file, \fIpax\fP shall not, by default, create a +second copy of the file. +.LP +If the extraction of a file from an archive is prematurely terminated +by a signal or error, \fIpax\fP may have only partially +extracted the file or (if the \fB-n\fP option was not specified) may +have extracted a file of the same name as that specified by +the user, but which is not the file the user wanted. Additionally, +the file modes of extracted directories may have additional bits +from the S_IRWXU mask set as well as incorrect modification and access +times. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fB-p\fP (privileges) option was invented to reconcile differences +between historical \fItar\fP and \fIcpio\fP +implementations. In particular, the two utilities use \fB-m\fP in +diametrically opposed ways. The \fB-p\fP option also provides a +consistent means of extending the ways in which future file attributes +can be addressed, such as for enhanced security systems or +high-performance files. Although it may seem complex, there are really +two modes that are most commonly used: +.TP 7 +\fB-p\ e\fP +``Preserve everything". This would be used by the historical superuser, +someone with all the appropriate privileges, to +preserve all aspects of the files as they are recorded in the archive. +The \fBe\fP flag is the sum of \fBo\fP and \fBp\fP, and +other implementation-defined attributes. +.TP 7 +\fB-p\ p\fP +``Preserve" the file mode bits. This would be used by the user with +regular privileges who wished to preserve aspects of the +file other than the ownership. The file times are preserved by default, +but two other flags are offered to disable these and use +the time of extraction. +.sp +.LP +The one pathname per line format of standard input precludes pathnames +containing s. Although such pathnames +violate the portable filename guidelines, they may exist and their +presence may inhibit usage of \fIpax\fP within shell scripts. +This problem is inherited from historical archive programs. The problem +can be avoided by listing filename arguments on the command +line instead of on standard input. +.LP +It is almost certain that appropriate privileges are required for +\fIpax\fP to accomplish parts of this volume of +IEEE\ Std\ 1003.1-2001. Specifically, creating files of type block +special or character special, restoring file access +times unless the files are owned by the user (the \fB-t\fP option), +or preserving file owner, group, and mode (the \fB-p\fP +option) all probably require appropriate privileges. +.LP +In \fBread\fP mode, implementations are permitted to overwrite files +when the archive has multiple members with the same name. +This may fail if permissions on the first version of the file do not +permit it to be overwritten. +.LP +The \fBcpio\fP and \fBustar\fP formats can only support files up to +8589934592 bytes (8 * 2^30) in size. +.SH EXAMPLES +.LP +The following command: +.sp +.RS +.nf + +\fBpax -w -f /dev/rmt/1m . +\fP +.fi +.RE +.LP +copies the contents of the current directory to tape drive 1, medium +density (assuming historical System V device naming +procedures-the historical BSD device name would be \fB/dev/rmt9\fP). +.LP +The following commands: +.sp +.RS +.nf + +\fBmkdir\fP \fInewdir\fP\fBpax -rw\fP \fIolddir newdir\fP +.fi +.RE +.LP +copy the \fIolddir\fP directory hierarchy to \fInewdir\fP. +.sp +.RS +.nf + +\fBpax -r -s ',^//*usr//*,,' -f a.pax +\fP +.fi +.RE +.LP +reads the archive \fBa.pax\fP, with all files rooted in \fB/usr\fP +in the archive extracted relative to the current +directory. +.LP +Using the option: +.sp +.RS +.nf + +\fB-o listopt="%M %(atime)T %(size)D %(name)s" +\fP +.fi +.RE +.LP +overrides the default output description in Standard Output and instead +writes: +.sp +.RS +.nf + +\fB-rw-rw--- Jan 12 15:53 1492 /usr/foo/bar +\fP +.fi +.RE +.LP +Using the options: +.sp +.RS +.nf + +\fB-o listopt='%L\\t%(size)D\\n%.7' \\ +-o listopt='(name)s\\n%(ctime)T\\n%T' +\fP +.fi +.RE +.LP +overrides the default output description in Standard Output and instead +writes: +.sp +.RS +.nf + +\fB/usr/foo/bar -> /tmp 1492 +/usr/fo +Jan 12 1991 +Jan 31 15:53 +\fP +.fi +.RE +.SH RATIONALE +.LP +The \fIpax\fP utility was new for the ISO\ POSIX-2:1993 standard. +It represents a peaceful compromise between advocates of +the historical \fItar\fP and \fIcpio\fP utilities. +.LP +A fundamental difference between \fIcpio\fP and \fItar\fP was in the +way directories were treated. The \fIcpio\fP utility did +not treat directories differently from other files, and to select +a directory and its contents required that each file in the +hierarchy be explicitly specified. For \fItar\fP, a directory matched +every file in the file hierarchy it rooted. +.LP +The \fIpax\fP utility offers both interfaces; by default, directories +map into the file hierarchy they root. The \fB-d\fP +option causes \fIpax\fP to skip any file not explicitly referenced, +as \fIcpio\fP historically did. The \fItar\fP \fB-\fP +\fIstyle\fP behavior was chosen as the default because it was believed +that this was the more common usage and because \fItar\fP +is the more commonly available interface, as it was historically provided +on both System V and BSD implementations. +.LP +The data interchange format specification in this volume of IEEE\ Std\ 1003.1-2001 +requires that processes with +"appropriate privileges" shall always restore the ownership and permissions +of extracted files exactly as archived. If viewed +from the historic equivalence between superuser and "appropriate privileges", +there are two problems with this requirement. +First, users running as superusers may unknowingly set dangerous permissions +on extracted files. Second, it is needlessly limiting, +in that superusers cannot extract files and own them as superuser +unless the archive was created by the superuser. (It should be +noted that restoration of ownerships and permissions for the superuser, +by default, is historical practice in \fIcpio\fP, but not +in \fItar\fP.) In order to avoid these two problems, the \fIpax\fP +specification has an additional "privilege" mechanism, the +\fB-p\fP option. Only a \fIpax\fP invocation with the privileges needed, +and which has the \fB-p\fP option set using the +\fBe\fP specification character, has the "appropriate privilege" to +restore full ownership and permission information. +.LP +Note also that this volume of IEEE\ Std\ 1003.1-2001 requires that +the file ownership and access permissions shall be +set, on extraction, in the same fashion as the \fIcreat\fP() function +when provided with the +mode stored in the archive. This means that the file creation mask +of the user is applied to the file permissions. +.LP +Users should note that directories may be created by \fIpax\fP while +extracting files with permissions that are different from +those that existed at the time the archive was created. When extracting +sensitive information into a directory hierarchy that no +longer exists, users are encouraged to set their file creation mask +appropriately to protect these files during extraction. +.LP +The table of contents output is written to standard output to facilitate +pipeline processing. +.LP +An early proposal had hard links displaying for all pathnames. This +was removed because it complicates the output of the case +where \fB-v\fP is not specified and does not match historical \fIcpio\fP +usage. The hard-link information is available in the +\fB-v\fP display. +.LP +The description of the \fB-l\fP option allows implementations to make +hard links to symbolic links. +IEEE\ Std\ 1003.1-2001 does not specify any way to create a hard link +to a symbolic link, but many implementations provide +this capability as an extension. If there are hard links to symbolic +links when an archive is created, the implementation is +required to archive the hard link in the archive (unless \fB-H\fP +or \fB-L\fP is specified). When in \fBread\fP mode and in +\fBcopy\fP mode, implementations supporting hard links to symbolic +links should use them when appropriate. +.LP +The archive formats inherited from the POSIX.1-1990 standard have +certain restrictions that have been brought along from +historical usage. For example, there are restrictions on the length +of pathnames stored in the archive. When \fIpax\fP is used in +\fBcopy\fP( \fB-rw\fP) mode (copying directory hierarchies), the ability +to use extensions from the \fB-x\fP \fBpax\fP format +overcomes these restrictions. +.LP +The default \fIblocksize\fP value of 5120 bytes for \fIcpio\fP was +selected because it is one of the standard block-size +values for \fIcpio\fP, set when the \fB-B\fP option is specified. +(The other default block-size value for \fIcpio\fP is 512 +bytes, and this was considered to be too small.) The default block +value of 10240 bytes for \fItar\fP was selected because that is +the standard block-size value for BSD \fItar\fP. The maximum block +size of 32256 bytes (2**15-512 bytes) +is the largest multiple of 512 bytes that fits into a signed 16-bit +tape controller transfer register. There are known limitations +in some historical systems that would prevent larger blocks from being +accepted. Historical values were chosen to improve +compatibility with historical scripts using \fIdd\fP or similar utilities +to manipulate +archives. Also, default block sizes for any file type other than character +special file has been deleted from this volume of +IEEE\ Std\ 1003.1-2001 as unimportant and not likely to affect the +structure of the resulting archive. +.LP +Implementations are permitted to modify the block-size value based +on the archive format or the device to which the archive is +being written. This is to provide implementations with the opportunity +to take advantage of special types of devices, and it should +not be used without a great deal of consideration as it almost certainly +decreases archive portability. +.LP +The intended use of the \fB-n\fP option was to permit extraction of +one or more files from the archive without processing the +entire archive. This was viewed by the standard developers as offering +significant performance advantages over historical +implementations. The \fB-n\fP option in early proposals had three +effects; the first was to cause special characters in patterns +to not be treated specially. The second was to cause only the first +file that matched a pattern to be extracted. The third was to +cause \fIpax\fP to write a diagnostic message to standard error when +no file was found matching a specified pattern. Only the +second behavior is retained by this volume of IEEE\ Std\ 1003.1-2001, +for many reasons. First, it is in general not +acceptable for a single option to have multiple effects. Second, the +ability to make pattern matching characters act as normal +characters is useful for parts of \fIpax\fP other than file extraction. +Third, a finer degree of control over the special +characters is useful because users may wish to normalize only a single +special character in a single filename. Fourth, given a more +general escape mechanism, the previous behavior of the \fB-n\fP option +can be easily obtained using the \fB-s\fP option or a \fIsed\fP script. +Finally, writing a diagnostic message when a pattern specified by +the user is +unmatched by any file is useful behavior in all cases. +.LP +In this version, the \fB-n\fP was removed from the \fBcopy\fP mode +synopsis of \fIpax\fP; it is inapplicable because there +are no pattern operands specified in this mode. +.LP +There is another method than \fIpax\fP for copying subtrees in IEEE\ Std\ 1003.1-2001 +described as part of the \fIcp\fP utility. Both methods are historical +practice: \fIcp\fP +provides a simpler, more intuitive interface, while \fIpax\fP offers +a finer granularity of control. Each provides additional +functionality to the other; in particular, \fIpax\fP maintains the +hard-link structure of the hierarchy while \fIcp\fP does not. It is +the intention of the standard developers that the results be similar +(using +appropriate option combinations in both utilities). The results are +not required to be identical; there seemed insufficient gain to +applications to balance the difficulty of implementations having to +guarantee that the results would be exactly identical. +.LP +A single archive may span more than one file. It is suggested that +implementations provide informative messages to the user on +standard error whenever the archive file is changed. +.LP +The \fB-d\fP option (do not create intermediate directories not listed +in the archive) found in early proposals was originally +provided as a complement to the historic \fB-d\fP option of \fIcpio\fP. +It has been deleted. +.LP +The \fB-s\fP option in early proposals specified a subset of the substitution +command from the \fIed\fP utility. As there was no reason for only +a subset to be supported, the \fB-s\fP option is now +compatible with the current \fIed\fP specification. Since the delimiter +can be any non-null +character, the following usage with single spaces is valid: +.sp +.RS +.nf + +\fBpax -s " foo bar " ... +\fP +.fi +.RE +.LP +The \fB-t\fP description is worded so as to note that this may cause +the access time update caused by some other activity +(which occurs while the file is being read) to be overwritten. +.LP +The default behavior of \fIpax\fP with regard to file modification +times is the same as historical implementations of +\fItar\fP. It is not the historical behavior of \fIcpio\fP. +.LP +Because the \fB-i\fP option uses \fB/dev/tty\fP, utilities without +a controlling terminal are not able to use this option. +.LP +The \fB-y\fP option, found in early proposals, has been deleted because +a line containing a single period for the \fB-i\fP +option has equivalent functionality. The special lines for the \fB-i\fP +option (a single period and the empty line) are historical +practice in \fIcpio\fP. +.LP +In early drafts, a \fB-e\fP \fIcharmap\fP option was included to increase +portability of files between systems using different +coded character sets. This option was omitted because it was apparent +that consensus could not be formed for it. In this version, +the use of UTF-8 should be an adequate substitute. +.LP +The \fB-k\fP option was added to address international concerns about +the dangers involved in the character set transformations +of \fB-e\fP (if the target character set were different from the source, +the filenames might be transformed into names matching +existing files) and also was made more general to protect files transferred +between file systems with different {NAME_MAX} values +(truncating a filename on a smaller system might also inadvertently +overwrite existing files). As stated, it prevents any +overwriting, even if the target file is older than the source. This +version adds more granularity of options to solve this problem +by introducing the \fB-o\fP \fBinvalid=\fP option-specifically the +UTF-8 action. (Note that an existing file that is named with a +UTF-8 encoding is still subject to overwriting in this case. The \fB-k\fP +option closes that loophole.) +.LP +Some of the file characteristics referenced in this volume of IEEE\ Std\ 1003.1-2001 +might not be supported by some +archive formats. For example, neither the \fBtar\fP nor \fBcpio\fP +formats contain the file access time. For this reason, the +\fBe\fP specification character has been provided, intended to cause +all file characteristics specified in the archive to be +retained. +.LP +It is required that extracted directories, by default, have their +access and modification times and permissions set to the +values specified in the archive. This has obvious problems in that +the directories are almost certainly modified after being +extracted and that directory permissions may not permit file creation. +One possible solution is to create directories with the mode +specified in the archive, as modified by the \fIumask\fP of the user, +with sufficient +permissions to allow file creation. After all files have been extracted, +\fIpax\fP would then reset the access and modification +times and permissions as necessary. +.LP +The list-mode formatting description borrows heavily from the one +defined by the \fIprintf\fP utility. However, since there is no separate +operand list to get conversion arguments, +the format was extended to allow specifying the name of the conversion +argument as part of the conversion specification. +.LP +The \fBT\fP conversion specifier allows time fields to be displayed +in any of the date formats. Unlike the \fIls\fP utility, \fIpax\fP +does not adjust the format when the date is less than six months in +the +past. This makes parsing the output more predictable. +.LP +The \fBD\fP conversion specifier handles the ability to display the +major/minor or file size, as with \fIls\fP, by using \fB%-8(\fP\fIsize\fP\fB)D\fP. +.LP +The \fBL\fP conversion specifier handles the \fIls\fP display for +symbolic links. +.LP +Conversion specifiers were added to generate existing known types +used for \fIls\fP. +.SS pax Interchange Format +.LP +The new POSIX data interchange format was developed primarily to satisfy +international concerns that the \fBustar\fP and +\fBcpio\fP formats did not provide for file, user, and group names +encoded in characters outside a subset of the +ISO/IEC\ 646:1991 standard. The standard developers realized that +this new POSIX data interchange format should be very +extensible because there were other requirements they foresaw in the +near future: +.IP " *" 3 +Support international character encodings and locale information +.LP +.IP " *" 3 +Support security information (ACLs, and so on) +.LP +.IP " *" 3 +Support future file types, such as realtime or contiguous files +.LP +.IP " *" 3 +Include data areas for implementation use +.LP +.IP " *" 3 +Support systems with words larger than 32 bits and timers with subsecond +granularity +.LP +.LP +The following were not goals for this format because these are better +handled by separate utilities or are inappropriate for a +portable format: +.IP " *" 3 +Encryption +.LP +.IP " *" 3 +Compression +.LP +.IP " *" 3 +Data translation between locales and codesets +.LP +.IP " *" 3 +\fIinode\fP storage +.LP +.LP +The format chosen to support the goals is an extension of the \fBustar\fP +format. Of the two formats previously available, only +the \fBustar\fP format was selected for extensions because: +.IP " *" 3 +It was easier to extend in an upwards-compatible way. It offered version +flags and header block type fields with room for future +standardization. The \fBcpio\fP format, while possessing a more flexible +file naming methodology, could not be extended without +breaking some theoretical implementation or using a dummy filename +that could be a legitimate filename. +.LP +.IP " *" 3 +Industry experience since the original " \fItar\fP wars" fought in +developing the ISO\ POSIX-1 standard has clearly been +in favor of the \fBustar\fP format, which is generally the default +output format selected for \fIpax\fP implementations on new +systems. +.LP +.LP +The new format was designed with one additional goal in mind: reasonable +behavior when an older \fItar\fP or \fIpax\fP utility +happened to read an archive. Since the POSIX.1-1990 standard mandated +that a "format-reading utility" had to treat unrecognized +\fItypeflag\fP values as regular files, this allowed the format to +include all the extended information in a pseudo-regular file +that preceded each real file. An option is given that allows the archive +creator to set up reasonable names for these files on the +older systems. Also, the normative text suggests that reasonable file +access values be used for this \fBustar\fP header block. +Making these header files inaccessible for convenient reading and +deleting would not be reasonable. File permissions of 600 or 700 +are suggested. +.LP +The \fBustar\fP \fItypeflag\fP field was used to accommodate the additional +functionality of the new format rather than magic +or version because the POSIX.1-1990 standard (and, by reference, the +previous version of \fIpax\fP), mandated the behavior of the +format-reading utility when it encountered an unknown \fItypeflag\fP, +but was silent about the other two fields. +.LP +Early proposals of the first revision to IEEE\ Std\ 1003.1-2001 contained +a proposed archive format that was based on +compatibility with the standard for tape files (ISO\ 1001, similar +to the format used historically on many mainframes and +minicomputers). This format was overly complex and required considerable +overhead in volume and header records. Furthermore, the +standard developers felt that it would not be acceptable to the community +of POSIX developers, so it was later changed to be a +format more closely related to historical practice on POSIX systems. +.LP +The prefix and name split of pathnames in \fBustar\fP was replaced +by the single path extended header record for +simplicity. +.LP +The concept of a global extended header ( \fItypeflag\fP \fBg\fP) +was controversial. If this were applied to an archive being +recorded on magnetic tape, a few unreadable blocks at the beginning +of the tape could be a serious problem; a utility attempting to +extract as many files as possible from a damaged archive could lose +a large percentage of file header information in this case. +However, if the archive were on a reliable medium, such as a CD-ROM, +the global extended header offers considerable potential size +reductions by eliminating redundant information. Thus, the text warns +against using the global method for unreliable media and +provides a method for implanting global information in the extended +header for each file, rather than in the \fItypeflag\fP +\fBg\fP records. +.LP +No facility for data translation or filtering on a per-file basis +is included because the standard developers could not invent +an interface that would allow this in an efficient manner. If a filter, +such as encryption or compression, is to be applied to all +the files, it is more efficient to apply the filter to the entire +archive as a single file. The standard developers considered +interfaces that would invoke a shell script for each file going into +or out of the archive, but the system overhead in this +approach was considered to be too high. +.LP +One such approach would be to have \fBfilter=\fP records that give +a pathname for an executable. When the program is invoked, +the file and archive would be open for standard input/output and all +the header fields would be available as environment variables +or command-line arguments. The standard developers did discuss such +schemes, but they were omitted from +IEEE\ Std\ 1003.1-2001 due to concerns about excessive overhead. Also, +the program itself would need to be in the archive +if it were to be used portably. +.LP +There is currently no portable means of identifying the character +set(s) used for a file in the file system. Therefore, +\fIpax\fP has not been given a mechanism to generate charset records +automatically. The only portable means of doing this is for +the user to write the archive using the \fB-o\fP \fBcharset=\fP \fIstring\fP +command line option. This assumes that all of the +files in the archive use the same encoding. The "implementation-defined" +text is included to allow for a system that can identify +the encodings used for each of its files. +.LP +The table of standards that accompanies the charset record description +is acknowledged to be very limited. Only a limited number +of character set standards is reasonable for maximal interchange. +Any character set is, of course, possible by prior agreement. It +was suggested that EBCDIC be listed, but it was omitted because it +is not defined by a formal standard. Formal standards, and then +only those with reasonably large followings, can be included here, +simply as a matter of practicality. The <\fIvalue\fP>s +represent names of officially registered character sets in the format +required by the ISO\ 2375:1985 standard. +.LP +The normal comma or -separated list rules are not followed +in the case of keyword options to allow ease of argument +parsing for \fIgetopts\fP. +.LP +Further information on character encodings is in pax Archive Character +Set Encoding/Decoding +\&. +.LP +The standard developers have reserved keyword name space for vendor +extensions. It is suggested that the format to be used +is: +.sp +.RS +.nf + +\fIVENDOR.keyword\fP +.fi +.RE +.LP +where \fIVENDOR\fP is the name of the vendor or organization in all +uppercase letters. It is further suggested that the keyword +following the period be named differently than any of the standard +keywords so that it could be used for future standardization, if +appropriate, by omitting the \fIVENDOR\fP prefix. +.LP +The <\fIlength\fP> field in the extended header record was included +to make it simpler to step through the records, even +if a record contains an unknown format (to a particular \fIpax\fP) +with complex interactions of special characters. It also +provides a minor integrity checkpoint within the records to aid a +program attempting to recover files from a damaged archive. +.LP +There are no extended header versions of the \fIdevmajor\fP and \fIdevminor\fP +fields because the unspecified format +\fBustar\fP header field should be sufficient. If they are not, vendor-specific +extended keywords (such as \fIVENDOR.devmajor\fP) +should be used. +.LP +Device and \fIi\fP-number labeling of files was not adopted from \fIcpio\fP; +files are interchanged strictly on a symbolic +name basis, as in \fBustar\fP. +.LP +Just as with the \fBustar\fP format descriptions, the new format makes +no special arrangements for multi-volume archives. Each +of the \fIpax\fP archive types is assumed to be inside a single POSIX +file and splitting that file over multiple volumes +(diskettes, tape cartridges, and so on), processing their labels, +and mounting each in the proper sequence are considered to be +implementation details that cannot be described portably. +.LP +The \fBpax\fP format is intended for interchange, not only for backup +on a single (family of) systems. It is not as densely +packed as might be possible for backup: +.IP " *" 3 +It contains information as coded characters that could be coded in +binary. +.LP +.IP " *" 3 +It identifies extended records with name fields that could be omitted +in favor of a fixed-field layout. +.LP +.IP " *" 3 +It translates names into a portable character set and identifies locale-related +information, both of which are probably +unnecessary for backup. +.LP +.LP +The requirements on restoring from an archive are slightly different +from the historical wording, allowing for non-monolithic +privilege to bring forward as much as possible. In particular, attributes +such as "high performance file" might be broadly but +not universally granted while set-user-ID or \fIchown\fP() might be +much more restricted. +There is no implication in IEEE\ Std\ 1003.1-2001 that the security +information be honored after it is restored to the file +hierarchy, in spite of what might be improperly inferred by the silence +on that topic. That is a topic for another standard. +.LP +Links are recorded in the fashion described here because a link can +be to any file type. It is desirable in general to be able +to restore part of an archive selectively and restore all of those +files completely. If the data is not associated with each link, +it is not possible to do this. However, the data associated with a +file can be large, and when selective restoration is not needed, +this can be a significant burden. The archive is structured so that +files that have no associated data can always be restored by +the name of any link name of any link, and the user may choose whether +data is recorded with each instance of a file that contains +data. The format permits mixing of both types of links in a single +archive; this can be done for special needs, and \fIpax\fP is +expected to interpret such archives on input properly, despite the +fact that there is no \fIpax\fP option that would force this +mixed case on output. (When \fB-o\fP \fBlinkdata\fP is used, the output +must contain the duplicate data, but the implementation +is free to include it or omit it when \fB-o\fP \fBlinkdata\fP is not +used.) +.LP +The time values are included as extended header records for those +implementations needing more than the eleven octal digits +allowed by the \fBustar\fP format. Portable file timestamps cannot +be negative. If \fIpax\fP encounters a file with a negative +timestamp in \fBcopy\fP or \fBwrite\fP mode, it can reject the file, +substitute a non-negative timestamp, or generate a +non-portable timestamp with a leading \fB'-'\fP . Even though some +implementations can support finer file-time granularities +than seconds, the normative text requires support only for seconds +since the Epoch because the ISO\ POSIX-1 standard states +them that way. The \fBustar\fP format includes only \fImtime\fP; the +new format adds \fIatime\fP and \fIctime\fP for symmetry. +The \fIatime\fP access time restored to the file system will be affected +by the \fB-p\fP \fBa\fP and \fB-p\fP \fBe\fP options. +The \fIctime\fP creation time (actually \fIinode\fP modification time) +is described with "appropriate privilege" so that it can +be ignored when writing to the file system. POSIX does not provide +a portable means to change file creation time. Nothing is +intended to prevent a non-portable implementation of \fIpax\fP from +restoring the value. +.LP +The \fIgid\fP, \fIsize\fP, and \fIuid\fP extended header records were +included to allow expansion beyond the sizes specified +in the regular \fItar\fP header. New file system architectures are +emerging that will exhaust the 12-digit size field. There are +probably not many systems requiring more than 8 digits for user and +group IDs, but the extended header values were included for +completeness, allowing overrides for all of the decimal values in +the \fItar\fP header. +.LP +The standard developers intended to describe the effective results +of \fIpax\fP with regard to file ownerships and permissions; +implementations are not restricted in timing or sequencing the restoration +of such, provided the results are as specified. +.LP +Much of the text describing the extended headers refers to use in +" \fBwrite\fP or \fBcopy\fP modes". The \fBcopy\fP mode +references are due to the normative text: "The effect of the copy +shall be as if the copied files were written to an archive file +and then subsequently extracted ...". There is certainly no way to +test whether \fIpax\fP is actually generating the extended +headers in \fBcopy\fP mode, but the effects must be as if it had. +.SS pax Archive Character Set Encoding/Decoding +.LP +There is a need to exchange archives of files between systems of different +native codesets. Filenames, group names, and user +names must be preserved to the fullest extent possible when an archive +is read on the receiving platform. Translation of the +contents of files is not within the scope of the \fIpax\fP utility. +.LP +There will also be the need to represent characters that are not available +on the receiving platform. These unsupported +characters cannot be automatically folded to the local set of characters +due to the chance of collisions. This could result in +overwriting previous extracted files from the archive or pre-existing +files on the system. +.LP +For these reasons, the codeset used to represent characters within +the extended header records of the \fIpax\fP archive must be +sufficiently rich to handle all commonly used character sets. The +fields requiring translation include, at a minimum, filenames, +user names, group names, and link pathnames. Implementations may wish +to have localized extended keywords that use non-portable +characters. +.LP +The standard developers considered the following options: +.IP " *" 3 +The archive creator specifies the well-defined name of the source +codeset. The receiver must then recognize the codeset name and +perform the appropriate translations to the destination codeset. +.LP +.IP " *" 3 +The archive creator includes within the archive the character mapping +table for the source codeset used to encode extended +header records. The receiver must then read the character mapping +table and perform the appropriate translations to the destination +codeset. +.LP +.IP " *" 3 +The archive creator translates the extended header records in the +source codeset into a canonical form. The receiver must then +perform the appropriate translations to the destination codeset. +.LP +.LP +The approach that incorporates the name of the source codeset poses +the problem of codeset name registration, and makes the +archive useless to \fIpax\fP archive decoders that do not recognize +that codeset. +.LP +Because parts of an archive may be corrupted, the standard developers +felt that including the character map of the source +codeset was too fragile. The loss of this one key component could +result in making the entire archive useless. (The difference +between this and the global extended header decision was that the +latter has a workaround-duplicating extended header records on +unreliable media-but this would be too burdensome for large character +set maps.) +.LP +Both of the above approaches also put an undue burden on the \fIpax\fP +archive receiver to handle the cross-product of all +source and destination codesets. +.LP +To simplify the translation from the source codeset to the canonical +form and from the canonical form to the destination +codeset, the standard developers decided that the internal representation +should be a stateless encoding. A stateless encoding is +one where each codepoint has the same meaning, without regard to the +decoder being in a specific state. An example of a stateful +encoding would be the Japanese Shift-JIS; an example of a stateless +encoding would be the ISO/IEC\ 646:1991 standard +(equivalent to 7-bit ASCII). +.LP +For these reasons, the standard developers decided to adopt a canonical +format for the representation of file information +strings. The obvious, well-endorsed candidate is the ISO/IEC\ 10646-1:2000 +standard (based in part on Unicode), which can be +used to represent the characters of virtually all standardized character +sets. The standard developers initially agreed upon using +UCS2 (16-bit Unicode) as the internal representation. This repertoire +of characters provides a sufficiently rich set to represent +all commonly-used codesets. +.LP +However, the standard developers found that the 16-bit Unicode representation +had some problems. It forced the issue of +standardizing byte ordering. The 2-byte length of each character made +the extended header records twice as long for the case of +strings coded entirely from historical 7-bit ASCII. For these reasons, +the standard developers chose the UTF-8 defined in the +ISO/IEC\ 10646-1:2000 standard. This multi-byte representation encodes +UCS2 or UCS4 characters reliably and deterministically, +eliminating the need for a canonical byte ordering. In addition, NUL +octets and other characters possibly confusing to POSIX file +systems do not appear, except to represent themselves. It was realized +that certain national codesets take up more space after the +encoding, due to their placement within the UCS range; it was felt +that the usefulness of the encoding of the names outweighs the +disadvantage of size increase for file, user, and group names. +.LP +The encoding of UTF-8 is as follows: +.sp +.RS +.nf + +\fBUCS4 Hex Encoding UTF-8 Binary Encoding +.sp + +00000000-0000007F 0xxxxxxx +00000080-000007FF 110xxxxx 10xxxxxx +00000800-0000FFFF 1110xxxx 10xxxxxx 10xxxxxx +00010000-001FFFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx +00200000-03FFFFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx +04000000-7FFFFFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx +\fP +.fi +.RE +.LP +where each \fB'x'\fP represents a bit value from the character being +translated. +.SS ustar Interchange Format +.LP +The description of the \fBustar\fP format reflects numerous enhancements +over pre-1988 versions of the historical \fItar\fP +utility. The goal of these changes was not only to provide the functional +enhancements desired, but also to retain compatibility +between new and old versions. This compatibility has been retained. +Archives written using the old archive format are compatible +with the new format. +.LP +Implementors should be aware that the previous file format did not +include a mechanism to archive directory type files. For this +reason, the convention of using a filename ending with slash was adopted +to specify a directory on the archive. +.LP +The total size of the \fIname\fP and \fIprefix\fP fields have been +set to meet the minimum requirements for {PATH_MAX}. If a +pathname will fit within the \fIname\fP field, it is recommended that +the pathname be stored there without the use of the +\fIprefix\fP field. Although the name field is known to be too small +to contain {PATH_MAX} characters, the value was not changed +in this version of the archive file format to retain backwards-compatibility, +and instead the prefix was introduced. Also, because +of the earlier version of the format, there is no way to remove the +restriction on the \fIlinkname\fP field being limited in size +to just that of the \fIname\fP field. +.LP +The \fIsize\fP field is required to be meaningful in all implementation +extensions, although it could be zero. This is required +so that the data blocks can always be properly counted. +.LP +It is suggested that if device special files need to be represented +that cannot be represented in the standard format, that one +of the extension types ( \fBA\fP- \fBZ\fP) be used, and that the additional +information for the special file be represented as +data and be reflected in the \fIsize\fP field. +.LP +Attempting to restore a special file type, where it is converted to +ordinary data and conflicts with an existing filename, need +not be specially detected by the utility. If run as an ordinary user, +\fIpax\fP should not be able to overwrite the entries in, +for example, \fB/dev\fP in any case (whether the file is converted +to another type or not). If run as a privileged user, it should +be able to do so, and it would be considered a bug if it did not. +The same is true of ordinary data files and similarly named +special files; it is impossible to anticipate the needs of the user +(who could really intend to overwrite the file), so the +behavior should be predictable (and thus regular) and rely on the +protection system as required. +.LP +The value 7 in the \fItypeflag\fP field is intended to define how +contiguous files can be stored in a \fBustar\fP archive. +IEEE\ Std\ 1003.1-2001 does not require the contiguous file extension, +but does define a standard way of archiving such +files so that all conforming systems can interpret these file types +in a meaningful and consistent manner. On a system that does +not support extended file types, the \fIpax\fP utility should do the +best it can with the file and go on to the next. +.LP +The file protection modes are those conventionally used by the \fIls\fP +utility. This is +extended beyond the usage in the ISO\ POSIX-2 standard to support +the "shared text" or "sticky" bit. It is intended that +the conformance document should not document anything beyond the existence +of and support of such a mode. Further extensions are +expected to these bits, particularly with overloading the set-user-ID +and set-group-ID flags. +.SS cpio Interchange Format +.LP +The reference to appropriate privilege in the \fBcpio\fP format refers +to an error on standard output; the \fBustar\fP format +does not make comparable statements. +.LP +The model for this format was the historical System V \fIcpio\fP \fB-c\fP +data interchange format. This model documents the +portable version of the \fBcpio\fP format and not the binary version. +It has the flexibility to transfer data of any type +described within IEEE\ Std\ 1003.1-2001, yet is extensible to transfer +data types specific to extensions beyond +IEEE\ Std\ 1003.1-2001 (for example, contiguous files). Because it +describes existing practice, there is no question of +maintaining upwards-compatibility. +.SS cpio Header +.LP +There has been some concern that the size of the \fIc_ino\fP field +of the header is too small to handle those systems that have +very large \fIinode\fP numbers. However, the \fIc_ino\fP field in +the header is used strictly as a hard-link resolution mechanism +for archives. It is not necessarily the same value as the \fIinode\fP +number of the file in the location from which that file is +extracted. +.LP +The name \fIc_magic\fP is based on historical usage. +.SS cpio Filename +.LP +For most historical implementations of the \fIcpio\fP utility, {PATH_MAX} +octets can be used to describe the pathname without +the addition of any other header fields (the NUL character would be +included in this count). {PATH_MAX} is the minimum value for +pathname size, documented as 256 bytes. However, an implementation +may use \fIc_namesize\fP to determine the exact length of the +pathname. With the current description of the \fI\fP header, +this pathname +size can be as large as a number that is described in six octal digits. +.LP +Two values are documented under the \fIc_mode\fP field values to provide +for extensibility for known file types: +.TP 7 +\fB0110\ 000\fP +Reserved for contiguous files. The implementation may treat the rest +of the information for this archive like a regular file. +If this file type is undefined, the implementation may create the +file as a regular file. +.sp +.LP +This provides for extensibility of the \fBcpio\fP format while allowing +for the ability to read old archives. Files of an +unknown type may be read as "regular files" on some implementations. +On a system that does not support extended file types, the +\fIpax\fP utility should do the best it can with the file and go on +to the next. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP , \fIcp\fP , \fIed\fP , \fIgetopts\fP +, \fIls\fP , \fIprintf\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIchown\fP(), \fIcreat\fP(), \fImkdir\fP(), \fImkfifo\fP(), \fIstat\fP(), +\fIutime\fP(), \fIwrite\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/pr.1p b/man1p/pr.1p new file mode 100644 index 000000000..0adef1175 --- /dev/null +++ b/man1p/pr.1p @@ -0,0 +1,414 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pr +.SH NAME +pr \- print files +.SH SYNOPSIS +.LP +\fBpr\fP +\fB[\fP\fB+\fP\fIpage\fP\fB][\fP\fB-\fP\fIcolumn\fP\fB][\fP\fB-adFmrt\fP\fB][\fP\fB-e\fP\fB[\fP\fIchar\fP\fB][\fP\fI +gap\fP\fB]][\fP\fB-h\fP \fIheader\fP\fB][\fP\fB-i\fP\fB[\fP\fIchar\fP\fB][\fP\fIgap\fP\fB]] +.sp +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-l\fP +\fIlines\fP\fB][\fP\fB-n\fP\fB[\fP\fIchar\fP\fB][\fP\fIwidth\fP\fB]][\fP\fB-o\fP +\fIoffset\fP\fB][\fP\fB-s\fP\fB[\fP\fIchar\fP\fB]][\fP\fB-w\fP \fIwidth\fP\fB][\fP\fB-fp\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fIfile\fP\fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIpr\fP utility is a printing and pagination filter. If multiple +input files are specified, each shall be read, formatted, +and written to standard output. By default, the input shall be separated +into 66-line pages, each with: +.IP " *" 3 +A 5-line header that includes the page number, date, time, and the +pathname of the file +.LP +.IP " *" 3 +A 5-line trailer consisting of blank lines +.LP +.LP +If standard output is associated with a terminal, diagnostic messages +shall be deferred until the \fIpr\fP utility has +completed processing. +.LP +When options specifying multi-column output are specified, output +text columns shall be of equal width; input lines that do not +fit into a text column shall be truncated. By default, text columns +shall be separated with at least one . +.SH OPTIONS +.LP +The \fIpr\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that: the \fIpage\fP option has a +\fB'+'\fP delimiter; \fIpage\fP and \fIcolumn\fP can be multi-digit +numbers; some of the option-arguments are optional; and +some of the option-arguments cannot be specified as separate arguments +from the preceding option letter. In particular, the +\fB-s\fP option does not allow the option letter to be separated from +its argument, and the options \fB-e\fP, \fB-i\fP, and +\fB-n\fP require that both arguments, if present, not be separated +from the option letter. +.LP +The following options shall be supported. In the following option +descriptions, \fIcolumn\fP, \fIlines\fP, \fIoffset\fP, +\fIpage\fP, and \fIwidth\fP are positive decimal integers; \fIgap\fP +is a non-negative decimal integer. +.TP 7 +\fB+\fP\fIpage\fP +Begin output at page number \fIpage\fP of the formatted input. +.TP 7 +\fB-\fP\fIcolumn\fP +Produce multi-column output that is arranged in \fIcolumn\fP columns +(the default shall be 1) and is written down each column +in the order in which the text is received from the input file. This +option should not be used with \fB-m\fP. The options +\fB-e\fP and \fB-i\fP shall be assumed for multiple text-column output. +Whether or not text columns are produced with identical +vertical lengths is unspecified, but a text column shall never exceed +the length of the page (see the \fB-l\fP option). When used +with \fB-t\fP, use the minimum number of lines to write the output. +.TP 7 +\fB-a\fP +Modify the effect of the \fB-\fP \fIcolumn\fP option so that the columns +are filled across the page in a round-robin order +(for example, when \fIcolumn\fP is 2, the first input line heads column +1, the second heads column 2, the third is the second line +in column 1, and so on). +.TP 7 +\fB-d\fP +Produce output that is double-spaced; append an extra following +every found in the input. +.TP 7 +\fB-e[\fP\fIchar\fP\fB][\fP\fIgap\fP\fB]\fP +.sp +Expand each input to the next greater column position specified +by the formula \fIn\fP* \fIgap\fP+1, where \fIn\fP +is an integer > 0. If \fIgap\fP is zero or is omitted, it shall default +to 8. All s in the input shall be expanded +into the appropriate number of s. If any non-digit character, +\fIchar\fP, is specified, it shall be used as the input +. +.TP 7 +\fB-f\fP +Use a for new pages, instead of the default behavior that +uses a sequence of s. Pause before +beginning the first page if the standard output is associated with +a terminal. +.TP 7 +\fB-F\fP +Use a for new pages, instead of the default behavior that +uses a sequence of s. +.TP 7 +\fB-h\ \fP \fIheader\fP +Use the string \fIheader\fP to replace the contents of the \fIfile\fP +operand in the page header. +.TP 7 +\fB-i[\fP\fIchar\fP\fB][\fP\fIgap\fP\fB]\fP +In output, replace multiple s with s wherever two or more +adjacent s reach column +positions \fIgap\fP+1, 2* \fIgap\fP+1, 3* \fIgap\fP+1, and so on. +If \fIgap\fP is zero or is omitted, default tab settings at +every eighth column position shall be assumed. If any non-digit character, +\fIchar\fP, is specified, it shall be used as the +output . +.TP 7 +\fB-l\ \fP \fIlines\fP +Override the 66-line default and reset the page length to \fIlines\fP. +If \fIlines\fP is not greater than the sum of both the +header and trailer depths (in lines), the \fIpr\fP utility shall suppress +both the header and trailer, as if the \fB-t\fP option +were in effect. +.TP 7 +\fB-m\fP +Merge files. Standard output shall be formatted so the \fIpr\fP utility +writes one line from each file specified by a +\fIfile\fP operand, side by side into text columns of equal fixed +widths, in terms of the number of column positions. +Implementations shall support merging of at least nine \fIfile\fP +operands. +.TP 7 +\fB-n[\fP\fIchar\fP\fB][\fP\fIwidth\fP\fB]\fP +.sp +Provide \fIwidth\fP-digit line numbering (default for \fIwidth\fP +shall be 5). The number shall occupy the first \fIwidth\fP +column positions of each text column of default output or each line +of \fB-m\fP output. If \fIchar\fP (any non-digit character) +is given, it shall be appended to the line number to separate it from +whatever follows (default for \fIchar\fP is a +). +.TP 7 +\fB-o\ \fP \fIoffset\fP +Each line of output shall be preceded by offset s. If the \fB-o\fP +option is not specified, the default offset +shall be zero. The space taken is in addition to the output line width +(see the \fB-w\fP option below). +.TP 7 +\fB-p\fP +Pause before beginning each page if the standard output is directed +to a terminal ( \fIpr\fP shall write an to +standard error and wait for a to be read on \fB/dev/tty\fP). +.TP 7 +\fB-r\fP +Write no diagnostic reports on failure to open files. +.TP 7 +\fB-s[\fP\fIchar\fP\fB]\fP +Separate text columns by the single character \fIchar\fP instead of +by the appropriate number of s (default for +\fIchar\fP shall be ). +.TP 7 +\fB-t\fP +Write neither the five-line identifying header nor the five-line trailer +usually supplied for each page. Quit writing after the +last line of each file without spacing to the end of the page. +.TP 7 +\fB-w\ \fP \fIwidth\fP +Set the width of the line to \fIwidth\fP column positions for multiple +text-column output only. If the \fB-w\fP option is not +specified and the \fB-s\fP option is not specified, the default width +shall be 72. If the \fB-w\fP option is not specified and +the \fB-s\fP option is specified, the default width shall be 512. +.LP +For single column output, input lines shall not be truncated. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a file to be written. If no \fIfile\fP operands are +specified, or if a \fIfile\fP operand is \fB'-'\fP , the +standard input shall be used. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified, or if a \fIfile\fP operand is \fB'-'\fP . +See the INPUT FILES section. +.SH INPUT FILES +.LP +The input files shall be text files. +.LP +The file \fB/dev/tty\fP shall be used to read responses required by +the \fB-p\fP option. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIpr\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and +which characters are defined as printable (character class +\fBprint\fP). Non-printable characters are still written to standard +output, but are not counted for the purpose for column-width +and line-length calculations. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILC_TIME\fP +Determine the format of the date and time for use in writing header +lines. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITZ\fP +Determine the timezone used to calculate date and time strings written +in header lines. If \fITZ\fP is unset or null, an +unspecified default timezone shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +If \fIpr\fP receives an interrupt while writing to a terminal, it +shall flush all accumulated error messages to the screen +before terminating. +.SH STDOUT +.LP +The \fIpr\fP utility output shall be a paginated version of the original +file (or files). This pagination shall be accomplished +using either s or a sequence of s, as controlled +by the \fB-F\fP \ or \fB-f\fP +option. Page headers shall be generated unless the \fB-t\fP option +is specified. The page headers shall be of the form: +.sp +.RS +.nf + +\fB"\\n\\n%s %s Page %d\\n\\n\\n", <\fP\fIoutput of date\fP\fB>, <\fP\fIfile\fP\fB>, <\fP\fIpage number\fP\fB> +\fP +.fi +.RE +.LP +In the POSIX locale, the <\fIoutput\ of\ date\fP> field, representing +the date and time of last modification of +the input file (or the current date and time if the input file is +standard input), shall be equivalent to the output of the +following command as it would appear if executed at the given time: +.sp +.RS +.nf + +\fBdate "+%b %e %H:%M %Y" +\fP +.fi +.RE +.LP +without the trailing , if the page being written is from +standard input. If the page being written is not from +standard input, in the POSIX locale, the same format shall be used, +but the time used shall be the modification time of the file +corresponding to \fIfile\fP instead of the current time. When the +\fILC_TIME\fP locale category is not set to the POSIX locale, a +different format and order of presentation of this field may be used. +.LP +If the standard input is used instead of a \fIfile\fP operand, the +<\fIfile\fP> field shall be replaced by a null +string. +.LP +If the \fB-h\fP option is specified, the <\fIfile\fP> field shall +be replaced by the \fIheader\fP argument. +.SH STDERR +.LP +The standard error shall be used for diagnostic messages and for alerting +the terminal when \fB-p\fP is specified. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.IP " 1." 4 +Print a numbered list of all files in the current directory: +.sp +.RS +.nf + +\fBls -a | pr -n -h "Files in $(pwd)." +\fP +.fi +.RE +.LP +.IP " 2." 4 +Print \fBfile1\fP and \fBfile2\fP as a double-spaced, three-column +listing headed by "file list'': +.sp +.RS +.nf + +\fBpr -3d -h "file list" file1 file2 +\fP +.fi +.RE +.LP +.IP " 3." 4 +Write \fBfile1\fP on \fBfile2\fP, expanding tabs to columns 10, 19, +28, ...: +.sp +.RS +.nf + +\fBpr -e9 -t file2 +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +This utility is one of those that does not follow the Utility Syntax +Guidelines because of its historical origins. The standard +developers could have added new options that obeyed the guidelines +(and marked the old options obsolescent) or devised an entirely +new utility; there are examples of both actions in this volume of +IEEE\ Std\ 1003.1-2001. Because of its widespread use by +historical applications, the standard developers decided to exempt +this version of \fIpr\fP from many of the guidelines. +.LP +Implementations are required to accept option-arguments to the \fB-h\fP, +\fB-l\fP, \fB-o\fP, and \fB-w\fP options whether +presented as part of the same argument or as a separate argument to +\fIpr\fP, as suggested by the Utility Syntax Guidelines. The +\fB-n\fP and \fB-s\fP options, however, are specified as in historical +practice because they are frequently specified without +their optional arguments. If a were allowed before the option-argument +in these cases, a \fIfile\fP operand could +mistakenly be interpreted as an option-argument in historical applications. +.LP +The text about the minimum number of lines in multi-column output +was included to ensure that a best effort is made in balancing +the length of the columns. There are known historical implementations +in which, for example, 60-line files are listed by \fIpr\fP +-2 as one column of 56 lines and a second of 4. Although this is not +a problem when a full page with headers and trailers is +produced, it would be relatively useless when used with \fB-t\fP. +.LP +Historical implementations of the \fIpr\fP utility have differed in +the action taken for the \fB-f\fP option. BSD uses it as +described here for the \fB-F\fP option; System V uses it to change +trailing s on each page to a +and, if standard output is a TTY device, sends an to standard +error and reads a line from \fB/dev/tty\fP before the +first page. There were strong arguments from both sides of this issue +concerning historical practice and as a result the \fB-F\fP +option was added. XSI-conformant systems support the System V historical +actions for the \fB-f\fP option. +.LP +The <\fIoutput\ of\ date\fP> field in the \fB-l\fP format is specified +only for the POSIX locale. As noted, the +format can be different in other locales. No mechanism for defining +this is present in this volume of +IEEE\ Std\ 1003.1-2001, as the appropriate vehicle is a message catalog; +that is, the format should be specified as a +"message". +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexpand\fP , \fIlp\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/printf.1p b/man1p/printf.1p new file mode 100644 index 000000000..6be3a2459 --- /dev/null +++ b/man1p/printf.1p @@ -0,0 +1,426 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PRINTF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" printf +.SH NAME +printf \- write formatted output +.SH SYNOPSIS +.LP +\fBprintf\fP \fIformat\fP\fB[\fP\fIargument\fP\fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIprintf\fP utility shall write formatted operands to the standard +output. The \fIargument\fP operands shall be formatted +under control of the \fIformat\fP operand. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIformat\fP +A string describing the format to use to write the remaining operands. +See the EXTENDED DESCRIPTION section. +.TP 7 +\fIargument\fP +The strings to be written to standard output, under the control of +\fIformat\fP. See the EXTENDED DESCRIPTION section. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIprintf\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILC_NUMERIC\fP +.sp +Determine the locale for numeric formatting. It shall affect the format +of numbers written using the \fBe\fP , \fBE\fP , +\fBf\fP , \fBg\fP , and \fBG\fP conversion specifier characters (if +supported). +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +See the EXTENDED DESCRIPTION section. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +The \fIformat\fP operand shall be used as the \fIformat\fP string +described in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 5, File Format Notation with the following +exceptions: +.IP " 1." 4 +A in the format string, in any context other than a flag of +a conversion specification, shall be treated as an +ordinary character that is copied to the output. +.LP +.IP " 2." 4 +A \fB' '\fP character in the format string shall be treated as a \fB' '\fP +character, not as a . +.LP +.IP " 3." 4 +In addition to the escape sequences shown in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 5, File Format Notation +( \fB'\\\\'\fP , \fB'\\a'\fP , \fB'\\b'\fP , \fB'\\f'\fP , +\fB'\\n'\fP , \fB'\\r'\fP , \fB'\\t'\fP , \fB'\\v'\fP ), \fB"\\ddd"\fP +, where \fIddd\fP is a one, two, or three-digit +octal number, shall be written as a byte with the numeric value specified +by the octal number. +.LP +.IP " 4." 4 +The implementation shall not precede or follow output from the \fBd\fP +or \fBu\fP conversion specifiers with +s not specified by the \fIformat\fP operand. +.LP +.IP " 5." 4 +The implementation shall not precede output from the \fBo\fP conversion +specifier with zeros not specified by the +\fIformat\fP operand. +.LP +.IP " 6." 4 +The \fBe\fP , \fBE\fP , \fBf\fP , \fBg\fP , and \fBG\fP conversion +specifiers need not be supported. +.LP +.IP " 7." 4 +An additional conversion specifier character, \fBb\fP , shall be supported +as follows. The argument shall be taken to be a +string that may contain backslash-escape sequences. The following +backslash-escape sequences shall be supported: +.RS +.IP " *" 3 +The escape sequences listed in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 5, File Format Notation ( \fB'\\\\'\fP , \fB'\\a'\fP , \fB'\\b'\fP +, \fB'\\f'\fP , +\fB'\\n'\fP , \fB'\\r'\fP , \fB'\\t'\fP , \fB'\\v'\fP ), which shall +be converted to the characters they represent +.LP +.IP " *" 3 +\fB"\\0ddd"\fP , where \fIddd\fP is a zero, one, two, or three-digit +octal number that shall be converted to a byte with the +numeric value specified by the octal number +.LP +.IP " *" 3 +\fB'\\c'\fP , which shall not be written and shall cause \fIprintf\fP +to ignore any remaining characters in the string +operand containing it, any remaining string operands, and any additional +characters in the \fIformat\fP operand +.LP +.RE +.LP +The interpretation of a backslash followed by any other sequence of +characters is unspecified. +.LP +Bytes from the converted string shall be written until the end of +the string or the number of bytes indicated by the precision +specification is reached. If the precision is omitted, it shall be +taken to be infinite, so all bytes up to the end of the +converted string shall be written. +.LP +.IP " 8." 4 +For each conversion specification that consumes an argument, the next +argument operand shall be evaluated and converted to the +appropriate type for the conversion as specified below. +.LP +.IP " 9." 4 +The \fIformat\fP operand shall be reused as often as necessary to +satisfy the argument operands. Any extra \fBc\fP or +\fBs\fP conversion specifiers shall be evaluated as if a null string +argument were supplied; other extra conversion +specifications shall be evaluated as if a zero argument were supplied. +If the \fIformat\fP operand contains no conversion +specifications and \fIargument\fP operands are present, the results +are unspecified. +.LP +.IP "10." 4 +If a character sequence in the \fIformat\fP operand begins with a +\fB'%'\fP character, but does not form a valid conversion +specification, the behavior is unspecified. +.LP +.LP +The \fIargument\fP operands shall be treated as strings if the corresponding +conversion specifier is \fBb\fP , \fBc\fP , +or \fBs\fP ; otherwise, it shall be evaluated as a C constant, as +described by the ISO\ C standard, with the following +extensions: +.IP " *" 3 +A leading plus or minus sign shall be allowed. +.LP +.IP " *" 3 +If the leading character is a single-quote or double-quote, the value +shall be the numeric value in the underlying codeset of +the character following the single-quote or double-quote. +.LP +.LP +If an argument operand cannot be completely converted into an internal +value appropriate to the corresponding conversion +specification, a diagnostic message shall be written to standard error +and the utility shall not exit with a zero exit status, but +shall continue processing any remaining operands and shall write the +value accumulated at the time the error was detected to +standard output. +.LP +It is not considered an error if an argument operand is not completely +used for a \fBc\fP or \fBs\fP conversion or if a +string operand's first or second character is used to get the numeric +value of a character. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The floating-point formatting conversion specifications of \fIprintf\fP() +are not +required because all arithmetic in the shell is integer arithmetic. +The \fIawk\fP utility +performs floating-point calculations and provides its own \fBprintf\fP +function. The \fIbc\fP +utility can perform arbitrary-precision floating-point arithmetic, +but does not provide extensive formatting capabilities. (This +\fIprintf\fP utility cannot really be used to format \fIbc\fP output; +it does not support +arbitrary precision.) Implementations are encouraged to support the +floating-point conversions as an extension. +.LP +Note that this \fIprintf\fP utility, like the \fIprintf\fP() function +defined in the +System Interfaces volume of IEEE\ Std\ 1003.1-2001 on which it is +based, makes no special provision for dealing with +multi-byte characters when using the \fB%c\fP conversion specification +or when a precision is specified in a \fB%b\fP or +\fB%s\fP conversion specification. Applications should be extremely +cautious using either of these features when there are +multi-byte characters in the character set. +.LP +No provision is made in this volume of IEEE\ Std\ 1003.1-2001 which +allows field widths and precisions to be specified +as \fB'*'\fP since the \fB'*'\fP can be replaced directly in the \fIformat\fP +operand using shell variable substitution. +Implementations can also provide this feature as an extension if they +so choose. +.LP +Hexadecimal character constants as defined in the ISO\ C standard +are not recognized in the \fIformat\fP operand because +there is no consistent way to detect the end of the constant. Octal +character constants are limited to, at most, three octal +digits, but hexadecimal character constants are only terminated by +a non-hex-digit character. In the ISO\ C standard, the +\fB"##"\fP concatenation operator can be used to terminate a constant +and follow it with a hexadecimal character to be written. +In the shell, concatenation occurs before the \fIprintf\fP utility +has a chance to parse the end of the hexadecimal constant. +.LP +The \fB%b\fP conversion specification is not part of the ISO\ C standard; +it has been added here as a portable way to +process backslash escapes expanded in string operands as provided +by the \fIecho\fP utility. +See also the APPLICATION USAGE section of \fIecho\fP for ways to use +\fIprintf\fP as a replacement for +all of the traditional versions of the \fIecho\fP utility. +.LP +If an argument cannot be parsed correctly for the corresponding conversion +specification, the \fIprintf\fP utility is required +to report an error. Thus, overflow and extraneous characters at the +end of an argument being used for a numeric conversion shall be +reported as errors. +.SH EXAMPLES +.LP +To alert the user and then print and read a series of prompts: +.sp +.RS +.nf + +\fBprintf "\\aPlease fill in the following: \\nName: " +read name +printf "Phone number: " +read phone +\fP +.fi +.RE +.LP +To read out a list of right and wrong answers from a file, calculate +the percentage correctly, and print them out. The numbers +are right-justified and separated by a single . The percentage +is written to one decimal place of accuracy: +.sp +.RS +.nf + +\fBwhile read right wrong ; do + percent=$(echo "scale=1;($right*100)/($right+$wrong)" | bc) + printf "%2d right\\t%2d wrong\\t(%s%%)\\n" \\ + $right $wrong $percent +done < database_file +\fP +.fi +.RE +The command: +.sp +.RS +.nf + +\fBprintf "%5d%4d\\n" 1 21 321 4321 54321 +\fP +.fi +.RE +.LP +produces: +.sp +.RS +.nf + +\fB 1 21 + 3214321 +54321 0 +\fP +.fi +.RE +.LP +Note that the \fIformat\fP operand is used three times to print all +of the given strings and that a \fB'0'\fP was supplied +by \fIprintf\fP to satisfy the last \fB%4d\fP conversion specification. +.LP +The \fIprintf\fP utility is required to notify the user when conversion +errors are detected while producing numeric output; +thus, the following results would be expected on an implementation +with 32-bit twos-complement integers when \fB%d\fP is +specified as the \fIformat\fP operand: +.TS C +center; l1 l1 l. +\fB\ \fP \fBStandard\fP \fB\ \fP +\fBArgument\fP \fBOutput\fP \fBDiagnostic Output\fP +5a 5 printf: "5a" not completely converted +9999999999 2147483647 printf: "9999999999" arithmetic overflow +-9999999999 -2147483648 printf: "-9999999999" arithmetic overflow +ABC 0 printf: "ABC" expected numeric value +.TE +.LP +The diagnostic message format is not specified, but these examples +convey the type of information that should be reported. Note +that the value shown on standard output is what would be expected +as the return value from the \fIstrtol\fP() function as defined in +the System Interfaces volume of +IEEE\ Std\ 1003.1-2001. A similar correspondence exists between \fB%u\fP +and \fIstrtoul\fP() and \fB%e\fP , \fB%f\fP , and \fB%g\fP (if the +implementation supports +floating-point conversions) and \fIstrtod\fP(). +.LP +In a locale using the ISO/IEC\ 646:1991 standard as the underlying +codeset, the command: +.sp +.RS +.nf + +\fBprintf "%d\\n" 3 +3 -3 \\'3 \\"+3 "'-3" +\fP +.fi +.RE +.LP +produces: +.TP 7 +3 +Numeric value of constant 3 +.TP 7 +3 +Numeric value of constant 3 +.TP 7 +-3 +Numeric value of constant -3 +.TP 7 +51 +Numeric value of the character \fB'3'\fP in the ISO/IEC\ 646:1991 +standard codeset +.TP 7 +43 +Numeric value of the character \fB'+'\fP in the ISO/IEC\ 646:1991 +standard codeset +.TP 7 +45 +Numeric value of the character \fB'-'\fP in the ISO/IEC\ 646:1991 +standard codeset +.sp +.LP +Note that in a locale with multi-byte characters, the value of a character +is intended to be the value of the equivalent of the +\fBwchar_t\fP representation of the character as described in the +System Interfaces volume of IEEE\ Std\ 1003.1-2001. +.SH RATIONALE +.LP +The \fIprintf\fP utility was added to provide functionality that has +historically been provided by \fIecho\fP. However, due to irreconcilable +differences in the various versions of \fIecho\fP extant, the version +has few special features, leaving those to this new \fIprintf\fP +utility, which is based on one in the Ninth Edition system. +.LP +The EXTENDED DESCRIPTION section almost exactly matches the \fIprintf\fP() +function in +the ISO\ C standard, although it is described in terms of the file +format notation in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 5, File Format Notation. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIawk\fP , \fIbc\fP , \fIecho\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIprintf\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/prs.1p b/man1p/prs.1p new file mode 100644 index 000000000..fba4d034c --- /dev/null +++ b/man1p/prs.1p @@ -0,0 +1,401 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PRS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" prs +.SH NAME +prs \- print an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBprs\fP \fB[\fP\fB-a\fP\fB][\fP\fB-d\fP +\fIdataspec\fP\fB][\fP\fB-r\fP\fB[\fP\fISID\fP\fB]]\fP \fIfile\fP\fB... +.br +.sp +\fP +.LP +\fBprs\fP \fB[\fP \fB-e| -l\fP\fB]\fP \fB-c\fP \fIcutoff\fP \fB[\fP\fB-d\fP +\fIdataspec\fP\fB]\fP \fIfile\fP\fB... +.br +.sp +\fP +.LP +\fBprs\fP \fB[\fP \fB-e| -l\fP\fB]\fP \fB-r\fP\fB[\fP\fISID\fP\fB][\fP\fB-d\fP +\fIdataspec\fP\fB]\fP\fIfile\fP\fB... +.br +\fP +.SH DESCRIPTION +.LP +The \fIprs\fP utility shall write to standard output parts or all +of an SCCS file in a user-supplied format. +.SH OPTIONS +.LP +The \fIprs\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that the \fB-r\fP option has an +optional option-argument. This optional option-argument cannot be +presented as a separate argument. The following options shall be +supported: +.TP 7 +\fB-d\ \fP \fIdataspec\fP +Specify the output data specification. The \fIdataspec\fP shall be +a string consisting of SCCS file \fIdata\fP +\fIkeywords\fP (see Data Keywords ) interspersed with optional user-supplied +text. +.TP 7 +\fB-r[\fP\fISID\fP\fB]\fP +Specify the SCCS identification string (SID) of a delta for which +information is desired. If no \fISID\fP option-argument is +specified, the SID of the most recently created delta shall be assumed. +.TP 7 +\fB-e\fP +Request information for all deltas created earlier than and including +the delta designated via the \fB-r\fP option or the +date-time given by the \fB-c\fP option. +.TP 7 +\fB-l\fP +Request information for all deltas created later than and including +the delta designated via the \fB-r\fP option or the +date-time given by the \fB-c\fP option. +.TP 7 +\fB-c\ \fP \fIcutoff\fP +Indicate the \fIcutoff\fP date-time, in the form: +.sp +.RS +.nf + +\fIYY\fP\fB[\fP\fIMM\fP\fB[\fP\fIDD\fP\fB[\fP\fIHH\fP\fB[\fP\fIMM\fP\fB[\fP\fISS\fP\fB]]]]]\fP +.fi +.RE +.LP +For the \fIYY\fP component, values in the range [69,99] shall refer +to years 1969 to 1999 inclusive, and values in the range +[00,68] shall refer to years 2000 to 2068 inclusive. +.TP 7 +\fBNote:\fP +.RS +It is expected that in a future version of IEEE\ Std\ 1003.1-2001 +the default century inferred from a 2-digit year will +change. (This would apply to all commands accepting a 2-digit year +as input.) +.RE +.sp +.LP +No changes (deltas) to the SCCS file that were created after the specified +\fIcutoff\fP date-time shall be included in the +output. Units omitted from the date-time default to their maximum +possible values; for example, \fB-c\ 7502\fP is equivalent +to \fB-c\ 750228235959\fP. +.TP 7 +\fB-a\fP +Request writing of information for both removed-that is, \fIdelta\fP +\fItype\fP= +\fIR\fP (see \fIrmdel\fP )- and existing-that is, \fIdelta\fP +\fItype\fP= \fID\fP,- deltas. If the \fB-a\fP option is not specified, +information for existing deltas only shall be +provided. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of an existing SCCS file or a directory. If \fIfile\fP +is a directory, the \fIprs\fP utility shall behave as +though each file in the directory were specified as a named file, +except that non-SCCS files (last component of the pathname does +not begin with \fBs.\fP) and unreadable files shall be silently ignored. +.LP +If exactly one \fIfile\fP operand appears, and it is \fB'-'\fP , the +standard input shall be read; each line of the standard +input shall be taken to be the name of an SCCS file to be processed. +Non-SCCS files and unreadable files shall be silently +ignored. +.sp +.SH STDIN +.LP +The standard input shall be a text file used only when the \fIfile\fP +operand is specified as \fB'-'\fP . Each line of the +text file shall be interpreted as an SCCS pathname. +.SH INPUT FILES +.LP +Any SCCS files displayed are files of an unspecified format. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIprs\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall be a text file whose format is dependent +on the data keywords specified with the \fB-d\fP option. +.SS Data Keywords +.LP +Data keywords specify which parts of an SCCS file shall be retrieved +and output. All parts of an SCCS file have an associated +data keyword. A data keyword may appear in a \fIdataspec\fP multiple +times. +.LP +The information written by \fIprs\fP shall consist of: +.IP " 1." 4 +The user-supplied text +.LP +.IP " 2." 4 +Appropriate values (extracted from the SCCS file) substituted for +the recognized data keywords in the order of appearance in the +\fIdataspec\fP +.LP +.LP +The format of a data keyword value shall either be simple ( \fB'S'\fP +), in which keyword substitution is direct, or +multi-line ( \fB'M'\fP ). +.LP +User-supplied text shall be any text other than recognized data keywords. +A shall be specified by \fB'\\t'\fP and + by \fB'\\n'\fP . When the \fB-r\fP option is not specified, +the default \fIdataspec\fP shall be: +.sp +.RS +.nf + +\fB:PN::\\n\\n +\fP +.fi +.RE +.LP +and the following \fIdataspec\fP shall be used for each selected delta: +.sp +.RS +.nf + +\fB:Dt:\\t:DL:\\nMRs:\\n:MR:COMMENTS:\\n:C: +\fP +.fi +.RE +.TS C +center;c1 s1 s1 s1 s. +\fBSCCS File Data Keywords\fP +.T& +l l l l l. +\fBKeyword\fP \fBData Item\fP \fBFile Section\fP \fBValue\fP \fBFormat\fP +\fB:Dt:\fP Delta information Delta Table \fBSee below*\fP S +\fB:DL:\fP Delta line statistics " \fB:Li:/:Ld:/:Lu:\fP S +\fB:Li:\fP Lines inserted by Delta " \fB\fInnnnn\fP***\fP S +\fB:Ld:\fP Lines deleted by Delta " \fB\fInnnnn\fP***\fP S +\fB:Lu:\fP Lines unchanged by Delta " \fB\fInnnnn\fP***\fP S +\fB:DT:\fP Delta type " \fBD or R\fP S +\fB:I:\fP SCCS ID string (SID) " \fBSee below**\fP S +\fB:R:\fP Release number " \fB\fInnnn\fP\fP S +\fB:L:\fP Level number " \fB\fInnnn\fP\fP S +\fB:B:\fP Branch number " \fB\fInnnn\fP\fP S +\fB:S:\fP Sequence number " \fB\fInnnn\fP\fP S +\fB:D:\fP Date delta created " \fB:Dy:/:Dm:/:Dd:\fP S +\fB:Dy:\fP Year delta created " \fB\fInn\fP\fP S +\fB:Dm:\fP Month delta created " \fB\fInn\fP\fP S +\fB:Dd:\fP Day delta created " \fB\fInn\fP\fP S +\fB:T:\fP Time delta created " \fB:Th:::Tm:::Ts:\fP S +\fB:Th:\fP Hour delta created " \fB\fInn\fP\fP S +\fB:Tm:\fP Minutes delta created " \fB\fInn\fP\fP S +\fB:Ts:\fP Seconds delta created " \fB\fInn\fP\fP S +\fB:P:\fP Programmer who created Delta " \fB\fIlogname\fP\fP S +\fB:DS:\fP Delta sequence number " \fB\fInnnn\fP\fP S +\fB:DP:\fP Predecessor Delta sequence " \fB\fInnnn\fP\fP S +\fB\ \fP number \ \fB\ \fP \ +\fB:DI:\fP Sequence number of deltas " \fB:Dn:/:Dx:/:Dg:\fP S +\fB\ \fP included, excluded, or ignored \ \fB\ \fP \ +\fB:Dn:\fP Deltas included (sequence #) " \fB:DS: :DS: ...\fP S +\fB:Dx:\fP Deltas excluded (sequence #) " \fB:DS: :DS: ...\fP S +\fB:Dg:\fP Deltas ignored (sequence #) " \fB:DS: :DS: ...\fP S +\fB:MR:\fP MR numbers for delta " \fB\fItext\fP\fP M +\fB:C:\fP Comments for delta " \fB\fItext\fP\fP M +\fB:UN:\fP User names User Names \fB\fItext\fP\fP M +\fB:FL:\fP Flag list Flags \fB\fItext\fP\fP M +\fB:Y:\fP Module type flag " \fB\fItext\fP\fP S +\fB:MF:\fP MR validation flag " \fByes or no\fP S +\fB:MP:\fP MR validation program name " \fB\fItext\fP\fP S +\fB:KF:\fP Keyword error, warning flag " \fByes or no\fP S +\fB:KV:\fP Keyword validation string " \fB\fItext\fP\fP S +\fB:BF:\fP Branch flag " \fByes or no\fP S +\fB:J:\fP Joint edit flag " \fByes or no\fP S +\fB:LK:\fP Locked releases " \fB:R: ...\fP S +\fB:Q:\fP User-defined keyword " \fB\fItext\fP\fP S +\fB:M:\fP Module name " \fB\fItext\fP\fP S +\fB:FB:\fP Floor boundary " \fB:R:\fP S +\fB:CB:\fP Ceiling boundary " \fB:R:\fP S +\fB:Ds:\fP Default SID " \fB:I:\fP S +\fB:ND:\fP Null delta flag " \fByes or no\fP S +\fB:FD:\fP File descriptive text Comments \fB\fItext\fP\fP M +\fB:BD:\fP Body Body \fB\fItext\fP\fP M +\fB:GB:\fP Gotten body " \fB\fItext\fP\fP M +\fB:W:\fP A form of \fIwhat\fP string N/A \fB:Z::M:\\t:I:\fP S +\fB:A:\fP A form of \fIwhat\fP string N/A \fB:Z::Y: :M: :I::Z:\fP S +\fB:Z:\fP \fIwhat\fP string delimiter N/A \fB\fB@(#)\fP\fP S +\fB:F:\fP SCCS filename N/A \fB\fItext\fP\fP S +\fB:PN:\fP SCCS file pathname N/A \fB\fItext\fP\fP S +.TE +.TP 7 +* +\fB:Dt:\fP= \fB:DT: :I: :D: :T: :P: :DS: :DP:\fP +.TP 7 +** +\fB:R:.:L:.:B:.:S:\fP if the delta is a branch delta ( \fB:BF:\fP== +\fByes\fP) +.br +\fB:R:.:L:\fP if the delta is not a branch delta ( \fB:BF:\fP== \fBno\fP) +.TP 7 +*** +The line statistics are capped at 99999. For example, if 100000 lines +were unchanged in a certain revision, \fB:Lu:\fP shall +produce the value 99999. +.sp +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.IP " 1." 4 +The following example: +.sp +.RS +.nf + +\fBprs -d "User Names for :F: are:\\n:UN:" s.file +\fP +.fi +.RE +.LP +might write to standard output: +.sp +.RS +.nf + +\fBUser Names for s.file are: +xyz +131 +abc +\fP +.fi +.RE +.LP +.IP " 2." 4 +The following example: +.sp +.RS +.nf + +\fBprs -d "Delta for pgm :M:: :I: - :D: By :P:" -r s.file +\fP +.fi +.RE +.LP +might write to standard output: +.sp +.RS +.nf + +\fBDelta for pgm main.c: 3.7 - 77/12/01 By cas +\fP +.fi +.RE +.LP +.IP " 3." 4 +As a special case: +.sp +.RS +.nf + +\fBprs s.file +\fP +.fi +.RE +.LP +might write to standard output: +.sp +.RS +.nf + +\fBs.file: +<\fP\fIblank line\fP\fB> +D 1.1 77/12/01 00:00:00 cas 1 000000/00000/00000 +MRs: +bl78-12345 +bl79-54321 +COMMENTS: +this is the comment line for s.file initial delta +<\fP\fIblank line\fP\fB> +\fP +.fi +.RE +.LP +for each delta table entry of the \fBD\fP type. The only option allowed +to be used with this special case is the \fB-a\fP +option. +.LP +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIadmin\fP , \fIdelta\fP , \fIget\fP , \fIwhat\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/ps.1p b/man1p/ps.1p new file mode 100644 index 000000000..a550a4951 --- /dev/null +++ b/man1p/ps.1p @@ -0,0 +1,598 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ps +.SH NAME +ps \- report process status +.SH SYNOPSIS +.LP +\fBps\fP \fB[\fP\fB-aA\fP\fB][\fP\fB-defl\fP\fB][\fP\fB-G\fP +\fIgrouplist\fP\fB][\fP\fB-o\fP \fIformat\fP\fB]\fP\fB...\fP\fB[\fP\fB-p\fP +\fIproclist\fP\fB][\fP\fB-t\fP +\fItermlist\fP\fB] +.br +.sp +[\fP\fB-U\fP \fIuserlist\fP\fB][\fP\fB-g\fP \fIgrouplist\fP\fB][\fP\fB-n\fP +\fInamelist\fP\fB][\fP\fB-u\fP +\fIuserlist\fP\fB]\fP\fB\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIps\fP utility shall write information about processes, subject +to having the appropriate privileges to obtain +information about those processes. +.LP +By default, \fIps\fP shall select all processes with the same effective +user ID as the current user and the same controlling +terminal as the invoker. +.SH OPTIONS +.LP +The \fIps\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-a\fP +Write information for all processes associated with terminals. Implementations +may omit session leaders from this list. +.TP 7 +\fB-A\fP +Write information for all processes. +.TP 7 +\fB-d\fP +Write information for all processes, except session leaders. +.TP 7 +\fB-e\fP +Write information for all processes. (Equivalent to +\fB-A\fP.) +.TP 7 +\fB-f\fP +Generate a \fBfull\fP listing. (See the STDOUT section for the contents +of a \fBfull\fP listing.) +.TP 7 +\fB-g\ \fP \fIgrouplist\fP +Write information for processes whose session leaders are given in +\fIgrouplist\fP. The application shall ensure that the +\fIgrouplist\fP is a single argument in the form of a or comma-separated +list. +.TP 7 +\fB-G\ \fP \fIgrouplist\fP +Write information for processes whose real group ID numbers are given +in \fIgrouplist\fP. The application shall ensure that +the \fIgrouplist\fP is a single argument in the form of a +or comma-separated list. +.TP 7 +\fB-l\fP +Generate a \fBlong\fP listing. (See STDOUT for the contents of a \fBlong\fP +listing.) +.TP 7 +\fB-n\ \fP \fInamelist\fP +Specify the name of an alternative system \fInamelist\fP file in place +of the default. The name of the default file and the format +of a \fInamelist\fP file are unspecified. +.TP 7 +\fB-o\ \fP \fIformat\fP +Write information according to the format specification given in \fIformat\fP. +This is fully described in the STDOUT section. +Multiple \fB-o\fP options can be specified; the format specification +shall be interpreted as the -separated +concatenation of all the \fIformat\fP option-arguments. +.TP 7 +\fB-p\ \fP \fIproclist\fP +Write information for processes whose process ID numbers are given +in \fIproclist\fP. The application shall ensure that the +\fIproclist\fP is a single argument in the form of a or comma-separated +list. +.TP 7 +\fB-t\ \fP \fItermlist\fP +Write information for processes associated with terminals given in +\fItermlist\fP. The application shall ensure that the +\fItermlist\fP is a single argument in the form of a or comma-separated +list. Terminal identifiers shall be given in +an implementation-defined format. \ On XSI-conformant systems, they +shall be given in one of two forms: the device's filename +(for example, \fBtty04\fP) or, if the device's filename starts with +\fBtty\fP, just the identifier following the characters +\fBtty\fP (for example, \fB"04"\fP ). +.TP 7 +\fB-u\ \fP \fIuserlist\fP +Write information for processes whose user ID numbers or login names +are given in \fIuserlist\fP. The application shall ensure +that the \fIuserlist\fP is a single argument in the form of a +or comma-separated list. In the listing, the numerical +user ID shall be written unless the \fB-f\fP option is used, in which +case the login name shall be written. +.TP 7 +\fB-U\ \fP \fIuserlist\fP +Write information for processes whose real user ID numbers or login +names are given in \fIuserlist\fP. The application shall +ensure that the \fIuserlist\fP is a single argument in the form of +a or comma-separated list. +.sp +.LP +With the exception of \fB-o\fP \fIformat\fP, all of the options shown +are used to select processes. If any are specified, the +default list shall be ignored and \fIps\fP shall select the processes +represented by the inclusive OR of all the +selection-criteria options. +.SH OPERANDS +.LP +None. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIps\fP: +.TP 7 +\fICOLUMNS\fP +Override the system-selected horizontal display line size, used to +determine the number of text columns to display. See the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment +Variables for valid values and results when it is unset or null. +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fILC_TIME\fP +Determine the format and contents of the date and time strings displayed. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITZ\fP +Determine the timezone used to calculate date and time strings displayed. +If \fITZ\fP is unset or null, an unspecified default +timezone shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +When the \fB-o\fP option is not specified, the standard output format +is unspecified. +.LP +On XSI-conformant systems, the output format shall be as follows. +The column headings and descriptions of the columns in a +\fIps\fP listing are given below. The precise meanings of these fields +are implementation-defined. The letters \fB'f'\fP and +\fB'l'\fP (below) indicate the option ( \fBfull\fP or \fBlong\fP) +that shall cause the corresponding heading to appear; +\fBall\fP means that the heading always appears. Note that these two +options determine only what information is provided for a +process; they do not determine which processes are listed. +.TS C +center; l l lw(40). +\fBF\fP (l) T{ +.na +Flags (octal and additive) associated with the process. +.ad +T} +\fBS\fP (l) T{ +.na +The state of the process. +.ad +T} +\fBUID\fP (f,l) T{ +.na +The user ID number of the process owner; the login name is printed under the \fB-f\fP option. +.ad +T} +\fBPID\fP (all) T{ +.na +The process ID of the process; it is possible to kill a process if this datum is known. +.ad +T} +\fBPPID\fP (f,l) T{ +.na +The process ID of the parent process. +.ad +T} +\fBC\fP (f,l) T{ +.na +Processor utilization for scheduling. +.ad +T} +\fBPRI\fP (l) T{ +.na +The priority of the process; higher numbers mean lower priority. +.ad +T} +\fBNI\fP (l) T{ +.na +Nice value; used in priority computation. +.ad +T} +\fBADDR\fP (l) T{ +.na +The address of the process. +.ad +T} +\fBSZ\fP (l) T{ +.na +The size in blocks of the core image of the process. +.ad +T} +\fBWCHAN\fP (l) T{ +.na +The event for which the process is waiting or sleeping; if blank, the process is running. +.ad +T} +\fBSTIME\fP (f) T{ +.na +Starting time of the process. +.ad +T} +\fBTTY\fP (all) T{ +.na +The controlling terminal for the process. +.ad +T} +\fBTIME\fP (all) T{ +.na +The cumulative execution time for the process. +.ad +T} +\fBCMD\fP (all) T{ +.na +The command name; the full command name and its arguments are written under the \fB-f\fP option. +.ad +T} +.TE +.LP +A process that has exited and has a parent, but has not yet been waited +for by the parent, shall be marked \fBdefunct\fP. +.LP +Under the option \fB-f\fP, \fIps\fP tries to determine the command +name and arguments given when the process was created by +examining memory or the swap area. Failing this, the command name, +as it would appear without the option \fB-f\fP, is written in +square brackets. +.LP +The \fB-o\fP option allows the output format to be specified under +user control. +.LP +The application shall ensure that the format specification is a list +of names presented as a single argument, or +comma-separated. Each variable has a default header. The default header +can be overridden by appending an equals sign and the new +text of the header. The rest of the characters in the argument shall +be used as the header text. The fields specified shall be +written in the order specified on the command line, and should be +arranged in columns in the output. The field widths shall be +selected by the system to be at least as wide as the header text (default +or overridden value). If the header text is null, such as +\fB-o\fP \fIuser\fP=, the field width shall be at least as wide as +the default header text. If all header text fields are null, +no header line shall be written. +.LP +The following names are recognized in the POSIX locale: +.TP 7 +\fBruser\fP +The real user ID of the process. This shall be the textual user ID, +if it can be obtained and the field width permits, or a +decimal representation otherwise. +.TP 7 +\fBuser\fP +The effective user ID of the process. This shall be the textual user +ID, if it can be obtained and the field width permits, or +a decimal representation otherwise. +.TP 7 +\fBrgroup\fP +The real group ID of the process. This shall be the textual group +ID, if it can be obtained and the field width permits, or a +decimal representation otherwise. +.TP 7 +\fBgroup\fP +The effective group ID of the process. This shall be the textual group +ID, if it can be obtained and the field width permits, +or a decimal representation otherwise. +.TP 7 +\fBpid\fP +The decimal value of the process ID. +.TP 7 +\fBppid\fP +The decimal value of the parent process ID. +.TP 7 +\fBpgid\fP +The decimal value of the process group ID. +.TP 7 +\fBpcpu\fP +The ratio of CPU time used recently to CPU time available in the same +period, expressed as a percentage. The meaning of +"recently" in this context is unspecified. The CPU time available +is determined in an unspecified manner. +.TP 7 +\fBvsz\fP +The size of the process in (virtual) memory in 1024 byte units as +a decimal integer. +.TP 7 +\fBnice\fP +The decimal value of the nice value of the process; see \fInice\fP() +\&. +.TP 7 +\fBetime\fP +In the POSIX locale, the elapsed time since the process was started, +in the form: +.sp +.RS +.nf + +\fB[[\fP\fIdd\fP\fB-\fP\fB]\fP\fIhh\fP\fB:\fP\fB]\fP\fImm\fP\fB:\fP\fIss\fP +.fi +.RE +.LP +where \fIdd\fP shall represent the number of days, \fIhh\fP the number +of hours, \fImm\fP the number of minutes, and +\fIss\fP the number of seconds. The \fIdd\fP field shall be a decimal +integer. The \fIhh\fP, \fImm\fP, and \fIss\fP fields +shall be two-digit decimal integers padded on the left with zeros. +.TP 7 +\fBtime\fP +In the POSIX locale, the cumulative CPU time of the process in the +form: +.sp +.RS +.nf + +\fB[\fP\fIdd\fP\fB-\fP\fB]\fP\fIhh\fP\fB:\fP\fImm\fP\fB:\fP\fIss\fP +.fi +.RE +.LP +The \fIdd\fP, \fIhh\fP, \fImm\fP, and \fIss\fP fields shall be as +described in the \fBetime\fP specifier. +.TP 7 +\fBtty\fP +The name of the controlling terminal of the process (if any) in the +same format used by the \fIwho\fP utility. +.TP 7 +\fBcomm\fP +The name of the command being executed ( \fIargv\fP[0] value) as a +string. +.TP 7 +\fBargs\fP +The command with all its arguments as a string. The implementation +may truncate this value to the field width; it is +implementation-defined whether any further truncation occurs. It is +unspecified whether the string represented is a version of the +argument list as it was passed to the command when it started, or +is a version of the arguments as they may have been modified by +the application. Applications cannot depend on being able to modify +their argument list and having that modification be reflected +in the output of \fIps\fP. +.sp +.LP +Any field need not be meaningful in all implementations. In such a +case a hyphen ( \fB'-'\fP ) should be output in place of +the field value. +.LP +Only \fBcomm\fP and \fBargs\fP shall be allowed to contain s; +all others shall not. Any implementation-defined +variables shall be specified in the system documentation along with +the default header and indicating whether the field may contain +s. +.LP +The following table specifies the default header to be used in the +POSIX locale corresponding to each format specifier. +.br +.sp +.ce 1 +\fBTable: Variable Names and Default Headers in \fIps\fP\fP +.TS C +center; l1 l1 l1 l. +\fBFormat Specifier\fP \fBDefault Header\fP \fBFormat Specifier\fP \fBDefault Header\fP +\fBargs\fP \fBCOMMAND\fP \fBppid\fP \fBPPID\fP +\fBcomm\fP \fBCOMMAND\fP \fBrgroup\fP \fBRGROUP\fP +\fBetime\fP \fBELAPSED\fP \fBruser\fP \fBRUSER\fP +\fBgroup\fP \fBGROUP\fP \fBtime\fP \fBTIME\fP +\fBnice\fP \fBNI\fP \fBtty\fP \fBTT\fP +\fBpcpu\fP \fB%CPU\fP \fBuser\fP \fBUSER\fP +\fBpgid\fP \fBPGID\fP \fBvsz\fP \fBVSZ\fP +\fBpid\fP \fBPID\fP \fB\ \fP \fB\ \fP +.TE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Things can change while \fIps\fP is running; the snapshot it gives +is only true for an instant, and might not be accurate by +the time it is displayed. +.LP +The \fBargs\fP format specifier is allowed to produce a truncated +version of the command arguments. In some implementations, +this information is no longer available when the \fIps\fP utility +is executed. +.LP +If the field width is too narrow to display a textual ID, the system +may use a numeric version. Normally, the system would be +expected to choose large enough field widths, but if a large number +of fields were selected to write, it might squeeze fields to +their minimum sizes to fit on one line. One way to ensure adequate +width for the textual IDs is to override the default header for +a field to make it larger than most or all user or group names. +.LP +There is no special quoting mechanism for header text. The header +text is the rest of the argument. If multiple header changes +are needed, multiple \fB-o\fP options can be used, such as: +.sp +.RS +.nf + +\fBps -o "user=User Name" -o pid=Process\\ ID +\fP +.fi +.RE +.LP +On some implementations, especially multi-level secure systems, \fIps\fP +may be severely restricted and produce information +only about child processes owned by the user. +.SH EXAMPLES +.LP +The command: +.sp +.RS +.nf + +\fBps -o user,pid,ppid=MOM -o args +\fP +.fi +.RE +.LP +writes at least the following in the POSIX locale: +.sp +.RS +.nf + +\fB USER PID MOM COMMAND +helene 34 12 ps -o uid,pid,ppid=MOM -o args +\fP +.fi +.RE +.LP +The contents of the \fBCOMMAND\fP field need not be the same in all +implementations, due to possible truncation. +.SH RATIONALE +.LP +There is very little commonality between BSD and System V implementations +of \fIps\fP. Many options conflict or have subtly +different usages. The standard developers attempted to select a set +of options for the base standard that were useful on a wide +range of systems and selected options that either can be implemented +on both BSD and System V-based systems without breaking the +current implementations or where the options are sufficiently similar +that any changes would not be unduly problematic for users or +implementors. +.LP +It is recognized that on some implementations, especially multi-level +secure systems, \fIps\fP may be nearly useless. The +default output has therefore been chosen such that it does not break +historical implementations and also is likely to provide at +least some useful information on most systems. +.LP +The major change is the addition of the format specification capability. +The motivation for this invention is to provide a +mechanism for users to access a wider range of system information, +if the system permits it, in a portable manner. The fields +chosen to appear in this volume of IEEE\ Std\ 1003.1-2001 were arrived +at after considering what concepts were likely to be +both reasonably useful to the "average" user and had a reasonable +chance of being implemented on a wide range of systems. Again +it is recognized that not all systems are able to provide all the +information and, conversely, some may wish to provide more. It is +hoped that the approach adopted will be sufficiently flexible and +extensible to accommodate most systems. Implementations may be +expected to introduce new format specifiers. +.LP +The default output should consist of a short listing containing the +process ID, terminal name, cumulative execution time, and +command name of each process. +.LP +The preference of the standard developers would have been to make +the format specification an operand of the \fIps\fP command. +Unfortunately, BSD usage precluded this. +.LP +At one time a format was included to display the environment array +of the process. This was deleted because there is no portable +way to display it. +.LP +The \fB-A\fP option is equivalent to the BSD \fB-g\fP and the SVID +\fB-e\fP. Because the two systems differed, a mnemonic +compromise was selected. +.LP +The \fB-a\fP option is described with some optional behavior because +the SVID omits session leaders, but BSD does not. +.LP +In an early proposal, format specifiers appeared for priority and +start time. The former was not defined adequately in this +volume of IEEE\ Std\ 1003.1-2001 and was removed in deference to the +defined nice value; the latter because elapsed time +was considered to be more useful. +.LP +In a new BSD version of \fIps\fP, a \fB-O\fP option can be used to +write all of the default information, followed by +additional format specifiers. This was not adopted because the default +output is implementation-defined. Nevertheless, this is a +useful option that should be reserved for that purpose. In the \fB-o\fP +option for the POSIX Shell and Utilities \fIps\fP, the +format is the concatenation of each \fB-o\fP. Therefore, the user +can have an alias or function that defines the beginning of +their desired format and add more fields to the end of the output +in certain cases where that would be useful. +.LP +The format of the terminal name is unspecified, but the descriptions +of \fIps\fP, \fItalk\fP, \fIwho\fP, and \fIwrite\fP require that they +all use the same format. +.LP +The \fBpcpu\fP field indicates that the CPU time available is determined +in an unspecified manner. This is because it is +difficult to express an algorithm that is useful across all possible +machine architectures. Historical counterparts to this value +have attempted to show percentage of use in the recent past, such +as the preceding minute. Frequently, these values for all +processes did not add up to 100%. Implementations are encouraged to +provide data in this field to users that will help them +identify processes currently affecting the performance of the system. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIkill\fP() , \fInice\fP() , \fIrenice\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/pwd.1p b/man1p/pwd.1p new file mode 100644 index 000000000..eedbfd162 --- /dev/null +++ b/man1p/pwd.1p @@ -0,0 +1,156 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PWD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pwd +.SH NAME +pwd \- return working directory name +.SH SYNOPSIS +.LP +\fBpwd\fP \fB[\fP\fB-L | -P\fP \fB]\fP +.SH DESCRIPTION +.LP +The \fIpwd\fP utility shall write to standard output an absolute pathname +of the current working directory, which does not +contain the filenames dot or dot-dot. +.SH OPTIONS +.LP +The \fIpwd\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported by the implementation: +.TP 7 +\fB-L\fP +If the \fIPWD\fP environment variable contains an absolute pathname +of the current directory that does not contain the +filenames dot or dot-dot, \fIpwd\fP shall write this pathname to standard +output. Otherwise, the \fB-L\fP option shall behave as +the \fB-P\fP option. +.TP 7 +\fB-P\fP +The absolute pathname written shall not contain filenames that, in +the context of the pathname, refer to files of type symbolic +link. +.sp +.LP +If both \fB-L\fP and \fB-P\fP are specified, the last one shall apply. +If neither \fB-L\fP nor \fB-P\fP is specified, the +\fIpwd\fP utility shall behave as if \fB-L\fP had been specified. +.SH OPERANDS +.LP +None. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIpwd\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPWD\fP +If the \fB-P\fP option is in effect, this variable shall be set to +an absolute pathname of the current working directory that +does not contain any components that specify symbolic links, does +not contain any components that are dot, and does not contain any +components that are dot-dot. If an application sets or unsets the +value of \fIPWD ,\fP the behavior of \fIpwd\fP is +unspecified. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fIpwd\fP utility output is an absolute pathname of the current +working directory: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIdirectory pathname\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If an error is detected, output shall not be written to standard output, +a diagnostic message shall be written to standard +error, and the exit status is not zero. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +Some implementations have historically provided \fIpwd\fP as a shell +special built-in command. +.LP +In most utilities, if an error occurs, partial output may be written +to standard output. This does not happen in historical +implementations of \fIpwd\fP. Because \fIpwd\fP is frequently used +in historical shell scripts without checking the exit status, +it is important that the historical behavior is required here; therefore, +the CONSEQUENCES OF ERRORS section specifically disallows +any partial output being written to standard output. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcd\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIgetcwd\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/qalter.1p b/man1p/qalter.1p new file mode 100644 index 000000000..7c0049841 --- /dev/null +++ b/man1p/qalter.1p @@ -0,0 +1,790 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "QALTER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" qalter +.SH NAME +qalter \- alter batch job +.SH SYNOPSIS +.LP +\fBqalter\fP \fB[\fP\fB-a\fP \fIdate_time\fP\fB][\fP\fB-A\fP +\fIaccount_string\fP\fB][\fP\fB-c\fP \fIinterval\fP\fB][\fP\fB-e\fP +\fIpath_name\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-h\fP \fIhold_list\fP\fB][\fP\fB-j\fP +\fIjoin_list\fP\fB][\fP\fB-k\fP \fIkeep_list\fP\fB][\fP\fB-l\fP \fIresource_list\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-m\fP \fImail_options\fP\fB][\fP\fB-M\fP +\fImail_list\fP\fB][\fP\fB-N\fP \fIname\fP\fB][\fP\fB-o\fP \fIpath_name\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-p\fP \fIpriority\fP\fB][\fP\fB-r\fP +\fIy\fP\fB|\fP\fIn\fP\fB][\fP\fB-S\fP \fIpath_name_list\fP\fB][\fP\fB-u\fP +\fIuser_list\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB\fP\fIjob_identifier\fP \fB... \fP +.SH DESCRIPTION +.LP +The attributes of a batch job are altered by a request to the batch +server that manages the batch job. The \fIqalter\fP utility +is a user-accessible batch client that requests the alteration of +the attributes of one or more batch jobs. +.LP +The \fIqalter\fP utility shall alter the attributes of those batch +jobs, and only those batch jobs, for which a batch +\fIjob_identifier\fP is presented to the utility. +.LP +The \fIqalter\fP utility shall alter the attributes of batch jobs +in the order in which the batch \fIjob_identifier\fPs are +presented to the utility. +.LP +If the \fIqalter\fP utility fails to process a batch \fIjob_identifier\fP +successfully, the utility shall proceed to process +the remaining batch \fIjob_identifier\fPs, if any. +.LP +For each batch \fIjob_identifier\fP for which the \fIqalter\fP utility +succeeds, each attribute of the identified batch job +shall be altered as indicated by all the options presented to the +utility. +.LP +For each identified batch job for which the \fIqalter\fP utility fails, +the utility shall not alter any attribute of the batch +job. +.LP +For each batch job that the \fIqalter\fP utility processes, the utility +shall not modify any attribute other than those +required by the options and option-arguments presented to the utility. +.LP +The \fIqalter\fP utility shall alter batch jobs by sending a \fIModify +Job Request\fP to the batch server that manages each +batch job. At the time the \fIqalter\fP utility exits, it shall have +modified the batch job corresponding to each successfully +processed batch \fIjob_identifier\fP. An attempt to alter the attributes +of a batch job in the RUNNING state is +implementation-defined. +.SH OPTIONS +.LP +The \fIqalter\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported by the implementation: +.TP 7 +\fB-a\ \fP \fIdate_time\fP +Redefine the time at which the batch job becomes eligible for execution. +.LP +The \fIdate_time\fP argument shall be in the same form and represent +the same time as for the \fItouch\fP utility. The time so represented +shall be set into the \fIExecution_Time\fP attribute +of the batch job. If the time specified is earlier than the current +time, the \fB-a\fP option shall have no effect. +.TP 7 +\fB-A\ \fP \fIaccount_string\fP +.sp +Redefine the account to which the resource consumption of the batch +job should be charged. +.LP +The syntax of the \fIaccount_string\fP option-argument is unspecified. +.LP +The \fIqalter\fP utility shall set the \fIAccount_Name\fP attribute +of the batch job to the value of the \fIaccount_string\fP +option-argument. +.TP 7 +\fB-c\ \fP \fIinterval\fP +Redefine whether the batch job should be checkpointed, and if so, +how often. +.LP +The \fIqalter\fP utility shall accept a value for the interval option-argument +that is one of the following: +.TP 7 +\fBn\fP +.RS +No checkpointing is to be performed on the batch job (NO_CHECKPOINT). +.RE +.TP 7 +\fBs\fP +.RS +Checkpointing is to be performed only when the batch server is shut +down (CHECKPOINT_AT_SHUTDOWN). +.RE +.TP 7 +\fBc\fP +.RS +Automatic periodic checkpointing is to be performed at the \fIMinimum_Cpu_Interval\fP +attribute of the batch queue, in units +of CPU minutes (CHECKPOINT_AT_MIN_CPU_INTERVAL). +.RE +.TP 7 +\fBc\fP=\fIminutes\fP +.RS +Automatic periodic checkpointing is to be performed every \fIminutes\fP +of CPU time, or every \fIMinimum_Cpu_Interval\fP +minutes, whichever is greater. The \fIminutes\fP argument shall conform +to the syntax for unsigned integers and shall be greater +than zero. +.RE +.sp +.LP +An implementation may define other checkpoint intervals. The conformance +document for an implementation shall describe any +alternative checkpoint intervals, how they are specified, their internal +behavior, and how they affect the behavior of the +utility. +.LP +The \fIqalter\fP utility shall set the \fICheckpoint\fP attribute +of the batch job to the value of the \fIinterval\fP +option-argument. +.TP 7 +\fB-e\ \fP \fIpath_name\fP +Redefine the path to be used for the standard error stream of the +batch job. +.LP +The \fIqalter\fP utility shall accept a \fIpath_name\fP option-argument +that conforms to the syntax of the \fIpath_name\fP +element defined in the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +which can be preceded by a host name element of +the form \fIhostname\fP:. +.LP +If the \fIpath_name\fP option-argument constitutes an absolute pathname, +the \fIqalter\fP utility shall set the +\fIError_Path\fP attribute of the batch job to the value of the \fIpath_name\fP +option-argument, including the host name element, +if present. +.LP +If the \fIpath_name\fP option-argument constitutes a relative pathname +and no host name element is specified, the \fIqalter\fP +utility shall set the \fIError_Path\fP attribute of the batch job +to the value of the absolute pathname derived by expanding the +\fIpath_name\fP option-argument relative to the current directory +of the process that executes the \fIqalter\fP utility. +.LP +If the \fIpath_name\fP option-argument constitutes a relative pathname +and a host name element is specified, the \fIqalter\fP +utility shall set the \fIError_Path\fP attribute of the batch job +to the value of the option-argument without expansion. +.LP +If the \fIpath_name\fP option-argument does not include a host name +element, the \fIqalter\fP utility shall prefix the +pathname in the \fIError_Path\fP attribute with \fIhostname\fP:, where +\fIhostname\fP is the name of the host upon which the +\fIqalter\fP utility is being executed. +.TP 7 +\fB-h\ \fP \fIhold_list\fP +Redefine the types of holds, if any, on the batch job. The \fIqalter\fP +\fB-h\fP option shall accept a value for the +\fIhold_list\fP option-argument that is a string of alphanumeric characters +in the portable character set. +.LP +The \fIqalter\fP utility shall accept a value for the \fIhold_list\fP +option-argument that is a string of one or more of the +characters \fB'u'\fP , \fB's'\fP , or \fB'o'\fP , or the single character +\fB'n'\fP . For each unique character in the +\fIhold_list\fP option-argument, the \fIqalter\fP utility shall add +a value to the \fIHold_Types\fP attribute of the batch job +as follows, each representing a different hold type: +.TP 7 +\fBu\fP +.RS +USER +.RE +.TP 7 +\fBs\fP +.RS +SYSTEM +.RE +.TP 7 +\fBo\fP +.RS +OPERATOR +.RE +.sp +.LP +If any of these characters are duplicated in the \fIhold_list\fP option-argument, +the duplicates shall be ignored. An existing +\fIHold_Types\fP attribute can be cleared by the hold type: +.TP 7 +\fBn\fP +.RS +NO_HOLD +.RE +.sp +.LP +The \fIqalter\fP utility shall consider it an error if any hold type +other than \fB'n'\fP is combined with hold type +\fB'n'\fP . Strictly conforming applications shall not repeat any +of the characters \fB'u'\fP , \fB's'\fP , \fB'o'\fP , +or \fB'n'\fP within the \fIhold_list\fP option-argument. The \fIqalter\fP +utility shall permit the repetition of characters, +but shall not assign additional meaning to the repeated characters. +An implementation may define other hold types. The conformance +document for an implementation shall describe any additional hold +types, how they are specified, their internal behavior, and how +they affect the behavior of the utility. +.TP 7 +\fB-j\ \fP \fIjoin_list\fP +Redefine which streams of the batch job are to be merged. The \fIqalter\fP +\fB-j\fP option shall accept a value for the +\fIjoin_list\fP option-argument that is a string of alphanumeric characters +in the portable character set. +.LP +The \fIqalter\fP utility shall accept a \fIjoin_list\fP option-argument +that consists of one or more of the characters +\fB'e'\fP and \fB'o'\fP , or the single character \fB'n'\fP . +.LP +All of the other batch job output streams specified shall be merged +into the output stream represented by the character listed +first in the \fIjoin_list\fP option-argument. +.LP +For each unique character in the \fIjoin_list\fP option-argument, +the \fIqalter\fP utility shall add a value to the +\fIJoin_Path\fP attribute of the batch job as follows, each representing +a different batch job stream to join: +.TP 7 +\fBe\fP +.RS +The standard error of the batch job (JOIN_STD_ERROR). +.RE +.TP 7 +\fBo\fP +.RS +The standard output of the batch job (JOIN_STD_OUTPUT). +.RE +.sp +.LP +An existing \fIJoin_Path\fP attribute can be cleared by the join type: +.TP 7 +\fBn\fP +.RS +NO_JOIN +.RE +.sp +.LP +If \fB'n'\fP is specified, then no files are joined. The \fIqalter\fP +utility shall consider it an error if any join type +other than \fB'n'\fP is combined with join type \fB'n'\fP . +.LP +Strictly conforming applications shall not repeat any of the characters +\fB'e'\fP , \fB'o'\fP , or \fB'n'\fP within the +\fIjoin_list\fP option-argument. The \fIqalter\fP utility shall permit +the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.LP +An implementation may define other join types. The conformance document +for an implementation shall describe any additional +batch job streams, how they are specified, their internal behavior, +and how they affect the behavior of the utility. +.TP 7 +\fB-k\ \fP \fIkeep_list\fP +Redefine which output of the batch job to retain on the execution +host. +.LP +The \fIqalter\fP \fB-k\fP option shall accept a value for the \fIkeep_list\fP +option-argument that is a string of +alphanumeric characters in the portable character set. +.LP +The \fIqalter\fP utility shall accept a \fIkeep_list\fP option-argument +that consists of one or more of the characters +\fB'e'\fP and \fB'o'\fP , or the single character \fB'n'\fP . +.LP +For each unique character in the \fIkeep_list\fP option-argument, +the \fIqalter\fP utility shall add a value to the +\fIKeep_Files\fP attribute of the batch job as follows, each representing +a different batch job stream to keep: +.TP 7 +\fBe\fP +.RS +The standard error of the batch job (KEEP_STD_ERROR). +.RE +.TP 7 +\fBo\fP +.RS +The standard output of the batch job (KEEP_STD_OUTPUT). +.RE +.sp +.LP +If both \fB'e'\fP and \fB'o'\fP are specified, then both files are +retained. An existing \fIKeep_Files\fP attribute can +be cleared by the keep type: +.TP 7 +\fBn\fP +.RS +NO_KEEP +.RE +.sp +.LP +If \fB'n'\fP is specified, then no files are retained. The \fIqalter\fP +utility shall consider it an error if any keep type +other than \fB'n'\fP is combined with keep type \fB'n'\fP . +.LP +Strictly conforming applications shall not repeat any of the characters +\fB'e'\fP , \fB'o'\fP , or \fB'n'\fP within the +\fIkeep_list\fP option-argument. The \fIqalter\fP utility shall permit +the repetition of characters, but shall not assign +additional meaning to the repeated characters. An implementation may +define other keep types. The conformance document for an +implementation shall describe any additional keep types, how they +are specified, their internal behavior, and how they affect the +behavior of the utility. +.TP 7 +\fB-l\ \fP \fIresource_list\fP +.sp +Redefine the resources that are allowed or required by the batch job. +.LP +The \fIqalter\fP utility shall accept a \fIresource_list\fP option-argument +that conforms to the following syntax: +.sp +.RS +.nf + +\fBresource=value[,,resource=value,,...] +\fP +.fi +.RE +.LP +The \fIqalter\fP utility shall set one entry in the value of the \fIResource_List\fP +attribute of the batch job for each +resource listed in the \fIresource_list\fP option-argument. +.LP +Because the list of supported resource names might vary by batch server, +the \fIqalter\fP utility shall rely on the batch +server to validate the resource names and associated values. See \fIMultiple +Keyword-Value +Pairs\fP for a means of removing \fIkeyword\fP= \fIvalue\fP (and \fIvalue\fP@ +\fIkeyword\fP) pairs and other general rules +for list-oriented batch job attributes. +.TP 7 +\fB-m\ \fP \fImail_options\fP +.sp +Redefine the points in the execution of the batch job at which the +batch server is to send mail about a change in the state of the +batch job. +.LP +The \fIqalter\fP \fB-m\fP option shall accept a value for the \fImail_options\fP +option-argument that is a string of +alphanumeric characters in the portable character set. +.LP +The \fIqalter\fP utility shall accept a value for the \fImail_options\fP +option-argument that is a string of one or more of +the characters \fB'e'\fP , \fB'b'\fP , and \fB'a'\fP , or the single +character \fB'n'\fP . For each unique character in +the \fImail_options\fP option-argument, the \fIqalter\fP utility shall +add a value to the \fIMail_Users\fP attribute of the +batch job as follows, each representing a different time during the +life of a batch job at which to send mail: +.TP 7 +\fBe\fP +.RS +MAIL_AT_EXIT +.RE +.TP 7 +\fBb\fP +.RS +MAIL_AT_BEGINNING +.RE +.TP 7 +\fBa\fP +.RS +MAIL_AT_ABORT +.RE +.sp +.LP +If any of these characters are duplicated in the \fImail_options\fP +option-argument, the duplicates shall be ignored. +.LP +An existing \fIMail_Points\fP attribute can be cleared by the mail +type: +.TP 7 +\fBn\fP +.RS +NO_MAIL +.RE +.sp +.LP +If \fB'n'\fP is specified, then mail is not sent. The \fIqalter\fP +utility shall consider it an error if any mail type other +than \fB'n'\fP is combined with mail type \fB'n'\fP . Strictly conforming +applications shall not repeat any of the characters +\fB'e'\fP , \fB'b'\fP , \fB'a'\fP , or \fB'n'\fP within the \fImail_options\fP +option-argument. The \fIqalter\fP +utility shall permit the repetition of characters but shall not assign +additional meaning to the repeated characters. +.LP +An implementation may define other mail types. The conformance document +for an implementation shall describe any additional mail +types, how they are specified, their internal behavior, and how they +affect the behavior of the utility. +.TP 7 +\fB-M\ \fP \fImail_list\fP +Redefine the list of users to which the batch server that executes +the batch job is to send mail, if the batch server sends +mail about the batch job. +.LP +The syntax of the \fImail_list\fP option-argument is unspecified. +If the implementation of the \fIqalter\fP utility uses a +name service to locate users, the utility shall accept the syntax +used by the name service. +.LP +If the implementation of the \fIqalter\fP utility does not use a name +service to locate users, the implementation shall accept +the following syntax for user names: +.sp +.RS +.nf + +\fBmail_address[,,mail_address,,...] +\fP +.fi +.RE +.LP +The interpretation of \fImail_address\fP is implementation-defined. +.LP +The \fIqalter\fP utility shall set the \fIMail_Users\fP attribute +of the batch job to the value of the \fImail_list\fP +option-argument. +.TP 7 +\fB-N\ \fP \fIname\fP +Redefine the name of the batch job. +.LP +The \fIqalter\fP \fB-N\fP option shall accept a value for the \fIname\fP +option-argument that is a string of up to 15 +alphanumeric characters in the portable character set where the first +character is alphabetic. +.LP +The syntax of the \fIname\fP option-argument is unspecified. +.LP +The \fIqalter\fP utility shall set the \fIJob_Name\fP attribute of +the batch job to the value of the \fIname\fP +option-argument. +.TP 7 +\fB-o\ \fP \fIpath_name\fP +Redefine the path for the standard output of the batch job. +.LP +The \fIqalter\fP utility shall accept a \fIpath_name\fP option-argument +that conforms to the syntax of the \fIpath_name\fP +element defined in the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +which can be preceded by a host name element of +the form \fIhostname\fP:. +.LP +If the \fIpath_name\fP option-argument constitutes an absolute pathname, +the \fIqalter\fP utility shall set the +\fIOutput_Path\fP attribute of the batch job to the value of the \fIpath_name\fP +option-argument. +.LP +If the \fIpath_name\fP option-argument constitutes a relative pathname +and no host name element is specified, the \fIqalter\fP +utility shall set the \fIOutput_Path\fP attribute of the batch job +to the absolute pathname derived by expanding the +\fIpath_name\fP option-argument relative to the current directory +of the process that executes the \fIqalter\fP utility. +.LP +If the \fIpath_name\fP option-argument constitutes a relative pathname +and a host name element is specified, the \fIqalter\fP +utility shall set the \fIOutput_Path\fP attribute of the batch job +to the value of the \fIpath_name\fP option-argument without +any expansion of the pathname. +.LP +If the \fIpath_name\fP option-argument does not include a host name +element, the \fIqalter\fP utility shall prefix the +pathname in the \fIOutput_Path\fP attribute with \fIhostname\fP:, +where \fIhostname\fP is the name of the host upon which the +\fIqalter\fP utility is being executed. +.TP 7 +\fB-p\ \fP \fIpriority\fP +Redefine the priority of the batch job. +.LP +The \fIqalter\fP utility shall accept a value for the priority option-argument +that conforms to the syntax for signed decimal +integers, and which is not less than -1024 and not greater than 1023. +.LP +The \fIqalter\fP utility shall set the \fIPriority\fP attribute of +the batch job to the value of the \fIpriority\fP +option-argument. +.TP 7 +\fB-r\ \fP \fBy\fP|\fBn\fP +Redefine whether the batch job is rerunnable. +.LP +If the value of the option-argument is \fB'y'\fP , the \fIqalter\fP +utility shall set the \fIRerunable\fP attribute of the +batch job to TRUE. +.LP +If the value of the option-argument is \fB'n'\fP , the \fIqalter\fP +utility shall set the \fIRerunable\fP attribute of the +batch job to FALSE. +.LP +The \fIqalter\fP utility shall consider it an error if any character +other than \fB'y'\fP or \fB'n'\fP is specified in +the option-argument. +.TP 7 +\fB-S\ \fP \fIpath_name_list\fP +.sp +Redefine the shell that interprets the script at the destination system. +.LP +The \fIqalter\fP utility shall accept a \fIpath_name_list\fP option-argument +that conforms to the following syntax: +.sp +.RS +.nf + +\fBpathname[@host][,pathname[@host],...] +\fP +.fi +.RE +.LP +The \fIqalter\fP utility shall accept only one pathname that is missing +a corresponding host name. The \fIqalter\fP utility +shall allow only one pathname per named host. +.LP +The \fIqalter\fP utility shall add a value to the \fIShell_Path_List\fP +attribute of the batch job for each entry in the +\fIpath_name_list\fP option-argument. See \fIMultiple Keyword-Value +Pairs\fP for a +means of removing \fIkeyword\fP= \fIvalue\fP (and \fIvalue\fP@ \fIkeyword\fP) +pairs and other general rules for list-oriented +batch job attributes. +.TP 7 +\fB-u\ \fP \fIuser_list\fP +Redefine the user name under which the batch job is to run at the +destination system. +.LP +The \fIqalter\fP utility shall accept a \fIuser_list\fP option-argument +that conforms to the following syntax: +.sp +.RS +.nf + +\fBusername[@host][,,username[@host],,...] +\fP +.fi +.RE +.LP +The \fIqalter\fP utility shall accept only one user name that is missing +a corresponding host name. The \fIqalter\fP utility +shall accept only one user name per named host. +.LP +The \fIqalter\fP utility shall add a value to the \fIUser_List\fP +attribute of the batch job for each entry in the +\fIuser_list\fP option-argument. See \fIMultiple Keyword-Value Pairs\fP +for a means of +removing \fIkeyword\fP= \fIvalue\fP (and \fIvalue\fP@ \fIkeyword\fP) +pairs and other general rules for list-oriented batch job +attributes. +.sp +.SH OPERANDS +.LP +The \fIqalter\fP utility shall accept one or more operands that conform +to the syntax for a batch \fIjob_identifier\fP (see \fIBatch Job Identifier\fP +). +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIqalter\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILOGNAME\fP +Determine the login name of the user. +.TP 7 +\fITZ\fP +Determine the timezone used to interpret the \fIdate-time\fP option-argument. +If \fITZ\fP is unset or null, an unspecified +default timezone shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +None. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +In addition to the default behavior, the \fIqalter\fP utility shall +not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates +that the batch \fIjob_identifier\fP does not exist on the +server. Whether or not the \fIqalter\fP utility attempts to locate +the batch job on other batch servers is +implementation-defined. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIqalter\fP utility allows users to change the attributes of +a batch job. +.LP +As a means of altering a queued job, the \fIqalter\fP utility is superior +to deleting and requeuing the batch job insofar as an +altered job retains its place in the queue with some traditional selection +algorithms. In addition, the \fIqalter\fP utility is +both shorter and simpler than a sequence of \fIqdel\fP and \fIqsub\fP +utilities. +.LP +The result of an attempt on the part of a user to alter a batch job +in a RUNNING state is implementation-defined because a batch +job in the RUNNING state will already have opened its output files +and otherwise performed any actions indicated by the options in +effect at the time the batch job began execution. +.LP +The options processed by the \fIqalter\fP utility are identical to +those of the \fIqsub\fP utility, with a few exceptions: \fB-V\fP, +\fB-v\fP, and \fB-q\fP. The \fB-V\fP and +\fB-v\fP are inappropriate for the \fIqalter\fP utility, since they +capture potentially transient environment information from +the submitting process. The \fB-q\fP option would specify a new queue, +which would largely negate the previously stated advantage +of using \fIqalter\fP; furthermore, the \fIqmove\fP utility provides +a superior means of +moving jobs. +.LP +Each of the following paragraphs provides the rationale for a \fIqalter\fP +option. +.LP +Additional rationale concerning these options can be found in the +rationale for the \fIqsub\fP utility. +.LP +The \fB-a\fP option allows users to alter the date and time at which +a batch job becomes eligible to run. +.LP +The \fB-A\fP option allows users to change the account that will be +charged for the resources consumed by the batch job. +Support for the \fB-A\fP option is mandatory for conforming implementations +of \fIqalter\fP, even though support of accounting is +optional for servers. Whether or not to support accounting is left +to the implementor of the server, but mandatory support of the +\fB-A\fP option assures users of a consistent interface and allows +them to control accounting on servers that support +accounting. +.LP +The \fB-c\fP option allows users to alter the checkpointing interval +of a batch job. A checkpointing system, which is not +defined by IEEE\ Std\ 1003.1-2001, allows recovery of a batch job +at the most recent checkpoint in the event of a crash. +Checkpointing is typically used for jobs that consume expensive computing +time or must meet a critical schedule. Users should be +allowed to make the tradeoff between the overhead of checkpointing +and the risk to the timely completion of the batch job; +therefore, this volume of IEEE\ Std\ 1003.1-2001 provides the checkpointing +interval option. Support for checkpointing is +optional for servers. +.LP +The \fB-e\fP option allows users to alter the name and location of +the standard error stream written by a batch job. However, +the path of the standard error stream is meaningless if the value +of the \fIJoin_Path\fP attribute of the batch job is TRUE. +.LP +The \fB-h\fP option allows users to set the hold type in the \fIHold_Types\fP +attribute of a batch job. The \fIqhold\fP and \fIqrls\fP utilities +add or remove hold types +to the \fIHold_Types\fP attribute, respectively. The \fB-h\fP option +has been modified to allow for implementation-defined hold +types. +.LP +The \fB-j\fP option allows users to alter the decision to join (merge) +the standard error stream of the batch job with the +standard output stream of the batch job. +.LP +The \fB-l\fP option allows users to change the resource limits imposed +on a batch job. +.LP +The \fB-m\fP option allows users to modify the list of points in the +life of a batch job at which the designated users will +receive mail notification. +.LP +The \fB-M\fP option allows users to alter the list of users who will +receive notification about events in the life of a batch +job. +.LP +The \fB-N\fP option allows users to change the name of a batch job. +.LP +The \fB-o\fP option allows users to alter the name and path to which +the standard output stream of the batch job will be +written. +.LP +The \fB-P\fP option allows users to modify the priority of a batch +job. Support for priority is optional for batch servers. +.LP +The \fB-r\fP option allows users to alter the rerunability status +of a batch job. +.LP +The \fB-S\fP option allows users to change the name and location of +the shell image that will be invoked to interpret the +script of the batch job. This option has been modified to allow a +list of shell name and locations associated with different +hosts. +.LP +The \fB-u\fP option allows users to change the user identifier under +which the batch job will execute. +.LP +The \fIjob_identifier\fP operand syntax is provided so that the user +can differentiate between the originating and destination +(or executing) batch server. These may or may not be the same. The +\&. \fIserver_name\fP portion identifies the originating batch +server, while the @ \fIserver\fP portion identifies the destination +batch server. +.LP +Historically, the \fIqalter\fP utility has been a component of the +Network Queuing System (NQS), the existing practice from +which this utility has been derived. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIBatch Environment Services\fP , \fIqdel\fP , \fIqhold\fP , \fIqmove\fP +, \fIqrls\fP , \fIqsub\fP , \fItouch\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/qdel.1p b/man1p/qdel.1p new file mode 100644 index 000000000..7f8ae5b13 --- /dev/null +++ b/man1p/qdel.1p @@ -0,0 +1,175 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "QDEL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" qdel +.SH NAME +qdel \- delete batch jobs +.SH SYNOPSIS +.LP +\fBqdel\fP \fIjob_identifier\fP \fB... \fP +.SH DESCRIPTION +.LP +A batch job is deleted by sending a request to the batch server that +manages the batch job. A batch job that has been deleted is +no longer subject to management by batch services. +.LP +The \fIqdel\fP utility is a user-accessible client of batch services +that requests the deletion of one or more batch jobs. +.LP +The \fIqdel\fP utility shall request a batch server to delete those +batch jobs for which a batch \fIjob_identifier\fP is +presented to the utility. +.LP +The \fIqdel\fP utility shall delete batch jobs in the order in which +their batch \fIjob_identifier\fPs are presented to the +utility. +.LP +If the \fIqdel\fP utility fails to process any batch \fIjob_identifier\fP +successfully, the utility shall proceed to process +the remaining batch \fIjob_identifier\fPs, if any. +.LP +The \fIqdel\fP utility shall delete each batch job by sending a \fIDelete +Job Request\fP to the batch server that manages the +batch job. +.LP +The \fIqdel\fP utility shall not exit until the batch job corresponding +to each successfully processed batch +\fIjob_identifier\fP has been deleted. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The \fIqdel\fP utility shall accept one or more operands that conform +to the syntax for a batch \fIjob_identifier\fP (see \fIBatch Job Identifier\fP +). +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIqdel\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILOGNAME\fP +Determine the login name of the user. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +An implementation of the \fIqdel\fP utility may write informative +messages to standard output. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +In addition to the default behavior, the \fIqdel\fP utility shall +not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates +that the batch \fIjob_identifier\fP does not exist on the +server. Whether or not the \fIqdel\fP utility waits to output the +diagnostic message while attempting to locate the job on other +servers is implementation-defined. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIqdel\fP utility allows users and administrators to delete jobs. +.LP +The \fIqdel\fP utility provides functionality that is not otherwise +available. For example, the \fIkill\fP utility of the operating system +does not suffice. First, to use the \fIkill\fP utility, the user might +have to log in on a remote node, because the \fIkill\fP utility does +not operate across the network. Second, unlike \fIqdel\fP, \fIkill\fP +cannot remove jobs from queues. Lastly, the arguments of the \fIqdel\fP +utility are job +identifiers rather than process identifiers, and so this utility can +be passed the output of the \fIqselect\fP utility, thus providing +users with a means of deleting a list of jobs. +.LP +Because a set of jobs can be selected using the \fIqselect\fP utility, +the \fIqdel\fP +utility has not been complicated with options that provide for selection +of jobs. Instead, the batch jobs to be deleted are +identified individually by their job identifiers. +.LP +Historically, the \fIqdel\fP utility has been a component of NQS, +the existing practice on which it is based. However, the +\fIqdel\fP utility defined in this volume of IEEE\ Std\ 1003.1-2001 +does not provide an option for specifying a signal +number to send to the batch job prior to the killing of the process; +that capability has been subsumed by the \fIqsig\fP utility. +.LP +A discussion was held about the delays of networking and the possibility +that the batch server may never respond, due to a down +router, down batch server, or other network mishap. The DESCRIPTION +records this under the words "fails to process any job +identifier". In the broad sense, the network problem is also an error, +which causes the failure to process the batch job +identifier. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIBatch Environment Services\fP , \fIkill\fP() , \fIqselect\fP , +\fIqsig\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/qhold.1p b/man1p/qhold.1p new file mode 100644 index 000000000..c2e1a68d6 --- /dev/null +++ b/man1p/qhold.1p @@ -0,0 +1,230 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "QHOLD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" qhold +.SH NAME +qhold \- hold batch jobs +.SH SYNOPSIS +.LP +\fBqhold\fP \fB[\fP\fB-h\fP \fIhold_list\fP\fB]\fP \fIjob_identifier\fP +\fB\&... \fP +.SH DESCRIPTION +.LP +A hold is placed on a batch job by a request to the batch server that +manages the batch job. A batch job that has one or more +holds is not eligible for execution. The \fIqhold\fP utility is a +user-accessible client of batch services that requests one or +more types of hold to be placed on one or more batch jobs. +.LP +The \fIqhold\fP utility shall place holds on those batch jobs for +which a batch \fIjob_identifier\fP is presented to the +utility. +.LP +The \fIqhold\fP utility shall place holds on batch jobs in the order +in which their batch \fIjob_identifier\fPs are presented +to the utility. If the \fIqhold\fP utility fails to process any batch +\fIjob_identifier\fP successfully, the utility shall +proceed to process the remaining batch \fIjob_identifier\fPs, if any. +.LP +The \fIqhold\fP utility shall place holds on each batch job by sending +a \fIHold Job Request\fP to the batch server that +manages the batch job. +.LP +The \fIqhold\fP utility shall not exit until holds have been placed +on the batch job corresponding to each successfully +processed batch \fIjob_identifier\fP. +.SH OPTIONS +.LP +The \fIqhold\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported by the implementation: +.TP 7 +\fB-h\ \fP \fIhold_list\fP +Define the types of holds to be placed on the batch job. +.LP +The \fIqhold\fP \fB-h\fP option shall accept a value for the \fIhold_list\fP +option-argument that is a string of alphanumeric +characters in the portable character set (see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable Character +Set). +.LP +The \fIqhold\fP utility shall accept a value for the \fIhold_list\fP +option-argument that is a string of one or more of the +characters \fB'u'\fP , \fB's'\fP , or \fB'o'\fP , or the single character +\fB'n'\fP . +.LP +For each unique character in the \fIhold_list\fP option-argument, +the \fIqhold\fP utility shall add a value to the +\fIHold_Types\fP attribute of the batch job as follows, each representing +a different hold type: +.TP 7 +\fBu\fP +.RS +USER +.RE +.TP 7 +\fBs\fP +.RS +SYSTEM +.RE +.TP 7 +\fBo\fP +.RS +OPERATOR +.RE +.sp +.LP +If any of these characters are duplicated in the \fIhold_list\fP option-argument, +the duplicates shall be ignored. +.LP +An existing \fIHold_Types\fP attribute can be cleared by the following +hold type: +.TP 7 +\fBn\fP +.RS +NO_HOLD +.RE +.sp +.LP +The \fIqhold\fP utility shall consider it an error if any hold type +other than \fB'n'\fP is combined with hold type +\fB'n'\fP . +.LP +Strictly conforming applications shall not repeat any of the characters +\fB'u'\fP , \fB's'\fP , \fB'o'\fP , or +\fB'n'\fP within the \fIhold_list\fP option-argument. The \fIqhold\fP +utility shall permit the repetition of characters, but +shall not assign additional meaning to the repeated characters. +.LP +An implementation may define other hold types. The conformance document +for an implementation shall describe any additional hold +types, how they are specified, their internal behavior, and how they +affect the behavior of the utility. +.LP +If the \fB-h\fP option is not presented to the \fIqhold\fP utility, +the implementation shall set the \fIHold_Types\fP +attribute to USER. +.sp +.SH OPERANDS +.LP +The \fIqhold\fP utility shall accept one or more operands that conform +to the syntax for a batch \fIjob_identifier\fP (see \fIBatch Job Identifier\fP +). +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIqhold\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILOGNAME\fP +Determine the login name of the user. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +None. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +In addition to the default behavior, the \fIqhold\fP utility shall +not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates +that the batch \fIjob_identifier\fP does not exist on the +server. Whether or not the \fIqhold\fP utility waits to output the +diagnostic message while attempting to locate the job on other +servers is implementation-defined. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIqhold\fP utility allows users to place a hold on one or more +jobs. A hold makes a batch job ineligible for +execution. +.LP +The \fIqhold\fP utility has options that allow the user to specify +the type of hold. Should the user wish to place a hold on a +set of jobs that meet a selection criteria, such a list of jobs can +be acquired using the \fIqselect\fP utility. +.LP +The \fB-h\fP option allows the user to specify the type of hold that +is to be placed on the job. This option allows for USER, +SYSTEM, OPERATOR, and implementation-defined hold types. The USER +and OPERATOR holds are distinct. The batch server that manages +the batch job will verify that the user is authorized to set the specified +hold for the batch job. +.LP +Mail is not required on hold because the administrator has the tools +and libraries to build this option if he or she wishes. +.LP +Historically, the \fIqhold\fP utility has been a part of some existing +batch systems, although it has not traditionally been a +part of the NQS. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIBatch Environment Services\fP , \fIqselect\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/qmove.1p b/man1p/qmove.1p new file mode 100644 index 000000000..557ff9b6f --- /dev/null +++ b/man1p/qmove.1p @@ -0,0 +1,154 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "QMOVE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" qmove +.SH NAME +qmove \- move batch jobs +.SH SYNOPSIS +.LP +\fBqmove\fP \fIdestination job_identifier\fP \fB... \fP +.SH DESCRIPTION +.LP +To move a batch job is to remove the batch job from the batch queue +in which it resides and instantiate the batch job in another +batch queue. A batch job is moved by a request to the batch server +that manages the batch job. The \fIqmove\fP utility is a +user-accessible batch client that requests the movement of one or +more batch jobs. +.LP +The \fIqmove\fP utility shall move those batch jobs, and only those +batch jobs, for which a batch \fIjob_identifier\fP is +presented to the utility. +.LP +The \fIqmove\fP utility shall move batch jobs in the order in which +the corresponding batch \fIjob_identifier\fPs are +presented to the utility. +.LP +If the \fIqmove\fP utility fails to process a batch \fIjob_identifier\fP +successfully, the utility shall proceed to process +the remaining batch \fIjob_identifier\fPs, if any. +.LP +The \fIqmove\fP utility shall move batch jobs by sending a \fIMove +Job Request\fP to the batch server that manages each batch +job. The \fIqmove\fP utility shall not exit before the batch jobs +corresponding to all successfully processed batch +\fIjob_identifier\fPs have been moved. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The \fIqmove\fP utility shall accept one operand that conforms to +the syntax for a destination (see \fIDestination\fP ). +.LP +The \fIqmove\fP utility shall accept one or more operands that conform +to the syntax for a batch \fIjob_identifier\fP (see \fIBatch Job Identifier\fP +). +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIqmove\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILOGNAME\fP +Determine the login name of the user. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +None. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +In addition to the default behavior, the \fIqmove\fP utility shall +not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates +that the batch \fIjob_identifier\fP does not exist on the +server. Whether or not the \fIqmove\fP utility waits to output the +diagnostic message while attempting to locate the job on other +servers is implementation-defined. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIqmove\fP utility allows users to move jobs between queues. +.LP +The alternative to using the \fIqmove\fP utility-deleting the batch +job and requeuing it-entails considerably more typing. +.LP +Since the means of selecting jobs based on attributes has been encapsulated +in the \fIqselect\fP utility, the only option of the \fIqmove\fP utility +concerns authorization. The +\fB-u\fP option provides the user with the convenience of changing +the user identifier under which the batch job will execute. +Minimalism and consistency have taken precedence over convenience; +the \fB-u\fP option has been deleted because the equivalent +capability exists with the \fB-u\fP option of the \fIqalter\fP utility. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIBatch Environment Services\fP , \fIqalter\fP , \fIqselect\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/qmsg.1p b/man1p/qmsg.1p new file mode 100644 index 000000000..f0e6b2a48 --- /dev/null +++ b/man1p/qmsg.1p @@ -0,0 +1,214 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "QMSG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" qmsg +.SH NAME +qmsg \- send message to batch jobs +.SH SYNOPSIS +.LP +\fBqmsg\fP \fB[\fP\fB-E\fP\fB][\fP\fB-O\fP\fB]\fP \fImessage_string +job_identifier\fP \fB... +\fP +.SH DESCRIPTION +.LP +To send a message to a batch job is to request that a server write +a message string into one or more output files of the batch +job. A message is sent to a batch job by a request to the batch server +that manages the batch job. The \fIqmsg\fP utility is a +user-accessible batch client that requests the sending of messages +to one or more batch jobs. +.LP +The \fIqmsg\fP utility shall write messages into the files of batch +jobs by sending a \fIJob Message Request\fP to the batch +server that manages the batch job. The \fIqmsg\fP utility shall not +directly write the message into the files of the batch +job. +.LP +The \fIqmsg\fP utility shall send a \fIJob Message Request\fP for +those batch jobs, and only those batch jobs, for which a +batch \fIjob_identifier\fP is presented to the utility. +.LP +The \fIqmsg\fP utility shall send \fIJob Message Request\fPs for batch +jobs in the order in which their batch +\fIjob_identifier\fPs are presented to the utility. +.LP +If the \fIqmsg\fP utility fails to process any batch \fIjob_identifier\fP +successfully, the utility shall proceed to process +the remaining batch \fIjob_identifier\fPs, if any. +.LP +The \fIqmsg\fP utility shall not exit before a \fIJob Message Request\fP +has been sent to the server that manages the batch +job that corresponds to each successfully processed batch \fIjob_identifier\fP. +.SH OPTIONS +.LP +The \fIqmsg\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported by the implementation: +.TP 7 +\fB-E\fP +Specify that the message is written to the standard error of each +batch job. +.LP +The \fIqmsg\fP utility shall write the message into the standard error +of the batch job. +.TP 7 +\fB-O\fP +Specify that the message is written to the standard output of each +batch job. +.LP +The \fIqmsg\fP utility shall write the message into the standard output +of the batch job. +.sp +.LP +If neither the \fB-O\fP nor the \fB-E\fP option is presented to the +\fIqmsg\fP utility, the utility shall write the message +into an implementation-defined file. The conformance document for +the implementation shall describe the name and location of the +implementation-defined file. If both the \fB-O\fP and the \fB-E\fP +options are presented to the \fIqmsg\fP utility, then the +utility shall write the messages to both standard output and standard +error. +.SH OPERANDS +.LP +The \fIqmsg\fP utility shall accept a minimum of two operands, \fImessage_string\fP +and one or more batch +\fIjob_identifier\fPs. +.LP +The \fImessage_string\fP operand shall be the string to be written +to one or more output files of the batch job followed by a +. If the string contains s, then the application shall +ensure that the string is quoted. The +\fImessage_string\fP shall be encoded in the portable character set +(see the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 6.1, Portable Character Set). +.LP +All remaining operands are batch \fIjob_identifier\fPs that conform +to the syntax for a batch \fIjob_identifier\fP (see \fIBatch Job Identifier\fP +). +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIqmsg\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILOGNAME\fP +Determine the login name of the user. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +None. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +In addition to the default behavior, the \fIqmsg\fP utility shall +not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates +that the batch \fIjob_identifier\fP does not exist on the +server. Whether or not the \fIqmsg\fP utility waits to output the +diagnostic message while attempting to locate the job on other +servers is implementation-defined. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIqmsg\fP utility allows users to write messages into the output +files of running jobs. Users, including operators and +administrators, have a number of occasions when they want to place +messages in the output files of a batch job. For example, if a +disk that is being used by a batch job is showing errors, the operator +might note this in the standard error stream of the batch +job. +.LP +The options of the \fIqmsg\fP utility provide users with the means +of placing the message in the output stream of their choice. +The default output stream for the message-if the user does not designate +an output stream-is implementation-defined, since many +implementations will provide, as an extension to this volume of IEEE\ Std\ 1003.1-2001, +a log file that shows the history +of utility execution. +.LP +If users wish to send a message to a set of jobs that meet a selection +criteria, the \fIqselect\fP utility can be used to acquire the appropriate +list of job identifiers. +.LP +The \fB-E\fP option allows users to place the message in the standard +error stream of the batch job. +.LP +The \fB-O\fP option allows users to place the message in the standard +output stream of the batch job. +.LP +Historically, the \fIqmsg\fP utility is an existing practice in the +offerings of one or more implementors of an NQS-derived +batch system. The utility has been found to be useful enough that +it deserves to be included in this volume of +IEEE\ Std\ 1003.1-2001. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIBatch Environment Services\fP , \fIqselect\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/qrerun.1p b/man1p/qrerun.1p new file mode 100644 index 000000000..68ca6e697 --- /dev/null +++ b/man1p/qrerun.1p @@ -0,0 +1,146 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "QRERUN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" qrerun +.SH NAME +qrerun \- rerun batch jobs +.SH SYNOPSIS +.LP +\fBqrerun\fP \fIjob_identifier\fP \fB... \fP +.SH DESCRIPTION +.LP +To rerun a batch job is to terminate the session leader of the batch +job, delete any associated checkpoint files, and return the +batch job to the batch queued state. A batch job is rerun by a request +to the batch server that manages the batch job. The +\fIqrerun\fP utility is a user-accessible batch client that requests +the rerunning of one or more batch jobs. +.LP +The \fIqrerun\fP utility shall rerun those batch jobs for which a +batch \fIjob_identifier\fP is presented to the utility. +.LP +The \fIqrerun\fP utility shall rerun batch jobs in the order in which +their batch \fIjob_identifier\fPs are presented to the +utility. +.LP +If the \fIqrerun\fP utility fails to process any batch \fIjob_identifier\fP +successfully, the utility shall proceed to process +the remaining batch \fIjob_identifier\fPs, if any. +.LP +The \fIqrerun\fP utility shall rerun batch jobs by sending a \fIRerun +Job Request\fP to the batch server that manages each +batch job. +.LP +For each successfully processed batch \fIjob_identifier\fP, the \fIqrerun\fP +utility shall have rerun the corresponding batch +job at the time the utility exits. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The \fIqrerun\fP utility shall accept one or more operands that conform +to the syntax for a batch \fIjob_identifier\fP (see \fIBatch Job Identifier\fP +). +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIqrerun\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILOGNAME\fP +Determine the login name of the user. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +None. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +In addition to the default behavior, the \fIqrerun\fP utility shall +not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates +that the batch \fIjob_identifier\fP does not exist on the +server. Whether or not the \fIqrerun\fP utility waits to output the +diagnostic message while attempting to locate the job on other +servers is implementation-defined. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIqrerun\fP utility allows users to cause jobs in the running +state to exit and rerun. +.LP +The \fIqrerun\fP utility is a new utility, \fIvis-a-vis\fP existing +practice, that has been defined in this volume of +IEEE\ Std\ 1003.1-2001 to correct user-perceived deficiencies in the +existing practice. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIBatch Environment Services\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/qrls.1p b/man1p/qrls.1p new file mode 100644 index 000000000..615356104 --- /dev/null +++ b/man1p/qrls.1p @@ -0,0 +1,236 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "QRLS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" qrls +.SH NAME +qrls \- release batch jobs +.SH SYNOPSIS +.LP +\fBqrls\fP \fB[\fP\fB-h\fP \fIhold_list\fP\fB]\fP \fIjob_identifier\fP +\fB\&... \fP +.SH DESCRIPTION +.LP +A batch job might have one or more holds, which prevent the batch +job from executing. A batch job from which all the holds have +been removed becomes eligible for execution and is said to have been +released. A batch job hold is removed by sending a request to +the batch server that manages the batch job. The \fIqrls\fP utility +is a user-accessible client of batch services that requests +holds be removed from one or more batch jobs. +.LP +The \fIqrls\fP utility shall remove one or more holds from those batch +jobs for which a batch \fIjob_identifier\fP is +presented to the utility. +.LP +The \fIqrls\fP utility shall remove holds from batch jobs in the order +in which their batch \fIjob_identifier\fPs are +presented to the utility. +.LP +If the \fIqrls\fP utility fails to process a batch \fIjob_identifier\fP +successfully, the utility shall proceed to process the +remaining batch \fIjob_identifier\fPs, if any. +.LP +The \fIqrls\fP utility shall remove holds on each batch job by sending +a \fIRelease Job Request\fP to the batch server that +manages the batch job. +.LP +The \fIqrls\fP utility shall not exit until the holds have been removed +from the batch job corresponding to each successfully +processed batch \fIjob_identifier\fP. +.SH OPTIONS +.LP +The \fIqrls\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported by the implementation: +.TP 7 +\fB-h\ \fP \fIhold_list\fP +Define the types of holds to be removed from the batch job. +.LP +The \fIqrls\fP \fB-h\fP option shall accept a value for the \fIhold_list\fP +option-argument that is a string of alphanumeric +characters in the portable character set (see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable Character +Set). +.LP +The \fIqrls\fP utility shall accept a value for the \fIhold_list\fP +option-argument that is a string of one or more of the +characters \fB'u'\fP , \fB's'\fP , or \fB'o'\fP , or the single character +\fB'n'\fP . +.LP +For each unique character in the \fIhold_list\fP option-argument, +the \fIqrls\fP utility shall add a value to the +\fIHold_Types\fP attribute of the batch job as follows, each representing +a different hold type: +.TP 7 +\fBu\fP +.RS +USER +.RE +.TP 7 +\fBs\fP +.RS +SYSTEM +.RE +.TP 7 +\fBo\fP +.RS +OPERATOR +.RE +.sp +.LP +If any of these characters are duplicated in the \fIhold_list\fP option-argument, +the duplicates shall be ignored. +.LP +An existing \fIHold_Types\fP attribute can be cleared by the following +hold type: +.TP 7 +\fBn\fP +.RS +NO_HOLD +.RE +.sp +.LP +The \fIqrls\fP utility shall consider it an error if any hold type +other than \fB'n'\fP is combined with hold type +\fB'n'\fP . +.LP +Strictly conforming applications shall not repeat any of the characters +\fB'u'\fP , \fB's'\fP , \fB'o'\fP , or +\fB'n'\fP within the \fIhold_list\fP option-argument. The \fIqrls\fP +utility shall permit the repetition of characters, but +shall not assign additional meaning to the repeated characters. +.LP +An implementation may define other hold types. The conformance document +for an implementation shall describe any additional hold +types, how they are specified, their internal behavior, and how they +affect the behavior of the utility. +.LP +If the \fB-h\fP option is not presented to the \fIqrls\fP utility, +the implementation shall remove the USER hold in the +\fIHold_Types\fP attribute. +.sp +.SH OPERANDS +.LP +The \fIqrls\fP utility shall accept one or more operands that conform +to the syntax for a batch \fIjob_identifier\fP (see \fIBatch Job Identifier\fP +). +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIqrls\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILOGNAME\fP +Determine the login name of the user. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +None. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +In addition to the default behavior, the \fIqrls\fP utility shall +not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates +that the batch \fIjob_identifier\fP does not exist on the +server. Whether or not the \fIqrls\fP utility waits to output the +diagnostic message while attempting to locate the job on other +servers is implementation-defined. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIqrls\fP utility allows users, operators, and administrators +to remove holds from jobs. +.LP +The \fIqrls\fP utility does not support any job selection options +or wildcard arguments. Users may acquire a list of jobs +selected by attributes using the \fIqselect\fP utility. For example, +a user could select +all of their held jobs. +.LP +The \fB-h\fP option allows the user to specify the type of hold that +is to be removed. This option allows for USER, SYSTEM, +OPERATOR, and implementation-defined hold types. The batch server +that manages the batch job will verify whether the user is +authorized to remove the specified hold for the batch job. If more +than one type of hold has been placed on the batch job, a user +may wish to remove only some of them. +.LP +Mail is not required on release because the administrator has the +tools and libraries to build this option if required. +.LP +The \fIqrls\fP utility is a new utility \fIvis-a-vis\fP existing practice; +it has been defined in this volume of +IEEE\ Std\ 1003.1-2001 as the natural complement to the \fIqhold\fP +utility. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIBatch Environment Services\fP , \fIqhold\fP , \fIqselect\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/qselect.1p b/man1p/qselect.1p new file mode 100644 index 000000000..673cdf744 --- /dev/null +++ b/man1p/qselect.1p @@ -0,0 +1,763 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "QSELECT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" qselect +.SH NAME +qselect \- select batch jobs +.SH SYNOPSIS +.LP +\fBqselect\fP \fB[\fP\fB-a\fP \fB[\fP\fIop\fP\fB]\fP\fIdate_time\fP\fB][\fP\fB-A\fP +\fIaccount_string\fP\fB][\fP\fB-c\fP \fB[\fP\fIop\fP\fB]\fP\fIinterval\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-h\fP \fIhold_list\fP\fB][\fP\fB-l\fP +\fIresource_list\fP\fB][\fP\fB-N\fP \fIname\fP\fB][\fP\fB-p\fP \fB[\fP\fIop\fP\fB]\fP\fIpriority\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-q\fP \fIdestination\fP\fB][\fP\fB-r\fP +\fIy\fP\fB|\fP\fIn\fP\fB][\fP\fB-s\fP \fIstates\fP\fB][\fP\fB-u\fP +\fIuser_list\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +To select a set of batch jobs is to return the batch \fIjob_identifier\fPs +for each batch job that meets a list of selection +criteria. A set of batch jobs is selected by a request to a batch +server. The \fIqselect\fP utility is a user-accessible batch +client that requests the selection of batch jobs. +.LP +Upon successful completion, the \fIqselect\fP utility shall have returned +a list of zero or more batch \fIjob_identifier\fPs +that meet the criteria specified by the options and option-arguments +presented to the utility. +.LP +The \fIqselect\fP utility shall select batch jobs by sending a \fISelect +Jobs Request\fP to a batch server. The \fIqselect\fP +utility shall not exit until the server replies to each request generated. +.LP +For each option presented to the \fIqselect\fP utility, the utility +shall restrict the set of selected batch jobs as described +in the OPTIONS section. +.LP +The \fIqselect\fP utility shall not restrict selection of batch jobs +except by authorization and as required by the options +presented to the utility. +.LP +When an option is specified with a mandatory or optional \fIop\fP +component to the option-argument, then \fIop\fP shall +specify a relation between the value of a certain batch job attribute +and the \fIvalue\fP component of the option-argument. If an +\fIop\fP is allowable on an option, then the description of the option +letter indicates the \fIop\fP as either mandatory or +optional. Acceptable strings for the \fIop\fP component, and the relation +the string indicates, are shown in the following +list: +.TP 7 +\fB\&.eq.\fP +The value represented by the attribute of the batch job is equal to +the value represented by the option-argument. +.TP 7 +\fB\&.ge.\fP +The value represented by the attribute of the batch job is greater +than or equal to the value represented by the +option-argument. +.TP 7 +\fB\&.gt.\fP +The value represented by the attribute of the batch job is greater +than the value represented by the option-argument. +.TP 7 +\fB\&.lt.\fP +The value represented by the attribute of the batch job is less than +the value represented by the option-argument. +.TP 7 +\fB\&.le.\fP +The value represented by the attribute of the batch job is less than +or equal to the value represented by the +option-argument. +.TP 7 +\fB\&.ne.\fP +The value represented by the attribute of the batch job is not equal +to the value represented by the option-argument. +.sp +.SH OPTIONS +.LP +The \fIqselect\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported by the implementation: +.TP 7 +\fB-a\ [\fP\fIop\fP\fB]\fP\fIdate_time\fP +.sp +Restrict selection to a specific time, or a range of times. +.LP +The \fIqselect\fP utility shall select only batch jobs for which the +value of the \fIExecution_Time\fP attribute is related to +the Epoch equivalent of the local time expressed by the value of the +\fIdate_time\fP component of the option-argument in the +manner indicated by the value of the \fIop\fP component of the option-argument. +.LP +The \fIqselect\fP utility shall accept a \fIdate_time\fP component +of the option-argument that conforms to the syntax of the +\fItime\fP operand of the \fItouch\fP utility. +.LP +If the \fIop\fP component of the option-argument is not presented +to the \fIqselect\fP utility, the utility shall select batch +jobs for which the \fIExecution_Time\fP attribute is equal to the +\fIdate_time\fP component of the option-argument. +.LP +When comparing times, the \fIqselect\fP utility shall use the following +definitions for the \fIop\fP component of the +option-argument: +.TP 7 +\fB\&.eq.\fP +.RS +The time represented by value of the \fIExecution_Time\fP attribute +of the batch job is equal to the time represented by the +\fIdate_time\fP component of the option-argument. +.RE +.TP 7 +\fB\&.ge.\fP +.RS +The time represented by value of the \fIExecution_Time\fP attribute +of the batch job is after or equal to the time represented +by the \fIdate_time\fP component of the option-argument. +.RE +.TP 7 +\fB\&.gt.\fP +.RS +The time represented by value of the \fIExecution_Time\fP attribute +of the batch job is after the time represented by the +\fIdate_time\fP component of the option-argument. +.RE +.TP 7 +\fB\&.lt.\fP +.RS +The time represented by value of the \fIExecution_Time\fP attribute +of the batch job is before the time represented by the +\fIdate_time\fP component of the option-argument. +.RE +.TP 7 +\fB\&.le.\fP +.RS +The time represented by value of the \fIExecution_Time\fP attribute +of the batch job is before or equal to the time +represented by the \fIdate_time\fP component of the option-argument. +.RE +.TP 7 +\fB\&.ne.\fP +.RS +The time represented by value of the \fIExecution_Time\fP attribute +of the batch job is not equal to the time represented by +the \fIdate_time\fP component of the option-argument. +.RE +.sp +.LP +The \fIqselect\fP utility shall accept the defined character strings +for the \fIop\fP component of the option-argument. +.TP 7 +\fB-A\ \fP \fIaccount_string\fP +.sp +Restrict selection to the batch jobs charging a specified account. +.LP +The \fIqselect\fP utility shall select only batch jobs for which the +value of the \fIAccount_Name\fP attribute of the batch +job matchs the value of the \fIaccount_string\fP option-argument. +.LP +The syntax of the \fIaccount_string\fP option-argument is unspecified. +.TP 7 +\fB-c\ [\fP\fIop\fP\fB]\fP\fIinterval\fP +.sp +Restrict selection to batch jobs within a range of checkpoint intervals. +.LP +The \fIqselect\fP utility shall select only batch jobs for which the +value of the \fICheckpoint\fP attribute relates to the +value of the \fIinterval\fP component of the option-argument in the +manner indicated by the value of the \fIop\fP component of +the option-argument. +.LP +If the \fIop\fP component of the option-argument is omitted, the \fIqselect\fP +utility shall select batch jobs for which the +value of the \fICheckpoint\fP attribute is equal to the value of the +\fIinterval\fP component of the option-argument. +.LP +When comparing checkpoint intervals, the \fIqselect\fP utility shall +use the following definitions for the \fIop\fP component +of the option-argument: +.TP 7 +\fB\&.eq.\fP +.RS +The value of the \fICheckpoint\fP attribute of the batch job equals +the value of the \fIinterval\fP component of the +option-argument. +.RE +.TP 7 +\fB\&.ge.\fP +.RS +The value of the \fICheckpoint\fP attribute of the batch job is greater +than or equal to the value of the \fIinterval\fP +component option-argument. +.RE +.TP 7 +\fB\&.gt.\fP +.RS +The value of the \fICheckpoint\fP attribute of the batch job is greater +than the value of the \fIinterval\fP component +option-argument. +.RE +.TP 7 +\fB\&.lt.\fP +.RS +The value of the \fICheckpoint\fP attribute of the batch job is less +than the value of the \fIinterval\fP component +option-argument. +.RE +.TP 7 +\fB\&.le.\fP +.RS +The value of the \fICheckpoint\fP attribute of the batch job is less +than or equal to the value of the \fIinterval\fP +component option-argument. +.RE +.TP 7 +\fB\&.ne.\fP +.RS +The value of the \fICheckpoint\fP attribute of the batch job does +not equal the value of the \fIinterval\fP component +option-argument. +.RE +.sp +.LP +The \fIqselect\fP utility shall accept the defined character strings +for the \fIop\fP component of the option-argument. +.LP +The ordering relationship for the values of the interval option-argument +is defined to be: +.sp +.RS +.nf + +\fB`n' .gt. `s' .gt. `c=\fP\fIminutes\fP\fB' .ge. `c' +\fP +.fi +.RE +When comparing \fICheckpoint\fP attributes with an interval having +the value of the single character \fB'u'\fP , only equality +or inequality are valid comparisons. +.TP 7 +\fB-h\ \fP \fIhold_list\fP +Restrict selection to batch jobs that have a specific type of hold. +.LP +The \fIqselect\fP utility shall select only batch jobs for which the +value of the \fIHold_Types\fP attribute matches the value +of the \fIhold_list\fP option-argument. +.LP +The \fIqselect\fP \fB-h\fP option shall accept a value for the \fIhold_list\fP +option-argument that is a string of +alphanumeric characters in the portable character set (see the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable +Character Set). +.LP +The \fIqselect\fP utility shall accept a value for the \fIhold_list\fP +option-argument that is a string of one or more of the +characters \fB'u'\fP , \fB's'\fP , or \fB'o'\fP , or the single character +\fB'n'\fP . +.LP +Each unique character in the \fIhold_list\fP option-argument of the +\fIqselect\fP utility is defined as follows, each +representing a different hold type: +.TP 7 +\fBu\fP +.RS +USER +.RE +.TP 7 +\fBs\fP +.RS +SYSTEM +.RE +.TP 7 +\fBo\fP +.RS +OPERATOR +.RE +.sp +.LP +If any of these characters are duplicated in the \fIhold_list\fP option-argument, +the duplicates shall be ignored. +.LP +The \fIqselect\fP utility shall consider it an error if any hold type +other than \fB'n'\fP is combined with hold type +\fB'n'\fP . +.LP +Strictly conforming applications shall not repeat any of the characters +\fB'u'\fP , \fB's'\fP , \fB'o'\fP , or +\fB'n'\fP within the \fIhold_list\fP option-argument. The \fIqselect\fP +utility shall permit the repetition of characters, but +shall not assign additional meaning to the repeated characters. +.LP +An implementation may define other hold types. The conformance document +for an implementation shall describe any additional hold +types, how they are specified, their internal behavior, and how they +affect the behavior of the utility. +.TP 7 +\fB-l\ \fP \fIresource_list\fP +.sp +Restrict selection to batch jobs with specified resource limits and +attributes. +.LP +The \fIqselect\fP utility shall accept a \fIresource_list\fP option-argument +with the following syntax: +.sp +.RS +.nf + +\fIresource_name op value\fP \fB[\fP\fB,,\fP\fIresource_name op value\fP\fB,, ...\fP\fB]\fP +.fi +.RE +.LP +When comparing resource values, the \fIqselect\fP utility shall use +the following definitions for the \fIop\fP component of +the option-argument: +.TP 7 +\fB\&.eq.\fP +.RS +The value of the resource of the same name in the \fIResource_List\fP +attribute of the batch job equals the value of the value +component of the option-argument. +.RE +.TP 7 +\fB\&.ge.\fP +.RS +The value of the resource of the same name in the \fIResource_List\fP +attribute of the batch job is greater than or equal to +the value of the \fIvalue\fP component of the option-argument. +.RE +.TP 7 +\fB\&.gt.\fP +.RS +The value of the resource of the same name in the \fIResource_List\fP +attribute of the batch job is greater than the value of +the value component of the option-argument. +.RE +.TP 7 +\fB\&.lt.\fP +.RS +The value of the resource of the same name in the \fIResource_List\fP +attribute of the batch job is less than the value of the +value component of the option-argument. +.RE +.TP 7 +\fB\&.ne.\fP +.RS +The value of the resource of the same name in the \fIResource_List\fP +attribute of the batch job does not equal the value of +the value component of the option-argument. +.RE +.TP 7 +\fB\&.le.\fP +.RS +The value of the resource of the same name in the \fIResource_List\fP +attribute of the batch job is less than or equal to the +value of the \fIvalue\fP component of the option-argument. +.RE +.sp +.LP +When comparing the limit of a \fIResource_List\fP attribute with the +\fIvalue\fP component of the option-argument, if the +limit, the value, or both are non-numeric, only equality or inequality +are valid comparisons. +.LP +The \fIqselect\fP utility shall select only batch jobs for which the +values of the \fIresource_name\fPs listed in the +\fIresource_list\fP option-argument match the corresponding limits +of the \fIResource_List\fP attribute of the batch job. +.LP +Limits of \fIresource_name\fPs present in the \fIResource_List\fP +attribute of the batch job that have no corresponding values +in the \fIresource_list\fP option-argument shall not be considered +when selecting batch jobs. +.TP 7 +\fB-N\ \fP \fIname\fP +Restrict selection to batch jobs with a specified name. +.LP +The \fIqselect\fP utility shall select only batch jobs for which the +value of the \fIJob_Name\fP attribute matches the value +of the \fIname\fP option-argument. The string specified in the \fIname\fP +option-argument shall be passed, uninterpreted, to the +server. This allows an implementation to match "wildcard" patterns +against batch job names. +.LP +An implementation shall describe in the conformance document the format +it supports for matching against the \fIJob_Name\fP +attribute. +.TP 7 +\fB-p\ [\fP\fIop\fP\fB]\fP\fIpriority\fP +.sp +Restrict selection to batch jobs of the specified priority or range +of priorities. +.LP +The \fIqselect\fP utility shall select only batch jobs for which the +value of the \fIPriority\fP attribute of the batch job +relates to the value of the \fIpriority\fP component of the option-argument +in the manner indicated by the value of the \fIop\fP +component of the option-argument. +.LP +If the \fIop\fP component of the option-argument is omitted, the \fIqselect\fP +utility shall select batch jobs for which the +value of the \fIPriority\fP attribute of the batch job is equal to +the value of the \fIpriority\fP component of the +option-argument. +.LP +When comparing priority values, the \fIqselect\fP utility shall use +the following definitions for the \fIop\fP component of +the option-argument: +.TP 7 +\fB\&.eq.\fP +.RS +The value of the \fIPriority\fP attribute of the batch job equals +the value of the \fIpriority\fP component of the +option-argument. +.RE +.TP 7 +\fB\&.ge.\fP +.RS +The value of the \fIPriority\fP attribute of the batch job is greater +than or equal to the value of the \fIpriority\fP +component option-argument. +.RE +.TP 7 +\fB\&.gt.\fP +.RS +The value of the \fIPriority\fP attribute of the batch job is greater +than the value of the \fIpriority\fP component +option-argument. +.RE +.TP 7 +\fB\&.lt.\fP +.RS +The value of the \fIPriority\fP attribute of the batch job is less +than the value of the \fIpriority\fP component +option-argument. +.RE +.TP 7 +\fB\&.lt.\fP +.RS +The value of the \fIPriority\fP attribute of the batch job is less +than or equal to the value of the \fIpriority\fP component +option-argument. +.RE +.TP 7 +\fB\&.ne.\fP +.RS +The value of the \fIPriority\fP attribute of the batch job does not +equal the value of the \fIpriority\fP component +option-argument. +.RE +.sp +.TP 7 +\fB-q\ \fP \fIdestination\fP +.sp +Restrict selection to the specified batch queue or server, or both. +.LP +The \fIqselect\fP utility shall select only batch jobs that are located +at the destination indicated by the value of the +\fIdestination\fP option-argument. +.LP +The destination defines a batch queue, a server, or a batch queue +at a server. +.LP +The \fIqselect\fP utility shall accept an option-argument for the +\fB-q\fP option that conforms to the syntax for a +destination. If the \fB-q\fP option is not presented to the \fIqselect\fP +utility, the utility shall select batch jobs from all +batch queues at the default batch server. +.LP +If the option-argument describes only a batch queue, the \fIqselect\fP +utility shall select only batch jobs from the batch +queue of the specified name at the default batch server. The means +by which \fIqselect\fP determines the default server is +implementation-defined. +.LP +If the option-argument describes only a batch server, the \fIqselect\fP +utility shall select batch jobs from all the batch +queues at that batch server. +.LP +If the option-argument describes both a batch queue and a batch server, +the \fIqselect\fP utility shall select only batch jobs +from the specified batch queue at the specified server. +.TP 7 +\fB-r\ \fP \fBy\fP|\fBn\fP +Restrict selection to batch jobs with the specified rerunability status. +.LP +The \fIqselect\fP utility shall select only batch jobs for which the +value of the \fIRerunable\fP attribute of the batch job +matches the value of the option-argument. +.LP +The \fIqselect\fP utility shall accept a value for the option-argument +that consists of either the single character +\fB'y'\fP or the single character \fB'n'\fP . The character \fB'y'\fP +represents the value TRUE, and the character +\fB'n'\fP represents the value FALSE. +.TP 7 +\fB-s\ \fP \fIstates\fP +Restrict selection to batch jobs in the specified states. +.LP +The \fIqselect\fP utility shall accept an option-argument that consists +of any combination of the characters \fB'e'\fP , +\fB'q'\fP , \fB'r'\fP , \fB'w'\fP , \fB'h'\fP , and \fB't'\fP . +.LP +Conforming applications shall not repeat any character in the option-argument. +The \fIqselect\fP utility shall permit the +repetition of characters in the option-argument, but shall not assign +additional meaning to repeated characters. +.LP +The \fIqselect\fP utility shall interpret the characters in the \fIstates\fP +option-argument as follows: +.TP 7 +\fBe\fP +.RS +Represents the EXITING state. +.RE +.TP 7 +\fBq\fP +.RS +Represents the QUEUED state. +.RE +.TP 7 +\fBr\fP +.RS +Represents the RUNNING state. +.RE +.TP 7 +\fBt\fP +.RS +Represents the TRANSITING state. +.RE +.TP 7 +\fBh\fP +.RS +Represents the HELD state. +.RE +.TP 7 +\fBw\fP +.RS +Represents the WAITING state. +.RE +.sp +.LP +For each character in the \fIstates\fP option-argument, the \fIqselect\fP +utility shall select batch jobs in the corresponding +state. +.TP 7 +\fB-u\ \fP \fIuser_list\fP +Restrict selection to batch jobs owned by the specified user names. +.LP +The \fIqselect\fP utility shall select only the batch jobs of those +users specified in the \fIuser_list\fP +option-argument. +.LP +The \fIqselect\fP utility shall accept a \fIuser_list\fP option-argument +that conforms to the following syntax: +.sp +.RS +.nf + +\fIusername\fP\fB[\fP\fB@\fP\fIhost\fP\fB][\fP\fB,,\fP\fIusername\fP\fB[\fP\fB@\fP\fIhost\fP\fB]\fP\fB,, ...\fP\fB]\fP +.fi +.RE +.LP +The \fIqselect\fP utility shall accept only one user name that is +missing a corresponding host name. The \fIqselect\fP utility +shall accept only one user name per named host. +.sp +.SH OPERANDS +.LP +None. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIqselect\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILOGNAME\fP +Determine the login name of the user. +.TP 7 +\fITZ\fP +Determine the timezone used to interpret the \fIdate-time\fP option-argument. +If \fITZ\fP is unset or null, an unspecified +default timezone shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fIqselect\fP utility shall write zero or more batch \fIjob_identifier\fPs +to standard output. +.LP +The \fIqselect\fP utility shall separate the batch \fIjob_identifier\fPs +written to standard output by white space. +.LP +The \fIqselect\fP utility shall write batch \fIjob_identifier\fPs +in the following format: +.sp +.RS +.nf + +\fIsequence_number.server_name\fP\fB@\fP\fIserver\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +The following example shows how a user might use the \fIqselect\fP +utility in conjunction with the \fIqdel\fP utility to delete all of +his or her jobs in the queued state without affecting any jobs +that are already running: +.sp +.RS +.nf + +\fBqdel $(qselect -s q) +\fP +.fi +.RE +.LP +or: +.sp +.RS +.nf + +\fBqselect -s q || xargs qdel +\fP +.fi +.RE +.SH RATIONALE +.LP +The \fIqselect\fP utility allows users to acquire a list of job identifiers +that match user-specified selection criteria. The +list of identifiers returned by the \fIqselect\fP utility conforms +to the syntax of the batch job identifier list processed by a +utility such as \fIqmove\fP, \fIqdel\fP, and \fIqrls\fP. The \fIqselect\fP +utility is thus a powerful tool for causing another batch system +utility to act upon a set of jobs that match a list of selection criteria. +.LP +The options of the \fIqselect\fP utility let the user apply a number +of useful filters for selecting jobs. Each option further +restricts the selection of jobs. Many of the selection options allow +the specification of a relational operator. The FORTRAN-like +syntax of the operator-that is, \fB".lt."\fP - was chosen rather than +the C-like \fB"<="\fP meta-characters. +.LP +The \fB-a\fP option allows users to restrict the selected jobs to +those that have been submitted (or altered) to wait until a +particular time. The time period is determined by the argument of +this option, which includes both a time and an operator-it is +thus possible to select jobs waiting until a specific time, jobs waiting +until after a certain time, or those waiting for a time +before the specified time. +.LP +The \fB-A\fP option allows users to restrict the selected jobs to +those that have been submitted (or altered) to charge a +particular account. +.LP +The \fB-c\fP option allows users to restrict the selected jobs to +those whose checkpointing interval falls within the specified +range. +.LP +The \fB-l\fP option allows users to select those jobs whose resource +limits fall within the range indicated by the value of the +option. For example, a user could select those jobs for which the +CPU time limit is greater than two hours. +.LP +The \fB-N\fP option allows users to select jobs by job name. For instance, +all the parts of a task that have been divided in +parallel jobs might be given the same name, and thus manipulated as +a group by means of this option. +.LP +The \fB-q\fP option allows users to select jobs in a specified queue. +.LP +The \fB-r\fP option allows users to select only those jobs with a +specified rerun criteria. For instance, a user might select +only those jobs that can be rerun for use with the \fIqrerun\fP utility. +.LP +The \fB-s\fP option allows users to select only those jobs that are +in a certain state. +.LP +The \fB-u\fP option allows users to select jobs that have been submitted +to execute under a particular account. +.LP +The selection criteria provided by the options of the \fIqselect\fP +utility allow users to select jobs based on all the +appropriate attributes that can be assigned to jobs by the \fIqsub\fP +utility. +.LP +Historically, the \fIqselect\fP utility has not been a part of existing +practice; it is an improvement that has been introduced +in this volume of IEEE\ Std\ 1003.1-2001. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIqdel\fP , \fIqrerun\fP , \fIqrls\fP , qselect , \fIqsub\fP , \fItouch\fP +, \fIBatch Environment Services\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/qsig.1p b/man1p/qsig.1p new file mode 100644 index 000000000..fa156fbac --- /dev/null +++ b/man1p/qsig.1p @@ -0,0 +1,190 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "QSIG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" qsig +.SH NAME +qsig \- signal batch jobs +.SH SYNOPSIS +.LP +\fBqsig\fP \fB[\fP\fB-s\fP \fIsignal\fP\fB]\fP \fIjob_identifier\fP +\fB\&... \fP +.SH DESCRIPTION +.LP +To signal a batch job is to send a signal to the session leader of +the batch job. A batch job is signaled by sending a request +to the batch server that manages the batch job. The \fIqsig\fP utility +is a user-accessible batch client that requests the +signaling of a batch job. +.LP +The \fIqsig\fP utility shall signal those batch jobs for which a batch +\fIjob_identifier\fP is presented to the utility. The +\fIqsig\fP utility shall not signal any batch jobs whose batch \fIjob_identifier\fPs +are not presented to the utility. +.LP +The \fIqsig\fP utility shall signal batch jobs in the order in which +the corresponding batch \fIjob_identifier\fPs are +presented to the utility. If the \fIqsig\fP utility fails to process +a batch \fIjob_identifier\fP successfully, the utility shall +proceed to process the remaining batch \fIjob_identifier\fPs, if any. +.LP +The \fIqsig\fP utility shall signal batch jobs by sending a \fISignal +Job Request\fP to the batch server that manages the +batch job. +.LP +For each successfully processed batch \fIjob_identifier\fP, the \fIqsig\fP +utility shall have received a completion reply to +each \fISignal Job Request\fP sent to a batch server at the time the +utility exits. +.SH OPTIONS +.LP +The \fIqsig\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported by the implementation: +.TP 7 +\fB-s\ \fP \fIsignal\fP +Define the signal to be sent to the batch job. +.LP +The \fIqsig\fP utility shall accept a \fIsignal\fP option-argument +that is either a symbolic signal name or an unsigned +integer signal number (see the POSIX.1-1990 standard, Section 3.3.1.1). +The \fIqsig\fP utility shall accept signal names for which +the SIG prefix has been omitted. +.LP +If the \fIsignal\fP option-argument is a signal name, the \fIqsig\fP +utility shall send that name. +.LP +If the \fIsignal\fP option-argument is a number, the \fIqsig\fP utility +shall send the signal value represented by the +number. +.LP +If the \fB-s\fP option is not presented to the \fIqsig\fP utility, +the utility shall send the signal SIGTERM to each signaled +batch job. +.sp +.SH OPERANDS +.LP +The \fIqsig\fP utility shall accept one or more operands that conform +to the syntax for a batch \fIjob_identifier\fP (see \fIBatch Job Identifier\fP +). +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIqsig\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILOGNAME\fP +Determine the login name of the user. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +An implementation of the \fIqsig\fP utility may write informative +messages to standard output. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +In addition to the default behavior, the \fIqsig\fP utility shall +not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates +that the batch \fIjob_identifier\fP does not exist on the +server. Whether or not the \fIqsig\fP utility waits to output the +diagnostic message while attempting to locate the batch job on +other servers is implementation-defined. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIqsig\fP utility allows users to signal batch jobs. +.LP +A user may be unable to signal a batch job with the \fIkill\fP utility +of the operating +system for a number of reasons. First, the process ID of the batch +job may be unknown to the user. Second, the processes of the +batch job may be on a remote node. However, by virtue of communication +between batch nodes, the \fIqsig\fP utility can arrange for +the signaling of a process. +.LP +Because a batch job that is not running cannot be signaled, and because +the signal may not terminate the batch job, the +\fIqsig\fP utility is not a substitute for the \fIqdel\fP utility. +.LP +The options of the \fIqsig\fP utility allow the user to specify the +signal that is to be sent to the batch job. +.LP +The \fB-s\fP option allows users to specify a signal by name or by +number, and thus override the default signal. The +POSIX.1-1990 standard defines signals by both name and number. +.LP +The \fIqsig\fP utility is a new utility, \fIvis-a-vis\fP existing +practice; it has been defined in this volume of +IEEE\ Std\ 1003.1-2001 in response to user-perceived shortcomings +in existing practice. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIBatch Environment Services\fP , \fIkill\fP() , \fIqdel\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/qstat.1p b/man1p/qstat.1p new file mode 100644 index 000000000..d2ea4d5e9 --- /dev/null +++ b/man1p/qstat.1p @@ -0,0 +1,368 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "QSTAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" qstat +.SH NAME +qstat \- show status of batch jobs +.SH SYNOPSIS +.LP +\fBqstat\fP \fB[\fP\fB-f\fP\fB]\fP \fIjob_identifier\fP \fB... +.br +.sp +qstat -Q\fP \fB[\fP\fB-f\fP\fB]\fP \fIdestination\fP \fB... +.br +.sp +qstat -B\fP \fB[\fP\fB-f\fP\fB]\fP \fIserver_name\fP \fB... \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The status of a batch job, batch queue, or batch server is obtained +by a request to the server. The \fIqstat\fP utility is a +user-accessible batch client that requests the status of one or more +batch jobs, batch queues, or servers, and writes the status +information to standard output. +.LP +For each successfully processed batch \fIjob_identifier\fP, the \fIqstat\fP +utility shall display information about the +corresponding batch job. +.LP +For each successfully processed destination, the \fIqstat\fP utility +shall display information about the corresponding batch +queue. +.LP +For each successfully processed server name, the \fIqstat\fP utility +shall display information about the corresponding +server. +.LP +The \fIqstat\fP utility shall acquire batch job status information +by sending a \fIJob Status Request\fP to a batch server. +The \fIqstat\fP utility shall acquire batch queue status information +by sending a \fIQueue Status Request\fP to a batch server. +The \fIqstat\fP utility shall acquire server status information by +sending a \fIServer Status Request\fP to a batch server. +.SH OPTIONS +.LP +The \fIqstat\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported by the implementation: +.TP 7 +\fB-f\fP +Specify that a full display is produced. +.LP +The minimum contents of a full display are specified in the STDOUT +section. +.LP +Additional contents and format of a full display are implementation-defined. +.TP 7 +\fB-Q\fP +Specify that the operand is a destination. +.LP +The \fIqstat\fP utility shall display information about each batch +queue at each destination identified as an operand. +.TP 7 +\fB-B\fP +Specify that the operand is a server name. +.LP +The \fIqstat\fP utility shall display information about each server +identified as an operand. +.sp +.SH OPERANDS +.LP +If the \fB-Q\fP option is presented to the \fIqstat\fP utility, the +utility shall accept one or more operands that conform to +the syntax for a destination (see \fIDestination\fP ). +.LP +If the \fB-B\fP option is presented to the \fIqstat\fP utility, the +utility shall accept one or more \fIserver_name\fP +operands. +.LP +If neither the \fB-B\fP nor the \fB-Q\fP option is presented to the +\fIqstat\fP utility, the utility shall accept one or more +operands that conform to the syntax for a batch \fIjob_identifier\fP +(see \fIBatch Job +Identifier\fP ). +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIqstat\fP: +.TP 7 +\fIHOME\fP +Determine the pathname of the user's home directory. +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular +expressions. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILC_NUMERIC\fP +.sp +Determine the locale for selecting the radix character used when writing +floating-point formatted output. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If an operand presented to the \fIqstat\fP utility is a batch \fIjob_identifier\fP +and the \fB-f\fP option is not specified, +the \fIqstat\fP utility shall display the following items on a single +line, in the stated order, with white space between each +item, for each successfully processed operand: +.IP " *" 3 +The batch \fIjob_identifier\fP +.LP +.IP " *" 3 +The batch job name +.LP +.IP " *" 3 +The \fIJob_Owner\fP attribute +.LP +.IP " *" 3 +The CPU time used by the batch job +.LP +.IP " *" 3 +The batch job state +.LP +.IP " *" 3 +The batch job location +.LP +.LP +If an operand presented to the \fIqstat\fP utility is a batch \fIjob_identifier\fP +and the \fB-f\fP option is specified, the +\fIqstat\fP utility shall display the following items for each success +fully processed operand: +.IP " *" 3 +The batch \fIjob_identifier\fP +.LP +.IP " *" 3 +The batch job name +.LP +.IP " *" 3 +The \fIJob_Owner\fP attribute +.LP +.IP " *" 3 +The execution user ID +.LP +.IP " *" 3 +The CPU time used by the batch job +.LP +.IP " *" 3 +The batch job state +.LP +.IP " *" 3 +The batch job location +.LP +.IP " *" 3 +Additional implementation-defined information, if any, about the batch +job or batch queue +.LP +.LP +If an operand presented to the \fIqstat\fP utility is a destination, +the \fB-Q\fP option is specified, and the \fB-f\fP +option is not specified, the \fIqstat\fP utility shall display the +following items on a single line, in the stated order, with +white space between each item, for each successfully processed operand: +.IP " *" 3 +The batch queue name +.LP +.IP " *" 3 +The maximum number of batch jobs that shall be run in the batch queue +concurrently +.LP +.IP " *" 3 +The total number of batch jobs in the batch queue +.LP +.IP " *" 3 +The status of the batch queue +.LP +.IP " *" 3 +For each state, the number of batch jobs in that state in the batch +queue and the name of the state +.LP +.IP " *" 3 +The type of batch queue (execution or routing) +.LP +.LP +If the operands presented to the \fIqstat\fP utility are destinations, +the \fB-Q\fP option is specified, and the \fB-f\fP +option is specified, the \fIqstat\fP utility shall display the following +items for each successfully processed operand: +.IP " *" 3 +The batch queue name +.LP +.IP " *" 3 +The maximum number of batch jobs that shall be run in the batch queue +concurrently +.LP +.IP " *" 3 +The total number of batch jobs in the batch queue +.LP +.IP " *" 3 +The status of the batch queue +.LP +.IP " *" 3 +For each state, the number of batch jobs in that state in the batch +queue and the name of the state +.LP +.IP " *" 3 +The type of batch queue (execution or routing) +.LP +.IP " *" 3 +Additional implementation-defined information, if any, about the batch +queue +.LP +.LP +If the operands presented to the \fIqstat\fP utility are batch server +names, the \fB-B\fP option is specified, and the +\fB-f\fP option is not specified, the \fIqstat\fP utility shall display +the following items on a single line, in the stated +order, with white space between each item, for each successfully processed +operand: +.IP " *" 3 +The batch server name +.LP +.IP " *" 3 +The maximum number of batch jobs that shall be run in the batch queue +concurrently +.LP +.IP " *" 3 +The total number of batch jobs managed by the batch server +.LP +.IP " *" 3 +The status of the batch server +.LP +.IP " *" 3 +For each state, the number of batch jobs in that state and the name +of the state +.LP +.LP +If the operands presented to the \fIqstat\fP utility are server names, +the \fB-B\fP option is specified, and the \fB-f\fP +option is specified, the \fIqstat\fP utility shall display the following +items for each successfully processed operand: +.IP " *" 3 +The server name +.LP +.IP " *" 3 +The maximum number of batch jobs that shall be run in the batch queue +concurrently +.LP +.IP " *" 3 +The total number of batch jobs managed by the server +.LP +.IP " *" 3 +The status of the server +.LP +.IP " *" 3 +For each state, the number of batch jobs in that state and the name +of the state +.LP +.IP " *" 3 +Additional implementation-defined information, if any, about the server +.LP +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +In addition to the default behavior, the \fIqstat\fP utility shall +not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates +that the batch \fIjob_identifier\fP does not exist on the +server. Whether or not the \fIqstat\fP utility waits to output the +diagnostic message while attempting to locate the batch job on +other servers is implementation-defined. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIqstat\fP utility allows users to display the status of jobs +and list the batch jobs in queues. +.LP +The operands of the \fIqstat\fP utility may be either job identifiers, +queues (specified as destination identifiers), or batch +server names. The \fB-Q\fP and \fB-B\fP options, or absence thereof, +indicate the nature of the operands. +.LP +The other options of the \fIqstat\fP utility allow the user to control +the amount of information displayed and the format in +which it is displayed. Should a user wish to display the status of +a set of jobs that match a selection criteria, the \fIqselect\fP utility +may be used to acquire such a list. +.LP +The \fB-f\fP option allows users to request a "full" display in an +implementation-defined format. +.LP +Historically, the \fIqstat\fP utility has been a part of the NQS and +its derivatives, the existing practice on which it is +based. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIBatch Environment Services\fP , \fIqselect\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/qsub.1p b/man1p/qsub.1p new file mode 100644 index 000000000..dd50d9e04 --- /dev/null +++ b/man1p/qsub.1p @@ -0,0 +1,1024 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "QSUB" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" qsub +.SH NAME +qsub \- submit a script +.SH SYNOPSIS +.LP +\fBqsub\fP \fB[\fP\fB-a\fP \fIdate_time\fP\fB][\fP\fB-A\fP +\fIaccount_string\fP\fB][\fP\fB-c\fP \fIinterval\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-C\fP \fIdirective_prefix\fP\fB][\fP\fB-e\fP +\fIpath_name\fP\fB][\fP\fB-h\fP\fB][\fP\fB-j\fP \fIjoin_list\fP\fB][\fP\fB-k\fP +\fIkeep_list\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-m\fP \fImail_options\fP\fB][\fP\fB-M\fP +\fImail_list\fP\fB][\fP\fB-N\fP \fIname\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-o\fP \fIpath_name\fP\fB][\fP\fB-p\fP +\fIpriority\fP\fB][\fP\fB-q\fP \fIdestination\fP\fB][\fP\fB-r\fP \fIy\fP\fB|\fP\fIn\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-S\fP \fIpath_name_list\fP\fB][\fP\fB-u\fP +\fIuser_list\fP\fB][\fP\fB-v\fP \fIvariable_list\fP\fB][\fP\fB-V\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-z\fP\fB][\fP\fIscript\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +To submit a script is to create a batch job that executes the script. +A script is submitted by a request to a batch server. The +\fIqsub\fP utility is a user-accessible batch client that submits +a script. +.LP +Upon successful completion, the \fIqsub\fP utility shall have created +a batch job that will execute the submitted script. +.LP +The \fIqsub\fP utility shall submit a script by sending a \fIQueue +Job Request\fP to a batch server. +.LP +The \fIqsub\fP utility shall place the value of the following environment +variables in the \fIVariable_List\fP attribute of +the batch job: \fIHOME ,\fP \fILANG ,\fP \fILOGNAME ,\fP \fIPATH ,\fP +\fIMAIL ,\fP \fISHELL ,\fP and \fITZ .\fP The name of +the environment variable shall be the current name prefixed with the +string PBS_O_. +.TP 7 +\fBNote:\fP +If the current value of the \fIHOME\fP variable in the environment +space of the \fIqsub\fP utility is \fB/aa/bb/cc\fP, then +\fIqsub\fP shall place \fIPBS_O_HOME =\fP \fB/aa/bb/cc\fP in the \fIVariable_List\fP +attribute of the batch job. +.sp +.LP +In addition to the variables described above, the \fIqsub\fP utility +shall add the following variables with the indicated +values to the variable list: +.TP 7 +\fIPBS_O_WORKDIR\fP +The absolute path of the current working directory of the \fIqsub\fP +utility process. +.TP 7 +\fIPBS_O_HOST\fP +The name of the host on which the \fIqsub\fP utility is running. +.sp +.SH OPTIONS +.LP +The \fIqsub\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported by the implementation: +.TP 7 +\fB-a\ \fP \fIdate_time\fP +Define the time at which a batch job becomes eligible for execution. +.LP +The \fIqsub\fP utility shall accept an option-argument that conforms +to the syntax of the \fItime\fP operand of the \fItouch\fP utility. +.br +.sp +.ce 1 +\fBTable: Environment Variable Values (Utilities)\fP +.TS C +center; l l. +\fBVariable Name\fP \fBValue at qsub Time\fP +\fIPBS_O_HOME\fP \fIHOME\fP +\fIPBS_O_HOST\fP \fIClient host name\fP +\fIPBS_O_LANG\fP \fILANG\fP +\fIPBS_O_LOGNAME\fP \fILOGNAME\fP +\fIPBS_O_PATH\fP \fIPATH\fP +\fIPBS_O_MAIL\fP \fIMAIL\fP +\fIPBS_O_SHELL\fP \fISHELL\fP +\fIPBS_O_TZ\fP \fITZ\fP +\fIPBS_O_WORKDIR\fP \fICurrent working directory\fP +.TE +.TP 7 +\fBNote:\fP +.RS +The server that initiates execution of the batch job will add other +variables to the batch job's environment; see \fIBatch Job Execution\fP +\&. +.RE +.sp +.LP +The \fIqsub\fP utility shall set the \fIExecution_Time\fP attribute +of the batch job to the number of seconds since the Epoch +that is equivalent to the local time expressed by the value of the +\fIdate_time\fP option-argument. The Epoch is defined in the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 3.149, +Epoch. +.LP +If the \fB-a\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIExecution_Time\fP attribute +of the batch job to a time (number of seconds since the Epoch) that +is earlier than the time at which the utility exits. +.TP 7 +\fB-A\ \fP \fIaccount_string\fP +.sp +Define the account to which the resource consumption of the batch +job should be charged. +.LP +The syntax of the \fIaccount_string\fP option-argument is unspecified. +.LP +The \fIqsub\fP utility shall set the \fIAccount_Name\fP attribute +of the batch job to the value of the \fIaccount_string\fP +option-argument. +.LP +If the \fB-A\fP option is not presented to the \fIqsub\fP utility, +the utility shall omit the \fIAccount_Name\fP attribute +from the attributes of the batch job. +.TP 7 +\fB-c\ \fP \fIinterval\fP +Define whether the batch job should be checkpointed, and if so, how +often. +.LP +The \fIqsub\fP utility shall accept a value for the interval option-argument +that is one of the following: +.TP 7 +\fBn\fP +.RS +No checkpointing shall be performed on the batch job (NO_CHECKPOINT). +.RE +.TP 7 +\fBs\fP +.RS +Checkpointing shall be performed only when the batch server is shut +down (CHECKPOINT_AT_SHUTDOWN). +.RE +.TP 7 +\fBc\fP +.RS +Automatic periodic checkpointing shall be performed at the \fIMinimum_Cpu_Interval\fP +attribute of the batch queue, in units +of CPU minutes (CHECKPOINT_AT_MIN_CPU_INTERVAL). +.RE +.TP 7 +\fBc\fP=\fIminutes\fP +.RS +Automatic periodic checkpointing shall be performed every \fIminutes\fP +of CPU time, or every \fIMinimum_Cpu_Interval\fP +minutes, whichever is greater. The \fIminutes\fP argument shall conform +to the syntax for unsigned integers and shall be greater +than zero. +.RE +.sp +.LP +The \fIqsub\fP utility shall set the \fICheckpoint\fP attribute of +the batch job to the value of the \fIinterval\fP +option-argument. +.LP +If the \fB-c\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fICheckpoint\fP attribute of +the batch job to the single character \fB'u'\fP (CHECKPOINT_UNSPECIFIED). +.TP 7 +\fB-C\ \fP \fIdirective_prefix\fP +.sp +Define the prefix that declares a directive to the \fIqsub\fP utility +within the script. +.LP +The \fIdirective_prefix\fP is not a batch job attribute; it affects +the behavior of the \fIqsub\fP utility. +.LP +If the \fB-C\fP option is presented to the \fIqsub\fP utility, and +the value of the \fIdirective_prefix\fP option-argument is +the null string, the utility shall not scan the script file for directives. +If the \fB-C\fP option is not presented to the +\fIqsub\fP utility, then the value of the \fIPBS_DPREFIX\fP environment +variable is used. If the environment variable is not +defined, then #PBS encoded in the portable character set is the default. +.TP 7 +\fB-e\ \fP \fIpath_name\fP +Define the path to be used for the standard error stream of the batch +job. +.LP +The \fIqsub\fP utility shall accept a \fIpath_name\fP option-argument +which can be preceded by a host name element of the form +\fIhostname\fP:. +.LP +If the \fIpath_name\fP option-argument constitutes an absolute pathname, +the \fIqsub\fP utility shall set the +\fIError_Path\fP attribute of the batch job to the value of the \fIpath_name\fP +option-argument. +.LP +If the \fIpath_name\fP option-argument constitutes a relative pathname +and no host name element is specified, the \fIqsub\fP +utility shall set the \fIError_Path\fP attribute of the batch job +to the value of the absolute pathname derived by expanding the +\fIpath_name\fP option-argument relative to the current directory +of the process executing \fIqsub\fP. +.LP +If the \fIpath_name\fP option-argument constitutes a relative pathname +and a host name element is specified, the \fIqsub\fP +utility shall set the \fIError_Path\fP attribute of the batch job +to the value of the \fIpath_name\fP option-argument without +expansion. The host name element shall be included. +.LP +If the \fIpath_name\fP option-argument does not include a host name +element, the \fIqsub\fP utility shall prefix the pathname +with \fIhostname\fP:, where \fIhostname\fP is the name of the host +upon which the \fIqsub\fP utility is being executed. +.LP +If the \fB-e\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIError_Path\fP attribute of +the batch job to the host name and path of the current directory of +the submitting process and the default filename. +.LP +The default filename for standard error has the following format: +.sp +.RS +.nf + +\fIjob_name\fP\fB.e\fP\fIsequence_number\fP +.fi +.RE +.TP 7 +\fB-h\fP +Specify that a USER hold is applied to the batch job. +.LP +The \fIqsub\fP utility shall set the value of the \fIHold_Types\fP +attribute of the batch job to the value USER. +.LP +If the \fB-h\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIHold_Types\fP attribute of +the batch job to the value NO_HOLD. +.TP 7 +\fB-j\ \fP \fIjoin_list\fP +Define which streams of the batch job are to be merged. The \fIqsub\fP +\fB-j\fP option shall accept a value for the +\fIjoin_list\fP option-argument that is a string of alphanumeric characters +in the portable character set (see the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable +Character Set). +.LP +The \fIqsub\fP utility shall accept a \fIjoin_list\fP option-argument +that consists of one or more of the characters +\fB'e'\fP and \fB'o'\fP , or the single character \fB'n'\fP . +.LP +All of the other batch job output streams specified will be merged +into the output stream represented by the character listed +first in the \fIjoin_list\fP option-argument. +.LP +For each unique character in the \fIjoin_list\fP option-argument, +the \fIqsub\fP utility shall add a value to the +\fIJoin_Path\fP attribute of the batch job as follows, each representing +a different batch job stream to join: +.TP 7 +\fBe\fP +.RS +The standard error of the batch job (JOIN_STD_ERROR). +.RE +.TP 7 +\fBo\fP +.RS +The standard output of the batch job (JOIN_STD_OUTPUT). +.RE +.sp +.LP +An existing \fIJoin_Path\fP attribute can be cleared by the following +join type: +.TP 7 +\fBn\fP +.RS +NO_JOIN +.RE +.sp +.LP +If \fB'n'\fP is specified, then no files are joined. The \fIqsub\fP +utility shall consider it an error if any join type +other than \fB'n'\fP is combined with join type \fB'n'\fP . +.LP +Strictly conforming applications shall not repeat any of the characters +\fB'e'\fP , \fB'o'\fP , or \fB'n'\fP within the +\fIjoin_list\fP option-argument. The \fIqsub\fP utility shall permit +the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.LP +An implementation may define other join types. The conformance document +for an implementation shall describe any additional +batch job streams, how they are specified, their internal behavior, +and how they affect the behavior of the utility. +.LP +If the \fB-j\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the value of the \fIJoin_Path\fP +attribute of the batch job to NO_JOIN. +.TP 7 +\fB-k\ \fP \fIkeep_list\fP +Define which output of the batch job to retain on the execution host. +.LP +The \fIqsub\fP \fB-k\fP option shall accept a value for the \fIkeep_list\fP +option-argument that is a string of alphanumeric +characters in the portable character set (see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable Character +Set). +.LP +The \fIqsub\fP utility shall accept a \fIkeep_list\fP option-argument +that consists of one or more of the characters +\fB'e'\fP and \fB'o'\fP , or the single character \fB'n'\fP . +.LP +For each unique character in the \fIkeep_list\fP option-argument, +the \fIqsub\fP utility shall add a value to the +\fIKeep_Files\fP attribute of the batch job as follows, each representing +a different batch job stream to keep: +.TP 7 +\fBe\fP +.RS +The standard error of the batch job (KEEP_STD_ERROR). +.RE +.TP 7 +\fBo\fP +.RS +The standard output of the batch job (KEEP_STD_OUTPUT). +.RE +.sp +.LP +If both \fB'e'\fP and \fB'o'\fP are specified, then both files are +retained. An existing \fIKeep_Files\fP attribute can +be cleared by the following keep type: +.TP 7 +\fBn\fP +.RS +NO_KEEP +.RE +.sp +.LP +If \fB'n'\fP is specified, then no files are retained. The \fIqsub\fP +utility shall consider it an error if any keep type +other than \fB'n'\fP is combined with keep type \fB'n'\fP . +.LP +Strictly conforming applications shall not repeat any of the characters +\fB'e'\fP , \fB'o'\fP , or \fB'n'\fP within the +\fIkeep_list\fP option-argument. The \fIqsub\fP utility shall permit +the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.LP +An implementation may define other keep types. The conformance document +for an implementation shall describe any additional keep +types, how they are specified, their internal behavior, and how they +affect the behavior of the utility. If the \fB-k\fP option is +not presented to the \fIqsub\fP utility, the utility shall set the +\fIKeep_Files\fP attribute of the batch job to the value +NO_KEEP. +.TP 7 +\fB-m\ \fP \fImail_options\fP +.sp +Define the points in the execution of the batch job at which the batch +server that manages the batch job shall send mail about a +change in the state of the batch job. +.LP +The \fIqsub\fP \fB-m\fP option shall accept a value for the \fImail_options\fP +option-argument that is a string of +alphanumeric characters in the portable character set (see the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable +Character Set). +.LP +The \fIqsub\fP utility shall accept a value for the \fImail_options\fP +option-argument that is a string of one or more of the +characters \fB'e'\fP , \fB'b'\fP , and \fB'a'\fP , or the single character +\fB'n'\fP . +.LP +For each unique character in the \fImail_options\fP option-argument, +the \fIqsub\fP utility shall add a value to the +\fIMail_Users\fP attribute of the batch job as follows, each representing +a different time during the life of a batch job at which +to send mail: +.TP 7 +\fBe\fP +.RS +MAIL_AT_EXIT +.RE +.TP 7 +\fBb\fP +.RS +MAIL_AT_BEGINNING +.RE +.TP 7 +\fBa\fP +.RS +MAIL_AT_ABORT +.RE +.sp +.LP +If any of these characters are duplicated in the \fImail_options\fP +option-argument, the duplicates shall be ignored. +.LP +An existing \fIMail_Points\fP attribute can be cleared by the following +mail type: +.TP 7 +\fBn\fP +.RS +NO_MAIL +.RE +.sp +.LP +If \fB'n'\fP is specified, then mail is not sent. The \fIqsub\fP utility +shall consider it an error if any mail type other +than \fB'n'\fP is combined with mail type \fB'n'\fP . +.LP +Strictly conforming applications shall not repeat any of the characters +\fB'e'\fP , \fB'b'\fP , \fB'a'\fP , or +\fB'n'\fP within the \fImail_options\fP option-argument. +.LP +The \fIqsub\fP utility shall permit the repetition of characters, +but shall not assign additional meaning to the repeated +characters. An implementation may define other mail types. The conformance +document for an implementation shall describe any +additional mail types, how they are specified, their internal behavior, +and how they affect the behavior of the utility. +.LP +If the \fB-m\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIMail_Points\fP attribute to +the value MAIL_AT_ABORT. +.TP 7 +\fB-M\ \fP \fImail_list\fP +Define the list of users to which a batch server that executes the +batch job shall send mail, if the server sends mail about +the batch job. +.LP +The syntax of the \fImail_list\fP option-argument is unspecified. +.LP +If the implementation of the \fIqsub\fP utility uses a name service +to locate users, the utility should accept the syntax used +by the name service. +.LP +If the implementation of the \fIqsub\fP utility does not use a name +service to locate users, the implementation should accept +the following syntax for user names: +.sp +.RS +.nf + +\fImail_address\fP\fB[\fP\fB,,\fP\fImail_address\fP\fB,, ...\fP\fB]\fP +.fi +.RE +.LP +The interpretation of \fImail_address\fP is implementation-defined. +.LP +The \fIqsub\fP utility shall set the \fIMail_Users\fP attribute of +the batch job to the value of the \fImail_list\fP +option-argument. +.LP +If the \fB-M\fP option is not presented to the \fIqsub\fP utility, +the utility shall place only the user name and host name +for the current process in the \fIMail_Users\fP attribute of the batch +job. +.TP 7 +\fB-N\ \fP \fIname\fP +Define the name of the batch job. +.LP +The \fIqsub\fP \fB-N\fP option shall accept a value for the \fIname\fP +option-argument that is a string of up to 15 +alphanumeric characters in the portable character set (see the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable +Character Set) where the first character is alphabetic. +.LP +The \fIqsub\fP utility shall set the value of the \fIJob_Name\fP attribute +of the batch job to the value of the \fIname\fP +option-argument. +.LP +If the \fB-N\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIJob_Name\fP attribute of the +batch job to the name of the \fIscript\fP argument from which the +directory specification if any, has been removed. +.LP +If the \fB-N\fP option is not presented to the \fIqsub\fP utility, +and the script is read from standard input, the utility +shall set the \fIJob_Name\fP attribute of the batch job to the value +STDIN. +.TP 7 +\fB-o\ \fP \fIpath_name\fP +Define the path for the standard output of the batch job. +.LP +The \fIqsub\fP utility shall accept a \fIpath_name\fP option-argument +that conforms to the syntax of the \fIpath_name\fP +element defined in the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +which can be preceded by a host name element of +the form \fIhostname\fP:. +.LP +If the \fIpath_name\fP option-argument constitutes an absolute pathname, +the \fIqsub\fP utility shall set the +\fIOutput_Path\fP attribute of the batch job to the value of the \fIpath_name\fP +option-argument without expansion. +.LP +If the \fIpath_name\fP option-argument constitutes a relative pathname +and no host name element is specified, the \fIqsub\fP +utility shall set the \fIOutput_Path\fP attribute of the batch job +to the pathname derived by expanding the value of the +\fIpath_name\fP option-argument relative to the current directory +of the process executing the \fIqsub\fP. +.LP +If the \fIpath_name\fP option-argument constitutes a relative pathname +and a host name element is specified, the \fIqsub\fP +utility shall set the \fIOutput_Path\fP attribute of the batch job +to the value of the \fIpath_name\fP option-argument without +expansion. +.LP +If the \fIpath_name\fP option-argument does not specify a host name +element, the \fIqsub\fP utility shall prefix the pathname +with \fIhostname\fP:, where \fIhostname\fP is the name of the host +upon which the \fIqsub\fP utility is executing. +.LP +If the \fB-o\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIOutput_Path\fP attribute of +the batch job to the host name and path of the current directory of +the submitting process and the default filename. +.LP +The default filename for standard output has the following format: +.sp +.RS +.nf + +\fIjob_name\fP\fB.o\fP\fIsequence_number\fP +.fi +.RE +.TP 7 +\fB-p\ \fP \fIpriority\fP +Define the priority the batch job should have relative to other batch +jobs owned by the batch server. +.LP +The \fIqsub\fP utility shall set the \fIPriority\fP attribute of the +batch job to the value of the \fIpriority\fP +option-argument. +.LP +If the \fB-p\fP option is not presented to the \fIqsub\fP utility, +the value of the \fIPriority\fP attribute is +implementation-defined. +.LP +The \fIqsub\fP utility shall accept a value for the \fIpriority\fP +option-argument that conforms to the syntax for signed +decimal integers, and which is not less than -1024 and not greater +than 1023. +.TP 7 +\fB-q\ \fP \fIdestination\fP +.sp +Define the destination of the batch job. +.LP +The destination is not a batch job attribute; it determines the batch +server, and possibly the batch queue, to which the +\fIqsub\fP utility batch queues the batch job. +.LP +The \fIqsub\fP utility shall submit the script to the batch server +named by the \fIdestination\fP option-argument or the +server that owns the batch queue named in the \fIdestination\fP option-argument. +.LP +The \fIqsub\fP utility shall accept an option-argument for the \fB-q\fP +option that conforms to the syntax for a destination +(see \fIDestination\fP ). +.LP +If the \fB-q\fP option is not presented to the \fIqsub\fP utility, +the \fIqsub\fP utility shall submit the batch job to the +default destination. The mechanism for determining the default destination +is implementation-defined. +.TP 7 +\fB-r\ \fP \fIy\fP|\fIn\fP +Define whether the batch job is rerunnable. +.LP +If the value of the option-argument is \fIy\fP, the \fIqsub\fP utility +shall set the \fIRerunable\fP attribute of the batch +job to TRUE. +.LP +If the value of the option-argument is \fIn\fP, the \fIqsub\fP utility +shall set the \fIRerunable\fP attribute of the batch +job to FALSE. +.LP +If the \fB-r\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIRerunable\fP attribute of the +batch job to TRUE. +.TP 7 +\fB-S\ \fP \fIpath_name_list\fP +.sp +Define the pathname to the shell under which the batch job is to execute. +.LP +The \fIqsub\fP utility shall accept a \fIpath_name_list\fP option-argument +that conforms to the following syntax: +.sp +.RS +.nf + +\fIpathname\fP\fB[\fP\fB@\fP\fIhost\fP\fB][\fP\fB,,\fP\fIpathname\fP\fB[\fP\fB@\fP\fIhost\fP\fB]\fP\fB,, ...\fP\fB]\fP +.fi +.RE +.LP +The \fIqsub\fP utility shall allow only one pathname for a given host +name. The \fIqsub\fP utility shall allow only one +pathname that is missing a corresponding host name. +.LP +The \fIqsub\fP utility shall add a value to the \fIShell_Path_List\fP +attribute of the batch job for each entry in the +\fIpath_name_list\fP option-argument. +.LP +If the \fB-S\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIShell_Path_List\fP attribute +of the batch job to the null string. +.LP +The conformance document for an implementation shall describe the +mechanism used to set the default shell and determine the +current value of the default shell. An implementation shall provide +a means for the installation to set the default shell to the +login shell of the user under which the batch job is to execute. See +\fIMultiple +Keyword-Value Pairs\fP for a means of removing \fIkeyword\fP= \fIvalue\fP +(and \fIvalue\fP@ \fIkeyword\fP) pairs and other +general rules for list-oriented batch job attributes. +.TP 7 +\fB-u\ \fP \fIuser_list\fP +Define the user name under which the batch job is to execute. +.LP +The \fIqsub\fP utility shall accept a \fIuser_list\fP option-argument +that conforms to the following syntax: +.sp +.RS +.nf + +\fIusername\fP\fB[\fP\fB@\fP\fIhost\fP\fB][\fP\fB,,\fP\fIusername\fP\fB[\fP\fB@\fP\fIhost\fP\fB]\fP\fB,, ...\fP\fB]\fP +.fi +.RE +.LP +The \fIqsub\fP utility shall accept only one user name that is missing +a corresponding host name. The \fIqsub\fP utility shall +accept only one user name per named host. +.LP +The \fIqsub\fP utility shall add a value to the \fIUser_List\fP attribute +of the batch job for each entry in the +\fIuser_list\fP option-argument. +.LP +If the \fB-u\fP option is not presented to the \fIqsub\fP utility, +the utility shall set the \fIUser_List\fP attribute of the +batch job to the user name from which the utility is executing. See +\fIMultiple +Keyword-Value Pairs\fP for a means of removing \fIkeyword\fP= \fIvalue\fP +(and \fIvalue\fP@ \fIkeyword\fP) pairs and other +general rules for list-oriented batch job attributes. +.TP 7 +\fB-v\ \fP \fIvariable_list\fP +.sp +Add to the list of variables that are exported to the session leader +of the batch job. +.LP +A \fIvariable_list\fP is a set of strings of either the form < \fIvariable\fP> +or < \fIvariable\fP= +\fIvalue\fP>, delimited by commas. +.LP +If the \fB-v\fP option is presented to the \fIqsub\fP utility, the +utility shall also add, to the environment +\fIVariable_List\fP attribute of the batch job, every variable named +in the environment \fIvariable_list\fP option-argument and, +optionally, values of specified variables. +.LP +If a value is not provided on the command line, the \fIqsub\fP utility +shall set the value of each variable in the environment +\fIVariable_List\fP attribute of the batch job to the value of the +corresponding environment variable for the process in which the +utility is executing; see Environment Variable Values (Utilities) +\&. +.LP +A conforming application shall not repeat a variable in the environment +\fIvariable_list\fP option-argument. +.LP +The \fIqsub\fP utility shall not repeat a variable in the environment +\fIVariable_List\fP attribute of the batch job. See \fIMultiple Keyword-Value +Pairs\fP for a means of removing \fIkeyword\fP= \fIvalue\fP +(and \fIvalue\fP@ \fIkeyword\fP) pairs and other general rules for +list-oriented batch job attributes. +.TP 7 +\fB-V\fP +Specify that all of the environment variables of the process are exported +to the context of the batch job. +.LP +The \fIqsub\fP utility shall place every environment variable in the +process in which the utility is executing in the list and +shall set the value of each variable in the attribute to the value +of that variable in the process. +.TP 7 +\fB-z\fP +Specify that the utility does not write the batch \fIjob_identifier\fP +of the created batch job to standard output. +.LP +If the \fB-z\fP option is presented to the \fIqsub\fP utility, the +utility shall not write the batch \fIjob_identifier\fP of +the created batch job to standard output. +.LP +If the \fB-z\fP option is not presented to the \fIqsub\fP utility, +the utility shall write the identifier of the created batch +job to standard output. +.sp +.SH OPERANDS +.LP +The \fIqsub\fP utility shall accept a \fIscript\fP operand that indicates +the path to the script of the batch job. +.LP +If the \fIscript\fP operand is not presented to the \fIqsub\fP utility, +or if the operand is the single-character string +\fB'-'\fP , the utility shall read the script from standard input. +.LP +If the script represents a partial path, the \fIqsub\fP utility shall +expand the path relative to the current directory of the +process executing the utility. +.SH STDIN +.LP +The \fIqsub\fP utility reads the script of the batch job from standard +input if the script operand is omitted or is the single +character \fB'-'\fP . +.SH INPUT FILES +.LP +In addition to binding the file indicated by the \fIscript\fP operand +to the batch job, the \fIqsub\fP utility reads the +script file and acts on directives in the script. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIqsub\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILOGNAME\fP +Determine the login name of the user. +.TP 7 +\fIPBS_DPREFIX\fP +.sp +Determine the default prefix for directives within the script. +.TP 7 +\fISHELL\fP +Determine the pathname of the preferred command language interpreter +of the user. +.TP 7 +\fITZ\fP +Determine the timezone used to interpret the \fIdate-time\fP option-argument. +If \fITZ\fP is unset or null, an unspecified +default timezone shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Once created, a batch job exists until it exits, aborts, or is deleted. +.LP +After a batch job is created by the \fIqsub\fP utility, batch servers +might route, execute, modify, or delete the batch +job. +.SH STDOUT +.LP +The \fIqsub\fP utility writes the batch \fIjob_identifier\fP assigned +to the batch job to standard output, unless the +\fB-z\fP option is specified. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.SS Script Preservation +.LP +The \fIqsub\fP utility shall make the script available to the server +executing the batch job in such a way that the server +executes the script as it exists at the time of submission. +.LP +The \fIqsub\fP utility can send a copy of the script to the server +with the \fIQueue Job Request\fP or store a temporary copy +of the script in a location specified to the server. +.SS Option Specification +.LP +A script can contain directives to the \fIqsub\fP utility. +.LP +The \fIqsub\fP utility shall scan the lines of the script for directives, +skipping blank lines, until the first line that +begins with a string other than the directive string; if directives +occur on subsequent lines, the utility shall ignore those +directives. +.LP +Lines are separated by a . If the first line of the script +begins with \fB"#!"\fP or a colon ( \fB':'\fP ), +then it is skipped. The \fIqsub\fP utility shall process a line in +the script as a directive if and only if the string of +characters from the first non-white-space character on the line until +the first or on the line match the +directive prefix. If a line in the script contains a directive and +the final characters of the line are backslash ( \fB'\\'\fP ) +and , then the next line shall be interpreted as a continuation +of that directive. +.LP +The \fIqsub\fP utility shall process the options and option-arguments +contained on the directive prefix line using the same +syntax as if the options were input on the \fIqsub\fP utility. +.LP +The \fIqsub\fP utility shall continue to process a directive prefix +line until after a is encountered. An +implementation may ignore lines which, according to the syntax of +the shell that will interpret the script, are comments. An +implementation shall describe in the conformance document the format +of any shell comments that it will recognize. +.LP +If an option is present in both a directive and the arguments to the +\fIqsub\fP utility, the utility shall ignore the option +and the corresponding option-argument, if any, in the directive. +.LP +If an option that is present in the directive is not present in the +arguments to the \fIqsub\fP utility, the utility shall +process the option and the option-argument, if any. +.LP +In order of preference, the \fIqsub\fP utility shall select the directive +prefix from one of the following sources: +.IP " *" 3 +If the \fB-C\fP option is presented to the utility, the value of the +\fIdirective_prefix\fP option-argument +.LP +.IP " *" 3 +If the environment variable \fIPBS_DPREFIX\fP is defined, the value +of that variable +.LP +.IP " *" 3 +The four-character string \fB"#PBS"\fP encoded in the portable character +set +.LP +.LP +If the \fB-C\fP option is present in the script file it shall be ignored. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIqsub\fP utility allows users to create a batch job that will +process the script specified as the operand of the +utility. +.LP +The options of the \fIqsub\fP utility allow users to control many +aspects of the queuing and execution of a batch job. +.LP +The \fB-a\fP option allows users to designate the time after which +the batch job will become eligible to run. By specifying an +execution time, users can take advantage of resources at off-peak +hours, synchronize jobs with chronologically predictable events, +and perhaps take advantage of off-peak pricing of computing time. +For these reasons and others, a timing option is existing +practice on the part of almost every batch system, including NQS. +.LP +The \fB-A\fP option allows users to specify the account that will +be charged for the batch job. Support for account is not +mandatory for conforming batch servers. +.LP +The \fB-C\fP option allows users to prescribe the prefix for directives +within the script file. The default prefix +\fB"#PBS"\fP may be inappropriate if the script will be interpreted +with an alternate shell, as specified by the \fB-S\fP +option. +.LP +The \fB-c\fP option allows users to establish the checkpointing interval +for their jobs. A checkpointing system, which is not +defined by this volume of IEEE\ Std\ 1003.1-2001, allows recovery +of a batch job at the most recent checkpoint in the event +of a crash. Checkpointing is typically used for jobs that consume +expensive computing time or must meet a critical schedule. Users +should be allowed to make the tradeoff between the overhead of checkpointing +and the risk to the timely completion of the batch +job; therefore, this volume of IEEE\ Std\ 1003.1-2001 provides the +checkpointing interval option. Support for checkpointing +is optional for batch servers. +.LP +The \fB-e\fP option allows users to redirect the standard error streams +of their jobs to a non-default path. For example, if +the submitted script generally produces a great deal of useless error +output, a user might redirect the standard error output to +the null device. Or, if the file system holding the default location +(the home directory of the user) has too little free space, +the user might redirect the standard error stream to a file in another +file system. +.LP +The \fB-h\fP option allows users to create a batch job that is held +until explicitly released. The ability to create a held job +is useful when some external event must complete before the batch +job can execute. For example, the user might submit a held job +and release it when the system load has dropped. +.LP +The \fB-j\fP option allows users to merge the standard error of a +batch job into its standard output stream, which has the +advantage of showing the sequential relationship between output and +error messages. +.LP +The \fB-m\fP option allows users to designate those points in the +execution of a batch job at which mail will be sent to the +submitting user, or to the account(s) indicated by the \fB-M\fP option. +By requesting mail notification at points of interest in +the life of a job, the submitting user, or other designated users, +can track the progress of a batch job. +.LP +The \fB-N\fP option allows users to associate a name with the batch +job. The job name in no way affects the processing of the +batch job, but rather serves as a mnemonic handle for users. For example, +the batch job name can help the user distinguish between +multiple jobs listed by the \fIqstat\fP utility. +.LP +The \fB-o\fP option allows users to redirect the standard output stream. +A user might, for example, wish to redirect to the +null device the standard output stream of a job that produces copious +yet superfluous output. +.LP +The \fB-P\fP option allows users to designate the relative priority +of a batch job for selection from a queue. +.LP +The \fB-q\fP option allows users to specify an initial queue for the +batch job. If the user specifies a routing queue, the +batch server routes the batch job to another queue for execution or +further routing. If the user specifies a non-routing queue, the +batch server of the queue eventually executes the batch job. +.LP +The \fB-r\fP option allows users to control whether the submitted +job will be rerun if the controlling batch node fails during +execution of the batch job. The \fB-r\fP option likewise allows users +to indicate whether or not the batch job is eligible to be +rerun by the \fIqrerun\fP utility. Some jobs cannot be correctly rerun +because of changes +they make in the state of databases or other aspects of their environment. +This volume of IEEE\ Std\ 1003.1-2001 specifies +that the default, if the \fB-r\fP option is not presented to the utility, +will be that the batch job cannot be rerun, since the +result of rerunning a non-rerunnable job might be catastrophic. +.LP +The \fB-S\fP option allows users to specify the program (usually a +shell) that will be invoked to process the script of the +batch job. This option has been modified to allow a list of shell +names and locations associated with different hosts. +.LP +The \fB-u\fP option is useful when the submitting user is authorized +to use more than one account on a given host, in which +case the \fB-u\fP option allows the user to select from among those +accounts. The option-argument is a list of user-host pairs, so +that the submitting user can provide different user identifiers for +different nodes in the event the batch job is routed. The +\fB-u\fP option provides a lot of flexibility to accommodate sites +with complex account structures. Users that have the same user +identifier on all the hosts they are authorized to use will not need +to use the \fB-u\fP option. +.LP +The \fB-V\fP option allows users to export all their current environment +variables, as of the time the batch job is submitted, +to the context of the processes of the batch job. +.LP +The \fB-v\fP option allows users to export specific environment variables +from their current process to the processes of the +batch job. +.LP +The \fB-z\fP option allows users to suppress the writing of the batch +job identifier to standard output. The \fB-z\fP option +is an existing NQS practice that has been standardized. +.LP +Historically, the \fIqsub\fP utility has served the batch job-submission +function in the NQS system, the existing practice on +which it is based. Some changes and additions have been made to the +\fIqsub\fP utility in this volume of +IEEE\ Std\ 1003.1-2001, \fIvis-a-vis\fP NQS, as a result of the growing +pool of experience with distributed batch +systems. +.LP +The set of features of the \fIqsub\fP utility as defined in this volume +of IEEE\ Std\ 1003.1-2001 appears to +incorporate all the common existing practice on potentially conforming +platforms. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIBatch Environment Services\fP , \fIqrerun\fP , \fIqstat\fP , \fItouch\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/read.1p b/man1p/read.1p new file mode 100644 index 000000000..daf4e3ad0 --- /dev/null +++ b/man1p/read.1p @@ -0,0 +1,214 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "READ" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" read +.SH NAME +read \- read a line from standard input +.SH SYNOPSIS +.LP +\fBread\fP \fB[\fP\fB-r\fP\fB]\fP \fIvar\fP\fB...\fP +.SH DESCRIPTION +.LP +The \fIread\fP utility shall read a single line from standard input. +.LP +By default, unless the \fB-r\fP option is specified, backslash ( \fB'\\'\fP +) shall act as an escape character, as described +in \fIEscape Character (Backslash)\fP . If standard input is a terminal +device and the +invoking shell is interactive, \fIread\fP shall prompt for a continuation +line when: +.IP " *" 3 +The shell reads an input line ending with a backslash, unless the +\fB-r\fP option is specified. +.LP +.IP " *" 3 +A here-document is not terminated after a is entered. +.LP +.LP +The line shall be split into fields as in the shell (see \fIField +Splitting\fP ); +the first field shall be assigned to the first variable \fIvar\fP, +the second field to the second variable \fIvar\fP, and so on. +If there are fewer \fIvar\fP operands specified than there are fields, +the leftover fields and their intervening separators shall +be assigned to the last \fIvar\fP. If there are fewer fields than +\fIvar\fPs, the remaining \fIvar\fPs shall be set to empty +strings. +.LP +The setting of variables specified by the \fIvar\fP operands shall +affect the current shell execution environment; see \fIShell Execution +Environment\fP . If it is called in a subshell or separate utility +execution +environment, such as one of the following: +.sp +.RS +.nf + +\fB(read foo) +nohup read ... +find . -exec read ... \\; +\fP +.fi +.RE +.LP +it shall not affect the shell variables in the caller's environment. +.SH OPTIONS +.LP +The \fIread\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option is supported: +.TP 7 +\fB-r\fP +Do not treat a backslash character in any special way. Consider each +backslash to be part of the input line. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIvar\fP +The name of an existing or nonexisting shell variable. +.sp +.SH STDIN +.LP +The standard input shall be a text file. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIread\fP: +.TP 7 +\fIIFS\fP +Determine the internal field separators used to delimit fields; see +\fIShell +Variables\fP . +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPS2\fP +Provide the prompt string that an interactive shell shall write to +standard error when a line ending with a backslash is read +and the \fB-r\fP option was not specified, or if a here-document is +not terminated after a is entered. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used for diagnostic messages and prompts +for continued input. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +End-of-file was detected or an error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fB-r\fP option is included to enable \fIread\fP to subsume the +purpose of the \fIline\fP utility, which is not included +in IEEE\ Std\ 1003.1-2001. +.LP +The results are undefined if an end-of-file is detected following +a backslash at the end of a line when \fB-r\fP is not +specified. +.SH EXAMPLES +.LP +The following command: +.sp +.RS +.nf + +\fBwhile read -r xx yy +do + printf "%s %s\\n" "$yy" "$xx" +done <\fP \fIinput_file\fP +.fi +.RE +.LP +prints a file with the first field of each line moved to the end of +the line. +.SH RATIONALE +.LP +The \fIread\fP utility historically has been a shell built-in. It +was separated off into its own utility to take advantage of +the richer description of functionality introduced by this volume +of IEEE\ Std\ 1003.1-2001. +.LP +Since \fIread\fP affects the current shell execution environment, +it is generally provided as a shell regular built-in. If it +is called in a subshell or separate utility execution environment, +such as one of the following: +.sp +.RS +.nf + +\fB(read foo) +nohup read ... +find . -exec read ... \\; +\fP +.fi +.RE +.LP +it does not affect the shell variables in the environment of the caller. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/readonly.1p b/man1p/readonly.1p new file mode 100644 index 000000000..35e04085c --- /dev/null +++ b/man1p/readonly.1p @@ -0,0 +1,151 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "READONLY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" readonly +.SH NAME +readonly \- set the readonly attribute for variables +.SH SYNOPSIS +.LP +\fBreadonly name\fP\fB[\fP\fB=\fP\fIword\fP\fB]\fP\fB... +.br +.sp +readonly -p +.br +\fP +.SH DESCRIPTION +.LP +The variables whose \fIname\fPs are specified shall be given the \fIreadonly\fP +attribute. The values of variables with the +\fIreadonly\fP attribute cannot be changed by subsequent assignment, +nor can those variables be unset by the \fIunset\fP utility. If the +name of a variable is followed by = \fIword\fP, then the value of +that +variable shall be set to \fIword\fP. +.LP +The \fIreadonly\fP special built-in shall support the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +When \fB-p\fP is specified, \fIreadonly\fP writes to the standard +output the names and values of all read-only variables, in +the following format: +.sp +.RS +.nf + +\fB"readonly %s=%s\\n", <\fP\fIname\fP\fB>, <\fP\fIvalue\fP\fB> +\fP +.fi +.RE +.LP +if \fIname\fP is set, and +.sp +.RS +.nf + +\fB"readonly %s\\n", <\fP\fIname\fP\fB> +\fP +.fi +.RE +.LP +if \fIname\fP is unset. +.LP +The shell shall format the output, including the proper use of quoting, +so that it is suitable for reinput to the shell as +commands that achieve the same value and \fIreadonly\fP attribute-setting +results in a shell execution environment in which: +.IP " 1." 4 +Variables with values at the time they were output do not have the +\fIreadonly\fP attribute set. +.LP +.IP " 2." 4 +Variables that were unset at the time they were output do not have +a value at the time at which the saved output is reinput to +the shell. +.LP +.LP +When no arguments are given, the results are unspecified. +.SH OPTIONS +.LP +See the DESCRIPTION. +.SH OPERANDS +.LP +See the DESCRIPTION. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +None. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +See the DESCRIPTION. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +Zero. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.sp +.RS +.nf + +\fBreadonly HOME PWD +\fP +.fi +.RE +.SH RATIONALE +.LP +Some historical shells preserve the \fIreadonly\fP attribute across +separate invocations. This volume of +IEEE\ Std\ 1003.1-2001 allows this behavior, but does not require +it. +.LP +The \fB-p\fP option allows portable access to the values that can +be saved and then later restored using, for example, a \fIdot\fP script. +Also see the RATIONALE for \fIexport\fP +for a description of the no-argument and \fB-p\fP output cases and +a related example. +.LP +Read-only functions were considered, but they were omitted as not +being historical practice or particularly useful. Furthermore, +functions must not be read-only across invocations to preclude ``spoofing'' +(spoofing is the term for the practice of creating a +program that acts like a well-known utility with the intent of subverting +the real intent of the user) of administrative or +security-relevant (or security-conscious) shell scripts. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISpecial Built-In Utilities\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/renice.1p b/man1p/renice.1p new file mode 100644 index 000000000..8b92bbb5e --- /dev/null +++ b/man1p/renice.1p @@ -0,0 +1,251 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "RENICE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" renice +.SH NAME +renice \- set nice values of running processes +.SH SYNOPSIS +.LP +\fBrenice -n\fP \fIincrement\fP \fB[\fP\fB-g | -p | -u\fP\fB]\fP \fIID\fP +\fB\&... \fP +.SH DESCRIPTION +.LP +The \fIrenice\fP utility shall request that the nice values (see the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 3.239, Nice Value) of one or more running processes be changed. +By +default, the applicable processes are specified by their process IDs. +When a process group is specified (see \fB-g\fP), the +request shall apply to all processes in the process group. +.LP +The nice value shall be bounded in an implementation-defined manner. +If the requested \fIincrement\fP would raise or lower the +nice value of the executed utility beyond implementation-defined limits, +then the limit whose value was exceeded shall be used. +.LP +When a user is \fIrenice\fPd, the request applies to all processes +whose saved set-user-ID matches the user ID corresponding to +the user. +.LP +Regardless of which options are supplied or any other factor, \fIrenice\fP +shall not alter the nice values of any process +unless the user requesting such a change has appropriate privileges +to do so for the specified process. If the user lacks +appropriate privileges to perform the requested action, the utility +shall return an error status. +.LP +The saved set-user-ID of the user's process shall be checked instead +of its effective user ID when \fIrenice\fP attempts to +determine the user ID of the process in order to determine whether +the user has appropriate privileges. +.SH OPTIONS +.LP +The \fIrenice\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-g\fP +Interpret all operands as unsigned decimal integer process group IDs. +.TP 7 +\fB-n\ \fP \fIincrement\fP +Specify how the nice value of the specified process or processes is +to be adjusted. The \fIincrement\fP option-argument is a +positive or negative decimal integer that shall be used to modify +the nice value of the specified process or processes. +.LP +Positive \fIincrement\fP values shall cause a lower nice value. Negative +\fIincrement\fP values may require appropriate +privileges and shall cause a higher nice value. +.TP 7 +\fB-p\fP +Interpret all operands as unsigned decimal integer process IDs. The +\fB-p\fP option is the default if no options are +specified. +.TP 7 +\fB-u\fP +Interpret all operands as users. If a user exists with a user name +equal to the operand, then the user ID of that user is used +in further processing. Otherwise, if the operand represents an unsigned +decimal integer, it shall be used as the numeric user ID of +the user. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIID\fP +A process ID, process group ID, or user name/user ID, depending on +the option selected. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIrenice\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.IP " 1." 4 +Adjust the nice value so that process IDs 987 and 32 would have a +lower nice value: +.sp +.RS +.nf + +\fBrenice -n 5 -p 987 32 +\fP +.fi +.RE +.LP +.IP " 2." 4 +Adjust the nice value so that group IDs 324 and 76 would have a higher +nice value, if the user has the appropriate privileges to +do so: +.sp +.RS +.nf + +\fBrenice -n -4 -g 324 76 +\fP +.fi +.RE +.LP +.IP " 3." 4 +Adjust the nice value so that numeric user ID 8 and user \fBsas\fP +would have a lower nice value: +.sp +.RS +.nf + +\fBrenice -n 4 -u 8 sas +\fP +.fi +.RE +.LP +.LP +Useful nice value increments on historical systems include 19 or 20 +(the affected processes run only when nothing else in the +system attempts to run) and any negative number (to make processes +run faster). +.SH RATIONALE +.LP +The \fIgid\fP, \fIpid\fP, and \fIuser\fP specifications do not fit +either the definition of operand or option-argument. +However, for clarity, they have been included in the OPTIONS section, +rather than the OPERANDS section. +.LP +The definition of nice value is not intended to suggest that all processes +in a system have priorities that are comparable. +Scheduling policy extensions such as the realtime priorities in the +System Interfaces volume of IEEE\ Std\ 1003.1-2001 make +the notion of a single underlying priority for all scheduling policies +problematic. Some implementations may implement the \fInice\fP-related +features to affect all processes on the system, others to affect just +the general +time-sharing activities implied by this volume of IEEE\ Std\ 1003.1-2001, +and others may have no effect at all. Because of +the use of "implementation-defined" in \fInice\fP and \fIrenice\fP, +a wide range of +implementation strategies are possible. +.LP +Originally, this utility was written in the historical manner, using +the term "nice value". This was always a point of concern +with users because it was never intuitively obvious what this meant. +With a newer version of \fIrenice\fP, which used the term +"system scheduling priority", it was hoped that novice users could +better understand what this utility was meant to do. Also, it +would be easier to document what the utility was meant to do. Unfortunately, +the addition of the POSIX realtime scheduling +capabilities introduced the concepts of process and thread scheduling +priorities that were totally unaffected by the \fInice\fP/ \fIrenice\fP +utilities or the \fInice\fP()/ \fIsetpriority\fP() functions. Continuing +to use the term "system scheduling priority'' +would have incorrectly suggested that these utilities and functions +were indeed affecting these realtime priorities. It was decided +to revert to the historical term "nice value" to reference this unrelated +process attribute. +.LP +Although this utility has use by system administrators (and in fact +appears in the system administration portion of the BSD +documentation), the standard developers considered that it was very +useful for individual end users to control their own +processes. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fInice\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/return.1p b/man1p/return.1p new file mode 100644 index 000000000..86bbc321e --- /dev/null +++ b/man1p/return.1p @@ -0,0 +1,94 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "RETURN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" return +.SH NAME +return \- return from a function +.SH SYNOPSIS +.LP +\fBreturn\fP \fB[\fP\fIn\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIreturn\fP utility shall cause the shell to stop executing the +current function or \fIdot\fP script. If the shell is not currently +executing a function or \fIdot\fP script, the results are unspecified. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +See the DESCRIPTION. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +None. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The value of the special parameter \fB'?'\fP shall be set to \fIn\fP, +an unsigned decimal integer, or to the exit status of +the last command executed if \fIn\fP is not specified. If the value +of \fIn\fP is greater than 255, the results are undefined. +When \fIreturn\fP is executed in a \fItrap\fP action, the last command +is considered to be +the command that executed immediately preceding the \fItrap\fP action. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The behavior of \fIreturn\fP when not in a function or \fIdot\fP script +differs between +the System V shell and the KornShell. In the System V shell this is +an error, whereas in the KornShell, the effect is the same as +\fIexit\fP. +.LP +The results of returning a number greater than 255 are undefined because +of differing practices in the various historical +implementations. Some shells AND out all but the low-order 8 bits; +others allow larger values, but not of unlimited size. +.LP +See the discussion of appropriate exit status values under \fIexit\fP +\&. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISpecial Built-In Utilities\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/rm.1p b/man1p/rm.1p new file mode 100644 index 000000000..3b12db63e --- /dev/null +++ b/man1p/rm.1p @@ -0,0 +1,354 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "RM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" rm +.SH NAME +rm \- remove directory entries +.SH SYNOPSIS +.LP +\fBrm\fP \fB[\fP\fB-fiRr\fP\fB]\fP \fIfile\fP\fB...\fP +.SH DESCRIPTION +.LP +The \fIrm\fP utility shall remove the directory entry specified by +each \fIfile\fP argument. +.LP +If either of the files dot or dot-dot are specified as the basename +portion of an operand (that is, the final pathname +component), \fIrm\fP shall write a diagnostic message to standard +error and do nothing more with such operands. +.LP +For each \fIfile\fP the following steps shall be taken: +.IP " 1." 4 +If the \fIfile\fP does not exist: +.RS +.IP " a." 4 +If the \fB-f\fP option is not specified, \fIrm\fP shall write a diagnostic +message to standard error. +.LP +.IP " b." 4 +Go on to any remaining \fIfiles\fP. +.LP +.RE +.LP +.IP " 2." 4 +If \fIfile\fP is of type directory, the following steps shall be taken: +.RS +.IP " a." 4 +If neither the \fB-R\fP option nor the \fB-r\fP option is specified, +\fIrm\fP shall write a diagnostic message to standard +error, do nothing more with \fIfile\fP, and go on to any remaining +files. +.LP +.IP " b." 4 +If the \fB-f\fP option is not specified, and either the permissions +of \fIfile\fP do not permit writing and the standard input +is a terminal or the \fB-i\fP option is specified, \fIrm\fP shall +write a prompt to standard error and read a line from the +standard input. If the response is not affirmative, \fIrm\fP shall +do nothing more with the current file and go on to any +remaining files. +.LP +.IP " c." 4 +For each entry contained in \fIfile\fP, other than dot or dot-dot, +the four steps listed here (1 to 4) shall be taken with the +entry as if it were a \fIfile\fP operand. The \fIrm\fP utility shall +not traverse directories by following symbolic links into +other parts of the hierarchy, but shall remove the links themselves. +.LP +.IP " d." 4 +If the \fB-i\fP option is specified, \fIrm\fP shall write a prompt +to standard error and read a line from the standard input. +If the response is not affirmative, \fIrm\fP shall do nothing more +with the current file, and go on to any remaining files. +.LP +.RE +.LP +.IP " 3." 4 +If \fIfile\fP is not of type directory, the \fB-f\fP option is not +specified, and either the permissions of \fIfile\fP do not +permit writing and the standard input is a terminal or the \fB-i\fP +option is specified, \fIrm\fP shall write a prompt to the +standard error and read a line from the standard input. If the response +is not affirmative, \fIrm\fP shall do nothing more with +the current file and go on to any remaining files. +.LP +.IP " 4." 4 +If the current file is a directory, \fIrm\fP shall perform actions +equivalent to the \fIrmdir\fP() function defined in the System Interfaces +volume of IEEE\ Std\ 1003.1-2001 +called with a pathname of the current file used as the \fIpath\fP +argument. If the current file is not a directory, \fIrm\fP +shall perform actions equivalent to the \fIunlink\fP() function defined +in the System +Interfaces volume of IEEE\ Std\ 1003.1-2001 called with a pathname +of the current file used as the \fIpath\fP +argument. +.LP +If this fails for any reason, \fIrm\fP shall write a diagnostic message +to standard error, do nothing more with the current +file, and go on to any remaining files. +.LP +.LP +The \fIrm\fP utility shall be able to descend to arbitrary depths +in a file hierarchy, and shall not fail due to path length +limitations (unless an operand specified by the user exceeds system +limitations). +.SH OPTIONS +.LP +The \fIrm\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-f\fP +Do not prompt for confirmation. Do not write diagnostic messages or +modify the exit status in the case of nonexistent operands. +Any previous occurrences of the \fB-i\fP option shall be ignored. +.TP 7 +\fB-i\fP +Prompt for confirmation as described previously. Any previous occurrences +of the \fB-f\fP option shall be ignored. +.TP 7 +\fB-R\fP +Remove file hierarchies. See the DESCRIPTION. +.TP 7 +\fB-r\fP +Equivalent to \fB-R\fP. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a directory entry to be removed. +.sp +.SH STDIN +.LP +The standard input shall be used to read an input line in response +to each prompt specified in the STDOUT section. Otherwise, +the standard input shall not be used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIrm\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended +regular expression defined for the \fByesexpr\fP locale keyword in +the \fILC_MESSAGES\fP category. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments) and the behavior of +character classes within regular expressions used in the +extended regular expression defined for the \fByesexpr\fP locale keyword +in the \fILC_MESSAGES\fP category. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale for the processing of affirmative responses that +should be used to affect the format and contents of +diagnostic messages written to standard error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +Prompts shall be written to standard error under the conditions specified +in the DESCRIPTION and OPTIONS sections. The prompts +shall contain the \fIfile\fP pathname, but their format is otherwise +unspecified. The standard error also shall be used for +diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All of the named directory entries for which \fIrm\fP performed actions +equivalent to the \fIrmdir\fP() or \fIunlink\fP() functions were removed. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fIrm\fP utility is forbidden to remove the names dot and dot-dot +in order to avoid the consequences of inadvertently doing +something like: +.sp +.RS +.nf + +\fBrm -r .* +\fP +.fi +.RE +.LP +Some implementations do not permit the removal of the last link to +an executable binary file that is being executed; see the +[EBUSY] error in the \fIunlink\fP() function defined in the System +Interfaces volume of +IEEE\ Std\ 1003.1-2001. Thus, the \fIrm\fP utility can fail to remove +such files. +.LP +The \fB-i\fP option causes \fIrm\fP to prompt and read the standard +input even if the standard input is not a terminal, but in +the absence of \fB-i\fP the mode prompting is not done when the standard +input is not a terminal. +.SH EXAMPLES +.IP " 1." 4 +The following command: +.sp +.RS +.nf + +\fBrm a.out core +\fP +.fi +.RE +.LP +removes the directory entries: \fBa.out\fP and \fBcore\fP. +.LP +.IP " 2." 4 +The following command: +.sp +.RS +.nf + +\fBrm -Rf junk +\fP +.fi +.RE +.LP +removes the directory \fBjunk\fP and all its contents, without prompting. +.LP +.SH RATIONALE +.LP +For absolute clarity, paragraphs (2b) and (3) in the DESCRIPTION of +\fIrm\fP describing the behavior when prompting for +confirmation, should be interpreted in the following manner: +.sp +.RS +.nf + +\fBif ((NOT f_option) AND + ((not_writable AND input_is_terminal) OR i_option)) +\fP +.fi +.RE +.LP +The exact format of the interactive prompts is unspecified. Only the +general nature of the contents of prompts are specified +because implementations may desire more descriptive prompts than those +used on historical implementations. Therefore, an +application not using the \fB-f\fP option, or using the \fB-i\fP option, +relies on the system to provide the most suitable dialog +directly with the user, based on the behavior specified. +.LP +The \fB-r\fP option is historical practice on all known systems. The +synonym \fB-R\fP option is provided for consistency with +the other utilities in this volume of IEEE\ Std\ 1003.1-2001 that +provide options requesting recursive descent through the +file hierarchy. +.LP +The behavior of the \fB-f\fP option in historical versions of \fIrm\fP +is inconsistent. In general, along with "forcing" the +unlink without prompting for permission, it always causes diagnostic +messages to be suppressed and the exit status to be unmodified +for nonexistent operands and files that cannot be unlinked. In some +versions, however, the \fB-f\fP option suppresses usage +messages and system errors as well. Suppressing such messages is not +a service to either shell scripts or users. +.LP +It is less clear that error messages regarding files that cannot be +unlinked (removed) should be suppressed. Although this is +historical practice, this volume of IEEE\ Std\ 1003.1-2001 does not +permit the \fB-f\fP option to suppress such +messages. +.LP +When given the \fB-r\fP and \fB-i\fP options, historical versions +of \fIrm\fP prompt the user twice for each directory, once +before removing its contents and once before actually attempting to +delete the directory entry that names it. This allows the user +to "prune" the file hierarchy walk. Historical versions of \fIrm\fP +were inconsistent in that some did not do the former prompt +for directories named on the command line and others had obscure prompting +behavior when the \fB-i\fP option was specified and the +permissions of the file did not permit writing. The POSIX Shell and +Utilities \fIrm\fP differs little from historic practice, but +does require that prompts be consistent. Historical versions of \fIrm\fP +were also inconsistent in that prompts were done to both +standard output and standard error. This volume of IEEE\ Std\ 1003.1-2001 +requires that prompts be done to standard error, +for consistency with \fIcp\fP and \fImv\fP, and to allow +historical extensions to \fIrm\fP that provide an option to list deleted +files on standard output. +.LP +The \fIrm\fP utility is required to descend to arbitrary depths so +that any file hierarchy may be deleted. This means, for +example, that the \fIrm\fP utility cannot run out of file descriptors +during its descent (that is, if the number of file +descriptors is limited, \fIrm\fP cannot be implemented in the historical +fashion where one file descriptor is used per directory +level). Also, \fIrm\fP is not permitted to fail because of path length +restrictions, unless an operand specified by the user is +longer than {PATH_MAX}. +.LP +The \fIrm\fP utility removes symbolic links themselves, not the files +they refer to, as a consequence of the dependence on the +\fIunlink\fP() functionality, per the DESCRIPTION. When removing hierarchies +with \fB-r\fP +or \fB-R\fP, the prohibition on following symbolic links has to be +made explicit. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIrmdir\fP() , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIremove\fP(), \fIrmdir\fP(), \fIunlink\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/rmdel.1p b/man1p/rmdel.1p new file mode 100644 index 000000000..73c37c0b6 --- /dev/null +++ b/man1p/rmdel.1p @@ -0,0 +1,154 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "RMDEL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" rmdel +.SH NAME +rmdel \- remove a delta from an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBrmdel -r\fP \fISID file\fP\fB... \fP +.SH DESCRIPTION +.LP +The \fIrmdel\fP utility shall remove the delta specified by the SID +from each named SCCS file. The delta to be removed shall be +the most recent delta in its branch in the delta chain of each named +SCCS file. In addition, the application shall ensure that the +SID specified is not that of a version being edited for the purpose +of making a delta; that is, if a \fIp-file\fP (see \fIget\fP ) exists +for the named SCCS file, the SID specified shall not appear in any +entry of the +\fIp-file\fP. +.LP +Removal of a delta shall be restricted to: +.IP " 1." 4 +The user who made the delta +.LP +.IP " 2." 4 +The owner of the SCCS file +.LP +.IP " 3." 4 +The owner of the directory containing the SCCS file +.LP +.SH OPTIONS +.LP +The \fIrmdel\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-r\ \fP \fISID\fP +Specify the SCCS identification string ( \fISID\fP) of the delta to +be deleted. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of an existing SCCS file or a directory. If \fIfile\fP +is a directory, the \fIrmdel\fP utility shall behave as +though each file in the directory were specified as a named file, +except that non-SCCS files (last component of the pathname does +not begin with \fBs.\fP) and unreadable files shall be silently ignored. +.LP +If exactly one \fIfile\fP operand appears, and it is \fB'-'\fP , the +standard input shall be read; each line of the standard +input is taken to be the name of an SCCS file to be processed. Non-SCCS +files and unreadable files shall be silently ignored. +.sp +.SH STDIN +.LP +The standard input shall be a text file used only when the \fIfile\fP +operand is specified as \fB'-'\fP . Each line of the +text file shall be interpreted as an SCCS pathname. +.SH INPUT FILES +.LP +The SCCS files shall be files of unspecified format. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIrmdel\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +The SCCS files shall be files of unspecified format. During processing +of a \fIfile\fP, a temporary \fIx-file\fP, as described +in \fIadmin\fP , may be created and deleted; a locking \fIz-file\fP, +as described in \fIget\fP , may be created and deleted. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIadmin\fP , \fIdelta\fP , \fIget\fP , \fIprs\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/rmdir.1p b/man1p/rmdir.1p new file mode 100644 index 000000000..1f1971c60 --- /dev/null +++ b/man1p/rmdir.1p @@ -0,0 +1,177 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "RMDIR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" rmdir +.SH NAME +rmdir \- remove directories +.SH SYNOPSIS +.LP +\fBrmdir\fP \fB[\fP\fB-p\fP\fB]\fP \fIdir\fP\fB...\fP +.SH DESCRIPTION +.LP +The \fIrmdir\fP utility shall remove the directory entry specified +by each \fIdir\fP operand. +.LP +For each \fIdir\fP operand, the \fIrmdir\fP utility shall perform +actions equivalent to the \fIrmdir\fP() function called with the \fIdir\fP +operand as its only argument. +.LP +Directories shall be processed in the order specified. If a directory +and a subdirectory of that directory are specified in a +single invocation of the \fIrmdir\fP utility, the application shall +specify the subdirectory before the parent directory so that +the parent directory will be empty when the \fIrmdir\fP utility tries +to remove it. +.SH OPTIONS +.LP +The \fIrmdir\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-p\fP +Remove all directories in a pathname. For each \fIdir\fP operand: +.RS +.IP " 1." 4 +The directory entry it names shall be removed. +.LP +.IP " 2." 4 +If the \fIdir\fP operand includes more than one pathname component, +effects equivalent to the following command shall +occur: +.sp +.RS +.nf + +\fBrmdir -p $(dirname\fP \fIdir\fP\fB) +\fP +.fi +.RE +.LP +.RE +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIdir\fP +A pathname of an empty directory to be removed. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIrmdir\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Each directory entry specified by a \fIdir\fP operand was removed +successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The definition of an empty directory is one that contains, at most, +directory entries for dot and dot-dot. +.SH EXAMPLES +.LP +If a directory \fBa\fP in the current directory is empty except it +contains a directory \fBb\fP and \fBa/b\fP is empty except +it contains a directory \fBc\fP: +.sp +.RS +.nf + +\fBrmdir -p a/b/c +\fP +.fi +.RE +.LP +removes all three directories. +.SH RATIONALE +.LP +On historical System V systems, the \fB-p\fP option also caused a +message to be written to the standard output. The message +indicated whether the whole path was removed or whether part of the +path remained for some reason. The STDERR section requires this +diagnostic when the entire path specified by a \fIdir\fP operand is +not removed, but does not allow the status message reporting +success to be written as a diagnostic. +.LP +The \fIrmdir\fP utility on System V also included a \fB-s\fP option +that suppressed the informational message output by the +\fB-p\fP option. This option has been omitted because the informational +message is not specified by this volume of +IEEE\ Std\ 1003.1-2001. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIrm\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIremove\fP(), \fIrmdir\fP(), \fIunlink\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/sact.1p b/man1p/sact.1p new file mode 100644 index 000000000..54c56d876 --- /dev/null +++ b/man1p/sact.1p @@ -0,0 +1,174 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SACT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sact +.SH NAME +sact \- print current SCCS file-editing activity (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBsact\fP \fIfile\fP\fB... \fP +.SH DESCRIPTION +.LP +The \fIsact\fP utility shall inform the user of any impending deltas +to a named SCCS file by writing a list to standard output. +This situation occurs when \fIget\fP \fB-e\fP has been executed previously +without a +subsequent execution of \fIdelta\fP, \fIunget\fP, or +\fIsccs\fP \fBunedit\fP. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of an existing SCCS file or a directory. If \fIfile\fP +is a directory, the \fIsact\fP utility shall behave as +though each file in the directory were specified as a named file, +except that non-SCCS files (last component of the pathname does +not begin with \fBs.\fP) and unreadable files shall be silently ignored. +.LP +If exactly one \fIfile\fP operand appears, and it is \fB'-'\fP , the +standard input shall be read; each line of the standard +input shall be taken to be the name of an SCCS file to be processed. +Non-SCCS files and unreadable files shall be silently +ignored. +.sp +.SH STDIN +.LP +The standard input shall be a text file used only when the \fIfile\fP +operand is specified as \fB'-'\fP . Each line of the +text file shall be interpreted as an SCCS pathname. +.SH INPUT FILES +.LP +Any SCCS files interrogated are files of an unspecified format. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIsact\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The output for each named file shall consist of a line in the following +format: +.sp +.RS +.nf + +\fB"%s %s %s %s %s\\n", <\fP\fISID\fP\fB>, <\fP\fInew SID\fP\fB>, <\fP\fIlogin\fP\fB>, <\fP\fIdate\fP\fB>, <\fP\fItime\fP\fB> +\fP +.fi +.RE +.TP 7 +<\fISID\fP> +Specifies the SID of a delta that currently exists in the SCCS file +to which changes are made to make the new delta. +.TP 7 +<\fInew\ SID\fP> +Specifies the SID for the new delta to be created. +.TP 7 +<\fIlogin\fP> +Contains the login name of the user who makes the delta (that is, +who executed a \fIget\fP +for editing). +.TP 7 +<\fIdate\fP> +Contains the date that \fIget\fP \fB-e\fP was executed, in the format +used by the \fIprs\fP \fB:D:\fP data keyword. +.TP 7 +<\fItime\fP> +Contains the time that \fIget\fP \fB-e\fP was executed, in the format +used by the \fIprs\fP \fB:T:\fP data keyword. +.sp +.LP +If there is more than one named file or if a directory or standard +input is named, each pathname shall be written before each of +the preceding lines: +.sp +.RS +.nf + +\fB"\\n%s:\\n", <\fP\fIpathname\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for optional informative messages +concerning SCCS files with no impending deltas, and for +diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIdelta\fP , \fIget\fP , \fIsccs\fP , \fIunget\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/sccs.1p b/man1p/sccs.1p new file mode 100644 index 000000000..1616e0b38 --- /dev/null +++ b/man1p/sccs.1p @@ -0,0 +1,411 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SCCS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sccs +.SH NAME +sccs \- front end for the SCCS subsystem (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBsccs\fP \fB[\fP\fB-r\fP\fB][\fP\fB-d\fP \fIpath\fP\fB][\fP\fB-p\fP +\fIpath\fP\fB]\fP +\fIcommand\fP \fB[\fP\fIoptions\fP\fB...\fP\fB][\fP\fIoperands\fP\fB...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIsccs\fP utility is a front end to the SCCS programs. It also +includes the capability to run set-user-id to another user +to provide additional protection. +.LP +The \fIsccs\fP utility shall invoke the specified \fIcommand\fP with +the specified \fIoptions\fP and \fIoperands\fP. By +default, each of the \fIoperands\fP shall be modified by prefixing +it with the string \fB"SCCS/s."\fP . +.LP +The \fIcommand\fP can be the name of one of the SCCS utilities in +this volume of IEEE\ Std\ 1003.1-2001 ( \fIadmin\fP, \fIdelta\fP, +\fIget\fP, \fIprs\fP, \fIrmdel\fP, \fIsact\fP, \fIunget\fP, \fIval\fP, +or \fIwhat\fP) or one of the pseudo-utilities listed in the EXTENDED +DESCRIPTION section. +.SH OPTIONS +.LP +The \fIsccs\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that \fIoptions\fP operands are +actually options to be passed to the utility named by \fIcommand\fP. +When the portion of the command: +.sp +.RS +.nf + +\fIcommand\fP \fB[\fP\fIoptions\fP \fB...\fP \fB] [\fP\fIoperands\fP \fB...\fP \fB]\fP +.fi +.RE +.LP +is considered, all of the pseudo-utilities used as \fIcommand\fP shall +support the Utility Syntax Guidelines. Any of the other +SCCS utilities that can be invoked in this manner support the Guidelines +to the extent indicated by their individual OPTIONS +sections. +.LP +The following options shall be supported preceding the \fIcommand\fP +operand: +.TP 7 +\fB-d\ \fP \fIpath\fP +A pathname of a directory to be used as a root directory for the SCCS +files. The default shall be the current directory. The +\fB-d\fP option shall take precedence over the \fIPROJECTDIR\fP variable. +See \fB-p\fP. +.TP 7 +\fB-p\ \fP \fIpath\fP +A pathname of a directory in which the SCCS files are located. The +default shall be the \fBSCCS\fP directory. +.LP +The \fB-p\fP option differs from the \fB-d\fP option in that the \fB-d\fP +option-argument shall be prefixed to the entire +pathname and the \fB-p\fP option-argument shall be inserted before +the final component of the pathname. For example: +.sp +.RS +.nf + +\fBsccs -d /x -p y get a/b +\fP +.fi +.RE +.LP +converts to: +.sp +.RS +.nf + +\fBget /x/a/y/s.b +\fP +.fi +.RE +.LP +This allows the creation of aliases such as: +.sp +.RS +.nf + +\fBalias syssccs="sccs -d /usr/src" +\fP +.fi +.RE +.LP +which is used as: +.sp +.RS +.nf + +\fBsyssccs get cmd/who.c +\fP +.fi +.RE +.TP 7 +\fB-r\fP +Invoke \fIcommand\fP with the real user ID of the process, not any +effective user ID that the \fIsccs\fP utility is set to. +Certain commands ( \fIadmin\fP, \fBcheck\fP, \fBclean\fP, \fBdiffs\fP, +\fBinfo\fP, \fIrmdel\fP, and \fBtell\fP) cannot be run set-user-ID +by all users, since this would allow +anyone to change the authorizations. These commands are always run +as the real user. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIcommand\fP +An SCCS utility name or the name of one of the pseudo-utilities listed +in the EXTENDED DESCRIPTION section. +.TP 7 +\fIoptions\fP +An option or option-argument to be passed to \fIcommand\fP. +.TP 7 +\fIoperands\fP +An operand to be passed to \fIcommand\fP. +.sp +.SH STDIN +.LP +See the utility description for the specified \fIcommand\fP. +.SH INPUT FILES +.LP +See the utility description for the specified \fIcommand\fP. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIsccs\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPROJECTDIR\fP +.sp +Provide a default value for the \fB-d\fP \fIpath\fP option. If the +value of \fIPROJECTDIR\fP begins with a slash, it shall be +considered an absolute pathname; otherwise, the value of \fIPROJECTDIR\fP +is treated as a user name and that user's initial +working directory shall be examined for a subdirectory \fBsrc\fP or +\fBsource\fP. If such a directory is found, it shall be used. +Otherwise, the value shall be used as a relative pathname. +.sp +.LP +Additional environment variable effects may be found in the utility +description for the specified \fIcommand\fP. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +See the utility description for the specified \fIcommand\fP. +.SH STDERR +.LP +See the utility description for the specified \fIcommand\fP. +.SH OUTPUT FILES +.LP +See the utility description for the specified \fIcommand\fP. +.SH EXTENDED DESCRIPTION +.LP +The following pseudo-utilities shall be supported as \fIcommand\fP +operands. All options referred to in the following list are +values given in the \fIoptions\fP operands following \fIcommand\fP. +.TP 7 +\fBcheck\fP +Equivalent to \fBinfo\fP, except that nothing shall be printed if +nothing is being edited, and a non-zero exit status shall be +returned if anything is being edited. The intent is to have this included +in an "install" entry in a makefile to ensure that +everything is included into the SCCS file before a version is installed. +.TP 7 +\fBclean\fP +Remove everything from the current directory that can be recreated +from SCCS files, but do not remove any files being edited. +If the \fB-b\fP option is given, branches shall be ignored in the +determination of whether they are being edited; this is +dangerous if branches are kept in the same directory. +.TP 7 +\fBcreate\fP +Create an SCCS file, taking the initial contents from the file of +the same name. Any options to \fIadmin\fP are accepted. If the creation +is successful, the original files shall be renamed by +prefixing the basenames with a comma. These renamed files should be +removed after it has been verified that the SCCS files have +been created successfully. +.TP 7 +\fBdelget\fP +Perform a \fIdelta\fP on the named files and then \fIget\fP new versions. +The new versions shall have ID keywords expanded and shall not be +editable. +Any \fB-m\fP, \fB-p\fP, \fB-r\fP, \fB-s\fP, and \fB-y\fP options shall +be passed to \fIdelta\fP, and any \fB-b\fP, \fB-c\fP, \fB-e\fP, \fB-i\fP, +\fB-k\fP, \fB-l\fP, \fB-s\fP, +and \fB-x\fP options shall be passed to \fIget\fP. +.TP 7 +\fBdeledit\fP +Equivalent to \fBdelget\fP, except that the \fIget\fP phase shall +include the \fB-e\fP +option. This option is useful for making a checkpoint of the current +editing phase. The same options shall be passed to \fIdelta\fP as +described above, and all the options listed for \fIget\fP above except +\fB-e\fP shall be passed to \fBedit\fP. +.TP 7 +\fBdiffs\fP +Write a difference listing between the current version of the files +checked out for editing and the versions in SCCS format. +Any \fB-r\fP, \fB-c\fP, \fB-i\fP, \fB-x\fP, and \fB-t\fP options shall +be passed to \fIget\fP; any \fB-l\fP, \fB-s\fP, \fB-e\fP, \fB-f\fP, +\fB-h\fP, and \fB-b\fP options shall be +passed to \fIdiff\fP. A \fB-C\fP option shall be passed to \fIdiff\fP +as \fB-c\fP. +.TP 7 +\fBedit\fP +Equivalent to \fIget\fP \fB-e\fP. +.TP 7 +\fBfix\fP +Remove the named delta, but leave a copy of the delta with the changes +that were in it. It is useful for fixing small compiler +bugs, and so on. The application shall ensure that it is followed +by a \fB-r\fP \fISID\fP option. Since \fBfix\fP does not leave +audit trails, it should be used carefully. +.TP 7 +\fBinfo\fP +Write a listing of all files being edited. If the \fB-b\fP option +is given, branches (that is, SIDs with two or fewer +components) shall be ignored. If a \fB-u\fP \fIuser\fP option is given, +then only files being edited by the named user shall be +listed. A \fB-U\fP option shall be equivalent to \fB-u\fP< \fIcurrent\ user\fP>. +.TP 7 +\fBprint\fP +Write out verbose information about the named files, equivalent to +\fIsccs\fP \fIprs\fP. +.TP 7 +\fBtell\fP +Write a -separated list of the files being edited to standard +output. Takes the \fB-b\fP, \fB-u\fP, and +\fB-U\fP options like \fBinfo\fP and \fBcheck\fP. +.TP 7 +\fBunedit\fP +This is the opposite of an \fBedit\fP or a \fIget\fP \fB-e\fP. It +should be used with +caution, since any changes made since the \fIget\fP are lost. +.sp +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Many of the SCCS utilities take directory names as operands as well +as specific filenames. The pseudo-utilities supported by +\fIsccs\fP are not described as having this capability, but are not +prohibited from doing so. +.SH EXAMPLES +.IP " 1." 4 +To get a file for editing, edit it and produce a new delta: +.sp +.RS +.nf + +\fBsccs get -e file.c +ex file.c +sccs delta file.c +\fP +.fi +.RE +.LP +.IP " 2." 4 +To get a file from another directory: +.sp +.RS +.nf + +\fBsccs -p /usr/src/sccs/s. get cc.c +\fP +.fi +.RE +.LP +or: +.sp +.RS +.nf + +\fBsccs get /usr/src/sccs/s.cc.c +\fP +.fi +.RE +.LP +.IP " 3." 4 +To make a delta of a large number of files in the current directory: +.sp +.RS +.nf + +\fBsccs delta *.c +\fP +.fi +.RE +.LP +.IP " 4." 4 +To get a list of files being edited that are not on branches: +.sp +.RS +.nf + +\fBsccs info -b +\fP +.fi +.RE +.LP +.IP " 5." 4 +To delta everything being edited by the current user: +.sp +.RS +.nf + +\fBsccs delta $(sccs tell -U) +\fP +.fi +.RE +.LP +.IP " 6." 4 +In a makefile, to get source files from an SCCS file if it does not +already exist: +.sp +.RS +.nf + +\fBSRCS = <\fP\fIlist of source files\fP\fB> +$(SRCS): + sccs get $(REL) $@ +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +SCCS and its associated utilities are part of the XSI Development +Utilities option within the XSI extension. +.LP +SCCS is an abbreviation for Source Code Control System. It is a maintenance +and enhancement tracking tool. When a file is put +under SCCS, the source code control system maintains the file and, +when changes are made, identifies and stores them in the file +with the original source code and/or documentation. As other changes +are made, they too are identified and retained in the +file. +.LP +Retrieval of the original and any set of changes is possible. Any +version of the file as it develops can be reconstructed for +inspection or additional modification. History data can be stored +with each version, documenting why the changes were made, who +made them, and when they were made. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIadmin\fP , \fIdelta\fP , \fIget\fP , \fImake\fP , \fIprs\fP , \fIrmdel\fP +, \fIsact\fP , \fIunget\fP , \fIval\fP , \fIwhat\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/sed.1p b/man1p/sed.1p new file mode 100644 index 000000000..d1ea019ae --- /dev/null +++ b/man1p/sed.1p @@ -0,0 +1,733 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sed +.SH NAME +sed \- stream editor +.SH SYNOPSIS +.LP +\fBsed\fP \fB[\fP\fB-n\fP\fB]\fP \fIscript\fP\fB[\fP\fIfile\fP\fB...\fP\fB]\fP\fB +.br +.sp +sed\fP \fB[\fP\fB-n\fP\fB][\fP\fB-e\fP \fIscript\fP\fB]\fP\fB...\fP\fB[\fP\fB-f\fP +\fIscript_file\fP\fB]\fP\fB...\fP\fB[\fP\fIfile\fP\fB...\fP\fB]\fP\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsed\fP utility is a stream editor that shall read one or more +text files, make editing changes according to a script of +editing commands, and write the results to standard output. The script +shall be obtained from either the \fIscript\fP operand +string or a combination of the option-arguments from the \fB-e\fP +\fIscript\fP and \fB-f\fP \fIscript_file\fP options. +.SH OPTIONS +.LP +The \fIsed\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that the order of presentation of the +\fB-e\fP and \fB-f\fP options is significant. +.LP +The following options shall be supported: +.TP 7 +\fB-e\ \fP \fIscript\fP +Add the editing commands specified by the \fIscript\fP option-argument +to the end of the script of editing commands. The +\fIscript\fP option-argument shall have the same properties as the +\fIscript\fP operand, described in the OPERANDS section. +.TP 7 +\fB-f\ \fP \fIscript_file\fP +Add the editing commands in the file \fIscript_file\fP to the end +of the script. +.TP 7 +\fB-n\fP +Suppress the default output (in which each line, after it is examined +for editing, is written to standard output). Only lines +explicitly selected for output are written. +.sp +.LP +Multiple \fB-e\fP and \fB-f\fP options may be specified. All commands +shall be added to the script in the order specified, +regardless of their origin. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile\fP +A pathname of a file whose contents are read and edited. If multiple +\fIfile\fP operands are specified, the named files shall +be read in the order specified and the concatenation shall be edited. +If no \fIfile\fP operands are specified, the standard input +shall be used. +.TP 7 +\fIscript\fP +A string to be used as the script of editing commands. The application +shall not present a \fIscript\fP that violates the +restrictions of a text file except that the final character need not +be a . +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified. See the INPUT FILES section. +.SH INPUT FILES +.LP +The input files shall be text files. The \fIscript_file\fPs named +by the \fB-f\fP option shall consist of editing +commands. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIsed\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular +expressions. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), and +the behavior of character classes within regular +expressions. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The input files shall be written to standard output, with the editing +commands specified in the script applied. If the \fB-n\fP +option is specified, only those input lines selected by the script +shall be written to standard output. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +The output files shall be text files whose formats are dependent on +the editing commands given. +.SH EXTENDED DESCRIPTION +.LP +The \fIscript\fP shall consist of editing commands of the following +form: +.sp +.RS +.nf + +\fB[\fP\fIaddress\fP\fB[\fP\fB,\fP\fIaddress\fP\fB]]\fP\fIfunction\fP +.fi +.RE +.LP +where \fIfunction\fP represents a single-character command verb from +the list in Editing Commands +in sed , followed by any applicable arguments. +.LP +The command can be preceded by s and/or semicolons. The function +can be preceded by s. These optional +characters shall have no effect. +.LP +In default operation, \fIsed\fP cyclically shall append a line of +input, less its terminating , into the pattern +space. Normally the pattern space will be empty, unless a \fBD\fP +command terminated the last cycle. The \fIsed\fP utility shall +then apply in sequence all commands whose addresses select that pattern +space, and at the end of the script copy the pattern space +to standard output (except when \fB-n\fP is specified) and delete +the pattern space. Whenever the pattern space is written to +standard output or a named file, \fIsed\fP shall immediately follow +it with a . +.LP +Some of the editing commands use a hold space to save all or part +of the pattern space for subsequent retrieval. The pattern and +hold spaces shall each be able to hold at least 8192 bytes. +.SS Addresses in sed +.LP +An address is either a decimal number that counts input lines cumulatively +across files, a \fB'$'\fP character that addresses +the last line of input, or a context address (which consists of a +BRE, as described in Regular +Expressions in sed , preceded and followed by a delimiter, usually +a slash). +.LP +An editing command with no addresses shall select every pattern space. +.LP +An editing command with one address shall select each pattern space +that matches the address. +.LP +An editing command with two addresses shall select the inclusive range +from the first pattern space that matches the first +address through the next pattern space that matches the second. (If +the second address is a number less than or equal to the line +number first selected, only one line shall be selected.) Starting +at the first line following the selected range, \fIsed\fP shall +look again for the first address. Thereafter, the process shall be +repeated. Omitting either or both of the address components in +the following form produces undefined results: +.sp +.RS +.nf + +\fB[\fP\fIaddress\fP\fB[\fP\fB,\fP\fIaddress\fP\fB]]\fP +.fi +.RE +.SS Regular Expressions in sed +.LP +The \fIsed\fP utility shall support the BREs described in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 9.3, Basic Regular +Expressions, with the following additions: +.IP " *" 3 +In a context address, the construction \fB"\\cBREc"\fP , where \fIc\fP +is any character other than backslash or +, shall be identical to \fB"/BRE/"\fP . If the character +designated by \fIc\fP appears following a backslash, +then it shall be considered to be that literal character, which shall +not terminate the BRE. For example, in the context address +\fB"\\xabc\\xdefx"\fP , the second \fIx\fP stands for itself, so that +the BRE is \fB"abcxdef"\fP . +.LP +.IP " *" 3 +The escape sequence \fB'\\n'\fP shall match a embedded in +the pattern space. A literal shall +not be used in the BRE of a context address or in the substitute function. +.LP +.IP " *" 3 +If an RE is empty (that is, no pattern is specified) \fIsed\fP shall +behave as if the last RE used in the last command applied +(either as an address or as part of a substitute command) was specified. +.LP +.SS Editing Commands in sed +.LP +In the following list of editing commands, the maximum number of permissible +addresses for each function is indicated by [ +\fI0addr\fP], [ \fI1addr\fP], or [ \fI2addr\fP], representing zero, +one, or two addresses. +.LP +The argument \fItext\fP shall consist of one or more lines. Each embedded + in the text shall be preceded by a +backslash. Other backslashes in text shall be removed, and the following +character shall be treated literally. +.LP +The \fBr\fP and \fBw\fP command verbs, and the \fIw\fP flag to the +\fBs\fP command, take an optional \fIrfile\fP (or +\fIwfile\fP) parameter, separated from the command verb letter or +flag by one or more s; implementations may allow +zero separation as an extension. +.LP +The argument \fIrfile\fP or the argument \fIwfile\fP shall terminate +the editing command. Each \fIwfile\fP shall be created +before processing begins. Implementations shall support at least ten +\fIwfile\fP arguments in the script; the actual number +(greater than or equal to 10) that is supported by the implementation +is unspecified. The use of the \fIwfile\fP parameter shall +cause that file to be initially created, if it does not exist, or +shall replace the contents of an existing file. +.LP +The \fBb\fP, \fBr\fP, \fBs\fP, \fBt\fP, \fBw\fP, \fBy\fP, and \fB:\fP +command verbs shall accept additional arguments. +The following synopses indicate which arguments shall be separated +from the command verbs by a single . +.LP +The \fBa\fP and \fBr\fP commands schedule text for later output. The +text specified for the \fBa\fP command, and the contents +of the file specified for the \fBr\fP command, shall be written to +standard output just before the next attempt to fetch a line of +input when executing the \fBN\fP or \fBn\fP commands, or when reaching +the end of the script. If written when reaching the end of +the script, and the \fB-n\fP option was not specified, the text shall +be written after copying the pattern space to standard +output. The contents of the file specified for the \fBr\fP command +shall be as of the time the output is written, not the time the +\fBr\fP command is applied. The text shall be output in the order +in which the \fBa\fP and \fBr\fP commands were applied to the +input. +.LP +Command verbs other than \fB{\fP, \fBa\fP, \fBb\fP, \fBc\fP, \fBi\fP, +\fBr\fP, \fBt\fP, \fBw\fP, \fB:\fP, and \fB#\fP +can be followed by a semicolon, optional s, and another command +verb. However, when the \fBs\fP command verb is used +with the \fIw\fP flag, following it with another command in this manner +produces undefined results. +.LP +A function can be preceded by one or more \fB'!'\fP characters, in +which case the function shall be applied if the addresses +do not select the pattern space. Zero or more s shall be accepted +before the first \fB'!'\fP character. It is +unspecified whether s can follow a \fB'!'\fP character, and +conforming applications shall not follow a \fB'!'\fP +character with s. +.TP 7 +\fB[\fP\fI2addr\fP\fB]\ {\fP\fIfunction\fP +.TP 7 +\fIfunction\fP +.TP 7 +\&... +.TP 7 +\fB}\fP +Execute a list of \fIsed\fP functions only when the pattern space +is selected. The list of \fIsed\fP functions shall be +surrounded by braces and separated by s, and conform to the +following rules. The braces can be preceded or followed +by s. The functions can be preceded by s, but shall +not be followed by s. The + shall be preceded by a and can be preceded +or followed by s. +.TP 7 +\fB[\fP\fI1addr\fP\fB]a\\\fP +.TP 7 +\fItext\fP +Write text to standard output as described previously. +.TP 7 +\fB[\fP\fI2addr\fP\fB]b\ [\fP\fIlabel\fP\fB]\fP +.sp +Branch to the \fB:\fP function bearing the \fIlabel\fP. If \fIlabel\fP +is not specified, branch to the end of the script. The +implementation shall support \fIlabel\fPs recognized as unique up +to at least 8 characters; the actual length (greater than or +equal to 8) that shall be supported by the implementation is unspecified. +It is unspecified whether exceeding a label length causes +an error or a silent truncation. +.TP 7 +\fB[\fP\fI2addr\fP\fB]c\\\fP +.TP 7 +\fItext\fP +Delete the pattern space. With a 0 or 1 address or at the end of a +2-address range, place \fItext\fP on the output and start +the next cycle. +.TP 7 +\fB[\fP\fI2addr\fP\fB]d\fP +Delete the pattern space and start the next cycle. +.TP 7 +\fB[\fP\fI2addr\fP\fB]D\fP +Delete the initial segment of the pattern space through the first + and start the next cycle. +.TP 7 +\fB[\fP\fI2addr\fP\fB]g\fP +Replace the contents of the pattern space by the contents of the hold +space. +.TP 7 +\fB[\fP\fI2addr\fP\fB]G\fP +Append to the pattern space a followed by the contents of +the hold space. +.TP 7 +\fB[\fP\fI2addr\fP\fB]h\fP +Replace the contents of the hold space with the contents of the pattern +space. +.TP 7 +\fB[\fP\fI2addr\fP\fB]H\fP +Append to the hold space a followed by the contents of the +pattern space. +.TP 7 +\fB[\fP\fI1addr\fP\fB]i\\\fP +.TP 7 +\fItext\fP +Write \fItext\fP to standard output. +.TP 7 +\fB[\fP\fI2addr\fP\fB]l\fP +(The letter ell.) Write the pattern space to standard output in a +visually unambiguous form. The characters listed in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Table 5-1, Escape Sequences +and Associated Actions ( \fB'\\\\'\fP , +\fB'\\a'\fP , \fB'\\b'\fP , \fB'\\f'\fP , \fB'\\r'\fP , \fB'\\t'\fP +, \fB'\\v'\fP ) shall be written as the +corresponding escape sequence; the \fB'\\n'\fP in that table is not +applicable. Non-printable characters not in that table shall +be written as one three-digit octal number (with a preceding backslash) +for each byte in the character (most significant byte +first). If the size of a byte on the system is greater than 9 bits, +the format used for non-printable characters is +implementation-defined. +.LP +Long lines shall be folded, with the point of folding indicated by +writing a backslash followed by a ; the length +at which folding occurs is unspecified, but should be appropriate +for the output device. The end of each line shall be marked with +a \fB'$'\fP . +.TP 7 +\fB[\fP\fI2addr\fP\fB]n\fP +Write the pattern space to standard output if the default output has +not been suppressed, and replace the pattern space with +the next line of input, less its terminating . +.LP +If no next line of input is available, the \fBn\fP command verb shall +branch to the end of the script and quit without starting +a new cycle. +.TP 7 +\fB[\fP\fI2addr\fP\fB]N\fP +Append the next line of input, less its terminating , to +the pattern space, using an embedded to +separate the appended material from the original material. Note that +the current line number changes. +.LP +If no next line of input is available, the \fBN\fP command verb shall +branch to the end of the script and quit without starting +a new cycle or copying the pattern space to standard output. +.TP 7 +\fB[\fP\fI2addr\fP\fB]p\fP +Write the pattern space to standard output. +.TP 7 +\fB[\fP\fI2addr\fP\fB]P\fP +Write the pattern space, up to the first , to standard output. +.TP 7 +\fB[\fP\fI1addr\fP\fB]q\fP +Branch to the end of the script and quit without starting a new cycle. +.TP 7 +\fB[\fP\fI1addr\fP\fB]r\ \fP \fIrfile\fP +Copy the contents of \fIrfile\fP to standard output as described previously. +If \fIrfile\fP does not exist or cannot be read, +it shall be treated as if it were an empty file, causing no error +condition. +.TP 7 +\fB[\fP\fI2addr\fP\fB]s/\fP\fIBRE\fP\fB/\fP\fIreplacement\fP\fB/\fP\fIflags\fP +.sp +Substitute the replacement string for instances of the BRE in the +pattern space. Any character other than backslash or + can be used instead of a slash to delimit the BRE and the +replacement. Within the BRE and the replacement, the BRE +delimiter itself can be used as a literal character if it is preceded +by a backslash. +.LP +The replacement string shall be scanned from beginning to end. An +ampersand ( \fB'&'\fP ) appearing in the replacement +shall be replaced by the string matching the BRE. The special meaning +of \fB'&'\fP in this context can be suppressed by +preceding it by a backslash. The characters \fB"\\\fP\fIn"\fP, where +\fIn\fP is a digit, shall be replaced by the text matched +by the corresponding backreference expression. The special meaning +of \fB"\\\fP\fIn"\fP where \fIn\fP is a digit in this +context, can be suppressed by preceding it by a backslash. For each +other backslash ( \fB'\\'\fP ) encountered, the following +character shall lose its special meaning (if any). The meaning of +a \fB'\\'\fP immediately followed by any character other than +\fB'&'\fP , \fB'\\'\fP , a digit, or the delimiter character used +for this command, is unspecified. +.LP +A line can be split by substituting a into it. The application +shall escape the in the +replacement by preceding it by a backslash. A substitution shall be +considered to have been performed even if the replacement +string is identical to the string that it replaces. Any backslash +used to alter the default meaning of a subsequent character shall +be discarded from the BRE or the replacement before evaluating the +BRE or using the replacement. +.LP +The value of \fIflags\fP shall be zero or more of: +.TP 7 +\fIn\fP +.RS +Substitute for the \fIn\fPth occurrence only of the BRE found within +the pattern space. +.RE +.TP 7 +\fBg\fP +.RS +Globally substitute for all non-overlapping instances of the BRE rather +than just the first one. If both \fBg\fP and \fIn\fP +are specified, the results are unspecified. +.RE +.TP 7 +\fBp\fP +.RS +Write the pattern space to standard output if a replacement was made. +.RE +.TP 7 +\fBw\ \fP \fIwfile\fP +.RS +Write. Append the pattern space to \fIwfile\fP if a replacement was +made. A conforming application shall precede the +\fIwfile\fP argument with one or more s. If the \fBw\fP flag +is not the last flag value given in a concatenation of +multiple flag values, the results are undefined. +.RE +.sp +.TP 7 +\fB[\fP\fI2addr\fP\fB]t\ [\fP\fIlabel\fP\fB]\fP +.sp +Test. Branch to the \fB:\fP command verb bearing the \fIlabel\fP if +any substitutions have been made since the most recent +reading of an input line or execution of a \fBt\fP. If \fIlabel\fP +is not specified, branch to the end of the script. +.TP 7 +\fB[\fP\fI2addr\fP\fB]w\ \fP \fIwfile\fP +.sp +Append (write) the pattern space to \fIwfile\fP. +.TP 7 +\fB[\fP\fI2addr\fP\fB]x\fP +Exchange the contents of the pattern and hold spaces. +.TP 7 +\fB[\fP\fI2addr\fP\fB]y/\fP\fIstring1\fP\fB/\fP\fIstring2\fP\fB/\fP +.sp +Replace all occurrences of characters in \fIstring1\fP with the corresponding +characters in \fIstring2\fP. If a backslash +followed by an \fB'n'\fP appear in \fIstring1\fP or \fIstring2\fP, +the two characters shall be handled as a single +. If the number of characters in \fIstring1\fP and \fIstring2\fP +are not equal, or if any of the characters in +\fIstring1\fP appear more than once, the results are undefined. Any +character other than backslash or can be used +instead of slash to delimit the strings. If the delimiter is not \fIn\fP, +within \fIstring1\fP and \fIstring2\fP, the delimiter +itself can be used as a literal character if it is preceded by a backslash. +If a backslash character is immediately followed by a +backslash character in \fIstring1\fP or \fIstring2\fP, the two backslash +characters shall be counted as a single literal +backslash character. The meaning of a backslash followed by any character +that is not \fB'n'\fP , a backslash, or the delimiter +character is undefined. +.TP 7 +\fB[\fP\fI0addr\fP\fB]:\fP\fIlabel\fP +Do nothing. This command bears a \fIlabel\fP to which the \fBb\fP +and \fBt\fP commands branch. +.TP 7 +\fB[\fP\fI1addr\fP\fB]=\fP +Write the following to standard output: +.sp +.RS +.nf + +\fB"%d\\n", <\fP\fIcurrent line number\fP\fB> +\fP +.fi +.RE +.TP 7 +\fB[\fP\fI0addr\fP\fB]\fP +Ignore this empty command. +.TP 7 +\fB[\fP\fI0addr\fP\fB]#\fP +Ignore the \fB'#'\fP and the remainder of the line (treat them as +a comment), with the single exception that if the first +two characters in the script are \fB"#n"\fP , the default output shall +be suppressed; this shall be the equivalent of specifying +\fB-n\fP on the command line. +.sp +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Regular expressions match entire strings, not just individual lines, +but a is matched by \fB'\\n'\fP in a +\fIsed\fP RE; a is not allowed by the general definition +of regular expression in IEEE\ Std\ 1003.1-2001. +Also note that \fB'\\n'\fP cannot be used to match a at +the end of an arbitrary input line; s +appear in the pattern space as a result of the \fBN\fP editing command. +.SH EXAMPLES +.LP +This \fIsed\fP script simulates the BSD \fIcat\fP \fB-s\fP command, +squeezing excess +blank lines from standard input. +.sp +.RS +.nf + +\fBsed -n ' +# Write non-empty lines. +/./ { + p + d + } +# Write a single empty line, then look for more empty lines. +/^$/ p +# Get next line, discard the held (empty line), +# and look for more empty lines. +:Empty +/^$/ { + N + s/.// + b Empty + } +# Write the non-empty line before going back to search +# for the first in a set of empty lines. + p +' +\fP +.fi +.RE +.SH RATIONALE +.LP +This volume of IEEE\ Std\ 1003.1-2001 requires implementations to +support at least ten distinct \fIwfile\fPs, matching +historical practice on many implementations. Implementations are encouraged +to support more, but conforming applications should not +exceed this limit. +.LP +The exit status codes specified here are different from those in System +V. System V returns 2 for garbled \fIsed\fP commands, +but returns zero with its usage message or if the input file could +not be opened. The standard developers considered this to be a +bug. +.LP +The manner in which the \fBl\fP command writes non-printable characters +was changed to avoid the historical +backspace-overstrike method, and other requirements to achieve unambiguous +output were added. See the RATIONALE for \fIed\fP for details of the +format chosen, which is the same as that chosen for \fIsed\fP. +.LP +This volume of IEEE\ Std\ 1003.1-2001 requires implementations to +provide pattern and hold spaces of at least 8192 +bytes, larger than the 4000 bytes spaces used by some historical implementations, +but less than the 20480 bytes limit used in an +early proposal. Implementations are encouraged to allocate dynamically +larger pattern and hold spaces as needed. +.LP +The requirements for acceptance of s and s in command +lines has been made more explicit than in early +proposals to describe clearly the historical practice and to remove +confusion about the phrase "protect initial blanks +[\fIsic\fP] and tabs from the stripping that is done on every script +line" that appears in much of the historical documentation +of the \fIsed\fP utility description of text. (Not all implementations +are known to have stripped s from text lines, +although they all have allowed leading s preceding the address +on a command line.) +.LP +The treatment of \fB'#'\fP comments differs from the SVID which only +allows a comment as the first line of the script, but +matches BSD-derived implementations. The comment character is treated +as a command, and it has the same properties in terms of +being accepted with leading s; the BSD implementation has historically +supported this. +.LP +Early proposals required that a \fIscript_file\fP have at least one +non-comment line. Some historical implementations have +behaved in unexpected ways if this were not the case. The standard +developers considered that this was incorrect behavior and that +application developers should not have to avoid this feature. A correct +implementation of this volume of +IEEE\ Std\ 1003.1-2001 shall permit \fIscript_file\fPs that consist +only of comment lines. +.LP +Early proposals indicated that if \fB-e\fP and \fB-f\fP options were +intermixed, all \fB-e\fP options were processed before +any \fB-f\fP options. This has been changed to process them in the +order presented because it matches historical practice and is +more intuitive. +.LP +The treatment of the \fBp\fP flag to the \fBs\fP command differs between +System V and BSD-based systems when the default +output is suppressed. In the two examples: +.sp +.RS +.nf + +\fBecho a | sed 's/a/A/p' +echo a | sed -n 's/a/A/p' +\fP +.fi +.RE +.LP +this volume of IEEE\ Std\ 1003.1-2001, BSD, System V documentation, +and the SVID indicate that the first example should +write two lines with \fBA\fP, whereas the second should write one. +Some System V systems write the \fBA\fP only once in both +examples because the \fBp\fP flag is ignored if the \fB-n\fP option +is not specified. +.LP +This is a case of a diametrical difference between systems that could +not be reconciled through the compromise of declaring the +behavior to be unspecified. The SVID/BSD/System V documentation behavior +was adopted for this volume of +IEEE\ Std\ 1003.1-2001 because: +.IP " *" 3 +No known documentation for any historic system describes the interaction +between the \fBp\fP flag and the \fB-n\fP option. +.LP +.IP " *" 3 +The selected behavior is more correct as there is no technical justification +for any interaction between the \fBp\fP flag and +the \fB-n\fP option. A relationship between \fB-n\fP and the \fBp\fP +flag might imply that they are only used together, but this +ignores valid scripts that interrupt the cyclical nature of the processing +through the use of the \fBD\fP, \fBd\fP, \fBq\fP, or +branching commands. Such scripts rely on the \fBp\fP suffix to write +the pattern space because they do not make use of the default +output at the "bottom" of the script. +.LP +.IP " *" 3 +Because the \fB-n\fP option makes the \fBp\fP flag unnecessary, any +interaction would only be useful if \fIsed\fP scripts +were written to run both with and without the \fB-n\fP option. This +is believed to be unlikely. It is even more unlikely that +programmers have coded the \fBp\fP flag expecting it to be unnecessary. +Because the interaction was not documented, the likelihood +of a programmer discovering the interaction and depending on it is +further decreased. +.LP +.IP " *" 3 +Finally, scripts that break under the specified behavior produce too +much output instead of too little, which is easier to +diagnose and correct. +.LP +.LP +The form of the substitute command that uses the \fBn\fP suffix was +limited to the first 512 matches in an early proposal. This +limit has been removed because there is no reason an editor processing +lines of {LINE_MAX} length should have this restriction. The +command \fBs/a/A/2047\fP should be able to substitute the 2047th occurrence +of \fBa\fP on a line. +.LP +The \fBb\fP, \fBt\fP, and \fB:\fP commands are documented to ignore +leading white space, but no mention is made of trailing +white space. Historical implementations of \fIsed\fP assigned different +locations to the labels \fB'x'\fP and +\fB"x\ "\fP . This is not useful, and leads to subtle programming +errors, but it is historical practice, and changing it +could theoretically break working scripts. Implementors are encouraged +to provide warning messages about labels that are never used +or jumps to labels that do not exist. +.LP +Historically, the \fIsed\fP \fB!\fP and \fB}\fP editing commands did +not permit multiple commands on a single line using a +semicolon as a command delimiter. Implementations are permitted, but +not required, to support this extension. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIawk\fP , \fIed\fP , \fIgrep\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/set.1p b/man1p/set.1p new file mode 100644 index 000000000..28c548d0a --- /dev/null +++ b/man1p/set.1p @@ -0,0 +1,592 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" set +.SH NAME +set \- set or unset options and positional parameters +.SH SYNOPSIS +.LP +\fBset\fP \fB[\fP\fB-abCefmnuvx\fP\fB][\fP\fB-h\fP\fB][\fP\fB-o\fP +\fIoption\fP\fB][\fP\fIargument\fP\fB...\fP\fB]\fP\fB +.br +.sp +set\fP \fB[\fP\fB+abCefmnuvx\fP\fB][\fP\fB+h\fP\fB][\fP\fB+o\fP +\fIoption\fP\fB][\fP\fIargument\fP\fB...]\fP\fB +.br +.sp +set --\fP \fB[\fP\fIargument\fP\fB...\fP\fB]\fP\fB +.br +.sp +set -o +.br +.sp +set +o +.br +\fP +.SH DESCRIPTION +.LP +If no \fIoption\fPs or \fIargument\fPs are specified, \fIset\fP shall +write the names and values of all shell variables in +the collation sequence of the current locale. Each \fIname\fP shall +start on a separate line, using the format: +.sp +.RS +.nf + +\fB"%s=%s\\n", <\fP\fIname\fP\fB>, <\fP\fIvalue\fP\fB> +\fP +.fi +.RE +.LP +The \fIvalue\fP string shall be written with appropriate quoting; +see the description of shell quoting in \fIQuoting\fP . The output +shall be suitable for reinput to the shell, setting or resetting, +as +far as possible, the variables that are currently set; read-only variables +cannot be reset. +.LP +When options are specified, they shall set or unset attributes of +the shell, as described below. When \fIargument\fPs are +specified, they cause positional parameters to be set or unset, as +described below. Setting or unsetting attributes and positional +parameters are not necessarily related actions, but they can be combined +in a single invocation of \fIset\fP. +.LP +The \fIset\fP special built-in shall support the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines +except that options can be specified with +either a leading hyphen (meaning enable the option) or plus sign (meaning +disable it) unless otherwise specified. +.LP +Implementations shall support the options in the following list in +both their hyphen and plus-sign forms. These options can also +be specified as options to \fIsh\fP. +.TP 7 +\fB-a\fP +When this option is on, the \fIexport\fP attribute shall be set for +each variable to which an assignment is performed; see the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.21, Variable +Assignment. If the assignment precedes a utility name in a command, +the \fIexport\fP attribute shall not persist in the +current execution environment after the utility completes, with the +exception that preceding one of the special built-in utilities +causes the \fIexport\fP attribute to persist after the built-in has +completed. If the assignment does not precede a utility name +in the command, or if the assignment is a result of the operation +of the \fIgetopts\fP or +\fIread\fP utilities, the \fIexport\fP attribute shall persist until +the variable is +unset. +.TP 7 +\fB-b\fP +This option shall be supported if the implementation supports the +User Portability Utilities option. It shall cause the shell +to notify the user asynchronously of background job completions. The +following message is written to standard error: +.sp +.RS +.nf + +\fB"[%d]%c %s%s\\n", <\fP\fIjob-number\fP\fB>, <\fP\fIcurrent\fP\fB>, , +\fP +.fi +.RE +.LP +where the fields shall be as follows: +.TP 7 +<\fIcurrent\fP> +.RS +The character \fB'+'\fP identifies the job that would be used as a +default for the \fIfg\fP or \fIbg\fP utilities; this job can also +be specified +using the \fIjob_id\fP \fB"%+"\fP or \fB"%%"\fP . The character \fB'-'\fP +identifies the job that would become the +default if the current default job were to exit; this job can also +be specified using the \fIjob_id\fP \fB"%-"\fP . For other +jobs, this field is a . At most one job can be identified with +\fB'+'\fP and at most one job can be identified with +\fB'-'\fP . If there is any suspended job, then the current job shall +be a suspended job. If there are at least two suspended +jobs, then the previous job also shall be a suspended job. +.RE +.TP 7 +<\fIjob-number\fP> +.RS +A number that can be used to identify the process group to the \fIwait\fP, +\fIfg\fP, \fIbg\fP, and \fIkill\fP utilities. Using these utilities, +the job can be identified by prefixing the job number +with \fB'%'\fP . +.RE +.TP 7 +<\fIstatus\fP> +.RS +Unspecified. +.RE +.TP 7 +<\fIjob-name\fP> +.RS +Unspecified. +.RE +.sp +.LP +When the shell notifies the user a job has been completed, it may +remove the job's process ID from the list of those known in +the current shell execution environment; see \fIAsynchronous Lists\fP +\&. Asynchronous +notification shall not be enabled by default. +.TP 7 +\fB-C\fP +(Uppercase C.) Prevent existing files from being overwritten by the +shell's \fB'>'\fP redirection operator (see \fIRedirecting Output\fP +); the \fB">|"\fP redirection operator shall override this +\fInoclobber\fP option for an individual file. +.TP 7 +\fB-e\fP +When this option is on, if a simple command fails for any of the reasons +listed in \fIConsequences of Shell Errors\fP or returns an exit status +value >0, and is not part of +the compound list following a \fBwhile\fP, \fBuntil\fP, or \fBif\fP +keyword, and is not a part of an AND or OR list, and is not +a pipeline preceded by the \fB!\fP reserved word, then the shell shall +immediately exit. +.TP 7 +\fB-f\fP +The shell shall disable pathname expansion. +.TP 7 +\fB-h\fP +Locate and remember utilities invoked by functions as those functions +are defined (the utilities are normally located when the +function is executed). +.TP 7 +\fB-m\fP +This option shall be supported if the implementation supports the +User Portability Utilities option. All jobs shall be run in +their own process groups. Immediately before the shell issues a prompt +after completion of the background job, a message reporting +the exit status of the background job shall be written to standard +error. If a foreground job stops, the shell shall write a +message to standard error to that effect, formatted as described by +the \fIjobs\fP utility. +In addition, if a job changes status other than exiting (for example, +if it stops for input or output or is stopped by a SIGSTOP +signal), the shell shall write a similar message immediately prior +to writing the next prompt. This option is enabled by default +for interactive shells. +.TP 7 +\fB-n\fP +The shell shall read commands but does not execute them; this can +be used to check for shell script syntax errors. An +interactive shell may ignore this option. +.TP 7 +\fB-o\fP +Write the current settings of the options to standard output in an +unspecified format. +.TP 7 +\fB+o\fP +Write the current option settings to standard output in a format that +is suitable for reinput to the shell as commands that +achieve the same options settings. +.TP 7 +\fB-o\ \fP \fIoption\fP +.sp +This option is supported if the system supports the User Portability +Utilities option. It shall set various options, many of which +shall be equivalent to the single option letters. The following values +of \fIoption\fP shall be supported: +.TP 7 +\fIallexport\fP +.RS +Equivalent to \fB-a\fP. +.RE +.TP 7 +\fIerrexit\fP +.RS +Equivalent to \fB-e\fP. +.RE +.TP 7 +\fIignoreeof\fP +.RS +Prevent an interactive shell from exiting on end-of-file. This setting +prevents accidental logouts when -D is +entered. A user shall explicitly \fIexit\fP to leave the interactive +shell. +.RE +.TP 7 +\fImonitor\fP +.RS +Equivalent to \fB-m\fP. This option is supported if the system supports +the User Portability Utilities option. +.RE +.TP 7 +\fInoclobber\fP +.RS +Equivalent to \fB-C\fP (uppercase C). +.RE +.TP 7 +\fInoglob\fP +.RS +Equivalent to \fB-f\fP. +.RE +.TP 7 +\fInoexec\fP +.RS +Equivalent to \fB-n\fP. +.RE +.TP 7 +\fInolog\fP +.RS +Prevent the entry of function definitions into the command history; +see \fICommand History List\fP +\&. +.RE +.TP 7 +\fInotify\fP +.RS +Equivalent to \fB-b\fP. +.RE +.TP 7 +\fInounset\fP +.RS +Equivalent to \fB-u\fP. +.RE +.TP 7 +\fIverbose\fP +.RS +Equivalent to \fB-v\fP. +.RE +.TP 7 +\fIvi\fP +.RS +Allow shell command line editing using the built-in \fIvi\fP editor. +Enabling \fIvi\fP mode shall disable any other command line editing +mode provided as an implementation +extension. +.LP +It need not be possible to set \fIvi\fP mode on for certain block-mode +terminals. +.RE +.TP 7 +\fIxtrace\fP +.RS +Equivalent to \fB-x\fP. +.RE +.sp +.TP 7 +\fB-u\fP +The shell shall write a message to standard error when it tries to +expand a variable that is not set and immediately exit. An +interactive shell shall not exit. +.TP 7 +\fB-v\fP +The shell shall write its input to standard error as it is read. +.TP 7 +\fB-x\fP +The shell shall write to standard error a trace for each command after +it expands the command and before it executes it. It is +unspecified whether the command that turns tracing off is traced. +.sp +.LP +The default for all these options shall be off (unset) unless stated +otherwise in the description of the option or unless the +shell was invoked with them on; see \fIsh\fP. +.LP +The remaining arguments shall be assigned in order to the positional +parameters. The special parameter \fB'#'\fP shall be set +to reflect the number of positional parameters. All positional parameters +shall be unset before any new values are assigned. +.LP +The special argument \fB"--"\fP immediately following the \fIset\fP +command name can be used to delimit the arguments if the +first argument begins with \fB'+'\fP or \fB'-'\fP , or to prevent +inadvertent listing of all shell variables when there are +no arguments. The command \fIset\fP \fB--\fP without \fIargument\fP +shall unset all positional parameters and set the special +parameter \fB'#'\fP to zero. +.SH OPTIONS +.LP +See the DESCRIPTION. +.SH OPERANDS +.LP +See the DESCRIPTION. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +None. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +See the DESCRIPTION. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +Zero. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +Write out all variables and their values: +.sp +.RS +.nf + +\fBset +\fP +.fi +.RE +.LP +Set $1, $2, and $3 and set \fB"$#"\fP to 3: +.sp +.RS +.nf + +\fBset c a b +\fP +.fi +.RE +.LP +Turn on the \fB-x\fP and \fB-v\fP options: +.sp +.RS +.nf + +\fBset -xv +\fP +.fi +.RE +.LP +Unset all positional parameters: +.sp +.RS +.nf + +\fBset -- +\fP +.fi +.RE +.LP +Set $1 to the value of \fIx\fP, even if it begins with \fB'-'\fP or +\fB'+'\fP : +.sp +.RS +.nf + +\fBset -- "$x" +\fP +.fi +.RE +.LP +Set the positional parameters to the expansion of \fIx\fP, even if +\fIx\fP expands with a leading \fB'-'\fP or \fB'+'\fP +: +.sp +.RS +.nf + +\fBset -- $x +\fP +.fi +.RE +.SH RATIONALE +.LP +The \fIset\fP -- form is listed specifically in the SYNOPSIS even +though this usage is implied by the Utility Syntax +Guidelines. The explanation of this feature removes any ambiguity +about whether the \fIset\fP -- form might be misinterpreted as +being equivalent to \fIset\fP without any options or arguments. The +functionality of this form has been adopted from the +KornShell. In System V, \fIset\fP -- only unsets parameters if there +is at least one argument; the only way to unset all +parameters is to use \fIshift\fP. Using the KornShell version should +not affect System V +scripts because there should be no reason to issue it without arguments +deliberately; if it were issued as, for example: +.sp +.RS +.nf + +\fBset -- "$@" +\fP +.fi +.RE +.LP +and there were in fact no arguments resulting from \fB"$@"\fP , unsetting +the parameters would have no result. +.LP +The \fIset\fP + form in early proposals was omitted as being an unnecessary +duplication of \fIset\fP alone and not widespread +historical practice. +.LP +The \fInoclobber\fP option was changed to allow \fIset\fP \fB-C\fP +as well as the \fIset\fP \fB-o\fP \fInoclobber\fP +option. The single-letter version was added so that the historical +\fB"$-"\fP paradigm would not be broken; see \fISpecial Parameters\fP +\&. +.LP +The \fB-h\fP flag is related to command name hashing and is only required +on XSI-conformant systems. +.LP +The following \fIset\fP flags were omitted intentionally with the +following rationale: +.TP 7 +\fB-k\fP +The \fB-k\fP flag was originally added by the author of the Bourne +shell to make it easier for users of pre-release versions +of the shell. In early versions of the Bourne shell the construct +\fIset\fP \fIname\fP= \fIvalue\fP had to be used to assign +values to shell variables. The problem with \fB-k\fP is that the behavior +affects parsing, virtually precluding writing any +compilers. To explain the behavior of \fB-k\fP, it is necessary to +describe the parsing algorithm, which is +implementation-defined. For example: +.sp +.RS +.nf + +\fBset -k; echo\fP \fIname\fP\fB=\fP\fIvalue\fP +.fi +.RE +.LP +and: +.sp +.RS +.nf + +\fBset -k +echo\fP \fIname\fP\fB=\fP\fIvalue\fP +.fi +.RE +.LP +behave differently. The interaction with functions is even more complex. +What is more, the \fB-k\fP flag is never needed, since +the command line could have been reordered. +.TP 7 +\fB-t\fP +The \fB-t\fP flag is hard to specify and almost never used. The only +known use could be done with here-documents. Moreover, +the behavior with \fIksh\fP and \fIsh\fP differs. The +reference page says that it exits after reading and executing one +command. What is one command? If the input is \fIdate\fP; +\fIdate\fP, \fIsh\fP executes both \fIdate\fP commands +while \fIksh\fP does only the first. +.sp +.LP +Consideration was given to rewriting \fIset\fP to simplify its confusing +syntax. A specific suggestion was that the \fIunset\fP utility should +be used to unset options instead of using the non- \fIgetopt\fP() +-able + \fIoption\fP syntax. However, the conclusion was reached that +the +historical practice of using + \fIoption\fP was satisfactory and that +there was no compelling reason to modify such widespread +historical practice. +.LP +The \fB-o\fP option was adopted from the KornShell to address user +needs. In addition to its generally friendly interface, +\fB-o\fP is needed to provide the \fIvi\fP command line editing mode, +for which historical +practice yields no single-letter option name. (Although it might have +been possible to invent such a letter, it was recognized that +other editing modes would be developed and \fB-o\fP provides ample +name space for describing such extensions.) +.LP +Historical implementations are inconsistent in the format used for +\fB-o\fP option status reporting. The \fB+o\fP format +without an option-argument was added to allow portable access to the +options that can be saved and then later restored using, for +instance, a dot script. +.LP +Historically, \fIsh\fP did trace the command \fIset\fP \fB+x\fP, but +\fIksh\fP did not. +.LP +The \fIignoreeof\fP setting prevents accidental logouts when the end-of-file +character (typically -D) is +entered. A user shall explicitly \fIexit\fP to leave the interactive +shell. +.LP +The \fIset\fP \fB-m\fP option was added to apply only to the UPE because +it applies primarily to interactive use, not shell +script applications. +.LP +The ability to do asynchronous notification became available in the +1988 version of the KornShell. To have it occur, the user +had to issue the command: +.sp +.RS +.nf + +\fBtrap "jobs -n" CLD +\fP +.fi +.RE +.LP +The C shell provides two different levels of an asynchronous notification +capability. The environment variable \fInotify\fP is +analogous to what is done in \fIset\fP \fB-b\fP or \fIset\fP \fB-o\fP +\fInotify\fP. When set, it notifies the user immediately +of background job completions. When unset, this capability is turned +off. +.LP +The other notification ability comes through the built-in utility +\fInotify\fP. The +syntax is: +.sp +.RS +.nf + +\fBnotify\fP \fB[\fP\fB%job ...\fP \fB]\fP +.fi +.RE +.LP +By issuing \fInotify\fP with no operands, it causes the C shell to +notify the user +asynchronously when the state of the current job changes. If given +operands, \fInotify\fP +asynchronously informs the user of changes in the states of the specified +jobs. +.LP +To add asynchronous notification to the POSIX shell, neither the KornShell +extensions to \fItrap\fP, nor the C shell \fInotify\fP environment +variable +seemed appropriate ( \fInotify\fP is not a proper POSIX environment +variable name). +.LP +The \fIset\fP \fB-b\fP option was selected as a compromise. +.LP +The \fInotify\fP built-in was considered to have more functionality +than was required +for simple asynchronous notification. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISpecial Built-In Utilities\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/sh.1p b/man1p/sh.1p new file mode 100644 index 000000000..9cb7c7383 --- /dev/null +++ b/man1p/sh.1p @@ -0,0 +1,1358 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sh +.SH NAME +sh \- shell, the standard command language interpreter +.SH SYNOPSIS +.LP +\fBsh\fP \fB[\fP\fB-abCefhimnuvx\fP\fB][\fP\fB-o\fP \fIoption\fP\fB][\fP\fB+abCefhimnuvx\fP\fB][\fP\fB+o\fP +\fIoption\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fIcommand_file\fP \fB[\fP\fIargument\fP\fB...\fP\fB]]\fP\fB +.br +.sp +sh -c\fP\fB[\fP\fB-abCefhimnuvx\fP\fB][\fP\fB-o\fP \fIoption\fP\fB][\fP\fB+abCefhimnuvx\fP\fB][\fP\fB+o\fP +\fIoption\fP\fB]\fP\fIcommand_string +.br +\fP \fB\ \ \ \ \ \ \fP \fI\fP\fB[\fP\fIcommand_name\fP +\fB[\fP\fIargument\fP\fB...\fP\fB]]\fP\fB +.br +.sp +sh -s\fP\fB[\fP\fB-abCefhimnuvx\fP\fB][\fP\fB-o\fP \fIoption\fP\fB][\fP\fB+abCefhimnuvx\fP\fB][\fP\fB+o\fP +\fIoption\fP\fB][\fP\fIargument\fP\fB]\fP\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsh\fP utility is a command language interpreter that shall +execute commands read from a command line string, the +standard input, or a specified file. The application shall ensure +that the commands to be executed are expressed in the language +described in \fIShell Command Language\fP . +.LP +Pathname expansion shall not fail due to the size of a file. +.LP +Shell input and output redirections have an implementation-defined +offset maximum that is established in the open file +description. +.SH OPTIONS +.LP +The \fIsh\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +with an extension for support of a leading +plus sign ( \fB'+'\fP ) as noted below. +.LP +The \fB-a\fP, \fB-b\fP, \fB-C\fP, \fB-e\fP, \fB-f\fP, \fB-m\fP, \fB-n\fP, +\fB-o\fP \fIoption\fP, \fB-u\fP, \fB-v\fP, +and \fB-x\fP options are described as part of the \fIset\fP utility +in \fISpecial Built-In Utilities\fP . The option letters derived from +the \fIset\fP special built-in shall also be accepted with a leading +plus sign ( \fB'+'\fP ) +instead of a leading hyphen (meaning the reverse case of the option +as described in this volume of +IEEE\ Std\ 1003.1-2001). +.LP +The following additional options shall be supported: +.TP 7 +\fB-c\fP +Read commands from the \fIcommand_string\fP operand. Set the value +of special parameter 0 (see \fISpecial Parameters\fP ) from the value +of the \fIcommand_name\fP operand and the positional +parameters ($1, $2, and so on) in sequence from the remaining \fIargument\fP +operands. No commands shall be read from the standard +input. +.TP 7 +\fB-i\fP +Specify that the shell is \fIinteractive\fP; see below. An implementation +may treat specifying the \fB-i\fP option as an +error if the real user ID of the calling process does not equal the +effective user ID or if the real group ID does not equal the +effective group ID. +.TP 7 +\fB-s\fP +Read commands from the standard input. +.sp +.LP +If there are no operands and the \fB-c\fP option is not specified, +the \fB-s\fP option shall be assumed. +.LP +If the \fB-i\fP option is present, or if there are no operands and +the shell's standard input and standard error are attached +to a terminal, the shell is considered to be \fIinteractive\fP. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fB-\fP +A single hyphen shall be treated as the first operand and then ignored. +If both \fB'-'\fP and \fB"--"\fP are given as +arguments, or if other operands precede the single hyphen, the results +are undefined. +.TP 7 +\fIargument\fP +The positional parameters ($1, $2, and so on) shall be set to \fIarguments\fP, +if any. +.TP 7 +\fIcommand_file\fP +The pathname of a file containing commands. If the pathname contains +one or more slash characters, the implementation attempts +to read that file; the file need not be executable. If the pathname +does not contain a slash character: +.RS +.IP " *" 3 +The implementation shall attempt to read that file from the current +working directory; the file need not be executable. +.LP +.IP " *" 3 +If the file is not in the current working directory, the implementation +may perform a search for an executable file using the +value of \fIPATH ,\fP as described in \fICommand Search and Execution\fP +\&. +.LP +.RE +.LP +Special parameter 0 (see \fISpecial Parameters\fP ) shall be set to +the value of +\fIcommand_file\fP. If \fIsh\fP is called using a synopsis form that +omits \fIcommand_file\fP, special parameter 0 shall be set +to the value of the first argument passed to \fIsh\fP from its parent +(for example, \fIargv\fP[0] for a C program), which is +normally a pathname used to execute the \fIsh\fP utility. +.TP 7 +\fIcommand_name\fP +.sp +A string assigned to special parameter 0 when executing the commands +in \fIcommand_string\fP. If \fIcommand_name\fP is not +specified, special parameter 0 shall be set to the value of the first +argument passed to \fIsh\fP from its parent (for example, +\fIargv\fP[0] for a C program), which is normally a pathname used +to execute the \fIsh\fP utility. +.TP 7 +\fIcommand_string\fP +.sp +A string that shall be interpreted by the shell as one or more commands, +as if the string were the argument to the \fIsystem\fP() function +defined in the System Interfaces volume of IEEE\ Std\ 1003.1-2001. +If the \fIcommand_string\fP operand is an empty string, \fIsh\fP shall +exit with a zero exit status. +.sp +.SH STDIN +.LP +The standard input shall be used only if one of the following is true: +.IP " *" 3 +The \fB-s\fP option is specified. +.LP +.IP " *" 3 +The \fB-c\fP option is not specified and no operands are specified. +.LP +.IP " *" 3 +The script executes one or more commands that require input from standard +input (such as a \fIread\fP command that does not redirect its input). +.LP +.LP +See the INPUT FILES section. +.LP +When the shell is using standard input and it invokes a command that +also uses standard input, the shell shall ensure that the +standard input file pointer points directly after the command it has +read when the command begins execution. It shall not read +ahead in such a manner that any characters intended to be read by +the invoked command are consumed by the shell (whether +interpreted by the shell or not) or that characters that are not read +by the invoked command are not seen by the shell. When the +command expecting to read standard input is started asynchronously +by an interactive shell, it is unspecified whether characters +are read by the command or interpreted by the shell. +.LP +If the standard input to \fIsh\fP is a FIFO or terminal device and +is set to non-blocking reads, then \fIsh\fP shall enable +blocking reads on standard input. This shall remain in effect when +the command completes. +.SH INPUT FILES +.LP +The input file shall be a text file, except that line lengths shall +be unlimited. If the input file is empty or consists solely +of blank lines or comments, or both, \fIsh\fP shall exit with a zero +exit status. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIsh\fP: +.TP 7 +\fIENV\fP +This variable, when and only when an interactive shell is invoked, +shall be subjected to parameter expansion (see \fIParameter Expansion\fP +) by the shell, and the resulting value shall be used as a pathname +of a file containing shell commands to execute in the current environment. +The file need not be executable. If the expanded value +of \fIENV\fP is not an absolute pathname, the results are unspecified. +\fIENV\fP shall be ignored if the real and effective user +IDs or real and effective group IDs of the process are different. +.TP 7 +\fIFCEDIT\fP +This variable, when expanded by the shell, shall determine the default +value for the \fB-e\fP \fIeditor\fP option's +\fIeditor\fP option-argument. If \fIFCEDIT\fP is null or unset, \fIed\fP +shall be used as the +editor. This volume of IEEE\ Std\ 1003.1-2001 specifies the effects +of this variable only for systems supporting the User +Portability Utilities option. +.TP 7 +\fIHISTFILE\fP +Determine a pathname naming a command history file. If the \fIHISTFILE\fP +variable is not set, the shell may attempt to access +or create a file \fB.sh_history\fP in the directory referred to by +the \fIHOME\fP environment variable. If the shell cannot +obtain both read and write access to, or create, the history file, +it shall use an unspecified mechanism that allows the history to +operate properly. (References to history "file" in this section shall +be understood to mean this unspecified mechanism in such +cases.) An implementation may choose to access this variable only +when initializing the history file; this initialization shall +occur when \fIfc\fP or \fIsh\fP first attempt to retrieve entries +from, or add entries to, the +file, as the result of commands issued by the user, the file named +by the \fIENV\fP variable, or implementation-defined system +start-up files. Implementations may choose to disable the history +list mechanism for users with appropriate privileges who do not +set \fIHISTFILE ;\fP the specific circumstances under which this occurs +are implementation-defined. If more than one instance of +the shell is using the same history file, it is unspecified how updates +to the history file from those shells interact. As entries +are deleted from the history file, they shall be deleted oldest first. +It is unspecified when history file entries are physically +removed from the history file. This volume of IEEE\ Std\ 1003.1-2001 +specifies the effects of this variable only for +systems supporting the User Portability Utilities option. +.TP 7 +\fIHISTSIZE\fP +Determine a decimal number representing the limit to the number of +previous commands that are accessible. If this variable is +unset, an unspecified default greater than or equal to 128 shall be +used. The maximum number of commands in the history list is +unspecified, but shall be at least 128. An implementation may choose +to access this variable only when initializing the history +file, as described under \fIHISTFILE .\fP Therefore, it is unspecified +whether changes made to \fIHISTSIZE\fP after the history +file has been initialized are effective. +.TP 7 +\fIHOME\fP +Determine the pathname of the user's home directory. The contents +of \fIHOME\fP are used in tilde expansion as described in \fITilde +Expansion\fP . This volume of IEEE\ Std\ 1003.1-2001 specifies the +effects of this variable only for systems supporting the User Portability +Utilities option. +.TP 7 +\fIIFS\fP +(Input Field Separators.) A string treated as a list of characters +that shall be used for field splitting and to split lines +into words with the \fIread\fP command. See \fIField +Splitting\fP . If \fIIFS\fP is not set, the shell shall behave as +if the value of \fIIFS\fP were , , +and . Implementations may ignore the value of \fIIFS\fP in +the environment at the time \fIsh\fP is invoked, +treating \fIIFS\fP as if it were not set. +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the behavior of range expressions, equivalence classes, +and multi-character collating elements within pattern +matching. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), which +characters are defined as letters (character class +\fBalpha\fP), and the behavior of character classes within pattern +matching. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fIMAIL\fP +Determine a pathname of the user's mailbox file for purposes of incoming +mail notification. If this variable is set, the shell +shall inform the user if the file named by the variable is created +or if its modification time has changed. Informing the user +shall be accomplished by writing a string of unspecified format to +standard error prior to the writing of the next primary prompt +string. Such check shall be performed only after the completion of +the interval defined by the \fIMAILCHECK\fP variable after the +last such check. The user shall be informed only if \fIMAIL\fP is +set and \fIMAILPATH\fP is not set. This volume of +IEEE\ Std\ 1003.1-2001 specifies the effects of this variable only +for systems supporting the User Portability Utilities +option. +.TP 7 +\fIMAILCHECK\fP +.sp +Establish a decimal integer value that specifies how often (in seconds) +the shell shall check for the arrival of mail in the files +specified by the \fIMAILPATH\fP or \fIMAIL\fP variables. The default +value shall be 600 seconds. If set to zero, the shell shall +check before issuing each primary prompt. This volume of IEEE\ Std\ 1003.1-2001 +specifies the effects of this variable only +for systems supporting the User Portability Utilities option. +.TP 7 +\fIMAILPATH\fP +Provide a list of pathnames and optional messages separated by colons. +If this variable is set, the shell shall inform the user +if any of the files named by the variable are created or if any of +their modification times change. (See the preceding entry for +\fIMAIL\fP for descriptions of mail arrival and user informing.) Each +pathname can be followed by \fB'%'\fP and a string that +shall be subjected to parameter expansion and written to standard +error when the modification time changes. If a \fB'%'\fP +character in the pathname is preceded by a backslash, it shall be +treated as a literal \fB'%'\fP in the pathname. The default +message is unspecified. +.LP +The \fIMAILPATH\fP environment variable takes precedence over the +\fIMAIL\fP variable. This volume of +IEEE\ Std\ 1003.1-2001 specifies the effects of this variable only +for systems supporting the User Portability Utilities +option. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPATH\fP +Establish a string formatted as described in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables, +used to effect command interpretation; see \fICommand Search and Execution\fP +\&. +.TP 7 +\fIPWD\fP +This variable shall represent an absolute pathname of the current +working directory. Assignments to this variable may be +ignored unless the value is an absolute pathname of the current working +directory and there are no filename components of dot or +dot-dot. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +See the STDERR section. +.SH STDERR +.LP +Except as otherwise stated (by the descriptions of any invoked utilities +or in interactive mode), standard error shall be used +only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +See \fIShell Command Language\fP . The following additional capabilities +are supported on +systems supporting the User Portability Utilities option. +.SS Command History List +.LP +When the \fIsh\fP utility is being used interactively, it shall maintain +a list of commands previously entered from the +terminal in the file named by the \fIHISTFILE\fP environment variable. +The type, size, and internal format of this file are +unspecified. Multiple \fIsh\fP processes can share access to the file +for a user, if file access permissions allow this; see the +description of the \fIHISTFILE\fP environment variable. +.SS Command Line Editing +.LP +When \fIsh\fP is being used interactively from a terminal, the current +command and the command history (see \fIfc\fP ) can be edited using +\fIvi\fP-mode command line editing. This mode +uses commands, described below, similar to a subset of those described +in the \fIvi\fP utility. +Implementations may offer other command line editing modes corresponding +to other editing utilities. +.LP +The command \fIset\fP \fB-o\fP \fIvi\fP +shall enable \fIvi\fP-mode editing and place \fIsh\fP into \fIvi\fP +insert mode (see Command Line Editing (vi-mode) ). This +command also shall disable any other editing mode that the implementation +may provide. The command \fIset\fP \fB+o\fP \fIvi\fP disables \fIvi\fP-mode +editing. +.LP +Certain block-mode terminals may be unable to support shell command +line editing. If a terminal is unable to provide either edit +mode, it need not be possible to \fIset\fP \fB-o\fP \fIvi\fP when +using the shell on this terminal. +.LP +In the following sections, the characters \fIerase\fP, \fIinterrupt\fP, +\fIkill\fP, and \fIend-of-file\fP are those set by +the \fIstty\fP utility. +.SS Command Line Editing (vi-mode) +.LP +In \fIvi\fP editing mode, there shall be a distinguished line, the +edit line. All the +editing operations which modify a line affect the edit line. The edit +line is always the newest line in the command history +buffer. +.LP +With \fIvi\fP-mode enabled, \fIsh\fP can be switched between insert +mode and command +mode. +.LP +When in insert mode, an entered character shall be inserted into the +command line, except as noted in vi Line Editing Insert Mode . Upon +entering \fIsh\fP and after termination of the previous command, +\fIsh\fP shall be in insert mode. +.LP +Typing an escape character shall switch \fIsh\fP into command mode +(see vi Line Editing Command +Mode ). In command mode, an entered character shall either invoke +a defined operation, be used as part of a multi-character +operation, or be treated as an error. A character that is not recognized +as part of an editing command shall terminate any specific +editing command and shall alert the terminal. Typing the \fIinterrupt\fP +character in command mode shall cause \fIsh\fP to +terminate command line editing on the current command line, reissue +the prompt on the next line of the terminal, and reset the +command history (see \fIfc\fP ) so that the most recently executed +command is the previous command (that is, +the command that was being edited when it was interrupted is not reentered +into the history). +.LP +In the following sections, the phrase "move the cursor to the beginning +of the word" shall mean "move the cursor to the first +character of the current word" and the phrase "move the cursor to +the end of the word" shall mean "move the cursor to the last +character of the current word". The phrase "beginning of the command +line" indicates the point between the end of the prompt +string issued by the shell (or the beginning of the terminal line, +if there is no prompt string) and the first character of the +command text. +.SS vi Line Editing Insert Mode +.LP +While in insert mode, any character typed shall be inserted in the +current command line, unless it is from the following +set. +.TP 7 + +Execute the current command line. If the current command line is not +empty, this line shall be entered into the command history +(see \fIfc\fP ). +.TP 7 +\fIerase\fP +Delete the character previous to the current cursor position and move +the current cursor position back one character. In insert +mode, characters shall be erased from both the screen and the buffer +when backspacing. +.TP 7 +\fIinterrupt\fP +Terminate command line editing with the same effects as described +for interrupting command mode; see Command Line Editing (vi-mode) +\&. +.TP 7 +\fIkill\fP +Clear all the characters from the input line. +.TP 7 +-V +Insert the next character input, even if the character is otherwise +a special insert mode character. +.TP 7 +-W +Delete the characters from the one preceding the cursor to the preceding +word boundary. The word boundary in this case is the +closer to the cursor of either the beginning of the line or a character +that is in neither the \fBblank\fP nor \fBpunct\fP +character classification of the current locale. +.TP 7 +\fIend-of-file\fP +Interpreted as the end of input in \fIsh\fP. This interpretation shall +occur only at the beginning of an input line. If +\fIend-of-file\fP is entered other than at the beginning of the line, +the results are unspecified. +.TP 7 + +Place \fIsh\fP into command mode. +.sp +.SS vi Line Editing Command Mode +.LP +In command mode for the command line editing feature, decimal digits +not beginning with 0 that precede a command letter shall be +remembered. Some commands use these decimal digits as a count number +that affects the operation. +.LP +The term \fImotion command\fP represents one of the commands: +.sp +.RS +.nf + +\fB 0 b F l W ^ $ ; E f T w | , B e h t +\fP +.fi +.RE +.LP +If the current line is not the edit line, any command that modifies +the current line shall cause the content of the current line +to replace the content of the edit line, and the current line shall +become the edit line. This replacement cannot be undone (see +the \fBu\fP and \fBU\fP commands below). The modification requested +shall then be performed to the edit line. When the current +line is the edit line, the modification shall be done directly to +the edit line. +.LP +Any command that is preceded by \fIcount\fP shall take a count (the +numeric value of any preceding decimal digits). Unless +otherwise noted, this count shall cause the specified operation to +repeat by the number of times specified by the count. Also +unless otherwise noted, a \fIcount\fP that is out of range is considered +an error condition and shall alert the terminal, but +neither the cursor position, nor the command line, shall change. +.LP +The terms \fIword\fP and \fIbigword\fP are used as defined in the +\fIvi\fP description. +The term \fIsave buffer\fP corresponds to the term \fIunnamed buffer\fP +in \fIvi\fP. +.LP +The following commands shall be recognized in command mode: +.TP 7 + +Execute the current command line. If the current command line is not +empty, this line shall be entered into the command history +(see \fIfc\fP ). +.TP 7 +-L +Redraw the current command line. Position the cursor at the same location +on the redrawn line. +.TP 7 +\fB#\fP +Insert the character \fB'#'\fP at the beginning of the current command +line and treat the resulting edit line as a comment. +This line shall be entered into the command history; see \fIfc\fP +\&. +.TP 7 +\fB=\fP +Display the possible shell word expansions (see \fIWord Expansions\fP +) of the bigword +at the current command line position. +.TP 7 +\fBNote:\fP +.RS +This does not modify the content of the current line, and therefore +does not cause the current line to become the edit +line. +.RE +.sp +.LP +These expansions shall be displayed on subsequent terminal lines. +If the bigword contains none of the characters \fB'?'\fP , +\fB'*'\fP , or \fB'['\fP , an asterisk ( \fB'*'\fP ) shall be implicitly +assumed at the end. If any directories are +matched, these expansions shall have a \fB'/'\fP character appended. +After the expansion, the line shall be redrawn, the cursor +repositioned at the current cursor position, and \fIsh\fP shall be +placed in command mode. +.TP 7 +\fB\\\fP +Perform pathname expansion (see \fIPathname Expansion\fP ) on the +current bigword, +up to the largest set of characters that can be matched uniquely. +If the bigword contains none of the characters \fB'?'\fP , +\fB'*'\fP , or \fB'['\fP , an asterisk ( \fB'*'\fP ) shall be implicitly +assumed at the end. This maximal expansion then +shall replace the original bigword in the command line, and the cursor +shall be placed after this expansion. If the resulting +bigword completely and uniquely matches a directory, a \fB'/'\fP character +shall be inserted directly after the bigword. If some +other file is completely matched, a single shall be inserted +after the bigword. After this operation, \fIsh\fP shall +be placed in insert mode. +.TP 7 +\fB*\fP +Perform pathname expansion on the current bigword and insert all expansions +into the command to replace the current bigword, +with each expansion separated by a single . If at the end of +the line, the current cursor position shall be moved to +the first column position following the expansions and \fIsh\fP shall +be placed in insert mode. Otherwise, the current cursor +position shall be the last column position of the first character +after the expansions and \fIsh\fP shall be placed in insert +mode. If the current bigword contains none of the characters \fB'?'\fP +, \fB'*'\fP , or \fB'['\fP , before the operation, +an asterisk shall be implicitly assumed at the end. +.TP 7 +\fB@\fP\fIletter\fP +Insert the value of the alias named \fI_letter\fP. The symbol \fIletter\fP +represents a single alphabetic character from the +portable character set; implementations may support additional characters +as an extension. If the alias \fI_letter\fP contains +other editing commands, these commands shall be performed as part +of the insertion. If no alias \fI_letter\fP is enabled, this +command shall have no effect. +.TP 7 +\fB[\fP\fIcount\fP\fB]~\fP +Convert, if the current character is a lowercase letter, to the equivalent +uppercase letter and \fIvice versa\fP, as +prescribed by the current locale. The current cursor position then +shall be advanced by one character. If the cursor was positioned +on the last character of the line, the case conversion shall occur, +but the cursor shall not advance. If the \fB'~'\fP +command is preceded by a \fIcount\fP, that number of characters shall +be converted, and the cursor shall be advanced to the +character position after the last character converted. If the \fIcount\fP +is larger than the number of characters after the +cursor, this shall not be considered an error; the cursor shall advance +to the last character on the line. +.TP 7 +\fB[\fP\fIcount\fP\fB].\fP +Repeat the most recent non-motion command, even if it was executed +on an earlier command line. If the previous command was +preceded by a \fIcount\fP, and no count is given on the \fB'.'\fP +command, the count from the previous command shall be +included as part of the repeated command. If the \fB'.'\fP command +is preceded by a \fIcount\fP, this shall override any +\fIcount\fP argument to the previous command. The \fIcount\fP specified +in the \fB'.'\fP command shall become the count for +subsequent \fB'.'\fP commands issued without a count. +.TP 7 +\fB[\fP\fInumber\fP\fB]v\fP +Invoke the \fIvi\fP editor to edit the current command line in a temporary +file. When the +editor exits, the commands in the temporary file shall be executed +and placed in the command history. If a \fInumber\fP is +included, it specifies the command number in the command history to +be edited, rather than the current command line. +.TP 7 +\fB[\fP\fIcount\fP\fB]l\fP\ \ \ (ell) +.TP 7 +\fB[\fP\fIcount\fP\fB]\fP +.sp +Move the current cursor position to the next character position. If +the cursor was positioned on the last character of the line, +the terminal shall be alerted and the cursor shall not be advanced. +If the \fIcount\fP is larger than the number of characters +after the cursor, this shall not be considered an error; the cursor +shall advance to the last character on the line. +.TP 7 +\fB[\fP\fIcount\fP\fB]h\fP +Move the current cursor position to the \fIcount\fPth (default 1) +previous character position. If the cursor was positioned on +the first character of the line, the terminal shall be alerted and +the cursor shall not be moved. If the count is larger than the +number of characters before the cursor, this shall not be considered +an error; the cursor shall move to the first character on the +line. +.TP 7 +\fB[\fP\fIcount\fP\fB]w\fP +Move to the start of the next word. If the cursor was positioned on +the last character of the line, the terminal shall be +alerted and the cursor shall not be advanced. If the \fIcount\fP is +larger than the number of words after the cursor, this shall +not be considered an error; the cursor shall advance to the last character +on the line. +.TP 7 +\fB[\fP\fIcount\fP\fB]W\fP +Move to the start of the next bigword. If the cursor was positioned +on the last character of the line, the terminal shall be +alerted and the cursor shall not be advanced. If the \fIcount\fP is +larger than the number of bigwords after the cursor, this +shall not be considered an error; the cursor shall advance to the +last character on the line. +.TP 7 +\fB[\fP\fIcount\fP\fB]e\fP +Move to the end of the current word. If at the end of a word, move +to the end of the next word. If the cursor was positioned on +the last character of the line, the terminal shall be alerted and +the cursor shall not be advanced. If the \fIcount\fP is larger +than the number of words after the cursor, this shall not be considered +an error; the cursor shall advance to the last character on +the line. +.TP 7 +\fB[\fP\fIcount\fP\fB]E\fP +Move to the end of the current bigword. If at the end of a bigword, +move to the end of the next bigword. If the cursor was +positioned on the last character of the line, the terminal shall be +alerted and the cursor shall not be advanced. If the +\fIcount\fP is larger than the number of bigwords after the cursor, +this shall not be considered an error; the cursor shall +advance to the last character on the line. +.TP 7 +\fB[\fP\fIcount\fP\fB]b\fP +Move to the beginning of the current word. If at the beginning of +a word, move to the beginning of the previous word. If the +cursor was positioned on the first character of the line, the terminal +shall be alerted and the cursor shall not be moved. If the +\fIcount\fP is larger than the number of words preceding the cursor, +this shall not be considered an error; the cursor shall +return to the first character on the line. +.TP 7 +\fB[\fP\fIcount\fP\fB]B\fP +Move to the beginning of the current bigword. If at the beginning +of a bigword, move to the beginning of the previous bigword. +If the cursor was positioned on the first character of the line, the +terminal shall be alerted and the cursor shall not be moved. +If the \fIcount\fP is larger than the number of bigwords preceding +the cursor, this shall not be considered an error; the cursor +shall return to the first character on the line. +.TP 7 +\fB^\fP +Move the current cursor position to the first character on the input +line that is not a . +.TP 7 +\fB$\fP +Move to the last character position on the current command line. +.TP 7 +\fB0\fP +(Zero.) Move to the first character position on the current command +line. +.TP 7 +\fB[\fP\fIcount\fP\fB]|\fP +Move to the \fIcount\fPth character position on the current command +line. If no number is specified, move to the first +position. The first character position shall be numbered 1. If the +count is larger than the number of characters on the line, this +shall not be considered an error; the cursor shall be placed on the +last character on the line. +.TP 7 +\fB[\fP\fIcount\fP\fB]f\fP\fIc\fP +Move to the first occurrence of the character \fB'c'\fP that occurs +after the current cursor position. If the cursor was +positioned on the last character of the line, the terminal shall be +alerted and the cursor shall not be advanced. If the character +\fB'c'\fP does not occur in the line after the current cursor position, +the terminal shall be alerted and the cursor shall not +be moved. +.TP 7 +\fB[\fP\fIcount\fP\fB]F\fP\fIc\fP +Move to the first occurrence of the character \fB'c'\fP that occurs +before the current cursor position. If the cursor was +positioned on the first character of the line, the terminal shall +be alerted and the cursor shall not be moved. If the character +\fB'c'\fP does not occur in the line before the current cursor position, +the terminal shall be alerted and the cursor shall not +be moved. +.TP 7 +\fB[\fP\fIcount\fP\fB]t\fP\fIc\fP +Move to the character before the first occurrence of the character +\fB'c'\fP that occurs after the current cursor position. +If the cursor was positioned on the last character of the line, the +terminal shall be alerted and the cursor shall not be advanced. +If the character \fB'c'\fP does not occur in the line after the current +cursor position, the terminal shall be alerted and the +cursor shall not be moved. +.TP 7 +\fB[\fP\fIcount\fP\fB]T\fP\fIc\fP +Move to the character after the first occurrence of the character +\fB'c'\fP that occurs before the current cursor position. +If the cursor was positioned on the first character of the line, the +terminal shall be alerted and the cursor shall not be moved. +If the character \fB'c'\fP does not occur in the line before the current +cursor position, the terminal shall be alerted and the +cursor shall not be moved. +.TP 7 +\fB[\fP\fIcount\fP\fB];\fP +Repeat the most recent \fBf\fP, \fBF\fP, \fBt\fP, or \fBT\fP command. +Any number argument on that previous command shall be +ignored. Errors are those described for the repeated command. +.TP 7 +\fB[\fP\fIcount\fP\fB],\fP +Repeat the most recent \fBf\fP, \fBF\fP, \fBt\fP, or \fBT\fP command. +Any number argument on that previous command shall be +ignored. However, reverse the direction of that command. +.TP 7 +\fBa\fP +Enter insert mode after the current cursor position. Characters that +are entered shall be inserted before the next +character. +.TP 7 +\fBA\fP +Enter insert mode after the end of the current command line. +.TP 7 +\fBi\fP +Enter insert mode at the current cursor position. Characters that +are entered shall be inserted before the current +character. +.TP 7 +\fBI\fP +Enter insert mode at the beginning of the current command line. +.TP 7 +\fBR\fP +Enter insert mode, replacing characters from the command line beginning +at the current cursor position. +.TP 7 +\fB[\fP\fIcount\fP\fB]c\fP\fImotion\fP +.sp +Delete the characters between the current cursor position and the +cursor position that would result from the specified motion +command. Then enter insert mode before the first character following +any deleted characters. If \fIcount\fP is specified, it shall +be applied to the motion command. A \fIcount\fP shall be ignored for +the following motion commands: +.sp +.RS +.nf + +\fB0 ^ $ c +\fP +.fi +.RE +.LP +If the motion command is the character \fB'c'\fP , the current command +line shall be cleared and insert mode shall be +entered. If the motion command would move the current cursor position +toward the beginning of the command line, the character under +the current cursor position shall not be deleted. If the motion command +would move the current cursor position toward the end of +the command line, the character under the current cursor position +shall be deleted. If the \fIcount\fP is larger than the number +of characters between the current cursor position and the end of the +command line toward which the motion command would move the +cursor, this shall not be considered an error; all of the remaining +characters in the aforementioned range shall be deleted and +insert mode shall be entered. If the motion command is invalid, the +terminal shall be alerted, the cursor shall not be moved, and +no text shall be deleted. +.TP 7 +\fBC\fP +Delete from the current character to the end of the line and enter +insert mode at the new end-of-line. +.TP 7 +\fBS\fP +Clear the entire edit line and enter insert mode. +.TP 7 +\fB[\fP\fIcount\fP\fB]r\fP\fIc\fP +Replace the current character with the character \fB'c'\fP . With +a number \fIcount\fP, replace the current and the +following \fIcount\fP-1 characters. After this command, the current +cursor position shall be on the last character that was +changed. If the \fIcount\fP is larger than the number of characters +after the cursor, this shall not be considered an error; all +of the remaining characters shall be changed. +.TP 7 +\fB[\fP\fIcount\fP\fB]_\fP +Append a after the current character position and then append +the last bigword in the previous input line after +the . Then enter insert mode after the last character just +appended. With a number \fIcount\fP, append the +\fIcount\fPth bigword in the previous line. +.TP 7 +\fB[\fP\fIcount\fP\fB]x\fP +Delete the character at the current cursor position and place the +deleted characters in the save buffer. If the cursor was +positioned on the last character of the line, the character shall +be deleted and the cursor position shall be moved to the previous +character (the new last character). If the \fIcount\fP is larger than +the number of characters after the cursor, this shall not be +considered an error; all the characters from the cursor to the end +of the line shall be deleted. +.TP 7 +\fB[\fP\fIcount\fP\fB]X\fP +Delete the character before the current cursor position and place +the deleted characters in the save buffer. The character +under the current cursor position shall not change. If the cursor +was positioned on the first character of the line, the terminal +shall be alerted, and the \fBX\fP command shall have no effect. If +the line contained a single character, the \fBX\fP command +shall have no effect. If the line contained no characters, the terminal +shall be alerted and the cursor shall not be moved. If the +\fIcount\fP is larger than the number of characters before the cursor, +this shall not be considered an error; all the characters +from before the cursor to the beginning of the line shall be deleted. +.TP 7 +\fB[\fP\fIcount\fP\fB]d\fP\fImotion\fP +.sp +Delete the characters between the current cursor position and the +character position that would result from the motion command. A +number \fIcount\fP repeats the motion command \fIcount\fP times. If +the motion command would move toward the beginning of the +command line, the character under the current cursor position shall +not be deleted. If the motion command is \fBd\fP, the entire +current command line shall be cleared. If the \fIcount\fP is larger +than the number of characters between the current cursor +position and the end of the command line toward which the motion command +would move the cursor, this shall not be considered an +error; all of the remaining characters in the aforementioned range +shall be deleted. The deleted characters shall be placed in the +save buffer. +.TP 7 +\fBD\fP +Delete all characters from the current cursor position to the end +of the line. The deleted characters shall be placed in the +save buffer. +.TP 7 +\fB[\fP\fIcount\fP\fB]y\fP\fImotion\fP +.sp +Yank (that is, copy) the characters from the current cursor position +to the position resulting from the motion command into the +save buffer. A number \fIcount\fP shall be applied to the motion command. +If the motion command would move toward the beginning of +the command line, the character under the current cursor position +shall not be included in the set of yanked characters. If the +motion command is \fBy\fP, the entire current command line shall be +yanked into the save buffer. The current cursor position shall +be unchanged. If the \fIcount\fP is larger than the number of characters +between the current cursor position and the end of the +command line toward which the motion command would move the cursor, +this shall not be considered an error; all of the remaining +characters in the aforementioned range shall be yanked. +.TP 7 +\fBY\fP +Yank the characters from the current cursor position to the end of +the line into the save buffer. The current character +position shall be unchanged. +.TP 7 +\fB[\fP\fIcount\fP\fB]p\fP +Put a copy of the current contents of the save buffer after the current +cursor position. The current cursor position shall be +advanced to the last character put from the save buffer. A \fIcount\fP +shall indicate how many copies of the save buffer shall be +put. +.TP 7 +\fB[\fP\fIcount\fP\fB]P\fP +Put a copy of the current contents of the save buffer before the current +cursor position. The current cursor position shall be +moved to the last character put from the save buffer. A \fIcount\fP +shall indicate how many copies of the save buffer shall be +put. +.TP 7 +\fBu\fP +Undo the last command that changed the edit line. This operation shall +not undo the copy of any command line to the edit +line. +.TP 7 +\fBU\fP +Undo all changes made to the edit line. This operation shall not undo +the copy of any command line to the edit line. +.TP 7 +\fB[\fP\fIcount\fP\fB]k\fP +.TP 7 +\fB[\fP\fIcount\fP\fB]-\fP +Set the current command line to be the \fIcount\fPth previous command +line in the shell command history. If \fIcount\fP is +not specified, it shall default to 1. The cursor shall be positioned +on the first character of the new command. If a \fBk\fP or +\fB-\fP command would retreat past the maximum number of commands +in effect for this shell (affected by the \fIHISTSIZE\fP +environment variable), the terminal shall be alerted, and the command +shall have no effect. +.TP 7 +\fB[\fP\fIcount\fP\fB]j\fP +.TP 7 +\fB[\fP\fIcount\fP\fB]+\fP +Set the current command line to be the \fIcount\fPth next command +line in the shell command history. If \fIcount\fP is not +specified, it shall default to 1. The cursor shall be positioned on +the first character of the new command. If a \fBj\fP or +\fB+\fP command advances past the edit line, the current command line +shall be restored to the edit line and the terminal shall be +alerted. +.TP 7 +\fB[\fP\fInumber\fP\fB]G\fP +Set the current command line to be the oldest command line stored +in the shell command history. With a number \fInumber\fP, +set the current command line to be the command line \fInumber\fP in +the history. If command line \fInumber\fP does not exist, the +terminal shall be alerted and the command line shall not be changed. +.TP 7 +\fB/\fP\fIpattern\fP +.sp +Move backwards through the command history, searching for the specified +pattern, beginning with the previous command line. Patterns +use the pattern matching notation described in \fIPattern Matching +Notation\fP , except +that the \fB'^'\fP character shall have special meaning when it appears +as the first character of \fIpattern\fP. In this case, +the \fB'^'\fP is discarded and the characters after the \fB'^'\fP +shall be matched only at the beginning of a line. Commands +in the command history shall be treated as strings, not as filenames. +If the pattern is not found, the current command line shall +be unchanged and the terminal is alerted. If it is found in a previous +line, the current command line shall be set to that line and +the cursor shall be set to the first character of the new command +line. +.LP +If \fIpattern\fP is empty, the last non-empty pattern provided to +\fB/\fP or \fB?\fP shall be used. If there is no previous +non-empty pattern, the terminal shall be alerted and the current command +line shall remain unchanged. +.TP 7 +\fB?\fP\fIpattern\fP +.sp +Move forwards through the command history, searching for the specified +pattern, beginning with the next command line. Patterns use +the pattern matching notation described in \fIPattern Matching Notation\fP +, except that +the \fB'^'\fP character shall have special meaning when it appears +as the first character of \fIpattern\fP. In this case, the +\fB'^'\fP is discarded and the characters after the \fB'^'\fP shall +be matched only at the beginning of a line. Commands in +the command history shall be treated as strings, not as filenames. +If the pattern is not found, the current command line shall be +unchanged and the terminal alerted. If it is found in a following +line, the current command line shall be set to that line and the +cursor shall be set to the fist character of the new command line. +.LP +If \fIpattern\fP is empty, the last non-empty pattern provided to +\fB/\fP or \fB?\fP shall be used. If there is no previous +non-empty pattern, the terminal shall be alerted and the current command +line shall remain unchanged. +.TP 7 +\fBn\fP +Repeat the most recent \fB/\fP or \fB?\fP command. If there is no +previous \fB/\fP or \fB?\fP, the terminal shall be +alerted and the current command line shall remain unchanged. +.TP 7 +\fBN\fP +Repeat the most recent \fB/\fP or \fB?\fP command, reversing the direction +of the search. If there is no previous \fB/\fP or +\fB?\fP, the terminal shall be alerted and the current command line +shall remain unchanged. +.sp +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ \ \ \ 0 +The script to be executed consisted solely of zero or more blank lines +or comments, or both. +.TP 7 +1-125 +A non-interactive shell detected a syntax, redirection, or variable +assignment error. +.TP 7 +\ \ 127 +A specified \fIcommand_file\fP could not be found by a non-interactive +shell. +.sp +.LP +Otherwise, the shell shall return the exit status of the last command +it invoked or attempted to invoke (see also the \fIexit\fP utility +in \fISpecial Built-In +Utilities\fP ). +.SH CONSEQUENCES OF ERRORS +.LP +See \fIConsequences of Shell Errors\fP . +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Standard input and standard error are the files that determine whether +a shell is interactive when \fB-i\fP is not specified. +For example: +.sp +.RS +.nf + +\fBsh > file +\fP +.fi +.RE +.LP +and: +.sp +.RS +.nf + +\fBsh 2> file +\fP +.fi +.RE +.LP +create interactive and non-interactive shells, respectively. Although +both accept terminal input, the results of error +conditions are different, as described in \fIConsequences of Shell +Errors\fP ; in the +second example a redirection error encountered by a special built-in +utility aborts the shell. +.LP +A conforming application must protect its first operand, if it starts +with a plus sign, by preceding it with the \fB"--"\fP +argument that denotes the end of the options. +.LP +Applications should note that the standard \fIPATH\fP to the shell +cannot be assumed to be either \fB/bin/sh\fP or +\fB/usr/bin/sh\fP, and should be determined by interrogation of the +\fIPATH\fP returned by \fIgetconf\fP \fIPATH ,\fP ensuring that the +returned pathname is an absolute pathname and not a +shell built-in. +.LP +For example, to determine the location of the standard \fIsh\fP utility: +.sp +.RS +.nf + +\fBcommand -v sh +\fP +.fi +.RE +.LP +On some implementations this might return: +.sp +.RS +.nf + +\fB/usr/xpg4/bin/sh +\fP +.fi +.RE +.LP +Furthermore, on systems that support executable scripts (the \fB"#!"\fP +construct), it is recommended that applications using +executable scripts install them using \fIgetconf\fP \fB-v\fP to determine +the shell +pathname and update the \fB"#!"\fP script appropriately as it is being +installed (for example, with \fIsed\fP). For example: +.sp +.RS +.nf + +\fB# +# Installation time script to install correct POSIX shell pathname +# +# Get list of paths to check +# +Sifs=$IFS +IFS=: +set $(getconf PATH) +IFS=$Sifs +# +# Check each path for 'sh' +# +for i in $@ +do + if [ -f ${i}/sh ]; + then + Pshell=${i}/sh + fi +done +# +# This is the list of scripts to update. They should be of the +# form '${name}.source' and will be transformed to '${name}'. +# Each script should begin: +# +# !INSTALLSHELLPATH -p +# +scripts="a b c" +# +# Transform each script +# +for i in ${scripts} +do + sed -e "s|INSTALLSHELLPATH|${Pshell}|" < ${i}.source > ${i} +done +\fP +.fi +.RE +.SH EXAMPLES +.IP " 1." 4 +Execute a shell command from a string: +.sp +.RS +.nf + +\fBsh -c "cat myfile" +\fP +.fi +.RE +.LP +.IP " 2." 4 +Execute a shell script from a file in the current directory: +.sp +.RS +.nf + +\fBsh my_shell_cmds +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +The \fIsh\fP utility and the \fIset\fP special built-in utility share +a common +set of options. +.LP +The KornShell ignores the contents of \fIIFS\fP upon entry to the +script. A conforming application cannot rely on importing +\fIIFS .\fP One justification for this, beyond security considerations, +is to assist possible future shell compilers. Allowing +\fIIFS\fP to be imported from the environment prevents many optimizations +that might otherwise be performed via dataflow analysis +of the script itself. +.LP +The text in the STDIN section about non-blocking reads concerns an +instance of \fIsh\fP that has been invoked, probably by a +C-language program, with standard input that has been opened using +the O_NONBLOCK flag; see \fIopen\fP() in the System Interfaces volume +of IEEE\ Std\ 1003.1-2001. If the shell did not +reset this flag, it would immediately terminate because no input data +would be available yet and that would be considered the same +as end-of-file. +.LP +The options associated with a \fIrestricted shell\fP (command name +\fIrsh\fP and the \fB-r\fP option) were excluded because +the standard developers considered that the implied level of security +could not be achieved and they did not want to raise false +expectations. +.LP +On systems that support set-user-ID scripts, a historical trapdoor +has been to link a script to the name \fB-i\fP. When it is +called by a sequence such as: +.sp +.RS +.nf + +\fBsh - +\fP +.fi +.RE +.LP +or by: +.sp +.RS +.nf + +\fB#! usr/bin/sh - +\fP +.fi +.RE +.LP +the historical systems have assumed that no option letters follow. +Thus, this volume of IEEE\ Std\ 1003.1-2001 allows +the single hyphen to mark the end of the options, in addition to the +use of the regular \fB"--"\fP argument, because it was +considered that the older practice was so pervasive. An alternative +approach is taken by the KornShell, where real and effective +user/group IDs must match for an interactive shell; this behavior +is specifically allowed by this volume of +IEEE\ Std\ 1003.1-2001. +.TP 7 +\fBNote:\fP +There are other problems with set-user-ID scripts that the two approaches +described here do not resolve. +.sp +.LP +The initialization process for the history file can be dependent on +the system start-up files, in that they may contain commands +that effectively preempt the user's settings of \fIHISTFILE\fP and +\fIHISTSIZE .\fP For example, function definition commands are +recorded in the history file, unless the \fIset\fP \fB-o\fP \fInolog\fP +option is +set. If the system administrator includes function definitions in +some system start-up file called before the \fIENV\fP file, the +history file is initialized before the user gets a chance to influence +its characteristics. In some historical shells, the history +file is initialized just after the \fIENV\fP file has been processed. +Therefore, it is implementation-defined whether changes made +to \fIHISTFILE\fP after the history file has been initialized are +effective. +.LP +The default messages for the various \fIMAIL -related\fP messages +are unspecified because they vary across implementations. +Typical messages are: +.sp +.RS +.nf + +\fB"you have mail\\n" +\fP +.fi +.RE +.LP +or: +.sp +.RS +.nf + +\fB"you have new mail\\n" +\fP +.fi +.RE +.LP +It is important that the descriptions of command line editing refer +to the same shell as that in IEEE\ Std\ 1003.1-2001 +so that interactive users can also be application programmers without +having to deal with programmatic differences in their two +environments. It is also essential that the utility name \fIsh\fP +be specified because this explicit utility name is too firmly +rooted in historical practice of application programs for it to change. +.LP +Consideration was given to mandating a diagnostic message when attempting +to set \fIvi\fP-mode on terminals that do not support command line +editing. However, it is not historical +practice for the shell to be cognizant of all terminal types and thus +be able to detect inappropriate terminals in all cases. +Implementations are encouraged to supply diagnostics in this case +whenever possible, rather than leaving the user in a state where +editing commands work incorrectly. +.LP +In early proposals, the KornShell-derived \fIemacs\fP mode of command +line editing was included, even though the \fIemacs\fP +editor itself was not. The community of \fIemacs\fP proponents was +adamant that the full \fIemacs\fP editor not be standardized +because they were concerned that an attempt to standardize this very +powerful environment would encourage vendors to ship strictly +conforming versions lacking the extensibility required by the community. +The author of the original \fIemacs\fP program also +expressed his desire to omit the program. Furthermore, there were +a number of historical systems that did not include \fIemacs\fP, +or included it without supporting it, but there were very few that +did not include and support \fIvi\fP. The shell \fIemacs\fP command +line editing mode was finally omitted because it became +apparent that the KornShell version and the editor being distributed +with the GNU system had diverged in some respects. The author +of \fIemacs\fP requested that the POSIX \fIemacs\fP mode either be +deleted or have a significant number of unspecified +conditions. Although the KornShell author agreed to consider changes +to bring the shell into alignment, the standard developers +decided to defer specification at that time. At the time, it was assumed +that convergence on an acceptable definition would occur +for a subsequent draft, but that has not happened, and there appears +to be no impetus to do so. In any case, implementations are +free to offer additional command line editing modes based on the exact +models of editors their users are most comfortable with. +.LP +Early proposals had the following list entry in vi Line Editing Insert +Mode : +.TP 7 +\fB\\\fP +If followed by the \fIerase\fP or \fIkill\fP character, that character +shall be inserted into the input line. Otherwise, the +backslash itself shall be inserted into the input line. +.sp +.LP +However, this is not actually a feature of \fIsh\fP command line editing +insert mode, but one of some historical terminal line +drivers. Some conforming implementations continue to do this when +the \fIstty\fP +\fBiexten\fP flag is set. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP , \fIcd\fP , \fIecho\fP , \fIexit\fP() +, \fIfc\fP , \fIpwd\fP , \fIread\fP() , \fIset\fP , \fIstty\fP , \fItest\fP +, \fIumask\fP() , \fIvi\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIdup\fP(), \fIexec\fP, \fIexit\fP(), \fIfork\fP(), \fIopen\fP(), +\fIpipe\fP(), \fIsignal\fP(), \fIsystem\fP(), \fIulimit\fP(), \fIumask\fP(), +\fIwait\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/shift.1p b/man1p/shift.1p new file mode 100644 index 000000000..b680847a9 --- /dev/null +++ b/man1p/shift.1p @@ -0,0 +1,93 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SHIFT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" shift +.SH NAME +shift \- shift positional parameters +.SH SYNOPSIS +.LP +\fBshift\fP \fB[\fP\fIn\fP\fB]\fP +.SH DESCRIPTION +.LP +The positional parameters shall be shifted. Positional parameter 1 +shall be assigned the value of parameter (1+\fIn\fP), +parameter 2 shall be assigned the value of parameter (2+\fIn\fP), +and so on. The parameters represented by the numbers +\fB"$#"\fP down to \fB"$#-n+1"\fP shall be unset, and the parameter +\fB'#'\fP is updated to reflect the new number of +positional parameters. +.LP +The value \fIn\fP shall be an unsigned decimal integer less than or +equal to the value of the special parameter \fB'#'\fP . +If \fIn\fP is not given, it shall be assumed to be 1. If \fIn\fP is +0, the positional and special parameters are not changed. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +See the DESCRIPTION. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +None. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The exit status is >0 if \fIn\fP>$#; otherwise, it is zero. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.sp +.RS +.nf + +\fB$\fP \fBset a b c d e +\fP\fB$\fP \fBshift 2 +\fP\fB$\fP \fBecho $* +\fP\fBc d e\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISpecial Built-In Utilities\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/sleep.1p b/man1p/sleep.1p new file mode 100644 index 000000000..b729909c0 --- /dev/null +++ b/man1p/sleep.1p @@ -0,0 +1,173 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SLEEP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sleep +.SH NAME +sleep \- suspend execution for an interval +.SH SYNOPSIS +.LP +\fBsleep\fP \fItime\fP +.SH DESCRIPTION +.LP +The \fIsleep\fP utility shall suspend execution for at least the integral +number of seconds specified by the \fItime\fP +operand. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fItime\fP +A non-negative decimal integer specifying the number of seconds for +which to suspend execution. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIsleep\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +If the \fIsleep\fP utility receives a SIGALRM signal, one of the following +actions shall be taken: +.IP " 1." 4 +Terminate normally with a zero exit status. +.LP +.IP " 2." 4 +Effectively ignore the signal. +.LP +.IP " 3." 4 +Provide the default behavior for signals described in the ASYNCHRONOUS +EVENTS section of \fIUtility Description Defaults\fP . This could +include terminating with a non-zero exit +status. +.LP +.LP +The \fIsleep\fP utility shall take the standard action for all other +signals. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The execution was successfully suspended for at least \fItime\fP seconds, +or a SIGALRM signal was received. See the +ASYNCHRONOUS EVENTS section. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +The \fIsleep\fP utility can be used to execute a command after a certain +amount of time, as in: +.sp +.RS +.nf + +\fB(sleep 105;\fP \fIcommand\fP\fB) & +\fP +.fi +.RE +.LP +or to execute a command every so often, as in: +.sp +.RS +.nf + +\fBwhile true +do + \fP \fIcommand\fP \fB sleep 37 +done +\fP +.fi +.RE +.SH RATIONALE +.LP +The exit status is allowed to be zero when \fIsleep\fP is interrupted +by the SIGALRM signal because most implementations of +this utility rely on the arrival of that signal to notify them that +the requested finishing time has been successfully attained. +Such implementations thus do not distinguish this situation from the +successful completion case. Other implementations are allowed +to catch the signal and go back to sleep until the requested time +expires or to provide the normal signal termination +procedures. +.LP +As with all other utilities that take integral operands and do not +specify subranges of allowed values, \fIsleep\fP is required +by this volume of IEEE\ Std\ 1003.1-2001 to deal with \fItime\fP requests +of up to 2147483647 seconds. This may mean that +some implementations have to make multiple calls to the delay mechanism +of the underlying operating system if its argument range is +less than this. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwait\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIalarm\fP(), \fIsleep\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/sort.1p b/man1p/sort.1p new file mode 100644 index 000000000..3714cceaf --- /dev/null +++ b/man1p/sort.1p @@ -0,0 +1,512 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SORT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sort +.SH NAME +sort \- sort, merge, or sequence check text files +.SH SYNOPSIS +.LP +\fBsort\fP \fB[\fP\fB-m\fP\fB][\fP\fB-o\fP \fIoutput\fP\fB][\fP\fB-bdfinru\fP\fB][\fP\fB-t\fP +\fIchar\fP\fB][\fP\fB-k\fP \fIkeydef\fP\fB]\fP\fB...\fP \fB[\fP\fIfile\fP\fB...\fP\fB]\fP\fB +.br +.sp +sort -c\fP \fB[\fP\fB-bdfinru\fP\fB][\fP\fB-t\fP \fIchar\fP\fB][\fP\fB-k\fP +\fIkeydef\fP\fB][\fP\fIfile\fP\fB]\fP\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsort\fP utility shall perform one of the following functions: +.IP " 1." 4 +Sort lines of all the named files together and write the result to +the specified output. +.LP +.IP " 2." 4 +Merge lines of all the named (presorted) files together and write +the result to the specified output. +.LP +.IP " 3." 4 +Check that a single input file is correctly presorted. +.LP +.LP +Comparisons shall be based on one or more sort keys extracted from +each line of input (or, if no sort keys are specified, the +entire line up to, but not including, the terminating ), +and shall be performed using the collating sequence of the +current locale. +.SH OPTIONS +.LP +The \fIsort\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +and the \fB-k\fP \fIkeydef\fP option should +follow the \fB-b\fP, \fB-d\fP, \fB-f\fP, \fB-i\fP, \fB-n\fP, and \fB-r\fP +options. +.LP +The following options shall be supported: +.TP 7 +\fB-c\fP +Check that the single input file is ordered as specified by the arguments +and the collating sequence of the current locale. No +output shall be produced; only the exit code shall be affected. +.TP 7 +\fB-m\fP +Merge only; the input file shall be assumed to be already sorted. +.TP 7 +\fB-o\ \fP \fIoutput\fP +Specify the name of an output file to be used instead of the standard +output. This file can be the same as one of the input +\fIfile\fPs. +.TP 7 +\fB-u\fP +Unique: suppress all but one in each set of lines having equal keys. +If used with the \fB-c\fP option, check that there are no +lines with duplicate keys, in addition to checking that the input +file is sorted. +.sp +.LP +The following options shall override the default ordering rules. When +ordering options appear independent of any key field +specifications, the requested field ordering rules shall be applied +globally to all sort keys. When attached to a specific key (see +\fB-k\fP), the specified ordering options shall override all global +ordering options for that key. +.TP 7 +\fB-d\fP +Specify that only s and alphanumeric characters, according +to the current setting of \fILC_CTYPE ,\fP shall be +significant in comparisons. The behavior is undefined for a sort key +to which \fB-i\fP or \fB-n\fP also applies. +.TP 7 +\fB-f\fP +Consider all lowercase characters that have uppercase equivalents, +according to the current setting of \fILC_CTYPE ,\fP to be +the uppercase equivalent for the purposes of comparison. +.TP 7 +\fB-i\fP +Ignore all characters that are non-printable, according to the current +setting of \fILC_CTYPE .\fP +.TP 7 +\fB-n\fP +Restrict the sort key to an initial numeric string, consisting of +optional s, optional minus sign, and zero or +more digits with an optional radix character and thousands separators +(as defined in the current locale), which shall be sorted by +arithmetic value. An empty digit string shall be treated as zero. +Leading zeros and signs on zeros shall not affect ordering. +.TP 7 +\fB-r\fP +Reverse the sense of comparisons. +.sp +.LP +The treatment of field separators can be altered using the options: +.TP 7 +\fB-b\fP +Ignore leading s when determining the starting and ending positions +of a restricted sort key. If the \fB-b\fP +option is specified before the first \fB-k\fP option, it shall be +applied to all \fB-k\fP options. Otherwise, the \fB-b\fP +option can be attached independently to each \fB-k\fP \fIfield_start\fP +or \fIfield_end\fP option-argument (see below). +.TP 7 +\fB-t\ \fP \fIchar\fP +Use \fIchar\fP as the field separator character; \fIchar\fP shall +not be considered to be part of a field (although it can be +included in a sort key). Each occurrence of \fIchar\fP shall be significant +(for example, <\fIchar\fP><\fIchar\fP> +delimits an empty field). If \fB-t\fP is not specified, s shall +be used as default field separators; each maximal +non-empty sequence of s that follows a non- shall be +a field separator. +.sp +.LP +Sort keys can be specified using the options: +.TP 7 +\fB-k\ \fP \fIkeydef\fP +The \fIkeydef\fP argument is a restricted sort key field definition. +The format of this definition is: +.sp +.RS +.nf + +\fIfield_start\fP\fB[\fP\fItype\fP\fB][\fP\fB,\fP\fIfield_end\fP\fB[\fP\fItype\fP\fB]]\fP +.fi +.RE +.LP +where \fIfield_start\fP and \fIfield_end\fP define a key field restricted +to a portion of the line (see the EXTENDED +DESCRIPTION section), and \fItype\fP is a modifier from the list of +characters \fB'b'\fP , \fB'd'\fP , \fB'f'\fP , +\fB'i'\fP , \fB'n'\fP , \fB'r'\fP . The \fB'b'\fP modifier shall behave +like the \fB-b\fP option, but shall apply only +to the \fIfield_start\fP or \fIfield_end\fP to which it is attached. +The other modifiers shall behave like the corresponding +options, but shall apply only to the key field to which they are attached; +they shall have this effect if specified with +\fIfield_start\fP, \fIfield_end\fP, or both. If any modifier is attached +to a \fIfield_start\fP or to a \fIfield_end\fP, no +option shall apply to either. Implementations shall support at least +nine occurrences of the \fB-k\fP option, which shall be +significant in command line order. If no \fB-k\fP option is specified, +a default sort key of the entire line shall be used. +.LP +When there are multiple key fields, later keys shall be compared only +after all earlier keys compare equal. Except when the +\fB-u\fP option is specified, lines that otherwise compare equal shall +be ordered as if none of the options \fB-d\fP, \fB-f\fP, +\fB-i\fP, \fB-n\fP, or \fB-k\fP were present (but with \fB-r\fP still +in effect, if it was specified) and with all bytes in the +lines significant to the comparison. The order in which lines that +still compare equal are written is unspecified. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a file to be sorted, merged, or checked. If no \fIfile\fP +operands are specified, or if a \fIfile\fP operand is +\fB'-'\fP , the standard input shall be used. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified, or if a \fIfile\fP operand is \fB'-'\fP . +See the INPUT FILES section. +.SH INPUT FILES +.LP +The input files shall be text files, except that the \fIsort\fP utility +shall add a to the end of a file ending +with an incomplete last line. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIsort\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for ordering rules. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and +the behavior of character classification for the \fB-b\fP, +\fB-d\fP, \fB-f\fP, \fB-i\fP, and \fB-n\fP options. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILC_NUMERIC\fP +.sp +Determine the locale for the definition of the radix character and +thousands separator for the \fB-n\fP option. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Unless the \fB-o\fP or \fB-c\fP options are in effect, the standard +output shall contain the sorted input. +.SH STDERR +.LP +The standard error shall be used for diagnostic messages. A warning +message about correcting an incomplete last line of an input +file may be generated, but need not affect the final exit status. +.SH OUTPUT FILES +.LP +If the \fB-o\fP option is in effect, the sorted input shall be written +to the file \fIoutput\fP. +.SH EXTENDED DESCRIPTION +.LP +The notation: +.sp +.RS +.nf + +\fB-k\fP \fIfield_start\fP\fB[\fP\fItype\fP\fB][\fP\fB,\fP\fIfield_end\fP\fB[\fP\fItype\fP\fB]]\fP +.fi +.RE +.LP +shall define a key field that begins at \fIfield_start\fP and ends +at \fIfield_end\fP inclusive, unless \fIfield_start\fP +falls beyond the end of the line or after \fIfield_end\fP, in which +case the key field is empty. A missing \fIfield_end\fP shall +mean the last character of the line. +.LP +A field comprises a maximal sequence of non-separating characters +and, in the absence of option \fB-t\fP, any preceding field +separator. +.LP +The \fIfield_start\fP portion of the \fIkeydef\fP option-argument +shall have the form: +.sp +.RS +.nf + +\fIfield_number\fP\fB[\fP\fB.\fP\fIfirst_character\fP\fB]\fP +.fi +.RE +.LP +Fields and characters within fields shall be numbered starting with +1. The \fIfield_number\fP and \fIfirst_character\fP +pieces, interpreted as positive decimal integers, shall specify the +first character to be used as part of a sort key. If +\fI\&.first_character\fP is omitted, it shall refer to the first character +of the field. +.LP +The \fIfield_end\fP portion of the \fIkeydef\fP option-argument shall +have the form: +.sp +.RS +.nf + +\fIfield_number\fP\fB[\fP\fB.\fP\fIlast_character\fP\fB]\fP +.fi +.RE +.LP +The \fIfield_number\fP shall be as described above for \fIfield_start.\fP +The \fIlast_character\fP piece, interpreted as a +non-negative decimal integer, shall specify the last character to +be used as part of the sort key. If \fIlast_character\fP +evaluates to zero or \fI.last_character\fP is omitted, it shall refer +to the last character of the field specified by +\fIfield_number\fP. +.LP +If the \fB-b\fP option or \fBb\fP type modifier is in effect, characters +within a field shall be counted from the first non- + in the field. (This shall apply separately to \fIfirst_character\fP +and \fIlast_character\fP.) +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All input files were output successfully, or \fB-c\fP was specified +and the input file was correctly sorted. +.TP 7 +\ 1 +Under the \fB-c\fP option, the file was not ordered as specified, +or if the \fB-c\fP and \fB-u\fP options were both +specified, two input lines were found with equal keys. +.TP 7 +>1 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The default value for \fB-t\fP, , has different properties +from, for example, \fB-t\fP "". If a line +contains: +.sp +.RS +.nf + +\fBfoo +\fP +.fi +.RE +.LP +the following treatment would occur with default separation as opposed +to specifically selecting a : +.TS C +center; l l l. +\fBField\fP \fBDefault\fP \fB-t ""\fP +1 foo \fIempty\fP +2 \fIempty\fP \fIempty\fP +3 \fIempty\fP foo +.TE +.LP +The leading field separator itself is included in a field when \fB-t\fP +is not used. For example, this command returns an exit +status of zero, meaning the input was already sorted: +.sp +.RS +.nf + +\fBsort -c -k 2 <b +xa +eof +\fP +.fi +.RE +.LP +(assuming that a precedes the in the current collating +sequence). The field separator is not included +in a field when it is explicitly set via \fB-t\fP. This is historical +practice and allows usage such as: +.sp +.RS +.nf + +\fBsort -t "|" -k 2n < of the second +field as the sort key: +.sp +.RS +.nf + +\fBsort -k 2.2b,2.2b infile1 infile2 +\fP +.fi +.RE +.LP +.IP " 4." 4 +The following command prints the System\ V password file (user database) +sorted by the numeric user ID (the third +colon-separated field): +.sp +.RS +.nf + +\fBsort -t : -k 3,3n /etc/passwd +\fP +.fi +.RE +.LP +.IP " 5." 4 +The following command prints the lines of the already sorted file +\fBinfile\fP, suppressing all but one occurrence of lines +having the same third field: +.sp +.RS +.nf + +\fBsort -um -k 3.1,3.0 infile +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +Examples in some historical documentation state that options \fB-um\fP +with one input file keep the first in each set of lines +with equal keys. This behavior was deemed to be an implementation +artifact and was not standardized. +.LP +The \fB-z\fP option was omitted; it is not standard practice on most +systems and is inconsistent with using \fIsort\fP to sort +several files individually and then merge them together. The text +concerning \fB-z\fP in historical documentation appeared to +require implementations to determine the proper buffer length during +the sort phase of operation, but not during the merge. +.LP +The \fB-y\fP option was omitted because of non-portability. The \fB-M\fP +option, present in System V, was omitted because of +non-portability in international usage. +.LP +An undocumented \fB-T\fP option exists in some implementations. It +is used to specify a directory for intermediate files. +Implementations are encouraged to support the use of the \fITMPDIR\fP +environment variable instead of adding an option to support +this functionality. +.LP +The \fB-k\fP option was added to satisfy two objections. First, the +zero-based counting used by \fIsort\fP is not consistent +with other utility conventions. Second, it did not meet syntax guideline +requirements. +.LP +Historical documentation indicates that "setting \fB-n\fP implies +\fB-b\fP". The description of \fB-n\fP already states +that optional leading s are tolerated in doing the comparison. +If \fB-b\fP is enabled, rather than implied, by +\fB-n\fP, this has unusual side effects. When a character offset is +used in a column of numbers (for example, to sort modulo 100), +that offset is measured relative to the most significant digit, not +to the column. Based upon a recommendation from the author of +the original \fIsort\fP utility, the \fB-b\fP implication has been +omitted from this volume of IEEE\ Std\ 1003.1-2001, +and an application wishing to achieve the previously mentioned side +effects has to code the \fB-b\fP flag explicitly. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcomm\fP , \fIjoin\fP , \fIuniq\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fItoupper\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/split.1p b/man1p/split.1p new file mode 100644 index 000000000..ac9fe5538 --- /dev/null +++ b/man1p/split.1p @@ -0,0 +1,258 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SPLIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" split +.SH NAME +split \- split files into pieces +.SH SYNOPSIS +.LP +\fBsplit\fP \fB[\fP\fB-l\fP \fIline_count\fP\fB][\fP\fB-a\fP +\fIsuffix_length\fP\fB][\fP\fIfile\fP\fB[\fP\fIname\fP\fB]]\fP\fB +.br +.sp +split -b\fP \fIn\fP\fB[\fP\fBk|m\fP\fB][\fP\fB-a\fP +\fIsuffix_length\fP\fB][\fP\fIfile\fP\fB[\fP\fIname\fP\fB]]\fP\fB\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsplit\fP utility shall read an input file and write one or +more output files. The default size of each output file shall +be 1000 lines. The size of the output files can be modified by specification +of the \fB-b\fP or \fB-l\fP options. Each output +file shall be created with a unique suffix. The suffix shall consist +of exactly \fIsuffix_length\fP lowercase letters from the +POSIX locale. The letters of the suffix shall be used as if they were +a base-26 digit system, with the first suffix to be created +consisting of all \fB'a'\fP characters, the second with a \fB'b'\fP +replacing the last \fB'a'\fP , and so on, until a name +of all \fB'z'\fP characters is created. By default, the names of the +output files shall be \fB'x'\fP , followed by a +two-character suffix from the character set as described above, starting +with \fB"aa"\fP , \fB"ab"\fP , \fB"ac"\fP , and +so on, and continuing until the suffix \fB"zz"\fP , for a maximum +of 676 files. +.LP +If the number of files required exceeds the maximum allowed by the +suffix length provided, such that the last allowable file +would be larger than the requested size, the \fIsplit\fP utility shall +fail after creating the last file with a valid suffix; +\fIsplit\fP shall not delete the files it created with valid suffixes. +If the file limit is not exceeded, the last file created +shall contain the remainder of the input file, and may be smaller +than the requested size. +.SH OPTIONS +.LP +The \fIsplit\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-a\ \fP \fIsuffix_length\fP +.sp +Use \fIsuffix_length\fP letters to form the suffix portion of the +filenames of the split file. If \fB-a\fP is not specified, the +default suffix length shall be two. If the sum of the \fIname\fP operand +and the \fIsuffix_length\fP option-argument would create +a filename exceeding {NAME_MAX} bytes, an error shall result; \fIsplit\fP +shall exit with a diagnostic message and no files shall +be created. +.TP 7 +\fB-b\ \fP \fIn\fP +Split a file into pieces \fIn\fP bytes in size. +.TP 7 +\fB-b\ \fP \fIn\fP\fBk\fP +Split a file into pieces \fIn\fP*1024 bytes in size. +.TP 7 +\fB-b\ \fP \fIn\fP\fBm\fP +Split a file into pieces \fIn\fP*1048576 bytes in size. +.TP 7 +\fB-l\ \fP \fIline_count\fP +Specify the number of lines in each resulting file piece. The \fIline_count\fP +argument is an unsigned decimal integer. The +default is 1000. If the input does not end with a , the partial +line shall be included in the last output file. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile\fP +The pathname of the ordinary file to be split. If no input file is +given or \fIfile\fP is \fB'-'\fP , the standard input +shall be used. +.TP 7 +\fIname\fP +The prefix to be used for each of the files resulting from the split +operation. If no \fIname\fP argument is given, +\fB'x'\fP shall be used as the prefix of the output files. The combined +length of the basename of \fIprefix\fP and +\fIsuffix_length\fP cannot exceed {NAME_MAX} bytes. See the OPTIONS +section. +.sp +.SH STDIN +.LP +See the INPUT FILES section. +.SH INPUT FILES +.LP +Any file can be used as input. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIsplit\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +The output files contain portions of the original input file; otherwise, +unchanged. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +In the following examples \fBfoo\fP is a text file that contains 5000 +lines. +.IP " 1." 4 +Create five files, \fBxaa\fP, \fBxab\fP, \fBxac\fP, \fBxad\fP, and +\fBxae\fP: +.sp +.RS +.nf + +\fBsplit foo +\fP +.fi +.RE +.LP +.IP " 2." 4 +Create five files, but the suffixed portion of the created files consists +of three letters, \fBxaaa\fP, \fBxaab\fP, +\fBxaac\fP, \fBxaad\fP, and \fBxaae\fP: +.sp +.RS +.nf + +\fBsplit -a 3 foo +\fP +.fi +.RE +.LP +.IP " 3." 4 +Create three files with four-letter suffixes and a supplied prefix, +\fBbar_aaaa\fP, \fBbar_aaab\fP, and \fBbar_aaac\fP: +.sp +.RS +.nf + +\fBsplit -a 4 -l 2000 foo bar_ +\fP +.fi +.RE +.LP +.IP " 4." 4 +Create as many files as are necessary to contain at most 20*1024 bytes, +each with the default prefix of \fBx\fP and a +five-letter suffix: +.sp +.RS +.nf + +\fBsplit -a 5 -b 20k foo +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +The \fB-b\fP option was added to provide a mechanism for splitting +files other than by lines. While most uses of the \fB-b\fP +option are for transmitting files over networks, some believed it +would have additional uses. +.LP +The \fB-a\fP option was added to overcome the limitation of being +able to create only 676 files. +.LP +Consideration was given to deleting this utility, using the rationale +that the functionality provided by this utility is +available via the \fIcsplit\fP utility (see \fIcsplit\fP ). Upon +reconsideration of the purpose of the User Portability Extension, +it was decided to retain both this utility and the \fIcsplit\fP utility +because users use both utilities and have historical expectations +of their +behavior. Furthermore, the splitting on byte boundaries in \fIsplit\fP +cannot be duplicated with the historical \fIcsplit\fP. +.LP +The text " \fIsplit\fP shall not delete the files it created with +valid suffixes" would normally be assumed, but since the +related utility, \fIcsplit\fP, does delete files under some circumstances, +the historical +behavior of \fIsplit\fP is made explicit to avoid misinterpretation. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcsplit\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/strings.1p b/man1p/strings.1p new file mode 100644 index 000000000..9a93a1e18 --- /dev/null +++ b/man1p/strings.1p @@ -0,0 +1,222 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRINGS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strings +.SH NAME +strings \- find printable strings in files +.SH SYNOPSIS +.LP +\fBstrings\fP \fB[\fP\fB-a\fP\fB][\fP\fB-t\fP \fIformat\fP\fB][\fP\fB-n\fP +\fInumber\fP\fB][\fP\fIfile\fP\fB...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIstrings\fP utility shall look for printable strings in regular +files and shall write those strings to standard output. A +printable string is any sequence of four (by default) or more printable +characters terminated by a or NUL +character. Additional implementation-defined strings may be written; +see \fIlocaledef\fP. +.SH OPTIONS +.LP +The \fIstrings\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-a\fP +Scan files in their entirety. If \fB-a\fP is not specified, it is +implementation-defined what portion of each file is scanned +for strings. +.TP 7 +\fB-n\ \fP \fInumber\fP +Specify the minimum string length, where the \fInumber\fP argument +is a positive decimal integer. The default shall be 4. +.TP 7 +\fB-t\ \fP \fIformat\fP +Write each string preceded by its byte offset from the start of the +file. The format shall be dependent on the single character +used as the \fIformat\fP option-argument: +.TP 7 +\fBd\fP +.RS +The offset shall be written in decimal. +.RE +.TP 7 +\fBo\fP +.RS +The offset shall be written in octal. +.RE +.TP 7 +\fBx\fP +.RS +The offset shall be written in hexadecimal. +.RE +.sp +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a regular file to be used as input. If no \fIfile\fP +operand is specified, the \fIstrings\fP utility shall read +from the standard input. +.sp +.SH STDIN +.LP +See the INPUT FILES section. +.SH INPUT FILES +.LP +The input files named by the utility arguments or the standard input +shall be regular files of any format. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIstrings\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and +to identify printable strings. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Strings found shall be written to the standard output, one per line. +.LP +When the \fB-t\fP option is not specified, the format of the output +shall be: +.sp +.RS +.nf + +\fB"%s", <\fP\fIstring\fP\fB> +\fP +.fi +.RE +.LP +With the \fB-t\ o\fP option, the format of the output shall be: +.sp +.RS +.nf + +\fB"%o %s", <\fP\fIbyte offset\fP\fB>, <\fP\fIstring\fP\fB> +\fP +.fi +.RE +.LP +With the \fB-t\ x\fP option, the format of the output shall be: +.sp +.RS +.nf + +\fB"%x %s", <\fP\fIbyte offset\fP\fB>, <\fP\fIstring\fP\fB> +\fP +.fi +.RE +.LP +With the \fB-t\ d\fP option, the format of the output shall be: +.sp +.RS +.nf + +\fB"%d %s", <\fP\fIbyte offset\fP\fB>, <\fP\fIstring\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +By default the data area (as opposed to the text, "bss", or header +areas) of a binary executable file is scanned. +Implementations document which areas are scanned. +.LP +Some historical implementations do not require NUL or terminators +for strings to permit those languages that do +not use NUL as a string terminator to have their strings written. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +Apart from rationalizing the option syntax and slight difficulties +with object and executable binary files, \fIstrings\fP is +specified to match historical practice closely. The \fB-a\fP and \fB-n\fP +options were introduced to replace the non-conforming +\fB-\fP and \fB-\fP \fInumber\fP options. +.LP +The \fB-o\fP option historically means different things on different +implementations. Some use it to mean " \fIoffset\fP in +decimal", while others use it as " \fIoffset\fP in octal". Instead +of trying to decide which way would be least objectionable, +the \fB-t\fP option was added. It was originally named \fB-O\fP to +mean "offset", but was changed to \fB-t\fP to be consistent +with \fIod\fP. +.LP +The ISO\ C standard function \fIisprint\fP() is restricted to a domain +of +\fBunsigned char\fP. This volume of IEEE\ Std\ 1003.1-2001 requires +implementations to write strings as defined by the +current locale. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIlocaledef\fP , \fInm\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/strip.1p b/man1p/strip.1p new file mode 100644 index 000000000..afef7bd8f --- /dev/null +++ b/man1p/strip.1p @@ -0,0 +1,128 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRIP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strip +.SH NAME +strip \- remove unnecessary information from executable files (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBstrip\fP \fIfile\fP\fB... \fP +.SH DESCRIPTION +.LP +The \fIstrip\fP utility shall remove from executable files named by +the \fIfile\fP operands any information the implementor +deems unnecessary for execution of those files. The nature of that +information is unspecified. The effect of \fIstrip\fP shall be +similar to the use of the \fB-s\fP option to \fIc99\fP or \fIfort77\fP. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname referring to an executable file. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +The input files shall be in the form of executable files successfully +produced by any compiler defined by this volume of +IEEE\ Std\ 1003.1-2001. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIstrip\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +The \fIstrip\fP utility shall produce executable files of unspecified +format. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +Historically, this utility has been used to remove the symbol table +from an executable file. It was included since it is known +that the amount of symbolic information can amount to several megabytes; +the ability to remove it in a portable manner was deemed +important, especially for smaller systems. +.LP +The behavior of \fIstrip\fP is said to be the same as the \fB-s\fP +option to a compiler. While the end result is essentially +the same, it is not required to be identical. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIar\fP , \fIc99\fP , \fIfort77\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/stty.1p b/man1p/stty.1p new file mode 100644 index 000000000..8493c8934 --- /dev/null +++ b/man1p/stty.1p @@ -0,0 +1,697 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STTY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" stty +.SH NAME +stty \- set the options for a terminal +.SH SYNOPSIS +.LP +\fBstty\fP \fB[\fP \fB-a| -g\fP\fB]\fP\fB +.br +.sp +stty\fP \fIoperands\fP\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIstty\fP utility shall set or report on terminal I/O characteristics +for the device that is its standard input. Without +options or operands specified, it shall report the settings of certain +characteristics, usually those that differ from +implementation-defined defaults. Otherwise, it shall modify the terminal +state according to the specified operands. Detailed +information about the modes listed in the first five groups below +are described in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. Operands +in the Combination Modes group (see Combination Modes ) are implemented +using operands in the +previous groups. Some combinations of operands are mutually-exclusive +on some terminal types; the results of using such +combinations are unspecified. +.LP +Typical implementations of this utility require a communications line +configured to use the \fBtermios\fP interface defined in +the System Interfaces volume of IEEE\ Std\ 1003.1-2001. On systems +where none of these lines are available, and on lines +not currently configured to support the \fBtermios\fP interface, some +of the operands need not affect terminal +characteristics. +.SH OPTIONS +.LP +The \fIstty\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-a\fP +Write to standard output all the current settings for the terminal. +.TP 7 +\fB-g\fP +Write to standard output all the current settings in an unspecified +form that can be used as arguments to another invocation of +the \fIstty\fP utility on the same system. The form used shall not +contain any characters that would require quoting to avoid word +expansion by the shell; see \fIWord Expansions\fP . +.sp +.SH OPERANDS +.LP +The following operands shall be supported to set the terminal characteristics. +.SS Control Modes +.TP 7 +\fBparenb\ \fP (\fB-parenb\fP) +Enable (disable) parity generation and detection. This shall have +the effect of setting (not setting) PARENB in the +\fBtermios\fP \fIc_cflag\fP field, as defined in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBparodd\ \fP (\fB-parodd\fP) +.sp +Select odd (even) parity. This shall have the effect of setting (not +setting) PARODD in the \fBtermios\fP \fIc_cflag\fP field, as +defined in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 11, +General Terminal Interface. +.TP 7 +\fBcs5\ cs6\ cs7\ cs8\fP +Select character size, if possible. This shall have the effect of +setting CS5, CS6, CS7, and CS8, respectively, in the +\fBtermios\fP \fIc_cflag\fP field, as defined in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fInumber\fP +Set terminal baud rate to the number given, if possible. If the baud +rate is set to zero, the modem control lines shall no +longer be asserted. This shall have the effect of setting the input +and output \fBtermios\fP baud rate values as defined in the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General +Terminal Interface. +.TP 7 +\fBispeed\ \fP \fInumber\fP +Set terminal input baud rate to the number given, if possible. If +the input baud rate is set to zero, the input baud rate shall +be specified by the value of the output baud rate. This shall have +the effect of setting the input \fBtermios\fP baud rate values +as defined in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter +11, General Terminal Interface. +.TP 7 +\fBospeed\ \fP \fInumber\fP +Set terminal output baud rate to the number given, if possible. If +the output baud rate is set to zero, the modem control lines +shall no longer be asserted. This shall have the effect of setting +the output \fBtermios\fP baud rate values as defined in the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General +Terminal Interface. +.TP 7 +\fBhupcl\ \fP (\fB-hupcl\fP) +Stop asserting modem control lines (do not stop asserting modem control +lines) on last close. This shall have the effect of +setting (not setting) HUPCL in the \fBtermios\fP \fIc_cflag\fP field, +as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBhup\ \fP (\fB-hup\fP) +Equivalent to \fBhupcl\fP( \fB-hupcl\fP). +.TP 7 +\fBcstopb\ \fP (\fB-cstopb\fP) +Use two (one) stop bits per character. This shall have the effect +of setting (not setting) CSTOPB in the \fBtermios\fP +\fIc_cflag\fP field, as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBcread\ \fP (\fB-cread\fP) +Enable (disable) the receiver. This shall have the effect of setting +(not setting) CREAD in the \fBtermios\fP \fIc_cflag\fP +field, as defined in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 11, General Terminal Interface. +.TP 7 +\fBclocal\ \fP (\fB-clocal\fP) +Assume a line without (with) modem control. This shall have the effect +of setting (not setting) CLOCAL in the \fBtermios\fP +\fIc_cflag\fP field, as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.sp +.LP +It is unspecified whether \fIstty\fP shall report an error if an attempt +to set a Control Mode fails. +.SS Input Modes +.TP 7 +\fBignbrk\ \fP (\fB-ignbrk\fP) +Ignore (do not ignore) break on input. This shall have the effect +of setting (not setting) IGNBRK in the \fBtermios\fP +\fIc_iflag\fP field, as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBbrkint\ \fP (\fB-brkint\fP) +Signal (do not signal) INTR on break. This shall have the effect of +setting (not setting) BRKINT in the \fBtermios\fP +\fIc_iflag\fP field, as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBignpar\ \fP (\fB-ignpar\fP) +Ignore (do not ignore) bytes with parity errors. This shall have the +effect of setting (not setting) IGNPAR in the +\fBtermios\fP \fIc_iflag\fP field, as defined in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBparmrk\ \fP (\fB-parmrk\fP) +.sp +Mark (do not mark) parity errors. This shall have the effect of setting +(not setting) PARMRK in the \fBtermios\fP \fIc_iflag\fP +field, as defined in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 11, General Terminal Interface. +.TP 7 +\fBinpck\ \fP (\fB-inpck\fP) +Enable (disable) input parity checking. This shall have the effect +of setting (not setting) INPCK in the \fBtermios\fP +\fIc_iflag\fP field, as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBistrip\ \fP (\fB-istrip\fP) +Strip (do not strip) input characters to seven bits. This shall have +the effect of setting (not setting) ISTRIP in the +\fBtermios\fP \fIc_iflag\fP field, as defined in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBinlcr\ \fP (\fB-inlcr\fP) +Map (do not map) NL to CR on input. This shall have the effect of +setting (not setting) INLCR in the \fBtermios\fP +\fIc_iflag\fP field, as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBigncr\ (-igncr)\fP +Ignore (do not ignore) CR on input. This shall have the effect of +setting (not setting) IGNCR in the \fBtermios\fP +\fIc_iflag\fP field, as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBicrnl\ \fP (\fB-icrnl\fP) +Map (do not map) CR to NL on input. This shall have the effect of +setting (not setting) ICRNL in the \fBtermios\fP +\fIc_iflag\fP field, as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBixon\ \fP (\fB-ixon\fP) +Enable (disable) START/STOP output control. Output from the system +is stopped when the system receives STOP and started when +the system receives START. This shall have the effect of setting (not +setting) IXON in the \fBtermios\fP \fIc_iflag\fP field, as +defined in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 11, +General Terminal Interface. +.TP 7 +\fBixany\ \fP (\fB-ixany\fP) +Allow any character to restart output. This shall have the effect +of setting (not setting) IXANY in the \fBtermios\fP +\fIc_iflag\fP field, as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBixoff\ \fP (\fB-ixoff\fP) +Request that the system send (not send) STOP characters when the input +queue is nearly full and START characters to resume data +transmission. This shall have the effect of setting (not setting) +IXOFF in the \fBtermios\fP \fIc_iflag\fP field, as defined in +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 11, +General +Terminal Interface. +.sp +.SS Output Modes +.TP 7 +\fBopost\ \fP (\fB-opost\fP) +Post-process output (do not post-process output; ignore all other +output modes). This shall have the effect of setting (not +setting) OPOST in the \fBtermios\fP \fIc_oflag\fP field, as defined +in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBocrnl\ \fP (\fB-ocrnl\fP) +Map (do not map) CR to NL on output This shall have the effect of +setting (not setting) OCRNL in the \fBtermios\fP \fIc_oflag\fP +field, as defined in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 11, General Terminal Interface. +.TP 7 +\fBonocr\ \fP (\fB-onocr\fP) +Do not (do) output CR at column zero. This shall have the effect of +setting (not setting) ONOCR in the \fBtermios\fP +\fIc_oflag\fP field, as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBonlret\ \fP (\fB-onlret\fP) +The terminal newline key performs (does not perform) the CR function. +This shall have the effect of setting (not setting) +ONLRET in the \fBtermios\fP \fIc_oflag\fP field, as defined in the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General +Terminal Interface. +.TP 7 +\fBofill\ \fP (\fB-ofill\fP) +Use fill characters (use timing) for delays. This shall have the effect +of setting (not setting) OFILL in the \fBtermios\fP +\fIc_oflag\fP field, as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBofdel\ \fP (\fB-ofdel\fP) +Fill characters are DELs (NULs). This shall have the effect of setting +(not setting) OFDEL in the \fBtermios\fP \fIc_oflag\fP +field, as defined in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 11, General Terminal Interface. +.TP 7 +\fBcr0\ cr1\ cr2\ cr3\fP +Select the style of delay for CRs. This shall have the effect of setting +CRDLY to CR0, CR1, CR2, or CR3, respectively, in the +\fBtermios\fP \fIc_oflag\fP field, as defined in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBnl0\ nl1\fP +Select the style of delay for NL. This shall have the effect of setting +NLDLY to NL0 or NL1, respectively, in the +\fBtermios\fP \fIc_oflag\fP field, as defined in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBtab0\ tab1\ tab2\ tab3\fP +.sp +Select the style of delay for horizontal tabs. This shall have the +effect of setting TABDLY to TAB0, TAB1, TAB2, or TAB3, +respectively, in the \fBtermios\fP \fIc_oflag\fP field, as defined +in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. Note +that +TAB3 has the effect of expanding s to s. +.TP 7 +\fBtabs\ \fP (\fB-tabs\fP) +Synonym for \fBtab0\fP ( \fBtab3\fP). +.TP 7 +\fBbs0\ bs1\fP +Select the style of delay for backspaces. This shall have the effect +of setting BSDLY to BS0 or BS1, respectively, in the +\fBtermios\fP \fIc_oflag\fP field, as defined in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBff0\ ff1\fP +Select the style of delay for form-feeds. This shall have the effect +of setting FFDLY to FF0 or FF1, respectively, in the +\fBtermios\fP \fIc_oflag\fP field, as defined in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBvt0\ vt1\fP +Select the style of delay for vertical-tabs. This shall have the effect +of setting VTDLY to VT0 or VT1, respectively, in the +\fBtermios\fP \fIc_oflag\fP field, as defined in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.sp +.SS Local Modes +.TP 7 +\fBisig\ \fP (\fB-isig\fP) +Enable (disable) the checking of characters against the special control +characters INTR, QUIT, and SUSP. This shall have the +effect of setting (not setting) ISIG in the \fBtermios\fP \fIc_lflag\fP +field, as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBicanon\ \fP (\fB-icanon\fP) +Enable (disable) canonical input (ERASE and KILL processing). This +shall have the effect of setting (not setting) ICANON in the +\fBtermios\fP \fIc_lflag\fP field, as defined in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBiexten\ \fP (\fB-iexten\fP) +Enable (disable) any implementation-defined special control characters +not currently controlled by \fBicanon\fP, \fBisig\fP, +\fBixon\fP, or \fBixoff\fP. This shall have the effect of setting +(not setting) IEXTEN in the \fBtermios\fP \fIc_lflag\fP +field, as defined in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 11, General Terminal Interface. +.TP 7 +\fBecho\ \fP (\fB-echo\fP) +Echo back (do not echo back) every character typed. This shall have +the effect of setting (not setting) ECHO in the +\fBtermios\fP \fIc_lflag\fP field, as defined in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBechoe\ \fP (\fB-echoe\fP) +The ERASE character visually erases (does not erase) the last character +in the current line from the display, if possible. This +shall have the effect of setting (not setting) ECHOE in the \fBtermios\fP +\fIc_lflag\fP field, as defined in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal +Interface. +.TP 7 +\fBechok\ \fP (\fB-echok\fP) +Echo (do not echo) NL after KILL character. This shall have the effect +of setting (not setting) ECHOK in the \fBtermios\fP +\fIc_lflag\fP field, as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBechonl\ \fP (\fB-echonl\fP) +Echo (do not echo) NL, even if \fBecho\fP is disabled. This shall +have the effect of setting (not setting) ECHONL in the +\fBtermios\fP \fIc_lflag\fP field, as defined in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBnoflsh\ \fP (\fB-noflsh\fP) +Disable (enable) flush after INTR, QUIT, SUSP. This shall have the +effect of setting (not setting) NOFLSH in the \fBtermios\fP +\fIc_lflag\fP field, as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.TP 7 +\fBtostop\ \fP (\fB-tostop\fP) +Send SIGTTOU for background output. This shall have the effect of +setting (not setting) TOSTOP in the \fBtermios\fP +\fIc_lflag\fP field, as defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface. +.sp +.SS Special Control Character Assignments +.TP 7 +<\fIcontrol\fP>-\fIcharacter\ string\fP +.sp +Set <\fIcontrol\fP>-\fIcharacter\fP to \fIstring\fP. If <\fIcontrol\fP>-\fIcharacter\fP +is one of the character +sequences in the first column of the following table, the corresponding +Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 11, General Terminal Interface control character from the +second column +shall be recognized. This has the effect of setting the corresponding +element of the \fBtermios\fP \fIc_cc\fP array (see the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 13, Headers, +\fI\fP). +.br +.sp +.ce 1 +\fBTable: Control Character Names in \fIstty\fP\fP +.TS C +center; l2 l2 l. +\fBControl Character\fP \fBc_cc Subscript\fP \fBDescription\fP +\fBeof\fP VEOF EOF character +\fBeol\fP VEOL EOL character +\fBerase\fP VERASE ERASE character +\fBintr\fP VINTR INTR character +\fBkill\fP VKILL KILL character +\fBquit\fP VQUIT QUIT character +\fBsusp\fP VSUSP SUSP character +\fBstart\fP VSTART START character +\fBstop\fP VSTOP STOP character +.TE +.LP +If \fIstring\fP is a single character, the control character shall +be set to that character. If \fIstring\fP is the +two-character sequence \fB"^-"\fP or the string \fIundef\fP, the control +character shall be set to _POSIX_VDISABLE , if it is +in effect for the device; if _POSIX_VDISABLE is not in effect for +the device, it shall be treated as an error. In the POSIX locale, +if \fIstring\fP is a two-character sequence beginning with circumflex +( \fB'^'\fP ), and the second character is one of those +listed in the \fB"^c"\fP column of the following table, the control +character shall be set to the corresponding character value +in the Value column of the table. +.sp +.ce 1 +\fBTable: Circumflex Control Characters in \fIstty\fP\fP +.TS C +center; l l l l l l. +\fB^c\fP \fBValue\fP \fB^c\fP \fBValue\fP \fB^c\fP \fBValue\fP +a, A l, L w, W +b, B m, M x, X +c, C n, N y, Y +d, D o, O z, Z +e, E p, P [ +f, F q, Q \\ +g, G r, R ] +h, H s, S ^ +i, I t, T _ +j, J u, U ? +k, K v, V +.TE +.TP 7 +\fBmin\ \fP \fInumber\fP +.sp +Set the value of MIN to \fInumber\fP. MIN is used in non-canonical +mode input processing ( \fBicanon\fP). +.TP 7 +\fBtime\ \fP \fInumber\fP +.sp +Set the value of TIME to \fInumber\fP. TIME is used in non-canonical +mode input processing ( \fBicanon\fP). +.sp +.SS Combination Modes +.TP 7 +\fIsaved\ settings\fP +.sp +Set the current terminal characteristics to the saved settings produced +by the \fB-g\fP option. +.TP 7 +\fBevenp\fP\ or\ \fBparity\fP +.sp +Enable \fBparenb\fP and \fBcs7\fP; disable \fBparodd\fP. +.TP 7 +\fBoddp\fP +.sp +Enable \fBparenb\fP, \fBcs7\fP, and \fBparodd\fP. +.TP 7 +\fB-parity\fP, \fB-evenp\fP, or \fB-oddp\fP +.sp +Disable \fBparenb\fP, and set \fBcs8\fP. +.TP 7 +\fBraw\ \fP (\fB-raw\fP\ or\ \fBcooked\fP) +.sp +Enable (disable) raw input and output. Raw mode shall be equivalent +to setting: +.sp +.RS +.nf + +\fBstty cs8 erase ^- kill ^- intr ^- \\ + quit ^- eof ^- eol ^- -post -inpck +\fP +.fi +.RE +.TP 7 +\fBnl\ \fP (\fB-nl\fP) +.sp +Disable (enable) \fBicrnl\fP. In addition, \fB-nl\fP unsets \fBinlcr\fP +and \fBigncr\fP. +.TP 7 +\fBek\fP +Reset ERASE and KILL characters back to system defaults. +.TP 7 +\fBsane\fP +.sp +Reset all modes to some reasonable, unspecified, values. +.sp +.SH STDIN +.LP +Although no input is read from standard input, standard input shall +be used to get the current terminal I/O characteristics and +to set new terminal I/O characteristics. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIstty\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +This variable determines the locale for the interpretation of sequences +of bytes of text data as characters (for example, +single-byte as opposed to multi-byte characters in arguments) and +which characters are in the class \fBprint\fP. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If operands are specified, no output shall be produced. +.LP +If the \fB-g\fP option is specified, \fIstty\fP shall write to standard +output the current settings in a form that can be used +as arguments to another instance of \fIstty\fP on the same system. +.LP +If the \fB-a\fP option is specified, all of the information as described +in the OPERANDS section shall be written to standard +output. Unless otherwise specified, this information shall be written +as -separated tokens in an unspecified format, +on one or more lines, with an unspecified number of tokens per line. +Additional information may be written. +.LP +If no options or operands are specified, an unspecified subset of +the information written for the \fB-a\fP option shall be +written. +.LP +If speed information is written as part of the default output, or +if the \fB-a\fP option is specified and if the terminal input +speed and output speed are the same, the speed information shall be +written as follows: +.sp +.RS +.nf + +\fB"speed %d baud;", <\fP\fIspeed\fP\fB> +\fP +.fi +.RE +.LP +Otherwise, speeds shall be written as: +.sp +.RS +.nf + +\fB"ispeed %d baud; ospeed %d baud;", <\fP\fIispeed\fP\fB>, <\fP\fIospeed\fP\fB> +\fP +.fi +.RE +.LP +In locales other than the POSIX locale, the word \fBbaud\fP may be +changed to something more appropriate in those locales. +.LP +If control characters are written as part of the default output, or +if the \fB-a\fP option is specified, control characters +shall be written as: +.sp +.RS +.nf + +\fB"%s = %s;", <\fP\fIcontrol-character name\fP\fB>, <\fP\fIvalue\fP\fB> +\fP +.fi +.RE +.LP +where <\fIvalue\fP> is either the character, or some visual representation +of the character if it is non-printable, or +the string \fIundef\fP if the character is disabled. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The terminal options were read or set successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fB-g\fP flag is designed to facilitate the saving and restoring +of terminal state from the shell level. For example, a +program may: +.sp +.RS +.nf + +\fBsaveterm="$(stty -g)" # save terminal state +stty\fP \fI(new settings)\fP \fB # set new state +\&... # ... +stty $saveterm # restore terminal state +\fP +.fi +.RE +.LP +Since the format is unspecified, the saved value is not portable across +systems. +.LP +Since the \fB-a\fP format is so loosely specified, scripts that save +and restore terminal settings should use the \fB-g\fP +option. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The original \fIstty\fP description was taken directly from System +V and reflected the System V terminal driver \fBtermio\fP. +It has been modified to correspond to the terminal driver \fBtermios\fP. +.LP +Output modes are specified only for XSI-conformant systems. All implementations +are expected to provide \fIstty\fP operands +corresponding to all of the output modes they support. +.LP +The \fIstty\fP utility is primarily used to tailor the user interface +of the terminal, such as selecting the preferred ERASE +and KILL characters. As an application programming utility, \fIstty\fP +can be used within shell scripts to alter the terminal +settings for the duration of the script. +.LP +The \fBtermios\fP section states that individual disabling of control +characters is possible through the option +_POSIX_VDISABLE. If enabled, two conventions currently exist for specifying +this: System V uses \fB"^-"\fP , and BSD uses +\fIundef\fP. Both are accepted by \fIstty\fP in this volume of IEEE\ Std\ 1003.1-2001. +The other BSD convention of using +the letter \fB'u'\fP was rejected because it conflicts with the actual +letter \fB'u'\fP , which is an acceptable value for a +control character. +.LP +Early proposals did not specify the mapping of \fB"^c"\fP to control +characters because the control characters were not +specified in the POSIX locale character set description file requirements. +The control character set is now specified in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 3, Definitions +so the +historical mapping is specified. Note that although the mapping corresponds +to control-character key assignments on many terminals +that use the ISO/IEC\ 646:1991 standard (or ASCII) character encodings, +the mapping specified here is to the control +characters, not their keyboard encodings. +.LP +Since \fBtermios\fP supports separate speeds for input and output, +two new options were added to specify each distinctly. +.LP +Some historical implementations use standard input to get and set +terminal characteristics; others use standard output. Since +input from a login TTY is usually restricted to the owner while output +to a TTY is frequently open to anyone, using standard input +provides fewer chances of accidentally (or maliciously) altering the +terminal settings of other users. Using standard input also +allows \fIstty\fP \fB-a\fP and \fIstty\fP \fB-g\fP output to be redirected +for later use. Therefore, usage of standard input is +required by this volume of IEEE\ Std\ 1003.1-2001. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/tabs.1p b/man1p/tabs.1p new file mode 100644 index 000000000..a64978ca7 --- /dev/null +++ b/man1p/tabs.1p @@ -0,0 +1,263 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TABS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tabs +.SH NAME +tabs \- set terminal tabs +.SH SYNOPSIS +.LP +\fBtabs\fP \fB[\fP \fB-\fP\fIn\fP\fB| -a| -a2| -c| -c2| -c3| -f| -p| +-s| +-u\fP\fB][\fP\fB+m\fP\fB[\fP\fIn\fP\fB]]\fP \fB\fP\fB[\fP\fB-T\fP +\fItype\fP\fB]\fP\fB +.br +.sp +tabs\fP \fB[\fP\fB-T\fP \fItype\fP\fB][\fP \fB+\fP\fB[\fP\fIn\fP\fB]]\fP +\fIn1\fP\fB[\fP\fB,\fP\fIn2\fP\fB,...\fP\fB]\fP\fB\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fItabs\fP utility shall display a series of characters that first +clears the hardware terminal tab settings and then +initializes the tab stops at the specified positions \ and optionally +adjusts the margin. +.LP +The phrase "tab-stop position \fIN\fP" shall be taken to mean that, +from the start of a line of output, tabbing to position +\fIN\fP shall cause the next character output to be in the ( \fIN\fP+1)th +column position on that line. The maximum number of tab +stops allowed is terminal-dependent. +.LP +It need not be possible to implement \fItabs\fP on certain terminals. +If the terminal type obtained from the \fITERM\fP +environment variable or \fB-T\fP option represents such a terminal, +an appropriate diagnostic message shall be written to standard +error and \fItabs\fP shall exit with a status greater than zero. +.SH OPTIONS +.LP +The \fItabs\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +\ except for +various extensions: the options \fB-a2\fP, \fB-c2\fP, and \fB-c3\fP +are multi-character. +.LP +The following options shall be supported: +.TP 7 +\fB-\fP\fIn\fP +Specify repetitive tab stops separated by a uniform number of column +positions, \fIn\fP, where \fIn\fP is a single-digit +decimal number. The default usage of \fItabs\fP with no arguments +shall be equivalent to \fBtabs\fP-8. When \fB-0\fP is used, +the tab stops shall be cleared and no new ones set. +.TP 7 +\fB-a\fP +1,10,16,36,72 +.br +Assembler, applicable to some mainframes. +.TP 7 +\fB-a2\fP +1,10,16,40,72 +.br +Assembler, applicable to some mainframes. +.TP 7 +\fB-c\fP +1,8,12,16,20,55 +.br +COBOL, normal format. +.TP 7 +\fB-c2\fP +1,6,10,14,49 +.br +COBOL, compact format (columns 1 to 6 omitted). +.TP 7 +\fB-c3\fP +1,6,10,14,18,22,26,30,34,38,42,46,50,54,58,62,67 +.br +COBOL compact format (columns 1 to 6 omitted), with more tabs than +\fB-c2\fP. +.TP 7 +\fB-f\fP +1,7,11,15,19,23 +.br +FORTRAN +.TP 7 +\fB-p\fP +1,5,9,13,17,21,25,29,33,37,41,45,49,53,57,61 +.br +PL/1 +.TP 7 +\fB-s\fP +1,10,55 +.br +SNOBOL +.TP 7 +\fB-u\fP +1,12,20,44 +.br +Assembler, applicable to some mainframes. +.TP 7 +\fB-T\ \fP \fItype\fP +Indicate the type of terminal. If this option is not supplied and +the \fITERM\fP variable is unset or null, an unspecified +default terminal type shall be used. The setting of \fItype\fP shall +take precedence over the value in \fITERM .\fP +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIn1\fP\fB[\fP,\fIn2\fP,...\fB]\fP +A single command line argument that consists of tab-stop values separated +using either commas or s. The +application shall ensure that the tab-stop values are positive decimal +integers in strictly ascending order. If any number (except +the first one) is preceded by a plus sign, it is taken as an increment +to be added to the previous value. For example, the tab +lists 1,10,20,30 and 1,10,+10,+10 are considered to be identical. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fItabs\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITERM\fP +Determine the terminal type. If this variable is unset or null, and +if the \fB-T\fP option is not specified, an unspecified +default terminal type shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If standard output is a terminal, the appropriate sequence to clear +and set the tab stops may be written to standard output in +an unspecified format. If standard output is not a terminal, undefined +results occur. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +This utility makes use of the terminal's hardware tabs and the \fIstty\fP +\fItabs\fP +option. +.LP +This utility is not recommended for application use. +.LP +Some integrated display units might not have escape sequences to set +tab stops, but may be set by internal system calls. On +these terminals, \fItabs\fP works if standard output is directed to +the terminal; if output is directed to another file, however, +\fItabs\fP fails. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +Consideration was given to having the \fItput\fP utility handle all +of the functions +described in \fItabs\fP. However, the separate \fItabs\fP utility +was retained because it seems more intuitive to use a command +named \fItabs\fP than \fItput\fP with a new option. The \fItput\fP +utility does not support setting or clearing tabs, and no known historical +version of +\fItabs\fP supports the capability of setting arbitrary tab stops. +.LP +The System V \fItabs\fP interface is very complex; the version in +this volume of IEEE\ Std\ 1003.1-2001 has a reduced +feature list, but many of the features omitted were restored as XSI +extensions even though the supported languages and coding +styles are primarily historical. +.LP +There was considerable sentiment for specifying only a means of resetting +the tabs back to a known state-presumably the +"standard" of tabs every eight positions. The following features were +omitted: +.IP " *" 3 +Setting tab stops via the first line in a file, using -- \fIfile\fP. +Since even the SVID has no complete explanation of this +feature, it is doubtful that it is in widespread use. +.LP +.LP +In an early proposal, a \fB-t\fP \fItablist\fP option was added for +consistency with \fIexpand\fP; this was later removed when inconsistencies +with the historical list of tabs were +identified. +.LP +Consideration was given to adding a \fB-p\fP option that would output +the current tab settings so that they could be saved and +then later restored. This was not accepted because querying the tab +stops of the terminal is not a capability in historical +\fIterminfo\fP or \fItermcap\fP facilities and might not be supported +on a wide range of terminals. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexpand\fP , \fIstty\fP , \fItput\fP , \fIunexpand\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/tail.1p b/man1p/tail.1p new file mode 100644 index 000000000..515d18ea9 --- /dev/null +++ b/man1p/tail.1p @@ -0,0 +1,249 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TAIL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tail +.SH NAME +tail \- copy the last part of a file +.SH SYNOPSIS +.LP +\fBtail\fP \fB[\fP\fB-f\fP\fB][\fP \fB-c\fP \fInumber\fP\fB| -n\fP +\fInumber\fP\fB][\fP\fIfile\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fItail\fP utility shall copy its input file to the standard output +beginning at a designated place. +.LP +Copying shall begin at the point in the file indicated by the \fB-c\fP +\fInumber\fP or \fB-n\fP \fInumber\fP options. The +option-argument \fInumber\fP shall be counted in units of lines or +bytes, according to the options \fB-n\fP and \fB-c\fP. Both +line and byte counts start from 1. +.LP +Tails relative to the end of the file may be saved in an internal +buffer, and thus may be limited in length. Such a buffer, if +any, shall be no smaller than {LINE_MAX}*10 bytes. +.SH OPTIONS +.LP +The \fItail\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-c\ \fP \fInumber\fP +The application shall ensure that the \fInumber\fP option-argument +is a decimal integer whose sign affects the location in the +file, measured in bytes, to begin the copying: +.TS C +center; l l. +\fBSign\fP \fBCopying Starts\fP ++ Relative to the beginning of the file. +- Relative to the end of the file. +\fInone\fP Relative to the end of the file. +.TE +.LP +The origin for counting shall be 1; that is, \fB-c\fP +1 represents +the first byte of the file, \fB-c\fP -1 the last. +.TP 7 +\fB-f\fP +If the input file is a regular file or if the \fIfile\fP operand specifies +a FIFO, do not terminate after the last line of the +input file has been copied, but read and copy further bytes from the +input file when they become available. If no \fIfile\fP +operand is specified and standard input is a pipe, the \fB-f\fP option +shall be ignored. If the input file is not a FIFO, pipe, or +regular file, it is unspecified whether or not the \fB-f\fP option +shall be ignored. +.TP 7 +\fB-n\ \fP \fInumber\fP +This option shall be equivalent to \fB-c\fP \fInumber\fP, except the +starting location in the file shall be measured in lines +instead of bytes. The origin for counting shall be 1; that is, \fB-n\fP ++1 represents the first line of the file, \fB-n\fP -1 the +last. +.sp +.LP +If neither \fB-c\fP nor \fB-n\fP is specified, \fB-n\fP 10 shall be +assumed. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of an input file. If no \fIfile\fP operands are specified, +the standard input shall be used. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified. See the INPUT FILES section. +.SH INPUT FILES +.LP +If the \fB-c\fP option is specified, the input file can contain arbitrary +data; otherwise, the input file shall be a text +file. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fItail\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The designated portion of the input file shall be written to standard +output. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fB-c\fP option should be used with caution when the input is +a text file containing multi-byte characters; it may produce +output that does not start on a character boundary. +.LP +Although the input file to \fItail\fP can be any type, the results +might not be what would be expected on some character +special device files or on file types not described by the System +Interfaces volume of IEEE\ Std\ 1003.1-2001. Since this +volume of IEEE\ Std\ 1003.1-2001 does not specify the block size used +when doing input, \fItail\fP need not read all of +the data from devices that only perform block transfers. +.SH EXAMPLES +.LP +The \fB-f\fP option can be used to monitor the growth of a file that +is being written by some other process. For example, the +command: +.sp +.RS +.nf + +\fBtail -f fred +\fP +.fi +.RE +.LP +prints the last ten lines of the file \fBfred\fP, followed by any +lines that are appended to \fBfred\fP between the time +\fItail\fP is initiated and killed. As another example, the command: +.sp +.RS +.nf + +\fBtail -f -c 15 fred +\fP +.fi +.RE +.LP +prints the last 15 bytes of the file \fBfred\fP, followed by any bytes +that are appended to \fBfred\fP between the time +\fItail\fP is initiated and killed. +.SH RATIONALE +.LP +This version of \fItail\fP was created to allow conformance to the +Utility Syntax Guidelines. The historical \fB-b\fP option +was omitted because of the general non-portability of block-sized +units of text. The \fB-c\fP option historically meant +"characters", but this volume of IEEE\ Std\ 1003.1-2001 indicates +that it means "bytes". This was selected to allow +reasonable implementations when multi-byte characters are possible; +it was not named \fB-b\fP to avoid confusion with the +historical \fB-b\fP. +.LP +The origin of counting both lines and bytes is 1, matching all widespread +historical implementations. +.LP +The restriction on the internal buffer is a compromise between the +historical System V implementation of 4096 bytes and the BSD +32768 bytes. +.LP +The \fB-f\fP option has been implemented as a loop that sleeps for +1 second and copies any bytes that are available. This is +sufficient, but if more efficient methods of determining when new +data are available are developed, implementations are encouraged +to use them. +.LP +Historical documentation indicates that \fItail\fP ignores the \fB-f\fP +option if the input file is a pipe (pipe and FIFO on +systems that support FIFOs). On BSD-based systems, this has been true; +on System V-based systems, this was true when input was +taken from standard input, but it did not ignore the \fB-f\fP flag +if a FIFO was named as the \fIfile\fP operand. Since the +\fB-f\fP option is not useful on pipes and all historical implementations +ignore \fB-f\fP if no \fIfile\fP operand is specified +and standard input is a pipe, this volume of IEEE\ Std\ 1003.1-2001 +requires this behavior. However, since the \fB-f\fP +option is useful on a FIFO, this volume of IEEE\ Std\ 1003.1-2001 +also requires that if standard input is a FIFO or a FIFO +is named, the \fB-f\fP option shall not be ignored. Although historical +behavior does not ignore the \fB-f\fP option for other +file types, this is unspecified so that implementations are allowed +to ignore the \fB-f\fP option if it is known that the file +cannot be extended. +.LP +This was changed to the current form based on comments noting that +\fB-c\fP was almost never used without specifying a number +and that there was no need to specify \fB-l\fP if \fB-n\fP \fInumber\fP +was given. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIhead\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/talk.1p b/man1p/talk.1p new file mode 100644 index 000000000..b6a101a4d --- /dev/null +++ b/man1p/talk.1p @@ -0,0 +1,278 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TALK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" talk +.SH NAME +talk \- talk to another user +.SH SYNOPSIS +.LP +\fBtalk\fP \fIaddress\fP \fB[\fP\fIterminal\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fItalk\fP utility is a two-way, screen-oriented communication +program. +.LP +When first invoked, \fItalk\fP shall send a message similar to: +.sp +.RS +.nf + +\fBMessage from <\fP\fIunspecified string\fP\fB> +talk: connection requested by\fP \fIyour_address\fP\fBtalk: respond with: talk\fP \fIyour_address\fP +.fi +.RE +.LP +to the specified \fIaddress\fP. At this point, the recipient of the +message can reply by typing: +.sp +.RS +.nf + +\fBtalk\fP \fIyour_address\fP +.fi +.RE +.LP +Once communication is established, the two parties can type simultaneously, +with their output displayed in separate regions of +the screen. Characters shall be processed as follows: +.IP " *" 3 +Typing the alert character shall alert the recipient's terminal. +.LP +.IP " *" 3 +Typing -L shall cause the sender's screen regions to be refreshed. +.LP +.IP " *" 3 +Typing the erase and kill characters shall affect the sender's terminal +in the manner described by the \fBtermios\fP interface +in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter +11, General +Terminal Interface. +.LP +.IP " *" 3 +Typing the interrupt or end-of-file characters shall terminate the +local \fItalk\fP utility. Once the \fItalk\fP session has +been terminated on one side, the other side of the \fItalk\fP session +shall be notified that the \fItalk\fP session has been +terminated and shall be able to do nothing except exit. +.LP +.IP " *" 3 +Typing characters from \fILC_CTYPE\fP classifications \fBprint\fP +or \fBspace\fP shall cause those characters to be sent to +the recipient's terminal. +.LP +.IP " *" 3 +When and only when the \fIstty\fP \fBiexten\fP local mode is enabled, +the existence and +processing of additional special control characters and multi-byte +or single-byte functions shall be implementation-defined. +.LP +.IP " *" 3 +Typing other non-printable characters shall cause implementation-defined +sequences of printable characters to be sent to the +recipient's terminal. +.LP +.LP +Permission to be a recipient of a \fItalk\fP message can be denied +or granted by use of the \fImesg\fP utility. However, a user's privilege +may further constrain the domain of accessibility of +other users' terminals. The \fItalk\fP utility shall fail when the +user lacks the appropriate privileges to perform the requested +action. +.LP +Certain block-mode terminals do not have all the capabilities necessary +to support the simultaneous exchange of messages +required for \fItalk\fP. When this type of exchange cannot be supported +on such terminals, the implementation may support an +exchange with reduced levels of simultaneous interaction or it may +report an error describing the terminal-related deficiency. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIaddress\fP +The recipient of the \fItalk\fP session. One form of \fIaddress\fP +is the <\fIuser\ name\fP>, as returned by the +\fIwho\fP utility. Other address formats and how they are handled +are unspecified. +.TP 7 +\fIterminal\fP +If the recipient is logged in more than once, the \fIterminal\fP argument +can be used to indicate the appropriate terminal +name. If \fIterminal\fP is not specified, the \fItalk\fP message shall +be displayed on one or more accessible terminals in use by +the recipient. The format of \fIterminal\fP shall be the same as that +returned by the \fIwho\fP utility. +.sp +.SH STDIN +.LP +Characters read from standard input shall be copied to the recipient's +terminal in an unspecified manner. If standard input is +not a terminal, talk shall write a diagnostic message and exit with +a non-zero status. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fItalk\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). If +the recipient's locale does not use an \fILC_CTYPE\fP +equivalent to the sender's, the results are undefined. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITERM\fP +Determine the name of the invoker's terminal type. If this variable +is unset or null, an unspecified default terminal type +shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +When the \fItalk\fP utility receives a SIGINT signal, the utility +shall terminate and exit with a zero status. It shall take +the standard action for all other signals. +.SH STDOUT +.LP +If standard output is a terminal, characters copied from the recipient's +standard input may be written to standard output. +Standard output also may be used for diagnostic messages. If standard +output is not a terminal, \fItalk\fP shall exit with a +non-zero status. +.SH STDERR +.LP +None. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred or \fItalk\fP was invoked on a terminal incapable +of supporting it. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Because the handling of non-printable, non- s is tied to the +\fIstty\fP +description of \fBiexten\fP, implementation extensions within the +terminal driver can be accessed. For example, some +implementations provide line editing functions with certain control +character sequences. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIwrite\fP utility was included in this volume of IEEE\ Std\ 1003.1-2001 +since it can be implemented on all terminal types. The \fItalk\fP +utility, which cannot be implemented on certain terminals, was +considered to be a "better" communications interface. Both of these +programs are in widespread use on historical implementations. +Therefore, both utilities have been specified. +.LP +All references to networking abilities (\fItalk\fPing to a user on +another system) were removed as being outside the scope of +this volume of IEEE\ Std\ 1003.1-2001. +.LP +Historical BSD and System V versions of \fItalk\fP terminate both +of the conversations when either user breaks out of the +session. This can lead to adverse consequences if a user unwittingly +continues to enter text that is interpreted by the shell when +the other terminates the session. Therefore, the version of \fItalk\fP +specified by this volume of IEEE\ Std\ 1003.1-2001 +requires both users to terminate their end of the session explicitly. +.LP +Only messages sent to the terminal of the invoking user can be internationalized +in any way: +.IP " *" 3 +The original "Message from <\fIunspecified string\fP> ..." message +sent to the terminal of the recipient cannot be +internationalized because the environment of the recipient is as yet +inaccessible to the \fItalk\fP utility. The environment of +the invoking party is irrelevant. +.LP +.IP " *" 3 +Subsequent communication between the two parties cannot be internationalized +because the two parties may specify different +languages in their environment (and non-portable characters cannot +be mapped from one language to another). +.LP +.IP " *" 3 +Neither party can be required to communicate in a language other than +C and/or the one specified by their environment because +unavailable terminal hardware support (for example, fonts) may be +required. +.LP +.LP +The text in the STDOUT section reflects the usage of the verb "display" +in this section; some \fItalk\fP implementations +actually use standard output to write to the terminal, but this volume +of IEEE\ Std\ 1003.1-2001 does not require that to +be the case. +.LP +The format of the terminal name is unspecified, but the descriptions +of \fIps\fP, +\fItalk\fP, \fIwho\fP, and \fIwrite\fP require that +they all use or accept the same format. +.LP +The handling of non-printable characters is partially implementation-defined +because the details of mapping them to printable +sequences is not needed by the user. Historical implementations, for +security reasons, disallow the transmission of non-printable +characters that may send commands to the other terminal. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImesg\fP , \fIstty\fP , \fIwho\fP , \fIwrite\fP , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/tee.1p b/man1p/tee.1p new file mode 100644 index 000000000..c74d80a8e --- /dev/null +++ b/man1p/tee.1p @@ -0,0 +1,174 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TEE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tee +.SH NAME +tee \- duplicate standard input +.SH SYNOPSIS +.LP +\fBtee\fP \fB[\fP\fB-ai\fP\fB][\fP\fIfile\fP\fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fItee\fP utility shall copy standard input to standard output, +making a copy in zero or more files. The \fItee\fP utility +shall not buffer output. +.LP +If the \fB-a\fP option is not specified, output files shall be written +(see \fIFile +Read, Write, and Creation\fP . +.SH OPTIONS +.LP +The \fItee\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-a\fP +Append the output to the files. +.TP 7 +\fB-i\fP +Ignore the SIGINT signal. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile\fP +A pathname of an output file. Processing of at least 13 \fIfile\fP +operands shall be supported. +.sp +.SH STDIN +.LP +The standard input can be of any type. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fItee\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default, except that if the \fB-i\fP option was specified, SIGINT +shall be ignored. +.SH STDOUT +.LP +The standard output shall be a copy of the standard input. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +If any \fIfile\fP operands are specified, the standard input shall +be copied to each named file. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The standard input was successfully copied to all output files. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If a write to any successfully opened \fIfile\fP operand fails, writes +to other successfully opened \fIfile\fP operands and +standard output shall continue, but the exit status shall be non-zero. +Otherwise, the default actions specified in \fIUtility Description +Defaults\fP apply. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fItee\fP utility is usually used in a pipeline, to make a copy +of the output of some utility. +.LP +The \fIfile\fP operand is technically optional, but \fItee\fP is no +more useful than \fIcat\fP when none is specified. +.SH EXAMPLES +.LP +Save an unsorted intermediate form of the data in a pipeline: +.sp +.RS +.nf + +\fB\&... | tee unsorted | sort > sorted +\fP +.fi +.RE +.SH RATIONALE +.LP +The buffering requirement means that \fItee\fP is not allowed to use +ISO\ C standard fully buffered or line-buffered +writes. It does not mean that \fItee\fP has to do 1-byte reads followed +by 1-byte writes. +.LP +It should be noted that early versions of BSD ignore any invalid options +and accept a single \fB'-'\fP as an alternative to +\fB-i\fP. They also print a message if unable to open a file: +.sp +.RS +.nf + +\fB"tee: cannot access %s\\n", <\fP\fIpathname\fP\fB> +\fP +.fi +.RE +.LP +Historical implementations ignore write errors. This is explicitly +not permitted by this volume of +IEEE\ Std\ 1003.1-2001. +.LP +Some historical implementations use O_APPEND when providing append +mode; others use the \fIlseek\fP() function to seek to the end-of-file +after opening the file without O_APPEND. This +volume of IEEE\ Std\ 1003.1-2001 requires functionality equivalent +to using O_APPEND; see \fIFile Read, Write, and Creation\fP . +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIIntroduction\fP , \fIcat\fP , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIlseek\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/test.1p b/man1p/test.1p new file mode 100644 index 000000000..78b92722a --- /dev/null +++ b/man1p/test.1p @@ -0,0 +1,757 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TEST" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" test +.SH NAME +test \- evaluate expression +.SH SYNOPSIS +.LP +\fBtest\fP \fB[\fP\fIexpression\fP\fB]\fP\fB +.br +.sp +[\fP \fB[\fP\fIexpression\fP\fB]\fP \fB] +.br +\fP +.SH DESCRIPTION +.LP +The \fItest\fP utility shall evaluate the \fIexpression\fP and indicate +the result of the evaluation by its exit status. An +exit status of zero indicates that the expression evaluated as true +and an exit status of 1 indicates that the expression evaluated +as false. +.LP +In the second form of the utility, which uses \fB"[]"\fP rather than +\fItest\fP, the application shall ensure that the +square brackets are separate arguments. +.SH OPTIONS +.LP +The \fItest\fP utility shall not recognize the \fB"--"\fP argument +in the manner specified by guideline 10 in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility +Syntax +Guidelines. +.LP +No options shall be supported. +.SH OPERANDS +.LP +The application shall ensure that all operators and elements of primaries +are presented as separate arguments to the \fItest\fP +utility. +.LP +The following primaries can be used to construct \fIexpression\fP: +.TP 7 +\fB-b\ \fP \fIfile\fP +True if \fIfile\fP exists and is a block special file. +.TP 7 +\fB-c\ \fP \fIfile\fP +True if \fIfile\fP exists and is a character special file. +.TP 7 +\fB-d\ \fP \fIfile\fP +True if \fIfile\fP exists and is a directory. +.TP 7 +\fB-e\ \fP \fIfile\fP +True if \fIfile\fP exists. +.TP 7 +\fB-f\ \fP \fIfile\fP +True if \fIfile\fP exists and is a regular file. +.TP 7 +\fB-g\ \fP \fIfile\fP +True if \fIfile\fP exists and its set-group-ID flag is set. +.TP 7 +\fB-h\ \fP \fIfile\fP +True if \fIfile\fP exists and is a symbolic link. +.TP 7 +\fB-L\ \fP \fIfile\fP +True if \fIfile\fP exists and is a symbolic link. +.TP 7 +\fB-n\ \fP \fIstring\fP +True if the length of \fIstring\fP is non-zero. +.TP 7 +\fB-p\ \fP \fIfile\fP +True if \fIfile\fP is a FIFO. +.TP 7 +\fB-r\ \fP \fIfile\fP +True if \fIfile\fP exists and is readable. True shall indicate that +permission to read from \fIfile\fP will be granted, as +defined in \fIFile Read, Write, and Creation\fP . +.TP 7 +\fB-S\ \fP \fIfile\fP +True if \fIfile\fP exists and is a socket. +.TP 7 +\fB-s\ \fP \fIfile\fP +True if \fIfile\fP exists and has a size greater than zero. +.TP 7 +\fB-t\ \fP \fIfile_descriptor\fP +.sp +True if the file whose file descriptor number is \fIfile_descriptor\fP +is open and is associated with a terminal. +.TP 7 +\fB-u\ \fP \fIfile\fP +True if \fIfile\fP exists and its set-user-ID flag is set. +.TP 7 +\fB-w\ \fP \fIfile\fP +True if \fIfile\fP exists and is writable. True shall indicate that +permission to write from \fIfile\fP will be granted, as +defined in \fIFile Read, Write, and Creation\fP . +.TP 7 +\fB-x\ \fP \fIfile\fP +True if \fIfile\fP exists and is executable. True shall indicate that +permission to execute \fIfile\fP will be granted, as +defined in \fIFile Read, Write, and Creation\fP . If \fIfile\fP is +a directory, +true shall indicate that permission to search \fIfile\fP will be granted. +.TP 7 +\fB-z\ \fP \fIstring\fP +True if the length of string \fIstring\fP is zero. +.TP 7 +\fIstring\fP +True if the string \fIstring\fP is not the null string. +.TP 7 +\fIs1\fP\fB\ =\ \fP \fIs2\fP +True if the strings \fIs1\fP and \fIs2\fP are identical. +.TP 7 +\fIs1\fP\fB\ !=\ \fP \fIs2\fP +True if the strings \fIs1\fP and \fIs2\fP are not identical. +.TP 7 +\fIn1\fP\fB\ -eq\ \fP \fIn2\fP +True if the integers \fIn1\fP and \fIn2\fP are algebraically equal. +.TP 7 +\fIn1\fP\fB\ -ne\ \fP \fIn2\fP +True if the integers \fIn1\fP and \fIn2\fP are not algebraically equal. +.TP 7 +\fIn1\fP\fB\ -gt\ \fP \fIn2\fP +True if the integer \fIn1\fP is algebraically greater than the integer +\fIn2\fP. +.TP 7 +\fIn1\fP\fB\ -ge\ \fP \fIn2\fP +True if the integer \fIn1\fP is algebraically greater than or equal +to the integer \fIn2\fP. +.TP 7 +\fIn1\fP\fB\ -lt\ \fP \fIn2\fP +True if the integer \fIn1\fP is algebraically less than the integer +\fIn2\fP. +.TP 7 +\fIn1\fP\fB\ -le\ \fP \fIn2\fP +True if the integer \fIn1\fP is algebraically less than or equal to +the integer \fIn2\fP. +.TP 7 +\fIexpression1\fP\fB\ -a\ \fP \fIexpression2\fP +.sp +True if both \fIexpression1\fP and \fIexpression2\fP are true. The +\fB-a\fP binary primary is left associative. It has a higher +precedence than \fB-o\fP. +.TP 7 +\fIexpression1\fP\fB\ -o\ \fP \fIexpression2\fP +.sp +True if either \fIexpression1\fP or \fIexpression2\fP is true. The +\fB-o\fP binary primary is left associative. +.sp +.LP +With the exception of the \fB-h\fP \fIfile\fP and \fB-L\fP \fIfile\fP +primaries, if a \fIfile\fP argument is a symbolic +link, \fItest\fP shall evaluate the expression by resolving the symbolic +link and using the file referenced by the link. +.LP +These primaries can be combined with the following operators: +.TP 7 +\fB!\ \fP \fIexpression\fP +True if \fIexpression\fP is false. +.TP 7 +\fB(\ \fP \fIexpression\ \fP \fB)\fP +True if \fIexpression\fP is true. The parentheses can be used to alter +the normal precedence and associativity. +.sp +.LP +The primaries with two elements of the form: +.sp +.RS +.nf + +\fB-\fP\fIprimary_operator primary_operand\fP +.fi +.RE +.LP +are known as \fIunary primaries\fP. The primaries with three elements +in either of the two forms: +.sp +.RS +.nf + +\fIprimary_operand\fP \fB-\fP\fIprimary_operator primary_operand +.sp + +primary_operand primary_operator primary_operand\fP +.fi +.RE +.LP +are known as \fIbinary primaries\fP. Additional implementation-defined +operators and \fIprimary_operator\fPs may be provided +by implementations. They shall be of the form - \fIoperator\fP where +the first character of \fIoperator\fP is not a digit. +.LP +The algorithm for determining the precedence of the operators and +the return value that shall be generated is based on the +number of arguments presented to \fItest\fP. (However, when using +the \fB"[...]"\fP form, the right-bracket final argument +shall not be counted in this algorithm.) +.LP +In the following list, $1, $2, $3, and $4 represent the arguments +presented to \fItest\fP: +.TP 7 +0\ arguments: +Exit false (1). +.TP 7 +1\ argument: +Exit true (0) if $1 is not null; otherwise, exit false. +.TP 7 +2\ arguments: +.RS +.IP " *" 3 +If $1 is \fB'!'\fP , exit true if $2 is null, false if $2 is not null. +.LP +.IP " *" 3 +If $1 is a unary primary, exit true if the unary test is true, false +if the unary test is false. +.LP +.IP " *" 3 +Otherwise, produce unspecified results. +.LP +.RE +.TP 7 +3\ arguments: +.RS +.IP " *" 3 +If $2 is a binary primary, perform the binary test of $1 and $3. +.LP +.IP " *" 3 +If $1 is \fB'!'\fP , negate the two-argument test of $2 and $3. +.LP +.IP " *" 3 +If $1 is \fB'('\fP and $3 is \fB')'\fP , perform the unary test of +$2. +.LP +.IP " *" 3 +Otherwise, produce unspecified results. +.LP +.RE +.TP 7 +4\ arguments: +.RS +.IP " *" 3 +If $1 is \fB'!'\fP , negate the three-argument test of $2, $3, and +$4. +.LP +.IP " *" 3 +If $1 is \fB'('\fP and $4 is \fB')'\fP , perform the two-argument +test of $2 and $3. +.LP +.IP " *" 3 +Otherwise, the results are unspecified. +.LP +.RE +.TP 7 +>4\ arguments: +The results are unspecified. +.LP +On XSI-conformant systems, combinations of primaries and operators +shall be evaluated using the precedence and associativity rules +described previously. In addition, the string comparison binary primaries +\fB'='\fP and \fB"!="\fP shall have a higher +precedence than any unary primary. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fItest\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +\fIexpression\fP evaluated to true. +.TP 7 +\ 1 +\fIexpression\fP evaluated to false or \fIexpression\fP was missing. +.TP 7 +>1 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Scripts should be careful when dealing with user-supplied input that +could be confused with primaries and operators. Unless the +application writer knows all the cases that produce input to the script, +invocations like: +.sp +.RS +.nf + +\fBtest "$1" -a "$2" +\fP +.fi +.RE +.LP +should be written as: +.sp +.RS +.nf + +\fBtest "$1" && test "$2" +\fP +.fi +.RE +.LP +to avoid problems if a user supplied values such as $1 set to \fB'!'\fP +and $2 set to the null string. That is, in cases +where maximal portability is of concern, replace: +.sp +.RS +.nf + +\fBtest expr1 -a expr2 +\fP +.fi +.RE +.LP +with: +.sp +.RS +.nf + +\fBtest expr1 && test expr2 +\fP +.fi +.RE +.LP +and replace: +.sp +.RS +.nf + +\fBtest expr1 -o expr2 +\fP +.fi +.RE +.LP +with: +.sp +.RS +.nf + +\fBtest expr1 || test expr2 +\fP +.fi +.RE +.LP +but note that, in \fItest\fP, \fB-a\fP has higher precedence than +\fB-o\fP while \fB"&&"\fP and \fB"||"\fP have +equal precedence in the shell. +.LP +Parentheses or braces can be used in the shell command language to +effect grouping. +.LP +Parentheses must be escaped when using \fIsh\fP; for example: +.sp +.RS +.nf + +\fBtest \\( expr1 -a expr2 \\) -o expr3 +\fP +.fi +.RE +.LP +This command is not always portable outside XSI-conformant systems. +The following form can be used instead: +.sp +.RS +.nf + +\fB( test expr1 && test expr2 ) || test expr3 +\fP +.fi +.RE +.LP +The two commands: +.sp +.RS +.nf + +\fBtest "$1" +test ! "$1" +\fP +.fi +.RE +.LP +could not be used reliably on some historical systems. Unexpected +results would occur if such a \fIstring\fP expression were +used and $1 expanded to \fB'!'\fP , \fB'('\fP , or a known unary primary. +Better constructs are: +.sp +.RS +.nf + +\fBtest -n "$1" +test -z "$1" +\fP +.fi +.RE +respectively. +.LP +Historical systems have also been unreliable given the common construct: +.sp +.RS +.nf + +\fBtest "$response" = "expected string" +\fP +.fi +.RE +.LP +One of the following is a more reliable form: +.sp +.RS +.nf + +\fBtest "X$response" = "Xexpected string" +test "expected string" = "$response" +\fP +.fi +.RE +.LP +Note that the second form assumes that \fIexpected string\fP could +not be confused with any unary primary. If \fIexpected +string\fP starts with \fB'-'\fP , \fB'('\fP , \fB'!'\fP , or even +\fB'='\fP , the first form should be used instead. +Using the preceding rules without the XSI marked extensions, any of +the three comparison forms is reliable, given any input. +(However, note that the strings are quoted in all cases.) +.LP +Because the string comparison binary primaries, \fB'='\fP and \fB"!="\fP +, have a higher precedence than any unary primary +in the greater than 4 argument case, unexpected results can occur +if arguments are not properly prepared. For example, in: +.sp +.RS +.nf + +\fBtest -d $1 -o -d $2 +\fP +.fi +.RE +.LP +If $1 evaluates to a possible directory name of \fB'='\fP , the first +three arguments are considered a string comparison, +which shall cause a syntax error when the second \fB-d\fP is encountered. +One of the following forms prevents this; the second is +preferred: +.sp +.RS +.nf + +\fBtest \\( -d "$1" \\) -o \\( -d "$2" \\) +test -d "$1" || test -d "$2" +\fP +.fi +.RE +.LP +Also in the greater than 4 argument case: +.sp +.RS +.nf + +\fBtest "$1" = "bat" -a "$2" = "ball" +\fP +.fi +.RE +.LP +syntax errors occur if $1 evaluates to \fB'('\fP or \fB'!'\fP . One +of the following forms prevents this; the third is +preferred: +.sp +.RS +.nf + +\fBtest "X$1" = "Xbat" -a "X$2" = "Xball" +test "$1" = "bat" && test "$2" = "ball" +test "X$1" = "Xbat" && test "X$2" = "Xball" +\fP +.fi +.RE +.SH EXAMPLES +.IP " 1." 4 +Exit if there are not two or three arguments (two variations): +.sp +.RS +.nf + +\fBif [ $# -ne 2 -a $# -ne 3 ]; then exit 1; fi +if [ $# -lt 2 -o $# -gt 3 ]; then exit 1; fi +\fP +.fi +.RE +.LP +.IP " 2." 4 +Perform a \fImkdir\fP if a directory does not exist: +.sp +.RS +.nf + +\fBtest ! -d tempdir && mkdir tempdir +\fP +.fi +.RE +.LP +.IP " 3." 4 +Wait for a file to become non-readable: +.sp +.RS +.nf + +\fBwhile test -r thefile +do + sleep 30 +done +echo '"thefile" is no longer readable' +\fP +.fi +.RE +.LP +.IP " 4." 4 +Perform a command if the argument is one of three strings (two variations): +.sp +.RS +.nf + +\fBif [ "$1" = "pear" ] || [ "$1" = "grape" ] || [ "$1" = "apple" ] +then + \fP \fIcommand\fP\fB +fi +.sp + +case "$1" in + pear|grape|apple)\fP \fIcommand\fP \fB;; +esac +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +The KornShell-derived conditional command (double bracket \fB[[]]\fP) +was removed from the shell command language description +in an early proposal. Objections were raised that the real problem +is misuse of the \fItest\fP command ( \fB[\fP), and putting it +into the shell is the wrong way to fix the problem. Instead, proper +documentation and a new shell reserved word ( \fB!\fP) are +sufficient. +.LP +Tests that require multiple \fItest\fP operations can be done at the +shell level using individual invocations of the +\fItest\fP command and shell logicals, rather than using the error-prone +\fB-o\fP flag of \fItest\fP. +.LP +XSI-conformant systems support more than four arguments. +.LP +XSI-conformant systems support the combining of primaries with the +following constructs: +.TP 7 +\fIexpression1\fP \fB-a\fP \fIexpression2\fP +.sp +True if both \fIexpression1\fP and \fIexpression2\fP are true. +.TP 7 +\fIexpression1\fP \fB-o\fP \fIexpression2\fP +.sp +True if at least one of \fIexpression1\fP and \fIexpression2\fP are +true. +.TP 7 +\fB(\fP \fIexpression\fP \fB)\fP +.sp +True if \fIexpression\fP is true. +.sp +.LP +In evaluating these more complex combined expressions, the following +precedence rules are used: +.IP " *" 3 +The unary primaries have higher precedence than the algebraic binary +primaries. +.LP +.IP " *" 3 +The unary primaries have lower precedence than the string binary primaries. +.LP +.IP " *" 3 +The unary and binary primaries have higher precedence than the unary +\fIstring\fP primary. +.LP +.IP " *" 3 +The \fB!\fP operator has higher precedence than the \fB-a\fP operator, +and the \fB-a\fP operator has higher precedence than +the \fB-o\fP operator. +.LP +.IP " *" 3 +The \fB-a\fP and \fB-o\fP operators are left associative. +.LP +.IP " *" 3 +The parentheses can be used to alter the normal precedence and associativity. +.LP +.LP +The BSD and System V versions of \fB-f\fP are not the same. The BSD +definition was: +.TP 7 +\fB-f\ \fP \fIfile\fP +True if \fIfile\fP exists and is not a directory. +.sp +.LP +The SVID version (true if the file exists and is a regular file) was +chosen for this volume of IEEE\ Std\ 1003.1-2001 +because its use is consistent with the \fB-b\fP, \fB-c\fP, \fB-d\fP, +and \fB-p\fP operands ( \fIfile\fP exists and is a +specific file type). +.LP +The \fB-e\fP primary, possessing similar functionality to that provided +by the C shell, was added because it provides the only +way for a shell script to find out if a file exists without trying +to open the file. Since implementations are allowed to add +additional file types, a portable script cannot use: +.sp +.RS +.nf + +\fBtest -b foo -o -c foo -o -d foo -o -f foo -o -p foo +\fP +.fi +.RE +.LP +to find out if \fBfoo\fP is an existing file. On historical BSD systems, +the existence of a file could be determined by: +.sp +.RS +.nf + +\fBtest -f foo -o -d foo +\fP +.fi +.RE +.LP +but there was no easy way to determine that an existing file was a +regular file. An early proposal used the KornShell \fB-a\fP +primary (with the same meaning), but this was changed to \fB-e\fP +because there were concerns about the high probability of humans +confusing the \fB-a\fP primary with the \fB-a\fP binary operator. +.LP +The following options were not included in this volume of IEEE\ Std\ 1003.1-2001, +although they are provided by some +implementations. These operands should not be used by new implementations +for other purposes: +.TP 7 +\fB-k\ \fP \fIfile\fP +True if \fIfile\fP exists and its sticky bit is set. +.TP 7 +\fB-C\ \fP \fIfile\fP +True if \fIfile\fP is a contiguous file. +.TP 7 +\fB-V\ \fP \fIfile\fP +True if \fIfile\fP is a version file. +.sp +.LP +The following option was not included because it was undocumented +in most implementations, has been removed from some +implementations (including System V), and the functionality is provided +by the shell (see \fIParameter Expansion\fP . +.TP 7 +\fB-l\ \fP \fIstring\fP +The length of the string \fIstring\fP. +.sp +.LP +The \fB-b\fP, \fB-c\fP, \fB-g\fP, \fB-p\fP, \fB-u\fP, and \fB-x\fP +operands are derived from the SVID; historical BSD does +not provide them. The \fB-k\fP operand is derived from System V; historical +BSD does not provide it. +.LP +On historical BSD systems, \fItest\fP \fB-w\fP \fIdirectory\fP always +returned false because \fItest\fP tried to open the +directory for writing, which always fails. +.LP +Some additional primaries newly invented or from the KornShell appeared +in an early proposal as part of the conditional command +( \fB[[]]\fP): \fIs1\fP \fB>\fP \fIs2\fP, \fIs1\fP \fB<\fP \fIs2\fP, +\fIstr\fP \fB=\fP \fIpattern\fP, \fIstr\fP +\fB!=\fP \fIpattern\fP, \fIf1\fP \fB-nt\fP \fIf2\fP, \fIf1\fP \fB-ot\fP +\fIf2\fP, and \fIf1\fP \fB-ef\fP \fIf2\fP. They +were not carried forward into the \fItest\fP utility when the conditional +command was removed from the shell because they have not +been included in the \fItest\fP utility built into historical implementations +of the \fIsh\fP +utility. +.LP +The \fB-t\fP \fIfile_descriptor\fP primary is shown with a mandatory +argument because the grammar is ambiguous if it can be +omitted. Historical implementations have allowed it to be omitted, +providing a default of 1. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIFile Read, Write, and Creation\fP , \fIfind\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/time.1p b/man1p/time.1p new file mode 100644 index 000000000..4804461e5 --- /dev/null +++ b/man1p/time.1p @@ -0,0 +1,278 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" time +.SH NAME +time \- time a simple command +.SH SYNOPSIS +.LP +\fBtime\fP \fB[\fP\fB-p\fP\fB]\fP \fIutility\fP +\fB[\fP\fIargument\fP\fB...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fItime\fP utility shall invoke the utility named by the \fIutility\fP +operand with arguments supplied as the +\fIargument\fP operands and write a message to standard error that +lists timing statistics for the utility. The message shall +include the following information: +.IP " *" 3 +The elapsed (real) time between invocation of \fIutility\fP and its +termination. +.LP +.IP " *" 3 +The User CPU time, equivalent to the sum of the \fItms_utime\fP and +\fItms_cutime\fP fields returned by the \fItimes\fP() function defined +in the System Interfaces volume of IEEE\ Std\ 1003.1-2001 for +the process in which \fIutility\fP is executed. +.LP +.IP " *" 3 +The System CPU time, equivalent to the sum of the \fItms_stime\fP +and \fItms_cstime\fP fields returned by the \fItimes\fP() function +for the process in which \fIutility\fP is executed. +.LP +.LP +The precision of the timing shall be no less than the granularity +defined for the size of the clock tick unit on the system, but +the results shall be reported in terms of standard time units (for +example, 0.02 seconds, 00:00:00.02, 1m33.75s, 365.21 seconds), +not numbers of clock ticks. +.LP +When \fItime\fP is used as part of a pipeline, the times reported +are unspecified, except when it is the sole command within a +grouping command (see \fIGrouping Commands\fP ) in that pipeline. +For example, the +commands on the left are unspecified; those on the right report on +utilities \fBa\fP and \fBc\fP, respectively: +.sp +.RS +.nf + +\fBtime a | b | c { time a } | b | c +a | b | time c a | b | (time c) +\fP +.fi +.RE +.SH OPTIONS +.LP +The \fItime\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-p\fP +Write the timing output to standard error in the format shown in the +STDERR section. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIutility\fP +The name of a utility that is to be invoked. If the \fIutility\fP +operand names any of the special built-in utilities in \fISpecial +Built-In Utilities\fP , the results are undefined. +.TP 7 +\fIargument\fP +Any string to be supplied as an argument when invoking the utility +named by the \fIutility\fP operand. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fItime\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic and informative messages written to +standard error. +.TP 7 +\fILC_NUMERIC\fP +.sp +Determine the locale for numeric formatting. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPATH\fP +Determine the search path that shall be used to locate the utility +to be invoked; see the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used to write the timing statistics. If +\fB-p\fP is specified, the following format shall be used +in the POSIX locale: +.sp +.RS +.nf + +\fB"real %f\\nuser %f\\nsys %f\\n", <\fP\fIreal seconds\fP\fB>, <\fP\fIuser seconds\fP\fB>, + <\fP\fIsystem seconds\fP\fB> +\fP +.fi +.RE +.LP +where each floating-point number shall be expressed in seconds. The +precision used may be less than the default six digits of +\fB%f\fP , but shall be sufficiently precise to accommodate the size +of the clock tick on the system (for example, if there were +60 clock ticks per second, at least two digits shall follow the radix +character). The number of digits following the radix +character shall be no less than one, even if this always results in +a trailing zero. The implementation may append white space and +additional information following the format shown here. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +If the \fIutility\fP utility is invoked, the exit status of \fItime\fP +shall be the exit status of \fIutility\fP; otherwise, +the \fItime\fP utility shall exit with one of the following values: +.TP 7 +1-125 +An error occurred in the \fItime\fP utility. +.TP 7 +\ \ 126 +The utility specified by \fIutility\fP was found but could not be +invoked. +.TP 7 +\ \ 127 +The utility specified by \fIutility\fP could not be found. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fIcommand\fP, \fIenv\fP, \fInice\fP, \fInohup\fP, \fItime\fP, +and \fIxargs\fP utilities have been specified to use exit code 127 +if an error occurs so that +applications can distinguish "failure to find a utility" from "invoked +utility exited with an error indication". The value 127 +was chosen because it is not commonly used for other meanings; most +utilities use small values for "normal error conditions" and +the values above 128 can be confused with termination due to receipt +of a signal. The value 126 was chosen in a similar manner to +indicate that the utility could be found, but not invoked. Some scripts +produce meaningful error messages differentiating the 126 +and 127 cases. The distinction between exit codes 126 and 127 is based +on KornShell practice that uses 127 when all attempts to +\fIexec\fP the utility fail with [ENOENT], and uses 126 when any attempt +to \fIexec\fP the utility fails for any other +reason. +.SH EXAMPLES +.LP +It is frequently desirable to apply \fItime\fP to pipelines or lists +of commands. This can be done by placing pipelines and +command lists in a single file; this file can then be invoked as a +utility, and the \fItime\fP applies to everything in the +file. +.LP +Alternatively, the following command can be used to apply \fItime\fP +to a complex command: +.sp +.RS +.nf + +\fBtime sh -c '\fP\fIcomplex-command-line\fP\fB' +\fP +.fi +.RE +.SH RATIONALE +.LP +When the \fItime\fP utility was originally proposed to be included +in the ISO\ POSIX-2:1993 standard, questions were raised +about its suitability for inclusion on the grounds that it was not +useful for conforming applications, specifically: +.IP " *" 3 +The underlying CPU definitions from the System Interfaces volume of +IEEE\ Std\ 1003.1-2001 are vague, so the numeric +output could not be compared accurately between systems or even between +invocations. +.LP +.IP " *" 3 +The creation of portable benchmark programs was outside the scope +this volume of IEEE\ Std\ 1003.1-2001. +.LP +.LP +However, \fItime\fP does fit in the scope of user portability. Human +judgement can be applied to the analysis of the output, +and it could be very useful in hands-on debugging of applications +or in providing subjective measures of system performance. Hence +it has been included in this volume of IEEE\ Std\ 1003.1-2001. +.LP +The default output format has been left unspecified because historical +implementations differ greatly in their style of +depicting this numeric output. The \fB-p\fP option was invented to +provide scripts with a common means of obtaining this +information. +.LP +In the KornShell, \fItime\fP is a shell reserved word that can be +used to time an entire pipeline, rather than just a simple +command. The POSIX definition has been worded to allow this implementation. +Consideration was given to invalidating this approach +because of the historical model from the C shell and System V shell. +However, since the System V \fItime\fP utility historically +has not produced accurate results in pipeline timing (because the +constituent processes are not all owned by the same parent +process, as allowed by POSIX), it did not seem worthwhile to break +historical KornShell usage. +.LP +The term \fIutility\fP is used, rather than \fIcommand\fP, to highlight +the fact that shell compound commands, pipelines, +special built-ins, and so on, cannot be used directly. However, \fIutility\fP +includes user application programs and shell +scripts, not just the standard utilities. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP , \fIsh\fP , the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, \fItimes\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/times.1p b/man1p/times.1p new file mode 100644 index 000000000..f98ab7b55 --- /dev/null +++ b/man1p/times.1p @@ -0,0 +1,102 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TIMES" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" times +.SH NAME +times \- write process times +.SH SYNOPSIS +.LP +\fBtimes\fP +.SH DESCRIPTION +.LP +The \fItimes\fP utility shall write the accumulated user and system +times for the shell and for all of its child processes, in +the following POSIX locale format: +.sp +.RS +.nf + +\fB"%dm%fs %dm%fs\\n%dm%fs %dm%fs\\n", <\fP\fIshell user minutes\fP\fB>, + <\fP\fIshell user seconds\fP\fB>, <\fP\fIshell system minutes\fP\fB>, + <\fP\fIshell system seconds\fP\fB>, <\fP\fIchildren user minutes\fP\fB>, + <\fP\fIchildren user seconds\fP\fB>, <\fP\fIchildren system minutes\fP\fB>, + <\fP\fIchildren system seconds\fP\fB> +\fP +.fi +.RE +.LP +The four pairs of times shall correspond to the members of the \fI\fP +\fBtms\fP structure (defined in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 13, Headers) as returned by \fItimes\fP(): +\fItms_utime\fP, \fItms_stime\fP, \fItms_cutime\fP, and \fItms_cstime\fP, +respectively. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +None. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +None. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +See the DESCRIPTION. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +Zero. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.sp +.RS +.nf + +\fB$\fP \fBtimes +\fP\fB0m0.43s 0m1.11s +8m44.18s 1m43.23s\fP +.fi +.RE +.SH RATIONALE +.LP +The \fItimes\fP special built-in from the Single UNIX Specification +is now required for all conforming shells. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISpecial Built-In Utilities\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/touch.1p b/man1p/touch.1p new file mode 100644 index 000000000..5c1c65a30 --- /dev/null +++ b/man1p/touch.1p @@ -0,0 +1,344 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TOUCH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" touch +.SH NAME +touch \- change file access and modification times +.SH SYNOPSIS +.LP +\fBtouch\fP \fB[\fP\fB-acm\fP\fB][\fP \fB-r\fP \fIref_file\fP\fB| +-t\fP \fItime\fP\fB]\fP +\fIfile\fP\fB...\fP +.SH DESCRIPTION +.LP +The \fItouch\fP utility shall change the modification times, access +times, or both of files. The modification time shall be +equivalent to the value of the \fIst_mtime\fP member of the \fBstat\fP +structure for a file, as described in the System +Interfaces volume of IEEE\ Std\ 1003.1-2001; the access time shall +be equivalent to the value of \fIst_atime\fP. +.LP +The time used can be specified by the \fB-t\fP \fItime\fP option-argument, +the corresponding time fields of the file +referenced by the \fB-r\fP \fIref_file\fP option-argument, or the +\fIdate_time\fP operand, as specified in the following +sections. If none of these are specified, \fItouch\fP shall use the +current time (the value returned by the equivalent of the \fItime\fP() +function defined in the System Interfaces volume of +IEEE\ Std\ 1003.1-2001). +.LP +For each \fIfile\fP operand, \fItouch\fP shall perform actions equivalent +to the following functions defined in the System +Interfaces volume of IEEE\ Std\ 1003.1-2001: +.IP " 1." 4 +If \fIfile\fP does not exist, a \fIcreat\fP() function call is made +with the \fIfile\fP +operand used as the \fIpath\fP argument and the value of the bitwise-inclusive +OR of S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, +and S_IWOTH used as the \fImode\fP argument. +.LP +.IP " 2." 4 +The \fIutime\fP() function is called with the following arguments: +.RS +.IP " a." 4 +The \fIfile\fP operand is used as the \fIpath\fP argument. +.LP +.IP " b." 4 +The \fButimbuf\fP structure members \fIactime\fP and \fImodtime\fP +are determined as described in the OPTIONS section. +.LP +.RE +.LP +.SH OPTIONS +.LP +The \fItouch\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-a\fP +Change the access time of \fIfile\fP. Do not change the modification +time unless \fB-m\fP is also specified. +.TP 7 +\fB-c\fP +Do not create a specified \fIfile\fP if it does not exist. Do not +write any diagnostic messages concerning this +condition. +.TP 7 +\fB-m\fP +Change the modification time of \fIfile\fP. Do not change the access +time unless \fB-a\fP is also specified. +.TP 7 +\fB-r\ \fP \fIref_file\fP +Use the corresponding time of the file named by the pathname \fIref_file\fP +instead of the current time. +.TP 7 +\fB-t\ \fP \fItime\fP +Use the specified \fItime\fP instead of the current time. The option-argument +shall be a decimal number of the form: +.sp +.RS +.nf + +\fB[[\fP\fICC\fP\fB]\fP\fIYY\fP\fB]\fP\fIMMDDhhmm\fP\fB[\fP\fB.\fP\fISS\fP\fB]\fP +.fi +.RE +.LP +where each two digits represents the following: +.TP 7 +\fIMM\fP +.RS +The month of the year [01,12]. +.RE +.TP 7 +\fIDD\fP +.RS +The day of the month [01,31]. +.RE +.TP 7 +\fIhh\fP +.RS +The hour of the day [00,23]. +.RE +.TP 7 +\fImm\fP +.RS +The minute of the hour [00,59]. +.RE +.TP 7 +\fICC\fP +.RS +The first two digits of the year (the century). +.RE +.TP 7 +\fIYY\fP +.RS +The second two digits of the year. +.RE +.TP 7 +\fISS\fP +.RS +The second of the minute [00,60]. +.RE +.sp +.LP +Both \fICC\fP and \fIYY\fP shall be optional. If neither is given, +the current year shall be assumed. If \fIYY\fP is +specified, but \fICC\fP is not, \fICC\fP shall be derived as follows: +.TS C +center; l l. +\fBIf \fIYY\fP is:\fP \fB\fICC\fP becomes:\fP +[69,99] 19 +[00,68] 20 +.TE +.TP 7 +\fBNote:\fP +.RS +It is expected that in a future version of IEEE\ Std\ 1003.1-2001 +the default century inferred from a 2-digit year will +change. (This would apply to all commands accepting a 2-digit year +as input.) +.RE +.sp +.LP +The resulting time shall be affected by the value of the \fITZ\fP +environment variable. If the resulting time value precedes +the Epoch, \fItouch\fP shall exit immediately with an error status. +The range of valid times past the Epoch is +implementation-defined, but it shall extend to at least the time 0 +hours, 0 minutes, 0 seconds, January 1, 2038, Coordinated +Universal Time. Some implementations may not be able to represent +dates beyond January 18, 2038, because they use \fBsigned int\fP +as a time holder. +.LP +The range for \fISS\fP is [00,60] rather than [00,59] because of leap +seconds. If \fISS\fP is 60, and the resulting time, as +affected by the \fITZ\fP environment variable, does not refer to a +leap second, the resulting time shall be one second after a +time where \fISS\fP is 59. If \fISS\fP is not given a value, it is +assumed to be zero. +.sp +.LP +If neither the \fB-a\fP nor \fB-m\fP options were specified, \fItouch\fP +shall behave as if both the \fB-a\fP and \fB-m\fP +options were specified. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile\fP +A pathname of a file whose times shall be modified. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fItouch\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITZ\fP +Determine the timezone to be used for interpreting the \fItime\fP +option-argument. If \fITZ\fP is unset or null, an +unspecified default timezone shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The utility executed successfully and all requested changes were made. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The interpretation of time is taken to be \fIseconds since the Epoch\fP +(see the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.14, Seconds Since the Epoch). It +should be noted that implementations conforming to the System Interfaces +volume of IEEE\ Std\ 1003.1-2001 do not take leap +seconds into account when computing seconds since the Epoch. When +\fISS\fP=60 is used, the resulting time always refers to 1 plus +\fIseconds since the Epoch\fP for a time when \fISS\fP=59. +.LP +Although the \fB-t\fP \fItime\fP option-argument specifies values +in 1969, the access time and modification time fields are +defined in terms of seconds since the Epoch (00:00:00 on 1 January +1970 UTC). Therefore, depending on the value of \fITZ\fP when +\fItouch\fP is run, there is never more than a few valid hours in +1969 and there need not be any valid times in 1969. +.LP +One ambiguous situation occurs if \fB-t\fP \fItime\fP is not specified, +\fB-r\fP \fIref_file\fP is not specified, and the +first operand is an eight or ten-digit decimal number. A portable +script can avoid this problem by using: +.sp +.RS +.nf + +\fBtouch -- file +\fP +.fi +.RE +.LP +or: +.sp +.RS +.nf + +\fBtouch ./file +\fP +.fi +.RE +.LP +in this case. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The functionality of \fItouch\fP is described almost entirely through +references to functions in the System Interfaces volume +of IEEE\ Std\ 1003.1-2001. In this way, there is no duplication of +effort required for describing such side effects as the +relationship of user IDs to the user database, permissions, and so +on. +.LP +There are some significant differences between the \fItouch\fP utility +in this volume of IEEE\ Std\ 1003.1-2001 and +those in System V and BSD systems. They are upwards-compatible for +historical applications from both implementations: +.IP " 1." 4 +In System V, an ambiguity exists when a pathname that is a decimal +number leads the operands; it is treated as a time value. In +BSD, no \fItime\fP value is allowed; files may only be \fItouch\fPed +to the current time. The \fB-t\fP \fItime\fP construct +solves these problems for future conforming applications (note that +the \fB-t\fP option is not historical practice). +.LP +.IP " 2." 4 +The inclusion of the century digits, \fICC\fP, is also new. Note that +a ten-digit \fItime\fP value is treated as if \fIYY\fP, +and not \fICC\fP, were specified. The caveat about the range of dates +following the Epoch was included as recognition that some +implementations are not able to represent dates beyond 18 January +2038 because they use \fBsigned int\fP as a time holder. +.LP +.LP +The \fB-r\fP option was added because several comments requested this +capability. This option was named \fB-f\fP in an early +proposal, but was changed because the \fB-f\fP option is used in the +BSD version of \fItouch\fP with a different meaning. +.LP +At least one historical implementation of \fItouch\fP incremented +the exit code if \fB-c\fP was specified and the file did not +exist. This volume of IEEE\ Std\ 1003.1-2001 requires exit status +zero if no errors occur. +.SH FUTURE DIRECTIONS +.LP +Applications should use the \fB-r\fP or \fB-t\fP options. +.SH SEE ALSO +.LP +\fIdate\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\fIcreat\fP(), \fItime\fP(), \fIutime\fP(), the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/tput.1p b/man1p/tput.1p new file mode 100644 index 000000000..3a94b1e9f --- /dev/null +++ b/man1p/tput.1p @@ -0,0 +1,228 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TPUT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tput +.SH NAME +tput \- change terminal characteristics +.SH SYNOPSIS +.LP +\fBtput\fP \fB[\fP\fB-T\fP \fItype\fP\fB]\fP \fIoperand\fP\fB... \fP +.SH DESCRIPTION +.LP +The \fItput\fP utility shall display terminal-dependent information. +The manner in which this information is retrieved is +unspecified. The information displayed shall clear the terminal screen, +initialize the user's terminal, or reset the user's +terminal, depending on the operand given. The exact consequences of +displaying this information are unspecified. +.SH OPTIONS +.LP +The \fItput\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-T\ \fP \fItype\fP +Indicate the type of terminal. If this option is not supplied and +the \fITERM\fP variable is unset or null, an unspecified +default terminal type shall be used. The setting of \fItype\fP shall +take precedence over the value in \fITERM .\fP +.sp +.SH OPERANDS +.LP +The following strings shall be supported as operands by the implementation +in the POSIX locale: +.TP 7 +\fBclear\fP +Display the clear-screen sequence. +.TP 7 +\fBinit\fP +Display the sequence that initializes the user's terminal in an implementation-defined +manner. +.TP 7 +\fBreset\fP +Display the sequence that resets the user's terminal in an implementation-defined +manner. +.sp +.LP +If a terminal does not support any of the operations described by +these operands, this shall not be considered an error +condition. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fItput\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITERM\fP +Determine the terminal type. If this variable is unset or null, and +if the \fB-T\fP option is not specified, an unspecified +default terminal type shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If standard output is a terminal device, it may be used for writing +the appropriate sequence to clear the screen or reset or +initialize the terminal. If standard output is not a terminal device, +undefined results occur. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The requested string was written successfully. +.TP 7 +\ 1 +Unspecified. +.TP 7 +\ 2 +Usage error. +.TP 7 +\ 3 +No information is available about the specified terminal type. +.TP 7 +\ 4 +The specified operand is invalid. +.TP 7 +>4 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If one of the operands is not available for the terminal, \fItput\fP +continues processing the remaining operands. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The difference between resetting and initializing a terminal is left +unspecified, as they vary greatly based on hardware types. +In general, resetting is a more severe action. +.LP +Some terminals use control characters to perform the stated functions, +and on such terminals it might make sense to use +\fItput\fP to store the initialization strings in a file or environment +variable for later use. However, because other terminals +might rely on system calls to do this work, the standard output cannot +be used in a portable manner, such as the following +non-portable constructs: +.sp +.RS +.nf + +\fBClearVar=`tput clear` +tput reset | mailx -s "Wake Up" ddg +\fP +.fi +.RE +.SH EXAMPLES +.IP " 1." 4 +Initialize the terminal according to the type of terminal in the environmental +variable \fITERM .\fP This command can be +included in a \fB.profile\fP file. +.sp +.RS +.nf + +\fBtput init +\fP +.fi +.RE +.LP +.IP " 2." 4 +Reset a 450 terminal. +.sp +.RS +.nf + +\fBtput -T 450 reset +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +The list of operands was reduced to a minimum for the following reasons: +.IP " *" 3 +The only features chosen were those that were likely to be used by +human users interacting with a terminal. +.LP +.IP " *" 3 +Specifying the full \fIterminfo\fP set was not considered desirable, +but the standard developers did not want to select among +operands. +.LP +.IP " *" 3 +This volume of IEEE\ Std\ 1003.1-2001 does not attempt to provide +applications with sophisticated terminal handling +capabilities, as that falls outside of its assigned scope and intersects +with the responsibilities of other standards bodies. +.LP +.LP +The difference between resetting and initializing a terminal is left +unspecified as this varies greatly based on hardware types. +In general, resetting is a more severe action. +.LP +The exit status of 1 is historically reserved for finding out if a +Boolean operand is not set. Although the operands were +reduced to a minimum, the exit status of 1 should still be reserved +for the Boolean operands, for those sites that wish to support +them. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstty\fP , \fItabs\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/tr.1p b/man1p/tr.1p new file mode 100644 index 000000000..9a8baabc4 --- /dev/null +++ b/man1p/tr.1p @@ -0,0 +1,538 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tr +.SH NAME +tr \- translate characters +.SH SYNOPSIS +.LP +\fBtr\fP \fB[\fP\fB-c | -C\fP\fB][\fP\fB-s]\fP \fIstring1 string2\fP\fB +.br +.sp +tr -s\fP \fB[\fP\fB-c | -C\fP\fB]\fP \fIstring1\fP\fB +.br +.sp +tr -d\fP \fB[\fP\fB-c | -C\fP\fB]\fP \fIstring1\fP\fB +.br +.sp +tr -ds\fP \fB[\fP\fB-c | -C\fP\fB]\fP \fIstring1 string2\fP\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fItr\fP utility shall copy the standard input to the standard +output with substitution or deletion of selected characters. +The options specified and the \fIstring1\fP and \fIstring2\fP operands +shall control translations that occur while copying +characters and single-character collating elements. +.SH OPTIONS +.LP +The \fItr\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-c\fP +Complement the set of values specified by \fIstring1\fP. See the EXTENDED +DESCRIPTION section. +.TP 7 +\fB-C\fP +Complement the set of characters specified by \fIstring1\fP. See the +EXTENDED DESCRIPTION section. +.TP 7 +\fB-d\fP +Delete all occurrences of input characters that are specified by \fIstring1\fP. +.TP 7 +\fB-s\fP +Replace instances of repeated characters with a single character, +as described in the EXTENDED DESCRIPTION section. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIstring1\fP,\ \fIstring2\fP +.sp +Translation control strings. Each string shall represent a set of +characters to be converted into an array of characters used for +the translation. For a detailed description of how the strings are +interpreted, see the EXTENDED DESCRIPTION section. +.sp +.SH STDIN +.LP +The standard input can be any type of file. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fItr\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of range expressions and equivalence +classes. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments) and the behavior of +character classes. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fItr\fP output shall be identical to the input, with the exception +of the specified transformations. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +The operands \fIstring1\fP and \fIstring2\fP (if specified) define +two arrays of characters. The constructs in the following +list can be used to specify characters or single-character collating +elements. If any of the constructs result in multi-character +collating elements, \fItr\fP shall exclude, without a diagnostic, +those multi-character elements from the resulting array. +.TP 7 +\fIcharacter\fP +Any character not described by one of the conventions below shall +represent itself. +.TP 7 +\\\fIoctal\fP +Octal sequences can be used to represent characters with specific +coded values. An octal sequence shall consist of a backslash +followed by the longest sequence of one, two, or three-octal-digit +characters (01234567). The sequence shall cause the value whose +encoding is represented by the one, two, or three-digit octal integer +to be placed into the array. If the size of a byte on the +system is greater than nine bits, the valid escape sequence used to +represent a byte is implementation-defined. Multi-byte +characters require multiple, concatenated escape sequences of this +type, including the leading \fB'\\'\fP for each byte. +.TP 7 +\\\fIcharacter\fP +The backslash-escape sequences in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Table 5-1, Escape Sequences +and Associated Actions ( \fB'\\\\'\fP , \fB'\\a'\fP , \fB'\\b'\fP +, \fB'\\f'\fP , \fB'\\n'\fP , \fB'\\r'\fP , +\fB'\\t'\fP , \fB'\\v'\fP ) shall be supported. The results of using +any other character, other than an octal digit, following +the backslash are unspecified. +.TP 7 +\fIc\fP-\fIc\fP +In the POSIX locale, this construct shall represent the range of collating +elements between the range endpoints (as long as +neither endpoint is an octal sequence of the form \\\fIoctal\fP), +inclusive, as defined by the collation sequence. The characters +or collating elements in the range shall be placed in the array in +ascending collation sequence. If the second endpoint precedes +the starting endpoint in the collation sequence, it is unspecified +whether the range of collating elements is empty, or this +construct is treated as invalid. In locales other than the POSIX locale, +this construct has unspecified behavior. +.LP +If either or both of the range endpoints are octal sequences of the +form \\\fIoctal\fP, this shall represent the range of +specific coded values between the two range endpoints, inclusive. +.TP 7 +.B :\fIclass\fP: +Represents all characters belonging to the defined character class, +as defined by the current setting of the \fILC_CTYPE\fP +locale category. The following character class names shall be accepted +when specified in \fIstring1\fP: +.TS C +center; l l l l l l. +\fBalnum\fP \fBblank\fP \fBdigit\fP \fBlower\fP \fBpunct\fP \fBupper\fP +\fBalpha\fP \fBcntrl\fP \fBgraph\fP \fBprint\fP \fBspace\fP \fBxdigit\fP +.TE +.LP +In addition, character class expressions of the form [: \fIname\fP:] +shall be recognized in those locales where the \fIname\fP +keyword has been given a \fBcharclass\fP definition in the \fILC_CTYPE\fP +category. +.LP +When both the \fB-d\fP and \fB-s\fP options are specified, any of +the character class names shall be accepted in +\fIstring2\fP. Otherwise, only character class names \fBlower\fP or +\fBupper\fP are valid in \fIstring2\fP and then only if the +corresponding character class ( \fBupper\fP and \fBlower\fP, respectively) +is specified in the same relative position in +\fIstring1\fP. Such a specification shall be interpreted as a request +for case conversion. When [: \fIlower\fP:] appears in +\fIstring1\fP and [: \fIupper\fP:] appears in \fIstring2\fP, the arrays +shall contain the characters from the \fBtoupper\fP +mapping in the \fILC_CTYPE\fP category of the current locale. When +[: \fIupper\fP:] appears in \fIstring1\fP and [: +\fIlower\fP:] appears in \fIstring2\fP, the arrays shall contain the +characters from the \fBtolower\fP mapping in the +\fILC_CTYPE\fP category of the current locale. The first character +from each mapping pair shall be in the array for \fIstring1\fP +and the second character from each mapping pair shall be in the array +for \fIstring2\fP in the same relative position. +.LP +Except for case conversion, the characters specified by a character +class expression shall be placed in the array in an +unspecified order. +.LP +If the name specified for \fIclass\fP does not define a valid character +class in the current locale, the behavior is +undefined. +.TP 7 +.B =\fIequiv\fP= +Represents all characters or collating elements belonging to the same +equivalence class as \fIequiv\fP, as defined by the +current setting of the \fILC_COLLATE\fP locale category. An equivalence +class expression shall be allowed only in \fIstring1\fP, +or in \fIstring2\fP when it is being used by the combined \fB-d\fP +and \fB-s\fP options. The characters belonging to the +equivalence class shall be placed in the array in an unspecified order. +.TP 7 +.B \fIx\fP*\fIn\fP +Represents \fIn\fP repeated occurrences of the character \fIx\fP. +Because this expression is used to map multiple characters +to one, it is only valid when it occurs in \fIstring2\fP. If \fIn\fP +is omitted or is zero, it shall be interpreted as large +enough to extend the \fIstring2\fP-based sequence to the length of +the \fIstring1\fP-based sequence. If \fIn\fP has a leading +zero, it shall be interpreted as an octal value. Otherwise, it shall +be interpreted as a decimal value. +.sp +.LP +When the \fB-d\fP option is not specified: +.IP " *" 3 +Each input character found in the array specified by \fIstring1\fP +shall be replaced by the character in the same relative +position in the array specified by \fIstring2\fP. When the array specified +by \fIstring2\fP is shorter that the one specified by +\fIstring1\fP, the results are unspecified. +.LP +.IP " *" 3 +If the \fB-C\fP option is specified, the complements of the characters +specified by \fIstring1\fP (the set of all characters +in the current character set, as defined by the current setting of +\fILC_CTYPE ,\fP except for those actually specified in the +\fIstring1\fP operand) shall be placed in the array in ascending collation +sequence, as defined by the current setting of +\fILC_COLLATE .\fP +.LP +.IP " *" 3 +If the \fB-c\fP option is specified, the complement of the values +specified by \fIstring1\fP shall be placed in the array in +ascending order by binary value. +.LP +.IP " *" 3 +Because the order in which characters specified by character class +expressions or equivalence class expressions is undefined, +such expressions should only be used if the intent is to map several +characters into one. An exception is case conversion, as +described previously. +.LP +.LP +When the \fB-d\fP option is specified: +.IP " *" 3 +Input characters found in the array specified by \fIstring1\fP shall +be deleted. +.LP +.IP " *" 3 +When the \fB-C\fP option is specified with \fB-d\fP, all characters +except those specified by \fIstring1\fP shall be deleted. +The contents of \fIstring2\fP are ignored, unless the \fB-s\fP option +is also specified. +.LP +.IP " *" 3 +When the \fB-c\fP option is specified with \fB-d\fP, all values except +those specified by \fIstring1\fP shall be deleted. The +contents of \fIstring2\fP shall be ignored, unless the \fB-s\fP option +is also specified. +.LP +.IP " *" 3 +The same string cannot be used for both the \fB-d\fP and the \fB-s\fP +option; when both options are specified, both +\fIstring1\fP (used for deletion) and \fIstring2\fP (used for squeezing) +shall be required. +.LP +.LP +When the \fB-s\fP option is specified, after any deletions or translations +have taken place, repeated sequences of the same +character shall be replaced by one occurrence of the same character, +if the character is found in the array specified by the last +operand. If the last operand contains a character class, such as the +following example: +.sp +.RS +.nf + +\fBtr -s '[:space:]' +\fP +.fi +.RE +.LP +the last operand's array shall contain all of the characters in that +character class. However, in a case conversion, as +described previously, such as: +.sp +.RS +.nf + +\fBtr -s '[:upper:]' '[:lower:]' +\fP +.fi +.RE +.LP +the last operand's array shall contain only those characters defined +as the second characters in each of the \fBtoupper\fP or +\fBtolower\fP character pairs, as appropriate. +.LP +An empty string used for \fIstring1\fP or \fIstring2\fP produces undefined +results. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All input was processed successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +If necessary, \fIstring1\fP and \fIstring2\fP can be quoted to avoid +pattern matching by the shell. +.LP +If an ordinary digit (representing itself) is to follow an octal sequence, +the octal sequence must use the full three digits to +avoid ambiguity. +.LP +When \fIstring2\fP is shorter than \fIstring1\fP, a difference results +between historical System\ V and BSD systems. A BSD +system pads \fIstring2\fP with the last character found in \fIstring2\fP. +Thus, it is possible to do the following: +.sp +.RS +.nf + +\fBtr 0123456789 d +\fP +.fi +.RE +.LP +which would translate all digits to the letter \fB'd'\fP . Since this +area is specifically unspecified in this volume of +IEEE\ Std\ 1003.1-2001, both the BSD and System\ V behaviors are allowed, +but a conforming application cannot rely on +the BSD behavior. It would have to code the example in the following +way: +.sp +.RS +.nf + +\fBtr 0123456789 '[d*]' +\fP +.fi +.RE +.LP +It should be noted that, despite similarities in appearance, the string +operands used by \fItr\fP are not regular +expressions. +.LP +Unlike some historical implementations, this definition of the \fItr\fP +utility correctly processes NUL characters in its input +stream. NUL characters can be stripped by using: +.sp +.RS +.nf + +\fBtr -d '\\000' +\fP +.fi +.RE +.SH EXAMPLES +.IP " 1." 4 +The following example creates a list of all words in \fBfile1\fP one +per line in \fBfile2\fP, where a word is taken to be a +maximal string of letters. +.sp +.RS +.nf + +\fBtr -cs "[:alpha:]" "[\\n*]" file2 +\fP +.fi +.RE +.LP +.IP " 2." 4 +The next example translates all lowercase characters in \fBfile1\fP +to uppercase and writes the results to standard output. +.sp +.RS +.nf + +\fBtr "[:lower:]" "[:upper:]" file2 +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +In some early proposals, an explicit option \fB-n\fP was added to +disable the historical behavior of stripping NUL characters +from the input. It was considered that automatically stripping NUL +characters from the input was not correct functionality. +However, the removal of \fB-n\fP in a later proposal does not remove +the requirement that \fItr\fP correctly process NUL +characters in its input stream. NUL characters can be stripped by +using \fItr\fP \fB-d\fP '\\000'. +.LP +Historical implementations of \fItr\fP differ widely in syntax and +behavior. For example, the BSD version has not needed the +bracket characters for the repetition sequence. The \fItr\fP utility +syntax is based more closely on the System V and XPG3 model +while attempting to accommodate historical BSD implementations. In +the case of the short \fIstring2\fP padding, the decision was +to unspecify the behavior and preserve System V and XPG3 scripts, +which might find difficulty with the BSD method. The assumption +was made that BSD users of \fItr\fP have to make accommodations to +meet the syntax defined here. Since it is possible to use the +repetition sequence to duplicate the desired behavior, whereas there +is no simple way to achieve the System V method, this was the +correct, if not desirable, approach. +.LP +The use of octal values to specify control characters, while having +historical precedents, is not portable. The introduction of +escape sequences for control characters should provide the necessary +portability. It is recognized that this may cause some +historical scripts to break. +.LP +An early proposal included support for multi-character collating elements. +It was pointed out that, while \fItr\fP does employ +some syntactical elements from REs, the aim of \fItr\fP is quite different; +ranges, for example, do not have a similar meaning +(``any of the chars in the range matches", \fIversus\fP "translate +each character in the range to the output counterpart"). As +a result, the previously included support for multi-character collating +elements has been removed. What remains are ranges in +current collation order (to support, for example, accented characters), +character classes, and equivalence classes. +.LP +In XPG3 the [: \fIclass\fP:] and [= \fIequiv\fP=] conventions are +shown with double brackets, as in RE syntax. However, +\fItr\fP does not implement RE principles; it just borrows part of +the syntax. Consequently, [: \fIclass\fP:] and [= +\fIequiv\fP=] should be regarded as syntactical elements on a par +with [ \fIx\fP* \fIn\fP], which is not an RE bracket +expression. +.LP +The standard developers will consider changes to \fItr\fP that allow +it to translate characters between different character +encodings, or they will consider providing a new utility to accomplish +this. +.LP +On historical System V systems, a range expression requires enclosing +square-brackets, such as: +.sp +.RS +.nf + +\fBtr '[a-z]' '[A-Z]' +\fP +.fi +.RE +.LP +However, BSD-based systems did not require the brackets, and this +convention is used here to avoid breaking large numbers of BSD +scripts: +.sp +.RS +.nf + +\fBtr a-z A-Z +\fP +.fi +.RE +.LP +The preceding System V script will continue to work because the brackets, +treated as regular characters, are translated to +themselves. However, any System V script that relied on \fB"a-z"\fP +representing the three characters \fB'a'\fP , +\fB'-'\fP , and \fB'z'\fP have to be rewritten as \fB"az-"\fP . +.LP +The ISO\ POSIX-2:1993 standard had a \fB-c\fP option that behaved +similarly to the \fB-C\fP option, but did not supply +functionality equivalent to the \fB-c\fP option specified in IEEE\ Std\ 1003.1-2001. +This meant that historical practice +of being able to specify \fItr\fP \fB-d\fP\\200-\\377 (which would +delete all bytes with the top bit set) would have no effect +because, in the C locale, bytes with the values octal 200 to octal +377 are not characters. +.LP +The earlier version also said that octal sequences referred to collating +elements and could be placed adjacent to each other to +specify multi-byte characters. However, it was noted that this caused +ambiguities because \fItr\fP would not be able to tell +whether adjacent octal sequences were intending to specify multi-byte +characters or multiple single byte characters. +IEEE\ Std\ 1003.1-2001 specifies that octal sequences always refer +to single byte binary values. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsed\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/trap.1p b/man1p/trap.1p new file mode 100644 index 000000000..18bcefb93 --- /dev/null +++ b/man1p/trap.1p @@ -0,0 +1,240 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TRAP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" trap +.SH NAME +trap \- trap signals +.SH SYNOPSIS +.LP +\fBtrap\fP \fB[\fP\fIaction condition\fP \fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +If \fIaction\fP is \fB'-'\fP , the shell shall reset each \fIcondition\fP +to the default value. If \fIaction\fP is null ( +\fB""\fP ), the shell shall ignore each specified \fIcondition\fP +if it arises. Otherwise, the argument \fIaction\fP shall be +read and executed by the shell when one of the corresponding conditions +arises. The action of \fItrap\fP shall override a previous +action (either default action or one explicitly set). The value of +\fB"$?"\fP after the \fItrap\fP action completes shall be +the value it had before \fItrap\fP was invoked. +.LP +The condition can be EXIT, 0 (equivalent to EXIT), or a signal specified +using a symbolic name, without the SIG prefix, as +listed in the tables of signal names in the \fI\fP header +defined in the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 13, Headers; +for example, HUP, INT, QUIT, TERM. Implementations may permit names +with the SIG prefix or ignore case in signal names as an +extension. Setting a trap for SIGKILL or SIGSTOP produces undefined +results. +.LP +The environment in which the shell executes a \fItrap\fP on EXIT shall +be identical to the environment immediately after the +last command executed before the \fItrap\fP on EXIT was taken. +.LP +Each time \fItrap\fP is invoked, the \fIaction\fP argument shall be +processed in a manner equivalent to: +.sp +.RS +.nf + +\fBeval\fP \fIaction\fP +.fi +.RE +.LP +Signals that were ignored on entry to a non-interactive shell cannot +be trapped or reset, although no error need be reported +when attempting to do so. An interactive shell may reset or catch +signals ignored on entry. Traps shall remain in place for a given +shell until explicitly changed with another \fItrap\fP command. +.LP +When a subshell is entered, traps that are not being ignored are set +to the default actions. This does not imply that the +\fItrap\fP command cannot be used within the subshell to set new traps. +.LP +The \fItrap\fP command with no arguments shall write to standard output +a list of commands associated with each condition. The +format shall be: +.sp +.RS +.nf + +\fB"trap -- %s %s ...\\n", <\fP\fIaction\fP\fB>, <\fP\fIcondition\fP\fB> ... +\fP +.fi +.RE +.LP +The shell shall format the output, including the proper use of quoting, +so that it is suitable for reinput to the shell as +commands that achieve the same trapping results. For example: +.sp +.RS +.nf + +\fBsave_traps=$(trap) +\&... +eval "$save_traps" +\fP +.fi +.RE +.LP +XSI-conformant systems also allow numeric signal numbers for the conditions +corresponding to the following signal names: +.TS C +center; l l. +\fBSignal Number\fP \fBSignal Name\fP +1 SIGHUP +2 SIGINT +3 SIGQUIT +6 SIGABRT +9 SIGKILL +14 SIGALRM +15 SIGTERM +.TE +.LP +The \fItrap\fP special built-in shall conform to the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +See the DESCRIPTION. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +None. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +See the DESCRIPTION. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +If the trap name \ or number is invalid, a non-zero +exit status shall be returned; otherwise, zero shall be returned. +For both interactive and non-interactive shells, invalid signal +names \ or numbers shall not be considered a syntax error and do +not cause the shell to abort. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +Write out a list of all traps and actions: +.sp +.RS +.nf + +\fBtrap +\fP +.fi +.RE +.LP +Set a trap so the \fIlogout\fP utility in the directory referred to +by the \fIHOME\fP +environment variable executes when the shell terminates: +.sp +.RS +.nf + +\fBtrap '$HOME/logout' EXIT +\fP +.fi +.RE +.LP +or: +.sp +.RS +.nf + +\fBtrap '$HOME/logout' 0 +\fP +.fi +.RE +.LP +Unset traps on INT, QUIT, TERM, and EXIT: +.sp +.RS +.nf + +\fBtrap - INT QUIT TERM EXIT +\fP +.fi +.RE +.SH RATIONALE +.LP +Implementations may permit lowercase signal names as an extension. +Implementations may also accept the names with the SIG +prefix; no known historical shell does so. The \fItrap\fP and \fIkill\fP +utilities in this +volume of IEEE\ Std\ 1003.1-2001 are now consistent in their omission +of the SIG prefix for signal names. Some \fIkill\fP implementations +do not allow the prefix, and \fIkill\fP \fB-l\fP lists the signals +without prefixes. +.LP +Trapping SIGKILL or SIGSTOP is syntactically accepted by some historical +implementations, but it has no effect. Portable POSIX +applications cannot attempt to trap these signals. +.LP +The output format is not historical practice. Since the output of +historical \fItrap\fP commands is not portable (because +numeric signal values are not portable) and had to change to become +so, an opportunity was taken to format the output in a way that +a shell script could use to save and then later reuse a trap if it +wanted. +.LP +The KornShell uses an \fBERR\fP trap that is triggered whenever \fIset\fP +\fB-e\fP would +cause an exit. This is allowable as an extension, but was not mandated, +as other shells have not used it. +.LP +The text about the environment for the EXIT trap invalidates the behavior +of some historical versions of interactive shells +which, for example, close the standard input before executing a trap +on 0. For example, in some historical interactive shell +sessions the following trap on 0 would always print \fB"--"\fP : +.sp +.RS +.nf + +\fBtrap 'read foo; echo "-$foo-"' 0 +\fP +.fi +.RE +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISpecial Built-In Utilities\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/true.1p b/man1p/true.1p new file mode 100644 index 000000000..7372f0437 --- /dev/null +++ b/man1p/true.1p @@ -0,0 +1,91 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TRUE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" true +.SH NAME +true \- return true value +.SH SYNOPSIS +.LP +\fBtrue\fP +.SH DESCRIPTION +.LP +The \fItrue\fP utility shall return with exit code zero. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +None. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +None. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +Not used. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +Zero. +.SH CONSEQUENCES OF ERRORS +.LP +None. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +This utility is typically used in shell scripts, as shown in the EXAMPLES +section. The special built-in utility \fB:\fP is +sometimes more efficient than \fItrue\fP. +.SH EXAMPLES +.LP +This command is executed forever: +.sp +.RS +.nf + +\fBwhile true +do + command +done +\fP +.fi +.RE +.SH RATIONALE +.LP +The \fItrue\fP utility has been retained in this volume of IEEE\ Std\ 1003.1-2001, +even though the shell special +built-in \fB:\fP provides similar functionality, because \fItrue\fP +is widely used in historical scripts and is less cryptic to +novice script readers. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfalse\fP , \fIShell Commands\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/tsort.1p b/man1p/tsort.1p new file mode 100644 index 000000000..ca4243356 --- /dev/null +++ b/man1p/tsort.1p @@ -0,0 +1,154 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TSORT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tsort +.SH NAME +tsort \- topological sort +.SH SYNOPSIS +.LP +\fBtsort\fP \fB[\fP\fIfile\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fItsort\fP utility shall write to standard output a totally ordered +list of items consistent with a partial ordering of +items contained in the input. +.LP +The application shall ensure that the input consists of pairs of items +(non-empty strings) separated by s. Pairs of +different items indicate ordering. Pairs of identical items indicate +presence, but not ordering. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a text file to order. If no \fIfile\fP operand is given, +the standard input shall be used. +.sp +.SH STDIN +.LP +The standard input shall be a text file that is used if no \fIfile\fP +operand is given. +.SH INPUT FILES +.LP +The input file named by the \fIfile\fP operand is a text file. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fItsort\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall be a text file consisting of the order list +produced from the partially ordered input. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fILC_COLLATE\fP variable need not affect the actions of \fItsort\fP. +The output ordering is not lexicographic, but +depends on the pairs of items given as input. +.SH EXAMPLES +.LP +The command: +.sp +.RS +.nf + +\fBtsort < +\fP +.fi +.RE +.LP +Otherwise, a message shall be written indicating that standard input +is not connected to a terminal. In the POSIX locale, the +\fItty\fP utility shall use the format: +.sp +.RS +.nf + +\fB"not a tty\\n" +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Standard input is a terminal. +.TP 7 +\ 1 +Standard input is not a terminal. +.TP 7 +>1 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +This utility checks the status of the file open as standard input +against that of an implementation-defined set of files. It is +possible that no match can be found, or that the match found need +not be the same file as that which was opened for standard input +(although they are the same device). +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIisatty\fP(), +\fIttyname\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/type.1p b/man1p/type.1p new file mode 100644 index 000000000..01a6ea1d7 --- /dev/null +++ b/man1p/type.1p @@ -0,0 +1,137 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TYPE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" type +.SH NAME +type \- write a description of command type +.SH SYNOPSIS +.LP +\fBtype\fP \fIname\fP\fB... \fP +.SH DESCRIPTION +.LP +The \fItype\fP utility shall indicate how each argument would be interpreted +if used as a command name. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIname\fP +A name to be interpreted. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fItype\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPATH\fP +Determine the location of \fIname\fP, as described in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output of \fItype\fP contains information about each +operand in an unspecified format. The information provided +typically identifies the operand as a shell built-in, function, alias, +or keyword, and where applicable, may display the operand's +pathname. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Since \fItype\fP must be aware of the contents of the current shell +execution environment (such as the lists of commands, +functions, and built-ins processed by \fIhash\fP), it is always provided +as a shell regular +built-in. If it is called in a separate utility execution environment, +such as one of the following: +.sp +.RS +.nf + +\fBnohup type writer +find . -type f | xargs type +\fP +.fi +.RE +it might not produce accurate results. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcommand\fP , \fIhash\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/ulimit.1p b/man1p/ulimit.1p new file mode 100644 index 000000000..193fb8c75 --- /dev/null +++ b/man1p/ulimit.1p @@ -0,0 +1,173 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ULIMIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ulimit +.SH NAME +ulimit \- set or report file size limit +.SH SYNOPSIS +.LP +\fBulimit\fP \fB[\fP\fB-f\fP\fB][\fP\fIblocks\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIulimit\fP utility shall set or report the file-size writing +limit imposed on files written by the shell and its child +processes (files of any size may be read). Only a process with appropriate +privileges can increase the limit. +.SH OPTIONS +.LP +The \fIulimit\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-f\fP +Set (or report, if no \fIblocks\fP operand is present), the file size +limit in blocks. The \fB-f\fP option shall also be the +default case. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIblocks\fP +The number of 512-byte blocks to use as the new file size limit. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIulimit\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall be used when no \fIblocks\fP operand is +present. If the current number of blocks is limited, the +number of blocks in the current limit shall be written in the following +format: +.sp +.RS +.nf + +\fB"%d\\n", <\fP\fInumber of 512-byte blocks\fP\fB> +\fP +.fi +.RE +.LP +If there is no current limit on the number of blocks, in the POSIX +locale the following format shall be used: +.sp +.RS +.nf + +\fB"unlimited\\n" +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +A request for a higher limit was rejected or an error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Since \fIulimit\fP affects the current shell execution environment, +it is always provided as a shell regular built-in. If it is +called in a separate utility execution environment, such as one of +the following: +.sp +.RS +.nf + +\fBnohup ulimit -f 10000 +env ulimit 10000 +\fP +.fi +.RE +.LP +it does not affect the file size limit of the caller's environment. +.LP +Once a limit has been decreased by a process, it cannot be increased +(unless appropriate privileges are involved), even back to +the original system limit. +.SH EXAMPLES +.LP +Set the file size limit to 51200 bytes: +.sp +.RS +.nf + +\fBulimit -f 100 +\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIulimit\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/umask.1p b/man1p/umask.1p new file mode 100644 index 000000000..d471b1c9b --- /dev/null +++ b/man1p/umask.1p @@ -0,0 +1,310 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UMASK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" umask +.SH NAME +umask \- get or set the file mode creation mask +.SH SYNOPSIS +.LP +\fBumask\fP \fB[\fP\fB-S\fP\fB][\fP\fImask\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIumask\fP utility shall set the file mode creation mask of the +current shell execution environment (see \fIShell Execution Environment\fP +) to the value specified by the \fImask\fP operand. This mask +shall affect the initial value of the file permission bits of subsequently +created files. If \fIumask\fP is called in a subshell +or separate utility execution environment, such as one of the following: +.sp +.RS +.nf + +\fB(umask 002) +nohup umask ... +find . -exec umask ... \\; +\fP +.fi +.RE +.LP +it shall not affect the file mode creation mask of the caller's environment. +.LP +If the \fImask\fP operand is not specified, the \fIumask\fP utility +shall write to standard output the value of the invoking +process' file mode creation mask. +.SH OPTIONS +.LP +The \fIumask\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-S\fP +Produce symbolic output. +.sp +.LP +The default output style is unspecified, but shall be recognized on +a subsequent invocation of \fIumask\fP on the same system +as a \fImask\fP operand to restore the previous file mode creation +mask. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fImask\fP +A string specifying the new file mode creation mask. The string is +treated in the same way as the \fImode\fP operand described +in the EXTENDED DESCRIPTION section for \fIchmod\fP. +.LP +For a \fIsymbolic_mode\fP value, the new value of the file mode creation +mask shall be the logical complement of the file +permission bits portion of the file mode specified by the \fIsymbolic_mode\fP +string. +.LP +In a \fIsymbolic_mode\fP value, the permissions \fIop\fP characters +\fB'+'\fP and \fB'-'\fP shall be interpreted +relative to the current file mode creation mask; \fB'+'\fP shall cause +the bits for the indicated permissions to be cleared in +the mask; \fB'-'\fP shall cause the bits for the indicated permissions +to be set in the mask. +.LP +The interpretation of \fImode\fP values that specify file mode bits +other than the file permission bits is unspecified. +.LP +In the octal integer form of \fImode\fP, the specified bits are set +in the file mode creation mask. +.LP +The file mode creation mask shall be set to the resulting numeric +value. +.LP +The default output of a prior invocation of \fIumask\fP on the same +system with no operand also shall be recognized as a +\fImask\fP operand. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIumask\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +When the \fImask\fP operand is not specified, the \fIumask\fP utility +shall write a message to standard output that can later +be used as a \fIumask\fP \fImask\fP operand. +.LP +If \fB-S\fP is specified, the message shall be in the following format: +.sp +.RS +.nf + +\fB"u=%s,g=%s,o=%s\\n", <\fP\fIowner permissions\fP\fB>, <\fP\fIgroup permissions\fP\fB>, + <\fP\fIother permissions\fP\fB> +\fP +.fi +.RE +.LP +where the three values shall be combinations of letters from the set +{ \fIr\fP, \fIw\fP, \fIx\fP}; the presence of a letter +shall indicate that the corresponding bit is clear in the file mode +creation mask. +.LP +If a \fImask\fP operand is specified, there shall be no output written +to standard output. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The file mode creation mask was successfully changed, or no \fImask\fP +operand was supplied. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Since \fIumask\fP affects the current shell execution environment, +it is generally provided as a shell regular built-in. +.LP +In contrast to the negative permission logic provided by the file +mode creation mask and the octal number form of the +\fImask\fP argument, the symbolic form of the \fImask\fP argument +specifies those permissions that are left alone. +.SH EXAMPLES +.LP +Either of the commands: +.sp +.RS +.nf + +\fBumask a=rx,ug+w +.sp + +umask 002 +\fP +.fi +.RE +.LP +sets the mode mask so that subsequently created files have their S_IWOTH +bit cleared. +.LP +After setting the mode mask with either of the above commands, the +\fIumask\fP command can be used to write out the current +value of the mode mask: +.sp +.RS +.nf + +\fB$\fP \fBumask +\fP\fB0002\fP +.fi +.RE +.LP +(The output format is unspecified, but historical implementations +use the octal integer mode format.) +.sp +.RS +.nf + +\fB$\fP \fBumask -S +\fP\fBu=rwx,g=rwx,o=rx\fP +.fi +.RE +.LP +Either of these outputs can be used as the mask operand to a subsequent +invocation of the \fIumask\fP utility. +.LP +Assuming the mode mask is set as above, the command: +.sp +.RS +.nf + +\fBumask g-w +\fP +.fi +.RE +.LP +sets the mode mask so that subsequently created files have their S_IWGRP +and S_IWOTH bits cleared. +.LP +The command: +.sp +.RS +.nf + +\fBumask -- -w +\fP +.fi +.RE +.LP +sets the mode mask so that subsequently created files have all their +write bits cleared. Note that \fImask\fP operands +\fB-r\fP, \fB-w\fP, \fB-x\fP or anything beginning with a hyphen, +must be preceded by \fB"--"\fP to keep it from being +interpreted as an option. +.SH RATIONALE +.LP +Since \fIumask\fP affects the current shell execution environment, +it is generally provided as a shell regular built-in. If it +is called in a subshell or separate utility execution environment, +such as one of the following: +.sp +.RS +.nf + +\fB(umask 002) +nohup umask ... +find . -exec umask ... \\; +\fP +.fi +.RE +.LP +it does not affect the file mode creation mask of the environment +of the caller. +.LP +The description of the historical utility was modified to allow it +to use the symbolic modes of \fIchmod\fP. The \fB-s\fP option used +in early proposals was changed to \fB-S\fP because \fB-s\fP +could be confused with a \fIsymbolic_mode\fP form of mask referring +to the S_ISUID and S_ISGID bits. +.LP +The default output style is implementation-defined to permit implementors +to provide migration to the new symbolic style at the +time most appropriate to their users. A \fB-o\fP flag to force octal +mode output was omitted because the octal mode may not be +sufficient to specify all of the information that may be present in +the file mode creation mask when more secure file access +permission checks are implemented. +.LP +It has been suggested that trusted systems developers might appreciate +ameliorating the requirement that the mode mask +"affects" the file access permissions, since it seems access control +lists might replace the mode mask to some degree. The +wording has been changed to say that it affects the file permission +bits, and it leaves the details of the behavior of how they +affect the file access permissions to the description in the System +Interfaces volume of IEEE\ Std\ 1003.1-2001. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP , \fIchmod\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIumask\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/unalias.1p b/man1p/unalias.1p new file mode 100644 index 000000000..f4004cc1d --- /dev/null +++ b/man1p/unalias.1p @@ -0,0 +1,146 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UNALIAS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" unalias +.SH NAME +unalias \- remove alias definitions +.SH SYNOPSIS +.LP +\fBunalias\fP \fIalias-name\fP\fB... +.br +.sp +unalias -a \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIunalias\fP utility shall remove the definition for each alias +name specified. See \fIAlias Substitution\fP . The aliases shall be +removed from the current shell execution +environment; see \fIShell Execution Environment\fP . +.SH OPTIONS +.LP +The \fIunalias\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-a\fP +Remove all alias definitions from the current shell execution environment. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIalias-name\fP +The name of an alias to be removed. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIunalias\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +One of the \fIalias-name\fP operands specified did not represent a +valid alias definition, or an error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Since \fIunalias\fP affects the current shell execution environment, +it is generally provided as a shell regular built-in. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIunalias\fP description is based on that from historical KornShell +implementations. Known differences exist between that +and the C shell. The KornShell version was adopted to be consistent +with all the other KornShell features in this volume of +IEEE\ Std\ 1003.1-2001, such as command line editing. +.LP +The \fB-a\fP option is the equivalent of the \fIunalias\fP * form +of the C shell and is provided to address security concerns +about unknown aliases entering the environment of a user (or application) +through the allowable implementation-defined predefined +alias route or as a result of an \fIENV\fP file. (Although \fIunalias\fP +could be used to simplify the "secure" shell script +shown in the \fIcommand\fP rationale, it does not obviate the need +to quote all command +names. An initial call to \fIunalias\fP \fB-a\fP would have to be +quoted in case there was an alias for \fIunalias\fP.) +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP , \fIalias\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/uname.1p b/man1p/uname.1p new file mode 100644 index 000000000..df18a2ef6 --- /dev/null +++ b/man1p/uname.1p @@ -0,0 +1,200 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UNAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" uname +.SH NAME +uname \- return system name +.SH SYNOPSIS +.LP +\fBuname\fP \fB[\fP\fB-snrvma\fP\fB]\fP +.SH DESCRIPTION +.LP +By default, the \fIuname\fP utility shall write the operating system +name to standard output. When options are specified, +symbols representing one or more system characteristics shall be written +to the standard output. The format and contents of the +symbols are implementation-defined. On systems conforming to the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, the +symbols written shall be those supported by the \fIuname\fP() function +as defined in the +System Interfaces volume of IEEE\ Std\ 1003.1-2001. +.SH OPTIONS +.LP +The \fIuname\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-a\fP +Behave as though all of the options \fB-mnrsv\fP were specified. +.TP 7 +\fB-m\fP +Write the name of the hardware type on which the system is running +to standard output. +.TP 7 +\fB-n\fP +Write the name of this node within an implementation-defined communications +network. +.TP 7 +\fB-r\fP +Write the current release level of the operating system implementation. +.TP 7 +\fB-s\fP +Write the name of the implementation of the operating system. +.TP 7 +\fB-v\fP +Write the current version level of this release of the operating system +implementation. +.sp +.LP +If no options are specified, the \fIuname\fP utility shall write the +operating system name, as if the \fB-s\fP option had been +specified. +.SH OPERANDS +.LP +None. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIuname\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +By default, the output shall be a single line of the following form: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIsysname\fP\fB> +\fP +.fi +.RE +.LP +If the \fB-a\fP option is specified, the output shall be a single +line of the following form: +.sp +.RS +.nf + +\fB"%s %s %s %s %s\\n", <\fP\fIsysname\fP\fB>, <\fP\fInodename\fP\fB>, <\fP\fIrelease\fP\fB>, + <\fP\fIversion\fP\fB>, <\fP\fImachine\fP\fB> +\fP +.fi +.RE +.LP +Additional implementation-defined symbols may be written; all such +symbols shall be written at the end of the line of output +before the . +.LP +If options are specified to select different combinations of the symbols, +only those symbols shall be written, in the order +shown above for the \fB-a\fP option. If a symbol is not selected for +writing, its corresponding trailing s also shall +not be written. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The requested information was successfully written. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Note that any of the symbols could include embedded s, which +may affect parsing algorithms if multiple options are +selected for output. +.LP +The node name is typically a name that the system uses to identify +itself for inter-system communication addressing. +.SH EXAMPLES +.LP +The following command: +.sp +.RS +.nf + +\fBuname -sr +\fP +.fi +.RE +.LP +writes the operating system name and release level, separated by one +or more s. +.SH RATIONALE +.LP +It was suggested that this utility cannot be used portably since the +format of the symbols is implementation-defined. The +POSIX.1 working group could not achieve consensus on defining these +formats in the underlying \fIuname\fP() function, and there was no +expectation that this volume of +IEEE\ Std\ 1003.1-2001 would be any more successful. Some applications +may still find this historical utility of value. For +example, the symbols could be used for system log entries or for comparison +with operator or user input. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIuname\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/uncompress.1p b/man1p/uncompress.1p new file mode 100644 index 000000000..5211168e3 --- /dev/null +++ b/man1p/uncompress.1p @@ -0,0 +1,163 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UNCOMPRESS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" uncompress +.SH NAME +uncompress \- expand compressed data +.SH SYNOPSIS +.LP +\fBuncompress\fP \fB[\fP\fB-cfv\fP\fB][\fP\fIfile\fP\fB...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIuncompress\fP utility shall restore files to their original +state after they have been compressed using the \fIcompress\fP utility. +If no files are specified, the standard input shall be uncompressed +to +the standard output. If the invoking process has appropriate privileges, +the ownership, modes, access time, and modification time +of the original file shall be preserved. +.LP +This utility shall support the uncompressing of any files produced +by the \fIcompress\fP utility on the same implementation. For files +produced by \fIcompress\fP on other systems, \fIuncompress\fP supports +9 to 14-bit compression (see \fIcompress\fP , \fB-b\fP); it is implementation-defined +whether values of \fB-b\fP greater than 14 are +supported. +.SH OPTIONS +.LP +The \fIuncompress\fP utility shall conform to the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-c\fP +Write to standard output; no files are changed. +.TP 7 +\fB-f\fP +Do not prompt for overwriting files. Except when run in the background, +if \fB-f\fP is not given the user shall be prompted as +to whether an existing file should be overwritten. If the standard +input is not a terminal and \fB-f\fP is not given, +\fIuncompress\fP shall write a diagnostic message to standard error +and exit with a status greater than zero. +.TP 7 +\fB-v\fP +Write messages to standard error concerning the expansion of each +file. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a file. If \fIfile\fP already has the \fB.Z\fP suffix +specified, it shall be used as the input file and the +output file shall be named \fBfile\fP with the \fB.Z\fP suffix removed. +Otherwise, \fIfile\fP shall be used as the name of the +output file and \fBfile\fP with the \fB.Z\fP suffix appended shall +be used as the input file. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified, or if a \fIfile\fP operand is \fB'-'\fP +\&. +.SH INPUT FILES +.LP +Input files shall be in the format produced by the \fIcompress\fP +utility. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIuncompress\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +When there are no \fIfile\fP operands or the \fB-c\fP option is specified, +the uncompressed output is written to standard +output. +.SH STDERR +.LP +Prompts shall be written to the standard error output under the conditions +specified in the DESCRIPTION and OPTIONS sections. +The prompts shall contain the \fIfile\fP pathname, but their format +is otherwise unspecified. Otherwise, the standard error output +shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +Output files are the same as the respective input files to \fIcompress\fP. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +The input file remains unmodified. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The limit of 14 on the \fIcompress\fP \fB-b\fP \fIbits\fP argument +is to achieve +portability to all systems (within the restrictions imposed by the +lack of an explicit published file format). Some implementations +based on 16-bit architectures cannot support 15 or 16-bit uncompression. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcompress\fP , \fIzcat\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/unexpand.1p b/man1p/unexpand.1p new file mode 100644 index 000000000..0db58e401 --- /dev/null +++ b/man1p/unexpand.1p @@ -0,0 +1,182 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UNEXPAND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" unexpand +.SH NAME +unexpand \- convert spaces to tabs +.SH SYNOPSIS +.LP +\fBunexpand\fP \fB[\fP \fB-a| -t\fP \fItablist\fP\fB][\fP\fIfile\fP\fB...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIunexpand\fP utility shall copy files or standard input to standard +output, converting s at the beginning of +each line into the maximum number of s followed by the minimum +number of s needed to fill the same column +positions originally filled by the translated s. By default, +tabstops shall be set at every eighth column position. +Each shall be copied to the output, and shall cause the +column position count for tab calculations to be +decremented; the count shall never be decremented to a value less +than one. +.SH OPTIONS +.LP +The \fIunexpand\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-a\fP +In addition to translating s at the beginning of each line, +translate all sequences of two or more s +immediately preceding a tab stop to the maximum number of s followed +by the minimum number of s needed to +fill the same column positions originally filled by the translated +s. +.TP 7 +\fB-t\ \fP \fItablist\fP +Specify the tab stops. The application shall ensure that the \fItablist\fP +option-argument is a single argument consisting of +a single positive decimal integer or multiple positive decimal integers, +separated by s or commas, in ascending order. +If a single number is given, tabs shall be set \fItablist\fP column +positions apart instead of the default 8. If multiple numbers +are given, the tabs shall be set at those specific column positions. +.LP +The application shall ensure that each tab-stop position \fIN\fP is +an integer value greater than zero, and the list shall be +in strictly ascending order. This is taken to mean that, from the +start of a line of output, tabbing to position \fIN\fP shall +cause the next character output to be in the ( \fIN\fP+1)th column +position on that line. When the \fB-t\fP option is not +specified, the default shall be the equivalent of specifying \fB-t\ 8\fP +(except for the interaction with \fB-a\fP, described +below). +.LP +No -to- conversions shall occur for characters at positions +beyond the last of those specified in a +multiple tab-stop list. +.LP +When \fB-t\fP is specified, the presence or absence of the \fB-a\fP +option shall be ignored; conversion shall not be limited +to the processing of leading s. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a text file to be used as input. +.sp +.SH STDIN +.LP +See the INPUT FILES section. +.SH INPUT FILES +.LP +The input files shall be text files. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIunexpand\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), the +processing of s and s, and for the +determination of the width in column positions each character would +occupy on an output device. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall be equivalent to the input files with the +specified -to- conversions. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +One non-intuitive aspect of \fIunexpand\fP is its restriction to leading +spaces when neither \fB-a\fP nor \fB-t\fP is +specified. Users who always want to convert all spaces in a file can +easily alias \fIunexpand\fP to use the \fB-a\fP or +\fB-t\ 8\fP option. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +On several occasions, consideration was given to adding a \fB-t\fP +option to the \fIunexpand\fP utility to complement the +\fB-t\fP in \fIexpand\fP (see \fIexpand\fP ). The historical +intent of \fIunexpand\fP was to translate multiple s into tab +stops, where tab stops were a multiple of eight column +positions on most UNIX systems. An early proposal omitted \fB-t\fP +because it seemed outside the scope of the User Portability +Utilities option; it was not described in any of the base documents. +However, hard-coding tab stops every eight columns was not +suitable for the international community and broke historical precedents +for some vendors in the FORTRAN community, so \fB-t\fP +was restored in conjunction with the list of valid extension categories +considered by the standard developers. Thus, +\fIunexpand\fP is now the logical converse of \fIexpand\fP. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexpand\fP , \fItabs\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/unget.1p b/man1p/unget.1p new file mode 100644 index 000000000..fc8abc5fc --- /dev/null +++ b/man1p/unget.1p @@ -0,0 +1,174 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UNGET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" unget +.SH NAME +unget \- undo a previous get of an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBunget\fP \fB[\fP\fB-ns\fP\fB][\fP\fB-r\fP \fISID\fP\fB]\fP \fIfile\fP\fB... +\fP +.SH DESCRIPTION +.LP +The \fIunget\fP utility shall reverse the effect of a \fIget\fP \fB-e\fP +done prior to +creating the intended new delta. +.SH OPTIONS +.LP +The \fIunget\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-r\ \fP \fISID\fP +Uniquely identify which delta is no longer intended. (This would have +been specified by \fIget\fP as the new delta.) The use of this option +is necessary only if two or more outstanding \fIget\fP commands for +editing on the same SCCS file were done by the same person (login +name). +.TP 7 +\fB-s\fP +Suppress the writing to standard output of the intended delta's SID. +.TP 7 +\fB-n\fP +Retain the file that was obtained by \fIget\fP, which would normally +be removed from the +current directory. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile\fP +A pathname of an existing SCCS file or a directory. If \fIfile\fP +is a directory, the \fIunget\fP utility shall behave as +though each file in the directory were specified as a named file, +except that non-SCCS files (last component of the pathname does +not begin with \fBs.\fP) and unreadable files shall be silently ignored. +.LP +If exactly one \fIfile\fP operand appears, and it is \fB'-'\fP , the +standard input shall be read; each line of the standard +input shall be taken to be the name of an SCCS file to be processed. +Non-SCCS files and unreadable files shall be silently +ignored. +.sp +.SH STDIN +.LP +The standard input shall be a text file used only when the \fIfile\fP +operand is specified as \fB'-'\fP . Each line of the +text file shall be interpreted as an SCCS pathname. +.SH INPUT FILES +.LP +Any SCCS files processed shall be files of an unspecified format. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIunget\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall consist of a line for each file, in the +following format: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fISID removed from file\fP\fB> +\fP +.fi +.RE +.LP +If there is more than one named file or if a directory or standard +input is named, each pathname shall be written before each of +the preceding lines: +.sp +.RS +.nf + +\fB"\\n%s:\\n", <\fP\fIpathname\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +Any SCCS files updated shall be files of an unspecified format. During +processing of a \fIfile\fP, a locking \fIz-file\fP, as +described in \fIget\fP, and a \fIq-file\fP (a working copy of the +\fIp-file\fP), may be +created and deleted. The \fIp-file\fP and \fIg-file\fP, as described +in \fIget\fP, shall be +deleted. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIdelta\fP , \fIget\fP , \fIsact\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/uniq.1p b/man1p/uniq.1p new file mode 100644 index 000000000..3444e72da --- /dev/null +++ b/man1p/uniq.1p @@ -0,0 +1,297 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UNIQ" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" uniq +.SH NAME +uniq \- report or filter out repeated lines in a file +.SH SYNOPSIS +.LP +\fBuniq\fP \fB[\fP\fB-c|-d|-u\fP\fB][\fP\fB-f\fP \fIfields\fP\fB][\fP\fB-s\fP +\fIchar\fP\fB][\fP\fIinput_file\fP \fB[\fP\fIoutput_file\fP\fB]]\fP +.SH DESCRIPTION +.LP +The \fIuniq\fP utility shall read an input file comparing adjacent +lines, and write one copy of each input line on the output. +The second and succeeding copies of repeated adjacent input lines +shall not be written. +.LP +Repeated lines in the input shall not be detected if they are not +adjacent. +.SH OPTIONS +.LP +The \fIuniq\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-c\fP +Precede each output line with a count of the number of times the line +occurred in the input. +.TP 7 +\fB-d\fP +Suppress the writing of lines that are not repeated in the input. +.TP 7 +\fB-f\ \fP \fIfields\fP +Ignore the first \fIfields\fP fields on each input line when doing +comparisons, where \fIfields\fP is a positive decimal +integer. A field is the maximal string matched by the basic regular +expression: +.sp +.RS +.nf + +\fB[[:blank:]]*[^[:blank:]]* +\fP +.fi +.RE +.LP +If the \fIfields\fP option-argument specifies more fields than appear +on an input line, a null string shall be used for +comparison. +.TP 7 +\fB-s\ \fP \fIchars\fP +Ignore the first \fIchars\fP characters when doing comparisons, where +\fIchars\fP shall be a positive decimal integer. If +specified in conjunction with the \fB-f\fP option, the first \fIchars\fP +characters after the first \fIfields\fP fields shall be +ignored. If the \fIchars\fP option-argument specifies more characters +than remain on an input line, a null string shall be used +for comparison. +.TP 7 +\fB-u\fP +Suppress the writing of lines that are repeated in the input. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIinput_file\fP +A pathname of the input file. If the \fIinput_file\fP operand is not +specified, or if the \fIinput_file\fP is \fB'-'\fP , +the standard input shall be used. +.TP 7 +\fIoutput_file\fP +A pathname of the output file. If the \fIoutput_file\fP operand is +not specified, the standard output shall be used. The +results are unspecified if the file named by \fIoutput_file\fP is +the file named by \fIinput_file\fP. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIinput_file\fP operand +is specified or if \fIinput_file\fP is \fB'-'\fP . See +the INPUT FILES section. +.SH INPUT FILES +.LP +The input file shall be a text file. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIuniq\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for ordering rules. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and +which characters constitute a in the current +locale. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall be used only if no \fIoutput_file\fP operand +is specified. See the OUTPUT FILES section. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +If the \fB-c\fP option is specified, the output file shall be empty +or each line shall be of the form: +.sp +.RS +.nf + +\fB"%d %s", <\fP\fInumber of duplicates\fP\fB>, <\fP\fIline\fP\fB> +\fP +.fi +.RE +.LP +otherwise, the output file shall be empty or each line shall be of +the form: +.sp +.RS +.nf + +\fB"%s", <\fP\fIline\fP\fB> +\fP +.fi +.RE +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The utility executed successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fIsort\fP utility can be used to cause repeated lines to be adjacent +in the input +file. +.SH EXAMPLES +.LP +The following input file data (but flushed left) was used for a test +series on \fIuniq\fP: +.sp +.RS +.nf + +\fB#01 foo0 bar0 foo1 bar1 +#02 bar0 foo1 bar1 foo1 +#03 foo0 bar0 foo1 bar1 +#04 +#05 foo0 bar0 foo1 bar1 +#06 foo0 bar0 foo1 bar1 +#07 bar0 foo1 bar1 foo0 +\fP +.fi +.RE +.LP +What follows is a series of test invocations of the \fIuniq\fP utility +that use a mixture of \fIuniq\fP options against the +input file data. These tests verify the meaning of \fIadjacent\fP. +The \fIuniq\fP utility views the input data as a sequence of +strings delimited by \fB'\\n'\fP . Accordingly, for the \fIfields\fPth +member of the sequence, \fIuniq\fP interprets unique or +repeated adjacent lines strictly relative to the \fIfields\fP+1th +member. +.IP " 1." 4 +This first example tests the line counting option, comparing each +line of the input file data starting from the second +field: +.sp +.RS +.nf + +\fBuniq -c -f 1 uniq_0I.t + 1 #01 foo0 bar0 foo1 bar1 + 1 #02 bar0 foo1 bar1 foo0 + 1 #03 foo0 bar0 foo1 bar1 + 1 #04 + 2 #05 foo0 bar0 foo1 bar1 + 1 #07 bar0 foo1 bar1 foo0 +\fP +.fi +.RE +.LP +The number \fB'2'\fP , prefixing the fifth line of output, signifies +that the \fIuniq\fP utility detected a pair of repeated +lines. Given the input data, this can only be true when \fIuniq\fP +is run using the \fB-f\ 1\fP option (which shall cause +\fIuniq\fP to ignore the first field on each input line). +.LP +.IP " 2." 4 +The second example tests the option to suppress unique lines, comparing +each line of the input file data starting from the +second field: +.sp +.RS +.nf + +\fBuniq -d -f 1 uniq_0I.t +#05 foo0 bar0 foo1 bar1 +\fP +.fi +.RE +.LP +.IP " 3." 4 +This test suppresses repeated lines, comparing each line of the input +file data starting from the second field: +.sp +.RS +.nf + +\fBuniq -u -f 1 uniq_0I.t +#01 foo0 bar0 foo1 bar1 +#02 bar0 foo1 bar1 foo1 +#03 foo0 bar0 foo1 bar1 +#04 +#07 bar0 foo1 bar1 foo0 +\fP +.fi +.RE +.LP +.IP " 4." 4 +This suppresses unique lines, comparing each line of the input file +data starting from the third character: +.sp +.RS +.nf + +\fBuniq -d -s 2 uniq_0I.t +\fP +.fi +.RE +.LP +In the last example, the \fIuniq\fP utility found no input matching +the above criteria. +.LP +.SH RATIONALE +.LP +Some historical implementations have limited lines to be 1080 bytes +in length, which does not meet the implied {LINE_MAX} +limit. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcomm\fP , \fIsort\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/unlink.1p b/man1p/unlink.1p new file mode 100644 index 000000000..f27861ae6 --- /dev/null +++ b/man1p/unlink.1p @@ -0,0 +1,124 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UNLINK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" unlink +.SH NAME +unlink \- call the unlink function +.SH SYNOPSIS +.LP +\fBunlink\fP \fIfile\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIunlink\fP utility shall perform the function call: +.sp +.RS +.nf + +\fBunlink(\fP\fIfile\fP\fB); +\fP +.fi +.RE +.LP +A user may need appropriate privilege to invoke the \fIunlink\fP utility. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile\fP +The pathname of an existing file. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +Not used. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIunlink\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +.sp +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +None. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIlink\fP() , \fIrm\fP , the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIunlink\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/unset.1p b/man1p/unset.1p new file mode 100644 index 000000000..4a42f84bd --- /dev/null +++ b/man1p/unset.1p @@ -0,0 +1,142 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UNSET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" unset +.SH NAME +unset \- unset values and attributes of variables and functions +.SH SYNOPSIS +.LP +\fBunset\fP \fB[\fP\fB-fv\fP\fB]\fP \fIname\fP \fB...\fP +.SH DESCRIPTION +.LP +Each variable or function specified by \fIname\fP shall be unset. +.LP +If \fB-v\fP is specified, \fIname\fP refers to a variable name and +the shell shall unset it and remove it from the +environment. Read-only variables cannot be unset. +.LP +If \fB-f\fP is specified, \fIname\fP refers to a function and the +shell shall unset the function definition. +.LP +If neither \fB-f\fP nor \fB-v\fP is specified, \fIname\fP refers to +a variable; if a variable by that name does not exist, it +is unspecified whether a function by that name, if any, shall be unset. +.LP +Unsetting a variable or function that was not previously set shall +not be considered an error and does not cause the shell to +abort. +.LP +The \fIunset\fP special built-in shall support the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +Note that: +.sp +.RS +.nf + +\fBVARIABLE= +\fP +.fi +.RE +.LP +is not equivalent to an \fIunset\fP of \fBVARIABLE\fP; in the example, +\fBVARIABLE\fP is set to \fB""\fP . Also, the +variables that can be \fIunset\fP should not be misinterpreted to +include the special parameters (see \fISpecial Parameters\fP ). +.SH OPTIONS +.LP +See the DESCRIPTION. +.SH OPERANDS +.LP +See the DESCRIPTION. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +None. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.TP 7 +\ 0 +All \fIname\fP operands were successfully unset. +.TP 7 +>0 +At least one \fIname\fP could not be unset. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +Unset \fIVISUAL\fP variable: +.sp +.RS +.nf + +\fBunset -v VISUAL +\fP +.fi +.RE +.LP +Unset the functions \fBfoo\fP and \fBbar\fP: +.sp +.RS +.nf + +\fBunset -f foo bar +\fP +.fi +.RE +.SH RATIONALE +.LP +Consideration was given to omitting the \fB-f\fP option in favor of +an +\fIunfunction\fP utility, but the standard developers decided to retain +historical +practice. +.LP +The \fB-v\fP option was introduced because System V historically used +one name space for both variables and functions. When +\fIunset\fP is used without options, System V historically unset either +a function or a variable, and there was no confusion about +which one was intended. A portable POSIX application can use \fIunset\fP +without an option to unset a variable, but not a +function; the \fB-f\fP option must be used. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISpecial Built-In Utilities\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/uucp.1p b/man1p/uucp.1p new file mode 100644 index 000000000..28b936f8b --- /dev/null +++ b/man1p/uucp.1p @@ -0,0 +1,263 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UUCP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" uucp +.SH NAME +uucp \- system-to-system copy +.SH SYNOPSIS +.LP +\fBuucp\fP \fB[\fP\fB-cCdfjmr\fP\fB][\fP\fB-n\fP \fIuser\fP\fB]\fP +\fIsource-file\fP\fB...\fP \fIdestination-file\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIuucp\fP utility shall copy files named by the \fIsource-file\fP +argument to the \fIdestination-file\fP argument. The +files named can be on local or remote systems. +.LP +The \fIuucp\fP utility cannot guarantee support for all character +encodings in all circumstances. For example, transmission +data may be restricted to 7 bits by the underlying network, 8-bit +data and filenames need not be portable to non-internationalized +systems, and so on. Under these circumstances, it is recommended that +only characters defined in the ISO/IEC\ 646:1991 standard +International Reference Version (equivalent to ASCII) 7-bit range +of characters be used, and that only characters defined in the +portable filename character set be used for naming files. The protocol +for transfer of files is unspecified by +IEEE\ Std\ 1003.1-2001. +.LP +Typical implementations of this utility require a communications line +configured to use the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface, but +other +communications means may be used. On systems where there are no available +communications means (either temporarily or permanently), +this utility shall write an error message describing the problem and +exit with a non-zero exit status. +.SH OPTIONS +.LP +The \fIuucp\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-c\fP +Do not copy local file to the spool directory for transfer to the +remote machine (default). +.TP 7 +\fB-C\fP +Force the copy of local files to the spool directory for transfer. +.TP 7 +\fB-d\fP +Make all necessary directories for the file copy (default). +.TP 7 +\fB-f\fP +Do not make intermediate directories for the file copy. +.TP 7 +\fB-j\fP +Write the job identification string to standard output. This job identification +can be used by \fIuustat\fP to obtain the status or terminate a job. +.TP 7 +\fB-m\fP +Send mail to the requester when the copy is completed. +.TP 7 +\fB-n\ \fP \fIuser\fP +Notify \fIuser\fP on the remote system that a file was sent. +.TP 7 +\fB-r\fP +Do not start the file transfer; just queue the job. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIdestination-file\fP,\ \fIsource-file\fP +.sp +A pathname of a file to be copied to, or from, respectively. Either +name can be a pathname on the local machine, or can have the +form: +.sp +.RS +.nf + +\fIsystem-name\fP\fB!\fP\fIpathname\fP +.fi +.RE +.LP +where \fIsystem-name\fP is taken from a list of system names that +\fIuucp\fP knows about. The destination \fIsystem-name\fP +can also be a list of names such as: +.sp +.RS +.nf + +\fIsystem-name\fP\fB!\fP\fIsystem-name\fP\fB!...!\fP\fIsystem-name\fP\fB!\fP\fIpathname\fP +.fi +.RE +.LP +in which case, an attempt is made to send the file via the specified +route to the destination. Care should be taken to ensure +that intermediate nodes in the route are willing to forward information. +.LP +The shell pattern matching notation characters \fB'?'\fP , \fB'*'\fP +, and \fB"[...]"\fP appearing in \fIpathname\fP +shall be expanded on the appropriate system. +.LP +Pathnames can be one of: +.RS +.IP " 1." 4 +An absolute pathname. +.LP +.IP " 2." 4 +A pathname preceded by ~ \fIuser\fP where \fIuser\fP is a login name +on the specified system and is replaced by that +user's login directory. Note that if an invalid login is specified, +the default is to the public directory (called \fIPUBDIR\fP; +the actual location of \fIPUBDIR\fP is implementation-defined). +.LP +.IP " 3." 4 +A pathname preceded by ~/ \fIdestination\fP where \fIdestination\fP +is appended to \fIPUBDIR\fP. +.TP 7 +\fBNote:\fP +.RS +This destination is treated as a filename unless more than one file +is being transferred by this request or the destination is +already a directory. To ensure that it is a directory, follow the +destination with a \fB'/'\fP . For example, \fB~/dan/\fP +as the destination makes the directory \fBPUBDIR/dan\fP if it does +not exist and puts the requested files in that directory. +.RE +.sp +.LP +.IP " 4." 4 +Anything else shall be prefixed by the current directory. +.LP +.RE +.LP +If the result is an erroneous pathname for the remote system, the +copy shall fail. If the \fIdestination-file\fP is a +directory, the last part of the \fIsource-file\fP name shall be used. +.LP +The read, write, and execute permissions given by \fIuucp\fP are implementation-defined. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +The files to be copied are regular files. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIuucp\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within bracketed +filename patterns. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and +the behavior of character classes within bracketed filename +patterns (for example, \fB"'[[:lower:]]*'"\fP ). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, +and informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +The output files (which may be on other systems) are copies of the +input files. +.LP +If \fB-m\fP is used, mail files are modified. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The domain of remotely accessible files can (and for obvious security +reasons usually should) be severely restricted. +.LP +Note that the \fB'!'\fP character in addresses has to be escaped when +using \fIcsh\fP as a command interpreter because of +its history substitution syntax. For \fIksh\fP and \fIsh\fP the escape +is not necessary, but +may be used. +.LP +As noted above, shell metacharacters appearing in pathnames are expanded +on the appropriate system. On an internationalized +system, this is done under the control of local settings of \fILC_COLLATE\fP +and \fILC_CTYPE .\fP Thus, care should be taken when +using bracketed filename patterns, as collation and typing rules may +vary from one system to another. Also be aware that certain +types of expression (that is, equivalence classes, character classes, +and collating symbols) need not be supported on +non-internationalized systems. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImailx\fP , \fIuuencode\fP , \fIuustat\fP , +\fIuux\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/uudecode.1p b/man1p/uudecode.1p new file mode 100644 index 000000000..3f290bd3f --- /dev/null +++ b/man1p/uudecode.1p @@ -0,0 +1,179 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UUDECODE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" uudecode +.SH NAME +uudecode \- decode a binary file +.SH SYNOPSIS +.LP +\fBuudecode\fP \fB[\fP\fB-o\fP \fIoutfile\fP\fB][\fP\fIfile\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIuudecode\fP utility shall read a file, or standard input if +no file is specified, that includes data created by the \fIuuencode\fP +utility. The \fIuudecode\fP utility shall scan the input file, searching +for +data compatible with one of the formats specified in \fIuuencode\fP, +and attempt to +create or overwrite the file described by the data (or overridden +by the \fB-o\fP option). The pathname shall be contained in the +data or specified by the \fB-o\fP option. The file access permission +bits and contents for the file to be produced shall be +contained in that data. The mode bits of the created file (other than +standard output) shall be set from the file access permission +bits contained in the data; that is, other attributes of the mode, +including the file mode creation mask (see \fIumask\fP() ), shall +not affect the file being produced. +.LP +If the pathname of the file to be produced exists, and the user does +not have write permission on that file, \fIuudecode\fP +shall terminate with an error. If the pathname of the file to be produced +exists, and the user has write permission on that file, +the existing file shall be overwritten. +.LP +If the input data was produced by \fIuuencode\fP on a system with +a different number +of bits per byte than on the target system, the results of \fIuudecode\fP +are unspecified. +.SH OPTIONS +.LP +The \fIuudecode\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported by the implementation: +.TP 7 +\fB-o\ \fP \fIoutfile\fP +A pathname of a file that shall be used instead of any pathname contained +in the input data. Specifying an \fIoutfile\fP +option-argument of \fB/dev/stdout\fP shall indicate standard output. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +The pathname of a file containing the output of \fIuuencode\fP. +.sp +.SH STDIN +.LP +See the INPUT FILES section. +.SH INPUT FILES +.LP +The input files shall be files containing the output of \fIuuencode\fP. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIuudecode\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If the file data header encoded by \fIuuencode\fP is \fB-\fP or \fB/dev/stdout\fP, +or the \fB-o\fP \fB/dev/stdout\fP option overrides the file data, +the standard output shall be in the same format as the file +originally encoded by \fIuuencode\fP. Otherwise, the standard output +shall not be +used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +The output file shall be in the same format as the file originally +encoded by \fIuuencode\fP. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The user who is invoking \fIuudecode\fP must have write permission +on any file being created. +.LP +The output of \fIuuencode\fP is essentially an encoded bit stream +that is not +cognizant of byte boundaries. It is possible that a 9-bit byte target +machine can process input from an 8-bit source, if it is +aware of the requirement, but the reverse is unlikely to be satisfying. +Of course, the only data that is meaningful for such a +transfer between architectures is generally character data. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +Input files are not necessarily text files, as stated by an early +proposal. Although the \fIuuencode\fP output is a text file, that +output could have been wrapped within another file or +mail message that is not a text file. +.LP +The \fB-o\fP option is not historical practice, but was added at the +request of WG15 so that the user could override the target +pathname without having to edit the input data itself. +.LP +In early drafts, the [ \fB-o\fP \fIoutfile\fP] option-argument allowed +the use of \fB-\fP to mean standard output. The symbol +\fB-\fP has only been used previously in IEEE\ Std\ 1003.1-2001 as +a standard input indicator. The developers of the +standard did not wish to overload the meaning of \fB-\fP in this manner. +The \fB/dev/stdout\fP concept exists on most modern +systems. The \fB/dev/stdout\fP syntax does not refer to a new special +file. It is just a magic cookie to specify standard +output. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIumask\fP() , \fIuuencode\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/uuencode.1p b/man1p/uuencode.1p new file mode 100644 index 000000000..3aae92b1f --- /dev/null +++ b/man1p/uuencode.1p @@ -0,0 +1,352 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UUENCODE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" uuencode +.SH NAME +uuencode \- encode a binary file +.SH SYNOPSIS +.LP +\fBuuencode\fP \fB[\fP\fB-m\fP\fB][\fP\fIfile\fP\fB]\fP \fIdecode_pathname\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIuuencode\fP utility shall write an encoded version of the named +input file, or standard input if no \fIfile\fP is +specified, to standard output. The output shall be encoded using one +of the algorithms described in the STDOUT section and shall +include the file access permission bits (in \fIchmod\fP octal or symbolic +notation) of the +input file and the \fIdecode_pathname\fP, for re-creation of the file +on another system that conforms to this volume of +IEEE\ Std\ 1003.1-2001. +.SH OPTIONS +.LP +The \fIuuencode\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported by the implementation: +.TP 7 +\fB-m\fP +Encode the output using the MIME Base64 algorithm described in STDOUT. +If \fB-m\fP is not specified, the historical algorithm +described in STDOUT shall be used. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIdecode_pathname\fP +.sp +The pathname of the file into which the \fIuudecode\fP utility shall +place the decoded +file. Specifying a \fIdecode_pathname\fP operand of \fB/dev/stdout\fP +shall indicate that \fIuudecode\fP is to use standard output. If there +are characters in \fIdecode_pathname\fP that +are not in the portable filename character set the results are unspecified. +.TP 7 +\fIfile\fP +A pathname of the file to be encoded. +.sp +.SH STDIN +.LP +See the INPUT FILES section. +.SH INPUT FILES +.LP +Input files can be files of any type. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIuuencode\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.SS uuencode Base64 Algorithm +.LP +The standard output shall be a text file (encoded in the character +set of the current locale) that begins with the line: +.sp +.RS +.nf + +\fB"begin-base64 %s %s\\n", <\fP\fImode\fP\fB>, <\fP\fIdecode_pathname\fP\fB> +\fP +.fi +.RE +.LP +and ends with the line: +.sp +.RS +.nf + +\fB"====\\n" +\fP +.fi +.RE +.LP +In both cases, the lines shall have no preceding or trailing s. +.LP +The encoding process represents 24-bit groups of input bits as output +strings of four encoded characters. Proceeding from left +to right, a 24-bit input group shall be formed by concatenating three +8-bit input groups. Each 24-bit input group then shall be +treated as four concatenated 6-bit groups, each of which shall be +translated into a single digit in the Base64 alphabet. When +encoding a bit stream via the Base64 encoding, the bit stream shall +be presumed to be ordered with the most-significant bit first. +That is, the first bit in the stream shall be the high-order bit in +the first byte, and the eighth bit shall be the low-order bit +in the first byte, and so on. Each 6-bit group is used as an index +into an array of 64 printable characters, as shown in uuencode Base64 +Values . +.sp +.ce 1 +\fBTable: uuencode Base64 Values\fP +.TS C +center; l1 l1 l1 l1 l1 l1 l1 l1 l1 l1 l. +\fBValue\fP \fBEncoding\fP Value \fBEncoding\fP \fBValue\fP Encoding \fBValue\fP \fBEncoding\fP \ \fB\ \fP \fB\ \fP +0 A 17 R 34 i 51 z \ \ \ +1 B 18 S 35 j 52 0 \ \ \ +2 C 19 T 36 k 53 1 \ \ \ +3 D 20 U 37 l 54 2 \ \ \ +4 E 21 V 38 m 55 3 \ \ \ +5 F 22 W 39 n 56 4 \ \ \ +6 G 23 X 40 o 57 5 \ \ \ +7 H 24 Y 41 p 58 6 \ \ \ +8 I 25 Z 42 q 59 7 \ \ \ +9 J 26 a 43 r 60 8 \ \ \ +10 K 27 b 44 s 61 9 \ \ \ +11 L 28 c 45 t 62 + \ \ \ +12 M 29 d 46 u 63 / \ \ \ +13 N 30 e 47 v \ \ \ \ \ +14 O 31 f 48 w (pad) = \ \ \ +15 P 32 g 49 x \ \ \ \ \ +16 Q 33 h 50 y \ \ \ \ \ +.TE +.LP +The character referenced by the index shall be placed in the output +string. +.LP +The output stream (encoded bytes) shall be represented in lines of +no more than 76 characters each. All line breaks or other +characters not found in the table shall be ignored by decoding software +(see \fIuudecode\fP ). +.LP +Special processing shall be performed if fewer than 24 bits are available +at the end of a message or encapsulated part of a +message. A full encoding quantum shall always be completed at the +end of a message. When fewer than 24 input bits are available in +an input group, zero bits shall be added (on the right) to form an +integral number of 6-bit groups. Output character positions that +are not required to represent actual input data shall be set to the +character \fB'='\fP . Since all Base64 input is an integral +number of octets, only the following cases can arise: +.IP " 1." 4 +The final quantum of encoding input is an integral multiple of 24 +bits; here, the final unit of encoded output shall be an +integral multiple of 4 characters with no \fB'='\fP padding. +.LP +.IP " 2." 4 +The final quantum of encoding input is exactly 16 bits; here, the +final unit of encoded output shall be three characters +followed by one \fB'='\fP padding character. +.LP +.IP " 3." 4 +The final quantum of encoding input is exactly 8 bits; here, the final +unit of encoded output shall be two characters followed +by two \fB'='\fP padding characters. +.LP +.LP +A terminating \fB"===="\fP evaluates to nothing and denotes the end +of the encoded data. +.SS uuencode Historical Algorithm +.LP +The standard output shall be a text file (encoded in the character +set of the current locale) that begins with the line: +.sp +.RS +.nf + +\fB"begin %s %s\\n" <\fP\fImode\fP\fB>, <\fP\fIdecode_pathname\fP\fB> +\fP +.fi +.RE +.LP +and ends with the line: +.sp +.RS +.nf + +\fB"end\\n" +\fP +.fi +.RE +.LP +In both cases, the lines shall have no preceding or trailing s. +.LP +The algorithm that shall be used for lines in between \fBbegin\fP +and \fBend\fP takes three octets as input and writes four +characters of output by splitting the input at six-bit intervals into +four octets, containing data in the lower six bits only. +These octets shall be converted to characters by adding a value of +0x20 to each octet, so that each octet is in the range +[0x20,0x5f], and then it shall be assumed to represent a printable +character in the ISO/IEC\ 646:1991 standard encoded +character set. It then shall be translated into the corresponding +character codes for the codeset in use in the current locale. +(For example, the octet 0x41, representing \fB'A'\fP , would be translated +to \fB'A'\fP in the current codeset, such as 0xc1 +if it were EBCDIC.) +.LP +Where the bits of two octets are combined, the least significant bits +of the first octet shall be shifted left and combined with +the most significant bits of the second octet shifted right. Thus +the three octets \fIA\fP, \fIB\fP, \fIC\fP shall be converted +into the four octets: +.sp +.RS +.nf + +\fB0x20 + (( A >> 2 ) & 0x3F) +0x20 + (((A << 4) | ((B >> 4) & 0xF)) & 0x3F) +0x20 + (((B << 2) | ((C >> 6) & 0x3)) & 0x3F) +0x20 + (( C ) & 0x3F) +\fP +.fi +.RE +.LP +These octets then shall be translated into the local character set. +.LP +Each encoded line contains a length character, equal to the number +of characters to be decoded plus 0x20 translated to the local +character set as described above, followed by the encoded characters. +The maximum number of octets to be encoded on each line shall +be 45. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The file is expanded by 35 percent (each three octets become four, +plus control information) causing it to take longer to +transmit. +.LP +Since this utility is intended to create files to be used for data +interchange between systems with possibly different codesets, +and to represent binary data as a text file, the ISO/IEC\ 646:1991 +standard was chosen for a midpoint in the algorithm as a +known reference point. The output from \fIuuencode\fP is a text file +on the local system. If the output were in the +ISO/IEC\ 646:1991 standard codeset, it might not be a text file (at +least because the s might not match), and +the goal of creating a text file would be defeated. If this text file +was then carried to another machine with the same codeset, it +would be perfectly compatible with that system's \fIuudecode\fP. If +it was transmitted +over a mail system or sent to a machine with a different codeset, +it is assumed that, as for every other text file, some +translation mechanism would convert it (by the time it reached a user +on the other system) into an appropriate codeset. This +translation only makes sense from the local codeset, not if the file +has been put into a ISO/IEC\ 646:1991 standard +representation first. Similarly, files processed by \fIuuencode\fP +can be placed in \fIpax\fP +archives, intermixed with other text files in the same codeset. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +A new algorithm was added at the request of the international community +to parallel work in RFC\ 2045 (MIME). As with the +historical \fIuuencode\fP format, the Base64 Content-Transfer-Encoding +is designed to represent arbitrary sequences of octets in a +form that is not humanly readable. A 65-character subset of the ISO/IEC\ 646:1991 +standard is used, enabling 6 bits to be +represented per printable character. (The extra 65th character, \fB'='\fP +, is used to signify a special processing +function.) +.LP +This subset has the important property that it is represented identically +in all versions of the ISO/IEC\ 646:1991 standard, +including US ASCII, and all characters in the subset are also represented +identically in all versions of EBCDIC. The historical +\fIuuencode\fP algorithm does not share this property, which is the +reason that a second algorithm was added to the +ISO\ POSIX-2 standard. +.LP +The string \fB"===="\fP was used for the termination instead of the +end used in the original format because the latter is a +string that could be valid encoded input. +.LP +In an early draft, the \fB-m\fP option was named \fB-b\fP (for Base64), +but it was renamed to reflect its relationship to the +RFC\ 2045. A \fB-u\fP was also present to invoke the default algorithm, +but since this was not historical practice, it was +omitted as being unnecessary. +.LP +See the RATIONALE section in \fIuudecode\fP for the derivation of +the \fB/dev/stdout\fP +symbol. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchmod\fP() , \fImailx\fP , \fIuudecode\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/uustat.1p b/man1p/uustat.1p new file mode 100644 index 000000000..8de5364b8 --- /dev/null +++ b/man1p/uustat.1p @@ -0,0 +1,159 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UUSTAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" uustat +.SH NAME +uustat \- uucp status inquiry and job control +.SH SYNOPSIS +.LP +\fBuustat\fP \fB[\fP \fB-q| -k\fP \fIjobid\fP\fB| -r\fP \fIjobid\fP\fB]\fP\fB +.br +.sp +uustat\fP \fB[\fP\fB-s\fP \fIsystem\fP\fB][\fP\fB-u\fP \fIuser\fP\fB]\fP\fB\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIuustat\fP utility shall display the status of, or cancel, previously +specified \fIuucp\fP requests, or provide general status on \fIuucp\fP +connections to other systems. +.LP +When no options are given, \fIuustat\fP shall write to standard output +the status of all \fIuucp\fP requests issued by the current user. +.LP +Typical implementations of this utility require a communications line +configured to use the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface, but +other +communications means may be used. On systems where there are no available +communications means (either temporarily or permanently), +this utility shall write an error message describing the problem and +exit with a non-zero exit status. +.SH OPTIONS +.LP +The \fIuustat\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-q\fP +Write the jobs queued for each machine. +.TP 7 +\fB-k\ \fP \fIjobid\fP +Kill the \fIuucp\fP request whose job identification is \fIjobid\fP. +The application +shall ensure that the killed \fIuucp\fP request belongs to the person +invoking \fIuustat\fP +unless that user has appropriate privileges. +.TP 7 +\fB-r\ \fP \fIjobid\fP +Rejuvenate \fIjobid\fP. The files associated with \fIjobid\fP are +touched so that their modification time is set to the +current time. This prevents the cleanup program from deleting the +job until the jobs modification time reaches the limit imposed by +the program. +.TP 7 +\fB-s\ \fP \fIsystem\fP +Write the status of all \fIuucp\fP requests for remote system \fIsystem\fP. +.TP 7 +\fB-u\ \fP \fIuser\fP +Write the status of all \fIuucp\fP requests issued by \fIuser\fP. +.sp +.SH OPERANDS +.LP +None. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIuustat\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, +and informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall consist of information about each job selected, +in an unspecified format. The information shall +include at least the job ID, the user ID or name, and the remote system +name. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIuucp\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/uux.1p b/man1p/uux.1p new file mode 100644 index 000000000..053f98d35 --- /dev/null +++ b/man1p/uux.1p @@ -0,0 +1,295 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UUX" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" uux +.SH NAME +uux \- remote command execution +.SH SYNOPSIS +.LP +\fBuux\fP \fB[\fP\fB-np\fP\fB]\fP \fIcommand-string\fP\fB +.br +.sp +uux\fP \fB[\fP\fB-jnp\fP\fB]\fP \fIcommand-string\fP\fB\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIuux\fP utility shall gather zero or more files from various +systems, execute a shell pipeline (see \fIShell Commands\fP ) on a +specified system, and then send the standard output of the command +to +a file on a specified system. Only the first command of a pipeline +can have a \fIsystem-name\fP! prefix. All other commands in the +pipeline shall be executed on the system of the first command. +.LP +The following restrictions are applicable to the shell pipeline processed +by \fIuux\fP: +.IP " *" 3 +In gathering files from different systems, pathname expansion shall +not be performed by \fIuux\fP. Thus, a request such as: +.sp +.RS +.nf + +\fBuux "c99 remsys!~/*.c" +\fP +.fi +.RE +.LP +would attempt to copy the file named literally \fB*.c\fP to the local +system. +.LP +.IP " *" 3 +The redirection operators \fB">>"\fP , \fB"<<"\fP , \fB">|"\fP , and +\fB">&"\fP shall not be +accepted. Any use of these redirection operators shall cause this +utility to write an error message describing the problem and exit +with a non-zero exit status. +.LP +.IP " *" 3 +The reserved word \fB!\fP cannot be used at the head of the pipeline +to modify the exit status. (See the \fIcommand-string\fP +operand description below.) +.LP +.IP " *" 3 +Alias substitution shall not be performed. +.LP +.LP +A filename can be specified as for \fIuucp\fP; it can be an absolute +pathname, a pathname +preceded by ~ \fIname\fP (which is replaced by the corresponding login +directory), a pathname specified as ~/ +\fIdest\fP ( \fIdest\fP is prefixed by the public directory called +\fIPUBDIR\fP; the actual location of \fIPUBDIR\fP is +implementation-defined), or a simple filename (which is prefixed by +\fIuux\fP with the current directory). See \fIuucp\fP for the details. +.LP +The execution of commands on remote systems shall take place in an +execution directory known to the \fIuucp\fP system. All files required +for the execution shall be put into this directory unless they +already reside on that machine. Therefore, the application shall ensure +that non-local filenames (without path or machine +reference) are unique within the \fIuux\fP request. +.LP +The \fIuux\fP utility shall attempt to get all files to the execution +system. For files that are output files, the application +shall ensure that the filename is escaped using parentheses. +.LP +The remote system shall notify the user by mail if the requested command +on the remote system was disallowed or the files were +not accessible. This notification can be turned off by the \fB-n\fP +option. +.LP +Typical implementations of this utility require a communications line +configured to use the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface, but +other +communications means may be used. On systems where there are no available +communications means (either temporarily or permanently), +this utility shall write an error message describing the problem and +exit with a non-zero exit status. +.LP +The \fIuux\fP utility cannot guarantee support for all character encodings +in all circumstances. For example, transmission data +may be restricted to 7 bits by the underlying network, 8-bit data +and filenames need not be portable to non-internationalized +systems, and so on. Under these circumstances, it is recommended that +only characters defined in the ISO/IEC\ 646:1991 standard +International Reference Version (equivalent to ASCII) 7-bit range +of characters be used and that only characters defined in the +portable filename character set be used for naming files. +.SH OPTIONS +.LP +The \fIuux\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-p\fP +Make the standard input to \fIuux\fP the standard input to the \fIcommand-string\fP. +.TP 7 +\fB-j\fP +Write the job identification string to standard output. This job identification +can be used by \fIuustat\fP to obtain the status or terminate a job. +.TP 7 +\fB-n\fP +Do not notify the user if the command fails. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIcommand-string\fP +.sp +A string made up of one or more arguments that are similar to normal +command arguments, except that the command and any filenames +can be prefixed by \fIsystem-name\fP!. A null \fIsystem-name\fP shall +be interpreted as the local system. +.sp +.SH STDIN +.LP +The standard input shall not be used unless the \fB'-'\fP or \fB-p\fP +option is specified; in those cases, the standard +input shall be made the standard input of the \fIcommand-string\fP. +.SH INPUT FILES +.LP +Input files shall be selected according to the contents of \fIcommand-string\fP. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIuux\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall not be used unless the \fB-j\fP option is +specified; in that case, the job identification string +shall be written to standard output in the following format: +.sp +.RS +.nf + +\fB"%s\\n", <\fP\fIjobid\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +Output files shall be created or written, or both, according to the +contents of \fIcommand-string\fP. +.LP +If \fB-n\fP is not used, mail files shall be modified following any +command or file-access failures on the remote system. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Note that, for security reasons, many installations limit the list +of commands executable on behalf of an incoming request from +\fIuux\fP. Many sites permit little more than the receipt of mail +via \fIuux\fP. +.LP +Any characters special to the command interpreter should be quoted +either by quoting the entire \fIcommand-string\fP or quoting +the special characters as individual arguments. +.LP +As noted in \fIuucp\fP, shell pattern matching notation characters +appearing in pathnames +are expanded on the appropriate local system. This is done under the +control of local settings of \fILC_COLLATE\fP and \fILC_CTYPE +\&.\fP Thus, care should be taken when using bracketed filename patterns, +as collation and typing rules may vary from one system to +another. Also be aware that certain types of expression (that is, +equivalence classes, character classes, and collating symbols) +need not be supported on non-internationalized systems. +.SH EXAMPLES +.IP " 1." 4 +The following command gets \fBfile1\fP from system \fBa\fP and \fBfile2\fP +from system \fBb\fP, executes \fIdiff\fP on the local system, and +puts the results in \fBfile.diff\fP in the local \fIPUBDIR\fP +directory. ( \fIPUBDIR\fP is the \fIuucp\fP public directory on the +local system.) +.sp +.RS +.nf + +\fBuux "!diff a!/usr/file1 b!/a4/file2 >!~/file.diff" +\fP +.fi +.RE +.LP +.IP " 2." 4 +The following command fails because \fIuux\fP places all files copied +to a system in the same working directory. Although the +files \fBxyz\fP are from two different systems, their filenames are +the same and conflict. +.sp +.RS +.nf + +\fBuux "!diff a!/usr1/xyz b!/usr2/xyz >!~/xyz.diff" +\fP +.fi +.RE +.LP +.IP " 3." 4 +The following command succeeds (assuming \fIdiff\fP is permitted on +system \fBa\fP) +because the file local to system \fBa\fP is not copied to the working +directory, and hence does not conflict with the file from +system \fBc\fP. +.sp +.RS +.nf + +\fBuux "a!diff a!/usr/xyz c!/usr/xyz >!~/xyz.diff" +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP , \fIuucp\fP , \fIuuencode\fP , \fIuustat\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/val.1p b/man1p/val.1p new file mode 100644 index 000000000..bc930deb1 --- /dev/null +++ b/man1p/val.1p @@ -0,0 +1,229 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "VAL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" val +.SH NAME +val \- validate SCCS files (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBval - +.br +.sp +val\fP \fB[\fP\fB-s\fP\fB][\fP\fB-m\fP \fIname\fP\fB][\fP\fB-r\fP +\fISID\fP\fB][\fP\fB-y\fP +\fItype\fP\fB]\fP \fIfile\fP\fB... \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIval\fP utility shall determine whether the specified \fIfile\fP +is an SCCS file meeting the characteristics specified +by the options. +.SH OPTIONS +.LP +The \fIval\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that the usage of the \fB'-'\fP +operand is not strictly as intended by the guidelines (that is, reading +options and operands from standard input). +.LP +The following options shall be supported: +.TP 7 +\fB-m\ \fP \fIname\fP +Specify a \fIname\fP, which is compared with the SCCS %\fBM\fP% keyword +in \fIfile\fP; see \fIget\fP +\&. +.TP 7 +\fB-r\ \fP \fISID\fP +Specify a \fISID\fP (SCCS Identification String), an SCCS delta number. +A check shall be made to determine whether the +\fISID\fP is ambiguous (for example, \fB-r\ 1\fP is ambiguous because +it physically does not exist but implies 1.1, 1.2, and +so on, which may exist) or invalid (for example, \fB-r\ 1.0\fP or +\fB-r\ 1.1.0\fP are invalid because neither case can +exist as a valid delta number). If the \fISID\fP is valid and not +ambiguous, a check shall be made to determine whether it +actually exists. +.TP 7 +\fB-s\fP +Silence the diagnostic message normally written to standard output +for any error that is detected while processing each named +file on a given command line. +.TP 7 +\fB-y\ \fP \fItype\fP +Specify a \fItype\fP, which shall be compared with the SCCS %\fBY\fP% +keyword in \fIfile\fP; see \fIget\fP . +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile\fP +A pathname of an existing SCCS file. If exactly one \fIfile\fP operand +appears, and it is \fB'-'\fP , the standard input +shall be read: each line shall be independently processed as if it +were a command line argument list. (However, the line is not +subjected to any of the shell word expansions, such as parameter expansion +or quote removal.) +.sp +.SH STDIN +.LP +The standard input shall be a text file used only when the \fIfile\fP +operand is specified as \fB'-'\fP . +.SH INPUT FILES +.LP +Any SCCS files processed shall be files of an unspecified format. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIval\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, +and informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall consist of informative messages about either: +.IP " 1." 4 +Each file processed +.LP +.IP " 2." 4 +Each command line read from standard input +.LP +.LP +If the standard input is not used, for each \fIfile\fP operand yielding +a discrepancy, the output line shall have the following +format: +.sp +.RS +.nf + +\fB"%s: %s\\n", <\fP\fIpathname\fP\fB>, <\fP\fIunspecified string\fP\fB> +\fP +.fi +.RE +.LP +If standard input is used, a line of input shall be written before +each of the preceding lines for files containing +discrepancies: +.sp +.RS +.nf + +\fB"%s:\\n", <\fP\fIinput line\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +Not used. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The 8-bit code returned by \fIval\fP shall be a disjunction of the +possible errors; that is, it can be interpreted as a bit +string where set bits are interpreted as follows: +.TS C +center; l l l. +0x80 = Missing file argument. +0x40 = Unknown or duplicate option. +0x20 = Corrupted SCCS file. +0x10 = Cannot open file or file not SCCS. +0x08 = \fISID\fP is invalid or ambiguous. +0x04 = \fISID\fP does not exist. +0x02 = %\fBY\fP%, \fB-y\fP mismatch. +0x01 = %\fBM\fP%, \fB-m\fP mismatch. +.TE +.LP +Note that \fIval\fP can process two or more files on a given command +line and can process multiple command lines (when reading +the standard input). In these cases an aggregate code shall be returned: +a logical OR of the codes generated for each command line +and file processed. +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Since the \fIval\fP exit status sets the 0x80 bit, shell applications +checking \fB"$?"\fP cannot tell if it terminated due +to a missing file argument or receipt of a signal. +.SH EXAMPLES +.LP +In a directory with three SCCS files- \fBs.x\fP (of \fBt\fP type "text"), +\fBs.y\fP, and \fBs.z\fP (a corrupted file)-the +following command could produce the output shown: +.sp +.RS +.nf + +\fBval - < can be used to return to command +mode; other uses of are described later +in this section; see Terminate Command or Input Mode . +.SS Initialization in ex and vi +.LP +See \fIInitialization in ex and vi\fP for a description of \fIex\fP +and \fIvi\fP initialization for the \fIvi\fP utility. +.SS Command Descriptions in vi +.LP +The following symbols are used in this reference page to represent +arguments to commands. +.TP 7 +\fIbuffer\fP +See the description of \fIbuffer\fP in the EXTENDED DESCRIPTION section +of the \fIex\fP +utility; see \fICommand Descriptions in ex\fP . +.LP +In open and visual mode, when a command synopsis shows both [ \fIbuffer\fP] +and [ \fIcount\fP] preceding the command name, +they can be specified in either order. +.TP 7 +\fIcount\fP +A positive integer used as an optional argument to most commands, +either to give a repeat count or as a size. This argument is +optional and shall default to 1 unless otherwise specified. +.LP +The Synopsis lines for the \fIvi\fP commands -G, -L, +-R, -], +\fB%\fP, \fB&\fP, \fB^\fP, \fBD\fP, \fBm\fP, \fBM\fP, \fBQ\fP, \fBu\fP, +\fBU\fP, and \fBZZ\fP do not have +\fIcount\fP as an optional argument. Regardless, it shall not be an +error to specify a \fIcount\fP to these commands, and any +specified \fIcount\fP shall be ignored. +.TP 7 +\fImotion\fP +An optional trailing argument used by the \fB!\fP, \fB<\fP, \fB>\fP, +\fBc\fP, \fBd\fP, and \fBy\fP commands, which +is used to indicate the region of text that shall be affected by the +command. The motion can be either one of the command +characters repeated or one of several other \fIvi\fP commands (listed +in the following table). Each of the applicable commands +specifies the region of text matched by repeating the command; each +command that can be used as a motion command specifies the +region of text it affects. +.LP +Commands that take \fImotion\fP arguments operate on either lines +or characters, depending on the circumstances. When operating +on lines, all lines that fall partially or wholly within the text +region specified for the command shall be affected. When +operating on characters, only the exact characters in the specified +text region shall be affected. Each motion command specifies +this individually. +.LP +When commands that may be motion commands are not used as motion commands, +they shall set the current position to the current +line and column as specified. +.LP +The following commands shall be valid cursor motion commands: +.sp +.RS +.nf + +\fB ( - j H + ) $ k L + [[ % l M +-H ]] _ n N +-N { ; t T +-P } ? w W + ^ b B + + e E + | f F + / h G +\fP +.fi +.RE +.LP +Any \fIcount\fP that is specified to a command that has an associated +motion command shall be applied to the motion command. If +a \fIcount\fP is applied to both the command and its associated motion +command, the effect shall be multiplicative. +.sp +.LP +The following symbols are used in this section to specify locations +in the edit buffer: +.TP 7 +\fIcurrent\ character\fP +.sp +The character that is currently indicated by the cursor. +.TP 7 +\fIend\ of\ a\ line\fP +.sp +The point located between the last non- (if any) and the +terminating of a line. For an empty line, +this location coincides with the beginning of the line. +.TP 7 +\fIend\ of\ the\ edit\ buffer\fP +.sp +The location corresponding to the end of the last line in the edit +buffer. +.sp +.LP +The following symbols are used in this section to specify command +actions: +.TP 7 +\fIbigword\fP +In the POSIX locale, \fIvi\fP shall recognize four kinds of \fIbigwords\fP: +.RS +.IP " 1." 4 +A maximal sequence of non- s preceded and followed by s +or the beginning or end of a line or the edit +buffer +.LP +.IP " 2." 4 +One or more sequential blank lines +.LP +.IP " 3." 4 +The first character in the edit buffer +.LP +.IP " 4." 4 +The last non- in the edit buffer +.LP +.RE +.TP 7 +\fIword\fP +In the POSIX locale, \fIvi\fP shall recognize five kinds of words: +.RS +.IP " 1." 4 +A maximal sequence of letters, digits, and underscores, delimited +at both ends by: +.RS +.IP " *" 3 +Characters other than letters, digits, or underscores +.LP +.IP " *" 3 +The beginning or end of a line +.LP +.IP " *" 3 +The beginning or end of the edit buffer +.LP +.RE +.LP +.IP " 2." 4 +A maximal sequence of characters other than letters, digits, underscores, +or s, delimited at both ends by: +.RS +.IP " *" 3 +A letter, digit, underscore +.LP +.IP " *" 3 +s +.LP +.IP " *" 3 +The beginning or end of a line +.LP +.IP " *" 3 +The beginning or end of the edit buffer +.LP +.RE +.LP +.IP " 3." 4 +One or more sequential blank lines +.LP +.IP " 4." 4 +The first character in the edit buffer +.LP +.IP " 5." 4 +The last non- in the edit buffer +.LP +.RE +.TP 7 +\fIsection\ boundary\fP +.sp +A \fIsection boundary\fP is one of the following: +.RS +.IP " 1." 4 +A line whose first character is a +.LP +.IP " 2." 4 +A line whose first character is an open curly brace ( \fB'{'\fP ) +.LP +.IP " 3." 4 +A line whose first character is a period and whose second and third +characters match a two-character pair in the \fBsections\fP +edit option (see \fIed\fP) +.LP +.IP " 4." 4 +A line whose first character is a period and whose only other character +matches the first character of a two-character pair in +the \fBsections\fP edit option, where the second character of the +two-character pair is a +.LP +.IP " 5." 4 +The first line of the edit buffer +.LP +.IP " 6." 4 +The last line of the edit buffer if the last line of the edit buffer +is empty or if it is a \fB]]\fP or \fB}\fP command; +otherwise, the last non- of the last line of the edit buffer +.LP +.RE +.TP 7 +\fIparagraph\ boundary\fP +.sp +A \fIparagraph boundary\fP is one of the following: +.RS +.IP " 1." 4 +A section boundary +.LP +.IP " 2." 4 +A line whose first character is a period and whose second and third +characters match a two-character pair in the +\fBparagraphs\fP edit option (see \fIed\fP) +.LP +.IP " 3." 4 +A line whose first character is a period and whose only other character +matches the first character of a two-character pair in +the \fIparagraphs\fP edit option, where the second character of the +two-character pair is a +.LP +.IP " 4." 4 +One or more sequential blank lines +.LP +.RE +.TP 7 +\fIremembered\ search\ direction\fP +.sp +See the description of \fIremembered search direction\fP in \fIed\fP. +.TP 7 +\fIsentence\ boundary\fP +.sp +A \fIsentence boundary\fP is one of the following: +.RS +.IP " 1." 4 +A paragraph boundary +.LP +.IP " 2." 4 +The first non- that occurs after a paragraph boundary +.LP +.IP " 3." 4 +The first non- that occurs after a period ( \fB'.'\fP ), exclamation +mark ( \fB'!'\fP ), or question mark ( +\fB'?'\fP ), followed by two s or the end of a line; any number +of closing parenthesis ( \fB')'\fP ), closing +brackets ( \fB']'\fP ), double quote ( \fB' ),'\fP or single quote +( \fB'"\fP ) characters can appear between the +punctuation mark and the two s or end-of-line +.LP +.RE +.sp +.LP +In the remainder of the description of the \fIvi\fP utility, the term +"buffer line" refers to a line in the edit buffer and +the term "display line" refers to the line or lines on the display +screen used to display one buffer line. The term "current +line" refers to a specific "buffer line". +.LP +If there are display lines on the screen for which there are no corresponding +buffer lines because they correspond to lines that +would be after the end of the file, they shall be displayed as a single +tilde ( \fB'~'\fP ) character, plus the terminating +. +.LP +The last line of the screen shall be used to report errors or display +informational messages. It shall also be used to display +the input for "line-oriented commands" ( \fB/\fP, \fB?\fP, \fB:\fP, +and \fB!\fP). When a line-oriented command is executed, +the editor shall enter text input mode on the last line on the screen, +using the respective command characters as prompt +characters. (In the case of the \fB!\fP command, the associated motion +shall be entered by the user before the editor enters text +input mode.) The line entered by the user shall be terminated by a +, a non- -V-escaped +, or unescaped . It is unspecified if more characters +than require a display width minus one +column number of screen columns can be entered. +.LP +If any command is executed that overwrites a portion of the screen +other than the last line of the screen (for example, the \fIex\fP +\fBsuspend\fP or \fB!\fP commands), other than the \fIex\fP \fBshell\fP +command, the user shall be prompted for a character before the screen +is +refreshed and the edit session continued. +.LP +s shall take up the number of columns on the screen set by the +\fBtabstop\fP edit option (see \fIed\fP), unless there are less than +that number of columns before the display margin that will cause +the displayed line to be folded; in this case, they shall only take +up the number of columns up to that boundary. +.LP +The cursor shall be placed on the current line and relative to the +current column as specified by each command described in the +following sections. +.LP +In open mode, if the current line is not already displayed, then it +shall be displayed. +.LP +In visual mode, if the current line is not displayed, then the lines +that are displayed shall be expanded, scrolled, or redrawn +to cause an unspecified portion of the current line to be displayed. +If the screen is redrawn, no more than the number of display +lines specified by the value of the \fBwindow\fP edit option shall +be displayed (unless the current line cannot be completely +displayed in the number of display lines specified by the \fBwindow\fP +edit option) and the current line shall be positioned as +close to the center of the displayed lines as possible (within the +constraints imposed by the distance of the line from the +beginning or end of the edit buffer). If the current line is before +the first line in the display and the screen is scrolled, an +unspecified portion of the current line shall be placed on the first +line of the display. If the current line is after the last +line in the display and the screen is scrolled, an unspecified portion +of the current line shall be placed on the last line of the +display. +.LP +In visual mode, if a line from the edit buffer (other than the current +line) does not entirely fit into the lines at the bottom +of the display that are available for its presentation, the editor +may choose not to display any portion of the line. The lines of +the display that do not contain text from the edit buffer for this +reason shall each consist of a single \fB'@'\fP +character. +.LP +In visual mode, the editor may choose for unspecified reasons to not +update lines in the display to correspond to the underlying +edit buffer text. The lines of the display that do not correctly correspond +to text from the edit buffer for this reason shall +consist of a single \fB'@'\fP character (plus the terminating ), +and the -R command shall cause +the editor to update the screen to correctly represent the edit buffer. +.LP +Open and visual mode commands that set the current column set it to +a column position in the display, and not a character +position in the line. In this case, however, the column position in +the display shall be calculated for an infinite width display; +for example, the column related to a character that is part of a line +that has been folded onto additional screen lines will be +offset from the display line column where the buffer line begins, +not from the beginning of a particular display line. +.LP +The display cursor column in the display is based on the value of +the current column, as follows, with each rule applied in +turn: +.IP " 1." 4 +If the current column is after the last display line column used by +the displayed line, the display cursor column shall be set +to the last display line column occupied by the last non- +in the current line; otherwise, the display cursor column +shall be set to the current column. +.LP +.IP " 2." 4 +If the character of which some portion is displayed in the display +line column specified by the display cursor column requires +more than a single display line column: +.RS +.IP " a." 4 +If in text input mode, the display cursor column shall be adjusted +to the first display line column in which any portion of that +character is displayed. +.LP +.IP " b." 4 +Otherwise, the display cursor column shall be adjusted to the last +display line column in which any portion of that character is +displayed. +.LP +.RE +.LP +.LP +The current column shall not be changed by these adjustments to the +display cursor column. +.LP +If an error occurs during the parsing or execution of a \fIvi\fP command: +.IP " *" 3 +The terminal shall be alerted. Execution of the \fIvi\fP command shall +stop, and the cursor (for example, the current line and +column) shall not be further modified. +.LP +.IP " *" 3 +Unless otherwise specified by the following command sections, it is +unspecified whether an informational message shall be +displayed. +.LP +.IP " *" 3 +Any partially entered \fIvi\fP command shall be discarded. +.LP +.IP " *" 3 +If the \fIvi\fP command resulted from a \fBmap\fP expansion, all characters +from that \fBmap\fP expansion shall be discarded, +except as otherwise specified by the \fBmap\fP command (see \fIed\fP). +.LP +.IP " *" 3 +If the \fIvi\fP command resulted from the execution of a buffer, no +further commands caused by the execution of the buffer +shall be executed. +.LP +.SS Page Backwards +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB-B +\fP +.fi +.RE +.sp +.LP +If in open mode, the -B command shall behave identically +to the \fBz\fP command. Otherwise, if the current line +is the first line of the edit buffer, it shall be an error. +.LP +If the \fBwindow\fP edit option is less than 3, display a screen where +the last line of the display shall be some portion +of: +.sp +.RS +.nf + +\fB(\fP\fIcurrent first line\fP\fB) -1 +\fP +.fi +.RE +.LP +otherwise, display a screen where the first line of the display shall +be some portion of: +.sp +.RS +.nf + +\fB(\fP\fIcurrent first line\fP\fB) -\fP \fIcount\fP \fBx ((window edit option) -2) +\fP +.fi +.RE +.LP +If this calculation would result in a line that is before the first +line of the edit buffer, the first line of the display shall +display some portion of the first line of the edit buffer. +.LP +\fICurrent line\fP: If no lines from the previous display remain on +the screen, set to the last line of the display; otherwise, +set to ( \fIline\fP - the number of new lines displayed on this screen). +.LP +\fICurrent column\fP: Set to non- . +.SS Scroll Forward +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB-D +\fP +.fi +.RE +.sp +.LP +If the current line is the last line of the edit buffer, it shall +be an error. +.LP +If no \fIcount\fP is specified, \fIcount\fP shall default to the \fIcount\fP +associated with the previous -D +or -U command. If there was no previous -D or -U +command, \fIcount\fP shall default +to the value of the \fBscroll\fP edit option. +.LP +If in open mode, write lines starting with the line after the current +line, until \fIcount\fP lines or the last line of the +file have been written. +.LP +\fICurrent line\fP: If the current line + \fIcount\fP is past the +last line of the edit buffer, set to the last line of the +edit buffer; otherwise, set to the current line + \fIcount\fP. +.LP +\fICurrent column\fP: Set to non- . +.SS Scroll Forward by Line +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB-E +\fP +.fi +.RE +.sp +.LP +Display the line count lines after the last line currently displayed. +.LP +If the last line of the edit buffer is displayed, it shall be an error. +If there is no line \fIcount\fP lines after the last +line currently displayed, the last line of the display shall display +some portion of the last line of the edit buffer. +.LP +\fICurrent line\fP: Unchanged if the previous current character is +displayed; otherwise, set to the first line displayed. +.LP +\fICurrent column\fP: Unchanged. +.SS Page Forward +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB-F +\fP +.fi +.RE +.sp +.LP +If in open mode, the -F command shall behave identically +to the \fBz\fP command. Otherwise, if the current line +is the last line of the edit buffer, it shall be an error. +.LP +If the \fBwindow\fP edit option is less than 3, display a screen where +the first line of the display shall be some portion +of: +.sp +.RS +.nf + +\fB(\fP\fIcurrent last line\fP\fB) +1 +\fP +.fi +.RE +.LP +otherwise, display a screen where the first line of the display shall +be some portion of: +.sp +.RS +.nf + +\fB(\fP\fIcurrent first line\fP\fB) +\fP \fIcount\fP \fBx ((window edit option) -2) +\fP +.fi +.RE +.LP +If this calculation would result in a line that is after the last +line of the edit buffer, the last line of the display shall +display some portion of the last line of the edit buffer. +.LP +\fICurrent line\fP: If no lines from the previous display remain on +the screen, set to the first line of the display; +otherwise, set to ( \fIline\fP + the number of new lines displayed +on this screen). +.LP +\fICurrent column\fP: Set to non- . +.SS Display Information +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB-G +\fP +.fi +.RE +.sp +.LP +This command shall be equivalent to the \fIex\fP \fBfile\fP command. +.SS Move Cursor Backwards +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB-H +.sp + +\fP\fB[\fP\fIcount\fP\fB]\fP \fBh +.sp + +the current\fP \fIerase\fP \fBcharacter (see stty) +\fP +.fi +.RE +.sp +.LP +If there are no characters before the current character on the current +line, it shall be an error. If there are less than +\fIcount\fP previous characters on the current line, \fIcount\fP shall +be adjusted to the number of previous characters on the +line. +.LP +If used as a motion command: +.IP " 1." 4 +The text region shall be from the character before the starting cursor +up to and including the \fIcount\fPth character before +the starting cursor. +.LP +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Set to ( \fIcolumn\fP - the number of columns +occupied by \fIcount\fP characters ending with the +previous current column). +.SS Move Down +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB +.sp + +\fP\fB[\fP\fIcount\fP\fB]\fP \fB-J +.sp + +\fP\fB[\fP\fIcount\fP\fB]\fP \fB-M +.sp + +\fP\fB[\fP\fIcount\fP\fB]\fP \fB-N +.sp + +\fP\fB[\fP\fIcount\fP\fB]\fP \fBj +.sp + +\fP\fB[\fP\fIcount\fP\fB]\fP \fB +.sp + +\fP\fB[\fP\fIcount\fP\fB]\fP \fB+ +\fP +.fi +.RE +.sp +.LP +If there are less than \fIcount\fP lines after the current line in +the edit buffer, it shall be an error. +.LP +If used as a motion command: +.IP " 1." 4 +The text region shall include the starting line and the next \fIcount\fP +- 1 lines. +.LP +.IP " 2." 4 +Any text copied to a buffer shall be in line mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Set to \fIcurrent line\fP+ \fIcount\fP. +.LP +\fICurrent column\fP: Set to non- for the , +-M, and \fB+\fP commands; +otherwise, unchanged. +.SS Clear and Redisplay +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB-L +\fP +.fi +.RE +.sp +.LP +If in open mode, clear the screen and redisplay the current line. +Otherwise, clear and redisplay the screen. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Move Up +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB-P +.sp + +\fP\fB[\fP\fIcount\fP\fB]\fP \fBk +.sp + +\fP\fB[\fP\fIcount\fP\fB]\fP \fB- +\fP +.fi +.RE +.sp +.LP +If there are less than \fIcount\fP lines before the current line in +the edit buffer, it shall be an error. +.LP +If used as a motion command: +.IP " 1." 4 +The text region shall include the starting line and the previous \fIcount\fP +lines. +.LP +.IP " 2." 4 +Any text copied to a buffer shall be in line mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Set to \fIcurrent line\fP - \fIcount\fP. +.LP +\fICurrent column\fP: Set to non- for the \fB-\fP command; +otherwise, unchanged. +.SS Redraw Screen +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB-R +\fP +.fi +.RE +.sp +.LP +If any lines have been deleted from the display screen and flagged +as deleted on the terminal using the \fB@\fP convention (see +the beginning of the EXTENDED DESCRIPTION section), they shall be +redisplayed to match the contents of the edit buffer. +.LP +It is unspecified whether lines flagged with \fB@\fP because they +do not fit on the terminal display shall be affected. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Scroll Backward +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB-U +\fP +.fi +.RE +.sp +.LP +If the current line is the first line of the edit buffer, it shall +be an error. +.LP +If no \fIcount\fP is specified, \fIcount\fP shall default to the \fIcount\fP +associated with the previous -D +or -U command. If there was no previous -D or -U +command, \fIcount\fP shall default +to the value of the \fBscroll\fP edit option. +.LP +\fICurrent line\fP: If \fIcount\fP is greater than the current line, +set to 1; otherwise, set to the current line - +\fIcount\fP. +.LP +\fICurrent column\fP: Set to non- . +.SS Scroll Backward by Line +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB-Y +\fP +.fi +.RE +.sp +.LP +Display the line \fIcount\fP lines before the first line currently +displayed. +.LP +If the current line is the first line of the edit buffer, it shall +be an error. If this calculation would result in a line that +is before the first line of the edit buffer, the first line of the +display shall display some portion of the first line of the edit +buffer. +.LP +\fICurrent line\fP: Unchanged if the previous current character is +displayed; otherwise, set to the first line displayed. +.LP +\fICurrent column\fP: Unchanged. +.SS Edit the Alternate File +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB-^ +\fP +.fi +.RE +.sp +This command shall be equivalent to the \fIex\fP \fBedit\fP command, +with the alternate +pathname as its argument. +.SS Terminate Command or Input Mode +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB +\fP +.fi +.RE +.sp +.LP +If a partial \fIvi\fP command (as defined by at least one, non- \fIcount\fP +character) has been entered, discard the +\fIcount\fP and the command character(s). +.LP +Otherwise, if no command characters have been entered, and the +was the result of a map expansion, the terminal shall +be alerted and the character shall be discarded, but it shall +not be an error. +.LP +Otherwise, it shall be an error. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Search for tagstring +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB-] +\fP +.fi +.RE +.sp +.LP +If the current character is not a word or , it shall be an +error. +.LP +This command shall be equivalent to the \fIex\fP \fBtag\fP command, +with the argument to +that command defined as follows. +.LP +If the current character is a : +.IP " 1." 4 +Skip all s after the cursor up to the end of the line. +.LP +.IP " 2." 4 +If the end of the line is reached, it shall be an error. +.LP +.LP +Then, the argument to the \fIex\fP \fBtag\fP command shall be the +current character and all +subsequent characters, up to the first non-word character or the end +of the line. +.SS Move Cursor Forward +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB +.sp + +\fP\fB[\fP\fIcount\fP\fB]\fP \fBl\fP (ell) +.fi +.RE +.sp +.LP +If there are less than \fIcount\fP non- s after the cursor +on the current line, \fIcount\fP shall be adjusted +to the number of non- s after the cursor on the line. +.LP +If used as a motion command: +.IP " 1." 4 +If the current or \fIcount\fPth character after the cursor is the +last non- in the line, the text region shall +be comprised of the current character up to and including the last +non- in the line. Otherwise, the text region +shall be from the current character up to, but not including, the +\fIcount\fPth character after the cursor. +.LP +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.LP +.LP +If not used as a motion command: +.LP +If there are no non- s after the current character on the +current line, it shall be an error. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Set to the last column that displays any portion +of the \fIcount\fPth character after the current +character. +.SS Replace Text with Results from Shell Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB!\fP \fImotion shell-commands\fP \fB +\fP +.fi +.RE +.sp +.LP +If the motion command is the \fB!\fP command repeated: +.IP " 1." 4 +If the edit buffer is empty and no \fIcount\fP was supplied, the command +shall be the equivalent of the \fIex\fP \fB:read\fP \fB!\fP command, +with the text input, and no text shall be copied to any +buffer. +.LP +.IP " 2." 4 +Otherwise: +.RS +.IP " a." 4 +If there are less than \fIcount\fP -1 lines after the current line +in the edit buffer, it shall be an error. +.LP +.IP " b." 4 +The text region shall be from the current line up to and including +the next \fIcount\fP -1 lines. +.LP +.RE +.LP +.LP +Otherwise, the text region shall be the lines in which any character +of the text region specified by the motion command +appear. +.LP +Any text copied to a buffer shall be in line mode. +.LP +This command shall be equivalent to the \fIex\fP \fB!\fP command for +the specified +lines. +.SS Move Cursor to End-of-Line +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB$ +\fP +.fi +.RE +.sp +.LP +It shall be an error if there are less than ( \fIcount\fP -1) lines +after the current line in the edit buffer. +.LP +If used as a motion command: +.IP " 1." 4 +If \fIcount\fP is 1: +.RS +.IP " a." 4 +It shall be an error if the line is empty. +.LP +.IP " b." 4 +Otherwise, the text region shall consist of all characters from the +starting cursor to the last non- in the +line, inclusive, and any text copied to a buffer shall be in character +mode. +.LP +.RE +.LP +.IP " 2." 4 +Otherwise, if the starting cursor position is at or before the first +non- in the line, the text region shall +consist of the current and the next \fIcount\fP -1 lines, and any +text saved to a buffer shall be in line mode. +.LP +.IP " 3." 4 +Otherwise, the text region shall consist of all characters from the +starting cursor to the last non- in the line +that is \fIcount\fP -1 lines forward from the current line, and any +text copied to a buffer shall be in character mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Set to the \fIcurrent line\fP + \fIcount\fP-1. +.LP +\fICurrent column\fP: The current column is set to the last display +line column of the last non- in the line, +or column position 1 if the line is empty. +.LP +The current column shall be adjusted to be on the last display line +column of the last non- of the current line +as subsequent commands change the current line, until a command changes +the current column. +.SS Move to Matching Character +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB% +\fP +.fi +.RE +.sp +.LP +If the character at the current position is not a parenthesis, bracket, +or curly brace, search forward in the line to the first +one of those characters. If no such character is found, it shall be +an error. +.LP +The matching character shall be the parenthesis, bracket, or curly +brace matching the parenthesis, bracket, or curly brace, +respectively, that was at the current position or that was found on +the current line. +.LP +Matching shall be determined as follows, for an open parenthesis: +.IP " 1." 4 +Set a counter to 1. +.LP +.IP " 2." 4 +Search forwards until a parenthesis is found or the end of the edit +buffer is reached. +.LP +.IP " 3." 4 +If the end of the edit buffer is reached, it shall be an error. +.LP +.IP " 4." 4 +If an open parenthesis is found, increment the counter by 1. +.LP +.IP " 5." 4 +If a close parenthesis is found, decrement the counter by 1. +.LP +.IP " 6." 4 +If the counter is zero, the current character is the matching character. +.LP +.LP +Matching for a close parenthesis shall be equivalent, except that +the search shall be backwards, from the starting character to +the beginning of the buffer, a close parenthesis shall increment the +counter by 1, and an open parenthesis shall decrement the +counter by 1. +.LP +Matching for brackets and curly braces shall be equivalent, except +that searching shall be done for open and close brackets or +open and close curly braces. It is implementation-defined whether +other characters are searched for and matched as well. +.LP +If used as a motion command: +.IP " 1." 4 +If the matching cursor was after the starting cursor in the edit buffer, +and the starting cursor position was at or before the +first non- non- in the starting line, and the matching +cursor position was at or after the last non- + non- in the matching line, the text region shall +consist of the current line to the matching line, +inclusive, and any text copied to a buffer shall be in line mode. +.LP +.IP " 2." 4 +If the matching cursor was before the starting cursor in the edit +buffer, and the starting cursor position was at or after the +last non- non- in the starting line, and the matching +cursor position was at or before the first non- + non- in the matching line, the text region shall +consist of the current line to the matching line, +inclusive, and any text copied to a buffer shall be in line mode. +.LP +.IP " 3." 4 +Otherwise, the text region shall consist of the starting character +to the matching character, inclusive, and any text copied to +a buffer shall be in character mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Set to the line where the matching character is +located. +.LP +\fICurrent column\fP: Set to the last column where any portion of +the matching character is displayed. +.SS Repeat Substitution +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB& +\fP +.fi +.RE +.sp +.LP +Repeat the previous substitution command. This command shall be equivalent +to the \fIex\fP +\fB&\fP command with the current line as its addresses, and without +\fIoptions\fP, \fIcount\fP, or \fIflags\fP. +.SS Return to Previous Context at Beginning of Line +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB'\fP \fIcharacter\fP +.fi +.RE +.sp +.LP +It shall be an error if there is no line in the edit buffer marked +by \fIcharacter\fP. +.LP +If used as a motion command: +.IP " 1." 4 +If the starting cursor is after the marked cursor, then the locations +of the starting cursor and the marked cursor in the edit +buffer shall be logically swapped. +.LP +.IP " 2." 4 +The text region shall consist of the starting line up to and including +the marked line, and any text copied to a buffer shall be +in line mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Set to the line referenced by the mark. +.LP +\fICurrent column\fP: Set to non- . +.SS Return to Previous Context +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB`\fP \fIcharacter\fP +.fi +.RE +.sp +.LP +It shall be an error if the marked line is no longer in the edit buffer. +If the marked line no longer contains a character in +the saved numbered character position, it shall be as if the marked +position is the first non- . +.LP +If used as a motion command: +.IP " 1." 4 +It shall be an error if the marked cursor references the same character +in the edit buffer as the starting cursor. +.LP +.IP " 2." 4 +If the starting cursor is after the marked cursor, then the locations +of the starting cursor and the marked cursor in the edit +buffer shall be logically swapped. +.LP +.IP " 3." 4 +If the starting line is empty or the starting cursor is at or before +the first non- non- of the +starting line, and the marked cursor line is empty or the marked cursor +references the first character of the marked cursor line, +the text region shall consist of all lines containing characters from +the starting cursor to the line before the marked cursor +line, inclusive, and any text copied to a buffer shall be in line +mode. +.LP +.IP " 4." 4 +Otherwise, if the marked cursor line is empty or the marked cursor +references a character at or before the first non- + non- of the marked cursor line, the region of text +shall be from the starting cursor to the last non- + of the line before the marked cursor line, inclusive, and +any text copied to a buffer shall be in character +mode. +.LP +.IP " 5." 4 +Otherwise, the region of text shall be from the starting cursor (inclusive), +to the marked cursor (exclusive), and any text +copied to a buffer shall be in character mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Set to the line referenced by the mark. +.LP +\fICurrent column\fP: Set to the last column in which any portion +of the character referenced by the mark is displayed. +.SS Return to Previous Section +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB[[ +\fP +.fi +.RE +.sp +.LP +Move the cursor backward through the edit buffer to the first character +of the previous section boundary, \fIcount\fP +times. +.LP +If used as a motion command: +.IP " 1." 4 +If the starting cursor was at the first character of the starting +line or the starting line was empty, and the first character +of the boundary was the first character of the boundary line, the +text region shall consist of the current line up to and including +the line where the \fIcount\fPth next boundary starts, and any text +copied to a buffer shall be in line mode. +.LP +.IP " 2." 4 +If the boundary was the last line of the edit buffer or the last non- + of the last line of the edit buffer, the +text region shall consist of the last character in the edit buffer +up to and including the starting character, and any text saved +to a buffer shall be in character mode. +.LP +.IP " 3." 4 +Otherwise, the text region shall consist of the starting character +up to but not including the first character in the +\fIcount\fPth next boundary, and any text copied to a buffer shall +be in character mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Set to the line where the \fIcount\fPth next boundary +in the edit buffer starts. +.LP +\fICurrent column\fP: Set to the last column in which any portion +of the first character of the \fIcount\fPth next boundary is +displayed, or column position 1 if the line is empty. +.SS Move to Next Section +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB]] +\fP +.fi +.RE +.sp +.LP +Move the cursor forward through the edit buffer to the first character +of the next section boundary, \fIcount\fP times. +.LP +If used as a motion command: +.IP " 1." 4 +If the starting cursor was at the first character of the starting +line or the starting line was empty, and the first character +of the boundary was the first character of the boundary line, the +text region shall consist of the current line up to and including +the line where the \fIcount\fPth previous boundary starts, and any +text copied to a buffer shall be in line mode. +.LP +.IP " 2." 4 +If the boundary was the first line of the edit buffer, the text region +shall consist of the first character in the edit buffer +up to but not including the starting character, and any text copied +to a buffer shall be in character mode. +.LP +.IP " 3." 4 +Otherwise, the text region shall consist of the first character in +the \fIcount\fPth previous section boundary up to but not +including the starting character, and any text copied to a buffer +shall be in character mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Set to the line where the \fIcount\fPth previous +boundary in the edit buffer starts. +.LP +\fICurrent column\fP: Set to the last column in which any portion +of the first character of the \fIcount\fPth previous +boundary is displayed, or column position 1 if the line is empty. +.SS Move to First Non- Position on Current Line +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB^ +\fP +.fi +.RE +.sp +If used as a motion command: +.IP " 1." 4 +If the line has no non- non- s, or if the cursor +is at the first non- non- + of the line, it shall be an error. +.LP +.IP " 2." 4 +If the cursor is before the first non- non- of the +line, the text region shall be comprised of the +current character, up to, but not including, the first non- +non- of the line. +.LP +.IP " 3." 4 +If the cursor is after the first non- non- of the +line, the text region shall be from the +character before the starting cursor up to and including the first +non- non- of the line. +.LP +.IP " 4." 4 +Any text copied to a buffer shall be in character mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Set to non- . +.SS Current and Line Above +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB_ +\fP +.fi +.RE +.sp +.LP +If there are less than \fIcount\fP -1 lines after the current line +in the edit buffer, it shall be an error. +.LP +If used as a motion command: +.IP " 1." 4 +If \fIcount\fP is less than 2, the text region shall be the current +line. +.LP +.IP " 2." 4 +Otherwise, the text region shall include the starting line and the +next \fIcount\fP -1 lines. +.LP +.IP " 3." 4 +Any text copied to a buffer shall be in line mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Set to current line + \fIcount\fP -1. +.LP +\fICurrent column\fP: Set to non- . +.SS Move Back to Beginning of Sentence +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB( +\fP +.fi +.RE +.sp +.LP +Move backward to the beginning of a sentence. This command shall be +equivalent to the \fB[[\fP command, with the exception that +sentence boundaries shall be used instead of section boundaries. +.SS Move Forward to Beginning of Sentence +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB) +\fP +.fi +.RE +.sp +.LP +Move forward to the beginning of a sentence. This command shall be +equivalent to the \fB]]\fP command, with the exception that +sentence boundaries shall be used instead of section boundaries. +.SS Move Back to Preceding Paragraph +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB{ +\fP +.fi +.RE +.sp +.LP +Move back to the beginning of the preceding paragraph. This command +shall be equivalent to the \fB[[\fP command, with the +exception that paragraph boundaries shall be used instead of section +boundaries. +.SS Move Forward to Next Paragraph +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB} +\fP +.fi +.RE +.sp +.LP +Move forward to the beginning of the next paragraph. This command +shall be equivalent to the \fB]]\fP command, with the +exception that paragraph boundaries shall be used instead of section +boundaries. +.SS Move to Specific Column Position +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB| +\fP +.fi +.RE +.sp +.LP +For the purposes of this command, lines that are too long for the +current display and that have been folded shall be treated as +having a single, 1-based, number of columns. +.LP +If there are less than \fIcount\fP columns in which characters from +the current line are displayed on the screen, \fIcount\fP +shall be adjusted to be the last column in which any portion of the +line is displayed on the screen. +.LP +If used as a motion command: +.IP " 1." 4 +If the line is empty, or the cursor character is the same as the character +on the \fIcount\fPth column of the line, it shall be +an error. +.LP +.IP " 2." 4 +If the cursor is before the \fIcount\fPth column of the line, the +text region shall be comprised of the current character, up +to but not including the character on the \fIcount\fPth column of +the line. +.LP +.IP " 3." 4 +If the cursor is after the \fIcount\fPth column of the line, the text +region shall be from the character before the starting +cursor up to and including the character on the \fIcount\fPth column +of the line. +.LP +.IP " 4." 4 +Any text copied to a buffer shall be in character mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Set to the last column in which any portion +of the character that is displayed in the \fIcount\fP column +of the line is displayed. +.SS Reverse Find Character +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB, +\fP +.fi +.RE +.sp +.LP +If the last \fBF\fP, \fBf\fP, \fBT\fP, or \fBt\fP command was \fBF\fP, +\fBf\fP, \fBT\fP, or \fBt\fP, this command shall +be equivalent to an \fBf\fP, \fBF\fP, \fBt\fP, or \fBT\fP command, +respectively, with the specified \fIcount\fP and the same +search character. +.LP +If there was no previous \fBF\fP, \fBf\fP, \fBT\fP, or \fBt\fP command, +it shall be an error. +.SS Repeat +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB. +\fP +.fi +.RE +.sp +.LP +Repeat the last \fB!\fP, \fB<\fP, \fB>\fP, \fBA\fP, \fBC\fP, \fBD\fP, +\fBI\fP, \fBJ\fP, \fBO\fP, \fBP\fP, +\fBR\fP, \fBS\fP, \fBX\fP, \fBY\fP, \fBa\fP, \fBc\fP, \fBd\fP, \fBi\fP, +\fBo\fP, \fBp\fP, \fBr\fP, \fBs\fP, \fBx\fP, +\fBy\fP, or \fB~\fP command. It shall be an error if none of these +commands have been executed. Commands (other than +commands that enter text input mode) executed as a result of map expansions, +shall not change the value of the last repeatable +command. +.LP +Repeated commands with associated motion commands shall repeat the +motion command as well; however, any specified \fIcount\fP +shall replace the \fIcount\fP(s) that were originally specified to +the repeated command or its associated motion command. +.LP +If the motion component of the repeated command is \fBf\fP, \fBF\fP, +\fBt\fP, or \fBT\fP, the repeated command shall not set +the remembered search character for the \fB;\fP and \fB,\fP commands. +.LP +If the repeated command is \fBp\fP or \fBP\fP, and the buffer associated +with that command was a numeric buffer named with a +number less than 9, the buffer associated with the repeated command +shall be set to be the buffer named by the name of the previous +buffer logically incremented by 1. +.LP +If the repeated character is a text input command, the input text +associated with that command is repeated literally: +.IP " *" 3 +Input characters are neither macro or abbreviation-expanded. +.LP +.IP " *" 3 +Input characters are not interpreted in any special way with the exception +that , , and +-T behave as described in Input Mode Commands in vi . +.LP +.LP +\fICurrent line\fP: Set as described for the repeated command. +.LP +\fICurrent column\fP: Set as described for the repeated command. +.SS Find Regular Expression +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB/ +\fP +.fi +.RE +.sp +.LP +If the input line contains no non- s, it shall be equivalent +to a line containing only the last regular +expression encountered. The enhanced regular expressions supported +by \fIvi\fP are described in \fIRegular Expressions in ex\fP . +.LP +Otherwise, the line shall be interpreted as one or more regular expressions, +optionally followed by an address offset or a +\fIvi\fP \fBz\fP command. +.LP +If the regular expression is not the last regular expression on the +line, or if a line offset or \fBz\fP command is specified, +the regular expression shall be terminated by an unescaped \fB'/'\fP +character, which shall not be used as part of the regular +expression. If the regular expression is not the first regular expression +on the line, it shall be preceded by zero or more +s, a semicolon, zero or more s, and a leading \fB'/'\fP +character, which shall not be interpreted as +part of the regular expression. It shall be an error to precede any +regular expression with any characters other than these. +.LP +Each search shall begin from the character after the first character +of the last match (or, if it is the first search, after the +cursor). If the \fBwrapscan\fP edit option is set, the search shall +continue to the character before the starting cursor +character; otherwise, to the end of the edit buffer. It shall be an +error if any search fails to find a match, and an informational +message to this effect shall be displayed. +.LP +An optional address offset (see \fIAddressing in ex\fP ) can be specified +after the last +regular expression by including a trailing \fB'/'\fP character after +the regular expression and specifying the address offset. +This offset will be from the line containing the match for the last +regular expression specified. It shall be an error if the line +offset would indicate a line address less than 1 or greater than the +last line in the edit buffer. An address offset of zero shall +be supported. It shall be an error to follow the address offset with +any other characters than s. +.LP +If not used as a motion command, an optional \fBz\fP command (see +Redraw Window ) can be +specified after the last regular expression by including a trailing +\fB'/'\fP character after the regular expression, zero or +more s, a \fB'z'\fP , zero or more s, an optional new +\fBwindow\fP edit option value, zero or more +s, and a location character. The effect shall be as if the +\fBz\fP command was executed after the \fB/\fP command. +It shall be an error to follow the \fBz\fP command with any other +characters than s. +.LP +The remembered search direction shall be set to forward. +.LP +If used as a motion command: +.IP " 1." 4 +It shall be an error if the last match references the same character +in the edit buffer as the starting cursor. +.LP +.IP " 2." 4 +If any address offset is specified, the last match shall be adjusted +by the specified offset as described previously. +.LP +.IP " 3." 4 +If the starting cursor is after the last match, then the locations +of the starting cursor and the last match in the edit buffer +shall be logically swapped. +.LP +.IP " 4." 4 +If any address offset is specified, the text region shall consist +of all lines containing characters from the starting cursor to +the last match line, inclusive, and any text copied to a buffer shall +be in line mode. +.LP +.IP " 5." 4 +Otherwise, if the starting line is empty or the starting cursor is +at or before the first non- non- + of the starting line, and the last match line is empty or +the last match starts at the first character of the last +match line, the text region shall consist of all lines containing +characters from the starting cursor to the line before the last +match line, inclusive, and any text copied to a buffer shall be in +line mode. +.LP +.IP " 6." 4 +Otherwise, if the last match line is empty or the last match begins +at a character at or before the first non- +non- of the last match line, the region of text shall be +from the current cursor to the last non- +of the line before the last match line, inclusive, and any text copied +to a buffer shall be in character mode. +.LP +.IP " 7." 4 +Otherwise, the region of text shall be from the current cursor (inclusive), +to the first character of the last match +(exclusive), and any text copied to a buffer shall be in character +mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: If a match is found, set to the last matched line +plus the address offset, if any; otherwise, +unchanged. +.LP +\fICurrent column\fP: Set to the last column on which any portion +of the first character in the last matched string is +displayed, if a match is found; otherwise, unchanged. +.SS Move to First Character in Line +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB0 \fP (zero) +.fi +.RE +.sp +.LP +Move to the first character on the current line. The character \fB'0'\fP +shall not be interpreted as a command if it is +immediately preceded by a digit. +.LP +If used as a motion command: +.IP " 1." 4 +If the cursor character is the first character in the line, it shall +be an error. +.LP +.IP " 2." 4 +The text region shall be from the character before the cursor character +up to and including the first character in the line. +.LP +.IP " 3." 4 +Any text copied to a buffer shall be in character mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: The last column in which any portion of the +first character in the line is displayed, or if the line is +empty, unchanged. +.SS Execute an ex Command +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB: +\fP +.fi +.RE +.sp +.LP +Execute one or more \fIex\fP commands. +.LP +If any portion of the screen other than the last line of the screen +was overwritten by any \fIex\fP command (except \fBshell\fP), \fIvi\fP +shall display a message indicating that it is waiting +for an input from the user, and shall then read a character. This +action may also be taken for other, unspecified reasons. +.LP +If the next character entered is a \fB':'\fP , another \fIex\fP command +shall be accepted +and executed. Any other character shall cause the screen to be refreshed +and \fIvi\fP shall return to command mode. +.LP +\fICurrent line\fP: As specified for the \fIex\fP command. +.LP +\fICurrent column\fP: As specified for the \fIex\fP command. +.SS Repeat Find +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB; +\fP +.fi +.RE +.sp +.LP +This command shall be equivalent to the last \fBF\fP, \fBf\fP, \fBT\fP, +or \fBt\fP command, with the specified \fIcount\fP, +and with the same search character used for the last \fBF\fP, \fBf\fP, +\fBT\fP, or \fBt\fP command. If there was no previous +\fBF\fP, \fBf\fP, \fBT\fP, or \fBt\fP command, it shall be an error. +.SS Shift Left +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB<\fP \fImotion\fP +.fi +.RE +.sp +.LP +If the motion command is the \fB<\fP command repeated: +.IP " 1." 4 +If there are less than \fIcount\fP -1 lines after the current line +in the edit buffer, it shall be an error. +.LP +.IP " 2." 4 +The text region shall be from the current line, up to and including +the next \fIcount\fP -1 lines. +.LP +.LP +Shift any line in the text region specified by the \fIcount\fP and +motion command one shiftwidth (see the \fIex\fP \fBshiftwidth\fP option) +toward the start of the line, as described by the \fIex\fP \fB<\fP +command. The unshifted lines shall be copied to the unnamed buffer +in line +mode. +.LP +\fICurrent line\fP: If the motion was from the current cursor position +toward the end of the edit buffer, unchanged. Otherwise, +set to the first line in the edit buffer that is part of the text +region specified by the motion command. +.LP +\fICurrent column\fP: Set to non- . +.SS Shift Right +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB>\fP \fImotion\fP +.fi +.RE +.sp +.LP +If the motion command is the \fB>\fP command repeated: +.IP " 1." 4 +If there are less than \fIcount\fP -1 lines after the current line +in the edit buffer, it shall be an error. +.LP +.IP " 2." 4 +The text region shall be from the current line, up to and including +the next \fIcount\fP -1 lines. +.LP +.LP +Shift any line with characters in the text region specified by the +\fIcount\fP and motion command one shiftwidth (see the \fIex\fP \fBshiftwidth\fP +option) away from the start of the line, as described by the \fIex\fP +\fB>\fP command. The unshifted lines shall be copied into the unnamed +buffer in line +mode. +.LP +\fICurrent line\fP: If the motion was from the current cursor position +toward the end of the edit buffer, unchanged. Otherwise, +set to the first line in the edit buffer that is part of the text +region specified by the motion command. +.LP +\fICurrent column\fP: Set to non- . +.SS Scan Backwards for Regular Expression +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB? +\fP +.fi +.RE +.sp +.LP +Scan backwards; the \fB?\fP command shall be equivalent to the \fB/\fP +command (see Find Regular +Expression ) with the following exceptions: +.IP " 1." 4 +The input prompt shall be a \fB'?'\fP . +.LP +.IP " 2." 4 +Each search shall begin from the character before the first character +of the last match (or, if it is the first search, the +character before the cursor character). +.LP +.IP " 3." 4 +The search direction shall be from the cursor toward the beginning +of the edit buffer, and the \fBwrapscan\fP edit option shall +affect whether the search wraps to the end of the edit buffer and +continues. +.LP +.IP " 4." 4 +The remembered search direction shall be set to backward. +.LP +.SS Execute +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB@\fP\fIbuffer\fP +.fi +.RE +.sp +.LP +If the \fIbuffer\fP is specified as \fB@\fP, the last buffer executed +shall be used. If no previous buffer has been executed, +it shall be an error. +.LP +Behave as if the contents of the named buffer were entered as standard +input. After each line of a line-mode buffer, and all but +the last line of a character mode buffer, behave as if a +were entered as standard input. +.LP +If an error occurs during this process, an error message shall be +written, and no more characters resulting from the execution +of this command shall be processed. +.LP +If a \fIcount\fP is specified, behave as if that count were entered +as user input before the characters from the \fB@\fP +buffer were entered. +.LP +\fICurrent line\fP: As specified for the individual commands. +.LP +\fICurrent column\fP: As specified for the individual commands. +.SS Reverse Case +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fB~ +\fP +.fi +.RE +.sp +.LP +Reverse the case of the current character and the next \fIcount\fP +-1 characters, such that lowercase characters that have +uppercase counterparts shall be changed to uppercase characters, and +uppercase characters that have lowercase counterparts shall be +changed to lowercase characters, as prescribed by the current locale. +No other characters shall be affected by this command. +.LP +If there are less than \fIcount\fP -1 characters after the cursor +in the edit buffer, \fIcount\fP shall be adjusted to the +number of characters after the cursor in the edit buffer minus 1. +.LP +For the purposes of this command, the next character after the last +non- on the line shall be the next character +in the edit buffer. +.LP +\fICurrent line\fP: Set to the line including the ( \fIcount\fP-1)th +character after the cursor. +.LP +\fICurrent column\fP: Set to the last column in which any portion +of the ( \fIcount\fP-1)th character after the cursor is +displayed. +.SS Append +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBa +\fP +.fi +.RE +.sp +.LP +Enter text input mode after the current cursor position. No characters +already in the edit buffer shall be affected by this +command. A \fIcount\fP shall cause the input text to be appended \fIcount\fP +-1 more times to the end of the input. +.LP +\fICurrent line/column\fP: As specified for the text input commands +(see Input Mode Commands in +vi ). +.SS Append at End-of-Line +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBA +\fP +.fi +.RE +.sp +.LP +This command shall be equivalent to the \fIvi\fP command: +.sp +.RS +.nf + +\fB$\fP \fB[\fP \fIcount\fP \fB]\fP \fBa +\fP +.fi +.RE +.LP +(see Append ). +.SS Move Backward to Preceding Word +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBb +\fP +.fi +.RE +.sp +.LP +With the exception that words are used as the delimiter instead of +bigwords, this command shall be equivalent to the \fBB\fP +command. +.SS Move Backward to Preceding Bigword +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBB +\fP +.fi +.RE +.sp +.LP +If the edit buffer is empty or the cursor is on the first character +of the edit buffer, it shall be an error. If less than +\fIcount\fP bigwords begin between the cursor and the start of the +edit buffer, \fIcount\fP shall be adjusted to the number of +bigword beginnings between the cursor and the start of the edit buffer. +.LP +If used as a motion command: +.IP " 1." 4 +The text region shall be from the first character of the \fIcount\fPth +previous bigword beginning up to but not including the +cursor character. +.LP +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Set to the line containing the \fIcurrent column\fP. +.LP +\fICurrent column\fP: Set to the last column upon which any part of +the first character of the \fIcount\fPth previous bigword +is displayed. +.SS Change +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB]\fP \fBc\fP \fImotion\fP +.fi +.RE +.sp +.LP +If the motion command is the \fBc\fP command repeated: +.IP " 1." 4 +The buffer text shall be in line mode. +.LP +.IP " 2." 4 +If there are less than \fIcount\fP -1 lines after the current line +in the edit buffer, it shall be an error. +.LP +.IP " 3." 4 +The text region shall be from the current line up to and including +the next \fIcount\fP -1 lines. +.LP +.LP +Otherwise, the buffer text mode and text region shall be as specified +by the motion command. +.LP +The replaced text shall be copied into \fIbuffer\fP, if specified, +and into the unnamed buffer. If the text to be replaced +contains characters from more than a single line, or the buffer text +is in line mode, the replaced text shall be copied into the +numeric buffers as well. +.LP +If the buffer text is in line mode: +.IP " 1." 4 +Any lines that contain characters in the region shall be deleted, +and the editor shall enter text input mode at the beginning of +a new line which shall replace the first line deleted. +.LP +.IP " 2." 4 +If the \fBautoindent\fP edit option is set, \fBautoindent\fP characters +equal to the \fBautoindent\fP characters on the first +line deleted shall be inserted as if entered by the user. +.LP +.LP +Otherwise, if characters from more than one line are in the region +of text: +.IP " 1." 4 +The text shall be deleted. +.LP +.IP " 2." 4 +Any text remaining in the last line in the text region shall be appended +to the first line in the region, and the last line in +the region shall be deleted. +.LP +.IP " 3." 4 +The editor shall enter text input mode after the last character not +deleted from the first line in the text region, if any; +otherwise, on the first column of the first line in the region. +.LP +.LP +Otherwise: +.IP " 1." 4 +If the glyph for \fB'$'\fP is smaller than the region, the end of +the region shall be marked with a \fB'$'\fP . +.LP +.IP " 2." 4 +The editor shall enter text input mode, overwriting the region of +text. +.LP +.LP +\fICurrent line/column\fP: As specified for the text input commands +(see Input Mode Commands in +vi ). +.SS Change to End-of-Line +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB]\fP \fBC +\fP +.fi +.RE +.sp +.LP +This command shall be equivalent to the \fIvi\fP command: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB]\fP \fBc$ +\fP +.fi +.RE +.LP +See the \fBc\fP command. +.SS Delete +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB]\fP \fBd\fP \fImotion\fP +.fi +.RE +.sp +.LP +If the motion command is the \fBd\fP command repeated: +.IP " 1." 4 +The buffer text shall be in line mode. +.LP +.IP " 2." 4 +If there are less than \fIcount\fP -1 lines after the current line +in the edit buffer, it shall be an error. +.LP +.IP " 3." 4 +The text region shall be from the current line up to and including +the next \fIcount\fP -1 lines. +.LP +.LP +Otherwise, the buffer text mode and text region shall be as specified +by the motion command. +.LP +If in open mode, and the current line is deleted, and the line remains +on the display, an \fB'@'\fP character shall be +displayed as the first glyph of that line. +.LP +Delete the region of text into \fIbuffer\fP, if specified, and into +the unnamed buffer. If the text to be deleted contains +characters from more than a single line, or the buffer text is in +line mode, the deleted text shall be copied into the numeric +buffers, as well. +.LP +\fICurrent line\fP: Set to the first text region line that appears +in the edit buffer, unless that line has been deleted, in +which case it shall be set to the last line in the edit buffer, or +line 1 if the edit buffer is empty. +.LP +\fICurrent column\fP: +.IP " 1." 4 +If the line is empty, set to column position 1. +.LP +.IP " 2." 4 +Otherwise, if the buffer text is in line mode or the motion was from +the cursor toward the end of the edit buffer: +.RS +.IP " a." 4 +If a character from the current line is displayed in the current column, +set to the last column that displays any portion of +that character. +.LP +.IP " b." 4 +Otherwise, set to the last column in which any portion of any character +in the line is displayed. +.LP +.RE +.LP +.IP " 3." 4 +Otherwise, if a character is displayed in the column that began the +text region, set to the last column that displays any +portion of that character. +.LP +.IP " 4." 4 +Otherwise, set to the last column in which any portion of any character +in the line is displayed. +.LP +.SS Delete to End-of-Line +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB]\fP \fBD +\fP +.fi +.RE +.sp +.LP +Delete the text from the current position to the end of the current +line; equivalent to the \fIvi\fP command: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB]\fP \fBd$ +\fP +.fi +.RE +.SS Move to End-of-Word +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBe +\fP +.fi +.RE +.sp +.LP +With the exception that words are used instead of bigwords as the +delimiter, this command shall be equivalent to the \fBE\fP +command. +.SS Move to End-of-Bigword +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBE +\fP +.fi +.RE +.sp +.LP +If the edit buffer is empty it shall be an error. If less than \fIcount\fP +bigwords end between the cursor and the end of the +edit buffer, \fIcount\fP shall be adjusted to the number of bigword +endings between the cursor and the end of the edit buffer. +.LP +If used as a motion command: +.IP " 1." 4 +The text region shall be from the last character of the \fIcount\fPth +next bigword up to and including the cursor +character. +.LP +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Set to the line containing the current column. +.LP +\fICurrent column\fP: Set to the last column upon which any part of +the last character of the \fIcount\fPth next bigword is +displayed. +.SS Find Character in Current Line (Forward) +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBf\fP \fIcharacter\fP +.fi +.RE +.sp +.LP +It shall be an error if \fIcount\fP occurrences of the character do +not occur after the cursor in the line. +.LP +If used as a motion command: +.IP " 1." 4 +The text range shall be from the cursor character up to and including +the \fIcount\fPth occurrence of the specified character +after the cursor. +.LP +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Set to the last column in which any portion +of the \fIcount\fPth occurrence of the specified character +after the cursor appears in the line. +.SS Find Character in Current Line (Reverse) +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBF\fP \fIcharacter\fP +.fi +.RE +.sp +.LP +It shall be an error if \fIcount\fP occurrences of the character do +not occur before the cursor in the line. +.LP +If used as a motion command: +.IP " 1." 4 +The text region shall be from the \fIcount\fPth occurrence of the +specified character before the cursor, up to, but not +including the cursor character. +.LP +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Set to the last column in which any portion +of the \fIcount\fPth occurrence of the specified character +before the cursor appears in the line. +.SS Move to Line +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBG +\fP +.fi +.RE +.sp +.LP +If \fIcount\fP is not specified, it shall default to the last line +of the edit buffer. If \fIcount\fP is greater than the last +line of the edit buffer, it shall be an error. +.LP +If used as a motion command: +.IP " 1." 4 +The text region shall be from the cursor line up to and including +the specified line. +.LP +.IP " 2." 4 +Any text copied to a buffer shall be in line mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Set to \fIcount\fP if \fIcount\fP is specified; +otherwise, the last line. +.LP +\fICurrent column\fP: Set to non- . +.SS Move to Top of Screen +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBH +\fP +.fi +.RE +.sp +.LP +If the beginning of the line \fIcount\fP greater than the first line +of which any portion appears on the display does not +exist, it shall be an error. +.LP +If used as a motion command: +.IP " 1." 4 +If in open mode, the text region shall be the current line. +.LP +.IP " 2." 4 +Otherwise, the text region shall be from the starting line up to and +including (the first line of the display + \fIcount\fP +-1). +.LP +.IP " 3." 4 +Any text copied to a buffer shall be in line mode. +.LP +.LP +If not used as a motion command: +.LP +If in open mode, this command shall set the current column to non- + and do nothing else. +.LP +Otherwise, it shall set the current line and current column as follows. +.LP +\fICurrent line\fP: Set to (the first line of the display + \fIcount\fP +-1). +.LP +\fICurrent column\fP: Set to non- . +.SS Insert Before Cursor +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBi +\fP +.fi +.RE +.sp +.LP +Enter text input mode before the current cursor position. No characters +already in the edit buffer shall be affected by this +command. A \fIcount\fP shall cause the input text to be appended \fIcount\fP +-1 more times to the end of the input. +.LP +\fICurrent line/column\fP: As specified for the text input commands +(see Input Mode Commands in +vi ). +.SS Insert at Beginning of Line +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBI +\fP +.fi +.RE +.sp +.LP +This command shall be equivalent to the \fIvi\fP command ^[ \fIcount\fP] +\fBi\fP. +.SS Join +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBJ +\fP +.fi +.RE +.sp +.LP +If the current line is the last line in the edit buffer, it shall +be an error. +.LP +This command shall be equivalent to the \fIex\fP \fBjoin\fP command +with no addresses, and +an \fIex\fP command \fIcount\fP value of 1 if \fIcount\fP was not +specified or if a +\fIcount\fP of 1 was specified, and an \fIex\fP command \fIcount\fP +value of \fIcount\fP -1 +for any other value of \fIcount\fP, except that the current line and +column shall be set as follows. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: The last column in which any portion of the +character following the last character in the initial line is +displayed, or the last non- in the line if no characters +were appended. +.SS Move to Bottom of Screen +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBL +\fP +.fi +.RE +.sp +.LP +If the beginning of the line \fIcount\fP less than the last line of +which any portion appears on the display does not exist, it +shall be an error. +.LP +If used as a motion command: +.IP " 1." 4 +If in open mode, the text region shall be the current line. +.LP +.IP " 2." 4 +Otherwise, the text region shall include all lines from the starting +cursor line to (the last line of the display -( +\fIcount\fP -1)). +.LP +.IP " 3." 4 +Any text copied to a buffer shall be in line mode. +.LP +.LP +If not used as a motion command: +.IP " 1." 4 +If in open mode, this command shall set the current column to non- + and do nothing else. +.LP +.IP " 2." 4 +Otherwise, it shall set the current line and current column as follows. +.LP +.LP +\fICurrent line\fP: Set to (the last line of the display -( \fIcount\fP +-1)). +.LP +\fICurrent column\fP: Set to non- . +.SS Mark Position +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBm\fP \fIletter\fP +.fi +.RE +.sp +.LP +This command shall be equivalent to the \fIex\fP \fBmark\fP command +with the specified +character as an argument. +.SS Move to Middle of Screen +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBM +\fP +.fi +.RE +.sp +.LP +The middle line of the display shall be calculated as follows: +.sp +.RS +.nf + +\fB(the top line of the display) + (((number of lines displayed) +1) /2) -1 +\fP +.fi +.RE +.LP +If used as a motion command: +.IP " 1." 4 +If in open mode, the text region shall be the current line. +.LP +.IP " 2." 4 +Otherwise, the text region shall include all lines from the starting +cursor line up to and including the middle line of the +display. +.LP +.IP " 3." 4 +Any text copied to a buffer shall be in line mode. +.LP +.LP +If not used as a motion command: +.LP +If in open mode, this command shall set the current column to non- + and do nothing else. +.LP +Otherwise, it shall set the current line and current column as follows. +.LP +\fICurrent line\fP: Set to the middle line of the display. +.LP +\fICurrent column\fP: Set to non- . +.SS Repeat Regular Expression Find (Forward) +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBn +\fP +.fi +.RE +.sp +.LP +If the remembered search direction was forward, the \fBn\fP command +shall be equivalent to the \fIvi\fP \fB/\fP command with +no characters entered by the user. Otherwise, it shall be equivalent +to the \fIvi\fP \fB?\fP command with no characters entered +by the user. +.LP +If the \fBn\fP command is used as a motion command for the \fB!\fP +command, the editor shall not enter text input mode on the +last line on the screen, and shall behave as if the user entered a +single \fB'!'\fP character as the text input. +.SS Repeat Regular Expression Find (Reverse) +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBN +\fP +.fi +.RE +.sp +.LP +Scan for the next match of the last pattern given to \fB/\fP or \fB?\fP, +but in the reverse direction; this is the reverse of +\fBn\fP. +.LP +If the remembered search direction was forward, the \fBN\fP command +shall be equivalent to the \fIvi\fP \fB?\fP command with +no characters entered by the user. Otherwise, it shall be equivalent +to the \fIvi\fP \fB/\fP command with no characters entered +by the user. If the \fBN\fP command is used as a motion command for +the \fB!\fP command, the editor shall not enter text input +mode on the last line on the screen, and shall behave as if the user +entered a single \fB!\fP character as the text input. +.SS Insert Empty Line Below +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBo +\fP +.fi +.RE +.sp +.LP +Enter text input mode in a new line appended after the current line. +A \fIcount\fP shall cause the input text to be appended +\fIcount\fP -1 more times to the end of the already added text, each +time starting on a new, appended line. +.LP +\fICurrent line/column\fP: As specified for the text input commands +(see Input Mode Commands in +vi ). +.SS Insert Empty Line Above +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBO +\fP +.fi +.RE +.sp +.LP +Enter text input mode in a new line inserted before the current line. +A \fIcount\fP shall cause the input text to be appended +\fIcount\fP -1 more times to the end of the already added text, each +time starting on a new, appended line. +.LP +\fICurrent line/column\fP: As specified for the text input commands +(see Input Mode Commands in +vi ). +.SS Put from Buffer Following +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB]\fP \fBp +\fP +.fi +.RE +.sp +.LP +If no \fIbuffer\fP is specified, the unnamed buffer shall be used. +.LP +If the buffer text is in line mode, the text shall be appended below +the current line, and each line of the buffer shall become +a new line in the edit buffer. A \fIcount\fP shall cause the buffer +text to be appended \fIcount\fP -1 more times to the end of +the already added text, each time starting on a new, appended line. +.LP +If the buffer text is in character mode, the text shall be appended +into the current line after the cursor, and each line of the +buffer other than the first and last shall become a new line in the +edit buffer. A \fIcount\fP shall cause the buffer text to be +appended \fIcount\fP -1 more times to the end of the already added +text, each time starting after the last added character. +.LP +\fICurrent line\fP: If the buffer text is in line mode, set the line +to line +1; otherwise, unchanged. +.LP +\fICurrent column\fP: If the buffer text is in line mode: +.IP " 1." 4 +If there is a non- in the first line of the buffer, set to +the last column on which any portion of the first non- + in the line is displayed. +.LP +.IP " 2." 4 +If there is no non- in the first line of the buffer, set to +the last column on which any portion of the last non- + in the first line of the buffer is displayed. +.LP +.LP +If the buffer text is in character mode: +.IP " 1." 4 +If the text in the buffer is from more than a single line, then set +to the last column on which any portion of the first +character from the buffer is displayed. +.LP +.IP " 2." 4 +Otherwise, if the buffer is the unnamed buffer, set to the last column +on which any portion of the last character from the +buffer is displayed. +.LP +.IP " 3." 4 +Otherwise, set to the first column on which any portion of the first +character from the buffer is displayed. +.LP +.SS Put from Buffer Before +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB]\fP \fBP +\fP +.fi +.RE +.sp +.LP +If no \fIbuffer\fP is specified, the unnamed buffer shall be used. +.LP +If the buffer text is in line mode, the text shall be inserted above +the current line, and each line of the buffer shall become +a new line in the edit buffer. A \fIcount\fP shall cause the buffer +text to be appended \fIcount\fP -1 more times to the end of +the already added text, each time starting on a new, appended line. +.LP +If the buffer text is in character mode, the text shall be inserted +into the current line before the cursor, and each line of +the buffer other than the first and last shall become a new line in +the edit buffer. A \fIcount\fP shall cause the buffer text to +be appended \fIcount\fP -1 more times to the end of the already added +text, each time starting after the last added character. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: If the buffer text is in line mode: +.IP " 1." 4 +If there is a non- in the first line of the buffer, set to +the last column on which any portion of that character +is displayed. +.LP +.IP " 2." 4 +If there is no non- in the first line of the buffer, set to +the last column on which any portion of the last non- + in the first line of the buffer is displayed. +.LP +.LP +If the buffer text is in character mode: +.IP " 1." 4 +If the buffer is the unnamed buffer, set to the last column on which +any portion of the last character from the buffer is +displayed. +.LP +.IP " 2." 4 +Otherwise, set to the first column on which any portion of the first +character from the buffer is displayed. +.LP +.SS Enter ex Mode +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBQ +\fP +.fi +.RE +.sp +.LP +Leave visual or open mode and enter \fIex\fP command mode. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS Replace Character +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBr\fP \fIcharacter\fP +.fi +.RE +.sp +.LP +Replace the \fIcount\fP characters at and after the cursor with the +specified character. If there are less than \fIcount\fP +non- s at and after the cursor on the line, it shall be an +error. +.LP +If character is -V, any next character other than the +shall be stripped of any special meaning +and used as a literal character. +.LP +If character is , no replacement shall be made and the current +line and current column shall be unchanged. +.LP +If character is or , \fIcount\fP new lines +shall be appended to the current line. All +but the last of these lines shall be empty. \fIcount\fP characters +at and after the cursor shall be discarded, and any remaining +characters after the cursor in the current line shall be moved to +the last of the new lines. If the \fBautoindent\fP edit option +is set, they shall be preceded by the same number of \fBautoindent\fP +characters found on the line from which the command was +executed. +.LP +\fICurrent line\fP: Unchanged unless the replacement character is +a or , in which case +it shall be set to line + \fIcount\fP. +.LP +\fICurrent column\fP: Set to the last column position on which a portion +of the last replaced character is displayed, or if the +replacement character caused new lines to be created, set to non- +. +.SS Replace Characters +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBR +\fP +.fi +.RE +.sp +.LP +Enter text input mode at the current cursor position possibly replacing +text on the current line. A \fIcount\fP shall cause the +input text to be appended \fIcount\fP -1 more times to the end of +the input. +.LP +\fICurrent line/column\fP: As specified for the text input commands +(see Input Mode Commands in +vi ). +.SS Substitute Character +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB]\fP \fBs +\fP +.fi +.RE +.sp +.LP +This command shall be equivalent to the \fIvi\fP command: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB]\fP \fBc +\fP +.fi +.RE +.SS Substitute Lines +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB]\fP \fBS +\fP +.fi +.RE +.sp +.LP +This command shall be equivalent to the \fIvi\fP command: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB]\fP \fBc_ +\fP +.fi +.RE +.SS Move Cursor to Before Character (Forward) +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBt\fP \fIcharacter\fP +.fi +.RE +.sp +.LP +It shall be an error if \fIcount\fP occurrences of the character do +not occur after the cursor in the line. +.LP +If used as a motion command: +.IP " 1." 4 +The text region shall be from the cursor up to but not including the +\fIcount\fPth occurrence of the specified character after +the cursor. +.LP +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Set to the last column in which any portion +of the character before the \fIcount\fPth occurrence of the +specified character after the cursor appears in the line. +.SS Move Cursor to After Character (Reverse) +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBT\fP \fIcharacter\fP +.fi +.RE +.sp +.LP +It shall be an error if \fIcount\fP occurrences of the character do +not occur before the cursor in the line. +.LP +If used as a motion command: +.IP " 1." 4 +If the character before the cursor is the specified character, it +shall be an error. +.LP +.IP " 2." 4 +The text region shall be from the character before the cursor up to +but not including the \fIcount\fPth occurrence of the +specified character before the cursor. +.LP +.IP " 3." 4 +Any text copied to a buffer shall be in character mode. +.LP +.LP +If not used as a motion command: +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Set to the last column in which any portion +of the character after the \fIcount\fPth occurrence of the +specified character before the cursor appears in the line. +.SS Undo +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBu +\fP +.fi +.RE +.sp +.LP +This command shall be equivalent to the \fIex\fP \fBundo\fP command +except that the current +line and current column shall be set as follows: +.LP +\fICurrent line\fP: Set to the first line added or changed if any; +otherwise, move to the line preceding any deleted text if +one exists; otherwise, move to line 1. +.LP +\fICurrent column\fP: If undoing an \fIex\fP command, set to the first +non- +. +.LP +Otherwise, if undoing a text input command: +.IP " 1." 4 +If the command was a \fBC\fP, \fBc\fP, \fBO\fP, \fBo\fP, \fBR\fP, +\fBS\fP, or \fBs\fP command, the current column shall +be set to the value it held when the text input command was entered. +.LP +.IP " 2." 4 +Otherwise, set to the last column in which any portion of the first +character after the deleted text is displayed, or, if no +non- s follow the text deleted from this line, set to the +last column in which any portion of the last non- + in the line is displayed, or 1 if the line is empty. +.LP +.LP +Otherwise, if a single line was modified (that is, not added or deleted) +by the \fBu\fP command: +.IP " 1." 4 +If text was added or changed, set to the last column in which any +portion of the first character added or changed is +displayed. +.LP +.IP " 2." 4 +If text was deleted, set to the last column in which any portion of +the first character after the deleted text is displayed, or, +if no non- s follow the deleted text, set to the last column +in which any portion of the last non- +in the line is displayed, or 1 if the line is empty. +.LP +.LP +Otherwise, set to non- . +.SS Undo Current Line +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBU +\fP +.fi +.RE +.sp +.LP +Restore the current line to its state immediately before the most +recent time that it became the current line. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Set to the first column in the line in which +any portion of the first character in the line is +displayed. +.SS Move to Beginning of Word +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBw +\fP +.fi +.RE +.sp +.LP +With the exception that words are used as the delimiter instead of +bigwords, this command shall be equivalent to the \fBW\fP +command. +.SS Move to Beginning of Bigword +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBW +\fP +.fi +.RE +.sp +.LP +If the edit buffer is empty, it shall be an error. If there are less +than \fIcount\fP bigwords between the cursor and the end +of the edit buffer, \fIcount\fP shall be adjusted to move the cursor +to the last bigword in the edit buffer. +.LP +If used as a motion command: +.IP " 1." 4 +If the associated command is \fBc\fP, \fIcount\fP is 1, and the cursor +is on a , the region of text shall be the +current character and no further action shall be taken. +.LP +.IP " 2." 4 +If there are less than \fIcount\fP bigwords between the cursor and +the end of the edit buffer, then the command shall succeed, +and the region of text shall include the last character of the edit +buffer. +.LP +.IP " 3." 4 +If there are s or an end-of-line that precede the \fIcount\fPth +bigword, and the associated command is \fBc\fP, +the region of text shall be up to and including the last character +before the preceding s or end-of-line. +.LP +.IP " 4." 4 +If there are s or an end-of-line that precede the bigword, +and the associated command is \fBd\fP or \fBy\fP, the +region of text shall be up to and including the last before +the start of the bigword or end-of-line. +.LP +.IP " 5." 4 +Any text copied to a buffer shall be in character mode. +.LP +.LP +If not used as a motion command: +.IP " 1." 4 +If the cursor is on the last character of the edit buffer, it shall +be an error. +.LP +.LP +\fICurrent line\fP: Set to the line containing the current column. +.LP +\fICurrent column\fP: Set to the last column in which any part of +the first character of the \fIcount\fPth next bigword is +displayed. +.SS Delete Character at Cursor +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB]\fP \fBx +\fP +.fi +.RE +.sp +.LP +Delete the \fIcount\fP characters at and after the current character +into \fIbuffer\fP, if specified, and into the unnamed +buffer. +.LP +If the line is empty, it shall be an error. If there are less than +\fIcount\fP non- s at and after the cursor on +the current line, \fIcount\fP shall be adjusted to the number of non- +s at and after the cursor. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: If the line is empty, set to column position +1. Otherwise, if there were \fIcount\fP or less non- +s at and after the cursor on the current line, set to the +last column that displays any part of the last non- + of the line. Otherwise, unchanged. +.SS Delete Character Before Cursor +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB]\fP \fBX +\fP +.fi +.RE +.sp +.LP +Delete the \fIcount\fP characters before the current character into +\fIbuffer\fP, if specified, and into the unnamed +buffer. +.LP +If there are no characters before the current character on the current +line, it shall be an error. If there are less than +\fIcount\fP previous characters on the current line, \fIcount\fP shall +be adjusted to the number of previous characters on the +line. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Set to (current column - the width of the deleted +characters). +.SS Yank +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB]\fP \fBy\fP \fImotion\fP +.fi +.RE +.sp +.LP +Copy (yank) the region of text into \fIbuffer\fP, if specified, and +into the unnamed buffer. +.LP +If the motion command is the \fBy\fP command repeated: +.IP " 1." 4 +The buffer shall be in line mode. +.LP +.IP " 2." 4 +If there are less than \fIcount\fP -1 lines after the current line +in the edit buffer, it shall be an error. +.LP +.IP " 3." 4 +The text region shall be from the current line up to and including +the next \fIcount\fP -1 lines. +.LP +.LP +Otherwise, the buffer text mode and text region shall be as specified +by the motion command. +.LP +\fICurrent line\fP: If the motion was from the current cursor position +toward the end of the edit buffer, unchanged. Otherwise, +set to the first line in the edit buffer that is part of the text +region specified by the motion command. +.LP +\fICurrent column\fP: +.IP " 1." 4 +If the motion was from the current cursor position toward the end +of the edit buffer, unchanged. +.LP +.IP " 2." 4 +Otherwise, if the current line is empty, set to column position 1. +.LP +.IP " 3." 4 +Otherwise, set to the last column that displays any part of the first +character in the file that is part of the text region +specified by the motion command. +.LP +.SS Yank Current Line +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB]\fP \fBY +\fP +.fi +.RE +.sp +.LP +This command shall be equivalent to the \fIvi\fP command: +.sp +.RS +.nf + +\fB[\fP\fIbuffer\fP\fB][\fP\fIcount\fP\fB]\fP \fBy_ +\fP +.fi +.RE +.SS Redraw Window +.LP +If in open mode, the \fBz\fP command shall have the Synopsis: +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIcount\fP\fB]\fP \fBz +\fP +.fi +.RE +.sp +.LP +If \fIcount\fP is not specified, it shall default to the \fBwindow\fP +edit option -1. The \fBz\fP command shall be equivalent +to the \fIex\fP \fBz\fP command, with a type character of \fB=\fP +and a \fIcount\fP of +\fIcount\fP -2, except that the current line and current column shall +be set as follows, and the \fBwindow\fP edit option shall +not be affected. If the calculation for the \fIcount\fP argument would +result in a negative number, the \fIcount\fP argument to +the \fIex\fP \fBz\fP command shall be zero. A blank line shall be +written after the last line +is written. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.LP +If not in open mode, the \fBz\fP command shall have the following +Synopsis: +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB[\fP\fIline\fP\fB]\fP \fBz\fP \fB[\fP\fIcount\fP\fB]\fP \fIcharacter\fP +.fi +.RE +.sp +.LP +If \fIline\fP is not specified, it shall default to the current line. +If \fIline\fP is specified, but is greater than the +number of lines in the edit buffer, it shall default to the number +of lines in the edit buffer. +.LP +If \fIcount\fP is specified, the value of the \fBwindow\fP edit option +shall be set to \fIcount\fP (as described in the \fIex\fP \fBwindow\fP +command), and the screen shall be redrawn. +.LP +\fIline\fP shall be placed as specified by the following characters: +.TP 7 +,\ +.sp +Place the beginning of the line on the first line of the display. +.TP 7 +\fB\&.\fP +Place the beginning of the line in the center of the display. The +middle line of the display shall be calculated as described +for the \fBM\fP command. +.TP 7 +\fB-\fP +Place an unspecified portion of the line on the last line of the display. +.TP 7 +\fB+\fP +If \fIline\fP was specified, equivalent to the case. If +\fIline\fP was not specified, display a screen where +the first line of the display shall be (current last line) +1. If +there are no lines after the last line in the display, it shall +be an error. +.TP 7 +\fB^\fP +If \fIline\fP was specified, display a screen where the last line +of the display shall contain an unspecified portion of the +first line of a display that had an unspecified portion of the specified +line on the last line of the display. If this calculation +results in a line before the beginning of the edit buffer, display +the first screen of the edit buffer. +.LP +Otherwise, display a screen where the last line of the display shall +contain an unspecified portion of (current first line -1). +If this calculation results in a line before the beginning of the +edit buffer, it shall be an error. +.sp +.LP +\fICurrent line\fP: If \fIline\fP and the \fB'^'\fP character were +specified: +.IP " 1." 4 +If the first screen was displayed as a result of the command attempting +to display lines before the beginning of the edit +buffer: if the first screen was already displayed, unchanged; otherwise, +set to (current first line -1). +.LP +.IP " 2." 4 +Otherwise, set to the last line of the display. +.LP +.LP +If \fIline\fP and the \fB'+'\fP character were specified, set to the +first line of the display. +.LP +Otherwise, if \fIline\fP was specified, set to \fIline\fP. +.LP +Otherwise, unchanged. +.LP +\fICurrent column\fP: Set to non- . +.SS Exit +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBZZ +\fP +.fi +.RE +.sp +.LP +This command shall be equivalent to the \fIex\fP \fBxit\fP command +with no addresses, +trailing \fB!\fP, or filename (see the \fIex\fP \fBxit\fP command). +.SS Input Mode Commands in vi +.LP +In text input mode, the current line shall consist of zero or more +of the following categories, plus the terminating +: +.IP " 1." 4 +Characters preceding the text input entry point +.LP +Characters in this category shall not be modified during text input +mode. +.LP +.IP " 2." 4 +\fBautoindent\fP characters +.LP +\fBautoindent\fP characters shall be automatically inserted into each +line that is created in text input mode, either as a +result of entering a or while in text +input mode, or as an effect of the command itself; +for example, \fBO\fP or \fBo\fP (see the \fIex\fP \fBautoindent\fP +command), as if entered +by the user. +.LP +It shall be possible to erase \fBautoindent\fP characters with the +-D command; it is unspecified whether they +can be erased by -H, -U, and -W characters. +Erasing any \fBautoindent\fP character +turns the glyph into erase-columns and deletes the character from +the edit buffer, but does not change its representation on the +screen. +.LP +.IP " 3." 4 +Text input characters +.LP +Text input characters are the characters entered by the user. Erasing +any text input character turns the glyph into +erase-columns and deletes the character from the edit buffer, but +does not change its representation on the screen. +.LP +Each text input character entered by the user (that does not have +a special meaning) shall be treated as follows: +.RS +.IP " a." 4 +The text input character shall be appended to the last character in +the edit buffer from the first, second, or third +categories. +.LP +.IP " b." 4 +If there are no erase-columns on the screen, the text input command +was the \fBR\fP command, and characters in the fifth +category from the original line follow the cursor, the next such character +shall be deleted from the edit buffer. If the +\fBslowopen\fP edit option is not set, the corresponding glyph on +the screen shall become erase-columns. +.LP +.IP " c." 4 +If there are erase-columns on the screen, as many columns as they +occupy, or as are necessary, shall be overwritten to display +the text input character. (If only part of a multi-column glyph is +overwritten, the remainder shall be left on the screen, and +continue to be treated as erase-columns; it is unspecified whether +the remainder of the glyph is modified in any way.) +.LP +.IP " d." 4 +If additional display line columns are needed to display the text +input character: +.RS +.IP " 1." 4 +If the \fBslowopen\fP edit option is set, the text input characters +shall be displayed on subsequent display line columns, +overwriting any characters displayed in those columns. +.LP +.IP " 2." 4 +Otherwise, any characters currently displayed on or after the column +on the display line where the text input character is to be +displayed shall be pushed ahead the number of display line columns +necessary to display the rest of the text input character. +.LP +.RE +.LP +.RE +.LP +.IP " 4." 4 +Erase-columns +.LP +Erase-columns are not logically part of the edit buffer, appearing +only on the screen, and may be overwritten on the screen by +subsequent text input characters. When text input mode ends, all erase-columns +shall no longer appear on the screen. +.LP +Erase-columns are initially the region of text specified by the \fBc\fP +command (see Change ); +however, erasing \fBautoindent\fP or text input characters causes +the glyphs of the erased characters to be treated as +erase-columns. +.LP +.IP " 5." 4 +Characters following the text region for the \fBc\fP command, or the +text input entry point for all other commands +.LP +Characters in this category shall not be modified during text input +mode, except as specified in category 3.b. for the \fBR\fP +text input command, or as s deleted when a or +is entered. +.LP +.LP +It is unspecified whether it is an error to attempt to erase past +the beginning of a line that was created by the entry of a + or during text input mode. If it is not +an error, the editor shall behave as if the erasing +character was entered immediately after the last text input character +entered on the previous line, and all of the non- +s on the current line shall be treated as erase-columns. +.LP +When text input mode is entered, or after a text input mode character +is entered (except as specified for the special characters +below), the cursor shall be positioned as follows: +.IP " 1." 4 +On the first column that displays any part of the first erase-column, +if one exists +.LP +.IP " 2." 4 +Otherwise, if the \fBslowopen\fP edit option is set, on the first +display line column after the last character in the first, +second, or third categories, if one exists +.LP +.IP " 3." 4 +Otherwise, the first column that displays any part of the first character +in the fifth category, if one exists +.LP +.IP " 4." 4 +Otherwise, the display line column after the last character in the +first, second, or third categories, if one exists +.LP +.IP " 5." 4 +Otherwise, on column position 1 +.LP +.LP +The characters that are updated on the screen during text input mode +are unspecified, other than that the last text input +character shall always be updated, and, if the \fBslowopen\fP edit +option is not set, the current cursor character shall always be +updated. +.LP +The following specifications are for command characters entered during +text input mode. +.SS NUL +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fBNUL +\fP +.fi +.RE +.sp +.LP +If the first character of the text input is a NUL, the most recently +input text shall be input as if entered by the user, and +then text input mode shall be exited. The text shall be input literally; +that is, characters are neither macro or abbreviation +expanded, nor are any characters interpreted in any special manner. +It is unspecified whether implementations shall support more +than 256 bytes of remembered input text. +.SS -D +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB-D +\fP +.fi +.RE +.sp +.LP +The -D character shall have no special meaning when in text +input mode for a line-oriented command (see Command Descriptions in +vi ). +.LP +This command need not be supported on block-mode terminals. +.LP +If the cursor does not follow an \fBautoindent\fP character, or an +\fBautoindent\fP character and a \fB'0'\fP or +\fB'^'\fP character: +.IP " 1." 4 +If the cursor is in column position 1, the -D character shall +be discarded and no further action taken. +.LP +.IP " 2." 4 +Otherwise, the -D character shall have no special meaning. +.LP +.LP +If the last input character was a \fB'0'\fP , the cursor shall be +moved to column position 1. +.LP +Otherwise, if the last input character was a \fB'^'\fP , the cursor +shall be moved to column position 1. In addition, the +\fBautoindent\fP level for the next input line shall be derived from +the same line from which the \fBautoindent\fP level for the +current input line was derived. +.LP +Otherwise, the cursor shall be moved back to the column after the +previous shiftwidth (see the \fIex\fP \fBshiftwidth\fP command) boundary. +.LP +All of the glyphs on columns between the starting cursor position +and (inclusively) the ending cursor position shall become +erase-columns as described in Input Mode Commands in vi . +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Set to 1 if the -D was preceded by +a \fB'^'\fP or \fB'0'\fP ; otherwise, set to +(column -1) -((column -2) % \fBshiftwidth\fP). +.SS -H +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB-H +\fP +.fi +.RE +.sp +.LP +If in text input mode for a line-oriented command, and there are no +characters to erase, text input mode shall be terminated, no +further action shall be done for this command, and the current line +and column shall be unchanged. +.LP +If there are characters other than \fBautoindent\fP characters that +have been input on the current line before the cursor, the +cursor shall move back one character. +.LP +Otherwise, if there are \fBautoindent\fP characters on the current +line before the cursor, it is implementation-defined whether +the -H command is an error or if the cursor moves back one +\fBautoindent\fP character. +.LP +Otherwise, if the cursor is in column position 1 and there are previous +lines that have been input, it is implementation-defined +whether the -H command is an error or if it is equivalent +to entering -H after the last input +character on the previous input line. +.LP +Otherwise, it shall be an error. +.LP +All of the glyphs on columns between the starting cursor position +and (inclusively) the ending cursor position shall become +erase-columns as described in Input Mode Commands in vi . +.LP +The current erase character (see \fIstty\fP) shall cause an equivalent +action to the +-H command, unless the previously inserted character was +a backslash, in which case it shall be as if the literal +current erase character had been inserted instead of the backslash. +.LP +\fICurrent line\fP: Unchanged, unless previously input lines are erased, +in which case it shall be set to line -1. +.LP +\fICurrent column\fP: Set to the first column that displays any portion +of the character backed up over. +.SS +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB +.sp + + +.sp + +-J +.sp + +-M +\fP +.fi +.RE +.sp +.LP +If input was part of a line-oriented command, text input mode shall +be terminated and the command shall continue execution with +the input provided. +.LP +Otherwise, terminate the current line. If there are no characters +other than \fBautoindent\fP characters on the line, all +characters on the line shall be discarded. Otherwise, it is unspecified +whether the \fBautoindent\fP characters in the line are +modified by entering these characters. +.LP +Continue text input mode on a new line appended after the current +line. If the \fBslowopen\fP edit option is set, the lines on +the screen below the current line shall not be pushed down, but the +first of them shall be cleared and shall appear to be +overwritten. Otherwise, the lines of the screen below the current +line shall be pushed down. +.LP +If the \fBautoindent\fP edit option is set, an appropriate number +of \fBautoindent\fP characters shall be added as a prefix to +the line as described by the \fIex\fP \fBautoindent\fP edit option. +.LP +All columns after the cursor that are erase-columns (as described +in Input Mode Commands in vi ) +shall be discarded. +.LP +If the \fBautoindent\fP edit option is set, all s immediately +following the cursor shall be discarded. +.LP +All remaining characters after the cursor shall be transferred to +the new line, positioned after any \fBautoindent\fP +characters. +.LP +\fICurrent line\fP: Set to current line +1. +.LP +\fICurrent column\fP: Set to the first column that displays any portion +of the first character after the \fBautoindent\fP +characters on the new line, if any, or the first column position after +the last \fBautoindent\fP character, if any, or column +position 1. +.SS -T +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB-T +\fP +.fi +.RE +.sp +.LP +The -T character shall have no special meaning when in text +input mode for a line-oriented command (see Command Descriptions in +vi ). +.LP +This command need not be supported on block-mode terminals. +.LP +Behave as if the user entered the minimum number of s necessary +to move the cursor forward to the column position +after the next \fBshiftwidth\fP (see the \fIex\fP \fBshiftwidth\fP +command) boundary. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Set to \fIcolumn\fP + \fBshiftwidth\fP - ((column +-1) % \fBshiftwidth\fP). +.SS -U +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB-U +\fP +.fi +.RE +.sp +.LP +If there are characters other than \fBautoindent\fP characters that +have been input on the current line before the cursor, the +cursor shall move to the first character input after the \fBautoindent\fP +characters. +.LP +Otherwise, if there are \fBautoindent\fP characters on the current +line before the cursor, it is implementation-defined whether +the -U command is an error or if the cursor moves to the +first column position on the line. +.LP +Otherwise, if the cursor is in column position 1 and there are previous +lines that have been input, it is implementation-defined +whether the -U command is an error or if it is equivalent +to entering -U after the last input +character on the previous input line. +.LP +Otherwise, it shall be an error. +.LP +All of the glyphs on columns between the starting cursor position +and (inclusively) the ending cursor position shall become +erase-columns as described in Input Mode Commands in vi . +.LP +The current \fIkill\fP character (see \fIstty\fP) shall cause an equivalent +action to the +-U command, unless the previously inserted character was +a backslash, in which case it shall be as if the literal +current \fIkill\fP character had been inserted instead of the backslash. +.LP +\fICurrent line\fP: Unchanged, unless previously input lines are erased, +in which case it shall be set to line -1. +.LP +\fICurrent column\fP: Set to the first column that displays any portion +of the last character backed up over. +.SS -V +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB-V +.sp + +-Q +\fP +.fi +.RE +.sp +.LP +Allow the entry of any subsequent character, other than -J +or the , as a literal character, +removing any special meaning that it may have to the editor in text +input mode. If a -V or -Q is +entered before a -J or , the -V or -Q +character shall be discarded, and +the -J or shall behave as described in the +command character during input mode. +.LP +For purposes of the display only, the editor shall behave as if a +\fB'^'\fP character was entered, and the cursor shall be +positioned as if overwriting the \fB'^'\fP character. When a subsequent +character is entered, the editor shall behave as if that +character was entered instead of the original -V or -Q +character. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: Unchanged. +.SS -W +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB-W +\fP +.fi +.RE +.sp +.LP +If there are characters other than \fBautoindent\fP characters that +have been input on the current line before the cursor, the +cursor shall move back over the last word preceding the cursor (including +any s between the end of the last word and +the current cursor); the cursor shall not move to before the first +character after the end of any \fBautoindent\fP characters. +.LP +Otherwise, if there are \fBautoindent\fP characters on the current +line before the cursor, it is implementation-defined whether +the -W command is an error or if the cursor moves to the +first column position on the line. +.LP +Otherwise, if the cursor is in column position 1 and there are previous +lines that have been input, it is implementation-defined +whether the -W command is an error or if it is equivalent +to entering -W after the last input +character on the previous input line. +.LP +Otherwise, it shall be an error. +.LP +All of the glyphs on columns between the starting cursor position +and (inclusively) the ending cursor position shall become +erase-columns as described in Input Mode Commands in vi . +.LP +\fICurrent line\fP: Unchanged, unless previously input lines are erased, +in which case it shall be set to line -1. +.LP +\fICurrent column\fP: Set to the first column that displays any portion +of the last character backed up over. +.SS +.TP 7 +\fISynopsis\fP: +.sp +.RS +.nf + +\fB +\fP +.fi +.RE +.sp +.LP +If input was part of a line-oriented command: +.IP " 1." 4 +If \fIinterrupt\fP was entered, text input mode shall be terminated +and the editor shall return to command mode. The terminal +shall be alerted. +.LP +.IP " 2." 4 +If was entered, text input mode shall be terminated and the +command shall continue execution with the input +provided. +.LP +.LP +Otherwise, terminate text input mode and return to command mode. +.LP +Any \fBautoindent\fP characters entered on newly created lines that +have no other non- s shall be deleted. +.LP +Any leading \fBautoindent\fP and s on newly created lines shall +be rewritten to be the minimum number of +s possible. +.LP +The screen shall be redisplayed as necessary to match the contents +of the edit buffer. +.LP +\fICurrent line\fP: Unchanged. +.LP +\fICurrent column\fP: +.IP " 1." 4 +If there are text input characters on the current line, the column +shall be set to the last column where any portion of the last +text input character is displayed. +.LP +.IP " 2." 4 +Otherwise, if a character is displayed in the current column, unchanged. +.LP +.IP " 3." 4 +Otherwise, set to column position 1. +.LP +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +When any error is encountered and the standard input is not a terminal +device file, \fIvi\fP shall not write the file or return +to command or text input mode, and shall terminate with a non-zero +exit status. +.LP +Otherwise, when an unrecoverable error is encountered it shall be +equivalent to a SIGHUP asynchronous event. +.LP +Otherwise, when an error is encountered, the editor shall behave as +specified in Command +Descriptions in vi . +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +See the RATIONALE for \fIex\fP for more information on \fIvi\fP. Major +portions of the \fIvi\fP utility +specification point to \fIex\fP to avoid inadvertent divergence. While +\fIex\fP and \fIvi\fP have historically been implemented as a single +utility, this is not required by +IEEE\ Std\ 1003.1-2001. +.LP +It is recognized that portions of \fIvi\fP would be difficult, if +not impossible, to implement satisfactorily on a block-mode +terminal, or a terminal without any form of cursor addressing, thus +it is not a mandatory requirement that such features should +work on all terminals. It is the intention, however, that a \fIvi\fP +implementation should provide the full set of capabilities on +all terminals capable of supporting them. +.LP +Historically, \fIvi\fP exited immediately if the standard input was +not a terminal. IEEE\ Std\ 1003.1-2001 permits, but +does not require, this behavior. An end-of-file condition is not equivalent +to an end-of-file character. A common end-of-file +character, -D, is historically a \fIvi\fP command. +.LP +The text in the STDOUT section reflects the usage of the verb \fIdisplay\fP +in this section; some implementations of \fIvi\fP +use standard output to write to the terminal, but IEEE\ Std\ 1003.1-2001 +does not require that to be the case. +.LP +Historically, implementations reverted to open mode if the terminal +was incapable of supporting full visual mode. +IEEE\ Std\ 1003.1-2001 requires this behavior. Historically, the open +mode of \fIvi\fP behaved roughly equivalently to the +visual mode, with the exception that only a single line from the edit +buffer (one "buffer line") was kept current at any time. +This line was normally displayed on the next-to-last line of a terminal +with cursor addressing (and the last line performed its +normal visual functions for line-oriented commands and messages). +In addition, some few commands behaved differently in open mode +than in visual mode. IEEE\ Std\ 1003.1-2001 requires conformance to +historical practice. +.LP +Historically, \fIex\fP and \fIvi\fP implementations have expected +text to proceed in the +usual European/Latin order of left to right, top to bottom. There +is no requirement in IEEE\ Std\ 1003.1-2001 that this be +the case. The specification was deliberately written using words like +"before", "after", "first", and "last" in order to +permit implementations to support the natural text order of the language. +.LP +Historically, lines past the end of the edit buffer were marked with +single tilde ( \fB'~'\fP ) characters; that is, if +the one-based display was 20 lines in length, and the last line of +the file was on line one, then lines 2-20 would contain only a +single \fB'~'\fP character. +.LP +Historically, the \fIvi\fP editor attempted to display only complete +lines at the bottom of the screen (it did display partial +lines at the top of the screen). If a line was too long to fit in +its entirety at the bottom of the screen, the screen lines where +the line would have been displayed were displayed as single \fB'@'\fP +characters, instead of displaying part of the line. +IEEE\ Std\ 1003.1-2001 permits, but does not require, this behavior. +Implementations are encouraged to attempt always to +display a complete line at the bottom of the screen when doing scrolling +or screen positioning by buffer lines. +.LP +Historically, lines marked with \fB'@'\fP were also used to minimize +output to dumb terminals over slow lines; that is, +changes local to the cursor were updated, but changes to lines on +the screen that were not close to the cursor were simply marked +with an \fB'@'\fP sign instead of being updated to match the current +text. IEEE\ Std\ 1003.1-2001 permits, but does not +require this feature because it is used ever less frequently as terminals +become smarter and connections are faster. +.SS Initialization in ex and vi +.LP +Historically, \fIvi\fP always had a line in the edit buffer, even +if the edit buffer was "empty". For example: +.IP " 1." 4 +The \fIex\fP command \fB=\fP executed from visual mode wrote "1" when +the buffer was +empty. +.LP +.IP " 2." 4 +Writes from visual mode of an empty edit buffer wrote files of a single +character (a ), while writes from \fIex\fP mode of an empty +edit buffer wrote empty files. +.LP +.IP " 3." 4 +Put and read commands into an empty edit buffer left an empty line +at the top of the edit buffer. +.LP +.LP +For consistency, IEEE\ Std\ 1003.1-2001 does not permit any of these +behaviors. +.LP +Historically, \fIvi\fP did not always return the terminal to its original +modes; for example, ICRNL was modified if it was not +originally set. IEEE\ Std\ 1003.1-2001 does not permit this behavior. +.SS Command Descriptions in vi +.LP +Motion commands are among the most complicated aspects of \fIvi\fP +to describe. With some exceptions, the text region and +buffer type effect of a motion command on a \fIvi\fP command are described +on a case-by-case basis. The descriptions of text +regions in IEEE\ Std\ 1003.1-2001 are not intended to imply direction; +that is, an inclusive region from line \fIn\fP to +line \fIn\fP+5 is identical to a region from line \fIn\fP+5 to line +\fIn\fP. This is of more than academic interest-movements to +marks can be in either direction, and, if the \fBwrapscan\fP option +is set, so can movements to search points. Historically, lines +are always stored into buffers in text order; that is, from the start +of the edit buffer to the end. IEEE\ Std\ 1003.1-2001 +requires conformance to historical practice. +.LP +Historically, command counts were applied to any associated motion, +and were multiplicative to any supplied motion count. For +example, \fB2cw\fP is the same as \fBc2w\fP, and \fB2c3w\fP is the +same as \fBc6w\fP. IEEE\ Std\ 1003.1-2001 requires +this behavior. Historically, \fIvi\fP commands that used bigwords, +words, paragraphs, and sentences as objects treated groups of +empty lines, or lines that contained only s, inconsistently. +Some commands treated them as a single entity, while +others treated each line separately. For example, the \fBw\fP, \fBW\fP, +and \fBB\fP commands treated groups of empty lines as +individual words; that is, the command would move the cursor to each +new empty line. The \fBe\fP and \fBE\fP commands treated +groups of empty lines as a single word; that is, the first use would +move past the group of lines. The \fBb\fP command would just +beep at the user, or if done from the start of the line as a motion +command, fail in unexpected ways. If the lines contained only +(or ended with) s, the \fBw\fP and \fBW\fP commands would just +beep at the user, the \fBE\fP and \fBe\fP commands +would treat the group as a single word, and the \fBB\fP and \fBb\fP +commands would treat the lines as individual words. For +consistency and simplicity of specification, IEEE\ Std\ 1003.1-2001 +requires that all \fIvi\fP commands treat groups of +empty or blank lines as a single entity, and that movement through +lines ending with s be consistent with other +movements. +.LP +Historically, \fIvi\fP documentation indicated that any number of +double quotes were skipped after punctuation marks at +sentence boundaries; however, implementations only skipped single +quotes. IEEE\ Std\ 1003.1-2001 requires both to be +skipped. +.LP +Historically, the first and last characters in the edit buffer were +word boundaries. This historical practice is required by +IEEE\ Std\ 1003.1-2001. +.LP +Historically, \fIvi\fP attempted to update the minimum number of columns +on the screen possible, which could lead to misleading +information being displayed. IEEE\ Std\ 1003.1-2001 makes no requirements +other than that the current character being +entered is displayed correctly, leaving all other decisions in this +area up to the implementation. +.LP +Historically, lines were arbitrarily folded between columns of any +characters that required multiple column positions on the +screen, with the exception of tabs, which terminated at the right-hand +margin. IEEE\ Std\ 1003.1-2001 permits the former +and requires the latter. Implementations that do not arbitrarily break +lines between columns of characters that occupy multiple +column positions should not permit the cursor to rest on a column +that does not contain any part of a character. +.LP +The historical \fIvi\fP had a problem in that all movements were by +buffer lines, not by display or screen lines. This is often +the right thing to do; for example, single line movements, such as +\fBj\fP or \fBk\fP, should work on buffer lines. Commands like +\fBdj\fP, or \fBj.\fP, where \fB.\fP is a change command, only make +sense for buffer lines. It is not, however, the right thing +to do for screen motion or scrolling commands like -D, -F, +and \fBH\fP. If the window is fairly +small, using buffer lines in these cases can result in completely +random motion; for example, \fB1\fP -D can result +in a completely changed screen, without any overlap. This is clearly +not what the user wanted. The problem is even worse in the +case of the \fBH\fP, \fBL\fP, and \fBM\fP commands-as they position +the cursor at the first non- of the line, they +may all refer to the same location in large lines, and will result +in no movement at all. +.LP +In addition, if the line is larger than the screen, using buffer lines +can make it impossible to display parts of the line-there +are not any commands that do not display the beginning of the line +in historical \fIvi\fP, and if both the beginning and end of +the line cannot be on the screen at the same time, the user suffers. +Finally, the page and half-page scrolling commands +historically moved to the first non- in the new line. If the +line is approximately the same size as the screen, this +is inadequate because the cursor before and after a -D command +will refer to the same location on the screen. +.LP +Implementations of \fIex\fP and \fIvi\fP exist that do not have these +problems because the +relevant commands ( -B, -D, -F, -U, +-Y, +-E, \fBH\fP, \fBL\fP, and \fBM)\fP operate on display (screen) +lines, not (edit) buffer lines. +.LP +IEEE\ Std\ 1003.1-2001 does not permit this behavior by default because +the standard developers believed that users +would find it too confusing. However, historical practice has been +relaxed. For example, \fIex\fP and \fIvi\fP historically attempted, +albeit sometimes unsuccessfully, to never put part of a +line on the last lines of a screen; for example, if a line would not +fit in its entirety, no part of the line was displayed, and +the screen lines corresponding to the line contained single \fB'@'\fP +characters. This behavior is permitted, but not required +by IEEE\ Std\ 1003.1-2001, so that it is possible for implementations +to support long lines in small screens more +reasonably without changing the commands to be oriented to the display +(instead of oriented to the buffer). +IEEE\ Std\ 1003.1-2001 also permits implementations to refuse to edit +any edit buffer containing a line that will not fit +on the screen in its entirety. +.LP +The display area (for example, the value of the \fBwindow\fP edit +option) has historically been "grown", or expanded, to +display new text when local movements are done in displays where the +number of lines displayed is less than the maximum possible. +Expansion has historically been the first choice, when the target +line is less than the maximum possible expansion value away. +Scrolling has historically been the next choice, done when the target +line is less than half a display away, and otherwise, the +screen was redrawn. There were exceptions, however, in that \fIex\fP +commands generally always +caused the screen to be redrawn. IEEE\ Std\ 1003.1-2001 does not specify +a standard behavior because there may be external +issues, such as connection speed, the number of characters necessary +to redraw as opposed to scroll, or terminal capabilities that +implementations will have to accommodate. +.LP +The current line in IEEE\ Std\ 1003.1-2001 maps one-to-one to a buffer +line in the file. The current column does not. +There are two different column values that are described by IEEE\ Std\ 1003.1-2001. +The first is the current column value +as set by many of the \fIvi\fP commands. This value is remembered +for the lifetime of the editor. The second column value is the +actual position on the screen where the cursor rests. The two are +not always the same. For example, when the cursor is backed by a +multi-column character, the actual cursor position on the screen has +historically been the last column of the character in command +mode, and the first column of the character in input mode. +.LP +Commands that set the current line, but that do not set the current +cursor value (for example, \fBj\fP and \fBk\fP) attempt to +get as close as possible to the remembered column position, so that +the cursor tends to restrict itself to a vertical column as the +user moves around in the edit buffer. IEEE\ Std\ 1003.1-2001 requires +conformance to historical practice, requiring that +the display location of the cursor on the display line be adjusted +from the current column value as necessary to support this +historical behavior. +.LP +Historically, only a single line (and for some terminals, a single +line minus 1 column) of characters could be entered by the +user for the line-oriented commands; that is, \fB:\fP, \fB!\fP, \fB/\fP, +or \fB?\fP. IEEE\ Std\ 1003.1-2001 permits, +but does not require, this limitation. +.LP +Historically, "soft" errors in \fIvi\fP caused the terminal to be +alerted, but no error message was displayed. As a general +rule, no error message was displayed for errors in command execution +in \fIvi\fP, when the error resulted from the user attempting +an invalid or impossible action, or when a searched-for object was +not found. Examples of soft errors included \fBh\fP at the left +margin, -B or \fB[[\fP at the beginning of the file, \fB2G\fP +at the end of the file, and so on. In addition, +errors such as \fB%\fP, \fB]]\fP, \fB}\fP, \fB)\fP, \fBN\fP, \fBn\fP, +\fBf\fP, \fBF\fP, \fBt\fP, and \fBT\fP failing to +find the searched-for object were soft as well. Less consistently, +\fB/\fP and \fB?\fP displayed an error message if the pattern +was not found, \fB/\fP, \fB?\fP, \fBN\fP, and \fBn\fP displayed an +error message if no previous regular expression had been +specified, and \fB;\fP did not display an error message if no previous +\fBf\fP, \fBF\fP, \fBt\fP, or \fBT\fP command had +occurred. Also, behavior in this area might reasonably be based on +a runtime evaluation of the speed of a network connection. +Finally, some implementations have provided error messages for soft +errors in order to assist naive users, based on the value of a +verbose edit option. IEEE\ Std\ 1003.1-2001 does not list specific +errors for which an error message shall be displayed. +Implementations should conform to historical practice in the absence +of any strong reason to diverge. +.SS Page Backwards +.LP +The -B and -F commands historically considered it +an error to attempt to page past the beginning +or end of the file, whereas the -D and -U commands +simply moved to the beginning or end of the file. +For consistency, IEEE\ Std\ 1003.1-2001 requires the latter behavior +for all four commands. All four commands still +consider it an error if the current line is at the beginning ( -B, +-U) or end ( -F, +-D) of the file. Historically, the -B and -F +commands skip two lines in order to +include overlapping lines when a single command is entered. This makes +less sense in the presence of a \fIcount\fP, as there will +be, by definition, no overlapping lines. The actual calculation used +by historical implementations of the \fIvi\fP editor for +-B was: +.sp +.RS +.nf + +\fB((current first line) - count x (window edit option)) +2 +\fP +.fi +.RE +.LP +and for -F was: +.sp +.RS +.nf + +\fB((current first line) + count x (window edit option)) -2 +\fP +.fi +.RE +.LP +This calculation does not work well when intermixing commands with +and without counts; for example, \fB3\fP -F +is not equivalent to entering the -F command three times, +and is not reversible by entering the -B +command three times. For consistency with other \fIvi\fP commands +that take counts, IEEE\ Std\ 1003.1-2001 requires a +different calculation. +.SS Scroll Forward +.LP +The 4BSD and System V implementations of \fIvi\fP differed on the +initial value used by the \fBscroll\fP command. 4BSD +used: +.sp +.RS +.nf + +\fB((window edit option) +1) /2 +\fP +.fi +.RE +.LP +while System V used the value of the \fBscroll\fP edit option. The +System V version is specified by +IEEE\ Std\ 1003.1-2001 because the standard developers believed that +it was more intuitive and permitted the user a method +of setting the scroll value initially without also setting the number +of lines that are displayed. +.SS Scroll Forward by Line +.LP +Historically, the -E and -Y commands considered +it an error if the last and first lines, +respectively, were already on the screen. IEEE\ Std\ 1003.1-2001 requires +conformance to historical practice. Historically, +the -E and -Y commands had no effect in open mode. +For simplicity and consistency of specification, +IEEE\ Std\ 1003.1-2001 requires that they behave as usual, albeit +with a single line screen. +.SS Clear and Redisplay +.LP +The historical -L command refreshed the screen exactly as +it was supposed to be currently displayed, replacing +any \fB'@'\fP characters for lines that had been deleted but not updated +on the screen with refreshed \fB'@'\fP characters. +The intent of the -L command is to refresh when the screen +has been accidentally overwritten; for example, by a +\fBwrite\fP command from another user, or modem noise. +.SS Redraw Screen +.LP +The historical -R command redisplayed only when necessary +to update lines that had been deleted but not updated +on the screen and that were flagged with \fB'@'\fP characters. There +is no requirement that the screen be in any way refreshed +if no lines of this form are currently displayed. IEEE\ Std\ 1003.1-2001 +permits implementations to extend this command to +refresh lines on the screen flagged with \fB'@'\fP characters because +they are too long to be displayed in the current +framework; however, the current line and column need not be modified. +.SS Search for tagstring +.LP +Historically, the first non- at or after the cursor was the +first character, and all subsequent characters that +were word characters, up to the end of the line, were included. For +example, with the cursor on the leading space or on the +\fB'#'\fP character in the text \fB"#bar@"\fP , the tag was \fB"#bar"\fP +\&. On the character \fB'b'\fP it was +\fB"bar"\fP , and on the \fB'a'\fP it was \fB"ar"\fP . IEEE\ Std\ 1003.1-2001 +requires this behavior. +.SS Replace Text with Results from Shell Command +.LP +Historically, the \fB<\fP, \fB>\fP, and \fB!\fP commands considered +most cursor motions other than line-oriented +motions an error; for example, the command \fB>/foo\fP succeeded, +while the command \fB>l\fP failed, even though +the text region described by the two commands might be identical. +For consistency, all three commands only consider entire lines +and not partial lines, and the region is defined as any line that +contains a character that was specified by the motion. +.SS Move to Matching Character +.LP +Other matching characters have been left implementation-defined in +order to allow extensions such as matching \fB'<'\fP +and \fB'>'\fP for searching HTML, or \fB#ifdef\fP, \fB#else\fP, and +\fB#endif\fP for searching C source. +.SS Repeat Substitution +.LP +IEEE\ Std\ 1003.1-2001 requires that any \fBc\fP and \fBg\fP flags +specified to the previous substitute command be +ignored; however, the \fBr\fP flag may still apply, if supported by +the implementation. +.SS Return to Previous (Context or Section) +.LP +The \fB[[\fP, \fB]]\fP, \fB(\fP, \fB)\fP, \fB{\fP, and \fB}\fP commands +are all affected by "section boundaries", but in +some historical implementations not all of the commands recognize +the same section boundaries. This is a bug, not a feature, and a +unique section-boundary algorithm was not described for each command. +One special case that is preserved is that the sentence +command moves to the end of the last line of the edit buffer while +the other commands go to the beginning, in order to preserve the +traditional character cut semantics of the sentence command. Historically, +\fIvi\fP section boundaries at the beginning and end of +the edit buffer were the first non- on the first and last +lines of the edit buffer if one exists; otherwise, the last +character of the first and last lines of the edit buffer if one exists. +To increase consistency with other section locations, this +has been simplified by IEEE\ Std\ 1003.1-2001 to the first character +of the first and last lines of the edit buffer, or the +first and the last lines of the edit buffer if they are empty. +.LP +Sentence boundaries were problematic in the historical \fIvi\fP. They +were not only the boundaries as defined for the section +and paragraph commands, but they were the first non- that +occurred after those boundaries, as well. Historically, the +\fIvi\fP section commands were documented as taking an optional window +size as a \fIcount\fP preceding the command. This was not +implemented in historical versions, so IEEE\ Std\ 1003.1-2001 requires +that the \fIcount\fP repeat the command, for +consistency with other \fIvi\fP commands. +.SS Repeat +.LP +Historically, mapped commands other than text input commands could +not be repeated using the \fBperiod\fP command. +IEEE\ Std\ 1003.1-2001 requires conformance to historical practice. +.LP +The restrictions on the interpretation of special characters (for +example, -H) in the repetition of text input +mode commands is intended to match historical practice. For example, +given the input sequence: +.sp +.RS +.nf + +\fBiab-H-H-Hdef +\fP +.fi +.RE +.LP +the user should be informed of an error when the sequence is first +entered, but not during a command repetition. The character +-T is specifically exempted from this restriction. Historical +implementations of \fIvi\fP ignored -T +characters that were input in the original command during command +repetition. IEEE\ Std\ 1003.1-2001 prohibits this +behavior. +.SS Find Regular Expression +.LP +Historically, commands did not affect the line searched to or from +if the motion command was a search ( \fB/\fP, \fB?\fP, +\fBN\fP, \fBn\fP) and the final position was the start/end of the +line. There were some special cases and \fIvi\fP was not +consistent. IEEE\ Std\ 1003.1-2001 does not permit this behavior, +for consistency. Historical implementations permitted but +were unable to handle searches as motion commands that wrapped (that +is, due to the edit option \fBwrapscan\fP) to the original +location. IEEE\ Std\ 1003.1-2001 requires that this behavior be treated +as an error. +.LP +Historically, the syntax \fB"/RE/0"\fP was used to force the command +to cut text in line mode. IEEE\ Std\ 1003.1-2001 +requires conformance to historical practice. +.LP +Historically, in open mode, a \fBz\fP specified to a search command +redisplayed the current line instead of displaying the +current screen with the current line highlighted. For consistency +and simplicity of specification, IEEE\ Std\ 1003.1-2001 +does not permit this behavior. +.LP +Historically, trailing \fBz\fP commands were permitted and ignored +if entered as part of a search used as a motion command. For +consistency and simplicity of specification, IEEE\ Std\ 1003.1-2001 +does not permit this behavior. +.SS Execute an ex Command +.LP +Historically, \fIvi\fP implementations restricted the commands that +could be entered on the colon command line (for example, +\fBappend\fP and \fBchange\fP), and some other commands were known +to cause them to fail catastrophically. For consistency, +IEEE\ Std\ 1003.1-2001 does not permit these restrictions. When executing +an \fIex\fP +command by entering \fB:\fP, it is not possible to enter a +as part of the command because it is considered the end +of the command. A different approach is to enter \fIex\fP command +mode by using the \fIvi\fP +\fBQ\fP command (and later resuming visual mode with the \fIex\fP +\fBvi\fP command). In \fIex\fP command mode, the single-line limitation +does not exist. So, for example, the following +is valid: +.sp +.RS +.nf + +\fBQ +s/break here/break\\ +here/ +vi +\fP +.fi +.RE +.LP +IEEE\ Std\ 1003.1-2001 requires that, if the \fIex\fP command overwrites +any part of +the screen that would be erased by a refresh, \fIvi\fP pauses for +a character from the user. Historically, this character could be +any character; for example, a character input by the user before the +message appeared, or even a mapped character. This is probably +a bug, but implementations that have tried to be more rigorous by +requiring that the user enter a specific character, or that the +user enter a character after the message was displayed, have been +forced by user indignation back into historical behavior. +IEEE\ Std\ 1003.1-2001 requires conformance to historical practice. +.SS Shift Left (Right) +.LP +Refer to the Rationale for the \fB!\fP and \fB/\fP commands. Historically, +the \fB<\fP and \fB>\fP commands sometimes +moved the cursor to the first non- (for example if the command +was repeated or with \fB_\fP as the motion command), +and sometimes left it unchanged. IEEE\ Std\ 1003.1-2001 does not permit +this inconsistency, requiring instead that the +cursor always move to the first non- . Historically, the \fB<\fP +and \fB>\fP commands did not support buffer +arguments, although some implementations allow the specification of +an optional buffer. This behavior is neither required nor +disallowed by IEEE\ Std\ 1003.1-2001. +.SS Execute +.LP +Historically, buffers could execute other buffers, and loops, infinite +and otherwise, were possible. +IEEE\ Std\ 1003.1-2001 requires conformance to historical practice. +The * \fIbuffer\fP syntax of \fIex\fP is not required in \fIvi\fP, +because it is not historical practice and has been used in some +\fIvi\fP implementations to support additional scripting languages. +.SS Reverse Case +.LP +Historically, the \fB~\fP command ignored any associated \fIcount\fP, +and acted only on the characters in the current +line. For consistency with other \fIvi\fP commands, IEEE\ Std\ 1003.1-2001 +requires that an associated \fIcount\fP act on +the next \fIcount\fP characters, and that the command move to subsequent +lines if warranted by \fIcount\fP, to make it possible +to modify large pieces of text in a reasonably efficient manner. There +exist \fIvi\fP implementations that optionally require an +associated motion command for the \fB~\fP command. Implementations +supporting this functionality are encouraged to base it on +the \fBtildedop\fP edit option and handle the text regions and cursor +positioning identically to the \fByank\fP command. +.SS Append +.LP +Historically, \fIcount\fPs specified to the \fBA\fP, \fBa\fP, \fBI\fP, +and \fBi\fP commands repeated the input of the first +line \fIcount\fP times, and did not repeat the subsequent lines of +the input text. IEEE\ Std\ 1003.1-2001 requires that +the entire text input be repeated \fIcount\fP times. +.SS Move Backward to Preceding Word +.LP +Historically, \fIvi\fP became confused if word commands were used +as motion commands in empty files. +IEEE\ Std\ 1003.1-2001 requires that this be an error. Historical +implementations of \fIvi\fP had a large number of bugs +in the word movement commands, and they varied greatly in behavior +in the presence of empty lines, "words" made up of a single +character, and lines containing only s. For consistency and +simplicity of specification, +IEEE\ Std\ 1003.1-2001 does not permit this behavior. +.SS Change to End-of-Line +.LP +Some historical implementations of the \fBC\fP command did not behave +as described by IEEE\ Std\ 1003.1-2001 when the +\fB$\fP key was remapped because they were implemented by pushing +the \fB$\fP key onto the input queue and reprocessing it. +IEEE\ Std\ 1003.1-2001 does not permit this behavior. Historically, +the \fBC\fP, \fBS\fP, and \fBs\fP commands did not +copy replaced text into the numeric buffers. For consistency and simplicity +of specification, IEEE\ Std\ 1003.1-2001 +requires that they behave like their respective \fBc\fP commands in +all respects. +.SS Delete +.LP +Historically, lines in open mode that were deleted were scrolled up, +and an \fB@\fP glyph written over the beginning of the +line. In the case of terminals that are incapable of the necessary +cursor motions, the editor erased the deleted line from the +screen. IEEE\ Std\ 1003.1-2001 requires conformance to historical +practice; that is, if the terminal cannot display the +\fB'@'\fP character, the line cannot remain on the screen. +.SS Delete to End-of-Line +.LP +Some historical implementations of the \fBD\fP command did not behave +as described by IEEE\ Std\ 1003.1-2001 when the +\fB$\fP key was remapped because they were implemented by pushing +the \fB$\fP key onto the input queue and reprocessing it. +IEEE\ Std\ 1003.1-2001 does not permit this behavior. +.SS Join +.LP +An historical oddity of \fIvi\fP is that the commands \fBJ\fP, \fB1J\fP, +and \fB2J\fP are all equivalent. +IEEE\ Std\ 1003.1-2001 requires conformance to historical practice. +The \fIvi\fP \fBJ\fP command is specified in terms of +the \fIex\fP \fBjoin\fP command with an \fIex\fP command +\fIcount\fP value. The address correction for a \fIcount\fP that is +past the end of the edit buffer is necessary for historical +compatibility for both \fIex\fP and \fIvi\fP. +.SS Mark Position +.LP +Historical practice is that only lowercase letters, plus \fB'`'\fP +and \fB'"\fP , could be used to mark a cursor +position. IEEE\ Std\ 1003.1-2001 requires conformance to historical +practice, but encourages implementations to support +other characters as marks as well. +.SS Repeat Regular Expression Find (Forward and Reverse) +.LP +Historically, the \fBN\fP and \fBn\fP commands could not be used as +motion components for the \fBc\fP command. With the +exception of the \fBcN\fP command, which worked if the search crossed +a line boundary, the text region would be discarded, and the +user would not be in text input mode. For consistency and simplicity +of specification, IEEE\ Std\ 1003.1-2001 does not +permit this behavior. +.SS Insert Empty Line (Below and Above) +.LP +Historically, counts to the \fBO\fP and \fBo\fP commands were used +as the number of physical lines to open, if the terminal +was dumb and the \fBslowopen\fP option was not set. This was intended +to minimize traffic over slow connections and repainting for +dumb terminals. IEEE\ Std\ 1003.1-2001 does not permit this behavior, +requiring that a \fIcount\fP to the open command +behave as for other text input commands. This change to historical +practice was made for consistency, and because a superset of the +functionality is provided by the \fBslowopen\fP edit option. +.SS Put from Buffer (Following and Before) +.LP +Historically, \fIcount\fPs to the \fBp\fP and \fBP\fP commands were +ignored if the buffer was a line mode buffer, but were +(mostly) implemented as described in IEEE\ Std\ 1003.1-2001 if the +buffer was a character mode buffer. Because +implementations exist that do not have this limitation, and because +pasting lines multiple times is generally useful, +IEEE\ Std\ 1003.1-2001 requires that \fIcount\fP be supported for +all \fBp\fP and \fBP\fP commands. +.LP +Historical implementations of \fIvi\fP were widely known to have major +problems in the \fBp\fP and \fBP\fP commands, +particularly when unusual regions of text were copied into the edit +buffer. The standard developers viewed these as bugs, and they +are not permitted for consistency and simplicity of specification. +.LP +Historically, a \fBP\fP or \fBp\fP command (or an \fIex\fP \fBput\fP +command executed +from open or visual mode) executed in an empty file, left an empty +line as the first line of the file. For consistency and +simplicity of specification, IEEE\ Std\ 1003.1-2001 does not permit +this behavior. +.SS Replace Character +.LP +Historically, the \fBr\fP command did not correctly handle the \fIerase\fP +and \fIword erase\fP characters as arguments, nor +did it handle an associated \fIcount\fP greater than 1 with a +argument, for which it replaced \fIcount\fP +characters with a single . IEEE\ Std\ 1003.1-2001 does not +permit these inconsistencies. +.LP +Historically, the \fBr\fP command permitted the -V escaping +of entered characters, such as and the +; however, it required two leading -V characters +instead of one. +IEEE\ Std\ 1003.1-2001 requires that this be changed for consistency +with the other text input commands of \fIvi\fP. +.LP +Historically, it is an error to enter the \fBr\fP command if there +are less than \fIcount\fP characters at or after the cursor +in the line. While a reasonable and unambiguous extension would be +to permit the \fBr\fP command on empty lines, it would require +that too large a \fIcount\fP be adjusted to match the number of characters +at or after the cursor for consistency, which is +sufficiently different from historical practice to be avoided. IEEE\ Std\ 1003.1-2001 +requires conformance to historical +practice. +.SS Replace Characters +.LP +Historically, if there were \fBautoindent\fP characters in the line +on which the \fBR\fP command was run, and +\fBautoindent\fP was set, the first would be properly indented +and no characters would be replaced by the +. Each additional would replace \fIn\fP characters, +where \fIn\fP was the number of characters +that were needed to indent the rest of the line to the proper indentation +level. This behavior is a bug and is not permitted by +IEEE\ Std\ 1003.1-2001. +.SS Undo +.LP +Historical practice for cursor positioning after undoing commands +was mixed. In most cases, when undoing commands that affected +a single line, the cursor was moved to the start of added or changed +text, or immediately after deleted text. However, if the user +had moved from the line being changed, the column was either set to +the first non- , returned to the origin of the +command, or remained unchanged. When undoing commands that affected +multiple lines or entire lines, the cursor was moved to the +first character in the first line restored. As an example of how inconsistent +this was, a search, followed by an \fBo\fP text +input command, followed by an \fBundo\fP would return the cursor to +the location where the \fBo\fP command was entered, but a +\fBcw\fP command followed by an \fBo\fP command followed by an \fBundo\fP +would return the cursor to the first non- + of the line. IEEE\ Std\ 1003.1-2001 requires the most useful +of these behaviors, and discards the least +useful, in the interest of consistency and simplicity of specification. +.SS Yank +.LP +Historically, the \fByank\fP command did not move to the end of the +motion if the motion was in the forward direction. It moved +to the end of the motion if the motion was in the backward direction, +except for the \fB_\fP command, or for the \fBG\fP and +\fB'\fP commands when the end of the motion was on the current line. +This was further complicated by the fact that for a number of +motion commands, the \fByank\fP command moved the cursor but did not +update the screen; for example, a subsequent command would +move the cursor from the end of the motion, even though the cursor +on the screen had not reflected the cursor movement for the +\fByank\fP command. IEEE\ Std\ 1003.1-2001 requires that all \fByank\fP +commands associated with backward motions move +the cursor to the end of the motion for consistency, and specifically, +to make \fB'\fP commands as motions consistent with search +patterns as motions. +.SS Yank Current Line +.LP +Some historical implementations of the \fBY\fP command did not behave +as described by IEEE\ Std\ 1003.1-2001 when the +\fB'_'\fP key was remapped because they were implemented by pushing +the \fB'_'\fP key onto the input queue and reprocessing +it. IEEE\ Std\ 1003.1-2001 does not permit this behavior. +.SS Redraw Window +.LP +Historically, the \fBz\fP command always redrew the screen. This is +permitted but not required by +IEEE\ Std\ 1003.1-2001, because of the frequent use of the \fBz\fP +command in macros such as \fBmap n nz.\fP for screen +positioning, instead of its use to change the screen size. The standard +developers believed that expanding or scrolling the screen +offered a better interface for users. The ability to redraw the screen +is preserved if the optional new window size is specified, +and in the -L and -R commands. +.LP +The semantics of \fBz^\fP are confusing at best. Historical practice +is that the screen before the screen that ended with the +specified line is displayed. IEEE\ Std\ 1003.1-2001 requires conformance +to historical practice. +.LP +Historically, the \fBz\fP command would not display a partial line +at the top or bottom of the screen. If the partial line +would normally have been displayed at the bottom of the screen, the +command worked, but the partial line was replaced with +\fB'@'\fP characters. If the partial line would normally have been +displayed at the top of the screen, the command would fail. +For consistency and simplicity of specification, IEEE\ Std\ 1003.1-2001 +does not permit this behavior. +.LP +Historically, the \fBz\fP command with a line specification of 1 ignored +the command. For consistency and simplicity of +specification, IEEE\ Std\ 1003.1-2001 does not permit this behavior. +.LP +Historically, the \fBz\fP command did not set the cursor column to +the first non- for the character if the first +screen was to be displayed, and was already displayed. For consistency +and simplicity of specification, +IEEE\ Std\ 1003.1-2001 does not permit this behavior. +.SS Input Mode Commands in vi +.LP +Historical implementations of \fIvi\fP did not permit the user to +erase more than a single line of input, or to use normal +erase characters such as \fIline erase\fP, \fIworderase\fP, and \fIerase\fP +to erase \fBautoindent\fP characters. As there +exist implementations of \fIvi\fP that do not have these limitations, +both behaviors are permitted, but only historical practice +is required. In the case of these extensions, \fIvi\fP is required +to pause at the \fBautoindent\fP and previous line +boundaries. +.LP +Historical implementations of \fIvi\fP updated only the portion of +the screen where the current cursor character was displayed. +For example, consider the \fIvi\fP input keystrokes: +.sp +.RS +.nf + +\fBiabcd0C +\fP +.fi +.RE +.LP +Historically, the would overwrite the characters \fB"abcd"\fP +when it was displayed. Other implementations +replace only the \fB'a'\fP character with the , and then push +the rest of the characters ahead of the cursor. Both +implementations have problems. The historical implementation is probably +visually nicer for the above example; however, for the +keystrokes: +.sp +.RS +.nf + +\fBiabcd0R +\fP +.fi +.RE +.LP +the historical implementation results in the string \fB"bcd"\fP disappearing +and then magically reappearing when the + character is entered. IEEE\ Std\ 1003.1-2001 requires the former +behavior when overwriting erase-columns-that +is, overwriting characters that are no longer logically part of the +edit buffer-and the latter behavior otherwise. +.LP +Historical implementations of \fIvi\fP discarded the -D and +-T characters when they were entered +at places where their command functionality was not appropriate. IEEE\ Std\ 1003.1-2001 +requires that the -T +functionality always be available, and that -D be treated +as any other key when not operating on \fBautoindent\fP +characters. +.SS NUL +.LP +Some historical implementations of \fIvi\fP limited the number of +characters entered using the NUL input character to 256 +bytes. IEEE\ Std\ 1003.1-2001 permits this limitation; however, implementations +are encouraged to remove this limit. +.SS -D +.LP +See also Rationale for the input mode command . The hidden +assumptions in the -D command (and in +the \fIvi\fP \fBautoindent\fP specification in general) is that s +take up a single column on the screen and that +s are comprised of an integral number of s. +.SS +.LP +Implementations are permitted to rewrite \fBautoindent\fP characters +in the line when , , +-D, and -T are entered, or when the \fBshift\fP +commands are used, because historical +implementations have both done so and found it necessary to do so. +For example, a -D when the cursor is preceded by +a single , with \fBtabstop\fP set to 8, and \fBshiftwidth\fP +set to 3, will result in the being replaced +by several s. +.SS -T +.LP +See also the Rationale for the input mode command . Historically, +-T only worked if no non- +s had yet been input in the current input line. In addition, +the characters inserted by -T were treated +as \fBautoindent\fP characters, and could not be erased using normal +user erase characters. Because implementations exist that do +not have these limitations, and as moving to a column boundary is +generally useful, IEEE\ Std\ 1003.1-2001 requires that +both limitations be removed. +.SS -V +.LP +Historically, \fIvi\fP used \fB^V\fP, regardless of the value of the +literal-next character of the terminal. +IEEE\ Std\ 1003.1-2001 requires conformance to historical practice. +.LP +The uses described for -V can also be accomplished with -Q, +which is useful on terminals that use +-V for the down-arrow function. However, most historical +implementations use -Q for the +\fItermios\fP START character, so the editor will generally not receive +the -Q unless \fBstty ixon\fP mode is set +to off. (In addition, some historical implementations of \fIvi\fP +explicitly set \fBixon\fP mode to on, so it was difficult for +the user to set it to off.) Any of the command characters described +in IEEE\ Std\ 1003.1-2001 can be made ineffective by +their selection as \fItermios\fP control characters, using the \fIstty\fP +utility or other +methods described in the System Interfaces volume of IEEE\ Std\ 1003.1-2001. +.SS +.LP +Historically, SIGINT alerted the terminal when used to end input mode. +This behavior is permitted, but not required, by +IEEE\ Std\ 1003.1-2001. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIed\fP , \fIex\fP , \fIstty\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/wait.1p b/man1p/wait.1p new file mode 100644 index 000000000..cfb1a04c1 --- /dev/null +++ b/man1p/wait.1p @@ -0,0 +1,314 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WAIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wait +.SH NAME +wait \- await process completion +.SH SYNOPSIS +.LP +\fBwait\fP \fB[\fP\fIpid\fP\fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +When an asynchronous list (see \fIAsynchronous Lists\fP ) is started +by the +shell, the process ID of the last command in each element of the asynchronous +list shall become known in the current shell +execution environment; see \fIShell Execution Environment\fP . +.LP +If the \fIwait\fP utility is invoked with no operands, it shall wait +until all process IDs known to the invoking shell have +terminated and exit with a zero exit status. +.LP +If one or more \fIpid\fP operands are specified that represent known +process IDs, the \fIwait\fP utility shall wait until all +of them have terminated. If one or more \fIpid\fP operands are specified +that represent unknown process IDs, \fIwait\fP shall +treat them as if they were known process IDs that exited with exit +status 127. The exit status returned by the \fIwait\fP utility +shall be the exit status of the process requested by the last \fIpid\fP +operand. +.LP +The known process IDs are applicable only for invocations of \fIwait\fP +in the current shell execution environment. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIpid\fP +One of the following: +.RS +.IP " 1." 4 +The unsigned decimal integer process ID of a command, for which the +utility is to wait for the termination. +.LP +.IP " 2." 4 +A job control job ID (see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 3.203, Job Control Job ID) that identifies a background process +group to be +waited for. The job control job ID notation is applicable only for +invocations of \fIwait\fP in the current shell execution +environment; see \fIShell Execution Environment\fP . The exit status +of \fIwait\fP shall +be determined by the last command in the pipeline. +.TP 7 +\fBNote:\fP +.RS +The job control job ID type of \fIpid\fP is only available on systems +supporting the User Portability Utilities option. +.RE +.sp +.LP +.RE +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIwait\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +If one or more operands were specified, all of them have terminated +or were not known by the invoking shell, and the status of +the last operand specified is known, then the exit status of \fIwait\fP +shall be the exit status information of the command +indicated by the last operand specified. If the process terminated +abnormally due to the receipt of a signal, the exit status shall +be greater than 128 and shall be distinct from the exit status generated +by other signals, but the exact value is unspecified. (See +the \fIkill\fP \fB-l\fP option.) Otherwise, the \fIwait\fP utility +shall exit with one of +the following values: +.TP 7 +\ \ \ \ 0 +The \fIwait\fP utility was invoked with no operands and all process +IDs known by the invoking shell have terminated. +.TP 7 +1-126 +The \fIwait\fP utility detected an error. +.TP 7 +\ \ 127 +The command identified by the last \fIpid\fP operand specified is +unknown. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +On most implementations, \fIwait\fP is a shell built-in. If it is +called in a subshell or separate utility execution +environment, such as one of the following: +.sp +.RS +.nf + +\fB(wait) +nohup wait ... +find . -exec wait ... \\; +\fP +.fi +.RE +.LP +it returns immediately because there are no known process IDs to wait +for in those environments. +.LP +Historical implementations of interactive shells have discarded the +exit status of terminated background processes before each +shell prompt. Therefore, the status of background processes was usually +lost unless it terminated while \fIwait\fP was waiting for +it. This could be a serious problem when a job that was expected to +run for a long time actually terminated quickly with a syntax +or initialization error because the exit status returned was usually +zero if the requested process ID was not found. This volume of +IEEE\ Std\ 1003.1-2001 requires the implementation to keep the status +of terminated jobs available until the status is +requested, so that scripts like: +.sp +.RS +.nf + +\fBj1& +p1=$! +j2& +wait $p1 +echo Job 1 exited with status $? +wait $! +echo Job 2 exited with status $? +\fP +.fi +.RE +.LP +work without losing status on any of the jobs. The shell is allowed +to discard the status of any process if it determines that +the application cannot get the process ID for that process from the +shell. It is also required to remember only {CHILD_MAX} number +of processes in this way. Since the only way to get the process ID +from the shell is by using the \fB'!'\fP shell parameter, the +shell is allowed to discard the status of an asynchronous list if +\fB"$!"\fP was not referenced before another asynchronous list +was started. (This means that the shell only has to keep the status +of the last asynchronous list started if the application did +not reference \fB"$!"\fP . If the implementation of the shell is smart +enough to determine that a reference to \fB"$!"\fP was +not saved anywhere that the application can retrieve it later, it +can use this information to trim the list of saved information. +Note also that a successful call to \fIwait\fP with no operands discards +the exit status of all asynchronous lists.) +.LP +If the exit status of \fIwait\fP is greater than 128, there is no +way for the application to know if the waited-for process +exited with that value or was killed by a signal. Since most utilities +exit with small values, there is seldom any ambiguity. Even +in the ambiguous cases, most applications just need to know that the +asynchronous job failed; it does not matter whether it +detected an error and failed or was killed and did not complete its +job normally. +.SH EXAMPLES +.LP +Although the exact value used when a process is terminated by a signal +is unspecified, if it is known that a signal terminated a +process, a script can still reliably determine which signal by using +\fIkill\fP as shown by +the following script: +.sp +.RS +.nf + +\fBsleep 1000& +pid=$! +kill -kill $pid +wait $pid +echo $pid was terminated by a SIG$(kill -l $?) signal. +\fP +.fi +.RE +.LP +If the following sequence of commands is run in less than 31 seconds: +.sp +.RS +.nf + +\fBsleep 257 | sleep 31 & +jobs -l %% +\fP +.fi +.RE +.LP +either of the following commands returns the exit status of the second +\fIsleep\fP in the +pipeline: +.sp +.RS +.nf + +\fBwait\fP \fI\fP\fBwait %% +\fP +.fi +.RE +.SH RATIONALE +.LP +The description of \fIwait\fP does not refer to the \fIwaitpid\fP() +function from the +System Interfaces volume of IEEE\ Std\ 1003.1-2001 because that would +needlessly overspecify this interface. However, the +wording means that \fIwait\fP is required to wait for an explicit +process when it is given an argument so that the status +information of other processes is not consumed. Historical implementations +use the \fIwait\fP() function defined in the System Interfaces volume +of IEEE\ Std\ 1003.1-2001 until +\fIwait\fP() returns the requested process ID or finds that the requested +process does not +exist. Because this means that a shell script could not reliably get +the status of all background children if a second background +job was ever started before the first job finished, it is recommended +that the \fIwait\fP utility use a method such as the +functionality provided by the \fIwaitpid\fP() function. +.LP +The ability to wait for multiple \fIpid\fP operands was adopted from +the KornShell. +.LP +This new functionality was added because it is needed to determine +the exit status of any asynchronous list accurately. The only +compatibility problem that this change creates is for a script like +.sp +.RS +.nf + +\fBwhile sleep 60 do + job& echo Job started $(date) as $! done +\fP +.fi +.RE +.LP +which causes the shell to monitor all of the jobs started until the +script terminates or runs out of memory. This would not be a +problem if the loop did not reference \fB"$!"\fP or if the script +would occasionally \fIwait\fP for jobs it started. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP , \fIkill\fP() , \fIsh\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIwait\fP(), \fIwaitpid\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/wc.1p b/man1p/wc.1p new file mode 100644 index 000000000..8a71c8c60 --- /dev/null +++ b/man1p/wc.1p @@ -0,0 +1,230 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wc +.SH NAME +wc \- word, line, and byte or character count +.SH SYNOPSIS +.LP +\fBwc\fP \fB[\fP\fB-c|-m\fP\fB][\fP\fB-lw\fP\fB][\fP\fIfile\fP\fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIwc\fP utility shall read one or more input files and, by default, +write the number of s, words, and bytes +contained in each input file to the standard output. +.LP +The utility also shall write a total count for all named files, if +more than one input file is specified. +.LP +The \fIwc\fP utility shall consider a \fIword\fP to be a non-zero-length +string of characters delimited by white space. +.SH OPTIONS +.LP +The \fIwc\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-c\fP +Write to the standard output the number of bytes in each input file. +.TP 7 +\fB-l\fP +Write to the standard output the number of s in each input +file. +.TP 7 +\fB-m\fP +Write to the standard output the number of characters in each input +file. +.TP 7 +\fB-w\fP +Write to the standard output the number of words in each input file. +.sp +.LP +When any option is specified, \fIwc\fP shall report only the information +requested by the specified options. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of an input file. If no \fIfile\fP operands are specified, +the standard input shall be used. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified. See the INPUT FILES section. +.SH INPUT FILES +.LP +The input files may be of any type. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIwc\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and +which characters are defined as white space characters. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +By default, the standard output shall contain an entry for each input +file of the form: +.sp +.RS +.nf + +\fB"%d %d %d %s\\n", <\fP\fInewlines\fP\fB>, <\fP\fIwords\fP\fB>, <\fP\fIbytes\fP\fB>, <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +If the \fB-m\fP option is specified, the number of characters shall +replace the <\fIbytes\fP> field in this format. +.LP +If any options are specified and the \fB-l\fP option is not specified, +the number of s shall not be written. +.LP +If any options are specified and the \fB-w\fP option is not specified, +the number of words shall not be written. +.LP +If any options are specified and neither \fB-c\fP nor \fB-m\fP is +specified, the number of bytes or characters shall not be +written. +.LP +If no input \fIfile\fP operands are specified, no name shall be written +and no s preceding the pathname shall be +written. +.LP +If more than one input \fIfile\fP operand is specified, an additional +line shall be written, of the same format as the other +lines, except that the word \fBtotal\fP (in the POSIX locale) shall +be written instead of a pathname and the total of each column +shall be written as appropriate. Such an additional line, if any, +is written at the end of the output. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fB-m\fP option is not a switch, but an option at the same level +as \fB-c\fP. Thus, to produce the full default output +with character counts instead of bytes, the command required is: +.sp +.RS +.nf + +\fBwc -mlw +\fP +.fi +.RE +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The output file format pseudo- \fIprintf\fP() string differs from +the System V version +of \fIwc\fP: +.sp +.RS +.nf + +\fB"%7d%7d%7d %s\\n" +\fP +.fi +.RE +.LP +which produces possibly ambiguous and unparsable results for very +large files, as it assumes no number shall exceed six +digits. +.LP +Some historical implementations use only , , and +as word separators. The equivalent of +the ISO\ C standard \fIisspace\fP() function is more appropriate. +.LP +The \fB-c\fP option stands for "character" count, even though it counts +bytes. This stems from the sometimes erroneous +historical view that bytes and characters are the same size. Due to +international requirements, the \fB-m\fP option (reminiscent +of "multi-byte") was added to obtain actual character counts. +.LP +Early proposals only specified the results when input files were text +files. The current specification more closely matches +historical practice. (Bytes, words, and s are counted separately +and the results are written when an end-of-file is +detected.) +.LP +Historical implementations of the \fIwc\fP utility only accepted one +argument to specify the options \fB-c\fP, \fB-l\fP, and +\fB-w\fP. Some of them also had multiple occurrences of an option +cause the corresponding count to be written multiple times and +had the order of specification of the options affect the order of +the fields on output, but did not document either of these. +Because common usage either specifies no options or only one option, +and because none of this was documented, the changes required +by this volume of IEEE\ Std\ 1003.1-2001 should not break many historical +applications (and do not break any historical +conforming applications). +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcksum\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/what.1p b/man1p/what.1p new file mode 100644 index 000000000..08f24b4b2 --- /dev/null +++ b/man1p/what.1p @@ -0,0 +1,185 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WHAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" what +.SH NAME +what \- identify SCCS files (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBwhat\fP \fB[\fP\fB-s\fP\fB]\fP \fIfile\fP\fB... \fP +.SH DESCRIPTION +.LP +The \fIwhat\fP utility shall search the given files for all occurrences +of the pattern that \fIget\fP (see \fIget\fP ) substitutes for the +%\fBZ\fP% keyword ( +\fB"@(#)"\fP ) and shall write to standard output what follows until +the first occurrence of one of the following: +.sp +.RS +.nf + +\fB" > newline \\ NUL +\fP +.fi +.RE +.SH OPTIONS +.LP +The \fIwhat\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-s\fP +Quit after finding the first occurrence of the pattern in each file. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIfile\fP +A pathname of a file to search. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +The input files shall be of any file type. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIwhat\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall consist of the following for each \fIfile\fP +operand: +.sp +.RS +.nf + +\fB"%s:\\n\\t%s\\n", <\fP\fIpathname\fP\fB>, <\fP\fIidentification string\fP\fB> +\fP +.fi +.RE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +0 +Any matches were found. +.TP 7 +1 +Otherwise. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fIwhat\fP utility is intended to be used in conjunction with +the SCCS command \fIget\fP, which automatically inserts identifying +information, but it can also be used where the +information is inserted by any other means. +.LP +When the string \fB"@(#)"\fP is included in a library routine in a +shared library, it might not be found in an \fBa.out\fP +file using that library routine. +.SH EXAMPLES +.LP +If the C-language program in file \fBf.c\fP contains: +.sp +.RS +.nf + +\fBchar ident[] = "@(#)identification information"; +\fP +.fi +.RE +.LP +and \fBf.c\fP is compiled to yield \fBf.o\fP and \fBa.out\fP, then +the command: +.sp +.RS +.nf + +\fBwhat f.c f.o a.out +\fP +.fi +.RE +.LP +writes: +.sp +.RS +.nf + +\fBf.c: + identification information + ... +f.o: + identification information + ... +a.out: + identification information + ... +\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIget\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/who.1p b/man1p/who.1p new file mode 100644 index 000000000..e9245ed86 --- /dev/null +++ b/man1p/who.1p @@ -0,0 +1,311 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WHO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" who +.SH NAME +who \- display who is on the system +.SH SYNOPSIS +.LP +\fBwho\fP \fB[\fP\fB-mTu\fP\fB]\fP\fB +.br +.sp +\fP +.LP +\fBwho\fP +\fB[\fP\fB-mu\fP\fB]\fP\fB-s\fP\fB[\fP\fB-bHlprt\fP\fB][\fP\fIfile\fP\fB]\fP\fB +.br +.sp +who\fP \fB[\fP\fB-mTu\fP\fB][\fP\fB-abdHlprt\fP\fB][\fP\fIfile\fP\fB]\fP\fB +.br +.sp +who -q\fP \fB[\fP\fIfile\fP\fB]\fP\fB +.br +.sp +who am i +.br +.sp +who am I \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIwho\fP utility shall list various pieces of information about +accessible users. The domain of accessibility is +implementation-defined. +.LP +Based on the options given, \fIwho\fP can also list the user's name, +terminal line, login time, elapsed time since activity +occurred on the line, and the process ID of the command interpreter +for each current system user. +.SH OPTIONS +.LP +The \fIwho\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported. The metavariables, such +as <\fIline\fP>, refer to fields described in the +STDOUT section. +.TP 7 +\fB-a\fP +Process the implementation-defined database or named file with the +\fB-b\fP, \fB-d\fP, \fB-l\fP, \fB-p\fP, \fB-r\fP, +\fB-t\fP, \fB-T\fP and \fB-u\fP options turned on. +.TP 7 +\fB-b\fP +Write the time and date of the last reboot. +.TP 7 +\fB-d\fP +Write a list of all processes that have expired and not been respawned +by the \fIinit\fP system process. The <\fIexit\fP> +field shall appear for dead processes and contain the termination +and exit values of the dead process. This can be useful in +determining why a process terminated. +.TP 7 +\fB-H\fP +Write column headings above the regular output. +.TP 7 +\fB-l\fP +(The letter ell.) List only those lines on which the system is waiting +for someone to login. The <\fIname\fP> field shall be +\fBLOGIN\fP in such cases. Other fields shall be the same as for user +entries except that the <\fIstate\fP> field does not +exist. +.TP 7 +\fB-m\fP +Output only information about the current terminal. +.TP 7 +\fB-p\fP +List any other process that is currently active and has been previously +spawned by \fIinit\fP. +.TP 7 +\fB-q\fP +(Quick.) List only the names and the number of users currently logged +on. When this option is used, all other options shall be +ignored. +.TP 7 +\fB-r\fP +Write the current \fIrun-level\fP of the \fIinit\fP process. +.TP 7 +\fB-s\fP +List only the <\fIname\fP>, <\fIline\fP>, and <\fItime\fP> fields. +This is the default case. +.TP 7 +\fB-t\fP +Indicate the last change to the system clock. +.TP 7 +\fB-T\fP +Show the state of each terminal, as described in the STDOUT section. +.TP 7 +\fB-u\fP +Write "idle time" for each displayed user in addition to any other +information. The idle time is the time since any activity +occurred on the user's terminal. The method of determining this is +unspecified. \ This option +shall list only those users who are currently logged in. The <\fIname\fP> +is the user's login name. The <\fIline\fP> +is the name of the line as found in the directory \fB/dev\fP. The +<\fItime\fP> is the time that the user logged in. The +<\fIactivity\fP> is the number of hours and minutes since activity +last occurred on that particular line. A dot indicates +that the terminal has seen activity in the last minute and is therefore +"current". If more than twenty-four hours have elapsed or +the line has not been used since boot time, the entry shall be marked +<\fIold\fP>. This field is useful when trying to +determine whether a person is working at the terminal or not. The +<\fIpid\fP> is the process ID of the user's login process. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fBam\ i\fP,\ \fBam\ I\fP +In the POSIX locale, limit the output to describing the invoking user, +equivalent to the \fB-m\fP option. The \fBam\fP and +\fBi\fP or \fBI\fP must be separate arguments. +.TP 7 +\fIfile\fP +Specify a pathname of a file to substitute for the implementation-defined +database of logged-on users that \fIwho\fP uses by +default. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIwho\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fILC_TIME\fP +Determine the locale used for the format and contents of the date +and time strings. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITZ\fP +Determine the timezone used when writing date and time information. +If \fITZ\fP is unset or null, an unspecified default +timezone shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fIwho\fP utility shall write its default format to the standard +output in an implementation-defined format, subject only +to the requirement of containing the information described above. +.LP +XSI-conformant systems shall write the default information to the +standard output in the following general format: +.sp +.RS +.nf + +\fB<\fP\fIname\fP\fB>\fP\fB[\fP\fB<\fP\fIstate\fP\fB>\fP\fB]\fP\fB<\fP\fIline\fP\fB><\fP\fItime\fP\fB>\fP\fB[\fP\fB<\fP\fIactivity\fP\fB>\fP\fB][\fP\fB<\fP\fIpid\fP\fB>\fP\fB][\fP\fB<\fP\fIcomment\fP\fB>\fP\fB][\fP\fB<\fP\fIexit\fP\fB>\fP\fB]\fP \fB +\fP +.fi +.RE +.LP +The following format shall be used for the \fB-T\fP option: +.sp +.RS +.nf + +\fB"%s %c %s %s\\n" <\fP\fIname\fP\fB>, <\fP\fIterminal state\fP\fB>, <\fP\fIterminal name\fP\fB>, + <\fP\fItime of login\fP\fB> +\fP +.fi +.RE +.LP +where <\fIterminal\ state\fP> is one of the following characters: +.TP 7 +\fB+\fP +The terminal allows write access to other users. +.TP 7 +\fB-\fP +The terminal denies write access to other users. +.TP 7 +\fB?\fP +The terminal write-access state cannot be determined. +.sp +.LP +In the POSIX locale, the <\fItime\ of\ login\fP> shall be equivalent +in format to the output of: +.sp +.RS +.nf + +\fBdate +"%b %e %H:%M" +\fP +.fi +.RE +.LP +If the \fB-u\fP option is used with \fB-T\fP, the idle time shall +be added to the end of the previous format in an unspecified +format. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The name \fIinit\fP used for the system process is the most commonly +used on historical systems, but it may vary. +.LP +The "domain of accessibility" referred to is a broad concept that +permits interpretation either on a very secure basis or even +to allow a network-wide implementation like the historical \fIrwho\fP. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +Due to differences between historical implementations, the base options +provided were a compromise to allow users to work with +those functions. The standard developers also considered removing +all the options, but felt that these options offered users +valuable functionality. Additional options to match historical systems +are available on XSI-conformant systems. +.LP +It is recognized that the \fIwho\fP command may be of limited usefulness, +especially in a multi-level secure environment. The +standard developers considered, however, that having some standard +method of determining the "accessibility" of other users would +aid user portability. +.LP +No format was specified for the default \fIwho\fP output for systems +not supporting the XSI Extension. In such a user-oriented +command, designed only for human use, this was not considered to be +a deficiency. +.LP +The format of the terminal name is unspecified, but the descriptions +of \fIps\fP, \fItalk\fP, and \fIwrite\fP require that they use the +same +format. +.LP +It is acceptable for an implementation to produce no output for an +invocation of \fIwho\fP \fBmil\fP. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImesg\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/write.1p b/man1p/write.1p new file mode 100644 index 000000000..e7906c138 --- /dev/null +++ b/man1p/write.1p @@ -0,0 +1,219 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WRITE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" write +.SH NAME +write \- write to another user +.SH SYNOPSIS +.LP +\fBwrite\fP \fIuser_name\fP \fB[\fP\fIterminal\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIwrite\fP utility shall read lines from the user's standard +input and write them to the terminal of another user. When +first invoked, it shall write the message: +.sp +.RS +.nf + +\fBMessage from\fP \fIsender-login-id\fP \fB(\fP\fIsending-terminal\fP\fB)\fP \fB[\fP\fIdate\fP\fB]\fP\fB... +\fP +.fi +.RE +.LP +to \fIuser_name\fP. When it has successfully completed the connection, +the sender's terminal shall be alerted twice to indicate +that what the sender is typing is being written to the recipient's +terminal. +.LP +If the recipient wants to reply, this can be accomplished by typing: +.sp +.RS +.nf + +\fBwrite\fP \fIsender-login-id\fP \fB[\fP\fIsending-terminal\fP\fB]\fP +.fi +.RE +.LP +upon receipt of the initial message. Whenever a line of input as delimited +by an NL, EOF, or EOL special character (see the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General +Terminal +Interface) is accumulated while in canonical input mode, the accumulated +data shall be written on the other user's terminal. +Characters shall be processed as follows: +.IP " *" 3 +Typing shall write the alert character to the recipient's +terminal. +.LP +.IP " *" 3 +Typing the erase and kill characters shall affect the sender's terminal +in the manner described by the \fBtermios\fP interface +in the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter +11, General +Terminal Interface. +.LP +.IP " *" 3 +Typing the interrupt or end-of-file characters shall cause \fIwrite\fP +to write an appropriate message ( \fB"EOT\\n"\fP in +the POSIX locale) to the recipient's terminal and exit. +.LP +.IP " *" 3 +Typing characters from \fILC_CTYPE\fP classifications \fBprint\fP +or \fBspace\fP shall cause those characters to be sent to +the recipient's terminal. +.LP +.IP " *" 3 +When and only when the \fIstty\fP \fBiexten\fP local mode is enabled, +the existence and +processing of additional special control characters and multi-byte +or single-byte functions is implementation-defined. +.LP +.IP " *" 3 +Typing other non-printable characters shall cause implementation-defined +sequences of printable characters to be written to the +recipient's terminal. +.LP +.LP +To write to a user who is logged in more than once, the \fIterminal\fP +argument can be used to indicate which terminal to write +to; otherwise, the recipient's terminal is selected in an implementation-defined +manner and an informational message is written to +the sender's standard output, indicating which terminal was chosen. +.LP +Permission to be a recipient of a \fIwrite\fP message can be denied +or granted by use of the \fImesg\fP utility. However, a user's privilege +may further constrain the domain of accessibility of +other users' terminals. The \fIwrite\fP utility shall fail when the +user lacks the appropriate privileges to perform the requested +action. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIuser_name\fP +Login name of the person to whom the message shall be written. The +application shall ensure that this operand is of the form +returned by the \fIwho\fP utility. +.TP 7 +\fIterminal\fP +Terminal identification in the same format provided by the \fIwho\fP +utility. +.sp +.SH STDIN +.LP +Lines to be copied to the recipient's terminal are read from standard +input. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIwrite\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). If +the recipient's locale does not use an \fILC_CTYPE\fP +equivalent to the sender's, the results are undefined. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +If an interrupt signal is received, \fIwrite\fP shall write an appropriate +message on the recipient's terminal and exit with a +status of zero. It shall take the standard action for all other signals. +.SH STDOUT +.LP +An informational message shall be written to standard output if a +recipient is logged in more than once. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +The recipient's terminal is used for output. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +The addressed user is not logged on or the addressed user denies permission. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fItalk\fP utility is considered by some users to be a more usable +utility on +full-screen terminals. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIwrite\fP utility was included in this volume of IEEE\ Std\ 1003.1-2001 +since it can be implemented on all +terminal types. The standard developers considered the \fItalk\fP +utility, which cannot be +implemented on certain terminals, to be a "better" communications +interface. Both of these programs are in widespread use on +historical implementations. Therefore, the standard developers decided +that both utilities should be specified. +.LP +The format of the terminal name is unspecified, but the descriptions +of \fIps\fP, \fItalk\fP, \fIwho\fP, and \fIwrite\fP require that they +all +use or accept the same format. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImesg\fP , \fItalk\fP , \fIwho\fP , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General +Terminal +Interface +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/xargs.1p b/man1p/xargs.1p new file mode 100644 index 000000000..a86964952 --- /dev/null +++ b/man1p/xargs.1p @@ -0,0 +1,515 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "XARGS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" xargs +.SH NAME +xargs \- construct argument lists and invoke utility +.SH SYNOPSIS +.LP +\fBxargs\fP +\fB[\fP\fB-t\fP\fB][\fP\fB-p\fP\fB]][\fP\fB-E\fP \fIeofstr\fP\fB][\fP\fB-I\fP +\fIreplstr\fP\fB][\fP\fB-L\fP \fInumber\fP\fB][\fP\fB-n\fP \fInumber\fP +\fB[\fP\fB-x\fP\fB]] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-s\fP \fIsize\fP\fB][\fP\fIutility\fP +\fB[\fP\fIargument\fP\fB...\fP\fB]]\fP +.SH DESCRIPTION +.LP +The \fIxargs\fP utility shall construct a command line consisting +of the \fIutility\fP and \fIargument\fP operands specified +followed by as many arguments read in sequence from standard input +as fit in length and number constraints specified by the +options. The \fIxargs\fP utility shall then invoke the constructed +command line and wait for its completion. This sequence shall +be repeated until one of the following occurs: +.IP " *" 3 +An end-of-file condition is detected on standard input. +.LP +.IP " *" 3 +The logical end-of-file string (see the \fB-E\fP \fIeofstr\fP option) +is found on standard input after double-quote +processing, apostrophe processing, and backslash escape processing +(see next paragraph). +.LP +.IP " *" 3 +An invocation of a constructed command line returns an exit status +of 255. +.LP +.LP +The application shall ensure that arguments in the standard input +are separated by unquoted s, unescaped +s, or s. A string of zero or more non-double-quote +( \fB' )'\fP characters and non- s +can be quoted by enclosing them in double-quotes. A string of zero +or more non-apostrophe ( \fB'"\fP ) characters and non- +s can be quoted by enclosing them in apostrophes. Any unquoted +character can be escaped by preceding it with a +backslash. The utility named by \fIutility\fP shall be executed one +or more times until the end-of-file is reached or the logical +end-of file string is found. The results are unspecified if the utility +named by \fIutility\fP attempts to read from its standard +input. +.LP +The generated command line length shall be the sum of the size in +bytes of the utility name and each argument treated as +strings, including a null byte terminator for each of these strings. +The \fIxargs\fP utility shall limit the command line length +such that when the command line is invoked, the combined argument +and environment lists (see the \fIexec\fP family of functions in +the System Interfaces volume of IEEE\ Std\ 1003.1-2001) shall not +exceed {ARG_MAX}-2048 bytes. Within this constraint, if +neither the \fB-n\fP nor the \fB-s\fP option is specified, the default +command line length shall be at least {LINE_MAX}. +.SH OPTIONS +.LP +The \fIxargs\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-E\ \fP \fIeofstr\fP +Use \fIeofstr\fP as the logical end-of-file string. If \fB-E\fP is +not specified, it is unspecified whether the logical +end-of-file string is the underscore character ( \fB'_'\fP ) or the +end-of-file string capability is disabled. When +\fIeofstr\fP is the null string, the logical end-of-file string capability +shall be disabled and underscore characters shall be +taken literally. +.TP 7 +\fB-I\ \fP \fIreplstr\fP +Insert mode: \fIutility\fP is executed for each line from standard +input, taking the entire line as a single argument, inserting +it in \fIargument\fPs for each occurrence of \fIreplstr\fP. A maximum +of five arguments in \fIargument\fPs can each contain one +or more instances of \fIreplstr\fP. Any s at the beginning +of each line shall be ignored. Constructed arguments +cannot grow larger than 255 bytes. Option \fB-x\fP shall be forced +on. +.TP 7 +\fB-L\ \fP \fInumber\fP +The \fIutility\fP shall be executed for each non-empty \fInumber\fP +lines of arguments from standard input. The last invocation +of \fIutility\fP shall be with fewer lines of arguments if fewer than +\fInumber\fP remain. A line is considered to end with the +first unless the last character of the line is a ; +a trailing signals continuation to +the next non-empty line, inclusive. The \fB-L\fP and \fB-n\fP options +are mutually-exclusive; the last one specified shall take +effect. +.TP 7 +\fB-n\ \fP \fInumber\fP +Invoke \fIutility\fP using as many standard input arguments as possible, +up to \fInumber\fP (a positive decimal integer) +arguments maximum. Fewer arguments shall be used if: +.RS +.IP " *" 3 +The command line length accumulated exceeds the size specified by +the \fB-s\fP option (or {LINE_MAX} if there is no \fB-s\fP +option). +.LP +.IP " *" 3 +The last iteration has fewer than \fInumber\fP, but not zero, operands +remaining. +.LP +.RE +.TP 7 +\fB-p\fP +Prompt mode: the user is asked whether to execute \fIutility\fP at +each invocation. Trace mode ( \fB-t\fP) is turned on to +write the command instance to be executed, followed by a prompt to +standard error. An affirmative response read from +\fB/dev/tty\fP shall execute the command; otherwise, that particular +invocation of \fIutility\fP shall be skipped. +.TP 7 +\fB-s\ \fP \fIsize\fP +Invoke \fIutility\fP using as many standard input arguments as possible +yielding a command line length less than \fIsize\fP +(a positive decimal integer) bytes. Fewer arguments shall be used +if: +.RS +.IP " *" 3 +The total number of arguments exceeds that specified by the \fB-n\fP +option. +.LP +.IP " *" 3 +The total number of lines exceeds that specified by the \fB-L\fP option. +.LP +.IP " *" 3 +End-of-file is encountered on standard input before \fIsize\fP bytes +are accumulated. +.LP +.RE +.LP +Values of \fIsize\fP up to at least {LINE_MAX} bytes shall be supported, +provided that the constraints specified in the +DESCRIPTION are met. It shall not be considered an error if a value +larger than that supported by the implementation or exceeding +the constraints specified in the DESCRIPTION is given; \fIxargs\fP +shall use the largest value it supports within the +constraints. +.TP 7 +\fB-t\fP +Enable trace mode. Each generated command line shall be written to +standard error just prior to invocation. +.TP 7 +\fB-x\fP +Terminate if a command line containing \fInumber\fP arguments (see +the \fB-n\fP option above) \ or +\fInumber\fP lines (see the \fB-L\fP option above) will not fit +in the implied or specified size (see the \fB-s\fP option above). +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIutility\fP +The name of the utility to be invoked, found by search path using +the \fIPATH\fP environment variable, described in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment +Variables. +If \fIutility\fP is omitted, the default shall be the \fIecho\fP utility. +If the +\fIutility\fP operand names any of the special built-in utilities +in \fISpecial Built-In +Utilities\fP , the results are undefined. +.TP 7 +\fIargument\fP +An initial option or operand for the invocation of \fIutility\fP. +.sp +.SH STDIN +.LP +The standard input shall be a text file. The results are unspecified +if an end-of-file condition is detected immediately +following an escaped . +.SH INPUT FILES +.LP +The file \fB/dev/tty\fP shall be used to read responses required by +the \fB-p\fP option. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIxargs\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended +regular expression defined for the \fByesexpr\fP locale keyword in +the \fILC_MESSAGES\fP category. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and +the behavior of character classes used in the extended regular +expression defined for the \fByesexpr\fP locale keyword in the \fILC_MESSAGES\fP +category. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale for the processing of affirmative responses and +that should be used to affect the format and contents of +diagnostic messages written to standard error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPATH\fP +Determine the location of \fIutility\fP, as described in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment +Variables. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used for diagnostic messages and the \fB-t\fP +and \fB-p\fP options. If the \fB-t\fP option is +specified, the \fIutility\fP and its constructed argument list shall +be written to standard error, as it will be invoked, prior to +invocation. If \fB-p\fP is specified, a prompt of the following format +shall be written (in the POSIX locale): +.sp +.RS +.nf + +\fB"?..." +\fP +.fi +.RE +.LP +at the end of the line of the output from \fB-t\fP. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ \ \ \ 0 +All invocations of \fIutility\fP returned exit status zero. +.TP 7 +1-125 +A command line meeting the specified requirements could not be assembled, +one or more of the invocations of \fIutility\fP +returned a non-zero exit status, or some other error occurred. +.TP 7 +\ \ 126 +The utility specified by \fIutility\fP was found but could not be +invoked. +.TP 7 +\ \ 127 +The utility specified by \fIutility\fP could not be found. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If a command line meeting the specified requirements cannot be assembled, +the utility cannot be invoked, an invocation of the +utility is terminated by a signal, or an invocation of the utility +exits with exit status 255, the \fIxargs\fP utility shall write +a diagnostic message and exit without processing any remaining input. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The 255 exit status allows a utility being used by \fIxargs\fP to +tell \fIxargs\fP to terminate if it knows no further +invocations using the current data stream will succeed. Thus, \fIutility\fP +should explicitly \fIexit\fP with an appropriate value to avoid accidentally +returning with 255. +.LP +Note that input is parsed as lines; s separate arguments. If +\fIxargs\fP is used to bundle output of commands like +\fIfind\fP \fIdir\fP \fB-print\fP or \fIls\fP into +commands to be executed, unexpected results are likely if any filenames +contain any s or s. This can be +fixed by using \fIfind\fP to call a script that converts each file +found into a quoted string +that is then piped to \fIxargs\fP. Note that the quoting rules used +by \fIxargs\fP are not the same as in the shell. They were +not made consistent here because existing applications depend on the +current rules and the shell syntax is not fully compatible +with it. An easy rule that can be used to transform any string into +a quoted form that \fIxargs\fP interprets correctly is to +precede each character in the string with a backslash. +.LP +On implementations with a large value for {ARG_MAX}, \fIxargs\fP may +produce command lines longer than {LINE_MAX}. For +invocation of utilities, this is not a problem. If \fIxargs\fP is +being used to create a text file, users should explicitly set +the maximum command line length with the \fB-s\fP option. +.LP +The \fIcommand\fP, \fIenv\fP, \fInice\fP, \fInohup\fP, \fItime\fP, +and \fIxargs\fP utilities have been specified to use exit code 127 +if an error occurs so +that applications can distinguish "failure to find a utility" from +"invoked utility exited with an error indication". The value +127 was chosen because it is not commonly used for other meanings; +most utilities use small values for "normal error conditions'' +and the values above 128 can be confused with termination due to receipt +of a signal. The value 126 was chosen in a similar manner +to indicate that the utility could be found, but not invoked. Some +scripts produce meaningful error messages differentiating the +126 and 127 cases. The distinction between exit codes 126 and 127 +is based on KornShell practice that uses 127 when all attempts to +\fIexec\fP the utility fail with [ENOENT], and uses 126 when any attempt +to \fIexec\fP the utility fails for any other +reason. +.SH EXAMPLES +.IP " 1." 4 +The following command combines the output of the parenthesised commands +onto one line, which is then written to the end-of-file +\fBlog\fP: +.sp +.RS +.nf + +\fB(logname; date; printf "%s\\n" "$0 $*") | xargs >>log +\fP +.fi +.RE +.LP +.IP " 2." 4 +The following command invokes \fIdiff\fP with successive pairs of +arguments originally +typed as command line arguments (assuming there are no embedded s +in the elements of the original argument list): +.sp +.RS +.nf + +\fBprintf "%s\\n" "$*" | xargs -n 2 -x diff +\fP +.fi +.RE +.LP +.IP " 3." 4 +In the following commands, the user is asked which files in the current +directory are to be archived. The files are archived +into \fBarch\fP; \fIa\fP, one at a time, or \fIb\fP, many at a time. +.sp +.RS +.nf + +\fBa. ls | xargs -p -L 1 ar -r arch +.sp + +b. ls | xargs -p -L 1 | xargs ar -r arch +\fP +.fi +.RE +.LP +.IP " 4." 4 +The following executes with successive pairs of arguments originally +typed as command line arguments: +.sp +.RS +.nf + +\fBecho $* | xargs -n 2 diff +\fP +.fi +.RE +.LP +.IP " 5." 4 +On XSI-conformant systems, the following moves all files from directory +\fB$1\fP to directory \fB$2\fP, and echoes each move +command just before doing it: +.sp +.RS +.nf + +\fBls $1 | xargs -I {} -t mv $1/{} $2/{} +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +The \fIxargs\fP utility was usually found only in System V-based systems; +BSD systems included an \fIapply\fP utility that +provided functionality similar to \fIxargs\fP \fB-n\fP \fInumber\fP. +The SVID lists \fIxargs\fP as a software development +extension. This volume of IEEE\ Std\ 1003.1-2001 does not share the +view that it is used only for development, and +therefore it is not optional. +.LP +The classic application of the \fIxargs\fP utility is in conjunction +with the \fIfind\fP +utility to reduce the number of processes launched by a simplistic +use of the \fIfind\fP +\fB-exec\fP combination. The \fIxargs\fP utility is also used to enforce +an upper limit on memory required to launch a process. +With this basis in mind, this volume of IEEE\ Std\ 1003.1-2001 selected +only the minimal features required. +.LP +Although the 255 exit status is mostly an accident of historical implementations, +it allows a utility being used by \fIxargs\fP +to tell \fIxargs\fP to terminate if it knows no further invocations +using the current data stream shall succeed. Any non-zero exit +status from a utility falls into the 1-125 range when \fIxargs\fP +exits. There is no statement of how the various non-zero utility +exit status codes are accumulated by \fIxargs\fP. The value could +be the addition of all codes, their highest value, the last one +received, or a single value such as 1. Since no algorithm is arguably +better than the others, and since many of the standard +utilities say little more (portably) than "pass/fail", no new algorithm +was invented. +.LP +Several other \fIxargs\fP options were withdrawn because simple alternatives +already exist within this volume of +IEEE\ Std\ 1003.1-2001. For example, the \fB-i\fP \fIreplstr\fP option +can be just as efficiently performed using a shell +\fBfor\fP loop. Since \fIxargs\fP calls an \fIexec\fP function with +each input line, the \fB-i\fP option does not usually +exploit the grouping capabilities of \fIxargs\fP. +.LP +The requirement that \fIxargs\fP never produces command lines such +that invocation of \fIutility\fP is within 2048 bytes of +hitting the POSIX \fIexec\fP {ARG_MAX} limitations is intended to +guarantee that the invoked utility has room to modify its +environment variables and command line arguments and still be able +to invoke another utility. Note that the minimum {ARG_MAX} +allowed by the System Interfaces volume of IEEE\ Std\ 1003.1-2001 +is 4096 bytes and the minimum value allowed by this +volume of IEEE\ Std\ 1003.1-2001 is 2048 bytes; therefore, the 2048 +bytes difference seems reasonable. Note, however, that +\fIxargs\fP may never be able to invoke a utility if the environment +passed in to \fIxargs\fP comes close to using {ARG_MAX} +bytes. +.LP +The version of \fIxargs\fP required by this volume of IEEE\ Std\ 1003.1-2001 +is required to wait for the completion of +the invoked command before invoking another command. This was done +because historical scripts using \fIxargs\fP assumed sequential +execution. Implementations wanting to provide parallel operation of +the invoked utilities are encouraged to add an option enabling +parallel invocation, but should still wait for termination of all +of the children before \fIxargs\fP terminates normally. +.LP +The \fB-e\fP option was omitted from the ISO\ POSIX-2:1993 standard +in the belief that the \fIeofstr\fP option-argument +was recognized only when it was on a line by itself and before quote +and escape processing were performed, and that the logical +end-of-file processing was only enabled if a \fB-e\fP option was specified. +In that case, a simple \fIsed\fP script could be used to duplicate +the \fB-e\fP functionality. Further investigation +revealed that: +.IP " *" 3 +The logical end-of-file string was checked for after quote and escape +processing, making a \fIsed\fP script that provided equivalent functionality +much more difficult to write. +.LP +.IP " *" 3 +The default was to perform logical end-of-file processing with an +underscore as the logical end-of-file string. +.LP +.LP +To correct this misunderstanding, the \fB-E\fP \fIeofstr\fP option +was adopted from the X/Open Portability Guide. Users should +note that the description of the \fB-E\fP option matches historical +documentation of the \fB-e\fP option (which was not adopted +because it did not support the Utility Syntax Guidelines), by saying +that if \fIeofstr\fP is the null string, logical end-of-file +processing is disabled. Historical implementations of \fIxargs\fP +actually did not disable logical end-of-file processing; they +treated a null argument found in the input as a logical end-of-file +string. (A null \fIstring\fP argument could be generated using +single or double quotes ( \fB''\fP or \fB""\fP ). Since this behavior +was not documented historically, it is considered to be +a bug. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP , \fIecho\fP , \fIfind\fP , the System +Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIexec\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/yacc.1p b/man1p/yacc.1p new file mode 100644 index 000000000..bc80e4f22 --- /dev/null +++ b/man1p/yacc.1p @@ -0,0 +1,1285 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "YACC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" yacc +.SH NAME +yacc \- yet another compiler compiler (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fByacc\fP \fB[\fP\fB-dltv\fP\fB][\fP\fB-b\fP \fIfile_prefix\fP\fB][\fP\fB-p\fP +\fIsym_prefix\fP\fB]\fP \fIgrammar\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIyacc\fP utility shall read a description of a context-free +grammar in \fIgrammar\fP and write C source code, conforming +to the ISO\ C standard, to a code file, and optionally header information +into a header file, in the current directory. The C +code shall define a function and related routines and macros for an +automaton that executes a parsing algorithm meeting the +requirements in Algorithms . +.LP +The form and meaning of the grammar are described in the EXTENDED +DESCRIPTION section. +.LP +The C source code and header file shall be produced in a form suitable +as input for the C compiler (see \fIc99\fP ). +.SH OPTIONS +.LP +The \fIyacc\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-b\ \fP \fIfile_prefix\fP +Use \fIfile_prefix\fP instead of \fBy\fP as the prefix for all output +filenames. The code file \fBy.tab.c\fP, the header +file \fBy.tab.h\fP (created when \fB-d\fP is specified), and the description +file \fBy.output\fP (created when \fB-v\fP is +specified), shall be changed to \fIfile_prefix\fP \fB.tab.c\fP, \fIfile_prefix\fP +\fB\&.tab.h\fP, and \fIfile_prefix\fP +\fB\&.output\fP, respectively. +.TP 7 +\fB-d\fP +Write the header file; by default only the code file is written. The +\fB#define\fP statements associate the token codes +assigned by \fIyacc\fP with the user-declared token names. This allows +source files other than \fBy.tab.c\fP to access the token +codes. +.TP 7 +\fB-l\fP +Produce a code file that does not contain any \fB#line\fP constructs. +If this option is not present, it is unspecified whether +the code file or header file contains \fB#line\fP directives. This +should only be used after the grammar and the associated +actions are fully debugged. +.TP 7 +\fB-p\ \fP \fIsym_prefix\fP +.sp +Use \fIsym_prefix\fP instead of \fByy\fP as the prefix for all external +names produced by \fIyacc\fP. The names affected shall +include the functions \fIyyparse\fP(), \fIyylex\fP(), and \fIyyerror\fP(), +and the variables \fIyylval\fP, \fIyychar\fP, and +\fIyydebug\fP. (In the remainder of this section, the six symbols +cited are referenced using their default names only as a +notational convenience.) Local names may also be affected by the \fB-p\fP +option; however, the \fB-p\fP option shall not affect +\fB#define\fP symbols generated by \fIyacc\fP. +.TP 7 +\fB-t\fP +Modify conditional compilation directives to permit compilation of +debugging code in the code file. Runtime debugging +statements shall always be contained in the code file, but by default +conditional compilation directives prevent their +compilation. +.TP 7 +\fB-v\fP +Write a file containing a description of the parser and a report of +conflicts generated by ambiguities in the grammar. +.sp +.SH OPERANDS +.LP +The following operand is required: +.TP 7 +\fIgrammar\fP +A pathname of a file containing instructions, hereafter called \fIgrammar\fP, +for which a parser is to be created. The format +for the grammar is described in the EXTENDED DESCRIPTION section. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +The file \fIgrammar\fP shall be a text file formatted as specified +in the EXTENDED DESCRIPTION section. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIyacc\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.LP +The \fILANG\fP and \fILC_*\fP variables affect the execution of the +\fIyacc\fP utility as stated. The \fImain\fP() function +defined in Yacc Library shall call: +.sp +.RS +.nf + +\fBsetlocale(LC_ALL, "") +\fP +.fi +.RE +.LP +and thus the program generated by \fIyacc\fP shall also be affected +by the contents of these variables at runtime. +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +If shift/reduce or reduce/reduce conflicts are detected in \fIgrammar\fP, +\fIyacc\fP shall write a report of those conflicts +to the standard error in an unspecified format. +.LP +Standard error shall also be used for diagnostic messages. +.SH OUTPUT FILES +.LP +The code file, the header file, and the description file shall be +text files. All are described in the following sections. +.SS Code File +.LP +This file shall contain the C source code for the \fIyyparse\fP() +function. It shall contain code for the various semantic +actions with macro substitution performed on them as described in +the EXTENDED DESCRIPTION section. It also shall contain a copy of +the \fB#define\fP statements in the header file. If a \fB%union\fP +declaration is used, the declaration for YYSTYPE shall also be +included in this file. +.SS Header File +.LP +The header file shall contain \fB#define\fP statements that associate +the token numbers with the token names. This allows +source files other than the code file to access the token codes. If +a \fB%union\fP declaration is used, the declaration for +YYSTYPE and an \fIextern YYSTYPE yylval\fP declaration shall also +be included in this file. +.SS Description File +.LP +The description file shall be a text file containing a description +of the state machine corresponding to the parser, using an +unspecified format. Limits for internal tables (see Limits ) shall +also be reported, in an +implementation-defined manner. (Some implementations may use dynamic +allocation techniques and have no specific limit values to +report.) +.SH EXTENDED DESCRIPTION +.LP +The \fIyacc\fP command accepts a language that is used to define a +grammar for a target language to be parsed by the tables and +code generated by \fIyacc\fP. The language accepted by \fIyacc\fP +as a grammar for the target language is described below using +the \fIyacc\fP input language itself. +.LP +The input \fIgrammar\fP includes rules describing the input structure +of the target language and code to be invoked when these +rules are recognized to provide the associated semantic action. The +code to be executed shall appear as bodies of text that are +intended to be C-language code. The C-language inclusions are presumed +to form a correct function when processed by \fIyacc\fP +into its output files. The code included in this way shall be executed +during the recognition of the target language. +.LP +Given a grammar, the \fIyacc\fP utility generates the files described +in the OUTPUT FILES section. The code file can be +compiled and linked using \fIc99\fP. If the declaration and programs +sections of the grammar +file did not include definitions of \fImain\fP(), \fIyylex\fP(), and +\fIyyerror\fP(), the compiled output requires linking with +externally supplied versions of those functions. Default versions +of \fImain\fP() and \fIyyerror\fP() are supplied in the +\fIyacc\fP library and can be linked in by using the \fB-l\ y\fP operand +to \fIc99\fP. +The \fIyacc\fP library interfaces need not support interfaces with +other than the default \fByy\fP symbol prefix. The application +provides the lexical analyzer function, \fIyylex\fP(); the \fIlex\fP +utility is specifically +designed to generate such a routine. +.SS Input Language +.LP +The application shall ensure that every specification file consists +of three sections in order: \fIdeclarations\fP, \fIgrammar +rules\fP, and \fIprograms\fP, separated by double percent signs ( +\fB"%%"\fP ). The declarations and programs sections can be +empty. If the latter is empty, the preceding \fB"%%"\fP mark separating +it from the rules section can be omitted. +.LP +The input is free form text following the structure of the grammar +defined below. +.SS Lexical Structure of the Grammar +.LP +The s, s, and s shall be ignored, except +that the application shall ensure that +they do not appear in names or multi-character reserved symbols. Comments +shall be enclosed in \fB"/*\ ...\ */"\fP , and +can appear wherever a name is valid. +.LP +Names are of arbitrary length, made up of letters, periods ( \fB'.'\fP +), underscores ( \fB'_'\fP ), and non-initial +digits. Uppercase and lowercase letters are distinct. Conforming applications +shall not use names beginning in \fByy\fP or +\fBYY\fP since the \fIyacc\fP parser uses such names. Many of the +names appear in the final output of \fIyacc\fP, and thus they +should be chosen to conform with any additional rules created by the +C compiler to be used. In particular they appear in +\fB#define\fP statements. +.LP +A literal shall consist of a single character enclosed in single-quotes +( \fB'"\fP ). All of the escape sequences supported +for character constants by the ISO\ C standard shall be supported +by \fIyacc\fP. +.LP +The relationship with the lexical analyzer is discussed in detail +below. +.LP +The application shall ensure that the NUL character is not used in +grammar rules or literals. +.SS Declarations Section +.LP +The declarations section is used to define the symbols used to define +the target language and their relationship with each +other. In particular, much of the additional information required +to resolve ambiguities in the context-free grammar for the target +language is provided here. +.LP +Usually \fIyacc\fP assigns the relationship between the symbolic names +it generates and their underlying numeric value. The +declarations section makes it possible to control the assignment of +these values. +.LP +It is also possible to keep semantic information associated with the +tokens currently on the parse stack in a user-defined +C-language \fBunion\fP, if the members of the union are associated +with the various names in the grammar. The declarations section +provides for this as well. +.LP +The first group of declarators below all take a list of names as arguments. +That list can optionally be preceded by the name of +a C union member (called a \fItag\fP below) appearing within \fB'<'\fP +and \fB'>'\fP . (As an exception to the +typographical conventions of the rest of this volume of IEEE\ Std\ 1003.1-2001, +in this case <\fItag\fP> does not +represent a metavariable, but the literal angle bracket characters +surrounding a symbol.) The use of \fItag\fP specifies that the +tokens named on this line shall be of the same C type as the union +member referenced by \fItag\fP. This is discussed in more +detail below. +.LP +For lists used to define tokens, the first appearance of a given token +can be followed by a positive integer (as a string of +decimal digits). If this is done, the underlying value assigned to +it for lexical purposes shall be taken to be that number. +.LP +The following declares \fIname\fP to be a token: +.sp +.RS +.nf + +\fB%token\fP \fB[\fP\fB<\fP\fItag\fP\fB>\fP\fB]\fP \fIname\fP \fB[\fP\fInumber\fP\fB][\fP\fIname\fP \fB[\fP\fInumber\fP\fB]]\fP\fB... +\fP +.fi +.RE +.LP +If \fItag\fP is present, the C type for all tokens on this line shall +be declared to be the type referenced by \fItag\fP. If a +positive integer, \fInumber\fP, follows a \fIname\fP, that value shall +be assigned to the token. +.LP +The following declares \fIname\fP to be a token, and assigns precedence +to it: +.sp +.RS +.nf + +\fB%left\fP \fB[\fP\fB<\fP\fItag\fP\fB>\fP\fB]\fP \fIname\fP \fB[\fP\fInumber\fP\fB][\fP\fIname\fP \fB[\fP\fInumber\fP\fB]]\fP\fB... +%right\fP \fB[\fP\fB<\fP\fItag\fP\fB>\fP\fB]\fP \fIname\fP \fB[\fP\fInumber\fP\fB][\fP\fIname\fP \fB[\fP\fInumber\fP\fB]]\fP\fB... +\fP +.fi +.RE +.LP +One or more lines, each beginning with one of these symbols, can appear +in this section. All tokens on the same line have the +same precedence level and associativity; the lines are in order of +increasing precedence or binding strength. \fB%left\fP denotes +that the operators on that line are left associative, and \fB%right\fP +similarly denotes right associative operators. If +\fItag\fP is present, it shall declare a C type for \fIname\fPs as +described for \fB%token\fP. +.LP +The following declares \fIname\fP to be a token, and indicates that +this cannot be used associatively: +.sp +.RS +.nf + +\fB%nonassoc\fP \fB[\fP\fB<\fP\fItag\fP\fB>\fP\fB]\fP \fIname\fP \fB[\fP\fInumber\fP\fB][\fP\fIname\fP \fB[\fP\fInumber\fP\fB]]\fP\fB... +\fP +.fi +.RE +.LP +If the parser encounters associative use of this token it reports +an error. If \fItag\fP is present, it shall declare a C type +for \fIname\fPs as described for \fB%token\fP. +.LP +The following declares that union member \fIname\fPs are non-terminals, +and thus it is required to have a \fItag\fP field at +its beginning: +.sp +.RS +.nf + +\fB%type <\fP\fItag\fP\fB>\fP \fIname\fP\fB... +\fP +.fi +.RE +.LP +Because it deals with non-terminals only, assigning a token number +or using a literal is also prohibited. If this construct is +present, \fIyacc\fP shall perform type checking; if this construct +is not present, the parse stack shall hold only the \fBint\fP +type. +.LP +Every name used in \fIgrammar\fP not defined by a \fB%token\fP, \fB%left\fP, +\fB%right\fP, or \fB%nonassoc\fP declaration +is assumed to represent a non-terminal symbol. The \fIyacc\fP utility +shall report an error for any non-terminal symbol that does +not appear on the left side of at least one grammar rule. +.LP +Once the type, precedence, or token number of a name is specified, +it shall not be changed. If the first declaration of a token +does not assign a token number, \fIyacc\fP shall assign a token number. +Once this assignment is made, the token number shall not +be changed by explicit assignment. +.LP +The following declarators do not follow the previous pattern. +.LP +The following declares the non-terminal \fIname\fP to be the \fIstart +symbol\fP, which represents the largest, most general +structure described by the grammar rules: +.sp +.RS +.nf + +\fB%start\fP \fIname\fP +.fi +.RE +.LP +By default, it is the left-hand side of the first grammar rule; this +default can be overridden with this declaration. +.LP +The following declares the \fIyacc\fP value stack to be a union of +the various types of values desired: +.sp +.RS +.nf + +\fB%union {\fP \fIbody of union\fP \fB(\fP\fIin C\fP\fB) } +\fP +.fi +.RE +.LP +By default, the values returned by actions (see below) and the lexical +analyzer shall be of type \fBint\fP. The \fIyacc\fP +utility keeps track of types, and it shall insert corresponding union +member names in order to perform strict type checking of the +resulting parser. +.LP +Alternatively, given that at least one <\fItag\fP> construct is used, +the union can be declared in a header file (which +shall be included in the declarations section by using a \fB#include\fP +construct within \fB%{\fP and \fB%}\fP), and a +\fBtypedef\fP used to define the symbol YYSTYPE to represent this +union. The effect of \fB%union\fP is to provide the declaration +of YYSTYPE directly from the \fIyacc\fP input. +.LP +C-language declarations and definitions can appear in the declarations +section, enclosed by the following marks: +.sp +.RS +.nf + +\fB%{ ... %} +\fP +.fi +.RE +.LP +These statements shall be copied into the code file, and have global +scope within it so that they can be used in the rules and +program sections. +.LP +The application shall ensure that the declarations section is terminated +by the token \fB%%\fP. +.SS Grammar Rules in yacc +.LP +The rules section defines the context-free grammar to be accepted +by the function \fIyacc\fP generates, and associates with +those rules C-language actions and additional precedence information. +The grammar is described below, and a formal definition +follows. +.LP +The rules section is comprised of one or more grammar rules. A grammar +rule has the form: +.sp +.RS +.nf + +\fBA : BODY ; +\fP +.fi +.RE +.LP +The symbol \fBA\fP represents a non-terminal name, and \fBBODY\fP +represents a sequence of zero or more \fIname\fPs, +\fIliteral\fPs, and \fIsemantic action\fPs that can then be followed +by optional \fIprecedence rule\fPs. Only the names and +literals participate in the formation of the grammar; the semantic +actions and precedence rules are used in other ways. The colon +and the semicolon are \fIyacc\fP punctuation. If there are several +successive grammar rules with the same left-hand side, the +vertical bar \fB'|'\fP can be used to avoid rewriting the left-hand +side; in this case the semicolon appears only after the last +rule. The BODY part can be empty (or empty of names and literals) +to indicate that the non-terminal symbol matches the empty +string. +.LP +The \fIyacc\fP utility assigns a unique number to each rule. Rules +using the vertical bar notation are distinct rules. The +number assigned to the rule appears in the description file. +.LP +The elements comprising a BODY are: +.TP 7 +\fIname\fP,\ \fIliteral\fP +These form the rules of the grammar: \fIname\fP is either a \fItoken\fP +or a \fInon-terminal\fP; \fIliteral\fP stands for +itself (less the lexically required quotation marks). +.TP 7 +\fIsemantic action\fP +.sp +With each grammar rule, the user can associate actions to be performed +each time the rule is recognized in the input process. (Note +that the word "action" can also refer to the actions of the parser-shift, +reduce, and so on.) +.LP +These actions can return values and can obtain the values returned +by previous actions. These values are kept in objects of type +YYSTYPE (see \fB%union\fP). The result value of the action shall be +kept on the parse stack with the left-hand side of the rule, +to be accessed by other reductions as part of their right-hand side. +By using the <\fItag\fP> information provided in the +declarations section, the code generated by \fIyacc\fP can be strictly +type checked and contain arbitrary information. In +addition, the lexical analyzer can provide the same kinds of values +for tokens, if desired. +.LP +An action is an arbitrary C statement and as such can do input or +output, call subprograms, and alter external variables. An +action is one or more C statements enclosed in curly braces \fB'{'\fP +and \fB'}'\fP . +.LP +Certain pseudo-variables can be used in the action. These are macros +for access to data structures known internally to +\fIyacc\fP. +.TP 7 +$$ +.RS +The value of the action can be set by assigning it to $$. If type +checking is enabled and the type of the value to be assigned +cannot be determined, a diagnostic message may be generated. +.RE +.TP 7 +$\fInumber\fP +.RS +This refers to the value returned by the component specified by the +token \fInumber\fP in the right side of a rule, reading +from left to right; \fInumber\fP can be zero or negative. If \fInumber\fP +is zero or negative, it refers to the data associated +with the name on the parser's stack preceding the leftmost symbol +of the current rule. (That is, \fB"$0"\fP refers to the name +immediately preceding the leftmost name in the current rule to be +found on the parser's stack and \fB"$-1"\fP refers to the +symbol to \fIits\fP left.) If \fInumber\fP refers to an element past +the current point in the rule, or beyond the bottom of the +stack, the result is undefined. If type checking is enabled and the +type of the value to be assigned cannot be determined, a +diagnostic message may be generated. +.RE +.TP 7 +$<\fItag\fP>\fInumber\fP +.RS +.sp +These correspond exactly to the corresponding symbols without the +\fItag\fP inclusion, but allow for strict type checking (and +preclude unwanted type conversions). The effect is that the macro +is expanded to use \fItag\fP to select an element from the +YYSTYPE union (using \fIdataname.tag\fP). This is particularly useful +if \fInumber\fP is not positive. +.RE +.TP 7 +$<\fItag\fP>$ +.RS +This imposes on the reference the type of the union member referenced +by \fItag\fP. This construction is applicable when a +reference to a left context value occurs in the grammar, and provides +\fIyacc\fP with a means for selecting a type. +.RE +.sp +.LP +Actions can occur anywhere in a rule (not just at the end); an action +can access values returned by actions to its left, and in +turn the value it returns can be accessed by actions to its right. +An action appearing in the middle of a rule shall be equivalent +to replacing the action with a new non-terminal symbol and adding +an empty rule with that non-terminal symbol on the left-hand +side. The semantic action associated with the new rule shall be equivalent +to the original action. The use of actions within rules +might introduce conflicts that would not otherwise exist. +.LP +By default, the value of a rule shall be the value of the first element +in it. If the first element does not have a type +(particularly in the case of a literal) and type checking is turned +on by \fB%type\fP, an error message shall result. +.TP 7 +\fIprecedence\fP +The keyword \fB%prec\fP can be used to change the precedence level +associated with a particular grammar rule. Examples of this +are in cases where a unary and binary operator have the same symbolic +representation, but need to be given different precedences, +or where the handling of an ambiguous if-else construction is necessary. +The reserved symbol \fB%prec\fP can appear immediately +after the body of the grammar rule and can be followed by a token +name or a literal. It shall cause the precedence of the grammar +rule to become that of the following token name or literal. The action +for the rule as a whole can follow \fB%prec\fP. +.sp +.LP +If a program section follows, the application shall ensure that the +grammar rules are terminated by \fB%%\fP. +.SS Programs Section +.LP +The \fIprograms\fP section can include the definition of the lexical +analyzer \fIyylex\fP(), and any other functions; for +example, those used in the actions specified in the grammar rules. +It is unspecified whether the programs section precedes or +follows the semantic actions in the output file; therefore, if the +application contains any macro definitions and declarations +intended to apply to the code in the semantic actions, it shall place +them within \fB"%{\ ...\ %}"\fP in the +declarations section. +.SS Input Grammar +.LP +The following input to \fIyacc\fP yields a parser for the input to +\fIyacc\fP. This formal syntax takes precedence over the +preceding text syntax description. +.LP +The lexical structure is defined less precisely; Lexical Structure +of the Grammar defines most +terms. The correspondence between the previous terms and the tokens +below is as follows. +.TP 7 +\fBIDENTIFIER\fP +This corresponds to the concept of \fIname\fP, given previously. It +also includes literals as defined previously. +.TP 7 +\fBC_IDENTIFIER\fP +This is a name, and additionally it is known to be followed by a colon. +A literal cannot yield this token. +.TP 7 +\fBNUMBER\fP +A string of digits (a non-negative decimal integer). +.TP 7 +\fBTYPE\fP,\ \fBLEFT\fP,\ \fBMARK\fP,\ \fBLCURL\fP,\ \fBRCURL\fP +.sp +These correspond directly to \fB%type\fP, \fB%left\fP, \fB%%\fP, \fB%{\fP, +and \fB%}\fP. +.TP 7 +\fB{\ ...\ }\fP +This indicates C-language source code, with the possible inclusion +of \fB'$'\fP macros as discussed previously. +.sp +.sp +.RS +.nf + +\fB/* Grammar for the input to yacc. */ +/* Basic entries. */ +/* The following are recognized by the lexical analyzer. */ +.sp + +%token IDENTIFIER /* Includes identifiers and literals */ +%token C_IDENTIFIER /* identifier (but not literal) + followed by a :. */ +%token NUMBER /* [0-9][0-9]* */ +.sp + +/* Reserved words : %type=>TYPE %left=>LEFT, and so on */ +.sp + +%token LEFT RIGHT NONASSOC TOKEN PREC TYPE START UNION +.sp + +%token MARK /* The %% mark. */ +%token LCURL /* The %{ mark. */ +%token RCURL /* The %} mark. */ +.sp + +/* 8-bit character literals stand for themselves; */ +/* tokens have to be defined for multi-byte characters. */ +.sp + +%start spec +.sp + +%% +.sp + +spec : defs MARK rules tail + ; +tail : MARK + { + /* In this action, set up the rest of the file. */ + } + | /* Empty; the second MARK is optional. */ + ; +defs : /* Empty. */ + | defs def + ; +def : START IDENTIFIER + | UNION + { + /* Copy union definition to output. */ + } + | LCURL + { + /* Copy C code to output file. */ + } + RCURL + | rword tag nlist + ; +rword : TOKEN + | LEFT + | RIGHT + | NONASSOC + | TYPE + ; +tag : /* Empty: union tag ID optional. */ + | '<' IDENTIFIER '>' + ; +nlist : nmno + | nlist nmno + ; +nmno : IDENTIFIER /* Note: literal invalid with % type. */ + | IDENTIFIER NUMBER /* Note: invalid with % type. */ + ; +.sp + +/* Rule section */ +.sp + +rules : C_IDENTIFIER rbody prec + | rules rule + ; +rule : C_IDENTIFIER rbody prec + | '|' rbody prec + ; +rbody : /* empty */ + | rbody IDENTIFIER + | rbody act + ; +act : '{' + { + /* Copy action, translate $$, and so on. */ + } + '}' + ; +prec : /* Empty */ + | PREC IDENTIFIER + | PREC IDENTIFIER act + | prec ';' + ; +\fP +.fi +.RE +.SS Conflicts +.LP +The parser produced for an input grammar may contain states in which +conflicts occur. The conflicts occur because the grammar is +not LALR(1). An ambiguous grammar always contains at least one LALR(1) +conflict. The \fIyacc\fP utility shall resolve all +conflicts, using either default rules or user-specified precedence +rules. +.LP +Conflicts are either shift/reduce conflicts or reduce/reduce conflicts. +A shift/reduce conflict is where, for a given state and +lookahead symbol, both a shift action and a reduce action are possible. +A reduce/reduce conflict is where, for a given state and +lookahead symbol, reductions by two different rules are possible. +.LP +The rules below describe how to specify what actions to take when +a conflict occurs. Not all shift/reduce conflicts can be +successfully resolved this way because the conflict may be due to +something other than ambiguity, so incautious use of these +facilities can cause the language accepted by the parser to be much +different from that which was intended. The description file +shall contain sufficient information to understand the cause of the +conflict. Where ambiguity is the reason either the default or +explicit rules should be adequate to produce a working parser. +.LP +The declared precedences and associativities (see Declarations Section +) are used to resolve +parsing conflicts as follows: +.IP " 1." 4 +A precedence and associativity is associated with each grammar rule; +it is the precedence and associativity of the last token or +literal in the body of the rule. If the \fB%prec\fP keyword is used, +it overrides this default. Some grammar rules might not have +both precedence and associativity. +.LP +.IP " 2." 4 +If there is a shift/reduce conflict, and both the grammar rule and +the input symbol have precedence and associativity associated +with them, then the conflict is resolved in favor of the action (shift +or reduce) associated with the higher precedence. If the +precedences are the same, then the associativity is used; left associative +implies reduce, right associative implies shift, and +non-associative implies an error in the string being parsed. +.LP +.IP " 3." 4 +When there is a shift/reduce conflict that cannot be resolved by rule +2, the shift is done. Conflicts resolved this way are +counted in the diagnostic output described in Error Handling . +.LP +.IP " 4." 4 +When there is a reduce/reduce conflict, a reduction is done by the +grammar rule that occurs earlier in the input sequence. +Conflicts resolved this way are counted in the diagnostic output described +in Error Handling . +.LP +.LP +Conflicts resolved by precedence or associativity shall not be counted +in the shift/reduce and reduce/reduce conflicts reported +by \fIyacc\fP on either standard error or in the description file. +.SS Error Handling +.LP +The token \fBerror\fP shall be reserved for error handling. The name +\fBerror\fP can be used in grammar rules. It indicates +places where the parser can recover from a syntax error. The default +value of \fBerror\fP shall be 256. Its value can be changed +using a \fB%token\fP declaration. The lexical analyzer should not +return the value of \fBerror\fP. +.LP +The parser shall detect a syntax error when it is in a state where +the action associated with the lookahead symbol is +\fBerror\fP. A semantic action can cause the parser to initiate error +handling by executing the macro YYERROR. When YYERROR is +executed, the semantic action passes control back to the parser. YYERROR +cannot be used outside of semantic actions. +.LP +When the parser detects a syntax error, it normally calls \fIyyerror\fP() +with the character string +\fB"syntax\ error"\fP as its argument. The call shall not be made +if the parser is still recovering from a previous error +when the error is detected. The parser is considered to be recovering +from a previous error until the parser has shifted over at +least three normal input symbols since the last error was detected +or a semantic action has executed the macro \fIyyerrok\fP. The +parser shall not call \fIyyerror\fP() when YYERROR is executed. +.LP +The macro function YYRECOVERING shall return 1 if a syntax error has +been detected and the parser has not yet fully recovered +from it. Otherwise, zero shall be returned. +.LP +When a syntax error is detected by the parser, the parser shall check +if a previous syntax error has been detected. If a +previous error was detected, and if no normal input symbols have been +shifted since the preceding error was detected, the parser +checks if the lookahead symbol is an endmarker (see Interface to the +Lexical Analyzer ). If it is, +the parser shall return with a non-zero value. Otherwise, the lookahead +symbol shall be discarded and normal parsing shall +resume. +.LP +When YYERROR is executed or when the parser detects a syntax error +and no previous error has been detected, or at least one +normal input symbol has been shifted since the previous error was +detected, the parser shall pop back one state at a time until the +parse stack is empty or the current state allows a shift over \fBerror\fP. +If the parser empties the parse stack, it shall return +with a non-zero value. Otherwise, it shall shift over \fBerror\fP +and then resume normal parsing. If the parser reads a lookahead +symbol before the error was detected, that symbol shall still be the +lookahead symbol when parsing is resumed. +.LP +The macro \fIyyerrok\fP in a semantic action shall cause the parser +to act as if it has fully recovered from any previous +errors. The macro \fIyyclearin\fP shall cause the parser to discard +the current lookahead token. If the current lookahead token +has not yet been read, \fIyyclearin\fP shall have no effect. +.LP +The macro YYACCEPT shall cause the parser to return with the value +zero. The macro YYABORT shall cause the parser to return with +a non-zero value. +.SS Interface to the Lexical Analyzer +.LP +The \fIyylex\fP() function is an integer-valued function that returns +a \fItoken number\fP representing the kind of token +read. If there is a value associated with the token returned by \fIyylex\fP() +(see the discussion of \fItag\fP above), it shall +be assigned to the external variable \fIyylval\fP. +.LP +If the parser and \fIyylex\fP() do not agree on these token numbers, +reliable communication between them cannot occur. For +(single-byte character) literals, the token is simply the numeric +value of the character in the current character set. The numbers +for other tokens can either be chosen by \fIyacc\fP, or chosen by +the user. In either case, the \fB#define\fP construct of C is +used to allow \fIyylex\fP() to return these numbers symbolically. +The \fB#define\fP statements are put into the code file, and +the header file if that file is requested. The set of characters permitted +by \fIyacc\fP in an identifier is larger than that +permitted by C. Token names found to contain such characters shall +not be included in the \fB#define\fP declarations. +.LP +If the token numbers are chosen by \fIyacc\fP, the tokens other than +literals shall be assigned numbers greater than 256, +although no order is implied. A token can be explicitly assigned a +number by following its first appearance in the declarations +section with a number. Names and literals not defined this way retain +their default definition. All token numbers assigned by +\fIyacc\fP shall be unique and distinct from the token numbers used +for literals and user-assigned tokens. If duplicate token +numbers cause conflicts in parser generation, \fIyacc\fP shall report +an error; otherwise, it is unspecified whether the token +assignment is accepted or an error is reported. +.LP +The end of the input is marked by a special token called the \fIendmarker\fP, +which has a token number that is zero or +negative. (These values are invalid for any other token.) All lexical +analyzers shall return zero or negative as a token number +upon reaching the end of their input. If the tokens up to, but excluding, +the endmarker form a structure that matches the start +symbol, the parser shall accept the input. If the endmarker is seen +in any other context, it shall be considered an error. +.SS Completing the Program +.LP +In addition to \fIyyparse\fP() and \fIyylex\fP(), the functions \fIyyerror\fP() +and \fImain\fP() are required to make a +complete program. The application can supply \fImain\fP() and \fIyyerror\fP(), +or those routines can be obtained from the +\fIyacc\fP library. +.SS Yacc Library +.LP +The following functions shall appear only in the \fIyacc\fP library +accessible through the \fB-l\ y\fP operand to \fIc99\fP; they can +therefore be redefined by a conforming application: +.TP 7 +\fBint\ \fP \fImain\fP(\fBvoid\fP) +.sp +This function shall call \fIyyparse\fP() and exit with an unspecified +value. Other actions within this function are +unspecified. +.TP 7 +\fBint\ \fP \fIyyerror\fP(\fBconst\ char\fP\ *\fIs\fP) +.sp +This function shall write the NUL-terminated argument to standard +error, followed by a . +.sp +.LP +The order of the \fB-l\ y\fP and \fB-l\ l\fP operands given to \fIc99\fP +is +significant; the application shall either provide its own \fImain\fP() +function or ensure that \fB-l\ y\fP precedes +\fB-l\ l\fP. +.SS Debugging the Parser +.LP +The parser generated by \fIyacc\fP shall have diagnostic facilities +in it that can be optionally enabled at either compile time +or at runtime (if enabled at compile time). The compilation of the +runtime debugging code is under the control of YYDEBUG, a +preprocessor symbol. If YYDEBUG has a non-zero value, the debugging +code shall be included. If its value is zero, the code shall +not be included. +.LP +In parsers where the debugging code has been included, the external +\fBint\fP \fIyydebug\fP can be used to turn debugging on +(with a non-zero value) and off (zero value) at runtime. The initial +value of \fIyydebug\fP shall be zero. +.LP +When \fB-t\fP is specified, the code file shall be built such that, +if YYDEBUG is not already defined at compilation time +(using the \fIc99\fP \fB-D\fP YYDEBUG option, for example), YYDEBUG +shall be set explicitly +to 1. When \fB-t\fP is not specified, the code file shall be built +such that, if YYDEBUG is not already defined, it shall be set +explicitly to zero. +.LP +The format of the debugging output is unspecified but includes at +least enough information to determine the shift and reduce +actions, and the input symbols. It also provides information about +error recovery. +.SS Algorithms +.LP +The parser constructed by \fIyacc\fP implements an LALR(1) parsing +algorithm as documented in the literature. It is unspecified +whether the parser is table-driven or direct-coded. +.LP +A parser generated by \fIyacc\fP shall never request an input symbol +from \fIyylex\fP() while in a state where the only +actions other than the error action are reductions by a single rule. +.LP +The literature of parsing theory defines these concepts. +.SS Limits +.LP +The \fIyacc\fP utility may have several internal tables. The minimum +maximums for these tables are shown in the following +table. The exact meaning of these values is implementation-defined. +The implementation shall define the relationship between these +values and between them and any error messages that the implementation +may generate should it run out of space for any internal +structure. An implementation may combine groups of these resources +into a single pool as long as the total available to the user +does not fall below the sum of the sizes specified by this section. +.br +.sp +.ce 1 +\fBTable: Internal Limits in \fIyacc\fP\fP +.TS C +center; l l lw(40). +\fB\ \fP \fBMinimum\fP T{ +.na +\fB\ \fP +.ad +T} +\fBLimit\fP \fBMaximum\fP T{ +.na +\fBDescription\fP +.ad +T} +{NTERMS} 126 T{ +.na +Number of tokens. +.ad +T} +{NNONTERM} 200 T{ +.na +Number of non-terminals. +.ad +T} +{NPROD} 300 T{ +.na +Number of rules. +.ad +T} +{NSTATES} 600 T{ +.na +Number of states. +.ad +T} +{MEMSIZE} 5200 T{ +.na +Length of rules. The total length, in names (tokens and non-terminals), of all the rules of the grammar. The left-hand side is counted for each rule, even if it is not explicitly repeated, as specified in Grammar Rules in yacc . +.ad +T} +{ACTSIZE} 4000 T{ +.na +Number of actions. "Actions" here (and in the description file) refer to parser actions (shift, reduce, and so on) not to semantic actions defined in Grammar Rules in yacc . +.ad +T} +.TE +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If any errors are encountered, the run is aborted and \fIyacc\fP exits +with a non-zero status. Partial code files and header +files may be produced. The summary information in the description +file shall always be produced if the \fB-v\fP flag is +present. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Historical implementations experience name conflicts on the names +\fByacc.tmp\fP, \fByacc.acts\fP, \fByacc.debug\fP, +\fBy.tab.c\fP, \fBy.tab.h\fP, and \fBy.output\fP if more than one +copy of \fIyacc\fP is running in a single directory at one +time. The \fB-b\fP option was added to overcome this problem. The +related problem of allowing multiple \fIyacc\fP parsers to be +placed in the same file was addressed by adding a \fB-p\fP option +to override the previously hard-coded \fByy\fP variable +prefix. +.LP +The description of the \fB-p\fP option specifies the minimal set of +function and variable names that cause conflict when +multiple parsers are linked together. YYSTYPE does not need to be +changed. Instead, the programmer can use \fB-b\fP to give the +header files for different parsers different names, and then the file +with the \fIyylex\fP() for a given parser can include the +header for that parser. Names such as \fIyyclearerr\fP do not need +to be changed because they are used only in the actions; they +do not have linkage. It is possible that an implementation has other +names, either internal ones for implementing things such as +\fIyyclearerr\fP, or providing non-standard features that it wants +to change with \fB-p\fP. +.LP +Unary operators that are the same token as a binary operator in general +need their precedence adjusted. This is handled by the +\fB%prec\fP advisory symbol associated with the particular grammar +rule defining that unary operator. (See Grammar Rules in yacc .) Applications +are not required to use this operator for unary operators, but the +grammars that do not require it are rare. +.SH EXAMPLES +.LP +Access to the \fIyacc\fP library is obtained with library search operands +to \fIc99\fP. To +use the \fIyacc\fP library \fImain\fP(): +.sp +.RS +.nf + +\fBc99 y.tab.c -l y +\fP +.fi +.RE +.LP +Both the \fIlex\fP library and the \fIyacc\fP library contain \fImain\fP(). +To access the +\fIyacc\fP \fImain\fP(): +.sp +.RS +.nf + +\fBc99 y.tab.c lex.yy.c -l y -l l +\fP +.fi +.RE +.LP +This ensures that the \fIyacc\fP library is searched first, so that +its \fImain\fP() is used. +.LP +The historical \fIyacc\fP libraries have contained two simple functions +that are normally coded by the application programmer. +These functions are similar to the following code: +.sp +.RS +.nf + +\fB#include +int main(void) +{ + extern int yyparse(); +.sp + + setlocale(LC_ALL, ""); +.sp + + /* If the following parser is one created by lex, the + application must be careful to ensure that LC_CTYPE + and LC_COLLATE are set to the POSIX locale. */ + (void) yyparse(); + return (0); +} +.sp + +#include +.sp + +int yyerror(const char *msg) +{ + (void) fprintf(stderr, "%s\\n", msg); + return (0); +} +\fP +.fi +.RE +.SH RATIONALE +.LP +The references in may be helpful in constructing the parser generator. +The referenced DeRemer and Pennello article (along with +the works it references) describes a technique to generate parsers +that conform to this volume of IEEE\ Std\ 1003.1-2001. +Work in this area continues to be done, so implementors should consult +current literature before doing any new implementations. The +original Knuth article is the theoretical basis for this kind of parser, +but the tables it generates are impractically large for +reasonable grammars and should not be used. The "equivalent to" wording +is intentional to assure that the best tables that are +LALR(1) can be generated. +.LP +There has been confusion between the class of grammars, the algorithms +needed to generate parsers, and the algorithms needed to +parse the languages. They are all reasonably orthogonal. In particular, +a parser generator that accepts the full range of LR(1) +grammars need not generate a table any more complex than one that +accepts SLR(1) (a relatively weak class of LR grammars) for a +grammar that happens to be SLR(1). Such an implementation need not +recognize the case, either; table compression can yield the +SLR(1) table (or one even smaller than that) without recognizing that +the grammar is SLR(1). The speed of an LR(1) parser for any +class is dependent more upon the table representation and compression +(or the code generation if a direct parser is generated) than +upon the class of grammar that the table generator handles. +.LP +The speed of the parser generator is somewhat dependent upon the class +of grammar it handles. However, the original Knuth +article algorithms for constructing LR parsers were judged by its +author to be impractically slow at that time. Although full LR is +more complex than LALR(1), as computer speeds and algorithms improve, +the difference (in terms of acceptable wall-clock execution +time) is becoming less significant. +.LP +Potential authors are cautioned that the referenced DeRemer and Pennello +article previously cited identifies a bug (an +over-simplification of the computation of LALR(1) lookahead sets) +in some of the LALR(1) algorithm statements that preceded it to +publication. They should take the time to seek out that paper, as +well as current relevant work, particularly Aho's. +.LP +The \fB-b\fP option was added to provide a portable method for permitting +\fIyacc\fP to work on multiple separate parsers in +the same directory. If a directory contains more than one \fIyacc\fP +grammar, and both grammars are constructed at the same time +(by, for example, a parallel \fImake\fP program), conflict results. +While the solution is not +historical practice, it corrects a known deficiency in historical +implementations. Corresponding changes were made to all sections +that referenced the filenames \fBy.tab.c\fP (now "the code file"), +\fBy.tab.h\fP (now "the header file"), and \fBy.output\fP +(now "the description file"). +.LP +The grammar for \fIyacc\fP input is based on System V documentation. +The textual description shows there that the \fB';'\fP +is required at the end of the rule. The grammar and the implementation +do not require this. (The use of \fBC_IDENTIFIER\fP causes +a reduce to occur in the right place.) +.LP +Also, in that implementation, the constructs such as \fB%token\fP +can be terminated by a semicolon, but this is not permitted +by the grammar. The keywords such as \fB%token\fP can also appear +in uppercase, which is again not discussed. In most places where +\fB'%'\fP is used, \fB'\\'\fP can be substituted, and there are alternate +spellings for some of the symbols (for example, +\fB%LEFT\fP can be \fB"%<"\fP or even \fB"\\<"\fP ). +.LP +Historically, <\fItag\fP> can contain any characters except \fB'>'\fP +, including white space, in the +implementation. However, since the \fItag\fP must reference an ISO\ C +standard union member, in practice conforming +implementations need to support only the set of characters for ISO\ C +standard identifiers in this context. +.LP +Some historical implementations are known to accept actions that are +terminated by a period. Historical implementations often +allow \fB'$'\fP in names. A conforming implementation does not need +to support either of these behaviors. +.LP +Deciding when to use \fB%prec\fP illustrates the difficulty in specifying +the behavior of \fIyacc\fP. There may be situations +in which the \fIgrammar\fP is not, strictly speaking, in error, and +yet \fIyacc\fP cannot interpret it unambiguously. The +resolution of ambiguities in the grammar can in many instances be +resolved by providing additional information, such as using +\fB%type\fP or \fB%union\fP declarations. It is often easier and it +usually yields a smaller parser to take this alternative when +it is appropriate. +.LP +The size and execution time of a program produced without the runtime +debugging code is usually smaller and slightly faster in +historical implementations. +.LP +Statistics messages from several historical implementations include +the following types of information: +.sp +.RS +.nf + +\fIn\fP\fB/512 terminals,\fP \fIn\fP\fB/300 non-terminals +\fP\fIn\fP\fB/600 grammar rules,\fP \fIn\fP\fB/1500 states +\fP\fIn\fP \fBshift/reduce,\fP \fIn\fP \fBreduce/reduce conflicts reported +\fP\fIn\fP\fB/350 working sets used +Memory: states, etc.\fP \fIn\fP\fB/15000, parser\fP \fIn\fP\fB/15000 +\fP\fIn\fP\fB/600 distinct lookahead sets +\fP\fIn\fP \fBextra closures +\fP\fIn\fP \fBshift entries,\fP \fIn\fP \fBexceptions +\fP\fIn\fP \fBgoto entries +\fP\fIn\fP \fBentries saved by goto default +Optimizer space used: input\fP \fIn\fP\fB/15000, output\fP \fIn\fP\fB/15000 +\fP\fIn\fP \fBtable entries,\fP \fIn\fP \fBzero +Maximum spread:\fP \fIn\fP\fB, Maximum offset:\fP \fIn\fP +.fi +.RE +.LP +The report of internal tables in the description file is left implementation-defined +because all aspects of these limits are +also implementation-defined. Some implementations may use dynamic +allocation techniques and have no specific limit values to +report. +.LP +The format of the \fBy.output\fP file is not given because specification +of the format was not seen to enhance applications +portability. The listing is primarily intended to help human users +understand and debug the parser; use of \fBy.output\fP by a +conforming application script would be unusual. Furthermore, implementations +have not produced consistent output and no popular +format was apparent. The format selected by the implementation should +be human-readable, in addition to the requirement that it be +a text file. +.LP +Standard error reports are not specifically described because they +are seldom of use to conforming applications and there was no +reason to restrict implementations. +.LP +Some implementations recognize \fB"={"\fP as equivalent to \fB'{'\fP +because it appears in historical documentation. This +construction was recognized and documented as obsolete as long ago +as 1978, in the referenced \fIYacc: Yet Another +Compiler-Compiler\fP. This volume of IEEE\ Std\ 1003.1-2001 chose +to leave it as obsolete and omit it. +.LP +Multi-byte characters should be recognized by the lexical analyzer +and returned as tokens. They should not be returned as +multi-byte character literals. The token \fBerror\fP that is used +for error recovery is normally assigned the value 256 in the +historical implementation. Thus, the token value 256, which is used +in many multi-byte character sets, is not available for use as +the value of a user-defined token. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIc99\fP , \fIlex\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man1p/zcat.1p b/man1p/zcat.1p new file mode 100644 index 000000000..d75f13f16 --- /dev/null +++ b/man1p/zcat.1p @@ -0,0 +1,124 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ZCAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" zcat +.SH NAME +zcat \- expand and concatenate data +.SH SYNOPSIS +.LP +\fBzcat\fP \fB[\fP\fIfile\fP\fB...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fIzcat\fP utility shall write to standard output the uncompressed +form of files that have been compressed using the \fIcompress\fP utility. +It is the equivalent of \fIuncompress\fP \fB-c\fP. Input files are +not affected. +.SH OPTIONS +.LP +None. +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +The pathname of a file previously processed by the \fIcompress\fP +utility. If +\fIfile\fP already has the \fB.Z\fP suffix specified, it is used as +submitted. Otherwise, the \fB.Z\fP suffix is appended to the +filename prior to processing. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified, or if a \fIfile\fP operand is \fB'-'\fP +\&. +.SH INPUT FILES +.LP +Input files shall be compressed files that are in the format produced +by the \fIcompress\fP utility. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIzcat\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The compressed files given as input shall be written on standard output +in their uncompressed form. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcompress\fP , \fIuncompress\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man2/_Exit.2 b/man2/_Exit.2 new file mode 100644 index 000000000..9f9d2e763 --- /dev/null +++ b/man2/_Exit.2 @@ -0,0 +1 @@ +.so man2/_exit.2 diff --git a/man2/_exit.2 b/man2/_exit.2 new file mode 100644 index 000000000..c7a12b143 --- /dev/null +++ b/man2/_exit.2 @@ -0,0 +1,95 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt, Ian Jackson. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Wed Jul 21 23:02:38 1993 by Rik Faith +.\" Modified 2001-11-17, aeb +.\" +.TH _EXIT 2 2001-11-17 Linux "Linux Programmer's Manual" +.SH NAME +_exit, _Exit \- terminate the current process +.SH SYNOPSIS +.B #include +.sp +.BI "void _exit(int " status ); +.sp +.B #include +.sp +.BI "void _Exit(int " status ); +.SH DESCRIPTION +The function +.B _exit +terminates the calling process "immediately". Any open file descriptors +belonging to the process are closed; any children of the process are +inherited by process 1, init, and the process's parent is sent a +.B SIGCHLD +signal. +.LP +The value +.I status +is returned to the parent process as the process's exit status, and +can be collected using one of the +.B wait +family of calls. +.LP +The function +.B _Exit +is equivalent to +.BR _exit . +.SH "RETURN VALUE" +These functions do not return. +.SH "CONFORMING TO" +SVr4, SVID, POSIX, X/OPEN, BSD 4.3. +The function \fI_Exit()\fP was introduced by C99. +.SH NOTES +For a discussion on the effects of an exit, the transmission of +exit status, zombie processes, signals sent, etc., see +.BR exit (3). +.LP +The function +.B _exit +is like \fBexit()\fP, but does not call any functions registered +with the ANSI C +.B atexit +function, nor any registered signal handlers. Whether it flushes +standard I/O buffers and removes temporary files created with +.BR tmpfile (3) +is implementation-dependent. +On the other hand, +.B _exit +does close open file descriptors, and this may cause an unknown delay, +waiting for pending output to finish. If the delay is undesired, +it may be useful to call functions like \fItcflush()\fP before +calling \fB_exit()\fP. +Whether any pending I/O is cancelled, and which pending I/O may be +cancelled upon \fB_exit()\fP, is implementation-dependent. +.SH "SEE ALSO" +.BR execve (2), +.BR fork (2), +.BR kill (2), +.BR wait (2), +.BR wait4 (2), +.BR waitpid (2), +.BR exit (3), +.BR termios (3) diff --git a/man2/_llseek.2 b/man2/_llseek.2 new file mode 100644 index 000000000..d15dbee55 --- /dev/null +++ b/man2/_llseek.2 @@ -0,0 +1 @@ +.so man2/llseek.2 diff --git a/man2/_newselect.2 b/man2/_newselect.2 new file mode 100644 index 000000000..e17784318 --- /dev/null +++ b/man2/_newselect.2 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man2/_sysctl.2 b/man2/_sysctl.2 new file mode 100644 index 000000000..9e14d4b16 --- /dev/null +++ b/man2/_sysctl.2 @@ -0,0 +1 @@ +.so man2/sysctl.2 diff --git a/man2/accept.2 b/man2/accept.2 new file mode 100644 index 000000000..a6bfd6cd2 --- /dev/null +++ b/man2/accept.2 @@ -0,0 +1,292 @@ +.\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-21 by Eric S. Raymond +.\" Modified 1998-2000 by Andi Kleen to match Linux 2.2 reality +.\" Modified 2002-04-23 by Roger Luethi +.\" Modified 2004-06-17 by Michael Kerrisk +.\" +.TH ACCEPT 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +accept \- accept a connection on a socket +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int accept(int " s ", struct sockaddr *" addr ", socklen_t *" addrlen ); +.SH DESCRIPTION + +The +.B accept +function is used with connection-based socket types +.RB ( SOCK_STREAM , +.B SOCK_SEQPACKET +and +.BR SOCK_RDM ). +It extracts the first connection request on the queue of pending +connections, creates a new connected socket with mostly the same properties as +.IR s , +and allocates a new file descriptor for the socket, which is returned. +The newly created socket is no longer in the listening state. +The original socket +.I s +is unaffected by this call. Note that any per file descriptor flags +(everything that can be set with the +.B F_SETFL +fcntl, like non blocking or async state) are not inherited across +an +.IR accept . +.PP +The argument +.I s +is a socket that has been created with +.BR socket (2), +bound to a local address with +.BR bind (2), +and is listening for connections after a +.BR listen (2). + +The argument +.I addr +is a pointer to a sockaddr structure. This structure is filled in +with the address of the connecting entity, +as known to the communications layer. The exact format of the +address passed in the +.I addr +parameter is determined by the socket's family (see +.BR socket (2) +and the respective protocol man pages). +The +.I addrlen +argument is a value-result parameter: it should initially contain the +size of the structure pointed to by +.IR addr ; +on return it will contain the actual length (in bytes) of the address +returned. When +.I addr +is NULL nothing is filled in. +.PP +If no pending +connections are present on the queue, and the socket is not marked as +non-blocking, +.B accept +blocks the caller until a connection is present. If the socket is marked +non-blocking and no pending connections are present on the queue, +.B accept +returns EAGAIN. +.PP +In order to be notified of incoming connections on a socket, you can use +.BR select (2) +or +.BR poll (2). +A readable event will be delivered when a new connection is attempted and you +may then call +.B accept +to get a socket for that connection. Alternatively, you can set the socket +to deliver +.B SIGIO +when activity occurs on a socket; see +.BR socket (7) +for details. +.PP +For certain protocols which require an explicit confirmation, +such as +DECNet, +.B accept +can be thought of as merely dequeuing the next connection request and not +implying confirmation. Confirmation can be implied by +a normal read or write on the new file descriptor, and rejection can be +implied by closing the new socket. Currently only +DECNet +has these semantics on Linux. +.SH NOTES +There may not always be a connection waiting after a +.B SIGIO +is delivered or +.BR select (2) +or +.BR poll (2) +return a readability event because the connection might have been +removed by an asynchronous network error or another thread before +.B accept +is called. +If this happens then the call will block waiting for the next +connection to arrive. +To ensure that +.B accept +never blocks, the passed socket +.I s +needs to have the +.B O_NONBLOCK +flag set (see +.BR socket (7)). +.SH "RETURN VALUE" +The call returns \-1 on error. If it succeeds, it returns a non-negative +integer that is a descriptor for the accepted socket. +.SH "ERROR HANDLING" +Linux +.B accept +passes already-pending network errors on the new socket +as an error code from +.BR accept . +This behaviour differs from other BSD socket +implementations. For reliable operation the application should detect +the network errors defined for the protocol after +.B accept +and treat +them like +.BR EAGAIN +by retrying. In case of TCP/IP these are +.BR ENETDOWN , +.BR EPROTO , +.BR ENOPROTOOPT , +.BR EHOSTDOWN , +.BR ENONET , +.BR EHOSTUNREACH , +.BR EOPNOTSUPP , +and +.BR ENETUNREACH . +.SH ERRORS +.B accept +shall fail if: +.TP +.BR EAGAIN " or " EWOULDBLOCK +The socket is marked non-blocking and no connections are +present to be accepted. +.TP +.B EBADF +The descriptor is invalid. +.TP +.B ECONNABORTED +A connection has been aborted. +.TP +.B EINTR +The system call was interrupted by a signal that was caught +before a valid connection arrived. +.TP +.B EINVAL +Socket is not listening for connections. +.TP +.B EMFILE +The per-process limit of open file descriptors has been reached. +.TP +.B ENFILE +The system limit on the total number of open files has been reached. +.TP +.B ENOTSOCK +The descriptor references a file, not a socket. +.TP +.B EOPNOTSUPP +The referenced socket is not of type +.BR SOCK_STREAM . +.PP +.B accept +may fail if: +.TP +.B EFAULT +The +.I addr +parameter is not in a writable part of the user address space. +.TP +.B ENOBUFS, ENOMEM +Not enough free memory. +This often means that the memory allocation is limited by the socket buffer +limits, not by the system memory. +.TP +.B EPROTO +Protocol error. +.PP +Linux +.B accept +may fail if: +.TP +.B EPERM +Firewall rules forbid connection. +.PP +In addition, network errors for the new socket and as defined +for the protocol may be returned. Various Linux kernels can +return other errors such as +.BR ENOSR , +.BR ESOCKTNOSUPPORT , +.BR EPROTONOSUPPORT , +.BR ETIMEDOUT . +The value +.B ERESTARTSYS +may be seen during a trace. +.SH "CONFORMING TO" +SVr4, 4.4BSD (the +.B accept +function first appeared in BSD 4.2). +The BSD man page documents five possible error returns +(EBADF, ENOTSOCK, EOPNOTSUPP, EWOULDBLOCK, EFAULT). +SUSv3 documents errors EAGAIN, EBADF, ECONNABORTED, EINTR, EINVAL, EMFILE, +ENFILE, ENOBUFS, ENOMEM, ENOTSOCK, EOPNOTSUPP, EPROTO, EWOULDBLOCK. In +addition, SUSv2 documents EFAULT and ENOSR. +.LP +Linux accept does _not_ inherit socket flags like +.BR O_NONBLOCK . +This behaviour differs from other BSD socket implementations. +Portable programs should not rely on this behaviour and always set +all required flags on the socket returned from accept. +.SH NOTE +The third argument of +.B accept +was originally declared as an `int *' (and is that under libc4 and libc5 +and on many other systems like BSD 4.*, SunOS 4, SGI); a POSIX 1003.1g draft +standard wanted to change it into a `size_t *', and that is what it is +for SunOS 5. +Later POSIX drafts have `socklen_t *', and so do the Single Unix Specification +and glibc2. +Quoting Linus Torvalds: + +.\" .I fails: only italicizes a single line +"_Any_ sane library _must_ have "socklen_t" be the same size +as int. Anything else breaks any BSD socket layer stuff. +POSIX initially _did_ make it a size_t, and I (and hopefully others, but +obviously not too many) complained to them very loudly indeed. Making +it a size_t is completely broken, exactly because size_t very seldom is +the same size as "int" on 64-bit architectures, for example. And it +_has_ to be the same size as "int" because that's what the BSD socket +interface is. +Anyway, the POSIX people eventually got a clue, and created "socklen_t". +They shouldn't have touched it in the first place, but once they did +they felt it had to have a named type for some unfathomable reason +(probably somebody didn't like losing face over having done the original +stupid thing, so they silently just renamed their blunder)." + +.SH "SEE ALSO" +.BR bind (2), +.BR connect (2), +.BR listen (2), +.BR select (2), +.BR socket (2) diff --git a/man2/access.2 b/man2/access.2 new file mode 100644 index 000000000..66bbf55be --- /dev/null +++ b/man2/access.2 @@ -0,0 +1,181 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt, Ian Jackson. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1993-07-21 Rik Faith (faith@cs.unc.edu) +.\" Modified 1994-08-21 by Michael Chastain (mec@shell.portal.com): +.\" Removed note about old kernel (pre-1.1.44) using wrong id on path. +.\" Modified 1996-03-18 by Martin Schulze (joey@infodrom.north.de): +.\" Stated more clearly how it behaves with symbolic links. +.\" Added correction due to Nick Duffek (nsd@bbc.com), aeb, 960426 +.\" Modified 1996-09-07 by Michael Haardt: +.\" Restrictions for NFS +.\" Modified 1997-09-09 by Joseph S. Myers +.\" Modified 1998-01-13 by Michael Haardt: +.\" Using access is often insecure +.\" Modified 2001-10-16 by aeb +.\" Modified 2002-04-23 by Roger Luethi +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH ACCESS 2 2004-06-23 "Linux" "Linux Programmer's Manual" +.SH NAME +access \- check user's permissions for a file +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int access(const char *" pathname ", int " mode ); +.fi +.SH DESCRIPTION +.B access +checks whether the process would be allowed to read, +write or test for existence of the file (or other file system +object) whose name is +.IR pathname . +If +.I pathname +is a symbolic link permissions of the file referred to by this +symbolic link are tested. + +.I mode +is a mask consisting of one or more of +.BR R_OK ", " W_OK ", " X_OK " and " F_OK . + +.BR R_OK ", " W_OK " and " X_OK +request checking whether the file exists and has read, write and +execute permissions, respectively. +.B F_OK +just requests checking for the existence of the file. + +The tests depend on the permissions of the directories +occurring in the path to the file, as given in +.IR pathname , +and on the permissions of directories and files referred to by symbolic +links encountered on the way. + +The check is done with the process's +.I real +UID and GID, rather than with the effective IDs as is done when +actually attempting an operation. This is to allow set-UID programs to +easily determine the invoking user's authority. + +Only access bits are checked, not the file type or contents. Therefore, if +a directory is found to be "writable," it probably means that files can be +created in the directory, and not that the directory can be written as a +file. Similarly, a DOS file may be found to be "executable," but the +.BR execve (2) +call will still fail. + +If the process has appropriate privileges, an implementation may +indicate success for +.B X_OK +even if none of the execute file permission bits are set. +.SH "RETURN VALUE" +On success (all requested permissions granted), zero is returned. +On error (at least one bit in +.I mode +asked for a permission that is denied, or some other error occurred), +\-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.B access +shall fail if: +.TP +.B EACCES +The requested access would be denied to the file or search permission +is denied for one of the directories in the path prefix of +.IR pathname . +(See also +.BR path_resolution (2).) +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENOENT +A directory component in +.I pathname +would have been accessible but does not exist or was a dangling +symbolic link. +.TP +.B ENOTDIR +A component used as a directory in +.I pathname +is not, in fact, a directory. +.TP +.B EROFS +Write permission was requested for a file on a read-only filesystem. +.PP +.B access +may fail if: +.TP +.B EFAULT +.I pathname +points outside your accessible address space. +.TP +.B EINVAL +.I mode +was incorrectly specified. +.TP +.B EIO +An I/O error occurred. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ETXTBSY +Write access was requested to an executable which is being +executed. +.SH RESTRICTIONS +.B access +returns an error if any of the access types in the requested call +fails, even if other types might be successful. +.PP +.B access +may not work correctly on NFS file systems with UID mapping enabled, +because UID mapping is done on the server and hidden from the client, +which checks permissions. +.PP +Using +.B access +to check if a user is authorized to e.g. open a file before actually +doing so using +.BR open (2) +creates a security hole, because the user might exploit the short time +interval between checking and opening the file to manipulate it. +.SH "CONFORMING TO" +SVID, AT&T, POSIX, X/OPEN, BSD 4.3 +.SH "SEE ALSO" +.BR chmod (2), +.BR chown (2), +.BR open (2), +.BR path_resolution (2), +.BR setgid (2), +.BR setuid (2), +.BR stat (2) diff --git a/man2/acct.2 b/man2/acct.2 new file mode 100644 index 000000000..145aa9327 --- /dev/null +++ b/man2/acct.2 @@ -0,0 +1,125 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified 1993-07-22 by Rik Faith +.\" Modified 1993-08-10 by Alan Cox +.\" Modified 1998-11-04 by Tigran Aivazian +.\" Modified 2004-05-27, 2004-06-17, 2004-06-23 by Michael Kerrisk +.\" +.TH ACCT 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +acct \- switch process accounting on or off +.SH SYNOPSIS +.ad l +.nf +.B #include +.sp +.BI "int acct(const char *" filename ); +.fi +.ad b +.SH DESCRIPTION +When called with the name of an existing file as argument, accounting is +turned on, records for each terminating process are appended to +\fIfilename\fP as it terminates. An argument of \fBNULL\fP causes +accounting to be turned off. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Write permission is denied for the specified file, +or search permission is denied for one of the directories +in the path prefix of +.I filename +(see also +.BR path_resolution (2)), +or +.I filename +is not a regular file. +.TP +.B EFAULT +.I filename +points outside your accessible address space. +.TP +.B EIO +Error writing to the file +.IR filename . +.TP +.B EISDIR +.I filename +is a directory. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR filename . +.TP +.B ENAMETOOLONG +.I filename +was too long. +.TP +.B ENFILE +The system limit on the total number of open files has been reached. +.TP +.B ENOENT +The specified filename does not exist. +.TP +.B ENOMEM +Out of memory. +.TP +.B ENOSYS +BSD process accounting has not been enabled when the operating system +kernel was compiled. +The kernel configuration parameter controlling this feature is +CONFIG_BSD_PROCESS_ACCT. +.TP +.B ENOTDIR +A component used as a directory in +.I filename +is not in fact a directory. +.TP +.B EPERM +The calling process has insufficient privilege to enable process accounting. +On Linux the +.B CAP_SYS_PACCT +capability is required. +.TP +.B EROFS +.I filename +refers to a file on a read-only file system. +.TP +.B EUSERS +There are no more free file structures or we ran out of memory. +.SH "CONFORMING TO" +SVr4 (but not POSIX). SVr4 documents an EBUSY error condition, +but no EISDIR or ENOSYS. Also AIX and HPUX document EBUSY (attempt is made +to enable accounting when it is already enabled), as does Solaris +(attempt is made to enable accounting using the same file that is +currently being used). +.SH NOTES +No accounting is produced for programs running when a crash occurs. In +particular, nonterminating processes are never accounted for. diff --git a/man2/adjtimex.2 b/man2/adjtimex.2 new file mode 100644 index 000000000..7ed06118c --- /dev/null +++ b/man2/adjtimex.2 @@ -0,0 +1,146 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 1997-07-30 by Paul Slootman +.\" Modified 2004-05-27 by Michael Kerrisk +.\" +.TH ADJTIMEX 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +adjtimex \- tune kernel clock +.SH SYNOPSIS +.B #include +.sp +.BI "int adjtimex(struct timex *" "buf" ); +.SH DESCRIPTION +Linux uses David L. Mills' clock adjustment algorithm (see RFC 1305). +The system call +.B adjtimex +reads and optionally sets adjustment parameters for this algorithm. +It takes a pointer to a +.I timex +structure, updates kernel parameters from field values, +and returns the same structure with current kernel values. +This structure is declared as follows: +.PP +.RS +.nf +struct timex { + int modes; /* mode selector */ + long offset; /* time offset (usec) */ + long freq; /* frequency offset (scaled ppm) */ + long maxerror; /* maximum error (usec) */ + long esterror; /* estimated error (usec) */ + int status; /* clock command/status */ + long constant; /* pll time constant */ + long precision; /* clock precision (usec) (read only) */ + long tolerance; /* clock frequency tolerance (ppm) + (read only) */ + struct timeval time; /* current time (read only) */ + long tick; /* usecs between clock ticks */ +}; +.fi +.RE +.PP +The +.I modes +field determines which parameters, if any, to set. +It may contain a +.RI bitwise- or +combination of zero or more of the following bits: +.PP +.RS +.nf +#define ADJ_OFFSET 0x0001 /* time offset */ +#define ADJ_FREQUENCY 0x0002 /* frequency offset */ +#define ADJ_MAXERROR 0x0004 /* maximum time error */ +#define ADJ_ESTERROR 0x0008 /* estimated time error */ +#define ADJ_STATUS 0x0010 /* clock status */ +#define ADJ_TIMECONST 0x0020 /* pll time constant */ +#define ADJ_TICK 0x4000 /* tick value */ +#define ADJ_OFFSET_SINGLESHOT 0x8001 /* old-fashioned adjtime */ +.fi +.RE +.PP +Ordinary users are restricted to a zero value for +.IR mode . +Only the superuser may set any parameters. +.br +.ne 12v +.SH "RETURN VALUE" +On success, +.B adjtimex +returns the clock state: +.PP +.RS +.nf +#define TIME_OK 0 /* clock synchronized */ +#define TIME_INS 1 /* insert leap second */ +#define TIME_DEL 2 /* delete leap second */ +#define TIME_OOP 3 /* leap second in progress */ +#define TIME_WAIT 4 /* leap second has occurred */ +#define TIME_BAD 5 /* clock not synchronized */ +.fi +.RE +.PP +On failure, +.B adjtimex +returns \-1 and sets +.IR errno . +.SH ERRORS +.TP +.B EFAULT +.I buf +does not point to writable memory. +.TP +.B EINVAL +An attempt is made to set +.I buf.offset +to a value outside the range \-131071 to +131071, +or to set +.I buf.status +to a value other than those listed above, +or to set +.I buf.tick +to a value outside the range +.RB 900000/ HZ +to +.RB 1100000/ HZ , +where +.B HZ +is the system timer interrupt frequency. +.TP +.B EPERM +.I buf.mode +is non-zero and the caller does not have sufficient privilege. +Under Linux the +.B CAP_SYS_TIME +capability is required. +.SH "CONFORMING TO" +\fBadjtimex\fP is Linux specific and should not be used in programs +intended to be portable. There is a similar but less general call +\fBadjtime\fR in SVr4. +.SH "SEE ALSO" +.BR settimeofday (2), +.BR capabilities (7) diff --git a/man2/afs_syscall.2 b/man2/afs_syscall.2 new file mode 100644 index 000000000..5d25ea6ce --- /dev/null +++ b/man2/afs_syscall.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/alarm.2 b/man2/alarm.2 new file mode 100644 index 000000000..8a7fb0737 --- /dev/null +++ b/man2/alarm.2 @@ -0,0 +1,84 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt, Ian Jackson. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Wed Jul 21 19:42:57 1993 by Rik Faith +.\" Modified Sun Jul 21 21:25:26 1996 by Andries Brouwer +.\" Modified Wed Nov 6 03:46:05 1996 by Eric S. Raymond +.\" +.TH ALARM 2 1993-07-21 Linux "Linux Programmer's Manual" +.SH NAME +alarm \- set an alarm clock for delivery of a signal +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "unsigned int alarm(unsigned int " seconds ); +.fi +.SH DESCRIPTION +.BR alarm " arranges for a " SIGALRM +signal to be delivered to the process in +.I seconds +seconds. + +If +.I seconds +is zero, no new +.B alarm +is scheduled. + +In any event any previously set +.B alarm +is cancelled. +.SH "RETURN VALUE" +.B alarm +returns the number of seconds remaining until any previously scheduled +alarm was due to be delivered, or zero if there was no previously +scheduled alarm. +.SH NOTES +.BR alarm " and " setitimer +share the same timer; calls to one will interfere with use of the +other. +.PP +.B sleep() +may be implemented using +.BR SIGALRM ; +mixing calls to +.B alarm() +and +.B sleep() +is a bad idea. + +Scheduling delays can, as ever, cause the execution of the process to +be delayed by an arbitrary amount of time. +.SH "CONFORMING TO" +SVr4, SVID, POSIX, X/OPEN, BSD 4.3 +.SH "SEE ALSO" +.BR gettimeofday (2), +.BR pause (2), +.BR select (2), +.BR setitimer (2), +.BR sigaction (2), +.BR signal (2), +.BR sleep (3) diff --git a/man2/alloc_hugepages.2 b/man2/alloc_hugepages.2 new file mode 100644 index 000000000..57a6ae181 --- /dev/null +++ b/man2/alloc_hugepages.2 @@ -0,0 +1,131 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 2003 Andries E. Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH ALLOC_HUGEPAGES 2 2003-02-02 "Linux 2.5.36" "Linux Programmer's Manual" +.SH NAME +alloc_hugepages, free_hugepages \- allocate or free huge pages +.SH SYNOPSIS +.BI "void *alloc_hugepages(int " key ", void *" addr ", size_t " len ", int " prot ", int " flag ); +.\" asmlinkage unsigned long sys_alloc_hugepages(int key, unsigned long addr, +.\" unsigned long len, int prot, int flag); +.sp +.BI "int free_hugepages(void *" addr ); +.\" asmlinkage int sys_free_hugepages(unsigned long addr); +.SH DESCRIPTION +The system calls +.B alloc_hugepages +and +.B free_hugepages +were introduced in Linux 2.5.36 and removed again in 2.5.54. +They existed only on i386 and ia64 (when built with CONFIG_HUGETLB_PAGE). +In Linux 2.4.20 the syscall numbers exist, but the calls return ENOSYS. +.LP +On i386 the memory management hardware knows about ordinary pages (4 KiB) +and huge pages (2 or 4 MiB). Similarly ia64 knows about huge pages of +several sizes. These system calls serve to map huge pages into the +process' memory or to free them again. +Huge pages are locked into memory, and are not swapped. +.LP +The +.I key +parameter is an identifier. When zero the pages are private, and +not inherited by children. +When positive the pages are shared with other applications using the same +.IR key , +and inherited by child processes. +.LP +The +.I addr +parameter of +.B free_hugepages() +tells which page is being freed - it was the return value of a +call to +.BR alloc_hugepages() . +(The memory is first actually freed when all users have released it.) +The +.I addr +parameter of +.B alloc_hugepages() +is a hint, that the kernel may or may not follow. +Addresses must be properly aligned. +.LP +The +.I len +parameter is the length of the required segment. It must be +a multiple of the huge page size. +.LP +The +.I prot +parameter specifies the memory protection of the segment. +It is one of PROT_READ, PROT_WRITE, PROT_EXEC. +.LP +The +.I flag +parameter is ignored, unless +.I key +is positive. In that case, if +.I flag +is IPC_CREAT, then a new huge page segment is created when none +with the given key existed. If this flag is not set, then ENOENT +is returned when no segment with the given key exists. +.IR +.SH "RETURN VALUE" +On success, +.B alloc_hugepages +returns the allocated virtual address, and +.B free_hugepages +returns zero. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B ENOSYS +The system call is not supported on this kernel. +.SH "CONFORMING TO" +These calls existed only in Linux 2.5.36 - 2.5.54. +These calls are specific to Linux on Intel processors, and should not be +used in programs intended to be portable. Indeed, the system call numbers +are marked for reuse, so programs using these may do something random +on a future kernel. +.SH FILES +.I /proc/sys/vm/nr_hugepages +Number of configured hugetlb pages. +This can be read and written. +.LP +.I /proc/meminfo +Gives info on the number of configured hugetlb pages and on their size +in the three variables HugePages_Total, HugePages_Free, Hugepagesize. +.SH NOTES +The system calls are gone. Now the hugetlbfs filesystem can be used instead. +Memory backed by huge pages (if the CPU supports them) is obtained by +mmap'ing files in this virtual filesystem. +.LP +The maximal number of huge pages can be specified using the +.B hugepages= +boot parameter. + +.\" requires CONFIG_HUGETLB_PAGE (under "Processor type and features") +.\" and CONFIG_HUGETLBFS (under "Filesystems"). +.\" mount -t hugetlbfs hugetlbfs /huge +.\" SHM_HUGETLB diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2 new file mode 100644 index 000000000..b623ea906 --- /dev/null +++ b/man2/arch_prctl.2 @@ -0,0 +1,129 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 2003 Andi Kleen +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.TH ARCH_PRCTL 2 2003-02-02 "Linux 2.4.20" "Linux Programmer's Manual" +.SH NAME +arch_prctl \- set architecture specific thread state +.SH SYNOPSIS +.B #include +.sp +.B #include +.sp +.BI "int arch_prctl(int code, unsigned long addr)" +.SH DESCRIPTION +The +.B arch_prctl +function sets architecture specific process or thread state. +.I code +selects a subfunction +and passes argument +.I addr +to it. +.LP +Sub functions for x86-64 are: +.TP +.B ARCH_SET_FS +Set the 64bit base for the +.I FS +register to +.IR addr . +.TP +.B ARCH_GET_FS +Return the 64bit base value for the +.I FS +register of the current thread in the +.I unsigned long +pointed to by the +.I address +parameter +.TP +.B ARCH_SET_GS +Set the 64bit base for the +.I GS +register to +.IR addr . +.TP +.B ARCH_GET_GS +Return the 64bit base value for the +.I GS +register of the current thread in the +.I unsigned long +pointed to by the +.I address +parameter. +.SH NOTES +.I arch_prctl +is only supported on Linux/x86-64 for 64bit programs currently. + +The 64bit base changes when a new 32bit segment selector is loaded. + +.B ARCH_SET_GS +is disabled in some kernels. + +Context switches for 64bit segment bases are rather expensive. It may be a +faster alternative to set a 32bit base using a segment selector by setting up +an LDT with +.BR modify_ldt (2) +or using the +.BR set_thread_area (2) +system call in a 2.5 kernel. +.B arch_prctl +is only needed when you want to set bases that are larger than 4GB. +Memory in the first 2GB of address space can be allocated by using +.BR mmap (2) +with the +.I MAP_32BIT +flag. + +No prototype for +.I arch_prctl +in glibc 2.2. You have to declare it yourself for now. +This will be fixed in future glibc versions. + +.I FS +may be already used by the threading library. +.SH ERRORS +.TP +.B EFAULT +.I addr +points to an unmapped address or is outside the process address space. +.TP +.B EINVAL +.I code +is not a valid subcommand. +.TP +.B EPERM +.I addr +is outside the process address space. +.SH AUTHOR +Man page written by Andi Kleen. +.SH CONFORMANCE +.I arch_prctl +is a Linux/x86-64 extension and should not be used in programs intended to be portable. +.SH "SEE ALSO" +.BR mmap (2), +.BR modify_ldt (2), +.BR prctl (2), +.BR set_thread_area (2) +.sp +AMD X86-64 Programmer's manual diff --git a/man2/bdflush.2 b/man2/bdflush.2 new file mode 100644 index 000000000..5a04862c0 --- /dev/null +++ b/man2/bdflush.2 @@ -0,0 +1,110 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2004-06-17 by Michael Kerrisk +.\" +.TH BDFLUSH 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +bdflush \- start, flush, or tune buffer-dirty-flush daemon +.SH SYNOPSIS +.nf +.BI "int bdflush(int " func ", long *" address ); +.BI "int bdflush(int " func ", long " data ); +.fi +.SH DESCRIPTION +.B bdflush +starts, flushes, or tunes the buffer-dirty-flush daemon. +Only a privileged process (one with the +.B CAP_SYS_ADMIN +capability) may call +.BR bdflush . +.PP +If +.I func +is negative or 0, and no daemon has been started, then +.B bdflush +enters the daemon code and never returns. +.PP +If +.I func +is 1, +some dirty buffers are written to disk. +.PP +If +.I func +is 2 or more and is even (low bit is 0), then +.I address +is the address of a long word, +and the tuning parameter numbered +.RI "(" "func" "\-2)/2" +is returned to the caller in that address. +.PP +If +.I func +is 3 or more and is odd (low bit is 1), then +.I data +is a long word, +and the kernel sets tuning parameter numbered +.RI "(" "func" "\-3)/2" +to that value. +.PP +The set of parameters, their values, and their legal ranges +are defined in the kernel source file +.IR fs/buffer.c . +.SH "RETURN VALUE" +If +.I func +is negative or 0 and the daemon successfully starts, +.B bdflush +never returns. +Otherwise, the return value is 0 on success and \-1 on failure, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EBUSY +An attempt was made to enter the daemon code after +another process has already entered. +.TP +.B EFAULT +.I address +points outside your accessible address space. +.TP +.B EINVAL +An attempt was made to read or write an invalid parameter number, +or to write an invalid value to a parameter. +.TP +.B EPERM +Caller does not have the +.B CAP_SYS_ADMIN +capability. +.SH "CONFORMING TO" +\fBbdflush\fP is Linux specific and should not be used in programs +intended to be portable. +.SH "SEE ALSO" +.BR fsync (2), +.BR sync (2), +.BR sync (8), +.BR update (8) diff --git a/man2/bind.2 b/man2/bind.2 new file mode 100644 index 000000000..9b3c5a258 --- /dev/null +++ b/man2/bind.2 @@ -0,0 +1,214 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Portions extracted from /usr/include/sys/socket.h, which does not have +.\" any authorship information in it. It is probably available under the GPL. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" +.\" Other portions are from the 6.9 (Berkeley) 3/10/91 man page: +.\" +.\" Copyright (c) 1983 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Modified Mon Oct 21 23:05:29 EDT 1996 by Eric S. Raymond +.\" Modified 1998 by Andi Kleen +.\" $Id: bind.2,v 1.3 1999/04/23 19:56:07 freitag Exp $ +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH BIND 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +bind \- bind a name to a socket +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int bind(int " sockfd ", struct sockaddr *" my_addr ", socklen_t " addrlen ); +.SH DESCRIPTION +.B bind +gives the socket +.I sockfd +the local address +.IR my_addr . +.I my_addr +is +.I addrlen +bytes long. Traditionally, this is called \(lqassigning a name to a socket.\(rq +When a socket is created with +.BR socket (2), +it exists in a name space (address family) but has no name assigned. +.PP +It is normally necessary to assign a local address using +.B bind +before a +.B SOCK_STREAM +socket may receive connections (see +.BR accept (2)). + +The rules used in name binding vary between address families. Consult +the manual entries in Section 7 for detailed information. For +.B AF_INET +see +.BR ip (7), +for +.B AF_UNIX +see +.BR unix (7), +for +.B AF_APPLETALK +see +.BR ddp (7), +for +.B AF_PACKET +see +.BR packet (7), +for +.B AF_X25 +see +.BR x25 (7) +and for +.B AF_NETLINK +see +.BR netlink (7). + +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +The address is protected, and the user is not the super-user. +.TP +.B EBADF +.I sockfd +is not a valid descriptor. +.TP +.B EINVAL +The socket is already bound to an address. This may change in the future: +see +.I linux/unix/sock.c +for details. +.TP +.B ENOTSOCK +Argument is a descriptor for a file, not a socket. +.PP +The following errors are specific to UNIX domain +.RB ( AF_UNIX ) +sockets: +.TP +.B EACCES +Search permission is denied on a component of the path prefix. +(See also +.BR path_resolution (2).) +.TP +.B EFAULT +.I my_addr +points outside the user's accessible address space. +.TP +.B EINVAL +The +.I addrlen +is wrong, or the socket was not in the +.B AF_UNIX +family. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR my_addr . +.TP +.B ENAMETOOLONG +.I my_addr +is too long. +.TP +.B ENOENT +The file does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.TP +.B EROFS +The socket inode would reside on a read-only file system. +.SH BUGS +The transparent proxy options are not described. +.SH "CONFORMING TO" +SVr4, 4.4BSD (the +.B bind +function first appeared in BSD 4.2). SVr4 documents additional +.BR EADDRNOTAVAIL , +.BR EADDRINUSE , +and +.B ENOSR +general error conditions, and +additional +.B EIO +and +.B EISDIR +Unix-domain error conditions. +.SH NOTE +The third argument of +.B bind +is in reality an int (and this is what BSD 4.* and libc4 and libc5 have). +Some POSIX confusion resulted in the present socklen_t, also used by glibc. +See also +.BR accept (2). +.SH "SEE ALSO" +.BR accept (2), +.BR connect (2), +.BR getsockname (2), +.BR listen (2), +.BR path_resolution (2), +.BR socket (2), +.BR ip (7), +.BR socket (7) diff --git a/man2/break.2 b/man2/break.2 new file mode 100644 index 000000000..5d25ea6ce --- /dev/null +++ b/man2/break.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/brk.2 b/man2/brk.2 new file mode 100644 index 000000000..2e24a02b6 --- /dev/null +++ b/man2/brk.2 @@ -0,0 +1,87 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Wed Jul 21 19:52:58 1993 by Rik Faith +.\" Modified Sun Aug 21 17:40:38 1994 by Rik Faith +.\" +.TH BRK 2 2003-11-01 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +brk, sbrk \- change data segment size +.SH SYNOPSIS +.B #include +.sp +.BI "int brk(void *" end_data_segment ); +.sp +.BI "void *sbrk(intptr_t " increment ); +.SH DESCRIPTION +.B brk +sets the end of the data segment to the value specified by +.IR end_data_segment , +when that value is reasonable, the system does have enough memory +and the process does not exceed its max data size (see +.BR setrlimit (2)). + +.B sbrk +increments the program's data space by +.I increment +bytes. +.B sbrk +isn't a system call, it is just a C library wrapper. +Calling +.B sbrk +with an increment of 0 can be used to find the current +location of the program break. +.SH "RETURN VALUE" +On success, +.B brk +returns zero, and +.B sbrk +returns a pointer to the start of the new area. On error, \-1 is returned, +and +.I errno +is set to +.BR ENOMEM . +.SH "CONFORMING TO" +BSD 4.3 + +.BR brk " and " sbrk +are not defined in the C Standard and are deliberately excluded from the +POSIX.1 standard (see paragraphs B.1.1.1.3 and B.8.3.3). +.SH NOTES +Various systems use various types for the parameter of +.BR sbrk (). +Common are \fBint\fP, \fBssize_t\fP, \fBptrdiff_t\fP, \fBintptr_t\fP. +.\" One sees +.\" \fBint\fP (e.g. XPGv4, DU 4.0, HP-UX 11, FreeBSD 4.0, OpenBSD 3.2), +.\" \fBssize_t\fP (OSF1 2.0, Irix 5.3, 6.5), +.\" \fBptrdiff_t\fP (libc4, libc5, ulibc, glibc2.0, 2.1), +.\" \fBintptr_t\fP (e.g. XPGv5, AIX, SunOS 5.8, 5.9, FreeBSD 4.7, NetBSD 1.6, +.\" Tru64 5.1, glibc2.2). +XPGv6 obsoletes this function. +.SH "SEE ALSO" +.BR execve (2), +.BR getrlimit (2), +.BR malloc (3) diff --git a/man2/cacheflush.2 b/man2/cacheflush.2 new file mode 100644 index 000000000..b924029e3 --- /dev/null +++ b/man2/cacheflush.2 @@ -0,0 +1,65 @@ +.\" Written by Ralf Baechle (ralf@waldorf-gmbh.de), +.\" Copyright (c) 1994, 1995 Waldorf GMBH +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH CACHEFLUSH 2 1995-06-27 "Linux 2.0.32" "Linux Programmer's Manual" +.SH NAME +cacheflush \- flush contents of instruction and/or data cache +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int cacheflush(char *" addr ", int "nbytes ", int "cache ); +.fi +.SH DESCRIPTION +.B cacheflush +flushes contents of indicated cache(s) for user addresses in the range +addr to (addr+nbytes-1). Cache may be one of: +.TP +.B ICACHE +Flush the instruction cache. +.TP +.B DCACHE +Write back to memory and invalidate the affected valid cache lines. +.TP +.B BCACHE +Same as +.B (ICACHE|DCACHE). +.PP +.SH "RETURN VALUE" +.B cacheflush +returns 0 on success or \-1 on error. If errors are detected, +errno will indicate the error. +.SH ERRORS +.TP +.B EFAULT +Some or all of the address range addr to (addr+nbytes-1) is not accessible. +.TP +.B EINVAL +cache parameter is not one of ICACHE, DCACHE, or BCACHE. +.PP +.SH BUGS +The current implementation ignores the addr and nbytes parameters. Therefore +always the whole cache is flushed. +.SH NOTE +This system call is only available on MIPS based systems. It should +not be used in programs intended to be portable. diff --git a/man2/capget.2 b/man2/capget.2 new file mode 100644 index 000000000..5f8225de9 --- /dev/null +++ b/man2/capget.2 @@ -0,0 +1,119 @@ +.\" +.\" $Id: capget.2,v 1.4 1999/09/09 16:43:26 morgan Exp $ +.\" written by Andrew Morgan +.\" may be distributed as per GPL +.\" Modified by David A. Wheeler +.\" Modified 2004-05-27, mtk +.\" Modified 2004-06-21, aeb +.\" +.TH CAPGET 2 2004-06-21 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +capget, capset \- set/get process capabilities +.SH SYNOPSIS +.B #undef _POSIX_SOURCE +.br +.B #include +.sp +.BI "int capget(cap_user_header_t " hdrp ", cap_user_data_t " datap ); +.sp +.BI "int capset(cap_user_header_t " hdrp ", const cap_user_data_t " datap ); +.SH DESCRIPTION +As of Linux 2.2, the power of the superuser (root) has been partitioned into +a set of discrete capabilities. +Every process has a set of effective capabilities identifying +which capabilities (if any) it may currently exercise. +Every process also has a set of inheritable capabilities that may be +passed through an +.BR execve (2) +call, and a set of permitted capabilities +that it can make effective or inheritable. +.PP +These two functions are the raw kernel interface for getting and +setting capabilities. Not only are these system calls specific to Linux, +but the kernel API is likely to change and use of +these functions (in particular the format of the +.B cap_user_*_t +types) is subject to change with each kernel revision. +.sp +The portable interfaces are +.IR cap_set_proc (3) +and +.IR cap_get_proc (3); +if possible you should use those interfaces in applications. +If you wish to use the Linux extensions in applications, you should +use the easier-to-use interfaces +.IR capsetp (3) +and +.IR capgetp (3). +.SS "Current details" +Now that you have been warned, some current kernel details. +The structs are defined as follows. +.sp +.nf +.in +4n +#define _LINUX_CAPABILITY_VERSION 0x19980330 + +typedef struct __user_cap_header_struct { + int version; + int pid; +} *cap_user_header_t; + +typedef struct __user_cap_data_struct { + int effective; + int permitted; + int inheritable; +} *cap_user_data_t; +.fi +.in -4n +.sp +The calls will return EINVAL, and set the version field of +.I hdr +to _LINUX_CAPABILITY_VERSION when another version was specified. + +The calls refer to the capabilities of the process indicated by +the pid field of +.I hdr +when that is nonzero, or to the current process otherwise. + +For details on the data, see +.BR capabilities (7). +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +Bad memory address. Neither of +.I hdrp +and +.I datap +may be NULL. +.TP +.B EINVAL +One of the arguments was invalid. +.TP +.B EPERM +An attempt was made to add a capability to the Permitted set, or to set +a capability in the Effective or Inheritable sets that is not in the +Permitted set. +.TP +.B EPERM +The calling process attempted to use +.BR capset () +to modify the capabilities of a process other than itself, +but lacked sufficient privilege; the +.B CAP_SETPCAP +capability is required. +.TP +.B ESRCH +No such process. +.SH "FURTHER INFORMATION" +The portable interface to the capability querying and setting +functions is provided by the +.B libcap +library and is available from here: +.br +.B ftp://ftp.kernel.org/pub/linux/libs/security/linux-privs +.SH "SEE ALSO" +.BR capabilities (7) diff --git a/man2/capset.2 b/man2/capset.2 new file mode 100644 index 000000000..9e829cbd8 --- /dev/null +++ b/man2/capset.2 @@ -0,0 +1 @@ +.so man2/capget.2 diff --git a/man2/chdir.2 b/man2/chdir.2 new file mode 100644 index 000000000..897153502 --- /dev/null +++ b/man2/chdir.2 @@ -0,0 +1,128 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1995-04-15 by Michael Chastain : +.\" Added 'fchdir'. Fixed bugs in error section. +.\" Modified 1996-10-21 by Eric S. Raymond +.\" Modified 1997-08-21 by Joseph S. Myers +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH CHDIR 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +chdir, fchdir \- change working directory +.SH SYNOPSIS +.B #include +.sp +.BI "int chdir(const char *" path ); +.br +.BI "int fchdir(int " fd ); +.SH DESCRIPTION +.B chdir +changes the current directory to that specified in +.IR path . +.PP +.B fchdir +is identical to +.BR chdir ; +the only difference is that the directory is given as an +open file descriptor. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +Depending on the file system, other errors can be returned. The more +general errors for +.B chdir +are listed below: +.TP +.B EACCES +Search permission is denied for one of the directories in the path prefix of +.IR path . +(See also +.BR path_resolution (2).) +.TP +.B EFAULT +.I path +points outside your accessible address space. +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR path . +.TP +.B ENAMETOOLONG +.I path +is too long. +.TP +.B ENOENT +The file does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of +.I path +is not a directory. +.PP +The general errors for +.B fchdir +are listed below: +.TP +.B EACCES +Search permission was denied on the directory open on +.IR fd . +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.SH NOTES +The prototype for +.B fchdir +is only available if +.B _BSD_SOURCE +is defined (either explicitly, or implicitly, by not defining +_POSIX_SOURCE or compiling with the -ansi flag). +.SH "CONFORMING TO" +The +.B chdir +call is compatible with SVr4, SVID, POSIX, X/OPEN, 4.4BSD. SVr4 documents +additional EINTR, ENOLINK, and EMULTIHOP error conditions but has +no ENOMEM. POSIX.1 does not have ENOMEM or ELOOP error conditions. +X/OPEN does not have EFAULT, ENOMEM or EIO error conditions. + +The +.B fchdir +call is compatible with SVr4, 4.4BSD and X/OPEN. +SVr4 documents additional EIO, EINTR, and ENOLINK error conditions. +X/OPEN documents additional EINTR and EIO error conditions. +.SH "SEE ALSO" +.BR chroot (2), +.BR path_resolution (2), +.BR getcwd (3) diff --git a/man2/chmod.2 b/man2/chmod.2 new file mode 100644 index 000000000..fcb3a1b22 --- /dev/null +++ b/man2/chmod.2 @@ -0,0 +1,212 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1997-01-12 by Michael Haardt +.\" : NFS details +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH CHMOD 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +chmod, fchmod \- change permissions of a file +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int chmod(const char *" path ", mode_t " mode ); +.br +.BI "int fchmod(int " fildes ", mode_t " mode ); +.SH DESCRIPTION +The mode of the file given by +.I path +or referenced by +.I fildes +is changed. + +Modes are specified by +.IR or'ing +the following: +.RS +.sp +.TP 1.0i +S_ISUID +04000 set user ID on execution +.TP +S_ISGID +02000 set group ID on execution +.TP +S_ISVTX +01000 sticky bit +.TP +S_IRUSR (S_IREAD) +00400 read by owner +.TP +S_IWUSR (S_IWRITE) +00200 write by owner +.TP +S_IXUSR (S_IEXEC) +00100 execute/search by owner +.TP +S_IRGRP +00040 read by group +.TP +S_IWGRP +00020 write by group +.TP +S_IXGRP +00010 execute/search by group +.TP +S_IROTH +00004 read by others +.TP +S_IWOTH +00002 write by others +.TP +S_IXOTH +00001 execute/search by others +.sp +.RE + +The effective UID of the calling process must match the owner of the file, +or the process must be privileged (Linux: it must have the +.B CAP_FOWNER +capability). + +If the calling process is not privileged (Linux: does not have the +.B CAP_FSETID +capability), and the group of the file does not match +the effective group ID of the process or one of its +supplementary group IDs, the S_ISGID bit will be turned off, +but this will not cause an error to be returned. + +As a security measure, depending on the file system, +the set user ID and set group ID execution bits +may be turned off if a file is written. +(On Linux this occurs if the writing process does not have the +.B CAP_FSETID +capability.) +On some file systems, only the super-user can set the sticky bit, +which may have a special meaning. +For the sticky bit, and for set user ID and set group ID bits on +directories, see +.BR stat (2). + +On NFS file systems, restricting the permissions will immediately influence +already open files, because the access control is done on the server, but +open files are maintained by the client. Widening the permissions may be +delayed for other clients if attribute caching is enabled on them. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +Depending on the file system, other errors can be returned. The more +general errors for +.B chmod +are listed below: + +.TP +.B EACCES +Search permission is denied on a component of the path prefix. +(See also +.BR path_resolution (2).) +.TP +.B EFAULT +.I path +points outside your accessible address space. +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR path . +.TP +.B ENAMETOOLONG +.I path +is too long. +.TP +.B ENOENT +The file does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.TP +.B EPERM +The effective UID does not match the owner of the file, +and the process is not privileged (Linux: it does not have the +.B CAP_FOWNER +capability). +.TP +.B EROFS +The named file resides on a read-only file system. +.PP +The general errors for +.B fchmod +are listed below: +.TP +.B EBADF +The file descriptor +.I fildes +is not valid. +.TP +.B EIO +See above. +.TP +.B EPERM +See above. +.TP +.B EROFS +See above. +.SH "CONFORMING TO" +The +.B chmod +call conforms to SVr4, SVID, POSIX, X/OPEN, 4.4BSD. +SVr4 documents EINTR, ENOLINK and EMULTIHOP returns, but no +ENOMEM. POSIX.1 does not document EFAULT, ENOMEM, ELOOP or EIO error +conditions, or the macros \fBS_IREAD\fP, \fBS_IWRITE\fP and \fBS_IEXEC\fP. +.PP +The +.B fchmod +call conforms to 4.4BSD and SVr4. +SVr4 documents additional EINTR and ENOLINK error conditions. +POSIX requires the +.B fchmod +function if at least one of +.B _POSIX_MAPPED_FILES +and +.B _POSIX_SHARED_MEMORY_OBJECTS +is defined, and documents additional ENOSYS and EINVAL error +conditions, but does not document EIO. +.SH "SEE ALSO" +.BR chown (2), +.BR execve (2), +.BR open (2), +.BR path_resolution (2), +.BR stat (2) diff --git a/man2/chown.2 b/man2/chown.2 new file mode 100644 index 000000000..ef0f2fcf5 --- /dev/null +++ b/man2/chown.2 @@ -0,0 +1,185 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" Copyright (c) 1998 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1996-07-09 by Andries Brouwer +.\" Modified 1996-11-06 by Eric S. Raymond +.\" Modified 1997-05-18 by Michael Haardt +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH CHOWN 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +chown, fchown, lchown \- change ownership of a file +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int chown(const char *" path ", uid_t " owner ", gid_t " group ); +.br +.BI "int fchown(int " fd ", uid_t " owner ", gid_t " group ); +.br +.BI "int lchown(const char *" path ", uid_t " owner ", gid_t " group ); +.SH DESCRIPTION +These system calls change the owner and group of the file specified by +.I path +or by +.IR fd . +Only a privileged process (Linux: one with the +.B CAP_CHOWN +capability) may change the owner of a file. +The owner of a file may change the group of the file +to any group of which that owner is a member. +A privileged process (Linux: with +.BR CAP_CHOWN ) +may change the group arbitrarily. + +If the +.I owner +or +.I group +is specified as \-1, then that ID is not changed. + +When the owner or group of an executable file are changed by a non-super-user, +the S_ISUID and S_ISGID mode bits are cleared. POSIX does not specify whether +this also should happen when root does the +.IR chown ; +the Linux behaviour depends on the kernel version. +.\" In Linux 2.0 kernels, superuser was like everyone else +.\" In 2.2, up to 2.2.12, these bits were not cleared for superuser. +.\" Since 2.2.13, superuser is once more like everyone else. +In case of a non-group-executable file (with clear S_IXGRP bit) +the S_ISGID bit indicates mandatory locking, and is not cleared +by a +.IR chown . + +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +Depending on the file system, other errors can be returned. The more +general errors for +.B chown +are listed below. +.TP +.B EACCES +Search permission is denied on a component of the path prefix. +(See also +.BR path_resolution (2).) +.TP +.B EFAULT +.I path +points outside your accessible address space. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR path . +.TP +.B ENAMETOOLONG +.I path +is too long. +.TP +.B ENOENT +The file does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.TP +.B EPERM +The calling process did not have the required permissions +(see above) to change owner and/or group. +.TP +.B EROFS +The named file resides on a read-only file system. +.PP +The general errors for +.B fchown +are listed below: +.TP +.B EBADF +The descriptor is not valid. +.TP +.B EIO +A low-level I/O error occurred while modifying the inode. +.TP +.B ENOENT +See above. +.TP +.B EPERM +See above. +.TP +.B EROFS +See above. +.SH NOTES +In versions of Linux prior to 2.1.81 (and distinct from 2.1.46), +.B chown +did not follow symbolic links. +Since Linux 2.1.81, +.B chown +does follow symbolic links, and there is a new system call +.B lchown +that does not follow symbolic links. +Since Linux 2.1.86, this new call (that has the same semantics +as the old +.BR chown ) +has got the same syscall number, and +.B chown +got the newly introduced number. +.LP +The prototype for +.B fchown +is only available if +.B _BSD_SOURCE +is defined (either explicitly, or implicitly, by not defining +_POSIX_SOURCE or compiling with the -ansi flag). +.SH "CONFORMING TO" +The +.B chown +call conforms to SVr4, SVID, POSIX, X/OPEN. The 4.4BSD version can only be +used by the superuser (that is, ordinary users cannot give away files). +SVr4 documents EINVAL, EINTR, ENOLINK and EMULTIHOP returns, but no +ENOMEM. POSIX.1 does not document ENOMEM or ELOOP error conditions. +.PP +The +.B fchown +call conforms to 4.4BSD and SVr4. +SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK error conditions. +.SH RESTRICTIONS +The \fBchown\fP() semantics are deliberately violated on NFS file systems +which have UID mapping enabled. Additionally, the semantics of all system +calls which access the file contents are violated, because \fBchown\fP() +may cause immediate access revocation on already open files. Client side +caching may lead to a delay between the time where ownership have +been changed to allow access for a user and the time where the file can +actually be accessed by the user on other clients. +.SH "SEE ALSO" +.BR chmod (2), +.BR flock (2), +.BR path_resolution (2) diff --git a/man2/chroot.2 b/man2/chroot.2 new file mode 100644 index 000000000..22079a70e --- /dev/null +++ b/man2/chroot.2 @@ -0,0 +1,117 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1994-08-21 by Michael Chastain +.\" Modified 1996-06-13 by aeb +.\" Modified 1996-11-06 by Eric S. Raymond +.\" Modified 1997-08-21 by Joseph S. Myers +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH CHROOT 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +chroot \- change root directory +.SH SYNOPSIS +.B #include +.sp +.BI "int chroot(const char *" path ); +.SH DESCRIPTION +.B chroot +changes the root directory to that specified in +.IR path . +This directory will be used for path names beginning with /. The root +directory is inherited by all children of the current process. + +Only a privileged process (Linux: one with the +.B CAP_SYS_CHROOT +capability) may call +.BR chroot (2). + +This call changes an ingredient in the pathname resolution process +and does nothing else. + +This call does not change the current working directory, +so that after the call `.' can be outside the tree rooted at `/'. +In particular, the super-user can escape from a `chroot jail' +by doing `mkdir foo; chroot foo; cd ..'. + +This call does not close open file descriptors, and such file +descriptors may allow access to files outside the chroot tree. + +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +Depending on the file system, other errors can be returned. The more +general errors are listed below: +.TP +.B EACCES +Search permission is denied on a component of the path prefix. +(See also +.BR path_resolution (2).) +.\" Also search permission is required on the final component, +.\" maybe just to guarantee that it is a directory? +.TP +.B EFAULT +.I path +points outside your accessible address space. +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR path . +.TP +.B ENAMETOOLONG +.I path +is too long. +.TP +.B ENOENT +The file does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of +.I path +is not a directory. +.TP +.B EPERM +The caller has insufficient privilege. +.SH "CONFORMING TO" +SVr4, SVID, 4.4BSD, X/OPEN. This function is not part of POSIX.1. +SVr4 documents additional EINTR, ENOLINK and EMULTIHOP error conditions. +X/OPEN does not document EIO, ENOMEM or EFAULT error conditions. +This interface is marked as legacy by X/OPEN. +.SH NOTES +FreeBSD has a stronger +.I jail() +system call. +.SH "SEE ALSO" +.BR chdir (2), +.BR path_resolution (2) diff --git a/man2/clone.2 b/man2/clone.2 new file mode 100644 index 000000000..89616c886 --- /dev/null +++ b/man2/clone.2 @@ -0,0 +1,504 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt , March 28, 1992 +.\" and Michael Kerrisk, 2001, 2002 +.\" May be distributed under the GNU General Public License. +.\" Modified by Michael Haardt +.\" Modified 24 Jul 1993 by Rik Faith +.\" Modified 21 Aug 1994 by Michael Chastain : +.\" New man page (copied from 'fork.2'). +.\" Modified 10 June 1995 by Andries Brouwer +.\" Modified 25 April 1998 by Xavier Leroy +.\" Modified 26 Jun 2001 by Michael Kerrisk +.\" Mostly upgraded to 2.4.x +.\" Added prototype for sys_clone() plus description +.\" Added CLONE_THREAD with a brief description of thread groups +.\" Added CLONE_PARENT and revised entire page remove ambiguity +.\" between "calling process" and "parent process" +.\" Added CLONE_PTRACE and CLONE_VFORK +.\" Added EPERM and EINVAL error codes +.\" Renamed "__clone" to "clone" (which is the protype in ) +.\" various other minor tidy ups and clarifications. +.\" Modified 26 Jun 2001 by Michael Kerrisk +.\" Updated notes for 2.4.7+ behaviour of CLONE_THREAD +.\" Modified 15 Oct 2002 by Michael Kerrisk +.\" Added description for CLONE_NEWNS, which was added in 2.4.19 +.\" Slightly rephrased, aeb. +.\" Modified 1 Feb 2003 - added CLONE_SIGHAND restriction, aeb. +.\" Modified 1 Jan 2004 - various updates, aeb +.\" Modified 2004-09-10 - added CLONE_PARENT_SETTID etc - aeb. +.\" +.TH CLONE 2 2004-09-10 "Linux 2.6" "Linux Programmer's Manual" +.SH NAME +clone \- create a child process +.SH SYNOPSIS +.B #include +.sp +.BI "int clone(int (*" "fn" ")(void *), void *" "child_stack" ", int " "flags" ", void *" "arg" ); +.sp +.BI "_syscall2(int, " clone ", int, " flags ", void *, " child_stack ) +.sp +.BI "_syscall5(int, " clone ", int, " flags ", void *, " child_stack , +.br +.BI " int *, " parent_tidptr ", struct user_desc *, " newtls , +.br +.BI " int *, " child_tidptr ) +.SH DESCRIPTION +.B clone +creates a new process, just like +.BR fork (2). +.B clone +is a library function layered on top +of the underlying +.BR clone +system call, hereinafter referred to as +.BR sys_clone . +A description of +.BR sys_clone +is given towards the end of this page. + +Unlike +.BR fork (2), +these calls +allow the child process to share parts of its execution context with +the calling process, such as the memory space, the table of file +descriptors, and the table of signal handlers. (Note that on this manual +page, "calling process" normally corresponds to "parent process". But see +the description of +.B CLONE_PARENT +below.) + +The main use of +.B clone +is to implement threads: multiple threads of control in a program that +run concurrently in a shared memory space. + +When the child process is created with +.BR clone , +it executes the function +application +.IR fn ( arg ). +(This differs from +.BR fork (2), +where execution continues in the child from the point +of the +.BR fork (2) +call.) +The +.I fn +argument is a pointer to a function that is called by the child +process at the beginning of its execution. +The +.I arg +argument is passed to the +.I fn +function. + +When the +.IR fn ( arg ) +function application returns, the child process terminates. The +integer returned by +.I fn +is the exit code for the child process. The child process may also +terminate explicitly by calling +.BR exit (2) +or after receiving a fatal signal. + +The +.I child_stack +argument specifies the location of the stack used by the child +process. Since the child and calling process may share memory, +it is not possible for the child process to execute in the +same stack as the calling process. The calling process must therefore +set up memory space for the child stack and pass a pointer to this +space to +.BR clone . +Stacks grow downwards on all processors that run Linux +(except the HP PA processors), so +.I child_stack +usually points to the topmost address of the memory space set up for +the child stack. + +The low byte of +.I flags +contains the number of the signal sent to the parent when the child +dies. If this signal is specified as anything other than +.BR SIGCHLD , +then the parent process must specify the +.B __WALL +or +.B __WCLONE +options when waiting for the child with +.BR wait (2). +If no signal is specified, then the parent process is not signaled +when the child terminates. + +.I flags +may also be bitwise-or'ed with one or several of the following +constants, in order to specify what is shared between the calling process +and the child process: + +.TP +.BR CLONE_PARENT " (since Linux 2.3.12)" +If +.B CLONE_PARENT +is set, then the parent of the new child (as returned by +.BR getppid (2)) +will be the same as that of the calling process. + +If +.B CLONE_PARENT +is not set, then (as with +.BR fork (2)) +the child's parent is the calling process. + +Note that it is the parent process, as returned by +.BR getppid (2), +which is signaled when the child terminates, so that +if +.B CLONE_PARENT +is set, then the parent of the calling process, rather than the +calling process itself, will be signaled. + +.TP +.B CLONE_FS +If +.B CLONE_FS +is set, the caller and the child processes share the same file system +information. This includes the root of the file system, the current +working directory, and the umask. Any call to +.BR chroot (2), +.BR chdir (2), +or +.BR umask (2) +performed by the calling process or the child process also takes effect in the +other process. + +If +.B CLONE_FS +is not set, the child process works on a copy of the file system +information of the calling process at the time of the +.BR clone +call. +Calls to +.BR chroot (2), +.BR chdir (2), +.BR umask (2) +performed later by one of the processes do not affect the other process. + +.TP +.B CLONE_FILES +If +.B CLONE_FILES +is set, the calling process and the child processes share the same file +descriptor table. File descriptors always refer to the same files in +the calling process and in the child process. Any file descriptor created by +the calling process or by the child process is also valid in the other +process. Similarly, if one of the processes closes a file descriptor, +or changes its associated flags, the other process is also affected. + +If +.B CLONE_FILES +is not set, the child process inherits a copy of all file descriptors +opened in the calling process at the time of +.BR clone . +Operations on file descriptors performed later by either the calling process or +the child process do not affect the other process. + +.TP +.BR CLONE_NEWNS " (since Linux 2.4.19) +Start the child in a new namespace. + +Every process lives in a namespace. The +.I namespace +of a process is the data (the set of mounts) describing the file hierarchy +as seen by that process. After a +.BR fork (2) +or +.BR clone (2) +where the +.B CLONE_NEWNS +flag is not set, the child lives in the same namespace as the parent. +The system calls +.BR mount (2) +and +.BR umount (2) +change the namespace of the calling process, and hence affect +all processes that live in the same namespace, but do not affect +processes in a different namespace. + +After a +.BR clone (2) +where the +.B CLONE_NEWNS +flag is set, the cloned child is started in a new namespace, +initialized with a copy of the namespace of the parent. + +Only a privileged process (one having the CAP_SYS_ADMIN capability) +may specify the +.B CLONE_NEWNS +flag. +It is not permitted to specify both +.B CLONE_NEWNS +and +.B CLONE_FS +in the same +.BR clone +call. + +.TP +.B CLONE_SIGHAND +If +.B CLONE_SIGHAND +is set, the calling process and the child processes share the same table of +signal handlers. If the calling process or child process calls +.BR sigaction (2) +to change the behavior associated with a signal, the behavior is +changed in the other process as well. However, the calling process and child +processes still have distinct signal masks and sets of pending +signals. So, one of them may block or unblock some signals using +.BR sigprocmask (2) +without affecting the other process. + +If +.B CLONE_SIGHAND +is not set, the child process inherits a copy of the signal handlers +of the calling process at the time +.B clone +is called. Calls to +.BR sigaction (2) +performed later by one of the processes have no effect on the other +process. + +.TP +.B CLONE_PTRACE +If +.B CLONE_PTRACE +is specified, and the calling process is being traced, then trace the child also (see +.BR ptrace (2)). + +.TP +.B CLONE_VFORK +If +.B CLONE_VFORK +is set, the execution of the calling process is suspended +until the child releases its virtual memory +resources via a call to +.BR execve (2) +or +.BR _exit (2) +(as with +.BR vfork (2)). + +If +.B CLONE_VFORK +is not set then both the calling process and the child are schedulable +after the call, and an application should not rely on execution occurring +in any particular order. + +.TP +.B CLONE_VM +If +.B CLONE_VM +is set, the calling process and the child processes run in the same memory +space. In particular, memory writes performed by the calling process +or by the child process are also visible in the other process. +Moreover, any memory mapping or unmapping performed with +.BR mmap (2) +or +.BR munmap (2) +by the child or calling process also affects the other process. + +If +.B CLONE_VM +is not set, the child process runs in a separate copy of the memory +space of the calling process at the time of +.BR clone . +Memory writes or file mappings/unmappings performed by one of the +processes do not affect the other, as with +.BR fork (2). + +.TP +.BR CLONE_PID " (obsolete)" +If +.B CLONE_PID +is set, the child process is created with the same process ID as +the calling process. This is good for hacking the system, but otherwise +of not much use. Since 2.3.21 this flag can be +specified only by the system boot process (PID 0). +It disappeared in Linux 2.5.16. + +.TP +.BR CLONE_THREAD " (since Linux 2.4.0-test8)" +If +.B CLONE_THREAD +is set, the child is placed in the same thread group as the calling process. +.\" For a while there was CLONE_DETACHED (introduced in 2.5.32): +.\" parent wants no child-exit signal. In 2.6.2 the need to give this +.\" together with CLONE_THREAD disappeared. + +If +.B CLONE_THREAD +is not set, then the child is placed in its own (new) +thread group, whose ID is the same as the process ID. + +(Thread groups are feature added in Linux 2.4 to support the +POSIX threads notion of a set of threads sharing a single PID. In Linux +since 2.4, calls to +.BR getpid (2) +return the thread group ID of the caller.) + +.TP +.BR CLONE_SETTLS " (since Linux 2.5.32)" +The +.I newtls +parameter is the new TLS (Thread Local Storage) descriptor. +(See +.BR set_thread_area (2).) + +.TP +.BR CLONE_PARENT_SETTID " (since Linux 2.5.49)" +Store child thread ID at location +.I parent_tidptr +in parent and child memory. +(In Linux 2.5.32-2.5.48 there was a flag CLONE_SETTID that did this.) + +.TP +.BR CLONE_CHILD_SETTID " (since Linux 2.5.49)" +Store child thread ID at location +.I child_tidptr +in child memory. + +.TP +.BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)" +Erase child thread ID at location +.I child_tidptr +in child memory when the child exits, and do a wakeup on the futex +at that address. +The address involved may be changed by the +.BR set_tid_address (2) +system call. This is used by threading libraries. + + +.SS "sys_clone" +The +.B sys_clone +system call corresponds more closely to +.BR fork (2) +in that execution in the child continues from the point of the +call. Thus, +.B sys_clone +only requires the +.I flags +and +.I child_stack +arguments, which have the same meaning as for +.BR clone . +(Note that the order of these arguments differs from +.BR clone .) + +Another difference for +.B sys_clone +is that the +.I child_stack +argument may be zero, in which case copy-on-write semantics ensure that the +child gets separate copies of stack pages when either process modifies +the stack. In this case, for correct operation, the +.B CLONE_VM +option should not be specified. + +Since Linux 2.5.49 the system call has five parameters. +The two new parameters are +.I parent_tidptr +which points to the location (in parent and child memory) where +the parent thread ID will be written in case CLONE_PARENT_SETTID +was specified, and +.I child_tidptr +which points to the location (in child memory) where the child thread ID +will be written in case CLONE_CHILD_SETTID was specified. + +.SH "RETURN VALUE" +.\" gettid() returns current->pid; +.\" getpid() returns current->tgid; +On success, the thread ID of the child process is returned +in the caller's thread of execution. On failure, a \-1 will be returned +in the caller's context, no child process will be created, and +.I errno +will be set appropriately. + +.SH ERRORS +.TP +.B EAGAIN +Too many processes are already running. +.TP +.B EINVAL +.B CLONE_SIGHAND +was specified, but +.B CLONE_VM +was not. (Since Linux 2.6.0-test6.) +.TP +.B EINVAL +.B CLONE_THREAD +was specified, but +.B CLONE_SIGHAND +was not. (Since Linux 2.5.35.) +.TP +.B EINVAL +Precisely one of +.B CLONE_DETACHED +and +.B CLONE_THREAD +was specified. (Since Linux 2.6.0-test6.) +.TP +.B EINVAL +Both +.B CLONE_FS +and +.B CLONE_NEWNS +were specified in +.IR flags . +.TP +.B EINVAL +Returned by +.B clone +when a zero value is specified for +.IR child_stack . +.TP +.B ENOMEM +Cannot allocate sufficient memory to allocate a task structure for the +child, or to copy those parts of the caller's context that need to be +copied. +.TP +.B EPERM +.B CLONE_NEWNS +was specified by a non-root process (process without CAP_SYS_ADMIN). +.TP +.B EPERM +.B CLONE_PID +was specified by a process other than process 0. + +.SH AVAILABILITY +There is no entry for +.B clone +in libc5. glibc2 provides +.B clone +as described in this manual page. + +.SH NOTES +For kernel versions 2.4.7-2.4.18 the CLONE_THREAD flag implied the +CLONE_PARENT flag. + +.SH "CONFORMING TO" +The +.B clone +and +.B sys_clone +calls are Linux-specific and should not be used in programs +intended to be portable. + +.SH "SEE ALSO" +.BR fork (2), +.BR getpid (2), +.BR gettid (2), +.BR wait (2), +.BR capabilities (7) diff --git a/man2/close.2 b/man2/close.2 new file mode 100644 index 000000000..8f59c0ef5 --- /dev/null +++ b/man2/close.2 @@ -0,0 +1,101 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt, Ian Jackson. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Wed Jul 21 22:40:25 1993 by Rik Faith +.\" Modified Sat Feb 18 15:27:48 1995 by Michael Haardt +.\" Modified Sun Apr 14 11:40:50 1996 by Andries Brouwer : +.\" corrected description of effect on locks (thanks to +.\" Tigran Aivazian ). +.\" Modified Fri Jan 31 16:21:46 1997 by Eric S. Raymond +.\" Modified 2000-07-22 by Nicolás Lichtmaier +.\" added note about close(2) not guaranteeing that data is safe on close. +.\" +.TH CLOSE 2 2001-12-13 "" "Linux Programmer's Manual" +.SH NAME +close \- close a file descriptor +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int close(int " fd ); +.fi +.SH DESCRIPTION +.B close +closes a file descriptor, so that it no longer refers to any file and +may be reused. Any locks held on the file it was associated with, +and owned by the process, are removed (regardless of the file +descriptor that was used to obtain the lock). +.PP +If +.I fd +is the last copy of a particular file descriptor the resources +associated with it are freed; +if the descriptor was the last reference to a file which has been +removed using +.BR unlink (2) +the file is deleted. +.SH "RETURN VALUE" +.B close +returns zero on success, or \-1 if an error occurred. +.SH ERRORS +.TP +.B EBADF +.I fd +isn't a valid open file descriptor. +.TP +.B EINTR +The +.BR close () +call was interrupted by a signal. +.TP +.B EIO +An I/O error occurred. +.SH "CONFORMING TO" +SVr4, SVID, POSIX, X/OPEN, BSD 4.3. SVr4 documents an additional +ENOLINK error condition. +.SH NOTES +Not checking the return value of close is a common but nevertheless +serious programming error. It is quite possible that errors on a +previous +.BR write (2) +operation are first reported at the final +.BR close . +Not checking the return value when closing the file may lead to +silent loss of data. This can especially be observed with NFS +and with disk quota. +.PP +A successful close does not guarantee that the data has been successfully +saved to disk, as the kernel defers writes. It is not common for a filesystem +to flush the buffers when the stream is closed. If you need to be sure that +the data is physically stored use +.BR fsync (2). +(It will depend on the disk hardware at this point.) +.SH "SEE ALSO" +.BR fcntl (2), +.BR fsync (2), +.BR open (2), +.BR shutdown (2), +.BR unlink (2), +.BR fclose (3) diff --git a/man2/connect.2 b/man2/connect.2 new file mode 100644 index 000000000..2ffa1c415 --- /dev/null +++ b/man2/connect.2 @@ -0,0 +1,231 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Portions extracted from /usr/include/sys/socket.h, which does not have +.\" any authorship information in it. It is probably available under the GPL. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" +.\" Other portions are from the 6.9 (Berkeley) 3/10/91 man page: +.\" +.\" Copyright (c) 1983 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 1998, 1999 by Andi Kleen +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH CONNECT 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +connect \- initiate a connection on a socket +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int connect(int " sockfd ", const struct sockaddr *" serv_addr , +.BI "socklen_t " addrlen ); +.SH DESCRIPTION +The file descriptor +.I sockfd +must refer to a socket. +If the socket is of type +.B SOCK_DGRAM +then the +.I serv_addr +address is the address to which datagrams are sent by default, and the only +address from which datagrams are received. If the socket is of type +.B SOCK_STREAM +or +.BR SOCK_SEQPACKET , +this call attempts to make a connection to another socket. The other +socket is specified by +.IR serv_addr , +which is an address (of length +.IR addrlen ) +in the communications space of the socket. Each +communications space interprets the +.I serv_addr +parameter in its own way. +.PP +Generally, connection-based protocol sockets may successfully +.B connect +only once; connectionless protocol sockets may use +.B connect +multiple times to change their association. Connectionless sockets may +dissolve the association by connecting to an address with the +.I sa_family +member of +.B sockaddr +set to +.BR AF_UNSPEC . +.SH "RETURN VALUE" +If the connection or binding succeeds, zero is returned. On error, \-1 is +returned, and +.I errno +is set appropriately. +.SH ERRORS +The following are general socket errors only. There may be other +domain-specific error codes. +.TP +.B EACCES +For Unix domain sockets, which are identified by pathname: +Write permission is denied on the socket file, +or search permission is denied for one of the directories +in the path prefix. +(See also +.BR path_resolution (2).) +.TP +.B EACCES, EPERM +The user tried to connect to a broadcast address without having the socket +broadcast flag enabled or the connection request failed because of a local +firewall rule. +.TP +.B EADDRINUSE +Local address is already in use. +.TP +.B EAFNOSUPPORT +The passed address didn't have the correct address family in its +.I sa_family +field. +.TP +.B EAGAIN +No more free local ports or insufficient entries in the routing cache. For +.B PF_INET +see the +.B net.ipv4.ip_local_port_range +sysctl in +.BR ip (7) +on how to increase the number of local ports. +.TP +.B EALREADY +The socket is non-blocking and a previous connection attempt has not yet +been completed. +.TP +.B EBADF +The file descriptor is not a valid index in the descriptor table. +.TP +.B ECONNREFUSED +No one listening on the remote address. +.TP +.B EFAULT +The socket structure address is outside the user's address space. +.TP +.B EINPROGRESS +The socket is non-blocking and the connection cannot be completed +immediately. It is possible to +.BR select (2) +or +.BR poll (2) +for completion by selecting the socket for writing. After +.B select +indicates writability, use +.BR getsockopt (2) +to read the +.B SO_ERROR +option at level +.B SOL_SOCKET +to determine whether +.B connect +completed successfully +.RB ( SO_ERROR +is zero) or unsuccessfully +.RB ( SO_ERROR +is one of the usual error codes listed here, +explaining the reason for the failure). +.TP +.B EISCONN +The socket is already connected. +.TP +.B ENETUNREACH +Network is unreachable. +.TP +.B ENOTSOCK +The file descriptor is not associated with a socket. +.TP +.B ETIMEDOUT +Timeout while attempting connection. The server may be too +busy to accept new connections. Note that for IP sockets the timeout may +be very long when syncookies are enabled on the server. +.SH "CONFORMING TO" +SVr4, 4.4BSD (the +.B connect +function first appeared in BSD 4.2). SVr4 documents the additional +general error codes +.BR EADDRNOTAVAIL , +.BR EINVAL , +.BR EAFNOSUPPORT , +.BR EALREADY , +.BR EINTR , +.BR EPROTOTYPE , +and +.BR ENOSR . +It also +documents many additional error conditions not described here. +.SH NOTE +The third argument of +.B connect +is in reality an int (and this is what BSD 4.* and libc4 and libc5 have). +Some POSIX confusion resulted in the present socklen_t, also used by glibc. +See also +.BR accept (2). +.SH BUGS +Unconnecting a socket by calling +.B connect +with a +.B AF_UNSPEC +address is not yet implemented. +.SH "SEE ALSO" +.BR accept (2), +.BR bind (2), +.BR getsockname (2), +.BR listen (2), +.BR path_resolution (2), +.BR socket (2) diff --git a/man2/creat.2 b/man2/creat.2 new file mode 100644 index 000000000..604e1213a --- /dev/null +++ b/man2/creat.2 @@ -0,0 +1 @@ +.so man2/open.2 diff --git a/man2/dup.2 b/man2/dup.2 new file mode 100644 index 000000000..1d378d1e4 --- /dev/null +++ b/man2/dup.2 @@ -0,0 +1,118 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt, Ian Jackson. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1993-07-21, Rik Faith +.\" Modified 1994-08-21, Michael Chastain : +.\" Fixed typoes. +.\" Modified 1997-01-31, Eric S. Raymond +.\" Modified 2002-09-28, aeb +.\" +.TH DUP 2 1994-08-21 "Linux 1.1.46" "Linux Programmer's Manual" +.SH NAME +dup, dup2 \- duplicate a file descriptor +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int dup(int " oldfd ); +.BI "int dup2(int " oldfd ", int " newfd ); +.fi +.SH DESCRIPTION +.BR dup " and " dup2 +create a copy of the file descriptor +.IR oldfd . + +After successful return of \fBdup\fR or \fBdup2\fR, +the old and new descriptors may be used interchangeably. They share +locks, file position pointers and flags; for example, if the file +position is modified by using +.B lseek +on one of the descriptors, the position is also changed for the other. + +The two descriptors do not share the close-on-exec flag, however. + +.B dup +uses the lowest-numbered unused descriptor for the new descriptor. + +.B dup2 +.RI "makes " newfd " be the copy of " oldfd ", closing " newfd +first if necessary. +.SH "RETURN VALUE" +.BR dup " and " dup2 +return the new descriptor, or \-1 if an error occurred (in which case, +.I errno +is set appropriately). +.SH ERRORS +.TP +.B EBADF +.I oldfd +isn't an open file descriptor, or +.I newfd +is out of the allowed range for file descriptors. +.TP +.B EBUSY +(Linux only) This may be returned by +.B dup2 +during a race condition with open() and dup(). +.TP +.B EINTR +The +.B dup2 +call was interrupted by a signal. +.TP +.B EMFILE +The process already has the maximum number of file +descriptors open and tried to open a new one. +.SH WARNING +The error returned by +.B dup2 +is different from that returned by +.BR fcntl( "..., " F_DUPFD ", ..." ) +when +.I newfd +is out of range. On some systems +.B dup2 +also sometimes returns +.B EINVAL +like +.BR F_DUPFD . +.SH BUGS +If +.I newfd +was open, any errors that would have been reported at +.IR close () +time, are lost. A careful programmer will not use +.B dup2 +without closing +.I newfd +first. +.SH "CONFORMING TO" +SVr4, SVID, POSIX, X/OPEN, BSD 4.3. SVr4 documents additional +EINTR and ENOLINK error conditions. POSIX.1 adds EINTR. +The EBUSY return is Linux-specific. +.SH "SEE ALSO" +.BR close (2), +.BR fcntl (2), +.BR open (2) diff --git a/man2/dup2.2 b/man2/dup2.2 new file mode 100644 index 000000000..49a65c65d --- /dev/null +++ b/man2/dup2.2 @@ -0,0 +1 @@ +.so man2/dup.2 diff --git a/man2/epoll_create.2 b/man2/epoll_create.2 new file mode 100644 index 000000000..0fa4d03e5 --- /dev/null +++ b/man2/epoll_create.2 @@ -0,0 +1,70 @@ +.\" +.\" epoll by Davide Libenzi ( efficient event notification retrieval ) +.\" Copyright (C) 2003 Davide Libenzi +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program; if not, write to the Free Software +.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +.\" +.\" Davide Libenzi +.\" +.\" Modified 2004-06-17 by Michael Kerrisk +.\" +.TH EPOLL_CREATE 2 "2004-06-17" "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +epoll_create \- open an epoll file descriptor +.SH SYNOPSIS +.B #include +.sp +.BR "int epoll_create(int " size ) +.SH DESCRIPTION +Open an +.B epoll +file descriptor by requesting the kernel allocate +an event backing store dimensioned for +.I size +descriptors. The +.I size +is not the maximum size of the backing store but +just a hint to the kernel about how to dimension internal structures. +The returned file descriptor will be used for all the subsequent calls to the +.B epoll +interface. The file descriptor returned by +.BR epoll_create (2) +must be closed by using +.BR close (2). +.SH "RETURN VALUE" +When successful, +.BR epoll_create (2) +returns a positive integer identifying the descriptor. +When an error occurs, +.BR epoll_create (2) +returns -1 and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B ENFILE +The system limit on the total number of open files has been reached. +.TP +.B ENOMEM +There was insufficient memory to create the kernel object. +.SH CONFORMING TO +.BR epoll_create (2) +is a new API introduced in Linux kernel 2.5.44. +The interface should be finalized by Linux kernel 2.5.66. +.SH "SEE ALSO" +.BR close (2), +.BR epoll_ctl (2), +.BR epoll_wait (2), +.BR epoll (4) diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2 new file mode 100644 index 000000000..9f79da969 --- /dev/null +++ b/man2/epoll_ctl.2 @@ -0,0 +1,187 @@ +.\" +.\" epoll by Davide Libenzi ( efficient event notification retrieval ) +.\" Copyright (C) 2003 Davide Libenzi +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program; if not, write to the Free Software +.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +.\" +.\" Davide Libenzi +.\" +.\" +.TH EPOLL_CTL 2 "2002-10-23" Linux "Linux Programmer's Manual" +.SH NAME +epoll_ctl \- control interface for an epoll descriptor +.SH SYNOPSIS +.B #include +.sp +.BR "int epoll_ctl(int " epfd ", int " op ", int " fd ", struct epoll_event *" event ) +.SH DESCRIPTION +Control an +.B epoll +descriptor, +.IR epfd , +by requesting the operation +.IR op +be performed on the target file descriptor, +.IR fd . +The +.IR event +describes the object linked to the file descriptor +.IR fd . +The +.B struct epoll_event +is defined as : +.sp +.nf + + typedef union epoll_data { + void *ptr; + int fd; + __uint32_t u32; + __uint64_t u64; + } epoll_data_t; + + struct epoll_event { + __uint32_t events; /* Epoll events */ + epoll_data_t data; /* User data variable */ + }; + +.fi + +The +.I events +member is a bit set composed using the following available event +types : +.TP +.B EPOLLIN +The associated file is available for +.BR read (2) +operations. +.TP +.B EPOLLOUT +The associated file is available for +.BR write (2) +operations. +.TP +.B EPOLLPRI +There is urgent data available for +.BR read (2) +operations. +.TP +.B EPOLLERR +Error condition happened on the associated file descriptor. +.TP +.B EPOLLHUP +Hang up happened on the associated file descriptor. +.TP +.B EPOLLET +Sets the Edge Triggered behaviour for the associated file descriptor. +The default behaviour for +.B epoll +is Level Triggered. See +.BR epoll (4) +for more detailed informations about Edge and Level Triggered event +distribution architectures. +.TP +.B EPOLLONESHOT +Sets the One-Shot behaviour for the associated file descriptor. It means +that after an event is pulled out with +.BR epoll_wait (2) +the associated file descriptor is internally disabled and no other events +will be reported by the +.B epoll +interface. The user must call +.BR epoll_ctl (2) +with +.B EPOLL_CTL_MOD +to re-enable the file descriptor with a new event mask. +.PP +.sp +The +.B epoll +interface supports all file descriptors that support +.BR poll (2). +Valid values for the +.IR op +parameter are : +.RS +.TP +.B EPOLL_CTL_ADD +Add the target file descriptor +.I fd +to the +.B epoll +descriptor +.I epfd +and associate the event +.I event +with the internal file linked to +.IR fd . +.TP +.B EPOLL_CTL_MOD +Change the event +.I event +associated to the target file descriptor +.IR fd . +.TP +.B EPOLL_CTL_DEL +Remove the target file descriptor +.I fd +from the +.B epoll +file descriptor, +.IR epfd . +.RE +.SH "RETURN VALUE" +When successful, +.BR epoll_ctl (2) +returns zero. When an error occurs, +.BR epoll_ctl (2) +returns \-1 and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +The +.I epfd +file descriptor is not a valid file descriptor. +.TP +.B EINVAL +The supplied file descriptor, +.IR epfd , +is not an +.B epoll +file descriptor, or the requested operation +.I op +is not supported by this interface. +.TP +.B ENOMEM +There was insufficient memory to handle the requested +.I op +control operation. +.TP +.B EPERM +The target file +.I fd +is not supported by +.BR epoll . +.SH CONFORMING TO +.BR epoll_ctl (2) +is a new API introduced in Linux kernel 2.5.44. +The interface should be finalized by Linux kernel 2.5.66. +.SH "SEE ALSO" +.BR epoll_create (2), +.BR epoll_wait (2), +.BR epoll (4) diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2 new file mode 100644 index 000000000..dfe524ea1 --- /dev/null +++ b/man2/epoll_wait.2 @@ -0,0 +1,119 @@ +.\" +.\" epoll by Davide Libenzi ( efficient event notification retrieval ) +.\" Copyright (C) 2003 Davide Libenzi +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program; if not, write to the Free Software +.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +.\" +.\" Davide Libenzi +.\" +.\" +.TH EPOLL_WAIT 2 "23 October 2002" Linux "Linux Programmer's Manual" +.SH NAME +epoll_wait \- wait for an I/O event on an epoll file descriptor +.SH SYNOPSIS +.B #include +.sp +.BR "int epoll_wait(int " epfd ", struct epoll_event * " events ", int " maxevents ", int " timeout) +.SH DESCRIPTION +Wait for events on the +.B epoll +file descriptor +.I epfd +for a maximum time of +.I timeout +milliseconds. The memory area pointed to by +.I events +will contain the events that will be available for the caller. +Up to +.I maxevents +are returned by +.BR epoll_wait (2). +The +.I maxevents +parameter must be greater than zero. Specifying a +.I timeout +of \-1 makes +.BR epoll_wait (2) +wait indefinitely, while specifying a +.I timeout +equal to zero makes +.BR epoll_wait (2) +to return immediately even if no events are available ( return code equal to zero ). +The +.B struct epoll_event +is defined as : +.sp +.nf + + typedef union epoll_data { + void *ptr; + int fd; + __uint32_t u32; + __uint64_t u64; + } epoll_data_t; + + struct epoll_event { + __uint32_t events; /* Epoll events */ + epoll_data_t data; /* User data variable */ + }; + +.fi + +The +.I data +of each returned structure will contain the same data the user set with a +.BR epoll_ctl (2) +.IR ( EPOLL_CTL_ADD , EPOLL_CTL_MOD ) +while the +.I events +member will contain the returned event bit field. +.SH "RETURN VALUE" +When successful, +.BR epoll_wait (2) +returns the number of file descriptors ready for the requested I/O, or zero +if no file descriptor became ready during the requested +.I timeout +milliseconds. When an error occurs, +.BR epoll_wait (2) +returns \-1 and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I epfd +is not a valid file descriptor. +.TP +.B EFAULT +The memory area pointed to by +.I events +is not accessible with write permissions. +.TP +.B EINVAL +The supplied file descriptor, +.IR epfd , +is not an +.B epoll +file descriptor, or the +.I maxevents +parameter is less than or equal to zero. +.SH CONFORMING TO +.BR epoll_wait (2) +is a new API introduced in Linux kernel 2.5.44. +The interface should be finalized by Linux kernel 2.5.66. +.SH "SEE ALSO" +.BR epoll_create (2), +.BR epoll_ctl (2), +.BR epoll (4) diff --git a/man2/execve.2 b/man2/execve.2 new file mode 100644 index 000000000..bf1189d15 --- /dev/null +++ b/man2/execve.2 @@ -0,0 +1,215 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1994-08-21 by Michael Chastain : +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 1999-11-12 by Urs Thuermann +.\" Modified 2004-06-23 by Michael Kerrisk +.sp +.BI "int execve(const char *" filename ", char *const " argv +.BI "[], char *const " envp []); +.SH DESCRIPTION +\fBexecve()\fP executes the program pointed to by \fIfilename\fP. +\fIfilename\fP must be either a binary executable, or a script +starting with a line of the form "\fB#! \fIinterpreter \fR[arg]". +In the latter case, the interpreter must be a valid pathname for an +executable which is not itself a script, which will be invoked as +\fBinterpreter\fR [arg] \fIfilename\fR. + +\fIargv\fP is an array of argument strings passed to the new program. +\fIenvp\fP is an array of strings, conventionally of the form +\fBkey=value\fR, which are passed as environment to the new +program. Both \fIargv\fP and \fIenvp\fP must be terminated by a null +pointer. The argument vector and environment can be accessed by the +called program's main function, when it is defined as \fBint main(int +argc, char *argv[], char *envp[])\fR. + +\fBexecve()\fP does not return on success, and the text, data, bss, and +stack of the calling process are overwritten by that of the program +loaded. The program invoked inherits the calling process's PID, and any +open file descriptors that are not set to close on exec. Signals pending +on the calling process are cleared. Any signals set to be caught by +the calling process are reset to their default behaviour. +The SIGCHLD signal (when set to SIG_IGN) may or may not be reset to SIG_DFL. + +If the current program is being ptraced, a \fBSIGTRAP\fP is sent to it +after a successful \fBexecve()\fP. + +If the set-uid bit is set on the program file pointed to by +\fIfilename\fP the effective user ID of the calling process is changed +to that of the owner of the program file. Similarly, when the set-gid +bit of the program file is set the effective group ID of the calling +process is set to the group of the program file. + +If the executable is an a.out dynamically-linked binary executable containing +shared-library stubs, the Linux dynamic linker +.BR ld.so (8) +is called at the start of execution to bring needed shared libraries into core +and link the executable with them. + +If the executable is a dynamically-linked ELF executable, the +interpreter named in the PT_INTERP segment is used to load the needed +shared libraries. This interpreter is typically +\fI/lib/ld-linux.so.1\fR for binaries linked with the Linux libc +version 5, or \fI/lib/ld-linux.so.2\fR for binaries linked with the +GNU libc version 2. +.SH "RETURN VALUE" +On success, \fBexecve()\fP does not return, on error \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B E2BIG +The argument list is too big. +.TP +.B EACCES +Search permission is denied on a component of the path prefix of +.I filename +or the name of a script interpreter. +(See also +.BR path_resolution (2).) +.TP +.B EACCES +The file or a script interpreter is not a regular file. +.TP +.B EACCES +Execute permission is denied for the file or a script or ELF interpreter. +.TP +.B EACCES +The file system is mounted +.IR noexec . +.TP +.B EFAULT +.I filename +points outside your accessible address space. +.TP +.B EINVAL +An ELF executable had more than one PT_INTERP segment (i.e., tried to +name more than one interpreter). +.TP +.B EIO +An I/O error occurred. +.TP +.B EISDIR +An ELF interpreter was a directory. +.TP +.B ELIBBAD +An ELF interpreter was not in a recognised format. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.I filename +or the name of a script or ELF interpreter. +.TP +.B EMFILE +The process has the maximum number of files open. +.TP +.B ENAMETOOLONG +.I filename +is too long. +.TP +.B ENFILE +The system limit on the total number of open files has been reached. +.TP +.B ENOENT +The file +.I filename +or a script or ELF interpreter does not exist, or a shared library +needed for file or interpreter cannot be found. +.TP +.B ENOEXEC +An executable is not in a recognised format, is for the wrong +architecture, or has some other format error that means it cannot be +executed. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix of +.I filename +or a script or ELF interpreter is not a directory. +.TP +.B EPERM +The file system is mounted +.IR nosuid , +the user is not the superuser, and the file has an SUID or SGID bit set. +.TP +.B EPERM +The process is being traced, the user is not the superuser and the +file has an SUID or SGID bit set. +.TP +.B ETXTBSY +Executable was open for writing by one or more processes. +.SH "CONFORMING TO" +SVr4, SVID, X/OPEN, BSD 4.3. POSIX does not document the #! behavior +but is otherwise compatible. SVr4 documents additional error +conditions EAGAIN, EINTR, ELIBACC, ENOLINK, EMULTIHOP; POSIX does not +document ETXTBSY, EPERM, EFAULT, ELOOP, EIO, ENFILE, EMFILE, EINVAL, +EISDIR or ELIBBAD error conditions. +.SH NOTES +SUID and SGID processes can not be \fBptrace()\fPd. + +Linux ignores the SUID and SGID bits on scripts. + +The result of mounting a filesystem +.I nosuid +vary between Linux kernel versions: +some will refuse execution of SUID/SGID executables when this would +give the user powers she did not have already (and return EPERM), +some will just ignore the SUID/SGID bits and exec successfully. + +A maximum line length of 127 characters is allowed for the first line in +a #! executable shell script. +.\" .SH BUGS +.\" Some Linux versions have failed to check permissions on ELF +.\" interpreters. This is a security hole, because it allows users to +.\" open any file, such as a rewinding tape device, for reading. Some +.\" Linux versions have also had other security holes in \fBexecve()\fP, +.\" that could be exploited for denial of service by a suitably crafted +.\" ELF binary. There are no known problems with 2.0.34 or 2.2.15. + +.SH HISTORICAL +With Unix V6 the argument list of an exec call was ended by 0, +while the argument list of +.I main +was ended by \-1. Thus, this +argument list was not directly usable in a further exec call. +Since Unix V7 both are NULL. + +.SH "SEE ALSO" +.BR chmod (2), +.BR fork (2), +.BR path_resolution (2), +.BR execl (3), +.BR environ (5), +.BR ld.so (8) diff --git a/man2/exit.2 b/man2/exit.2 new file mode 100644 index 000000000..9f9d2e763 --- /dev/null +++ b/man2/exit.2 @@ -0,0 +1 @@ +.so man2/_exit.2 diff --git a/man2/exit_group.2 b/man2/exit_group.2 new file mode 100644 index 000000000..b8492ff88 --- /dev/null +++ b/man2/exit_group.2 @@ -0,0 +1,45 @@ +.\" Copyright (C) 2004 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH EXIT_GROUP 2 2004-10-12 "Linux 2.6" "Linux Programmer's Manual" +.SH NAME +exit_group \- exit all threads in a process +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void exit_group(int " status ); +.SH DESCRIPTION +This system call is equivalent to +.BR exit (2) +except that it terminates not only the present thread, but all threads +in the current thread group. + +.SH "RETURN VALUE" +This system call does not return. + +.SH HISTORY +This call is present since Linux 2.5.35. + +.SH "SEE ALSO" +.BR exit (2) + diff --git a/man2/fchdir.2 b/man2/fchdir.2 new file mode 100644 index 000000000..60b9685da --- /dev/null +++ b/man2/fchdir.2 @@ -0,0 +1 @@ +.so man2/chdir.2 diff --git a/man2/fchmod.2 b/man2/fchmod.2 new file mode 100644 index 000000000..92647d2e3 --- /dev/null +++ b/man2/fchmod.2 @@ -0,0 +1 @@ +.so man2/chmod.2 diff --git a/man2/fchown.2 b/man2/fchown.2 new file mode 100644 index 000000000..f0a5635ae --- /dev/null +++ b/man2/fchown.2 @@ -0,0 +1 @@ +.so man2/chown.2 diff --git a/man2/fcntl.2 b/man2/fcntl.2 new file mode 100644 index 000000000..c6aa1d7ba --- /dev/null +++ b/man2/fcntl.2 @@ -0,0 +1,747 @@ +'\" t +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt, Ian Jackson; +.\" 1998 Jamie Lokier; +.\" 2002 Michael Kerrisk. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-09-26 by Andries Brouwer +.\" and again on 960413 and 980804 and 981223. +.\" Modified 1998-12-11 by Jamie Lokier +.\" Applied correction by Christian Ehrhardt - aeb, 990712 +.\" Modified 2002-04-23 by Michael Kerrisk +.\" Added note on F_SETFL and O_DIRECT +.\" Complete rewrite + expansion of material on file locking +.\" Incorporated description of F_NOTIFY, drawing on +.\" Stephen Rothwell's notes in Documentation/dnotify.txt. +.\" Added description of F_SETLEASE and F_GETLEASE +.\" Corrected and polished, aeb, 020527. +.\" Modified 2004-03-03 by Michael Kerrisk +.\" Modified description of file leases: fixed some errors of detail +.\" Replaced the term "lease contestant" by "lease breaker" +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH FCNTL 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +fcntl \- manipulate file descriptor +.SH SYNOPSIS +.nf +.B #include +.B #include +.sp +.BI "int fcntl(int " fd ", int " cmd ); +.BI "int fcntl(int " fd ", int " cmd ", long " arg ); +.BI "int fcntl(int " fd ", int " cmd ", struct flock *" lock ); +.fi +.SH DESCRIPTION +.B fcntl +performs one of various miscellaneous operations on +.IR fd . +The operation in question is determined by +.IR cmd . +.SS "Handling close-on-exec" +.TP +.B F_DUPFD +Find the lowest numbered available file descriptor +greater than or equal to +.I arg +and make it be a copy of +.IR fd . +This is different form +.BR dup2 (2) +which uses exactly the descriptor specified. +.sp +The old and new descriptors may be used interchangeably. They share locks, +file position pointers and flags; for example, if the file position is +modified by using +.B lseek +on one of the descriptors, the position is also changed for the other. +.sp +The two descriptors do not share the close-on-exec flag, however. +The close-on-exec flag of the copy is off, meaning that it will +not be closed on exec. +.sp +On success, the new descriptor is returned. +.TP +.B F_GETFD +Read the close-on-exec flag. If the +.B FD_CLOEXEC +bit is 0, the file will remain open across +.BR exec , +otherwise it will be closed. +.TP +.B F_SETFD +Set the close-on-exec flag to the value specified by the +.B FD_CLOEXEC +bit of +.IR arg . +.SS "The file status flags" +A file descriptor has certain associated flags, initialized by +.BR open (2) +.\" or +.\" .BR creat (2), +and possibly modified by +.BR fcntl (2). +The flags are shared between copies (made with +.BR dup (2), +.BR fork (2), +etc.) of the same file descriptor. +.sp +The flags and their semantics are described in +.BR open (2). +.TP +.B F_GETFL +Read the file descriptor's flags. +.TP +.B F_SETFL +Set the file status flags part of the descriptor's flags to the value +specified by +.IR arg . +Remaining bits (access mode, file creation flags) in +.I arg +are ignored. +On Linux this command can only change the O_APPEND, O_NONBLOCK, O_ASYNC, +and O_DIRECT flags. +.P +.SS "Advisory locking" +.BR F_GETLK ", " F_SETLK " and " F_SETLKW +are used to acquire, release, and test for the existence of record +locks (also known as file-segment or file-region locks). +The third argument +.I lock +is a pointer to a structure that has at least the following fields +(in unspecified order). +.in +2n +.nf +.sp +struct flock { + ... + short l_type; /* Type of lock: F_RDLCK, + F_WRLCK, F_UNLCK */ + short l_whence; /* How to interpret l_start: + SEEK_SET, SEEK_CUR, SEEK_END */ + off_t l_start; /* Starting offset for lock */ + off_t l_len; /* Number of bytes to lock */ + pid_t l_pid; /* PID of process blocking our lock + (F_GETLK only) */ + ... +}; +.fi +.in -2n +.P +The +.IR l_whence ", " l_start ", and " l_len +fields of this structure specify the range of bytes we wish to lock. +.I l_start +is the starting offset for the lock, and is interpreted +relative to either: +the start of the file (if +.I l_whence +is +.BR SEEK_SET ); +the current file offset (if +.I l_whence +is +.BR SEEK_CUR ); +or the end of the file (if +.I l_whence +is +.BR SEEK_END ). +In the final two cases, +.I l_start +can be a negative number provided the +offset does not lie before the start of the file. +.I l_len +is a non-negative integer (but see the NOTES below) specifying +the number of bytes to be locked. +Bytes past the end of the file may be locked, +but not bytes before the start of the file. +Specifying 0 for +.I l_len +has the special meaning: lock all bytes starting at the +location specified by +.IR l_whence " and " l_start +through to the end of file, no matter how large the file grows. +.P +The +.I l_type +field can be used to place a read +.RB ( F_RDLCK ) +or a write +.RB ( F_WDLCK ) +lock on a file. +Any number of processes may hold a read lock (shared lock) +on a file region, but only one process may hold a write lock +(exclusive lock). An exclusive lock excludes all other locks, +both shared and exclusive. +A single process can hold only one type of lock on a file region; +if a new lock is applied to an already-locked region, +then the existing lock is converted to the the new lock type. +(Such conversions may involve splitting, shrinking, or coalescing with +an existing lock if the byte range specified by the new lock does not +precisely coincide with the range of the existing lock.) +.TP +.B F_SETLK +Acquire a lock (when +.I l_type +is +.B F_RDLCK +or +.BR F_WRLCK ) +or release a lock (when +.I l_type +is +.BR F_UNLCK ) +on the bytes specified by the +.IR l_whence ", " l_start ", and " l_len +fields of +.IR lock . +If a conflicting lock is held by another process, +this call returns \-1 and sets +.I errno +to +.B EACCES +or +.BR EAGAIN . +.TP +.B F_SETLKW +As for +.BR F_SETLK , +but if a conflicting lock is held on the file, then wait for that +lock to be released. +If a signal is caught while waiting, then the call is interrupted +and (after the signal handler has returned) +returns immediately (with return value \-1 and +.I errno +set to +.BR EINTR ). +.TP +.B F_GETLK +On input to this call, +.I lock +describes a lock we would like to place on the file. +If the lock could be placed, +.BR fcntl () +does not actually place it, but returns +.B F_UNLCK +in the +.I l_type +field of +.I lock +and leaves the other fields of the structure unchanged. +If one or more incompatible locks would prevent +this lock being placed, then +.BR fcntl () +returns details about one of these locks in the +.IR l_type ", " l_whence ", " l_start ", and " l_len +fields of +.I lock +and sets +.I l_pid +to be the PID of the process holding that lock. +.P +In order to place a read lock, +.I fd +must be open for reading. +In order to place a write lock, +.I fd +must be open for writing. +To place both types of lock, open a file read-write. +.P +As well as being removed by an explicit +.BR F_UNLCK , +record locks are automatically released when the process +terminates or if it closes +.I any +file descriptor referring to a file on which locks are held. +.\" (Additional file descriptors referring to the same file +.\" may have been obtained by calls to +.\" .BR open "(2), " dup "(2), " dup2 "(2), or " fcntl (2).) +This is bad: it means that a process can lose the locks on +a file like +.I /etc/passwd +or +.I /etc/mtab +when for some reason a library function decides to open, read +and close it. +.P +Record locks are not inherited by a child created via +.BR fork (2), +but are preserved across an +.BR execve (2). +.P +Because of the buffering performed by the +.BR stdio (3) +library, the use of record locking with routines in that package +should be avoided; use +.BR read "(2) and " write (2) +instead. +.P +.SS "Mandatory locking" +(Non-POSIX.) +The above record locks may be either advisory or mandatory, +and are advisory by default. +To make use of mandatory locks, mandatory locking must be enabled +(using the "-o mand" option to +.BR mount (8)) +for the file system containing the +file to be locked and enabled on the file itself (by disabling +group execute permission on the file and enabling the set-GID +permission bit). + +Advisory locks are not enforced and are useful only between +cooperating processes. Mandatory locks are enforced for all +processes. +.P +.SS "Managing signals" +.BR F_GETOWN ", " F_SETOWN ", " F_GETSIG " and " F_SETSIG +are used to manage I/O availability signals: +.TP +.B F_GETOWN +Get the process ID or process group currently receiving SIGIO +and SIGURG signals for events on file descriptor +.IR fd . +Process groups are returned as negative values. +.TP +.B F_SETOWN +Set the process ID or process group that will receive SIGIO +and SIGURG signals for events on file descriptor +.IR fd . +Process groups are specified using negative values. +.RB ( F_SETSIG +can be used to specify a different signal instead of SIGIO). + +.\" From glibc.info: +If you set the +.B O_ASYNC +status flag on a file descriptor (either by providing this flag with the +.IR open (2) +call, or by using the +.B F_SETFL +command of +.BR fcntl ), +a SIGIO signal is sent whenever input or output becomes possible +on that file descriptor. +.sp +The process or process group to receive the signal can be selected by +using the +.B F_SETOWN +command to the +.B fcntl +function. If the file descriptor is a socket, this also selects +the recipient of SIGURG signals that are delivered when out-of-band +data arrives on that socket. (SIGURG is sent in any situation where +.BR select (2) +would report the socket as having an "exceptional condition".) +If the file descriptor corresponds to a terminal device, then SIGIO +signals are sent to the foreground process group of the terminal. +.TP +.B F_GETSIG +Get the signal sent when input or output becomes possible. A value of +zero means SIGIO is sent. Any other value (including SIGIO) is the +signal sent instead, and in this case additional info is available to +the signal handler if installed with SA_SIGINFO. +.TP +.B F_SETSIG +Sets the signal sent when input or output becomes possible. A value of +zero means to send the default SIGIO signal. Any other value (including +SIGIO) is the signal to send instead, and in this case additional info +is available to the signal handler if installed with SA_SIGINFO. +.sp +By using F_SETSIG with a non-zero value, and setting SA_SIGINFO for the +signal handler (see +.BR sigaction (2)), +extra information about I/O events is passed to +the handler in a +.I siginfo_t +structure. +If the +.I si_code +field indicates the source is SI_SIGIO, the +.I si_fd +field gives the file descriptor associated with the event. Otherwise, +there is no indication which file descriptors are pending, and you +should use the usual mechanisms +.RB ( select (2), +.BR poll (2), +.BR read (2) +with +.B O_NONBLOCK +set etc.) to determine which file descriptors are available for I/O. +.sp +By selecting a POSIX.1b real time signal (value >= SIGRTMIN), multiple +I/O events may be queued using the same signal numbers. (Queuing is +dependent on available memory). Extra information is available +if SA_SIGINFO is set for the signal handler, as above. +.PP +Using these mechanisms, a program can implement fully asynchronous I/O +without using +.BR select (2) +or +.BR poll (2) +most of the time. +.PP +The use of +.BR O_ASYNC , +.BR F_GETOWN , +.B F_SETOWN +is specific to BSD and Linux. +.B F_GETSIG +and +.B F_SETSIG +are Linux-specific. POSIX has asynchronous I/O and the +.I aio_sigevent +structure to achieve similar things; these are also available +in Linux as part of the GNU C Library (Glibc). +.P +.SS Leases +.B F_SETLEASE +and +.B F_GETLEASE +(Linux 2.4 onwards) are used (respectively) to establish and +retrieve the current setting of the calling process's lease on +the file referred to by +.IR fd . +A file lease provides a mechanism whereby the process holding +the lease (the "lease holder") is notified (via delivery of a signal) +when another process (the "lease breaker") tries to +.BR open (2) +or +.BR truncate (2) +that file. +.TP +.B F_SETLEASE +Set or remove a file lease according to which of the following +values is specified in the integer +.IR arg : + +.RS +.TP +.B F_RDLCK +Take out a read lease. +This will cause us to be notified when +another process opens the file for writing or truncates it. +.TP +.B F_WRLCK +Take out a write lease. +This will cause us to be notified when +another process opens the file (for reading or writing) or truncates it. +A write lease may be placed on a file only if no other process +currently has the file open. +.TP +.B F_UNLCK +Remove our lease from the file. +.RE +.P +A process may hold only one type of lease on a file. +.P +Leases may only be taken out on regular files. +An unprivileged process may only take out a lease on a file whose +UID matches the file system UID of the process. +A process with the +.B CAP_LEASE +capability may take out leases on arbitrary files. +.TP +.B F_GETLEASE +Indicates what type of lease we hold on the file +referred to by +.I fd +by returning either +.BR F_RDLCK ", " F_WRLCK ", or " F_UNLCK, +indicating, respectively, that the calling process holds a +read, a write, or no lease on the file. +(The third argument to +.BR fcntl () +is omitted.) +.PP +When a process (the "lease breaker") performs an +.BR open () +or +.BR truncate () +that conflicts with a lease established via +.BR F_SETLEASE , +the system call is blocked by the kernel, unless the +.B O_NONBLOCK +flag was specified to +.BR open (), +in which case the system call will return with the error +.BR EWOULDBLOCK . +The kernel notifies the lease holder by sending it a signal +(SIGIO by default). +The lease holder should respond to receipt of this signal by doing +whatever cleanup is required in preparation for the file to be +accessed by another process (e.g., flushing cached buffers) and +then either remove or downgrade its lease. +A lease is removed by performing an +.B F_SETLEASE +command specifying +.I arg +as +.BR F_UNLCK . +If we currently hold a write lease on the file, +and the lease breaker is opening the file for reading, +then it is sufficient to downgrade the lease to a read lease. +This is done by performing an +.B F_SETLEASE +command specifying +.I arg +as +.BR F_RDLCK . + +If the lease holder fails to downgrade or remove the lease within +the number of seconds specified in +.I /proc/sys/fs/lease-break-time +then the kernel forcibly removes or downgrades the lease holder's lease. + +Once the lease has been voluntarily or forcibly removed or downgraded, +and assuming the lease breaker has not unblocked its system call, +the kernel permits the lease breaker's system call to proceed. + +The default signal used to notify the lease holder is SIGIO, +but this can be changed using the +.B F_SETSIG +command to +.B fcntl (). +If a +.B F_SETSIG +command is performed (even one specifying SIGIO), and the signal +handler is established using SA_SIGINFO, then the handler will +receive a +.I siginfo_t +sructure as its second argument, and the +.I si_fd +field of this argument will hold the descriptor of the leased file +that has been accessed by another process. +(This is useful if the caller holds leases against multiple files). +.SS "File and directory change notification" +.TP +.B F_NOTIFY +(Linux 2.4 onwards) +Provide notification when the directory referred to by +.I fd +or any of the files that it contains is changed. +The events to be notified are specified in +.IR arg , +which is a bit mask specified by ORing together zero or more of +the following bits: + +.TS +l l +---- +lB l. +Bit Description (event in directory) +DN_ACCESS A file was accessed (read, pread, readv) +DN_MODIFY A file was modified (write, pwrite, + writev, truncate, ftruncate) +DN_CREATE A file was created (open, creat, mknod, + mkdir, link, symlink, rename) +DN_DELETE A file was unlinked (unlink, rename to + another directory, rmdir) +DN_RENAME A file was renamed within this + directory (rename) +DN_ATTRIB The attributes of a file were changed + (chown, chmod, utime[s]) +.TE +.sp +(In order to obtain these definitions, the _GNU_SOURCE macro must be +defined before including .) +.sp +Directory notifications are normally "one-shot", and the application +must re-register to receive further notifications. +Alternatively, if +.B DN_MULTISHOT +is included in +.IR arg , +then notification will remain in effect until explicitly removed. + +.\" The following does seem a poor API-design choice... +A series of +.B F_NOTIFY +requests is cumulative, with the events in +.I arg +being added to the set already monitored. +To disable notification of all events, make an +.B F_NOTIFY +call specifying +.I arg +as 0. +.sp +Notification occurs via delivery of a signal. +The default signal is SIGIO, but this can be changed using the +.B F_SETSIG +command to +.BR fcntl (). +In the latter case, the signal handler receives a +.I siginfo_t +structure as its second argument (if the handler was +established using SA_SIGINFO) and the +.I si_fd +field of this structure contains the file descriptor which +generated the notification (useful when establishing notification +on multiple directories). +.sp +Especially when using +.BR DN_MULTISHOT , +a POSIX.1b real time signal should be used for notication, +so that multiple notifications can be queued. +.SH "RETURN VALUE" +For a successful call, the return value depends on the operation: +.TP 0.9i +.B F_DUPFD +The new descriptor. +.TP +.B F_GETFD +Value of flag. +.TP +.B F_GETFL +Value of flags. +.TP +.B F_GETOWN +Value of descriptor owner. +.TP +.B F_GETSIG +Value of signal sent when read or write becomes possible, or zero +for traditional SIGIO behaviour. +.TP +All other commands +Zero. +.PP +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.BR EACCES " or " EAGAIN +Operation is prohibited by locks held by other processes. +Or, operation is prohibited because the file has been memory-mapped by +another process. +.TP +.B EBADF +.I fd +is not an open file descriptor, or the command was +.B F_SETLK +or +.B F_SETLKW +and the file descriptor open mode doesn't match with the +type of lock requested. +.TP +.B EDEADLK +It was detected that the specified +.B F_SETLKW +command would cause a deadlock. +.TP +.B EFAULT +.I lock +is outside your accessible address space. +.TP +.B EINTR +For +.BR F_SETLKW , +the command was interrupted by a signal. +For +.BR F_GETLK " and " F_SETLK , +the command was interrupted by a signal before the lock was checked or +acquired. Most likely when locking a remote file (e.g. locking over +NFS), but can sometimes happen locally. +.TP +.B EINVAL +For +.BR F_DUPFD , +.I arg +is negative or is greater than the maximum allowable value. For +.BR F_SETSIG , +.I arg +is not an allowable signal number. +.TP +.B EMFILE +For +.BR F_DUPFD , +the process already has the maximum number of file descriptors open. +.TP +.B ENOLCK +Too many segment locks open, lock table is full, or a remote locking +protocol failed (e.g. locking over NFS). +.TP +.B EPERM +Attempted to clear the +.B O_APPEND +flag on a file that has the append-only attribute set. +.SH NOTES +The errors returned by +.B dup2 +are different from those returned by +.BR F_DUPFD . + +Since kernel 2.0, there is no interaction between the types of lock +placed by +.BR flock (2) +and +.BR fcntl (2). + +POSIX 1003.1-2001 allows +.I l_len +to be negative. (And if it is, the interval described by the lock +covers bytes +.IR l_start + l_len +up to and including +.IR l_start -1.) +This is supported by Linux since Linux 2.4.21 and 2.5.49. + +Several systems have more fields in +.I "struct flock" +such as e.g. +.IR l_sysid . +Clearly, +.I l_pid +alone is not going to be very useful if the process holding the lock +may live on a different machine. + +.SH "CONFORMING TO" +SVr4, SVID, POSIX, X/OPEN, BSD 4.3. Only the operations F_DUPFD, +F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK, F_SETLK and F_SETLKW are +specified in POSIX.1. F_GETOWN and F_SETOWN are BSDisms not supported +in SVr4; F_GETSIG and F_SETSIG are specific to Linux. +.BR F_NOTIFY ", " F_GETLEASE ", and " F_SETLEASE +are Linux specific. +(Define the _GNU_SOURCE macro before including to +obtain these definitions.) +The flags legal for F_GETFL/F_SETFL are those supported by +.BR open (2) +and vary between these systems; O_APPEND, O_NONBLOCK, O_RDONLY, +and O_RDWR are specified in POSIX.1. SVr4 supports several other +options and flags not documented here. +.PP +SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions. +.SH "SEE ALSO" +.BR dup2 (2), +.BR flock (2), +.BR open (2), +.BR socket (2), +.BR lockf (3), +.BR capabilities (7) +.P +See also locks.txt, mandatory.txt, and dnotify.txt in +/usr/src/linux/Documentation. diff --git a/man2/fdatasync.2 b/man2/fdatasync.2 new file mode 100644 index 000000000..696e4cab8 --- /dev/null +++ b/man2/fdatasync.2 @@ -0,0 +1,93 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" Copyright (C) 1996 Markus Kuhn. +.\" +.\" [This version merged from two independently written pages - aeb] +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" 1996-04-12 Andries Brouwer +.\" 1996-04-13 Markus Kuhn +.\" +.TH FDATASYNC 2 1996-04-13 "Linux 1.3.86" "Linux Programmer's Manual" +.SH NAME +fdatasync \- synchronize a file's in-core data with that on disk +.SH SYNOPSIS +.B #include +.sp +.BI "int fdatasync(int " fd ); +.SH DESCRIPTION +.B fdatasync +flushes all data buffers of a file to disk (before the system +call returns). It resembles +.B fsync +but is not required to update the metadata such as access time. + +Applications that access databases or log files often write a tiny +data fragment (e.g., one line in a log file) and then call +.B fsync +immediately in order to ensure that the written data is physically +stored on the harddisk. Unfortunately, +.B fsync +will always initiate two write operations: one for the newly written +data and another one in order to update the modification time stored +in the inode. If the modification time is not a part of the transaction +concept +.B fdatasync +can be used to avoid unnecessary inode disk write operations. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor open for writing. +.TP +.B EIO +An error occurred during synchronization. +.TP +.BR EROFS ", " EINVAL +.I fd +is bound to a special file which does not support synchronization. +.SH BUGS +Currently (Linux 2.2) +.B fdatasync +is equivalent to +.BR fsync . +.SH AVAILABILITY +On POSIX systems on which +.B fdatasync +is available, +.B _POSIX_SYNCHRONIZED_IO +is defined in to a value greater than 0. (See also +.BR sysconf (3).) +.\" POSIX 1003.1-2001: It shall be defined to -1 or 0 or 200112L. +.\" -1: unavailable, 0: ask using sysconf(). +.\" glibc defines them to 1. +.SH "CONFORMING TO" +POSIX1b (formerly POSIX.4) +.SH "SEE ALSO" +.BR fsync (2) +.br +B.O. Gallmeister, POSIX.4, O'Reilly, pp. 220-223 and 343. diff --git a/man2/fgetxattr.2 b/man2/fgetxattr.2 new file mode 100644 index 000000000..d9e5d9037 --- /dev/null +++ b/man2/fgetxattr.2 @@ -0,0 +1 @@ +.so man2/getxattr.2 diff --git a/man2/flistxattr.2 b/man2/flistxattr.2 new file mode 100644 index 000000000..117bd2b53 --- /dev/null +++ b/man2/flistxattr.2 @@ -0,0 +1 @@ +.so man2/listxattr.2 diff --git a/man2/flock.2 b/man2/flock.2 new file mode 100644 index 000000000..7b0a5aec4 --- /dev/null +++ b/man2/flock.2 @@ -0,0 +1,180 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) and +.\" 2002 Michael Kerrisk +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Fri Jan 31 16:26:07 1997 by Eric S. Raymond +.\" Modified Fri Dec 11 17:57:27 1998 by Jamie Lokier +.\" Modified 24 Apr 2002 by Michael Kerrisk +.\" Substantial rewrites and additions +.\" +.TH FLOCK 2 2002-04-24 Linux "Linux Programmer's Manual" +.SH NAME +flock \- apply or remove an advisory lock on an open file +.SH SYNOPSIS +.B #include +.sp +.BR "int flock(int " fd ", int " operation ); +.SH DESCRIPTION +Apply or remove an advisory lock on the open file specified by +.IR fd . +The parameter +.I operation +is one of the following: +.RS +.sp +.TP 1.0i +.B LOCK_SH +Place a shared lock. +More than one process may hold a shared lock for a given file +at a given time. +.TP +.B LOCK_EX +Place an exclusive lock. +Only one process may hold an exclusive lock for a given +file at a given time. +.TP +.B LOCK_UN +Remove an existing lock held by this process. +.sp +.RE + +A call to +.BR flock () +may block if an incompatible lock is held by another process. +To make a non-blocking request, include +.B LOCK_NB +(by +.IR OR ing) +with any of the above operations. + +A single file may not simultaneously have both shared and exclusive locks. + +Locks created by +.BR flock () +are associated with a file, or, more precisely, an open file table entry. +This means that duplicate file descriptors (created by, for example, +.BR fork "(2) or " dup (2)) +refer to the same lock, and this lock may be modified +or released using any of these descriptors. +Furthermore, the lock is released either by an explicit +.B LOCK_UN +operation on any of these duplicate descriptors, or when all +such descriptors have been closed. + +A process may only hold one type of lock (shared or exclusive) +on a file. +Subsequent +.BR flock () +calls on an already locked file will convert an existing lock to the new +lock mode. + +Locks created by +.BR flock () +are preserved across an +.BR execve (2). + +A shared or exclusive lock can be placed on a file regardless of the +mode in which the file was opened. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a not an open file descriptor. +.TP +.B EINTR +While waiting to acquire a lock, the call was interrupted by +delivery of a signal caught by a handler. +.TP +.B EINVAL +.I operation +is invalid. +.TP +.B ENOLCK +The kernel ran out of memory for allocating lock records. +.TP +.B EWOULDBLOCK +The file is locked and the +.B LOCK_NB +flag was selected. +.SH "CONFORMING TO" +4.4BSD (the +.BR flock (2) +call first appeared in 4.2BSD). +A version of +.BR flock (2), +possibly implemented in terms of +.BR fcntl (2), +appears on most Unices. +.SH NOTES +.BR flock (2) +does not lock files over NFS. Use +.BR fcntl (2) +instead: that does work over NFS, given a sufficiently recent version of +Linux and a server which supports locking. +.PP +Since kernel 2.0, +.BR flock (2) +is implemented as a system call in its own right rather +than being emulated in the GNU C library as a call to +.BR fcntl (2). +This yields true BSD semantics: +there is no interaction between the types of lock +placed by +.BR flock (2) +and +.BR fcntl (2), +and +.BR flock (2) +does not detect deadlock. +.PP +.BR flock (2) +places advisory locks only; given suitable permissions on a file, +a process is free to ignore the use of +.BR flock (2) +and perform I/O on the file. +.PP +.BR flock (2) +and +.BR fcntl (2) +locks have different semantics with respect to forked processes and +.BR dup (2). +.SH "SEE ALSO" +.BR close (2), +.BR dup (2), +.BR execve (2), +.BR fcntl (2), +.BR fork (2), +.BR open (2), +.BR lockf (3) + +There are also +.I locks.txt +and +.I mandatory.txt +in +.IR /usr/src/linux/Documentation . diff --git a/man2/fork.2 b/man2/fork.2 new file mode 100644 index 000000000..c3959870b --- /dev/null +++ b/man2/fork.2 @@ -0,0 +1,91 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt (michael@moria.de) +.\" Modified Sat Jul 24 13:22:07 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 21 Aug 1994 by Michael Chastain (mec@shell.portal.com): +.\" Referenced 'clone(2)'. +.\" Modified 1995-06-10, 1996-04-18, 1999-11-01, 2000-12-24 +.\" by Andries Brouwer (aeb@cwi.nl) +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH FORK 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +fork \- create a child process +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.B pid_t fork(void); +.SH DESCRIPTION +.B fork +creates a child process that differs from the parent process only in its +PID and PPID, and in the fact that resource utilizations are set to 0. +File locks and pending signals are not inherited. +.PP +Under Linux, +.B fork +is implemented using copy-on-write pages, so the only penalty incurred by +fork is the time and memory required to duplicate the parent's page tables, +and to create a unique task structure for the child. +.SH "RETURN VALUE" +On success, the PID of the child process is returned in the parent's thread +of execution, and a 0 is returned in the child's thread of execution. On +failure, a \-1 will be returned in the parent's context, no child process +will be created, and +.I errno +will be set appropriately. +.SH ERRORS +.TP +.B EAGAIN +.B fork +cannot allocate sufficient memory to copy the parent's page tables and +allocate a task structure for the child. +.TP +.B EAGAIN +It was not possible to create a new process because the caller's +.B RLIMIT_NPROC +resource limit was encountered. +To exceed this limit, the process must have either the +.BR CAP_SYS_ADMIN +or the +.BR CAP_SYS_RESOURCE +capability. +.TP +.B ENOMEM +.B fork +failed to allocate the necessary kernel structures because memory is tight. +.SH "CONFORMING TO" +The +.B fork +call conforms to SVr4, SVID, POSIX, X/OPEN, BSD 4.3. +.SH "SEE ALSO" +.BR clone (2), +.BR execve (2), +.BR setrlimit (2), +.BR vfork (2), +.BR wait (2), +.BR capabilities (7) diff --git a/man2/free_hugepages.2 b/man2/free_hugepages.2 new file mode 100644 index 000000000..d4b906a97 --- /dev/null +++ b/man2/free_hugepages.2 @@ -0,0 +1 @@ +.so man2/alloc_hugepages.2 diff --git a/man2/fremovexattr.2 b/man2/fremovexattr.2 new file mode 100644 index 000000000..38d01ccde --- /dev/null +++ b/man2/fremovexattr.2 @@ -0,0 +1 @@ +.so man2/removexattr.2 diff --git a/man2/fsetxattr.2 b/man2/fsetxattr.2 new file mode 100644 index 000000000..dc0780751 --- /dev/null +++ b/man2/fsetxattr.2 @@ -0,0 +1 @@ +.so man2/setxattr.2 diff --git a/man2/fstat.2 b/man2/fstat.2 new file mode 100644 index 000000000..b1a86c195 --- /dev/null +++ b/man2/fstat.2 @@ -0,0 +1 @@ +.so man2/stat.2 diff --git a/man2/fstatfs.2 b/man2/fstatfs.2 new file mode 100644 index 000000000..923d3c0cc --- /dev/null +++ b/man2/fstatfs.2 @@ -0,0 +1 @@ +.so man2/statfs.2 diff --git a/man2/fstatvfs.2 b/man2/fstatvfs.2 new file mode 100644 index 000000000..7343466a9 --- /dev/null +++ b/man2/fstatvfs.2 @@ -0,0 +1 @@ +.so man2/statvfs.2 diff --git a/man2/fsync.2 b/man2/fsync.2 new file mode 100644 index 000000000..1d37aa1da --- /dev/null +++ b/man2/fsync.2 @@ -0,0 +1,104 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 21 Aug 1994 by Michael Chastain : +.\" Removed note about old libc (pre-4.5.26) translating to 'sync'. +.\" Modified 15 Apr 1995 by Michael Chastain : +.\" Added `see also' section. +.\" Modified 13 Apr 1996 by Markus Kuhn +.\" Added remarks about fdatasync. +.\" Modified 31 Jan 1997 by Eric S. Raymond +.\" Modified 18 Apr 2001 by Andi Kleen +.\" Fix description to describe what it really does; add a few caveats. +.\" +.TH FSYNC 2 2001-04-18 "Linux 1.3.85" "Linux Programmer's Manual" +.SH NAME +fsync, fdatasync \- synchronize a file's complete in-core state with that on disk +.SH SYNOPSIS +.B #include +.sp +.BI "int fsync(int " fd ); +.sp +.BI "int fdatasync(int " fd ); +.SH DESCRIPTION +.B fsync +copies all in-core parts of a file to disk, and waits until the +device reports that all parts are on stable storage. +It also updates metadata stat information. It does not necessarily ensure +that the entry in the directory containing the file has also reached disk. +For that an explicit +.B fsync +on the file descriptor of the directory is also needed. + +.B fdatasync +does the same as +.B fsync +but only flushes user data, not the meta data like the mtime or atime. + +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor open for writing. +.TP +.B EIO +An error occurred during synchronization. +.TP +.BR EROFS ", " EINVAL +.I fd +is bound to a special file which does not support synchronization. +.SH NOTES +In case the hard disk has write cache enabled, +the data may not really be on permanent storage when +.BR fsync / fdatasync +return. +.\" See +.\" .BR hdparm (8) +.\" for how to disable that cache for IDE disks. +.LP +When an ext2 file system is mounted with the +.I sync +option, directory entries are also implicitly synced by +.BR fsync . +.LP +On kernels before 2.4, +.B fsync +on big files can be inefficient. +An alternative might be to use the +.I O_SYNC +flag to +.BR open (2). +.SH "CONFORMING TO" +POSIX.1b (formerly POSIX.4) +.SH "SEE ALSO" +.BR bdflush (2), +.BR open (2), +.BR sync (2) +.BR mount (8), +.BR sync (8), +.BR update (8) diff --git a/man2/ftruncate.2 b/man2/ftruncate.2 new file mode 100644 index 000000000..2ed34f1ed --- /dev/null +++ b/man2/ftruncate.2 @@ -0,0 +1 @@ +.so man2/truncate.2 diff --git a/man2/futex.2 b/man2/futex.2 new file mode 100644 index 000000000..27a61fc76 --- /dev/null +++ b/man2/futex.2 @@ -0,0 +1,206 @@ +.\" Page by b.hubert - may be freely modified and distributed +.\" +.\" Niki A. Rahimi (LTC Security Development, narahimi@us.ibm.com) +.\" added ERRORS section. +.\" +.\" Modified 2004-06-17 mtk +.\" Modified 2004-10-07 aeb, added FUTEX_REQUEUE, FUTEX_CMP_REQUEUE +.\" +.TH FUTEX 2 "2004-10-07" "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +futex \- Fast Userspace Locking system call +.SH SYNOPSIS +.sp +.B "#include " +.sp +.B "#include " +.sp +.BI "int futex (int *" uaddr ", int " op ", int " val , +.BI "const struct timespec *" timeout , +.BI "int *" uaddr2 ", int " val3 ); +.\" int *? void *? u32 *? +.SH "DESCRIPTION" +.PP +The +.B futex +system call provides a method for +a program to wait for a value at a given address to change, and a +method to wake up anyone waiting on a particular address (while the +addresses for the same memory in separate processes may not be +equal, the kernel maps them internally so the same memory mapped in +different locations will correspond for +.B futex +calls). It is typically used to +implement the contended case of a lock in shared memory, as +described in +.BR futex (4). +.PP +When a +.BR futex (4) +operation did not finish uncontended in userspace, a call needs to be made +to the kernel to arbitrate. Arbitration can either mean putting the calling +process to sleep or, conversely, waking a waiting process. +.PP +Callers of this function are expected to adhere to the semantics as set out in +.BR futex (4). +As these +semantics involve writing non-portable assembly instructions, this in turn +probably means that most users will in fact be library authors and not +general application developers. +.PP +The +.I uaddr +argument needs to point to an aligned integer which stores the counter. +The operation to execute is passed via the +.I op +parameter, along with a value +.IR val . +.PP +Five operations are currently defined: +.TP +.B FUTEX_WAIT +This operation atomically verifies that the futex address +.I uaddr +still contains the value +.IR val , +and sleeps awaiting FUTEX_WAKE on this futex address. If the +.I timeout +argument is non-NULL, its contents describe the maximum +duration of the wait, which is infinite otherwise. The arguments +.I uaddr2 +and +.I val3 +are ignored. + +For +.BR futex (4), +this call is executed if decrementing the count gave a negative value +(indicating contention), and will sleep until another process releases +the futex and executes the FUTEX_WAKE operation. +.TP +.B FUTEX_WAKE +This operation wakes at most \fIval\fR +processes waiting on this futex address (ie. inside FUTEX_WAIT). +The arguments +.IR timeout , +.I uaddr2 +and +.I val3 +are ignored. + +For +.BR futex (4), +this is executed if incrementing +the count showed that there were waiters, once the futex value has been set +to 1 (indicating that it is available). +.TP +.B FUTEX_FD +To support asynchronous wakeups, this operation associates a file descriptor +with a futex. +.\" , suitable for .BR poll (2). +If another process executes a FUTEX_WAKE, the process will receive the signal +number that was passed in +.IR val . +The calling process must close the returned file descriptor after use. +The arguments +.IR timeout , +.I uaddr2 +and +.I val3 +are ignored. + +To prevent race conditions, the caller should test if the futex has been upped +after FUTEX_FD returns. +.TP +.BR FUTEX_REQUEUE " (since Linux 2.5.70)" +This operation was introduced in order to avoid a "thundering herd" effect +when FUTEX_WAKE is used and all processes woken up need to acquire another +futex. This call wakes up +.I val +processes, and requeues all other waiters on the futex at address +.IR uaddr2 . +The arguments +.I timeout +and +.I val3 +are ignored. +.TP +.BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)" +There was a race in the intended use of FUTEX_REQUEUE, so +FUTEX_CMP_REQUEUE was introduced. This is similar to FUTEX_REQUEUE, +but first checks whether the location +.I uaddr +still contains the value +.IR val3 . +If not, an error EAGAIN is returned. +The argument +.I timeout +is ignored. +.SH "RETURN VALUE" +.PP +Depending on which operation was executed, the returned value can have +differing meanings. +.TP +.B FUTEX_WAIT +Returns 0 if the process was woken by a FUTEX_WAKE call. In case of timeout, +ETIMEDOUT is returned. If the futex was not equal to the expected value, +the operation returns EWOULDBLOCK. Signals (or other spurious wakeups) +cause FUTEX_WAIT to return EINTR. +.TP +.B FUTEX_WAKE +Returns the number of processes woken up. +.TP +.B FUTEX_FD +Returns the new file descriptor associated with the futex. +.TP +.B FUTEX_REQUEUE +Returns the number of processes woken up. +.TP +.B FUTEX_CMP_REQUEUE +Returns the number of processes woken up. +.SH ERRORS +.TP +.B EACCES +No read access to futex memory. +.TP +.B EAGAIN +FUTEX_CMP_REQUEUE found an unexpected futex value. +(This probably indicates a race; +use the safe FUTEX_WAKE now.) +.TP +.B EFAULT +Error in getting +.I timeout +information from userspace. +.TP +.B EINVAL +An operation was not defined or error in page alignment. +.TP +.B ENFILE +The system limit on the total number of open files has been reached. +.SH "NOTES" +.PP +To reiterate, bare futexes are not intended as an easy to use abstraction +for end-users. Implementors are expected to be assembly literate and to have +read the sources of the futex userspace library referenced below. +.\" .SH "AUTHORS" +.\" .PP +.\" Futexes were designed and worked on by +.\" Hubertus Franke (IBM Thomas J. Watson Research Center), +.\" Matthew Kirkwood, Ingo Molnar (Red Hat) +.\" and Rusty Russell (IBM Linux Technology Center). +.\" This page written by bert hubert. +.SH "VERSIONS" +.PP +Initial futex support was merged in Linux 2.5.7 but with different semantics +from what was described above. A 4-parameter system call with the semantics +given here was introduced in Linux 2.5.40. In Linux 2.5.70 one parameter +was added. In Linux 2.6.7 a sixth parameter was added - messy, especially +on the s390 architecture. +.SH "SEE ALSO" +.PP +.BR futex (4), +`Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux' +(proceedings of the Ottawa Linux Symposium 2002), +futex example library, futex-*.tar.bz2 +. diff --git a/man2/get_thread_area.2 b/man2/get_thread_area.2 new file mode 100644 index 000000000..01955687a --- /dev/null +++ b/man2/get_thread_area.2 @@ -0,0 +1,50 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" This file is distributed according to the GNU General Public License. +.\" See the file COPYING in the top level source directory for details. +.\" +.\" Written by Kent Yoder. +.TH "GET_THREAD_AREA" 2 "2003-02-21" "Linux 2.5.32" "Linux Programmer's Manual" +.SH NAME +get_thread_area \- Get a Thread Local Storage (TLS) area +.SH "SYNOPSIS" +.B #include +.br +.B #include +.sp +.BI "int get_thread_area (struct user_desc *" u_info ); + +.SH "DESCRIPTION" +.B get_thread_area +returns an entry in the current thread's Thread Local Storage (TLS) array. +The index of the entry corresponds to the value +of \fIu_info->\fR\fIentry_number\fR, passed in by the user. +If the value is in bounds, \fBget_thread_info\fR copies the corresponding +TLS entry into the area pointed to by \fIu_info\fR. + +.SH "RETURN VALUE" +.B get_thread_area +returns 0 on success. +Otherwise, it returns \-1 and sets +.I errno +appropriately. + +.SH ERRORS +.TP +.B EFAULT +\fIu_info\fR is an invalid pointer. +.TP +.B EINVAL +\fIu_info->\fR\fIentry_number\fR is out of bounds. +.SH "CONFORMING TO" +.B get_thread_area +is Linux specific and should not be used in programs +that are intended to be portable. + +.SH AVAILABILITY +A version of +.B get_thread_area +first appeared in Linux 2.5.32. + +.SH "SEE ALSO" +.BR modify_ldt (2), +.BR set_thread_area (2) diff --git a/man2/getcontext.2 b/man2/getcontext.2 new file mode 100644 index 000000000..4ed154f52 --- /dev/null +++ b/man2/getcontext.2 @@ -0,0 +1,124 @@ +.\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH GETCONTEXT 2 2001-11-15 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +getcontext, setcontext \- get or set the user context +.SH SYNOPSIS +.B #include +.sp +.BI "int getcontext(ucontext_t *" ucp ); +.br +.BI "int setcontext(const ucontext_t *" ucp ); +.SH DESCRIPTION +In a SysV-like environment, one has the two types +\fBmcontext_t\fP and \fBucontext_t\fP defined in +.I +and the four functions +\fBgetcontext()\fP, \fBsetcontext()\fP, \fBmakecontext()\fP +and \fBswapcontext()\fP +that allow user-level context switching between multiple +threads of control within a process. +.LP +The \fBmcontext_t\fP type is machine-dependent and opaque. +The \fBucontext_t\fP type is a structure that has at least +the following fields: +.RS +.nf +typedef struct ucontext { + struct ucontext *uc_link; + sigset_t uc_sigmask; + stack_t uc_stack; + mcontext_t uc_mcontext; + ... +} ucontext_t; +.fi +.RE +with \fBsigset_t\fP and \fBstack_t\fP defined in +.IR . +Here \fIuc_link\fP points to the context that will be resumed +when the current context terminates (in case the current context +was created using \fBmakecontext()\fP), \fIuc_sigmask\fP is the +set of signals blocked in this context (see +.BR sigprocmask (2)), +\fIuc_stack\fP is the stack used by this context (see +.BR sigaltstack (2)), +and \fIuc_mcontext\fP is the +machine-specific representation of the saved context, +that includes the calling thread's machine registers. +.LP +The function \fBgetcontext()\fP initializes the structure +pointed at by \fIucp\fP to the currently active context. +.LP +The function \fBsetcontext()\fP restores the user context +pointed at by \fIucp\fP. A successful call does not return. +The context should have been obtained by a call of \fBgetcontext()\fP, +or \fBmakecontext()\fP, or passed as third argument to a signal +handler. +.LP +If the context was obtained by a call of \fBgetcontext()\fP, +program execution continues as if this call just returned. +.LP +If the context was obtained by a call of \fBmakecontext()\fP, +program execution continues by a call to the function \fIfunc\fP +specified as the second argument of that call to \fBmakecontext()\fP. +When the function \fIfunc\fP returns, we continue with the +\fIuc_link\fP member of the structure \fIucp\fP specified as the +first argument of that call to \fBmakecontext()\fP. +When this member is NULL, the thread exits. +.LP +If the context was obtained by a call to a signal handler, +then old standard text says that "program execution continues with the +program instruction following the instruction interrupted +by the signal". However, this sentence was removed in SUSv2, +and the present verdict is "the result is unspecified". +.SH "RETURN VALUE" +When successful, \fBgetcontext()\fP returns 0 and \fBsetcontext()\fP +does not return. On error, both return \-1 and set \fIerrno\fP +appropriately. +.SH ERRORS +None defined. +.SH NOTES +The earliest incarnation of this mechanism was the +\fIsetjmp()\fP/\fIlongjmp()\fP mechanism. Since that does not define +the handling of the signal context, the next stage was the +\fIsigsetjmp()\fP/\fIsiglongjmp()\fP pair. +The present mechanism gives much more control. On the other hand, +there is no easy way to detect whether a return from \fBgetcontext()\fP +is from the first call, or via a \fBsetcontext()\fP call. +The user has to invent her own bookkeeping device, and a register +variable won't do since registers are restored. +.LP +When a signal occurs, the current user context is saved and +a new context is created by the kernel for the signal handler. +Do not leave the handler using \fIlongjmp()\fP - it is undefined +what would happen with contexts. Use \fIsiglongjmp()\fP or +\fIsetcontext()\fP instead. +.SH "CONFORMING TO" +SUSv2 +.SH "SEE ALSO" +.BR sigaction (2), +.BR sigaltstack (2), +.BR sigprocmask (2), +.BR longjmp (3), +.BR makecontext (3), +.BR sigsetjmp (3) diff --git a/man2/getdents.2 b/man2/getdents.2 new file mode 100644 index 000000000..d6e0b4b58 --- /dev/null +++ b/man2/getdents.2 @@ -0,0 +1,117 @@ +.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Written 11 June 1995 by Andries Brouwer +.\" Modified 22 July 1995 by Michael Chastain : +.\" Derived from 'readdir.2'. +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.TH GETDENTS 2 1995-07-22 "Linux 1.3.6" "Linux Programmer's Manual" +.SH NAME +getdents \- get directory entries +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.B #include +.sp +.B _syscall3(int, getdents, uint, fd, struct dirent *, dirp, uint, count); +.sp +.BI "int getdents(unsigned int " fd ", struct dirent *" dirp ", unsigned int " count ); +.fi +.SH DESCRIPTION +This is not the function you are interested in. +Look at +.BR readdir (3) +for the POSIX conforming C library interface. +This page documents the bare kernel system call interface. +.PP +The system call +.B getdents +reads several +.I dirent +structures from the directory +pointed at by +.I fd +into the memory area pointed to by +.IR dirp . +The parameter +.I count +is the size of the memory area. +.PP +The +.I dirent +structure is declared as follows: +.PP +.RS +.nf +struct dirent +{ + long d_ino; /* inode number */ + off_t d_off; /* offset to next \fIdirent\fP */ + unsigned short d_reclen; /* length of this \fIdirent\fP */ + char d_name [NAME_MAX+1]; /* file name (null-terminated) */ +} +.fi +.RE +.PP +.I d_ino +is an inode number. +.I d_off +is the distance from the start of the directory to the start of the next +.IR dirent . +.I d_reclen +is the size of this entire +.IR dirent . +.I d_name +is a null-terminated file name. +.PP +This call supersedes +.BR readdir (2). +.SH "RETURN VALUE" +On success, the number of bytes read is returned. +On end of directory, 0 is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +Invalid file descriptor +.IR fd . +.TP +.B EFAULT +Argument points outside the calling process's address space. +.TP +.B EINVAL +Result buffer is too small. +.TP +.B ENOENT +No such directory. +.TP +.B ENOTDIR +File descriptor does not refer to a directory. +.SH "CONFORMING TO" +SVr4, SVID. SVr4 documents additional ENOLINK, EIO error conditions. +.SH "SEE ALSO" +.BR readdir (2), +.BR readdir (3) diff --git a/man2/getdomainname.2 b/man2/getdomainname.2 new file mode 100644 index 000000000..4aee81a73 --- /dev/null +++ b/man2/getdomainname.2 @@ -0,0 +1,85 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1997-08-25 by Nicolás Lichtmaier +.\" Modified 2004-06-17 by Michael Kerrisk +.\" +.TH GETDOMAINNAME 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +getdomainname, setdomainname \- get/set domain name +.SH SYNOPSIS +.B #include +.sp +.BI "int getdomainname(char *" name ", size_t " len ); +.br +.BI "int setdomainname(const char *" name ", size_t " len ); +.SH DESCRIPTION +These functions are used to access or to change the domain name of the +current processor. +If the NUL-terminated domain name requires more than \fIlen\fP bytes, +.B getdomainname +returns the first \fIlen\fP bytes (glibc) or returns an error (libc). +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +For +.BR setdomainname : +.I name +pointed outside of user address space. +.TP +.B EINVAL +For +.BR getdomainname +under libc: +.I name +is +.B NULL +or +.I name +is longer than +.I len +bytes. +.TP +.B EINVAL +For +.BR setdomainname : +.I len +was negative or too large. +.TP +.B EPERM +For +.BR setdomainname : +the caller is unprivileged (Linux: does not have the +.B CAP_SYS_ADMIN +capability). +.SH "CONFORMING TO" +POSIX does not specify these calls. +.SH "SEE ALSO" +.BR gethostname (2), +.BR sethostname (2), +.BR uname (2) diff --git a/man2/getdtablesize.2 b/man2/getdtablesize.2 new file mode 100644 index 000000000..7ab5f8066 --- /dev/null +++ b/man2/getdtablesize.2 @@ -0,0 +1,60 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 2002-04-15 by Roger Luethi and aeb +.\" +.TH GETDTABLESIZE 2 2002-04-15 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +getdtablesize \- get descriptor table size +.SH SYNOPSIS +.B #include +.sp +.B int getdtablesize(void); +.SH DESCRIPTION +.B getdtablesize +returns the maximum number of files a process can have open, +one more than the largest possible value for a file descriptor. +.SH "RETURN VALUE" +The current limit on the number of open files per process. +.SH NOTES +.B getdtablesize +is implemented as a libc library function. The glibc version calls +.BR getrlimit (2) +and returns the current +.B RLIMIT_NOFILE +limit, or +.B OPEN_MAX +when that fails. +The libc4 and libc5 versions return +.B OPEN_MAX +(set to 256 since Linux 0.98.4). +.SH "CONFORMING TO" +SVr4, 4.4BSD (the +.B getdtablesize +function first appeared in BSD 4.2). +.SH "SEE ALSO" +.BR close (2), +.BR dup (2), +.BR getrlimit (2), +.BR open (2) diff --git a/man2/getegid.2 b/man2/getegid.2 new file mode 100644 index 000000000..d9b10e73f --- /dev/null +++ b/man2/getegid.2 @@ -0,0 +1 @@ +.so man2/getgid.2 diff --git a/man2/geteuid.2 b/man2/geteuid.2 new file mode 100644 index 000000000..165cfe1d0 --- /dev/null +++ b/man2/geteuid.2 @@ -0,0 +1 @@ +.so man2/getuid.2 diff --git a/man2/getgid.2 b/man2/getgid.2 new file mode 100644 index 000000000..492e09063 --- /dev/null +++ b/man2/getgid.2 @@ -0,0 +1,51 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH GETGID 2 1993-07-23 "Linux 0.99.11" "Linux Programmer's Manual" +.SH NAME +getgid, getegid \- get group identity +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.B gid_t getgid(void); +.br +.B gid_t getegid(void); +.SH DESCRIPTION +.B getgid +returns the real group ID of the current process. + +.B getegid +returns the effective group ID of the current process. + +The real ID corresponds to the ID of the calling process. The effective ID +corresponds to the set ID bit on the file being executed. +.SH ERRORS +These functions are always successful. +.SH "CONFORMING TO" +POSIX, BSD 4.3 +.SH "SEE ALSO" +.BR setgid (2), +.BR setregid (2) diff --git a/man2/getgroups.2 b/man2/getgroups.2 new file mode 100644 index 000000000..f4f0ee13b --- /dev/null +++ b/man2/getgroups.2 @@ -0,0 +1,130 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Thu Oct 31 12:04:29 1996 by Eric S. Raymond +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH GETGROUPS 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +getgroups, setgroups \- get/set list of supplementary group IDs +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int getgroups(int " size ", gid_t " list []); +.sp +.B #include +.sp +.BI "int setgroups(size_t " size ", const gid_t *" list ); +.SH DESCRIPTION +.TP +.B getgroups +Up to +.I size +supplementary group IDs (of the calling process) are returned in +.IR list . +It is unspecified whether the effective group ID of the calling process +is included in the returned list. (Thus, an application should also call +.BR getegid (2) +and add or remove the resulting value.) +If +.I size +is zero, +.I list +is not modified, but the total number of supplementary group IDs for the +process is returned. +.TP +.B setgroups +Sets the supplementary group IDs for the process. +Appropriate privileges (Linux: the +.B CAP_SETGID +capability) are required. +.SH "RETURN VALUE" +.TP +.B getgroups +On success, the number of supplementary group IDs is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.TP +.B setgroups +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.I list +has an invalid address. +.TP +.B EINVAL +For +.BR setgroups , +.I size +is greater than +.B NGROUPS +(32 for Linux 2.0.32). +For +.BR getgroups , +.I size +is less than the number of supplementary group IDs, but is not zero. +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR setgroups . +.SH NOTES +A process can have up to at least NGROUPS_MAX supplementary group IDs +in addition to the effective group ID. The set of supplementary group IDs +is inherited from the parent process and may be changed using +.BR setgroups . +The maximum number of supplementary group IDs can be found using +.BR sysconf (3): +.nf + long ngroups_max; + ngroups_max = sysconf(_SC_NGROUPS_MAX); +.fi +The maximal return value of +.B getgroups +cannot be larger than one more than the value obtained this way. +.LP +The prototype for +.B setgroups +is only available if +.B _BSD_SOURCE +is defined (either explicitly, or implicitly, by not defining +_POSIX_SOURCE or compiling with the -ansi flag). +.SH "CONFORMING TO" +SVr4, SVID (issue 4 only; these calls were not present in SVr3), +X/OPEN, 4.3BSD. The +.B getgroups +function is in POSIX.1. Since +.B setgroups +requires privilege, it is not covered by POSIX.1. +.SH "SEE ALSO" +.BR getgid (2), +.BR setgid (2), +.BR initgroups (3), +.BR capabilities (7) diff --git a/man2/gethostid.2 b/man2/gethostid.2 new file mode 100644 index 000000000..83e2b62db --- /dev/null +++ b/man2/gethostid.2 @@ -0,0 +1,69 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Updated with additions from Mitchum DSouza +.\" Portions Copyright 1993 Mitchum DSouza +.\" +.\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond +.TH GETHOSTID 2 1993-11-29 "Linux 0.99.13" "Linux Programmer's Manual" +.SH NAME +gethostid, sethostid \- get or set the unique identifier of the current host +.SH SYNOPSIS +.B #include +.sp +.B long gethostid(void); +.br +.BI "int sethostid(long " hostid ); +.SH DESCRIPTION +Get or set a unique 32-bit identifier for the current machine. The 32-bit +identifier is intended to be unique among all UNIX systems in +existence. This normally resembles the Internet address for the local +machine, as returned by +.BR gethostbyname (3), +and thus usually never needs to be set. + +The +.B sethostid +call is restricted to the superuser. + +The +.I hostid +argument is stored in the file +.IR /etc/hostid . +.SH "RETURN VALUE" +.B gethostid +returns the 32-bit identifier for the current host as set by +.BR sethostid (2). +.SH "CONFORMING TO" +4.2BSD. These functions were dropped in 4.4BSD. +POSIX.1 does not define these functions, but ISO/IEC 9945-1:1990 mentions +them in B.4.4.1. SVr4 includes +.B gethostid +but not +.BR sethostid . +.SH FILES +.I /etc/hostid +.SH "SEE ALSO" +.BR hostid (1), +.BR gethostbyname (3) diff --git a/man2/gethostname.2 b/man2/gethostname.2 new file mode 100644 index 000000000..789bd586c --- /dev/null +++ b/man2/gethostname.2 @@ -0,0 +1,97 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1995-07-22 by Michael Chastain : +.\" 'gethostname' is real system call on Linux/Alpha. +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2000-06-04, 2001-12-15 by aeb +.\" Modified 2004-06-17 by mtk +.\" +.TH GETHOSTNAME 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +gethostname, sethostname \- get/set host name +.SH SYNOPSIS +.B #include +.sp +.BI "int gethostname(char *" name ", size_t " len ); +.br +.BI "int sethostname(const char *" name ", size_t " len ); +.SH DESCRIPTION +These functions are used to access or to change the host name of the +current processor. +The +.B gethostname() +function returns a NUL-terminated hostname (set earlier by +.BR sethostname() ) +in the array \fIname\fP that has a length of \fIlen\fP bytes. +In case the NUL-terminated hostname does not fit, no error is +returned, but the hostname is truncated. It is unspecified +whether the truncated hostname will be NUL-terminated. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.I name +is an invalid address. +.TP +.B EINVAL +.I len +is negative or, for +.BR sethostname , +.I len +is larger than the maximum allowed size, +or, for +.BR gethostname +on Linux/i386, +.I len +is smaller than the actual size. +(In this last case glibc 2.1 uses ENAMETOOLONG.) +.TP +.B EPERM +For +.BR sethostname , +the caller did not have the +.B CAP_SYS_ADMIN +capability. +.SH "CONFORMING TO" +SVr4, 4.4BSD (this function first appeared in 4.2BSD). +POSIX 1003.1-2001 specifies +.B gethostname +but not +.BR sethostname . +.SH BUGS +For many Linux kernel / libc combinations +.B gethostname +will return an error instead of returning a truncated hostname. +.SH NOTES +SUSv2 guarantees that `Host names are limited to 255 bytes'. +POSIX 1003.1-2001 guarantees that `Host names (not including +the terminating NUL) are limited to HOST_NAME_MAX bytes'. +.SH "SEE ALSO" +.BR getdomainname (2), +.BR setdomainname (2), +.BR uname (2) diff --git a/man2/getitimer.2 b/man2/getitimer.2 new file mode 100644 index 000000000..530a14605 --- /dev/null +++ b/man2/getitimer.2 @@ -0,0 +1,147 @@ +.\" Copyright 7/93 by Darren Senn +.\" Based on a similar page Copyright 1992 by Rick Faith +.\" May be freely distributed +.\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond +.TH GETITIMER 2 1993-08-05 "Linux 0.99.11" "Linux Programmer's Manual" +.SH NAME +getitimer, setitimer \- get or set value of an interval timer +.SH SYNOPSIS +.PD 0 +.HP +.B #include +.sp +.HP +.B int getitimer(int +.IB which , +.B struct itimerval +.BI * value ); +.HP +.B int setitimer(int +.IB which , +.B const struct itimerval +.BI * value , +.B struct itimerval +.BI * ovalue ); +.PD +.SH DESCRIPTION +The system provides each process with three interval timers, each decrementing +in a distinct time domain. When any timer expires, a signal is sent to the +process, and the timer (potentially) restarts. +.TP 1.5i +.B ITIMER_REAL +decrements in real time, and delivers +.B SIGALRM +upon expiration. +.TP +.B ITIMER_VIRTUAL +decrements only when the process is executing, and delivers +.B SIGVTALRM +upon expiration. +.TP +.B ITIMER_PROF +decrements both when the process executes and when the system is executing +on behalf of the process. Coupled with +.BR ITIMER_VIRTUAL , +this timer is usually used to profile the time spent by the application in user +and kernel space. +.B SIGPROF +is delivered upon expiration. +.LP +Timer values are defined by the following structures: +.PD 0 +.RS .5i +.nf +struct itimerval { + struct timeval it_interval; /* next value */ + struct timeval it_value; /* current value */ +}; +struct timeval { + long tv_sec; /* seconds */ + long tv_usec; /* microseconds */ +}; +.fi +.RE +.PD +.LP +The function +.B getitimer +fills the structure indicated by +.I value +with the current setting for the timer indicated by +.I which +(one of +.BR ITIMER_REAL , +.BR ITIMER_VIRTUAL , +or +.BR ITIMER_PROF ). +The element +.B it_value +is set to the amount of time remaining on the timer, or zero if the timer +is disabled. Similarly, +.B it_interval +is set to the reset value. +The function +.B setitimer +sets the indicated timer to the value in +.IR value . +If +.I ovalue +is nonzero, the old value of the timer is stored there. +.LP +Timers decrement from +.I it_value +to zero, generate a signal, and reset to +.IR it_interval . +A timer which is set to zero +.RI ( it_value +is zero or the timer expires and +.I it_interval +is zero) stops. +.LP +Both +.I tv_sec +and +.I tv_usec +are significant in determining the duration of a timer. +.LP +Timers will never expire before the requested time, +instead expiring some short, constant time afterwards, dependent +on the system timer resolution (currently 10ms). Upon expiration, a +signal will be generated and the timer reset. If the timer expires +while the process is active (always true for +.BR ITIMER_VIRT ) +the signal will be delivered immediately when generated. Otherwise the +delivery will be offset by a small time dependent on the system loading. +.LP +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.I value +or +.I ovalue +are not valid pointers. +.TP +.B EINVAL +.I which +is not one of +.BR ITIMER_REAL , +.BR ITIMER_VIRT , +or +.BR ITIMER_PROF . +.SH "CONFORMING TO" +SVr4, 4.4BSD (This call first appeared in 4.2BSD). +.SH "SEE ALSO" +.BR gettimeofday (2), +.BR sigaction (2), +.BR signal (2) +.SH BUGS +Under Linux, the generation and delivery of a signal are distinct, and +there each signal is permitted only one outstanding event. It's therefore +conceivable that under pathologically heavy loading, +.B ITIMER_REAL +will expire before the signal from a previous expiration has been delivered. +The second signal in such an event will be lost. diff --git a/man2/getpagesize.2 b/man2/getpagesize.2 new file mode 100644 index 000000000..6f68ea58a --- /dev/null +++ b/man2/getpagesize.2 @@ -0,0 +1,85 @@ +.\" Copyright (C) 2001 Andries Brouwer +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH GETPAGESIZE 2 2001-12-21 "Linux 2.5.0" "Linux Programmer's Manual" +.SH NAME +getpagesize \- get memory page size +.SH SYNOPSIS +.B #include +.sp +.B int getpagesize(void); +.SH DESCRIPTION +The function +.B getpagesize() +returns the number of bytes in a page, where a "page" is the thing +used where it says in the description of +.BR mmap (2) +that files are mapped in page-sized units. + +The size of the kind of pages that +.B mmap +uses, is found using + +.RS +.nf +#include +long sz = sysconf(_SC_PAGESIZE); +.fi +.RE + +(where some systems also allow the synonym _SC_PAGE_SIZE for _SC_PAGESIZE), +or + +.RS +.nf +#include +int sz = getpagesize(); +.fi +.RE +.SH HISTORY +This call first appeared in 4.2BSD. +.SH CONFORMING TO +SVr4, 4.4BSD, SUSv2. +In SUSv2 the +.B getpagesize() +call is labeled "legacy", and in POSIX 1003.1-2001 +it has been dropped. +HPUX does not have this call. +.SH NOTES +Whether +.B getpagesize() +is present as a Linux system call depends on the architecture. +If it is, it returns the kernel symbol PAGE_SIZE, +which is architecture and machine model dependent. +Generally, one uses binaries that are architecture but not +machine model dependent, in order to have a single binary +distribution per architecture. This means that a user program +should not find PAGE_SIZE at compile time from a header file, +but use an actual system call, at least for those architectures +(like sun4) where this dependency exists. +Here libc4, libc5, glibc 2.0 fail because their +.B getpagesize() +returns a statically derived value, and does not use a system call. +Things are OK in glibc 2.1. +.SH "SEE ALSO" +.BR mmap (2), +.BR sysconf (3) diff --git a/man2/getpeername.2 b/man2/getpeername.2 new file mode 100644 index 000000000..fc71a8459 --- /dev/null +++ b/man2/getpeername.2 @@ -0,0 +1,100 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getpeername.2 6.5 (Berkeley) 3/10/91 +.\" +.\" Modified Sat Jul 24 16:37:50 1993 by Rik Faith +.\" Modified Thu Jul 30 14:37:50 1993 by Martin Schulze +.\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer +.\" Modified 17 Jul 2002, Michael Kerrisk +.\" Added 'socket' to NAME, so that "man -k socket" will show this page. +.\" +.TH GETPEERNAME 2 1993-07-30 "BSD Man Page" "Linux Programmer's Manual" +.SH NAME +getpeername \- get name of connected peer socket +.SH SYNOPSIS +.B #include +.sp +.BI "int getpeername(int " s ", struct sockaddr *" name ", socklen_t *" namelen ); +.SH DESCRIPTION +.B Getpeername +returns the name of the peer connected to socket +.IR s . +The +.I namelen +parameter should be initialized to indicate the amount of space pointed to +by +.IR name . +On return it contains the actual size of the name returned (in bytes). The +name is truncated if the buffer provided is too small. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +The argument +.I s +is not a valid descriptor. +.TP +.B EFAULT +The +.I name +parameter points to memory not in a valid part of the +process address space. +.TP +.B ENOBUFS +Insufficient resources were available in the system +to perform the operation. +.TP +.B ENOTCONN +The socket is not connected. +.TP +.B ENOTSOCK +The argument +.I s +is a file, not a socket. +.SH "CONFORMING TO" +SVr4, 4.4BSD (the +.B getpeername +function call first appeared in 4.2BSD). +.SH NOTE +The third argument of +.B getpeername +is in reality an `int *' (and this is what BSD 4.* and libc4 and libc5 have). +Some POSIX confusion resulted in the present socklen_t, also used by glibc. +See also +.BR accept (2). +.SH "SEE ALSO" +.BR accept (2), +.BR bind (2), +.BR getsockname (2) diff --git a/man2/getpgid.2 b/man2/getpgid.2 new file mode 100644 index 000000000..d6b107a1c --- /dev/null +++ b/man2/getpgid.2 @@ -0,0 +1 @@ +.so man2/setpgid.2 diff --git a/man2/getpgrp.2 b/man2/getpgrp.2 new file mode 100644 index 000000000..d6b107a1c --- /dev/null +++ b/man2/getpgrp.2 @@ -0,0 +1 @@ +.so man2/setpgid.2 diff --git a/man2/getpid.2 b/man2/getpid.2 new file mode 100644 index 000000000..b5e500ab2 --- /dev/null +++ b/man2/getpid.2 @@ -0,0 +1,50 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.TH GETPID 2 1993-07-23 "Linux 0.99.11" "Linux Programmer's Manual" +.SH NAME +getpid, getppid \- get process identification +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.B pid_t getpid(void); +.br +.B pid_t getppid(void); +.SH DESCRIPTION +.B getpid +returns the process ID of the current process. (This is often used by +routines that generate unique temporary file names.) + +.B getppid +returns the process ID of the parent of the current process. +.SH "CONFORMING TO" +POSIX, BSD 4.3, SVID +.SH "SEE ALSO" +.BR fork (2), +.BR kill (2), +.BR exec (3), +.BR mkstemp (3), +.BR tempnam (3), +.BR tmpfile (3), +.BR tmpnam (3) diff --git a/man2/getpmsg.2 b/man2/getpmsg.2 new file mode 100644 index 000000000..5d25ea6ce --- /dev/null +++ b/man2/getpmsg.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/getppid.2 b/man2/getppid.2 new file mode 100644 index 000000000..fca885ee4 --- /dev/null +++ b/man2/getppid.2 @@ -0,0 +1 @@ +.so man2/getpid.2 diff --git a/man2/getpriority.2 b/man2/getpriority.2 new file mode 100644 index 000000000..3a077c60c --- /dev/null +++ b/man2/getpriority.2 @@ -0,0 +1,177 @@ +.\" Copyright (c) 1980, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getpriority.2 6.9 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-07-01 by Andries Brouwer +.\" Modified 1996-11-06 by Eric S. Raymond +.\" Modified 2001-10-21 by Michael Kerrisk +.\" Corrected statement under EPERM to clarify privileges required +.\" Modified 2002-06-21 by Michael Kerrisk +.\" Clarified meaning of 0 value for 'who' argument +.\" Modified 2004-05-27 by Michael Kerrisk +.\" +.TH GETPRIORITY 2 2002-06-21 "BSD Man Page" "Linux Programmer's Manual" +.SH NAME +getpriority, setpriority \- get/set program scheduling priority +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int getpriority(int " which ", int " who ); +.br +.BI "int setpriority(int " which ", int " who ", int " prio ); +.SH DESCRIPTION +The scheduling priority of the process, process group, or user, as +indicated by +.I which +and +.I who +is obtained with the +.B getpriority +call and set with the +.B setpriority +call. + +The value +.I which +is one of +.BR PRIO_PROCESS , +.BR PRIO_PGRP , +or +.BR PRIO_USER , +and +.I who +is interpreted relative to +.I which +(a process identifier for +.BR PRIO_PROCESS , +process group +identifier for +.BR PRIO_PGRP , +and a user ID for +.BR PRIO_USER ). +A zero value for +.I who +denotes (respectively) the calling process, the process group of the +calling process, or the real user ID of the calling process. +.I Prio +is a value in the range \-20 to 20 (but see the Notes below). +The default priority is 0; +lower priorities cause more favorable scheduling. + +The +.B getpriority +call returns the highest priority (lowest numerical value) +enjoyed by any of the specified processes. The +.B setpriority +call sets the priorities of all of the specified processes +to the specified value. Only the super-user may lower priorities. +.SH "RETURN VALUE" +Since +.B getpriority +can legitimately return the value \-1, it is necessary +to clear the external variable +.I errno +prior to the +call, then check it afterwards to determine +if a \-1 is an error or a legitimate value. +The +.B setpriority +call returns 0 if there is no error, or +\-1 if there is. +.SH ERRORS +.TP +.B EINVAL +.I which +was not one of +.BR PRIO_PROCESS , +.BR PRIO_PGRP , +or +.BR PRIO_USER . +.TP +.B ESRCH +No process was located using the +.I which +and +.I who +values specified. +.PP +In addition to the errors indicated above, +.B setpriority +may fail if: +.TP +.B EPERM +A process was located, but its effective user ID did not match +either the effective or the real user ID of the caller, +and (on Linux systems) the caller did not have the +.B CAP_SYS_NICE +capability. +.TP +.B EACCES +A non super-user attempted to lower a process priority. +.SH NOTES +The details on the condition for EPERM depend on the system. +The above description is what SUSv3 says, and seems to be followed on +all SYSV-like systems. +Linux requires the real or effective user ID of the caller to match +the real user of the process \fIwho\fP (instead of its effective user ID). +All BSD-like systems (SunOS 4.1.3, Ultrix 4.2, +BSD 4.3, FreeBSD 4.3, OpenBSD-2.5, ...) require +the effective user ID of the caller to match +the real or effective user ID of the process \fIwho\fP. +.LP +The actual priority range varies between kernel versions. +Linux before 1.3.36 had -infinity..15. Linux since 1.3.43 has -20..19, +and the system call getpriority returns 40..1 for these values +(since negative numbers are error codes). +The library call converts N into 20-N. +.LP +Including +.I +is not required these days, but increases portability. +(Indeed, +.I +defines the +.I rusage +structure with fields of type +.I struct timeval +defined in +.IR .) +.SH "CONFORMING TO" +SVr4, 4.4BSD (these function calls first appeared in 4.2BSD). +.SH "SEE ALSO" +.BR nice (1), +.BR fork (2), +.BR capabilities (7), +.BR renice (8) diff --git a/man2/getresgid.2 b/man2/getresgid.2 new file mode 100644 index 000000000..ac4fb7cb8 --- /dev/null +++ b/man2/getresgid.2 @@ -0,0 +1 @@ +.so man2/getresuid.2 diff --git a/man2/getresuid.2 b/man2/getresuid.2 new file mode 100644 index 000000000..937931a63 --- /dev/null +++ b/man2/getresuid.2 @@ -0,0 +1,62 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified, 2003-05-26, Michael Kerrisk, +.TH GETRESUID 2 2003-05-26 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +getresuid, getresgid \- get real, effective and saved user or group ID +.SH SYNOPSIS +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "int getresuid(uid_t *" ruid ", uid_t *" euid ", uid_t *" suid ); +.br +.BI "int getresgid(gid_t *" rgid ", gid_t *" egid ", gid_t *" sgid ); +.SH DESCRIPTION +.B getresuid +and +.B getresgid +(both introduced in Linux 2.1.44) +get the real, effective and saved user ID's (resp. group ID's) +of the current process. + +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +One of the arguments specified an address outside the calling program's +address space. +.SH "CONFORMING TO" +This call is Linux-specific. +The prototype is given by glibc since version 2.3.2 +provided _GNU_SOURCE is defined. +.SH "SEE ALSO" +.BR getuid (2), +.BR setresuid (2), +.BR setreuid (2), +.BR setuid (2) diff --git a/man2/getrlimit.2 b/man2/getrlimit.2 new file mode 100644 index 000000000..34fa7ab9d --- /dev/null +++ b/man2/getrlimit.2 @@ -0,0 +1,319 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt, March 28, 1992 +.\" Copyright (c) 2002 Michael Kerrisk +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1996-01-13 by Arnt Gulbrandsen +.\" Modified 1996-01-22 by aeb, following a remark by +.\" Tigran Aivazian +.\" Modified 1996-04-14 by aeb, following a remark by +.\" Robert Bihlmeyer +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 2001-05-04 by aeb, following a remark by +.\" Håvard Lygre +.\" Modified 2001-04-17 by Michael Kerrisk +.\" Modified 2002-06-13 by Michael Kerrisk +.\" Added note on non-standard behaviour when SIGCHLD is ignored. +.\" Modified 2002-07-09 by Michael Kerrisk +.\" Enhanced descriptions of 'resource' values for [gs]etrlimit() +.\" Modified 2003-11-28 by aeb, added RLIMIT_CORE +.\" Modified 2004-03-26 by aeb, added RLIMIT_AS +.\" Modified 2004-06-16 by Michael Kerrisk +.\" Added notes on CAP_SYS_RESOURCE +.\" +.TH GETRLIMIT 2 2004-06-16 "Linux" "Linux Programmer's Manual" +.SH NAME +getrlimit, getrusage, setrlimit \- get/set resource limits and usage +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.sp +.BI "int getrlimit(int " resource ", struct rlimit *" rlim ); +.br +.BI "int getrusage(int " who ", struct rusage *" usage ); +.br +.BI "int setrlimit(int " resource ", const struct rlimit *" rlim ); +.SH DESCRIPTION +.B getrlimit +and +.B setrlimit +get and set resource limits respectively. +Each resource has an associated soft and hard limit, as defined by the +.B rlimit +structure (the +.I rlim +argument to both +.BR getrlimit "() and " setrlimit ()): +.PP +.in +0.5i +.nf +struct rlimit { + rlim_t rlim_cur; /* Soft limit */ + rlim_t rlim_max; /* Hard limit (ceiling + for rlim_cur) */ +}; + +.fi +.in -0.5i +The soft limit is the value that the kernel enforces for the +corresponding resource. +The hard limit acts as a ceiling for the soft limit: +an unprivileged process may only set its soft limit to a value in the +range from 0 up to the hard limit, and (irreversibly) lower its hard limit. +A privileged process (under Linux: one with the +.B CAP_SYS_RESOURCE +capability) may make arbitrary changes to either limit value. +.PP +The value +.B RLIM_INFINITY +denotes no limit on a resource (both in the structure returned by +.BR getrlimit () +and in the structure passed to +.BR setrlimit ()). +.PP +.I resource +must be one of: +.TP +.B RLIMIT_AS +The maximum size of the process's virtual memory (address space) in bytes. +.\" since 2.0.27 / 2.1.12 +This limit affects calls to +.BR brk (2), +.BR mmap (2) +and +.BR mremap (2), +which fail with the error +.B ENOMEM +upon exceeding this limit. Also automatic stack expansion will fail +(and generate a SIGSEGV that kills the process when no alternate stack +has been made available). +Since the value is a long, on machines with a 32-bit long +either this limit is at most 2 GiB, or this resource is unlimited. +.TP +.B RLIMIT_CORE +Maximum size of +.I core +file. When 0 no core dump files are created. +When nonzero, larger dumps are truncated to this size. +.TP +.B RLIMIT_CPU +CPU time limit in seconds. +When the process reaches the soft limit, it is sent a +.B SIGXCPU +signal. +The default action for this signal is to terminate the process. +However, the signal can be caught, and the handler can return control to +the main program. +If the process continues to consume CPU time, it will be sent +.B SIGXCPU +once per second until the hard limit is reached, at which time +it is sent +.BR SIGKILL . +(This latter point describes Linux 2.2 and 2.4 behaviour. +Implementations vary in how they treat processes which continue to +consume CPU time after reaching the soft limit. +Portable applications that need to catch this signal should +perform an orderly termination upon first receipt of +.BR SIGXCPU .) +.TP +.B RLIMIT_DATA +The maximum size of the process's data segment (initialized data, +uninitialized data, and heap). +This limit affects calls to +.BR brk "() and " sbrk (), +which fail with the error +.B ENOMEM +upon encountering the soft limit of this resource. +.TP +.B RLIMIT_FSIZE +The maximum size of files that the process may create. +Attempts to extend a file beyond this limit result in delivery of a +.B SIGXFSZ +signal. +By default, this signal terminates a process, but a process can +catch this signal instead, in which case the relevant system call (e.g., +.BR write "(), " truncate ()) +fails with the error +.BR EFBIG . +.TP +.B RLIMIT_LOCKS +A limit on the combined number of +.BR flock () +locks and +.BR fcntl() +leases that this process may establish. +(Early Linux 2.4 only.) +.\" to be precise: Linux 2.4.0-test9; no longer in 2.4.25 / 2.5.65 +.TP +.B RLIMIT_MEMLOCK +The maximum number of bytes of virtual memory that may be locked +into RAM using +.BR mlock "() and " mlockall (). +.TP +.B RLIMIT_NOFILE +Specifies a value one greater than the maximum file descriptor number +that can be opened by this process. +Attempts +.RB ( open "(), " pipe "(), " dup "(), etc.)" +to exceed this limit yield the error +.BR EMFILE . +.TP +.B RLIMIT_NPROC +The maximum number of processes that can be created for the real user +ID of the calling process. +Upon encountering this limit, +.BR fork () +fails with the error +.BR EAGAIN . +.TP +.B RLIMIT_RSS +Specifies the limit (in pages) of the process's resident set +(the number of virtual pages resident in RAM). +This limit only has effect in Linux 2.4 onwatrds, and there only +affects calls to +.BR madvise () +specifying +.BR MADVISE_WILLNEED . +.TP +.B RLIMIT_STACK +The maximum size of the process stack, in bytes. +Upon reaching this limit, a +.B SIGSEGV +signal is generated. +To handle this signal, a process must employ an alternate signal stack +.RB ( sigaltstack (2)). +.PP +.B RLIMIT_OFILE +is the BSD name for +.BR RLIMIT_NOFILE . +.PP +.B getrusage +returns the current resource usages, for a \fIwho\fP +of either +.B RUSAGE_SELF +or +.BR RUSAGE_CHILDREN . +The former asks for resources used by the current process, +the latter for resources used by those of its children +that have terminated and have been waited for. +.PP +.in +0.5i +.nf +struct rusage { + struct timeval ru_utime; /* user time used */ + struct timeval ru_stime; /* system time used */ + long ru_maxrss; /* maximum resident set size */ + long ru_ixrss; /* integral shared memory size */ + long ru_idrss; /* integral unshared data size */ + long ru_isrss; /* integral unshared stack size */ + long ru_minflt; /* page reclaims */ + long ru_majflt; /* page faults */ + long ru_nswap; /* swaps */ + long ru_inblock; /* block input operations */ + long ru_oublock; /* block output operations */ + long ru_msgsnd; /* messages sent */ + long ru_msgrcv; /* messages received */ + long ru_nsignals; /* signals received */ + long ru_nvcsw; /* voluntary context switches */ + long ru_nivcsw; /* involuntary context switches */ +}; +.fi +.in -0.5i +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.I rlim +or +.I usage +points outside the accessible address space. +.TP +.B EINVAL +.BR getrlimit " or " setrlimit +is called with a bad \fIresource\fP, or \fBgetrusage\fP is called with a +bad \fIwho\fP. +.TP +.B EPERM +An unprivileged process tried to use \fBsetrlimit()\fP to +increase a soft or hard limit above the current hard limit; the +.B CAP_SYS_RESOURCE +capability is required to do this. +Or, the process tried to use \fBsetrlimit()\fP to increase +the soft or hard RLIMIT_NOFILE limit above the current kernel +maximum (NR_OPEN). +.SH "CONFORMING TO" +SVr4, BSD 4.3 +.SH NOTE +Including +.I +is not required these days, but increases portability. +(Indeed, +.I struct timeval +is defined in +.IR .) +.PP +On Linux, if the disposition of +.B SIGCHLD +is set to +.B SIG_IGN +then the resource usages of child processes +are automatically included in the value returned by +.BR RUSAGE_CHILDREN , +although POSIX 1003.1-2001 explicitly prohibits this. +.\" See the description of getrusage() in XSH. +.\" A similar statement was also in SUSv2. +.LP +The above struct was taken from BSD 4.3 Reno. +Not all fields are meaningful under Linux. +Right now (Linux 2.4, 2.6) only the fields +.BR ru_utime , +.BR ru_stime , +.BR ru_minflt , +.BR ru_majflt , +and +.BR ru_nswap +are maintained. +.SH "SEE ALSO" +.BR dup (2), +.BR fcntl (2), +.BR fork (2), +.BR mlock (2), +.BR mlockall (2), +.BR mmap (2), +.BR open (2), +.BR quotactl (2), +.BR sbrk (2), +.BR wait3 (2), +.BR wait4 (2), +.BR malloc (3), +.BR ulimit (3), +.BR capabilities (7), +.BR signal (7) diff --git a/man2/getrusage.2 b/man2/getrusage.2 new file mode 100644 index 000000000..df6d7362a --- /dev/null +++ b/man2/getrusage.2 @@ -0,0 +1 @@ +.so man2/getrlimit.2 diff --git a/man2/getsid.2 b/man2/getsid.2 new file mode 100644 index 000000000..3c61e57b0 --- /dev/null +++ b/man2/getsid.2 @@ -0,0 +1,68 @@ +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Thu Oct 31 14:18:40 1996 by Eric S. Raymond +.\" Modified 2001-12-17, aeb +.TH GETSID 2 2001-12-17 "Linux 2.5.0" "Linux Programmer's Manual" +.SH NAME +getsid \- get session ID +.SH SYNOPSIS +.B #include +.sp +.BI "pid_t getsid(pid_t" " pid" ); +.SH DESCRIPTION +.B getsid(0) +returns the session ID of the calling process. +.BI getsid( p ) +returns the session ID of the process with process ID +.IR p . +(The session ID of a process is the process group ID of the +session leader.) +On error, (pid_t) \-1 will be returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EPERM +A process with process ID +.I p +exists, but it is not in the same session as the current process, +and the implementation considers this an error. +.TP +.B ESRCH +No process with process ID +.I p +was found. +.SH "CONFORMING TO" +SVr4, POSIX 1003.1-2001. +.SH NOTES +Linux does not return EPERM. +.LP +Linux has this system call since Linux 1.3.44. +There is libc support since libc 5.2.19. +.LP +To get the prototype under glibc, define both _XOPEN_SOURCE and +_XOPEN_SOURCE_EXTENDED, or use "#define _XOPEN_SOURCE \fIn\fP" +for some integer \fIn\fP larger than or equal to 500. +.SH "SEE ALSO" +.BR getpgid (2), +.BR setsid (2) diff --git a/man2/getsockname.2 b/man2/getsockname.2 new file mode 100644 index 000000000..969c646e6 --- /dev/null +++ b/man2/getsockname.2 @@ -0,0 +1,97 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getsockname.2 6.4 (Berkeley) 3/10/91 +.\" +.\" Modified Sat Jul 24 16:30:29 1993 by Rik Faith +.\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond +.\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer +.\" +.TH GETSOCKNAME 2 1993-07-24 "BSD Man Page" "Linux Programmer's Manual" +.SH NAME +getsockname \- get socket name +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int getsockname(int " s ", struct sockaddr *" name ", socklen_t *" namelen ); +.fi +.SH DESCRIPTION +.B Getsockname +returns the current +.I name +for the specified socket. The +.I namelen +parameter should be initialized to indicate +the amount of space pointed to by +.IR name . +On return it contains the actual size of the name +returned (in bytes). +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +The argument +.I s +is not a valid descriptor. +.TP +.B EFAULT +The +.I name +parameter points to memory not in a valid part of the +process address space. +.TP +.B ENOBUFS +Insufficient resources were available in the system +to perform the operation. +.TP +.B ENOTSOCK +The argument +.I s +is a file, not a socket. +.SH "CONFORMING TO" +SVr4, 4.4BSD (the +.B getsockname +function call appeared in 4.2BSD). SVr4 documents additional ENOMEM +and ENOSR error codes. +.SH NOTE +The third argument of +.B getsockname +is in reality an `int *' (and this is what BSD 4.* and libc4 and libc5 have). +Some POSIX confusion resulted in the present socklen_t, also used by glibc. +See also +.BR accept (2). +.SH "SEE ALSO" +.BR bind (2), +.BR socket (2) diff --git a/man2/getsockopt.2 b/man2/getsockopt.2 new file mode 100644 index 000000000..f673fa7d0 --- /dev/null +++ b/man2/getsockopt.2 @@ -0,0 +1,181 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Id: getsockopt.2,v 1.1 1999/05/24 14:57:04 freitag Exp $ +.\" +.\" Modified Sat Jul 24 16:19:32 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Apr 22 02:29:06 1996 by Martin Schulze (joey@infodrom.north.de) +.\" Modified Tue Aug 27 10:52:51 1996 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Thu Jan 23 13:29:34 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 1999 by Andi Kleen . Removed most stuff because it is in socket.7 +.\" now. +.\" +.TH GETSOCKOPT 2 1999-05-24 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +getsockopt, setsockopt \- get and set options on sockets +.SH SYNOPSIS +.B #include +.br +.B #include +.sp 2 +.BI "int getsockopt(int " s ", int " level ", int " optname , +.BI "void *" optval ", socklen_t *" optlen ); +.sp +.BI "int setsockopt(int " s ", int " level ", int " optname , +.BI "const void *" optval ", socklen_t " optlen ); +.SH DESCRIPTION +.B Getsockopt +and +.B setsockopt +manipulate the +.I options +associated with a socket. Options may exist at multiple +protocol levels; they are always present at the uppermost +.B socket +level. + +When manipulating socket options the level at which the +option resides and the name of the option must be specified. +To manipulate options at the socket level, +.I level +is specified as +.BR SOL_SOCKET . +To manipulate options at any +other level the protocol number of the appropriate protocol +controlling the option is supplied. For example, +to indicate that an option is to be interpreted by the +.B TCP +protocol, +.I level +should be set to the protocol number of +.BR TCP ; +see +.BR getprotoent (3). + +The parameters +.I optval +and +.I optlen +are used to access option values for +.BR setsockopt . +For +.B getsockopt +they identify a buffer in which the value for the +requested option(s) are to be returned. For +.BR getsockopt , +.I optlen +is a value-result parameter, initially containing the +size of the buffer pointed to by +.IR optval , +and modified on return to indicate the actual size of +the value returned. If no option value is +to be supplied or returned, +.I optval +may be NULL. + +.I Optname +and any specified options are passed uninterpreted to the appropriate +protocol module for interpretation. The include file +.I +contains definitions for socket level options, described below. Options at +other protocol levels vary in format and name; consult the appropriate +entries in section 4 of the manual. + +Most socket-level options utilize an +.I int +parameter for +.IR optval . +For +.BR setsockopt , +the parameter should be non-zero to enable a boolean option, or zero if the +option is to be disabled. + +.PP +For a description of the available socket options see +.BR socket (7) +and the appropriate protocol man pages. + +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP 10 +.B EBADF +The argument +.I s +is not a valid descriptor. +.TP +.B EFAULT +The address pointed to by +.I optval +is not in a valid part of the process address space. For +.BR getsockopt , +this error may also be returned if +.I optlen +is not in a valid part of the process address space. +.TP +.B EINVAL +.I optlen +invalid in setsockopt +.TP +.B ENOPROTOOPT +The option is unknown at the level indicated. +.TP +.B ENOTSOCK +The argument +.I s +is a file, not a socket. +.SH "CONFORMING TO" +SVr4, 4.4BSD (these system calls first appeared in 4.2BSD). +SVr4 documents additional ENOMEM and ENOSR error codes, but does +not document the +.BR SO_SNDLOWAT ", " SO_RCVLOWAT ", " SO_SNDTIMEO ", " SO_RCVTIMEO +options +.SH NOTE +The fifth argument of +.BR getsockopt " and " setsockopt +is in reality an int [*] (and this is what BSD 4.* and libc4 and libc5 have). +Some POSIX confusion resulted in the present socklen_t, also used by glibc. +See also +.BR accept (2). +.SH BUGS +Several of the socket options should be handled at lower levels of the +system. +.SH "SEE ALSO" +.BR ioctl (2), +.BR socket (2), +.BR getprotoent (3), +.BR protocols (5), +.BR socket (7), +.BR tcp (7), +.BR unix (7) diff --git a/man2/gettid.2 b/man2/gettid.2 new file mode 100644 index 000000000..44e197e71 --- /dev/null +++ b/man2/gettid.2 @@ -0,0 +1,54 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 2003 Abhijit Menon-Sen +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH GETTID 2 "2003-02-01" "Linux 2.4.20" "Linux Programmer's Manual" +.SH NAME +gettid \- get thread identification +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.B _syscall0(pid_t,gettid) +.sp +.B pid_t gettid(void); +.SH DESCRIPTION +\fBgettid\fP returns the thread ID of the current process. This is equal +to the process ID (as returned by +.BR getpid (2)), +unless the process is part of a thread group (created by specifying +the CLONE_THREAD flag to the +.BR clone (2) +system call). All processes in the same thread group +have the same PID, but each one has a unique TID. +.SH "RETURN VALUE" +On success, returns the thread ID of the current process. +.SH ERRORS +This call is always successful. +.SH "CONFORMING TO" +\fBgettid\fP is Linux specific and should not be used in programs that +are intended to be portable. +.SH "SEE ALSO" +.BR clone (2), +.BR fork (2), +.BR getpid (2) diff --git a/man2/gettimeofday.2 b/man2/gettimeofday.2 new file mode 100644 index 000000000..eafd7df55 --- /dev/null +++ b/man2/gettimeofday.2 @@ -0,0 +1,228 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt (michael@moria.de) +.\" Modified 1993-07-23 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1994-08-21 by Michael Chastain (mec@shell.portal.com): +.\" Fixed necessary '#include' lines. +.\" Modified 1995-04-15 by Michael Chastain (mec@shell.portal.com): +.\" Added reference to adjtimex. +.\" Removed some nonsense lines pointed out by Urs Thuermann, +.\" (urs@isnogud.escape.de), aeb, 950722. +.\" Modified 1997-01-14 by Austin Donnelly (and1000@debian.org): +.\" Added return values section, and bit on EFAULT +.\" Added clarification on timezone, aeb, 971210. +.\" Removed "#include ", aeb, 010316. +.\" Modified, 2004-05-27 by Michael Kerrisk +.\" Added notes on capability requirement. +.\" +.TH GETTIMEOFDAY 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +gettimeofday, settimeofday \- get / set time +.SH SYNOPSIS +.B #include +.sp +.BI "int gettimeofday(struct timeval *" tv ", struct timezone *" tz ); +.br +.BI "int settimeofday(const struct timeval *" tv +.BI ", const struct timezone *" tz ); +.SH DESCRIPTION +The functions +.B gettimeofday +and +.B settimeofday +can get and set the time as well as a timezone. +The +.I tv +argument is a +.B timeval +struct, as specified in : +.sp +.nf +struct timeval { +.in +8 +time_t tv_sec; /* seconds */ +suseconds_t tv_usec; /* microseconds */ +.in -8 +}; +.fi +.sp +and gives the number of seconds and microseconds since the Epoch (see +.BR time (2)). +The +.I tz +argument is a +.B timezone +: +.sp +.nf +struct timezone { +.in +8 +int tz_minuteswest; /* minutes W of Greenwich */ +int tz_dsttime; /* type of dst correction */ +.in -8 +}; +.fi +.PP +The use of the timezone struct is obsolete; the +.I tz_dsttime +field has never been used under Linux - it has not +been and will not be supported by libc or glibc. +Each and every occurrence of this field in the kernel source +(other than the declaration) is a bug. Thus, the following +is purely of historic interest. + +The field +.I tz_dsttime +contains a symbolic constant (values are given below) +that indicates in which part of the year Daylight Saving Time +is in force. (Note: its value is constant throughout the year - +it does not indicate that DST is in force, it just selects an +algorithm.) +The daylight saving time algorithms defined are as follows : +.PP +.ta 14 +\fB DST_NONE\fP /* not on dst */ +.br +\fB DST_USA\fP /* USA style dst */ +.br +\fB DST_AUST\fP /* Australian style dst */ +.br +\fB DST_WET\fP /* Western European dst */ +.br +\fB DST_MET\fP /* Middle European dst */ +.br +\fB DST_EET\fP /* Eastern European dst */ +.br +\fB DST_CAN\fP /* Canada */ +.br +\fB DST_GB\fP /* Great Britain and Eire */ +.br +\fB DST_RUM\fP /* Rumania */ +.br +\fB DST_TUR\fP /* Turkey */ +.br +\fB DST_AUSTALT\fP /* Australian style with shift in 1986 */ +.PP +Of course it turned out that the period in which +Daylight Saving Time is in force cannot be given +by a simple algorithm, one per country; indeed, +this period is determined by unpredictable political +decisions. So this method of representing time zones +has been abandoned. Under Linux, in a call to +.B settimeofday +the +.I tz_dsttime +field should be zero. +.PP +Under Linux there is some peculiar `warp clock' semantics associated +to the +.B settimeofday +system call if on the very first call (after booting) +that has a non-NULL +.I tz +argument, the +.I tv +argument is NULL and the +.I tz_minuteswest +field is nonzero. In such a case it is assumed that the CMOS clock +is on local time, and that it has to be incremented by this amount +to get UTC system time. +No doubt it is a bad idea to use this feature. +.PP +The following macros are defined to operate on a struct timeval : +.br +.nf +#define timerisset(tvp)\\ +.ti +8 +((tvp)->tv_sec || (tvp)->tv_usec) +#define timercmp(tvp, uvp, cmp)\\ +.in +8 +((tvp)->tv_sec cmp (uvp)->tv_sec ||\\ +(tvp)->tv_sec == (uvp)->tv_sec &&\\ +(tvp)->tv_usec cmp (uvp)->tv_usec) +.in -8 +#define timerclear(tvp)\\ +.ti +8 +((tvp)->tv_sec = (tvp)->tv_usec = 0) +.fi +.PP +If either +.I tv +or +.I tz +is null, the corresponding structure is not set or returned. +.PP +Only the super user may use +.BR settimeofday . +.SH "RETURN VALUE" +.B gettimeofday +and +.B settimeofday +return 0 for success, or \-1 for failure (in which case +.I errno +is set appropriately). +.SH ERRORS +.TP +.B EFAULT +One of +.I tv +or +.I tz +pointed outside the accessible address space. +.TP +.B EINVAL +Timezone (or something else) is invalid. +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR settimeofday ; +under Linux the +.B CAP_SYS_TIME +capability is required. +.SH NOTE +The prototype for +.B settimeofday +and the defines for +.BR timercmp , +.BR timerisset , +.BR timerclear , +.BR timeradd , +.BR timersub +are (since glibc2.2.2) only available if +.B _BSD_SOURCE +is defined (either explicitly, or implicitly, by not defining +_POSIX_SOURCE or compiling with the -ansi flag). +.LP +Traditionally, the fields of struct timeval were longs. +.SH "CONFORMING TO" +SVr4, BSD 4.3. POSIX 1003.1-2001 describes gettimeofday() +but not settimeofday(). +.SH "SEE ALSO" +.BR date (1), +.BR adjtimex (2), +.BR time (2), +.BR ctime (3), +.BR ftime (3), +.BR capabilities (7) diff --git a/man2/getuid.2 b/man2/getuid.2 new file mode 100644 index 000000000..78e9641bd --- /dev/null +++ b/man2/getuid.2 @@ -0,0 +1,55 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Historical remark, aeb, 2004-06-05 +.TH GETUID 2 1993-07-23 "Linux 0.99.11" "Linux Programmer's Manual" +.SH NAME +getuid, geteuid \- get user identity +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.B uid_t getuid(void); +.br +.B uid_t geteuid(void); +.SH DESCRIPTION +.B getuid +returns the real user ID of the current process. + +.B geteuid +returns the effective user ID of the current process. + +The real ID corresponds to the ID of the calling process. The effective ID +corresponds to the set ID bit on the file being executed. +.SH ERRORS +These functions are always successful. +.SH "CONFORMING TO" +POSIX, BSD 4.3. +.SH HISTORY +In Unix V6 the \fBgetuid()\fP call returned (euid << 8) + uid. +Unix V7 introduced separate calls \fBgetuid()\fP and \fBgeteuid()\fP. +.SH "SEE ALSO" +.BR setreuid (2), +.BR setuid (2) diff --git a/man2/getxattr.2 b/man2/getxattr.2 new file mode 100644 index 000000000..ada194b2b --- /dev/null +++ b/man2/getxattr.2 @@ -0,0 +1,143 @@ +.\" +.\" Extended attributes system calls manual pages +.\" +.\" (C) Andreas Gruenbacher, February 2001 +.\" (C) Silicon Graphics Inc, September 2001 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH GETXATTR 2 "Extended Attributes" "Dec 2001" "Linux Programmer's Manual" +.SH NAME +getxattr, lgetxattr, fgetxattr \- retrieve an extended attribute value +.SH SYNOPSIS +.fam C +.nf +.B #include +.B #include +.sp +.BI "ssize_t getxattr (const char\ *" path ", const char\ *" name ", +.BI "\t\t\t\t void\ *" value ", size_t " size ); +.BI "ssize_t lgetxattr (const char\ *" path ", const char\ *" name ", +.BI "\t\t\t\t void\ *" value ", size_t " size ); +.BI "ssize_t fgetxattr (int " filedes ", const char\ *" name ", +.BI "\t\t\t\t void\ *" value ", size_t " size ); +.fi +.fam T +.SH DESCRIPTION +Extended attributes are +.IR name :\c +.I value +pairs associated with inodes (files, directories, symlinks, etc). +They are extensions to the normal attributes which are associated +with all inodes in the system (i.e. the +.BR stat (2) +data). +A complete overview of extended attributes concepts can be found in +.BR attr (5). +.PP +.B getxattr +retrieves the +.I value +of the extended attribute identified by +.I name +and associated with the given +.I path +in the filesystem. +The length of the attribute +.I value +is returned. +.PP +.B lgetxattr +is identical to +.BR getxattr , +except in the case of a symbolic link, where the link itself is +interrogated, not the file that it refers to. +.PP +.B fgetxattr +is identical to +.BR getxattr , +only the open file pointed to by +.I filedes +(as returned by +.BR open (2)) +is interrogated in place of +.IR path . +.PP +An extended attribute +.I name +is a simple NULL-terminated string. +The name includes a namespace prefix \- there may be several, disjoint +namespaces associated with an individual inode. +The value of an extended attribute is a chunk of arbitrary textual or +binary data of specified length. +.PP +An empty buffer of +.I size +zero can be passed into these calls to return the current size of the +named extended attribute, which can be used to estimate the size of a +buffer which is sufficiently large to hold the value associated with +the extended attribute. +.PP +The interface is designed to allow guessing of initial buffer +sizes, and to enlarge buffers when the return value indicates +that the buffer provided was too small. +.SH RETURN VALUE +On success, a positive number is returned indicating the size of the +extended attribute value. +On failure, \-1 is returned and +.I errno +is set appropriately. +.PP +If the named attribute does not exist, or the process has no access to +this attribute, +.I errno +is set to ENOATTR. +.PP +If the +.I size +of the +.I value +buffer is too small to hold the result, +.I errno +is set to ERANGE. +.PP +If extended attributes are not supported by the filesystem, or are disabled, +.I errno +is set to ENOTSUP. +.PP +The errors documented for the +.BR stat (2) +system call are also applicable here. +.SH AUTHORS +Andreas Gruenbacher, +.RI < a.gruenbacher@computer.org > +and the SGI XFS development team, +.RI < linux-xfs@oss.sgi.com >. +Please send any bug reports or comments to these addresses. +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR listxattr (2), +.BR open (2), +.BR removexattr (2), +.BR setxattr (2), +.BR stat (2), +.BR attr (5) diff --git a/man2/gtty.2 b/man2/gtty.2 new file mode 100644 index 000000000..5d25ea6ce --- /dev/null +++ b/man2/gtty.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/idle.2 b/man2/idle.2 new file mode 100644 index 000000000..35d13c26c --- /dev/null +++ b/man2/idle.2 @@ -0,0 +1,63 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Portions extracted from linux/mm/swap.c: +.\" Copyright (C) 1991, 1992 Linus Torvalds +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 21 Aug 1994 by Michael Chastain : +.\" Added text about calling restriction (new in kernel 1.1.20 I believe). +.\" N.B. calling "idle" from user process used to hang process! +.\" Modified Thu Oct 31 14:41:15 1996 by Eric S. Raymond +.\" " +.TH IDLE 2 1994-08-21 "Linux 1.1.46" "Linux Programmer's Manual" +.SH NAME +idle \- make process 0 idle +.SH SYNOPSIS +.B #include +.sp +.B int idle(void); +.SH DESCRIPTION +.B idle +is an internal system call used during bootstrap. +It marks the process's pages as swappable, lowers its priority, +and enters the main scheduling loop. +.B idle +never returns. +.PP +Only process 0 may call +.BR idle . +Any user process, even a process with super-user permission, +will receive +.BR EPERM . +.SH "RETURN VALUE" +.B idle +never returns for process 0, and always returns \-1 for a user process. +.SH ERRORS +.TP +.B EPERM +Always, for a user process. +.SH "CONFORMING TO" +This function is Linux-specific, and should not be used in programs +intended to be portable. +.SH NOTES +Since 2.3.13 this system call does not exist anymore. diff --git a/man2/inb.2 b/man2/inb.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/inb.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/inb_p.2 b/man2/inb_p.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/inb_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/inl.2 b/man2/inl.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/inl.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/inl_p.2 b/man2/inl_p.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/inl_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/insb.2 b/man2/insb.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/insb.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/insl.2 b/man2/insl.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/insl.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/insw.2 b/man2/insw.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/insw.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/intro.2 b/man2/intro.2 new file mode 100644 index 000000000..3f63a709b --- /dev/null +++ b/man2/intro.2 @@ -0,0 +1,186 @@ +.\" +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Tue Jul 6 12:42:46 MDT 1993 +.\" Added "Calling Directly" and supporting paragraphs +.\" +.\" Modified Sat Jul 24 15:19:12 1993 by Rik Faith +.\" +.\" Modified 21 Aug 1994 by Michael Chastain : +.\" Added explanation of arg stacking when 6 or more args. +.\" +.\" Modified 10 June 1995 by Andries Brouwer +.\" +.TH INTRO 2 1996-05-22 "Linux 1.2.13" "Linux Programmer's Manual" +.SH NAME +intro, _syscall \- Introduction to system calls +.SH DESCRIPTION +This chapter describes the Linux system calls. +For a list of the 164 syscalls present in Linux 2.0, see syscalls(2). +.SS "Calling Directly" +In most cases, it is unnecessary to invoke a system call directly, but there +are times when the Standard C library does not implement a nice function call +for you. +.SS "Synopsis" +.B #include + +A _syscall macro + +desired system call + +.SS Setup +The important thing to know about a system call is its prototype. You +need to know how many arguments, their types, and the function return type. +There are six macros that make the actual call into the system easier. +They have the form: +.sp +.RS +.RI _syscall X ( type , name , type1 , arg1 , type2 , arg2 ,...) +.RS +.HP +where \fIX\fP is 0\(en5, which are the number of arguments taken by the +system call +.HP +\fItype\fP is the return type of the system call +.HP +\fIname\fP is the name of the system call +.HP +\fItypeN\fP is the Nth argument's type +.HP +\fIargN\fP is the name of the Nth argument +.RE +.RE +.sp +These macros create a function called \fIname\fP with the arguments you +specify. Once you include the _syscall() in your source file, +you call the system call by \fIname\fP. +.SH EXAMPLE +.nf +.sp +#include +#include +#include /* for _syscallX macros/related stuff */ +#include /* for struct sysinfo */ + +_syscall1(int, sysinfo, struct sysinfo *, info); + +/* Note: if you copy directly from the nroff source, remember to +REMOVE the extra backslashes in the printf statement. */ + +int main(void) +{ + struct sysinfo s_info; + int error; + + error = sysinfo(&s_info); + printf("code error = %d\\n", error); + printf("Uptime = %lds\\nLoad: 1 min %lu / 5 min %lu / 15 min %lu\\n" + "RAM: total %lu / free %lu / shared %lu\\n" + "Memory in buffers = %lu\\nSwap: total %lu / free %lu\\n" + "Number of processes = %d\\n", + s_info.uptime, s_info.loads[0], + s_info.loads[1], s_info.loads[2], + s_info.totalram, s_info.freeram, + s_info.sharedram, s_info.bufferram, + s_info.totalswap, s_info.freeswap, + s_info.procs); + return(0); +} +.fi +.SH "Sample Output" +.nf +code error = 0 +uptime = 502034s +Load: 1 min 13376 / 5 min 5504 / 15 min 1152 +RAM: total 15343616 / free 827392 / shared 8237056 +Memory in buffers = 5066752 +Swap: total 27881472 / free 24698880 +Number of processes = 40 +.fi +.SH NOTES +The _syscall() macros DO NOT produce a prototype. You may have to +create one, especially for C++ users. +.sp +System calls are not required to return only positive or negative error +codes. You need to read the source to be sure how it will return errors. +Usually, it is the negative of a standard error code, e.g., \-\fBEPERM\fP. +The _syscall() macros will return the result \fIr\fP of the system call +when \fIr\fP is nonnegative, but will return \-1 and set the variable +.I errno +to \-\fIr\fP when \fIr\fP is negative. +For the error codes, see +.BR errno (3). +.sp +Some system calls, such as +.BR mmap , +require more than five arguments. These are handled by pushing the +arguments on the stack and passing a pointer to the block of arguments. +.sp +When defining a system call, the argument types MUST be passed by-value +or by-pointer (for aggregates like structs). +.sp +The preferred way to invoke system calls that glibc does not know +about yet, is via +.BR syscall (2). +.SH "CONFORMING TO" +Certain codes are used to indicate Unix variants and standards to +which calls in the section conform. These are: +.TP +SVr4 +System V Release 4 Unix, as described in the "Programmer's Reference +Manual: Operating System API (Intel processors)" (Prentice-Hall +1992, ISBN 0-13-951294-2) +.TP +SVID +System V Interface Definition, as described in "The System V Interface +Definition, Fourth Edition". +.TP +POSIX.1 +IEEE 1003.1-1990 part 1, aka ISO/IEC 9945-1:1990s, aka "IEEE Portable +Operating System Interface for Computing Environments", as elucidated +in Donald Lewine's "POSIX Programmer's Guide" (O'Reilly & Associates, +Inc., 1991, ISBN 0-937175-73-0. +.TP +POSIX.1b +IEEE Std 1003.1b-1993 (POSIX.1b standard) describing real-time facilities +for portable operating systems, aka ISO/IEC 9945-1:1996, as elucidated in +"Programming for the real world \- POSIX.4" +by Bill O. Gallmeister (O'Reilly & Associates, Inc. ISBN 1-56592-074-0). +.TP +SUS, SUSv2 +Single Unix Specification. +(Developed by X/Open and The Open Group. See also +http://www.UNIX-systems.org/version2/ .) +.TP +4.3BSD/4.4BSD +The 4.3 and 4.4 distributions of Berkeley Unix. 4.4BSD was +upward-compatible from 4.3. +.TP +V7 +Version 7, the ancestral Unix from Bell Labs. +.SH FILES +.I /usr/include/linux/unistd.h +.SH "SEE ALSO" +.BR syscall (2), +.BR errno (3) diff --git a/man2/inw.2 b/man2/inw.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/inw.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/inw_p.2 b/man2/inw_p.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/inw_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/io_cancel.2 b/man2/io_cancel.2 new file mode 100644 index 000000000..4b7413a56 --- /dev/null +++ b/man2/io_cancel.2 @@ -0,0 +1,92 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" This file is distributed according to the GNU General Public License. +.\" See the file COPYING in the top level source directory for details. +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "IO_CANCEL" 2 "2003-02-21" "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +io_cancel \- Cancel an outstanding asynchronous I/O operation +.SH "SYNOPSIS" +.ad l +.hy 0 + +#include +.sp +.HP 16 +long\ \fBio_cancel\fR\ (aio_context_t\ \fIctx_id\fR, struct\ iocb\ \fI*iocb\fR, struct\ io_event\ \fI*result\fR); +.ad +.hy + +.SH "DESCRIPTION" + +.PP +\fBio_cancel\fR attempts to cancel an asynchronous I/O operation +previously submitted with the \fBio_submit\fR system call. +\fIctx_id\fR is the AIO context ID of the operation to be cancelled. +If the AIO context is found, the event will be cancelled and then copied +into the memory pointed to by \fIresult\fR without being placed +into the completion queue. + +.SH "RETURN VALUE" + +.PP +\fBio_cancel\fR returns 0 on success; otherwise, it returns one of the +errors listed in the "Errors" section. + +.SH "ERRORS" + +.TP +EINVAL +The AIO context specified by \fIctx_id\fR is invalid. + +.TP +EFAULT +One of the data structures points to invalid data. + +.TP +EAGAIN +The \fIiocb\fR specified was not cancelled. + +.TP +ENOSYS +\fBio_cancel\fR is not implemented on this architecture. + +.SH "VERSIONS" + +.PP +The asynchronous I/O system calls first appeared in Linux 2.5, August 2002. + +.SH "CONFORMING TO" + +.PP +\fBio_cancel\fR is Linux specific and should not be used in programs that are intended to be portable. + +.SH "SEE ALSO" + +.PP +\fBio_setup\fR(2), \fBio_destroy\fR(2), \fBio_getevents\fR(2), \fBio_submit\fR(2). + +.SH "NOTES" + +.PP +The asynchronous I/O system calls were written by Benjamin LaHaise. + +.SH AUTHOR +Kent Yoder. diff --git a/man2/io_destroy.2 b/man2/io_destroy.2 new file mode 100644 index 000000000..5e2a02bd5 --- /dev/null +++ b/man2/io_destroy.2 @@ -0,0 +1,86 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" This file is distributed according to the GNU General Public License. +.\" See the file COPYING in the top level source directory for details. +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "IO_DESTROY" 2 "2003-02-21" "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +io_destroy \- Destroy an asynchronous I/O context +.SH "SYNOPSIS" +.ad l +.hy 0 + +#include +.sp +.HP 17 +long\ \fBio_destroy\fR\ (aio_context_t\ \fIctx\fR); +.ad +.hy + +.SH "DESCRIPTION" + +.PP +\fBio_destroy\fR removes the asynchronous I/O context from the list of +I/O contexts and then destroys it. +\fBio_destroy\fR can also cancel any outstanding asynchronous I/O +actions on \fIctx\fR and block on completion. + +.SH "RETURN VALUE" + +.PP +\fBio_destroy\fR returns 0 on success. + +.SH "ERRORS" + +.TP +EINVAL +The AIO context specified by \fIctx\fR is invalid. + +.TP +EFAULT +The context pointed to is invalid. + +.TP +ENOSYS +\fBio_destroy\fR is not implemented on this architecture. + +.SH "CONFORMING TO" + +.PP +\fBio_destroy\fR is Linux specific and should not be used in programs +that are intended to be portable. + +.SH "VERSIONS" + +.PP +The asynchronous I/O system calls first appeared in Linux 2.5, August 2002. + +.SH "SEE ALSO" + +.PP +\fBio_setup\fR(2), \fBio_submit\fR(2), \fBio_getevents\fR(2), \fBio_cancel\fR(2). + +.SH "NOTES" + +.PP +The asynchronous I/O system calls were written by Benjamin LaHaise. + +.SH AUTHOR +Kent Yoder. diff --git a/man2/io_getevents.2 b/man2/io_getevents.2 new file mode 100644 index 000000000..ea670fd8f --- /dev/null +++ b/man2/io_getevents.2 @@ -0,0 +1,95 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" This file is distributed according to the GNU General Public License. +.\" See the file COPYING in the top level source directory for details. +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "IO_GETEVENTS" 2 "2003-02-21" "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +io_getevents \- Read asynchronous I/O events from the completion queue +.SH "SYNOPSIS" +.ad l +.hy 0 + +#include + +.sp + +#include + +.sp +.HP 19 +long\ \fBio_getevents\fR\ (aio_context_t\ \fIctx_id\fR, long\ \fImin_nr\fR, long\ \fInr\fR, struct\ io_event\ \fI*events\fR, struct\ timespec\ \fI*timeout\fR); +.ad +.hy + +.SH "DESCRIPTION" + +.PP +\fBio_getevents\fR attempts to read at least \fImin_nr\fR events and +up to \fInr\fR events from the completion queue of the AIO context +specified by \fIctx_id\fR. +\fItimeout\fR specifies the amount of time to wait for events, +where a NULL timeout waits until at least \fImin_nr\fR events have been seen. +Note that \fItimeout\fR is relative and will be updated if not NULL +and the operation blocks. + +.SH "RETURN VALUE" + +.PP +\fBio_getevents\fR returns the number of events read: 0 if no events are +available or < \fImin_nr\fR if the \fItimeout\fR has elapsed. + +.SH "ERRORS" + +.TP +EINVAL +\fIctx_id\fR is invalid. \fImin_nr\fR is out of range or \fInr\fR is +out of range. + +.TP +EFAULT +Either \fIevents\fR or \fItimeout\fR is an invalid pointer. + +.TP +ENOSYS +\fBio_getevents\fR is not implemented on this architecture. + +.SH "CONFORMING TO" + +.PP +\fBio_getevents\fR is Linux specific and should not be used in programs that are intended to be portable. + +.SH "VERSIONS" + +.PP +The asynchronous I/O system calls first appeared in Linux 2.5, August 2002. + +.SH "SEE ALSO" + +.PP +\fBio_setup\fR(2), \fBio_submit\fR(2), \fBio_getevents\fR(2), \fBio_cancel\fR(2), \fBio_destroy\fR(2). + +.SH "NOTES" + +.PP +The asynchronous I/O system calls were written by Benjamin LaHaise. + +.SH AUTHOR +Kent Yoder. diff --git a/man2/io_setup.2 b/man2/io_setup.2 new file mode 100644 index 000000000..84e38c81b --- /dev/null +++ b/man2/io_setup.2 @@ -0,0 +1,98 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" This file is distributed according to the GNU General Public License. +.\" See the file COPYING in the top level source directory for details. +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "IO_SETUP" 2 "2003-02-21" "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +io_setup \- Create an asynchronous I/O context +.SH "SYNOPSIS" +.ad l +.hy 0 + +#include +.sp +.HP 15 +long\ \fBio_setup\fR\ (unsigned\ \fInr_events\fR, aio_context_t\ \fI*ctxp\fR); +.ad +.hy + +.SH "DESCRIPTION" + +.PP +\fBio_setup\fR creates an asynchronous I/O context capable of receiving +at least \fInr_events\fR. +\fIctxp\fR must not point to an AIO context that already exists, and must +be initialized to 0 prior to the call. +On successful creation of the AIO context, \fI*ctxp\fR is filled in +with the resulting handle. + +.SH "RETURN VALUE" + +.PP +\fBio_setup\fR returns 0 on success; otherwise, one of the errors +listed in the "Errors" section is returned. + +.SH "ERRORS" + +.TP +EINVAL +\fIctxp\fR is not initialized, or the specified \fInr_events\fR +exceeds internal limits. \fInr_events\fR should be greater than 0. + +.TP +EFAULT +An invalid pointer is passed for \fIctxp\fR. + +.TP +ENOMEM +Insufficient kernel resources are available. + +.TP +EAGAIN +The specified \fInr_events\fR exceeds the user's limit of available events. + +.TP +ENOSYS +\fBio_setup\fR is not implemented on this architecture. + +.SH "CONFORMING TO" + +.PP +\fBio_setup\fR is Linux specific and should not be used in programs +that are intended to be portable. + +.SH "VERSIONS" + +.PP +The asynchronous I/O system calls first appeared in Linux 2.5, August 2002. + +.SH "SEE ALSO" + +.PP +\fBio_destroy\fR(2), \fBio_getevents\fR(2), \fBio_submit\fR(2), \fBio_cancel\fR(2). + +.SH "NOTES" + +.PP +The asynchronous I/O system calls were written by Benjamin LaHaise. + +.SH AUTHOR +Kent Yoder. diff --git a/man2/io_submit.2 b/man2/io_submit.2 new file mode 100644 index 000000000..f3e786968 --- /dev/null +++ b/man2/io_submit.2 @@ -0,0 +1,96 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" This file is distributed according to the GNU General Public License. +.\" See the file COPYING in the top level source directory for details. +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "IO_SUBMIT" 2 "2003-02-21" "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +io_submit \- Submit asynchronous I/O blocks for processing +.SH "SYNOPSIS" +.ad l +.hy 0 + +#include +.sp +.HP 16 +long\ \fBio_submit\fR\ (aio_context_t\ \fIctx_id\fR, long\ \fInr\fR, struct\ iocb\ \fI**iocbpp\fR); +.ad +.hy + +.SH "DESCRIPTION" + +.PP +\fBio_submit\fR queues \fInr\fR I/O request blocks for processing in +the AIO context \fIctx_id\fR. \fIiocbpp\fR should be an array of +\fInr\fR AIO request blocks, which will be submitted to context \fIctx_id\fR. + +.SH "RETURN VALUE" + +.PP +\fBio_submit\fR returns the number of \fIiocb\fRs submitted and +0 if \fInr\fR is zero. + +.SH "ERRORS" + +.TP +EINVAL +The \fIaio_context\fR specified by \fIctx_id\fR is invalid. +\fInr\fR is less than 0. The \fIiocb\fR at *iocbpp[0] is not properly +initialized, or the operation specified is invalid for the file descriptor +in the \fIiocb\fR. + +.TP +EFAULT +One of the data structures points to invalid data. + +.TP +EBADF +The file descriptor specified in the first \fIiocb\fR is invalid. + +.TP +EAGAIN +Insufficient resources are available to queue any \fIiocb\fRs. + +.TP +ENOSYS +\fBio_submit\fR is not implemented on this architecture. + +.SH "CONFORMING TO" + +.PP +\fBio_submit\fR is Linux specific and should not be used in programs that are intended to be portable. + +.SH "VERSIONS" + +.PP +The asynchronous I/O system calls first appeared in Linux 2.5, August 2002. + +.SH "SEE ALSO" + +.PP +\fBio_setup\fR(2), \fBio_destroy\fR(2), \fBio_getevents\fR(2), \fBio_cancel\fR(2). + +.SH "NOTES" + +.PP +The asynchronous I/O system calls were written by Benjamin LaHaise. + +.SH AUTHOR +Kent Yoder. diff --git a/man2/ioctl.2 b/man2/ioctl.2 new file mode 100644 index 000000000..d847e7094 --- /dev/null +++ b/man2/ioctl.2 @@ -0,0 +1,133 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ioctl.2 6.4 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 1999-06-25 by Rachael Munns +.\" Modified 2000-09-21 by Andries Brouwer +.\" +.TH IOCTL 2 2000-09-21 "BSD Man Page" "Linux Programmer's Manual" +.SH NAME +ioctl \- control device +.SH SYNOPSIS +.B #include +.sp +.BI "int ioctl(int " d ", int " request ", ...);" +.SH DESCRIPTION +The +.B ioctl +function manipulates the underlying device parameters of special files. In +particular, many operating characteristics of character special files +(e.g. terminals) may be controlled with +.B ioctl +requests. The argument +.I d +must be an open file descriptor. +.PP +The second argument is a device-dependent request code. The third +argument is an untyped pointer to memory. It's traditionally +.BI "char *" argp +(from the days before +.B "void *" +was valid C), and will be so named for this discussion. +.PP +An ioctl +.I request +has encoded in it whether the argument is an +.I in +parameter or +.I out +parameter, and the size of the argument +.I argp +in bytes. Macros and defines used in specifying an ioctl +.I request +are located in the file +.IR . +.SH "RETURN VALUE" +Usually, on success zero is returned. +A few ioctls use the return value as an output parameter +and return a nonnegative value on success. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP 0.7i +.B EBADF +.I d +is not a valid descriptor. +.TP +.B EFAULT +.I argp +references an inaccessible memory area. +.TP +.B EINVAL +.I Request +or +.I argp +is not valid. +.TP +.B ENOTTY +.I d +is not associated with a character special device. +.TP +.B ENOTTY +The specified request does not apply to the kind of object that the +descriptor +.I d +references. +.SH NOTE +In order to use this call, one needs an open file descriptor. +Often the +.BR open (2) +call has unwanted side effects, that can be avoided under Linux +by giving it the O_NONBLOCK flag. +.SH "CONFORMING TO" +No single standard. Arguments, returns, and semantics of +.BR ioctl (2) +vary according to the device driver in question (the call is used as a +catch-all for operations that don't cleanly fit the Unix stream I/O +model). See +.BR ioctl_list (2) +for a list of many of the known +.B ioctl +calls. The +.B ioctl +function call appeared in Version 7 AT&T Unix. +.SH "SEE ALSO" +.BR execve (2), +.BR fcntl (2), +.BR ioctl_list (2), +.BR open (2), +.BR mt (4), +.BR sd (4), +.BR tty (4) diff --git a/man2/ioctl_list.2 b/man2/ioctl_list.2 new file mode 100644 index 000000000..d2094a0da --- /dev/null +++ b/man2/ioctl_list.2 @@ -0,0 +1,672 @@ +.\" Ioctl List 1.3.27 +.\" Sun 17 Sep 1995 +.\" Michael Elizabeth Chastain +.\" +.\" +.\" // Copyright +.\" +.\" Ioctl List 1.3.27 is copyright 1995 by Michael Elizabeth Chastain. +.\" It is licensed under the Gnu Public License, Version 2. +.\" +.\" +.\" +.\" // Change Log +.\" +.\" 1.3.27 421 ioctls. +.\" Type information for non-pointer args. +.\" SIOCDEVPRIVATE, SIOCPROTOPRIVATE ioctls. +.\" Descriptions of extended arguments. +.\" +.\" 1.2.9 365 ioctls. +.\" First public version. +.\" +.\" +.TH IOCTL_LIST 2 2003-03-30 "Linux 1.3" "Linux Programmer's Manual" +.SH NAME +ioctl_list \- list of ioctl calls in Linux/i386 kernel + +.SH DESCRIPTION + +This is Ioctl List 1.3.27, a list of ioctl calls in Linux/i386 kernel +1.3.27. It contains 421 ioctls from /usr/include/{asm,linux}/*.h. +For each ioctl, its numerical value, its name, and its argument +type are given. +.PP +An argument type of 'const struct foo *' means the argument is input +to the kernel. 'struct foo *' means the kernel outputs the argument. +If the kernel uses the argument for both input and output, this is +marked with // I-O. +.PP +Some ioctls take more arguments or return more values than a single +structure. These are marked // MORE and documented further in a +separate section. +.PP +This list is very incomplete. +Please e-mail changes and comments to . + +.SH "IOCTL STRUCTURE" +.\" added two sections - aeb +Ioctl command values are 32-bit constants. +In principle these constants are completely arbitrary, but people have +tried to build some structure into them. +.LP +The old Linux situation was that of mostly 16-bit constants, where the +last byte is a serial number, and the preceding byte(s) give a type +indicating the driver. Sometimes the major number was used: 0x03 +for the HDIO_* ioctls, 0x06 for the LP* ioctls. And sometimes +one or more ASCII letters were used. For example, TCGETS has value +0x00005401, with 0x54 = 'T' indicating the terminal driver, and +CYGETTIMEOUT has value 0x00435906, with 0x43 0x59 = 'C' 'Y' +indicating the cyclades driver. +.LP +Later (0.98p5) some more information was built into the number. +One has 2 direction bits +(00: none, 01: write, 10: read, 11: read/write) +followed by 14 size bits (giving the size of the argument), +followed by an 8-bit type (collecting the ioctls in groups +for a common purpose or a common driver), and an 8-bit +serial number. +.LP +The macros describing this structure live in +and are _IO(type,nr) and {_IOR,_IOW,_IOWR}(type,nr,size). +They use sizeof(size) so that size is a +misnomer here - this third parameter is a data type. +.LP +Note that the size bits are very unreliable - in lots of cases +they are wrong - either because of buggy macros using +sizeof(sizeof(struct)), or because of legacy values. +.LP +Thus, it seems that the new structure only gave disadvantages: +it does not help in checking, but it causes varying values +for the various architectures. + +.SH "RETURN VALUE" +Decent ioctls return 0 on success and \-1 on error, while +any output value is stored via the argument. However, +quite a few ioctls in fact return an output value. +This is not yet indicated below. + +.nf + +// Main table. + +// +0x00008901 FIOSETOWN const int * +0x00008902 SIOCSPGRP const int * +0x00008903 FIOGETOWN int * +0x00008904 SIOCGPGRP int * +0x00008905 SIOCATMARK int * +0x00008906 SIOCGSTAMP timeval * + +// +0x00005401 TCGETS struct termios * +0x00005402 TCSETS const struct termios * +0x00005403 TCSETSW const struct termios * +0x00005404 TCSETSF const struct termios * +0x00005405 TCGETA struct termio * +0x00005406 TCSETA const struct termio * +0x00005407 TCSETAW const struct termio * +0x00005408 TCSETAF const struct termio * +0x00005409 TCSBRK int +0x0000540A TCXONC int +0x0000540B TCFLSH int +0x0000540C TIOCEXCL void +0x0000540D TIOCNXCL void +0x0000540E TIOCSCTTY int +0x0000540F TIOCGPGRP pid_t * +0x00005410 TIOCSPGRP const pid_t * +0x00005411 TIOCOUTQ int * +0x00005412 TIOCSTI const char * +0x00005413 TIOCGWINSZ struct winsize * +0x00005414 TIOCSWINSZ const struct winsize * +0x00005415 TIOCMGET int * +0x00005416 TIOCMBIS const int * +0x00005417 TIOCMBIC const int * +0x00005418 TIOCMSET const int * +0x00005419 TIOCGSOFTCAR int * +0x0000541A TIOCSSOFTCAR const int * +0x0000541B FIONREAD int * +0x0000541B TIOCINQ int * +0x0000541C TIOCLINUX const char * // MORE +0x0000541D TIOCCONS void +0x0000541E TIOCGSERIAL struct serial_struct * +0x0000541F TIOCSSERIAL const struct serial_struct * +0x00005420 TIOCPKT const int * +0x00005421 FIONBIO const int * +0x00005422 TIOCNOTTY void +0x00005423 TIOCSETD const int * +0x00005424 TIOCGETD int * +0x00005425 TCSBRKP int +0x00005426 TIOCTTYGSTRUCT struct tty_struct * +0x00005450 FIONCLEX void +0x00005451 FIOCLEX void +0x00005452 FIOASYNC const int * +0x00005453 TIOCSERCONFIG void +0x00005454 TIOCSERGWILD int * +0x00005455 TIOCSERSWILD const int * +0x00005456 TIOCGLCKTRMIOS struct termios * +0x00005457 TIOCSLCKTRMIOS const struct termios * +0x00005458 TIOCSERGSTRUCT struct async_struct * +0x00005459 TIOCSERGETLSR int * +0x0000545A TIOCSERGETMULTI struct serial_multiport_struct * +0x0000545B TIOCSERSETMULTI const struct serial_multiport_struct * + +// +0x000089E0 SIOCAX25GETUID const struct sockaddr_ax25 * +0x000089E1 SIOCAX25ADDUID const struct sockaddr_ax25 * +0x000089E2 SIOCAX25DELUID const struct sockaddr_ax25 * +0x000089E3 SIOCAX25NOUID const int * +0x000089E4 SIOCAX25DIGCTL const int * +0x000089E5 SIOCAX25GETPARMS struct ax25_parms_struct * // I-O +0x000089E6 SIOCAX25SETPARMS const struct ax25_parms-struct * + +// +0x00007314 STL_BINTR void +0x00007315 STL_BSTART void +0x00007316 STL_BSTOP void +0x00007317 STL_BRESET void + +// +0x00005301 CDROMPAUSE void +0x00005302 CDROMRESUME void +0x00005303 CDROMPLAYMSF const struct cdrom_msf * +0x00005304 CDROMPLAYTRKIND const struct cdrom_ti * +0x00005305 CDROMREADTOCHDR struct cdrom_tochdr * +0x00005306 CDROMREADTOCENTRY struct cdrom_tocentry * // I-O +0x00005307 CDROMSTOP void +0x00005308 CDROMSTART void +0x00005309 CDROMEJECT void +0x0000530A CDROMVOLCTRL const struct cdrom_volctrl * +0x0000530B CDROMSUBCHNL struct cdrom_subchnl * // I-O +0x0000530C CDROMREADMODE2 const struct cdrom_msf * // MORE +0x0000530D CDROMREADMODE1 const struct cdrom_msf * // MORE +0x0000530E CDROMREADAUDIO const struct cdrom_read_audio * // MORE +0x0000530F CDROMEJECT_SW int +0x00005310 CDROMMULTISESSION struct cdrom_multisession * // I-O +0x00005311 CDROM_GET_UPC struct { char [8]; } * +0x00005312 CDROMRESET void +0x00005313 CDROMVOLREAD struct cdrom_volctrl * +0x00005314 CDROMREADRAW const struct cdrom_msf * // MORE +0x00005315 CDROMREADCOOKED const struct cdrom_msf * // MORE +0x00005316 CDROMSEEK const struct cdrom_msf * + +// +0x00002000 CM206CTL_GET_STAT int +0x00002001 CM206CTL_GET_LAST_STAT int + +// +0x00435901 CYGETMON struct cyclades_monitor * +0x00435902 CYGETTHRESH int * +0x00435903 CYSETTHRESH int +0x00435904 CYGETDEFTHRESH int * +0x00435905 CYSETDEFTHRESH int +0x00435906 CYGETTIMEOUT int * +0x00435907 CYSETTIMEOUT int +0x00435908 CYGETDEFTIMEOUT int * +0x00435909 CYSETDEFTIMEOUT int + +// +0x80046601 EXT2_IOC_GETFLAGS int * +0x40046602 EXT2_IOC_SETFLAGS const int * +0x80047601 EXT2_IOC_GETVERSION int * +0x40047602 EXT2_IOC_SETVERSION const int * + +// +0x00000000 FDCLRPRM void +0x00000001 FDSETPRM const struct floppy_struct * +0x00000002 FDDEFPRM const struct floppy_struct * +0x00000003 FDGETPRM struct floppy_struct * +0x00000004 FDMSGON void +0x00000005 FDMSGOFF void +0x00000006 FDFMTBEG void +0x00000007 FDFMTTRK const struct format_descr * +0x00000008 FDFMTEND void +0x0000000A FDSETEMSGTRESH int +0x0000000B FDFLUSH void +0x0000000C FDSETMAXERRS const struct floppy_max_errors * +0x0000000E FDGETMAXERRS struct floppy_max_errors * +0x00000010 FDGETDRVTYP struct { char [16]; } * +0x00000014 FDSETDRVPRM const struct floppy_drive_params * +0x00000015 FDGETDRVPRM struct floppy_drive_params * +0x00000016 FDGETDRVSTAT struct floppy_drive_struct * +0x00000017 FDPOLLDRVSTAT struct floppy_drive_struct * +0x00000018 FDRESET int +0x00000019 FDGETFDCSTAT struct floppy_fdc_state * +0x0000001B FDWERRORCLR void +0x0000001C FDWERRORGET struct floppy_write_errors * +0x0000001E FDRAWCMD struct floppy_raw_cmd * // MORE // I-O +0x00000028 FDTWADDLE void + +// +0x0000125D BLKROSET const int * +0x0000125E BLKROGET int * +0x0000125F BLKRRPART void +0x00001260 BLKGETSIZE int * +0x00001261 BLKFLSBUF void +0x00001262 BLKRASET int +0x00001263 BLKRAGET int * +0x00000001 FIBMAP int * // I-O +0x00000002 FIGETBSZ int * + +// +0x00000301 HDIO_GETGEO struct hd_geometry * +0x00000302 HDIO_GET_UNMASKINTR int * +0x00000304 HDIO_GET_MULTCOUNT int * +0x00000307 HDIO_GET_IDENTITY struct hd_driveid * +0x00000308 HDIO_GET_KEEPSETTINGS int * +0x00000309 HDIO_GET_CHIPSET int * +0x0000030A HDIO_GET_NOWERR int * +0x0000030B HDIO_GET_DMA int * +0x0000031F HDIO_DRIVE_CMD int * // I-O +0x00000321 HDIO_SET_MULTCOUNT int +0x00000322 HDIO_SET_UNMASKINTR int +0x00000323 HDIO_SET_KEEPSETTINGS int +0x00000324 HDIO_SET_CHIPSET int +0x00000325 HDIO_SET_NOWERR int +0x00000326 HDIO_SET_DMA int + +// +0x000089F0 EQL_ENSLAVE struct ifreq * // MORE // I-O +0x000089F1 EQL_EMANCIPATE struct ifreq * // MORE // I-O +0x000089F2 EQL_GETSLAVECFG struct ifreq * // MORE // I-O +0x000089F3 EQL_SETSLAVECFG struct ifreq * // MORE // I-O +0x000089F4 EQL_GETMASTRCFG struct ifreq * // MORE // I-O +0x000089F5 EQL_SETMASTRCFG struct ifreq * // MORE // I-O + +// +0x000089F0 SIOCDEVPLIP struct ifreq * // I-O + +// +0x00005490 PPPIOCGFLAGS int * +0x00005491 PPPIOCSFLAGS const int * +0x00005492 PPPIOCGASYNCMAP int * +0x00005493 PPPIOCSASYNCMAP const int * +0x00005494 PPPIOCGUNIT int * +0x00005495 PPPIOCSINPSIG const int * +0x00005497 PPPIOCSDEBUG const int * +0x00005498 PPPIOCGDEBUG int * +0x00005499 PPPIOCGSTAT struct ppp_stats * +0x0000549A PPPIOCGTIME struct ppp_ddinfo * +0x0000549B PPPIOCGXASYNCMAP struct { int [8]; } * +0x0000549C PPPIOCSXASYNCMAP const struct { int [8]; } * +0x0000549D PPPIOCSMRU const int * +0x0000549E PPPIOCRASYNCMAP const int * +0x0000549F PPPIOCSMAXCID const int * + +// +0x000089E0 SIOCAIPXITFCRT const char * +0x000089E1 SIOCAIPXPRISLT const char * +0x000089E2 SIOCIPXCFGDATA struct ipx_config_data * + +// +0x00004B60 GIO_FONT struct { char [8192]; } * +0x00004B61 PIO_FONT const struct { char [8192]; } * +0x00004B6B GIO_FONTX struct console_font_desc * // MORE I-O +0x00004B6C PIO_FONTX const struct console_font_desc * //MORE +0x00004B70 GIO_CMAP struct { char [48]; } * +0x00004B71 PIO_CMAP const struct { char [48]; } +0x00004B2F KIOCSOUND int +0x00004B30 KDMKTONE int +0x00004B31 KDGETLED char * +0x00004B32 KDSETLED int +0x00004B33 KDGKBTYPE char * +0x00004B34 KDADDIO int // MORE +0x00004B35 KDDELIO int // MORE +0x00004B36 KDENABIO void // MORE +0x00004B37 KDDISABIO void // MORE +0x00004B3A KDSETMODE int +0x00004B3B KDGETMODE int * +0x00004B3C KDMAPDISP void // MORE +0x00004B3D KDUNMAPDISP void // MORE +0x00004B40 GIO_SCRNMAP struct { char [E_TABSZ]; } * +0x00004B41 PIO_SCRNMAP const struct { char [E_TABSZ]; } * +0x00004B69 GIO_UNISCRNMAP struct { short [E_TABSZ]; } * +0x00004B6A PIO_UNISCRNMAP const struct { short [E_TABSZ]; } * +0x00004B66 GIO_UNIMAP struct unimapdesc * // MORE // I-O +0x00004B67 PIO_UNIMAP const struct unimapdesc * // MORE +0x00004B68 PIO_UNIMAPCLR const struct unimapinit * +0x00004B44 KDGKBMODE int * +0x00004B45 KDSKBMODE int +0x00004B62 KDGKBMETA int * +0x00004B63 KDSKBMETA int +0x00004B64 KDGKBLED int * +0x00004B65 KDSKBLED int +0x00004B46 KDGKBENT struct kbentry * // I-O +0x00004B47 KDSKBENT const struct kbentry * +0x00004B48 KDGKBSENT struct kbsentry * // I-O +0x00004B49 KDSKBSENT const struct kbsentry * +0x00004B4A KDGKBDIACR struct kbdiacrs * +0x00004B4B KDSKBDIACR const struct kbdiacrs * +0x00004B4C KDGETKEYCODE struct kbkeycode * // I-O +0x00004B4D KDSETKEYCODE const struct kbkeycode * +0x00004B4E KDSIGACCEPT int + +// +0x00000601 LPCHAR int +0x00000602 LPTIME int +0x00000604 LPABORT int +0x00000605 LPSETIRQ int +0x00000606 LPGETIRQ int * +0x00000608 LPWAIT int +0x00000609 LPCAREFUL int +0x0000060A LPABORTOPEN int +0x0000060B LPGETSTATUS int * +0x0000060C LPRESET void +0x0000060D LPGETSTATS struct lp_stats * + +// +0x000089E0 SIOCGETVIFCNT struct sioc_vif_req * // I-O +0x000089E1 SIOCGETSGCNT struct sioc_sg_req * // I-O + +// +0x40086D01 MTIOCTOP const struct mtop * +0x801C6D02 MTIOCGET struct mtget * +0x80046D03 MTIOCPOS struct mtpos * +0x80206D04 MTIOCGETCONFIG struct mtconfiginfo * +0x40206D05 MTIOCSETCONFIG const struct mtconfiginfo * + +// +0x000089E0 SIOCNRGETPARMS struct nr_parms_struct * // I-O +0x000089E1 SIOCNRSETPARMS const struct nr_parms_struct * +0x000089E2 SIOCNRDECOBS void +0x000089E3 SIOCNRRTCTL const int * + +// +0x00009000 DDIOCSDBG const int * +0x00005382 CDROMAUDIOBUFSIZ int + +// +0x00005470 TIOCSCCINI void +0x00005471 TIOCCHANINI const struct scc_modem * +0x00005472 TIOCGKISS struct ioctl_command * // I-O +0x00005473 TIOCSKISS const struct ioctl_command * +0x00005474 TIOCSCCSTAT struct scc_stat * + +// +0x00005382 SCSI_IOCTL_GET_IDLUN struct { int [2]; } * +0x00005383 SCSI_IOCTL_TAGGED_ENABLE void +0x00005384 SCSI_IOCTL_TAGGED_DISABLE void +0x00005385 SCSI_IOCTL_PROBE_HOST const int * // MORE + +// +0x80027501 SMB_IOC_GETMOUNTUID uid_t * + +// +0x0000890B SIOCADDRT const struct rtentry * // MORE +0x0000890C SIOCDELRT const struct rtentry * // MORE +0x00008910 SIOCGIFNAME char [] +0x00008911 SIOCSIFLINK void +0x00008912 SIOCGIFCONF struct ifconf * // MORE // I-O +0x00008913 SIOCGIFFLAGS struct ifreq * // I-O +0x00008914 SIOCSIFFLAGS const struct ifreq * +0x00008915 SIOCGIFADDR struct ifreq * // I-O +0x00008916 SIOCSIFADDR const struct ifreq * +0x00008917 SIOCGIFDSTADDR struct ifreq * // I-O +0x00008918 SIOCSIFDSTADDR const struct ifreq * +0x00008919 SIOCGIFBRDADDR struct ifreq * // I-O +0x0000891A SIOCSIFBRDADDR const struct ifreq * +0x0000891B SIOCGIFNETMASK struct ifreq * // I-O +0x0000891C SIOCSIFNETMASK const struct ifreq * +0x0000891D SIOCGIFMETRIC struct ifreq * // I-O +0x0000891E SIOCSIFMETRIC const struct ifreq * +0x0000891F SIOCGIFMEM struct ifreq * // I-O +0x00008920 SIOCSIFMEM const struct ifreq * +0x00008921 SIOCGIFMTU struct ifreq * // I-O +0x00008922 SIOCSIFMTU const struct ifreq * +0x00008923 OLD_SIOCGIFHWADDR struct ifreq * // I-O +0x00008924 SIOCSIFHWADDR const struct ifreq * // MORE +0x00008925 SIOCGIFENCAP int * +0x00008926 SIOCSIFENCAP const int * +0x00008927 SIOCGIFHWADDR struct ifreq * // I-O +0x00008929 SIOCGIFSLAVE void +0x00008930 SIOCSIFSLAVE void +0x00008931 SIOCADDMULTI const struct ifreq * +0x00008932 SIOCDELMULTI const struct ifreq * +0x00008940 SIOCADDRTOLD void +0x00008941 SIOCDELRTOLD void +0x00008950 SIOCDARP const struct arpreq * +0x00008951 SIOCGARP struct arpreq * // I-O +0x00008952 SIOCSARP const struct arpreq * +0x00008960 SIOCDRARP const struct arpreq * +0x00008961 SIOCGRARP struct arpreq * // I-O +0x00008962 SIOCSRARP const struct arpreq * +0x00008970 SIOCGIFMAP struct ifreq * // I-O +0x00008971 SIOCSIFMAP const struct ifreq * + +// +0x00005100 SNDCTL_SEQ_RESET void +0x00005101 SNDCTL_SEQ_SYNC void +0xC08C5102 SNDCTL_SYNTH_INFO struct synth_info * // I-O +0xC0045103 SNDCTL_SEQ_CTRLRATE int * // I-O +0x80045104 SNDCTL_SEQ_GETOUTCOUNT int * +0x80045105 SNDCTL_SEQ_GETINCOUNT int * +0x40045106 SNDCTL_SEQ_PERCMODE void +0x40285107 SNDCTL_FM_LOAD_INSTR const struct sbi_instrument * +0x40045108 SNDCTL_SEQ_TESTMIDI const int * +0x40045109 SNDCTL_SEQ_RESETSAMPLES const int * +0x8004510A SNDCTL_SEQ_NRSYNTHS int * +0x8004510B SNDCTL_SEQ_NRMIDIS int * +0xC074510C SNDCTL_MIDI_INFO struct midi_info * // I-O +0x4004510D SNDCTL_SEQ_THRESHOLD const int * +0xC004510E SNDCTL_SYNTH_MEMAVL int * // I-O +0x4004510F SNDCTL_FM_4OP_ENABLE const int * +0xCFB85110 SNDCTL_PMGR_ACCESS struct patmgr_info * // I-O +0x00005111 SNDCTL_SEQ_PANIC void +0x40085112 SNDCTL_SEQ_OUTOFBAND const struct seq_event_rec * +0xC0045401 SNDCTL_TMR_TIMEBASE int * // I-O +0x00005402 SNDCTL_TMR_START void +0x00005403 SNDCTL_TMR_STOP void +0x00005404 SNDCTL_TMR_CONTINUE void +0xC0045405 SNDCTL_TMR_TEMPO int * // I-O +0xC0045406 SNDCTL_TMR_SOURCE int * // I-O +0x40045407 SNDCTL_TMR_METRONOME const int * +0x40045408 SNDCTL_TMR_SELECT int * // I-O +0xCFB85001 SNDCTL_PMGR_IFACE struct patmgr_info * // I-O +0xC0046D00 SNDCTL_MIDI_PRETIME int * // I-O +0xC0046D01 SNDCTL_MIDI_MPUMODE const int * +0xC0216D02 SNDCTL_MIDI_MPUCMD struct mpu_command_rec * // I-O +0x00005000 SNDCTL_DSP_RESET void +0x00005001 SNDCTL_DSP_SYNC void +0xC0045002 SNDCTL_DSP_SPEED int * // I-O +0xC0045003 SNDCTL_DSP_STEREO int * // I-O +0xC0045004 SNDCTL_DSP_GETBLKSIZE int * // I-O +0xC0045006 SOUND_PCM_WRITE_CHANNELS int * // I-O +0xC0045007 SOUND_PCM_WRITE_FILTER int * // I-O +0x00005008 SNDCTL_DSP_POST void +0xC0045009 SNDCTL_DSP_SUBDIVIDE int * // I-O +0xC004500A SNDCTL_DSP_SETFRAGMENT int * // I-O +0x8004500B SNDCTL_DSP_GETFMTS int * +0xC0045005 SNDCTL_DSP_SETFMT int * // I-O +0x800C500C SNDCTL_DSP_GETOSPACE struct audio_buf_info * +0x800C500D SNDCTL_DSP_GETISPACE struct audio_buf_info * +0x0000500E SNDCTL_DSP_NONBLOCK void +0x80045002 SOUND_PCM_READ_RATE int * +0x80045006 SOUND_PCM_READ_CHANNELS int * +0x80045005 SOUND_PCM_READ_BITS int * +0x80045007 SOUND_PCM_READ_FILTER int * +0x00004300 SNDCTL_COPR_RESET void +0xCFB04301 SNDCTL_COPR_LOAD const struct copr_buffer * +0xC0144302 SNDCTL_COPR_RDATA struct copr_debug_buf * // I-O +0xC0144303 SNDCTL_COPR_RCODE struct copr_debug_buf * // I-O +0x40144304 SNDCTL_COPR_WDATA const struct copr_debug_buf * +0x40144305 SNDCTL_COPR_WCODE const struct copr_debug_buf * +0xC0144306 SNDCTL_COPR_RUN struct copr_debug_buf * // I-O +0xC0144307 SNDCTL_COPR_HALT struct copr_debug_buf * // I-O +0x4FA44308 SNDCTL_COPR_SENDMSG const struct copr_msg * +0x8FA44309 SNDCTL_COPR_RCVMSG struct copr_msg * +0x80044D00 SOUND_MIXER_READ_VOLUME int * +0x80044D01 SOUND_MIXER_READ_BASS int * +0x80044D02 SOUND_MIXER_READ_TREBLE int * +0x80044D03 SOUND_MIXER_READ_SYNTH int * +0x80044D04 SOUND_MIXER_READ_PCM int * +0x80044D05 SOUND_MIXER_READ_SPEAKER int * +0x80044D06 SOUND_MIXER_READ_LINE int * +0x80044D07 SOUND_MIXER_READ_MIC int * +0x80044D08 SOUND_MIXER_READ_CD int * +0x80044D09 SOUND_MIXER_READ_IMIX int * +0x80044D0A SOUND_MIXER_READ_ALTPCM int * +0x80044D0B SOUND_MIXER_READ_RECLEV int * +0x80044D0C SOUND_MIXER_READ_IGAIN int * +0x80044D0D SOUND_MIXER_READ_OGAIN int * +0x80044D0E SOUND_MIXER_READ_LINE1 int * +0x80044D0F SOUND_MIXER_READ_LINE2 int * +0x80044D10 SOUND_MIXER_READ_LINE3 int * +0x80044D1C SOUND_MIXER_READ_MUTE int * +0x80044D1D SOUND_MIXER_READ_ENHANCE int * +0x80044D1E SOUND_MIXER_READ_LOUD int * +0x80044DFF SOUND_MIXER_READ_RECSRC int * +0x80044DFE SOUND_MIXER_READ_DEVMASK int * +0x80044DFD SOUND_MIXER_READ_RECMASK int * +0x80044DFB SOUND_MIXER_READ_STEREODEVS int * +0x80044DFC SOUND_MIXER_READ_CAPS int * +0xC0044D00 SOUND_MIXER_WRITE_VOLUME int * // I-O +0xC0044D01 SOUND_MIXER_WRITE_BASS int * // I-O +0xC0044D02 SOUND_MIXER_WRITE_TREBLE int * // I-O +0xC0044D03 SOUND_MIXER_WRITE_SYNTH int * // I-O +0xC0044D04 SOUND_MIXER_WRITE_PCM int * // I-O +0xC0044D05 SOUND_MIXER_WRITE_SPEAKER int * // I-O +0xC0044D06 SOUND_MIXER_WRITE_LINE int * // I-O +0xC0044D07 SOUND_MIXER_WRITE_MIC int * // I-O +0xC0044D08 SOUND_MIXER_WRITE_CD int * // I-O +0xC0044D09 SOUND_MIXER_WRITE_IMIX int * // I-O +0xC0044D0A SOUND_MIXER_WRITE_ALTPCM int * // I-O +0xC0044D0B SOUND_MIXER_WRITE_RECLEV int * // I-O +0xC0044D0C SOUND_MIXER_WRITE_IGAIN int * // I-O +0xC0044D0D SOUND_MIXER_WRITE_OGAIN int * // I-O +0xC0044D0E SOUND_MIXER_WRITE_LINE1 int * // I-O +0xC0044D0F SOUND_MIXER_WRITE_LINE2 int * // I-O +0xC0044D10 SOUND_MIXER_WRITE_LINE3 int * // I-O +0xC0044D1C SOUND_MIXER_WRITE_MUTE int * // I-O +0xC0044D1D SOUND_MIXER_WRITE_ENHANCE int * // I-O +0xC0044D1E SOUND_MIXER_WRITE_LOUD int * // I-O +0xC0044DFF SOUND_MIXER_WRITE_RECSRC int * // I-O + +// +0x000004D2 UMSDOS_READDIR_DOS struct umsdos_ioctl * // I-O +0x000004D3 UMSDOS_UNLINK_DOS const struct umsdos_ioctl * +0x000004D4 UMSDOS_RMDIR_DOS const struct umsdos_ioctl * +0x000004D5 UMSDOS_STAT_DOS struct umsdos_ioctl * // I-O +0x000004D6 UMSDOS_CREAT_EMD const struct umsdos_ioctl * +0x000004D7 UMSDOS_UNLINK_EMD const struct umsdos_ioctl * +0x000004D8 UMSDOS_READDIR_EMD struct umsdos_ioctl * // I-O +0x000004D9 UMSDOS_GETVERSION struct umsdos_ioctl * +0x000004DA UMSDOS_INIT_EMD void +0x000004DB UMSDOS_DOS_SETUP const struct umsdos_ioctl * +0x000004DC UMSDOS_RENAME_DOS const struct umsdos_ioctl * + +// +0x00005600 VT_OPENQRY int * +0x00005601 VT_GETMODE struct vt_mode * +0x00005602 VT_SETMODE const struct vt_mode * +0x00005603 VT_GETSTATE struct vt_stat * +0x00005604 VT_SENDSIG void +0x00005605 VT_RELDISP int +0x00005606 VT_ACTIVATE int +0x00005607 VT_WAITACTIVE int +0x00005608 VT_DISALLOCATE int +0x00005609 VT_RESIZE const struct vt_sizes * +0x0000560A VT_RESIZEX const struct vt_consize * + + + +// More arguments. + +Some ioctl's take a pointer to a structure which contains additional +pointers. These are documented here in alphabetical order. + +CDROMREADAUDIO takes an input pointer 'const struct cdrom_read_audio *'. +The 'buf' field points to an output buffer +of length 'nframes * CD_FRAMESIZE_RAW'. + +CDROMREADCOOKED, CDROMREADMODE1, CDROMREADMODE2, and CDROMREADRAW take +an input pointer 'const struct cdrom_msf *'. They use the same pointer +as an output pointer to 'char []'. The length varies by request. For +CDROMREADMODE1, most drivers use 'CD_FRAMESIZE', but the Optics Storage +driver uses 'OPT_BLOCKSIZE' instead (both have the numerical value +2048). + + CDROMREADCOOKED char [CD_FRAMESIZE] + CDROMREADMODE1 char [CD_FRAMESIZE or OPT_BLOCKSIZE] + CDROMREADMODE2 char [CD_FRAMESIZE_RAW0] + CDROMREADRAW char [CD_FRAMESIZE_RAW] + +EQL_ENSLAVE, EQL_EMANCIPATE, EQL_GETSLAVECFG, EQL_SETSLAVECFG, +EQL_GETMASTERCFG, and EQL_SETMASTERCFG take a 'struct ifreq *'. +The 'ifr_data' field is a pointer to another structure as follows: + + EQL_ENSLAVE const struct slaving_request * + EQL_EMANCIPATE const struct slaving_request * + EQL_GETSLAVECFG struct slave_config * // I-O + EQL_SETSLAVECFG const struct slave_config * + EQL_GETMASTERCFG struct master_config * + EQL_SETMASTERCFG const struct master_config * + +FDRAWCMD takes a 'struct floppy raw_cmd *'. If 'flags & FD_RAW_WRITE' +is non-zero, then 'data' points to an input buffer of length 'length'. +If 'flags & FD_RAW_READ' is non-zero, then 'data' points to an output +buffer of length 'length'. + +GIO_FONTX and PIO_FONTX take a 'struct console_font_desc *' or +a 'const struct console_font_desc *', respectively. 'chardata' points to +a buffer of 'char [charcount]'. This is an output buffer for GIO_FONTX +and an input buffer for PIO_FONTX. + +GIO_UNIMAP and PIO_UNIMAP take a 'struct unimapdesc *' or +a 'const struct unimapdesc *', respectively. 'entries' points to a buffer +of 'struct unipair [entry_ct]'. This is an output buffer for GIO_UNIMAP +and an input buffer for PIO_UNIMAP. + +KDADDIO, KDDELIO, KDDISABIO, and KDENABIO enable or disable access to +I/O ports. They are essentially alternate interfaces to 'ioperm'. + +KDMAPDISP and KDUNMAPDISP enable or disable memory mappings or I/O port +access. They are not implemented in the kernel. + +SCSI_IOCTL_PROBE_HOST takes an input pointer 'const int *', which is a +length. It uses the same pointer as an output pointer to a 'char []' +buffer of this length. + +SIOCADDRT and SIOCDELRT take an input pointer whose type depends on +the protocol: + + Most protocols const struct rtentry * + AX.25 const struct ax25_route * + NET/ROM const struct nr_route_struct * + +SIOCGIFCONF takes a 'struct ifconf *'. The 'ifc_buf' field points to a +buffer of length 'ifc_len' bytes, into which the kernel writes a list of +type 'struct ifreq []'. + +SIOCSIFHWADDR takes an input pointer whose type depends on the protocol: + + Most protocols const struct ifreq * + AX.25 const char [AX25_ADDR_LEN] + +TIOCLINUX takes a 'const char *'. It uses this to distinguish several +independent sub-cases. In the table below, 'N + foo' means 'foo' after +an N-byte pad. 'struct selection' is implicitly defined +in 'drivers/char/selection.c' + + TIOCLINUX-2 1 + const struct selection * + TIOCLINUX-3 void + TIOCLINUX-4 void + TIOCLINUX-5 4 + const struct { long [8]; } * + TIOCLINUX-6 char * + TIOCLINUX-7 char * + TIOCLINUX-10 1 + const char * + + + + + +// Duplicate ioctls + +This list does not include ioctls in the range SIOCDEVPRIVATE and +SIOCPROTOPRIVATE. + +0x00000001 FDSETPRM FIBMAP +0x00000002 FDDEFPRM FIGETBSZ +0x00005382 CDROMAUDIOBUFSIZ SCSI_IOCTL_GET_IDLUN +0x00005402 SNDCTL_TMR_START TCSETS +0x00005403 SNDCTL_TMR_STOP TCSETSW +0x00005404 SNDCTL_TMR_CONTINUE TCSETSF diff --git a/man2/ioperm.2 b/man2/ioperm.2 new file mode 100644 index 000000000..a2a48e675 --- /dev/null +++ b/man2/ioperm.2 @@ -0,0 +1,95 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de) +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 15:12:05 1993 by Rik Faith +.\" Modified Tue Aug 1 16:27 1995 by Jochen Karrer +.\" +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" Modified Mon Feb 15 17:28:41 CET 1999 by Andries E. Brouwer +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH IOPERN 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +ioperm \- set port input/output permissions +.SH SYNOPSIS +.B #include +/* for libc5 */ +.br +.B #include +/* for glibc */ +.sp +.BI "int ioperm(unsigned long " from ", unsigned long " num ", int " turn_on ); +.SH DESCRIPTION +\fBIoperm\fP sets the port access permission bits for the process for +\fInum\fP bytes starting from port address \fBfrom\fP to the value +\fBturn_on\fP. The use of \fBioperm\fP requires root privileges. + +Only the first 0x3ff I/O ports can be specified in this manner. For more +ports, the +.B iopl +function must be used. +Permissions are not inherited on fork, but on exec they are. This is +useful for giving port access permissions to non-privileged tasks. + +This call is mostly for the i386 architecture. +On many other architectures it does not exist or will always +return an error. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +Invalid values for +.I from +or +.IR num . +.TP +.B EIO +(on ppc) This call is not supported. +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR ioperm ; +the +.B CAP_SYS_RAWIO +capability is required. +.SH "CONFORMING TO" +\fBioperm\fP is Linux specific and should not be used in programs +intended to be portable. +.SH NOTES +Libc5 treats it as a system call and has a prototype in +.IR . +Glibc1 does not have a prototype. Glibc2 has a prototype both in +.I +and in +.IR . +Avoid the latter, it is available on i386 only. +.SH "SEE ALSO" +.BR iopl (2), +.BR capabilities (7) diff --git a/man2/iopl.2 b/man2/iopl.2 new file mode 100644 index 000000000..3f07dbeac --- /dev/null +++ b/man2/iopl.2 @@ -0,0 +1,93 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Portions extracted from linux/kernel/ioport.c (no copyright notice). +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Tue Aug 1 16:47 1995 by Jochen Karrer +.\" +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" Modified Fri Nov 27 14:50:36 CET 1998 by Andries Brouwer +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH IOPL 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +iopl \- change I/O privilege level +.SH SYNOPSIS +.B #include +.sp +.BI "int iopl(int " level ); +.SH DESCRIPTION +.B iopl +changes the I/O privilege level of the current process, as specified in +.IR level . + +This call is necessary to allow 8514-compatible X servers to run under +Linux. Since these X servers require access to all 65536 I/O ports, the +.B ioperm +call is not sufficient. + +In addition to granting unrestricted I/O port access, running at a higher +I/O privilege level also allows the process to disable interrupts. This +will probably crash the system, and is not recommended. + +Permissions are inherited by fork and exec. + +The I/O privilege level for a normal process is 0. + +This call is mostly for the i386 architecture. +On many other architectures it does not exist or will always +return an error. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +.I level +is greater than 3. +.TP +.B ENOSYS +This call is unimplemented. +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR iopl ; +the +.B CAP_SYS_RAWIO +capability is required. +.SH "CONFORMING TO" +\fBiopl\fP is Linux specific and should not be used in processes +intended to be portable. +.SH NOTES +Libc5 treats it as a system call and has a prototype in +.IR . +Glibc1 does not have a prototype. Glibc2 has a prototype both in +.I +and in +.IR . +Avoid the latter, it is available on i386 only. +.SH "SEE ALSO" +.BR ioperm (2), +.BR capabilities (7) diff --git a/man2/ipc.2 b/man2/ipc.2 new file mode 100644 index 000000000..b3d2b88e6 --- /dev/null +++ b/man2/ipc.2 @@ -0,0 +1,57 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.TH IPC 2 1995-04-15 "Linux 1.2.4" "Linux Programmer's Manual" +.SH NAME +ipc \- System V IPC system calls +.SH SYNOPSIS +.BI "int ipc(unsigned int " call ", int " first ", int " second , +.BI "int " third ", void *" ptr ", long " fifth ); +.SH DESCRIPTION +.B ipc() +is a common kernel entry point for the System V IPC calls +for messages, semaphores, and shared memory. +.I call +determines which IPC function to invoke; +the other arguments are passed through to the appropriate call. +.PP +User programs should call the appropriate functions by their usual names. +Only standard library implementors and kernel hackers need to know about +.BR ipc() . +.SH "CONFORMING TO" +\fBipc()\fP is Linux specific, and should not be used in programs +intended to be portable. +.SH "SEE ALSO" +.BR msgctl (2), +.BR msgget (2), +.BR msgrcv (2), +.BR msgsnd (2), +.BR semctl (2), +.BR semget (2), +.BR semop (2), +.BR shmat (2), +.BR shmctl (2), +.BR shmdt (2), +.BR shmget (2) diff --git a/man2/kill.2 b/man2/kill.2 new file mode 100644 index 000000000..bfff57ada --- /dev/null +++ b/man2/kill.2 @@ -0,0 +1,140 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified by Thomas Koenig +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1993-07-25 by Rik Faith +.\" Modified 1995-11-01 by Michael Haardt +.\" +.\" Modified 1996-04-14 by Andries Brouwer +.\" [added some polishing contributed by Mike Battersby ] +.\" Modified 1996-07-21 by Andries Brouwer +.\" Modified 1997-01-17 by Andries Brouwer +.\" Modified 2001-12-18 by Andries Brouwer +.\" Modified 2002-07-24 by Michael Kerrisk +.\" Added note on historical rules enforced when an unprivileged process +.\" sends a signal. +.\" Modified 2004-06-16 by Michael Kerrisk +.\" Added note on CAP_KILL +.\" Modified 2004-06-24 by aeb +.\" +.TH KILL 2 2004-06-24 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +kill \- send signal to a process +.SH SYNOPSIS +.nf +.B #include +.br +.B #include +.sp +.BI "int kill(pid_t " pid ", int " sig ); +.fi +.SH DESCRIPTION +The +.B kill +system call +can be used to send any signal to any process group or process. +.PP +If \fIpid\fP is positive, then signal \fIsig\fP is sent to \fIpid\fP. +.PP +If \fIpid\fP equals 0, then \fIsig\fP is sent to every process in the +process group of the current process. +.PP +If \fIpid\fP equals \-1, then \fIsig\fP is sent to every process except +for process 1 (init), but see below. +.PP +If \fIpid\fP is less than \-1, then \fIsig\fP is sent to every process +in the process group \fI\-pid\fP. +.PP +If \fIsig\fP is 0, then no signal is sent, but error checking is still +performed. + +For a process to have permission to send a signal +it must either be privileged (under Linux: have the +.B CAP_KILL +capability), or the real or effective +user ID of the sending process must equal the real or +saved set-user-ID of the target process. +In the case of SIGCONT it suffices when the sending and receiving +processes belong to the same session. +.SH "RETURN VALUE" +On success (at least one signal was sent), zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +An invalid signal was specified. +.TP +.B EPERM +The process does not have permission to send the signal +to any of the target processes. +.TP +.B ESRCH +The pid or process group does not exist. +Note that an existing process might be a zombie, +a process which already committed termination, but +has not yet been \fBwait()\fPed for. +.SH NOTES +It is impossible to send a signal to task number one, the init process, for +which it has not installed a signal handler. This is done to assure the +system is not brought down accidentally. +.LP +POSIX 1003.1-2001 requires that \fIkill(-1,sig)\fP send \fIsig\fP +to all processes that the current process may send signals to, +except possibly for some implementation-defined system processes. +Linux allows a process to signal itself, but on Linux the call +\fIkill(-1,sig)\fP does not signal the current process. +.LP +POSIX 1003.1-2003 requires that if a process sends a signal to itself, +and that process does not have the signal blocked, and no other thread +has it unblocked or is waiting for it in \fIsigwait()\fP, at least one +unblocked signal must be delivered to the sending thread before the +call of \fIkill()\fP returns. +.SH "LINUX HISTORY" +Across different kernel versions, Linux has enforced different rules +for the permissions required for an unprivileged process +to send a signal to another process. +.\" In the 0.* kernels things chopped and changed quite +.\" a bit - MTK, 24 Jul 02 +In kernels 1.0 to 1.2.2, a signal could be sent if the +effective user ID of the sender matched that of the receiver, +or the real user ID of the sender matched that of the receiver. +From kernel 1.2.3 until 1.3.77, a signal could be sent if the +effective user ID of the sender matched either the real or effective +user ID of the receiver. +The current rules, which conform to POSIX 1003.1-2001, were adopted +in kernel 1.3.78. +.SH "CONFORMING TO" +SVr4, SVID, POSIX.1, X/OPEN, BSD 4.3, POSIX 1003.1-2001 +.SH "SEE ALSO" +.BR _exit (2), +.BR killpg (2), +.BR signal (2), +.BR tkill (2), +.BR exit (3), +.BR capabilities (7), +.BR signal (7) diff --git a/man2/killpg.2 b/man2/killpg.2 new file mode 100644 index 000000000..2236c52fd --- /dev/null +++ b/man2/killpg.2 @@ -0,0 +1,111 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)killpg.2 6.5 (Berkeley) 3/10/91 +.\" +.\" Modified Fri Jul 23 21:55:01 1993 by Rik Faith +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" Modified 2004-06-16 by Michael Kerrisk +.\" Added notes on CAP_KILL +.\" Modified 2004-06-21 by aeb +.\" +.TH KILLPG 2 2004-06-21 "BSD Man Page" "Linux Programmer's Manual" +.SH NAME +killpg \- send signal to a process group +.SH SYNOPSIS +.B #include +.sp +.BI "int killpg(int " pgrp ", int " sig ); +.SH DESCRIPTION +.B Killpg +sends the signal +.I sig +to the process group +.IR pgrp . +See +.BR signal (7) +for a list of signals. +If +.I pgrp +is 0, +.B killpg +sends the signal to the sending process's process group. + +(POSIX says: If +.I pgrp +is less than or equal to 1, the behaviour is undefined.) + +For a process to have permission to send a signal +it must either be privileged (under Linux: have the +.B CAP_KILL +capability), or the real or effective +user ID of the sending process must equal the real or +saved set-user-ID of the target process. +In the case of SIGCONT it suffices when the sending and receiving +processes belong to the same session. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +.I Sig +is not a valid signal number. +.TP +.B EPERM +The process does not have permission to send the signal +to any of the target processes. +.TP +.B ESRCH +No process can be found in the process group specified by +.IR pgrp . +.TP +.B ESRCH +The process group was given as 0 but the sending process does not +have a process group. +.SH NOTES +There are various differences between the permission checking +in BSD-type systems and SYSV-type systems. See the POSIX rationale +for kill(). A difference not mentioned by POSIX concerns the return +value EPERM: BSD documents that no signal is sent and EPERM returned +when the permission check failed for at least one target process, +while POSIX documents EPERM only when the permission check failed +for all target processes. +.SH "CONFORMING TO" +SVr4, 4.4BSD (The +.B killpg +function call first appeared in 4.0BSD). +.SH "SEE ALSO" +.BR getpgrp (2), +.BR kill (2), +.BR signal (2), +.BR capabilities (7) diff --git a/man2/lchown.2 b/man2/lchown.2 new file mode 100644 index 000000000..f0a5635ae --- /dev/null +++ b/man2/lchown.2 @@ -0,0 +1 @@ +.so man2/chown.2 diff --git a/man2/lgetxattr.2 b/man2/lgetxattr.2 new file mode 100644 index 000000000..d9e5d9037 --- /dev/null +++ b/man2/lgetxattr.2 @@ -0,0 +1 @@ +.so man2/getxattr.2 diff --git a/man2/link.2 b/man2/link.2 new file mode 100644 index 000000000..01b5b099e --- /dev/null +++ b/man2/link.2 @@ -0,0 +1,144 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt, Ian Jackson. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1994-08-21 by Michael Haardt +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH LINK 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +link \- make a new name for a file +.SH SYNOPSIS +.B #include +.sp +.BI "int link(const char *" oldpath ", const char *" newpath ); +.SH DESCRIPTION +.B link +creates a new link (also known as a hard link) to an existing file. + +If +.I newpath +exists it will +.I not +be overwritten. + +This new name may be used exactly as the old one for any operation; +both names refer to the same file (and so have the same permissions +and ownership) and it is impossible to tell which name was the +`original'. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Write access to the directory containing +.I newpath +is denied, or search permission is denied for one of the directories +in the path prefix of +.I oldpath +or +.IR newpath . +(See also +.BR path_resolution (2).) +.TP +.B EEXIST +.I newpath +already exists. +.TP +.B EFAULT +.IR oldpath " or " newpath " points outside your accessible address space." +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR oldpath " or " newpath . +.TP +.B EMLINK +The file referred to by +.I oldpath +already has the maximum number of links to it. +.TP +.B ENAMETOOLONG +.IR oldpath " or " newpath " was too long." +.TP +.B ENOENT +A directory component in +.IR oldpath " or " newpath +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The device containing the file has no room for the new directory +entry. +.TP +.B ENOTDIR +A component used as a directory in +.IR oldpath " or " newpath +is not, in fact, a directory. +.TP +.B EPERM +.I oldpath +is a directory. +.TP +.B EPERM +The filesystem containing +.IR oldpath " and " newpath +does not support the creation of hard links. +.TP +.B EROFS +The file is on a read-only filesystem. +.TP +.B EXDEV +.IR oldpath " and " newpath +are not on the same filesystem. +.SH NOTES +Hard links, as created by +.BR link , +cannot span filesystems. Use +.B symlink +if this is required. +.SH "CONFORMING TO" +SVr4, SVID, POSIX, BSD 4.3, X/OPEN. SVr4 documents additional ENOLINK and +EMULTIHOP error conditions; POSIX.1 does not document ELOOP. +X/OPEN does not document EFAULT, ENOMEM or EIO. +.SH BUGS +On NFS file systems, the return code may be wrong in case the NFS server +performs the link creation and dies before it can say so. Use +.BR stat (2) +to find out if the link got created. +.SH "SEE ALSO" +.BR ln (1), +.BR open (2), +.BR path_resolution (2), +.BR rename (2), +.BR stat (2), +.BR symlink (2), +.BR unlink (2) diff --git a/man2/listen.2 b/man2/listen.2 new file mode 100644 index 000000000..c9b3b77e7 --- /dev/null +++ b/man2/listen.2 @@ -0,0 +1,132 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Id: listen.2,v 1.6 1999/05/18 14:10:32 freitag Exp $ +.\" +.\" Modified Fri Jul 23 22:07:54 1993 by Rik Faith +.\" Modified 950727 by aeb, following a suggestion by Urs Thuermann +.\" +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" Modified 1998 by Andi Kleen +.\" Modified 11 May 2001 by Sam Varshavchik +.\" +.TH LISTEN 2 1993-07-23 "BSD Man Page" "Linux Programmer's Manual" +.SH NAME +listen \- listen for connections on a socket +.SH SYNOPSIS +.B #include +.sp +.BI "int listen(int " s ", int " backlog ); +.SH DESCRIPTION +To accept connections, a socket is first created with +.BR socket (2), +a willingness to accept incoming connections and a queue limit for incoming +connections are specified with +.BR listen , +and then the connections are +accepted with +.BR accept (2). +The +.B listen +call applies only to sockets of type +.B SOCK_STREAM +or +.BR SOCK_SEQPACKET . +.PP +The +.I backlog +parameter defines the maximum length the queue of pending connections may +grow to. If a connection request arrives with the queue full the client +may receive an error with an indication of +.B ECONNREFUSED +or, if the underlying protocol supports retransmission, the request may be +ignored so that retries succeed. +.SH NOTES +The behaviour of the +.I backlog +parameter on TCP sockets changed with Linux 2.2. +Now it specifies the queue length for +.I completely +established sockets waiting to be accepted, instead of the number of incomplete +connection requests. The maximum length of the queue for incomplete sockets +can be set using the +.B tcp_max_syn_backlog +sysctl. +When syncookies are enabled there is no logical maximum +length and this sysctl setting is ignored. +See +.BR tcp (7) +for more information. + +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EADDRINUSE +Another socket is already listening on the same port. +.TP +.B EBADF +The argument +.I s +is not a valid descriptor. +.TP +.B ENOTSOCK +The argument +.I s +is not a socket. +.TP +.B EOPNOTSUPP +The socket is not of a type that supports the +.B listen +operation. +.SH "CONFORMING TO" +Single Unix, 4.4BSD, POSIX 1003.1g draft. The +.B listen +function call first appeared in 4.2BSD. +.SH BUGS +If the socket is of type +.BR AF_INET , +and the +.I backlog +argument is greater +than the constant +.B SOMAXCONN +(128 in Linux 2.0 & 2.2), it is silently truncated +to +.BR SOMAXCONN . +Don't rely on this value in portable applications since BSD +(and some BSD-derived systems) limit the backlog to 5. +.SH "SEE ALSO" +.BR accept (2), +.BR connect (2), +.BR socket (2) diff --git a/man2/listxattr.2 b/man2/listxattr.2 new file mode 100644 index 000000000..fda133b9e --- /dev/null +++ b/man2/listxattr.2 @@ -0,0 +1,155 @@ +.\" +.\" Extended attributes system calls manual pages +.\" +.\" (C) Andreas Gruenbacher, February 2001 +.\" (C) Silicon Graphics Inc, September 2001 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH LISTXATTR 2 "Extended Attributes" "Dec 2001" "Linux Programmer's Manual" +.SH NAME +listxattr, llistxattr, flistxattr \- list extended attribute names +.SH SYNOPSIS +.fam C +.nf +.B #include +.B #include +.sp +.BI "ssize_t listxattr (const char\ *" path ", +.BI "\t\t\t\t char\ *" list ", size_t " size ); +.BI "ssize_t llistxattr (const char\ *" path ", +.BI "\t\t\t\t char\ *" list ", size_t " size ); +.BI "ssize_t flistxattr (int " filedes ", +.BI "\t\t\t\t char\ *" list ", size_t " size ); +.fi +.fam T +.SH DESCRIPTION +Extended attributes are name:value +pairs associated with inodes (files, directories, symlinks, etc). +They are extensions to the normal attributes which are associated +with all inodes in the system (i.e. the +.BR stat (2) +data). +A complete overview of extended attributes concepts can be found in +.BR attr (5). +.PP +.B listxattr +retrieves the +.I list +of extended attribute names associated with the given +.I path +in the filesystem. +The list is the set of (NULL-terminated) names, one after the other. +Names of extended attributes to which the calling process does not +have access may be omitted from the list. +The length of the attribute name +.I list +is returned. +.PP +.B llistxattr +is identical to +.BR listxattr , +except in the case of a symbolic link, where the list of names of +extended attributes associated with the link itself is retrieved, +not the file that it refers to. +.PP +.B flistxattr +is identical to +.BR listxattr , +only the open file pointed to by +.I filedes +(as returned by +.BR open (2)) +is interrogated in place of +.IR path . +.PP +A single extended attribute +.I name +is a simple NULL-terminated string. +The name includes a namespace prefix \- there may be several, disjoint +namespaces associated with an individual inode. +.PP +An empty buffer of +.I size +zero can be passed into these calls to return the current size of the +list of extended attribute names, which can be used to estimate the +size of a buffer which is sufficiently large to hold the list of names. +.SH EXAMPLES +The +.I list +of names is returned as an unordered array of NULL-terminated character +strings (attribute names are separated by NULL characters), like this: +.fam C +.RS +.nf +user.name1\\0system.name1\\0user.name2\\0 +.fi +.RE +.fam T +.P +Filesystems like ext2, ext3 and XFS which implement POSIX ACLs using +extended attributes, might return a +.I list +like this: +.fam C +.RS +.nf +system.posix_acl_access\\0system.posix_acl_default\\0 +.fi +.RE +.fam T +.SH RETURN VALUE +On success, a positive number is returned indicating the size of the +extended attribute name list. +On failure, \-1 is returned and +.I errno +is set appropriately. +.PP +If the +.I size +of the +.I list +buffer is too small to hold the result, +.I errno +is set to ERANGE. +.PP +If extended attributes are not supported by the filesystem, or are disabled, +.I errno +is set to ENOTSUP. +.PP +The errors documented for the +.BR stat (2) +system call are also applicable here. +.SH AUTHORS +Andreas Gruenbacher, +.RI < a.gruenbacher@computer.org > +and the SGI XFS development team, +.RI < linux-xfs@oss.sgi.com >. +Please send any bug reports or comments to these addresses. +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR getxattr (2), +.BR open (2), +.BR removexattr (2), +.BR setxattr (2), +.BR stat (2), +.BR attr (5) diff --git a/man2/llistxattr.2 b/man2/llistxattr.2 new file mode 100644 index 000000000..117bd2b53 --- /dev/null +++ b/man2/llistxattr.2 @@ -0,0 +1 @@ +.so man2/listxattr.2 diff --git a/man2/llseek.2 b/man2/llseek.2 new file mode 100644 index 000000000..d1e8ae5a2 --- /dev/null +++ b/man2/llseek.2 @@ -0,0 +1,79 @@ +.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Written 10 June 1995 by Andries Brouwer +.\" Modified Thu Oct 31 15:16:23 1996 by Eric S. Raymond +.\" +.TH LLSEEK 2 1995-06-10 "Linux 1.2.9" "Linux Programmer's Manual" +.SH NAME +_llseek \- reposition read/write file offset +.SH SYNOPSIS +.B #include +.sp +.B #include +.sp +.B _syscall5(int, _llseek, uint, fd, ulong, hi, ulong, lo, loff_t *, res, uint, wh); +.sp +.BI "int _llseek(unsigned int " fd ", unsigned long " offset_high , +.BI "unsigned long " offset_low ", loff_t *" result ", unsigned int " whence ); +.SH DESCRIPTION +The +.B _llseek +function repositions the offset of the file descriptor +.I fd +to +.I (offset_high<<32) | offset_low +bytes relative to the beginning of the file, the current position in the file, +or the end of the file, depending on whether +.I whence +is +.BR SEEK_SET , +.BR SEEK_CUR , +or +.BR SEEK_END , +respectively. +It returns the resulting file position in the argument +.IR result . + +.SH "RETURN VALUE" +Upon successful completion, +.B _llseek +returns 0. Otherwise, a value of \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not an open file descriptor. +.TP +.B EFAULT +Problem with copying results to user space. +.TP +.B EINVAL +.I whence +is invalid. +.SH "CONFORMING TO" +This function is Linux-specific, and should not be used in programs +intended to be portable. +.SH "SEE ALSO" +.BR lseek (2) diff --git a/man2/lock.2 b/man2/lock.2 new file mode 100644 index 000000000..5d25ea6ce --- /dev/null +++ b/man2/lock.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/lookup_dcookie.2 b/man2/lookup_dcookie.2 new file mode 100644 index 000000000..9e0079a13 --- /dev/null +++ b/man2/lookup_dcookie.2 @@ -0,0 +1,89 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 2003 John Levon +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 2004-06-17 Michael Kerrisk +.\" +.TH LOOKUP_DCOOKIE 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +lookup_dcookie \- return a directory entry's path +.SH SYNOPSIS +.sp +.BI "int lookup_dcookie(u64 " cookie ", char * " buffer ", size_t " len ); +.SH DESCRIPTION +Look up the full path of the directory entry specified by the value +.I cookie +. +The cookie is an opaque identifier uniquely identifying a particular directory +entry. The buffer given is filled in with the full path of the directory +entry. + +For +.B lookup_dcookie +to return successfully, +the kernel must still hold a cookie reference to the directory entry. + +.SH "NOTES" +.B lookup_dcookie +is a special-purpose system call, currently used only by the oprofile profiler. +It relies on a kernel driver to register cookies for directory entries. + +The path returned may be suffixed by the string " (deleted)" if the directory +entry has been removed. + +.SH "RETURN VALUE" +On success, +.B lookup_dcookie +returns the length of the path string copied into the buffer. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +The buffer was not valid. +.TP +.B EINVAL +The kernel has no registered cookie/directory entry mappings at the +time of lookup, or the cookie does not refer to a valid directory entry. +.TP +.B ENAMETOOLONG +The name could not fit in the buffer. +.TP +.B ENOMEM +The kernel could not allocate memory for the temporary buffer holding +the path. +.TP +.B EPERM +The process does not have the capability +.B CAP_SYS_ADMIN +required to look up cookie values. +.TP +.B ERANGE +The buffer was not large enough to hold the path of the directory entry. +.SH "CONFORMING TO" +.B lookup_dcookie +is Linux-specific. +.SH AVAILABILITY +Since Linux 2.5.43. +The ENAMETOOLONG error return was added in 2.5.70. diff --git a/man2/lremovexattr.2 b/man2/lremovexattr.2 new file mode 100644 index 000000000..38d01ccde --- /dev/null +++ b/man2/lremovexattr.2 @@ -0,0 +1 @@ +.so man2/removexattr.2 diff --git a/man2/lseek.2 b/man2/lseek.2 new file mode 100644 index 000000000..bd1981aa0 --- /dev/null +++ b/man2/lseek.2 @@ -0,0 +1,153 @@ +'\" t +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)lseek.2 6.5 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1995-06-10 by Andries Brouwer +.\" Modified 1996-10-31 by Eric S. Raymond +.\" Modified 1998-01-17 by Michael Haardt +.\" +.\" Modified 2001-09-24 by Michael Haardt +.\" Modified 2003-08-21 by Andries Brouwer +.\" +.TH LSEEK 2 2001-09-24 "Linux" "Linux Programmer's Manual" +.SH NAME +lseek \- reposition read/write file offset +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "off_t lseek(int " fildes ", off_t " offset ", int " whence ); +.SH DESCRIPTION +The +.B lseek +function repositions the offset of the file descriptor +.I fildes +to the argument +.I offset +according to the directive +.I whence +as follows: +.TP +.B SEEK_SET +The offset is set to +.I offset +bytes. +.TP +.B SEEK_CUR +The offset is set to its current location plus +.I offset +bytes. +.TP +.B SEEK_END +The offset is set to the size of the file plus +.I offset +bytes. +.PP +The +.B lseek +function allows the file offset to be set beyond the end of the existing +end-of-file of the file (but this does not change the size of the file). +If data is later written at this point, subsequent reads of the data +in the gap return bytes of zeros (until data is actually written into +the gap). +.SH "RETURN VALUE" +Upon successful completion, +.B lseek +returns the resulting offset location as measured in bytes from the +beginning of the file. Otherwise, a value of (off_t)\-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fildes +is not an open file descriptor. +.TP +.B EINVAL +.I whence +is not one of SEEK_SET, SEEK_CUR, SEEK_END, +or the resulting file offset would be negative. +.\" Some systems may allow negative offsets for character devices +.\" and/or for remote filesystems. +.TP +.B EOVERFLOW +The resulting file offset cannot be represented in an off_t. +.TP +.B ESPIPE +.I fildes +is associated with a pipe, socket, or FIFO. +.SH "CONFORMING TO" +SVr4, POSIX, BSD 4.3 +.SH RESTRICTIONS +Some devices are incapable of seeking and POSIX does not specify which +devices must support it. + +Linux specific restrictions: using \fBlseek\fP on a tty device returns +\fBESPIPE\fP. +.\" Other systems return the number of written characters, +.\" using SEEK_SET to set the counter. (Of written characters.) +.SH NOTES +This document's use of +.I whence +is incorrect English, but maintained for historical reasons. + +When converting old code, substitute values for \fIwhence\fP with the +following macros: +.PP +.TS +c c +l l. +old new +0 SEEK_SET +1 SEEK_CUR +2 SEEK_END +L_SET SEEK_SET +L_INCR SEEK_CUR +L_XTND SEEK_END +.TE +.PP +SVR1-3 returns \fBlong\fP instead of \fBoff_t\fP, BSD returns \fBint\fP. +.PP +Note that file descriptors created by +.BR dup (2) +or +.BR fork (2) +share the current file position pointer, so seeking on such files may be +subject to race conditions. +.SH "SEE ALSO" +.BR dup (2), +.BR fork (2), +.BR open (2), +.BR fseek (3) diff --git a/man2/lsetxattr.2 b/man2/lsetxattr.2 new file mode 100644 index 000000000..dc0780751 --- /dev/null +++ b/man2/lsetxattr.2 @@ -0,0 +1 @@ +.so man2/setxattr.2 diff --git a/man2/lstat.2 b/man2/lstat.2 new file mode 100644 index 000000000..b1a86c195 --- /dev/null +++ b/man2/lstat.2 @@ -0,0 +1 @@ +.so man2/stat.2 diff --git a/man2/madvise.2 b/man2/madvise.2 new file mode 100644 index 000000000..c519492fd --- /dev/null +++ b/man2/madvise.2 @@ -0,0 +1,154 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 2001 David Gómez +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Based on comments from mm/filemap.c. Last modified on 10-06-2001 +.\" Modified, 25 Feb 2002, Michael Kerrisk, +.\" Added notes on MADV_DONTNEED +.\" +.TH MADVISE 2 2001-06-10 "Linux 2.4.5" "Linux Programmer's Manual" +.SH NAME +madvise \- give advice about use of memory +.SH SYNOPSIS +.br +.B #include +.sp +.BI "int madvise(void *" start ", size_t " length ", int " advice ); +.SH DESCRIPTION +The +.B madvise +system call advises the kernel about how to handle paging input/output in +the address range beginning at address +.I start +and with size +.I length +bytes. It allows an application to tell the kernel how it expects to use +some mapped or shared memory areas, so that the kernel can choose +appropriate read-ahead and caching techniques. +This call does not influence the semantics of the application +(except in the case of +.BR MADV_DONTNEED ), +but +may influence its performance. The kernel is free to ignore the advice. +.LP +The advice is indicated in the +.I advice +parameter which can be +.TP +.B MADV_NORMAL +No special treatment. This is the default. +.TP +.B MADV_RANDOM +Expect page references in random order. +(Hence, read ahead may be less useful than normally.) +.TP +.B MADV_SEQUENTIAL +Expect page references in sequential order. +(Hence, pages in the given range can be aggressively read ahead, +and may be freed soon after they are accessed.) +.TP +.B MADV_WILLNEED +Expect access in the near future. +(Hence, it might be a good idea to read some pages ahead.) +.TP +.B MADV_DONTNEED +Do not expect access in the near future. +(For the time being, the application is finished with the given range, +so the kernel can free resources associated with it.) +Subsequent accesses of pages in this range will succeed, but will result +either in re-loading of the memory contents from the underlying mapped file +(see \fBmmap\fP) or zero-fill-on-demand pages for mappings +without an underlying file. +.SH "RETURN VALUE" +On success +.B madvise +returns zero. On error, it returns \-1 and +.I errno +is set appropiately. +.SH ERRORS +.TP +.B EAGAIN +A kernel resource was temporarily unavailable. +.TP +.B EBADF +The map exists, but the area maps something that isn't a file. +.TP +.B EINVAL +The value +.IR len +is negative, +.\" .I len +.\" is zero, +.I start +is not page-aligned, +.I advice +is not a valid value, or the application is attempting +to release locked or shared pages (with MADV_DONTNEED). +.TP +.B EIO +(for MADV_WILLNEED) Paging in this area would exceed the process's +maximum resident set size. +.TP +.B ENOMEM +(for MADV_WILLNEED) Not enough memory - paging in failed. +.TP +.B ENOMEM +Addresses in the specified range are not currently +mapped, or are outside the address space of the process. +.SH "LINUX NOTES" +.LP +The current Linux implementation (2.4.0) views this system call +more as a command than as advice and hence may return an error +when it cannot do what it usually would do in response to this +advice. (See the ERRORS description above.) +This is nonstandard behaviour. +.LP +The Linux implementation requires that the address +.I start +be page-aligned, and allows +.I length +to be zero. If there are some parts of the specified address range +that are not mapped, the Linux version of +.B madvise +ignores them and applies the call to the rest (but returns +.B ENOMEM +from the system call, as it should). +.SH HISTORY +The +.B madvise +function first appeared in 4.4BSD. +.SH "CONFORMING TO" +POSIX.1b (POSIX.4). +POSIX 1003.1-2001 describes +.B posix_madvise +with constants POSIX_MADV_NORMAL, etc., +with a behaviour close to that described here. There is a similar +.I posix_fadvise +for file access. +.SH "SEE ALSO" +.BR getrlimit (2), +.BR mincore (2), +.BR mmap (2), +.BR mprotect (2), +.BR msync (2), +.BR munmap (2) diff --git a/man2/mincore.2 b/man2/mincore.2 new file mode 100644 index 000000000..4ca045a1c --- /dev/null +++ b/man2/mincore.2 @@ -0,0 +1,129 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 2001 Bert Hubert +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Created Sun Jun 3 17:23:32 2001 by bert hubert +.\" Slightly adapted, following comments by Hugh Dickins, aeb, 2001-06-04. +.\" Modified, 20 May 2003, Michael Kerrisk +.\" Modified, 30 Apr 2004, Michael Kerrisk +.\" +.TH MINCORE 2 2004-04-30 "Linux 2.6.5" "Linux Programmer's Manual" +.SH NAME +mincore \- get information on whether pages are in core +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int mincore(void *" start ", size_t " length ", unsigned char *" vec ); +.SH DESCRIPTION +The +.B mincore +function requests a vector describing which pages of a file are in core and +can be read without disk access. The kernel will supply data for +.I length +bytes following the +.I start +address. On return, the kernel will have filled +.I vec +with bytes, of which the least significant bit indicates if a page is +core resident. (The other bits are undefined, reserved for possible +later use.) +Of course this is only a snapshot - pages that are not +locked in core can come and go any moment, and the contents of +.I vec +may be stale already when this call returns. + +For +.B mincore +to return successfully, +.I start +must lie on a page boundary. It is the caller's responsibility to +round up to the nearest page. The +.I length +parameter need not be a multiple of the page size. The vector +.I vec +must be large enough to contain (length+PAGE_SIZE-1) / PAGE_SIZE bytes. +One may obtain the page size from +.BR getpagesize (2). + +.SH "RETURN VALUE" +On success, +.B mincore +returns zero. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.B EAGAIN +kernel is temporarily out of resources +.TP +.B EFAULT +.I vec +points to an invalid address +.TP +.B EINVAL +.I start +is not a multiple of the page size, or +.I len +has a non-positive value +.TP +.B ENOMEM +.I address +to +.I address ++ +.I length +contained unmapped memory, or memory not part of a file. + +.SH BUGS +Up to now (Linux 2.6.5), +.B mincore +does not return correct information for MAP_PRIVATE mappings. + +.\" Linux (up to now, 2.6.5), +.\" .B mincore +.\" does not return correct information for MAP_PRIVATE mappings: +.\" for a MAP_PRIVATE file mapping, +.\" .B mincore +.\" returns the residency of the file pages, rather than any +.\" modified process-private pages that have been copied on write; +.\" for a MAP_PRIVATE mapping of +.\" .IR /dev/zero , +.\" .B mincore +.\" always reports pages as non-resident; +.\" and for a MAP_PRIVATE, MAP_ANONYMOUS mapping, +.\" .B mincore +.\" always fails with the error +.\" .BR ENOMEM . +.SH "CONFORMING TO" +.B mincore +does not appear to be part of POSIX or the Single Unix Specification. +.SH HISTORY +The mincore() function first appeared in 4.4BSD. +.SH AVAILABILITY +Since Linux 2.3.99pre1 and glibc 2.2. +.SH "SEE ALSO" +.BR getpagesize (2), +.BR mlock (2), +.BR mmap (2) diff --git a/man2/mkdir.2 b/man2/mkdir.2 new file mode 100644 index 000000000..d02811f3e --- /dev/null +++ b/man2/mkdir.2 @@ -0,0 +1,127 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt +.\" 1993,1994 Ian Jackson. +.\" You may distribute it under the terms of the GNU General +.\" Public Licence. It comes with NO WARRANTY. +.\" +.TH MKDIR 2 2003-12-09 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +mkdir \- create a directory +.SH SYNOPSIS +.nf +.B #include +.B #include +.\" .B #include +.sp +.BI "int mkdir(const char *" pathname ", mode_t " mode ); +.fi +.SH DESCRIPTION +.B mkdir +attempts to create a directory named +.IR pathname . + +The parameter +.I mode +specifies the permissions to use. It is modified by the process's +.I umask +in the usual way: the permissions of the created directory are +.RI ( mode " & ~" umask " & 0777)." +Other mode bits of the created directory depend on the operating system. +For Linux, see below. + +The newly created directory will be owned by the effective user ID of the +process. If the directory containing the file has the set group ID +bit set, or if the filesystem is mounted with BSD group semantics, the +new directory will inherit the group ownership from its parent; +otherwise it will be owned by the effective group ID of the process. + +If the parent directory has the set group ID bit set then so will the +newly created directory. + +.SH "RETURN VALUE" +.BR mkdir +returns zero on success, or \-1 if an error occurred (in which case, +.I errno +is set appropriately). +.SH ERRORS +.TP +.B EACCES +The parent directory does not allow write permission to the process, +or one of the directories in +.IR pathname +did not allow search permission. +(See also +.BR path_resolution (2).) +.TP +.B EEXIST +.I pathname +already exists (not necessarily as a directory). +This includes the case where +.I pathname +is a symbolic link, dangling or not. +.TP +.B EFAULT +.IR pathname " points outside your accessible address space." +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.IR pathname " was too long." +.TP +.B ENOENT +A directory component in +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The device containing +.I pathname +has no room for the new directory. +.TP +.B ENOSPC +The new directory cannot be created because the user's disk quota is +exhausted. +.TP +.B ENOTDIR +A component used as a directory in +.I pathname +is not, in fact, a directory. +.TP +.B EPERM +The filesystem containing +.IR pathname +does not support the creation of directories. +.TP +.B EROFS +.I pathname +refers to a file on a read-only filesystem. +.SH "CONFORMING TO" +SVr4, POSIX, BSD, SYSV, X/OPEN. SVr4 documents additional EIO, EMULTIHOP +and ENOLINK error conditions; POSIX.1 omits ELOOP. +.SH NOTES +Under Linux apart from the permission bits, only the S_ISVTX mode bit +is honored. That is, under Linux the created directory actually gets mode +.RI ( mode " & ~" umask " & 01777)." +See also +.BR stat (2). +.PP +There are many infelicities in the protocol underlying NFS. Some +of these affect +.BR mkdir . +.SH "SEE ALSO" +.BR mkdir (1), +.BR chmod (2), +.BR mknod (2), +.BR mount (2), +.BR path_resolution (2), +.BR rmdir (2), +.BR stat (2), +.BR umask (2), +.BR unlink (2) diff --git a/man2/mknod.2 b/man2/mknod.2 new file mode 100644 index 000000000..e59505fe0 --- /dev/null +++ b/man2/mknod.2 @@ -0,0 +1,177 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt +.\" 1993,1994 Ian Jackson. +.\" You may distribute it under the terms of the GNU General +.\" Public Licence. It comes with NO WARRANTY. +.\" +.\" Modified 1996-08-18 by urs +.\" Modified 2003-04-23 by Michael Kerrisk +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH MKNOD 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +mknod \- create a special or ordinary file +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.B #include +.sp +.BI "int mknod(const char *" pathname ", mode_t " mode ", dev_t " dev ); +.fi +.SH DESCRIPTION +The system call +.B mknod +creates a filesystem node (file, device special file or +named pipe) named +.IR pathname , +with attributes specified by +.I mode +and +.IR dev . + +The +.I mode +argument specifies both the permissions to use and the type of node +to be created. +It should be a combination (using bitwise OR) of one of the file types +listed below and the permissions for the new node. + +The permissions are modified by the process's +.BR umask +in the usual way: the permissions of the created node are +.BR "(mode & ~umask)" . + +The file type must be one of +.BR S_IFREG , +.BR S_IFCHR , +.BR S_IFBLK , +.BR S_IFIFO +or +.BR S_IFSOCK +.\" (S_IFSOCK since Linux 1.2.4) +to specify a normal file (which will be created empty), character +special file, block special file, FIFO (named pipe), or Unix domain socket, +respectively. +(Zero file type is equivalent to type S_IFREG.) + +If the file type is +.BR S_IFCHR " or " S_IFBLK +then +.I dev +specifies the major and minor numbers of the newly created device +special file; otherwise it is ignored. + +If +.I pathname +already exists, or is a symbolic link, this call fails with an EEXIST error. + +The newly created node will be owned by the effective user ID of the +process. If the directory containing the node has the set group ID +bit set, or if the filesystem is mounted with BSD group semantics, the +new node will inherit the group ownership from its parent directory; +otherwise it will be owned by the effective group ID of the process. +.SH "RETURN VALUE" +.BR mknod +returns zero on success, or \-1 if an error occurred (in which case, +.I errno +is set appropriately). +.SH ERRORS +.TP +.B EACCES +The parent directory does not allow write permission to the process, +or one of the directories in the path prefix of +.IR pathname +did not allow search permission. +(See also +.BR path_resolution (2).) +.TP +.B EEXIST +.I pathname +already exists. +.TP +.B EFAULT +.IR pathname " points outside your accessible address space." +.TP +.B EINVAL +.I mode +requested creation of something other than a normal file, device +special file, FIFO or socket. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.IR pathname " was too long." +.TP +.B ENOENT +A directory component in +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The device containing +.I pathname +has no room for the new node. +.TP +.B ENOTDIR +A component used as a directory in +.I pathname +is not, in fact, a directory. +.TP +.B EPERM +.I mode +requested creation of something other than a regular file, +FIFO (named pipe), or Unix domain socket, and the caller +is not privileged (Linux: does not have the +.B CAP_MKNOD +capability); also returned if the filesystem containing +.I pathname +does not support the type of node requested. +.TP +.B EROFS +.I pathname +refers to a file on a read-only filesystem. +.SH "CONFORMING TO" +SVr4 (but the call requires privilege and is thus not in POSIX), +4.4BSD. The Linux version differs from the SVr4 version in that it +does not require root permission to create pipes, also in that no +EMULTIHOP, ENOLINK, or EINTR error is documented. +.SH NOTES +POSIX 1003.1-2001 says: "The only portable use of +.BR mknod () +is to create a FIFO-special file. If +.I mode +is not S_IFIFO or +.I dev +is not 0, the behavior of +.BR mknod () +is unspecified." + +Under Linux, this call cannot be used to create directories. +One should make directories with +.BR mkdir , +and FIFOs with +.BR mkfifo . +.\" Unix domain sockets with .BR socket " (and " bind ), + +There are many infelicities in the protocol underlying NFS. Some +of these affect +.BR mknod . +.SH "SEE ALSO" +.BR fcntl (2), +.BR mkdir (2), +.BR mount (2), +.BR path_resolution (2), +.BR socket (2), +.BR stat (2), +.BR umask (2), +.BR unlink (2), +.BR mkfifo (3) diff --git a/man2/mlock.2 b/man2/mlock.2 new file mode 100644 index 000000000..fc0caac31 --- /dev/null +++ b/man2/mlock.2 @@ -0,0 +1,146 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) Markus Kuhn, 1996 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 1995-11-26 Markus Kuhn +.\" First version written +.\" 2003-07-09 Michael Kerrisk +.\" Added note on suspend mode on laptops +.\" +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH MLOCK 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +mlock \- disable paging for some parts of memory +.SH SYNOPSIS +.nf +.B #include +.sp +\fBint mlock(const void *\fIaddr\fB, size_t \fIlen\fB); +.fi +.SH DESCRIPTION +.B mlock +disables paging for the memory in the range starting at +.I addr +with length +.I len +bytes. All pages which contain a part of the specified memory range +are guaranteed be resident in RAM when the +.B mlock +system call returns successfully and they are guaranteed to stay in RAM +until the pages are unlocked by +.B munlock +or +.BR munlockall , +until the pages are unmapped via +.BR munmap , +or until the process terminates or starts another program with +.BR exec . +Child processes do not inherit page locks across a +.BR fork . + +Memory locking has two main applications: real-time algorithms and +high-security data processing. Real-time applications require +deterministic timing, and, like scheduling, paging is one major cause +of unexpected program execution delays. Real-time applications will +usually also switch to a real-time scheduler with +.BR sched_setscheduler . +Cryptographic security software often handles critical bytes like +passwords or secret keys as data structures. As a result of paging, +these secrets could be transferred onto a persistent swap store medium, +where they might be accessible to the enemy long after the security +software has erased the secrets in RAM and terminated. +(But be aware that the suspend mode on laptops and some desktop +computers will save a copy of the system's RAM to disk, regardless +of memory locks.) + +Memory locks do not stack, i.e., pages which have been locked several times +by calls to +.B mlock +or +.B mlockall +will be unlocked by a single call to +.B munlock +for the corresponding range or by +.BR munlockall . +Pages which are mapped to several locations or by several processes stay +locked into RAM as long as they are locked at least at one location or by +at least one process. + +On POSIX systems on which +.B mlock +and +.B munlock +are available, +.B _POSIX_MEMLOCK_RANGE +is defined in and the value +.B PAGESIZE +from indicates the number of bytes per page. +.SH NOTES +With the Linux system call, +.I addr +is automatically rounded down to the nearest page boundary. +However, POSIX 1003.1-2001 allows an implementation to require that +.I addr +is page aligned, so portable applications should ensure this. +.SH "RETURN VALUE" +On success, +.B mlock +returns zero. On error, \-1 is returned, +.I errno +is set appropriately, and no changes are made to any locks in the +address space of the process. +.SH ERRORS +.TP +.B EINVAL +(Not on Linux) +.I addr +was not a multiple of the page size. +.TP +.B ENOMEM +Some of the specified address range does not correspond to mapped +pages in the address space of the process or the process tried to +exceed the maximum number of allowed locked pages. +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR mlock . +Under Linux the +.B CAP_IPC_LOCK +capability is required. +.LP +Linux adds +.TP +.B EINVAL +.I len +was negative. +.SH "CONFORMING TO" +POSIX.1b, SVr4. SVr4 documents an additional EAGAIN error code. +.SH "SEE ALSO" +.BR mlockall (2), +.BR munlock (2), +.BR munlockall (2), +.BR munmap (2), +.BR setrlimit (2), +.BR capabilities (7) diff --git a/man2/mlockall.2 b/man2/mlockall.2 new file mode 100644 index 000000000..826fb71ce --- /dev/null +++ b/man2/mlockall.2 @@ -0,0 +1,156 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) Markus Kuhn, 1996 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 1995-11-26 Markus Kuhn +.\" First version written +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH MLOCKALL 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +mlockall \- disable paging for calling process +.SH SYNOPSIS +.nf +.B #include +.sp +\fBint mlockall(int \fIflags\fB); +.fi +.SH DESCRIPTION +.B mlockall +disables paging for all pages mapped into the address space of the +calling process. This includes the pages of the code, data and stack +segment, as well as shared libraries, user space kernel data, shared +memory and memory mapped files. All mapped pages are guaranteed to be +resident in RAM when the +.B mlockall +system call returns successfully and they are guaranteed to stay in RAM +until the pages are unlocked again by +.B munlock +or +.B munlockall +or until the process terminates or starts another program with +.BR exec . +Child processes do not inherit page locks across a +.BR fork . + +Memory locking has two main applications: real-time algorithms and +high-security data processing. Real-time applications require +deterministic timing, and, like scheduling, paging is one major cause +of unexpected program execution delays. Real-time applications will +usually also switch to a real-time scheduler with +.BR sched_setscheduler . +Cryptographic security software often handles critical bytes like +passwords or secret keys as data structures. As a result of paging, +these secrets could be transfered onto a persistent swap store medium, +where they might be accessible to the enemy long after the security +software has erased the secrets in RAM and terminated. For security +applications, only small parts of memory have to be locked, for which +.B mlock +is available. + +The +.I flags +parameter can be constructed from the bitwise OR of the following +constants: +.TP 1.2i +.B MCL_CURRENT +Lock all pages which are currently mapped into the address space of +the process. +.TP +.B MCL_FUTURE +Lock all pages which will become mapped into the address space of the +process in the future. These could be for instance new pages required +by a growing heap and stack as well as new memory mapped files or +shared memory regions. +.PP +If +.B MCL_FUTURE +has been specified and the number of locked pages exceeds the upper +limit of allowed locked pages, then the system call which caused the +new mapping will fail with +.BR ENOMEM . +If these new pages have been mapped by the the growing stack, then the +kernel will deny stack expansion and send a +.BR SIGSEGV . + +Real-time processes should reserve enough locked stack pages before +entering the time-critical section, so that no page fault can be +caused by function calls. This can be achieved by calling a function +which has a sufficiently large automatic variable and which writes to +the memory occupied by this large array in order to touch these stack +pages. This way, enough pages will be mapped for the stack and can be +locked into RAM. The dummy writes ensure that not even copy-on-write +page faults can occur in the critical section. + +Memory locks do not stack, i.e., pages which have been locked several times +by calls to +.B mlockall +or +.B mlock +will be unlocked by a single call to +.BR munlockall . +Pages which are mapped to several locations or by several processes stay +locked into RAM as long as they are locked at least at one location or by +at least one process. +.SH "RETURN VALUE" +On success, +.B mlockall +returns zero. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +Unknown flags were specified. +.TP +.B ENOMEM +The process tried to exceed the maximum number of allowed locked +pages. +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR mlockall . +Under Linux the +.B CAP_IPC_LOCK +capability is required. +.SH AVAILABILITY +On POSIX systems on which +.B mlockall +and +.B munlockall +are available, +.B _POSIX_MEMLOCK +is defined in to a value greater than 0. (See also +.BR sysconf (3).) +.\" POSIX 1003.1-2001: It shall be defined to -1 or 0 or 200112L. +.\" -1: unavailable, 0: ask using sysconf(). +.\" glibc defines it to 1. +.SH "CONFORMING TO" +POSIX.1b, SVr4. SVr4 documents an additional EAGAIN error code. +.SH "SEE ALSO" +.BR mlock (2), +.BR munlock (2), +.BR munlockall (2), +.BR sysconf (3), +.BR capabilities (7) diff --git a/man2/mmap.2 b/man2/mmap.2 new file mode 100644 index 000000000..6b339e803 --- /dev/null +++ b/man2/mmap.2 @@ -0,0 +1,346 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2000-03-25 by Jim Van Zandt +.\" Modified 2001-10-04 by John Levon +.\" Modified 2003-02-02 by Andi Kleen +.\" Modified 2003-05-21 by Michael Kerrisk +.\" MAP_LOCKED works from 2.5.37 +.\" Modified 2004-06-17 by Michael Kerrisk +.\" Modified 2004-09-11 by aeb +.\" +.TH MMAP 2 2004-09-11 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +mmap, munmap \- map or unmap files or devices into memory +.SH SYNOPSIS +.B #include +.sp +.BI "void * mmap(void *" start ", size_t " length ", int " prot +.BI ", int " flags ", int " fd ", off_t " offset ); +.sp +.BI "int munmap(void *" start ", size_t " length ); +.SH DESCRIPTION +The +.B mmap +function asks to map +.I length +bytes starting at offset +.I offset +from the file (or other object) specified by the file descriptor +.I fd +into memory, preferably at address +.IR start . +This latter address is a hint only, and is usually specified as 0. +The actual place where the object is mapped is returned by +.BR mmap , +and is never 0. +.LP +The +.I prot +argument describes the desired memory protection (and must not +conflict with the open mode of the file). It is either +.B PROT_NONE +or is the bitwise OR of one or more of the other PROT_* flags. +.TP 1.1i +.B PROT_EXEC +Pages may be executed. +.TP +.B PROT_READ +Pages may be read. +.TP +.B PROT_WRITE +Pages may be written. +.TP +.B PROT_NONE +Pages may not be accessed. +.LP +The +.I flags +parameter specifies the type of the mapped object, mapping options and +whether modifications made to the mapped copy of the page are private to +the process or are to be shared with other references. It has bits +.TP 1.1i +.B MAP_FIXED +Do not select a different address than the one specified. +If the specified address cannot be used, +.B mmap +will fail. If MAP_FIXED is specified, +.I start +must be a multiple of the pagesize. Use of this option is discouraged. +.TP +.B MAP_SHARED +Share this mapping with all other processes that map this object. +Storing to the region is equivalent to writing to the file. +The file may not actually be updated until +.BR msync (2) +or +.BR munmap (2) +are called. +.TP +.B MAP_PRIVATE +Create a private copy-on-write mapping. +Stores to the region do not affect the original file. +It is unspecified whether changes made to the file after the +.B mmap +call are visible in the mapped region. +.LP +You must specify exactly one of MAP_SHARED and MAP_PRIVATE. +.LP +The above three flags are described in POSIX.1b (formerly POSIX.4) and SUSv2. +Linux also knows about the following non-standard flags: +.TP +.B MAP_DENYWRITE +This flag is ignored. +.\" Introduced in 1.1.36, removed in 1.3.24. +(Long ago, it signalled that attempts to write to the underlying file +should fail with ETXTBUSY. But this was a source of denial-of-service attacks.) +.TP +.B MAP_EXECUTABLE +This flag is ignored. +.\" Introduced in 1.1.38, removed in 1.3.24. Flag tested in proc_follow_link. +.\" (Long ago, it signalled that the underlying file is an executable. +.\" However, that information was not really used anywhere.) +.\" Linus talked about DOS related to MAP_EXECUTABLE, but he was thinking of +.\" MAP_DENYWRITE? +.TP +.B MAP_NORESERVE +(Used together with MAP_PRIVATE.) Do not reserve swap space pages for +this mapping. When swap space is reserved, one has the guarantee +that it is possible to modify this private copy-on-write region. +When it is not reserved one might get SIGSEGV upon a write +when no memory is available. +.TP +.BR MAP_LOCKED " (since Linux 2.5.37)" +Lock the pages of the mapped region into memory in the manner of +.BR mlock() . +This flag is ignored in older kernels. +.\" If set, the mapped pages will not be swapped out. +.TP +.B MAP_GROWSDOWN +Used for stacks. Indicates to the kernel VM system that the mapping +should extend downwards in memory. +.TP +.B MAP_ANONYMOUS +The mapping is not backed by any file; the +.I fd +and +.I offset +arguments are ignored. This flag in conjunction with MAP_SHARED +is implemented since Linux 2.4. +.TP +.B MAP_ANON +Alias for MAP_ANONYMOUS. Deprecated. +.TP +.B MAP_FILE +Compatibility flag. Ignored. +.TP +.B MAP_32BIT +Put the mapping into the first 2GB of the process address space. +Ignored when +.I MAP_FIXED +is set. This flag is currently only supported on x86-64 for 64bit programs. +.TP +.BR MAP_POPULATE " (since Linux 2.5.46)" +Populate (prefault) pagetables. +.TP +.BR MAP_NONBLOCK " (since Linux 2.5.46)" +Do not block on IO. +.LP +Some systems document the additional flags MAP_AUTOGROW, MAP_AUTORESRV, +MAP_COPY, and MAP_LOCAL. +.LP +.I fd +should be a valid file descriptor, unless MAP_ANONYMOUS is set, +in which case the argument is ignored. +.LP +.I offset +should be a multiple of the page size as returned by +.BR getpagesize (2). +.LP +Memory mapped by +.B mmap +is preserved across +.BR fork (2), +with the same attributes. +.LP +A file is mapped in multiples of the page size. For a file that is not +a multiple of the page size, the remaining memory is zeroed when mapped, +and writes to that region are not written out to the file. The effect of +changing the size of the underlying file of a mapping on the pages that +correspond to added or removed regions of the file is unspecified. + +The +.B munmap +system call deletes the mappings for the specified address range, and +causes further references to addresses within the range to generate +invalid memory references. The region is also automatically unmapped +when the process is terminated. On the other hand, closing the file +descriptor does not unmap the region. +.LP +The address +.I start +must be a multiple of the page size. All pages containing a part +of the indicated range are unmapped, and subsequent references +to these pages will generate SIGSEGV. It is not an error if the +indicated range does not contain any mapped pages. + +For file-backed mappings, the +.B st_atime +field for the mapped file may be updated at any time between the +.B mmap() +and the corresponding unmapping; the first reference to a mapped +page will update the field if it has not been already. +.LP +The +.B st_ctime +and +.B st_mtime +field for a file mapped with PROT_WRITE and MAP_SHARED will be updated after +a write to the mapped region, and before a subsequent +.I msync() +with the MS_SYNC or MS_ASYNC flag, if one occurs. +.SH "RETURN VALUE" +On success, +.B mmap +returns a pointer to the mapped area. +On error, the value +.B MAP_FAILED +(that is, (void *) \-1) is returned, and +.I errno +is set appropriately. +On success, +.B munmap +returns 0, on failure \-1, and +.I errno +is set (probably to EINVAL). +.SH NOTES +It is architecture dependent whether +.I PROT_READ +includes +.I PROT_EXEC +or not. Portable programs should always set +.I PROT_EXEC +if they intend to execute code in the new mapping. +.SH ERRORS +.TP +.B EACCES +A file descriptor refers to a non-regular file. +Or MAP_PRIVATE was requested, but +.I fd +is not open for reading. +Or MAP_SHARED was requested and PROT_WRITE is set, but +.I fd +is not open in read/write (O_RDWR) mode. +Or PROT_WRITE is set, but the file is append-only. +.TP +.B EAGAIN +The file has been locked, or too much memory has been locked. +.TP +.B EBADF +.I fd +is not a valid file descriptor (and MAP_ANONYMOUS was not set). +.TP +.B EINVAL +We don't like +.I start +or +.I length +or +.IR offset . +(E.g., they are too large, or not aligned on a PAGESIZE boundary.) +.\" jbl - not sure this actually happens ? see generic_file_mmap +.TP +.B ENFILE +.\" This is for shared anonymous segments +.\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp() +The system limit on the total number of open files has been reached. +.\" .TP +.\" .B ENOEXEC +.\" A file could not be mapped for reading. +.TP +.B ENODEV +The underlying filesystem of the specified file does not support +memory mapping. +.TP +.B ENOMEM +No memory is available, or the process's maximum number of mappings would +have been exceeded. +.TP +.B EPERM +The +.I prot +argument asks for +.B PROT_EXEC +but the mapped area belongs to a file on a filesystem that +was mounted no-exec. +.\" (Since 2.4.25 / 2.6.0.) +.TP +.B ETXTBSY +MAP_DENYWRITE was set but the object specified by +.I fd +is open for writing. +.LP +Use of a mapped region can result in these signals: +.TP +.B SIGSEGV +Attempted write into a region specified to mmap as read-only. +.TP +.B SIGBUS +Attempted access to a portion of the buffer that does not correspond +to the file (for example, beyond the end of the file, including the +case where another process has truncated the file). +.SH AVAILABILITY +On POSIX systems on which +.BR mmap , +.B msync +and +.B munmap +are available, +.B _POSIX_MAPPED_FILES +is defined in to a value greater than 0. (See also +.BR sysconf (3).) +.\" POSIX 1003.1-2001: It shall be defined to -1 or 0 or 200112L. +.\" -1: unavailable, 0: ask using sysconf(). +.\" glibc defines it to 1. +.SH "CONFORMING TO" +SVr4, POSIX.1b (formerly POSIX.4), 4.4BSD, SUSv2. +SVr4 documents additional error codes ENXIO and ENODEV. +SUSv2 documents additional error codes EMFILE and EOVERFLOW. +.SH BUGS +On Linux there are no guarantees like those suggested above +under MAP_NORESERVE. By default, any process can be killed +at any moment when the system runs out of memory. +.SH "SEE ALSO" +.BR getpagesize (2), +.BR mlock (2), +.BR mmap2 (2), +.BR mremap (2), +.BR msync (2), +.BR shm_open (2) +.br +B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129 and 389-391. +.\" +.\" Repeat after me: private read-only mappings are 100% equivalent to +.\" shared read-only mappings. No ifs, buts, or maybes. -- Linus diff --git a/man2/mmap2.2 b/man2/mmap2.2 new file mode 100644 index 000000000..b9cbc591e --- /dev/null +++ b/man2/mmap2.2 @@ -0,0 +1,77 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 2002, Michael Kerrisk +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 31 Jan 2002, Michael Kerrisk +.\" Added description of mmap2 +.\" +.TH MMAP2 2 2002-01-31 "Linux 2.3.31" "Linux Programmer's Manual" +.SH NAME +mmap2 \- map files or devices into memory +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "_syscall6(void *, " start ", size_t, " length ", int, " prot , +.BI "int, " flags ", int, " fd ", off_t, " pgoffset ); +.sp +.BI "void * mmap2(void *" start ", size_t " length ", int " prot , +.BI "int " flags ", int " fd ", off_t " pgoffset ); +.sp +.B #endif +.SH DESCRIPTION +The function +.B mmap2 +operates in exactly the same way as +.BR mmap (2), +except that the final argument specifies the offset into the +file in units of the system page size (instead of bytes). +This enables applications that use a 32-bit off_t to map +larger files (typically up to 2^44 bytes). +.SH "RETURN VALUE" +On success, +.B mmap2 +returns a pointer to the mapped area. On error -1 is returned +and +.I errno +is set appropriately. +.SH ERRORS +.TP +.SH EFAULT +Problem with getting the +data from userspace. +.SH NOTES +The function +.B mmap2 +is available since Linux 2.3.31. +It is Linux specific, and should be avoided in portable applications. +See also the +.I mmap64() +function that is part of the LFS (Large File Summit). +.SH "SEE ALSO" +.BR getpagesize (2), +.BR mmap (2), +.BR mremap (2), +.BR msync (2), +.BR shm_open (2) diff --git a/man2/modify_ldt.2 b/man2/modify_ldt.2 new file mode 100644 index 000000000..e684c3665 --- /dev/null +++ b/man2/modify_ldt.2 @@ -0,0 +1,104 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1995 Michael Chastain (mec@duracef.shout.net), 22 July 1995. +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH MODIFY_LDT 2 1995-07-22 "Linux 1.3.6" "Linux Programmer's Manual" +.SH NAME +modify_ldt \- get or set ldt +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "_syscall3(int, modify_ldt, int, " func ", void *, " ptr ", unsigned long, " bytecount ) +.sp +.BI "int modify_ldt(int " "func" ", void *" "ptr" ", unsigned long " "bytecount" ); +.SH DESCRIPTION +.B modify_ldt +reads or writes the local descriptor table (ldt) for a process. +The ldt is a per-process memory management table used by the i386 processor. +For more information on this table, see an Intel 386 processor handbook. +.PP +When +.I func +is 0, +.B modify_ldt +reads the ldt into the memory pointed to by +.IR ptr . +The number of bytes read is the smaller of +.I bytecount +and the actual size of the ldt. +.PP +When +.I func +is 1, +.B modify_ldt +modifies one ldt entry. +.I ptr +points to a +.I modify_ldt_ldt_s +structure and +.I bytecount +must equal the size of this structure. +.\" .PP +.\" The ldt is specific for the calling process. Any attempts to change +.\" the ldt to include the address space of another process or the kernel +.\" will result in a segmentation violation when trying to access the memory +.\" outside of the process address space. The memory protection is enforced +.\" at the paging layer. +.SH "RETURN VALUE" +On success, +.B modify_ldt +returns either the actual number of bytes read (for reading) +or 0 (for writing). +On failure, +.B modify_ldt +returns \-1 and sets +.IR errno . +.SH ERRORS +.TP +.B EFAULT +.I ptr +points outside the address space. +.TP +.B EINVAL +.I ptr +is 0, +or +.I func +is 1 and +.I bytecount +is not equal to the size of the structure +.IR modify_ldt_ldt_s , +or +.I func +is 1 and the new ldt entry has invalid values. +.TP +.B ENOSYS +.I func +is neither 0 nor 1. +.SH "CONFORMING TO" +This call in Linux-specific and should not be used in programs intended +to be portable. +.SH "SEE ALSO" +.BR vm86 (2) diff --git a/man2/mount.2 b/man2/mount.2 new file mode 100644 index 000000000..ef15ec5d4 --- /dev/null +++ b/man2/mount.2 @@ -0,0 +1,323 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 1993 Rickard E. Faith +.\" Copyright (C) 1994 Andries E. Brouwer +.\" Copyright (C) 2002 Michael Kerrisk +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1996-11-04 by Eric S. Raymond +.\" Modified 2001-10-13 by Michael Kerrisk +.\" Added note on historical behaviour of MS_NOSUID +.\" Modified 2002-05-16 by Michael Kerrisk +.\" Extensive changes and additions +.\" Modified 2002-05-27 by aeb +.\" Modified 2002-06-11 by Michael Kerrisk +.\" Enhanced descriptions of MS_MOVE, MS_BIND, and MS_REMOUNT +.\" Modified 2004-06-17 by Michael Kerrisk +.\" +.TH MOUNT 2 2004-06-17 "Linux 2.6" "Linux Programmer's Manual" +.SH NAME +mount, umount \- mount and unmount filesystems +.SH SYNOPSIS +.B "#include " +.sp +.BI "int mount(const char *" source ", const char *" target , +.BI "const char *" filesystemtype ", unsigned long " mountflags , +.BI "const void *" data ); +.sp +.BI "int umount(const char *" target ); +.sp +.BI "int umount2(const char *" target ", int " flags ); +.SH DESCRIPTION +.B mount +attaches the filesystem specified by +.I source +(which is often a device name, but can also be a directory name +or a dummy) to the directory specified by +.IR target . + +.BR umount " and " umount2 +remove the attachment of the (topmost) filesystem mounted on +.IR target . + +Appropriate privilege (Linux: the +.B CAP_SYS_ADMIN +capability) is required to mount and unmount filesystems. + +Since Linux 2.4 a single filesystem can be visible at +multiple mount points, and multiple mounts can be stacked +on the same mount point. +.\" Multiple mounts on same mount point: since 2.3.99pre7. + +Values for the +.IR filesystemtype +argument supported by the kernel are listed in +.I /proc/filesystems +(like "minix", "ext2", "msdos", "proc", "nfs", "iso9660" etc.). +Further types may become available when the appropriate modules +are loaded. + +The +.IR mountflags +argument may have the magic number 0xC0ED (\fBMS_MGC_VAL\fP) +in the top 16 bits (this was required in kernel versions prior to 2.4, but +is no longer required and ignored if specified), +and various mount flags (as defined in for libc4 and libc5 +and in for glibc2) in the low order 16 bits: +.TP +.B MS_BIND +(Linux 2.4 onwards) +.\" since 2.4.0-test9 +Perform a bind mount, making a file or a directory subtree visible at +another point within a file system. +Bind mounts may cross file system boundaries and span +.BR chroot (2) +jails. +The +.IR filesystemtype ", " mountflags ", and " data +arguments are ignored. +.\" with the exception of the "hidden" MS_REC mountflags bit +.TP +.B MS_DIRSYNC +(Since Linux 2.5.19.) +Make directory changes on this file system synchronous. +(This property can be obtained for individual directories +or subtrees using +.BR chattr (8).) +.TP +.B MS_MANDLOCK +Permit mandatory locking on files in this file system. +(Mandatory locking must still be enabled on a per-file basis, +as described in +.BR fcntl (2).) +.\" FIXME: More can be said about MS_MOVE +.TP +.B MS_MOVE +Move a subtree. +.I source +specifies an existing mount point and +.I target +specifies the new location. +The move is atomic: at no point is the subtree unmounted. +The +.IR filesystemtype ", " mountflags ", and " data +arguments are ignored. +.TP +.B MS_NOATIME +Do not update access times for (all types of) files on this file system. +.TP +.B MS_NODEV +Do not allow access to devices (special files) on this file system. +.TP +.B MS_NODIRATIME +Do not update access times for directories on this file system. +.TP +.B MS_NOEXEC +Do not allow programs to be executed from this file system. +.\" (Possibly useful for a file system that contains non-Linux executables. +.\" Often used as a security feature, e.g. to make sure that restricted +.\" users cannot execute files uploaded using ftp or so.) +.TP +.B MS_NOSUID +Do not honour set-UID and set-GID bits when executing +programs from this file system. +.\" (This is a security feature to prevent users executing set-UID and +.\" set-GID programs from removable disk devices.) +.TP +.B MS_RDONLY +Mount file system read-only. +.TP +.B MS_REMOUNT +Remount an existing mount. This is allows you to change the +.I mountflags +and +.I data +of an existing mount without having to unmount and remount the file system. +.I source +and +.I target +should be the same values specified in the initial +.BR mount () +call; +.I filesystemtype +is ignored. +.TP +.B MS_SYNCHRONOUS +Make writes on this file system synchronous (as though +the +.B O_SYNC +flag to +.BR open (2) +was specified for all file opens to this file system). +.PP +From Linux 2.4 onwards, the +.BR MS_NODEV ", " MS_NOEXEC ", and " MS_NOSUID +flags are settable on a per-mount point basis. +.PP +The +.IR data +argument is interpreted by the different file systems. +Typically it is a string of comma-separated options +understood by this file system. +See +.BR mount (8) +for details of the options available for each filesystem type. +.PP +.\" Note: the kernel naming differs from the glibc naming +.\" umount2 is the glibc name for what the kernel now calls umount +.\" and umount is the glibc name for oldumount +Linux 2.1.116 added the +.BR umount2 () +system call, which, like +.BR umount (), +unmounts a target, but allows additional +.I flags +controlling the behaviour of the operation: +.TP +.B MNT_FORCE +Force unmount even if busy. +(Since 2.1.116. Only for NFS mounts.) +.TP +.B MNT_DETACH +Perform a lazy unmount: make the mount point unavailable for +new accesses, and actually perform the unmount when the mount point +ceases to be busy. (Since 2.4.11.) +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +The error values given below result from filesystem type independent +errors. Each filesystem type may have its own special errors and its +own special behavior. See the kernel source code for details. + +.TP +.B EACCES +A component of a path was not searchable. (See also +.BR path_resolution (2).) +.br +Or, mounting a read-only filesystem was attempted without giving the +MS_RDONLY flag. +.br +Or, the block device +.I source +is located on a filesystem mounted with the MS_NODEV option. +.\" mtk: Probably: write permission is required for MS_BIND, with +.\" the error EPERM if not present; CAP_DAC_OVERRIDE is required. +.TP +.B EBUSY +.I source +is already mounted. Or, it cannot be remounted read-only, +because it still holds files open for writing. +Or, it cannot be mounted on +.I target +because +.I target +is still busy (it is the working directory of some task, +the mount point of another device, has open files, etc.). +Or, it could not be unmounted because it is busy. +.TP +.B EFAULT +One of the pointer arguments points outside the user address space. +.TP +.B EINVAL +.I source +had an invalid superblock. +Or, a remount was attempted, while +.I source +was not already mounted on +.IR target . +Or, a move was attempted, while +.I source +was not a mount point, or was '/'. +Or, an umount was attempted, while +.I target +was not a mount point. +.TP +.B ELOOP +Too many link encountered during pathname resolution. +Or, a move was attempted, while +.I target +is a descendant of +.IR source . +.TP +.B EMFILE +(In case no block device is required:) +Table of dummy devices is full. +.TP +.B ENAMETOOLONG +A pathname was longer than MAXPATHLEN. +.TP +.B ENODEV +.I Filesystemtype +not configured in the kernel. +.TP +.B ENOENT +A pathname was empty or had a nonexistent component. +.TP +.B ENOMEM +The kernel could not allocate a free page to copy filenames or data into. +.TP +.B ENOTBLK +.I source +is not a block device (and a device was required). +.TP +.B ENOTDIR +The second argument, or a prefix of the first argument, is not +a directory. +.TP +.B ENXIO +The major number of the block device +.I source +is out of range. +.TP +.B EPERM +The caller does not have the required privileges. +.SH "CONFORMING TO" +These functions are Linux-specific and should not be used in +programs intended to be portable. +.SH HISTORY +The original +.B umount +function was called as \fIumount(device)\fP and would return ENOTBLK +when called with something other than a block device. +In Linux 0.98p4 a call \fIumount(dir)\fP was added, in order to +support anonymous devices. +In Linux 2.3.99-pre7 the call \fIumount(device)\fP was removed, +leaving only \fIumount(dir)\fP (since now devices can be mounted +in more than one place, so specifying the device does not suffice). +.LP +The original MS_SYNC flag was renamed MS_SYNCHRONOUS in 1.1.69 +when a different MS_SYNC was added to . +.LP +Before Linux 2.4 an attempt to execute a set-UID or set-GID program +on a filesystem mounted with +.B MS_NOSUID +would fail with +.BR EPERM . +Since Linux 2.4 the set-UID and set-GID bits are just silently ignored +in this case. +.\" The change is in patch-2.4.0-prerelease. +.SH "SEE ALSO" +.BR path_resolution (2), +.BR mount (8), +.BR umount (8) diff --git a/man2/mprotect.2 b/man2/mprotect.2 new file mode 100644 index 000000000..604682203 --- /dev/null +++ b/man2/mprotect.2 @@ -0,0 +1,155 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (C) 1995 Michael Shields . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and author of this work. +.\" +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 1997-05-31 by Andries Brouwer +.\" Modified 2003-08-24 by Andries Brouwer +.\" Modified 2004-08-16 by Andi Kleen +.\" +.TH MPROTECT 2 2003-08-24 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +mprotect \- control allowable accesses to a region of memory +.SH SYNOPSIS +.nf +.B #include +.sp +\fBint mprotect(const void *\fIaddr\fB, size_t \fIlen\fB, int \fIprot\fB); +.fi +.SH DESCRIPTION +The function +.B mprotect +specifies the desired protection for the memory page(s) containing +part or all of the interval [\fIaddr\fP,\fIaddr\fP+\fIlen\fP-1]. +If an access is disallowed by the protection given it, the program receives a +.BR SIGSEGV . +.PP +.I prot +is a bitwise-or of the following values: +.TP 1.1i +.B PROT_NONE +The memory cannot be accessed at all. +.TP +.B PROT_READ +The memory can be read. +.TP +.B PROT_WRITE +The memory can be written to. +.TP +.B PROT_EXEC +The memory can contain executing code. +.PP +The new protection replaces any existing protection. For example, if the +memory had previously been marked \fBPROT_READ\fR, and \fBmprotect\fR +is then called with \fIprot\fR \fBPROT_WRITE\fR, it will no longer +be readable. +.SH "RETURN VALUE" +On success, +.B mprotect +returns zero. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +The memory cannot be given the specified access. This can happen, +for example, if you +.BR mmap (2) +a file to which you have read-only access, then ask +.B mprotect +to mark it +.BR PROT_WRITE . +.TP +.B EFAULT +The memory cannot be accessed. +.TP +.B EINVAL +\fIaddr\fR is not a valid pointer, or not a multiple of PAGESIZE. +.TP +.B ENOMEM +Internal kernel structures could not be allocated. +.SH EXAMPLE +.nf +#include +#include +#include +#include + +#include /* for PAGESIZE */ +#ifndef PAGESIZE +#define PAGESIZE 4096 +#endif + +int +main(void) +{ + char *p; + char c; + + /* Allocate a buffer; it will have the default + protection of PROT_READ|PROT_WRITE. */ + p = malloc(1024+PAGESIZE-1); + if (!p) { + perror("Couldn't malloc(1024)"); + exit(errno); + } + + /* Align to a multiple of PAGESIZE, assumed to be a power of two */ + p = (char *)(((int) p + PAGESIZE-1) & ~(PAGESIZE-1)); + + c = p[666]; /* Read; ok */ + p[666] = 42; /* Write; ok */ + + /* Mark the buffer read-only. */ + if (mprotect(p, 1024, PROT_READ)) { + perror("Couldn't mprotect"); + exit(errno); + } + + c = p[666]; /* Read; ok */ + p[666] = 42; /* Write; program dies on SIGSEGV */ + + exit(0); +} +.fi +.SH "CONFORMING TO" +SVr4, POSIX.1b (formerly POSIX.4). SVr4 defines an additional error +code EAGAIN. The SVr4 error conditions don't map neatly onto Linux's. +POSIX says that +.B mprotect +can be used only on regions of memory obtained from +.BR mmap (2). +.SH NOTES +On Linux it is always legal to call +.B mprotect +on any address in a process' address space (except for the +kernel vsyscall area). In particular it can be used +to change existing code mappings to be writable. + +Whether +.B PROT_EXEC +has any effect different from +.B PROT_READ +is architecture and kernel version dependent. +.SH "SEE ALSO" +.BR mmap (2) diff --git a/man2/mpx.2 b/man2/mpx.2 new file mode 100644 index 000000000..5d25ea6ce --- /dev/null +++ b/man2/mpx.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/mremap.2 b/man2/mremap.2 new file mode 100644 index 000000000..6416395cf --- /dev/null +++ b/man2/mremap.2 @@ -0,0 +1,119 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1996 Tom Bjorkholm +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 1996-04-11 Tom Bjorkholm +.\" First version written (1.3.86) +.\" 1996-04-12 Tom Bjorkholm +.\" Update for Linux 1.3.87 and later +.\" +.TH MREMAP 2 1996-04-12 "Linux 1.3.87" "Linux Programmer's Manual" +.SH NAME +mremap \- re-map a virtual memory address +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "void * mremap(void *" old_address ", size_t " old_size +.BI ", size_t " new_size ", unsigned long " flags ); +.fi +.SH DESCRIPTION +\fBmremap\fR expands (or shrinks) an existing memory mapping, potentially +moving it at the same time (controlled by the \fIflags\fR argument and +the available virtual address space). + +\fIold_address\fR is the old address of the virtual memory block that you +want to expand (or shrink). Note that \fIold_address\fR has to be page +aligned. \fIold_size\fR is the old size of the +virtual memory block. \fInew_size\fR is the requested size of the +virtual memory block after the resize. + +The \fIflags\fR argument is a bitmap of flags. + +In Linux the memory is divided into pages. A user process has (one or) +several linear virtual memory segments. Each virtual memory segment has one +or more mappings to real memory pages (in the page table). Each virtual +memory segment has its own protection (access rights), which may cause +a segmentation violation if the memory is accessed incorrectly (e.g., +writing to a read-only segment). Accessing virtual memory outside of the +segments will also cause a segmentation violation. + +\fBmremap\fR uses the Linux page table scheme. \fBmremap\fR changes the +mapping between virtual addresses and memory pages. This can be used to +implement a very efficient \fBrealloc\fR. + +.SH FLAGS +.TP +.B MREMAP_MAYMOVE +indicates if the operation should fail, or change the virtual address +if the resize cannot be done at the current virtual address. + +.SH "RETURN VALUE" +On success \fBmremap\fR returns a pointer to the new virtual memory area. +On error, the value +.B MAP_FAILED +(that is, (void *) \-1) is returned, and \fIerrno\fR is set appropriately. + +.SH ERRORS +.TP +.B EAGAIN +The memory segment is locked and cannot be re-mapped. +.TP +.B EFAULT +"Segmentation fault." Some address in the range +\fIold_address\fP to \fIold_address\fP+\fIold_size\fP is an invalid +virtual memory address for this process. +You can also get EFAULT even if there exist mappings that cover the +whole address space requested, but those mappings are of different types. +.TP +.B EINVAL +An invalid argument was given. Most likely \fIold_address\fR was not +page aligned. +.TP +.B ENOMEM +The memory area cannot be expanded at the current virtual address, and the +.B MREMAP_MAYMOVE +flag is not set in \fIflags\fP. +Or, there is not enough (virtual) memory available. +.SH NOTES +With current glibc includes, in order to get the definition of +.BR MREMAP_MAYMOVE , +you need to define _GNU_SOURCE before including . +.SH "CONFORMING TO" +This call is Linux-specific, and should not be used in programs +intended to be portable. 4.2BSD had a (never actually implemented) +.BR mremap (2) +call with completely different semantics. +.SH "SEE ALSO" +.BR brk (2), +.BR getpagesize (2), +.BR mmap (2), +.BR sbrk (2), +.BR malloc (3), +.BR realloc (3) +.P +Your favorite OS text book for more information on paged memory. +(\fIModern Operating Systems\fR by Andrew S. Tannenbaum, +\fIInside Linux\fR by Randolf Bentson, +\fIThe Design of the UNIX Operating System\fR by Maurice J. Bach.) diff --git a/man2/msgctl.2 b/man2/msgctl.2 new file mode 100644 index 000000000..a0dc291c0 --- /dev/null +++ b/man2/msgctl.2 @@ -0,0 +1,180 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" Modified Sun Feb 18 01:59:29 2001 by Andries E. Brouwer +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on CAP_IPC_OWNER requirement +.\" Modified, 17 Jun 2004, Michael Kerrisk +.\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID +.\" +.TH MSGCTL 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +msgctl \- message control operations +.SH SYNOPSIS +.nf +.B +#include +.B +#include +.B +#include +.fi +.sp +.BI "int msgctl(int " msqid , +.BI "int " cmd , +.BI "struct msqid_ds *" buf ); +.SH DESCRIPTION +This function performs the control operation specified by +.I cmd +on the message queue with identifier +.IR msqid . +Legal values for +.I cmd +are: +.TP +.B IPC_STAT +Copy info from the message queue data structure associated with +.I msqid +into the structure pointed to by +.IR buf . +The caller must have read permission on the message queue. +.TP +.B IPC_SET +Write the values of some members of the +.B msqid_ds +structure pointed to by +.I buf +to the message queue data structure, updating also its +.B msg_ctime +member. +The following members of the structure can be updated: +.nf +.sp +.ft B + msg_perm.uid + msg_perm.gid + msg_perm.mode \fR/* only lowest 9-bits */\fP + msg_qbytes +.fi +.ft R +.sp +The calling process must have appropriate (probably, root) privileges +or its effective user\-ID must be that of the creator +.RI ( msg_perm.cuid ) +or owner +.RI ( msg_perm.uid ) +of the message queue. +Appropriate privilege (Linux: the +.B CAP_IPC_RESOURCE +capability) is required to raise the +.B msg_qbytes +value beyond the system parameter +.BR MSGMNB . +.TP +.B IPC_RMID +Immediately remove the message queue and its associated data structure, +awakening all waiting reader and writer processes (with an error +return and +.B errno +set to +.BR EIDRM ). +The calling process must have appropriate (probably, root) privileges +or its effective user\-ID must be either that of the creator or owner +of the message queue. +.SH "RETURN VALUE" +On success, the return value will be +.BR 0 , +otherwise +.B \-1 +with +.B errno +indicating the error. +.SH ERRORS +On failure, +.B errno +is set to one of the following: +.TP 11 +.B EACCES +The argument +.I cmd +is equal to +.B IPC_STAT +or +.BR MSG_STAT , +but the calling process does not have read permission on the message queue +.IR msqid , +and does not have the +.B CAP_IPC_OWNER +capability. +.TP +.B EFAULT +The argument +.I cmd +has the value +.B IPC_SET +or +.BR IPC_STAT , +but the address pointed to by +.I buf +isn't accessible. +.TP +.B EIDRM +The message queue was removed. +.TP +.B EINVAL +Invalid value for +.I cmd +or +.IR msqid . +.TP +.B EPERM +The argument +.I cmd +has the value +.B IPC_SET +or +.BR IPC_RMID , +but the effective user ID of the calling process is not the creator +(as found in +.IR msg_perm.cuid ) +or the owner +(as found in +.IR msg_perm.uid ) +of the message queue, +and the process is not privileged (Linux: it does not have the +.B CAP_SYS_ADMIN +capability). +.SH NOTES +Various fields in a \fIstruct msqid_ds\fP were shorts under Linux 2.2 +and have become longs under Linux 2.4. To take advantage of this, +a recompilation under glibc-2.1.91 or later should suffice. +(The kernel distinguishes old and new calls by a IPC_64 flag in +.IR cmd .) +.SH "CONFORMING TO" +SVr4, SVID. SVID does not document the EIDRM error condition. +.SH "SEE ALSO" +.BR msgget (2), +.BR msgrcv (2), +.BR msgsnd (2), +.BR ipc (5), +.BR capabilities (7) diff --git a/man2/msgget.2 b/man2/msgget.2 new file mode 100644 index 000000000..03e285862 --- /dev/null +++ b/man2/msgget.2 @@ -0,0 +1,219 @@ +.\" Copyright 1993 Giorgio Ciucci +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Added correction due to Nick Duffek , aeb, 960426 +.\" Modified Wed Nov 6 04:00:31 1996 by Eric S. Raymond +.\" Modified, 8 Jan 2003, Michael Kerrisk, +.\" Removed EIDRM from errors - that can't happen... +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH MSGGET 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +msgget \- get a message queue identifier +.SH SYNOPSIS +.nf +.B +#include +.B +#include +.B +#include +.fi +.sp +.BI "int msgget(key_t " key , +.BI "int " msgflg ); +.SH DESCRIPTION +The function returns the message queue identifier associated +with the value of the +.I key +argument. +A new message queue is created if +.I key +has the value +.B IPC_PRIVATE +or +.I key +isn't +.BR IPC_PRIVATE , +no message queue with the given key +.IR key +exists, and +.B IPC_CREAT +is asserted in +.I msgflg +(i.e., +.IB msgflg & IPC_CREAT +is nonzero). +The presence in +.I msgflg +of the fields +.B IPC_CREAT +and +.B IPC_EXCL +plays the same role, with respect to the existence +of the message queue, as the presence +of +.B O_CREAT +and +.B O_EXCL +in the mode argument of the +.BR open (2) +system call: i.e. the +.B msgget +function fails if +.I msgflg +asserts both +.B IPC_CREAT +and +.B IPC_EXCL +and a message queue already exists for +.IR key . +.PP +Upon creation, the lower 9 bits of the argument +.I msgflg +define the access permissions of the message queue. +These permission bits have the same format and semantics +as the access permissions parameter in +.BR open (2) +or +.BR creat (2) +system calls. (The execute permissions are not used.) +.PP +If a new message queue is created, +the system call initializes the system message queue data structure +.B msqid_ds +as follows: +.IP +.B msg_perm.cuid +and +.B msg_perm.uid +are set to the effective user\-ID of the calling process. +.IP +.B msg_perm.cgid +and +.B msg_perm.gid +are set to the effective group\-ID of the calling process. +.IP +The lowest order 9 bits of +.B msg_perm.mode +are set to the lowest order 9 bit of +.IR msgflg . +.IP +.BR msg_qnum , +.BR msg_lspid , +.BR msg_lrpid , +.BR msg_stime +and +.B msg_rtime +are set to 0. +.IP +.B msg_ctime +is set to the current time. +.IP +.B msg_qbytes +is set to the system limit +.BR MSGMNB . +.PP +If the message queue already exists the access permissions are +verified, and a check is made to see if it is marked for +destruction. +.SH "RETURN VALUE" +If successful, the return value will be the message queue identifier (a +nonnegative integer), otherwise +.B \-1 +with +.B errno +indicating the error. +.SH ERRORS +On failure, +.B errno +is set to one of the following values: +.TP 11 +.B EACCES +A message queue exists for +.IR key , +but the calling process does not have permission to access the queue, +and does not have the +.BR CAP_IPC_OWNER +capability. +.TP +.B EEXIST +A message queue exists for +.B key +and +.I msgflg +was asserting both +.B IPC_CREAT +and +.BR IPC_EXCL . +.TP +.B ENOENT +No message queue exists for +.I key +and +.I msgflg +wasn't asserting +.BR IPC_CREAT . +.TP +.B ENOMEM +A message queue has to be created but the system has not enough memory for +the new data structure. +.TP +.B ENOSPC +A message queue has to be created but the system limit for the maximum +number of message queues +.RB ( MSGMNI ) +would be exceeded. +.SH NOTES +.B IPC_PRIVATE +isn't a flag field but a +.B key_t +type. +If this special value is used for +.IR key , +the system call ignores everything but the lowest order 9 bits of +.I msgflg +and creates a new message queue (on success). +.PP +The following is a system limit on message queue resources affecting a +.B msgget +call: +.TP 11 +.B MSGMNI +System wide maximum number of message queues: policy +dependent. +.SH BUGS +The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW +would more clearly show its function. +.SH "CONFORMING TO" +SVr4, SVID. +Until version 2.3.20 Linux would return EIDRM for a +.B msgget +on a message queue scheduled for deletion. +.SH "SEE ALSO" +.BR msgctl (2), +.BR msgrcv (2), +.BR msgsnd (2), +.BR ftok (3), +.BR ipc (5), +.BR capabilities (7) diff --git a/man2/msgop.2 b/man2/msgop.2 new file mode 100644 index 000000000..00e0513cf --- /dev/null +++ b/man2/msgop.2 @@ -0,0 +1,415 @@ +.\" Copyright 1993 Giorgio Ciucci +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Tue Oct 22 16:40:11 1996 by Eric S. Raymond +.\" Modified Mon Jul 10 21:09:59 2000 by aeb +.\" Modified 1 Jun 2002, Michael Kerrisk +.\" Language clean-ups. +.\" Enhanced and corrected information on msg_qbytes, MSGMNB and MSGMAX +.\" Added note on restart behaviour of msgsnd and msgrcv +.\" Formatting clean-ups (argument and field names marked as .I +.\" instead of .B) +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH MSGOP 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +msgop \- message operations +.SH SYNOPSIS +.nf +.B +#include +.br +.B +#include +.br +.B +#include +.fi +.sp +.BI "int msgsnd(int " msqid , +.BI "struct msgbuf *" msgp , +.BI "size_t " msgsz , +.BI "int " msgflg ); +.sp +.BI "ssize_t msgrcv(int " msqid , +.BI "struct msgbuf *" msgp , +.BI "size_t " msgsz , +.BI "long " msgtyp , +.BI "int " msgflg ); +.SH DESCRIPTION +To send or receive a message, the calling process allocates a structure +of the following general form: +.sp +.B + struct msgbuf { +.br +.B + long mtype; +/* message type, must be > 0 */ +.br +.B + char mtext[1]; +/* message data */ +.br +.B + }; +.sp +The +.I mtext +field is an array (or other structure) whose size is specified by +.IR msgsz , +a non-negative integer value. +Messages of zero length (i.e., no +.I mtext +field) are permitted. +The +.I mtype +field must have a strictly positive integer value that can be +used by the receiving process for message selection +(see the section about +.BR msgrcv ). +.PP +The calling process must have write permission to send +and read permission to receive a message on the queue. +.PP +The +.B msgsnd +system call appends a copy of the message pointed to by +.I msgp +to the message queue whose identifier is specified +by +.IR msqid . +.PP +If sufficient space is available on the queue, +.B msgsnd +succeeds immediately. +(The queue capacity is defined by the +.I msg_bytes +field in the associated data structure for the message queue. +During queue creation this field is initialised to +.B MSGMNB +bytes, but this limit can be modified using +.BR msgctl .) +If insufficient space is available on the queue, then the default +behaviour of +.B msgsnd +is to block until space becomes available. +If +.B IPC_NOWAIT +is asserted in +.B msgflg +then the call instead fails with the error +.BR EAGAIN . + +A blocked +.B msgsnd +call may also fail if the queue is removed +(in which case the system call fails with +.I errno +set to +.BR EIDRM ), +or a signal is caught (in which case the system call fails +with +.I errno +set to +.BR EINTR ). +.RB ( msgsnd " and " msgrcv +are never automatically restarted after being interrupted by a +signal handler, regardless of the setting of the +.B SA_RESTART +flag when establishing a signal handler.) +.PP +Upon successful completion the message queue data structure is updated +as follows: +.IP +.I msg_lspid +is set to the process ID of the calling process. +.IP +.I msg_qnum +is incremented by 1. +.IP +.I msg_stime +is set to the current time. +.PP +The system call +.B msgrcv +reads a message from the message queue specified by +.I msqid +into the +.I msgbuf +pointed to by the +.I msgp +argument, removing the read message from the queue. +.PP +The argument +.I msgsz +specifies the maximum size in bytes for the member +.I mtext +of the structure pointed to by the +.I msgp +argument. +If the message text has length greater than +.IR msgsz , +then if the +.I msgflg +argument asserts +.BR MSG_NOERROR , +the message text will be truncated (and the truncated part will be +lost), otherwise the message isn't removed from the queue and +the system call fails returning with +.I errno +set to +.BR E2BIG . +.PP +The argument +.I msgtyp +specifies the type of message requested as follows: +.IP +If +.I msgtyp +is +.BR 0 , +then the first message in the queue is read. +.IP +If +.I msgtyp +is greater than +.BR 0 , +then the first message on the queue of type +.I msgtyp +is read, unless +.B MSG_EXCEPT +was asserted in +.IR msgflg , +in which case +the first message on the queue of type not equal to +.I msgtyp +will be read. +.IP +If +.I msgtyp +is less than +.BR 0 , +then the first message on the queue with the lowest type less than or +equal to the absolute value of +.I msgtyp +will be read. +.PP +The +.I msgflg +argument asserts none, one or more (or\-ing them) of the following +flags: +.IP +.B IPC_NOWAIT +For immediate return if no message of the requested type is on the queue. +The system call fails with errno set to +.BR ENOMSG . +.IP +.B MSG_EXCEPT +Used with +.I msgtyp +greater than +.B 0 +to read the first message on the queue with message type that differs +from +.IR msgtyp . +.IP +.B MSG_NOERROR +To truncate the message text if longer than +.I msgsz +bytes. +.PP +If no message of the requested type is available and +.B IPC_NOWAIT +isn't asserted in +.IR msgflg , +the calling process is blocked until one of the following conditions occurs: +.IP +A message of the desired type is placed on the queue. +.IP +The message queue is removed from the system. +In this case the system call fails with +.I errno +set to +.BR EIDRM . +.IP +The calling process catches a signal. +In this case the system call fails with +.I errno +set to +.BR EINTR . +.PP +Upon successful completion the message queue data structure is updated +as follows: +.IP +.I msg_lrpid +is set to the process ID of the calling process. +.IP +.I msg_qnum +is decremented by 1. +.IP +.I msg_rtime +is set to the current time. +.SH "RETURN VALUE" +On a failure both functions return +.B \-1 +with +.I errno +indicating the error, +otherwise +.B msgsnd +returns +.B 0 +and +.B msgrvc +returns the number of bytes actually copied into the +.I mtext +array. +.SH ERRORS +When +.B msgsnd +fails, at return +.I errno +will be set to one among the following values: +.TP +.B EACCES +The calling process does not have write permission on the message queue, +and does not have the +.BR CAP_IPC_OWNER +capability. +.TP 11 +.B EAGAIN +The message can't be sent due to the +.I msg_qbytes +limit for the queue and +.B IPC_NOWAIT +was asserted in +.IR mgsflg . +.TP +.B EFAULT +The address pointed to by +.I msgp +isn't accessible. +.TP +.B EIDRM +The message queue was removed. +.TP +.B EINTR +Sleeping on a full message queue condition, the process caught a signal. +.TP +.B EINVAL +Invalid +.I msqid +value, or nonpositive +.I mtype +value, or +invalid +.I msgsz +value (less than 0 or greater than the system value +.BR MSGMAX ). +.TP +.B ENOMEM +The system has not enough memory to make a copy of the supplied +.IR msgbuf . +.PP +When +.B msgrcv +fails, at return +.I errno +will be set to one among the following values: +.TP 11 +.B E2BIG +The message text length is greater than +.I msgsz +and +.B MSG_NOERROR +isn't asserted in +.IR msgflg . +.TP +.B EACCES +The calling process does not have read permission on the message queue, +and does not have the +.BR CAP_IPC_OWNER +capability. +.TP +.B EFAULT +The address pointed to by +.I msgp +isn't accessible. +.TP +.B EIDRM +While the process was sleeping to receive a message, +the message queue was removed. +.TP +.B EINTR +While the process was sleeping to receive a message, +the process received a signal that had to be caught. +.TP +.B EINVAL +Illegal +.I msgqid +value, or +.I msgsz +less than +.BR 0 . +.TP +.B ENOMSG +.B IPC_NOWAIT +was asserted in +.I msgflg +and no message of the requested type existed on the message queue. +.SH NOTES +The followings are system limits affecting a +.B msgsnd +system call: +.TP 11 +.B MSGMAX +Maximum size for a message text: the implementation set this value to +8192 bytes. +.TP +.B MSGMNB +Default maximum size in bytes of a message queue: 16384 bytes. +The super\-user can increase the size of a message queue beyond +.B MSGMNB +by a +.B msgctl +system call. +.PP +The implementation has no intrinsic limits for the system wide maximum +number of message headers +.RB ( MSGTQL ) +and for the system wide maximum size in bytes of the message pool +.RB ( MSGPOOL ). +.SH "CONFORMING TO" +SVr4, SVID. +.SH NOTE +The pointer argument is declared as \fIstruct msgbuf *\fP with +libc4, libc5, glibc 2.0, glibc 2.1. It is declared as \fIvoid *\fP +(\fIconst void *\fP for \fImsgsnd()\fP) with glibc 2.2, following the SUSv2. +.SH "SEE ALSO" +.BR msgctl (2), +.BR msgget (2), +.BR msgrcv (2), +.BR msgsnd (2), +.BR ipc (5), +.BR capabilities (7) diff --git a/man2/msgrcv.2 b/man2/msgrcv.2 new file mode 100644 index 000000000..b34869edf --- /dev/null +++ b/man2/msgrcv.2 @@ -0,0 +1 @@ +.so man2/msgop.2 diff --git a/man2/msgsnd.2 b/man2/msgsnd.2 new file mode 100644 index 000000000..b34869edf --- /dev/null +++ b/man2/msgsnd.2 @@ -0,0 +1 @@ +.so man2/msgop.2 diff --git a/man2/msync.2 b/man2/msync.2 new file mode 100644 index 000000000..f3fc2ca3b --- /dev/null +++ b/man2/msync.2 @@ -0,0 +1,88 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH MSYNC 2 2003-08-21 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +msync \- synchronize a file with a memory map +.SH SYNOPSIS +.B #include +.sp +.BI "int msync(void *" start ", size_t " length ", int " flags ); +.SH DESCRIPTION +.B msync +flushes changes made to the in-core copy of a file that was mapped +into memory using +.BR mmap (2) +back to disk. Without use of this call +there is no guarantee that changes are written back before +.BR munmap (2) +is called. To be more precise, the part of the file that +corresponds to the memory area starting at +.I start +and having length +.I length +is updated. The +.I flags +argument may have the bits MS_ASYNC, MS_SYNC and MS_INVALIDATE set, +but not both MS_ASYNC and MS_SYNC. +MS_ASYNC specifies that an update be scheduled, but the call +returns immediately. +MS_SYNC asks for an update and waits for it to complete. +MS_INVALIDATE asks to invalidate other mappings of the same file +(so that they can be updated with the fresh values just written). +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.BR EINVAL +.I start +is not a multiple of PAGESIZE, or any bit other than +MS_ASYNC | MS_INVALIDATE | MS_SYNC is set in +.IR flags. +.TP +.B ENOMEM +The indicated memory (or part of it) was not mapped. +.SH AVAILABILITY +On POSIX systems on which +.B msync +is available, both +.B _POSIX_MAPPED_FILES +and +.B _POSIX_SYNCHRONIZED_IO +are defined in to a value greater than 0. (See also +.BR sysconf (3).) +.\" POSIX 1003.1-2001: It shall be defined to -1 or 0 or 200112L. +.\" -1: unavailable, 0: ask using sysconf(). +.\" glibc defines them to 1. +.SH "CONFORMING TO" +POSIX.1b (formerly POSIX.4) + +This call was introduced in Linux 1.3.21, and then used EFAULT instead of +ENOMEM. In Linux 2.4.19 this was changed to the POSIX value ENOMEM. +.SH "SEE ALSO" +.BR mmap (2) +.br +B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129 and 389-391. diff --git a/man2/munlock.2 b/man2/munlock.2 new file mode 100644 index 000000000..2d49abca7 --- /dev/null +++ b/man2/munlock.2 @@ -0,0 +1,98 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) Markus Kuhn, 1996 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 1995-11-26 Markus Kuhn +.\" First version written +.\" +.TH MUNLOCK 2 2003-08-21 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +munlock \- reenable paging for some parts of memory +.SH SYNOPSIS +.nf +.B #include +.sp +\fBint munlock(const void *\fIaddr\fB, size_t \fIlen\fB); +.fi +.SH DESCRIPTION +.B munlock +reenables paging for the memory in the range starting at +.I addr +with length +.I len +bytes. All pages which contain a part of the specified memory range +can after calling +.B munlock +be moved to external swap space again by the kernel. + +Memory locks do not stack, i.e., pages which have been locked several times +by calls to +.B mlock +or +.B mlockall +will be unlocked by a single call to +.B munlock +for the corresponding range or by +.BR munlockall . +Pages which are mapped to several locations or by several processes stay +locked into RAM as long as they are locked at least at one location or by +at least one process. + +On POSIX systems on which +.B mlock +and +.B munlock +are available, +.B _POSIX_MEMLOCK_RANGE +is defined in and the value +.B PAGESIZE +from indicates the number of bytes per page. +.SH "RETURN VALUE" +On success, +.B munlock +returns zero. On error, \-1 is returned, +.I errno +is set appropriately, and no changes are made to any locks in the +address space of the process. +.SH ERRORS +.TP +.B EINVAL +(Not on Linux) +.I addr +was not a multiple of the page size. +.TP +.B ENOMEM +Some of the specified address range does not correspond to mapped +pages in the address space of the process. +.LP +Linux adds +.TP +.B EINVAL +.I len +was negative. +.SH "CONFORMING TO" +POSIX.1b, SVr4 +.SH "SEE ALSO" +.BR mlock (2), +.BR mlockall (2), +.BR munlockall (2) diff --git a/man2/munlockall.2 b/man2/munlockall.2 new file mode 100644 index 000000000..5bb868cc9 --- /dev/null +++ b/man2/munlockall.2 @@ -0,0 +1,86 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) Markus Kuhn, 1996 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 1995-11-26 Markus Kuhn +.\" First version written +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH MUNLOCKALL 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +munlockall \- reenable paging for calling process +.SH SYNOPSIS +.nf +.B #include +.sp +\fBint munlockall(void); +.fi +.SH DESCRIPTION +.B munlockall +reenables paging for all pages mapped into the address space of the +calling process. + +Memory locks do not stack, i.e., pages which have been locked several times +by calls to +.B mlock +or +.B mlockall +will be unlocked by a single call to +.BR munlockall . +Pages which are mapped to several locations or by several processes stay +locked into RAM as long as they are locked at least at one location or by +at least one process. + +On POSIX systems on which +.B mlockall +and +.B munlockall +are available, +.B _POSIX_MEMLOCK +is defined in +.I . +.SH "RETURN VALUE" +On success, +.B munlockall +returns zero. On error, \-1 is returned and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR munlockall . +Under Linux the +.B CAP_IPC_LOCK +capability is required. +.\" Weirdness this way comes: CAP_IPC_LOCK is required for munlockall() +.\" and shmctl(SHM_UNLOCK), but is *not* required for munlock +.\" (as at kernel 2.6.6) +.SH "CONFORMING TO" +POSIX.1b, SVr4 +.SH "SEE ALSO" +.BR mlock (2), +.BR mlockall (2), +.BR munlock (2), +.BR capabilities (7) diff --git a/man2/munmap.2 b/man2/munmap.2 new file mode 100644 index 000000000..8902d1b35 --- /dev/null +++ b/man2/munmap.2 @@ -0,0 +1 @@ +.so man2/mmap.2 diff --git a/man2/nanosleep.2 b/man2/nanosleep.2 new file mode 100644 index 000000000..ec8dde866 --- /dev/null +++ b/man2/nanosleep.2 @@ -0,0 +1,140 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) Markus Kuhn, 1996 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 1996-04-10 Markus Kuhn +.\" First version written +.\" Modified, 2004-10-24, aeb +.TH NANOSLEEP 2 2004-10-24 "Linux 2.6.9" "Linux Programmer's Manual" +.SH NAME +nanosleep \- pause execution for a specified time +.SH SYNOPSIS +.B #include +.sp +\fBint nanosleep(const struct timespec *\fIreq\fB, struct timespec *\fIrem\fB); +.fi +.SH DESCRIPTION +.B nanosleep +delays the execution of the program for at least the time specified in +.IR *req . +The function can return earlier if a signal has been delivered to the +process. In this case, it returns \-1, sets \fIerrno\fR to +.BR EINTR , +and writes the +remaining time into the structure pointed to by +.IR rem +unless +.I rem +is +.BR NULL . +The value of +.I *rem +can then be used to call +.B nanosleep +again and complete the specified pause. + +The structure +.I timespec +is used to specify intervals of time with nanosecond precision. It is +specified in +.I +and has the form +.sp +.RS +.nf +.ne 12 +.ta 8n 16n 32n +struct timespec +{ + time_t tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +}; +.ta +.fi +.RE +.PP +The value of the nanoseconds field must be in the range 0 to 999999999. + +Compared to +.BR sleep (3) +and +.BR usleep (3), +.B nanosleep +has the advantage of not affecting any signals, it is standardized by +POSIX, it provides higher timing resolution, and it allows to continue +a sleep that has been interrupted by a signal more easily. +.SH ERRORS +In case of an error or exception, the +.B nanosleep +system call returns \-1 instead of 0 and sets +.I errno +to one of the following values: +.TP +.B EFAULT +Problem with copying information from user space. +.TP +.B EINTR +The pause has been interrupted by a non-blocked signal that was +delivered to the process. The remaining sleep time has been written +into *\fIrem\fR so that the process can easily call +.B nanosleep +again and continue with the pause. +.TP +.B EINVAL +The value in the +.I tv_nsec +field was not in the range 0 to 999999999 or +.I tv_sec +was negative. +.SH BUGS +The current implementation of +.B nanosleep +is based on the normal kernel timer mechanism, which has a resolution +of 1/\fIHZ\fR\ s (i.e, 10\ ms on Linux/i386 and 1\ ms on Linux/Alpha). +Therefore, +.B nanosleep +pauses always for at least the specified time, however it can take up +to 10 ms longer than specified until the process becomes runnable +again. For the same reason, the value returned in case of a delivered +signal in *\fIrem\fR is usually rounded to the next larger multiple of +1/\fIHZ\fR\ s. + +.SS "Old behaviour" +In order to support applications requiring much more precise pauses +(e.g., in order to control some time-critical hardware), +.B nanosleep +would handle pauses of up to 2\ ms by busy waiting with microsecond +precision when called from a process scheduled under a real-time policy +like +.I SCHED_FIFO +or +.IR SCHED_RR . +This special extension was removed in kernel 2.5.39, hence is still present in +current 2.4 kernels, but not in 2.6 kernels. +.SH "CONFORMING TO" +POSIX.1b (formerly POSIX.4). +.SH "SEE ALSO" +.BR sched_setscheduler (2), +.BR timer_create (2), +.BR sleep (3), +.BR usleep (3) diff --git a/man2/nfsservctl.2 b/man2/nfsservctl.2 new file mode 100644 index 000000000..2f2050abc --- /dev/null +++ b/man2/nfsservctl.2 @@ -0,0 +1,47 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This text is in the public domain. +.\" +.TH NFSSERVCTL 2 1997-07-16 "Linux 2.1.32" "Linux Programmer's Manual" +.SH NAME +nfsservctl \- syscall interface to kernel nfs daemon +.SH SYNOPSIS +.B #include +.sp +.BI "nfsservctl(int " cmd ", struct nfsctl_arg *" argp ", union nfsctl_res *" resp ); +.SH DESCRIPTION +.nf +/* + * These are the commands understood by nfsctl(). + */ +#define NFSCTL_SVC 0 /* This is a server process. */ +#define NFSCTL_ADDCLIENT 1 /* Add an NFS client. */ +#define NFSCTL_DELCLIENT 2 /* Remove an NFS client. */ +#define NFSCTL_EXPORT 3 /* export a file system. */ +#define NFSCTL_UNEXPORT 4 /* unexport a file system. */ +#define NFSCTL_UGIDUPDATE 5 /* update a client's uid/gid map. */ +#define NFSCTL_GETFH 6 /* get an fh (used by mountd) */ + +struct nfsctl_arg { + int ca_version; /* safeguard */ + union { + struct nfsctl_svc u_svc; + struct nfsctl_client u_client; + struct nfsctl_export u_export; + struct nfsctl_uidmap u_umap; + struct nfsctl_fhparm u_getfh; + unsigned int u_debug; + } u; +} + +union nfsctl_res { + struct knfs_fh cr_getfh; + unsigned int cr_debug; +}; +.fi +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH "CONFORMING TO" +This call is Linux-specific. diff --git a/man2/nice.2 b/man2/nice.2 new file mode 100644 index 000000000..a5e2369a8 --- /dev/null +++ b/man2/nice.2 @@ -0,0 +1,84 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt , March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-11-04 by Eric S. Raymond +.\" Modified 2001-06-04 by aeb +.\" Modified 2004-05-27 by Michael Kerrisk +.\" +.TH NICE 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +nice \- change process priority +.SH SYNOPSIS +.B #include +.sp +.BI "int nice(int " inc ); +.SH DESCRIPTION +.B nice +adds +.I inc +to the nice value for the calling pid. +(A large nice value means a low priority.) +Only the super\%user may specify a negative increment, or priority increase. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EPERM +The calling process attempted to increase its priority by +supplying a negative +.IR inc +but has insufficient privileges. +Under Linux the +.B CAP_SYS_NICE +capability is required. +.SH "CONFORMING TO" +SVr4, SVID EXT, AT&T, X/OPEN, BSD 4.3. However, the Linux and glibc +(earlier than glibc 2.2.4) return value is nonstandard, see below. +SVr4 documents an additional +EINVAL error code. +.SH NOTES +Note that the routine is documented in SUSv2 and POSIX 1003.1-2003 +to return the new nice value, while the Linux syscall and (g)libc +(earlier than glibc 2.2.4) routines return 0 on success. +The new nice value can be found using +.BR getpriority (2). +Note that an implementation in which +.B nice +returns the new nice value can legitimately return \-1. +To reliably detect an error, set +.I errno +to 0 before the call, and check its value when +.B nice +returns \-1. +.SH "SEE ALSO" +.BR nice (1), +.BR fork (2), +.BR getpriority (2), +.BR setpriority (2), +.BR capabilities (7), +.BR renice (8) diff --git a/man2/obsolete.2 b/man2/obsolete.2 new file mode 100644 index 000000000..90a78f4e8 --- /dev/null +++ b/man2/obsolete.2 @@ -0,0 +1,50 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified 22 July 1995 by Michael Chastain (mec@duracef.shout.net): +.\" Fixed incorrect word in 'TH' call. +.\" +.\" Modified Tue Oct 22 16:44:55 1996 by Eric S. Raymond +.\" +.TH OBSOLETE 2 1995-07-22 "Linux 2.0" "Linux Programmer's Manual" +.SH NAME +oldfstat, oldlstat, oldstat, oldolduname, olduname \- obsolete system calls +.SH SYNOPSIS +Obsolete system calls. +.SH DESCRIPTION +The Linux 2.0 kernel implements these calls to support old executables. +These calls return structures which have grown since their +first implementation, +but old executables must continue to receive old smaller structures. +.PP +Current executables should be linked with current libraries and never +use these calls. +.SH "CONFORMING TO" +These calls are unique to Linux and should not be used at all in new programs. +.SH "SEE ALSO" +.BR fstat (2), +.BR lstat (2), +.BR stat (2), +.BR uname (2), +.BR unimplemented (2) diff --git a/man2/oldfstat.2 b/man2/oldfstat.2 new file mode 100644 index 000000000..e9807034a --- /dev/null +++ b/man2/oldfstat.2 @@ -0,0 +1 @@ +.so man2/obsolete.2 diff --git a/man2/oldlstat.2 b/man2/oldlstat.2 new file mode 100644 index 000000000..e9807034a --- /dev/null +++ b/man2/oldlstat.2 @@ -0,0 +1 @@ +.so man2/obsolete.2 diff --git a/man2/oldolduname.2 b/man2/oldolduname.2 new file mode 100644 index 000000000..e9807034a --- /dev/null +++ b/man2/oldolduname.2 @@ -0,0 +1 @@ +.so man2/obsolete.2 diff --git a/man2/oldstat.2 b/man2/oldstat.2 new file mode 100644 index 000000000..e9807034a --- /dev/null +++ b/man2/oldstat.2 @@ -0,0 +1 @@ +.so man2/obsolete.2 diff --git a/man2/olduname.2 b/man2/olduname.2 new file mode 100644 index 000000000..e9807034a --- /dev/null +++ b/man2/olduname.2 @@ -0,0 +1 @@ +.so man2/obsolete.2 diff --git a/man2/open.2 b/man2/open.2 new file mode 100644 index 000000000..47490f860 --- /dev/null +++ b/man2/open.2 @@ -0,0 +1,448 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt, Ian Jackson. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1994-08-21 by Michael Haardt +.\" Modified 1996-04-13 by Andries Brouwer +.\" Modified 1996-05-13 by Thomas Koenig +.\" Modified 1996-12-20 by Michael Haardt +.\" Modified 1999-02-19 by Andries Brouwer +.\" Modified 1998-11-28 by Joseph S. Myers +.\" Modified 1999-06-03 by Michael Haardt +.\" Modified 2002-05-07 by Michael Kerrisk +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH OPEN 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +open, creat \- open and possibly create a file or device +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.sp +.BI "int open(const char *" pathname ", int " flags ); +.BI "int open(const char *" pathname ", int " flags ", mode_t " mode ); +.BI "int creat(const char *" pathname ", mode_t " mode ); +.fi +.SH DESCRIPTION +The +.B open() +system call is used to convert a pathname into a file descriptor +(a small, non-negative integer for use in subsequent I/O as with +.BR read ", " write ", etc.)." +When the call is successful, the file descriptor returned will be +the lowest file descriptor not currently open for the process. +This call creates a new open file, not shared with any other process. +(But shared open files may arise via the +.BR fork (2) +system call.) +The new file descriptor is set to remain open across exec functions +(see +.BR fcntl (2)). +The file offset is set to the beginning of the file. + +The parameter +.I flags +is one of +.BR O_RDONLY ", " O_WRONLY " or " O_RDWR +which request opening the file read-only, write-only or read/write, +respectively, +.RI bitwise- or 'd +with zero or more of the following: +.TP +.B O_CREAT +If the file does not exist it will be created. +The owner (user ID) of the file is set to the effective user ID +of the process. The group ownership (group ID) is set either to +the effective group ID of the process or to the group ID of the +parent directory (depending on filesystem type and mount options, +and the mode of the parent directory, see, e.g., the mount options +.I bsdgroups +and +.I sysvgroups +of the ext2 filesystem, as described in +.BR mount (8)). +.TP +.B O_EXCL +When used with +.BR O_CREAT , +if the file already exists it is an error and the +.B open +will fail. In this context, a symbolic link exists, regardless +of where its points to. +.B O_EXCL +is broken on NFS file systems, programs which rely on it for performing +locking tasks will contain a race condition. The solution for performing +atomic file locking using a lockfile is to create a unique file on the same +fs (e.g., incorporating hostname and pid), use +.BR link (2) +to make a link to the lockfile. If \fBlink()\fP returns 0, the lock is +successful. Otherwise, use +.BR stat (2) +on the unique file to check if its link count has increased to 2, +in which case the lock is also successful. +.TP +.B O_NOCTTY +If +.I pathname +refers to a terminal device \(em see +.BR tty (4) +\(em it will not become the process's controlling terminal even if the +process does not have one. +.TP +.B O_TRUNC +If the file already exists and is a regular file and the open mode allows +writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0. +If the file is a FIFO or terminal device file, the O_TRUNC +flag is ignored. Otherwise the effect of O_TRUNC is unspecified. +.TP +.B O_APPEND +The file is opened in append mode. Before each +.BR write , +the file pointer is positioned at the end of the file, +as if with +.BR lseek . +.B O_APPEND +may lead to corrupted files on NFS file systems if more than one process +appends data to a file at once. This is because NFS does not support +appending to a file, so the client kernel has to simulate it, which +can't be done without a race condition. +.TP +.BR O_NONBLOCK " or " O_NDELAY +When possible, the file is opened in non-blocking mode. Neither the +.B open +nor any subsequent operations on the file descriptor which is +returned will cause the calling process to wait. +For the handling of FIFOs (named pipes), see also +.BR fifo (4). +This mode need not have any effect on files other than FIFOs. +.TP +.B O_SYNC +The file is opened for synchronous I/O. Any +.BR write s +on the resulting file descriptor will block the calling process until +the data has been physically written to the underlying hardware. +.I See RESTRICTIONS below, though. +.TP +.B O_NOFOLLOW +If \fIpathname\fR is a symbolic link, then the open fails. This is a +FreeBSD extension, which was added to Linux in version 2.1.126. +Symbolic links in earlier components of the pathname will still be +followed. The headers from glibc 2.0.100 and later include a +definition of this flag; \fIkernels before 2.1.126 will ignore it if +used\fR. +.TP +.B O_DIRECTORY +If \fIpathname\fR is not a directory, cause the open to fail. This +flag is Linux-specific, and was added in kernel version 2.1.126, to +avoid denial-of-service problems if \fBopendir\fR(3) is called on a +FIFO or tape device, but should not be used outside of the +implementation of \fBopendir\fR. +.TP +.B O_DIRECT +Try to minimize cache effects of the I/O to and from this file. +In general this will degrade performance, but it is useful in +special situations, such as when applications do their own caching. +File I/O is done directly to/from user space buffers. +The I/O is synchronous, i.e., at the completion of the +.BR read (2) +or +.BR write (2) +system call, data is guaranteed to have been transferred. +Under Linux 2.4 transfer sizes, and the alignment of user buffer +and file offset must all be multiples of the logical block size +of the file system. Under Linux 2.6 alignment to 512-byte boundaries +suffices. +.\" Alignment should satisfy requirements for the underlying device +.\" There may be coherency problems. +.br +A semantically similar interface for block devices is described in +.BR raw (8). +.TP +.B O_ASYNC +Generate a signal (SIGIO by default, but this can be changed via +.BR fcntl (2)) +when input or output becomes possible on this file descriptor. +This feature is only available for terminals, pseudo-terminals, and +sockets. See +.BR fcntl (2) +for further details. +.TP +.B O_LARGEFILE +(LFS) +Allow files whose sizes cannot be represented in an +.B off_t +(but can be represented in an +.BR off64_t ) +to be opened. +.PP +Some of these optional flags can be altered using +.B fcntl +after the file has been opened. + +The argument +.I mode +specifies the permissions to use in case a new file is created. It is +modified by the process's +.BR umask +in the usual way: the permissions of the created file are +.BR "(mode & ~umask)" . +Note that this mode only applies to future accesses of the +newly created file; the +.B open +call that creates a read-only file may well return a read/write +file descriptor. +.PP +The following symbolic constants are provided for +.IR mode : +.TP +.B S_IRWXU +00700 user (file owner) has read, write and execute permission +.TP +.B S_IRUSR (S_IREAD) +00400 user has read permission +.TP +.B S_IWUSR (S_IWRITE) +00200 user has write permission +.TP +.B S_IXUSR (S_IEXEC) +00100 user has execute permission +.TP +.B S_IRWXG +00070 group has read, write and execute permission +.TP +.B S_IRGRP +00040 group has read permission +.TP +.B S_IWGRP +00020 group has write permission +.TP +.B S_IXGRP +00010 group has execute permission +.TP +.B S_IRWXO +00007 others have read, write and execute permission +.TP +.B S_IROTH +00004 others have read permission +.TP +.B S_IWOTH +00002 others have write permisson +.TP +.B S_IXOTH +00001 others have execute permission +.PP +.I mode +must be specified when +.B O_CREAT +is in the +.IR flags , +and is ignored otherwise. + +.B creat +is equivalent to +.B open +with +.I flags +equal to +.BR O_CREAT|O_WRONLY|O_TRUNC . +.SH "RETURN VALUE" +.BR open " and " creat +return the new file descriptor, or \-1 if an error occurred (in which case, +.I errno +is set appropriately). +Note that +.B open +can open device special files, but +.B creat +cannot create them - use +.BR mknod (2) +instead. +.LP +On NFS file systems with UID mapping enabled, \fBopen\fP may return a file +descriptor but e.g. \fBread\fP(2) requests are denied with \fBEACCES\fP. +This is because the client performs \fBopen\fP by checking the permissions, +but UID mapping is performed by the server upon read and write requests. + +If the file is newly created, its atime, ctime, mtime fields are set +to the current time, and so are the ctime and mtime fields of the +parent directory. +Otherwise, if the file is modified because of the O_TRUNC flag, +its ctime and mtime fields are set to the current time. + +.SH ERRORS +.TP +.B EACCES +The requested access to the file is not allowed, or search permission +is denied for one of the directories in the path prefix of +.IR pathname , +or the file did not exist yet and write access to the parent directory +is not allowed. +(See also +.BR path_resolution (2).) +.TP +.B EEXIST +.I pathname +already exists and +.BR O_CREAT " and " O_EXCL +were used. +.TP +.B EFAULT +.IR pathname " points outside your accessible address space." +.TP +.B EISDIR +.I pathname +refers to a directory and the access requested involved writing +(that is, +.B O_WRONLY +or +.B O_RDWR +is set). +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname , +or \fBO_NOFOLLOW\fR was specified but +.I pathname +was a symbolic link. +.TP +.B EMFILE +The process already has the maximum number of files open. +.TP +.B ENAMETOOLONG +.IR pathname " was too long." +.TP +.B ENFILE +The system limit on the total number of open files has been reached. +.TP +.B ENODEV +.I pathname +refers to a device special file and no corresponding device exists. +(This is a Linux kernel bug - in this situation ENXIO must be returned.) +.TP +.B ENOENT +O_CREAT is not set and the named file does not exist. +Or, a directory component in +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +.I pathname +was to be created but the device containing +.I pathname +has no room for the new file. +.TP +.B ENOTDIR +A component used as a directory in +.I pathname +is not, in fact, a directory, or \fBO_DIRECTORY\fR was specified and +.I pathname +was not a directory. +.TP +.B ENXIO +O_NONBLOCK | O_WRONLY is set, the named file is a FIFO and +no process has the file open for reading. +Or, the file is a device special file and no corresponding device exists. +.TP +.B EOVERFLOW +.I pathname +refers to a regular file, too large to be opened - see O_LARGEFILE above. +.TP +.B EROFS +.I pathname +refers to a file on a read-only filesystem and write access was +requested. +.TP +.B ETXTBSY +.I pathname +refers to an executable image which is currently being executed and +write access was requested. +.SH NOTE +Under Linux, the O_NONBLOCK flag indicates that one wants to open +but does not necessarily have the intention to read or write. +This is typically used to open devices in order to get a file descriptor +for use with +.BR ioctl (2). +.SH "CONFORMING TO" +SVr4, SVID, POSIX, X/OPEN, BSD 4.3. +The +.B O_NOFOLLOW +and +.B O_DIRECTORY +flags are Linux-specific. +One may have to define the +.B _GNU_SOURCE +macro to get their definitions. +.LP +The (undefined) effect of +.B O_RDONLY | O_TRUNC +various among implementations. On many systems the file is actually +truncated. +.\" Linux 2.0, 2.5: truncate +.\" Solaris 5.7, 5.8: truncate +.\" Irix 6.5: truncate +.\" Tru64 5.1B: truncate +.\" HP-UX 11.22: truncate +.\" FreeBSD 4.7: truncate +.LP +The +.B O_DIRECT +flag was introduced in SGI IRIX, where it has alignment restrictions +similar to those of Linux 2.4. IRIX has also a fcntl(2) call to +query appropriate alignments, and sizes. FreeBSD 4.x introduced +a flag of same name, but without alignment restrictions. +Support was added under Linux in kernel version 2.4.10. +Older Linux kernels simply ignore this flag. +.SH BUGS +"The thing that has always disturbed me about O_DIRECT is that the whole +interface is just stupid, and was probably designed by a deranged monkey +on some serious mind-controlling substances." -- Linus +.SH RESTRICTIONS +There are many infelicities in the protocol underlying NFS, affecting +amongst others +.BR O_SYNC " and " O_NDELAY . + +POSIX provides for three different variants of synchronised I/O, +corresponding to the flags \fBO_SYNC\fR, \fBO_DSYNC\fR and +\fBO_RSYNC\fR. Currently (2.1.130) these are all synonymous under Linux. +.SH "SEE ALSO" +.BR close (2), +.BR fcntl (2), +.BR link (2), +.BR mknod (2), +.BR mount (2), +.BR path_resolution (2), +.BR read (2), +.BR socket (2), +.BR stat (2), +.BR umask (2), +.BR unlink (2), +.BR write (2), +.BR fopen (3), +.BR fifo (4) diff --git a/man2/outb.2 b/man2/outb.2 new file mode 100644 index 000000000..982e321d7 --- /dev/null +++ b/man2/outb.2 @@ -0,0 +1,66 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1995 Paul Gortmaker +.\" (gpg109@rsphy1.anu.edu.au) +.\" Wed Nov 29 10:58:54 EST 1995 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" +.TH OUTB 2 1995-11-29 "Linux" "Linux Programmer's Manual" +.SH NAME +outb, outw, outl, outsb, outsw, outsl, +inb, inw, inl, insb, insw, insl, +outb_p, outw_p, outl_p, inb_p, inw_p, inl_p \- port I/O +.sp +.SH DESCRIPTION +This family of functions is used to do low level port input and output. +The out* functions do port output, the in* functions do port input; +the b-suffix functions are byte-width and the w-suffix functions +word-width; the _p-suffix functions pause until the I/O completes. +.LP +They are primarily designed for internal kernel use, +but can be used from user space. +.\" , given the following information +.\" in addition to that given in +.\" .BR outb (9). +.sp +You compile with \fB\-O\fP or \fB\-O2\fP or similar. The functions +are defined as inline macros, and will not be substituted in without +optimization enabled, causing unresolved references at link time. +.sp +You use +.BR ioperm (2) +or alternatively +.BR iopl (2) +to tell the kernel to allow the user space application to access the +I/O ports in question. Failure to do this will cause the application +to receive a segmentation fault. + +.SH "CONFORMING TO" +\fBoutb\fP and friends are hardware specific. The +.I port +and +.I value +arguments are in the opposite order from most DOS implementations. +.SH "SEE ALSO" +.BR ioperm (2), +.BR iopl (2) diff --git a/man2/outb_p.2 b/man2/outb_p.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/outb_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/outl.2 b/man2/outl.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/outl.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/outl_p.2 b/man2/outl_p.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/outl_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/outsb.2 b/man2/outsb.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/outsb.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/outsl.2 b/man2/outsl.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/outsl.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/outsw.2 b/man2/outsw.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/outsw.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/outw.2 b/man2/outw.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/outw.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/outw_p.2 b/man2/outw_p.2 new file mode 100644 index 000000000..2c63c7549 --- /dev/null +++ b/man2/outw_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/path_resolution.2 b/man2/path_resolution.2 new file mode 100644 index 000000000..ec6dcd3de --- /dev/null +++ b/man2/path_resolution.2 @@ -0,0 +1,212 @@ +.\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH PATH_RESOLUTION 2 2004-06-21 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +Unix/Linux path resolution \- find the file referred to by a filename +.SH DESCRIPTION +Some Unix/Linux system calls have as parameter one or more filenames. +A filename (or pathname) is resolved as follows. + +.SS "Step 1: Start of the resolution process" +If the pathname starts with the '/' character, the starting lookup directory +is the root directory of the current process. (A process inherits its +root directory from its parent. Usually this will be the root directory +of the file hierarchy. A process may get a different root directory +by use of the +.BR chroot (2) +system call. A process may get an entirely private namespace in case +it - or one of its ancestors - was started by an invocation of the +.BR clone (2) +system call that had the CLONE_NEWNS flag set.) +This handles the '/' part of the pathname. + +If the pathname does not start with the '/' character, the +starting lookup directory of the resolution process is the current working +directory of the process. (This is also inherited from the parent. +It can be changed by use of the +.BR chdir (2) +system call.) + +Pathnames starting with a '/' character are called absolute pathnames. +Pathnames not starting with a '/' are called relative pathnames. + +.SS "Step 2: Walk along the path" +Set the current lookup directory to the starting lookup directory. +Now, for each non-final component of the pathname, where a component +is a substring delimited by '/' characters, this component is looked up +in the current lookup directory. + +If the process does not have search permission on the current lookup directory, +an EACCES error is returned ("Permission denied"). + +If the component is not found, an ENOENT error is returned +("No such file or directory"). + +If the component is found, but is neither a directory nor a symbolic link, +an ENOTDIR error is returned ("Not a directory"). + +If the component is found and is a directory, we set the +current lookup directory to that directory, and go to the +next component. + +If the component is found and is a symbolic link (symlink), we first +resolve this symbolic link (with the current lookup directory +as starting lookup directory). Upon error, that error is returned. +If the result is not a directory, an ENOTDIR error is returned. +If the resolution of the symlink is successful and returns a directory, +we set the current lookup directory to that directory, and go to +the next component. +Note that the resolution process here involves recursion. +In order to protect the kernel against stack overflow, and also +to protect against denial of service, there are limits on the +maximum recursion depth, and on the maximum number of symlinks +followed. An ELOOP error is returned when the maximum is +exceeded ("Too many levels of symbolic links"). +.\" +.\" presently: max recursion depth during symlink resolution: 5 +.\" max total number of symlinks followed: 40 +.\" _POSIX_SYMLOOP_MAX is 8 + +.SS "Step 3: Find the final entry" +The lookup of the final component of the pathname goes just like +that of all other components, as described in the previous step, +with two differences: (i) the final component need not be a +directory (at least as far as the path resolution process is concerned - +it may have to be a directory, or a non-directory, because of +the requirements of the specific system call), and (ii) it +is not necessarily an error if the component is not found - +maybe we are just creating it. The details on the treatment +of the final entry are described in the manual pages of the specific +system calls. + +.SS ". and .." +By convention, every directory has the entries "." and "..", +which refer to the directory itself and to its parent directory, +respectively. + +The path resolution process will assume that these entries have +their conventional meanings, regardless of whether they are +actually present in the physical filesystem. + +One cannot walk down past the root: "/.." is the same as "/". + +.SS "Mount points" +After a "mount dev path" command, the pathname "path" refers to +the root of the filesystem hierarchy on the device "dev", and no +longer to whatever it referred to earlier. + +One can walk out of a mounted filesystem: "path/.." refers to +the parent directy of "path", outside of the filesystem hierarchy on "dev". + +.SS "Trailing slashes" +If a pathname ends in a '/', that forces resolution of the preceding +component as in Step 2 - it has to exist and resolve to a directory. +Otherwise a trailing '/' is ignored. +(Or, equivalently, a pathname with a trailing '/' is equivalent to +the pathname obtained by appending '.' to it.) + +.SS "Final symlink" +If the last component of a pathname is a symbolic link, then it +depends on the system call whether the file referred to will be +the symbolic link or the result of path resolution on its contents. +For example, the system call +.BR lstat (2) +will operate on the symlink, while +.BR stat (2) +operates on the file pointed to by the symlink. + +.SS "Length limit" +There is a maximum length for pathnames. If the pathname (or some +intermediate pathname obtained while resolving symbolic links) +is too long, an ENAMETOOLONG error is returned ("File name too long"). + +.SS "Empty pathname" +In the original Unix, the empty pathname referred to the current directory. +Nowadays POSIX decrees that an empty pathname must not be resolved +successfully. Linux returns ENOENT in this case. + +.SS "Permissions" +The permission bits of a file consist of three groups of three bits, cf.\& +.BR chmod (1) +and +.BR stat (2). +The first group of three is used when the effective user ID of +the current process equals the owner ID of the file. The second group +of three is used when the group ID of the file either equals the +effective group ID of the current process, or is one of the +supplementary group IDs of the current process (as set by +.BR setgroups (2)). +When neither holds, the third group is used. + +Of the three bits used, the first bit determines read permission, +the second write permission, and the last execute permission +in case of ordinary files, or search permission in case of directories. + +Linux uses the fsuid instead of the effective user ID in permission checks. +Ordinarily the fsuid will equal the effective user ID, but the fsuid can be +changed by the system call +.BR setfsuid (2). + +(Here "fsuid" stands for something like "file system user ID". +The concept was required for the implementation of a user space +NFS server at a time when processes could send a signal to a process +with the same effective user ID. It is obsolete now. Nobody should use +.BR setfsuid (2).) + +Similarly, Linux uses the fsgid instead of the effective group ID. See +.BR setfsgid (2). + +.\" say sth on fs mounted read-only ? + +.SS "Capabilities" +If the permission bits of the file deny whatever is asked, permission +can still be granted by the appropriate capabilities. + +Traditional systems do not use capabilities and root (user ID 0) is +all-powerful. Such systems are presently (2.6.7) handled by giving root +all capabilities except for CAP_SETPCAP. More precisely, at exec time +a process gets all capabilities except CAP_SETPCAP and the five capabilities +CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH, CAP_FOWNER, CAP_FSETID, +in case it has zero euid, and it gets these last five capabilities +in case it has zero fsuid, while all other processes get no capabilities. + +The CAP_DAC_OVERRIDE capability overrides all permission checking, +but will only grant execute permission when at least one +of the three execute permission bits is set. + +The CAP_DAC_READ_SEARCH capability will grant read and search permission +on directories, and read permission on ordinary files. + +.\" Is there a better place for this? +The CAP_SYS_ADMIN capability will (e.g.) allow a process to violate +the limit (visible in +.IR /proc/sys/fs/file-max ) +on the maximum number of open files in the system, where a process +lacking that capability would see an ENFILE error return. + +.\" say sth on immutable files + +.\" say sth on ACLs + +.SH "SEE ALSO" +.BR capabilities (7) diff --git a/man2/pause.2 b/man2/pause.2 new file mode 100644 index 000000000..494528832 --- /dev/null +++ b/man2/pause.2 @@ -0,0 +1,67 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt (michael@moria.de) +.\" Modified Sat Jul 24 14:48:00 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995 by Mike Battersby (mib@deakin.edu.au) +.\" Modified 2000 by aeb, following Michael Kerrisk +.\" +.TH PAUSE 2 1995-08-31 "Linux" "Linux Programmer's Manual" +.SH NAME +pause \- wait for signal +.SH SYNOPSIS +.B #include +.sp +.B int pause(void); +.SH DESCRIPTION +The +.B pause +library function causes the invoking process (or thread) to sleep +until a signal is received that either terminates it or causes it +to call a signal-catching function. +.\" The +.\" .B pause +.\" system call causes the invoking process to sleep until a signal +.\" is received. +.SH "RETURN VALUE" +The +.B pause +function only returns when a signal was caught and the +signal-catching function returned. In this case +.B pause +returns \-1, and +.I errno +is set to +.\" .BR ERESTARTNOHAND . +.BR EINTR . +.SH ERRORS +.TP +.B EINTR +a signal was caught and the signal-catching function returned. +.SH "CONFORMING TO" +SVr4, SVID, POSIX, X/OPEN, BSD 4.3 +.SH "SEE ALSO" +.BR kill (2), +.BR select (2), +.BR signal (2) diff --git a/man2/pciconfig_iobase.2 b/man2/pciconfig_iobase.2 new file mode 100644 index 000000000..5ab299588 --- /dev/null +++ b/man2/pciconfig_iobase.2 @@ -0,0 +1 @@ +.so man2/pciconfig_read.2 diff --git a/man2/pciconfig_read.2 b/man2/pciconfig_read.2 new file mode 100644 index 000000000..f7551906f --- /dev/null +++ b/man2/pciconfig_read.2 @@ -0,0 +1,89 @@ +.\" Contributed by Niki A. Rahimi, LTC Security Development +.\" narahimi@us.ibm.com +.\" May be freely distributed. +.\" +.TH PCICONFIG_READ 2 2003-07-14 "Linux 2.4.19" "Linux Programmer's Manual" +.SH NAME +pciconfig_read, pciconfig_write, pciconfig_iobase \- pci device information handling +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int pciconfig_read(unsigned long " bus ", unsigned long " dfn , +.BI " unsigned long " off ", unsigned long " len ", void *" buf ); +.BI "int pciconfig_write(unsigned long " bus ", unsigned long " dfn , +.BI " unsigned long " off ", unsigned long " len ", void *" buf ); +.BI "int pciconfig_iobase(long " which ", unsigned long " bus , +.BI " unsigned long " devfn ); +.fi +.SH DESCRIPTION +.TP +Most of the interaction with PCI devices is already handled by the kernel PCI layer, and thus these calls should not normally need to be accessed from userspace. +.TP +.BR pciconfig_read +Reads to +.I +buf +from device +.I +dev +at offset +.I +off +value. +.TP +.BR pciconfig_write +Writes from +.I +buf +to device +.I +dev +at offset +.I +off +value. +.TP +.BR pciconfig_iobase +You pass it a bus/devfn pair and get a physical address for either the memory offset (for things like prep, this is 0xc0000000), the IO base for PIO cycles, or the ISA holes if any. +.SH "RETURN VALUE" +.TP +.BR pciconfig_read +On success zero is returned. On error, -1 is returned and errno is set appropriately. +.TP +.BR pciconfig_write +On success zero is returned. On error, -1 is returned and errno is set appropriately. +.TP +.BR pciconfig_iobase +Returns information on locations of various I/O regions in physical memory according to the +.I which +value. Values for +.I which +are: IOBASE_BRIDGE_NUMBER, IOBASE_MEMORY, IOBASE_IO, IOBASE_ISA_IO, IOBASE_ISA_MEM. +.SH ERRORS +.TP +.B EINVAL +.I len +value is invalid. This does not apply to pci_iobase. +.TP +.B EIO +I/O error. +.TP +.B ENODEV +For pci_iobase, hose value is NULL? For the other calls, could not find a slot. +.TP +.B ENOSYS +The system has not implemented these calls (CONFIG_PCI not defined). +.TP +.B EOPNOTSUPP +This return value is only valid for pci_iobase. It is returned if the value for +.I +which +is invalid. +.TP +.B EPERM +User does not have the CAP_SYS_ADMIN capability. This does not apply to pci_iobase. +.SH "CONFORMING TO" +These calls are Linux specific, available since Linux 2.0.26/2.1.11. +.SH "SEE ALSO" +.BR capabilities (7) diff --git a/man2/pciconfig_write.2 b/man2/pciconfig_write.2 new file mode 100644 index 000000000..5ab299588 --- /dev/null +++ b/man2/pciconfig_write.2 @@ -0,0 +1 @@ +.so man2/pciconfig_read.2 diff --git a/man2/personality.2 b/man2/personality.2 new file mode 100644 index 000000000..86f5c903c --- /dev/null +++ b/man2/personality.2 @@ -0,0 +1,64 @@ +.\" Copyright (C) 1995, Thomas K. Dyas +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Created Sat Aug 21 1995 Thomas K. Dyas +.\" +.\" typo corrected, aeb, 950825 +.\" added layout change from joey, 960722 +.\" changed prototype, documented 0xffffffff, aeb, 030101 +.\" +.TH PERSONALITY 2 2003-01-01 "Linux 2.0" "Linux Programmer's Manual" +.SH NAME +personality \- set the process execution domain +.SH SYNOPSIS +.BI "long personality(unsigned long " persona ); +.SH DESCRIPTION +Linux supports different execution domains, or personalities, for each +process. Among other things, execution domains tell Linux how to map +signal numbers into signal actions. The execution domain system allows +Linux to provide limited support for binaries compiled under other +Unix-like operating systems. + +This function will return the current +.B personality +when +.I persona +equals 0xffffffff. Otherwise, it will make the execution domain +referenced by +.I persona +the new execution domain of the current process. +.SH "RETURN VALUE" +On success, the previous +.I persona +is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +The kernel was unable to change the personality. +.PP +.SH FILES +.I /usr/include/linux/personality.h +.SH "CONFORMING TO" +.B personality +is Linux-specific and should not be used in programs intended to be portable. diff --git a/man2/pipe.2 b/man2/pipe.2 new file mode 100644 index 000000000..3e03ab3b9 --- /dev/null +++ b/man2/pipe.2 @@ -0,0 +1,67 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 2004-06-17 by Michael Kerrisk +.\" +.TH PIPE 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +pipe \- create pipe +.SH SYNOPSIS +.B #include +.sp +.BI "int pipe(int " filedes "[2]);" +.SH DESCRIPTION +.B pipe +creates a pair of file descriptors, pointing to a pipe inode, and places +them in the array pointed to by +.IR filedes . +.I filedes[0] +is for reading, +.I filedes[1] +is for writing. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.I filedes +is not valid. +.TP +.B EMFILE +Too many file descriptors are in use by the process. +.TP +.B ENFILE +The system limit on the total number of open files has been reached. +.SH "CONFORMING TO" +SVr4, SVID, AT&T, POSIX, X/OPEN, BSD 4.3 +.SH "SEE ALSO" +.BR fork (2), +.BR read (2), +.BR socketpair (2), +.BR write (2) diff --git a/man2/pivot_root.2 b/man2/pivot_root.2 new file mode 100644 index 000000000..59ae23531 --- /dev/null +++ b/man2/pivot_root.2 @@ -0,0 +1,111 @@ +.\" Copyright (C) 2000 by Werner Almesberger +.\" May be distributed under GPL +.\" +.\" Written 2000-02-23 by Werner Almesberger +.\" Modified 2004-06-17 Michael Kerrisk +.\" +.TH PIVOT_ROOT 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +pivot_root \- change the root file system +.SH SYNOPSIS +.B #include +.sp +.B _syscall2(int,pivot_root,const char *,new_root,const char *,put_old) +.sp +.BI "int pivot_root(const char *" new_root ", const char *" put_old ); +.SH DESCRIPTION +\fBpivot_root\fP moves the root file system of the current process to the +directory \fIput_old\fP and makes \fInew_root\fP the new root file system +of the current process. +.\" +.\" The +.\" .B CAP_SYS_ADMIN +.\" capability is required. + +The typical use of \fBpivot_root\fP is during system startup, when the +system mounts a temporary root file system (e.g. an \fBinitrd\fP), then +mounts the real root file system, and eventually turns the latter into +the current root of all relevant processes or threads. + +\fBpivot_root\fP may or may not change the current root and the current +working directory (cwd) of any processes or threads which use the old +root directory. The caller of \fBpivot_root\fP +must ensure that processes with root or cwd at the old root operate +correctly in either case. An easy way to ensure this is to change their +root and cwd to \fInew_root\fP before invoking \fBpivot_root\fP. + +The paragraph above is intentionally vague because the implementation +of \fBpivot_root\fP may change in the future. At the time of writing, +\fBpivot_root\fP changes root and cwd of each process or +thread to \fInew_root\fP if they point to the old root directory. This +is necessary in order to prevent kernel threads from keeping the old +root directory busy with their root and cwd, even if they never access +the file system in any way. In the future, there may be a mechanism for +kernel threads to explicitly relinquish any access to the file system, +such that this fairly intrusive mechanism can be removed from +\fBpivot_root\fP. + +Note that this also applies to the current process: \fBpivot_root\fP may +or may not affect its cwd. It is therefore recommended to call +\fBchdir("/")\fP immediately after \fBpivot_root\fP. + +The following restrictions apply to \fInew_root\fP and \fIput_old\fP: +.IP \- 3 +They must be directories. +.IP \- 3 +\fInew_root\fP and \fIput_old\fP must not be on the same file system as +the current root. +.IP \- 3 +\fIput_old\fP must be underneath \fInew_root\fP, i.e. adding a non-zero +number of \fB/..\fP to the string pointed to by \fIput_old\fP must yield +the same directory as \fInew_root\fP. +.IP \- 3 +No other file system may be mounted on \fIput_old\fP. +.PP +See also \fBpivot_root(8)\fP for additional usage examples. + +If the current root is not a mount point (e.g. after \fBchroot(2)\fP or +\fBpivot_root\fP, see also below), not the old root directory, but the +mount point of that file system is mounted on \fIput_old\fP. +.SH NOTES +\fInew_root\fP does not have to be a mount point. In this case, +\fB/proc/mounts\fP will show the mount point of the file system containing +\fInew_root\fP as root (\fB/\fP). +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +\fIerrno\fP is set appropriately. +.SH ERRORS +\fBpivot_root\fP may return (in \fIerrno\fP) any of the errors returned by +\fBstat(2)\fP. Additionally, it may return: + +.TP +.B EBUSY +\fInew_root\fP or \fIput_old\fP are on the current root file system, +or a file system is already mounted on \fIput_old\fP. +.TP +.B EINVAL +\fIput_old\fP is not underneath \fInew_root\fP. +.TP +.B ENOTDIR +\fInew_root\fP or \fIput_old\fP is not a directory. +.TP +.B EPERM +The current process does not have the +.B CAP_SYS_ADMIN +capability. +.SH BUGS +\fBpivot_root\fP should not have to change root and cwd of all other +processes in the system. + +Some of the more obscure uses of \fBpivot_root\fP may quickly lead to +insanity. +.SH "CONFORMING TO" +\fBpivot_root\fP is Linux-specific and hence is not portable. +.SH HISTORY +\fBpivot_root\fP was introduced in Linux 2.3.41. +.SH "SEE ALSO" +.BR chdir (2), +.BR chroot (2), +.BR stat (2), +.BR initrd (4), +.BR pivot_root (8) diff --git a/man2/poll.2 b/man2/poll.2 new file mode 100644 index 000000000..a04ea75e4 --- /dev/null +++ b/man2/poll.2 @@ -0,0 +1,145 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Additions from Richard Gooch and aeb, 971207 +.\" +.TH POLL 2 1997-12-07 "Linux 2.1.23" "Linux Programmer's Manual" +.SH NAME +poll \- wait for some event on a file descriptor +.SH SYNOPSIS +.B #include +.sp +.BI "int poll(struct pollfd *" ufds ", unsigned int " nfds ", int " timeout ); +.SH DESCRIPTION +.B poll +is a variation on the theme of +.BR select . +It specifies an array of +.I nfds +structures of type +.br +.nf + struct pollfd { + int fd; /* file descriptor */ + short events; /* requested events */ + short revents; /* returned events */ + }; +.fi +and a +.I timeout +in milliseconds. A negative value means infinite timeout. +The field +.I fd +contains a file descriptor for an open file. +The field +.I events +is an input parameter, a bitmask specifying the events the application +is interested in. +The field +.I revents +is an output parameter, filled by the kernel with the events that +actually occurred, either of the type requested, or of one of the +types +.B POLLERR +or +.B POLLHUP +or +.BR POLLNVAL . +(These three bits are meaningless in the +.I events +field, and will be set in the +.I revents +field whenever the corresponding condition is true.) +If none of the events requested (and no error) has occurred for any +of the file descriptors, the kernel waits for +.I timeout +milliseconds for one of these events to occur. +The following possible bits in these masks are defined in +.br +.nf + #define POLLIN 0x0001 /* There is data to read */ + #define POLLPRI 0x0002 /* There is urgent data to read */ + #define POLLOUT 0x0004 /* Writing now will not block */ + #define POLLERR 0x0008 /* Error condition */ + #define POLLHUP 0x0010 /* Hung up */ + #define POLLNVAL 0x0020 /* Invalid request: fd not open */ +.fi +When compiling XPG4.2 source one also has +.br +.nf +#ifdef _XOPEN_SOURCE + #define POLLRDNORM 0x0040 /* Normal data may be read */ + #define POLLRDBAND 0x0080 /* Priority data may be read */ + #define POLLWRNORM 0x0100 /* Writing now will not block */ + #define POLLWRBAND 0x0200 /* Priority data may be written */ +#endif +.fi +Finally, Linux knows about +.br +.nf +#ifdef _GNU_SOURCE + #define POLLMSG 0x0400 +#endif +.fi +.SH "RETURN VALUE" +On success, a positive number is returned, where the number returned +is the number of structures which have non-zero +.I revents +fields (in other words, those descriptors with events or errors reported). +A value of 0 indicates that the call timed out and no file +descriptors have been selected. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +An invalid file descriptor was given in one of the sets. +.TP +.B EFAULT +The array given as argument was not contained in the calling program's +address space. +.TP +.B EINTR +A signal occurred before any requested event. +.TP +.B EINVAL +The +.I nfds +value exceeds the RLIMIT_NOFILE value. +.TP +.B ENOMEM +There was no space to allocate file descriptor tables. +.SH BUGS +See the BUGS section of +.BR select (2). +.SH "CONFORMING TO" +XPG4-UNIX. +.SH AVAILABILITY +The poll() systemcall was introduced in Linux 2.1.23. +The poll() library call was introduced in libc 5.4.28 +(and provides emulation using select if your kernel does not +have a poll syscall). +.SH "SEE ALSO" +.BR select (2), +.BR select_tut (2) diff --git a/man2/posix_fadvise.2 b/man2/posix_fadvise.2 new file mode 100644 index 000000000..814e3b21f --- /dev/null +++ b/man2/posix_fadvise.2 @@ -0,0 +1,107 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 2003 Abhijit Menon-Sen +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH POSIX_FADVISE 2 "14 Feb 2003" "Linux 2.5.60" "Linux Programmer's Manual" +.SH NAME +posix_fadvise \- predeclare an access pattern for file data +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int posix_fadvise(int " fd ", off_t " offset ", off_t " len ", int " advice ");" +.fi +.SH DESCRIPTION +Programs can use \fBposix_fadvise\fP to announce an intention to access +file data in a specific pattern in the future, thus allowing the kernel +to perform appropriate optimisations. + +The \fIadvice\fP applies to a (not necessarily existent) region starting +at \fIoffset\fP and extending for \fIlen\fP bytes (or until the end of +the file if \fIlen\fP is 0) within the file referred to by \fIfd\fP. The +advice is not binding; it merely constitutes an expectation on behalf of +the application. + +Permissible values for \fIadvice\fP include: +.TP +.B POSIX_FADV_NORMAL +Indicates that the application has no advice to give about its access +pattern for the specified data. If no advice is given for an open file, +this is the default assumption. +.TP +.B POSIX_FADV_SEQUENTIAL +The application expects to access the specified data sequentially (with +lower offsets read before higher ones). +.TP +.B POSIX_FADV_RANDOM +The specified data will be accessed in random order. +.TP +.B POSIX_FADV_NOREUSE +The specified data will be accessed only once. +.TP +.B POSIX_FADV_WILLNEED +The specified data will be accessed in the near future. +.TP +.B POSIX_FADV_DONTNEED +The specified data will not be accessed in the near future. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and \fIerrno\fP +is set appropriately. +.SH ERRORS +.TP +.B EBADF +The \fIfd\fP argument was not a valid file descriptor. +.TP +.B EINVAL +An invalid value was specified for \fIadvice\fP. +.TP +.B ESPIPE +The specified file descriptor refers to a pipe or FIFO. (Linux actually +returns EINVAL in this case.) +.SH NOTES +Under Linux, \fBPOSIX_FADV_NORMAL\fP sets the readahead window to the +default size for the backing device; \fBPOSIX_FADV_SEQUENTIAL\fP doubles +this size, and \fBPOSIX_FADV_RANDOM\fP disables file readahead entirely. +These changes affect the the entire file, not just the specified region +(but other open file handles to the same file are unaffected). + +\fBPOSIX_FADV_WILLNEED\fP and \fBPOSIX_FADV_NOREUSE\fP both initiate a +non-blocking read of the specified region into the page cache. The amount +of data read may be decreased by the kernel depending on VM load. (A few +megabytes will usually be fully satisfied, and more is rarely useful.) + +\fBPOSIX_FADV_DONTNEED\fP attempts to free cached pages associated with +the specified region. This is useful, for example, while streaming large +files. A program may periodically request the kernel to free cached data +that has already been used, so that more useful cached pages are not +discarded instead. + +Pages that have not yet been written out will be unaffected, so if the +application wishes to guarantee that pages will be released, it should +call \fBfsync\fP or \fBfdatasync\fP first. +.SH "CONFORMING TO" +SUSv3 (Advanced Realtime Option), POSIX 1003.1-2003. +Note that the type of the +.I len +parameter was changed from size_t to off_t in POSIX 1003.1-2003 TC5. +.SH "SEE ALSO" +.BR posix_fallocate "(2), " posix_madvise "(2)." diff --git a/man2/prctl.2 b/man2/prctl.2 new file mode 100644 index 000000000..a22b945e4 --- /dev/null +++ b/man2/prctl.2 @@ -0,0 +1,127 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 1998 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Thu Nov 11 04:19:42 MET 1999, aeb: added PR_GET_PDEATHSIG +.\" Modified 27 Jun 02, Michael Kerrisk +.\" Added PR_SET_DUMPABLE, PR_GET_DUMPABLE, +.\" PR_SET_KEEPCAPS, PR_GET_KEEPCAPS +.\" +.\" FIXME: The following (applicable only on IA-64) are not currently +.\" described: PR_SET_UNALIGN, PR_GET_UNALIGN, PR_SET_FPEMU, PR_GET_FPEMU +.\" +.TH PRCTL 2 2002-06-27 "Linux 2.4.18" "Linux Programmer's Manual" +.SH NAME +prctl \- operations on a process +.SH SYNOPSIS +.B #include +.sp +.BI "int prctl(int " option ", unsigned long " arg2 ", unsigned long " arg3 +.BI ", unsigned long " arg4 ", unsigned long " arg5 ); +.SH DESCRIPTION +.B prctl +is called with a first argument describing what to do +(with values defined in <\fIlinux/prctl.h\fP>), and further +parameters with a significance depending on the first one. +The first argument can be: +.TP +.B PR_SET_PDEATHSIG +(since Linux 2.1.57) +Set the parent process death signal +of the current process to \fIarg2\fP (either a signal value +in the range 1..maxsig, or 0 to clear). +This is the signal that the current process will get when its +parent dies. This value is cleared upon a fork(). +.TP +.B PR_GET_PDEATHSIG +(since Linux 2.3.15) +Read the current value of the parent process death signal +into the (int *) \fIarg2\fP. +.TP +.B PR_SET_DUMPABLE +(Since Linux 2.4) +Set the state of the flag determining whether core dumps are produced +for this process upon delivery of a signal whose default behaviour is +to produce a core dump. +(Normally this flag is set for a process by default, but it is cleared +when a set-UID or set-GID program is executed and also by various system +calls that manipulate process UIDs and GIDs). +.I arg2 +must be either 0 (process is not dumpable) or 1 (process is dumpable). +.TP +.B PR_GET_DUMPABLE +(Since Linux 2.4) +Return (as the function result) the current state of the calling +process's dumpable flag. +.TP +.B PR_SET_KEEPCAPS +Set the state of the process's "keep capabilities" flag, +which determines whether the process's effective and permitted +capability sets are cleared when a change is made to the process's user IDs +such that all of the process's real, effective, and saved set user IDs +become non-zero when at least one of them previously had the value 0. +(By default, these credential sets are cleared). +.I arg2 +must be either 0 (capabilities are cleared) or 1 (capabilities are kept). +.TP +.B PR_GET_KEEPCAPS +Return (as the function result) the current state of the calling process's +"keep capabilities" flag. +.SH "RETURN VALUE" +.B PR_GET_DUMPABLE +and +.B PR_GET_KEEPCAPS +return 0 or 1 on success. +All other +.I option +values return 0 on success. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +The value of +.I option +is not recognized, or it is +.B PR_SET_PDEATHSIG +and +.I arg2 +is not zero or a signal number. +.SH "CONFORMING TO" +This call is Linux-specific. +IRIX has a prctl system call (also introduced in Linux 2.1.44 +as irix_prctl on the MIPS architecture), +with prototype +.sp +.BI "ptrdiff_t prctl(int " option ", int " arg2 ", int " arg3 ); +.sp +and options to get the maximum number of processes per user, +get the maximum number of processors the calling process can use, +find out whether a specified process is currently blocked, +get or set the maximum stack size, etc., etc. +.SH AVAILABILITY +The prctl() systemcall was introduced in Linux 2.1.57. +There is no prctl() library call as yet. +.SH "SEE ALSO" +.BR signal (2) diff --git a/man2/pread.2 b/man2/pread.2 new file mode 100644 index 000000000..d0dffa921 --- /dev/null +++ b/man2/pread.2 @@ -0,0 +1,87 @@ +.\" Copyright (C) 1999 Joseph Samuel Myers. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH PREAD 2 1999-01-21 "Linux 2.2.0-pre9" "Linux Programmer's Manual" +.SH NAME +pread, pwrite \- read from or write to a file descriptor at a given offset +.SH SYNOPSIS +.B #define _XOPEN_SOURCE 500 +.sp +.B #include +.sp +.BI "ssize_t pread(int " fd ", void *" buf ", size_t " count ", off_t " offset ); +.sp +.BI "ssize_t pwrite(int " fd ", const void *" buf ", size_t " count ", off_t " offset ); +.fi +.SH DESCRIPTION +.B pread() +reads up to +.I count +bytes from file descriptor +.I fd +at offset +.I offset +(from the start of the file) into the buffer starting at +.IR buf . +The file offset is not changed. +.PP +.B pwrite() +writes up to +.I count +bytes from the buffer starting at +.I buf +to the file descriptor +.I fd +at offset +.IR offset . +The file offset is not changed. +.PP +The file referenced by +.I fd +must be capable of seeking. +.SH "RETURN VALUE" +On success, the number of bytes read or written is returned (zero +indicates that nothing was written, in the case of \fBpwrite\fR, or +end of file, in the case of \fBpread\fR), or \-1 on error, in which +case +.I errno +is set to indicate the error. +.SH ERRORS +.B pread +can fail and set +.I errno +to any error specified for \fBread\fR(2) or \fBlseek\fR(2). +.B pwrite +can fail and set +.I errno +to any error specified for \fBwrite\fR(2) or \fBlseek\fR(2). +.SH "CONFORMING TO" +Unix98 +.SH HISTORY +The \fBpread\fR and \fBpwrite\fR system calls were added to Linux in +version 2.1.60; the entries in the i386 system call table were added +in 2.1.69. The libc support (including emulation on older kernels +without the system calls) was added in glibc 2.1. +.SH "SEE ALSO" +.BR lseek (2), +.BR read (2), +.BR write (2) diff --git a/man2/prof.2 b/man2/prof.2 new file mode 100644 index 000000000..5d25ea6ce --- /dev/null +++ b/man2/prof.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/pselect.2 b/man2/pselect.2 new file mode 100644 index 000000000..e17784318 --- /dev/null +++ b/man2/pselect.2 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man2/ptrace.2 b/man2/ptrace.2 new file mode 100644 index 000000000..b319b53c1 --- /dev/null +++ b/man2/ptrace.2 @@ -0,0 +1,269 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" changes Copyright 1999 Mike Coleman (mkc@acm.org) +.\" -- major revision to fully document ptrace semantics per recent Linux +.\" kernel (2.2.10) and glibc (2.1.2) +.\" Sun Nov 7 03:18:35 CST 1999 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Fri Jul 23 23:47:18 1993 by Rik Faith +.\" Modified Fri Jan 31 16:46:30 1997 by Eric S. Raymond +.\" Modified Thu Oct 7 17:28:49 1999 by Andries Brouwer +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH PTRACE 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +ptrace \- process trace +.SH SYNOPSIS +.B #include +.sp +.BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", void *" addr ", void *" data ); +.SH DESCRIPTION +The +.B ptrace +system call provides a means by which a parent process may observe and control +the execution of another process, and examine and change its core image and +registers. It is primarily used to implement breakpoint debugging and system +call tracing. +.LP +The parent can initiate a trace by calling +.BR fork (2) +and having the resulting child do a PTRACE_TRACEME, followed (typically) by an +.BR exec (3). +Alternatively, the parent may commence trace of an existing process using +PTRACE_ATTACH. +.LP +While being traced, the child will stop each time a signal is delivered, even +if the signal is being ignored. (The exception is SIGKILL, which has its +usual effect.) The parent will be notified at its next +.BR wait (2) +and may inspect and modify the child process while it is stopped. The parent +then causes the child to continue, optionally ignoring the delivered signal +(or even delivering a different signal instead). +.LP +When the parent is finished tracing, it can terminate the child with +PTRACE_KILL or cause it to continue executing in a normal, untraced mode +via PTRACE_DETACH. +.LP +The value of \fIrequest\fP determines the action to be performed: +.TP +PTRACE_TRACEME +Indicates that this process is to be traced by its parent. Any signal +(except SIGKILL) delivered to this process will cause it to stop and its +parent to be notified via +.BR wait. +Also, all subsequent calls to +.BR exec +by this process will cause a SIGTRAP to be sent to it, giving the parent a +chance to gain control before the new program begins execution. A process +probably shouldn't make this request if its parent isn't expecting to trace +it. (\fIpid\fP, \fIaddr\fP, and \fIdata\fP are ignored.) +.LP +The above request is used only by the child process; the rest are used only by +the parent. In the following requests, \fIpid\fP specifies the child process +to be acted on. For requests other than PTRACE_KILL, the child process must +be stopped. +.TP +PTRACE_PEEKTEXT, PTRACE_PEEKDATA +Reads a word at the location +.IR addr +in the child's memory, returning the word as the result of the +.B ptrace +call. Linux does not have separate text and data address spaces, so the two +requests are currently equivalent. (The argument \fIdata\fP is ignored.) +.TP +PTRACE_PEEKUSR +Reads a word at offset +.I addr +in the child's +.B USER +area, which holds the registers and other information about the process (see + and ). The word is returned as the result of the +.B ptrace +call. Typically the offset must be word-aligned, though this might vary by +architecture. (\fIdata\fP is ignored.) +.TP +PTRACE_POKETEXT, PTRACE_POKEDATA +Copies the word +.IR data +to location +.IR addr +in the child's memory. As above, the two requests are currently equivalent. +.TP +PTRACE_POKEUSR +Copies the word +.IR data +to offset +.I addr +in the child's +.B USER +area. As above, the offset must typically be word-aligned. In order to +maintain the integrity of the kernel, some modifications to the +.B USER +area are disallowed. +.TP +PTRACE_GETREGS, PTRACE_GETFPREGS +Copies the child's general purpose or floating-point registers, respectively, +to location \fIdata\fP in the parent. See for information on +the format of this data. (\fIaddr\fP is ignored.) +.TP +PTRACE_SETREGS, PTRACE_SETFPREGS +Copies the child's general purpose or floating-point registers, respectively, +from location \fIdata\fP in the parent. As for PTRACE_POKEUSER, some general +purpose register modifications may be disallowed. (\fIaddr\fP is ignored.) +.TP +PTRACE_CONT +Restarts the stopped child process. If \fIdata\fP is non-zero and not +SIGSTOP, it is interpreted as a signal to be delivered to the child; +otherwise, no signal is delivered. Thus, for example, the parent can control +whether a signal sent to the child is delivered or not. (\fIaddr\fP is +ignored.) +.TP +PTRACE_SYSCALL, PTRACE_SINGLESTEP +Restarts the stopped child as for PTRACE_CONT, but arranges for the child to +be stopped at the next entry to or exit from a system call, or after execution +of a single instruction, respectively. (The child will also, as usual, be +stopped upon receipt of a signal.) From the parent's perspective, the child +will appear to have been stopped by receipt of a SIGTRAP. So, for +PTRACE_SYSCALL, for example, the idea is to inspect the arguments to the +system call at the first stop, then do another PTRACE_SYSCALL and inspect the +return value of the system call at the second stop. (\fIaddr\fP is ignored.) +.TP +PTRACE_KILL +Sends the child a SIGKILL to terminate it. (\fIaddr\fP and \fIdata\fP are +ignored.) +.TP +PTRACE_ATTACH +Attaches to the process specified in +.IR pid , +making it a traced "child" of the current process; the behavior of the child +is as if it had done a PTRACE_TRACEME. The current process actually becomes +the parent of the child process for most purposes (e.g., it will receive +notification of child events and appears in +.BR ps (1) +output as the child's parent), but a +.BR getppid (2) +by the child will still return the pid of the original parent. The child is +sent a SIGSTOP, but will not necessarily have stopped by the completion of +this call; use +.BR wait +to wait for the child to stop. (\fIaddr\fP and \fIdata\fP are ignored.) +.TP +PTRACE_DETACH +Restarts the stopped child as for PTRACE_CONT, but first detaches from the +process, undoing the reparenting effect of PTRACE_ATTACH, and the effects of +PTRACE_TRACEME. Although perhaps not intended, under Linux a traced child +can be detached in this way regardless of which method was used to initiate +tracing. (\fIaddr\fP is ignored.) +.SH NOTES +Although arguments to +.B ptrace +are interpreted according to the prototype given, GNU libc currently declares +.B ptrace +as a variadic function with only the \fIrequest\fP argument fixed. This means +that unneeded trailing arguments may be omitted, though doing so makes use of +undocumented +.B gcc(1) +behavior. +.LP +.BR init (8), +the process with pid 1, may not be traced. +.LP +The layout of the contents of memory and the USER area are quite OS- and +architecture-specific. +.LP +The size of a "word" is determined by the OS variant (e.g., for 32-bit Linux +it's 32 bits, etc.). +.LP +Tracing causes a few subtle differences in the semantics of traced processes. +For example, if a process is attached to with PTRACE_ATTACH, its original +parent can no longer receive notification via +.BR wait +when it stops, and there is no way for the new parent to effectively simulate +this notification. +.LP +This page documents the way the +.B ptrace +call works currently in Linux. Its behavior differs noticeably on other +flavors of Unix. In any case, use of +.B ptrace +is highly OS- and architecture-specific. +.LP +The SunOS man page describes +.B ptrace +as "unique and arcane", which it is. The proc-based debugging interface +present in Solaris 2 implements a superset of +.B ptrace +functionality in a more powerful and uniform way. +.SH "RETURN VALUE" +On success, PTRACE_PEEK* requests return the requested data, while other requests +return zero. On error, all requests return \-1, and +.IR errno (3) +is set appropriately. Since the value returned by a successful PTRACE_PEEK* +request may be \-1, the caller must check +.I errno +after such requests to determine whether or not an error occurred. +.SH ERRORS +.TP +.B EBUSY +(i386 only) There was an error with allocating or freeing a debug register. +.TP +.B EFAULT +There was an attempt to read from or write to an invalid area in the parent's +or child's memory, probably because the area wasn't mapped or accessible. +Unfortunately, under Linux, different variations of this fault will return EIO +or EFAULT more or less arbitrarily. +.TP +.B EIO +\fIrequest\fP is invalid, or an attempt was made to read from or write to an +invalid area in the parent's or child's memory, or there was a word-alignment +violation, or an invalid signal was specified during a restart request. +.TP +.B EPERM +The specified process cannot be traced. This could be because the +parent has insufficient privileges (the required capability is +.BR CAP_SYS_PTRACE ); +non-root processes cannot trace processes that they +cannot send signals to or those running setuid/setgid programs, for obvious +reasons. Alternatively, the process may already be being traced, or be +.BR init +(pid 1). +.TP +.B ESRCH +The specified process does not exist, or is not currently being traced by the +caller, or is not stopped (for requests that require that). +.SH "CONFORMING TO" +SVr4, SVID EXT, AT&T, X/OPEN, BSD 4.3 +.SH "SEE ALSO" +.BR gdb (1), +.BR strace (1), +.BR execve (2), +.BR fork (2), +.BR signal (2), +.BR wait (2), +.BR exec (3), +.BR capabilities (7) diff --git a/man2/putpmsg.2 b/man2/putpmsg.2 new file mode 100644 index 000000000..5d25ea6ce --- /dev/null +++ b/man2/putpmsg.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/pwrite.2 b/man2/pwrite.2 new file mode 100644 index 000000000..87eacb238 --- /dev/null +++ b/man2/pwrite.2 @@ -0,0 +1 @@ +.so man2/pread.2 diff --git a/man2/quotactl.2 b/man2/quotactl.2 new file mode 100644 index 000000000..b6b1d5a1f --- /dev/null +++ b/man2/quotactl.2 @@ -0,0 +1,185 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH QUOTACTL 2 1996-04-14 "Linux 1.3.88" "Linux Programmer's Manual" +.SH NAME +quotactl \- manipulate disk quota +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int quotactl(int " cmd ", const char *" special ", int " id , +.BI "caddr_t " addr ); +.sp +.B #include +.sp +.BI "_syscall4(int, quotactl, int, " cmd ", const char *, " special +.BI ", int, " id ", caddr_t, " addr ); +.SH DESCRIPTION +The quota system defines for each user and/or group a soft limit +and a hard limit bounding the amount of disk space that can be +used on a given file system. The hard limit cannot be crossed. +The soft limit can be crossed, but warnings will ensue. Moreover, +the user cannot be above the soft limit for more than one week (by default) +at a time: after this week the soft limit counts as hard limit. + +The +.B quotactl +system call manipulates these quota. Its first argument is +of the form +.BI QCMD( subcmd , type ) +where +.I type +is either +.B USRQUOTA +or +.B GRPQUOTA +(for user quota and group quota, respectively), and +.I subcmd +is described below. + +The second argument +.I special +is the block special device these quota apply to. +It must be mounted. + +The third argument +.I id +is the user or group ID these quota apply to (when relevant). + +The fourth argument +.I addr +is the address of a data structure, depending on the command. + +The +.I subcmd +is one of +.TP 1.1i +.B Q_QUOTAON +Enable quota. The +.I addr +argument is the pathname of the file containing +the quota for the filesystem. +.TP +.B Q_QUOTAOFF +Disable quota. +.TP +.B Q_GETQUOTA +Get limits and current usage of disk space. The +.I addr +argument is a pointer to a dqblk structure (defined in +.IR ). +.TP +.B Q_SETQUOTA +Set limits and current usage; +.I addr +is as before. +.TP +.B Q_SETQLIM +Set limits; +.I addr +is as before. +.TP +.B Q_SETUSE +Set usage. +.TP +.B Q_SYNC +Sync disk copy of a filesystem's quota. +.TP +.B Q_GETSTATS +Get collected stats. + +.SH "RETURN VALUE" +On success, +.B quotactl +returns 0. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP 0.9i +.B EACCES +The quota file is not an ordinary file. +.TP +.B EBUSY +.B Q_QUOTAON +was asked, but quota were enabled already. +.TP +.B EFAULT +Bad +.I addr +value. +.TP +.B EINVAL +.I type +is not a known quota type. Or, +.I special +could not be found. +.TP +.B EIO +Cannot read or write the quota file. +.TP +.B EMFILE +Too many open files: cannot open quota file. +.TP +.B ENODEV +.I special +cannot be found in the mount table. +.TP +.B ENOPKG +The kernel was compiled without quota support. +.TP +.B ENOTBLK +.I special +is not a block special device. +.TP +.B EPERM +The process was not root (for the file system), and +.B Q_GETQUOTA +was asked for another +.I id +than that of the process itself, or anything other than +.B Q_GETSTATS +or +.B Q_SYNC +was asked. +.TP +.B ESRCH +.B Q_GETQUOTA +or +.B Q_SETQUOTA +or +.B Q_SETUSE +or +.B Q_SETQLIM +was asked for a file system that didn't have quota enabled. +.SH "CONFORMING TO" +BSD +.SH "SEE ALSO" +.BR quota (1), +.BR getrlimit (2), +.BR setrlimit (2), +.BR ulimit (3), +.BR quotacheck (8), +.BR quotaon (8) diff --git a/man2/read.2 b/man2/read.2 new file mode 100644 index 000000000..e7539a03c --- /dev/null +++ b/man2/read.2 @@ -0,0 +1,140 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt, Ian Jackson. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Sat Jul 24 00:06:00 1993 by Rik Faith +.\" Modified Wed Jan 17 16:02:32 1996 by Michael Haardt +.\" +.\" Modified Thu Apr 11 19:26:35 1996 by Andries Brouwer +.\" Modified Sun Jul 21 18:59:33 1996 by Andries Brouwer +.\" Modified Fri Jan 31 16:47:33 1997 by Eric S. Raymond +.\" Modified Sat Jul 12 20:45:39 1997 by Michael Haardt +.\" +.\" +.TH READ 2 1997-07-12 "Linux 2.0.32" "Linux Programmer's Manual" +.SH NAME +read \- read from a file descriptor +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "ssize_t read(int " fd ", void *" buf ", size_t " count ); +.fi +.SH DESCRIPTION +.B read() +attempts to read up to +.I count +bytes from file descriptor +.I fd +into the buffer starting at +.IR buf . +.PP +If +.I count +is zero, \fBread()\fP returns zero and has no other results. +If +.I count +is greater than SSIZE_MAX, the result is unspecified. +.PP +.SH "RETURN VALUE" +On success, the number of bytes read is returned (zero indicates end of +file), and the file position is advanced by this number. +It is not an error if this number is smaller than the number of bytes +requested; this may happen for example because fewer bytes are actually +available right now (maybe because we were close to end-of-file, or +because we are reading from a pipe, or from a terminal), or because +\fBread()\fP was interrupted by a signal. +On error, \-1 is returned, and +.I errno +is set appropriately. In this case it is left unspecified whether +the file position (if any) changes. +.SH ERRORS +.TP +.B EAGAIN +Non-blocking I/O has been selected using +.B O_NONBLOCK +and no data was immediately available for reading. +.TP +.B EBADF +.I fd +is not a valid file descriptor or is not open for reading. +.TP +.B EFAULT +.I buf +is outside your accessible address space. +.TP +.B EINTR +The call was interrupted by a signal before any data was read. +.TP +.B EINVAL +.I fd +is attached to an object which is unsuitable for reading. +.TP +.B EIO +I/O error. This will happen for example when the process is in a +background process group, tries to read from its controlling tty, +and either it is ignoring or blocking SIGTTIN or its process group +is orphaned. It may also occur when there is a low-level I/O error +while reading from a disk or tape. +.TP +.B EISDIR +.I fd +refers to a directory. +.PP +Other errors may occur, depending on the object connected to +.IR fd . +POSIX allows a +.B read +that is interrupted after reading some data +to return \-1 (with +.I errno +set to EINTR) or to return the number of bytes already read. +.SH "CONFORMING TO" +SVr4, SVID, AT&T, POSIX, X/OPEN, BSD 4.3 +.SH RESTRICTIONS +On NFS file systems, reading small amounts of data will only update the +time stamp the first time, subsequent calls may not do so. This is caused +by client side attribute caching, because most if not all NFS clients +leave atime updates to the server and client side reads satisfied from the +client's cache will not cause atime updates on the server as there are no +server side reads. UNIX semantics can be obtained by disabling client +side attribute caching, but in most situations this will substantially +increase server load and decrease performance. +.PP +Many filesystems and disks were considered to be fast enough that the +implementation of +.B O_NONBLOCK +was deemed unneccesary. So, O_NONBLOCK may not be available on files +and/or disks. +.SH "SEE ALSO" +.BR close (2), +.BR fcntl (2), +.BR ioctl (2), +.BR lseek (2), +.BR readdir (2), +.BR readlink (2), +.BR select (2), +.BR write (2), +.BR fread (3), +.BR readv (3) diff --git a/man2/readahead.2 b/man2/readahead.2 new file mode 100644 index 000000000..fc659bb39 --- /dev/null +++ b/man2/readahead.2 @@ -0,0 +1,92 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 2004, Michael Kerrisk +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" 2004-05-40 Created by Michael Kerrisk +.\" 2004-10-05 aeb, minor correction +.\" +.TH READAHEAD 2 2004-10-05 "Linux 2.6.5" "Linux Programmer's Manual" +.SH NAME +readahead \- perform file readahead into page cache +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "ssize_t readahead(int " fd ", off64_t *" offset ", size_t " count ); +.fi +.SH DESCRIPTION +.B readahead() +populates the page cache with data from a file so that subsequent +reads from that file will not block on disk I/O. +The +.I fd +argument is a file descriptor identifying the file which is +to be read. +The +.I offset +argument specifies the starting point from which data is to be read +and +.I count +specifies the number of bytes to be read. +I/O is performed in whole pages, so that +.I offset +is effectively rounded down to a page boundary +and bytes are read up to the next page boundary greater than or +equal to +.IR "(offset+count)" . +.B readahead() +does not read beyond the end of the file. +.B readahead() +blocks until the specified data has been read. +The current file offset of the open file referred to by +.I fd +is left unchanged. +.SH "RETURN VALUE" +On success, +.B readahead() +returns 0; on failure, \-1 is returned, with +.I errno +set to indicate the cause of the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor or is not open for reading. +.TP +.B EINVAL +.I fd +does not refer to a file type to which +.B readahead +can be applied. +.SH "CONFORMING TO" +The +.B readahead() +system call is Linux specific, and its use should be avoided +in portable applications. +.SH NOTES +The +.B readahead() +system call appeared in Linux 2.4.13. +.SH "SEE ALSO" +.BR fadvise (2), +.BR lseek (2), +.BR madvise (2), +.BR mmap (2), +.BR read (2) diff --git a/man2/readdir.2 b/man2/readdir.2 new file mode 100644 index 000000000..1a9b2b6c9 --- /dev/null +++ b/man2/readdir.2 @@ -0,0 +1,115 @@ +.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Written 11 June 1995 by Andries Brouwer +.\" Modified 22 July 1995 by Michael Chastain : +.\" In 1.3.X, returns only one entry each time; return value is different. +.TH READDIR 2 1995-07-22 "Linux 1.3.6" "Linux Programmer's Manual" +.SH NAME +readdir \- read directory entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.sp +.B _syscall3(int, readdir, uint, fd, struct dirent *, dirp, uint, count); +.sp +.BI "int readdir(unsigned int " fd ", struct dirent *" dirp ", unsigned int " count ); +.fi +.SH DESCRIPTION +This is not the function you are interested in. +Look at +.BR readdir (3) +for the POSIX conforming C library interface. +This page documents the bare kernel system call interface, +which can change, and which is superseded by +.BR getdents (2). +.PP +.B readdir +reads one +.I dirent +structure from the directory +pointed at by +.I fd +into the memory area pointed to by +.IR dirp . +The parameter +.I count +is ignored; at most one dirent structure is read. +.PP +The +.I dirent +structure is declared as follows: +.PP +.RS +.nf +struct dirent +{ + long d_ino; /* inode number */ + off_t d_off; /* offset to this \fIdirent\fP */ + unsigned short d_reclen; /* length of this \fId_name\fP */ + char d_name [NAME_MAX+1]; /* file name (null-terminated) */ +} +.fi +.RE +.PP +.I d_ino +is an inode number. +.I d_off +is the distance from the start of the directory to this +.IR dirent . +.I d_reclen +is the size of +.IR d_name, +not counting the null terminator. +.I d_name +is a null-terminated file name. +.PP +.SH "RETURN VALUE" +On success, 1 is returned. +On end of directory, 0 is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +Invalid file descriptor +.IR fd . +.TP +.B EFAULT +Argument points outside the calling process's address space. +.TP +.B EINVAL +Result buffer is too small. +.TP +.B ENOENT +No such directory. +.TP +.B ENOTDIR +File descriptor does not refer to a directory. +.SH "CONFORMING TO" +This system call is Linux specific. +.SH "SEE ALSO" +.BR getdents (2), +.BR readdir (3) diff --git a/man2/readlink.2 b/man2/readlink.2 new file mode 100644 index 000000000..6f16f4744 --- /dev/null +++ b/man2/readlink.2 @@ -0,0 +1,109 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)readlink.2 6.8 (Berkeley) 3/10/91 +.\" +.\" Modified Sat Jul 24 00:10:21 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Tue Jul 9 23:55:17 1996 by aeb +.\" Modified Fri Jan 24 00:26:00 1997 by aeb +.\" +.TH READLINK 2 1997-08-21 "Linux 2.0.30" "Linux Programmer's Manual" +.SH NAME +readlink \- read value of a symbolic link +.SH SYNOPSIS +.B #include +.sp +.BI "int readlink(const char *" path ", char *" buf ", size_t " bufsiz ); +.SH DESCRIPTION +.B readlink +places the contents of the symbolic link +.I path +in the buffer +.IR buf , +which has size +.IR bufsiz . +.B readlink +does not append a +.B NUL +character to +.IR buf . +It will truncate the contents (to a length of +.I bufsiz +characters), in case the buffer is too small to hold all of the contents. +.SH "RETURN VALUE" +The call returns the count of characters placed in the buffer +if it succeeds, or a \-1 if an error occurs, placing the error +code in +.IR errno . +.SH ERRORS +.TP +.B EACCES +Search permission is denied for a component of the path prefix. +(See also +.BR path_resolution (2).) +.TP +.B EFAULT +.I buf +extends outside the process's allocated address space. +.TP +.B EINVAL +.I bufsiz +is not positive. +.TP +.B EINVAL +The named file is not a symbolic link. +.TP +.B EIO +An I/O error occurred while reading from the file system. +.TP +.B ELOOP +Too many symbolic links were encountered in translating the pathname. +.TP +.B ENAMETOOLONG +A pathname, or a component of a pathname, was too long. +.TP +.B ENOENT +The named file does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.SH "CONFORMING TO" +X/OPEN, 4.4BSD (the +.B readlink +function call appeared in 4.2BSD). +.SH "SEE ALSO" +.BR lstat (2), +.BR path_resolution (2), +.BR stat (2), +.BR symlink (2) diff --git a/man2/readv.2 b/man2/readv.2 new file mode 100644 index 000000000..4436cd250 --- /dev/null +++ b/man2/readv.2 @@ -0,0 +1,129 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 18:34:44 1993 by Rik Faith (faith@cs.unc.edu) +.\" Merged readv.[23], 2002-10-17, aeb +.\" +.TH READV 2 2002-10-17 "" "Linux Programmer's Manual" +.SH NAME +readv, writev \- read or write data into multiple buffers +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "ssize_t readv(int " fd ", const struct iovec *" vector ", int " count ); +.sp +.BI "ssize_t writev(int " fd ", const struct iovec *" vector ", int " count ); +.fi +.SH DESCRIPTION +The +.B readv() +function reads +.I count +blocks from the file associated with the file descriptor +.I fd +into the multiple buffers described by +.IR vector . +.PP +The +.B writev() +function writes at most +.I count +blocks described by +.I vector +to the file associated with the file descriptor +.IR fd . +.PP +The pointer +.I vector +points to a +.B struct iovec +defined in +.B +as +.PP +.br +.nf +.in 10 +struct iovec { +.in 14 +void *iov_base; /* Starting address */ +size_t iov_len; /* Number of bytes */ +.in 10 +}; +.fi +.PP +Buffers are processed in the order specified. +.PP +The +.B readv() +function works just like +.BR read (2) +except that multiple buffers are filled. +.PP +The +.B writev() +function works just like +.BR write (2) +except that multiple buffers are written out. +.PP +.SH "RETURN VALUE" +On success, the +.B readv() +function returns the number of bytes read; the +.B writev() +function returns the number of bytes written. +On error, \-1 is returned, and \fIerrno\fP is set appropriately. +.SH ERRORS +The errors are as given for +.BR read (2) +and +.BR write (2). +Additionally the following error is defined. +.TP +.B EINVAL +The sum of the +.I iov_len +values overflows an +.B ssize_t +value. Or, +the vector count \fIcount\fR is zero or greater than \fBMAX_IOVEC\fR. +.SH "CONFORMING TO" +4.4BSD (the +.B readv +and +.B writev +functions first appeared in BSD 4.2), Unix98, POSIX 1003.1-2001. +Linux libc5 used \fBsize_t\fR as the type of the \fIcount\fR parameter, +and \fBint\fP as return type for these functions. +.\" The readv/writev system calls were buggy before Linux 1.3.40. +.\" (Says release.libc.) +.SH BUGS +It is not advisable to mix calls to functions like +.B readv() +or +.BR writev() , +which operate on file descriptors, with the functions from the stdio +library; the results will be undefined and probably not what you want. +.SH "SEE ALSO" +.BR read (2), +.BR write (2) diff --git a/man2/reboot.2 b/man2/reboot.2 new file mode 100644 index 000000000..0dba410a6 --- /dev/null +++ b/man2/reboot.2 @@ -0,0 +1,152 @@ +.\" Copyright (c) 1998 Andries Brouwer (aeb@cwi.nl), 24 September 1998 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH REBOOT 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +reboot \- reboot or enable/disable Ctrl-Alt-Del +.SH SYNOPSIS +For libc4 and libc5 the library call and the system call are identical, +and since kernel version 2.1.30 there are symbolic names +LINUX_REBOOT_* for the constants and a fourth argument to the call: +.sp +.B #include +.br +.B #include +.sp +.BI "int reboot(int " magic ", int " magic2 ", int " flag ", void *" arg ); +.sp +Under glibc some of the constants involved have gotten symbolic names RB_*, +and the library call is a 1-argument wrapper around the 3-argument +system call: +.sp +.B #include +.br +.B #include +.sp +.BI "int reboot(int " flag ); +.SH DESCRIPTION +The +.B reboot +call reboots the system, or enables/disables the reboot keystroke +(abbreviated CAD, since the default is Ctrl-Alt-Delete; +it can be changed using +.BR loadkeys (1)). +.PP +This system call will fail (with EINVAL) unless +.I magic +equals LINUX_REBOOT_MAGIC1 (that is, 0xfee1dead) and +.I magic2 +equals LINUX_REBOOT_MAGIC2 (that is, 672274793). +However, since 2.1.17 also LINUX_REBOOT_MAGIC2A (that is, 85072278) +and since 2.1.97 also LINUX_REBOOT_MAGIC2B (that is, 369367448) +and since 2.5.71 also LINUX_REBOOT_MAGIC2C (that is, 537993216) +are permitted as value for +.IR magic2 . +(The hexadecimal values of these constants are meaningful.) +The +.I flag +argument can have the following values: +.TP +.B LINUX_REBOOT_CMD_RESTART +(RB_AUTOBOOT, 0x1234567). +The message `Restarting system.' is printed, and a default +restart is performed immediately. +If not preceded by a +.BR sync (2), +data will be lost. +.TP +.B LINUX_REBOOT_CMD_HALT +(RB_HALT_SYSTEM, 0xcdef0123; since 1.1.76). +The message `System halted.' is printed, and the system is halted. +Control is given to the ROM monitor, if there is one. +If not preceded by a +.BR sync (2), +data will be lost. +.TP +.B LINUX_REBOOT_CMD_POWER_OFF +(0x4321fedc; since 2.1.30). +The message `Power down.' is printed, the system is stopped, +and all power is removed from the system, if possible. +If not preceded by a +.BR sync (2), +data will be lost. +.TP +.B LINUX_REBOOT_CMD_RESTART2 +(0xa1b2c3d4; since 2.1.30). +The message `Restarting system with command '%s'' is printed, +and a restart (using the command string given in +.IR arg ) +is performed immediately. +If not preceded by a +.BR sync (2), +data will be lost. +.TP +.B LINUX_REBOOT_CMD_CAD_ON +(RB_ENABLE_CAD, 0x89abcdef). +CAD is enabled. +This means that the CAD keystroke will immediately cause +the action associated to LINUX_REBOOT_CMD_RESTART. +.TP +.B LINUX_REBOOT_CMD_CAD_OFF +(RB_DISABLE_CAD, 0). +CAD is disabled. +This means that the CAD keystroke will cause a SIGINT signal to be +sent to init (process 1), whereupon this process may decide upon a +proper action (maybe: kill all processes, sync, reboot). +.LP +Only the super-user may use this function. +.LP +The precise effect of the above actions depends on the architecture. +For the i386 architecture, the additional argument does not do +anything at present (2.1.122), but the type of reboot can be +determined by kernel command line arguments (`reboot=...') to be +either warm or cold, and either hard or through the BIOS. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +Problem with getting userspace data under LINUX_REBOOT_CMD_RESTART2. +.TP +.B EINVAL +Bad magic numbers or \fIflag\fP. +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR reboot ; +the +.B CAP_SYS_BOOT +capability is required. +.SH "CONFORMING TO" +.B reboot +is Linux specific, and should not be used in programs intended to be portable. +.SH "SEE ALSO" +.BR sync (2), +.BR bootparam (7), +.BR capabilities (7), +.BR ctrlaltdel (8), +.BR halt (8), +.BR reboot (8) diff --git a/man2/recv.2 b/man2/recv.2 new file mode 100644 index 000000000..a3feed2ed --- /dev/null +++ b/man2/recv.2 @@ -0,0 +1,424 @@ +.\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Id: recv.2,v 1.3 1999/05/13 11:33:38 freitag Exp $ +.\" +.\" Modified Sat Jul 24 00:22:20 1993 by Rik Faith +.\" Modified Tue Oct 22 17:45:19 1996 by Eric S. Raymond +.\" Modified 1998,1999 by Andi Kleen +.\" 2001-06-19 corrected SO_EE_OFFENDER, bug report by James Hawtin +.\" +.TH RECV 2 2002-12-31 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +recv, recvfrom, recvmsg \- receive a message from a socket +.SH SYNOPSIS +.\" .B #include +.\" .br +.B #include +.br +.B #include +.sp +.BI "ssize_t recv(int " s ", void *" buf ", size_t " len ", int " flags ); +.sp +.BI "ssize_t recvfrom(int " s ", void *" buf ", size_t " len , +.BI "int " flags ", struct sockaddr *" from ", socklen_t *" fromlen ); +.sp +.BI "ssize_t recvmsg(int " s ", struct msghdr *" msg ", int " flags ); +.SH DESCRIPTION +The +.B recvfrom +and +.B recvmsg +calls are used to receive messages from a socket, and may be used +to receive data on a socket whether or not it is connection-oriented. +.PP +If +.I from +is not NULL, and the underlying protocol provides the source address, +this source address is filled in. +.\" (Note: for datagram sockets in both the Unix and Internet domains, +.\" .I from +.\" is filled in. +.\" .I from +.\" is also filled in for stream sockets in the Unix domain, but is not +.\" filled in for stream sockets in the Internet domain.) +.\" [The above notes on AF_UNIX and AF_INET sockets apply as at +.\" Kernel 2.4.18. (MTK, 22 Jul 02)] +The argument +.I fromlen +is a value-result parameter, initialized to the size of the buffer +associated with +.IR from , +and modified on return to indicate the actual size of the address stored +there. +.PP +The +.B recv +call is normally used only on a +.I connected +socket (see +.BR connect (2)) +and is identical to +.B recvfrom +with a NULL +.I from +parameter. +.PP +All three routines return the length of the message on successful +completion. If a message is too long to fit in the supplied buffer, excess +bytes may be discarded depending on the type of socket the message is +received from (see +.BR socket (2)). +.PP +If no messages are available at the socket, the receive calls wait for a +message to arrive, unless the socket is nonblocking (see +.BR fcntl (2)) +in which case the value \-1 is returned and the external variable +.I errno +set to +.BR EAGAIN . +The receive calls normally return any data available, up to the requested +amount, rather than waiting for receipt of the full amount requested. +.PP +The +.BR select (2) +or +.BR poll (2) +call may be used to determine when more data arrives. +.PP +The +.I flags +argument to a recv call is formed by +.IR OR 'ing +one or more of the following values: +.TP +.B MSG_OOB +This flag requests receipt of out-of-band data that would not be received +in the normal data stream. Some protocols place expedited data +at the head of the normal data queue, and thus this flag cannot +be used with such protocols. +.TP +.B MSG_PEEK +This flag causes the receive operation to return data from the beginning of the +receive queue without removing that data from the queue. Thus, a +subsequent receive call will return the same data. +.TP +.B MSG_WAITALL +This flag requests that the operation block until the full request is +satisfied. However, the call may still return less data than requested if +a signal is caught, an error or disconnect occurs, or the next data to be +received is of a different type than that returned. +.TP +.B MSG_TRUNC +Return the real length of the packet, even when it was longer than +the passed buffer. Only valid for packet sockets. +.TP +.B MSG_ERRQUEUE +This flag +specifies that queued errors should be received from the socket error queue. +The error is passed in +an ancillary message with a type dependent on the protocol (for IPv4 +.BR IP_RECVERR ). +The user should supply a buffer of sufficient size. See +.BR cmsg (3) +and +.BR ip (7) +for more information. +The payload of the original packet that caused the error +is passed as normal data via +.BR msg_iovec . +The original destination address of the datagram that caused the error +is supplied via +.BR msg_name . +.IP +For local errors, no address is passed (this can be checked with the +.I cmsg_len +member of the +.BR cmsghdr ). +For error receives, the +.B MSG_ERRQUEUE +is set in the +.BR msghdr . +After an error has been passed, the pending socket error +is regenerated based on the next queued error and will be passed +on the next socket operation. + +The error is supplied in a +.B sock_extended_err +structure: +.IP +.RS +.ne 18 +.nf +.ta 4n 20n 32n +#define SO_EE_ORIGIN_NONE 0 +#define SO_EE_ORIGIN_LOCAL 1 +#define SO_EE_ORIGIN_ICMP 2 +#define SO_EE_ORIGIN_ICMP6 3 + +struct sock_extended_err +{ + u_int32_t ee_errno; /* error number */ + u_int8_t ee_origin; /* where the error originated */ + u_int8_t ee_type; /* type */ + u_int8_t ee_code; /* code */ + u_int8_t ee_pad; + u_int32_t ee_info; /* additional information */ + u_int32_t ee_data; /* other data */ + /* More data may follow */ +}; + +struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *); +.ta +.fi +.RE +.IP +.B ee_errno +contains the errno number of the queued error. +.B ee_origin +is the origin code of where the error originated. +The other fields are protocol specific. The macro +.B SOCK_EE_OFFENDER +returns a pointer to the address of the network object +where the error originated from given a pointer to the ancillary message. +If this address is not known, the +.I sa_family +member of the +.B sockaddr +contains +.B AF_UNSPEC +and the other fields of the +.B sockaddr +are undefined. The payload of the packet +that caused the error is passed as normal data. +.IP +For local errors, no address is passed (this +can be checked with the +.I cmsg_len +member of the +.BR cmsghdr ). +For error receives, +the +.B MSG_ERRQUEUE +is set in the +.BR msghdr . +After an error has been passed, the pending socket error +is regenerated based on the next queued error and will be passed +on the next socket operation. +.PP +The +.B recvmsg +call uses a +.I msghdr +structure to minimize the number of directly supplied parameters. This +structure has the following form, as defined in +.IR : +.IP +.RS +.nf +.ta 4n 17n 33n +struct msghdr { + void * msg_name; /* optional address */ + socklen_t msg_namelen; /* size of address */ + struct iovec * msg_iov; /* scatter/gather array */ + size_t msg_iovlen; /* # elements in msg_iov */ + void * msg_control; /* ancillary data, see below */ + socklen_t msg_controllen; /* ancillary data buffer len */ + int msg_flags; /* flags on received message */ +}; +.ta +.fi +.RE +.PP +Here +.I msg_name +and +.I msg_namelen +specify the source address if the socket is unconnected; +.I msg_name +may be given as a null pointer if no names are desired or required. +The fields +.I msg_iov +and +.I msg_iovlen +describe scatter-gather locations, as discussed in +.BR readv (2). +The field +.IR msg_control , +which has length +.IR msg_controllen , +points to a buffer for other protocol control related messages or +miscellaneous ancillary data. When +.B recvmsg +is called, +.I msg_controllen +should contain the length of the available buffer in +.IR msg_control ; +upon return from a successful call it will contain the length +of the control message sequence. +.PP +The messages are of the form: +.PP +.RS +.nf +.ta 4n 16n 28n +struct cmsghdr { + socklen_t cmsg_len; /* data byte count, including hdr */ + int cmsg_level; /* originating protocol */ + int cmsg_type; /* protocol-specific type */ +/* followed by + u_char cmsg_data[]; */ +}; +.ta +.fi +.RE +.PP +Ancillary data should only be accessed by the macros defined in +.BR cmsg (3). +.PP +As an example, Linux uses this auxiliary data mechanism to pass extended +errors, IP options or file descriptors over Unix sockets. +.PP +The +.I msg_flags +field in the msghdr is set on return of +.BR recvmsg (). +It can contain several flags: +.TP +.B MSG_EOR +indicates end-of-record; the data returned completed a record (generally +used with sockets of type +.BR SOCK_SEQPACKET ). +.TP +.B MSG_TRUNC +indicates that the trailing portion of a datagram was discarded because the +datagram was larger than the buffer supplied. +.TP +.B MSG_CTRUNC +indicates that some control data were discarded due to lack of space in the +buffer for ancillary data. +.TP +.B MSG_OOB +is returned to indicate that expedited or out-of-band data were received. +.TP +.B MSG_ERRQUEUE +indicates that no data was received but an extended error from the socket +error queue. +.TP +.B MSG_DONTWAIT +Enables non-blocking operation; if the operation would block, +.B EAGAIN +is returned (this can also be enabled using the +.B O_NONBLOCK +with the +.B F_SETFL +.BR fcntl (2)). +.SH "RETURN VALUE" +These calls return the number of bytes received, or \-1 +if an error occurred. The return value will be 0 when the +peer has performed an orderly shutdown. +.SH ERRORS +These are some standard errors generated by the socket layer. Additional errors +may be generated and returned from the underlying protocol modules; see their +manual pages. +.TP +.B EAGAIN +The socket is marked non-blocking and the receive operation +would block, or a receive timeout had been set and the timeout expired +before data was received. +.TP +.B EBADF +The argument +.I s +is an invalid descriptor. +.TP +.B ECONNREFUSED +A remote host refused to allow the network connection (typically +because it is not running the requested service). +.TP +.B EFAULT +The receive buffer pointer(s) point outside the process's +address space. +.TP +.B EINTR +The receive was interrupted by delivery of a signal before +any data were available. +.TP +.B EINVAL +Invalid argument passed. +.TP +.B ENOMEM +Could not allocate memory for recvmsg. +.TP +.B ENOTCONN +The socket is associated with a connection-oriented protocol +and has not been connected (see +.BR connect (2) +and +.BR accept (2)). +.TP +.B ENOTSOCK +The argument +.I s +does not refer to a socket. +.SH "CONFORMING TO" +4.4BSD (these function calls first appeared in 4.2BSD), +POSIX 1003.1-2001. +.LP +POSIX only describes the +.BR MSG_OOB , +.BR MSG_PEEK , +and +.B MSG_WAITALL +flags. +.SH NOTE +The prototypes given above follow glibc2. +The Single Unix Specification agrees, except that it has return values +of type `ssize_t' (while BSD 4.* and libc4 and libc5 all have `int'). +The +.I flags +argument is `int' in BSD 4.*, but `unsigned int' in libc4 and libc5. +The +.I len +argument is `int' in BSD 4.*, but `size_t' in libc4 and libc5. +The +.I fromlen +argument is `int *' in BSD 4.*, libc4 and libc5. +The present `socklen_t *' was invented by POSIX. +See also +.BR accept (2). +.SH "SEE ALSO" +.BR fcntl (2), +.BR getsockopt (2), +.BR read (2), +.BR select (2), +.BR socket (2), +.BR cmsg (3) diff --git a/man2/recvfrom.2 b/man2/recvfrom.2 new file mode 100644 index 000000000..13228c391 --- /dev/null +++ b/man2/recvfrom.2 @@ -0,0 +1 @@ +.so man2/recv.2 diff --git a/man2/recvmsg.2 b/man2/recvmsg.2 new file mode 100644 index 000000000..13228c391 --- /dev/null +++ b/man2/recvmsg.2 @@ -0,0 +1 @@ +.so man2/recv.2 diff --git a/man2/remap_file_pages.2 b/man2/remap_file_pages.2 new file mode 100644 index 000000000..8299be4b0 --- /dev/null +++ b/man2/remap_file_pages.2 @@ -0,0 +1,138 @@ +.\" From michael.kerrisk@gmx.net Wed Dec 10 17:40:03 2003 +.\" +.\" Copyright (C) 2003, Michael Kerrisk (mtk16@ext.canterbury.ac.nz) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" 2003-12-10 Initial creation, Michael Kerrisk +.\" 2004-10-28 aeb, corrected prototype, prot must be 0 +.\" +.TH REMAP_FILE_PAGES 2 2004-10-28 "Linux 2.6" "Linux Programmer's Manual" +.SH NAME +remap_file_pages \- create a non-linear file mapping +.SH SYNOPSIS +.B #include +.sp +.BI "int remap_file_pages(void *" start ", " +.BI "size_t " size ", int " prot ", " +.BI "ssize_t " pgoff ", int " flags ); +.SH DESCRIPTION +The +.B remap_file_pages() +system call is used to create a non-linear mapping, that is, a mapping +in which the pages of the file are mapped into a non-sequential order +in memory. +The advantage of using +.B remap_file_pages() +over using repeated calls to +.BR mmap (2) +is that the former approach does not require the kernel to create +additional VMA (Virtual Memory Area) data structures. + +To create a non-linear mapping we perform the following steps: +.TP +\fB1.\fp +Use +.B mmap() +to create a mapping (which is initially linear). +This mapping must be created with the +MAP_SHARED flag. +.TP +\fB2.\fp +Use one or more calls to +.B remap_file_pages() +to rearrange the correspondence between the pages of the mapping +and the pages of the file. +It is possible to map the same page of a file +into multiple locations within the mapped region. +.LP +The +.I pgoff +and +.I size +arguments specify the region of the file that is to be relocated +within the mapping: +.I pgoff +is a file offset in units of the system page size; +.I size +is the length of the region in bytes. + +The +.I start +argument serves two purposes. +First, it identifies the mapping whose pages we want to rearrange. +Thus, +.I start +must be an address that falls within +a region previously mapped by a call to +.BR mmap() . +Second, +.I start +specifies the address at which the file pages +identified by +.I pgoff +and +.I size +will be placed. + +The +.I prot +argument must be specified as 0. + +The +.I flags +argument has the same meaning as for +.BR mmap() , +but all flags other than MAP_NONBLOCK are ignored. +.SH "RETURN VALUE" +On success, +.B remap_file_pages() +returns 0. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH NOTES +The +.B remap_file_pages() +system call appeared in Linux 2.5.46. +.SH ERRORS +.TP +.B EINVAL +.I start +does not refer to a valid mapping +created with the MAP_SHARED flag. +.TP +.B EINVAL +.IR start , +.IR size , +.IR prot , +or +.I pgoff +is invalid. +.\" And possibly others from vma->vm_ops->populate() +.SH "CONFORMING TO" +The +.B remap_file_pages() +system call is Linux specific. +.SH "SEE ALSO" +.BR getpagesize (2), +.BR mmap (2), +.BR mmap2 (2), +.BR mprotect (2), +.BR mremap (2), +.BR msync (2) diff --git a/man2/removexattr.2 b/man2/removexattr.2 new file mode 100644 index 000000000..ce152f919 --- /dev/null +++ b/man2/removexattr.2 @@ -0,0 +1,111 @@ +.\" +.\" Extended attributes system calls manual pages +.\" +.\" (C) Andreas Gruenbacher, February 2001 +.\" (C) Silicon Graphics Inc, September 2001 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH REMOVEXATTR 2 "Extended Attributes" "Dec 2001" "Linux Programmer's Manual" +.SH NAME +removexattr, lremovexattr, fremovexattr \- remove an extended attribute +.SH SYNOPSIS +.fam C +.nf +.B #include +.B #include +.sp +.BI "int removexattr (const char\ *" path ", const char\ *" name ); +.BI "int lremovexattr (const char\ *" path ", const char\ *" name ); +.BI "int fremovexattr (int " filedes ", const char\ *" name ); +.fi +.fam T +.SH DESCRIPTION +Extended attributes are +.IR name :\c +value pairs associated with inodes (files, directories, symlinks, etc). +They are extensions to the normal attributes which are associated +with all inodes in the system (i.e. the +.BR stat (2) +data). +A complete overview of extended attributes concepts can be found in +.BR attr (5). +.PP +.B removexattr +removes the extended attribute identified by +.I name +and associated with the given +.I path +in the filesystem. +.PP +.B lremovexattr +is identical to +.BR removexattr , +except in the case of a symbolic link, where the extended attribute is +removed from the link itself, not the file that it refers to. +.PP +.B fremovexattr +is identical to +.BR removexattr , +only the extended attribute is removed from the open file pointed to by +.I filedes +(as returned by +.BR open (2)) +in place of +.IR path . +.PP +An extended attribute name is a simple NULL-terminated string. +The +.I name +includes a namespace prefix \- there may be several, disjoint +namespaces associated with an individual inode. +.SH RETURN VALUE +On success, zero is returned. +On failure, \-1 is returned and +.I errno +is set appropriately. +.PP +If the named attribute does not exist, +.I errno +is set to ENOATTR. +.PP +If extended attributes are not supported by the filesystem, or are disabled, +.I errno +is set to ENOTSUP. +.PP +The errors documented for the +.BR stat (2) +system call are also applicable here. +.SH AUTHORS +Andreas Gruenbacher, +.RI < a.gruenbacher@computer.org > +and the SGI XFS development team, +.RI < linux-xfs@oss.sgi.com >. +Please send any bug reports or comments to these addresses. +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR getxattr (2), +.BR listxattr (2), +.BR open (2), +.BR setxattr (2), +.BR stat (2), +.BR attr (5) diff --git a/man2/rename.2 b/man2/rename.2 new file mode 100644 index 000000000..00022a904 --- /dev/null +++ b/man2/rename.2 @@ -0,0 +1,210 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt; +.\" 1993,1995 Ian Jackson. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Sat Jul 24 00:35:52 1993 by Rik Faith +.\" Modified Thu Jun 4 12:21:13 1998 by Andries Brouwer +.\" +.TH RENAME 2 1998-06-04 "Linux 2.0" "Linux Programmer's Manual" +.SH NAME +rename \- change the name or location of a file +.SH SYNOPSIS +.B #include +.sp +.BI "int rename(const char *" oldpath ", const char *" newpath ); +.SH DESCRIPTION +.B rename +renames a file, moving it between directories if required. + +Any other hard links to the file (as created using +.BR link (2)) +are unaffected. + +If +.I newpath +already exists it will be atomically replaced (subject to +a few conditions - see ERRORS below), so that there is +no point at which another process attempting to access +.I newpath +will find it missing. + +If +.I newpath +exists but the operation fails for some reason +.B rename +guarantees to leave an instance of +.I newpath +in place. + +However, when overwriting there will probably be a window in which +both +.I oldpath +and +.I newpath +refer to the file being renamed. + +If +.I oldpath +refers to a symbolic link the link is renamed; if +.I newpath +refers to a symbolic link the link will be overwritten. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Write permission is denied for the directory containing +.I oldpath +or +.IR newpath , +or, search permission is denied for one of the directories +in the path prefix of +.I oldpath +or +.IR newpath , +or +.I oldpath +is a directory and does not allow write permission (needed to update +the +.B .. +entry). +(See also +.BR path_resolution (2).) +.TP +.B EBUSY +The rename fails because +.IR oldpath " or " newpath +is a directory that is in use by some process (perhaps as +current working directory, or as root directory, or because +it was open for reading) or is in use by the system +(for example as mount point), while the system considers +this an error. +(Note that there is no requirement to return EBUSY in such +cases - there is nothing wrong with doing the rename anyway - +but it is allowed to return EBUSY if the system cannot otherwise +handle such situations.) +.TP +.B EFAULT +.IR oldpath " or " newpath " points outside your accessible address space." +.TP +.B EINVAL +The new pathname contained a path prefix of the old, or, more generally, +an attempt was made to make a directory a subdirectory of itself. +.TP +.B EISDIR +.I newpath +is an existing directory, but +.I oldpath +is not a directory. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR oldpath " or " newpath . +.TP +.B EMLINK +.I oldpath +already has the maximum number of links to it, or +it was a directory and the directory containing +.I newpath +has the maximum number of links. +.TP +.B ENAMETOOLONG +.IR oldpath " or " newpath " was too long." +.TP +.B ENOENT +A directory component in +.I oldpath " or " newpath +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The device containing the file has no room for the new directory +entry. +.TP +.B ENOTDIR +A component used as a directory in +.IR oldpath " or " newpath +is not, in fact, a directory. +Or, +.I oldpath +is a directory, and +.I newpath +exists but is not a directory. +.TP +.BR ENOTEMPTY " or " EEXIST +.IR newpath +is a non-empty directory, i.e., contains entries other than "." and "..". +.TP +.BR EPERM " or " EACCES +The directory containing +.I oldpath +has the sticky bit +.RB ( S_ISVTX ) +set and the process's effective user ID is neither +the user ID of the file to be deleted nor that of the directory +containing it, and the process is not privileged +(Linux: does not have the +.B CAP_FOWNER +capability); +or +.I newpath +is an existing file and the directory containing it has the sticky bit set +and the process's effective user ID is neither the user ID of the file +to be replaced nor that of the directory containing it, +and the process is not privileged +(Linux: does not have the +.B CAP_FOWNER +capability); +or the filesystem containing +.IR pathname +does not support renaming of the type requested. +.TP +.B EROFS +The file is on a read-only filesystem. +.TP +.B EXDEV +.IR oldpath " and " newpath +are not on the same filesystem. +.SH "CONFORMING TO" +POSIX, 4.3BSD, ANSI C +.SH BUGS +On NFS filesystems, you can not assume that if the operation +failed the file was not renamed. If the server does the rename operation +and then crashes, the retransmitted RPC which will be processed when the +server is up again causes a failure. The application is expected to +deal with this. See +.BR link (2) +for a similar problem. +.SH "SEE ALSO" +.BR mv (1), +.BR chmod (2), +.BR link (2), +.BR path_resolution (2), +.BR symlink (2), +.BR unlink (2) diff --git a/man2/rmdir.2 b/man2/rmdir.2 new file mode 100644 index 000000000..74d59f089 --- /dev/null +++ b/man2/rmdir.2 @@ -0,0 +1,125 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt, Ian Jackson. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH RMDIR 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +rmdir \- delete a directory +.SH SYNOPSIS +.B #include +.sp +.BI "int rmdir(const char *" pathname ); +.SH DESCRIPTION +.B rmdir +deletes a directory, which must be empty. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Write access to the directory containing +.I pathname +was not allowed, or one of the directories in the path prefix of +.IR pathname +did not allow search permission. +(See also +.BR path_resolution (2). +.TP +.B EBUSY +.I pathname +is the current working directory or root directory of some process. +.TP +.B EFAULT +.IR pathname " points outside your accessible address space." +.TP +.B EINVAL +.I pathname +has +.B . +as last component. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.IR pathname " was too long." +.TP +.B ENOENT +A directory component in +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +.IR pathname , +or a component used as a directory in +.IR pathname , +is not, in fact, a directory. +.TP +.B ENOTEMPTY +.I pathname +contains entries other than +.BR . " and " .. " ." +.TP +.B EPERM +The directory containing +.I pathname +has the sticky bit +.RB ( S_ISVTX ) +set and the process's effective user ID is neither the user ID of the file to +be deleted nor that of the directory containing it, and the process is not +privileged (Linux: does not have the +.B CAP_FOWNER +capability). +.TP +.B EPERM +The filesystem containing +.IR pathname +does not support the removal of directories. +.TP +.B EROFS +.I pathname +refers to a file on a read-only filesystem. +.SH "CONFORMING TO" +SVr4, SVID, POSIX, BSD 4.3 +.SH BUGS +Infelicities in the protocol underlying NFS can cause the unexpected +disappearance of directories which are still being used. +.SH "SEE ALSO" +.BR rm (1), +.BR rmdir (1), +.BR chdir (2), +.BR chmod (2), +.BR mkdir (2), +.BR rename (2), +.BR unlink (2) diff --git a/man2/sbrk.2 b/man2/sbrk.2 new file mode 100644 index 000000000..a3711a537 --- /dev/null +++ b/man2/sbrk.2 @@ -0,0 +1 @@ +.so man2/brk.2 diff --git a/man2/sched_get_priority_max.2 b/man2/sched_get_priority_max.2 new file mode 100644 index 000000000..a962787da --- /dev/null +++ b/man2/sched_get_priority_max.2 @@ -0,0 +1,111 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) Tom Bjorkholm & Markus Kuhn, 1996 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 1996-04-01 Tom Bjorkholm +.\" First version written +.\" 1996-04-10 Markus Kuhn +.\" revision +.\" +.TH GET_PRIORITY_MAX 2 1996-04-10 "Linux 1.3.81" "Linux Programmer's Manual" +.SH NAME +sched_get_priority_max, sched_get_priority_min \- get static priority range +.SH SYNOPSIS +.B #include +.sp +\fBint sched_get_priority_max(int \fIpolicy\fB); +.sp +\fBint sched_get_priority_min(int \fIpolicy\fB); +.fi +.SH DESCRIPTION +.B sched_get_priority_max +returns the maximum priority value that can be used with the +scheduling algorithm identified by \fIpolicy\fR. +.B sched_get_priority_min +returns the minimum priority value that can be used with the +scheduling algorithm identified by \fIpolicy\fR. Supported \fIpolicy\fR +values are +.IR SCHED_FIFO , +.IR SCHED_RR , +and +.IR SCHED_OTHER . + +Processes with numerically higher priority values are scheduled before +processes with numerically lower priority values. Thus, the value +returned by \fBsched_get_priority_max\fR will be greater than the +value returned by \fBsched_get_priority_min\fR. + +Linux allows the static priority value range 1 to 99 for +\fISCHED_FIFO\fR and \fISCHED_RR\fR and the priority 0 for +\fISCHED_OTHER\fR. Scheduling priority ranges for the various policies +are not alterable. + +The range of scheduling priorities may vary on other POSIX systems, +thus it is a good idea for portable applications to use a virtual +priority range and map it to the interval given by +\fBsched_get_priority_max\fR and \fBsched_get_priority_min\fR. +POSIX.1b requires a spread of at least 32 between the maximum and the +minimum values for \fISCHED_FIFO\fR and \fISCHED_RR\fR. + +POSIX systems on which +.B sched_get_priority_max +and +.B sched_get_priority_min +are available define +.I _POSIX_PRIORITY_SCHEDULING +in . + +.SH "RETURN VALUE" +On success, +.B sched_get_priority_max +and +.B sched_get_priority_min +return the maximum/minimum priority value for the named scheduling +policy. +On error, \-1 is returned, +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +The parameter \fIpolicy\fR does not identify a defined scheduling policy. +.SH "CONFORMING TO" +POSIX.1b (formerly POSIX.4) +.SH "SEE ALSO" +.BR sched_getaffinity (2), +.BR sched_getparam (2), +.BR sched_getscheduler (2), +.BR sched_setaffinity (2), +.BR sched_setparam (2), +.BR sched_setscheduler (2) +.PP +.BR sched_setscheduler (2) +has a description of the Linux scheduling scheme. +.PP +.I Programming for the real world \- POSIX.4 +by Bill O. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0 +.br +.I IEEE Std 1003.1b-1993 +(POSIX.1b standard) +.br +.I ISO/IEC 9945-1:1996 diff --git a/man2/sched_get_priority_min.2 b/man2/sched_get_priority_min.2 new file mode 100644 index 000000000..17b99f0e3 --- /dev/null +++ b/man2/sched_get_priority_min.2 @@ -0,0 +1 @@ +.so man2/sched_get_priority_max.2 diff --git a/man2/sched_getaffinity.2 b/man2/sched_getaffinity.2 new file mode 100644 index 000000000..f376c11f4 --- /dev/null +++ b/man2/sched_getaffinity.2 @@ -0,0 +1 @@ +.so man2/sched_setaffinity.2 diff --git a/man2/sched_getparam.2 b/man2/sched_getparam.2 new file mode 100644 index 000000000..d39facd91 --- /dev/null +++ b/man2/sched_getparam.2 @@ -0,0 +1 @@ +.so man2/sched_setparam.2 diff --git a/man2/sched_getscheduler.2 b/man2/sched_getscheduler.2 new file mode 100644 index 000000000..13aa82793 --- /dev/null +++ b/man2/sched_getscheduler.2 @@ -0,0 +1 @@ +.so man2/sched_setscheduler.2 diff --git a/man2/sched_rr_get_interval.2 b/man2/sched_rr_get_interval.2 new file mode 100644 index 000000000..a2bce2877 --- /dev/null +++ b/man2/sched_rr_get_interval.2 @@ -0,0 +1,100 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) Tom Bjorkholm & Markus Kuhn, 1996 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 1996-04-01 Tom Bjorkholm +.\" First version written +.\" 1996-04-10 Markus Kuhn +.\" revision +.\" +.TH RR_GET_INTERVAL 2 1996-04-10 "Linux 1.3.81" "Linux Programmer's Manual" +.SH NAME +sched_rr_get_interval \- get the SCHED_RR interval for the named process +.SH SYNOPSIS +.B #include +.sp +\fBint sched_rr_get_interval(pid_t \fIpid\fB, struct timespec *\fItp\fB); +.sp +.nf +.ta 4n 12n 24n +\fBstruct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +}; +.ta +.fi +.SH DESCRIPTION +.B sched_rr_get_interval +writes into the \fItimespec\fR structure pointed to by \fItp\fR the +round robin time quantum for the process identified by \fIpid\fR. If +\fIpid\fR is zero, the time quantum for the calling process is written +into *\fItp\fR. The identified process should be running under the +.I SCHED_RR +scheduling policy. + +The round robin time quantum value is not alterable under Linux +1.3.81. + +POSIX systems on which +.B sched_rr_get_interval +is available define +.I _POSIX_PRIORITY_SCHEDULING +in . + +.SH "RETURN VALUE" +On success, +.B sched_rr_get_interval +returns 0. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +Problem with copying information to userspace. +.TP +.B EINVAL +Invalid pid. +.TP +.B ENOSYS +The system call is not yet implemented. +.TP +.B ESRCH +The process whose ID is \fIpid\fR could not be found. +.SH "CONFORMING TO" +POSIX.1b (formerly POSIX.4) +.SH BUGS +As of Linux 1.3.81 \fBsched_rr_get_interval\fR returns with error +ENOSYS, because SCHED_RR has not yet been fully implemented and tested +properly. +.SH "SEE ALSO" +.BR sched_setscheduler (2) +has a description of the Linux scheduling scheme. +.PP +.I Programming for the real world \- POSIX.4 +by Bill O. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0 +.br +.I IEEE Std 1003.1b-1993 +(POSIX.1b standard, formerly POSIX.4) +.br +.I ISO/IEC 9945-1:1996 diff --git a/man2/sched_setaffinity.2 b/man2/sched_setaffinity.2 new file mode 100644 index 000000000..cf0c700da --- /dev/null +++ b/man2/sched_setaffinity.2 @@ -0,0 +1,146 @@ +.\" man2/sched_setaffinity.2 - sched_setaffinity and sched_getaffinity man page +.\" +.\" Copyright (C) 2002 Robert Love +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 2002-11-19 Robert Love - initial version +.\" 2004-04-20 mtk - fixed description of return value +.\" 2004-04-22 aeb - added glibc prototype history +.\" +.TH SCHED_SETAFFINITY 2 2004-04-22 "Linux" "Linux Programmer's Manual" +.SH NAME +sched_setaffinity, sched_getaffinity \- set and get a process's CPU affinity +mask +.SH SYNOPSIS +.B #include +.sp +.BI "int sched_setaffinity(pid_t " pid ", unsigned int " len , +.BI "unsigned long *" mask ); +.sp +.BI "int sched_getaffinity(pid_t " pid ", unsigned int " len , +.BI "unsigned long *" mask ); +.SH DESCRIPTION +.B sched_setaffinity +sets the CPU affinity mask of the process denoted by +.IR pid . +If +.I pid +is zero, then the current process is used. +.sp +The affinity mask is represented by the bitmask stored in +.IR mask . +The least significant bit corresponds to the first logical processor number on +the system, while the most significant bit corresponds to the last logical +processor number on the system. A set bit corresponds to a legally schedulable +CPU while an unset bit corresponds to an illegally schedulable CPU. In other +words, a process is bound to and will only run on processors whose +corresponding bit is set. Usually, all bits in the mask are set. +.sp +The argument +.I len +is the length (in bytes) of the data pointed to by +.IR mask . +Normally this is the size of a word on the system. For compatibility with +future versions of the Linux kernel, since this size can change, the bitmask +supplied must be at least as large as the affinity mask stored in the kernel. +.sp +The function +.B sched_getaffinity +writes into the pointer supplied by +.I mask +that has size +.I len +the affinity mask of process +.IR pid . +If +.I pid +is zero, then the mask of the current process is returned. + +.SH "RETURN VALUE" +On success, +.B sched_setaffinity +returns 0. +On error, \-1 is returned, and +.I errno +is set appropriately. + +On success, +.B sched_getaffinity +always returns the size (in bytes) of the affinity mask used by the kernel. +On error, \-1 is returned, and +.I errno +is set appropriately. + +.SH ERRORS +.TP +.B EFAULT +A supplied memory address was invalid. +.TP +.B EINVAL +The affinity bitmask +.I mask +contains no processors that are physically on the system, or the length +.I len +is smaller than the size of the affinity mask used by the kernel. +.TP +.B EPERM +The calling process does not have appropriate privileges. +The process calling +.BR sched_setaffinity +needs an effective user ID equal to the user ID or effective user ID +of the process identified by +.IR pid , +or it must possess the +.IR CAP_SYS_NICE +capability. +.TP +.B ESRCH +The process whose ID is \fIpid\fR could not be found. +.SH "HISTORY" +The affinity syscalls were introduced in Linux kernel 2.5.8. +The library calls were introduced in glibc 2.3, and are still in +glibc 2.3.2. Later glibc 2.3.2 development versions changed this +interface to one without the +.I len +field, and still later versions reverted again. The glibc prototype is now +.sp +.nf +/* Set the CPU affinity for a task */ +extern int sched_setaffinity (pid_t pid, size_t cpusetsize, + const cpu_set_t *cpuset); +.sp +/* Get the CPU affinity for a task */ +extern int sched_getaffinity (pid_t pid, size_t cpusetsize, + cpu_set_t *cpuset); +.fi +.SH "SEE ALSO" +.BR getpriority (2), +.BR nice (2), +.BR sched_get_priority_max (2), +.BR sched_get_priority_min (2), +.BR sched_getscheduler (2), +.BR sched_setscheduler (2), +.BR setpriority (2), +.BR capabilities (7) +.PP +.BR sched_setscheduler (2) +has a description of the Linux scheduling scheme. diff --git a/man2/sched_setparam.2 b/man2/sched_setparam.2 new file mode 100644 index 000000000..2551707f5 --- /dev/null +++ b/man2/sched_setparam.2 @@ -0,0 +1,132 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) Tom Bjorkholm & Markus Kuhn, 1996 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 1996-04-01 Tom Bjorkholm +.\" First version written +.\" 1996-04-10 Markus Kuhn +.\" revision +.\" Modified 2004-05-27 by Michael Kerrisk +.\" +.TH SCHED_SETPARAM 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +sched_setparam, sched_getparam \- set and get scheduling parameters +.SH SYNOPSIS +.B #include +.sp +\fBint sched_setparam(pid_t \fIpid\fB, const struct sched_param *\fIp\fB); +.sp +\fBint sched_getparam(pid_t \fIpid\fB, struct sched_param *\fIp\fB); +.sp +.nf +.ta 4n +\fBstruct sched_param { + ... + int \fIsched_priority\fB; + ... +}; +.ta +.fi +.SH DESCRIPTION +.B sched_setparam +sets the scheduling parameters associated with the scheduling policy +for the process identified by \fIpid\fR. If \fIpid\fR is zero, then +the parameters of the current process are set. The interpretation of +the parameter \fIp\fR depends on the selected policy. Currently, the +following three scheduling policies are supported under Linux: +.IR SCHED_FIFO , +.IR SCHED_RR , +and +.IR SCHED_OTHER. + +.B sched_getparam +retrieves the scheduling parameters for the +process identified by \fIpid\fR. If \fIpid\fR is zero, then the parameters +of the current process are retrieved. + +.B sched_setparam +checks the validity of \fIp\fR for the scheduling policy of the +process. The parameter \fIp->sched_priority\fR must lie within the +range given by \fBsched_get_priority_min\fR and +\fBsched_get_priority_max\fR. + +POSIX systems on which +.B sched_setparam +and +.B sched_getparam +are available define +.I _POSIX_PRIORITY_SCHEDULING +in . + +.SH "RETURN VALUE" +On success, +.BR sched_setparam +and +.BR sched_getparam +return 0. +On error, \-1 is returned, +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +The parameter \fIp\fR does not make sense for the current +scheduling policy. +.TP +.B EPERM +The calling process does not have appropriate privileges. +A process calling +.BR sched_setparam +needs an effective user ID equal to the user ID or effective user ID +of the process identified by +.IR pid , +or (Linux) it must have the +CAP_SYS_NICE +capability. +.TP +.B ESRCH +The process whose ID is \fIpid\fR could not be found. +.SH "CONFORMING TO" +POSIX.1b (formerly POSIX.4) +.SH "SEE ALSO" +.BR getpriority (2), +.BR nice (2), +.BR sched_get_priority_max (2), +.BR sched_get_priority_min (2), +.BR sched_getaffinity (2), +.BR sched_getscheduler (2), +.BR sched_setaffinity (2), +.BR sched_setscheduler (2), +.BR setpriority (2), +.BR capabilities (7) +.PP +.BR sched_setscheduler (2) +has a description of the Linux scheduling scheme. +.PP +.I Programming for the real world \- POSIX.4 +by Bill O. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0 +.br +.I IEEE Std 1003.1b-1993 +(POSIX.1b standard) +.br +.I ISO/IEC 9945-1:1996 diff --git a/man2/sched_setscheduler.2 b/man2/sched_setscheduler.2 new file mode 100644 index 000000000..31f770f98 --- /dev/null +++ b/man2/sched_setscheduler.2 @@ -0,0 +1,289 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) Tom Bjorkholm, Markus Kuhn & David A. Wheeler 1996-1999 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 1996-04-01 Tom Bjorkholm +.\" First version written +.\" 1996-04-10 Markus Kuhn +.\" revision +.\" 1999-08-18 David A. Wheeler added Note. +.\" Modified, 25 Jun 2002, Michael Kerrisk +.\" Corrected description of queue placement by sched_setparam() and +.\" sched_setscheduler() +.\" A couple of grammar clean-ups +.\" Modified 2004-05-27 by Michael Kerrisk +.\" +.TH SETSCHEDULER 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +sched_setscheduler, sched_getscheduler \- +set and get scheduling algorithm/parameters +.SH SYNOPSIS +.B #include +.sp +.BI "int sched_setscheduler(pid_t " pid ", int " policy , +.BI "const struct sched_param *" p ); +.sp +.BI "int sched_getscheduler(pid_t " pid ); +.sp +.nf +.ta 4n +\fBstruct sched_param { + ... + int \fIsched_priority\fB; + ... +}; +.ta +.fi +.SH DESCRIPTION +.B sched_setscheduler +sets both the scheduling policy and the associated parameters for the +process identified by \fIpid\fP. If \fIpid\fP equals zero, the +scheduler of the calling process will be set. The interpretation of +the parameter \fIp\fP depends on the selected policy. Currently, the +following three scheduling policies are supported under Linux: +.IR SCHED_FIFO , +.IR SCHED_RR , +and +.IR SCHED_OTHER ; +their respective semantics are described below. + +.B sched_getscheduler +queries the scheduling policy currently applied to the process +identified by \fIpid\fP. If \fIpid\fP equals zero, the policy of the +calling process will be retrieved. + + +.SS Scheduling Policies +The scheduler is the kernel part that decides which runnable process +will be executed by the CPU next. The Linux scheduler offers three +different scheduling policies, one for normal processes and two for +real-time applications. A static priority value \fIsched_priority\fP +is assigned to each process and this value can be changed only via +system calls. Conceptually, the scheduler maintains a list of runnable +processes for each possible \fIsched_priority\fP value, and +\fIsched_priority\fP can have a value in the range 0 to 99. In order +to determine the process that runs next, the Linux scheduler looks for +the non-empty list with the highest static priority and takes the +process at the head of this list. The scheduling policy determines for +each process, where it will be inserted into the list of processes +with equal static priority and how it will move inside this list. + +\fISCHED_OTHER\fP is the default universal time-sharing scheduler +policy used by most processes, \fISCHED_FIFO\fP and \fISCHED_RR\fP are +intended for special time-critical applications that need precise +control over the way in which runnable processes are selected for +execution. Processes scheduled with \fISCHED_OTHER\fP must be assigned +the static priority 0, processes scheduled under \fISCHED_FIFO\fP or +\fISCHED_RR\fP can have a static priority in the range 1 to 99. Only +processes with superuser privileges can get a static priority higher +than 0 and can therefore be scheduled under \fISCHED_FIFO\fP or +\fISCHED_RR\fP. The system calls \fBsched_get_priority_min\fP and +\fBsched_get_priority_max\fP can be used to find out the valid +priority range for a scheduling policy in a portable way on all +POSIX.1b conforming systems. + +All scheduling is preemptive: If a process with a higher static +priority gets ready to run, the current process will be preempted and +returned into its wait list. The scheduling policy only determines the +ordering within the list of runnable processes with equal static +priority. + +.SS SCHED_FIFO: First In-First Out scheduling +\fISCHED_FIFO\fP can only be used with static priorities higher than +0, which means that when a \fISCHED_FIFO\fP processes becomes runnable, +it will always preempt immediately any currently running normal +\fISCHED_OTHER\fP process. \fISCHED_FIFO\fP is a simple scheduling +algorithm without time slicing. For processes scheduled under the +\fISCHED_FIFO\fP policy, the following rules are applied: A +\fISCHED_FIFO\fP process that has been preempted by another process of +higher priority will stay at the head of the list for its priority and +will resume execution as soon as all processes of higher priority are +blocked again. When a \fISCHED_FIFO\fP process becomes runnable, it +will be inserted at the end of the list for its priority. A call to +\fBsched_setscheduler\fP or \fBsched_setparam\fP will put the +\fISCHED_FIFO\fP (or \fISCHED_RR\fP) process identified by +\fIpid\fP at the start of the list if it was runnable. +As a consequence, it may preempt the currently running process if +it has the same priority. +(POSIX 1003.1 specifies that the process should go to the end +of the list.) +.\" In 2.2.x and 2.4.x, the process is placed at the front of the queue +.\" In 2.0.x, the Right Thing happened: the process went to the back -- MTK +A process calling \fBsched_yield\fP will be +put at the end of the list. No other events will move a process +scheduled under the \fISCHED_FIFO\fP policy in the wait list of +runnable processes with equal static priority. A \fISCHED_FIFO\fP +process runs until either it is blocked by an I/O request, it is +preempted by a higher priority process, or it calls \fBsched_yield\fP. + + +.SS SCHED_RR: Round Robin scheduling +\fISCHED_RR\fP is a simple enhancement of \fISCHED_FIFO\fP. Everything +described above for \fISCHED_FIFO\fP also applies to \fISCHED_RR\fP, +except that each process is only allowed to run for a maximum time +quantum. If a \fISCHED_RR\fP process has been running for a time +period equal to or longer than the time quantum, it will be put at the +end of the list for its priority. A \fISCHED_RR\fP process that has +been preempted by a higher priority process and subsequently resumes +execution as a running process will complete the unexpired portion of +its round robin time quantum. The length of the time quantum can be +retrieved by \fBsched_rr_get_interval\fP. +.\" On Linux 2.4, the length of the RR interval is influenced +.\" by the process nice value -- MTK + +.SS SCHED_OTHER: Default Linux time-sharing scheduling +\fISCHED_OTHER\fP can only be used at static priority 0. +\fISCHED_OTHER\fP is the standard Linux time-sharing scheduler that is +intended for all processes that do not require special static priority +real-time mechanisms. The process to run is chosen from the static +priority 0 list based on a dynamic priority that is determined only +inside this list. The dynamic priority is based on the nice level (set +by the \fBnice\fP or \fBsetpriority\fP system call) and increased for +each time quantum the process is ready to run, but denied to run by +the scheduler. This ensures fair progress among all \fISCHED_OTHER\fP +processes. + +.SS Response time +A blocked high priority process waiting for the I/O has a certain +response time before it is scheduled again. The device driver writer +can greatly reduce this response time by using a "slow interrupt" +interrupt handler. +.\" as described in +.\" .BR request_irq (9). + +.SS Miscellaneous +Child processes inherit the scheduling algorithm and parameters across a +.BR fork . + +Memory locking is usually needed for real-time processes to avoid +paging delays, this can be done with +.B mlock +or +.BR mlockall . + +As a non-blocking end-less loop in a process scheduled under +\fISCHED_FIFO\fP or \fISCHED_RR\fP will block all processes with lower +priority forever, a software developer should always keep available on +the console a shell scheduled under a higher static priority than the +tested application. This will allow an emergency kill of tested +real-time applications that do not block or terminate as expected. As +\fISCHED_FIFO\fP and \fISCHED_RR\fP processes can preempt other +processes forever, only root processes are allowed to activate these +policies under Linux. + +POSIX systems on which +.B sched_setscheduler +and +.B sched_getscheduler +are available define +.I _POSIX_PRIORITY_SCHEDULING +in . + +.SH "RETURN VALUE" +On success, +.BR sched_setscheduler +returns zero. +On success, +.BR sched_getscheduler +returns the policy for the process (a non-negative integer). +On error, \-1 is returned, +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +The scheduling \fIpolicy\fP is not one of the recognized policies, +or the parameter \fIp\fP does not make sense for the \fIpolicy\fP. +.TP +.B EPERM +The calling process does not have appropriate privileges +(Linux: does not have the +.B CAP_SYS_NICE +capability). Only privileged processes are allowed to +activate the \fISCHED_FIFO\fP and \fISCHED_RR\fP +policies. A process calling +.BR sched_setscheduler +needs an effective user ID equal to the user ID or effective user ID +of the process identified by +.IR pid , +or it must be privileged. +.TP +.B ESRCH +The process whose ID is \fIpid\fP could not be found. +.SH "CONFORMING TO" +POSIX.1b (formerly POSIX.4) +.SH NOTE +Standard Linux is a general-purpose operating system +and can handle background processes, +interactive applications, and soft real-time applications +(applications that need to usually meet timing deadlines). +This man page is directed at these kinds of applications. +.PP +Standard Linux is +.I not +designed to support +hard real-time applications, that is, applications in which deadlines +(often much shorter than a second) must be guaranteed or the system +will fail catastrophically. +Like all general-purpose operating systems, Linux +is designed to maximize average case performance +instead of worst case performance. +Linux's worst case performance for +interrupt handling is much poorer than its average case, its various +kernel locks (such as for SMP) produce long maximum wait times, and +many of its performance improvement techniques decrease average time by +increasing worst-case time. +For most situations, that's what you want, but +if you truly are developing a hard real-time application, +consider using hard real-time extensions to Linux such as +RTLinux (http://www.rtlinux.org) or RTAI (http://www.rtai.org) +or use a different operating system +designed specifically for hard real-time applications. +.SH "SEE ALSO" +.BR getpriority (2), +.BR mlock (2), +.BR mlockall (2), +.BR munlock (2), +.BR munlockall (2), +.BR nice (2), +.BR sched_get_priority_max (2), +.BR sched_get_priority_min (2), +.BR sched_getaffinity (2), +.BR sched_getparam (2), +.BR sched_rr_get_interval (2), +.BR sched_setaffinity (2), +.BR sched_setparam (2), +.BR sched_yield (2), +.BR setpriority (2), +.BR capabilities (7) +.PP +.I Programming for the real world \- POSIX.4 +by Bill O. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0 +.br +.I IEEE Std 1003.1b-1993 +(POSIX.1b standard) +.br +.I ISO/IEC 9945-1:1996 +\- This is the new 1996 revision of POSIX.1 which contains in one +single standard POSIX.1(1990), POSIX.1b(1993), POSIX.1c(1995), and +POSIX.1i(1995). diff --git a/man2/sched_yield.2 b/man2/sched_yield.2 new file mode 100644 index 000000000..59563d734 --- /dev/null +++ b/man2/sched_yield.2 @@ -0,0 +1,75 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) Tom Bjorkholm & Markus Kuhn, 1996 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 1996-04-01 Tom Bjorkholm +.\" First version written +.\" 1996-04-10 Markus Kuhn +.\" revision +.\" +.TH SCHED_YIELD 2 1996-04-10 "Linux 1.3.81" "Linux Programmer's Manual" +.SH NAME +sched_yield \- yield the processor +.SH SYNOPSIS +.B #include +.sp +\fBint sched_yield(void); +.fi +.SH DESCRIPTION +A process can relinquish the processor voluntarily without blocking by calling +.BR sched_yield . +The process will then be moved to the end of the queue for its static +priority and a new process gets to run. + +Note: If the current process is the only process in the highest +priority list at that time, this process will continue to run after a +call to +.BR sched_yield . + +POSIX systems on which +.B sched_yield +is available define +.I _POSIX_PRIORITY_SCHEDULING +in . + +.SH "RETURN VALUE" +On success, +.B sched_yield +returns 0. +On error, \-1 is returned, and +.I errno +is set appropriately. + +.SH "CONFORMING TO" +POSIX.1b (formerly POSIX.4) +.SH "SEE ALSO" +.BR sched_setscheduler (2) +for a description of Linux scheduling. +.PP +.I Programming for the real world \- POSIX.4 +by Bill O. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0 +.br +.I IEEE Std 1003.1b-1993 +(POSIX.1b standard) +.br +.I ISO/IEC 9945-1:1996 diff --git a/man2/security.2 b/man2/security.2 new file mode 100644 index 000000000..5d25ea6ce --- /dev/null +++ b/man2/security.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/select.2 b/man2/select.2 new file mode 100644 index 000000000..b6b48ec17 --- /dev/null +++ b/man2/select.2 @@ -0,0 +1,394 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is copyright (C) 1992 Drew Eckhardt, +.\" copyright (C) 1995 Michael Shields. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-05-18 by Jim Van Zandt +.\" Sun Feb 11 14:07:00 MET 1996 Martin Schulze +.\" * layout slightly modified +.\" +.\" Modified Mon Oct 21 23:05:29 EDT 1996 by Eric S. Raymond +.\" Modified Thu Feb 24 01:41:09 CET 2000 by aeb +.\" Modified Thu Feb 9 22:32:09 CET 2001 by bert hubert , aeb +.\" Modified Mon Nov 11 14:35:00 PST 2002 by Ben Woodard +.\" +.TH SELECT 2 2001-02-09 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \- synchronous I/O multiplexing +.SH SYNOPSIS +/* According to POSIX 1003.1-2001 */ +.br +.B #include +.sp +/* According to earlier standards */ +.br +.B #include +.br +.B #include +.br +.B #include +.sp +\fBint select(int \fIn\fB, fd_set *\fIreadfds\fB, +fd_set *\fIwritefds\fB, fd_set *\fIexceptfds\fB, +struct timeval *\fItimeout\fB); +.sp +\fBint pselect(int \fIn\fB, fd_set *\fIreadfds\fB, +fd_set *\fIwritefds\fB, fd_set *\fIexceptfds\fB, +const struct timespec *\fItimeout\fB, const sigset_t *\fIsigmask\fB); +.sp +.BI "FD_CLR(int " fd ", fd_set *" set ); +.br +.BI "FD_ISSET(int " fd ", fd_set *" set ); +.br +.BI "FD_SET(int " fd ", fd_set *" set ); +.br +.BI "FD_ZERO(fd_set *" set ); +.fi +.SH DESCRIPTION +The functions +.B select +and +.B pselect +wait for a number of file descriptors to change status. +.PP +Their function is identical, with three differences: +.TP +(i) +The +.B select +function uses a timeout that is a +.I struct timeval +(with seconds and microseconds), while +.B pselect +uses a +.I struct timespec +(with seconds and nanoseconds). +.TP +(ii) +The +.B select +function may update the +.I timeout +parameter to indicate how much time was left. The +.B pselect +function does not change this parameter. +.TP +(iii) +The +.B select +function has no +.I sigmask +parameter, and behaves as +.B pselect +called with NULL +.IR sigmask . +.PP +Three independent sets of descriptors are watched. Those listed in +.I readfds +will be watched to see if characters become +available for reading (more precisely, to see if a read will not +block - in particular, a file descriptor is also ready on end-of-file), +those in +.I writefds +will be watched to see if a write will not block, and +those in +.I exceptfds +will be watched for exceptions. On exit, the sets are modified in place +to indicate which descriptors actually changed status. +.PP +Four macros are provided to manipulate the sets. +.B FD_ZERO +will clear a set. +.B FD_SET +and +.B FD_CLR +add or remove a given descriptor from a set. +.B FD_ISSET +tests to see if a descriptor is part of the set; this is useful after +.B select +returns. +.PP +.I n +is the highest-numbered descriptor in any of the three sets, plus 1. +.PP +.I timeout +is an upper bound on the amount of time elapsed before +.B select +returns. It may be zero, causing +.B select +to return immediately. (This is useful for polling.) If +.I timeout +is NULL (no timeout), +.B select +can block indefinitely. +.PP +.I sigmask +is a pointer to a signal mask (see +.BR sigprocmask (2)); +if it is not NULL, then +.B pselect +first replaces the current signal mask by the one pointed to by +.IR sigmask , +then does the `select' function, and then restores the original +signal mask again. +.PP +The idea of +.B pselect +is that if one wants to wait for an event, either a signal +or something on a file descriptor, an atomic test is needed to prevent +race conditions. (Suppose the signal handler sets a global flag and +returns. Then a test of this global flag followed by a call of +.BR select () +could hang indefinitely if the signal arrived just after the test +but just before the call. On the other hand, +.B pselect +allows one to first block signals, handle the signals that have come in, +then call +.BR pselect () +with the desired +.IR sigmask , +avoiding the race.) +Since Linux today does not have a +.BR pselect () +system call, the current glibc2 routine still contains this race. +.SS "The timeout" +The time structures involved are defined in +.I +and look like + +.RS +.nf +struct timeval { + long tv_sec; /* seconds */ + long tv_usec; /* microseconds */ +}; +.fi +.RE + +and + +.RS +.nf +struct timespec { + long tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +}; +.fi +.RE + +(However, see below on the POSIX 1003.1-2001 versions.) +.PP +Some code calls +.B select +with all three sets empty, +.I n +zero, and a non-null +.I timeout +as a fairly portable way to sleep with subsecond precision. +.PP +On Linux, the function +.B select +modifies +.I timeout +to reflect the amount of time not slept; most other implementations +do not do this. This causes problems both when Linux code which reads +.I timeout +is ported to other operating systems, and when code is ported to Linux +that reuses a struct timeval for multiple +.BR select s +in a loop without reinitializing it. Consider +.I timeout +to be undefined after +.B select +returns. +.\" .PP - it is rumoured that: +.\" On BSD, when a timeout occurs, the file descriptor bits are not changed. +.\" - it is certainly true that: +.\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout. +.SH "RETURN VALUE" +On success, +.B select +and +.B pselect +return the number of descriptors contained in the three returned +descriptor sets (that is, the total number of one bits in +.IR readfds , +.IR writefds , +.IR exceptfds ) +which may be zero if the timeout expires before anything interesting happens. +On error, \-1 is returned, and +.I errno +is set appropriately; the sets and +.I timeout +become undefined, so do not +rely on their contents after an error. +.SH ERRORS +.TP +.B EBADF +An invalid file descriptor was given in one of the sets. +.TP +.B EINTR +A non blocked signal was caught. +.TP +.B EINVAL +.I n +is negative or the value contained within +.I timeout +is invalid. +.TP +.B ENOMEM +.B select +was unable to allocate memory for internal tables. +.SH EXAMPLE +.nf +#include +#include +#include +#include + +int +main(void) { + fd_set rfds; + struct timeval tv; + int retval; + + /* Watch stdin (fd 0) to see when it has input. */ + FD_ZERO(&rfds); + FD_SET(0, &rfds); + /* Wait up to five seconds. */ + tv.tv_sec = 5; + tv.tv_usec = 0; + + retval = select(1, &rfds, NULL, NULL, &tv); + /* Don't rely on the value of tv now! */ + + if (retval == -1) + perror("select()"); + else if (retval) + printf("Data is available now.\\n"); + /* FD_ISSET(0, &rfds) will be true. */ + else + printf("No data within five seconds.\\n"); + + return 0; +} +.fi +.SH "CONFORMING TO" +4.4BSD (the +.B select +function first appeared in 4.2BSD). Generally portable to/from +non-BSD systems supporting clones of the BSD socket layer (including +System V variants). However, note that the System V variant typically +sets the timeout variable before exit, but the BSD variant does not. +.PP +The +.B pselect +function is defined in IEEE Std 1003.1g-2000 (POSIX.1g), and part of +POSIX 1003.1-2001. +It is found in glibc2.1 and later. +Glibc2.0 has a function with this name, that however does not take a +.I sigmask +parameter. +.SH NOTES +An fd_set is a fixed size buffer. Executing FD_CLR or FD_SET with a value of +.I fd +that is negative or is equal to or larger than FD_SETSIZE will result +in undefined behavior. Moreover, POSIX requires +.I fd +to be a valid file descriptor. + +Concerning the types involved, the classical situation is that +the two fields of a struct timeval are longs (as shown above), +and the struct is defined in +.IR . +The POSIX 1003.1-2001 situation is + +.RS +.nf +struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* microseconds */ +}; +.fi +.RE + +where the struct is defined in +.I +and the data types time_t and suseconds_t are defined in +.IR . +.LP +Concerning prototypes, the classical situation is that one should +include +.I +for +.BR select . +The POSIX 1003.1-2001 situation is that one should include +.I +for +.B select +and +.BR pselect . +Libc4 and libc5 do not have a +.I +header; under glibc 2.0 and later this header exists. +Under glibc 2.0 it unconditionally gives the wrong prototype for +.BR pselect , +under glibc 2.1-2.2.1 it gives +.B pselect +when +.B _GNU_SOURCE +is defined, under glibc 2.2.2-2.2.4 it gives it when +.B _XOPEN_SOURCE +is defined and has a value of 600 or larger. +No doubt, since POSIX 1003.1-2001, it should give the prototype by default. +.SH BUGS +.B pselect +is currently emulated with a user-space wrapper that has a race condition. +For reliable (and more portable) signal trapping, use the self-pipe trick. +(Where a signal handler writes to a pipe whose other end is read by the +main loop.) + +Under Linux, +.B select +may report a socket file descriptor as "ready for reading", while +nevertheless a subsequent read blocks. This could for example +happen when data has arrived but upon examination has wrong +checksum and is discarded. There may be other circumstances. +.\" Stevens discusses a case where accept can block after select +.\" returns successfully because of an intervening RST from the client. +Thus it may be safer to use O_NONBLOCK on sockets that should not block. +.\" Maybe the kernel should have returned EIO in such a situation? +.SH "SEE ALSO" +For a tutorial with discussion and examples, see +.BR select_tut (2). +.LP +For vaguely related stuff, see +.BR accept (2), +.BR connect (2), +.BR poll (2), +.BR read (2), +.BR recv (2), +.BR send (2), +.BR sigprocmask (2), +.BR write (2) diff --git a/man2/select_tut.2 b/man2/select_tut.2 new file mode 100644 index 000000000..cc3c6eba6 --- /dev/null +++ b/man2/select_tut.2 @@ -0,0 +1,751 @@ +.\" This manpage is copyright (C) 2001 Paul Sheer. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" very minor changes, aeb +.\" +.\" Modified 5 June 2002, Michael Kerrisk +.\" +.TH SELECT_TUT 2 "October 21, 2001" "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \- synchronous I/O multiplexing +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.sp +.BI "int select(int " nfds ", fd_set *" readfds , +.BI "fd_set *" writefds ", fd_set *" exceptfds , +.BI "struct timeval *" utimeout ); +.sp +.BI "int pselect(int " nfds ", fd_set *" readfds , +.BI "fd_set *" writefds ", fd_set *" exceptfds , +.BI "const struct timespec *" ntimeout ", sigset_t *" sigmask ); +.sp +.BI "FD_CLR(int " fd ", fd_set *" set ); +.br +.BI "FD_ISSET(int " fd ", fd_set *" set ); +.br +.BI "FD_SET(int " fd ", fd_set *" set ); +.br +.BI "FD_ZERO(fd_set *" set ); +.fi +.SH DESCRIPTION + +\fBselect\fP (or \fBpselect\fP) is the pivot function of most C programs that +handle more than one simultaneous file descriptor (or socket handle) in an efficient +manner. Its principal arguments are three arrays of file descriptors: +\fIreadfds\fP, \fIwritefds\fP, and \fIexceptfds\fP. The way that +\fBselect\fP is usually used is to block while waiting for a "change of +status" on one or more of the file descriptors. A "change of status" is +when more characters become available from the file descriptor, \fIor\fP +when space becomes available within the kernel's internal buffers for +more to be written to the file descriptor, \fIor\fP when a file +descriptor goes into error (in the case of a socket or pipe this is +when the other end of the connection is closed). + +In summary, \fBselect\fP just watches multiple file descriptors, +and is the standard Unix call to do so. + +The arrays of file descriptors are called \fIfile descriptor sets\fP. +Each set is declared as type \fBfd_set\fP, and its contents can be +altered with the macros \fBFD_CLR\fP, \fBFD_ISSET\fP, \fBFD_SET\fP, and +\fBFD_ZERO\fP. \fBFD_ZERO\fP is usually the first function to be used on +a newly declared set. Thereafter, the individual file descriptors that +you are interested in can be added one by one with \fBFD_SET\fP. +\fBselect\fP modifies the contents of the sets according to the rules +described below; after calling \fBselect\fP you can test if your file +descriptor is still present in the set with the \fBFD_ISSET\fP macro. +\fBFD_ISSET\fP returns non-zero if the descriptor is present and zero if +it is not. \fBFD_CLR\fP removes a file descriptor from the set although +I can't see the use for it in a clean program. + +.SH ARGUMENTS +.TP +\fIreadfds\fP +This set is watched to see if data is available for reading from any of +its file descriptors. After \fBselect\fP has returned, \fIreadfds\fP will be +cleared of all file descriptors except for those file descriptors that +are immediately available for reading with a \fBrecv()\fP (for sockets) or +\fBread()\fP (for pipes, files, and sockets) call. +.TP +\fIwritefds\fP +This set is watched to see if there is space to write data to any of +its file descriptor. After \fBselect\fP has returned, \fIwritefds\fP will be +cleared of all file descriptors except for those file descriptors that +are immediately available for writing with a \fBsend()\fP (for sockets) or +\fBwrite()\fP (for pipes, files, and sockets) call. +.TP +\fIexceptfds\fP +This set is watched for exceptions or errors on any of the file +descriptors. However, that is actually just a rumor. How you use +\fIexceptfds\fP is to watch for \fIout\-of\-band\fP (OOB) data. OOB data +is data sent on a socket using the \fBMSG_OOB\fP flag, and hence +\fIexceptfds\fP only really applies to sockets. See \fBrecv\fP(2) and +\fBsend\fP(2) about this. After \fBselect\fP has returned, +\fIexceptfds\fP will be cleared of all file descriptors except for those +descriptors that are available for reading OOB data. You can only ever +read one byte of OOB data though (which is done with \fBrecv()\fP), and +writing OOB data (done with \fBsend\fP) can be done at any time and will +not block. Hence there is no need for a fourth set to check if a socket +is available for writing OOB data. +.TP +\fInfds\fP +This is an integer one more than the maximum of any file descriptor in +any of the sets. In other words, while you are busy adding file descriptors +to your sets, you must calculate the maximum integer value of all of +them, then increment this value by one, and then pass this as \fInfds\fP to +\fBselect\fP. +.TP +\fIutimeout\fP +.RS +This is the longest time \fBselect\fP must wait before returning, even +if nothing interesting happened. If this value is passed as \fBNULL\fP, +then \fBselect\fP blocks indefinitely waiting for an event. +\fIutimeout\fP can be set to zero seconds, which causes \fBselect\fP to +return immediately. The structure \fBstruct timeval\fP is defined as, +.PP +.nf +struct timeval { + time_t tv_sec; /* seconds */ + long tv_usec; /* microseconds */ +}; +.fi +.RE +.TP +\fIntimeout\fP +.RS +This argument has the same meaning as \fIutimeout\fP but \fBstruct timespec\fP +has nanosecond precision as follows, +.PP +.nf +struct timespec { + long tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +}; +.fi +.RE +.TP +\fIsigmask\fP +This argument holds a set of signals to allow while performing a \fBpselect\fP +call (see \fBsigaddset\fP(3) and \fBsigprocmask\fP(2)). It can be passed +as NULL, in which case it does not modify the set of allowed signals on +entry and exit to the function. It will then behave just like \fBselect\fP. + +.SH COMBINING SIGNAL AND DATA EVENTS +\fBpselect\fP must be used if you are waiting for a signal as well as +data from a file descriptor. Programs that receive signals as events +normally use the signal handler only to raise a global flag. The global +flag will indicate that the event must be processed in the main loop of +the program. A signal will cause the \fBselect\fP (or \fBpselect\fP) +call to return with \fBerrno\fP set to \fBEINTR\fP. This behavior is +essential so that signals can be processed in the main loop of the +program, otherwise \fBselect\fP would block indefinitely. Now, somewhere +in the main loop will be a conditional to check the global flag. So we +must ask: what if a signal arrives after the conditional, but before the +\fBselect\fP call? The answer is that \fBselect\fP would block +indefinitely, even though an event is actually pending. This race +condition is solved by the \fBpselect\fP call. This call can be used to +mask out signals that are not to be received except within the +\fBpselect\fP call. For instance, let us say that the event in question +was the exit of a child process. Before the start of the main loop, we +would block \fBSIGCHLD\fP using \fBsigprocmask\fP. Our \fBpselect\fP +call would enable \fBSIGCHLD\fP by using the virgin signal mask. Our +program would look like: +.PP +.nf +int child_events = 0; + +void child_sig_handler (int x) { + child_events++; + signal (SIGCHLD, child_sig_handler); +} + +int main (int argc, char **argv) { + sigset_t sigmask, orig_sigmask; + + sigemptyset (&sigmask); + sigaddset (&sigmask, SIGCHLD); + sigprocmask (SIG_BLOCK, &sigmask, + &orig_sigmask); + + signal (SIGCHLD, child_sig_handler); + + for (;;) { /* main loop */ + for (; child_events > 0; child_events--) { + /* do event work here */ + } + r = pselect (nfds, &rd, &wr, &er, 0, &orig_sigmask); + + /* main body of program */ + } +} +.fi +.PP +Note that the above \fBpselect\fP call can be replaced with: +.PP +.nf + sigprocmask (SIG_BLOCK, &orig_sigmask, 0); + r = select (nfds, &rd, &wr, &er, 0); + sigprocmask (SIG_BLOCK, &sigmask, 0); +.fi +.PP +but then there is still the possibility that a signal +could arrive after the first \fBsigprocmask\fP and before +the \fBselect\fP. If you do do this, it is prudent to +at least put a finite timeout so that the process does +not block. At present glibc probably works this way. +The Linux kernel does not have a native \fBpselect\fP +system call as yet so this is all probably much of a +moot point. +.PP + + +.SH PRACTICAL + +So what is the point of \fBselect\fP? Can't I just read and write to my +descriptors whenever I want? The point of select is that it watches +multiple descriptors at the same time and properly puts the process to +sleep if there is no activity. It does this while enabling you to handle +multiple simultaneous pipes and sockets. Unix programmers often find +themselves in a position where they have to handle IO from more than one +file descriptor where the data flow may be intermittent. If you were to +merely create a sequence of \fBread\fP and \fBwrite\fP calls, you would +find that one of your calls may block waiting for data from/to a file +descriptor, while another file descriptor is unused though available +for data. \fBselect\fP efficiently copes with this situation. + +A classic example of \fBselect\fP comes from the \fBselect\fP +man page: + +.nf +#include +#include +#include +#include + +int +main(void) { + fd_set rfds; + struct timeval tv; + int retval; + + /* Watch stdin (fd 0) to see when it has input. */ + FD_ZERO(&rfds); + FD_SET(0, &rfds); + /* Wait up to five seconds. */ + tv.tv_sec = 5; + tv.tv_usec = 0; + + retval = select(1, &rfds, NULL, NULL, &tv); + /* Don't rely on the value of tv now! */ + + if (retval == -1) + perror("select()"); + else if (retval) + printf("Data is available now.\\n"); + /* FD_ISSET(0, &rfds) will be true. */ + else + printf("No data within five seconds.\\n"); + + exit(0); +} +.fi + + +.SH PORT FORWARDING EXAMPLE + +Here is an example that better demonstrates the true utility of +\fBselect\fP. The listing below a TCP forwarding program that forwards +from one TCP port to another. +.PP +.nf +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +static int forward_port; + +#undef max +#define max(x,y) ((x) > (y) ? (x) : (y)) + +static int listen_socket (int listen_port) { + struct sockaddr_in a; + int s; + int yes; + if ((s = socket (AF_INET, SOCK_STREAM, 0)) < 0) { + perror ("socket"); + return -1; + } + yes = 1; + if (setsockopt + (s, SOL_SOCKET, SO_REUSEADDR, + (char *) &yes, sizeof (yes)) < 0) { + perror ("setsockopt"); + close (s); + return -1; + } + memset (&a, 0, sizeof (a)); + a.sin_port = htons (listen_port); + a.sin_family = AF_INET; + if (bind + (s, (struct sockaddr *) &a, sizeof (a)) < 0) { + perror ("bind"); + close (s); + return -1; + } + printf ("accepting connections on port %d\\n", + (int) listen_port); + listen (s, 10); + return s; +} + +static int connect_socket (int connect_port, + char *address) { + struct sockaddr_in a; + int s; + if ((s = socket (AF_INET, SOCK_STREAM, 0)) < 0) { + perror ("socket"); + close (s); + return -1; + } + + memset (&a, 0, sizeof (a)); + a.sin_port = htons (connect_port); + a.sin_family = AF_INET; + + if (!inet_aton + (address, + (struct in_addr *) &a.sin_addr.s_addr)) { + perror ("bad IP address format"); + close (s); + return -1; + } + + if (connect + (s, (struct sockaddr *) &a, + sizeof (a)) < 0) { + perror ("connect()"); + shutdown (s, SHUT_RDWR); + close (s); + return -1; + } + return s; +} + +#define SHUT_FD1 { \\ + if (fd1 >= 0) { \\ + shutdown (fd1, SHUT_RDWR); \\ + close (fd1); \\ + fd1 = -1; \\ + } \\ + } + +#define SHUT_FD2 { \\ + if (fd2 >= 0) { \\ + shutdown (fd2, SHUT_RDWR); \\ + close (fd2); \\ + fd2 = -1; \\ + } \\ + } + +#define BUF_SIZE 1024 + +int main (int argc, char **argv) { + int h; + int fd1 = -1, fd2 = -1; + char buf1[BUF_SIZE], buf2[BUF_SIZE]; + int buf1_avail, buf1_written; + int buf2_avail, buf2_written; + + if (argc != 4) { + fprintf (stderr, + "Usage\\n\\tfwd \\ + \\n"); + exit (1); + } + + signal (SIGPIPE, SIG_IGN); + + forward_port = atoi (argv[2]); + + h = listen_socket (atoi (argv[1])); + if (h < 0) + exit (1); + + for (;;) { + int r, nfds = 0; + fd_set rd, wr, er; + FD_ZERO (&rd); + FD_ZERO (&wr); + FD_ZERO (&er); + FD_SET (h, &rd); + nfds = max (nfds, h); + if (fd1 > 0 && buf1_avail < BUF_SIZE) { + FD_SET (fd1, &rd); + nfds = max (nfds, fd1); + } + if (fd2 > 0 && buf2_avail < BUF_SIZE) { + FD_SET (fd2, &rd); + nfds = max (nfds, fd2); + } + if (fd1 > 0 + && buf2_avail - buf2_written > 0) { + FD_SET (fd1, &wr); + nfds = max (nfds, fd1); + } + if (fd2 > 0 + && buf1_avail - buf1_written > 0) { + FD_SET (fd2, &wr); + nfds = max (nfds, fd2); + } + if (fd1 > 0) { + FD_SET (fd1, &er); + nfds = max (nfds, fd1); + } + if (fd2 > 0) { + FD_SET (fd2, &er); + nfds = max (nfds, fd2); + } + + r = select (nfds + 1, &rd, &wr, &er, NULL); + + if (r == -1 && errno == EINTR) + continue; + if (r < 0) { + perror ("select()"); + exit (1); + } + if (FD_ISSET (h, &rd)) { + unsigned int l; + struct sockaddr_in client_address; + memset (&client_address, 0, l = + sizeof (client_address)); + r = accept (h, (struct sockaddr *) + &client_address, &l); + if (r < 0) { + perror ("accept()"); + } else { + SHUT_FD1; + SHUT_FD2; + buf1_avail = buf1_written = 0; + buf2_avail = buf2_written = 0; + fd1 = r; + fd2 = + connect_socket (forward_port, + argv[3]); + if (fd2 < 0) { + SHUT_FD1; + } else + printf ("connect from %s\\n", + inet_ntoa + (client_address.sin_addr)); + } + } +/* NB: read oob data before normal reads */ + if (fd1 > 0) + if (FD_ISSET (fd1, &er)) { + char c; + errno = 0; + r = recv (fd1, &c, 1, MSG_OOB); + if (r < 1) { + SHUT_FD1; + } else + send (fd2, &c, 1, MSG_OOB); + } + if (fd2 > 0) + if (FD_ISSET (fd2, &er)) { + char c; + errno = 0; + r = recv (fd2, &c, 1, MSG_OOB); + if (r < 1) { + SHUT_FD1; + } else + send (fd1, &c, 1, MSG_OOB); + } + if (fd1 > 0) + if (FD_ISSET (fd1, &rd)) { + r = + read (fd1, buf1 + buf1_avail, + BUF_SIZE - buf1_avail); + if (r < 1) { + SHUT_FD1; + } else + buf1_avail += r; + } + if (fd2 > 0) + if (FD_ISSET (fd2, &rd)) { + r = + read (fd2, buf2 + buf2_avail, + BUF_SIZE - buf2_avail); + if (r < 1) { + SHUT_FD2; + } else + buf2_avail += r; + } + if (fd1 > 0) + if (FD_ISSET (fd1, &wr)) { + r = + write (fd1, + buf2 + buf2_written, + buf2_avail - + buf2_written); + if (r < 1) { + SHUT_FD1; + } else + buf2_written += r; + } + if (fd2 > 0) + if (FD_ISSET (fd2, &wr)) { + r = + write (fd2, + buf1 + buf1_written, + buf1_avail - + buf1_written); + if (r < 1) { + SHUT_FD2; + } else + buf1_written += r; + } +/* check if write data has caught read data */ + if (buf1_written == buf1_avail) + buf1_written = buf1_avail = 0; + if (buf2_written == buf2_avail) + buf2_written = buf2_avail = 0; +/* one side has closed the connection, keep + writing to the other side until empty */ + if (fd1 < 0 + && buf1_avail - buf1_written == 0) { + SHUT_FD2; + } + if (fd2 < 0 + && buf2_avail - buf2_written == 0) { + SHUT_FD1; + } + } + return 0; +} +.fi +.PP +The above program properly forwards most kinds of TCP connections +including OOB signal data transmitted by \fBtelnet\fP servers. It +handles the tricky problem of having data flow in both directions +simultaneously. You might think it more efficient to use a \fBfork()\fP +call and devote a thread to each stream. This becomes more tricky than +you might suspect. Another idea is to set non-blocking IO using an +\fBioctl()\fP call. This also has its problems because you end up having +to have inefficient timeouts. + +The program does not handle more than one simultaneous connection at a +time, although it could easily be extended to do this with a linked list +of buffers - one for each connection. At the moment, new +connections cause the current connection to be dropped. + +.SH SELECT LAW + +Many people who try to use \fBselect\fP come across behavior that is +difficult to understand and produces non-portable or borderline +results. For instance, the above program is carefully written not to +block at any point, even though it does not set its file descriptors to +non-blocking mode at all (see \fBioctl\fP(2)). It is easy to introduce +subtle errors that will remove the advantage of using \fBselect\fP, +hence I will present a list of essentials to watch for when using the +\fBselect\fP call. + +.TP +\fB1.\fP +You should always try use \fBselect\fP without a timeout. Your program +should have nothing to do if there is no data available. Code that +depends on timeouts is not usually portable and difficult to debug. +.TP +\fB2.\fP +The value \fInfds\fP must be properly calculated for efficiency as +explained above. +.TP +\fB3.\fP +No file descriptor must be added to any set if you do not intend +to check its result after the \fBselect\fP call, and respond +appropriately. See next rule. +.TP +\fB4.\fP +After \fBselect\fP returns, all file descriptors in all sets +\fImust\fP be checked. Any file descriptor that is available +for writing \fImust\fP be written to, and any file descriptor +available for reading \fImust\fP be read, etc. +.TP +\fB5.\fP +The functions \fBread()\fP, \fBrecv()\fP, \fBwrite()\fP, and +\fBsend()\fP do \fInot\fP necessarily read/write the full amount of data +that you have requested. If they do read/write the full amount, its +because you have a low traffic load and a fast stream. This is not +always going to be the case. You should cope with the case of your +functions only managing to send or receive a single byte. +.TP +\fB6.\fP +Never read/write only in single bytes at a time unless your are really +sure that you have a small amount of data to process. It is extremely +inefficient not to read/write as much data as you can buffer each time. +The buffers in the example above are 1024 bytes although they could +easily be made as large as the maximum possible packet size on your +local network. +.TP +\fB7.\fP +The functions \fBread()\fP, \fBrecv()\fP, \fBwrite()\fP, and +\fBsend()\fP as well as the \fBselect()\fP call can return -1 with an +errno of \fBEINTR\fP or \fBEAGAIN\fP (\fBEWOULDBLOCK\fP) which are not +errors. These results must be properly managed (not done properly +above). If your program is not going to receive any signals then +it is unlikely you will get \fBEINTR\fP. If your program does not +set non-blocking IO, you will not get \fBEAGAIN\fP. Nonetheless +you should still cope with these errors for completeness. +.TP +\fB8.\fP +Never call \fBread()\fP, \fBrecv()\fP, \fBwrite()\fP, or \fBsend()\fP +with a buffer length of zero. +.TP +\fB9.\fP +Except as indicated in \fB7.\fP, the functions \fBread()\fP, +\fBrecv()\fP, \fBwrite()\fP, and \fBsend()\fP never have a return value +less than 1 except if an error has occurred. For instance, a +\fBread()\fP on a pipe where the other end has died returns zero (so +does an end-of-file error), \fIbut\fP only returns zero +once (a followup read or write will return \-1). Should +any of these functions return 0 or \-1, you should \fInot\fP +pass that descriptor to select ever again. In the above example, +I close the descriptor immediately, and then set it to \-1 +to prevent it being included in a set. +.TP +\fB10.\fP +The timeout value must be initialized with each new call to \fBselect\fP, +since some operating systems modify the structure. \fBpselect\fP +however does not modify its timeout structure. +.TP +\fB11.\fP +I have heard that the Windows socket layer does not cope with OOB data +properly. It also does not cope with \fBselect\fP calls when no file +descriptors are set at all. Having no file descriptors set is a useful +way to sleep the process with sub-second precision by using the timeout. +(See further on.) + +.SH USLEEP EMULATION + +On systems that do not have a \fBusleep\fP function, you can call +\fBselect\fP with a finite timeout and no file descriptors as +follows: +.PP +.nf + struct timeval tv; + tv.tv_sec = 0; + tv.tv_usec = 200000; /* 0.2 seconds */ + select (0, NULL, NULL, NULL, &tv); +.fi +.PP +This is only guarenteed to work on Unix systems, however. + +.SH RETURN VALUE + +On success, \fBselect\fP returns the total number of file descriptors +still present in the file descriptor sets. + +If \fBselect\fP timed out, then the file descriptors sets should be all +empty (but may not be on some systems). However the return value will +definitely be zero. + +A return value of \-1 indicates an error, with \fBerrno\fP being +set appropriately. In the case of an error, the returned sets and +the timeout struct contents are undefined and should not be used. +\fBpselect\fP however never modifies \fIntimeout\fP. + +.SH ERRORS +.TP +\fBEBADF\fP +A set contained an invalid file descriptor. This error often occurs when +you add a file descriptor to a set that you have already issued a +\fBclose\fP on, or when that file descriptor has experienced some kind +of error. Hence you should cease adding to sets any file descriptor that +returns an error on reading or writing. +.TP +\fBEINTR\fP +An interrupting signal was caught like \fBSIGINT\fP or \fBSIGCHLD\fP etc. +In this case you should rebuild your file descriptor sets and retry. +.TP +\fBEINVAL\fP +Occurs if \fInfds\fP is negative or an invalid value is specified +in \fIutimeout\fP or \fIntimeout\fP. +.TP +\fBENOMEM\fP +Internal memory allocation failure. + +.SH NOTES +Generally speaking, all operating systems that support sockets, also +support \fBselect\fP. Some people consider \fBselect\fP to be an +esoteric and rarely used function. Indeed, many types of programs become +extremely complicated without it. \fBselect\fP can be used to solve +many problems in a portable and efficient way that naive programmers try +to solve with threads, forking, IPCs, signals, memory sharing and other +dirty methods. \fBpselect\fP is a newer function that is less commonly +used. +.PP +The +.BR poll (2) +system call has the same functionality as \fBselect\fP, +but with less subtle behavior. It is less portable than \fBselect\fP. + +.SH CONFORMING TO +4.4BSD (the \fBselect\fP function first appeared in 4.2BSD). Generally +portable to/from non-BSD systems supporting clones of the BSD socket +layer (including System V variants). However, note that the System V +variant typically sets the timeout variable before exit, but the BSD +variant does not. +.PP +The \fBpselect\fP function is defined in IEEE Std 1003.1g-2000 (POSIX.1g). +It is found in glibc2.1 and later. Glibc2.0 has a function with this name, +that however does not take a \fIsigmask\fP parameter. + +.SH SEE ALSO +.BR accept (2), +.BR connect (2), +.BR ioctl (2), +.BR poll (2), +.BR read (2), +.BR recv (2), +.BR select (2), +.BR send (2), +.BR sigprocmask (2), +.BR write (2), +.BR sigaddset (3), +.BR sigdelset (3), +.BR sigemptyset (3), +.BR sigfillset (3), +.BR sigismember (3) + +.SH AUTHORS +This man page was written by Paul Sheer. diff --git a/man2/semctl.2 b/man2/semctl.2 new file mode 100644 index 000000000..86b1e0db7 --- /dev/null +++ b/man2/semctl.2 @@ -0,0 +1,369 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Tue Oct 22 17:53:56 1996 by Eric S. Raymond +.\" Modified Fri Jun 19 10:59:15 1998 by Andries Brouwer +.\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer +.\" Modified 20 Dec 2001, Michael Kerrisk +.\" Modified 21 Dec 2001, aeb +.\" Modified 27 May 2004, Michael Kerrisk +.\" Added notes on CAP_IPC_OWNER requirement +.\" Modified 17 Jun 2004, Michael Kerrisk +.\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID +.\" +.TH SEMCTL 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +semctl \- semaphore control operations +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.sp +.BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);" +.fi +.SH DESCRIPTION +The function +.B semctl +performs the control operation specified by +.I cmd +on the semaphore set identified by +.IR semid , +or on the +.IR semnum -th +semaphore of that set. +(Semaphores are numbered starting at 0.) +.PP +This function has three or four arguments. When there +are four, the call is +.BI semctl( semid , semnum , cmd , arg ); +where the fourth argument +.I arg +has a type +.B union semun +defined as follows: + +.nf +#if defined(__GNU_LIBRARY__) && !defined(_SEM_SEMUN_UNDEFINED) +/* union semun is defined by including */ +#else +/* according to X/OPEN we have to define it ourselves */ +union semun { + int val; /* value for SETVAL */ + struct semid_ds *buf; /* buffer for IPC_STAT, IPC_SET */ + unsigned short *array; /* array for GETALL, SETALL */ + /* Linux specific part: */ + struct seminfo *__buf; /* buffer for IPC_INFO */ +}; +#endif +.fi +.PP +Legal values for +.I cmd +are: +.TP 12 +.B IPC_STAT +Copy info from the semaphore set data structure +into the structure pointed to by +.IB arg .buf \fR. +The argument +.I semnum +is ignored. +The calling process must have read access privileges on the semaphore set. +.TP +.B IPC_SET +Write the values of some members of the +.B semid_ds +structure pointed to by +.IB arg .buf +to the semaphore set data structure, updating also its +.B sem_ctime +member. +Considered members from the user supplied +.B "struct semid_ds" +pointed to by +.IB arg .buf +are +.nf +.sp +.ft B + sem_perm.uid + sem_perm.gid + sem_perm.mode \fR/* only lowest 9-bits */\fP +.fi +.ft R +.sp +The effective user\-ID of the calling process must be that of the +super\-user, or match the creator or owner of the semaphore set. +The argument +.I semnum +is ignored. +.TP +.B IPC_RMID +Immediately remove the semaphore set and its data structures +awakening all waiting processes (with an error return and +.B errno +set to +.BR EIDRM ). +The effective user\-ID of the calling process must be that of the +super\-user, or match the creator or owner of the semaphore set. +The argument +.I semnum +is ignored. +.TP +.B GETALL +Return +.B semval +for all semaphores of the set into +.IB arg .array \fR. +The argument +.I semnum +is ignored. +The calling process must have read access privileges on the semaphore set. +.TP +.B GETNCNT +The system call returns the value of +.B semncnt +for the +.IR semnum \-th +semaphore of the set +(i.e. the number of processes waiting for an increase of +.B semval +for the +.IR semnum \-th +semaphore of the set). +The calling process must have read access privileges on the semaphore set. +.TP +.B GETPID +The system call returns the value of +.B sempid +for the +.IR semnum \-th +semaphore of the set +(i.e. the pid of the process that executed the last +.B semop +call for the +.IR semnum \-th +semaphore of the set). +The calling process must have read access privileges on the semaphore set. +.TP +.B GETVAL +The system call returns the value of +.B semval +for the +.IR semnum \-th +semaphore of the set. +The calling process must have read access privileges on the semaphore set. +.TP +.B GETZCNT +The system call returns the value of +.B semzcnt +for the +.IR semnum \-th +semaphore of the set +(i.e. the number of processes waiting for +.B semval +of the +.IR semnum \-th +semaphore of the set to become 0). +The calling process must have read access privileges on the semaphore set. +.TP +.B SETALL +Set +.B semval +for all semaphores of the set using +.IB arg .array , +updating also the +.B sem_ctime +member of the +.B semid_ds +structure associated to the set. +Undo entries are cleared for altered semaphores in all processes. +Processes sleeping on the wait queue are awakened if some +.B semval +becomes 0 or increases. +The argument +.I semnum +is ignored. +The calling process must have alter access privileges on the semaphore set. +.TP +.B SETVAL +Set the value of +.B semval +to +.IB arg .val +for the +.IR semnum \-th +semaphore of the set, updating also the +.B sem_ctime +member of the +.B semid_ds +structure associated to the set. +Undo entries are cleared for altered semaphores in all processes. +Processes sleeping on the wait queue are awakened if +.B semval +becomes 0 or increases. +The calling process must have alter access privileges on the semaphore set. +.SH "RETURN VALUE" +On failure +.B semctl +returns +.B \-1 +with +.B errno +indicating the error. +Otherwise the system call returns a nonnegative value depending on +.I cmd +as follows: +.TP 11 +.B GETNCNT +the value of +.BR semncnt . +.TP +.B GETPID +the value of +.BR sempid . +.TP +.B GETVAL +the value of +.BR semval . +.TP +.B GETZCNT +the value of +.BR semzcnt . +.LP +All other +.I cmd +values return 0 on success. +.SH ERRORS +On failure, +.B errno +will be set to one of the following: +.TP 11 +.B EACCES +The argument +.I cmd +has one of the values +.BR GETALL , +.BR GETPID , +.BR GETVAL , +.BR GETNCNT , +.BR GETZCNT , +.BR IPC_STAT , +.BR SEM_STAT , +.BR SETALL , +or +.B SETVAL +and the calling process does not have the required +permissions on the semaphore set and does not have the +.B CAP_IPC_OWNER +capability. +.TP +.B EFAULT +The address pointed to by +.IB arg .buf +or +.IB arg .array +isn't accessible. +.TP +.B EIDRM +The semaphore set was removed. +.TP +.B EINVAL +Invalid value for +.I cmd +or +.IR semid . +.TP +.B EPERM +The argument +.I cmd +has value +.B IPC_SET +or +.B IPC_RMID +but the but the effective user ID of the calling process is not the creator +(as found in +.IR sem_perm.cuid ) +or the owner +(as found in +.IR sem_perm.uid ) +of the semaphore set, +and the process does not have the +.B CAP_SYS_ADMIN +capability. +.TP +.B ERANGE +The argument +.I cmd +has value +.B SETALL +or +.B SETVAL +and the value to which +.B semval +has to be set (for some semaphore of the set) is less than 0 +or greater than the implementation value +.BR SEMVMX . +.SH NOTES +The +.BR IPC_INFO , +.BR SEM_STAT +and +.B SEM_INFO +control calls are used by the +.BR ipcs (8) +program to provide information on allocated resources. +In the future these can be modified as needed or moved to a proc file system +interface. +.LP +Various fields in a \fIstruct semid_ds\fP were shorts under Linux 2.2 +and have become longs under Linux 2.4. To take advantage of this, +a recompilation under glibc-2.1.91 or later should suffice. +(The kernel distinguishes old and new calls by a IPC_64 flag in +.IR cmd .) +.PP +The following system limit on semaphore sets affects a +.B semctl +call: +.TP 11 +.B SEMVMX +Maximum value for +.BR semval : +implementation dependent (32767). +.LP +For greater portability it is best to always call +.B semctl +with four arguments. +.LP +Under Linux, the function +.B semctl +is not a system call, but is implemented via the system call +.BR ipc (2). +.SH "CONFORMING TO" +SVr4, SVID. SVr4 documents more error conditions EINVAL and EOVERFLOW. +.SH "SEE ALSO" +.BR ipc (2), +.BR semget (2), +.BR semop (2), +.BR ipc (5), +.BR capabilities (7) diff --git a/man2/semget.2 b/man2/semget.2 new file mode 100644 index 000000000..baeaf4825 --- /dev/null +++ b/man2/semget.2 @@ -0,0 +1,264 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Tue Oct 22 17:54:56 1996 by Eric S. Raymond +.\" Modified 1 Jan 2002, Martin Schulze +.\" Modified 4 Jan 2002, Michael Kerrisk +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH SEMGET 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +semget \- get a semaphore set identifier +.SH SYNOPSIS +.nf +.B +#include +.B +#include +.B +#include +.fi +.sp +.BI "int semget(key_t " key , +.BI "int " nsems , +.BI "int " semflg ); +.SH DESCRIPTION +This function returns the semaphore set identifier +associated with the argument +.IR key . +A new set of +.I nsems +semaphores is created if +.I key +has the value +.B IPC_PRIVATE +or if no existing semaphore set is associated to +.I key +and +.B IPC_CREAT +is asserted in +.I semflg +(i.e. +.IR semflg " &" +.B IPC_CREAT +isn't zero). +.PP +The presence in +.I semflg +of the fields +.B IPC_CREAT +and +.B IPC_EXCL +plays the same role, with respect to the existence +of the semaphore set, as the presence +of +.B O_CREAT +and +.B O_EXCL +in the mode argument of the +.BR open (2) +system call: i.e. the +.B semget +function fails if +.I semflg +asserts both +.B IPC_CREAT +and +.B IPC_EXCL +and a semaphore set already exists for +.IR key . +.PP +Upon creation, the low-order 9 bits of the argument +.I semflg +define the access permissions (for owner, group and others) +for the semaphore set. +These bits have the same format, and the same +meaning, as the mode argument in the +.BR open (2) +or +.BR creat (2) +system calls (though the execute permissions are +not meaningful for semaphores, and write permissions mean permission +to alter semaphore values). +.PP +When creating a new semaphore set, +.B semget +initializes the semaphore set's associated data structure +.B semid_ds +as follows: +.IP +.B sem_perm.cuid +and +.B sem_perm.uid +are set to the effective user\-ID of the calling process. +.IP +.B sem_perm.cgid +and +.B sem_perm.gid +are set to the effective group\-ID of the calling process. +.IP +The low-order 9 bits of +.B sem_perm.mode +are set to the low-order 9 bits of +.IR semflg . +.IP +.B sem_nsems +is set to the value of +.IR nsems . +.IP +.B sem_otime +is set to 0. +.IP +.B sem_ctime +is set to the current time. +.PP +The argument +.I nsems +can be +.B 0 +(a don't care) +when a semaphore set is not being created. +Otherwise +.I nsems +must be greater than +.B 0 +and less than or equal to the maximum number of semaphores per semaphore set +.RB ( SEMMSL ). +.PP +If the semaphore set already exists, the access permissions are +verified. +.\" and a check is made to see if it is marked for destruction. +.SH "RETURN VALUE" +If successful, the return value will be the semaphore set identifier +(a nonnegative integer), otherwise +.B \-1 +is returned, with +.I errno +indicating the error. +.SH ERRORS +On failure +.I errno +will be set to one of the following: +.TP 11 +.B EACCES +A semaphore set exists for +.IR key , +but the calling process does not have permission to access the set, +and does not have the +.BR CAP_IPC_OWNER +capability. +.TP +.B EEXIST +A semaphore set exists for +.B key +and +.I semflg +was asserting both +.B IPC_CREAT +and +.BR IPC_EXCL . +.\" .TP +.\" .B EIDRM +.\" The semaphore set is marked to be deleted. +.TP +.B EINVAL +.IR nsems +is less than 0 or greater than the limit on the number +of semaphores per semaphore set +.RB ( SEMMSL ), +or a semaphore set corresponding to +.I key +already exists, and +.I nsems +is larger than the number of semaphores in that set. +.TP +.B ENOENT +No semaphore set exists for +.I key +and +.I semflg +wasn't asserting +.BR IPC_CREAT . +.TP +.B ENOMEM +A semaphore set has to be created but the system has not enough memory for +the new data structure. +.TP +.B ENOSPC +A semaphore set has to be created but the system limit for the maximum +number of semaphore sets +.RB ( SEMMNI ), +or the system wide maximum number of semaphores +.RB ( SEMMNS ), +would be exceeded. +.SH NOTES +.B IPC_PRIVATE +isn't a flag field but a +.B key_t +type. +If this special value is used for +.IR key , +the system call ignores everything but the low-order 9 bits of +.I semflg +and creates a new semaphore set (on success). +.PP +The followings are limits on semaphore set resources affecting a +.B semget +call: +.TP 11 +.B SEMMNI +System wide maximum number of semaphore sets: policy dependent. +.TP +.B SEMMSL +Maximum number of semaphores per semid: implementation dependent +(500 currently). +.TP +.B SEMMNS +System wide maximum number of semaphores: policy dependent. +Values greater than +.B SEMMSL * SEMMNI +makes it irrelevant. +.SH BUGS +The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW +would more clearly show its function. +.LP +The data structure associated with each semaphore in the set +isn't initialized by the system call. +In order to initialize those data structures, one has to execute a +subsequent call to +.BR semctl (2) +to perform a +.B SETVAL +or a +.B SETALL +command on the semaphore set. +.SH "CONFORMING TO" +SVr4, SVID. +SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN, +ERANGE, EFAULT. +.SH "SEE ALSO" +.BR semctl (2), +.BR semop (2), +.BR ftok (3), +.BR ipc (5), +.BR capabilities (7) diff --git a/man2/semop.2 b/man2/semop.2 new file mode 100644 index 000000000..2b80f3ab2 --- /dev/null +++ b/man2/semop.2 @@ -0,0 +1,453 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1996-10-22, Eric S. Raymond +.\" Modified 2002-01-08, Michael Kerrisk +.\" Modified 2003-04-28, Ernie Petrides +.\" Modified 2004-05-27, Michael Kerrisk +.\" +.TH SEMOP 2 2003-04-28 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +semop, semtimedop \- semaphore operations +.SH SYNOPSIS +.nf +.B +#include +.B +#include +.B +#include +.fi +.sp +.BI "int semop(int " semid , +.BI "struct sembuf *" sops , +.BI "unsigned " nsops ); +.sp +.BI "int semtimedop(int " semid , +.BI "struct sembuf *" sops , +.BI "unsigned " nsops , +.BI "struct timespec *" timeout ); +.SH DESCRIPTION +A semaphore is represented by an anonymous structure +including the following members: +.sp +.in +4n +.nf +unsigned short semval; /* semaphore value */ +unsigned short semzcnt; /* # waiting for zero */ +unsigned short semncnt; /* # waiting for increase */ +pid_t sempid; /* process that did last op */ +.sp +.in -4n +.fi +The function +.B semop +performs operations on selected members of the semaphore set indicated by +.IR semid . +Each of the +.I nsops +elements in the array pointed to by +.I sops +specifies an operation to be performed on a semaphore by a +.B "struct sembuf" +including the following members: +.sp +.in +4n +.nf +unsigned short sem_num; /* semaphore number */ +short sem_op; /* semaphore operation */ +short sem_flg; /* operation flags */ +.sp +.in -4n +.fi +Flags recognized in +.I sem_flg +are +.B IPC_NOWAIT +and +.BR SEM_UNDO . +If an operation asserts +.BR SEM_UNDO , +it will be undone when the process exits. +.PP +The set of operations contained in +.I sops +is performed +.IR atomically , +that is, the operations are performed at the same time, and only +if they can all be simultaneously performed. +The behaviour of the system call if not all operations can be +performed immediately depends on the presence of the +.B IPC_NOWAIT +flag in the individual +.I sem_flg +fields, as noted below. + +Each operation is performed on the +.IR sem_num \-th +semaphore of the semaphore set, where the first semaphore of the set +is semaphore +.BR 0 . +There are three types of operation, distinguished by the value of +.IR sem_op . +.PP +If +.I sem_op +is a positive integer, the operation adds this value to +the semaphore value +.RI ( semval ). +Furthermore, if +.B SEM_UNDO +is asserted for this operation, the system updates the process undo count +.RI ( semadj ) +for this semaphore. +This operation can always proceed \- it never forces a process to wait. +The calling process must have alter permission on the semaphore set. +.PP +If +.I sem_op +is zero, the process must have read access permission on the semaphore +set. +This is a "wait-for-zero" operation: if +.I semval +is zero, the operation can immediately proceed. +Otherwise, if +.B IPC_NOWAIT +is asserted in +.IR sem_flg , +the system call fails with +.I errno +set to +.B EAGAIN +(and none of the operations in +.I sops +is performed). +Otherwise +.I semzcnt +(the count of processes waiting until this semaphore's value becomes zero) +is incremented by one and the process sleeps until +one of the following occurs: +.IP \(bu +.I semval +becomes 0, at which time the value of +.I semzcnt +is decremented. +.IP \(bu +The semaphore set +is removed: the system call fails, with +.I errno +set to +.BR EIDRM . +.IP \(bu +The calling process catches a signal: +the value of +.I semzcnt +is decremented and the system call fails, with +.I errno +set to +.BR EINTR . +.IP \(bu +The time limit specified by +.I timeout +in a +.B semtimedop +call expires: the system call fails, with +.I errno +set to +.BR EAGAIN . +.PP +If +.I sem_op +is less than zero, the process must have alter permission on the +semaphore set. +If +.I semval +is greater than or equal to the absolute value of +.IR sem_op , +the operation can proceed immediately: +the absolute value of +.I sem_op +is subtracted from +.IR semval , +and, if +.B SEM_UNDO +is asserted for this operation, the system updates the process undo count +.RI ( semadj ) +for this semaphore. +If the absolute value of +.I sem_op +is greater than +.IR semval , +and +.B IPC_NOWAIT +is asserted in +.IR sem_flg , +the system call fails, with +.I errno +set to +.B EAGAIN +(and none of the operations in +.I sops +is performed). +Otherwise +.I semncnt +(the counter of processes waiting for this semaphore's value to increase) +is incremented by one and the process sleeps until +one of the following occurs: +.IP \(bu +.I semval +becomes greater than or equal to the absolute value of +.IR sem_op , +at which time the value of +.I semncnt +is decremented, the absolute value of +.I sem_op +is subtracted from +.I semval +and, if +.B SEM_UNDO +is asserted for this operation, the system updates the process undo count +.RI ( semadj ) +for this semaphore. +.IP \(bu +The semaphore set is removed from the system: the system call fails with +.I errno +set to +.BR EIDRM . +.IP \(bu +The calling process catches a signal: +the value of +.I semncnt +is decremented and the system call fails with +.I errno +set to +.BR EINTR . +.IP \(bu +The time limit specified by +.I timeout +in a +.B semtimedop +call expires: the system call fails, with +.I errno +set to +.BR EAGAIN . +.PP +On successful completion, the +.I sempid +value for each semaphore specified in the array pointed to by +.I sops +is set to the process ID of the calling process. +In addition, the +.I sem_otime +.\" and +.\" .I sem_ctime +is set to the current time. +.PP +The function +.B semtimedop +behaves identically to the function +.B semop +except that in those cases were the calling process would sleep, +the duration of that sleep is limited by the amount of elapsed +time specified by the +.B timespec +structure whose address is passed in the +.I timeout +parameter. If the specified time limit has been reached, +the system call fails with +.I errno +set to +.B EAGAIN +(and none of the operations in +.I sops +is performed). +If the +.I timeout +parameter is +.BR NULL , +then +.B semtimedop +behaves exactly like +.BR semop . +.SH "RETURN VALUE" +If successful the system call returns +.BR 0 , +otherwise it returns +.B \-1 +with +.I errno +indicating the error. +.SH ERRORS +On failure, +.I errno +is set to one of the following: +.TP +.B E2BIG +The argument +.I nsops +is greater than +.BR SEMOPM , +the maximum number of operations allowed per system +call. +.TP +.B EACCES +The calling process does not have the permissions required +to perform the specified semaphore operations, +and does not have the +.B CAP_IPC_OWNER +capability. +.TP +.B EAGAIN +An operation could not proceed immediately and either +.BR IPC_NOWAIT +was asserted in its +.I sem_flg +or the time limit specified in +.I timeout +expired. +.TP +.B EFAULT +An address specified in either the +.I sops +or +.I timeout +parameters isn't accessible. +.TP +.B EFBIG +For some operation the value of +.I sem_num +is less than 0 or greater than or equal to the number +of semaphores in the set. +.TP +.B EIDRM +The semaphore set was removed. +.TP +.B EINTR +While blocked in this system call, the process caught a signal. +.TP +.B EINVAL +The semaphore set doesn't exist, or +.I semid +is less than zero, or +.I nsops +has a non-positive value. +.TP +.B ENOMEM +The +.I sem_flg +of some operation asserted +.B SEM_UNDO +and the system does not have enough memory to allocate the undo +structure. +.TP +.B ERANGE +For some operation +.I sem_op+semval +is greater than +.BR SEMVMX , +the implementation dependent maximum value for +.IR semval . +.SH NOTES +The +.I sem_undo +structures of a process aren't inherited across a +.BR fork (2) +system call, but they are inherited across a +.BR execve (2) +system call. +.PP +.B semop +is never automatically restarted after being interrupted by a signal handler, +regardless of the setting of the +.B SA_RESTART +flags when establishing a signal handler. +.PP +.I semadj +is a per\-process integer which is simply the (negative) count +of all semaphore operations performed specifying the +.B SEM_UNDO +flag. +When a semaphore's value is directly set using the +.B SETVAL +or +.B SETALL +request to +.BR semctl (2), +the corresponding +.I semadj +values in all processes are cleared. +.PP +The \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, and \fIsemnct\fP values +for a semaphore can all be retrieved using appropriate +.BR semctl (2) +calls. +.PP +The followings are limits on semaphore set resources affecting a +.B semop +call: +.TP +.B SEMOPM +Maximum number of operations allowed for one +.B semop +call (32). +.TP +.B SEMVMX +Maximum allowable value for +.IR semval : +implementation dependent (32767). +.PP +The implementation has no intrinsic limits for +the adjust on exit maximum value +.RB ( SEMAEM ), +the system wide maximum number of undo structures +.RB ( SEMMNU ) +and the per\-process maximum number of undo entries system parameters. +.SH BUGS +When a process terminates, its set of associated +.I semadj +structures is used to undo the effect of all of the +semaphore operations it performed with the +.B SEM_UNDO +flag. +This raises a difficulty: if one (or more) of these semaphore adjustments +would result in an attempt to decrease a semaphore's value below zero, +what should an implementation do? +One possible approach would be to block until all the semaphore +adjustments could be performed. +This is however undesirable since it could force process termination to +block for arbitrarily long periods. +Another possibility is that such semaphore adjustments could be ignored +altogether (somewhat analogously to failing when +.B IPC_NOWAIT +is specified for a semaphore operation). +Linux adopts a third approach: decreasing the semaphore value +as far as possible (i.e., to zero) and allowing process +termination to proceed immediately. +.SH "CONFORMING TO" +SVr4, SVID. SVr4 documents additional error conditions EINVAL, EFBIG, +ENOSPC. +.SH "SEE ALSO" +.BR semctl (2), +.BR semget (2), +.BR sigaction (2), +.BR ipc (5), +.BR capabilities (7) diff --git a/man2/semtimedop.2 b/man2/semtimedop.2 new file mode 100644 index 000000000..8a4061874 --- /dev/null +++ b/man2/semtimedop.2 @@ -0,0 +1 @@ +.so man2/semop.2 diff --git a/man2/send.2 b/man2/send.2 new file mode 100644 index 000000000..dc8ee0e08 --- /dev/null +++ b/man2/send.2 @@ -0,0 +1,363 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified Oct 1998 by Andi Kleen +.\" Modified Oct 2003 by aeb +.\" Modified 2004-07-01 by mtk +.\" +.TH SEND 2 2004-07-01 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +send, sendto, sendmsg \- send a message from a socket +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "ssize_t send(int " s ", const void *" buf ", size_t " len , +.BI "int " flags ); +.br +.BI "ssize_t sendto(int " s ", const void *" buf ", size_t " len , +.BI "int " flags ", const struct sockaddr *" to ", socklen_t " tolen ); +.br +.BI "ssize_t sendmsg(int " s ", const struct msghdr *" msg , +.BI "int " flags ); +.SH DESCRIPTION +The system calls +.BR send , +.BR sendto , +and +.B sendmsg +are used to transmit a message to another socket. +.PP +The +.B send +call may be used only when the socket is in a +.I connected +state (so that the intended recipient is known). +The only difference between +.B send +and +.B write +is the presence of +.IR flags . +With zero +.I flags +parameter, +.B send +is equivalent to +.BR write . +Also, +.RI send( s , buf , len ) +is equivalent to +.RI sendto( s , buf , len ,NULL,0). +.PP +The parameter +.I s +is the file descriptor of the sending socket. +.PP +If +.B sendto +is used on a connection-mode (SOCK_STREAM, SOCK_SEQPACKET) socket, +the parameters +.I to +and +.I tolen +are ignored (and the error EISCONN may be returned when they are +not NULL and 0), and the error ENOTCONN is returned when the socket was +not actually connected. Otherwise, the address of the target is given by +.I to +with +.I tolen +specifying its size. +For +.BR sendmsg , +the address of the target is given by +.IR msg.msg_name , +with +.I msg.msg_namelen +specifying its size. +.PP +For +.B send +and +.BR sendto , +the message is found in +.I buf +and has length +.IR len . +For +.BR sendmsg , +the message is pointed to by the elements of the array +.IR msg.msg_iov . +The +.B sendmsg +call also allows sending ancillary data (also known as control information). +.PP +If the message is too long to pass atomically through the +underlying protocol, the error +.B EMSGSIZE +is returned, and the message is not transmitted. +.PP +No indication of failure to deliver is implicit in a +.BR send . +Locally detected errors are indicated by a return value of \-1. +.PP +When the message does not fit into the send buffer of the socket, +.B send +normally blocks, unless the socket has been placed in non-blocking I/O +mode. In non-blocking mode it would return +.B EAGAIN +in this case. +The +.BR select (2) +call may be used to determine when it is possible to send more data. +.PP +The +.I flags +parameter is the bitwise OR +of zero or more of the following flags. +.\" XXX document MSG_PROXY +.TP +.B MSG_OOB +Sends +.I out-of-band +data on sockets that support this notion (e.g. of type +.BR SOCK_STREAM ); +the underlying protocol must also support +.I out-of-band +data. +.TP +.B MSG_EOR +Terminates a record (when this notion is supported, as for sockets of type +.BR SOCK_SEQPACKET ). +.TP +.B MSG_DONTROUTE +Don't use a gateway to send out the packet, only send to hosts on +directly connected networks. This is usually used only +by diagnostic or routing programs. This is only defined for protocol +families that route; packet sockets don't. +.TP +.B MSG_DONTWAIT +Enables non-blocking operation; if the operation would block, +.B EAGAIN +is returned (this can also be enabled using the +.B O_NONBLOCK +with the +.B F_SETFL +.BR fcntl (2)). +.TP +.B MSG_NOSIGNAL +Requests not to send +.B SIGPIPE +on errors on stream oriented sockets when the other end breaks the +connection. The +.B EPIPE +error is still returned. +.TP +.BR MSG_CONFIRM " (Linux 2.3+ only)" +Tell the link layer that forward progress happened: you got a successful +reply from the other side. If the link layer doesn't get this +it'll regularly reprobe the neighbour (e.g. via a unicast ARP). +Only valid on +.B SOCK_DGRAM +and +.B SOCK_RAW +sockets and currently only implemented for IPv4 and IPv6. See +.BR arp (7) +for details. +.TP +.BR MSG_MORE " (Since Linux 2.4.4)" +The caller has more data to send. +This flag is used with TCP sockets to obtain the same effect +as the TCP_CORK socket option (see +.BR tcp (7)), +with the difference that this flag can be set on a per-call basis. +Since Linux 2.6, this flag is also supported for UDP sockets, and informs +the kernel to package all of the data sent in calls with this flag set +into a single datagram which is only transmitted when a call is performed +that does not specify this flag. +.PP +The definition of the +.I msghdr +structure follows. See +.BR recv (2) +and below for an exact description of its fields. +.IP +.RS +.nf +.ta 4n 17n 33n +struct msghdr { + void * msg_name; /* optional address */ + socklen_t msg_namelen; /* size of address */ + struct iovec * msg_iov; /* scatter/gather array */ + size_t msg_iovlen; /* # elements in msg_iov */ + void * msg_control; /* ancillary data, see below */ + socklen_t msg_controllen; /* ancillary data buffer len */ + int msg_flags; /* flags on received message */ +}; +.ta +.fi +.RE +.PP +You may send control information using the +.I msg_control +and +.I msg_controllen +members. The maximum control buffer length the kernel can process is limited +per socket by the +.B net.core.optmem_max +sysctl; see +.BR socket (7). +.\" Still to be documented: +.\" Send file descriptors and user credentials using the +.\" msg_control* fields. +.\" The flags returned in msg_flags. +.SH "RETURN VALUE" +The calls return the number of characters sent, or \-1 +if an error occurred. +.SH ERRORS +These are some standard errors generated by the socket layer. Additional errors +may be generated and returned from the underlying protocol modules; see their +respective manual pages. +.TP +.B EACCES +(For Unix domain sockets, which are identified by pathname) +Write permission is denied on the destination socket file, +or search permission is denied for one of the directories +the path prefix. (See +.BR path_resolution (2).) +.TP +.BR EAGAIN " or " EWOULDBLOCK +The socket is marked non-blocking and the requested operation +would block. +.TP +.B EBADF +An invalid descriptor was specified. +.TP +.B ECONNRESET +Connection reset by peer. +.TP +.B EDESTADDRREQ +The socket is not connection-mode, and no peer address is set. +.TP +.B EFAULT +An invalid user space address was specified for a parameter. +.TP +.B EINTR +A signal occurred before any data was transmitted. +.TP +.B EINVAL +Invalid argument passed. +.TP +.B EISCONN +The connection-mode socket was connected already but a +recipient was specified. +(Now either this error is returned, or the recipient specification +is ignored.) +.TP +.B EMSGSIZE +The socket type +.\" (e.g., SOCK_DGRAM ) +requires that message be sent atomically, and the size +of the message to be sent made this impossible. +.TP +.B ENOBUFS +The output queue for a network interface was full. +This generally indicates that the interface has stopped sending, +but may be caused by transient congestion. +(Normally, this does not occur in Linux. Packets are just silently dropped +when a device queue overflows.) +.TP +.B ENOMEM +No memory available. +.TP +.B ENOTCONN +The socket is not connected, and no target has been given. +.TP +.B ENOTSOCK +The argument +.I s +is not a socket. +.TP +.B EOPNOTSUPP +Some bit in the +.I flags +argument is inappropriate for the socket type. +.TP +.B EPIPE +The local end has been shut down on a connection oriented socket. +In this case the process +will also receive a +.B SIGPIPE +unless +.B MSG_NOSIGNAL +is set. +.SH "CONFORMING TO" +4.4BSD, SVr4, POSIX 1003.1-2001. +These function calls appeared in 4.2BSD. +.LP +POSIX only describes the +.B MSG_OOB +and +.B MSG_EOR +flags. +The +.B MSG_CONFIRM +flag is a Linux extension. +.SH NOTE +The prototypes given above follow the Single Unix Specification, +as glibc2 also does; the +.I flags +argument was `int' in BSD 4.*, but `unsigned int' in libc4 and libc5; +the +.I len +argument was `int' in BSD 4.* and libc4, but `size_t' in libc5; +the +.I tolen +argument was `int' in BSD 4.* and libc4 and libc5. +See also +.BR accept (2). +.SH BUGS +Linux may return EPIPE instead of ENOTCONN. +.SH "SEE ALSO" +.BR fcntl (2), +.BR getsockopt (2), +.BR recv (2), +.BR select (2), +.BR sendfile (2), +.BR socket (2), +.BR write (2), +.BR ip (7), +.BR socket (7), +.BR tcp (7), +.BR udp (7) diff --git a/man2/sendfile.2 b/man2/sendfile.2 new file mode 100644 index 000000000..40ef77b88 --- /dev/null +++ b/man2/sendfile.2 @@ -0,0 +1,117 @@ +.\" This man page is Copyright (C) 1998 Pawel Krawczyk. +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" $Id: sendfile.2,v 1.5 1999/05/18 11:54:11 freitag Exp $ +.\" 2000-11-19 bert hubert : in_fd cannot be socket +.TH SENDFILE 2 1998-12-01 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +sendfile \- transfer data between file descriptors +.SH SYNOPSIS +.B #include +.sp +.BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" offset ", size_t" " count" ); +.\" The below is too ugly. Comments about glibc versions belong +.\" in the notes, not in the header. +.\" +.\" .B #include +.\" .br +.\" .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2 +.\" .br +.\" .B #include +.\" .br +.\" #else +.\" .br +.\" .B #include +.\" .br +.\" .B /* No system prototype before glibc 2.1. */ +.\" .br +.\" .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" offset ", size_t" " count" ) +.\" .br +.\" .B #endif +.\" +.SH DESCRIPTION +This call copies data between one file descriptor and another. +Either or both of these file descriptors may refer to a socket (but see below). +.I in_fd +should be a file descriptor opened for reading and +.I out_fd +should be a descriptor opened for writing. +.I offset +is a pointer to a variable holding the input file pointer position from +which +.BR sendfile () +will start reading data. When +.BR sendfile () +returns, this variable +will be set to the offset of the byte following the last byte that was read. +.I count +is the number of bytes to copy between file descriptors. + +Because this copying is done within the kernel, +.BR sendfile () +does not need to spend time transferring data +to and from user space. + +.SH NOTES +Sendfile does not modify the current file pointer of +.IR in_fd , +but does for +.IR out_fd . + +If you plan to use sendfile for sending files to a TCP socket, but need +to send some header data in front of the file contents, please see +the +.B TCP_CORK +option in +.BR tcp (7) +to minimize the number of packets and to tune performance. + +Presently the descriptor from which data is read cannot +correspond to a socket, it must correspond to a file +which supports mmap()-like operations. + +.SH "RETURN VALUE" +If the transfer was successful, the number of bytes written to +.I out_fd +is returned. On error, \-1 is returned, and +.I errno +is set appropriately. + +.SH ERRORS +.TP +.B EAGAIN +Non-blocking I/O has been selected using +.B O_NONBLOCK +and the write would block. +.TP +.B EBADF +The input file was not opened for reading or the output file +was not opened for writing. +.TP +.B EFAULT +Bad address. +.TP +.B EINVAL +Descriptor is not valid or locked. +.TP +.B EIO +Unspecified error while reading from +.IR in_fd . +.TP +.B ENOMEM +Insufficient memory to read from +.IR in_fd . +.SH VERSIONS +.B sendfile +is a new feature in Linux 2.2. +The include file is present since glibc2.1. + +Other Unixes often implement +.B sendfile +with different semantics and prototypes. It should +not be used in portable programs. +.SH "SEE ALSO" +.BR open (2), +.BR socket (2) diff --git a/man2/sendmsg.2 b/man2/sendmsg.2 new file mode 100644 index 000000000..9a61b33bb --- /dev/null +++ b/man2/sendmsg.2 @@ -0,0 +1 @@ +.so man2/send.2 diff --git a/man2/sendto.2 b/man2/sendto.2 new file mode 100644 index 000000000..9a61b33bb --- /dev/null +++ b/man2/sendto.2 @@ -0,0 +1 @@ +.so man2/send.2 diff --git a/man2/set_thread_area.2 b/man2/set_thread_area.2 new file mode 100644 index 000000000..8e551c6b0 --- /dev/null +++ b/man2/set_thread_area.2 @@ -0,0 +1,67 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" This file is distributed according to the GNU General Public License. +.\" See the file COPYING in the top level source directory for details. +.\" +.\" Author: Kent Yoder +.\" +.TH "SET_THREAD_AREA" 2 "2003-02-21" "Linux 2.5.29" "Linux Programmer's Manual" +.SH NAME +set_thread_area \- Set a Thread Local Storage (TLS) area +.SH "SYNOPSIS" +.B #include +.br +.B #include +.sp +.BI "int set_thread_area (struct user_desc *" u_info ); +.SH "DESCRIPTION" +.B set_thread_area +sets an entry in the current thread's Thread Local Storage (TLS) array. +The TLS array entry set by +.B set_thread_area +corresponds to the value of +.I u_info->entry_number +passed in by the user. If this value is in bounds, +.B set_thread_area +copies the TLS descriptor pointed to by +.I u_info +into the thread's TLS array. +.PP +When +.B set_thread_area +is passed an +.I entry_number +of \-1, it uses a free TLS entry. If +.B set_thread_area +finds a free TLS entry, the value of +.I u_info->entry_number +is set upon return to show which entry was changed. + +.SH "RETURN VALUE" +.B set_thread_area +returns 0 on success, and \-1 on failure, with +.I errno +set appropriately. + +.SH "ERRORS" +.TP +.B EINVAL +\fIu_info->\fR\fIentry_number\fR is out of bounds. +.TP +.B EFAULT +\fIu_info\fR is an invalid pointer. +.TP +.B ESRCH +A free TLS entry could not be located. + +.SH "CONFORMING TO" +.B set_thread_area +is Linux specific and should not be used in programs that are intended +to be portable. + +.SH "VERSIONS" +A version of +.B set_thread_area +first appeared in Linux 2.5.29. + +.SH "SEE ALSO" +.BR get_thread_area (2). diff --git a/man2/set_tid_address.2 b/man2/set_tid_address.2 new file mode 100644 index 000000000..64620b351 --- /dev/null +++ b/man2/set_tid_address.2 @@ -0,0 +1,88 @@ +.\" Copyright (C) 2004 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH SET_TID_ADDRESS 2 2004-09-10 "Linux 2.6" "Linux Programmer's Manual" +.SH NAME +set_tid_address \- set pointer to thread ID +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "long set_tid_address(int *" tidptr ); +.SH DESCRIPTION +The kernel keeps for each process two values called +.I set_child_tid +and +.I clear_child_tid +that are NULL by default. + +.SS set_child_tid +If a process is started using +.BR clone (2) +with the +.B CLONE_CHILD_SETTID +flag, +.I set_child_tid +is set to +.IR child_tidptr , +the fifth parameter of that system call. +.LP +When +.I set_child_tid +is set, the very first thing the new process does +is writing its PID at this address. + +.SS clear_child_tid +If a process is started using +.BR clone (2) +with the +.B CLONE_CHILD_CLEARTID +flag, +.I clear_child_tid +is set to +.IR child_tidptr , +the fifth parameter of that system call. +.LP +The system call +.B set_tid_address +sets the +.I clear_child_tid +value for the calling process to +.IR tidptr . +.LP +When +.I clear_child_tid +is set, and the process exits, and the process was sharing memory +with other processes or threads, then 0 is written at this address, +and a +.I futex(child_tidptr, FUTEX_WAKE, 1, NULL, NULL, 0); +call is done. (That is, wake a single process waiting on this futex.) +Errors are ignored. +.SH "RETURN VALUE" +.B set_tid_address +returns the PID of the current process. +.SH HISTORY +This call is present since Linux 2.5.48. +Details as given here are valid since Linux 2.5.49. +.SH "SEE ALSO" +.BR clone (2), +.BR futex (2) diff --git a/man2/setcontext.2 b/man2/setcontext.2 new file mode 100644 index 000000000..8bf0b0cef --- /dev/null +++ b/man2/setcontext.2 @@ -0,0 +1 @@ +.so man2/getcontext.2 diff --git a/man2/setdomainname.2 b/man2/setdomainname.2 new file mode 100644 index 000000000..1c1594cbe --- /dev/null +++ b/man2/setdomainname.2 @@ -0,0 +1 @@ +.so man2/getdomainname.2 diff --git a/man2/setegid.2 b/man2/setegid.2 new file mode 100644 index 000000000..85032b503 --- /dev/null +++ b/man2/setegid.2 @@ -0,0 +1 @@ +.so man2/seteuid.2 diff --git a/man2/seteuid.2 b/man2/seteuid.2 new file mode 100644 index 000000000..177e25535 --- /dev/null +++ b/man2/seteuid.2 @@ -0,0 +1,96 @@ +.\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" [should really be seteuid.3] +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH SETEGID 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +seteuid, setegid \- set effective user or group ID +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int seteuid(uid_t " euid ); +.br +.BI "int setegid(gid_t " egid ); +.SH DESCRIPTION +.B seteuid +sets the effective user ID of the current process. +Unprivileged user processes may only set the effective user ID to the +real user ID, the effective user ID or the saved user ID. + +Precisely the same holds for +.B setegid +with "group" instead of "user". + +.\" When +.\" .I euid +.\" equals \-1, nothing is changed. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.\" .TP +.\" .B EINVAL +.TP +.B EPERM +The current process is not privileged (Linux: does not have the +.B CAP_SETUID +capability in the case of +.BR seteuid (), +or the +.B CAP_SETGID +capability in the case of +.BR setegid ()) +and +.I euid +(resp. +.IR egid ) +is not the real user (group) ID, the effective user (group) ID +or the saved user (group) ID. +.SH NOTES +Setting the effective user (group) ID to the saved user (group) ID is +possible since Linux 1.1.37 (1.1.38). +On an arbitrary system one should check _POSIX_SAVED_IDS. +.LP +Under libc4, libc5 and glibc2.0 +.BI seteuid( euid ) +is equivalent to +.BI setreuid(-1, " euid" ) +and hence may change the saved user ID. +Under glibc2.1 it is equivalent to +.BI setresuid(-1, " euid" ,-1) +and hence does not change the saved user ID. +Similar remarks hold for +.BR setegid . +.SH "CONFORMING TO" +BSD 4.3 +.SH "SEE ALSO" +.BR geteuid (2), +.BR setresuid (2), +.BR setreuid (2), +.BR setuid (2), +.BR capabilities (7) diff --git a/man2/setfsgid.2 b/man2/setfsgid.2 new file mode 100644 index 000000000..244bc6350 --- /dev/null +++ b/man2/setfsgid.2 @@ -0,0 +1,92 @@ +.\" Copyright (C) 1995, Thomas K. Dyas +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Created 1995-08-06 Thomas K. Dyas +.\" Modified 2000-07-01 aeb +.\" Modified 2002-07-23 aeb +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH SETFSGID 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +setfsgid \- set group identity used for file system checks +.SH SYNOPSIS +.B #include +/* glibc uses */ +.sp +.BI "int setfsgid(uid_t " fsgid ); +.SH DESCRIPTION +The system call +.B setfsgid +sets the group ID that the Linux kernel uses to check for all accesses +to the file system. Normally, the value of +.I fsgid +will shadow the value of the effective group ID. In fact, whenever the +effective group ID is changed, +.I fsgid +will also be changed to the new value of the effective group ID. + +Explicit calls to +.B setfsuid +and +.B setfsgid +are usually only used by programs such as the Linux NFS server that +need to change what user and group ID is used for file access without a +corresponding change in the real and effective user and group IDs. +A change in the normal user IDs for a program such as the NFS server +is a security hole that can expose it to unwanted signals. (But see below.) + +.B setfsgid +will only succeed if the caller is the superuser or if +.I fsgid +matches either the real group ID, effective group ID, +saved set-group-ID, or the current value of +.IR fsgid . +.SH "RETURN VALUE" +On success, the previous value of +.I fsgid +is returned. On error, the current value of +.I fsgid +is returned. +.SH "CONFORMING TO" +.B setfsgid +is Linux specific and should not be used in programs intended to be portable. +It is present since Linux 1.1.44 and in libc since libc 4.7.6. +.SH BUGS +No error messages of any kind are returned to the caller. At the very +least, +.B EPERM +should be returned when the call fails (because the caller lacks the +.B CAP_SETGID +capability). +.SH NOTES +When glibc determines that the argument is not a valid group ID, +it will return \-1 and set \fIerrno\fP to EINVAL without attempting +the system call. +.LP +Note that at the time this system call was introduced, a process +could send a signal to a process with the same effective user ID. +Today signal permission handling is slightly different. +.SH "SEE ALSO" +.BR kill (2), +.BR setfsuid (2), +.BR capabilities (7) diff --git a/man2/setfsuid.2 b/man2/setfsuid.2 new file mode 100644 index 000000000..fdc4666ce --- /dev/null +++ b/man2/setfsuid.2 @@ -0,0 +1,92 @@ +.\" Copyright (C) 1995, Thomas K. Dyas +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Created 1995-08-06 Thomas K. Dyas +.\" Modified 2000-07-01 aeb +.\" Modified 2002-07-23 aeb +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH SETFSUID 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +setfsuid \- set user identity used for file system checks +.SH SYNOPSIS +.B #include +/* glibc uses */ +.sp +.BI "int setfsuid(uid_t " fsuid ); +.SH DESCRIPTION +The system call +.B setfsuid +sets the user ID that the Linux kernel uses to check for all accesses +to the file system. Normally, the value of +.I fsuid +will shadow the value of the effective user ID. In fact, whenever the +effective user ID is changed, +.I fsuid +will also be changed to the new value of the effective user ID. + +Explicit calls to +.B setfsuid +and +.B setfsgid +are usually only used by programs such as the Linux NFS server that +need to change what user and group ID is used for file access without a +corresponding change in the real and effective user and group IDs. +A change in the normal user IDs for a program such as the NFS server +is a security hole that can expose it to unwanted signals. (But see below.) + +.B setfsuid +will only succeed if the caller is the superuser or if +.I fsuid +matches either the real user ID, effective user ID, saved set-user-ID, or +the current value of +.IR fsuid . +.SH "RETURN VALUE" +On success, the previous value of +.I fsuid +is returned. On error, the current value of +.I fsuid +is returned. +.SH "CONFORMING TO" +.B setfsuid +is Linux specific and should not be used in programs intended to be portable. +It is present since Linux 1.1.44 and in libc since libc 4.7.6. +.SH BUGS +No error messages of any kind are returned to the caller. At the very +least, +.B EPERM +should be returned when the call fails (because the caller lacks the +.B CAP_SETUID +capability). +.SH NOTES +When glibc determines that the argument is not a valid user ID, +it will return \-1 and set \fIerrno\fP to EINVAL without attempting +the system call. +.LP +Note that at the time this system call was introduced, a process +could send a signal to a process with the same effective user ID. +Today signal permission handling is slightly different. +.SH "SEE ALSO" +.BR kill (2), +.BR setfsgid (2), +.BR capabilities (7) diff --git a/man2/setgid.2 b/man2/setgid.2 new file mode 100644 index 000000000..a2cdcad8f --- /dev/null +++ b/man2/setgid.2 @@ -0,0 +1,64 @@ +.\" Copyright (C), 1994, Graeme W. Wilford. (Wilf.) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Fri Jul 29th 12:56:44 BST 1994 Wilf. +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2002-03-09 by aeb +.\" +.TH SETGID 2 2002-03-09 "Linux 2.5" "Linux Programmer's Manual" +.SH NAME +setgid \- set group identity +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int setgid(gid_t " gid ); +.SH DESCRIPTION +.B setgid +sets the effective group ID of the current process. If the caller is the +superuser, the real and saved group ID's are also set. + +Under Linux, +.B setgid +is implemented like the POSIX version with the _POSIX_SAVED_IDS feature. +This allows a setgid program that is not suid root to drop all of its group +privileges, do some un-privileged work, and then re-engage the original +effective group ID in a secure manner. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EPERM +The user is not the super-user (does not have the CAP_SETGID capability), and +.I gid +does not match the effective group ID or saved set-group-ID of +the calling process. +.SH "CONFORMING TO" +SVr4, SVID. +.SH "SEE ALSO" +.BR getgid (2), +.BR setegid (2), +.BR setregid (2), +.BR capabilities (7) diff --git a/man2/setgroups.2 b/man2/setgroups.2 new file mode 100644 index 000000000..0ae4cc0b1 --- /dev/null +++ b/man2/setgroups.2 @@ -0,0 +1 @@ +.so man2/getgroups.2 diff --git a/man2/sethostid.2 b/man2/sethostid.2 new file mode 100644 index 000000000..21378d76f --- /dev/null +++ b/man2/sethostid.2 @@ -0,0 +1 @@ +.so man2/gethostid.2 diff --git a/man2/sethostname.2 b/man2/sethostname.2 new file mode 100644 index 000000000..e1fa2a617 --- /dev/null +++ b/man2/sethostname.2 @@ -0,0 +1 @@ +.so man2/gethostname.2 diff --git a/man2/setitimer.2 b/man2/setitimer.2 new file mode 100644 index 000000000..9518567e0 --- /dev/null +++ b/man2/setitimer.2 @@ -0,0 +1 @@ +.so man2/getitimer.2 diff --git a/man2/setpgid.2 b/man2/setpgid.2 new file mode 100644 index 000000000..2567ee2a1 --- /dev/null +++ b/man2/setpgid.2 @@ -0,0 +1,190 @@ +.\" Copyright (c) 1983, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getpgrp.2 6.4 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-04-15 by Michael Chastain : +.\" Added 'getpgid'. +.\" Modified 1996-07-21 by Andries Brouwer +.\" Modified 1996-11-06 by Eric S. Raymond +.\" Modified 1999-09-02 by Michael Haardt +.\" Modified 2002-01-18 by Michael Kerrisk +.\" Modified 2003-01-20 by Andries Brouwer +.\" +.TH SETPGID 2 2003-01-20 "Linux" "Linux Programmer's Manual" +.SH NAME +setpgid, getpgid, setpgrp, getpgrp \- set/get process group +.SH SYNOPSIS +.B #include +.sp +.BI "int setpgid(pid_t " pid ", pid_t " pgid ); +.br +.BI "pid_t getpgid(pid_t " pid ); +.br +.B int setpgrp(void); +.br +.B pid_t getpgrp(void); +.SH DESCRIPTION +.B setpgid +sets the process group ID of the process specified by +.I pid +to +.IR pgid . +If +.I pid +is zero, the process ID of the current process is used. If +.I pgid +is zero, the process ID of the process specified by +.I pid +is used. If \fBsetpgid\fP is used to move a process from one process +group to another (as is done by some shells when creating pipelines), +both process groups must be part of the same session. In this case, +the \fIpgid\fP specifies an existing process group to be joined and the +session ID of that group must match the session ID of the joining process. + +.B getpgid +returns the process group ID of the process specified by +.IR pid . +If +.I pid +is zero, the process ID of the current process is used. + +The call +.B setpgrp() +is equivalent to +.BR setpgid(0,0) . + +Similarly, +.B getpgrp() +is equivalent to +.BR getpgid(0) . +Each process group is a member of a session and each process is a +member of the session of which its process group is a member. + +Process groups are used for distribution of signals, and by terminals to +arbitrate requests for their input: Processes that have the same process +group as the terminal are foreground and may read, while others will +block with a signal if they attempt to read. +These calls are thus used by programs such as +.BR csh (1) +to create process groups in implementing job control. The +.B TIOCGPGRP +and +.B TIOCSPGRP +calls described in +.BR termios (3) +are used to get/set the process group of the control terminal. + +If a session has a controlling terminal, CLOCAL is not set and a hangup +occurs, then the session leader is sent a SIGHUP. If the session leader +exits, the SIGHUP signal will be sent to each process in the foreground +process group of the controlling terminal. + +If the exit of the process causes a process group to become orphaned, +and if any member of the newly-orphaned process group is stopped, then a +SIGHUP signal followed by a SIGCONT signal will be sent to each process +in the newly-orphaned process group. + +.SH "RETURN VALUE" +On success, +.BR setpgid " and " setpgrp +return zero. On error, \-1 is returned, and +.I errno +is set appropriately. + +.B getpgid +returns a process group on success. +On error, \-1 is returned, and +.I errno +is set appropriately. + +.B getpgrp +always returns the current process group. +.SH ERRORS +.TP +.B EACCES +An attempt was made to change the process group ID +of one of the children of the calling process and the child had +already performed an \fBexecve\fP +(\fBsetpgid\fP, \fBsetpgrp\fP). +.TP +.B EINVAL +.I pgid +is less than 0 +(\fBsetpgid\fP, \fBsetpgrp\fP). +.TP +.B EPERM +An attempt was made to move a process into a process group in a +different session, or to change the process +group ID of one of the children of the calling process and the +child was in a different session, or to change the process group ID of +a session leader +(\fBsetpgid\fP, \fBsetpgrp\fP). +.TP +.B ESRCH +For +.BR getpgid : +.I pid +does not match any process. +For +.BR setpgid : +.I pid +is not the current process and not a child of the current process. +.SH "CONFORMING TO" +The functions +.B setpgid +and +.B getpgrp +conform to POSIX.1. +The function +.B setpgrp +is from BSD 4.2. +The function +.B getpgid +conforms to SVr4. +.SH NOTES +POSIX took +.B setpgid +from the BSD function +.BR setpgrp . +Also SysV has a function with the same name, but it is identical to +.BR setsid (2). +.LP +To get the prototypes under glibc, define both _XOPEN_SOURCE and +_XOPEN_SOURCE_EXTENDED, or use "#define _XOPEN_SOURCE \fIn\fP" +for some integer \fIn\fP larger than or equal to 500. +.SH "SEE ALSO" +.BR getuid (2), +.BR setsid (2), +.BR tcgetpgrp (3), +.BR tcsetpgrp (3), +.BR termios (3) diff --git a/man2/setpgrp.2 b/man2/setpgrp.2 new file mode 100644 index 000000000..d6b107a1c --- /dev/null +++ b/man2/setpgrp.2 @@ -0,0 +1 @@ +.so man2/setpgid.2 diff --git a/man2/setpriority.2 b/man2/setpriority.2 new file mode 100644 index 000000000..b1dcfd91d --- /dev/null +++ b/man2/setpriority.2 @@ -0,0 +1 @@ +.so man2/getpriority.2 diff --git a/man2/setregid.2 b/man2/setregid.2 new file mode 100644 index 000000000..ec3ff6416 --- /dev/null +++ b/man2/setregid.2 @@ -0,0 +1 @@ +.so man2/setreuid.2 diff --git a/man2/setresgid.2 b/man2/setresgid.2 new file mode 100644 index 000000000..d6866a1de --- /dev/null +++ b/man2/setresgid.2 @@ -0,0 +1 @@ +.so man2/setresuid.2 diff --git a/man2/setresuid.2 b/man2/setresuid.2 new file mode 100644 index 000000000..443bc3266 --- /dev/null +++ b/man2/setresuid.2 @@ -0,0 +1,87 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified, 2003-05-26, Michael Kerrisk, +.TH SETRESUID 2 2003-05-26 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +setresuid, setresgid \- set real, effective and saved user or group ID +.SH SYNOPSIS +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "int setresuid(uid_t " ruid ", uid_t " euid ", uid_t " suid ); +.br +.BI "int setresgid(gid_t " rgid ", gid_t " egid ", gid_t " sgid ); +.SH DESCRIPTION +.B setresuid +sets the real user ID, the effective user ID, and the saved +(effective) user ID of the current process. + +Unprivileged user processes (i.e., processes with each of +real, effective and saved user ID nonzero) may change the real, +effective and saved user ID, each to one of: +the current uid, the current effective uid or the current saved uid. + +The super-user may set real, effective and saved user ID to arbitrary values. + +If one of the parameters equals \-1, the corresponding value is not changed. + +Completely analogously, +.B setresgid +sets the real, effective and saved group ID's of the current process, +with the same restrictions for processes with each of +real, effective and saved user ID nonzero. + +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EAGAIN +.I uid +does not match the current uid and this call would +bring that userID over its NPROC rlimit. +.TP +.B EPERM +The current process was not privileged (did not have the CAP_SETUID +capability) and tried to change the IDs is a not allowed way. +.SH "CONFORMING TO" +This call is nonstandard. +.SH HISTORY +This system call was first introduced in HP-UX. +It is available under Linux since Linux 2.1.44. +These days it is also found in FreeBSD (for emulation of Linux binaries). +.SH NOTES +Under HP-UX and FreeBSD the prototype is found in +.IR . +Under Linux the prototype is given by glibc since version 2.3.2 +provided _GNU_SOURCE is defined. +.SH "SEE ALSO" +.BR getresuid (2), +.BR getuid (2), +.BR setreuid (2), +.BR setuid (2), +.BR capabilities (7) diff --git a/man2/setreuid.2 b/man2/setreuid.2 new file mode 100644 index 000000000..2b17d2456 --- /dev/null +++ b/man2/setreuid.2 @@ -0,0 +1,117 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)setregid.2 6.4 (Berkeley) 3/10/91 +.\" +.\" Modified Sat Jul 24 09:08:49 1993 by Rik Faith +.\" Portions extracted from linux/kernel/sys.c: +.\" Copyright (C) 1991, 1992 Linus Torvalds +.\" May be distributed under the GNU General Public License +.\" Changes: 1994-07-29 by Wilf +.\" 1994-08-02 by Wilf due to change in kernel. +.\" 2004-07-04 by aeb +.\" 2004-05-27 by Michael Kerrisk +.\" +.TH SETREUID 2 2004-07-04 "Linux 2.6" "Linux Programmer's Manual" +.SH NAME +setreuid, setregid \- set real and/or effective user or group ID +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int setreuid(uid_t " ruid ", uid_t " euid ); +.br +.BI "int setregid(gid_t " rgid ", gid_t " egid ); +.SH DESCRIPTION +.B setreuid +sets real and effective user IDs of the current process. + +Supplying a value of \-1 for either the real or effective user ID forces +the system to leave that ID unchanged. + +Unprivileged processes may only set the effective user ID to the real user ID, +the effective user ID or the saved effective user ID. + +POSIX: It is unspecified whether unprivileged processes may set the +real user ID to the real user ID, the effective user ID or the saved +effective user ID. + +Linux: Unprivileged users may only set the real user ID to +the real user ID or the effective user ID. + +Linux: If the real user ID is set or the effective user ID is set to a value +not equal to the previous real user ID, the saved user ID will be set to the +new effective user ID. + +Completely analogously, +.B setregid +sets real and effective group ID's of the current process, +and all of the above holds with "group" instead of "user". + +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EPERM +The current process is not privileged +(Linux: does not have the +.B CAP_SETUID +capability in the case of +.BR setreuid (), +or the +.B CAP_SETGID +capability in the case of +.BR setregid ()) +and a change other than (i) +swapping the effective user (group) ID with the real user (group) ID, +or (ii) setting one to the value of the other or (iii) setting the +effective user (group) ID to the value of the saved user (group) ID +was specified. +.SH NOTES +Setting the effective user (group) ID to the saved user ID is +possible since Linux 1.1.37 (1.1.38). +.SH "CONFORMING TO" +BSD 4.3 (the +.B setreuid +and +.B setregid +function calls first appeared in 4.2BSD). +.SH "SEE ALSO" +.BR getgid (2), +.BR getuid (2), +.BR seteuid (2), +.BR setgid (2), +.BR setresuid (2), +.BR setuid (2), +.BR capabilities (7) diff --git a/man2/setrlimit.2 b/man2/setrlimit.2 new file mode 100644 index 000000000..df6d7362a --- /dev/null +++ b/man2/setrlimit.2 @@ -0,0 +1 @@ +.so man2/getrlimit.2 diff --git a/man2/setsid.2 b/man2/setsid.2 new file mode 100644 index 000000000..269032d72 --- /dev/null +++ b/man2/setsid.2 @@ -0,0 +1,63 @@ +.\" Copyright Michael Haardt (michael@cantor.informatik.rwth-aachen.de) Sat Aug 27 20:43:50 MET DST 1994 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sun Sep 11 19:19:05 1994 +.\" Modified Mon Mar 25 10:19:00 1996 (merged a few +.\" tiny changes from a man page by Charles Livingston). +.\" Modified Sun Jul 21 14:45:46 1996 +.\" +.TH SETSID 2 1994-08-27 "Linux 1.0.0" "Linux Programmer's Manual" +.SH NAME +setsid \- creates a session and sets the process group ID +.SH SYNOPSIS +.ad l +.B #include +.sp +.B pid_t setsid(void); +.br +.ad b +.SH DESCRIPTION +\fBsetsid()\fP creates a new session if the calling process is not a +process group leader. The calling process is the leader of the new +session, the process group leader of the new process group, and has no +controlling tty. The process group ID and session ID of the calling +process are set to the PID of the calling process. The calling process +will be the only process in this new process group and in this new session. +.SH "RETURN VALUE" +The session ID of the calling process. +.SH ERRORS +On error, \-1 will be returned. The only error which can happen is +EPERM. It is returned when the process group ID of any process +equals the PID of the calling process. Thus, in particular, +.B setsid +fails if the calling process is already a process group leader. +.SH NOTES +A process group leader is a process with process group ID equal +to its PID. In order to be sure that +.B setsid +will succeed, fork and exit, and have the child do +.BR setsid(). +.SH "CONFORMING TO" +POSIX, SVr4. +.SH "SEE ALSO" +.BR setpgid (2), +.BR setpgrp (2) diff --git a/man2/setsockopt.2 b/man2/setsockopt.2 new file mode 100644 index 000000000..d98c7769b --- /dev/null +++ b/man2/setsockopt.2 @@ -0,0 +1 @@ +.so man2/getsockopt.2 diff --git a/man2/settimeofday.2 b/man2/settimeofday.2 new file mode 100644 index 000000000..2b6eff428 --- /dev/null +++ b/man2/settimeofday.2 @@ -0,0 +1 @@ +.so man2/gettimeofday.2 diff --git a/man2/setuid.2 b/man2/setuid.2 new file mode 100644 index 000000000..31dece93f --- /dev/null +++ b/man2/setuid.2 @@ -0,0 +1,105 @@ +.\" Copyright (C), 1994, Graeme W. Wilford (Wilf). +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Fri Jul 29th 12:56:44 BST 1994 Wilf. +.\" Changes inspired by patch from Richard Kettlewell +.\" , aeb 970616. +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.TH SETUID 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +setuid \- set user identity +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int setuid(uid_t " uid ); +.SH DESCRIPTION +.B setuid +sets the effective user ID of the current process. +If the effective userid of the caller is root, +the real and saved user ID's are also set. +.PP +Under Linux, +.B setuid +is implemented like the POSIX version with the _POSIX_SAVED_IDS feature. +This allows a setuid (other than root) program to drop all of its user +privileges, do some un-privileged work, and then re-engage the original +effective user ID in a secure manner. +.PP +If the user is root or the program is setuid root, special care must be +taken. The +.B setuid +function checks the effective user ID of the caller and if it is the superuser, +all process related user ID's are set to +.IR uid . +After this has occurred, it is impossible for the program to regain root +privileges. +.PP +Thus, a setuid-root program wishing to temporarily drop root +privileges, assume the identity of a non-root user, and then regain +root privileges afterwards cannot use +.BR setuid . +You can accomplish this with the (non-POSIX, BSD) call +.BR seteuid . +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EAGAIN +The +.I uid +does not match the current uid and +.I uid +brings process over it's NPROC rlimit. +.TP +.B EPERM +The user is not privileged (Linux: does not have the +.B CAP_SETUID +capability) and +.I uid +does not match the real or saved user ID of the calling process. +.SH "CONFORMING TO" +SVr4, SVID, POSIX.1. Not quite compatible with the 4.4BSD call, which +sets all of the real, saved, and effective user IDs. SVr4 documents an +additional EINVAL error condition. +.SH "LINUX-SPECIFIC REMARKS" +Linux has the concept of filesystem user ID, normally equal to the +effective user ID. The +.B setuid +call also sets the filesystem user ID of the current process. +See +.BR setfsuid (2). +.PP +If +.I uid +is different from the old effective uid, the process will +be forbidden from leaving core dumps. +.SH "SEE ALSO" +.BR getuid (2), +.BR seteuid (2), +.BR setfsuid (2), +.BR setreuid (2), +.BR capabilities (7) diff --git a/man2/setup.2 b/man2/setup.2 new file mode 100644 index 000000000..12578ae46 --- /dev/null +++ b/man2/setup.2 @@ -0,0 +1,69 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified Sun Jul 25 10:14:13 1993 by Rik Faith +.\" Modified 15 April 1995 by Michael Chastain +.\" Update calling parameters to Linux 1.2.4 values. +.\" Modified 10 June 1995 by Andries Brouwer +.\" Modified 3 May 1996 by Martin Schulze +.\" Modified Wed Nov 6 04:05:28 1996 by Eric S. Raymond +.\" Modified Sat Jan 29 01:08:23 2000 by aeb +.\" +.TH SETUP 2 1996-05-03 "Linux 1.2.9" "Linux Programmer's Manual" +.SH NAME +setup \- setup devices and file systems, mount root file system +.SH SYNOPSIS +.B #include +.sp +.B _syscall0(int, setup); +.sp +.B int setup(void); +.SH DESCRIPTION +.B setup +is called once from within +.IR linux/init/main.c . +It calls initialization functions for devices and file systems +configured into the kernel and then mounts the root file system. +.PP +No user process may call +.BR setup . +Any user process, even a process with super-user permission, +will receive +.BR EPERM . +.SH "RETURN VALUE" +.B setup +always returns \-1 for a user process. +.SH ERRORS +.TP +.B EPERM +Always, for a user process. +.SH "CONFORMING TO" +This function is Linux specific, and should not be used in programs +intended to be portable, or indeed in any programs at all. +Since Linux 2.1.121, no such function exists anymore. +The calling sequence varied: it has had a single parameter +.I "void * BIOS" +and at other times a single parameter +.IR "int magic" . diff --git a/man2/setxattr.2 b/man2/setxattr.2 new file mode 100644 index 000000000..d86dfefe5 --- /dev/null +++ b/man2/setxattr.2 @@ -0,0 +1,143 @@ +.\" +.\" Extended attributes system calls manual pages +.\" +.\" (C) Andreas Gruenbacher, February 2001 +.\" (C) Silicon Graphics Inc, September 2001 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH SETXATTR 2 "Extended Attributes" "Dec 2001" "Linux Programmer's Manual" +.SH NAME +setxattr, lsetxattr, fsetxattr \- set an extended attribute value +.SH SYNOPSIS +.fam C +.nf +.B #include +.B #include +.sp +.BI "int setxattr (const char\ *" path ", const char\ *" name ", +.BI "\t\t\t const void\ *" value ", size_t " size ", int " flags ); +.BI "int lsetxattr (const char\ *" path ", const char\ *" name ", +.BI "\t\t\t const void\ *" value ", size_t " size ", int " flags ); +.BI "int fsetxattr (int " filedes ", const char\ *" name ", +.BI "\t\t\t const void\ *" value ", size_t " size ", int " flags ); +.fi +.fam T +.SH DESCRIPTION +Extended attributes are +.IR name :\c +.I value +pairs associated with inodes (files, directories, symlinks, etc). +They are extensions to the normal attributes which are associated +with all inodes in the system (i.e. the +.BR stat (2) +data). +A complete overview of extended attributes concepts can be found in +.BR attr (5). +.PP +.B setxattr +sets the +.I value +of the extended attribute identified by +.I name +and associated with the given +.I path +in the filesystem. +The +.I size +of the +.I value +must be specified. +.PP +.B lsetxattr +is identical to +.BR setxattr , +except in the case of a symbolic link, where the extended attribute is +set on the link itself, not the file that it refers to. +.PP +.B fsetxattr +is identical to +.BR setxattr , +only the extended attribute is set on the open file pointed to by +.I filedes +(as returned by +.BR open (2)) +in place of +.IR path . +.PP +An extended attribute name is a simple NULL-terminated string. +The +.I name +includes a namespace prefix \- there may be several, disjoint +namespaces associated with an individual inode. +The +.I value +of an extended attribute is a chunk of arbitrary textual or +binary data of specified length. +.PP +The +.I flags +parameter can be used to refine the semantics of the operation. +XATTR_CREATE specifies a pure create, which fails if the named +attribute exists already. +XATTR_REPLACE specifies a pure replace operation, which fails if the +named attribute does not already exist. +By default (no flags), the extended attribute will be created if +need be, or will simply replace the value if the attribute exists. +.SH RETURN VALUE +On success, zero is returned. +On failure, \-1 is returned and +.I errno +is set appropriately. +.PP +If XATTR_CREATE is specified, and the attribute exists already, +.I errno +is set to EEXIST. +If XATTR_REPLACE is specified, and the attribute does not exist, +.I errno +is set to ENOATTR. +.PP +If there is insufficient space remaining to store the extended attribute, +.I errno +is set to either ENOSPC, or EDQUOT if quota enforcement was the cause. +.PP +If extended attributes are not supported by the filesystem, or are disabled, +.I errno +is set to ENOTSUP. +.PP +The errors documented for the +.BR stat (2) +system call are also applicable here. +.SH AUTHORS +Andreas Gruenbacher, +.RI < a.gruenbacher@computer.org > +and the SGI XFS development team, +.RI < linux-xfs@oss.sgi.com >. +Please send any bug reports or comments to these addresses. +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR getxattr (2), +.BR listxattr (2), +.BR open (2), +.BR removexattr (2), +.BR stat (2), +.BR attr (5) diff --git a/man2/sgetmask.2 b/man2/sgetmask.2 new file mode 100644 index 000000000..b4b6ef50b --- /dev/null +++ b/man2/sgetmask.2 @@ -0,0 +1 @@ +.so man2/signal.2 diff --git a/man2/shmat.2 b/man2/shmat.2 new file mode 100644 index 000000000..3f3e5a4bd --- /dev/null +++ b/man2/shmat.2 @@ -0,0 +1 @@ +.so man2/shmop.2 diff --git a/man2/shmctl.2 b/man2/shmctl.2 new file mode 100644 index 000000000..c420b9878 --- /dev/null +++ b/man2/shmctl.2 @@ -0,0 +1,200 @@ +.\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993 +.\" Portions Copyright 1993 Giorgio Ciucci +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1993-07-28, Rik Faith +.\" Modified 1993-11-28, Giorgio Ciucci +.\" Modified 1997-01-31, Eric S. Raymond +.\" Modified 2001-02-18, Andries Brouwer +.\" Modified 2002-01-05, 2004-05-27, 2004-06-17, +.\" Michael Kerrisk +.\" Modified 2004-10-11, aeb +.\" +.TH SHMCTL 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +shmctl \- shared memory control +.SH SYNOPSIS +.ad l +.B #include +.sp +.B #include +.sp +.BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf ); +.ad b +.SH DESCRIPTION +\fBshmctl()\fP +allows the user to receive information on a shared memory segment, +set the owner, group, and permissions of a shared memory segment, +or destroy a segment. The information about the segment identified by +\fIshmid\fP is returned in a \fIshmid_ds\fP +structure: +.PP +.in +4n +.nf +struct shmid_ds { + struct ipc_perm shm_perm; /* operation perms */ + int shm_segsz; /* size of segment (bytes) */ + time_t shm_atime; /* last attach time */ + time_t shm_dtime; /* last detach time */ + time_t shm_ctime; /* last change time */ + unsigned short shm_cpid; /* pid of creator */ + unsigned short shm_lpid; /* pid of last operator */ + short shm_nattch; /* no. of current attaches */ + ... +}; +.fi +.in -4n +.PP +The highlighted fields in the member \fIshm_perm\fP can be set: +.PP +.in +4n +.nf +struct ipc_perm { + key_t key; + \fBushort uid\fP; /* \fBowner\fP euid and egid */ + \fBushort gid\fP; + ushort cuid; /* creator euid and egid */ + ushort cgid; + \fBushort mode\fP; /* lower 9 bits of access modes */ + ushort seq; /* sequence number */ +}; +.fi +.in -4n +.PP +The following \fIcmds\fP are available: +.br +.TP 12 +.B IPC_STAT +is used to copy the information about the shared memory segment into +the buffer \fIbuf\fP. The user must have \fBread\fP access to the +shared memory segment. +.TP +.B IPC_SET +is used to apply the changes the user has made to the \fIuid\fP, \fIgid\fP, +or \fImode\fP members of the \fIshm_perms\fP field. Only the lowest 9 bits +of \fImode\fP are used. The +.I shm_ctime +member is also updated. The user must be the owner or creator, or be +privileged. +.TP +.B IPC_RMID +is used to mark the segment as destroyed. It will actually be destroyed +after the last detach. (I.e., when the +.I shm_nattch +member of the associated structure +.I shmid_ds +is zero.) The user must be the owner or creator, or be privileged. +.PP +The user \fImust\fP ensure that a segment is eventually destroyed; otherwise +its pages that were faulted in will remain in memory or swap. +.SS "Linux additions" +A privileged user can prevent or allow swapping of a shared +memory segment with the following \fIcmds\fP: +.br +.TP 12 +.B SHM_LOCK +prevents swapping of a shared memory segment. The user must fault in +any pages that are required to be present after locking is enabled. +.TP +.B SHM_UNLOCK +allows the shared memory segment to be swapped out. +.PP +The +.BR IPC_INFO , +.BR SHM_STAT +and +.B SHM_INFO +control calls are used by the +.BR ipcs (8) +program to provide information on allocated resources. +.SH "RETURN VALUE" +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP 11 +.B EACCES +\fBIPC_STAT\fP or \fBSHM_STAT\fP is requested and +\fIshm_perm.modes\fP does not allow read access for +.IR shmid , +and the calling process does not have the +.BR CAP_IPC_OWNER +capability. +.TP +.B EFAULT +The argument +.I cmd +has value +.B IPC_SET +or +.B IPC_STAT +but the address pointed to by +.I buf +isn't accessible. +.TP +.B EIDRM +\fIshmid\fP points to a removed identifier. +.TP +.B EINVAL +\fIshmid\fP is not a valid identifier, or \fIcmd\fP +is not a valid command. +.TP +.B EOVERFLOW +\fBIPC_STAT\fP is attempted, and the gid or uid value +is too large to be stored in the structure pointed to by +.IR buf . +.TP +.B EPERM +\fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the +effective user ID of the calling process is not that of the creator +(found in +.IR shm_perm.cuid ), +or the owner +(found in +.IR shm_perm.uid ), +and the process was not privileged (Linux: did not have the +.B CAP_SYS_ADMIN +capability). + +Or, +.B SHM_LOCK +or +.B SHM_UNLOCK +was specified, but the process was not privileged +(Linux: did not have the +.B CAP_IPC_LOCK +capability). +.SH NOTE +Various fields in a \fIstruct shmid_ds\fP were shorts under Linux 2.2 +and have become longs under Linux 2.4. To take advantage of this, +a recompilation under glibc-2.1.91 or later should suffice. +(The kernel distinguishes old and new calls by an IPC_64 flag in +.IR cmd .) +.SH "CONFORMING TO" +SVr4, SVID. SVr4 documents additional error conditions EINVAL, +ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents +an EIDRM error condition. +.SH "SEE ALSO" +.BR shmget (2), +.BR shmop (2), +.BR capabilities (7) diff --git a/man2/shmdt.2 b/man2/shmdt.2 new file mode 100644 index 000000000..3f3e5a4bd --- /dev/null +++ b/man2/shmdt.2 @@ -0,0 +1 @@ +.so man2/shmop.2 diff --git a/man2/shmget.2 b/man2/shmget.2 new file mode 100644 index 000000000..b8cec39c2 --- /dev/null +++ b/man2/shmget.2 @@ -0,0 +1,276 @@ +.\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Wed Jul 28 10:57:35 1993, Rik Faith +.\" Modified Sun Nov 28 16:43:30 1993, Rik Faith +.\" with material from Giorgio Ciucci +.\" Portions Copyright 1993 Giorgio Ciucci +.\" Modified Tue Oct 22 22:03:17 1996 by Eric S. Raymond +.\" Modified, 8 Jan 2003, Michael Kerrisk, +.\" Removed EIDRM from errors - that can't happen... +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH SHMGET 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +shmget \- allocates a shared memory segment +.SH SYNOPSIS +.ad l +.B #include +.sp +.B #include +.sp +.BI "int shmget(key_t " key ", int " size ", int " shmflg ); +.ad b +.SH DESCRIPTION +.B shmget() +returns the identifier of the shared memory segment +associated with the value of the argument +.IR key . +A new shared memory segment, with size equal to the value of +.I size +rounded up to a multiple of +.BR PAGE_SIZE , +is created if +.I key +has the value +.B IPC_PRIVATE +or +.I key +isn't +.BR IPC_PRIVATE , +no shared memory segment corresponding to +.IR key +exists, and +.B IPC_CREAT +is asserted in +.I shmflg +(i.e. +.IB shmflg &IPC_CREAT +isn't zero). +.PP +The value +.I shmflg +is composed of: +.TP 12 +.B IPC_CREAT +to create a new segment. If this flag is not used, then +.B shmget() +will find the segment associated with \fIkey\fP and check to see if +the user has permission to access the segment. +.TP +.B IPC_EXCL +used with \fBIPC_CREAT\fP to ensure failure if the segment already exists. +.TP +.B mode_flags (lowest 9 bits) +specifying the permissions granted to the owner, group, and world. +Presently, the execute permissions are not used by the system. +.\" FIXME -- document SHM_HUGETLB +.PP +If a new segment is created, the access permissions from +.I shmflg +are copied into the +.I shm_perm +member of the +.I shmid_ds +structure that defines the segment. +The \fIshmid_ds\fP structure has the following form: +.PP +.in +0.5i +.nf +struct shmid_ds { + struct ipc_perm shm_perm; /* operation perms */ + int shm_segsz; /* size of segment (bytes) */ + time_t shm_atime; /* last attach time */ + time_t shm_dtime; /* last detach time */ + time_t shm_ctime; /* last change time */ + unsigned short shm_cpid; /* pid of creator */ + unsigned short shm_lpid; /* pid of last operator */ + short shm_nattch; /* no. of current attaches */ +}; +.fi +.in -0.5i +.PP +.in +0.5i +.nf +struct ipc_perm { + key_t key; + ushort uid; /* owner euid and egid */ + ushort gid; + ushort cuid; /* creator euid and egid */ + ushort cgid; + ushort mode; /* lower 9 bits of \fIshmflg\fP */ + ushort seq; /* sequence number */ +}; +.fi +.PP +When creating a new shared memory segment, +the system call initializes the \fIshmid_ds\fP data structure +.B shmid_ds +as follows: +.IP +.B shm_perm.cuid +and +.B shm_perm.uid +are set to the effective user\-ID of the calling process. +.IP +.B shm_perm.cgid +and +.B shm_perm.gid +are set to the effective group\-ID of the calling process. +.IP +The lowest order 9 bits of +.B shm_perm.mode +are set to the lowest order 9 bit of +.IR shmflg . +.IP +.B shm_segsz +is set to the value of +.IR size . +.IP +.BR shm_lpid , +.BR shm_nattch , +.B shm_atime +and +.B shm_dtime +are set to +.BR 0 . +.IP +.B shm_ctime +is set to the current time. +.PP +If the shared memory segment already exists, the access permissions are +verified, and a check is made to see if it is marked for destruction. +.PP +.SH "SYSTEM CALLS" +.TP +.B fork() +After a +.B fork() +the child inherits the attached shared memory segments. +.TP +.B exec() +After an +.B exec() +all attached shared memory segments are detached (not destroyed). +.TP +.B exit() +Upon +.B exit() +all attached shared memory segments are detached (not destroyed). +.PP +.SH "RETURN VALUE" +A valid segment identifier, +.IR shmid , +is returned on success, \-1 on error. +.SH ERRORS +On failure, +.B errno +is set to one of the following: +.TP 12 +.B EACCES +The user does not have permission to access the +shared memory segment, and does not have the +.B CAP_IPC_OWNER +capability. +.TP +.B EEXIST +.B IPC_CREAT | IPC_EXCL +was specified and the segment exists. +.TP +.\" FIXME -- SHM_HUGETLB requires CAP_IPC_LOCK, or the error EPERM +.\" results +.B EINVAL +A new segment was to be created and \fIsize\fP < \fBSHMMIN\fP +or \fIsize\fP > \fBSHMMAX\fP, or no new segment was to be created, +a segment with given key existed, but \fIsize\fP is greater than the size +of that segment. +.TP +.B ENFILE +.\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp() +The system limit on the total number of open files has been reached. +.TP +.B ENOENT +No segment exists for the given \fIkey\fP, and +.B IPC_CREAT +was not specified. +.TP +.B ENOMEM +No memory could be allocated for segment overhead. +.TP +.B ENOSPC +All possible shared memory id's have been taken +.RB ( SHMMNI ), +or allocating a segment of the requested +.I size +would cause the system to exceed the system-wide limit on shared memory +.RB ( SHMALL ). +.SH NOTES +.B IPC_PRIVATE +isn't a flag field but a +.B key_t +type. +If this special value is used for +.IR key , +the system call ignores everything but the lowest order 9 bits of +.I shmflg +and creates a new shared memory segment (on success). +.PP +The followings are limits on shared memory segment resources affecting a +.B shmget +call: +.TP 11 +.B SHMALL +System wide maximum of shared memory pages: policy dependent. +.TP +.B SHMMAX +Maximum size in bytes for a shared memory segment: implementation +dependent (currently 4M). +.TP +.B SHMMIN +Minimum size in bytes for a shared memory segment: implementation +dependent (currently 1 byte, though +.B PAGE_SIZE +is the effective minimum size). +.TP +.B SHMMNI +System wide maximum number of shared memory segments: implementation +dependent (currently 4096, was 128 before Linux 2.3.99). +.PP +The implementation has no specific limits for the per process maximum +number of shared memory segments +.RB ( SHMSEG ). +.SH BUGS +The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW +would more clearly show its function. +.SH "CONFORMING TO" +SVr4, SVID. SVr4 documents an additional error condition EEXIST. +Until version 2.3.30 Linux would return EIDRM for a +.B shmget +on a shared memory segment scheduled for deletion. +.SH "SEE ALSO" +.BR shmat (2), +.BR shmctl (2), +.BR shmdt (2), +.BR ftok (3), +.BR ipc (5), +.BR capabilities (7) diff --git a/man2/shmop.2 b/man2/shmop.2 new file mode 100644 index 000000000..b24a2141f --- /dev/null +++ b/man2/shmop.2 @@ -0,0 +1,278 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Sun Nov 28 17:06:19 1993, Rik Faith (faith@cs.unc.edu) +.\" with material from Luigi P. Bai (lpb@softint.com) +.\" Portions Copyright 1993 Luigi P. Bai +.\" Modified Tue Oct 22 22:04:23 1996 by Eric S. Raymond +.\" Modified, 5 Jan 2002, Michael Kerrisk +.\" Modified, 19 Sep 2002, Michael Kerrisk +.\" Added SHM_REMAP flag description +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH SHMOP 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +shmop \- shared memory operations +.SH SYNOPSIS +.nf +.B +#include +.B +#include +.fi +.sp +.BI "void *shmat(int " shmid , +.BI "const void *" shmaddr , +.BI "int " shmflg ); +.sp +.BI "int shmdt(const void *" shmaddr ); +.SH DESCRIPTION +The function +.B shmat +attaches the shared memory segment identified by +.B shmid +to the address space of the calling process. +The attaching address is specified by +.I shmaddr +with one of the following criteria: +.LP +If +.I shmaddr +is +.BR NULL , +the system chooses a suitable (unused) address at which to attach +the segment. +.LP +If +.I shmaddr +isn't +.B NULL +and +.B SHM_RND +is asserted in +.IR shmflg , +the attach occurs at the address equal to +.I shmaddr +rounded down to the nearest multiple of +.BR SHMLBA . +Otherwise +.I shmaddr +must be a page-aligned address at which the attach occurs. +.PP +If +.B SHM_RDONLY +is asserted in +.IR shmflg , +the segment is attached for reading and the process must have +read permission for the segment. +Otherwise the segment is attached for read and write +and the process must have read and write permission for the segment. +There is no notion of a write-only shared memory segment. +.PP +The (Linux-specific) +.B SHM_REMAP +flag may be asserted in +.I shmflg +to indicate that the mapping of the segment should replace +any existing mapping in the range starting at +.I shmaddr +and continuing for the size of the segment. +(Normally an +.B EINVAL +error would result if a mapping already exists in this address range.) +In this case, +.I shmaddr +must not be +.BR NULL . +.PP +The +.B brk +value of the calling process is not altered by the attach. +The segment will automatically be detached at process exit. +The same segment may be attached as a read and as a read-write +one, and more than once, in the process's address space. +.PP +On a successful +.B shmat +call the system updates the members of the +.B shmid_ds +structure associated to the shared memory segment as follows: +.IP +.B shm_atime +is set to the current time. +.IP +.B shm_lpid +is set to the process-ID of the calling process. +.IP +.B shm_nattch +is incremented by one. +.PP +Note that the attach succeeds also if the shared memory segment is +marked to be deleted. +.PP +The function +.B shmdt +detaches the shared memory segment located at the address specified by +.I shmaddr +from the address space of the calling process. +The to\-be\-detached segment must be currently +attached with +.I shmaddr +equal to the value returned by the its attaching +.B shmat +call. +.PP +On a successful +.B shmdt +call the system updates the members of the +.B shmid_ds +structure associated with the shared memory segment as follows: +.IP +.B shm_dtime +is set to the current time. +.IP +.B shm_lpid +is set to the process-ID of the calling process. +.IP +.B shm_nattch +is decremented by one. +If it becomes 0 and the segment is marked for deletion, +the segment is deleted. +.PP +The occupied region in the user space of the calling process is +unmapped. +.SH "SYSTEM CALLS" +.TP 11 +.B fork() +After a +.B fork() +the child inherits the attached shared memory segments. +.TP +.B exec() +After an +.B exec() +all attached shared memory segments are detached from the process. +.TP +.B exit() +Upon +.B exit() +all attached shared memory segments are detached from the process. +.SH "RETURN VALUE" +On success +.B shmat +returns the address of the attached shared memory segment, and +.B shmdt +returns 0. +On failure both functions return \-1 with +.I errno +indicating the error. +.SH ERRORS +When +.B shmat +fails, +.I errno +is set to one of the following: +.TP +.B EACCES +The calling process does not have the required permissions for +the requested attach type, and does not have the +.B CAP_IPC_OWNER +capability. +.TP +.B EINVAL +Invalid +.I shmid +value, unaligned (i.e., not page-aligned and \fBSHM_RND\fP was not +specified) or invalid +.I shmaddr +value, or failing attach at +.BR brk , +.\" FIXME What does "failing attach at brk" mean? +or +.B SHM_REMAP +was specified and +.I shmaddr +was +.BR NULL . +.TP +.B ENOMEM +Could not allocate memory for the descriptor or for the page tables. +.PP +The function +.B shmdt +can fail only if there is no shared memory segment attached at +.IR shmaddr , +in such a case at return +.I errno +will be set to +.BR EINVAL . +.SH NOTES +Using +.B shmat +with +.I shmaddr +equal to +.B NULL +is the preferred, portable way of attaching a shared memory segment. +Be aware that the shared memory segment attached in this way +may be attached at different addresses in different processes. +Therefore, any pointers maintained within the shared memory must be +made relative (typically to the starting address of the segment), +rather than absolute. +.LP +The following system parameter affects a +.B shmat +system call: +.TP 11 +.B SHMLBA +Segment low boundary address multiple. +Must be page aligned. +For the current implementation the +.B SHMBLA +value is +.BR PAGE_SIZE . +.PP +The implementation has no intrinsic limit to the per\-process maximum +number of shared memory segments +.RB ( SHMSEG ). +.SH "CONFORMING TO" +SVr4, SVID. SVr4 documents an additional error condition EMFILE. +In SVID-v4 the type of the \fIshmaddr\fP argument was changed from +.B "char *" +into +.BR "const void *" , +and the returned type of \fIshmat\fP() from +.B "char *" +into +.BR "void *" . +(Linux libc4 and libc5 have the +.B "char *" +prototypes; glibc2 has +.BR "void *" .) +.SH "SEE ALSO" +.BR brk (2), +.BR mmap (2), +.BR shmctl (2), +.BR shmget (2), +.BR ipc (5), +.BR capabilities (7) diff --git a/man2/shutdown.2 b/man2/shutdown.2 new file mode 100644 index 000000000..4da0d45b0 --- /dev/null +++ b/man2/shutdown.2 @@ -0,0 +1,91 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Id: shutdown.2,v 1.1.1.1 1999/03/21 22:52:23 freitag Exp $ +.\" +.\" Modified Sat Jul 24 09:57:55 1993 by Rik Faith +.\" Modified Tue Oct 22 22:04:51 1996 by Eric S. Raymond +.\" Modified 1998 by Andi Kleen +.\" +.TH SHUTDOWN 2 1993-07-24 "BSD Man Page" "Linux Programmer's Manual" +.SH NAME +shutdown \- shut down part of a full-duplex connection +.SH SYNOPSIS +.B #include +.sp +.BI "int shutdown(int " s ", int " how ); +.SH DESCRIPTION +The +.B shutdown +call causes all or part of a full-duplex connection on the socket +associated with +.I s +to be shut down. If +.I how +is +.BR SHUT_RD , +further receptions will be disallowed. If +.I how +is +.BR SHUT_WR , +further transmissions will be disallowed. If +.I how +is +.BR SHUT_RDWR , +further receptions and transmissions will be disallowed. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I s +is not a valid descriptor. +.TP +.B ENOTCONN +The specified socket is not connected. +.TP +.B ENOTSOCK +.I s +is a file, not a socket. +.SH NOTES +The constants SHUT_RD, SHUT_WR, SHUT_RDWR have the value 0, 1, 2, +respectively, and are defined in +.I +since glibc-2.1.91. +.SH "CONFORMING TO" +4.4BSD (the +.B shutdown +function call first appeared in 4.2BSD). +.SH "SEE ALSO" +.BR connect (2), +.BR socket (2) diff --git a/man2/sigaction.2 b/man2/sigaction.2 new file mode 100644 index 000000000..eaa4f67b8 --- /dev/null +++ b/man2/sigaction.2 @@ -0,0 +1,466 @@ +'\" t +.\" Copyright (c) 1994,1995 Mike Battersby +.\" based on work by faith@cs.unc.edu +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified, aeb, 960424 +.\" Modified Fri Jan 31 17:31:20 1997 by Eric S. Raymond +.\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff. +.\" Modified Sat May 8 17:40:19 1999 by Matthew Wilcox - add POSIX.1b signals +.\" Modified Sat Dec 29 01:44:52 2001 by Evan Jones - SA_ONSTACK +.\" +.TH SIGACTION 2 2001-12-29 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +sigaction, sigprocmask, sigpending, sigsuspend \- POSIX signal handling functions +.SH SYNOPSIS +.B #include +.sp 2 +.BI "int sigaction(int " signum ", const struct sigaction *" act , +.BI "struct sigaction *" oldact ); +.sp +.BI "int sigprocmask(int " how ", const sigset_t *" set , +.BI "sigset_t *" oldset ); +.sp +.BI "int sigpending(sigset_t *" set ); +.sp +.BI "int sigsuspend(const sigset_t *" mask ); +.SH DESCRIPTION +The +.B sigaction +system call is used to change the action taken by a process on +receipt of a specific signal. +.PP +.I signum +specifies the signal and can be any valid signal except +.B SIGKILL +and +.BR SIGSTOP . +.PP +If +.I act +is non\-null, the new action for signal +.I signum +is installed from +.IR act . +If +.I oldact +is non\-null, the previous action is saved in +.IR oldact . +.PP +The +.B sigaction +structure is defined as something like +.sp +.RS +.nf +struct sigaction { + void (*sa_handler)(int); + void (*sa_sigaction)(int, siginfo_t *, void *); + sigset_t sa_mask; + int sa_flags; + void (*sa_restorer)(void); +} +.fi +.RE +.PP +On some architectures a union is involved - do not assign to both +.I sa_handler +and +.IR sa_sigaction . +.PP +The +.I sa_restorer +element is obsolete and should not be used. +POSIX does not specify a +.I sa_restorer +element. +.PP +.I sa_handler +specifies the action to be associated with +.I signum +and may be +.B SIG_DFL +for the default action, +.B SIG_IGN +to ignore this signal, or a pointer to a signal handling function. +This function receives the signal number as its only argument. +.PP +.I sa_sigaction +also specifies the action to be associated with +.IR signum . +This function receives the signal number as its first argument, a +pointer to a +.I siginfo_t +as its second argument and a pointer to a +.I ucontext_t +(cast to void *) as its third argument. +.PP +.I sa_mask +gives a mask of signals which should be blocked during execution of +the signal handler. In addition, the signal which triggered the handler +will be blocked, unless the +.B SA_NODEFER +or +.B SA_NOMASK +flags are used. +.PP +.I sa_flags +specifies a set of flags which modify the behaviour of the signal handling +process. It is formed by the bitwise OR of zero or more of the following: +.RS +.TP +.B SA_NOCLDSTOP +If +.I signum +is +.BR SIGCHLD ", " +do not receive notification when child processes stop (i.e., when child +processes receive one of +.BR SIGSTOP ", " SIGTSTP ", " SIGTTIN +or +.BR SIGTTOU ")." +.TP +.BR SA_ONESHOT " or " SA_RESETHAND +Restore the signal action to the default state once the signal handler +has been called. +.TP +.BR SA_ONSTACK +Call the signal handler on an alternate signal stack provided by +.BR sigaltstack (2). +If an alternate stack is not available, the default stack will be used. +.TP +.B SA_RESTART +Provide behaviour compatible with BSD signal semantics by making certain +system calls restartable across signals. +.TP +.BR SA_NOMASK " or " SA_NODEFER +Do not prevent the signal from being received from within its own signal +handler. +.TP +.B SA_SIGINFO +The signal handler takes 3 arguments, not one. In this case, +.I sa_sigaction +should be set instead of +.IR sa_handler . +(The sa_sigaction field was added in Linux 2.1.86.) +.RE +.PP +The +.I siginfo_t +parameter to +.I sa_sigaction +is a struct with the following elements +.sp +.RS +.nf +.ta 4 13 24 +siginfo_t { + int si_signo; /* Signal number */ + int si_errno; /* An errno value */ + int si_code; /* Signal code */ + pid_t si_pid; /* Sending process ID */ + uid_t si_uid; /* Real user ID of sending process */ + int si_status; /* Exit value or signal */ + clock_t si_utime; /* User time consumed */ + clock_t si_stime; /* System time consumed */ + sigval_t si_value; /* Signal value */ + int si_int; /* POSIX.1b signal */ + void * si_ptr; /* POSIX.1b signal */ + void * si_addr; /* Memory location which caused fault */ + int si_band; /* Band event */ + int si_fd; /* File descriptor */ +} +.fi +.RE + +.IR si_signo ", " si_errno " and " si_code +are defined for all signals. +The rest of the struct may be a union, so that one should only +read the fields that are meaningful for the given signal. +.BR kill (2), +POSIX.1b signals and SIGCHLD fill in +.IR si_pid " and " si_uid . +.BR +SIGCHLD also fills in +.IR si_status ", " si_utime " and " si_stime . +.IR si_int " and " si_ptr +are specified by the sender of the POSIX.1b signal. +.\" See +.\" .BR sigqueue (2) +.\" for more details. +SIGILL, SIGFPE, SIGSEGV and SIGBUS fill in +.I si_addr +with the address of the fault. +SIGPOLL fills in +.IR si_band " and " si_fd . + +.I si_code +indicates why this signal was sent. It is a value, not a bitmask. The +values which are possible for any signal are listed in this table: +.TS +tab(:) allbox; +c s +l l. +\fIsi_code\fR +Value:Signal origin +SI_USER:kill, sigsend or raise +SI_KERNEL:The kernel +SI_QUEUE:sigqueue +SI_TIMER:timer expired +SI_MESGQ:mesq state changed +SI_ASYNCIO:AIO completed +SI_SIGIO:queued SIGIO +.TE + +.TS +tab(:) allbox; +c s +l l. +SIGILL +ILL_ILLOPC:illegal opcode +ILL_ILLOPN:illegal operand +ILL_ILLADR:illegal addressing mode +ILL_ILLTRP:illegal trap +ILL_PRVOPC:privileged opcode +ILL_PRVREG:privileged register +ILL_COPROC:coprocessor error +ILL_BADSTK:internal stack error +.TE + +.TS +tab(:) allbox; +c s +l l. +SIGFPE +FPE_INTDIV:integer divide by zero +FPE_INTOVF:integer overflow +FPE_FLTDIV:floating point divide by zero +FPE_FLTOVF:floating point overflow +FPE_FLTUND:floating point underflow +FPE_FLTRES:floating point inexact result +FPE_FLTINV:floating point invalid operation +FPE_FLTSUB:subscript out of range +.TE + +.TS +tab(:) allbox; +c s +l l. +SIGSEGV +SEGV_MAPERR:address not mapped to object +SEGV_ACCERR:invalid permissions for mapped object +.TE + +.TS +tab(:) allbox; +c s +l l. +SIGBUS +BUS_ADRALN:invalid address alignment +BUS_ADRERR:non-existent physical address +BUS_OBJERR:object specific hardware error +.TE + +.TS +tab(:) allbox; +c s +l l. +SIGTRAP +TRAP_BRKPT:process breakpoint +TRAP_TRACE:process trace trap +.TE + +.TS +tab(:) allbox; +c s +l l. +SIGCHLD +CLD_EXITED:child has exited +CLD_KILLED:child was killed +CLD_DUMPED:child terminated abnormally +CLD_TRAPPED:traced child has trapped +CLD_STOPPED:child has stopped +CLD_CONTINUED:stopped child has continued +.TE + +.TS +tab(:) allbox; +c s +l l. +SIGPOLL +POLL_IN:data input available +POLL_OUT:output buffers available +POLL_MSG:input message available +POLL_ERR:i/o error +POLL_PRI:high priority input available +POLL_HUP:device disconnected +.TE + +.PP +The +.B sigprocmask +call is used to change the list of currently blocked signals. The +behaviour of the call is dependent on the value of +.IR how , +as follows. +.RS +.TP +.B SIG_BLOCK +The set of blocked signals is the union of the current set and the +.I set +argument. +.TP +.B SIG_UNBLOCK +The signals in +.I set +are removed from the current set of blocked signals. It is legal to +attempt to unblock a signal which is not blocked. +.TP +.B SIG_SETMASK +The set of blocked signals is set to the argument +.IR set . +.RE +.PP +If +.I oldset +is non\-null, the previous value of the signal mask is stored in +.IR oldset . +.PP +The +.B sigpending +call allows the examination of pending signals (ones which have been +raised while blocked). The signal mask of pending signals is stored +in +.IR set . +.PP +The +.B sigsuspend +call temporarily replaces the signal mask for the process with that +given by +.I mask +and then suspends the process until a signal is received. + +.SH "RETURN VALUE" +The functions +.BR sigaction , +.BR sigprocmask , +and +.B sigpending +return 0 on success and \-1 on error. +The function +.B sigsuspend +always returns \-1, normally with the error +.BR EINTR . + +.SH ERRORS +.TP +.B EFAULT +.IR act ", " oldact ", " set ", " oldset +or +.I mask +point to memory which is not a valid part of the process address space. +.TP +.B EINTR +System call was interrupted. +.TP +.B EINVAL +An invalid signal was specified. This will also be generated if an attempt +is made to change the action for +.BR SIGKILL " or " SIGSTOP ", " +which cannot be caught. +.SH NOTES +It is not possible to block +.BR SIGKILL " or " SIGSTOP +with the sigprocmask call. Attempts to do so will be silently ignored. +.PP +According to POSIX, the behaviour of a process is undefined after it +ignores a SIGFPE, SIGILL, or SIGSEGV signal that was not generated +by the \fIkill()\fP or the \fIraise()\fP functions. +Integer division by zero has undefined result. +On some architectures it will generate a SIGFPE signal. +(Also dividing the most negative integer by \-1 may generate SIGFPE.) +Ignoring this signal might lead to an endless loop. +.PP +POSIX (B.3.3.1.3) disallows setting the action for SIGCHLD to SIG_IGN. +The BSD and SYSV behaviours differ, causing BSD software +that sets the action for SIGCHLD to SIG_IGN to fail on Linux. +.PP +The POSIX spec only defines +.BR SA_NOCLDSTOP . +Use of other +.I sa_flags +is non\-portable. +.PP +The +.B SA_RESETHAND +flag is compatible with the SVr4 flag of the same name. +.PP +The +.B SA_NODEFER +flag is compatible with the SVr4 flag of the same name under kernels +1.3.9 and newer. On older kernels the Linux implementation +allowed the receipt of any signal, not just the one we are installing +(effectively overriding any +.I sa_mask +settings). +.PP +The +.BR SA_RESETHAND " and " SA_NODEFER +names for SVr4 compatibility are present only in library versions 3.0.9 +and greater. +.PP +The +.B SA_SIGINFO +flag is specified by POSIX.1b. Support for it was added in Linux 2.2. +.PP +.B sigaction +can be called with a null second argument to query the current signal +handler. It can also be used to check whether a given signal is valid for +the current machine by calling it with null second and third arguments. +.PP +See +.BR sigsetops (3) +for details on manipulating signal sets. +.SH "CONFORMING TO" +POSIX, SVr4. SVr4 does not document the EINTR condition. + +.SH UNDOCUMENTED +Before the introduction of +.B SA_SIGINFO +it was also possible to get some additional information, +namely by using a sa_handler with second argument of type +.IR "struct sigcontext". +See the relevant kernel sources for details. +This use is obsolete now. + +.SH "SEE ALSO" +.BR kill (1), +.BR kill (2), +.BR killpg (2), +.BR pause (2), +.BR sigaltstack (2), +.BR signal (2), +.BR sigvec (2), +.BR raise (3), +.BR siginterrupt (3), +.BR sigsetops (3), +.BR signal (7) diff --git a/man2/sigaltstack.2 b/man2/sigaltstack.2 new file mode 100644 index 000000000..21c4597e5 --- /dev/null +++ b/man2/sigaltstack.2 @@ -0,0 +1,185 @@ +'\" t +.\" Copyright (c) 2001, Michael Kerrisk (mtk16@ext.canterbury.ac.nz) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" aeb, various minor fixes +.TH SIGALTSTACK 2 2001-09-27 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +sigaltstack - set and/or get signal stack context +.SH SYNOPSIS +.B #include +.sp +.BI "int sigaltstack(const stack_t *" ss ", stack_t *" oss ); +.SH DESCRIPTION +\fBsigaltstack\fP allows a process to define a new alternate +signal stack and/or retrieve the state of an existing +alternate signal stack. An alternate signal stack is used during the +execution of a signal handler if the establishment of that handler (see +.BR sigaction (2)) +requested it. + +The normal sequence of events for using an alternate signal stack +is the following: +.TP +1. +Allocate an area of memory to be used for the alternate +signal stack. +.TP +2. +Use \fBsigaltstack\fP to inform the system of the existence and +location of the alternate signal stack. +.TP +3. +When establishing a signal handler using \fBsigaction\fP, +inform the system that the signal handler should be executed +on the alternate signal stack by +specifying the \fBSA_ONSTACK\fP flag. +.P +The \fIss\fP argument is used to specify a new +alternate signal stack, while the \fIoss\fP argument +is used to retrieve information about the currently +established signal stack. +If we are interested in performing just one +of these tasks then the other argument can be specified as NULL. +Each of these arguments is a structure of the following type: +.sp +.RS +.nf +typedef struct { + void *ss_sp; /* Base address of stack */ + int ss_flags; /* Flags */ + size_t ss_size; /* Number of bytes in stack */ +} stack_t; +.fi +.RE + +To establish a new alternate signal stack, +\fIss.ss_flags\fP is set to zero, and \fIss.sp_sp\fP and +\fIss.ss_size\fP specify the starting address and size of +the stack. +The constant \fBSIGSTKSZ\fP is defined to be large enough +to cover the usual size requirements for an alternate signal stack, +and the constant \fBMINSIGSTKSZ\fP defines the minimum +size required to execute a signal handler. + +To disable an existing stack, specify \fIss.ss_flags\fP +as \fBSS_DISABLE\fP. In this case, the remaining fields +in \fIss\fP are ignored. + +If \fIoss\fP is not NULL, then it is used to return information about +the alternate signal stack which was in effect prior to the +call to \fBsigaltstack\fP. +The \fIoss.ss_sp\fP and \fIoss.ss_size\fP fields return the starting +address and size of that stack. +The \fIoss.ss_flags\fP may return either of the following values: + +.TP +.B SS_ONSTACK +The process is currently executing on the alternate +signal stack. (Note that it is not possible +to change the alternate signal stack if the process is +currently executing on it.) +.TP +.B SS_DISABLE +The alternate signal stack is currently disabled. + +.SH "RETURN VALUE" +\fBsigaltstack\fP returns 0 on success, or \-1 on failure with +\fIerrno\fP set to indicate the error. + +.SH ERRORS +.TP +.B EFAULT +Either \fIss\fP or \fIoss\fP is not NULL and points to an area +outside of the process's address space. +.TP +.B EINVAL +\fIss\fP is not NULL and the \fPss_flags\fP field contains +a non-zero value other than SS_DISABLE. +.TP +.B ENOMEM +The specified size of the new alternate signal stack +(\fIss.ss_size\fP) was less than \fBMINSTKSZ\fP. +.TP +.B EPERM +An attempt was made to change the alternate signal stack while +it was active (i.e., the process was already executing +on the current alternate signal stack). +.SH NOTES +The following code segment demonstrates the use of \fBsigaltstack\fP: + +.RS +.nf +stack_t ss; + +ss.ss_sp = malloc(SIGSTKSZ); +if (ss.ss_sp == NULL) + /* Handle error */; +ss.ss_size = SIGSTKSZ; +ss.ss_flags = 0; +if (sigaltstack(&ss, NULL) == -1) + /* Handle error */; +.fi +.RE +.P +Establishing an alternate signal stack is useful if a process +expects that it may exhaust its standard stack. +This may occur, for example, because the stack grows so large +that it encounters the upwardly growing heap, or it reaches a +limit established by a call to \fBsetrlimit(RLIMIT_STACK, &rlim)\fP. +If the standard stack is exhausted, the kernel sends +the process a \fBSIGSEGV\fP signal. +In these circumstances the only way to catch this signal is +on an alternate signal stack. +.P +On most hardware architectures supported by Linux, stacks grow +downwards. \fBsigaltstack\fP automatically takes account +of the direction of stack growth. +.P +Functions called from a signal handler executing on an alternate +signal stack will also use the alternate signal stack. +(This also applies to any handlers invoked for other signals while +the process is executing on the alternate signal stack.) +Unlike the standard stack, the system does not +automatically extend the alternate signal stack. +Exceeding the allocated size of the alternate signal stack will +lead to unpredictable results. +.P +A successful call to \fBexecve\fP removes any existing alternate +signal stack. +.P +\fBsigaltstack\fP supersedes the older \fBsigstack\fP call. +For backwards compatibility, glibc also provides \fBsigstack\fP. +All new applications should be written using \fBsigaltstack\fB. + +.SH HISTORY +BSD 4.2 had a \fIsigstack\fP() system call. It used a slightly +different struct, and had as major disadvantage that the caller +had to know the direction of stack growth. + +.SH "CONFORMING TO" +SUSv2, SVr4, POSIX 1003.1-2001. + +.SH "SEE ALSO" +.BR execve (2), +.BR setrlimit (2), +.BR sigaction (2), +.BR siglongjmp (3), +.BR sigsetjmp (3), +.BR signal (7) diff --git a/man2/sigblock.2 b/man2/sigblock.2 new file mode 100644 index 000000000..b75dc6212 --- /dev/null +++ b/man2/sigblock.2 @@ -0,0 +1,103 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)sigblock.2 6.7 (Berkeley) 3/10/91 +.\" +.\" Modified Sat Jul 24 10:09:15 1993 by Rik Faith +.\" Modified Fri Aug 11 1995 by Stephen Lee +.\" Modified 1995 by Mike Battersby +.\"" +.TH SIGBLOCK 2 1995-08-31 "Linux 1.3" "Linux Programmer's Manual" +.SH NAME +sigblock, siggetmask, sigsetmask, sigmask \- manipulate the signal mask +.SH SYNOPSIS +.B #include +.sp +.BI "int sigblock(int " mask ); +.sp +.B int siggetmask(void); +.sp +.BI "int sigsetmask(int " mask ); +.sp +.BI "int sigmask(int " signum ); +.SH DESCRIPTION +This interface is made obsolete by +.BR sigprocmask (2). + +The +.B sigblock +system call adds the signals specified in +.I mask +to the set of signals currently being blocked from delivery. +.PP +The +.B sigsetmask +system call replaces the set of blocked signals totally with a new set +specified in +.IR mask . +Signals are blocked if the corresponding bit in +.I mask +is a 1. +.PP +The current set of blocked signals can be obtained using +.BR siggetmask . +.PP +The +.B sigmask +macro is provided to construct the mask for a given +.IR signum . + +.SH "RETURN VALUE" +.B siggetmask +returns the current set of masked signals. + +.B sigsetmask +and +.B sigblock +return the previous set of masked signals. +.SH NOTES +Prototypes for these functions are only available if +.B _BSD_SOURCE +is defined before the inclusion of any system header file. +.PP +It is not possible to block +.B SIGKILL +or +.B SIGSTOP +\- this restriction is silently imposed by the system. + +.SH "CONFORMING TO" +4.4BSD. These function calls appeared in BSD 4.3 and are deprecated. +Use the POSIX signal facilities for new programs. +.SH "SEE ALSO" +.BR kill (2), +.BR sigprocmask (2), +.BR signal (7) diff --git a/man2/siggetmask.2 b/man2/siggetmask.2 new file mode 100644 index 000000000..ebe864f81 --- /dev/null +++ b/man2/siggetmask.2 @@ -0,0 +1 @@ +.so man2/sigblock.2 diff --git a/man2/sigmask.2 b/man2/sigmask.2 new file mode 100644 index 000000000..ebe864f81 --- /dev/null +++ b/man2/sigmask.2 @@ -0,0 +1 @@ +.so man2/sigblock.2 diff --git a/man2/signal.2 b/man2/signal.2 new file mode 100644 index 000000000..9c989d138 --- /dev/null +++ b/man2/signal.2 @@ -0,0 +1,299 @@ +.\" Copyright (c) 2000 Andries Brouwer +.\" based on work by Rik Faith +.\" and Mike Battersby . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH SIGNAL 2 2000-04-28 "Linux 2.2" "Linux Programmer's Manual" +.SH NAME +signal \- ANSI C signal handling +.SH SYNOPSIS +.B #include +.sp +.B typedef void (*sighandler_t)(int); +.sp +.BI "sighandler_t signal(int " signum ", sighandler_t " handler ); +.SH DESCRIPTION +The +.BR signal () +system call installs a new signal handler for the signal with number +.IR signum . +The signal handler is set to +.I sighandler +which may be a user specified function, or either +.B SIG_IGN +or +.BR SIG_DFL . + +Upon arrival of a signal with number +.I signum +the following happens. +If the corresponding handler is set to +.BR SIG_IGN , +then the signal is ignored. +If the handler is set to +.BR SIG_DFL , +then the default action associated to the signal (see +.BR signal (7)) +occurs. +Finally, if the handler is set to a function +.I sighandler +then first either the handler is reset to SIG_DFL +or an implementation-dependent blocking of the signal +is performed and next +.I sighandler +is called with argument +.IR signum . + +Using a signal handler function for a signal +is called "catching the signal". +The signals +.B SIGKILL +and +.B SIGSTOP +cannot be caught or ignored. + +.SH "RETURN VALUE" +The +.BR signal () +function returns the previous value of the signal handler, or +.B SIG_ERR +on error. + +.SH PORTABILITY +The original Unix +.BR signal () +would reset the handler to SIG_DFL, and System V +(and the Linux kernel and libc4,5) does the same. +On the other hand, BSD does not reset the handler, but blocks +new instances of this signal from occurring during a call of the handler. +The glibc2 library follows the BSD behaviour. + +If one on a libc5 system includes +.B "" +instead of +.B "" +then +.B signal +is redefined as +.B __bsd_signal +and signal has the BSD semantics. This is not recommended. + +If one on a glibc2 system defines a feature test +macro such as +.B _XOPEN_SOURCE +or uses a separate +.B sysv_signal +function, one obtains classical behaviour. This is not recommended. + +Trying to change the semantics of this call using +defines and includes is not a good idea. It is better to avoid +.B signal +altogether, and use +.BR sigaction (2) +instead. + +.SH NOTES +The effects of this call in a multi-threaded process are unspecified. +.PP +The routine +.I handler +must be very careful, since processing elsewhere was interrupted +at some arbitrary point. POSIX has the concept of "safe function". +If a signal interrupts an unsafe function, and +.I handler +calls an unsafe function, then the behavior is undefined. Safe +functions are listed explicitly in the various standards. +The POSIX 1003.1-2003 list is + +_Exit() +_exit() +abort() +accept() +access() +aio_error() +aio_return() +aio_suspend() +alarm() +bind() +cfgetispeed() +cfgetospeed() +cfsetispeed() +cfsetospeed() +chdir() +chmod() +chown() +clock_gettime() +close() +connect() +creat() +dup() +dup2() +execle() +execve() +fchmod() +fchown() +fcntl() +fdatasync() +fork() +fpathconf() +fstat() +fsync() +ftruncate() +getegid() +geteuid() +getgid() +getgroups() +getpeername() +getpgrp() +getpid() +getppid() +getsockname() +getsockopt() +getuid() +kill() +link() +listen() +lseek() +lstat() +mkdir() +mkfifo() +open() +pathconf() +pause() +pipe() +poll() +posix_trace_event() +pselect() +raise() +read() +readlink() +recv() +recvfrom() +recvmsg() +rename() +rmdir() +select() +sem_post() +send() +sendmsg() +sendto() +setgid() +setpgid() +setsid() +setsockopt() +setuid() +shutdown() +sigaction() +sigaddset() +sigdelset() +sigemptyset() +sigfillset() +sigismember() +signal() +sigpause() +sigpending() +sigprocmask() +sigqueue() +sigset() +sigsuspend() +sleep() +socket() +socketpair() +stat() +symlink() +sysconf() +tcdrain() +tcflow() +tcflush() +tcgetattr() +tcgetpgrp() +tcsendbreak() +tcsetattr() +tcsetpgrp() +time() +timer_getoverrun() +timer_gettime() +timer_settime() +times() +umask() +uname() +unlink() +utime() +wait() +waitpid() +write(). +.PP +According to POSIX, the behaviour of a process is undefined after it +ignores a +.BR SIGFPE , +.BR SIGILL , +or +.B SIGSEGV +signal that was not generated by the +.BR kill (2) +or the +.BR raise (3) +functions. +Integer division by zero has undefined result. +On some architectures it will generate a +.B SIGFPE +signal. +(Also dividing the most negative integer by \-1 may generate +.BR SIGFPE .) +Ignoring this signal might lead to an endless loop. +.PP +According to POSIX (3.3.1.3) it is unspecified what happens when +.B SIGCHLD +is set to +.BR SIG_IGN . +Here the BSD and SYSV behaviours differ, causing BSD software +that sets the action for +.B SIGCHLD +to +.B SIG_IGN +to fail on Linux. +.PP +The use of +.B sighandler_t +is a GNU extension. +Various versions of libc predefine this type; libc4 and libc5 define +.IR SignalHandler , +glibc defines +.I sig_t +and, when +.B _GNU_SOURCE +is defined, also +.IR sighandler_t . +.SH "CONFORMING TO" +ANSI C + +.SH "SEE ALSO" +.BR kill (1), +.BR alarm (2), +.BR kill (2), +.BR killpg (2), +.BR pause (2), +.BR sigaction (2), +.BR sigvec (2), +.BR raise (3), +.BR sigsetops (3), +.BR signal (7) diff --git a/man2/sigpause.2 b/man2/sigpause.2 new file mode 100644 index 000000000..0f562fa31 --- /dev/null +++ b/man2/sigpause.2 @@ -0,0 +1,83 @@ +.\" Copyright (C) 2004 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH SIGPAUSE 2 2004-05-10 "Linux 2.6" "Linux Programmer's Manual" +.SH NAME +sigpause \- atomically release blocked signals and wait for interrupt +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int sigpause(int " sigmask "); /* BSD */" +.sp +.BI "int sigpause(int " sig "); /* Unix95 */" +.fi +.SH DESCRIPTION +Don't use this function. Use +.BR sigsuspend (2) +instead. +.LP +The function +.B sigpause +is designed to wait for some signal. +It changes the process' signal mask (set of blocked signals), +and then waits for a signal to arrive. +Upon arrival of a signal, the original signal mask is restored. +.SH "RETURN VALUE" +If +.B sigpause +returns, it was interrupted by a signal and the return value is \-1 +with +.I errno +set to +.BR EINTR . +.SH HISTORY +The classical BSD version of this function appeared in 4.2BSD. +It sets the process' signal mask to +.IR sigmask . +When the number of signals was increased above 32, this version +was replaced by the incompatible Unix95 one, which removes only the +specified signal +.I sig +from the process' signal mask. +.\" __xpg_sigpause: Unix 95, spec 1170, SVID, SVR4, XPG +The unfortunate situation with two incompatible functions with the +same name was solved by the +.BR \%sigsuspend (2) +function, that takes a +.B "sigset_t *" +parameter (instead of an int). +.LP +On Linux, this routine is a system call only on the Sparc (sparc64) +architecture. Libc4 and libc5 only know about the BSD version. +Glibc uses the BSD version unless _XOPEN_SOURCE is defined. +.\" .SH NOTE +.\" For the BSD version, one usually uses a zero +.\" .I sigmask +.\" to indicate that no signals are to be blocked. +.SH "SEE ALSO" +.BR kill (2), +.BR sigaction (2), +.BR sigblock (2), +.BR sigprocmask (2), +.BR sigsuspend (2), +.BR sigvec (2) diff --git a/man2/sigpending.2 b/man2/sigpending.2 new file mode 100644 index 000000000..d642d26cf --- /dev/null +++ b/man2/sigpending.2 @@ -0,0 +1 @@ +.so man2/sigaction.2 diff --git a/man2/sigprocmask.2 b/man2/sigprocmask.2 new file mode 100644 index 000000000..d642d26cf --- /dev/null +++ b/man2/sigprocmask.2 @@ -0,0 +1 @@ +.so man2/sigaction.2 diff --git a/man2/sigqueue.2 b/man2/sigqueue.2 new file mode 100644 index 000000000..635e1cf82 --- /dev/null +++ b/man2/sigqueue.2 @@ -0,0 +1,114 @@ +.\" Copyright (c) 2002 Michael Kerrisk +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" added note on self-signalling, aeb, 2002-06-07 +.\" added note on CAP_KILL, mtk, 2004-06-16 +.\" +.TH SIGQUEUE 2 2004-06-16 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +sigqueue \- queue a signal and data to a process +.SH SYNOPSIS +.B #include +.sp +.BI "int sigqueue(pid_t " pid ", int " sig ", const union sigval " value "); +.SH DESCRIPTION +.BR sigqueue () +sends the signal specified in +.I sig +to the process whose PID is given in +.IR pid . +The permissions required to send a signal are the same as for +.BR kill (2). +As with +.BR kill (2), +the null signal (0) can be used to check if a process with a given +PID exists. +.PP +The +.I value +argument is used to specify an accompanying item of data (either an integer +or a pointer value) to be sent with the signal, and has the following type: +.sp +.in +2n +.nf +union sigval { + int sival_int; + void *sival_ptr; +}; +.fi +.in -2n + +If the receiving process has installed a handler for this signal using the +.B SA_SIGINFO +flag to +.BR sigaction (2), +then it can obtain this data via the +.I si_value +field of the +.I siginfo_t +structure passed as the second argument to the handler. +Furthermore, the +.I si_code +field of that structure will be set to +.BR SI_QUEUE . +.SH "RETURN VALUE" +On success, +.BR sigqueue () +returns 0, indicating that the signal was successfully +queued to the receiving proces. +Otherwise \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The limit of signals which may be queued has been reached. +(See +.BR signal (7) +for further information.) +.TP +.B EINVAL +.I sig +was invalid. +.TP +.B EPERM +The process does not have permission to send the signal +to the receiving process. +For the required permissions, see +.BR kill (2). +.TP +.B ESRCH +No process has a PID matching +.IR pid . +.SH NOTES +If this function results in the sending of a signal to the process +that invoked it, and that signal was not blocked by the calling thread, +and no other threads were willing to handle this signal (either by +having it unblocked, or by waiting for it using +.BR sigwait (3)), +then at least some signal must be delivered to this thread before this +function returns. +.SH "CONFORMING TO" +POSIX 1003.1-2001 +.SH "SEE ALSO" +.BR kill (2), +.BR sigaction (2), +.BR signal (2), +.BR sigwait (3), +.BR signal (7) diff --git a/man2/sigreturn.2 b/man2/sigreturn.2 new file mode 100644 index 000000000..2d9c697b5 --- /dev/null +++ b/man2/sigreturn.2 @@ -0,0 +1,64 @@ +.\" Copyright (C) 1995, Thomas K. Dyas +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Created Sat Aug 21 1995 Thomas K. Dyas +.\" Modified Tue Oct 22 22:09:03 1996 by Eric S. Raymond +.\" +.TH SIGRETURN 2 1995-08-21 "Linux 1.3.20" "Linux Programmer's Manual" +.SH NAME +sigreturn \- return from signal handler and cleanup stack frame +.SH SYNOPSIS +.BI "int sigreturn(unsigned long " __unused ); +.SH DESCRIPTION +When the Linux kernel creates the stack frame for a signal handler, a +call to +.B sigreturn +is inserted into the stack frame so that the the signal handler will +call +.B sigreturn +upon return. This inserted call to +.B sigreturn +cleans up the stack so that the process can restart from where it was +interrupted by the signal. +.SH "RETURN VALUE" +.B sigreturn +never returns. +.SH WARNING +The +.B sigreturn +call is used by the kernel to implement signal handlers. It should +.B never +be called directly. Better yet, the specific use of the +.I __unused +argument varies depending on the architecture. +.SH "CONFORMING TO" +.B sigreturn +is specific to Linux and should not be used in programs intended to be +portable. +.SH FILES +/usr/src/linux/arch/i386/kernel/signal.c +.br +/usr/src/linux/arch/alpha/kernel/entry.S +.SH "SEE ALSO" +.BR kill (2), +.BR signal (2), +.BR signal (7) diff --git a/man2/sigsetmask.2 b/man2/sigsetmask.2 new file mode 100644 index 000000000..ebe864f81 --- /dev/null +++ b/man2/sigsetmask.2 @@ -0,0 +1 @@ +.so man2/sigblock.2 diff --git a/man2/sigsuspend.2 b/man2/sigsuspend.2 new file mode 100644 index 000000000..d642d26cf --- /dev/null +++ b/man2/sigsuspend.2 @@ -0,0 +1 @@ +.so man2/sigaction.2 diff --git a/man2/sigtimedwait.2 b/man2/sigtimedwait.2 new file mode 100644 index 000000000..1b13df15d --- /dev/null +++ b/man2/sigtimedwait.2 @@ -0,0 +1 @@ +.so man2/sigwaitinfo.2 diff --git a/man2/sigvec.2 b/man2/sigvec.2 new file mode 100644 index 000000000..86cca9fca --- /dev/null +++ b/man2/sigvec.2 @@ -0,0 +1,47 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Tue Oct 22 22:09:26 1996 by Eric S. Raymond +.\" FIXME -- Error conditions need to be documented +.TH SIGVEC 2 1995-08-31 "Linux 1.3" "Linux Programmer's Manual" +.SH NAME +sigvec \- BSD software signal facilities +.SH SYNOPSIS +.B #include +.sp +.BI "int sigvec(int " sig ", struct sigvec *" vec ", struct sigvec *" ovec ); +.SH DESCRIPTION +This interface is made obsolete by +.BR sigaction (2). +.PP +Under Linux +.B sigvec +is #define'd to +.BR sigaction , +and provides at best a rough approximation of the BSD sigvec interface. +.SH "CONFORMING TO" +BSD, SVr4 +.SH "SEE ALSO" +.BR sigaction (2), +.BR signal (2) diff --git a/man2/sigwaitinfo.2 b/man2/sigwaitinfo.2 new file mode 100644 index 000000000..fa68a1042 --- /dev/null +++ b/man2/sigwaitinfo.2 @@ -0,0 +1,143 @@ +.\" Copyright (c) 2002 Michael kerrisk +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH SIGWAITINFO 2 2002-06-07 "Linux 2.4.18" "Linux Programmer's Manual" +.SH NAME +sigwaitinfo, sigtimedwait \- synchronously wait for queued signals +.SH SYNOPSIS +.B #include +.sp +.BI "int sigwaitinfo(const sigset_t *" set ", siginfo_t *" info ");" +.sp +.BI "int sigtimedwait(const sigset_t *" set ", siginfo_t *" info ", " +.BI "const struct timespec " timeout ");" +.SH DESCRIPTION +.BR sigwaitinfo () +suspends execution of the calling process until one of the signals in +.I set +is delivered. +(If one of the signals in +.I set +is already pending for the calling process, +.BR sigwaitinfo () +will return immediately with information about that signal.) + +.BR sigwaitinfo () +removes the delivered signal from the calling process's list of pending +signals and returns the signal number as its function result. +If the +.I info +argument is not +.BR NULL , +then it returns a structure of type +.I siginfo_t +(see +.BR sigaction (2)) +containing information about the signal. +.PP +Signals returned via +.BR sigwaitinfo () +are delivered in the usual order; see +.BR signal (7) +for further details. +.PP +.BR sigtimedwait () +operates in exactly the same way as +.BR sigwaitinfo () +except that it has an additional argument, +.IR timeout , +which enables an upper bound to be placed on the time for which +the process is suspended. +This argument is of the following type: +.sp +.in +2n +.nf +struct timespec { + long tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +} +.fi +.in -2n +.sp +If both fields of this structure are specified as 0, a poll is performed: +.BR sigtimedwait () +returns immediately, either with information about a signal that +was pending for the caller, or with an error +if none of the signals in +.I set +was pending. +.SH "RETURN VALUE" +On success, both +.BR sigwaitinfo () +and +.BR sigtimedwait () +return a signal number (i.e., a value greater than zero). +On failure both calls return \-1, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +No signal in +.I set +was delivered within the +.I timeout +period specified to +.BR sigtimedwait (). +.TP +.B EINTR +The wait was interrupted by a signal handler. +(This handler was for a signal other than one of those in +.IR set .) +.TP +.B EINVAL +.I timeout +was invalid. +.SH NOTES +In normal usage, the caller blocks the signals in +.I set +via a prior call to +.BR sigprocmask () +(so that the default disposition for these signals does not occur if they +are delivered between successive calls to +.BR sigwaitinfo () or +.BR sigtimedwait()) +and does not establish handlers for these signals. +.PP +POSIX leaves the meaning of a +.B NULL +value for the +.I timeout +argument of +.BR sigtimedwait () +unspecified, permitting the possibility that this has the same meaning +as a call to +.BR sigwaitinfo (), +and indeed this is what is done on Linux. +.SH "CONFORMING TO" +POSIX 1003.1-2001 +.SH "SEE ALSO" +.BR kill (2), +.BR sigaction (2), +.BR signal (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigqueue (2), +.BR sigsetops (3), +.BR signal (7) diff --git a/man2/socket.2 b/man2/socket.2 new file mode 100644 index 000000000..64f332582 --- /dev/null +++ b/man2/socket.2 @@ -0,0 +1,349 @@ +'\" t +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Id: socket.2,v 1.4 1999/05/13 11:33:42 freitag Exp $ +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 1998, 1999 by Andi Kleen +.\" Modified 2002-07-17 by Michael Kerrisk +.\" Modified 2004-06-17 by Michael Kerrisk +.\" +.TH SOCKET 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +socket \- create an endpoint for communication +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int socket(int " domain ", int " type ", int " protocol ); +.SH DESCRIPTION +.B Socket +creates an endpoint for communication and returns a descriptor. +.PP +The +.I domain +parameter specifies a communication domain; this selects the protocol +family which will be used for communication. These families are defined in +.BR . +The currently understood formats include: +.PP +.TS +tab(:); +l l l. +Name:Purpose:Man page +T{ +.B "PF_UNIX,\ PF_LOCAL" +T}:T{ +Local communication +T}:T{ +.BR unix (7) +T} +T{ +.B PF_INET +T}:IPv4 Internet protocols:T{ +.BR ip (7) +T} +T{ +.B PF_INET6 +T}:IPv6 Internet protocols: +T{ +.B PF_IPX +T}:IPX \- Novell protocols: +T{ +.B PF_NETLINK +T}:T{ +Kernel user interface device +T}:T{ +.BR netlink (7) +T} +T{ +.B PF_X25 +T}:ITU-T X.25 / ISO-8208 protocol:T{ +.BR x25 (7) +T} +T{ +.B PF_AX25 +T}:T{ +Amateur radio AX.25 protocol +T}: +T{ +.B PF_ATMPVC +T}:Access to raw ATM PVCs: +T{ +.B PF_APPLETALK +T}:Appletalk:T{ +.BR ddp (7) +T} +T{ +.B PF_PACKET +T}:T{ +Low level packet interface +T}:T{ +.BR packet (7) +T} +.TE +.PP +The socket has the indicated +.IR type , +which specifies the communication semantics. Currently defined types +are: +.TP +.B SOCK_STREAM +Provides sequenced, reliable, two-way, connection-based byte streams. +An out-of-band data transmission mechanism may be supported. +.TP +.B SOCK_DGRAM +Supports datagrams (connectionless, unreliable messages of a fixed +maximum length). +.TP +.B SOCK_SEQPACKET +Provides a sequenced, reliable, two-way connection-based data +transmission path for datagrams of fixed maximum length; a consumer is +required to read an entire packet with each read system call. +.TP +.B SOCK_RAW +Provides raw network protocol access. +.TP +.B SOCK_RDM +Provides a reliable datagram layer that does not guarantee ordering. +.TP +.B SOCK_PACKET +Obsolete and should not be used in new programs; +see +.BR packet (7). +.PP +Some socket types may not be implemented by all protocol families; for example, +.B SOCK_SEQPACKET +is not implemented for +.BR AF_INET . +.PP +The +.I protocol +specifies a particular protocol to be used with the socket. Normally only +a single protocol exists to support a particular socket type within a given +protocol family, in which a case +.I protocol +can be specified as 0. +However, it is possible that many protocols may exist, in +which case a particular protocol must be specified in this manner. The +protocol number to use is specific to the \*(lqcommunication domain\*(rq +in which communication is to take place; see +.BR protocols (5). +See +.BR getprotoent (3) +on how to map protocol name strings to protocol numbers. +.PP +Sockets of type +.B SOCK_STREAM +are full-duplex byte streams, similar to pipes. They do not preserve +record boundaries. A stream socket must be in +a +.I connected +state before any data may be sent or received on it. A connection to +another socket is created with a +.BR connect (2) +call. Once connected, data may be transferred using +.BR read (2) +and +.BR write (2) +calls or some variant of the +.BR send (2) +and +.BR recv (2) +calls. When a session has been completed a +.BR close (2) +may be performed. Out-of-band data may also be transmitted as described in +.BR send (2) +and received as described in +.BR recv (2). +.PP +The communications protocols which implement a +.B SOCK_STREAM +ensure that data is not lost or duplicated. If a piece of data for which +the peer protocol has buffer space cannot be successfully transmitted +within a reasonable length of time, then the connection is considered +to be dead. +When +.B SO_KEEPALIVE +is enabled on the socket the protocol checks in a protocol-specific +manner if the other end is still alive. +A +.B SIGPIPE +signal is raised if a process sends or receives +on a broken stream; this causes naive processes, +which do not handle the signal, to exit. +.B SOCK_SEQPACKET +sockets employ the same system calls as +.B SOCK_STREAM +sockets. The only difference is that +.BR read (2) +calls will return only the amount of data requested, and any remaining in +the arriving packet will be discarded. Also all message boundaries in +incoming datagrams are preserved. +.PP +.B SOCK_DGRAM +and +.B SOCK_RAW +sockets allow sending of datagrams to correspondents named in +.BR send (2) +calls. Datagrams are generally received with +.BR recvfrom (2), +which returns the next datagram with its return address. +.PP +.B SOCK_PACKET +is an obsolete socket type to receive raw packets directly from the +device driver. Use +.BR packet (7) +instead. +.PP +An +.BR fcntl (2) +call with the the +.B F_SETOWN +argument +can be used to specify a process group to receive a +.B SIGURG +signal when the out-of-band data arrives or +.B SIGPIPE +signal when a +.B SOCK_STREAM +connection breaks unexpectedly. +It may also be used to set the process or process group that receives +the I/O and asynchronous notification of I/O events via +.BR SIGIO. +Using +.B F_SETOWN +is equivalent to an +.BR ioctl (2) +call with the +.B FIOSETOWN +or +.B SIOCSPGRP +argument. +.PP +When the network signals an error condition to the protocol module (e.g. +using a ICMP message for IP) the pending error flag is set for the socket. +The next operation on this socket will return the error code of the pending +error. For some protocols it is possible to enable a per-socket error queue +to retrieve detailed information about the error; see +.B IP_RECVERR +in +.BR ip (7) . +.PP +The operation of sockets is controlled by socket level +.IR options . +These options are defined in +.BR . +The functions +.BR setsockopt (2) +and +.BR getsockopt (2) +are used to set and get options, respectively. +.SH "RETURN VALUE" +\-1 is returned if an error occurs; otherwise the return value is a +descriptor referencing the socket. +.SH ERRORS +.TP +.B EACCES +Permission to create a socket of the specified type and/or protocol +is denied. +.TP +.B EAFNOSUPPORT +The implementation does not support the specified address family. +.TP +.B EINVAL +Unknown protocol, or protocol family not available. +.TP +.B EMFILE +Process file table overflow. +.TP +.B ENFILE +The system limit on the total number of open files has been reached. +.TP +.BR ENOBUFS " or " ENOMEM +Insufficient memory is available. The socket cannot be +created until sufficient resources are freed. +.TP +.B EPROTONOSUPPORT +The protocol type or the specified protocol is not +supported within this domain. +.PP +Other errors may be generated by the underlying protocol modules. +.SH "CONFORMING TO" +4.4BSD, SUSv2, POSIX 1003.1-2001. +The +.B socket +function call appeared in 4.2BSD. It is generally portable to/from +non-BSD systems supporting clones of the BSD socket layer (including +System V variants). +.SH NOTE +The manifest constants used under BSD 4.* for protocol families +are PF_UNIX, PF_INET, etc., while AF_UNIX etc. are used for address +families. However, already the BSD man page promises: "The protocol +family generally is the same as the address family", and subsequent +standards use AF_* everywhere. +.SH BUGS +.B SOCK_UUCP +is not implemented yet. +.SH "SEE ALSO" +.BR accept (2), +.BR bind (2), +.BR connect (2), +.BR fcntl (2), +.BR getpeername (2), +.BR getsockname (2), +.BR getsockopt (2), +.BR ioctl (2), +.BR listen (2), +.BR read (2), +.BR recv (2), +.BR select (2), +.BR send (2), +.BR shutdown (2), +.BR socketpair (2), +.BR write (2), +.BR getprotoent (3), +.BR ip (7), +.BR socket (7), +.BR tcp (7), +.BR udp (7), +.BR unix (7) +.PP +\(lqAn Introductory 4.3 BSD Interprocess Communication Tutorial\(rq +is reprinted in +.I UNIX Programmer's Supplementary Documents Volume 1. +.PP +\(lqBSD Interprocess Communication Tutorial\(rq +is reprinted in +.I UNIX Programmer's Supplementary Documents Volume 1. diff --git a/man2/socketcall.2 b/man2/socketcall.2 new file mode 100644 index 000000000..86462721c --- /dev/null +++ b/man2/socketcall.2 @@ -0,0 +1,61 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Tue Oct 22 22:11:53 1996 by Eric S. Raymond +.TH IPC 2 1995-04-15 "Linux 1.2.4" "Linux Programmer's Manual" +.SH NAME +socketcall \- socket system calls +.SH SYNOPSIS +.BI "int socketcall(int" " call, " "unsigned long *" "args);" +.SH DESCRIPTION +.B socketcall +is a common kernel entry point for the socket system calls. +.I call +determines which socket function to invoke. +.I args +points to a block containing the actual arguments, +which are passed through to the appropriate call. +.PP +User programs should call the appropriate functions by their usual names. +Only standard library implementors and kernel hackers need to know about +.BR socketcall . +.SH "CONFORMING TO" +This call is specific to Linux, and should not be used in programs +intended to be portable. +.SH "SEE ALSO" +.BR accept (2), +.BR bind (2), +.BR connect (2), +.BR getpeername (2), +.BR getsockname (2), +.BR getsockopt (2), +.BR listen (2), +.BR recv (2), +.BR recvfrom (2), +.BR send (2), +.BR sendto (2), +.BR setsockopt (2), +.BR shutdown (2), +.BR socket (2), +.BR socketpair (2) diff --git a/man2/socketpair.2 b/man2/socketpair.2 new file mode 100644 index 000000000..864506202 --- /dev/null +++ b/man2/socketpair.2 @@ -0,0 +1,106 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)socketpair.2 6.4 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 2002-07-22 by Michael Kerrisk +.\" Modified 2004-06-17 by Michael Kerrisk +.\" +.TH SOCKETPAIR 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +socketpair \- create a pair of connected sockets +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int socketpair(int " d ", int " type ", int " protocol ", int " sv [2]); +.SH DESCRIPTION +The +.I socketpair +call creates an unnamed pair of connected sockets in +the specified domain +.IR d , +of the specified +.IR type , +and using the optionally specified +.IR protocol . +The descriptors used in referencing the new sockets are returned in +.IR sv [0] +and +.IR sv [1]. +The two sockets are indistinguishable. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EAFNOSUPPORT +The specified address family is not supported on this machine. +.TP +.B EFAULT +The address +.I sv +does not specify a valid part of the process address space. +.TP +.B EMFILE +Too many descriptors are in use by this process. +.TP +.B ENFILE +The system limit on the total number of open files has been reached. +.TP +.B EOPNOTSUPP +The specified protocol does not support creation of socket pairs. +.TP +.B EPROTONOSUPPORT +The specified protocol is not supported on this machine. +.SH "CONFORMING TO" +4.4BSD, SUSv2, POSIX 1003.1-2001. +The +.B socketpair +function call appeared in 4.2BSD. It is generally portable to/from +non-BSD systems supporting clones of the BSD socket layer (including +System V variants). +.SH NOTES +On Linux, the only supported domain for this call is +.BR AF_UNIX +(or synonymously, +.BR AF_LOCAL ). +(Most implementations have the same restriction.) +.SH "SEE ALSO" +.BR pipe (2), +.BR read (2), +.BR socket (2), +.BR write (2), +.BR unix (7) diff --git a/man2/ssetmask.2 b/man2/ssetmask.2 new file mode 100644 index 000000000..b4b6ef50b --- /dev/null +++ b/man2/ssetmask.2 @@ -0,0 +1 @@ +.so man2/signal.2 diff --git a/man2/sstk.2 b/man2/sstk.2 new file mode 100644 index 000000000..7a20da9b8 --- /dev/null +++ b/man2/sstk.2 @@ -0,0 +1,37 @@ +.\" From the 4.3BSD Architecture Manual - BSD copyright +.TH SSTK 2 2003-11-11 "" "BSD planned" +.SH NAME +sstk \- change stack size +.SH SYNOPSIS +caddr_t sstk(int incr); +.SH DESCRIPTION +(From the 4.3BSD Architecture Manual) +.sp +Each process begins execution with three logical areas of memories +called text, data and stack. The text area is read-only and shared, +while the data and stack areas are private to the process. +Both the data and stack areas may be extended and contracted on +program request. The call +.sp +.in +5 +caddr_t addr = sbrk(incr); +.in +.sp +changes the size of the data area by +.I incr +bytes and returns the new end of the data area, while +.sp +.in +5 +caddr_t addr = sstk(incr); +.in +.sp +changes the size of the stack area. The stack area is also automatically +extended as needed. On the VAX the text and data areas are adjacent +in the P0 region, while the stack section is in the P1 region, and +grows downward. +.SH NOTE +This call is not supported in 4.3BSD or 4.4BSD or glibc or Linux or any +other known Unix-like system. Some systems have a routine of this name +that returns ENOSYS. +.SH "SEE ALSO" +.BR sbrk (2) diff --git a/man2/stat.2 b/man2/stat.2 new file mode 100644 index 000000000..6abc60179 --- /dev/null +++ b/man2/stat.2 @@ -0,0 +1,351 @@ +'\" t +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-05-18 by Todd Larason +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 1995-01-09 by Richard Kettlewell +.\" Modified 1998-05-13 by Michael Haardt +.\" Modified 1999-07-06 by aeb & Albert Cahalan +.\" Modified 2000-01-07 by aeb +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH STAT 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +stat, fstat, lstat \- get file status +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.sp +.BI "int stat(const char *" file_name ", struct stat *" buf ); +.br +.BI "int fstat(int " filedes ", struct stat *" buf ); +.br +.BI "int lstat(const char *" file_name ", struct stat *" buf ); +.SH DESCRIPTION +.PP +These functions return information about the specified file. You do +not need any access rights to the file to get this information but you +need search rights to all directories named in the path leading to the +file. +.PP +.B stat +stats the file pointed to by +.I file_name +and fills in +.IR buf . + +.B lstat +is identical to +.BR stat , +except in the case of a symbolic link, where the link itself is stat-ed, +not the file that it refers to. + +.B fstat +is identical to +.BR stat , +only the open file pointed to by +.I filedes +(as returned by +.BR open (2)) +is stat-ed in place of +.IR file_name . + +.PP +They all return a +.I stat +structure, which contains the following fields: +.PP +.RS +.nf +struct stat { + dev_t st_dev; /* device */ + ino_t st_ino; /* inode */ + mode_t st_mode; /* protection */ + nlink_t st_nlink; /* number of hard links */ + uid_t st_uid; /* user ID of owner */ + gid_t st_gid; /* group ID of owner */ + dev_t st_rdev; /* device type (if inode device) */ + off_t st_size; /* total size, in bytes */ + blksize_t st_blksize; /* blocksize for filesystem I/O */ + blkcnt_t st_blocks; /* number of blocks allocated */ + time_t st_atime; /* time of last access */ + time_t st_mtime; /* time of last modification */ + time_t st_ctime; /* time of last status change */ +}; +.fi +.RE +.PP +The value +.I st_size +gives the size of the file (if it is a regular file or a symlink) +in bytes. The size of a symlink is the length of the pathname +it contains, without trailing NUL. + +The value +.I st_blocks +gives the size of the file in 512-byte blocks. +(This may be smaller than +.IR st_size /512 +e.g. when the file has holes.) +The value +.IR st_blksize +gives the "preferred" blocksize for efficient file system I/O. +(Writing to a file in smaller chunks may cause +an inefficient read-modify-rewrite.) +.PP +Not all of the Linux filesystems implement all of the time fields. +Some file system types allow mounting in such a way that file +accesses do not cause an update of the +.I st_atime +field. (See `noatime' in +.BR mount (8).) + +The field +.I st_atime +is changed by file accesses, e.g. by +.BR execve (2), +.BR mknod (2), +.BR pipe (2), +.BR utime (2) +and +.BR read (2) +(of more than zero bytes). Other routines, like +.BR mmap (2), +may or may not update +.IR st_atime . + +The field +.I st_mtime +is changed by file modifications, e.g. by +.BR mknod (2), +.BR truncate (2), +.BR utime (2) +and +.BR write (2) +(of more than zero bytes). +Moreover, +.I st_mtime +of a directory is changed by the creation or deletion of files +in that directory. +The +.I st_mtime +field is +.I not +changed for changes in owner, group, hard link count, or mode. + +The field +.I st_ctime +is changed by writing or by setting inode information +(i.e., owner, group, link count, mode, etc.). +.PP +The following POSIX macros are defined to check the file type: +.RS +.TP 1.2i +S_ISREG(m) +is it a regular file? +.TP +S_ISDIR(m) +directory? +.TP +S_ISCHR(m) +character device? +.TP +S_ISBLK(m) +block device? +.TP +S_ISFIFO(m) +fifo? +.TP +S_ISLNK(m) +symbolic link? (Not in POSIX.1-1996.) +.TP +S_ISSOCK(m) +socket? (Not in POSIX.1-1996.) +.RE +.PP +The following flags are defined for the +.I st_mode +field: +.P +.TS +l l l. +S_IFMT 0170000 bitmask for the file type bitfields +S_IFSOCK 0140000 socket +S_IFLNK 0120000 symbolic link +S_IFREG 0100000 regular file +S_IFBLK 0060000 block device +S_IFDIR 0040000 directory +S_IFCHR 0020000 character device +S_IFIFO 0010000 fifo +S_ISUID 0004000 set UID bit +S_ISGID 0002000 set GID bit (see below) +S_ISVTX 0001000 sticky bit (see below) +S_IRWXU 00700 mask for file owner permissions +S_IRUSR 00400 owner has read permission +S_IWUSR 00200 owner has write permission +S_IXUSR 00100 owner has execute permission +S_IRWXG 00070 mask for group permissions +S_IRGRP 00040 group has read permission +S_IWGRP 00020 group has write permission +S_IXGRP 00010 group has execute permission +S_IRWXO 00007 mask for permissions for others (not in group) +S_IROTH 00004 others have read permission +S_IWOTH 00002 others have write permisson +S_IXOTH 00001 others have execute permission +.TE +.P +The set GID bit (S_ISGID) has several special uses: +For a directory it indicates that BSD semantics is to be used +for that directory: files created there inherit their group ID from +the directory, not from the effective group ID of the creating process, +and directories created there will also get the S_ISGID bit set. +For a file that does not have the group execution bit (S_IXGRP) set, +it indicates mandatory file/record locking. +.P +The `sticky' bit (S_ISVTX) on a directory means that a file +in that directory can be renamed or deleted only by the owner +of the file, by the owner of the directory, and by a privileged +process. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Search permission is denied for one of the directories +in the path prefix of +.IR file_name . +(See also +.BR path_resolution (2).) +.TP +.B EBADF +.I filedes +is bad. +.TP +.B EFAULT +Bad address. +.TP +.B ELOOP +Too many symbolic links encountered while traversing the path. +.TP +.B ENAMETOOLONG +File name too long. +.TP +.B ENOENT +A component of the path +.I file_name +does not exist, or the path is an empty string. +.TP +.B ENOMEM +Out of memory (i.e. kernel memory). +.TP +.B ENOTDIR +A component of the path is not a directory. +.SH "CONFORMING TO" +The +.B stat +and +.B fstat +calls conform to SVr4, SVID, POSIX, X/OPEN, BSD 4.3. The +.B lstat +call conforms to 4.3BSD and SVr4. +SVr4 documents additional +.B fstat +error conditions EINTR, ENOLINK, and EOVERFLOW. SVr4 +documents additional +.B stat +and +.B lstat +error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW. +Use of the +.I st_blocks +and +.I st_blksize +fields may be less portable. (They were introduced in BSD. +Are not specified by POSIX. The interpretation differs between +systems, and possibly on a single system when NFS mounts are involved.) +.LP +POSIX does not describe the S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG, S_IFBLK, +S_IFDIR, S_IFCHR, S_IFIFO, S_ISVTX bits, but instead demands the use of +the macros S_ISDIR(), etc. The S_ISLNK and S_ISSOCK macros are not in +POSIX.1-1996, but both will be in the next POSIX standard; +the former is from SVID 4v2, the latter from SUSv2. +.LP +Unix V7 (and later systems) had S_IREAD, S_IWRITE, S_IEXEC, where POSIX +prescribes the synonyms S_IRUSR, S_IWUSR, S_IXUSR. +.SH "OTHER SYSTEMS" +Values that have been (or are) in use on various systems: +.P +.TS +l l l l l. +hex name ls octal description +f000 S_IFMT 170000 mask for file type +0000 000000 SCO out-of-service inode, BSD unknown type + SVID-v2 and XPG2 have both 0 and 0100000 for ordinary file +1000 S_IFIFO p| 010000 fifo (named pipe) +2000 S_IFCHR c 020000 character special (V7) +3000 S_IFMPC 030000 multiplexed character special (V7) +4000 S_IFDIR d/ 040000 directory (V7) +5000 S_IFNAM 050000 XENIX named special file + with two subtypes, distinguished by st_rdev values 1, 2: +0001 S_INSEM s 000001 XENIX semaphore subtype of IFNAM +0002 S_INSHD m 000002 XENIX shared data subtype of IFNAM +6000 S_IFBLK b 060000 block special (V7) +7000 S_IFMPB 070000 multiplexed block special (V7) +8000 S_IFREG - 100000 regular (V7) +9000 S_IFCMP 110000 VxFS compressed +9000 S_IFNWK n 110000 network special (HP-UX) +a000 S_IFLNK l@ 120000 symbolic link (BSD) +b000 S_IFSHAD 130000 Solaris shadow inode for ACL (not seen by userspace) +c000 S_IFSOCK s= 140000 socket (BSD; also "S_IFSOC" on VxFS) +d000 S_IFDOOR D> 150000 Solaris door +e000 S_IFWHT w% 160000 BSD whiteout (not used for inode) + +0200 S_ISVTX 001000 `sticky bit': save swapped text even after use (V7) + reserved (SVID-v2) + On non-directories: don't cache this file (SunOS) + On directories: restricted deletion flag (SVID-v4.2) +0400 S_ISGID 002000 set group ID on execution (V7) + for directories: use BSD semantics for propagation of gid +0400 S_ENFMT 002000 SysV file locking enforcement (shared w/ S_ISGID) +0800 S_ISUID 004000 set user ID on execution (V7) +0800 S_CDF 004000 directory is a context dependent file (HP-UX) +.TE + +A sticky command appeared in Version 32V AT&T UNIX. + +.SH "SEE ALSO" +.BR chmod (2), +.BR chown (2), +.BR readlink (2), +.BR utime (2), +.BR capabilities (7) diff --git a/man2/statfs.2 b/man2/statfs.2 new file mode 100644 index 000000000..968db0a02 --- /dev/null +++ b/man2/statfs.2 @@ -0,0 +1,243 @@ +.\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 2003-08-17 by Walter Harms +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH STATFS 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +statfs, fstatfs \- get file system statistics +.SH SYNOPSIS +.BR "#include " "/* or */" +.sp +.BI "int statfs(const char *" path ", struct statfs *" buf ); +.br +.BI "int fstatfs(int " fd ", struct statfs *" buf ); +.SH DESCRIPTION +The function +.B statfs +returns information about a mounted file system. +.I path +is the path name of any file within the mounted filesystem. +.I buf +is a pointer to a +.I statfs +structure defined approximately as follows: + +.RS +.nf +struct statfs { + long f_type; /* type of filesystem (see below) */ + long f_bsize; /* optimal transfer block size */ + long f_blocks; /* total data blocks in file system */ + long f_bfree; /* free blocks in fs */ + long f_bavail; /* free blocks avail to non-superuser */ + long f_files; /* total file nodes in file system */ + long f_ffree; /* free file nodes in fs */ + fsid_t f_fsid; /* file system id */ + long f_namelen; /* maximum length of filenames */ +}; + +File system types: + + ADFS_SUPER_MAGIC 0xadf5 + AFFS_SUPER_MAGIC 0xADFF + BEFS_SUPER_MAGIC 0x42465331 + BFS_MAGIC 0x1BADFACE + CIFS_MAGIC_NUMBER 0xFF534D42 + CODA_SUPER_MAGIC 0x73757245 + COH_SUPER_MAGIC 0x012FF7B7 + CRAMFS_MAGIC 0x28cd3d45 + DEVFS_SUPER_MAGIC 0x1373 + EFS_SUPER_MAGIC 0x00414A53 + EXT_SUPER_MAGIC 0x137D + EXT2_OLD_SUPER_MAGIC 0xEF51 + EXT2_SUPER_MAGIC 0xEF53 + EXT3_SUPER_MAGIC 0xEF53 + HFS_SUPER_MAGIC 0x4244 + HPFS_SUPER_MAGIC 0xF995E849 + HUGETLBFS_MAGIC 0x958458f6 + ISOFS_SUPER_MAGIC 0x9660 + JFFS2_SUPER_MAGIC 0x72b6 + JFS_SUPER_MAGIC 0x3153464a + MINIX_SUPER_MAGIC 0x137F /* orig. minix */ + MINIX_SUPER_MAGIC2 0x138F /* 30 char minix */ + MINIX2_SUPER_MAGIC 0x2468 /* minix V2 */ + MINIX2_SUPER_MAGIC2 0x2478 /* minix V2, 30 char names */ + MSDOS_SUPER_MAGIC 0x4d44 + NCP_SUPER_MAGIC 0x564c + NFS_SUPER_MAGIC 0x6969 + NTFS_SB_MAGIC 0x5346544e + OPENPROM_SUPER_MAGIC 0x9fa1 + PROC_SUPER_MAGIC 0x9fa0 + QNX4_SUPER_MAGIC 0x002f + REISERFS_SUPER_MAGIC 0x52654973 + ROMFS_MAGIC 0x7275 + SMB_SUPER_MAGIC 0x517B + SYSV2_SUPER_MAGIC 0x012FF7B6 + SYSV4_SUPER_MAGIC 0x012FF7B5 + TMPFS_MAGIC 0x01021994 + UDF_SUPER_MAGIC 0x15013346 + UFS_MAGIC 0x00011954 + USBDEVICE_SUPER_MAGIC 0x9fa2 + VXFS_SUPER_MAGIC 0xa501FCF5 + XENIX_SUPER_MAGIC 0x012FF7B4 + XFS_SUPER_MAGIC 0x58465342 + _XIAFS_SUPER_MAGIC 0x012FD16D +.fi +.RE +.PP +Nobody knows what +.I f_fsid +is supposed to contain (but see below). +.PP +Fields that are undefined for a particular file system are set to 0. +.B fstatfs +returns the same information about an open file referenced by descriptor +.IR fd . +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +(statfs) +Search permission is denied for a component of the path prefix of +.IR path . +(See also +.BR path_resolution (2).) +.TP +.B EBADF +(fstatfs) +.I fd +is not a valid open file descriptor. +.TP +.B EFAULT +.I buf +or +.I path +points to an invalid address. +.TP +.B EINTR +This call was interrupted by a signal. +.TP +.B EIO +An I/O error occurred while reading from the file system. +.TP +.B ELOOP +(statfs) +Too many symbolic links were encountered in translating +.IR path . +.TP +.B ENAMETOOLONG +(statfs) +.I path +is too long. +.TP +.B ENOENT +(statfs) +The file referred to by +.I path +does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSYS +The file system does not support this call. +.TP +.B ENOTDIR +(statfs) +A component of the path prefix of +.I path +is not a directory. +.TP +.B EOVERFLOW +Some values were too large to be represented in the returned struct. +.PP +.SH "CONFORMING TO" +The Linux +.B statfs +was inspired by the 4.4BSD one +(but they do not use the same structure). +.SH "NOTES ON f_fsid" +Solaris, Irix and POSIX have a system call +.BR statvfs (2) +that returns a +.B "struct statvfs" +(defined in +.IR "" ) +containing an +.B "unsigned long" +.IR f_fsid . +Linux, SunOS, HPUX, 4.4BSD have a system call +.I statfs +that returns a +.B "struct statfs" +(defined in +.IR "" ) +containing a +.B fsid_t +.IR f_fsid , +where +.I fsid_t +is defined as +.BR "struct { int val[2]; }" . +The same holds for FreeBSD, except that it uses the include file +.IR "" . + +The general idea is that +.I f_fsid +contains some random stuff such that the pair +.RI ( f_fsid , ino ) +uniquely determines a file. +Some OSes use (a variation on) the device number, or the device number +combined with the filesystem type. +Several OSes restrict giving out the +.I f_fsid +field to the superuser only (and zero it for nonprivileged users), +because this field is used in the filehandle of the filesystem +when NFS-exported, and giving it out is a security concern. +.LP +Under some OSes the +.I fsid +can be used as second parameter to the +.I sysfs() +system call. +.SH NOTES +The kernel has system calls statfs, fstatfs, statfs64, fstatfs64 +to support this library call. + +Some systems only have , other systems also have +, where the former includes the latter. So it seems +including the former is the best choice. + +LSB has deprecated the library calls +.I [f]statfs() +and tells us to use +.I [f]statvfs() +instead. +.SH "SEE ALSO" +.BR path_resolution (2), +.BR stat (2), +.BR statvfs (2) diff --git a/man2/statvfs.2 b/man2/statvfs.2 new file mode 100644 index 000000000..f56ae9847 --- /dev/null +++ b/man2/statvfs.2 @@ -0,0 +1,176 @@ +.\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" The pathconf note is from Walter Harms +.\" This is not a system call on Linux +.\" +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH STATVFS 2 2003-08-22 "Linux 2.6.0" "Linux Programmer's Manual" +.SH NAME +statvfs, fstatvfs \- get file system statistics +.SH SYNOPSIS +.B #include +.sp +.BI "int statvfs(const char *" path ", struct statvfs *" buf ); +.br +.BI "int fstatvfs(int " fd ", struct statvfs *" buf ); +.SH DESCRIPTION +The function +.B statvfs +returns information about a mounted file system. +.I path +is the path name of any file within the mounted filesystem. +.I buf +is a pointer to a +.I statvfs +structure defined approximately as follows: + +.nf + struct statvfs { + unsigned long f_bsize; /* file system block size */ + unsigned long f_frsize; /* fragment size */ + fsblkcnt_t f_blocks; /* size of fs in f_frsize units */ + fsblkcnt_t f_bfree; /* # free blocks */ + fsblkcnt_t f_bavail; /* # free blocks for non-root */ + fsfilcnt_t f_files; /* # inodes */ + fsfilcnt_t f_ffree; /* # free inodes */ + fsfilcnt_t f_favail; /* # free inodes for non-root */ + unsigned long f_fsid; /* file system id */ + unsigned long f_flag; /* mount flags */ + unsigned long f_namemax; /* maximum filename length */ + }; +.fi + +Here the types +.B fsblkcnt_t +and +.B fsfilcnt_t +are defined in +.IR . +Both used to be +.BR "unsigned long" . + +The field +.I f_flag +is a bit mask (of mount flags, see +.BR mount (8)). +Bits defined by POSIX are +.TP +.B ST_RDONLY +Read-only file system. +.TP +.B ST_NOSUID +Setuid/setgid bits are ignored by +.BR exec (2). +.LP + +It is unspecified whether all members of the returned struct +have meaningful values on all filesystems. + +.B fstatvfs +returns the same information about an open file referenced by descriptor +.IR fd . +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +(statvfs) +Search permission is denied for a component of the path prefix of +.IR path . +(See also +.BR path_resolution (2).) +.TP +.B EBADF +(fstatvfs) +.I fd +is not a valid open file descriptor. +.TP +.B EFAULT +.I Buf +or +.I path +points to an invalid address. +.TP +.B EINTR +This call was interrupted by a signal. +.TP +.B EIO +An I/O error occurred while reading from the file system. +.TP +.B ELOOP +(statvfs) +Too many symbolic links were encountered in translating +.IR path . +.TP +.B ENAMETOOLONG +(statvfs) +.I path +is too long. +.TP +.B ENOENT +(statvfs) +The file referred to by +.I path +does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSYS +The file system does not support this call. +.TP +.B ENOTDIR +(statvfs) +A component of the path prefix of +.I path +is not a directory. +.TP +.B EOVERFLOW +Some values were too large to be represented in the returned struct. +.PP +.SH "CONFORMING TO" +Solaris, Irix, POSIX 1003.1-2001 +.SH NOTES +The Linux kernel has system calls statfs, fstatfs +to support this library call. + +The current glibc implementation of +.sp +.nf + pathconf(path, _PC_REC_XFER_ALIGN); + pathconf(path, _PC_ALLOC_SIZE_MIN); + pathconf(path, _PC_REC_MIN_XFER_SIZE); +.fi +.sp +uses the +.IR f_frsize , +.IR f_frsize , +and +.IR f_bsize +fields of the return value of +.IR "statvfs(path,buf)" . +.SH "SEE ALSO" +.BR statfs (2) diff --git a/man2/stime.2 b/man2/stime.2 new file mode 100644 index 000000000..1cf47c5e8 --- /dev/null +++ b/man2/stime.2 @@ -0,0 +1,68 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 2001-03-16 by Andries Brouwer +.\" Modified 2004-05-27 by Michael Kerrisk +.\" +.TH STIME 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +stime \- set time +.SH SYNOPSIS +.BR "#define _SVID_SOURCE" " /* glibc2 needs this */" +.br +.B #include +.sp +.BI "int stime(time_t *" t ); +.SH DESCRIPTION +\fBstime\fP sets the system's idea of the time and date. Time, pointed +to by \fIt\fP, is measured in seconds from 00:00:00 GMT January 1, 1970. +\fBstime()\fP may only be executed by the super user. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +Error in getting information from user space. +.TP +.B EPERM +The calling process has insufficient privilege. +Under Linux the +.B CAP_SYS_TIME +privilege is required. +.SH "CONFORMING TO" +SVr4, SVID, X/OPEN +.SH NOTES +Under glibc2, +.I +only provides a prototype when +.B _SVID_SOURCE +is defined. +.SH "SEE ALSO" +.BR date (1), +.BR settimeofday (2), +.BR capabilities (7) diff --git a/man2/stty.2 b/man2/stty.2 new file mode 100644 index 000000000..5d25ea6ce --- /dev/null +++ b/man2/stty.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/swapoff.2 b/man2/swapoff.2 new file mode 100644 index 000000000..2bd424c14 --- /dev/null +++ b/man2/swapoff.2 @@ -0,0 +1 @@ +.so man2/swapon.2 diff --git a/man2/swapon.2 b/man2/swapon.2 new file mode 100644 index 000000000..06f64fd08 --- /dev/null +++ b/man2/swapon.2 @@ -0,0 +1,133 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-07-22 by Michael Chastain +.\" Modified 1995-07-23 by aeb +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 1998-09-08 by aeb +.\" Modified 2004-06-17 by Michael Kerrisk +.\" Modified 2004-10-10 by aeb +.\" +.TH SWAPON 2 2004-10-10 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +swapon, swapoff \- start/stop swapping to file/device +.SH SYNOPSIS +.B #include +.br +.B #include /* to find PAGE_SIZE */ +.br +.B #include +.sp +.BI "int swapon(const char *" path ", int " swapflags ); +.br +.BI "int swapoff(const char *" path ); +.SH DESCRIPTION +.B swapon +sets the swap area to the file or block device specified by +.IR path . +.B swapoff +stops swapping to the file or block device specified by +.IR path . +.PP +.B swapon +takes a +.I swapflags +argument. +If +.I swapflags +has the +.I SWAP_FLAG_PREFER +bit turned on, the new swap area will have a higher priority than default. +The priority is encoded as: +.br +.sp +.I " (prio << SWAP_FLAG_PRIO_SHIFT) & SWAP_FLAG_PRIO_MASK" +.br +.PP +These functions may only be used by a privileged process (one having the +.B CAP_SYS_ADMIN +capability). +.SH PRIORITY +Each swap area has a priority, either high or low. +The default priority is low. +Within the low-priority areas, +newer areas are even lower priority than older areas. +.PP +All priorities set with +.I swapflags +are high-priority, higher than default. +They may have any non-negative value chosen by the caller. +Higher numbers mean higher priority. +.PP +Swap pages are allocated from areas in priority order, +highest priority first. +For areas with different priorities, +a higher-priority area is exhausted before using a lower-priority area. +If two or more areas have the same priority, +and it is the highest priority available, +pages are allocated on a round-robin basis between them. +.PP +As of Linux 1.3.6, the kernel usually follows these rules, +but there are exceptions. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +The file +.I path +exists, but refers neither to a regular file nor to a block device. +.TP +.B ENFILE +The system limit on the total number of open files has been reached. +.TP +.B ENOENT +The file +.I path +does not exist. +.TP +.B ENOMEM +The system has insufficient memory to start swapping. +.TP +.B EPERM +The caller does not have the +.B CAP_SYS_ADMIN +capability, or all +.B MAX_SWAPFILES +(earlier 8; 32 since Linux 2.4.10) are in use. +.SH "CONFORMING TO" +These functions are Linux specific and should not be used in programs +intended to be portable. +The second `swapflags' argument was introduced in Linux 1.3.2. +.SH NOTES +The partition or path must be prepared with +.BR mkswap (8). +.SH "SEE ALSO" +.BR mkswap (8), +.BR swapoff (8), +.BR swapon (8) diff --git a/man2/symlink.2 b/man2/symlink.2 new file mode 100644 index 000000000..efcd6af26 --- /dev/null +++ b/man2/symlink.2 @@ -0,0 +1,154 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt, Ian Jackson. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-04-26 by Nick Duffek +.\" Modified 1996-11-06 by Eric S. Raymond +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH SYMLINK 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +symlink \- make a new name for a file +.SH SYNOPSIS +.B #include +.sp +.BI "int symlink(const char *" oldpath ", const char *" newpath ); +.SH DESCRIPTION +.B symlink +creates a symbolic link named +.I newpath +which contains the string +.IR oldpath . + +Symbolic links are interpreted at run-time as if the contents of the +link had been substituted into the path being followed to find a file or +directory. + +Symbolic links may contain +.B .. +path components, which (if used at the start of the link) refer to the +parent directories of that in which the link resides. + +A symbolic link (also known as a soft link) may point to an existing +file or to a nonexistent one; the latter case is known as a dangling +link. + +The permissions of a symbolic link are irrelevant; the ownership is +ignored when following the link, but is checked when removal or +renaming of the link is requested and the link is in a directory with +the sticky bit +.RB ( S_ISVTX ) +set. + +If +.I newpath +exists it will +.I not +be overwritten. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Write access to the directory containing +.I newpath +is denied, or one of the directories in the path prefix of +.IR newpath +did not allow search permission. +(See also +.BR path_resolution (2).) +.TP +.B EEXIST +.I newpath +already exists. +.TP +.B EFAULT +.IR oldpath " or " newpath " points outside your accessible address space." +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR newpath . +.TP +.B ENAMETOOLONG +.IR oldpath " or " newpath " was too long." +.TP +.B ENOENT +A directory component in +.I newpath +does not exist or is a dangling symbolic link, or +.I oldpath +is the empty string. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The device containing the file has no room for the new directory +entry. +.TP +.B ENOTDIR +A component used as a directory in +.IR newpath +is not, in fact, a directory. +.TP +.B EPERM +The filesystem containing +.IR newpath +does not support the creation of symbolic links. +.TP +.B EROFS +.I newpath +is on a read-only filesystem. +.SH NOTES +No checking of +.I oldpath +is done. + +Deleting the name referred to by a symlink will actually delete the +file (unless it also has other hard links). If this behaviour is not +desired, use +.BR link . +.SH "CONFORMING TO" +SVr4, SVID, POSIX, BSD 4.3. SVr4 documents additional error codes +SVr4, SVID, BSD 4.3, X/OPEN. SVr4 documents additional error codes +EDQUOT and ENOSYS. +See +.BR open (2) +re multiple files with the same name, and NFS. +.SH "SEE ALSO" +.BR ln (1), +.BR link (2), +.BR lstat (2), +.BR open (2), +.BR path_resolution (2), +.BR readlink (2), +.BR rename (2), +.BR unlink (2) diff --git a/man2/sync.2 b/man2/sync.2 new file mode 100644 index 000000000..c8b0b1d8c --- /dev/null +++ b/man2/sync.2 @@ -0,0 +1,64 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified Sat Jul 24 12:02:47 1993 by Rik Faith +.\" Modified 15 Apr 1995 by Michael Chastain : +.\" Added reference to `bdflush(2)'. +.\" Modified 960414 by Andries Brouwer : +.\" Added the fact that since 1.3.20 sync actually waits. +.\" Modified Tue Oct 22 22:27:07 1996 by Eric S. Raymond +.\" Modified 2001-10-10 by aeb, following Michael Kerrisk. +.\" +.TH SYNC 2 2001-10-10 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +sync \- commit buffer cache to disk +.SH SYNOPSIS +.B #include +.sp +.B void sync(void); +.SH DESCRIPTION +.B sync +first commits inodes to buffers, and then buffers to disk. +.SH ERRORS +This function is always successful. +.SH "CONFORMING TO" +SVr4, SVID, X/OPEN, BSD 4.3 +.SH BUGS +According to the standard specification (e.g., SVID), +\fBsync()\fP schedules the writes, but may return before the actual +writing is done. +However, since version 1.3.20 Linux does actually wait. +(This still does not guarantee data integrity: modern disks have +large caches.) +.SH NOTES +Since glibc 2.2.2 the Linux prototype is as listed above, +following the various standards. In libc4, libc5, and glibc up to 2.2.1 +it was "int sync(void)", and sync always returned 0. +.SH "SEE ALSO" +.BR bdflush (2), +.BR fdatasync (2), +.BR fsync (2), +.BR sync (8), +.BR update (8) diff --git a/man2/syscall.2 b/man2/syscall.2 new file mode 100644 index 000000000..acc08c8ab --- /dev/null +++ b/man2/syscall.2 @@ -0,0 +1,72 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)syscall.2 8.1 (Berkeley) 6/16/93 +.\" +.\" +.\" 2002-03-20 Christoph Hellwig +.\" - adopted for Linux +.\" +.Dd June 16, 1993 +.Dt SYSCALL 2 +.Os BSD 4 +.Sh NAME +.Nm syscall +.Nd indirect system call +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Ft int +.Fn syscall "int number" "..." +.Sh DESCRIPTION +.Fn Syscall +performs the system call whose assembly language +interface has the specified +.Fa number +with the specified arguments. +Symbolic constants for system calls can be found in the header file +.Ao Pa sys/syscall.h Ac . +.Sh RETURN VALUES +The return value is defined by the system call being invoked. +In general, a 0 return value indicates success. +A -1 return value indicates an error, +and an error code is stored in +.Va errno . +.Sh BUGS +There is no way to simulate system calls that have multiple return values +such as +.Xr pipe 2 . +.Sh HISTORY +The +.Fn syscall +function call appeared in +.Bx 4.0 . +.\" dummy comment without newline \ No newline at end of file diff --git a/man2/syscalls.2 b/man2/syscalls.2 new file mode 100644 index 000000000..1fc0af027 --- /dev/null +++ b/man2/syscalls.2 @@ -0,0 +1,323 @@ +.\" Copyright (C) 1998 Andries Brouwer (aeb@cwi.nl) +.\" Modifications for 2.2 and 2.4 Copyright (C) 2002 Ian Redfern +.\" +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH SYSCALLS 2 2002-01-07 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +none \- list of all system calls +.SH SYNOPSIS +Linux 2.4 system calls. +.SH DESCRIPTION +The system call is the fundamental interface between an application +and the Linux kernel. As of Linux 2.4.17, there are 1100 system calls +listed in +.IR /usr/src/linux/include/asm-*/unistd.h . +This man page lists those that are common to most platforms +(providing hyperlinks if you read this with a browser). + +_llseek(2), +_newselect(2), +_sysctl(2), +accept(2), +access(2), +acct(2), +adjtimex(2), +afs_syscall, +alarm(2), +bdflush(2), +bind(2), +break, +brk(2), +cacheflush(2), +capget(2), +capset(2), +chdir(2), +chmod(2), +chown(2), chown32, +chroot(2), +clone(2), +close(2), +connect(2), +creat(2), +create_module(2), +delete_module(2), +dup(2), +dup2(2), +execve(2), +exit(2), +fchdir(2), +fchmod(2), +fchown(2), fchown32, +fcntl(2), fcntl64, +fdatasync(2), +flock(2), +fork(2), +fstat(2), fstat64, +fstatfs(2), +fsync(2), +ftime, +ftruncate(2), ftruncate64, +get\%_kernel\%_syms(2), +get\%cwd(2), +get\%dents(2), get\%dents64, +get\%egid(2), get\%egid32, +get\%euid(2), get\%euid32, +get\%gid(2), get\%gid32, +get\%groups(2), get\%groups32, +get\%itimer(2), +get\%pagesize(2), +get\%peername(2), +get\%pmsg, +get\%pgid(2), +get\%pgrp(2), +get\%pid(2), +get\%ppid(2), +get\%priority(2), +get\%resgid(2), get\%resgid32, +get\%resuid(2), get\%resuid32, +get\%rlimit(2), +get\%rusage(2), +get\%sid(2), +get\%sockname(2), +get\%sockopt(2), +get\%tid, +get\%timeofday(2), +get\%uid(2), get\%uid32, +gtty, +idle, +init_module(2), +ioctl(2), +io\%perm(2), +iopl(2), +ipc(2), +kill(2), +lchown(2), lchown32, +link(2), +listen(2), +lock, +lseek(2), +lstat(2), lstat64, +madvise(2), +mincore(2), +mkdir(2), +mknod(2), +mlock(2), +mlockall(2), +mmap(2), +modify_ldt(2), +mount(2), +mprotect(2), +mpx, +mremap(2), +msync(2), +munlock(2), +munlockall(2), +munmap(2), +nanosleep(2), +nfsservctl(2), +nice(2), +oldfstat, oldlstat, oldolduname, oldstat, oldumount, olduname, +open(2), +pause(2), +personality(2), +phys, +pipe(2), +pivot_root(2), +poll(2), +prctl(2), +pread(2), +prof, profil, +ptrace(2), +putpmsg, +pwrite(2), +query_module(2), +quotactl(2), +read(2), +readahead, +readdir(2), +readlink(2), +readv(2), +reboot(2), +recv(2), recvfrom(2), recvmsg(2), +rename(2), +rmdir(2), +rt_sigaction, +rt_sigpending, +rt_sigprocmask, +rt_sigqueueinfo, +rt_sigreturn, +rt_sigsuspend, +rt_sigtimedwait, +sched_\%get_\%priority_max(2), +sched_\%get_\%priority_min(2), +sched_\%get\%param(2), +sched_\%get\%scheduler(2), +sched_\%rr_\%get_\%interval(2), +sched_\%set\%param(2), +sched_\%set\%scheduler(2), +sched_\%yield(2), +security, +select(2), +sendfile(2), +send(2), sendmsg(2), sendto(2), +set\%domainname(2), +set\%fsgid(2), set\%fsgid32, +set\%fsuid(2), set\%fsuid32, +set\%gid(2), set\%gid32, +set\%groups(2), set\%groups32, +set\%hostname(2), +set\%itimer(2), +set\%pgid(2), +set\%priority(2), +set\%regid(2), set\%regid32, +set\%resgid(2), set\%resgid32, +set\%resuid(2), set\%resuid32, +set\%reuid(2), set\%reuid32, +set\%rlimit(2), +set\%sid(2), +set\%sockopt(2), +set\%timeofday(2), +set\%uid(2), set\%uid32, +setup(2), +sgetmask(2), +shutdown(2), +sigaction(2), +sigaltstack(2), +signal(2), +sigpending(2), +sigprocmask(2), +sigreturn(2), +sigsuspend(2), +socket(2), +socketcall(2), +socketpair(2), +ssetmask(2), +stat(2), stat64, +statfs(2), +stime(2), +stty, +swapoff(2), +swapon(2), +symlink(2), +sync(2), +sysfs(2), +sysinfo(2), +syslog(2), +time(2), +times(2), +truncate(2), truncate64, +ulimit, +umask(2), +umount(2), +uname(2), +unlink(2), +uselib(2), +ustat(2), +utime(2), +vfork(2), +vhangup(2), +vm86(2), +vm86old, +wait4(2), +waitpid(2), +write(2), +writev(2). + +Of the above, 9 are obsolete, namely +getrlimit, oldfstat, oldlstat, oldolduname, oldstat, olduname, +readdir, select and vm86old +(see also +.BR obsolete (2)), +and 15 are unimplemented in the standard kernel, namely +afs_syscall, break, ftime, getpmsg, gtty, idle, lock, mpx, phys, +prof, profil, putpmsg, security, stty and ulimit (see also +.BR unimplemented (2)). +However, +.BR ftime (3), +.BR profil (3) +and +.BR ulimit (3) +exist as library routines. +The slot for phys is in use since 2.1.116 for umount; +phys will never be implemented. The getpmsg and putpmsg calls are for +kernels patched to support streams, and may never be in the standard +kernel. The security call is for future use. + +Roughly speaking, the code belonging to the system call +with number __NR_xxx defined in +.I /usr/include/asm/unistd.h +can be found in the kernel source in the routine +.IR sys_xxx() . +(The dispatch table for i386 can be found in +.IR /usr/src/linux/arch/i386/kernel/entry.S .) +There are many exceptions, however, mostly because +older system calls were superseded by newer ones, +and this has been treated somewhat unsystematically. On platforms with +proprietary OS emulation, such as parisc, sparc, sparc64 and alpha, +there are many additional system calls; mips64 also contains a full +set of 32-bit system calls. +Below the details for Linux 2.4.17. + +The defines __NR_oldstat and __NR_stat refer to the routines +sys_stat() and sys_newstat(), and similarly for +.I fstat +and +.IR lstat . +Similarly, the defines __NR_oldolduname, __NR_olduname and +__NR_uname refer to the routines sys_olduname(), sys_uname() +and sys_newuname(). +Thus, __NR_stat and __NR_uname have always referred to the latest +version of the system call, and the older ones are for backward +compatibility. + +It is different with +.I select +and +.IR mmap . +These use five or more parameters, and caused problems the way +parameter passing on the i386 used to be set up. Thus, while +other architectures have sys_select() and sys_mmap() corresponding +to __NR_select and __NR_mmap, on i386 one finds old_select() +and old_mmap() (routines that use a pointer to a +parameter block) instead. These days passing five parameters +is not a problem any more, and there is a __NR__newselect (used by +libc 6) that corresponds directly to sys_select() and similarly __NR_mmap2. + +Two other system call numbers, __NR__llseek and __NR__sysctl +have an additional underscore absent in sys_llseek() and sys_sysctl(). + +Then there is __NR_readdir corresponding to old_readdir(), +which will read at most one directory entry at a time, and is +superseded by sys_getdents(). + +On many platforms, including i386, socket calls are all multiplexed +through socketcall() and System V IPC calls through ipc(). + +On newer platforms that only have 64-bit file access and 32-bit uids +(e.g. alpha, ia64, s390x) there are no *64 or *32 calls. Where the *64 +and *32 calls exist, the other versions are obsolete. + +The chown and lchown system calls were swapped in 2.1.81. The *64 and +*32 calls were added for kernel 2.4, as were the new versions of +getrlimit and mmap, and the new calls pivot_root, mincore, madvise, +security, gettid and readahead. diff --git a/man2/sysctl.2 b/man2/sysctl.2 new file mode 100644 index 000000000..1fc101b13 --- /dev/null +++ b/man2/sysctl.2 @@ -0,0 +1,145 @@ +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Written 11 April 1996 by Andries Brouwer +.\" 960412: Added comments from Stephen Tweedie +.\" Modified Tue Oct 22 22:28:41 1996 by Eric S. Raymond +.\" Modified Mon Jan 5 20:31:04 1998 by aeb. +.\" +.TH SYSCTL 2 1996-04-11 "Linux 1.3.85" "Linux Programmer's Manual" +.SH NAME +sysctl \- read/write system parameters +.SH SYNOPSIS +.B #include +.sp +.B #include +.sp +.B #include +.sp +.B _syscall1(int, _sysctl, struct __sysctl_args *, args); +.sp +.BI "int _sysctl(struct __sysctl_args *" args ); +.SH DESCRIPTION +The +.B _sysctl +call reads and/or writes kernel parameters. For example, the hostname, +or the maximum number of open files. The argument has the form +.PP +.nf +struct __sysctl_args { + int *name; /* integer vector describing variable */ + int nlen; /* length of this vector */ + void *oldval; /* 0 or address where to store old value */ + size_t *oldlenp; /* available room for old value, + overwritten by actual size of old value */ + void *newval; /* 0 or address of new value */ + size_t newlen; /* size of new value */ +}; +.fi +.PP +This call does a search in a tree structure, possibly resembling +a directory tree under +.BR /proc/sys , +and if the requested item is found calls some appropriate routine +to read or modify the value. + +.SH EXAMPLE +.nf +#include +#include +#include + +_syscall1(int, _sysctl, struct __sysctl_args *, args); +int sysctl(int *name, int nlen, void *oldval, size_t *oldlenp, + void *newval, size_t newlen) +{ + struct __sysctl_args args={name,nlen,oldval,oldlenp,newval,newlen}; + return _sysctl(&args); +} + +#define SIZE(x) sizeof(x)/sizeof(x[0]) +#define OSNAMESZ 100 + +char osname[OSNAMESZ]; +int osnamelth; +int name[] = { CTL_KERN, KERN_OSTYPE }; + +main(){ + osnamelth = sizeof(osname); + if (sysctl(name, SIZE(name), osname, &osnamelth, 0, 0)) + perror("sysctl"); + else + printf("This machine is running %*s\en", osnamelth, osname); + return 0; +} +.fi + +.SH "RETURN VALUE" +Upon successful completion, +.B _sysctl +returns 0. Otherwise, a value of \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +The invocation asked for the previous value by setting +.I oldval +non-NULL, but allowed zero room in +.IR oldlenp . +.TP +.B ENOTDIR +.I name +was not found. +.TP +.B EPERM +No search permission for one of the encountered `directories', +or no read permission where +.I oldval +was nonzero, or no write permission where +.I newval +was nonzero. +.SH "CONFORMING TO" +This call is Linux-specific, and should not be used in programs +intended to be portable. +A +.B sysctl +call has been present in Linux since version 1.3.57. It originated in +4.4BSD. Only Linux has the +.I /proc/sys +mirror, and the object naming schemes differ between Linux and BSD 4.4, +but the declaration of the +.BR sysctl (2) +function is the same in both. +.SH BUGS +The object names vary between kernel versions. +THIS MAKES THIS SYSTEM CALL WORTHLESS FOR APPLICATIONS. +Use the +.I /proc/sys +interface instead. +.br +Not all available objects are properly documented. +.br +It is not yet possible to change operating system by writing to +.IR /proc/sys/kernel/ostype . +.SH "SEE ALSO" +.BR proc (5) diff --git a/man2/sysfs.2 b/man2/sysfs.2 new file mode 100644 index 000000000..c3ebc4cdd --- /dev/null +++ b/man2/sysfs.2 @@ -0,0 +1,103 @@ +.\" Copyright (C) 1995, Thomas K. Dyas +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Created Wed Aug 9 1995 Thomas K. Dyas +.\" +.\" FIXME -- I can't find this in SVr4! +.TH SYSFS 2 1995-08-09 "Linux 1.3.16" "Linux Programmer's Manual" +.SH NAME +sysfs \- get file system type information +.SH SYNOPSIS +.BI "int sysfs(int " option ", const char *" fsname ); + +.BI "int sysfs(int " option ", unsigned int " fs_index ", char *" buf ); + +.BI "int sysfs(int " option ); +.SH DESCRIPTION +.B sysfs +returns information about the file system types currently present in +the kernel. The specific form of the +.B sysfs +call and the information returned depends on the +.I option +in effect: + +.TP +.B 1 +Translate the file-system identifier string +.I fsname +into a file-system type index. +.TP +.B 2 +Translate the file-system type index +.I fs_index +into a NUL-terminated file-system identifier string. This string will +be written to the buffer pointed to by +.IR buf . +Make sure that +.I buf +has enough space to accept the string. +.TP +.B 3 +Return the total number of file system types currently present in the +kernel. + +.PP +The numbering of the file-system type indexes begins with zero. +.SH "RETURN VALUE" +On success, +.B sysfs +returns the file-system index for option +.BR 1 , +zero for option +.BR 2 , +and the number of currently configured file systems for option +.BR 3 . +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.RI "Either " fsname " or " buf +is outside your accessible address space. +.TP +.B EINVAL +.I fsname +is not a valid file-system type identifier; +.I fs_index +is out-of-bounds; +.I option +is invalid. +.PP +.SH "CONFORMING TO" +SVr4. +.SH NOTE +On Linux with the +.I proc +filesystem mounted on +.IR /proc , +the same information can be derived from +.IR /proc/filesystems . +.SH BUGS +There is no libc or glibc support. +There is no way to guess how large \fIbuf\fP should be. diff --git a/man2/sysinfo.2 b/man2/sysinfo.2 new file mode 100644 index 000000000..a2ec8e9f3 --- /dev/null +++ b/man2/sysinfo.2 @@ -0,0 +1,88 @@ +.\" -*- nroff -*- +.\" +.\" (C)opyright 1993 by Dan Miner (dminer@nyx.cs.du.edu) +.\" +.\" Permission is granted to freely distribute or modify this file +.\" for the purpose of improving Linux or its documentation efforts. +.\" If you modify this file, please put a date stamp and HOW you +.\" changed this file. Thanks. -DM +.\" +.\" Modified Sat Jul 24 12:35:12 1993 by Rik Faith +.\" Modified Tue Oct 22 22:29:51 1996 by Eric S. Raymond +.\" Modified Mon Aug 25 16:06:11 1997 by Nicolás Lichtmaier +.\" +.TH SYSINFO 2 1997-08-25 "Linux 2.0" "Linux Programmer's Manual" +.SH NAME +sysinfo \- returns information on overall system statistics +.SH SYNOPSIS +.B #include +.sp +.BI "int sysinfo(struct sysinfo *" info ); +.SH DESCRIPTION +Until Linux 2.3.16, +.B sysinfo +used to return information in the following structure: + +.RS +.nf +struct sysinfo { + long uptime; /* Seconds since boot */ + unsigned long loads[3]; /* 1, 5, and 15 minute load averages */ + unsigned long totalram; /* Total usable main memory size */ + unsigned long freeram; /* Available memory size */ + unsigned long sharedram; /* Amount of shared memory */ + unsigned long bufferram; /* Memory used by buffers */ + unsigned long totalswap; /* Total swap space size */ + unsigned long freeswap; /* swap space still available */ + unsigned short procs; /* Number of current processes */ + char _f[22]; /* Pads structure to 64 bytes */ +}; +.fi +.RE + +and the sizes were given in bytes. Since Linux 2.3.23 (i386), 2.3.48 +(all architectures) the structure is + +.RS +.nf +struct sysinfo { + long uptime; /* Seconds since boot */ + unsigned long loads[3]; /* 1, 5, and 15 minute load averages */ + unsigned long totalram; /* Total usable main memory size */ + unsigned long freeram; /* Available memory size */ + unsigned long sharedram; /* Amount of shared memory */ + unsigned long bufferram; /* Memory used by buffers */ + unsigned long totalswap; /* Total swap space size */ + unsigned long freeswap; /* swap space still available */ + unsigned short procs; /* Number of current processes */ + unsigned long totalhigh; /* Total high memory size */ + unsigned long freehigh; /* Available high memory size */ + unsigned int mem_unit; /* Memory unit size in bytes */ + char _f[20-2*sizeof(long)-sizeof(int)]; /* Padding for libc5 */ +}; +.fi +.RE + +and the sizes are given as multiples of \fImem_unit\fP bytes. + +.B sysinfo +provides a simple way of getting overall system statistics. This is more +portable than reading \fI/dev/kmem\fP. +For an example of its use, see intro(2). +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +pointer to \fIstruct\ sysinfo\fP is invalid +.SH "CONFORMING TO" +This function is Linux-specific, and should not be used in programs +intended to be portable. +.sp +The Linux kernel has a sysinfo system call since 0.98.pl6. +Linux libc contains a sysinfo() routine since 5.3.5, and +glibc has one since 1.90. +.SH "SEE ALSO" +.BR proc (5) diff --git a/man2/syslog.2 b/man2/syslog.2 new file mode 100644 index 000000000..672102ca8 --- /dev/null +++ b/man2/syslog.2 @@ -0,0 +1,182 @@ +.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Written 11 June 1995 by Andries Brouwer +.TH SYSLOG 2 2001-11-25 "Linux 1.2.9" "Linux Programmer's Manual" +.SH NAME +syslog, klogctl \- read and/or clear kernel message ring buffer; set console_loglevel +.SH SYNOPSIS +.nf +/* The glibc interface */ +.br +.B "#include " +.sp +.BI "int klogctl(int " type ", char *" bufp ", int " len ); +.sp +/* The handcrafted system call */ +.br +.B #include +.br +.B #include +.sp +.B _syscall3(int, syslog, int, type, char *, bufp, int, len); +.sp +.BI "int syslog(int " type ", char *" bufp ", int " len ); +.fi +.SH DESCRIPTION +If you need the libc function +.BR syslog() , +(that talks to +.BR syslogd (8)), +then look at +.BR syslog (3). +The system call of this name is about controlling the kernel +.I printk() +buffer, and the glibc version is called +.BR klogctl() . + +The \fItype\fP argument determines the action taken by this function. + +Quoting from +.IR kernel/printk.c : +.nf +/* + * Commands to sys_syslog: + * + * 0 -- Close the log. Currently a NOP. + * 1 -- Open the log. Currently a NOP. + * 2 -- Read from the log. + * 3 -- Read up to the last 4k of messages in the ring buffer. + * 4 -- Read and clear last 4k of messages in the ring buffer + * 5 -- Clear ring buffer. + * 6 -- Disable printk's to console + * 7 -- Enable printk's to console + * 8 -- Set level of messages printed to console + * 9 -- Return number of unread characters in the log buffer + */ +.fi + +Only function 3 is allowed to non-root processes. +(Function 9 was added in 2.4.10.) + +.B The kernel log buffer +.br +The kernel has a cyclic buffer of length LOG_BUF_LEN +(4096, since 1.3.54: 8192, since 2.1.113: 16384; in recent kernels +the size can be set at compile time) in which messages given as argument +to the kernel function \fIprintk\fP() are stored +(regardless of their loglevel). + +The call +.B syslog +.RI (2, buf , len ) +waits until this kernel log buffer is nonempty, and then reads +at most \fIlen\fP bytes into the buffer \fIbuf\fP. It returns +the number of bytes read. Bytes read from the log disappear from +the log buffer: the information can only be read once. +This is the function executed by the kernel when a user program +reads +.IR /proc/kmsg . + +The call +.B syslog +.RI (3, buf , len ) +will read the last \fIlen\fP bytes from the log buffer (nondestructively), +but will not read more than was written into the buffer since the +last `clear ring buffer' command (which does not clear the buffer at all). +It returns the number of bytes read. + +The call +.B syslog +.RI (4, buf , len ) +does precisely the same, but also executes the `clear ring buffer' command. + +The call +.B syslog +.RI (5, dummy , idummy ) +only executes the `clear ring buffer' command. + +.B The loglevel +.br +The kernel routine \fIprintk\fP() will only print a message on the +console, if it has a loglevel less than the value of the variable +.I console_loglevel +(initially DEFAULT_CONSOLE_LOGLEVEL (7), but set to 10 if the +kernel commandline contains the word `debug', and to 15 in case +of a kernel fault - the 10 and 15 are just silly, and equivalent to 8). +This variable is set (to a value in the range 1-8) by the call +.B syslog +.RI (8, dummy , value ). +The calls +.B syslog +.RI ( type , dummy , idummy ) +with \fItype\fP equal to 6 or 7, set it to 1 (kernel panics only) +or 7 (all except debugging messages), respectively. + +Every text line in a message has its own loglevel. This level is +DEFAULT_MESSAGE_LOGLEVEL - 1 (6) unless the line starts with +where \fId\fP is a digit in the range 1-7, in which case the level +is \fId\fP. The conventional meaning of the loglevel is defined in +.I +as follows: + +.nf +#define KERN_EMERG "<0>" /* system is unusable */ +#define KERN_ALERT "<1>" /* action must be taken immediately */ +#define KERN_CRIT "<2>" /* critical conditions */ +#define KERN_ERR "<3>" /* error conditions */ +#define KERN_WARNING "<4>" /* warning conditions */ +#define KERN_NOTICE "<5>" /* normal but significant condition */ +#define KERN_INFO "<6>" /* informational */ +#define KERN_DEBUG "<7>" /* debug-level messages */ +.fi + +.SH "RETURN VALUE" +In case of error, \-1 is returned, and \fIerrno\fP is set. Otherwise, +for \fItype\fP equal to 2, 3 or 4, \fBsyslog\fP() returns the number +of bytes read, and otherwise 0. +.SH ERRORS +.TP +.B EINVAL +Bad parameters. +.TP +.B EPERM +An attempt was made to change console_loglevel or clear the kernel +message ring buffer by a process without root permissions. +.TP +.B ERESTARTSYS +System call was interrupted by a signal - nothing was read. +(This can be seen only during a trace.) +.SH "CONFORMING TO" +This system call is Linux specific and should not be used in programs +intended to be portable. +.SH NOTES +From the very start people noted that it is unfortunate that +kernel call and library routine of the same name are entirely +different animals. +In libc4 and libc5 the number of this call was defined by +.BR SYS_klog . +In glibc 2.0 the syscall is baptised +.BR klogctl . + +.SH "SEE ALSO" +.BR syslog (3) diff --git a/man2/tgkill.2 b/man2/tgkill.2 new file mode 100644 index 000000000..82fc2d6af --- /dev/null +++ b/man2/tgkill.2 @@ -0,0 +1 @@ +.so man2/tkill.2 diff --git a/man2/time.2 b/man2/time.2 new file mode 100644 index 000000000..e64254581 --- /dev/null +++ b/man2/time.2 @@ -0,0 +1,76 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified Sat Jul 24 14:13:40 1993 by Rik Faith +.\" Additions by Joseph S. Myers , 970909 +.\" +.TH TIME 2 1997-09-09 "Linux 2.0.30" "Linux Programmer's Manual" +.SH NAME +time \- get time in seconds +.SH SYNOPSIS +.B #include +.sp +.BI "time_t time(time_t *" t ); +.SH DESCRIPTION +\fBtime\fP returns the time since the Epoch +(00:00:00 UTC, January 1, 1970), measured in seconds. + +If +.I t +is non-NULL, +the return value is also stored in the memory pointed to by +.IR t . +.SH "RETURN VALUE" +On success, the value of time in seconds since the Epoch is returned. +On error, ((time_t)\-1) is returned, and \fIerrno\fP is set +appropriately. +.SH ERRORS +.TP +.B EFAULT +.I t +points outside your accessible address space. +.SH NOTES +POSIX.1 defines +.I seconds since the Epoch +as a value to be interpreted as the number of seconds between a +specified time and the Epoch, according to a formula for conversion +from UTC equivalent to conversion on the naïve basis that leap +seconds are ignored and all years divisible by 4 are leap years. This +value is not the same as the actual number of seconds between the time +and the Epoch, because of leap seconds and because clocks are not +required to be synchronised to a standard reference. The intention is +that the interpretation of seconds since the Epoch values be +consistent; see POSIX.1 Annex B 2.2.2 for further rationale. +.SH "CONFORMING TO" +SVr4, SVID, POSIX, X/OPEN, BSD 4.3 +.br +Under BSD 4.3, this call is obsoleted by +.BR gettimeofday (2). +POSIX does not specify any error conditions. +.SH "SEE ALSO" +.BR date (1), +.BR gettimeofday (2), +.BR ctime (3), +.BR ftime (3) diff --git a/man2/times.2 b/man2/times.2 new file mode 100644 index 000000000..f0ebee887 --- /dev/null +++ b/man2/times.2 @@ -0,0 +1,153 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt (michael@moria.de) +.\" Modified Sat Jul 24 14:29:17 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 961203 and 001211 and 010326 by aeb@cwi.nl +.\" Modified 001213 by Michael Haardt (michael@moria.de) +.\" Modified 13 Jun 02, Michael Kerrisk +.\" Added note on non-standard behaviour when SIGCHLD is ignored. +.\" +.TH TIMES 2 2002-06-14 "Linux" "Linux Programmer's Manual" +.SH NAME +times \- get process times +.SH SYNOPSIS +.B #include +.sp +.BI "clock_t times(struct tms *" buf ); +.SH DESCRIPTION +The +.BR times () +function stores the current process times in the +.B "struct tms" +that +.IR buf +points to. +The +.I struct tms +is as defined in +.IR : +.sp +.nf +struct tms { +.RS +clock_t tms_utime; /* user time */ +clock_t tms_stime; /* system time */ +clock_t tms_cutime; /* user time of children */ +clock_t tms_cstime; /* system time of children */ +.RE +}; +.fi +.LP +The +.I tms_utime +field contains the CPU time spent executing instructions +of the calling process. +The +.I tms_stime +field contains the CPU time spent in the system while +executing tasks on behalf of the calling process. +The +.I tms_cutime +field contains the sum of the +.I tms_utime +and +.I tms_cutime +values for all waited-for terminated children. +The +.I tms_cstime +field contains the sum of the +.I tms_stime +and +.I tms_cstime +values for all waited-for terminated children. +.LP +Times for terminated children (and their descendants) +is added in at the moment +.BR wait (2) +or +.BR waitpid (2) +returns their process ID. In particular, times of grandchildren +that the children did not wait for are never seen. +.LP +All times reported are in clock ticks. +.SH "RETURN VALUE" +The function +.B times +returns the number of clock ticks that have elapsed since +an arbitrary point in the past. For Linux this point is +the moment the system was booted. +This return value may overflow the possible range of type clock_t. +On error, (clock_t) \-1 is returned, and +.I errno +is set appropriately. +.SH NOTES +The number of clock ticks per second can be obtained using +.RS +sysconf(_SC_CLK_TCK); +.RE +In POSIX-1996 the symbol CLK_TCK (defined in +.IR ) +is mentioned as obsolescent. It is obsolete now. +.PP +On Linux, if the disposition of SIGCHLD is set to +.B SIG_IGN +then the times of terminated children +are automatically included in the +.I tms_cstime +and +.I tms_cutime +fields, although POSIX 1003.1-2001 says that this should only happen +if the calling process +.BR wait ()s +on its children. +.\" See the description of times() in XSH, which says: +.\" The times of a terminated child process are included... when wait() +.\" or waitpid() returns the process ID of this termianted child. +.LP +Note that +.BR clock (3) +returns values of type clock_t that are not measured in clock ticks +but in CLOCKS_PER_SEC. +.SH "CONFORMING TO" +SVr4, SVID, POSIX, X/OPEN, BSD 4.3 +.SH "HISTORICAL NOTES" +SVr1-3 returns +.B long +and the struct members are of type +.B time_t +although they store clock ticks, not seconds since the epoch. V7 used +.B long +for the struct members, because it had no type +.B time_t +yet. +.PP +On older systems the number of clock ticks per second is given +by the variable HZ. +.SH "SEE ALSO" +.BR time (1), +.BR getrusage (2), +.BR wait (2), +.BR clock (3), +.BR sysconf (3) diff --git a/man2/tkill.2 b/man2/tkill.2 new file mode 100644 index 000000000..774c0bb66 --- /dev/null +++ b/man2/tkill.2 @@ -0,0 +1,81 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 2003 Abhijit Menon-Sen +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" 2004-05-31, added tgkill, ahu, aeb +.\" +.TH TKILL 2 "2004-05-31" "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +tkill, tgkill \- send a signal to a single process +.SH SYNOPSIS +.nf +.B #include +.br +.B #include +.sp +.B "_syscall2(int, tkill, int, tid, int, sig)" +.sp +.B int tkill(int tid, int sig); +.sp +.B "_syscall3(int, tkill, int, tgid, int, tid, int, sig)" +.sp +.B int tgkill(int tgid, int tid, int sig); +.fi +.SH DESCRIPTION +The \fBtkill\fP system call is analogous to +.BR kill (2), +except when the specified process is part of a thread group +(created by specifying the CLONE_THREAD flag in the call to clone). +Since all the processes in a thread group have the same PID, +they cannot be individually signalled with \fBkill\fP. +With \fBtkill\fP, however, one can address each process +by its unique TID. +.PP +The \fBtgkill\fP call improves on \fBtkill\fP by allowing the caller to +specify the thread group ID of the thread to be signalled, protecting +against TID reuse. If the tgid is specified as \-1, \fBtgkill\fP degenerates +into \fBtkill\fP. +.PP +These are the raw system call interfaces, meant for internal +thread library use. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and \fIerrno\fP +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +An invalid TID or signal was specified. +.TP +.B EPERM +Permission denied. For the required permissions, see +.BR kill (2). +.TP +.B ESRCH +No process with the specified thread ID (and thread group ID) exists. +.SH "CONFORMING TO" +\fBtkill\fP and \fBtgkill\fP are Linux specific and should not be used +in programs that are intended to be portable. +\fBtkill\fP is supported since Linux 2.4.19 / 2.5.4. +\fBtgkill\fP was added in Linux 2.5.75. +.SH "SEE ALSO" +.BR gettid (2), +.BR kill (2) diff --git a/man2/truncate.2 b/man2/truncate.2 new file mode 100644 index 000000000..27c6fe152 --- /dev/null +++ b/man2/truncate.2 @@ -0,0 +1,185 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)truncate.2 6.9 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 1998-12-21 by Andries Brouwer +.\" Modified 2002-01-07 by Michael Kerrisk +.\" Modified 2002-04-06 by Andries Brouwer +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH TRUNCATE 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +truncate, ftruncate \- truncate a file to a specified length +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int truncate(const char *" path ", off_t " length ); +.br +.BI "int ftruncate(int " fd ", off_t " length ); +.SH DESCRIPTION +The +.B truncate +and +.B ftruncate +functions cause the regular file named by +.I path +or referenced by +.I fd +to be truncated to a size of precisely +.I length +bytes. +.LP +If the file previously was larger than this size, the extra data is lost. +If the file previously was shorter, it is extended, and +the extended part reads as zero bytes. +.LP +The file pointer is not changed. +.LP +If the size changed, then the ctime and mtime fields for the file +are updated, and suid and sgid mode bits may be cleared. +.LP +With +.BR ftruncate , +the file must be open for writing; with +.BR truncate , +the file must be writable. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +For +.BR truncate : +.TP +.B EACCES +Search permission is denied for a component of the path prefix, +or the named file is not writable by the user. +(See also +.BR path_resolution (2).) +.TP +.B EFAULT +.I Path +points outside the process's allocated address space. +.TP +.B EFBIG +The argument +.I length +is larger than the maximum file size. (XSI) +.TP +.B EINTR +A signal was caught during execution. +.TP +.B EINVAL +The argument +.I length +is negative or larger than the maximum file size. +.TP +.B EIO +An I/O error occurred updating the inode. +.TP +.B EISDIR +The named file is a directory. +.TP +.B ELOOP +Too many symbolic links were encountered in translating the pathname. +.TP +.B ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.TP +.B ENOENT +The named file does not exist. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.TP +.B EROFS +The named file resides on a read-only file system. +.TP +.B ETXTBSY +The file is a pure procedure (shared text) file that is being executed. +.PP +For +.B ftruncate +the same errors apply, but instead of things that can be wrong with +.IR path , +we now have things that can be wrong with +.IR fd : +.TP +.B EBADF +The +.I fd +is not a valid descriptor. +.TP +.BR EBADF " or " EINVAL +The +.I fd +is not open for writing. +.TP +.B EINVAL +The +.I fd +does not reference a regular file. +.SH "CONFORMING TO" +4.4BSD, SVr4 (these function calls first appeared in BSD 4.2). +POSIX 1003.1-1996 has +.BR ftruncate . +POSIX 1003.1-2001 also has +.IR truncate , +as an XSI extension. +.LP +SVr4 documents additional +.B truncate +error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK. SVr4 documents for +.B ftruncate +an additional EAGAIN error condition. +.SH NOTES +The above description is for XSI-compliant systems. +For non-XSI-compliant systems, the POSIX standard allows +two behaviours for +.B ftruncate +when +.I length +exceeds the file length +(note that +.B truncate +is not specified at all in such an environment): +either returning an error, or extending the file. +(Most Unices follow the XSI requirement.) +.\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002 +.SH "SEE ALSO" +.BR open (2), +.BR path_resolution (2) diff --git a/man2/umask.2 b/man2/umask.2 new file mode 100644 index 000000000..a01f18a3b --- /dev/null +++ b/man2/umask.2 @@ -0,0 +1,61 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified Sat Jul 24 12:51:53 1993 by Rik Faith +.\" Modified Tue Oct 22 22:39:04 1996 by Eric S. Raymond +.\" Modified Thu May 1 06:05:54 UTC 1997 by Nicolás Lichtmaier +.\" with Lars Wirzenius suggestion +.TH UMASK 2 1998-08-09 "Linux" "Linux Programmer's Manual" +.SH NAME +umask \- set file creation mask +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "mode_t umask(mode_t " mask ); +.SH DESCRIPTION +.B umask +sets the umask to +.I mask +& 0777. + +The umask is used by +.BR open (2) +to set initial file permissions on a newly-created file. +Specifically, permissions in the umask are turned off from +the \fBmode\fR argument to +.BR open (2) +(so, for example, the common umask default value of 022 results in new +files being created with permissions 0666 & ~022 = 0644 = rw-r--r-- +in the usual case where the \fBmode\fR is specified as 0666). +.SH "RETURN VALUE" +This system call always succeeds and the previous value of the mask +is returned. +.SH "CONFORMING TO" +SVr4, SVID, POSIX, X/OPEN, BSD 4.3 +.SH "SEE ALSO" +.BR creat (2), +.BR open (2) diff --git a/man2/umount.2 b/man2/umount.2 new file mode 100644 index 000000000..373253092 --- /dev/null +++ b/man2/umount.2 @@ -0,0 +1 @@ +.so man2/mount.2 diff --git a/man2/umount2.2 b/man2/umount2.2 new file mode 100644 index 000000000..373253092 --- /dev/null +++ b/man2/umount2.2 @@ -0,0 +1 @@ +.so man2/mount.2 diff --git a/man2/uname.2 b/man2/uname.2 new file mode 100644 index 000000000..5850b79bb --- /dev/null +++ b/man2/uname.2 @@ -0,0 +1,122 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH UNAME 2 2001-12-15 "Linux 2.5.0" "Linux Programmer's Manual" +.SH NAME +uname \- get name and information about current kernel +.SH SYNOPSIS +.B #include +.sp +.BI "int uname(struct utsname *" buf ); +.SH DESCRIPTION +.B uname +returns system information in the structure pointed to by +.IR buf . +The +.I utsname +struct is defined in +.IR : +.RS +.nf +struct utsname { +.in +8 +char sysname[]; +char nodename[]; +char release[]; +char version[]; +char machine[]; +.in -8 +#ifdef _GNU_SOURCE +.in +8 +char domainname[]; +.in -8 +#endif +}; +.fi +.RE +The length of the arrays in a +.I struct utsname +is unspecified; the fields are NUL-terminated. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.I buf +is not valid. +.SH "CONFORMING TO" +SVr4, SVID, POSIX, X/OPEN. +There is no +.B uname +call in BSD 4.3. +.PP +The +.I domainname +member (the NIS or YP domain name) is a GNU extension. +.SH NOTES +This is a system call, and the operating system presumably knows +its name, release and version. It also knows what hardware it runs on. +So, four of the fields of the struct are meaningful. +On the other hand, the field \fInodename\fP is meaningless: +it gives the name of the present machine in some undefined +network, but typically machines are in more than one network +and have several names. Moreover, the kernel has no way of knowing +about such things, so it has to be told what to answer here. +The same holds for the additional \fIdomainname\fP field. +.LP +To this end Linux uses the system calls +.BR sethostname (2) +and +.BR setdomainname (2). +Note that there is no standard that says that the hostname set by +.BR sethostname (2) +is the same string as the \fInodename\fP field of the struct returned by +.B uname +(indeed, some systems allow a 256-byte hostname and an 8-byte nodename), +but this is true on Linux. The same holds for +.BR setdomainname (2) +and the \fIdomainname\fP field. +.LP +The length of the fields in the struct varies. Some operating systems +or libraries use a hardcoded 9 or 33 or 65 or 257. Other systems use +SYS_NMLN or _SYS_NMLN or UTSLEN or _UTSNAME_LENGTH. Clearly, it is a bad +idea to use any of these constants - just use sizeof(...). +Often 257 is chosen in order to have room for an internet hostname. +.LP +There have been three Linux system calls \fIuname\fP(). The first one +used length 9, the second one used 65, the third one also uses 65 but +adds the \fIdomainname\fP field. +.LP +Part of the utsname information is also accessible via +.I sysctl +and via +.IR /proc/sys/kernel/ { ostype , +.IR hostname , +.IR osrelease , +.IR version , +.IR domainname }. +.SH "SEE ALSO" +.BR uname (1), +.BR getdomainname (2), +.BR gethostname (2) diff --git a/man2/undocumented.2 b/man2/undocumented.2 new file mode 100644 index 000000000..f610f053e --- /dev/null +++ b/man2/undocumented.2 @@ -0,0 +1,24 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" This page is in the public domain. +.\" +.TH UNIMPLEMENTED 2 2003-02-01 "Linux 2.4.20" "Linux Programmer's Manual" +.SH NAME +madvise1, +rt_sigaction, +rt_sigpending, +rt_sigprocmask, +rt_sigqueueinfo, +rt_sigreturn, +rt_sigsuspend, +rt_sigtimedwait, +ugetrlimit +\- undocumented system calls +.SH SYNOPSIS +Undocumented system calls. +.SH DESCRIPTION +The 2.4.20 kernel knows 253 syscalls for the i386 architecture. +The above ones have not yet been documented. +.SH "SEE ALSO" +.BR obsolete (2), +.BR syscalls (2), +.BR unimplemented (2) diff --git a/man2/unimplemented.2 b/man2/unimplemented.2 new file mode 100644 index 000000000..d9a5aea18 --- /dev/null +++ b/man2/unimplemented.2 @@ -0,0 +1,64 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Updated, aeb, 980612 +.\" +.TH UNIMPLEMENTED 2 2003-02-28 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +afs_syscall, break, ftime, getpmsg, gtty, lock, mpx, prof, profil, +putpmsg, security, stty, ulimit \- unimplemented system calls +.SH SYNOPSIS +Unimplemented system calls. +.SH DESCRIPTION +These system calls are not implemented in the Linux 2.4 kernel. +.SH "RETURN VALUE" +These system calls always return \-1 and set +.I errno +to +.BR ENOSYS . +.SH NOTES +Note that +.IR ftime (3), +.IR profil (3) +and +.IR ulimit (3) +are implemented as library functions. + +Some system calls, like +.IR alloc_hugepages (2), +.IR free_hugepages (2), +.IR ioperm (2), +.IR iopl (2), +and +.IR vm86 (2) +only exist on certain architectures. + +Some system calls, like +.IR ipc (2) +and +.IR {create,init,delete}_module (2) +only exist when the Linux kernel was built with support for them. + +.SH "SEE ALSO" +.BR obsolete (2) diff --git a/man2/unlink.2 b/man2/unlink.2 new file mode 100644 index 000000000..901d8b139 --- /dev/null +++ b/man2/unlink.2 @@ -0,0 +1,149 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Ian Jackson. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-09-08 by Arnt Gulbrandsen +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2001-05-17 by aeb +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH UNLINK 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +unlink \- delete a name and possibly the file it refers to +.SH SYNOPSIS +.B #include +.sp +.BI "int unlink(const char *" pathname ); +.SH DESCRIPTION +.B unlink +deletes a name from the filesystem. If that name was the +last link to a file and no processes have the file open the file is +deleted and the space it was using is made available for reuse. + +If the name was the last link to a file but any processes still have +the file open the file will remain in existence until the last file +descriptor referring to it is closed. + +If the name referred to a symbolic link the link is removed. + +If the name referred to a socket, fifo or device the name for it is +removed but processes which have the object open may continue to use +it. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Write access to the directory containing +.I pathname +is not allowed for the process's effective UID, or one of the +directories in +.IR pathname +did not allow search permission. +(See also +.BR path_resolution (2).) +.TP +.BR EBUSY " (not on Linux)" +The file +.I pathname +cannot be unlinked because it is being used by the system +or another process and the implementation considers this an error. +.TP +.B EFAULT +.I pathname +points outside your accessible address space. +.TP +.B EIO +An I/O error occurred. +.TP +.B EISDIR +.I pathname +refers to a directory. +(This is the non-POSIX value returned by Linux since 2.1.132.) +.TP +.B ELOOP +Too many symbolic links were encountered in translating +.IR pathname . +.TP +.B ENAMETOOLONG +.IR pathname " was too long." +.TP +.B ENOENT +A component in +.I pathname +does not exist or is a dangling symbolic link, or +.I pathname +is empty. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component used as a directory in +.I pathname +is not, in fact, a directory. +.TP +.B EPERM +The system does not allow unlinking of directories, +or unlinking of directories requires privileges that the +current process doesn't have. +(This is the POSIX prescribed error return.) +.TP +.BR EPERM " (Linux only)" +The filesystem does not allow unlinking of files. +.TP +.BR EPERM " or " EACCES +The directory containing +.I pathname +has the sticky bit +.RB ( S_ISVTX ) +set and the process's effective UID is neither the UID of the file to +be deleted nor that of the directory containing it, and +the process is not privileged (Linux: does not have the +.B CAP_FOWNER +capability). +.TP +.B EROFS +.I pathname +refers to a file on a read-only filesystem. +.SH "CONFORMING TO" +SVr4, SVID, POSIX, X/OPEN, 4.3BSD. SVr4 documents additional error +conditions EINTR, EMULTIHOP, ETXTBSY, ENOLINK. +.SH BUGS +Infelicities in the protocol underlying NFS can cause the unexpected +disappearance of files which are still being used. +.SH "SEE ALSO" +.BR rm (1), +.BR chmod (2), +.BR link (2), +.BR mknod (2), +.BR open (2), +.BR path_resolution (2), +.BR rename (2), +.BR rmdir (2), +.BR mkfifo (3), +.BR remove (3) diff --git a/man2/uselib.2 b/man2/uselib.2 new file mode 100644 index 000000000..91c3287f7 --- /dev/null +++ b/man2/uselib.2 @@ -0,0 +1,77 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH USELIB 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +uselib \- select shared library +.SH SYNOPSIS +.B #include +.sp +.BI "int uselib(const char *" library ); +.SH DESCRIPTION +\fBuselib\fP selects the shared library binary that will be used by +the calling process. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +In addition to all of the error codes returned by +.BR open (2) +and +.BR mmap (2), +the following may also be returned: + +.TP +.B EACCES +The library specified by +.I library +is not readable, or the caller does not have search permission +for one of the directories in the path prefix. (See also +.BR path_resolution (2).) +.TP +.B ENFILE +The system limit on the total number of open files has been reached. +.TP +.B ENOEXEC +The file specified by +.I library +is not executable, or does not have the correct magic numbers. +.SH "CONFORMING TO" +\fBuselib()\fP is Linux specific, and should not be used in programs +intended to be portable. +.SH "SEE ALSO" +.BR ar (1), +.BR gcc (1), +.BR ld (1), +.BR ldd (1), +.BR mmap (2), +.BR open (2), +.BR capability (7), +.BR ld.so (8) diff --git a/man2/ustat.2 b/man2/ustat.2 new file mode 100644 index 000000000..89cfec50b --- /dev/null +++ b/man2/ustat.2 @@ -0,0 +1,109 @@ +.\" Copyright (C) 1995, Thomas K. Dyas +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Created 1995-08-09 Thomas K. Dyas +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2001-03-22 by aeb +.\" Modified 2003-08-04 by aeb +.\" +.TH USTAT 2 2003-08-04 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +ustat \- get file system statistics +.SH SYNOPSIS +.nf +.B #include +.br +.BR "#include " " /* libc[45] */" +.br +.BR "#include " " /* glibc2 */" +.sp +.BI "int ustat(dev_t " dev ", struct ustat *" ubuf ); +.SH DESCRIPTION +.B ustat +returns information about a mounted file system. +.I dev +is a device number identifying a device containing +a mounted file system. +.I ubuf +is a pointer to a ustat structure that contains the following +members: + +.sp +.RS +.nf +.ne 7 +.ta 8n 16n 32n +daddr_t f_tfree; /* Total free blocks */ +ino_t f_tinode; /* Number of free inodes */ +char f_fname[6]; /* Filsys name */ +char f_fpack[6]; /* Filsys pack name */ +.ta +.fi +.RE +.PP + +The last two fields, f_fname and f_fpack, are not implemented and will +always be filled with NUL characters. +.SH "RETURN VALUE" +On success, zero is returned and the ustat structure pointed to by +.I ubuf +will be filled in. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.I ubuf +points outside of your accessible address space. +.TP +.B EINVAL +.I dev +does not refer to a device containing a mounted file system. +.TP +.B ENOSYS +The mounted file system referenced by +.I dev +does not support this operation, or any version of Linux before +1.3.16. +.SH "CONFORMING TO" +SVr4. SVr4 documents additional error conditions ENOLINK, ECOMM, and EINTR +but has no ENOSYS condition. +.SH NOTES +.B ustat +is deprecated and has only been provided for compatibility. +All new programs should use +.BR statfs (2) +instead. +.SH "HP NOTES" +The HP version of struct ustat has an additional field +.I f_blksize +that is unknown elsewhere. HP warns: +For some file systems, the number of free inodes does not change. +Such file systems will return -1 in the field +.IR f_tinode . +.\" Some software tries to use this in order to test whether the +.\" underlying filesystem is NFS. +For some file systems, inodes are dynamically allocated. +Such file systems will return the current number of free inodes. +.SH "SEE ALSO" +.BR stat (2), +.BR statfs (2) diff --git a/man2/utime.2 b/man2/utime.2 new file mode 100644 index 000000000..865f09ae7 --- /dev/null +++ b/man2/utime.2 @@ -0,0 +1,161 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-06-10 by Andries Brouwer +.\" Modified 2004-06-23 by Michael Kerrisk +.\" Modified 2004-10-10 by Andries Brouwer +.\" +.TH UTIME 2 2004-10-10 "Linux 2.6.8" "Linux Programmer's Manual" +.SH NAME +utime, utimes \- change access and/or modification times of an inode +.SH SYNOPSIS +.nf +.B #include +.br +.B #include +.sp +.BI "int utime(const char *" filename ", const struct utimbuf *" buf ); +.sp 2 +.B #include +.sp +.BI "int utimes(const char *" filename ", const struct timeval " tv [2]); +.fi +.SH DESCRIPTION +.B utime +changes the access and modification times of the inode specified by +.I filename +to the +.IR actime " and " modtime +fields of +.I buf +respectively. + +If +.I buf +is NULL, then the access and modification times of the file are set +to the current time. + +Changing time stamps is permitted when: either +the process has appropriate privileges (Linux: has the +.B CAP_FOWNER +capability), or the effective user ID equals the user ID +of the file, or +.I buf +must is NULL and the process has write permission to the file. + +The +.I utimbuf +structure is: + +.RS +.nf +struct utimbuf { + time_t actime; /* access time */ + time_t modtime; /* modification time */ +}; +.fi +.RE + +The function +.B utime +allows specification of time stamps with a resolution of 1 second. +The function +.B utimes +is similar, but allows a resolution of 1 microsecond. +Here +.IR tv [0] +refers to access time, and +.IR tv [1] +to modification time. + +The +.I timeval +structure is: + +.RS +.nf +struct timeval { + long tv_sec; /* seconds */ + long tv_usec; /* microseconds */ +}; +.fi +.RE +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Search permission is denied for one of the directories in +the path prefix of +.I path +(see also +.BR path_resolution (2)), +or +.I buf +is NULL and the process does not have permission to change the time stamps +(see above). +.TP +.B ENOENT +.I filename +does not exist. +.TP +.B EPERM +.I buf +is not NULL and the process does not have permission to change the time stamps. +.TP +.B EROFS +.I path +resides on a read-only file system. +.SH NOTES +Linux does not allow changing the time stamps on an immutable file, +or setting the time stamps to something other than the current time +on an append-only file. + +In libc4 and libc5, +.B utimes +is just a wrapper for +.B utime +and hence does not allow a subsecond resolution. + +POSIX calls +.B utimes +legacy. +.SH BUGS +Linux is not careful to distinguish between the EACCES and EPERM error returns. +On the other hand, POSIX 1003.1-2003 is buggy in its error description for +.BR utimes . +.SH "CONFORMING TO" +.BR utime : +SVr4, SVID, POSIX. SVr4 documents additional error conditions EFAULT, +EINTR, ELOOP, EMULTIHOP, ENAMETOOLONG, ENOLINK, ENOLINK, ENOTDIR. +.br +.BR utimes : +BSD 4.3 +.SH "SEE ALSO" +.BR chattr (1), +.BR stat (2) diff --git a/man2/utimes.2 b/man2/utimes.2 new file mode 100644 index 000000000..04372d49b --- /dev/null +++ b/man2/utimes.2 @@ -0,0 +1 @@ +.so man2/utime.2 diff --git a/man2/vfork.2 b/man2/vfork.2 new file mode 100644 index 000000000..4c951b636 --- /dev/null +++ b/man2/vfork.2 @@ -0,0 +1,181 @@ +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl), 1 Nov 1999 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" 1999-11-10: Merged text taken from the page contributed by +.\" Reed H. Petty (rhp@draper.net) +.\" +.TH VFORK 2 1999-11-01 "Linux 2.2.0" "Linux Programmer's Manual" +.SH NAME +vfork \- create a child process and block parent +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.B pid_t vfork(void); +.SH "STANDARD DESCRIPTION" +(From XPG4 / SUSv2 / POSIX draft.) +The +.IR vfork () +function has the same effect as +.IR fork (), +except that the behaviour is undefined if the process created by +.IR vfork () +either modifies any data other than a variable of type pid_t used +to store the return value from +.IR vfork (), +or returns from the function in which +.IR vfork () +was called, or calls any other function before successfully calling +.IR _exit () +or one of the +.I exec +family of functions. +.SH ERRORS +.TP +.B EAGAIN +Too many processes - try again. +.TP +.B ENOMEM +There is insufficient swap space for the new process. +.SH "LINUX DESCRIPTION" +.BR vfork , +just like +.BR fork (2), +creates a child process of the calling process. +For details and return value and errors, see +.BR fork (2). +.PP +.B vfork() +is a special case of +.BR clone (2). +It is used to create new processes without copying the page tables of +the parent process. It may be useful in performance sensitive applications +where a child will be created which then immediately issues an +.IR execve() . +.PP +.B vfork() +differs from fork in that the parent is suspended until the child makes +a call to +.BR execve (2) +or +.BR _exit (2). +The child shares all memory with its parent, including the stack, until +.I execve() +is issued by the child. The child must not return from the +current function or call +.IR exit() , +but may call +.IR _exit() . +.PP +Signal handlers are inherited, but not shared. Signals to the parent +arrive after the child releases the parent. +.SH "HISTORIC DESCRIPTION" +Under Linux, +.IR fork () +is implemented using copy-on-write pages, so the only penalty incurred by +.IR fork () +is the time and memory required to duplicate the parent's page tables, +and to create a unique task structure for the child. +However, in the bad old days a +.IR fork() +would require making a complete copy of the caller's data space, +often needlessly, since usually immediately afterwards an +.IR exec () +is done. Thus, for greater efficiency, BSD introduced the +.B vfork +system call, that did not fully copy the address space of +the parent process, but borrowed the parent's memory and thread +of control until a call to +.IR execve () +or an exit occurred. The parent process was suspended while the +child was using its resources. +The use of vfork was tricky - for example, not modifying data +in the parent process depended on knowing which variables are +held in a register. +.SH BUGS +It is rather unfortunate that Linux revived this spectre from the past. +The BSD manpage states: +"This system call will be eliminated when proper system sharing mechanisms +are implemented. Users should not depend on the memory sharing semantics of +.I vfork +as it will, in that case, be made synonymous to +.IR fork .\c +" + +Formally speaking, the standard description given above does not allow +one to use +.IR vfork () +since a following +.IR exec +might fail, and then what happens is undefined. + +Details of the signal handling are obscure and differ between systems. +The BSD manpage states: +"To avoid a possible deadlock situation, processes that are children +in the middle of a +.I vfork +are never sent SIGTTOU or SIGTTIN signals; rather, output or +.IR ioctl s +are allowed and input attempts result in an end-of-file indication." + +Currently (Linux 2.3.25), +.BR strace (1) +cannot follow +.IR vfork() +and requires a kernel patch. +.SH HISTORY +The +.IR vfork () +system call appeared in 3.0BSD. +.\" In the release notes for BSD 4.2 Sam Leffler wrote: `vfork: Is still +.\" present, but definitely on its way out'. +In BSD 4.4 it was made synonymous to +.IR fork (), +but NetBSD introduced it again, +cf. http://www.netbsd.org/Documentation/kernel/vfork.html . +In Linux, it has been equivalent to +.IR fork () +until 2.2.0-pre6 or so. Since 2.2.0-pre9 (on i386, somewhat later on +other architectures) it is an independent system call. Support was +added in glibc 2.0.112. +.SH "CONFORMING TO" +The +.B vfork +call may be a bit similar to calls with the same name in other +operating systems. The requirements put on +.B vfork +by the standards are weaker than those put on +.BR fork , +so an implementation where the two are synonymous +is compliant. In particular, the programmer cannot +rely on the parent remaining blocked until a call of +.I execve() +or +.I _exit() +and cannot rely on any specific behaviour w.r.t. shared memory. +.\" In AIXv3.1 vfork is equivalent to fork. +.SH "SEE ALSO" +.BR clone (2), +.BR execve (2), +.BR fork (2), +.BR wait (2) diff --git a/man2/vhangup.2 b/man2/vhangup.2 new file mode 100644 index 000000000..d0453ab80 --- /dev/null +++ b/man2/vhangup.2 @@ -0,0 +1,55 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH VHANGUP 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +vhangup \- virtually hangup the current tty +.SH SYNOPSIS +.B #include +.sp +.B int vhangup(void); +.SH DESCRIPTION +.B vhangup +simulates a hangup on the current terminal. This call arranges for other +users to have a \*(lqclean\*(rq tty at login time. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR vhangup ; +the +.B CAP_SYS_TTY_CONFIG +capability is required. +.SH "CONFORMING TO" +This call is Linux-specific, and should not be used in programs +intended to be portable. +.SH "SEE ALSO" +.BR capabilities (7), +.BR init (8) diff --git a/man2/vm86.2 b/man2/vm86.2 new file mode 100644 index 000000000..6709d5467 --- /dev/null +++ b/man2/vm86.2 @@ -0,0 +1,69 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Copyright 1997 Andries E. Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH VM86 2 1997-07-17 "Linux 2.1.15" "Linux Programmer's Manual" +.SH NAME +vm86old, vm86 \- enter virtual 8086 mode +.SH SYNOPSIS +.B #include +.sp +.BI "int vm86old(struct vm86_struct *" info ); +.sp +.BI "int vm86(unsigned long " fn ", struct vm86plus_struct *" v86 ); +.SH DESCRIPTION +The system call +.B vm86 +was introduced in Linux 0.97p2. In Linux 2.1.15 and 2.0.28 it was renamed to +.BR vm86old , +and a new +.B vm86 +was introduced. The definition of `struct vm86_struct' was changed +in 1.1.8 and 1.1.9. +.LP +These calls cause the process to enter VM86 mode (virtual-8086 in Intel +literature), and are used by +.BR dosemu . +.PP +VM86 mode is an emulation of real mode within a protected mode task. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +This return value is specific to i386 and indicates a problem with getting +userspace data. +.TP +.B ENOSYS +This return value indicates the call is not implemented on the present +architecture. +.TP +.B EPERM +Saved kernel stack exists. (This is a kernel sanity check; the saved +stack should only exist within vm86 mode itself.) +.SH "CONFORMING TO" +This call is specific to Linux on Intel processors, and should not be +used in programs intended to be portable. diff --git a/man2/wait.2 b/man2/wait.2 new file mode 100644 index 000000000..7689dc5be --- /dev/null +++ b/man2/wait.2 @@ -0,0 +1,265 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" +.\" Modified Sat Jul 24 13:30:06 1993 by Rik Faith +.\" Modified Sun Aug 21 17:42:42 1994 by Rik Faith +.\" (Thanks to Koen Holtman ) +.\" Modified Wed May 17 15:54:12 1995 by Rik Faith +.\" To remove *'s from status in macros (Thanks to Michael Shields). +.\" Modified as suggested by Nick Duffek , aeb, 960426 +.\" Modified Mon Jun 23 14:09:52 1997 by aeb - add EINTR. +.\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff. +.\" Modified Mon Jul 24 21:37:38 2000 by David A. Wheeler +.\" - noted thread issues. +.\" Modified 26 Jun 01 by Michael Kerrisk +.\" Added __WCLONE, __WALL, and __WNOTHREAD descriptions +.\" Modified 2001-09-25, aeb +.\" Modified 26 Jun 01 by Michael Kerrisk, +.\" Updated notes on setting disposition of SIGCHLD to SIG_IGN +.\" +.TH WAIT 2 2000-07-24 "Linux" "Linux Programmer's Manual" +.SH NAME +wait, waitpid \- wait for process termination +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "pid_t wait(int *" "status" ); +.br +.BI "pid_t waitpid(pid_t " pid ", int *" status ", int " options ); +.SH DESCRIPTION +The +.B wait +function suspends execution of the current process until a child has +exited, or until a signal is delivered whose action is to terminate +the current process or to call a signal handling function. If a child +has already exited by the time of the call (a so\-called "zombie" +process), the function returns immediately. Any system resources used +by the child are freed. + +The +.B waitpid +function suspends execution of the current process until a +child as specified by the +.I pid +argument has exited, or until a signal is delivered whose action is to +terminate the current process or to call a signal handling function. +If a child as requested by +.I pid +has already exited by the time of the call (a so\-called "zombie" +process), the function returns immediately. Any system resources used +by the child are freed. + +The value of +.I pid +can be one of: +.IP "< \-1" +which means to wait for any child process whose process group ID is +equal to the absolute value of +.IR pid . +.IP \-1 +which means to wait for any child process; this is the same +behaviour which +.B wait +exhibits. +.IP 0 +which means to wait for any child process whose process group ID is +equal to that of the calling process. +.IP "> 0" +which means to wait for the child whose process ID is equal to the +value of +.IR pid . +.PP +The value of +.I options +is an OR of zero or more of the following constants: +.TP +.B WNOHANG +which means to return immediately if no child has exited. +.TP +.B WUNTRACED +which means to also return for children which are stopped +(but not traced), and whose status has not been reported. +Status for traced children which are stopped is provided +also without this option. +.PP +(For Linux-only options, see below.) +.PP +If +.I status +is not +.BR NULL , +.B wait +or +.B waitpid +store status information in the location pointed to by +.IR status . + +This status can be evaluated with the following macros (these macros take +the stat buffer (an \fBint\fR) as an argument \(em not a pointer to the +buffer!): +.TP +.BI WIFEXITED( status ) +returns true if the child terminated normally, that is, +by calling exit() or _exit(), or by returning from main(). +.TP +.BI WEXITSTATUS( status ) +evaluates to the least significant eight bits of the return code of +the child which terminated, which may have been set as the argument to +a call to exit() or _exit() or as the argument for a return statement +in the main program. This macro can only be evaluated if +.B WIFEXITED +returned true. +.TP +.BI WIFSIGNALED( status ) +returns true if the child process terminated because of a signal +which was not caught. +.TP +.BI WTERMSIG( status ) +returns the number of the signal that caused the child process to +terminate. This macro can only be evaluated if +.B WIFSIGNALED +returned non\-zero. +.TP +.BI WIFSTOPPED( status ) +returns true if the child process which caused the return is currently +stopped; this is only possible if the call was done using +.BR WUNTRACED +or when the child is being traced (see +.BR ptrace (2)). +.TP +.BI WSTOPSIG( status ) +returns the number of the signal which caused the child to stop. This +macro can only be evaluated if +.B WIFSTOPPED +returned non\-zero. +.LP +Some versions of Unix (e.g. Linux, Solaris, but not AIX, SunOS) +also define a macro +.BI WCOREDUMP( status ) +to test whether the child process dumped core. Only use this +enclosed in #ifdef WCOREDUMP ... #endif. +.SH "RETURN VALUE" +The process ID of the child which exited, or zero if +.B WNOHANG +was used and no child was available, or \-1 on error (in which case +.I errno +is set to an appropriate value). +.SH ERRORS +.TP +.BR ECHILD " (for " wait ) +The calling process does not have any unwaited-for children. +.TP +.BR ECHILD " (for " waitpid ) +The process specified in +.I pid +does not exist or is not a child of the calling process. +(This can happen for one's own child if the action for SIGCHLD +is set to SIG_IGN. See also the LINUX NOTES section about threads.) +.TP +.B EINTR +.B WNOHANG +was not set and an unblocked signal or a +.B SIGCHLD +was caught. +.TP +.B EINVAL +The +.I options +argument was invalid. +.SH NOTES +The Single Unix Specification describes a flag SA_NOCLDWAIT (not supported +under Linux) such that if either this flag is set, or the action for +SIGCHLD is set to SIG_IGN +then children that exit do not become zombies and a call to +.BR wait () +or +.BR waitpid () +will block until all children have exited, and then fail with +.I errno +set to ECHILD. +.LP +The original POSIX standard left the behaviour of setting SIGCHLD to +SIG_IGN unspecified. +Later standards, including SUSv2 and POSIX 1003.1-2001 specify the +behaviour just described as an XSI-compliance option. +Linux does not conform to the second of the two points just described: +if a +.BR wait "() or " waitpid () +call is made while SIGCHLD is being ignored, +the call behaves just as though SIGCHLD were not being igored, that is, +the call blocks until the next child terminates and then returns the +PID and status of that child. +.SH "LINUX NOTES" +In the Linux kernel, a kernel-scheduled thread is not a distinct +construct from a process. Instead, a thread is simply a process +that is created using the Linux-unique +.BR clone (2) +system call; other routines such as the portable +.BR pthread_create (3) +call are implemented using +.BR clone (2). +Before Linux 2.4, a thread was just a special case of a process, +and as a consequence one thread could not wait on the children +of another thread, even when the latter belongs to the same thread group. +However, POSIX prescribes such functionality, and since Linux 2.4 +a thread can, and by default will, wait on children of other threads +in the same thread group. +.LP +The following Linux-specific +.I options +are for use with children created using +.BR clone (2). +.TP +.B __WCLONE +.\" since 0.99pl10 +Wait for "clone" children only. If omitted then wait +for "non-clone" children only. (A "clone" child is one +which delivers no signal, or a signal other than +.B SIGCHLD +to its parent upon termination.) +This option is ignored if +.B __WALL +is also specified. +.TP +.B __WALL +.\" since patch-2.3.48 +(Since Linux 2.4) Wait for all children, regardless of +type ("clone" or "non-clone"). +.TP +.B __WNOTHREAD +.\" since patch-2.4.0-test8 +(Since Linux 2.4) Do not wait for children of other threads in +the same thread group. This was the default before Linux 2.4. +.SH "CONFORMING TO" +SVr4, POSIX.1 +.SH "SEE ALSO" +.BR clone (2), +.BR ptrace (2), +.BR signal (2), +.BR wait4 (2), +.BR pthread_create (3), +.BR signal (7) diff --git a/man2/wait3.2 b/man2/wait3.2 new file mode 100644 index 000000000..097794b11 --- /dev/null +++ b/man2/wait3.2 @@ -0,0 +1 @@ +.so man2/wait4.2 diff --git a/man2/wait4.2 b/man2/wait4.2 new file mode 100644 index 000000000..90ef0848c --- /dev/null +++ b/man2/wait4.2 @@ -0,0 +1,209 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" +.\" Modified Sat Jul 24 13:32:44 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Jun 23 14:09:52 1997 by aeb - add EINTR. +.\" Modified Tue Jul 7 12:26:42 1998 by aeb - changed return value wait3 +.\" +.TH WAIT4 2 1997-06-23 "Linux" "Linux Programmer's Manual" +.SH NAME +wait3, wait4 \- wait for process termination, BSD style +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.B #include +.sp 2 +.BI "pid_t wait3(int *" "status" ", int " options , +.BI " struct rusage *" rusage ); +.sp +.BI "pid_t wait4(pid_t " pid ", int *" status ", int " options , +.BI " struct rusage *" rusage ); +.fi +.SH DESCRIPTION +The +.B wait3 +function suspends execution of the current process until a child has +exited, or until a signal is delivered whose action is to terminate +the current process or to call a signal handling function. If a child +has already exited by the time of the call (a so\-called "zombie" +process), the function returns immediately. Any system resources used +by the child are freed. + +The +.B wait4 +function suspends execution of the current process until a +child as specified by the +.I pid +argument has exited, or until a signal is delivered whose action is to +terminate the current process or to call a signal handling function. +If a child as requested by +.I pid +has already exited by the time of the call (a so\-called "zombie" +process), the function returns immediately. Any system resources used +by the child are freed. + +The value of +.I pid +can be one of: +.IP "< \-1" +which means to wait for any child process whose process group ID is +equal to the absolute value of +.IR pid . +.IP \-1 +which means to wait for any child process; this is equivalent to +calling +.BR wait3 . +.IP 0 +which means to wait for any child process whose process group ID is +equal to that of the calling process. +.IP "> 0" +which means to wait for the child whose process ID is equal to the +value of +.IR pid . +.PP +The value of +.I options +is a bitwise OR of zero or more of the following constants: +.TP +.B WNOHANG +which means to return immediately if no child is there to be waited +for. +.TP +.B WUNTRACED +which means to also return for children which are stopped, and whose +status has not been reported. +.PP +If +.I status +is not +.BR NULL , +.B wait3 +or +.B wait4 +store status information in the location pointed to by +.IR status . +.PP +This status can be evaluated with the following macros (these macros take +the stat buffer (an \fBint\fR) as an argument \(em not a pointer to the +buffer!): +.TP +.BI WIFEXITED( status ) +is non\-zero if the child exited normally. +.TP +.BI WEXITSTATUS( status ) +evaluates to the least significant eight bits of the return code of +the child which terminated, which may have been set as the argument to +a call to +.B exit() +or as the argument for a +.B return +statement in the main program. This macro can only be evaluated if +.B WIFEXITED +returned non\-zero. +.TP +.BI WIFSIGNALED( status ) +returns true if the child process exited because of a signal which was +not caught. +.TP +.BI WTERMSIG( status ) +returns the number of the signal that caused the child process to +terminate. This macro can only be evaluated if +.B WIFSIGNALED +returned non\-zero. +.TP +.BI WIFSTOPPED( status ) +returns true if the child process which caused the return is currently +stopped; this is only possible if the call was done using +.BR WUNTRACED . +.TP +.BI WSTOPSIG( status ) +returns the number of the signal which caused the child to stop. This +macro can only be evaluated if +.B WIFSTOPPED +returned non\-zero. +.PP +If +.I rusage +is not +.BR NULL , +the +.B struct rusage +as defined in +.I +it points to will be filled with accounting information. See +.BR getrusage (2) +for details. +.SH "RETURN VALUE" +The process ID of the child which exited, \-1 on error +(in particular, when no unwaited-for child processes +of the specified kind exist) +or zero if +.B WNOHANG +was used and no child was available yet. +In the latter two cases +.I errno +will be set appropriately. +.SH ERRORS +.TP +.B ECHILD +No unwaited-for child process as specified does exist. +.TP +.B EINTR +if +.B WNOHANG +was not set and an unblocked signal or a +.B SIGCHLD +was caught. +.TP +.B EINVAL +Invalid value for +.I options +given for wait4. +.SH NOTES +Including +.I +is not required these days, but increases portability. +(Indeed, +.I +defines the +.I rusage +structure with fields of type +.I struct timeval +defined in +.IR .) +.LP +The prototype for these functions is only available if +.B _BSD_SOURCE +is defined (either explicitly, or implicitly, by not defining +_POSIX_SOURCE or compiling with the -ansi flag). +.SH "CONFORMING TO" +SVr4, POSIX.1 +.SH "SEE ALSO" +.BR getrusage (2), +.BR signal (2), +.BR wait (2), +.BR signal (7) diff --git a/man2/waitpid.2 b/man2/waitpid.2 new file mode 100644 index 000000000..0605b3543 --- /dev/null +++ b/man2/waitpid.2 @@ -0,0 +1 @@ +.so man2/wait.2 diff --git a/man2/write.2 b/man2/write.2 new file mode 100644 index 000000000..83f164a51 --- /dev/null +++ b/man2/write.2 @@ -0,0 +1,127 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt, Ian Jackson. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Sat Jul 24 13:35:59 1993 by Rik Faith +.\" Modified Sun Nov 28 17:19:01 1993 by Rik Faith +.\" Modified Sat Jan 13 12:58:08 1996 by Michael Haardt +.\" +.\" Modified Sun Jul 21 18:59:33 1996 by Andries Brouwer +.\" 2001-12-13 added remark by Zack Weinberg +.\" +.TH WRITE 2 2001-12-13 "Linux 2.0.32" "Linux Programmer's Manual" +.SH NAME +write \- write to a file descriptor +.SH SYNOPSIS +.B #include +.sp +.BI "ssize_t write(int " fd ", const void *" buf ", size_t " count ); +.SH DESCRIPTION +.B write +writes up to +.I count +bytes to the file referenced by the file descriptor +.I fd +from the buffer starting at +.IR buf . +POSIX requires that a \fBread()\fP which can be proved to occur after a +\fBwrite()\fP has returned returns the new data. Note that not all file +systems are POSIX conforming. +.SH "RETURN VALUE" +On success, the number of bytes written are returned (zero indicates +nothing was written). On error, \-1 is returned, and \fIerrno\fP is set +appropriately. If \fIcount\fP is zero and the file descriptor refers to +a regular file, 0 will be returned without causing any other effect. +For a special file, the results are not portable. +.SH ERRORS +.TP +.B EAGAIN +Non-blocking I/O has been selected using +.B O_NONBLOCK +and the write would block. +.TP +.B EBADF +.I fd +is not a valid file descriptor or is not open for writing. +.TP +.B EFAULT +.I buf +is outside your accessible address space. +.TP +.B EFBIG +An attempt was made to write a file that exceeds the implementation-defined +maximum file size or the process' file size limit, or to write at a position +past than the maximum allowed offset. +.TP +.B EINTR +The call was interrupted by a signal before any data was written. +.TP +.B EINVAL +.I fd +is attached to an object which is unsuitable for writing. +.TP +.B EIO +A low-level I/O error occurred while modifying the inode. +.TP +.B ENOSPC +The device containing the file referred to by +.I fd +has no room for the data. +.TP +.B EPIPE +.I fd +is connected to a pipe or socket whose reading end is closed. When this +happens the writing process will also receive a +.B SIGPIPE +signal. +(Thus, the write return value is seen only if the program +catches, blocks or ignores this signal.) +.PP +Other errors may occur, depending on the object connected to +.IR fd . +.SH "CONFORMING TO" +SVr4, SVID, POSIX, X/OPEN, 4.3BSD. SVr4 documents additional error +conditions EDEADLK, ENOLCK, ENOLNK, ENOSR, ENXIO, or ERANGE. +Under SVr4 a write may be interrupted and return EINTR at any point, +not just before any data is written. +.SH NOTES +A successful return from +.B write +does not make any guarantee that data has been committed to disk. +In fact, on some buggy implementations, it does not even guarantee +that space has successfully been reserved for the data. +The only way to be sure is to call +.BR fsync (2) +after you are done writing all your data. +.SH "SEE ALSO" +.BR close (2), +.BR fcntl (2), +.BR fsync (2), +.BR ioctl (2), +.BR lseek (2), +.BR open (2), +.BR read (2), +.BR select (2), +.BR fwrite (3), +.BR writev (3) diff --git a/man2/writev.2 b/man2/writev.2 new file mode 100644 index 000000000..54e3384ef --- /dev/null +++ b/man2/writev.2 @@ -0,0 +1 @@ +.so man2/readv.2 diff --git a/man3/CMSG_ALIGN.3 b/man3/CMSG_ALIGN.3 new file mode 100644 index 000000000..ad67f433f --- /dev/null +++ b/man3/CMSG_ALIGN.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man3/CMSG_FIRSTHDR.3 b/man3/CMSG_FIRSTHDR.3 new file mode 100644 index 000000000..ad67f433f --- /dev/null +++ b/man3/CMSG_FIRSTHDR.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man3/CMSG_NXTHDR.3 b/man3/CMSG_NXTHDR.3 new file mode 100644 index 000000000..ad67f433f --- /dev/null +++ b/man3/CMSG_NXTHDR.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man3/CMSG_SPACE.3 b/man3/CMSG_SPACE.3 new file mode 100644 index 000000000..ad67f433f --- /dev/null +++ b/man3/CMSG_SPACE.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man3/HUGE_VAL.3 b/man3/HUGE_VAL.3 new file mode 100644 index 000000000..dd04d2c5c --- /dev/null +++ b/man3/HUGE_VAL.3 @@ -0,0 +1 @@ +.so man3/INFINITY.3 diff --git a/man3/HUGE_VALF.3 b/man3/HUGE_VALF.3 new file mode 100644 index 000000000..dd04d2c5c --- /dev/null +++ b/man3/HUGE_VALF.3 @@ -0,0 +1 @@ +.so man3/INFINITY.3 diff --git a/man3/HUGE_VALL.3 b/man3/HUGE_VALL.3 new file mode 100644 index 000000000..dd04d2c5c --- /dev/null +++ b/man3/HUGE_VALL.3 @@ -0,0 +1 @@ +.so man3/INFINITY.3 diff --git a/man3/INFINITY.3 b/man3/INFINITY.3 new file mode 100644 index 000000000..84a8b7601 --- /dev/null +++ b/man3/INFINITY.3 @@ -0,0 +1,77 @@ +.\" Copyright 2004 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH INFINITY 3 2004-10-31 "" "Linux Programmer's Manual" +.SH NAME +INFINITY, NAN, HUGE_VAL, HUGE_VALF, HUGE_VALL - floating point constants +.SH SYNOPSIS +.nf +#define _ISOC99_SOURCE +.br +.B #include +.sp +.B INFINITY +.sp +.B NAN +.sp +.B HUGE_VAL +.br +.B HUGE_VALF +.br +.B HUGE_VALL +.fi +.SH DESCRIPTION +The macro +.B INFINITY +expands to a float constant representing positive infinity. + +The macro +.B NAN +expands to a float constant representing a quiet NaN +(when supported). A +.I quiet +NaN is a NaN ("not-a-number") that does not raise exceptions +when it is used in arithmetic. The opposite is a +.I signalling +NaN. See IEC 60559:1989. + +The macros +.BR HUGE_VAL , +.BR HUGE_VALF , +.BR HUGE_VALL +expand to constants of types double, float and long double, respectively, +that represent a large positive value, possibly plus infinity. + +.SH AVAILABILITY +On a glibc system, the macro HUGE_VAL is always available. +Availability of the NAN macro can be tested using +.BR "#ifdef NAN" , +and similarly for INFINITY, HUGE_VALF, HUGE_VALL. +They will be defined by +.I +if _ISOC99_SOURCE or _GNU_SOURCE is defined, or __STDC_VERSION__ is defined +and has a value not less than 199901L. + +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR fpclassify (3) diff --git a/man3/MB_CUR_MAX.3 b/man3/MB_CUR_MAX.3 new file mode 100644 index 000000000..5129f80bb --- /dev/null +++ b/man3/MB_CUR_MAX.3 @@ -0,0 +1,40 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.\" Modified, aeb, 990824 +.\" +.TH MB_CUR_MAX 3 1999-07-04 "Linux" "Linux Programmer's Manual" +.SH NAME +MB_CUR_MAX \- maximum length of a multibyte character in the current locale +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +The +.B MB_CUR_MAX +macro defines an integer expression giving +the maximum number of bytes needed to represent a single +wide character in the current locale. +It is locale dependent and therefore not a compile-time constant. +.SH "RETURN VALUE" +An integer >= 1 and <= MB_LEN_MAX. +The value 1 denotes traditional 8-bit encoded characters. +.SH "CONFORMING TO" +ANSI C, POSIX.1 +.SH "SEE ALSO" +.BR MB_LEN_MAX (3), +.BR mblen (3), +.BR mbstowcs (3), +.BR mbtowc (3), +.BR wcstombs (3), +.BR wctomb (3) diff --git a/man3/MB_LEN_MAX.3 b/man3/MB_LEN_MAX.3 new file mode 100644 index 000000000..cb262b01b --- /dev/null +++ b/man3/MB_LEN_MAX.3 @@ -0,0 +1,42 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.\" Modified, aeb, 990824 +.\" +.TH MB_LEN_MAX 3 1999-07-04 "Linux" "Linux Programmer's Manual" +.SH NAME +MB_LEN_MAX \- maximum multibyte length of a character across all locales +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +The +.B MB_LEN_MAX +macro is the upper bound for the number of bytes needed to represent a single +wide character, across all locales. +.SH "RETURN VALUE" +A constant integer >= 1. +.SH "CONFORMING TO" +ANSI C, POSIX.1 +.SH NOTES +The entities +.B MB_LEN_MAX +and +.B sizeof(wchar_t) +are totally unrelated. In the GNU libc, +.B MB_LEN_MAX +is typically 6 while +.B sizeof(wchar_t) +is 4. +.SH "SEE ALSO" +.BR MB_CUR_MAX (3) diff --git a/man3/NAN.3 b/man3/NAN.3 new file mode 100644 index 000000000..dd04d2c5c --- /dev/null +++ b/man3/NAN.3 @@ -0,0 +1 @@ +.so man3/INFINITY.3 diff --git a/man3/__fbufsize.3 b/man3/__fbufsize.3 new file mode 100644 index 000000000..fb0e7c0d7 --- /dev/null +++ b/man3/__fbufsize.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/__flbf.3 b/man3/__flbf.3 new file mode 100644 index 000000000..fb0e7c0d7 --- /dev/null +++ b/man3/__flbf.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/__fpending.3 b/man3/__fpending.3 new file mode 100644 index 000000000..fb0e7c0d7 --- /dev/null +++ b/man3/__fpending.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/__fpurge.3 b/man3/__fpurge.3 new file mode 100644 index 000000000..d7cfd4977 --- /dev/null +++ b/man3/__fpurge.3 @@ -0,0 +1 @@ +.so man3/fpurge.3 diff --git a/man3/__freadable.3 b/man3/__freadable.3 new file mode 100644 index 000000000..fb0e7c0d7 --- /dev/null +++ b/man3/__freadable.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/__freading.3 b/man3/__freading.3 new file mode 100644 index 000000000..fb0e7c0d7 --- /dev/null +++ b/man3/__freading.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/__fsetlocking.3 b/man3/__fsetlocking.3 new file mode 100644 index 000000000..fb0e7c0d7 --- /dev/null +++ b/man3/__fsetlocking.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/__fwritable.3 b/man3/__fwritable.3 new file mode 100644 index 000000000..fb0e7c0d7 --- /dev/null +++ b/man3/__fwritable.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/__fwriting.3 b/man3/__fwriting.3 new file mode 100644 index 000000000..fb0e7c0d7 --- /dev/null +++ b/man3/__fwriting.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/__malloc_hook.3 b/man3/__malloc_hook.3 new file mode 100644 index 000000000..421aafcbe --- /dev/null +++ b/man3/__malloc_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man3/__setfpucw.3 b/man3/__setfpucw.3 new file mode 100644 index 000000000..b53a92710 --- /dev/null +++ b/man3/__setfpucw.3 @@ -0,0 +1,55 @@ +.\" Written Sat Mar 8 10:35:08 MEZ 1997 by J. "MUFTI" Scheurich (mufti@csv.ica.uni-stuttgart.de) +.TH __SETFPUCW 3 1997-03-08 "i386 Linux Man Page" "Linux Programmer's Manual" +.SH NAME +__setfpucw \- set fpu control word on i386 architecture (obsolete) +.SH SYNOPSIS +.B #include +.sp +.BI "void __setfpucw((unsigned short) " control_word ); +.br +.SH DESCRIPTION +.B __setfpucw +transfers +.I control_word +to the registers of the fpu (floating point unit) on i386 architecture. This +was used to control floating point precision, rounding and floating point +exceptions. +.SH EXAMPLE + +.BR __setfpucw(0x1372) + +Set fpu control word on i386 architecture to +.br + - extended precision +.br + - rounding to nearest +.br + - exceptions on overflow, zero divide and NaN +.br +.SH AVAILABILITY +As of glibc 2.1 this function does not exist anymore. +There are new functions from ISO C99, with prototypes in +.IR /usr/include/fenv.h , +to control fpu rounding modes, like +.IR fegetround , +.IR fesetround , +and the floating point environment, like +.IR fegetenv , +.IR feholdexcept , +.IR fesetenv , +.IR feupdateenv +and fpu exception handling, like +.IR feclearexcept , +.IR fegetexceptflag , +.IR feraiseexcept , +.IR fesetexceptflag , +.IR fetestexcept . +.PP +If direct acces to the FPU control word is still needed, the _FPU_GETCW +and _FPU_SETCW macros from +.I /usr/include/fpu_control.h +can be used. +.SH "SEE ALSO" +.BR feclearexcept (3) +.br +.IR /usr/include/i386/fpu_control.h diff --git a/man3/_flushlbf.3 b/man3/_flushlbf.3 new file mode 100644 index 000000000..fb0e7c0d7 --- /dev/null +++ b/man3/_flushlbf.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/a64l.3 b/man3/a64l.3 new file mode 100644 index 000000000..21ac2bfab --- /dev/null +++ b/man3/a64l.3 @@ -0,0 +1,66 @@ +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.\" Corrected, aeb, 2002-05-30 +.\" +.TH A64L 3 2002-02-15 "" "Linux Programmer's Manual" +.SH NAME +a64l, l64a \- convert between long and base-64 +.SH SYNOPSIS +.B #include +.sp +.BI "long a64l(char *" str64 ); +.sp +.BI "char *l64a(long " value ); +.sp +.SH DESCRIPTION +These functions provide a conversion between 32-bit long integers +and little-endian base-64 ASCII strings (of length zero to six). +If the string used as argument for +.BR a64l () +has length greater than six, only the first six bytes are used. +If longs have more than 32 bits, then +.BR l64a () +uses only the low order 32 bits of +.IR value , +and +.BR a64l () +sign-extends its 32-bit result. +.LP +The 64 digits in the base 64 system are: +.RS +.nf +\&'.' represents a 0 +\&'/' represents a 1 +0-9 represent 2-11 +A-Z represent 12-37 +a-z represent 38-63 +.fi +.RE +.br +So 123 = 59*64^0 + 1*64^1 = "v/". +.SH NOTES +The value returned by +.BR a64l () +may be a pointer to a static buffer, possibly overwritten +by later calls. +.LP +The behaviour of +.BR l64a () +is undefined when +.I value +is negative. If +.I value +is zero, it returns an empty string. +.LP +These functions are broken in glibc before 2.2.5 +(puts most significant digit first). +.LP +This is not the encoding used by +.BR uuencode (1). +.SH "CONFORMING TO" +XPG 4.2, POSIX 1003.1-2001. +.SH "SEE ALSO" +.BR uuencode (1), +.BR itoa (3), +.BR strtoul (3) diff --git a/man3/abort.3 b/man3/abort.3 new file mode 100644 index 000000000..1ba5c573b --- /dev/null +++ b/man3/abort.3 @@ -0,0 +1,54 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:46:21 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Aug 4 10:51:53 2000 - patch from Joseph S. Myers +.\" +.TH ABORT 3 1993-04-12 "GNU" "Linux Programmer's Manual" +.SH NAME +abort \- cause abnormal program termination +.SH SYNOPSIS +.nf +.B #include +.sp +.B void abort(void); +.fi +.SH DESCRIPTION +The \fBabort()\fP function causes abnormal program termination unless +the signal SIGABRT is caught and the signal handler does not return. +If the \fBabort()\fP function causes program termination, all open +streams are closed and flushed. +.PP +If the SIGABRT signal is blocked or ignored, the \fBabort()\fP +function will still override it. +.SH "RETURN VALUE" +The \fBabort()\fP function never returns. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899 (C99) +.SH "SEE ALSO" +.BR sigaction (2), +.BR exit (3), +.BR raise (3) diff --git a/man3/abs.3 b/man3/abs.3 new file mode 100644 index 000000000..4c60f1d38 --- /dev/null +++ b/man3/abs.3 @@ -0,0 +1,80 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Mar 29 22:31:13 1993, David Metcalfe +.\" Modified Sun Jun 6 23:27:50 1993, David Metcalfe +.\" Modified Sat Jul 24 21:45:37 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified Sat Dec 16 15:02:59 2000, Joseph S. Myers +.\" +.TH ABS 3 2000-12-17 "GNU" "Linux Programmer's Manual" +.SH NAME +abs, labs, llabs, imaxabs \- compute the absolute value of an integer +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int abs(int " j ); +.br +.BI "long int labs(long int " j ); +.br +.BI "long long int llabs(long long int " j ); +.sp +.B #include +.sp +.BI "intmax_t imaxabs(intmax_t " j ); +.fi +.SH DESCRIPTION +The \fBabs()\fP function computes the absolute value of the integer +argument \fIj\fP. The \fBlabs()\fP, \fBllabs()\fP and \fBimaxabs()\fP +functions compute the absolute value of the argument \fIj\fP of the +appropriate integer type for the function. +.SH "RETURN VALUE" +Returns the absolute value of the integer argument, of the appropriate +integer type for the function. +.SH "CONFORMING TO" +SVID 3, POSIX.1, BSD 4.3, ISO/IEC 9899 (C99). POSIX.1 (1996 edition) only +requires the \fBabs()\fP function. ISO/IEC 9899:1990 (C89) only +includes the \fBabs()\fP and \fBlabs()\fP functions; the functions +\fBllabs()\fP and \fBimaxabs()\fP were added in C99. +.SH NOTES +Trying to take the absolute value of the most negative integer +is not defined. +.PP +The \fBllabs()\fP function is included in glibc since version 2.0, but +is not in libc5 or libc4. The \fBimaxabs()\fP function is included in +glibc since version 2.1.1. +.PP +For \fBllabs()\fP to be declared, it may be necessary to define +\fB_ISOC99_SOURCE\fP or \fB_ISOC9X_SOURCE\fP (depending on the +version of glibc) before including any standard headers. +.PP +GCC handles \fBabs()\fP and \fBlabs()\fP as builtin functions. GCC +3.0 also handles \fBllabs()\fP and \fBimaxabs()\fP as builtins. +.SH "SEE ALSO" +.BR ceil (3), +.BR fabs (3), +.BR floor (3), +.BR rint (3) diff --git a/man3/acos.3 b/man3/acos.3 new file mode 100644 index 000000000..57855ed97 --- /dev/null +++ b/man3/acos.3 @@ -0,0 +1,64 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-25 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ACOS 3 2004-10-06 "" "Linux Programmer's Manual" +.SH NAME +acos, acosf, acosl \- arc cosine function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double acos(double " x ); +.BI "float acosf(float " x ); +.BI "long double acosl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBacos()\fP function calculates the arc cosine of \fIx\fP; that is +the value whose cosine is \fIx\fP. If \fIx\fP falls outside the range +\-1 to 1, \fBacos()\fP fails and \fIerrno\fP is set. +.SH "RETURN VALUE" +The \fBacos()\fP function returns the arc cosine in radians and the +value is mathematically defined to be between 0 and PI (inclusive). +.SH ERRORS +.TP +.B EDOM +\fIx\fP is out of range. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and long double variants are C99 requirements. +.SH "SEE ALSO" +.BR asin (3), +.BR atan (3), +.BR atan2 (3), +.BR cos (3), +.BR sin (3), +.BR tan (3) diff --git a/man3/acosf.3 b/man3/acosf.3 new file mode 100644 index 000000000..66104f71b --- /dev/null +++ b/man3/acosf.3 @@ -0,0 +1 @@ +.so man3/acos.3 diff --git a/man3/acosh.3 b/man3/acosh.3 new file mode 100644 index 000000000..723b01e07 --- /dev/null +++ b/man3/acosh.3 @@ -0,0 +1,63 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-25 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ACOSH 3 2002-07-25 "" "Linux Programmer's Manual" +.SH NAME +acosh, acoshf, acoshl \- inverse hyperbolic cosine function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double acosh(double " x ); +.br +.BI "float acoshf(float " x ); +.br +.BI "long double acoshl(long double " x ); +.sp +.fi +Link with \-lm. +.SH DESCRIPTION +The \fBacosh()\fP function calculates the inverse hyperbolic cosine of +\fIx\fP; that is the value whose hyperbolic cosine is \fIx\fP. If \fIx\fP +is less than 1.0, \fBacosh()\fP returns not-a-number (NaN) and \fIerrno\fP +is set. +.SH ERRORS +.TP +.B EDOM +\fIx\fP is out of range. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and long double variants are C99 requirements. +.SH "SEE ALSO" +.BR asinh (3), +.BR atanh (3), +.BR cosh (3), +.BR sinh (3), +.BR tanh (3) diff --git a/man3/acoshf.3 b/man3/acoshf.3 new file mode 100644 index 000000000..f0f5c7a00 --- /dev/null +++ b/man3/acoshf.3 @@ -0,0 +1 @@ +.so man3/acosh.3 diff --git a/man3/acoshl.3 b/man3/acoshl.3 new file mode 100644 index 000000000..f0f5c7a00 --- /dev/null +++ b/man3/acoshl.3 @@ -0,0 +1 @@ +.so man3/acosh.3 diff --git a/man3/acosl.3 b/man3/acosl.3 new file mode 100644 index 000000000..66104f71b --- /dev/null +++ b/man3/acosl.3 @@ -0,0 +1 @@ +.so man3/acos.3 diff --git a/man3/addmntent.3 b/man3/addmntent.3 new file mode 100644 index 000000000..3c2bb35c9 --- /dev/null +++ b/man3/addmntent.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man3/addseverity.3 b/man3/addseverity.3 new file mode 100644 index 000000000..b1dedffe4 --- /dev/null +++ b/man3/addseverity.3 @@ -0,0 +1,53 @@ +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" adapted glibc info page +.\" +.\" polished a little, aeb +.TH ADDSEVERITY 3 2002-08-07 "gnu" "Linux Programmer's Manual" +.SH NAME +addseverity \- introduce new severity classes +.SH SYNOPSIS +.nf +.sp +.B #define _SVID_SOURCE +.br +.B #include +.sp +.BI "int addseverity(int " severity ", const char *" s ); +.sp +.fi +.SH DESCRIPTION +This function allows the introduction of new severity classes +which can be addressed by the +.I severity +parameter of the +.BR fmtmsg (3) +function. By default that latter function only knows how to +print messages for severity 0-4 (with strings (none), HALT, +ERROR, WARNING, INFO). This call attaches the given string +.I s +to the given value +.IR severity . +If +.I s +is NULL, the severity class with the numeric value +.I severity +is removed. +It is not possible to overwrite or remove one of the default +severity classes. The severity value must be nonnegative. +.SH "RETURN VALUE" +Upon success, the value +.B MM_OK +is returned. Upon error, the return value is +.BR MM_NOTOK . +Possible errors include: out of memory, attempt to remove a +nonexistent or default severity class. +.SH NOTE +New severity classes can also be added by setting the environment varible +.BR SEV_LEVEL . +.SH "CONFORMING TO" +This function is not specified in the X/Open Portability Guide +although the `fmtsmg' function is. It is available on System V +systems. +.SH "SEE ALSO" +.BR fmtmsg (3) diff --git a/man3/aio_cancel.3 b/man3/aio_cancel.3 new file mode 100644 index 000000000..19c996e52 --- /dev/null +++ b/man3/aio_cancel.3 @@ -0,0 +1,83 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH AIO_CANCEL 3 2003-11-14 "" "Linux Programmer's Manual" +.SH NAME +aio_cancel \- cancel an outstanding asynchronous I/O request +.SH SYNOPSIS +.sp +.B "#include " +.sp +.BI "int aio_cancel(int " fd ", struct aiocb *" aiocbp ); +.sp +.SH DESCRIPTION +The +.B aio_cancel +function attempts to cancel outstanding asynchronous I/O requests +for the file descriptor +.IR fd . +If +.I aiocbp +is NULL, all such requests are cancelled. Otherwise, only the request +described by the control block pointed to by +.I aiocbp +is cancelled. +.LP +Normal asynchronous notification occurs for cancelled requests. +The request return status is set to \-1, and the request error status +is set to ECANCELED. +The control block of requests that cannot be cancelled is not changed. +.LP +If +.I aiocbp +is not NULL, and +.I fd +differs from the file descriptor with which the asynchronous operation +was initiated, unspecified results occur. +.LP +Which operations are cancelable is implementation-defined. +.\" FreeBSD: not those on raw disk devices. +.SH "RETURN VALUE" +This function returns AIO_CANCELED if all requests were successfully +cancelled. It returns AIO_NOTCANCELED when at least one of the +requests specified was not cancelled because it was in progress. +In this case one may check the status of individual requests using +.BR aio_error (3). +This function returns AIO_ALLDONE when all requests had +been completed already before this call. +When some error occurs, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.SH "CONFORMING TO" +POSIX 1003.1-2003 +.SH "SEE ALSO" +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3) diff --git a/man3/aio_error.3 b/man3/aio_error.3 new file mode 100644 index 000000000..67f693efb --- /dev/null +++ b/man3/aio_error.3 @@ -0,0 +1,69 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH AIO_ERROR 3 2003-11-14 "" "Linux Programmer's Manual" +.SH NAME +aio_error \- get error status of asynchronous I/O operation +.SH SYNOPSIS +.sp +.B "#include " +.sp +.BI "int aio_error(const struct aiocb *" aiocbp ); +.sp +.SH DESCRIPTION +The +.B aio_error +function returns the error status for the asynchronous I/O request +with control block pointed to by +.IR aiocbp . +.SH "RETURN VALUE" +This function returns EINPROGRESS if the request has not been +completed yet. It returns ECANCELED if the request was cancelled. +It returns 0 if the request completed successfully. +Otherwise an error value is returned, the same value that would have +been stored in the +.I errno +variable in case of a synchronous +.IR read , +.IR write , +.IR fsync , +or +.I fdatasync +request. +On error, the error value is returned. +.SH ERRORS +.TP +.B EINVAL +.I aiocbp +does not point at a control block for an asynchronous I/O request +of which the return status (see +.BR aio_return (3)) +has not been retrieved yet. +.SH "CONFORMING TO" +POSIX 1003.1-2003 +.SH "SEE ALSO" +.BR aio_cancel (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3) diff --git a/man3/aio_fsync.3 b/man3/aio_fsync.3 new file mode 100644 index 000000000..82a186d79 --- /dev/null +++ b/man3/aio_fsync.3 @@ -0,0 +1,86 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH AIO_FSYNC 3 2003-11-14 "" "Linux Programmer's Manual" +.SH NAME +aio_fsync \- asynchronous file synchronization +.SH SYNOPSIS +.sp +.B "#include " +.sp +.BI "int aio_fsync(int " op ", struct aiocb *" aiocbp ); +.sp +.SH DESCRIPTION +The +.B aio_fsync +function does a sync on all outstanding asynchronous I/O operations +associated with +.IR aiocbp->aio_fildes . +.LP +More precisely, if +.I op +is O_SYNC, then all currently queued I/O operations shall be +completed as if by a call of +.BR fsync (2), +and if +.I op +is O_DSYNC, this call is the asynchronous analog of +.BR fdatasync (2). +Note that this is a request only - this call does not wait +for I/O completion. +.LP +Apart from +.I aio_fildes +the only field in the structure pointed to by +.I aiocbp +that is used by this call is the +.I aio_sigevent +field (a struct sigevent) that indicates the desired type of +asynchronous notification at completion. +All other fields are ignored. +.SH "RETURN VALUE" +On success (the sync request was successfully queued) +this function returns 0. On error \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EAGAIN +Out of resources. +.TP +.B EBADF +.I aio_fildes +is not a valid file descriptor open for writing. +.TP +.B EINVAL +No synchronized I/O for this file is supported, or +.I op +is not O_SYNC or O_DSYNC. +.SH "CONFORMING TO" +POSIX 1003.1-2003 +.SH "SEE ALSO" +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3) diff --git a/man3/aio_read.3 b/man3/aio_read.3 new file mode 100644 index 000000000..299029fd0 --- /dev/null +++ b/man3/aio_read.3 @@ -0,0 +1,115 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH AIO_READ 3 2003-11-14 "" "Linux Programmer's Manual" +.SH NAME +aio_read \- asynchronous read +.SH SYNOPSIS +.sp +.B "#include " +.sp +.BI "int aio_read(struct aiocb *" aiocbp ); +.sp +.SH DESCRIPTION +The +.B aio_read +function requests an asynchronous "n = read(fd, buf, count)" +with fd, buf, count given by +.IR aiocbp->aio_fildes , +.IR aiocbp->aio_buf , +.IR aiocbp->aio_nbytes , +respectively. The return status n can be retrieved upon completion using +.BR aio_return (3). +.LP +The data is read starting at the absolute file offset +.IR aiocbp->aio_offset , +regardless of the current file position. After this request, +the value of the current file position is unspecified. +.LP +The "asynchronous" means that this call returns as soon as the +request has been enqueued; the read may or may not have completed +when the call returns. One tests for completion using +.BR aio_error (3). +.LP +If _POSIX_PRIORITIZED_IO is defined, and this file supports it, +then the asynchronous operation is submitted at a priority equal +to that of the calling process minus +.IR aiocbp->aio_reqprio . +.LP +The field +.I aiocbp->aio_lio_opcode +is ignored. +.LP +No data is read from a regular file beyond its maximum offset. +.SH "RETURN VALUE" +On success, 0 is returned. On error the request is not enqueued, \-1 +is returned, and +.I errno +is set appropriately. If an error is first detected later, it will +be reported via +.BR aio_return (3) +(returns status \-1) and +.BR aio_error (3) +(error status whatever one would have gotten in +.IR errno , +such as EBADF). +.SH ERRORS +.TP +.B EAGAIN +Out of resources. +.TP +.B EBADF +.I aio_fildes +is not a valid file descriptor open for reading. +.TP +.B EINVAL +One or more of +.IR aio_offset , +.IR aio_reqprio , +.IR aio_nbytes +are invalid. +.TP +.B ENOSYS +This function is not supported. +.TP +.B EOVERFLOW +The file is a regular file, we start reading before end-of-file +and want at least one byte, but the starting position is past +the maximum offset for this file. +.SH NOTES +It is a good idea to zero out the control block before use. +This control block must not be changed while the read operation +is in progress. +The buffer area being read into +.\" or the control block of the operation +must not be accessed during the operation or undefined results may +occur. The memory areas involved must remain valid. + +.SH "CONFORMING TO" +POSIX 1003.1-2003 +.SH "SEE ALSO" +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3) diff --git a/man3/aio_return.3 b/man3/aio_return.3 new file mode 100644 index 000000000..4f0163d27 --- /dev/null +++ b/man3/aio_return.3 @@ -0,0 +1,66 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH AIO_RETURN 3 2003-11-14 "" "Linux Programmer's Manual" +.SH NAME +aio_return \- get return status of asynchronous I/O operation +.SH SYNOPSIS +.sp +.B "#include " +.sp +.BI "ssize_t aio_return(struct aiocb *" aiocbp ); +.sp +.SH DESCRIPTION +The +.B aio_return +function returns the final return status for the asynchronous I/O request +with control block pointed to by +.IR aiocbp . +.LP +This function should be called only once for any given request, after +.BR aio_error (2) +returns something other than EINPROGRESS. +.SH "RETURN VALUE" +If the asynchronous I/O operation has completed, this function returns +the value that would have been returned in case of a synchronous +.IR read , +.IR write , +or +.IR fsync +request. +Otherwise the return value is undefined. +On error, the error value is returned. +.SH ERRORS +.TP +.B EINVAL +.I aiocbp +does not point at a control block for an asynchronous I/O request +of which the return status has not been retrieved yet. +.SH "CONFORMING TO" +POSIX 1003.1-2003 +.SH "SEE ALSO" +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_suspend (3), +.BR aio_write (3) diff --git a/man3/aio_suspend.3 b/man3/aio_suspend.3 new file mode 100644 index 000000000..a788eb273 --- /dev/null +++ b/man3/aio_suspend.3 @@ -0,0 +1,83 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH AIO_SUSPEND 3 2003-11-14 "" "Linux Programmer's Manual" +.SH NAME +aio_suspend \- wait for asynchronous I/O operation or timeout +.SH SYNOPSIS +.nf +.sp +.B "#include " +.sp +.BI "int aio_suspend(const struct aiocb * const " cblist [], +.br +.BI " int " n ", const struct timespec *" timeout ); +.sp +.fi +.SH DESCRIPTION +The +.B aio_suspend +function suspends the calling process until at least one of the +asynchronous I/O requests in the list +.I cblist +of length +.I n +have completed, a signal is delivered, or +.I timeout +is not NULL and the time interval it indicates has passed. +.LP +Each item in the list must either be NULL (and then is ignored), +or a pointer to a control block on which I/O was initiated using +.BR aio_read (3), +.BR aio_write (3), +or +.BR lio_listio (3). +.LP +If CLOCK_MONOTONIC is supported, this clock is used to measure +the timeout interval. +.SH "RETURN VALUE" +If this function returns after completion of one of the indicated +requests, it returns 0. Otherwise it returns \-1 and sets +.I errno +appropriately. +.SH ERRORS +.TP +.B EAGAIN +The call was ended by timeout, before any of the indicated operations +had completed. +.TP +.B EINTR +The call was ended by signal. +(Possibly the completion signal of one of the operations we were waiting for.) +.SH NOTE +One can achieve polling by using a non-NULL +.I timeout +that specifies a zero time interval. +.SH "CONFORMING TO" +POSIX 1003.1-2003 +.SH "SEE ALSO" +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_write (3) diff --git a/man3/aio_write.3 b/man3/aio_write.3 new file mode 100644 index 000000000..055952f51 --- /dev/null +++ b/man3/aio_write.3 @@ -0,0 +1,117 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH AIO_WRITE 3 2003-11-14 "" "Linux Programmer's Manual" +.SH NAME +aio_write \- asynchronous write +.SH SYNOPSIS +.sp +.B "#include " +.sp +.BI "int aio_write(struct aiocb *" aiocbp ); +.sp +.SH DESCRIPTION +The +.B aio_write +function requests an asynchronous "n = write(fd, buf, count)" +with fd, buf, count given by +.IR aiocbp->aio_fildes , +.IR aiocbp->aio_buf , +.IR aiocbp->aio_nbytes , +respectively. The return status n can be retrieved upon completion using +.BR aio_return (3). +.LP +If O_APPEND is not set, the data is written starting at the +absolute file offset +.IR aiocbp->aio_offset , +regardless of the current file position. +If O_APPEND is set, the data is written at the end of the file. +After this request, the value of the current file position is unspecified. +.LP +The "asynchronous" means that this call returns as soon as the +request has been enqueued; the write may or may not have completed +when the call returns. One tests for completion using +.BR aio_error (3). +.LP +If _POSIX_PRIORITIZED_IO is defined, and this file supports it, +then the asynchronous operation is submitted at a priority equal +to that of the calling process minus +.IR aiocbp->aio_reqprio . +.LP +The field +.I aiocbp->aio_lio_opcode +is ignored. +.LP +No data is written to a regular file beyond its maximum offset. +.SH "RETURN VALUE" +On success, 0 is returned. On error the request is not enqueued, \-1 +is returned, and +.I errno +is set appropriately. If an error is first detected later, it will +be reported via +.BR aio_return (3) +(returns status \-1) and +.BR aio_error (3) +(error status whatever one would have gotten in +.IR errno , +such as EBADF). +.SH ERRORS +.TP +.B EAGAIN +Out of resources. +.TP +.B EBADF +.I aio_fildes +is not a valid file descriptor open for writing. +.TP +.B EFBIG +The file is a regular file, we want to write at least one byte, +but the starting position is at or beyond the maximum offset for this file. +.TP +.B EINVAL +One or more of +.IR aio_offset , +.IR aio_reqprio , +.IR aio_nbytes +are invalid. +.TP +.B ENOSYS +This function is not supported. + +.SH NOTES +It is a good idea to zero out the control block before use. +This control block must not be changed while the write operation +is in progress. +The buffer area being written out +.\" or the control block of the operation +must not be accessed during the operation or undefined results may +occur. The memory areas involved must remain valid. + +.SH "CONFORMING TO" +POSIX 1003.1-2003 +.SH "SEE ALSO" +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3) diff --git a/man3/alloca.3 b/man3/alloca.3 new file mode 100644 index 000000000..b88ad123c --- /dev/null +++ b/man3/alloca.3 @@ -0,0 +1,107 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)alloca.3 5.1 (Berkeley) 5/2/91 +.\" +.\" Converted Mon Nov 29 11:05:55 1993 by Rik Faith +.\" Modified Tue Oct 22 23:41:56 1996 by Eric S. Raymond +.\" Modified 2002-07-17, aeb +.\" +.TH ALLOCA 3 2002-07-17 "GNU" "Linux Programmer's Manual" +.SH NAME +alloca \- memory allocator +.SH SYNOPSIS +.B #include +.sp +.BI "void *alloca(size_t " size ); +.SH DESCRIPTION +The +.B alloca +function allocates +.I size +bytes of space in the stack frame of the caller. This temporary space is +automatically freed when the function that called +.B alloca +returns to its caller. +.SH "RETURN VALUE" +The +.B alloca +function returns a pointer to the beginning of the allocated space. +If the allocation causes stack overflow, program behaviour is undefined. +.SH "CONFORMING TO" +There is evidence that the +.B alloca +function appeared in 32v, pwb, pwb.2, 3bsd, and 4bsd. There is a man page +for it in BSD 4.3. Linux uses the GNU version. +This function is not in POSIX or SUSv3. +.SH "NOTES ON THE GNU VERSION" +Normally, +.B gcc +translates calls to +.B alloca +by inlined code. This is not done when either the \-ansi or +the \-fno\-builtin option is given. But beware! By default +the glibc version of +.I +includes +.I +and that contains the line +.RS +# define alloca(size) __builtin_alloca (size) +.RE +with messy consequences if one has a private version of this function. +.LP +The fact that the code is inlined, means that it is impossible +to take the address of this function, or to change its behaviour +by linking with a different library. +.LP +The inlined code often consists of a single instruction adjusting +the stack pointer, and does not check for stack overflow. +Thus, there is no NULL error return. +.SH BUGS +The +.B alloca +function is machine and compiler dependent. On many systems +its implementation is buggy. Its use is discouraged. +.LP +On many systems +.B alloca +cannot be used inside the list of arguments of a function call, because +the stack space reserved by +.B alloca +would appear on the stack in the middle of the space for the +function arguments. +.SH "SEE ALSO" +.BR brk (2), +.BR pagesize (2), +.BR calloc (3), +.BR malloc (3), +.BR realloc (3) diff --git a/man3/alphasort.3 b/man3/alphasort.3 new file mode 100644 index 000000000..7e757c7a0 --- /dev/null +++ b/man3/alphasort.3 @@ -0,0 +1 @@ +.so man3/scandir.3 diff --git a/man3/argz_add.3 b/man3/argz_add.3 new file mode 100644 index 000000000..544091b04 --- /dev/null +++ b/man3/argz_add.3 @@ -0,0 +1,207 @@ +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" based on the description in glibc source and infopages +.\" +.\" Corrections and additions, aeb +.TH ARGZ_ADD 3 +.SH NAME +argz_add, argz_add_sep, argz_append, argz_count, argz_create, +argz_create_sep, argz_delete, argz_extract, argz_insert, +argz_next, argz_replace, argz_stringify \- functions to handle an argz list +.SH SYNOPSIS +.nf +.sp +.B "#include " +.sp +.BI "error_t" +.BI "argz_add(char **" argz ", size_t *" argz_len ", const char *" str ); +.sp +.BI "error_t" +.BI "argz_add_sep(char **" argz ", size_t *" argz_len , +.ti 20n +.BI "const char *" str ", int " delim ); +.sp +.BI "error_t" +.BI "argz_append(char **" argz ", size_t *" argz_len , +.ti 20n +.BI "const char *" buf ", size_t " buf_len ); +.sp +.BI "size_t" +.BI "argz_count(const char *" argz ", size_t " argz_len ); +.sp +.BI "error_t" +.BI "argz_create(char * const " argv "[], char **" argz , +.ti 20n +.BI "size_t *" argz_len ); +.sp +.BI "error_t" +.BI "argz_create_sep(const char *" str ", int " sep ", char **" argz , +.ti 20n +.BI "size_t *" argz_len ); +.sp +.BI "error_t" +.BI "argz_delete(char **" argz ", size_t *" argz_len ", char *" entry ); +.sp +.BI "void" +.BI "argz_extract(char *" argz ", size_t " argz_len ", char **" argv ); +.sp +.BI "error_t" +.BI "argz_insert (char **" argz ", size_t *" argz_len ", char *" before , +.ti 20n +.BI "const char *" entry ); +.sp +.BI "char *" +.BI "argz_next(char *" argz ", size_t " argz_len ", const char *" entry ); +.sp +.BI "error_t" +.BI "argz_replace(char **" argz ", size_t *" argz_len ", const char *" str , +.ti 20n +.BI "const char *" with ", unsigned int *" replace_count ); +.sp +.BI "void" +.BI "argz_stringify(char *" argz ", size_t " len ", int " sep ); +.sp +.SH DESCRIPTION +These functions are glibc-specific. +.LP +An argz vector is a pointer to a character buffer together with a length. +The intended interpretation of the character buffer is array +of strings, where the strings are separated by NUL bytes. +If the length is nonzero, the last byte of the buffer must be a NUL. +.LP +These functions are for handling argz vectors. +The pair (NULL,0) is an argz vector, and, conversely, +argz vectors of length 0 must have NULL pointer. +Allocation of nonempty argz vectors is done using +.BR malloc (3), +so that +.BR free (3) +can be used to dispose of them again. +.LP +.B argz_add() +adds the string +.I str +at the end of the array +.RI * argz , +and updates +.RI * argz +and +.RI * argz_len . +.LP +.B argz_add_sep() +is similar, but splits the string +.I str +into substrings separated by the delimiter +.IR delim . +For example, one might use this on a Unix search path with +delimiter ':'. +.LP +.B argz_append() +appends the argz vector +.RI ( buf , buf_len ) +after +.RI (* argz ,* argz_len ) +and updates +.RI * argz +and +.RI * argz_len . +(Thus, +.RI * argz_len +will be increased by +.IR buf_len .) +.LP +.B argz_count() +counts the number of strings, that is, the number of NUL bytes, in +.RI ( argz , argz_len ). +.LP +.B argz_create() +converts a Unix-style argument vector +.IR argv , +terminated by (char *) 0, into an argz vector +.RI (* argz ,* argz_len ). +.LP +.B argz_create_sep() +converts the NUL-terminated string +.I str +into an argz vector +.RI (* argz ,* argz_len ) +by breaking it up at every occurrence of the separator +.IR sep . +.LP +.B argz_delete() +removes the substring pointed to by +.I entry +from the argz vector +.RI (* argz ,* argz_len ) +and updates +.RI * argz +and +.RI * argz_len . +.LP +.B argz_extract() +is the opposite of +.BR argz_create() . +It takes the argz vector +.RI ( argz , argz_len ) +and fills the array starting at +.I argv +with pointers to the substrings, and a final NULL, +making a Unix-style argv vector. +The array +.I argv +must have room for +.IR argz_count ( argz , argz_len ") + 1" +pointers. +.LP +.B argz_insert() +is the opposite of +.BR argz_delete() . +It inserts the argument +.I entry +at position +.I before +into the argz vector +.RI (* argz ,* argz_len ) +and updates +.RI * argz +and +.RI * argz_len . +If +.I before +is NULL, then +.I entry +will inserted at the end. +.LP +.B argz_next() +is a function to step trough the argz vector. If +.I entry +is NULL, the first entry is returned. Otherwise, the entry +following is returned. It returns NULL if there is no following entry. +.LP +.B argz_replace() +replaces each occurrence of +.I str +with +.IR with , +reallocating argz as necessary. If +.I replace_count +is non-NULL, +.RI * replace_count +will be incremented by the number of replacements. +.LP +.B argz_stringify() +is the opposite of +.BR argz_create_sep() . +It transforms the argz vector into a normal string by replacing +all NULs except the last by +.IR sep . +.SH "RETURN VALUE" +All argz functions that do memory allocation have a return type of +\fIerror_t\fP, and return \fB0\fP for success, and \fBENOMEM\fP +if an allocation error occurs. +.SH BUGS +Argz vectors without final NUL may lead to Segmentation Faults. +.SH NOTES +These functions are a GNU extension. Handle with care. +.SH "SEE ALSO" +.BR envz (3) diff --git a/man3/argz_add_sep.3 b/man3/argz_add_sep.3 new file mode 100644 index 000000000..25a6e267c --- /dev/null +++ b/man3/argz_add_sep.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_append.3 b/man3/argz_append.3 new file mode 100644 index 000000000..25a6e267c --- /dev/null +++ b/man3/argz_append.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_count.3 b/man3/argz_count.3 new file mode 100644 index 000000000..25a6e267c --- /dev/null +++ b/man3/argz_count.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_create.3 b/man3/argz_create.3 new file mode 100644 index 000000000..25a6e267c --- /dev/null +++ b/man3/argz_create.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_create_sep.3 b/man3/argz_create_sep.3 new file mode 100644 index 000000000..25a6e267c --- /dev/null +++ b/man3/argz_create_sep.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_delete.3 b/man3/argz_delete.3 new file mode 100644 index 000000000..25a6e267c --- /dev/null +++ b/man3/argz_delete.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_extract.3 b/man3/argz_extract.3 new file mode 100644 index 000000000..25a6e267c --- /dev/null +++ b/man3/argz_extract.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_insert.3 b/man3/argz_insert.3 new file mode 100644 index 000000000..25a6e267c --- /dev/null +++ b/man3/argz_insert.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_next.3 b/man3/argz_next.3 new file mode 100644 index 000000000..25a6e267c --- /dev/null +++ b/man3/argz_next.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_replace.3 b/man3/argz_replace.3 new file mode 100644 index 000000000..25a6e267c --- /dev/null +++ b/man3/argz_replace.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_stringify.3 b/man3/argz_stringify.3 new file mode 100644 index 000000000..25a6e267c --- /dev/null +++ b/man3/argz_stringify.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/asctime.3 b/man3/asctime.3 new file mode 100644 index 000000000..84a3baa92 --- /dev/null +++ b/man3/asctime.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man3/asctime_r.3 b/man3/asctime_r.3 new file mode 100644 index 000000000..84a3baa92 --- /dev/null +++ b/man3/asctime_r.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man3/asin.3 b/man3/asin.3 new file mode 100644 index 000000000..76c7133c1 --- /dev/null +++ b/man3/asin.3 @@ -0,0 +1,67 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-25 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ASIN 3 2002-07-25 "" "Linux Programmer's Manual" +.SH NAME +asin, asinf, asinl \- arc sine function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double asin(double " x ); +.br +.BI "float asinf(float " x ); +.br +.BI "long double asinl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBasin()\fP function calculates the arc sine of \fIx\fP; that is +the value whose sine is \fIx\fP. If \fIx\fP falls outside the range +\-1 to 1, \fBasin()\fP fails and \fIerrno\fP is set. +.SH "RETURN VALUE" +The \fBasin()\fP function returns the arc sine in radians and the +value is mathematically defined to be between -PI/2 and PI/2 +(inclusive). +.SH ERRORS +.TP +.B EDOM +\fIx\fP is out of range. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and long double variants are C99 requirements. +.SH "SEE ALSO" +.BR acos (3), +.BR atan (3), +.BR atan2 (3), +.BR cos (3), +.BR sin (3), +.BR tan (3) diff --git a/man3/asinf.3 b/man3/asinf.3 new file mode 100644 index 000000000..4c88df085 --- /dev/null +++ b/man3/asinf.3 @@ -0,0 +1 @@ +.so man3/asin.3 diff --git a/man3/asinh.3 b/man3/asinh.3 new file mode 100644 index 000000000..cd3d54121 --- /dev/null +++ b/man3/asinh.3 @@ -0,0 +1,57 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ASINH 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +asinh, asinhf, asinhl \- inverse hyperbolic sine function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double asinh(double " x ); +.br +.BI "float asinhf(float " x ); +.br +.BI "long double asinhl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBasinh()\fP function calculates the inverse hyperbolic sine of +\fIx\fP; that is the value whose hyperbolic sine is \fIx\fP. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and long double variants are C99 requirements. +.SH "SEE ALSO" +.BR acosh (3), +.BR atanh (3), +.BR cosh (3), +.BR sinh (3), +.BR tanh (3) diff --git a/man3/asinhf.3 b/man3/asinhf.3 new file mode 100644 index 000000000..93c50342a --- /dev/null +++ b/man3/asinhf.3 @@ -0,0 +1 @@ +.so man3/asinh.3 diff --git a/man3/asinhl.3 b/man3/asinhl.3 new file mode 100644 index 000000000..93c50342a --- /dev/null +++ b/man3/asinhl.3 @@ -0,0 +1 @@ +.so man3/asinh.3 diff --git a/man3/asinl.3 b/man3/asinl.3 new file mode 100644 index 000000000..4c88df085 --- /dev/null +++ b/man3/asinl.3 @@ -0,0 +1 @@ +.so man3/asin.3 diff --git a/man3/asprintf.3 b/man3/asprintf.3 new file mode 100644 index 000000000..38936d9e7 --- /dev/null +++ b/man3/asprintf.3 @@ -0,0 +1,68 @@ +.\" Copyright (C) 2001 Andries Brouwer +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Text fragments inspired by Martin Schulze . +.\" +.TH ASPRINTF 3 2001-12-18 "GNU" "Linux Programmer's Manual" +.SH NAME +asprintf, vasprintf \- print to allocated string +.SH SYNOPSIS +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "int asprintf(char **" strp ", const char *" fmt ", ...);" +.sp +.BI "int vasprintf(char **" strp ", const char *" fmt ", va_list " ap ); +.SH DESCRIPTION +The functions +.B asprintf +and +.B vasprintf +are analogues of +.B sprintf +and +.BR vsprintf , +except that they allocate a string large enough to hold the output +including the terminating NUL, +and return a pointer to it via the first parameter. +This pointer should be passed to +.BR free (3) +to release the allocated storage when it is no longer needed. +.SH "RETURN VALUE" +When successful, these functions return the number of bytes printed, +just like +.BR sprintf (3). +If memory allocation wasn't possible, or some other error occurs, +these functions will return \-1, and the contents of +.I strp +is undefined. +.SH NOTES +These functions are GNU extensions, not in C or POSIX. +They are also available under *BSD. +The FreeBSD implementation sets +.I strp +to NULL on error. +.SH "SEE ALSO" +.BR free (3), +.BR malloc (3), +.BR printf (3) diff --git a/man3/assert.3 b/man3/assert.3 new file mode 100644 index 000000000..728cc08b7 --- /dev/null +++ b/man3/assert.3 @@ -0,0 +1,74 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 21:42:42 1993 by Rik Faith +.\" Modified Tue Oct 22 23:44:11 1996 by Eric S. Raymond +.TH ASSERT 3 2002-08-25 "C99" "Linux Programmer's Manual" +.SH NAME +assert \- abort the program if assertion is false +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void assert(scalar " expression ); +.fi +.SH DESCRIPTION +If the macro +.B NDEBUG +was defined at the moment +.B +was last included, the macro +.B assert() +generates no code, and hence does nothing at all. +Otherwise, the macro +.B assert() +prints an error message to standard output and terminates the program +by calling +.B abort() +if +.I expression +is false (i.e., compares equal to zero). +.LP +The purpose of this macro is to help the programmer find bugs in +his program. The message "assertion failed in file foo.c, function +do_bar(), line 1287" is of no help at all to a user. +.SH "RETURN VALUE" +No value is returned. +.SH "CONFORMING TO" +ISO9899 (ANSI C). In the 1990 standard, +.I expression +is required to be of type +.B int +and undefined behavior results if it is not, but in the 1999 standard +it may have any scalar type. +.\" See Defect Report 107 for more details. +.SH BUGS +.B assert() +is implemented as a macro; if the expression tested has side-effects, +program behaviour will be different depending on whether +.B NDEBUG +is defined. This may create Heisenbugs which go away when debugging +is turned on. +.SH "SEE ALSO" +.BR abort (3), +.BR assert_perror (3), +.BR exit (3) diff --git a/man3/assert_perror.3 b/man3/assert_perror.3 new file mode 100644 index 000000000..02d6d9b22 --- /dev/null +++ b/man3/assert_perror.3 @@ -0,0 +1,68 @@ +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.\" +.TH ASSERT_PERROR 3 2002-08-25 "GNU" "Linux Programmer's Manual" +.SH NAME +assert_perror \- test errnum and abort +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void assert_perror(int " errnum ); +.fi +.SH DESCRIPTION +If the macro +.B NDEBUG +was defined at the moment +.B +was last included, the macro +.B assert_perror() +generates no code, and hence does nothing at all. +Otherwise, the macro +.B assert_perror() +prints an error message to standard output and terminates the program +by calling +.B abort() +if +.I errnum +is nonzero. The message contains the filename, function name and +line number of the macro call, and the output of +.IR strerror(errnum) . +.SH "RETURN VALUE" +No value is returned. +.SH "CONFORMING TO" +This is a GNU extension. +.SH BUGS +The purpose of the assert macros is to help the programmer find bugs in +his program, things that cannot happen unless there was a coding mistake. +However, with system or library calls the situation is rather different, +and error returns can happen, and will happen, and should be tested for. +Not by an assert, where the test goes away when NDEBUG is defined, +but by proper error handling code. Never use this macro. +.SH "SEE ALSO" +.BR abort (3), +.BR assert (3), +.BR exit (3), +.BR strerror (3) diff --git a/man3/atan.3 b/man3/atan.3 new file mode 100644 index 000000000..13151c26e --- /dev/null +++ b/man3/atan.3 @@ -0,0 +1,62 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ATAN 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +atan, atanf, atanl \- arc tangent function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double atan(double " x ); +.sp +.BI "float atanf(float " x ); +.sp +.BI "long double atanl( long double " x ); +.sp +.fi +Link with \-lm. +.SH DESCRIPTION +The \fBatan()\fP function calculates the arc tangent of \fIx\fP; that is +the value whose tangent is \fIx\fP. +.SH "RETURN VALUE" +The \fBatan()\fP function returns the arc tangent in radians and the +value is mathematically defined to be between -PI/2 and PI/2 +(inclusive). +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and long double variants are C99 requirements. +.SH "SEE ALSO" +.BR acos (3), +.BR asin (3), +.BR atan2 (3), +.BR cos (3), +.BR sin (3), +.BR tan (3) diff --git a/man3/atan2.3 b/man3/atan2.3 new file mode 100644 index 000000000..ed4ff9580 --- /dev/null +++ b/man3/atan2.3 @@ -0,0 +1,63 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ATAN2 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +atan2, atan2f, atan2l \- arc tangent function of two variables +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double atan2(double " y ", double " x ); +.sp +.BI "float atan2f(float " y ", float " x ); +.sp +.BI "long double atan2l(long double " y ", long double " x ); +.sp +.fi +Link with \-lm. +.SH DESCRIPTION +The \fBatan2()\fP function calculates the arc tangent of the two +variables \fIx\fP and \fIy\fP. It is similar to calculating the +arc tangent of \fIy\fP / \fIx\fP, except that the signs of both +arguments are used to determine the quadrant of the result. +.SH "RETURN VALUE" +The \fBatan2()\fP function returns the result in radians, which +is between -PI and PI (inclusive). +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and long double variants are C99 requirements. +.SH "SEE ALSO" +.BR acos (3), +.BR asin (3), +.BR atan (3), +.BR cos (3), +.BR sin (3), +.BR tan (3) diff --git a/man3/atan2f.3 b/man3/atan2f.3 new file mode 100644 index 000000000..e445b12b6 --- /dev/null +++ b/man3/atan2f.3 @@ -0,0 +1 @@ +.so man3/atan2.3 diff --git a/man3/atan2l.3 b/man3/atan2l.3 new file mode 100644 index 000000000..e445b12b6 --- /dev/null +++ b/man3/atan2l.3 @@ -0,0 +1 @@ +.so man3/atan2.3 diff --git a/man3/atanf.3 b/man3/atanf.3 new file mode 100644 index 000000000..784b32ab9 --- /dev/null +++ b/man3/atanf.3 @@ -0,0 +1 @@ +.so man3/atan.3 diff --git a/man3/atanh.3 b/man3/atanh.3 new file mode 100644 index 000000000..f28ce7ce1 --- /dev/null +++ b/man3/atanh.3 @@ -0,0 +1,63 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ATANH 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +atanh, atanhf, atanhl \- inverse hyperbolic tangent function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double atanh(double " x ); +.sp +.BI "float atanhf(float " x ); +.sp +.BI "long double atanhl(long double " x ); +.sp +.fi +Link with \-lm. +.SH DESCRIPTION +The \fBatanh()\fP function calculates the inverse hyperbolic tangent of +\fIx\fP; that is the value whose hyperbolic tangent is \fIx\fP. If the +absolute value of \fIx\fP is greater than 1.0, \fBacosh()\fP returns +not-a-number (NaN) and \fIerrno\fP is set. +.SH ERRORS +.TP +.B EDOM +\fIx\fP is out of range. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and long double variants are C99 requirements. +.SH "SEE ALSO" +.BR acosh (3), +.BR asinh (3), +.BR cosh (3), +.BR sinh (3), +.BR tanh (3) diff --git a/man3/atanhf.3 b/man3/atanhf.3 new file mode 100644 index 000000000..225a33928 --- /dev/null +++ b/man3/atanhf.3 @@ -0,0 +1 @@ +.so man3/atanh.3 diff --git a/man3/atanhl.3 b/man3/atanhl.3 new file mode 100644 index 000000000..225a33928 --- /dev/null +++ b/man3/atanhl.3 @@ -0,0 +1 @@ +.so man3/atanh.3 diff --git a/man3/atanl.3 b/man3/atanl.3 new file mode 100644 index 000000000..784b32ab9 --- /dev/null +++ b/man3/atanl.3 @@ -0,0 +1 @@ +.so man3/atan.3 diff --git a/man3/atexit.3 b/man3/atexit.3 new file mode 100644 index 000000000..c38962017 --- /dev/null +++ b/man3/atexit.3 @@ -0,0 +1,87 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 2003-10-25, Walter Harms +.\" +.TH ATEXIT 3 2003-11-01 "" "Linux Programmer's Manual" +.SH NAME +atexit \- register a function to be called at normal program termination +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int atexit(void (*" function )(void)); +.fi +.SH DESCRIPTION +The \fBatexit()\fP function registers the given \fIfunction\fP to be +called at normal program termination, either via +.BR exit (3) +or via return from the program's \fBmain\fP(). +Functions so registered are called in +the reverse order of their registration; no arguments are passed. +.LP +At least ATEXIT_MAX functions can be registered. This value +is at least 32. It can be obtained using +.BR sysconf (3). +.LP +By a successful call to one of the exec functions, +all registrations are undone. +.SH "RETURN VALUE" +The \fBatexit()\fP function returns the value 0 if successful; otherwise +it returns a nonzero value. +.SH EXAMPLE +.nf +#include +#include +#include + +void bye(void) { + printf("That was all, folks\en"); +} + +int main(){ + long a; + int i; + + a = sysconf(_SC_ATEXIT_MAX); + printf("ATEXIT_MAX = %ld\en", a); + + i = atexit(bye); + if (i != 0) { + fprintf(stderr, "cannot set exit function\en"); + return EXIT_FAILURE; + } + return EXIT_SUCCESS; +} +.fi +.SH "CONFORMING TO" +SVID 3, BSD 4.3, ISO 9899, POSIX 1003.1-2001 +.SH "SEE ALSO" +.BR _exit (3), +.BR exit (3), +.BR on_exit (3) diff --git a/man3/atof.3 b/man3/atof.3 new file mode 100644 index 000000000..3088cb1d4 --- /dev/null +++ b/man3/atof.3 @@ -0,0 +1,56 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Mar 29 22:39:24 1993, David Metcalfe +.\" Modified Sat Jul 24 21:39:22 1993, Rik Faith (faith@cs.unc.edu) +.TH ATOF 3 1993-03-29 "GNU" "Linux Programmer's Manual" +.SH NAME +atof \- convert a string to a double +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double atof(const char *" nptr ); +.fi +.SH DESCRIPTION +The \fBatof()\fP function converts the initial portion of the string +pointed to by \fInptr\fP to double. The behaviour is the same as +.sp +.RS +.B strtod(nptr, (char **)NULL); +.RE +.sp +except that \fBatof()\fP does not detect errors. +.SH "RETURN VALUE" +The converted value. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899 +.SH "SEE ALSO" +.BR atoi (3), +.BR atol (3), +.BR strtod (3), +.BR strtol (3), +.BR strtoul (3) diff --git a/man3/atoi.3 b/man3/atoi.3 new file mode 100644 index 000000000..a1fa01b5c --- /dev/null +++ b/man3/atoi.3 @@ -0,0 +1,78 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Mar 29 22:39:41 1993, David Metcalfe +.\" Modified Sat Jul 24 21:38:42 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Dec 17 18:35:06 2000, Joseph S. Myers +.\" +.TH ATOI 3 2000-12-17 "GNU" "Linux Programmer's Manual" +.SH NAME +atoi, atol, atoll, atoq \- convert a string to an integer +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int atoi(const char *" nptr ); +.br +.BI "long atol(const char *" nptr ); +.br +.BI "long long atoll(const char *" nptr ); +.br +.BI "long long atoq(const char *" nptr ); +.fi +.SH DESCRIPTION +The \fBatoi()\fP function converts the initial portion of the string +pointed to by \fInptr\fP to +.IR int . +The behaviour is the same as +.sp +.RS +.B strtol(nptr, (char **)NULL, 10); +.RE +.sp +except that \fBatoi()\fP does not detect errors. +.PP +The \fBatol()\fP and \fBatoll()\fP functions behave the same as +\fBatoi()\fR, except that they convert the initial portion of the +string to their return type of \fIlong\fP or \fIlong long\fP. +\fBatoq()\fP is an obsolete name for \fBatoll()\fP. +.SH "RETURN VALUE" +The converted value. +.SH "CONFORMING TO" +SVID 3, POSIX.1, BSD 4.3, ISO/IEC 9899. ISO/IEC 9899:1990 (C89) and +POSIX.1 (1996 edition) include the functions \fBatoi()\fP and +\fBatol()\fP only; C99 adds the function \fBatoll()\fP. +.SH NOTES +The non-standard \fBatoq()\fP function is not present in libc 4.6.27 +or glibc 2, but is present in libc5 and libc 4.7 (though only as an +inline function in \fB\fP until libc 5.4.44). The +\fBatoll()\fP function is present in glibc 2 since version 2.0.2, but +not in libc4 or libc5. +.SH "SEE ALSO" +.BR atof (3), +.BR strtod (3), +.BR strtol (3), +.BR strtoul (3) diff --git a/man3/atol.3 b/man3/atol.3 new file mode 100644 index 000000000..51f084f16 --- /dev/null +++ b/man3/atol.3 @@ -0,0 +1 @@ +.so man3/atoi.3 diff --git a/man3/atoll.3 b/man3/atoll.3 new file mode 100644 index 000000000..51f084f16 --- /dev/null +++ b/man3/atoll.3 @@ -0,0 +1 @@ +.so man3/atoi.3 diff --git a/man3/atoq.3 b/man3/atoq.3 new file mode 100644 index 000000000..51f084f16 --- /dev/null +++ b/man3/atoq.3 @@ -0,0 +1 @@ +.so man3/atoi.3 diff --git a/man3/auth_destroy.3 b/man3/auth_destroy.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/auth_destroy.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/authnone_create.3 b/man3/authnone_create.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/authnone_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/authunix_create.3 b/man3/authunix_create.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/authunix_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/authunix_create_default.3 b/man3/authunix_create_default.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/authunix_create_default.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/basename.3 b/man3/basename.3 new file mode 100644 index 000000000..5f0629d5c --- /dev/null +++ b/man3/basename.3 @@ -0,0 +1,163 @@ +.\" (c) 2000 by Michael Kerrisk (michael.kerrisk@gmx.net) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Created, 14 Dec 2000 by Michael Kerrisk +.\" +.TH DIRNAME 3 2000-12-14 "GNU" "Linux Programmer's Manual" +.SH NAME +dirname, basename \- Parse pathname components +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *dirname(char *" path ); +.nl +.BI "char *basename(char *" path ); +.fi +.SH DESCRIPTION +Warning: there are two different functions +.B basename +- see below. +.LP +The functions +.B dirname +and +.B basename +break a null-terminated pathname string into directory +and filename components. +In the usual case, +.B dirname +returns the string up to, but not including, the final '/', and +.B basename +returns the component following the final '/'. +Trailing '/' characters are not counted as part of the pathname. +.PP +If +.I path +does not contain a slash, +.B dirname +returns the string "." while +.B basename +returns a copy of +.IR path . +If +.I path +is the string "/", then both +.B dirname +and +.B basename +return the string "/". +If +.I path +is a NULL pointer or points to an empty string, then both +.B dirname +and +.B basename +return the string ".". +.PP +Concatenating the string returned by +.BR dirname , +a "/", and the string returned by +.B basename +yields a complete pathname. +.PP +Both +.B dirname +and +.B basename +may modify the contents of +.IR path , +so copies should be passed to these functions. +Furthermore, +.B dirname +and +.B basename +may return pointers to statically allocated memory +which may be overwritten by subsequent calls. +.PP +The following list of examples (taken from SUSv2) +shows the strings returned by +.B dirname +and +.B basename +for different paths: +.sp +.nf +.B +path dirname basename +"/usr/lib" "/usr" "lib" +"/usr/" "/" "usr" +"usr" "." "usr" +"/" "/" "/" +"." "." "." +".." "." ".." +.fi +.SH EXAMPLE +.RS +.nf +char *dirc, *basec, *bname, *dname; +char *path = "/etc/passwd"; + +dirc = strdup(path); +basec = strdup(path); +dname = dirname(dirc); +bname = basename(basec); +printf("dirname=%s, basename=%s\\n", dname, bname); +.fi +.RE +.SH "RETURN VALUE" +Both +.B dirname +and +.B basename +return pointers to null-terminated strings. +.SH NOTES +There are two different versions of +.B basename +- the POSIX version described above, and the GNU version one gets +after +.br +.nf +.B " #define _GNU_SOURCE" +.br +.B " #include " +.fi +The GNU version never modifies its argument, and returns the +empty string when +.I path +has a trailing slash, and in particular also when it is "/". +There is no GNU version of +.BR dirname . +.LP +With glibc, one gets the POSIX version of +.B basename +when is included, and the GNU version otherwise. +.SH BUGS +In the glibc implementation of the POSIX versions of these functions +they modify their argument, and segfault when called with a static string +like "/usr/". +Before glibc 2.2.1, the glibc version of +.B dirname +did not correctly handle pathnames with trailing '/' characters, +and generated a segfault if given a NULL argument. +.SH "CONFORMING TO" +POSIX 1003.1-2001 +.SH "SEE ALSO" +.BR basename (1), +.BR dirname (1) diff --git a/man3/bcmp.3 b/man3/bcmp.3 new file mode 100644 index 000000000..c940645e2 --- /dev/null +++ b/man3/bcmp.3 @@ -0,0 +1,67 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:36:50 1993 by Rik Faith +.\" Modified Tue Oct 22 23:47:36 1996 by Eric S. Raymond +.TH BCMP 3 2002-12-31 "Linux" "Linux Programmer's Manual" +.SH NAME +bcmp \- compare byte sequences +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int bcmp(const void *" s1 ", const void *" s2 ", size_t " n ); +.fi +.SH DESCRIPTION +The +.B bcmp() +function compares the two byte sequences +.I s1 +and +.I s2 +of length +.I n +each. If they are equal, and in particular if +.I n +is zero, +.B bcmp() +returns 0. Otherwise it returns a non-zero result. +.SH "RETURN VALUE" +The +.B bcmp() +function returns 0 if the byte sequences are equal, +otherwise a non-zero result is returned. +.SH "CONFORMING TO" +4.3BSD. This function is deprecated -- use +.BR memcmp +in new programs. +.SH "SEE ALSO" +.BR memcmp (3), +.BR strcasecmp (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strncasecmp (3), +.BR strncmp (3) diff --git a/man3/bcopy.3 b/man3/bcopy.3 new file mode 100644 index 000000000..1d1a37bb1 --- /dev/null +++ b/man3/bcopy.3 @@ -0,0 +1,63 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified Sun Feb 26 14:52:00 1995 by Rik Faith +.\" Modified Tue Oct 22 23:48:10 1996 by Eric S. Raymond +.\" " +.TH BCOPY 3 2002-12-31 "Linux" "LINUX Programmer's Manual" +.SH NAME +bcopy \- copy byte sequence +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void bcopy(const void *" src ", void *" dest ", size_t " n ); +.fi +.SH DESCRIPTION +The +.B bcopy() +function copies +.I n +bytes from +.I src +to +.IR dest . +The result is correct, even when both areas overlap. +.SH "RETURN VALUE" +None. +.SH "CONFORMING TO" +4.3BSD. This function is deprecated -- use +.B memcpy +in new programs. Note that the first two parameters +are interchanged for +.BR memcpy . +.SH "SEE ALSO" +.BR memccpy (3), +.BR memcpy (3), +.BR memmove (3), +.BR strcpy (3), +.BR strncpy (3) diff --git a/man3/bindresvport.3 b/man3/bindresvport.3 new file mode 100644 index 000000000..2bfa74101 --- /dev/null +++ b/man3/bindresvport.3 @@ -0,0 +1,27 @@ +.\" @(#)bindresvport.3n 2.2 88/08/02 4.0 RPCSRC; from 1.7 88/03/14 SMI +.TH BINDRESVPORT 3 1987-11-22 +.SH NAME +bindresvport \- bind a socket to a privileged IP port +.SH SYNOPSIS +.nf +.B #include +.B #include +.LP +.B int bindresvport(sd, sin) +.B int sd; +.B struct sockaddr_in \(**sin; +.fi +.SH DESCRIPTION +.LP +.B bindresvport() +is used to bind a socket descriptor to a privileged +.SM IP +port, that is, a +port number in the range 0-1023. +The routine returns 0 if it is successful, +otherwise \-1 is returned and +.B errno +set to reflect the cause of the error. +.LP +Only root can bind to a privileged port; this call will fail for any +other users. diff --git a/man3/bsearch.3 b/man3/bsearch.3 new file mode 100644 index 000000000..f065011cf --- /dev/null +++ b/man3/bsearch.3 @@ -0,0 +1,110 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Mar 29 22:41:16 1993, David Metcalfe +.\" Modified Sat Jul 24 21:35:16 1993, Rik Faith (faith@cs.unc.edu) +.TH BSEARCH 3 2003-11-01 "" "Linux Programmer's Manual" +.SH NAME +bsearch \- binary search of a sorted array +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void *bsearch(const void *" key ", const void *" base ", size_t " nmemb , +.RS +.BI "size_t " size ", int (*" compar ")(const void *, const void *));" +.RE +.fi +.SH DESCRIPTION +The \fBbsearch()\fP function searches an array of \fInmemb\fP objects, +the initial member of which is pointed to by \fIbase\fP, for a member +that matches the object pointed to by \fIkey\fP. The size of each member +of the array is specified by \fIsize\fP. +.PP +The contents of the array should be in ascending sorted order according +to the comparison function referenced by \fIcompar\fP. The \fIcompar\fP +routine is expected to have two arguments which point to the \fIkey\fP +object and to an array member, in that order, and should return an integer +less than, equal to, or greater than zero if the \fIkey\fP object is found, +respectively, to be less than, to match, or be greater than the array +member. +.SH "RETURN VALUE" +The \fBbsearch()\fP function returns a pointer to a matching member of the +array, or NULL if no match is found. If there are multiple elements that +match the key, the element returned is unspecified. +.SH EXAMPLE +The example below first sorts an array of structures using +.BR qsort (3), +then retrieves desired elements using +.BR bsearch() . +.sp +.nf +#include +#include +#include + +struct mi { + int nr; + char *name; +} months[] = { + { 1, "jan" }, { 2, "feb" }, { 3, "mar" }, { 4, "apr" }, + { 5, "may" }, { 6, "jun" }, { 7, "jul" }, { 8, "aug" }, + { 9, "sep" }, {10, "oct" }, {11, "nov" }, {12, "dec" } +}; + +#define nr_of_months (sizeof(months)/sizeof(months[0])) + +static int compmi(const void *m1, const void *m2) { + struct mi *mi1 = (struct mi *) m1; + struct mi *mi2 = (struct mi *) m2; + return strcmp(mi1->name, mi2->name); +} + +int main(int argc, char **argv) { + int i; + + qsort(months, nr_of_months, sizeof(struct mi), compmi); + for (i = 1; i < argc; i++) { + struct mi key, *res; + key.name = argv[i]; + res = bsearch(&key, months, nr_of_months, + sizeof(struct mi), compmi); + if (res == NULL) + printf("'%s': unknown month\en", argv[i]); + else + printf("%s: month #%d\en", res->name, res->nr); + } + return 0; +} +.fi +.\" this example referred to in qsort.3 +.SH "CONFORMING TO" +SVID 3, BSD 4.3, ISO 9899 (C99) +.SH "SEE ALSO" +.BR hsearch (3), +.BR lsearch (3), +.BR qsort (3), +.BR tsearch (3) diff --git a/man3/bstring.3 b/man3/bstring.3 new file mode 100644 index 000000000..b858305ca --- /dev/null +++ b/man3/bstring.3 @@ -0,0 +1,91 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-04-12, David Metcalfe +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-01-20, Walter Harms +.TH BSTRING 3 2002-01-20 "" "Linux Programmer's Manual" +.SH NAME +bcmp, bcopy, bzero, memccpy, memchr, memcmp, memcpy, memfrob, memmem, +memmove, memset \- byte string operations +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int bcmp(const void *" s1 ", const void *" s2 ", int " n ); +.sp +.BI "void bcopy(const void *" src ", void *" dest ", int " n ); +.sp +.BI "void bzero(void *" s ", int " n ); +.sp +.BI "void *memccpy(void *" dest ", const void *" src ", int " c ", size_t " n ); +.sp +.BI "void *memchr(const void *" s ", int " c ", size_t " n ); +.sp +.BI "int memcmp(const void *" s1 ", const void *" s2 ", size_t " n ); +.sp +.BI "void *memcpy(void *" dest ", const void *" src ", size_t " n ); +.sp +.BI "void *memfrob(void *" s ", size_t " n ); +.sp +.BI "void *memmem(const void *" needle ", size_t " needlelen , +.RS +.BI "const void *" haystack ", size_t " haystacklen ); +.RE +.sp +.BI "void *memmove(void *" dest ", const void *" src ", size_t " n ); +.sp +.BI "void *memset(void *" s ", int " c ", size_t " n ); +.fi +.SH DESCRIPTION +The byte string functions perform operations on strings (byte arrays) +that are not necessarily NUL-terminated. See the individual man pages +for descriptions of each function. +.SH NOTE +The functions +.BR bcmp (), +.BR bcopy () +and +.BR bzero () +are obsolete. Use +.BR memcmp (), +.BR memcpy () +and +.BR memset () +instead. +.\" The old functions are not even available on some non-GNU/Linux systems. +.SH "SEE ALSO" +.BR bcmp (3), +.BR bcopy (3), +.BR bzero (3), +.BR memccpy (3), +.BR memchr (3), +.BR memcmp (3), +.BR memcpy (3), +.BR memfrob (3), +.BR memmem (3), +.BR memmove (3), +.BR memset (3) diff --git a/man3/btowc.3 b/man3/btowc.3 new file mode 100644 index 000000000..e93c5a562 --- /dev/null +++ b/man3/btowc.3 @@ -0,0 +1,42 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH BTOWC 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +btowc \- convert single byte to wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wint_t btowc(int " c ); +.fi +.SH DESCRIPTION +The \fBbtowc\fP function converts \fIc\fP, interpreted as a multibyte sequence +of length 1, starting in the initial shift state, to a wide character and +returns it. If \fIc\fP is EOF or not a valid multibyte sequence of length 1, +the \fBbtowc\fP function returns WEOF. +.SH "RETURN VALUE" +The \fBbtowc\fP function returns the wide character converted from the single +byte \fIc\fP. If \fIc\fP is EOF or not a valid multibyte sequence of length 1, +it returns WEOF. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR mbtowc (3) +.SH NOTES +The behaviour of \fBbtowc\fP depends on the LC_CTYPE category of the +current locale. +.PP +This function should never be used. It does not work for encodings which have +state, and unnecessarily treats single bytes differently from multibyte +sequences. Use the function \fBmbtowc\fP instead. diff --git a/man3/btree.3 b/man3/btree.3 new file mode 100644 index 000000000..40705d9a7 --- /dev/null +++ b/man3/btree.3 @@ -0,0 +1,233 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)btree.3 8.4 (Berkeley) 8/18/94 +.\" +.TH BTREE 3 1994-08-18 +.\".UC 7 +.SH NAME +btree \- btree database access method +.SH SYNOPSIS +.nf +.ft B +#include +#include +.ft R +.fi +.SH DESCRIPTION +The routine +.IR dbopen +is the library interface to database files. +One of the supported file formats is btree files. +The general description of the database access methods is in +.IR dbopen (3), +this manual page describes only the btree specific information. +.PP +The btree data structure is a sorted, balanced tree structure storing +associated key/data pairs. +.PP +The btree access method specific data structure provided to +.I dbopen +is defined in the include file as follows: +.PP +typedef struct { +.RS +u_long flags; +.br +u_int cachesize; +.br +int maxkeypage; +.br +int minkeypage; +.br +u_int psize; +.br +int (*compare)(const DBT *key1, const DBT *key2); +.br +size_t (*prefix)(const DBT *key1, const DBT *key2); +.br +int lorder; +.RE +} BTREEINFO; +.PP +The elements of this structure are as follows: +.TP +flags +The flag value is specified by +.IR or 'ing +any of the following values: +.RS +.TP +R_DUP +Permit duplicate keys in the tree, i.e. permit insertion if the key to be +inserted already exists in the tree. +The default behavior, as described in +.IR dbopen (3), +is to overwrite a matching key when inserting a new key or to fail if +the R_NOOVERWRITE flag is specified. +The R_DUP flag is overridden by the R_NOOVERWRITE flag, and if the +R_NOOVERWRITE flag is specified, attempts to insert duplicate keys into +the tree will fail. +.IP +If the database contains duplicate keys, the order of retrieval of +key/data pairs is undefined if the +.I get +routine is used, however, +.I seq +routine calls with the R_CURSOR flag set will always return the logical +``first'' of any group of duplicate keys. +.RE +.TP +cachesize +A suggested maximum size (in bytes) of the memory cache. +This value is +.B only +advisory, and the access method will allocate more memory rather than fail. +Since every search examines the root page of the tree, caching the most +recently used pages substantially improves access time. +In addition, physical writes are delayed as long as possible, so a moderate +cache can reduce the number of I/O operations significantly. +Obviously, using a cache increases (but only increases) the likelihood of +corruption or lost data if the system crashes while a tree is being modified. +If +.I cachesize +is 0 (no size is specified) a default cache is used. +.TP +maxkeypage +The maximum number of keys which will be stored on any single page. +Not currently implemented. +.\" The maximum number of keys which will be stored on any single page. +.\" Because of the way the btree data structure works, +.\" .I maxkeypage +.\" must always be greater than or equal to 2. +.\" If +.\" .I maxkeypage +.\" is 0 (no maximum number of keys is specified) the page fill factor is +.\" made as large as possible (which is almost invariably what is wanted). +.TP +minkeypage +The minimum number of keys which will be stored on any single page. +This value is used to determine which keys will be stored on overflow +pages, i.e. if a key or data item is longer than the pagesize divided +by the minkeypage value, it will be stored on overflow pages instead +of in the page itself. +If +.I minkeypage +is 0 (no minimum number of keys is specified) a value of 2 is used. +.TP +psize +Page size is the size (in bytes) of the pages used for nodes in the tree. +The minimum page size is 512 bytes and the maximum page size is 64K. +If +.I psize +is 0 (no page size is specified) a page size is chosen based on the +underlying file system I/O block size. +.TP +compare +Compare is the key comparison function. +It must return an integer less than, equal to, or greater than zero if the +first key argument is considered to be respectively less than, equal to, +or greater than the second key argument. +The same comparison function must be used on a given tree every time it +is opened. +If +.I compare +is NULL (no comparison function is specified), the keys are compared +lexically, with shorter keys considered less than longer keys. +.TP +prefix +Prefix is the prefix comparison function. +If specified, this routine must return the number of bytes of the second key +argument which are necessary to determine that it is greater than the first +key argument. +If the keys are equal, the key length should be returned. +Note, the usefulness of this routine is very data dependent, but, in some +data sets can produce significantly reduced tree sizes and search times. +If +.I prefix +is NULL (no prefix function is specified), +.B and +no comparison function is specified, a default lexical comparison routine +is used. +If +.I prefix +is NULL and a comparison routine is specified, no prefix comparison is +done. +.TP +lorder +The byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.I lorder +is 0 (no order is specified) the current host order is used. +.PP +If the file already exists (and the O_TRUNC flag is not specified), the +values specified for the parameters flags, lorder and psize are ignored +in favor of the values used when the tree was created. +.PP +Forward sequential scans of a tree are from the least key to the greatest. +.PP +Space freed up by deleting key/data pairs from the tree is never reclaimed, +although it is normally made available for reuse. +This means that the btree storage structure is grow-only. +The only solutions are to avoid excessive deletions, or to create a fresh +tree periodically from a scan of an existing one. +.PP +Searches, insertions, and deletions in a btree will all complete in +O lg base N where base is the average fill factor. +Often, inserting ordered data into btrees results in a low fill factor. +This implementation has been modified to make ordered insertion the best +case, resulting in a much better than normal page fill factor. +.SH ERRORS +The +.I btree +access method routines may fail and set +.I errno +for any of the errors specified for the library routine +.IR dbopen (3). +.SH "SEE ALSO" +.IR dbopen (3), +.IR hash (3), +.IR mpool (3), +.IR recno (3) +.sp +.IR "The Ubiquitous B-tree" , +Douglas Comer, ACM Comput. Surv. 11, 2 (June 1979), 121-138. +.sp +.IR "Prefix B-trees" , +Bayer and Unterauer, ACM Transactions on Database Systems, Vol. 2, 1 +(March 1977), 11-26. +.sp +.IR "The Art of Computer Programming Vol. 3: Sorting and Searching" , +D.E. Knuth, 1968, pp 471-480. +.SH BUGS +Only big and little endian byte order is supported. diff --git a/man3/byteorder.3 b/man3/byteorder.3 new file mode 100644 index 000000000..ddc594793 --- /dev/null +++ b/man3/byteorder.3 @@ -0,0 +1,66 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:29:05 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Thu Jul 26 14:06:20 2001 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH BYTEORDER 3 1993-04-15 "BSD" "Linux Programmer's Manual" +.SH NAME +htonl, htons, ntohl, ntohs \- convert values between host and network +byte order +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "uint32_t htonl(uint32_t " hostlong ); +.sp +.BI "uint16_t htons(uint16_t " hostshort ); +.sp +.BI "uint32_t ntohl(uint32_t " netlong ); +.sp +.BI "uint16_t ntohs(uint16_t " netshort ); +.fi +.SH DESCRIPTION +The \fBhtonl()\fP function converts the unsigned integer \fIhostlong\fP +from host byte order to network byte order. +.PP +The \fBhtons()\fP function converts the unsigned short integer \fIhostshort\fP +from host byte order to network byte order. +.PP +The \fBntohl()\fP function converts the unsigned integer \fInetlong\fP +from network byte order to host byte order. +.PP +The \fBntohs()\fP function converts the unsigned short integer \fInetshort\fP +from network byte order to host byte order. +.PP +On the i80x86 the host byte order is Least Significant Byte first, +whereas the network byte order, as used on the Internet, is Most +Significant Byte first. +.SH "CONFORMING TO" +BSD 4.3 +.SH "SEE ALSO" +.BR gethostbyname (3), +.BR getservent (3) diff --git a/man3/bzero.3 b/man3/bzero.3 new file mode 100644 index 000000000..e648e811f --- /dev/null +++ b/man3/bzero.3 @@ -0,0 +1,54 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:28:17 1993 by Rik Faith +.\" Modified Tue Oct 22 23:49:37 1996 by Eric S. Raymond +.TH BZERO 3 2002-12-31 "Linux" "Linux Programmer's Manual" +.SH NAME +bzero \- write zero bytes +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void bzero(void *" s ", size_t " n ); +.fi +.SH DESCRIPTION +The +.B bzero() +function sets the first +.I n +bytes of the byte area starting at +.I s +to zero. +.SH "RETURN VALUE" +None. +.SH "CONFORMING TO" +4.3BSD. This function is deprecated -- use +.BR memset +in new programs. +.SH "SEE ALSO" +.BR memset (3), +.BR swab (3) diff --git a/man3/cabs.3 b/man3/cabs.3 new file mode 100644 index 000000000..ff924fc4f --- /dev/null +++ b/man3/cabs.3 @@ -0,0 +1,28 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CABS 3 2002-07-28 "" "complex math routines" +.SH NAME +cabs, cabsf, cabsl \- absolute value of a complex number +.SH SYNOPSIS +.B #include +.sp +.BI "double cabs(double complex " z ); +.sp +.BI "float cabsf(float complex " z ); +.sp +.BI "long double cabsl(long double complex " z ); +.sp +Link with \-lm. +.SH DESCRIPTION +The cabs() function returns the absolute value of the complex number z. The +result is a real number. +.SH NOTE +The function is actually an alias for hypot(a,b) = sqrt(a*a+b*b). +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR abs (3), +.BR cimag (3), +.BR hypot (3), +.BR complex (5) diff --git a/man3/cabsf.3 b/man3/cabsf.3 new file mode 100644 index 000000000..ba441dbab --- /dev/null +++ b/man3/cabsf.3 @@ -0,0 +1 @@ +.so man3/cabs.3 diff --git a/man3/cabsl.3 b/man3/cabsl.3 new file mode 100644 index 000000000..ba441dbab --- /dev/null +++ b/man3/cabsl.3 @@ -0,0 +1 @@ +.so man3/cabs.3 diff --git a/man3/cacos.3 b/man3/cacos.3 new file mode 100644 index 000000000..13e3aacbf --- /dev/null +++ b/man3/cacos.3 @@ -0,0 +1,28 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CACOS 3 2002-07-28 "" "complex math routines" +.SH NAME +cacos, cacosf, cacosl \- complex arc cosine +.SH SYNOPSIS +.B #include +.sp +.BI "double complex cacos(double complex " z ); +.sp +.BI "float complex cacosf(float complex " z ); +.sp +.BI "long double complex cacosl(long double complex " z ); +.sp +Link with \-lm. +.SH DESCRIPTION +The cacos() function calculates the complex acos(). +If y = cacos(z), then z = ccos(y). +The real part of y is chosen in the interval [0,pi]. +.LP +One has cacos(z) = -i clog(z+csqrt(z*z-1)). +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR ccos (3), +.BR clog (3), +.BR complex (5) diff --git a/man3/cacosf.3 b/man3/cacosf.3 new file mode 100644 index 000000000..a4f10e17f --- /dev/null +++ b/man3/cacosf.3 @@ -0,0 +1 @@ +.so man3/cacos.3 diff --git a/man3/cacosh.3 b/man3/cacosh.3 new file mode 100644 index 000000000..f4780f575 --- /dev/null +++ b/man3/cacosh.3 @@ -0,0 +1,30 @@ +.\" Copyright 2002 Walter Harms(walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CACOSH 3 2002-07-28 "" "complex math routines" +.SH NAME +cacosh, cacoshf, cacoshl \- complex arc hyperbolic cosine +.SH SYNOPSIS +.B #include +.sp +.BI "double complex cacosh(double complex " z ); +.sp +.BI "float complex cacoshf(float complex " z ); +.sp +.BI "long double complex cacoshl(long double complex " z ); +.sp +Link with \-lm. +.SH DESCRIPTION +The cacosh() function calculates the complex acosh(). +If y = cacosh(z), then z = ccosh(y). +The imaginary part of y is chosen in the interval [-pi,pi]. +The real part of y is chosen nonnegative. +.LP +One has cacosh(z) = (0.5)*clog((1+z)/(1-z)). +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR acosh (3), +.BR cabs (3), +.BR cimag (3), +.BR complex (5) diff --git a/man3/cacoshf.3 b/man3/cacoshf.3 new file mode 100644 index 000000000..5853c95f1 --- /dev/null +++ b/man3/cacoshf.3 @@ -0,0 +1 @@ +.so man3/cacosh.3 diff --git a/man3/cacoshl.3 b/man3/cacoshl.3 new file mode 100644 index 000000000..5853c95f1 --- /dev/null +++ b/man3/cacoshl.3 @@ -0,0 +1 @@ +.so man3/cacosh.3 diff --git a/man3/cacosl.3 b/man3/cacosl.3 new file mode 100644 index 000000000..a4f10e17f --- /dev/null +++ b/man3/cacosl.3 @@ -0,0 +1 @@ +.so man3/cacos.3 diff --git a/man3/calloc.3 b/man3/calloc.3 new file mode 100644 index 000000000..a4b9d4455 --- /dev/null +++ b/man3/calloc.3 @@ -0,0 +1 @@ +.so man3/malloc.3 diff --git a/man3/callrpc.3 b/man3/callrpc.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/callrpc.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/carg.3 b/man3/carg.3 new file mode 100644 index 000000000..484e3d0ca --- /dev/null +++ b/man3/carg.3 @@ -0,0 +1,33 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CARG 3 2002-07-28 "" "complex math routines" +.SH NAME +carg, cargf, cargl \- calculate the argument +.SH SYNOPSIS +.B #include +.sp +.BI "double carg(double complex " z ");" +.sp +.BI "float cargf(float complex " z ");" +.sp +.BI "long double cargl(long double complex " z ");" +.sp +Link with \-lm. +.SH DESCRIPTION +A complex number can be described by two real coordinates. +One may use rectangular coordinates and gets z = x+I*y, where +x = creal(z) and y = cimag(z). +.LP +Or one may use polar coordinates and gets z = r*cexp(I*a) +where r = cabs(z) is the "radius", the "modulus", the absolute value of z, +and a = carg(z) is the "phase angle", the argument of z. +.LP +One has carg(z) = atan(creal(z) / cimag(z)). +.SH "RETURN VALUE" +The return value is the range of [-pi,pi]. +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR cabs (3), +.BR complex (5) diff --git a/man3/cargf.3 b/man3/cargf.3 new file mode 100644 index 000000000..c049a27d1 --- /dev/null +++ b/man3/cargf.3 @@ -0,0 +1 @@ +.so man3/carg.3 diff --git a/man3/cargl.3 b/man3/cargl.3 new file mode 100644 index 000000000..c049a27d1 --- /dev/null +++ b/man3/cargl.3 @@ -0,0 +1 @@ +.so man3/carg.3 diff --git a/man3/casin.3 b/man3/casin.3 new file mode 100644 index 000000000..f5084b79e --- /dev/null +++ b/man3/casin.3 @@ -0,0 +1,29 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CASIN 3 2002-07-28 "" "complex math routines" +.SH NAME +casin, casinf, casinl \- complex arc sine +.SH SYNOPSIS +.B #include +.sp +.BI "double complex casin(double complex " z ); +.sp +.BI "float complex casinf(float complex " z ); +.sp +.BI "long double complex casinl(long double complex " z ); +.sp +Link with \-lm. +.SH DESCRIPTION +The casin() function calculates the complex asin(). +If y = casin(z), then z = csin(y). +The real part of y is chosen in the interval [-pi/2,pi/2]. +.LP +One has +casin(z) = -i clog(iz+csqrt(1-z*z)). +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR ccos (3), +.BR clog (3), +.BR complex (5) diff --git a/man3/casinf.3 b/man3/casinf.3 new file mode 100644 index 000000000..3418b5b76 --- /dev/null +++ b/man3/casinf.3 @@ -0,0 +1 @@ +.so man3/casin.3 diff --git a/man3/casinh.3 b/man3/casinh.3 new file mode 100644 index 000000000..0cc96af35 --- /dev/null +++ b/man3/casinh.3 @@ -0,0 +1,29 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CASINH 3 2002-07-28 "" "complex math routines" +.SH NAME +casinh, casinhf, casinhl \- complex arc sine hyperbolic +.SH SYNOPSIS +.B #include +.sp +.BI "double complex casinh(double complex " z ); +.sp +.BI "float complex casinhf(float complex " z ); +.sp +.BI "long double complex casinhl(long double complex " z ); +.sp +Link with \-lm. +.SH DESCRIPTION +The casinh() function calculates the complex asinh(). +If y = casinh(z), then z = csinh(y). +The imaginary part of y is chosen in the interval [-pi/2,pi/2]. +.LP +One has casinh(z) = clog(z+csqrt(z*z+1)). +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR asinh (3), +.BR cabs (3), +.BR cimag (3), +.BR complex (5) diff --git a/man3/casinhf.3 b/man3/casinhf.3 new file mode 100644 index 000000000..f8b022ca1 --- /dev/null +++ b/man3/casinhf.3 @@ -0,0 +1 @@ +.so man3/casinh.3 diff --git a/man3/casinhl.3 b/man3/casinhl.3 new file mode 100644 index 000000000..f8b022ca1 --- /dev/null +++ b/man3/casinhl.3 @@ -0,0 +1 @@ +.so man3/casinh.3 diff --git a/man3/casinl.3 b/man3/casinl.3 new file mode 100644 index 000000000..3418b5b76 --- /dev/null +++ b/man3/casinl.3 @@ -0,0 +1 @@ +.so man3/casin.3 diff --git a/man3/catan.3 b/man3/catan.3 new file mode 100644 index 000000000..42e12f68b --- /dev/null +++ b/man3/catan.3 @@ -0,0 +1,29 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CATAN 3 2002-07-28 "" "complex math routines" +.SH NAME +catan, catanf, catanl \- complex arc tangents +.SH SYNOPSIS +.B #include +.sp +.BI "double complex catan(double complex " z ); +.sp +.BI "float complex catanf(float complex " z ); +.sp +.BI "long double complex catanl(long double complex " z ); +.sp +Link with \-lm. +.SH DESCRIPTION +The catan() function calculates the complex atan(). +If y = catan(z), then z = ctan(y). +The real part of y is chosen in the interval [-pi/2,pi/2]. +.LP +One has +catan(z) = 1/2i clog((1+iz)/(1-iz)). +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR ccos (3), +.BR clog (3), +.BR complex (5) diff --git a/man3/catanf.3 b/man3/catanf.3 new file mode 100644 index 000000000..854de1390 --- /dev/null +++ b/man3/catanf.3 @@ -0,0 +1 @@ +.so man3/catan.3 diff --git a/man3/catanh.3 b/man3/catanh.3 new file mode 100644 index 000000000..a3691721e --- /dev/null +++ b/man3/catanh.3 @@ -0,0 +1,29 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CATANH 3 2002-07-28 "" "complex math routines" +.SH NAME +catanh, catanhf, catanhl \- complex arc tangents hyperbolic +.SH SYNOPSIS +.B #include +.sp +.BI "double complex catanh(double complex " z ); +.sp +.BI "float complex catanhf(float complex " z ); +.sp +.BI "long double complex catanhl(long double complex " z ); +.sp +Link with \-lm. +.SH DESCRIPTION +The catanh() function calculates the complex atanh(). +If y = catanh(z), then z = ctanh(y). +The imaginary part of y is chosen in the interval [-pi/2,pi/2]. +.LP +One has catanh(z) = 0.5*clog((1+z)/(1-z)). +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR atanh (3), +.BR cabs (3), +.BR cimag (3), +.BR complex (5) diff --git a/man3/catanhf.3 b/man3/catanhf.3 new file mode 100644 index 000000000..6c61e7cee --- /dev/null +++ b/man3/catanhf.3 @@ -0,0 +1 @@ +.so man3/catanh.3 diff --git a/man3/catanhl.3 b/man3/catanhl.3 new file mode 100644 index 000000000..6c61e7cee --- /dev/null +++ b/man3/catanhl.3 @@ -0,0 +1 @@ +.so man3/catanh.3 diff --git a/man3/catanl.3 b/man3/catanl.3 new file mode 100644 index 000000000..854de1390 --- /dev/null +++ b/man3/catanl.3 @@ -0,0 +1 @@ +.so man3/catan.3 diff --git a/man3/catclose.3 b/man3/catclose.3 new file mode 100644 index 000000000..92ff6665a --- /dev/null +++ b/man3/catclose.3 @@ -0,0 +1 @@ +.so man3/catopen.3 diff --git a/man3/catgets.3 b/man3/catgets.3 new file mode 100644 index 000000000..b4d0052cc --- /dev/null +++ b/man3/catgets.3 @@ -0,0 +1,84 @@ +.\" Copyright 1993 Mitchum DSouza +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Updated, aeb, 980809 +.TH CATGETS 3 1998-08-09 +.SH NAME +catgets \- get message from a message catalog +.SH SYNOPSIS +.LP +.nf +.ft B +#include +.ft +.fi +.LP +.BI "char *catgets(nl_catd " catalog ", int " set_number , +.BI "int " message_number ", const char *" message ); +.SH DESCRIPTION +.B catgets() +reads the message +.IR message_number , +in set +.IR set_number , +from the message catalog identified by +.IR catalog , +where +.I catalog +is a catalog descriptor returned from an earlier call to +.BR catopen (3). +The fourth argument +.I message +points to a default message string which will be returned by +.B catgets() +if the identified message catalog is not currently available. The +message-text is contained in an internal buffer area and should be copied by +the application if it is to be saved or modified. The return string is +always terminated with a null byte. +.SH "RETURN VALUE" +.LP +On success, +.B catgets() +returns a pointer to an internal buffer area +containing the null-terminated message string. +On failure, +.B catgets() +returns the value +.IR message . +.SH NOTES +These functions are only available in libc.so.4.4.4c and above. +The Jan 1987 X/Open Portability Guide specifies a more subtle +error return: +.I message +is returned if the message catalog specified by +.I catalog +is not available, while an empty string is returned +when the message catalog is available but does not contain +the specified message. +These two possible error returns seem to be discarded in XPG4.2 +in favour of always returning +.IR message . +.SH "CONFORMING TO" +XPG4.2 +.SH "SEE ALSO" +.BR catopen (3), +.BR setlocale (3) diff --git a/man3/catopen.3 b/man3/catopen.3 new file mode 100644 index 000000000..8286716fd --- /dev/null +++ b/man3/catopen.3 @@ -0,0 +1,171 @@ +.\" Copyright 1993 Mitchum DSouza +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Thu Dec 13 22:51:19 2001 by Martin Schulze +.\" Modified 2001-12-14 aeb +.\" +.TH CATOPEN 3 2001-12-14 +.SH NAME +catopen, catclose \- open/close a message catalog +.SH SYNOPSIS +.B #include +.sp +.BI "nl_catd catopen(const char *" name ", int " flag ); +.br +.BI "int catclose(nl_catd " catalog ); +.SH DESCRIPTION +The function +.B catopen() +opens a message catalog and returns a catalog descriptor. +The descriptor remains valid until catclose() or exec(). +If a file descriptor is used to implement catalog descriptors +then the FD_CLOEXEC flag will be set. +.LP +The argument +.I name +specifies the name of the message catalog to be opened. +If +.I name +specifies and absolute path (i.e., contains a '/'), +then +.I name +specifies a pathname for the message catalog. +Otherwise, the environment variable +.B NLSPATH +is used with +.I name +substituted for +.B %N +(see +.BR locale (7)). +It is unspecified whether +.B NLSPATH +will be used when the process has root privileges. +If +.B NLSPATH +does not exist in the environment, +or if a message catalog cannot be opened +in any of the paths specified by it, +then an implementation defined path is used. +This latter default path may depend on the +.B LC_MESSAGES +locale setting when the +.I flag +argument is +.B NL_CAT_LOCALE +and on the +.B LANG +environment variable when the +.I flag +argument is 0. +Changing the LC_MESSAGES part of the locale may invalidate +open catalog descriptors. +.LP +The +.I flag +argument to +.B catopen() +is used to indicate the source for the language to use. +If it is set to +.B NL_CAT_LOCALE +then it will use the current locale setting for +.BR LC_MESSAGES . +Otherwise it will use the +.B LANG +environment variable. +.LP +The function +.B catclose() +closes the message catalog identified by +.IR catalog . +It invalidates any subsequent references to the message catalog +defined by +.IR catalog . +.LP +.SH "RETURN VALUE" +The function +.B catopen() +returns a message catalog descriptor of type +.I nl_catd +on success. +On failure, it returns (nl_catd) \-1 +and sets +.B errno +to indicate the error. The possible error values include all +possible values for the +.I open() +call. +.LP +The function +.B catclose() +returns 0 on success, or \-1 on failure. +.SH ENVIRONMENT +.TP +.B LC_MESSAGES +May be the source of the LC_MESSAGES locale setting, and thus +determine the language to use if +.I flag +is set to +.BR NL_CAT_LOCALE . +.TP +.B LANG +The language to use if +.I flag +is 0. +.SH NOTES +The above is the POSIX 1003.1-2001 description. +The glibc value for NL_CAT_LOCALE is 1. +(Compare MCLoadAll below.) +The default path varies, but usually looks at a number of places below +.IR /usr/share/locale . +.SH "NOTES FOR LIBC4 AND LIBC5" +These functions are available for Linux since libc 4.4.4c. +In the case of linux libc4 and libc5, the catalog descriptor +.I nl_catd +is a mmap()'ed area of memory and not a file descriptor. +The +.I flag +argument to +.B catopen() +should be either +.B MCLoadBySet +(=0) or +.B MCLoadAll +(=1). +The former value indicates that a set from the catalog is to be +loaded when needed, whereas the latter causes the initial call to +.BR catopen () +to load the entire catalog into memory. +The default search path varies, but usually looks at a number of places below +.I /etc/locale +and +.IR /usr/lib/locale . +.SH "CONFORMING TO" +POSIX 1003.1-2001. +In XPG 1987, Vol. 3 it says: +.I "The flag argument of catopen is reserved for future use" +.IR "and should be set to 0" . +It is unclear what the source was for the constants MCLoadBySet +and MCLoadAll. +.SH "SEE ALSO" +.BR catgets (3), +.BR setlocale (3) diff --git a/man3/cbc_crypt.3 b/man3/cbc_crypt.3 new file mode 100644 index 000000000..853c9cbdf --- /dev/null +++ b/man3/cbc_crypt.3 @@ -0,0 +1 @@ +.so man3/des_crypt.3 diff --git a/man3/cbrt.3 b/man3/cbrt.3 new file mode 100644 index 000000000..9b2f70dd3 --- /dev/null +++ b/man3/cbrt.3 @@ -0,0 +1,52 @@ +.\" Copyright 1995 Jim Van Zandt +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" changed `square root' into `cube root' - aeb, 950919 +.\" +.\" Modified 2002-07-27 Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH CBRT 3 2002-27-07 "GNU" "Linux Programmer's Manual" +.SH NAME +cbrt, cbrtf, cbrtl \- cube root function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double cbrt(double " x ); +.br +.BI "float cbrtf(float " x ); +.br +.BI "long double cbrtl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBcbrt()\fP function returns the (real) cube root of \fIx\fP. +This function cannot fail; every representable real value has a +representable real cube root. +.SH "CONFORMING TO" +.B cbrt() +was a GNU extension. It is now a C99 requirement. +.SH "SEE ALSO" +.BR pow (3), +.BR sqrt (3) diff --git a/man3/cbrtf.3 b/man3/cbrtf.3 new file mode 100644 index 000000000..b662c9ecd --- /dev/null +++ b/man3/cbrtf.3 @@ -0,0 +1 @@ +.so man3/cbrt.3 diff --git a/man3/cbrtl.3 b/man3/cbrtl.3 new file mode 100644 index 000000000..b662c9ecd --- /dev/null +++ b/man3/cbrtl.3 @@ -0,0 +1 @@ +.so man3/cbrt.3 diff --git a/man3/ccos.3 b/man3/ccos.3 new file mode 100644 index 000000000..4f2ec6932 --- /dev/null +++ b/man3/ccos.3 @@ -0,0 +1,25 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CCOS 3 2002-07-28 "" "complex math routines" +.SH NAME +ccos, ccosf, ccosl \- complex cosine function +.SH SYNOPSIS +.B #include +.sp +.BI "double complex ccos(double complex " z ");" +.sp +.BI "float complex ccosf(float complex " z ");" +.sp +.BI "long double complex ccosl(long double complex " z ");" +.sp +Link with \-lm. +.SH DESCRIPTION +The complex cosine function ccos(z) is defined as (exp(i*z)+exp(-i*z))/2. +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR cabs (3), +.BR csin (3), +.BR ctan (3), +.BR complex (5) diff --git a/man3/ccosf.3 b/man3/ccosf.3 new file mode 100644 index 000000000..a9811b00d --- /dev/null +++ b/man3/ccosf.3 @@ -0,0 +1 @@ +.so man3/ccos.3 diff --git a/man3/ccosh.3 b/man3/ccosh.3 new file mode 100644 index 000000000..4034a0609 --- /dev/null +++ b/man3/ccosh.3 @@ -0,0 +1,26 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CCOSH 3 2002-07-28 "" "complex math routines" +.SH NAME +ccosh, ccoshf, ccoshl \- complex hyperbolic cosine +.SH SYNOPSIS +.B #include +.sp +.BI "double complex ccosh(double complex " z ");" +.sp +.BI "float complex ccoshf(float complex " z ");" +.sp +.BI "long double complex ccoshl(long double complex " z ");" +.sp +Link with \-lm. +.SH DESCRIPTION +The complex hyperbolic cosine function ccosh(z) is defined as +(exp(z)+exp(-z))/2. +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR cabs (3), +.BR csinh (3), +.BR ctanh (3), +.BR complex (5) diff --git a/man3/ccoshf.3 b/man3/ccoshf.3 new file mode 100644 index 000000000..eaf3be5db --- /dev/null +++ b/man3/ccoshf.3 @@ -0,0 +1 @@ +.so man3/ccosh.3 diff --git a/man3/ccoshl.3 b/man3/ccoshl.3 new file mode 100644 index 000000000..eaf3be5db --- /dev/null +++ b/man3/ccoshl.3 @@ -0,0 +1 @@ +.so man3/ccosh.3 diff --git a/man3/ccosl.3 b/man3/ccosl.3 new file mode 100644 index 000000000..a9811b00d --- /dev/null +++ b/man3/ccosl.3 @@ -0,0 +1 @@ +.so man3/ccos.3 diff --git a/man3/ceil.3 b/man3/ceil.3 new file mode 100644 index 000000000..87dad5f6e --- /dev/null +++ b/man3/ceil.3 @@ -0,0 +1,70 @@ +.\" Copyright 2001 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH CEIL 3 2001-05-31 "" "Linux Programmer's Manual" +.SH NAME +ceil, ceilf, ceill \- ceiling function: smallest integral value not less than argument +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double ceil(double " x ); +.br +.BI "float ceilf(float " x ); +.br +.BI "long double ceill(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +These functions round \fIx\fP up to the nearest integer. +.SH "RETURN VALUE" +The rounded integer value. If \fIx\fP is integral or infinite, +\fIx\fP itself is returned. +.SH ERRORS +No errors other than EDOM and ERANGE can occur. +If \fIx\fP is NaN, then NaN is returned and +.I errno +may be set to EDOM. +.SH NOTES +SUSv2 and POSIX 1003.1-2001 contain text about overflow (which might set +.I errno +to ERANGE, or raise an exception). +In practice, the result cannot overflow on any current machine, +so this error-handling stuff is just nonsense. +(More precisely, overflow can happen only when the maximum value +of the exponent is smaller than the number of mantissa bits. +For the IEEE-754 standard 32-bit and 64-bit floating point numbers +the maximum value of the exponent is 128 (resp. 1024), and the number +of mantissa bits is 24 (resp. 53).) +.SH "CONFORMING TO" +The +.B ceil() +function conforms to SVID 3, POSIX, BSD 4.3, ISO 9899. +The other functions are from C99. +.SH "SEE ALSO" +.BR floor (3), +.BR lrint (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3), +.BR trunc (3) diff --git a/man3/ceilf.3 b/man3/ceilf.3 new file mode 100644 index 000000000..569d1baf7 --- /dev/null +++ b/man3/ceilf.3 @@ -0,0 +1 @@ +.so man3/ceil.3 diff --git a/man3/ceill.3 b/man3/ceill.3 new file mode 100644 index 000000000..569d1baf7 --- /dev/null +++ b/man3/ceill.3 @@ -0,0 +1 @@ +.so man3/ceil.3 diff --git a/man3/cerf.3 b/man3/cerf.3 new file mode 100644 index 000000000..cfa1de721 --- /dev/null +++ b/man3/cerf.3 @@ -0,0 +1,35 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH cerf 3 2002-07-28 "" "complex math routines" +.SH NAME +cerf, cerff, cerfl, cerfc, cerfcf, cerfcl \- complex error function +.SH SYNOPSIS +.B #include +.sp +.BI "double complex cerf(double complex " z ); +.sp +.BI "float complex cerff(float complex " z ); +.sp +.BI "long double complex cerfl(long double complex " z ); +.sp +.BI "double complex cerfc(double complex " z ); +.sp +.BI "float complex cerfcf(float complex " z ); +.sp +.BI "long double complex cerfcl(long double complex " z ); +.sp +Link with \-lm. +.SH DESCRIPTION +The function cerf() is the complex version of the error function. +erf(z) = 2/sqrt(pi) * integral from 0 to z of exp(-t*t) dt. +The function cerfc() is defined as cerfc(z) = 1-cerf(z). +.\" must check 1/sqrt(2*pi) ? +.SH "CONFORMING TO" +The function name is reserved for future use in C99. +.SH AVAILABILITY +Not yet in glibc 2.3.2. +.\" But reserved in NAMESPACE. +.SH "SEE ALSO" +.BR erf (3), +.BR complex (5) diff --git a/man3/cerfc.3 b/man3/cerfc.3 new file mode 100644 index 000000000..ec1ee79a0 --- /dev/null +++ b/man3/cerfc.3 @@ -0,0 +1 @@ +.so man3/cerf.3 diff --git a/man3/cerfcf.3 b/man3/cerfcf.3 new file mode 100644 index 000000000..ec1ee79a0 --- /dev/null +++ b/man3/cerfcf.3 @@ -0,0 +1 @@ +.so man3/cerf.3 diff --git a/man3/cerfcl.3 b/man3/cerfcl.3 new file mode 100644 index 000000000..ec1ee79a0 --- /dev/null +++ b/man3/cerfcl.3 @@ -0,0 +1 @@ +.so man3/cerf.3 diff --git a/man3/cerff.3 b/man3/cerff.3 new file mode 100644 index 000000000..ec1ee79a0 --- /dev/null +++ b/man3/cerff.3 @@ -0,0 +1 @@ +.so man3/cerf.3 diff --git a/man3/cerfl.3 b/man3/cerfl.3 new file mode 100644 index 000000000..ec1ee79a0 --- /dev/null +++ b/man3/cerfl.3 @@ -0,0 +1 @@ +.so man3/cerf.3 diff --git a/man3/cexp.3 b/man3/cexp.3 new file mode 100644 index 000000000..8045ed627 --- /dev/null +++ b/man3/cexp.3 @@ -0,0 +1,28 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CEXP 3 2002-07-28 "" "complex math routines" +.SH NAME +cexp, cexpf, cexpl \- complex exponential function +.SH SYNOPSIS +.B #include +.sp +.BI "double complex cexp(double complex " z ");" +.sp +.BI "float complex cexpf(float complex " z ");" +.sp +.BI "long double complex cexpl(long double complex " z ");" +.sp +Link with \-lm. +.SH DESCRIPTION +The function calculates e (2.71828..., the base of natural logarithms) +raised to the power of z. +.LP +One has cexp(I*z) = ccos(z) + I*csin(z). +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR cabs (3), +.BR clog (3), +.BR cpow (3), +.BR complex (5) diff --git a/man3/cexp2.3 b/man3/cexp2.3 new file mode 100644 index 000000000..496c753a6 --- /dev/null +++ b/man3/cexp2.3 @@ -0,0 +1,28 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CEXP2 3 2002-07-28 "" "complex math routines" +.SH NAME +cexp2, cexp2f, cexp2l \- base-2 exponent of a complex number +.SH SYNOPSIS +.B #include +.sp +.BI "double complex cexp2(double complex " z ");" +.sp +.BI "float complex cexp2f(float complex " z ");" +.sp +.BI "long double complex cexp2l(long double complex " z ");" +.sp +Link with \-lm. +.SH DESCRIPTION +The function returns 2 raised to the power of z. +.SH "CONFORMING TO" +The function name is reserved for future use in C99. +.SH AVAILABILITY +Not yet in glibc 2.3.2. +.\" But reserved in NAMESPACE. +.SH "SEE ALSO" +.BR cabs (3), +.BR cexp (3), +.BR clog10 (3), +.BR complex (5) diff --git a/man3/cexp2f.3 b/man3/cexp2f.3 new file mode 100644 index 000000000..19660179c --- /dev/null +++ b/man3/cexp2f.3 @@ -0,0 +1 @@ +.so man3/cexp2.3 diff --git a/man3/cexp2l.3 b/man3/cexp2l.3 new file mode 100644 index 000000000..19660179c --- /dev/null +++ b/man3/cexp2l.3 @@ -0,0 +1 @@ +.so man3/cexp2.3 diff --git a/man3/cexpf.3 b/man3/cexpf.3 new file mode 100644 index 000000000..1c19767f8 --- /dev/null +++ b/man3/cexpf.3 @@ -0,0 +1 @@ +.so man3/cexp.3 diff --git a/man3/cexpl.3 b/man3/cexpl.3 new file mode 100644 index 000000000..1c19767f8 --- /dev/null +++ b/man3/cexpl.3 @@ -0,0 +1 @@ +.so man3/cexp.3 diff --git a/man3/cfgetispeed.3 b/man3/cfgetispeed.3 new file mode 100644 index 000000000..eb472496d --- /dev/null +++ b/man3/cfgetispeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/cfgetospeed.3 b/man3/cfgetospeed.3 new file mode 100644 index 000000000..eb472496d --- /dev/null +++ b/man3/cfgetospeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/cfmakeraw.3 b/man3/cfmakeraw.3 new file mode 100644 index 000000000..eb472496d --- /dev/null +++ b/man3/cfmakeraw.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/cfree.3 b/man3/cfree.3 new file mode 100644 index 000000000..5d43a921a --- /dev/null +++ b/man3/cfree.3 @@ -0,0 +1,102 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH CFREE 3 2003-11-18 "" "Linux Programmer's Manual" +.SH NAME +cfree \- free allocated memory +.SH SYNOPSIS +.nf +.sp +.B "#include " +.sp +/* In SunOS 4 */ +.BI "int cfree(void *" ptr ); +.sp +/* In glibc or FreeBSD libcompat */ +.BI "void cfree(void *" ptr ); +.sp +/* In SCO OpenServer */ +.BI "void cfree(char *" ptr ", unsigned " num ", unsigned " size ); +.sp +/* In Solaris watchmalloc.so.1 */ +.BI "void cfree(void *" ptr ", size_t " nelem ", size_t " elsize ); +.fi +.SH DESCRIPTION +This function should never be used. Use +.BR free (3) +instead. +.SS "1-arg cfree" +In glibc, the function +.B cfree() +is a synonym for +.BR free (3), +"added for compatibility with SunOS". +.LP +Other systems have other functions with this name. +The declaration is sometimes in +.I +and sometimes in +.IR . +.LP +.SS "3-arg cfree" +Some SCO and Solaris versions have malloc libraries with a 3-argument +.BR cfree() , +apparently as an analog to +.BR calloc (3). +.LP +If you need it while porting something, add +.sp +.in +5 +#define cfree(p, n, s) free((p)) +.in +.sp +to your file. +.LP +A frequently asked question is "Can I use +.B free() +to free memory allocated with +.BR calloc() , +or do I need +.BR cfree() ?" +Answer: use +.BR free() . +.LP +An SCO manual writes: "The cfree routine is provided for compliance +to the iBCSe2 standard and simply calls free. The num and size +arguments to cfree are not used." +.SH "RETURN VALUE" +The SunOS version of +.B cfree() +(which is a synonym for +.BR free() ) +returns 1 on success and 0 on failure. +In case of error, +.I errno +is set to EINVAL: the value of +.I ptr +was not a pointer to a block previously allocated by +one of the routines in the malloc() family. +.SH "CONFORMING TO" +The 3-argument version of +.B cfree() +as used by SCO conforms to the iBCSe2 standard: +Intel386 Binary Compatibility Specification, Edition 2. diff --git a/man3/cfsetispeed.3 b/man3/cfsetispeed.3 new file mode 100644 index 000000000..eb472496d --- /dev/null +++ b/man3/cfsetispeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/cfsetospeed.3 b/man3/cfsetospeed.3 new file mode 100644 index 000000000..eb472496d --- /dev/null +++ b/man3/cfsetospeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/cimag.3 b/man3/cimag.3 new file mode 100644 index 000000000..fcf359f78 --- /dev/null +++ b/man3/cimag.3 @@ -0,0 +1,28 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CIMAG 3 2002-07-28 "" "complex math routines" +.SH NAME +cimag, cimagf, cimagl \- get imaginary part of a complex number +.SH SYNOPSIS +.B #include +.sp +.BI "double cimag(double complex " z ");" +.sp +.BI "float cimagf(float complex " z ");" +.sp +.BI "long double cimagl(long double complex " z ");" +.sp +Link with \-lm. +.SH DESCRIPTION +The cimag() function returns the imaginary part of the complex number z. +.LP +One has z = creal(z) + I*cimag(z). +.SH NOTE +gcc also supports __imag__. That is a GNU extension. +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR cabs (3), +.BR creal (3), +.BR complex (5) diff --git a/man3/cimagf.3 b/man3/cimagf.3 new file mode 100644 index 000000000..d582faa0d --- /dev/null +++ b/man3/cimagf.3 @@ -0,0 +1 @@ +.so man3/cimag.3 diff --git a/man3/cimagl.3 b/man3/cimagl.3 new file mode 100644 index 000000000..d582faa0d --- /dev/null +++ b/man3/cimagl.3 @@ -0,0 +1 @@ +.so man3/cimag.3 diff --git a/man3/clearenv.3 b/man3/clearenv.3 new file mode 100644 index 000000000..f800ff47e --- /dev/null +++ b/man3/clearenv.3 @@ -0,0 +1,83 @@ +.\" Copyright 2001 John Levon +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Additions, aeb, 2001-10-17. +.TH CLEARENV 3 2001-10-17 "Linux Programmer's Manual" +.SH NAME +clearenv \- clear the environment +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int clearenv(void);" +.fi +.SH DESCRIPTION +The \fBclearenv()\fP function clears the environment of all name-value +pairs and sets the value of the external variable +.I environ +to NULL. + +.SH "RETURN VALUE" +The \fBclearenv()\fP function returns zero on success, and a non-zero +value on failure. +.\" Most versions of Unix return -1 on error, or do not even have errors. +.\" Glibc info and the Watcom C library document "a nonzero value". + +.SH AVAILABILITY +Not in libc4, libc5. In glibc since glibc 2.0. + +.SH "CONFORMING TO" +Various Unix variants (DGUX, HPUX, QNX, ...). +POSIX.9 (bindings for FORTRAN77). +POSIX.1-1996 did not accept \fBclearenv()\fP and \fIputenv()\fP, +but changed its mind and scheduled these functions for some +later issue of this standard (cf. B.4.6.1). However, SUSv3 +only adds \fIputenv()\fP, and rejected \fBclearenv()\fP. + +.SH NOTES +Used in security-conscious applications. If it is unavailable +the assignment +.RS +.nf + environ = NULL; +.fi +.RE +will probably do. +.LP +The DGUX and Tru64 manpages write: If +.I environ +has been modified by anything other than the +.IR putenv() , +.IR getenv() , +or +.IR clearenv() +functions, then +.BR clearenv() +will return an error and the process environment will remain unchanged. +.\" .LP +.\" HPUX has a ENOMEM error return. +.SH "SEE ALSO" +.BR getenv (3), +.BR putenv (3), +.BR setenv (3), +.BR unsetenv (3), +.BR environ (5) diff --git a/man3/clearerr.3 b/man3/clearerr.3 new file mode 100644 index 000000000..3a95cca9f --- /dev/null +++ b/man3/clearerr.3 @@ -0,0 +1 @@ +.so man3/ferror.3 diff --git a/man3/clearerr_unlocked.3 b/man3/clearerr_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/clearerr_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/clnt_broadcast.3 b/man3/clnt_broadcast.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clnt_broadcast.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_call.3 b/man3/clnt_call.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clnt_call.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_control.3 b/man3/clnt_control.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clnt_control.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_create.3 b/man3/clnt_create.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clnt_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_destroy.3 b/man3/clnt_destroy.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clnt_destroy.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_freeres.3 b/man3/clnt_freeres.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clnt_freeres.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_geterr.3 b/man3/clnt_geterr.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clnt_geterr.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_pcreateerror.3 b/man3/clnt_pcreateerror.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clnt_pcreateerror.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_perrno.3 b/man3/clnt_perrno.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clnt_perrno.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_perror.3 b/man3/clnt_perror.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clnt_perror.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_spcreateerror.3 b/man3/clnt_spcreateerror.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clnt_spcreateerror.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_sperrno.3 b/man3/clnt_sperrno.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clnt_sperrno.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_sperror.3 b/man3/clnt_sperror.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clnt_sperror.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clntraw_create.3 b/man3/clntraw_create.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clntraw_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnttcp_create.3 b/man3/clnttcp_create.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clnttcp_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clntudp_bufcreate.3 b/man3/clntudp_bufcreate.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clntudp_bufcreate.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clntudp_create.3 b/man3/clntudp_create.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/clntudp_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clock.3 b/man3/clock.3 new file mode 100644 index 000000000..676f4807d --- /dev/null +++ b/man3/clock.3 @@ -0,0 +1,81 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 21:27:01 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 14 Jun 2002, Michael Kerrisk +.\" Added notes on differences from other Unices with respect to +.\" waited-for children. +.TH CLOCK 3 2002-06-14 "GNU" "Linux Programmer's Manual" +.SH NAME +clock \- Determine processor time +.SH SYNOPSIS +.nf +.B #include +.sp +.B clock_t clock(void); +.fi +.SH DESCRIPTION +The +.B clock() +function returns an approximation of processor time used by the program. +.SH "RETURN VALUE" +The value returned is the CPU time used so far as a +.BR clock_t ; +to get the number of seconds used, divide by +.BR CLOCKS_PER_SEC . +If the processor time used is not available or its value cannot +be represented, the function returns the value (clock_t)-1. +.SH "CONFORMING TO" +ANSI C. +POSIX requires that CLOCKS_PER_SEC equals 1000000 independent +of the actual resolution. +.SH NOTES +The C standard allows for arbitrary values at the start of the program; +subtract the value returned from a call to +.B clock() +at the start of the program to get maximum portability. +.PP +Note that the time can wrap around. On a 32bit system where +CLOCKS_PER_SEC equals 1000000 this function will return the same +value approximately every 72 minutes. +.PP +On several other implementations, +the value returned by +.BR clock () +also includes the times of any children whose status has been +collected via +.BR wait () +(or another wait-type call). +Linux does not include the times of waited-for children in the +value returned by +.BR clock (). +.\" I have seen this behaviour on Irix 6.3, and the OSF/1, HP/UX, and +.\" Solaris manual pages say that clock() also does this on those systems. +.\" POSIX 1003.1-2001 doesn't explicitly allow this, nor is there an +.\" explicit prohibition. -- MTK +The +.B times() +function, which explicitly returns (separate) information about the +caller and its children, may be preferable. +.SH "SEE ALSO" +.BR getrusage (2), +.BR times (2) diff --git a/man3/clock_getres.3 b/man3/clock_getres.3 new file mode 100644 index 000000000..407e85793 --- /dev/null +++ b/man3/clock_getres.3 @@ -0,0 +1,195 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 2003 Nick Clifford (zaf@nrc.co.nz), Jan 25, 2003 +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl), Aug 24, 2003 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" 2003-08-23 Martin Schulze improvements +.\" 2003-08-24 aeb, large parts rewritten +.\" 2004-08-06 Christoph Lameter , SMP note +.\" +.TH CLOCK_GETRES 3 2003-08-24 "" "Linux Programmer's Manual" +.SH NAME +clock_getres, clock_gettime, clock_settime \- clock and time functions +.SH SYNOPSIS +.B #include +.sp +.BI "int clock_getres(clockid_t " clk_id ", struct timespec *" res ); +.br +.BI "int clock_gettime(clockid_t " clk_id ", struct timespec *" tp ); +.br +.BI "int clock_settime(clockid_t " clk_id ", const struct timespec *" tp ); +.SH DESCRIPTION +The function +.BR clock_getres () +finds the resolution (precision) of the specified clock +.IR clk_id , +and, if +.I res +is non-NULL, stores it in the struct timespec pointed to by +.IR res . +The resolution of clocks depends on the implementation and cannot be +configured by a particular process. +If the time value pointed to by the argument +.I tp +of +.BR clock_settime () +is not a multiple of +.IR res , +then it is truncated to a multiple of +.IR res . +.PP +The functions +.BR clock_gettime () +and +.BR clock_settime () +retrieve and set the time of the specified clock +.IR clk_id . +.PP +The +.I res +and +.I tp +arguments are +.B timespec +structs, as specified in +.IR : +.sp +.nf +struct timespec { +.in +8 +time_t tv_sec; /* seconds */ +long tv_nsec; /* nanoseconds */ +.in -8 +}; +.fi +.PP +The +.I clk_id +argument is the identifier of the particular clock on which to act. +A clock may be system-wide and hence visible for all processes, or +per-process if it measures time only within a single process. +.LP +All implementations support the system-wide realtime clock, +which is identified by +.BR CLOCK_REALTIME . +Its time represents seconds and nanoseconds since the Epoch. +When its time is changed, timers for a relative interval are +unaffected, but timers for an absolute point in time are affected. +.LP +More clocks may be implemented. The interpretation of the +corresponding time values and the effect on timers is unspecified. +.LP +Sufficiently recent versions of GNU libc and the Linux kernel +support the following clocks: +.TP +.B CLOCK_REALTIME +System-wide realtime clock. +Setting this clock requires appropriate privileges. +.TP +.B CLOCK_MONOTONIC +Clock that cannot be set and represents monotonic time since +some unspecified starting point. +.TP +.B CLOCK_PROCESS_CPUTIME_ID +High-resolution per-process timer from the CPU. +.TP +.B CLOCK_THREAD_CPUTIME_ID +Thread-specific CPU-time clock. +.SH "RETURN VALUE" +.BR clock_gettime "(), " clock_settime () +and +.BR clock_getres () +return 0 for success, or \-1 for failure (in which case +.I errno +is set appropriately). +.SH ERRORS +.TP +.B EFAULT +.I tp +points outside the accessible address space. +.TP +.B EINVAL +The +.I clk_id +specified is not supported on this system. +.TP +.B EPERM +.BR clock_settime () +does not have permission to set the clock indicated. +.SH NOTE +Most systems require the program be linked with the librt +library to use these functions. +.SH NOTE for SMP systems +The +.B CLOCK_PROCESS_CPUTIME_ID +and +.B CLOCK_THREAD_CPUTIME_ID +clocks are realized on many platforms using timers from the CPUs +(TSC on i386, AR.ITC on Itanium). +These registers may differ between CPUs and as a consequence +these clocks may return +.B bogus results +if a process is migrated to another CPU. +.PP +If the CPUs in an SMP system have different clock sources then +there is no way to maintain a correlation between the timer registers since +each CPU will run at a slightly different frequency. If that is the case then +.I clock_getcpuclockid(0) +will return +.B ENOENT +to signify this condition. The two clocks will then only be useful if it +can be ensured that a process stays on a certain CPU. +.PP +The processors in an SMP system do not start all at exactly the same +time and therefore the timer registers are typically running at an offset. +Some architectures include code that attempts to limit these offsets on bootup. +However, the code cannot guarantee to accurately tune the offsets. +Glibc contains no provisions to deal with these offsets (unlike the Linux +Kernel). Typically these offsets are small and therefore the effects may be +negligible in most cases. +.SH AVAILABILITY +On POSIX systems on which these functions are available, the symbol +.B _POSIX_TIMERS +is defined in to a value greater than 0. +The symbols +.BR _POSIX_MONOTONIC_CLOCK , +.BR _POSIX_CPUTIME , +.B _POSIX_THREAD_CPUTIME +indicate that +.BR CLOCK_MONOTONIC , +.BR CLOCK_PROCESS_CPUTIME_ID , +.B CLOCK_THREAD_CPUTIME_ID +are available. +(See also +.BR sysconf (3).) +.SH "CONFORMING TO" +SUSv2, POSIX 1003.1-2001. +.SH "SEE ALSO" +.BR date (1), +.BR adjtimex (2), +.BR gettimeofday (2), +.BR settimeofday (2), +.BR time (2), +.BR ctime (3), +.BR ftime (3), +.BR sysconf (3) diff --git a/man3/clock_gettime.3 b/man3/clock_gettime.3 new file mode 100644 index 000000000..eb21f95e9 --- /dev/null +++ b/man3/clock_gettime.3 @@ -0,0 +1 @@ +.so man3/clock_getres.3 diff --git a/man3/clock_settime.3 b/man3/clock_settime.3 new file mode 100644 index 000000000..eb21f95e9 --- /dev/null +++ b/man3/clock_settime.3 @@ -0,0 +1 @@ +.so man3/clock_getres.3 diff --git a/man3/clog.3 b/man3/clog.3 new file mode 100644 index 000000000..f3a73795c --- /dev/null +++ b/man3/clog.3 @@ -0,0 +1,31 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CLOG 3 2002-07-28 "" "complex math routines" +.SH NAME +clog, clogf, clogl \- natural logarithm of a complex number +.SH SYNOPSIS +.B #include +.sp +.BI "double complex clog(double complex " z ); +.sp +.BI "float complex clogf(float complex " z ); +.sp +.BI "long double complex clogl(long double complex " z ); +.sp +Link with \-lm. +.SH DESCRIPTION +The logarithm clog is the inverse function of the exponential cexp. +Thus, if y = clog(z), then z = cexp(y). +The imaginary part of y is chosen in the interval [-pi,pi]. +.LP +One has clog(z) = log(cabs(z))+I*carg(z). +.LP +Please note that z close to zero will cause an overflow. +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR cabs (3), +.BR cexp (3), +.BR clog10 (3), +.BR complex (5) diff --git a/man3/clog10.3 b/man3/clog10.3 new file mode 100644 index 000000000..f3b60daf4 --- /dev/null +++ b/man3/clog10.3 @@ -0,0 +1,30 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CLOG10 3 2002-07-28 "" "complex math routines" +.SH NAME +clog10, clog10f, clog10l \- base-10 logarithm of a complex number +.SH SYNOPSIS +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "double complex clog10(double complex " z ); +.sp +.BI "float complex clog10f(float complex " z ); +.sp +.BI "long double complex clog10l(long double complex " z ); +.sp +Link with \-lm. +.SH DESCRIPTION +The logarithm is defined as log10(cabs(z))+I*carg(z). +Please note that z close to zero will cause an overflow. +.SH "CONFORMING TO" +The function is a GNU extension. +It is reserved for future use in C99. +.SH "SEE ALSO" +.BR cabs (3), +.BR cexp (3), +.BR clog (3), +.BR clog2 (3), +.BR complex (5) diff --git a/man3/clog10f.3 b/man3/clog10f.3 new file mode 100644 index 000000000..fc825a73e --- /dev/null +++ b/man3/clog10f.3 @@ -0,0 +1 @@ +.so man3/clog10.3 diff --git a/man3/clog10l.3 b/man3/clog10l.3 new file mode 100644 index 000000000..fc825a73e --- /dev/null +++ b/man3/clog10l.3 @@ -0,0 +1 @@ +.so man3/clog10.3 diff --git a/man3/clog2.3 b/man3/clog2.3 new file mode 100644 index 000000000..a963695d9 --- /dev/null +++ b/man3/clog2.3 @@ -0,0 +1,30 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CLOG2 3 2002-07-28 "" "complex math routines" +.SH NAME +clog2, clog2f, clog2l \- base-2 logarithm of a complex number +.SH SYNOPSIS +.B #include +.sp +.BI "double complex clog2(double complex " z ); +.sp +.BI "float complex clog2f(float complex " z ); +.sp +.BI "long double complex clog2l(long double complex " z ); +.sp +Link with \-lm. +.SH DESCRIPTION +The logarithm is defined as log2(cabs(z))+I*carg(z). +Please note that z close to zero will cause an overflow. +.SH "CONFORMING TO" +The function name is reserved for future use in C99. +.SH AVAILABILITY +Not yet in glibc 2.3.2. +.\" But reserved in NAMESPACE. +.SH "SEE ALSO" +.BR cabs (3), +.BR cexp (3), +.BR clog (3), +.BR clog10 (3), +.BR complex (5) diff --git a/man3/clog2f.3 b/man3/clog2f.3 new file mode 100644 index 000000000..e487cb182 --- /dev/null +++ b/man3/clog2f.3 @@ -0,0 +1 @@ +.so man3/clog2.3 diff --git a/man3/clog2l.3 b/man3/clog2l.3 new file mode 100644 index 000000000..e487cb182 --- /dev/null +++ b/man3/clog2l.3 @@ -0,0 +1 @@ +.so man3/clog2.3 diff --git a/man3/clogf.3 b/man3/clogf.3 new file mode 100644 index 000000000..478e02b4d --- /dev/null +++ b/man3/clogf.3 @@ -0,0 +1 @@ +.so man3/clog.3 diff --git a/man3/clogl.3 b/man3/clogl.3 new file mode 100644 index 000000000..478e02b4d --- /dev/null +++ b/man3/clogl.3 @@ -0,0 +1 @@ +.so man3/clog.3 diff --git a/man3/closedir.3 b/man3/closedir.3 new file mode 100644 index 000000000..dba5abbfc --- /dev/null +++ b/man3/closedir.3 @@ -0,0 +1,59 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:25:52 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.TH CLOSEDIR 3 1995-06-11 "" "Linux Programmer's Manual" +.SH NAME +closedir \- close a directory +.SH SYNOPSIS +.nf +.B #include +.sp +.B #include +.sp +.BI "int closedir(DIR *" dir ); +.fi +.SH DESCRIPTION +The \fBclosedir()\fP function closes the directory stream associated with +\fIdir\fP. The directory stream descriptor \fIdir\fP is not available +after this call. +.SH "RETURN VALUE" +The \fBclosedir()\fP function returns 0 on success or \-1 on failure. +.SH ERRORS +.TP +.B EBADF +Invalid directory stream descriptor \fIdir\fP. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3 +.SH "SEE ALSO" +.BR close (2), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) diff --git a/man3/closelog.3 b/man3/closelog.3 new file mode 100644 index 000000000..ec352b291 --- /dev/null +++ b/man3/closelog.3 @@ -0,0 +1 @@ +.so man3/syslog.3 diff --git a/man3/cmsg.3 b/man3/cmsg.3 new file mode 100644 index 000000000..a8a74eb71 --- /dev/null +++ b/man3/cmsg.3 @@ -0,0 +1,219 @@ +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" $Id: cmsg.3,v 1.8 2000/12/20 18:10:31 ak Exp $ +.TH CMSG 3 1998-10-02 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- Access ancillary data +.SH SYNOPSIS +.B #include +.br +.sp 2 +.BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh ); +.br +.BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh ", struct cmsghdr *" cmsg ); +.br +.BI "size_t CMSG_ALIGN(size_t " length ); +.br +.BI "size_t CMSG_SPACE(size_t " length ); +.br +.BI "size_t CMSG_LEN(size_t " length ); +.br +.BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg ); +.sp +.nf +.ta 8n 20n 32n +struct cmsghdr { + socklen_t cmsg_len; /* data byte count, including header */ + int cmsg_level; /* originating protocol */ + int cmsg_type; /* protocol-specific type */ +/* followed by unsigned char cmsg_data[]; */ +}; +.ta +.fi +.SH DESCRIPTION +These macros are used to create and access control messages (also called +ancillary data) that are not a part of the socket payload. +This control information may +include the interface the packet was received on, various rarely used header +fields, an extended error description, a set of file descriptors or Unix +credentials. For instance, control messages can be used to send +additional header fields such as IP options. +Ancillary data is sent by calling +.BR sendmsg (2) +and received by calling +.BR recvmsg (2). +See their manual pages for more information. +.PP +Ancillary data is a sequence of +.B struct cmsghdr +structures with appended data. This sequence should only be accessed +using the macros described in this manual page and never directly. +See the specific protocol man pages for the available control message types. +The maximum ancillary buffer size allowed per socket can be set using the +.B net.core.optmem_max +sysctl; see +.BR socket (7). +.PP +.B CMSG_FIRSTHDR +returns a pointer to the first +.B cmsghdr +in the ancillary +data buffer associated with the passed +.BR msghdr . +.PP +.B CMSG_NXTHDR +returns the next valid +.B cmsghdr +after the passed +.B cmsghdr. +It returns +.B NULL +when there isn't enough space left in the buffer. +.PP +.BR CMSG_ALIGN , +given a length, returns it including the required alignment. This is a +constant expression. +.PP +.B CMSG_SPACE +returns the number of bytes an ancillary element with payload of the passed data length +occupies. This is a constant expression. +.PP +.B CMSG_DATA +returns a pointer to the data portion of a +.BR cmsghdr . +.PP +.B CMSG_LEN +returns the value to store in the +.I cmsg_len +member of the +.B cmsghdr +structure, taking into account any necessary +alignment. It takes the data length as an argument. This is a constant +expression. +.PP +To create ancillary data, first initialize the +.I msg_controllen +member of the +.B msghdr +with the length of the control message buffer. Use +.B CMSG_FIRSTHDR +on the +.B msghdr +to get the first control message and +.B CMSG_NEXTHDR +to get all subsequent ones. +In each control message, initialize +.I cmsg_len +(with +.BR CMSG_LEN ), +the other +.B cmsghdr +header fields, and the data portion using +.BR CMSG_DATA . +Finally, the +.I msg_controllen +field of the +.B msghdr +should be set to the sum of the +.B CMSG_SPACE +of the length of +all control messages in the buffer. +For more information on the +.BR msghdr , +see +.BR recvmsg (2). +.PP +When the control message buffer is too short to store all messages, the +.B MSG_CTRUNC +flag is set in the +.I msg_flags +member of the +.BR msghdr . +.SH EXAMPLE +This code looks for the +.B IP_TTL +option in a received ancillary buffer: +.PP +.RS +.nf +.ta 8n 16n 32n +struct msghdr msgh; +struct cmsghdr *cmsg; +int *ttlptr; +int received_ttl; + +/* Receive auxiliary data in msgh */ +for (cmsg = CMSG_FIRSTHDR(&msgh); + cmsg != NULL; + cmsg = CMSG_NXTHDR(&msgh,cmsg) { + if (cmsg->cmsg_level == SOL_IP + && cmsg->cmsg_type == IP_TTL) { + ttlptr = (int *) CMSG_DATA(cmsg); + received_ttl = *ttlptr; + break; + } +} +if (cmsg == NULL) { + /* + * Error: IP_TTL not enabled or small buffer + * or I/O error. + */ +} +.ta +.fi +.RE +.PP +The code below passes an array of file descriptors over a Unix socket using +.BR SCM_RIGHTS : +.PP +.RS +.nf +.ta 8n 16n 32n +struct msghdr msg = {0}; +struct cmsghdr *cmsg; +int myfds[NUM_FD]; /* Contains the file descriptors to pass. */ +char buf[CMSG_SPACE(sizeof myfds)]; /* ancillary data buffer */ +int *fdptr; + +msg.msg_control = buf; +msg.msg_controllen = sizeof buf; +cmsg = CMSG_FIRSTHDR(&msg); +cmsg->cmsg_level = SOL_SOCKET; +cmsg->cmsg_type = SCM_RIGHTS; +cmsg->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD); +/* Initialize the payload: */ +fdptr = (int *)CMSG_DATA(cmsg); +memcpy(fdptr, myfds, NUM_FD * sizeof(int)); +/* Sum of the length of all control messages in the buffer: */ +msg.msg_controllen = cmsg->cmsg_len; +.ta +.fi +.RE +.SH NOTES +For portability, ancillary data should be accessed only using the macros +described here. +.B CMSG_ALIGN +is a Linux extension and should be not used in portable programs. +.PP +In Linux, +.BR CMSG_LEN , +.BR CMSG_DATA , +and +.B CMSG_ALIGN +are constant expressions (assuming their argument is constant) - +this could be used to declare the size of global +variables. This may be not portable, however. +.SH "CONFORMS TO" +This ancillary data model conforms to the POSIX.1003.1g draft, 4.4BSD-Lite, +the IPv6 advanced API described in RFC2292 and the Single Unix specification v2. +.B +CMSG_ALIGN +is a Linux extension. +.SH "SEE ALSO" +.BR recvmsg (2), +.BR sendmsg (2) +.PP +RFC 2292 diff --git a/man3/confstr.3 b/man3/confstr.3 new file mode 100644 index 000000000..93c8ef6b2 --- /dev/null +++ b/man3/confstr.3 @@ -0,0 +1,111 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 19:53:02 1993 by Rik Faith (faith@cs.unc.edu) +.TH CONFSTR 3 1993-04-17 "GNU" "Linux Programmer's Manual" +.SH NAME +confstr \- get configuration dependent string variables +.SH SYNOPSIS +.nf +.B #define _POSIX_C_SOURCE 2 +or +.B #define _XOPEN_SOURCE +.nl +.B #include +.sp +.BI "size_t confstr(int " "name" ", char *" buf ", size_t " len ); +.fi +.SH DESCRIPTION +.B confstr() +gets the value of configuration-dependent string variables. +.PP +The +.I name +argument is the system variable to be queried. +The following variables are supported: +.TP +.B _CS_PATH +A value for the +.B PATH +variable which indicates where all the POSIX.2 standard utilities can +be found. +.PP +If +.I buf +is not +.BR NULL , +and +.I len +is not zero, +.B confstr() +copies the value of the string to +.I buf +truncated to +.I len \- 1 +characters if necessary, with a null character as termination. +This can be detected by comparing the return value of +.B confstr() +against +.IR len . +.PP +If +.I len +is zero and +.I buf +is +.BR NULL , +.B confstr() +just returns the value as defined below. +.SH "RETURN VALUE" +If +.I name +does not correspond to a valid configuration variable, +.B confstr() +returns 0. +.SH EXAMPLES +The following code fragment determines the path where to find +the POSIX.2 system utilities: +.br +.nf +.in 10 + +char *pathbuf; size_t n; + +n = confstr(_CS_PATH,NULL,(size_t)0); +if ((pathbuf = malloc(n)) == NULL) abort(); +confstr(_CS_PATH, pathbuf, n); +.SH ERRORS +If the value of +.I name +is invalid, +.I errno +is set to +.BR EINVAL . +.SH "CONFORMING TO" +proposed POSIX.2 +.SH BUGS +POSIX.2 is not yet an approved standard; the information in this +manpage is subject to change. +.SH "SEE ALSO" +.BR sh (1), +.BR exec (3), +.BR system (3) diff --git a/man3/conj.3 b/man3/conj.3 new file mode 100644 index 000000000..ee82deacb --- /dev/null +++ b/man3/conj.3 @@ -0,0 +1,27 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CONJ 3 2002-07-28 "" "complex math routines" +.SH NAME +conj, conjf, conjl \- calculate the complex conjugate +.SH SYNOPSIS +.B #include +.sp +.BI "double complex conj(double complex " z ); +.sp +.BI "float complex conjf(float complex " z ); +.sp +.BI "long double complex conjl(long double complex " z ); +.sp +Link with \-lm. +.SH DESCRIPTION +The conj() function returns the complex conjugate value of z. +That is the value obtained by changing the sign of the imaginary part. +.LP +One has cabs(z) = csqrt(z * conj(z)). +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR cabs (3), +.BR sqrt (3), +.BR complex (5) diff --git a/man3/conjf.3 b/man3/conjf.3 new file mode 100644 index 000000000..babfc4a0f --- /dev/null +++ b/man3/conjf.3 @@ -0,0 +1 @@ +.so man3/conj.3 diff --git a/man3/conjl.3 b/man3/conjl.3 new file mode 100644 index 000000000..babfc4a0f --- /dev/null +++ b/man3/conjl.3 @@ -0,0 +1 @@ +.so man3/conj.3 diff --git a/man3/copysign.3 b/man3/copysign.3 new file mode 100644 index 000000000..eebc72ef7 --- /dev/null +++ b/man3/copysign.3 @@ -0,0 +1,55 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-10 by Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.TH COPYSIGN 3 2002-08-10 "GNU" "Linux Programmer's Manual" +.SH NAME +copysign, copysignf, copysignl \- copy sign of a number +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double copysign(double " x ", double " y ); +.br +.BI "float copysignf(float " x ", float " y ); +.br +.BI "long double copysignl(long double " x ", long double " y ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBcopysign()\fP functions return a value whose absolute value matches +that of \fIx\fP, but whose sign matches that of \fIy\fP. +If \fIx\fP is a NaN, then a NaN with the sign of \fIy\fP is returned. +.SH NOTES +The \fBcopysign()\fP functions may treat a negative zero as positive. +.SH "CONFORMING TO" +C99, BSD 4.3. +This function is defined in IEC 559 (and the appendix with +recommended functions in IEEE 754/IEEE 854). +.SH "SEE ALSO" +.BR signbit (3) diff --git a/man3/copysignf.3 b/man3/copysignf.3 new file mode 100644 index 000000000..46ef5e6db --- /dev/null +++ b/man3/copysignf.3 @@ -0,0 +1 @@ +.so man3/copysign.3 diff --git a/man3/copysignl.3 b/man3/copysignl.3 new file mode 100644 index 000000000..46ef5e6db --- /dev/null +++ b/man3/copysignl.3 @@ -0,0 +1 @@ +.so man3/copysign.3 diff --git a/man3/cos.3 b/man3/cos.3 new file mode 100644 index 000000000..74b3f505a --- /dev/null +++ b/man3/cos.3 @@ -0,0 +1,59 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH COS 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +cos, cosf, cosl \- cosine function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double cos(double " x ); +.br +.BI "float cosf(float " x ); +.br +.BI "long double cosl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBcos()\fP function returns the cosine of \fIx\fP, where \fIx\fP is +given in radians. +.SH "RETURN VALUE" +The \fBcos()\fP function returns a value between \-1 and 1. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR acos (3), +.BR asin (3), +.BR atan (3), +.BR atan2 (3), +.BR sin (3), +.BR tan (3) diff --git a/man3/cosf.3 b/man3/cosf.3 new file mode 100644 index 000000000..9abaea4b0 --- /dev/null +++ b/man3/cosf.3 @@ -0,0 +1 @@ +.so man3/cos.3 diff --git a/man3/cosh.3 b/man3/cosh.3 new file mode 100644 index 000000000..ede541ea1 --- /dev/null +++ b/man3/cosh.3 @@ -0,0 +1,58 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1996-06-08 by aeb +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH COSH 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +cosh, coshf, coshl \- hyperbolic cosine function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double cosh(double " x ); +.br +.BI "float coshf(float " x ); +.br +.BI "long double coshl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBcosh()\fP function returns the hyperbolic cosine of \fIx\fP, which +is defined mathematically as (exp(x) + exp(-x)) / 2. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899 (C99). +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR acosh (3), +.BR asinh (3), +.BR atanh (3), +.BR sinh (3), +.BR tanh (3) diff --git a/man3/coshf.3 b/man3/coshf.3 new file mode 100644 index 000000000..e9bab10c7 --- /dev/null +++ b/man3/coshf.3 @@ -0,0 +1 @@ +.so man3/cosh.3 diff --git a/man3/coshl.3 b/man3/coshl.3 new file mode 100644 index 000000000..e9bab10c7 --- /dev/null +++ b/man3/coshl.3 @@ -0,0 +1 @@ +.so man3/cosh.3 diff --git a/man3/cosl.3 b/man3/cosl.3 new file mode 100644 index 000000000..9abaea4b0 --- /dev/null +++ b/man3/cosl.3 @@ -0,0 +1 @@ +.so man3/cos.3 diff --git a/man3/cpow.3 b/man3/cpow.3 new file mode 100644 index 000000000..6a59bc614 --- /dev/null +++ b/man3/cpow.3 @@ -0,0 +1,25 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CPOW 3 2002-07-28 "" "complex math routines" +.SH NAME +cpow, cpowf, cpowl \- complex power function +.SH SYNOPSIS +.B #include +.sp +.BI "double complex cpow(double complex " x ", complex double " z ");" +.sp +.BI "float complex cpowf(float complex " x ", complex float " z ");" +.sp +.BI "long double complex cpowl(long double complex " x ", complex long double " z ");" +.sp +Link with \-lm. +.SH DESCRIPTION +The function calculates x raised to the power z. +(With a branch cut for x along the negative real axis.) +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR cabs (3), +.BR pow (3), +.BR complex (5) diff --git a/man3/cpowf.3 b/man3/cpowf.3 new file mode 100644 index 000000000..91e516d15 --- /dev/null +++ b/man3/cpowf.3 @@ -0,0 +1 @@ +.so man3/cpow.3 diff --git a/man3/cpowl.3 b/man3/cpowl.3 new file mode 100644 index 000000000..91e516d15 --- /dev/null +++ b/man3/cpowl.3 @@ -0,0 +1 @@ +.so man3/cpow.3 diff --git a/man3/cproj.3 b/man3/cproj.3 new file mode 100644 index 000000000..16750184c --- /dev/null +++ b/man3/cproj.3 @@ -0,0 +1,29 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CPROJ 3 2002-07-28 "" "complex math routines" +.SH NAME +cproj, cprojf, cprojl \- project into Riemann Sphere +.SH SYNOPSIS +.B #include +.sp +.BI "double complex cproj(double complex " z ");" +.sp +.BI "float complex cprojf(float complex " z ");" +.sp +.BI "long double complex cprojl(long double complex " z ");" +.sp +Link with \-lm. +.SH DESCRIPTION +This function projects a point in the plane onto the surface of a +Riemann Sphere, the one-point compactification of the complex plane. +Each finite point z projects to z itself. +Every complex infinite value is projected to a single infinite value, +namely to positive infinity on the real axis. +.SH "CONFORMING TO" +C99 +.SH NOTE +The glibc implementation is broken and does something entirely different. +.SH "SEE ALSO" +.BR cabs (3), +.BR complex (5) diff --git a/man3/cprojf.3 b/man3/cprojf.3 new file mode 100644 index 000000000..dc33dea33 --- /dev/null +++ b/man3/cprojf.3 @@ -0,0 +1 @@ +.so man3/cproj.3 diff --git a/man3/cprojl.3 b/man3/cprojl.3 new file mode 100644 index 000000000..dc33dea33 --- /dev/null +++ b/man3/cprojl.3 @@ -0,0 +1 @@ +.so man3/cproj.3 diff --git a/man3/creal.3 b/man3/creal.3 new file mode 100644 index 000000000..35986d3fd --- /dev/null +++ b/man3/creal.3 @@ -0,0 +1,28 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CREAL 3 2002-07-28 "" "complex math routines" +.SH NAME +creal, crealf, creall \- get real part of a complex number +.SH SYNOPSIS +.B #include +.sp +.BI "double creal(double complex " z ); +.sp +.BI "float crealf(float complex " z ); +.sp +.BI "long double creall(long double complex " z ); +.sp +Link with \-lm. +.SH DESCRIPTION +The creal() function returns the real part of the complex number z. +.LP +One has z = creal(z) + I*cimag(z). +.SH NOTE +The gcc supports also __real__. That is a GNU extension. +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR cabs (3), +.BR cimag (3), +.BR complex (5) diff --git a/man3/crealf.3 b/man3/crealf.3 new file mode 100644 index 000000000..409b15707 --- /dev/null +++ b/man3/crealf.3 @@ -0,0 +1 @@ +.so man3/creal.3 diff --git a/man3/creall.3 b/man3/creall.3 new file mode 100644 index 000000000..409b15707 --- /dev/null +++ b/man3/creall.3 @@ -0,0 +1 @@ +.so man3/creal.3 diff --git a/man3/crypt.3 b/man3/crypt.3 new file mode 100644 index 000000000..251ab7bf6 --- /dev/null +++ b/man3/crypt.3 @@ -0,0 +1,151 @@ +.\" Michael Haardt (michael@cantor.informatik.rwth.aachen.de) Sat Sep 3 22:00:30 MET DST 1994 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Sun Feb 19 21:32:25 1995, faith@cs.unc.edu edited details away +.\" +.\" TO DO: This manual page should go more into detail how DES is perturbed, +.\" which string will be encrypted, and what determines the repetition factor. +.\" Is a simple repetition using ECB used, or something more advanced? I hope +.\" the presented explanations are at least better than nothing, but by no +.\" means enough. +.\" +.\" added _XOPEN_SOURCE, aeb, 970705 +.\" added GNU MD5 stuff, aeb, 011223 +.\" +.TH CRYPT 3 2001-12-23 "" "Library functions" +.SH NAME +crypt \- password and data encryption +.SH SYNOPSIS +.B #define _XOPEN_SOURCE +.br +.B #include +.sp +.BI "char *crypt(const char *" key ", const char *" salt ); +.SH DESCRIPTION +.B crypt +is the password encryption function. It is based on the Data Encryption +Standard algorithm with variations intended (among other things) to +discourage use of hardware implementations of a key search. +.PP +.I key +is a user's typed password. +.PP +.I salt +is a two-character string chosen from the set +[\fBa\fP\(en\fBzA\fP\(en\fBZ0\fP\(en\fB9./\fP]. This string is used to +perturb the algorithm in one of 4096 different ways. +.PP +By taking the lowest 7 bits of each of the first eight characters of the +.IR key , +a 56-bit key is obtained. This 56-bit key is used to encrypt repeatedly a +constant string (usually a string consisting of all zeros). The returned +value points to the encrypted password, a series of 13 printable ASCII +characters (the first two characters represent the salt itself). The +return value points to static data whose content is overwritten by each +call. +.PP +Warning: The key space consists of +.if t 2\s-2\u56\s0\d +.if n 2**56 +equal 7.2e16 possible values. Exhaustive searches of this key space are +possible using massively parallel computers. Software, such as +.BR crack (1), +is available which will search the portion of this key space that is +generally used by humans for passwords. Hence, password selection should, +at minimum, avoid common words and names. The use of a +.BR passwd (1) +program that checks for crackable passwords during the selection process is +recommended. +.PP +The DES algorithm itself has a few quirks which make the use of the +.BR crypt (3) +interface a very poor choice for anything other than password +authentication. If you are planning on using the +.BR crypt (3) +interface for a cryptography project, don't do it: get a good book on +encryption and one of the widely available DES libraries. +.SH "RETURN VALUE" +A pointer to the encrypted password is returned. +On error, NULL is returned. +.SH ERRORS +.TP +.B ENOSYS +The +.B crypt +function was not implemented, probably because of U.S.A. export restrictions. +.\" This level of detail is not necessary in this man page. . . +.\" .PP +.\" When encrypting a plain text P using DES with the key K results in the +.\" encrypted text C, then the complementary plain text P' being encrypted +.\" using the complementary key K' will result in the complementary encrypted +.\" text C'. +.\" .PP +.\" Weak keys are keys which stay invariant under the DES key transformation. +.\" The four known weak keys 0101010101010101, fefefefefefefefe, +.\" 1f1f1f1f0e0e0e0e and e0e0e0e0f1f1f1f1 must be avoided. +.\" .PP +.\" There are six known half weak key pairs, which keys lead to the same +.\" encrypted data. Keys which are part of such key clusters should be +.\" avoided. +.\" Sorry, I could not find out what they are. +.\"" +.\" .PP +.\" Heavily redundant data causes trouble with DES encryption, when used in the +.\" .I codebook +.\" mode that +.\" .BR crypt (3) +.\" implements. The +.\" .BR crypt (3) +.\" interface should be used only for its intended purpose of password +.\" verification, and should not be used as part of a data encryption tool. +.\" .PP +.\" The first and last three output bits of the fourth S-box can be +.\" represented as function of their input bits. Empiric studies have +.\" shown that S-boxes partially compute the same output for similar input. +.\" It is suspected that this may contain a back door which could allow the +.\" NSA to decrypt DES encrypted data. +.\" .PP +.\" Making encrypted data computed using crypt() publically available has +.\" to be considered insecure for the given reasons. +.SH "GNU EXTENSION" +The glibc2 version of this function has the following additional features. +If +.I salt +is a character string starting with the three characters "$1$" +followed by at most eight characters, and optionally terminated by "$", +then instead of using the DES machine, the glibc crypt function +uses an MD5-based algorithm, and outputs up to 34 bytes, +namely "$1$$", where "" stands for the up to 8 +characters following "$1$" in the salt, followed by 22 bytes chosen +from the set [\fBa\fP\(en\fBzA\fP\(en\fBZ0\fP\(en\fB9./\fP]. +The entire key is significant here (instead of only the first +8 bytes). +.LP +Programs using this function must be linked with -lcrypt. +.SH "CONFORMING TO" +SVID, X/OPEN, BSD 4.3, POSIX 1003.1-2001 +.SH "SEE ALSO" +.BR login (1), +.BR passwd (1), +.BR encrypt (3), +.BR getpass (3), +.BR passwd (5) diff --git a/man3/csin.3 b/man3/csin.3 new file mode 100644 index 000000000..9b8710577 --- /dev/null +++ b/man3/csin.3 @@ -0,0 +1,25 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CSIN 3 2002-07-28 "" "complex math routines" +.SH NAME +csin, csinf, csinl \- complex sine function +.SH SYNOPSIS +.B #include +.sp +.BI "double complex csin(double complex " z ");" +.sp +.BI "float complex csinf(float complex " z ); +.sp +.BI "long double complex csinl(long double complex " z ");" +.sp +Link with \-lm. +.SH DESCRIPTION +The complex sine function csin(z) is defined as (exp(i*z)-exp(-i*z))/(2*i). +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR cabs (3), +.BR csin (3), +.BR ctan (3), +.BR complex (5) diff --git a/man3/csinf.3 b/man3/csinf.3 new file mode 100644 index 000000000..a5fe0e010 --- /dev/null +++ b/man3/csinf.3 @@ -0,0 +1 @@ +.so man3/csin.3 diff --git a/man3/csinh.3 b/man3/csinh.3 new file mode 100644 index 000000000..fa6c4f229 --- /dev/null +++ b/man3/csinh.3 @@ -0,0 +1,26 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CSINH 3 2002-07-28 "" "complex math routines" +.SH NAME +csinh, csinhf, csinhl \- complex hyperbolic sine +.SH SYNOPSIS +.B #include +.sp +.BI "double complex csinh(double complex " z ");" +.sp +.BI "float complex csinhf(float complex " z ");" +.sp +.BI "long double complex csinhl(long double complex " z ");" +.sp +Link with \-lm. +.SH DESCRIPTION +The complex hyperbolic sine function sinh(z) is defined as +(exp(z)-exp(-z))/2. +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR cabs (3), +.BR ccosh (3), +.BR ctanh (3), +.BR complex (5) diff --git a/man3/csinhf.3 b/man3/csinhf.3 new file mode 100644 index 000000000..e6a49a65f --- /dev/null +++ b/man3/csinhf.3 @@ -0,0 +1 @@ +.so man3/csinh.3 diff --git a/man3/csinhl.3 b/man3/csinhl.3 new file mode 100644 index 000000000..e6a49a65f --- /dev/null +++ b/man3/csinhl.3 @@ -0,0 +1 @@ +.so man3/csinh.3 diff --git a/man3/csinl.3 b/man3/csinl.3 new file mode 100644 index 000000000..a5fe0e010 --- /dev/null +++ b/man3/csinl.3 @@ -0,0 +1 @@ +.so man3/csin.3 diff --git a/man3/csqrt.3 b/man3/csqrt.3 new file mode 100644 index 000000000..f3629d1ab --- /dev/null +++ b/man3/csqrt.3 @@ -0,0 +1,29 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CSQRT 3 2002-07-28 "" "complex math routines" +.SH NAME +csqrt, csqrtf, csqrtl \- complex square root +.SH SYNOPSIS +.B #include +.sp +.BI "double complex csqrt(double complex " z ");" +.sp +.BI "float complex csqrtf(float complex " z ");" +.sp +.BI "long double complex csqrtl(long double complex " z ");" +.sp +Link with \-lm. +.SH DESCRIPTION +Calculate the square root of a given complex number, +with nonnegative real part, and +with a branch cut along the negative real axis. +(That means that csqrt(-1+eps*I) will be close to I while +csqrt(-1-eps*I) will be close to -I, if eps is a small positive +real number.) +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR cabs (3), +.BR cexp (3), +.BR complex (5) diff --git a/man3/csqrtf.3 b/man3/csqrtf.3 new file mode 100644 index 000000000..e3cf32905 --- /dev/null +++ b/man3/csqrtf.3 @@ -0,0 +1 @@ +.so man3/csqrt.3 diff --git a/man3/csqrtl.3 b/man3/csqrtl.3 new file mode 100644 index 000000000..e3cf32905 --- /dev/null +++ b/man3/csqrtl.3 @@ -0,0 +1 @@ +.so man3/csqrt.3 diff --git a/man3/ctan.3 b/man3/ctan.3 new file mode 100644 index 000000000..f3ed1314b --- /dev/null +++ b/man3/ctan.3 @@ -0,0 +1,25 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CTAN 3 2002-07-28 "" "complex math routines" +.SH NAME +ctan, ctanf, ctanl \- complex tangent function +.SH SYNOPSIS +.B #include +.sp +.BI "double complex ctan(double complex " z ");" +.sp +.BI "float complex ctanf(float complex " z ); +.sp +.BI "long double complex ctanl(long double complex " z ");" +.sp +Link with \-lm. +.SH DESCRIPTION +The complex tangent function ctan(z) is defined as ccos(z)/csin(z). +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR cabs (3), +.BR ccos (3), +.BR csin (3), +.BR complex (5) diff --git a/man3/ctanf.3 b/man3/ctanf.3 new file mode 100644 index 000000000..47e122864 --- /dev/null +++ b/man3/ctanf.3 @@ -0,0 +1 @@ +.so man3/ctan.3 diff --git a/man3/ctanh.3 b/man3/ctanh.3 new file mode 100644 index 000000000..c5c50b259 --- /dev/null +++ b/man3/ctanh.3 @@ -0,0 +1,26 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH CTANH 3 2002-07-28 "" "complex math routines" +.SH NAME +ctanh, ctanhf, ctanhl \- complex hyperbolic tangent +.SH SYNOPSIS +.B #include +.sp +.BI "double complex ctanh(double complex " z ");" +.sp +.BI "float complex ctanhf(float complex " z ); +.sp +.BI "long double complex ctanhl(long double complex " z ");" +.sp +Link with \-lm. +.SH DESCRIPTION +The complex hyperbolic tangent function tanh(z) is defined as +cosh(z)/sinh(z). +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR cabs (3), +.BR ccosh (3), +.BR csinh (3), +.BR complex (5) diff --git a/man3/ctanhf.3 b/man3/ctanhf.3 new file mode 100644 index 000000000..1c6e2c28e --- /dev/null +++ b/man3/ctanhf.3 @@ -0,0 +1 @@ +.so man3/ctanh.3 diff --git a/man3/ctanhl.3 b/man3/ctanhl.3 new file mode 100644 index 000000000..1c6e2c28e --- /dev/null +++ b/man3/ctanhl.3 @@ -0,0 +1 @@ +.so man3/ctanh.3 diff --git a/man3/ctanl.3 b/man3/ctanl.3 new file mode 100644 index 000000000..47e122864 --- /dev/null +++ b/man3/ctanl.3 @@ -0,0 +1 @@ +.so man3/ctan.3 diff --git a/man3/ctermid.3 b/man3/ctermid.3 new file mode 100644 index 000000000..1cec6bf39 --- /dev/null +++ b/man3/ctermid.3 @@ -0,0 +1,58 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 19:51:06 1993 by Rik Faith (faith@cs.unc.edu) +.TH CTERMID 3 1993-04-06 "GNU" "Linux Programmer's Manual" +.SH NAME +ctermid \- get controlling terminal name +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *ctermid(char *" "s" ); +.fi +.SH DESCRIPTION +.B ctermid() +returns a string which is the pathname for the current controlling terminal for this +process. +If +.I s +is +.BR NULL , +a static buffer is used, otherwise +.I s +points to a buffer used to hold the terminal pathname. +The symbolic constant +.B L_ctermid +is the maximum number of characters in the returned pathname. +.SH "RETURN VALUE" +The pointer to the pathname. +.SH "CONFORMING TO" +SVID, Issue 1; POSIX.1 +.SH BUGS +The path returned may not uniquely identify the controlling +terminal; it may, for example, be +.BR /dev/tty . +.PP +It is not assured that the program can open the terminal. +.SH "SEE ALSO" +.BR ttyname (3) diff --git a/man3/ctime.3 b/man3/ctime.3 new file mode 100644 index 000000000..30b4d08ce --- /dev/null +++ b/man3/ctime.3 @@ -0,0 +1,230 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:49:27 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Apr 26 12:38:55 MET DST 1996 by Martin Schulze (joey@linux.de) +.\" Modified 2001-11-13, aeb +.\" Modified 2001-12-13, joey, aeb +.\" +.TH CTIME 3 2001-12-13 "" "Linux Programmer's Manual" +.SH NAME +asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r, +localtime_r \- transform date and time to broken-down time or ASCII +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *asctime(const struct tm *" tm ); +.br +.BI "char *asctime_r(const struct tm *" tm ", char *" buf ); +.sp +.BI "char *ctime(const time_t *" timep ); +.br +.BI "char *ctime_r(const time_t *" timep ", char *" buf ); +.sp +.BI "struct tm *gmtime(const time_t *" timep ); +.br +.BI "struct tm *gmtime_r(const time_t *" timep ", struct tm *" result ); +.sp +.BI "struct tm *localtime(const time_t *" timep ); +.br +.BI "struct tm *localtime_r(const time_t *" timep ", struct tm *" result ); +.sp +.BI "time_t mktime(struct tm *" tm ); +.fi +.SH DESCRIPTION +The \fBctime()\fP, \fBgmtime()\fP and \fBlocaltime()\fP functions all take +an argument of data type \fItime_t\fP which represents calendar time. +When interpreted as an absolute time value, it represents the number of +seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal +Time (UTC). +.PP +The \fBasctime()\fP and \fBmktime()\fP functions both take an argument +representing broken-down time which is a representation +separated into year, month, day, etc. +.PP +Broken-down time is stored +in the structure \fItm\fP which is defined in \fI\fP as follows: +.sp +.RS +.nf +.ne 11 +.ta 8n 16n 32n +struct tm { + int tm_sec; /* seconds */ + int tm_min; /* minutes */ + int tm_hour; /* hours */ + int tm_mday; /* day of the month */ + int tm_mon; /* month */ + int tm_year; /* year */ + int tm_wday; /* day of the week */ + int tm_yday; /* day in the year */ + int tm_isdst; /* daylight saving time */ +}; +.ta +.fi +.RE +.PP +The members of the \fItm\fP structure are: +.TP +.I tm_sec +The number of seconds after the minute, normally in the range 0 to 59, +but can be up to 61 to allow for leap seconds. +.TP +.I tm_min +The number of minutes after the hour, in the range 0 to 59. +.TP +.I tm_hour +The number of hours past midnight, in the range 0 to 23. +.TP +.I tm_mday +The day of the month, in the range 1 to 31. +.TP +.I tm_mon +The number of months since January, in the range 0 to 11. +.TP +.I tm_year +The number of years since 1900. +.TP +.I tm_wday +The number of days since Sunday, in the range 0 to 6. +.TP +.I tm_yday +The number of days since January 1, in the range 0 to 365. +.TP +.I tm_isdst +A flag that indicates whether daylight saving time is in effect at the +time described. The value is positive if daylight saving time is in +effect, zero if it is not, and negative if the information is not +available. +.PP +The call +.BI ctime( t ) +is equivalent to +.BI asctime(localtime( t )) \fR. +It converts the calendar time \fIt\fP into a string of the form +.sp +.RS +"Wed Jun 30 21:49:08 1993\\n" +.RE +.sp +The abbreviations for the days of the week are `Sun', `Mon', `Tue', `Wed', +`Thu', `Fri', and `Sat'. The abbreviations for the months are `Jan', +`Feb', `Mar', `Apr', `May', `Jun', `Jul', `Aug', `Sep', `Oct', `Nov', and +`Dec'. The return value points to a statically allocated string which +might be overwritten by subsequent calls to any of the date and time +functions. The function also sets the external variable \fItzname\fP (see +.BR tzset (3)) +with information about the current time zone. +The re-entrant version \fBctime_r()\fP does the same, but stores the +string in a user-supplied buffer of length at least 26. It need not +set \fItzname\fP. +.PP +The \fBgmtime()\fP function converts the calendar time \fItimep\fP to +broken-down time representation, expressed in Coordinated Universal Time +(UTC). It may return NULL when the year does not fit into an integer. +The return value points to a statically allocated struct which might be +overwritten by subsequent calls to any of the date and time functions. +The \fBgmtime_r()\fP function does the same, but stores the data in a +user-supplied struct. +.PP +The \fBlocaltime()\fP function converts the calendar time \fItimep\fP to +broken-time representation, expressed relative to the user's specified +time zone. The function acts as if it called +.BR tzset (3) +and sets the external variables \fItzname\fP with +information about the current time zone, \fItimezone\fP with the difference +between Coordinated Universal Time (UTC) and local standard time in +seconds, and \fIdaylight\fP to a non-zero value if daylight savings +time rules apply during some part of the year. +The return value points to a statically allocated struct which might be +overwritten by subsequent calls to any of the date and time functions. +The \fBlocaltime_r()\fP function does the same, but stores the data in a +user-supplied struct. It need not set \fItzname\fP. +.PP +The \fBasctime()\fP function converts the broken-down time value +\fItm\fP into a string with the same format as \fBctime()\fP. +The return value points to a statically allocated string which might be +overwritten by subsequent calls to any of the date and time functions. +The \fBasctime_r()\fP function does the same, but stores the string in +a user-supplied buffer of length at least 26. +.PP +The \fBmktime()\fP function converts a broken-down time structure, expressed +as local time, to calendar time representation. The function ignores +the specified contents of the structure members \fItm_wday\fP and \fItm_yday\fP +and recomputes them from the other information in the broken-down time +structure. +If structure members are outside their legal interval, they will be +normalized (so that, e.g., 40 October is changed into 9 November). +Calling \fBmktime()\fP also sets the external variable \fItzname\fP with +information about the current time zone. If the specified broken-down +time cannot be represented as calendar time (seconds since the epoch), +\fBmktime()\fP returns a value of (time_t)(\-1) and does not alter the +\fItm_wday\fP and \fItm_yday\fP members of the broken-down time structure. +.SH "RETURN VALUE" +Each of these functions returns the value described, or NULL +(\-1 in case of \fBmktime()\fP) in case an error was detected. +.SH NOTES +The four functions +.BR asctime() , +.BR ctime() , +.B gmtime() +and +.B localtime() +return a pointer to static data and hence are not thread-safe. +Thread-safe versions +.BR asctime_r() , +.BR ctime_r() , +.B gmtime_r() +and +.BR localtime_r() +are specified by SUSv2, and available since libc 5.2.5. +.LP +The glibc version of struct tm has additional fields +.sp +.RS +.nf +long tm_gmtoff; /* Seconds east of UTC */ +const char *tm_zone; /* Timezone abbreviation */ +.fi +.RE +.sp +defined when _BSD_SOURCE was set before including +.IR . +This is a BSD extension, present in 4.3BSD-Reno. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899 +.SH "SEE ALSO" +.BR date (1), +.BR gettimeofday (2), +.BR time (2), +.BR utime (2), +.BR clock (3), +.BR difftime (3), +.BR newctime (3), +.BR strftime (3), +.BR strptime (3), +.BR tzset (3) diff --git a/man3/ctime_r.3 b/man3/ctime_r.3 new file mode 100644 index 000000000..84a3baa92 --- /dev/null +++ b/man3/ctime_r.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man3/cuserid.3 b/man3/cuserid.3 new file mode 100644 index 000000000..b6d53bf72 --- /dev/null +++ b/man3/cuserid.3 @@ -0,0 +1 @@ +.so man3/getlogin.3 diff --git a/man3/daemon.3 b/man3/daemon.3 new file mode 100644 index 000000000..84c14c023 --- /dev/null +++ b/man3/daemon.3 @@ -0,0 +1,88 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)daemon.3 8.1 (Berkeley) 6/9/93 +.\" Added mentioning of glibc weirdness wrt unistd.h. 5/11/98, Al Viro +.TH DAEMON 3 1993-06-09 "BSD MANPAGE" "Linux Programmer's Manual" +.SH NAME +daemon \- run in the background +.SH SYNOPSIS +.B #include +.sp +.BI "int daemon(int " nochdir ", int " noclose ); +.SH DESCRIPTION +The +.BR daemon () +function is for programs wishing to detach themselves from the +controlling terminal and run in the background as system daemons. +.PP +Unless the argument +.I nochdir +is non-zero, +.BR daemon () +changes the current working directory to the root ("/"). +.PP +Unless the argument +.I noclose +is non-zero, +.BR daemon () +will redirect standard input, standard output and standard error +to \fI/dev/null\fP. +.SH "RETURN VALUE" +(This function forks, and if the +.B fork() +succeeds, the parent does +.\" not .IR in order not to underline _ +.BR _exit (0), +so that further errors are seen by the child only.) +On success zero will be returned. +If an error occurs, +.BR daemon () +returns \-1 and sets the global variable +.I errno +to any of the errors specified for the library functions +.BR fork (2) +and +.BR setsid (2). +.SH "SEE ALSO" +.BR fork (2), +.BR setsid (2) +.SH NOTES +The glibc implementation can also return \-1 when +.I /dev/null +exists but is not a character device with the expected +major and minor numbers. In this case +.I errno +need not be set. +.SH HISTORY +The +.BR daemon () +function first appeared in BSD4.4. diff --git a/man3/db.3 b/man3/db.3 new file mode 100644 index 000000000..03ede6636 --- /dev/null +++ b/man3/db.3 @@ -0,0 +1 @@ +.so man3/dbopen.3 diff --git a/man3/dbopen.3 b/man3/dbopen.3 new file mode 100644 index 000000000..47277c874 --- /dev/null +++ b/man3/dbopen.3 @@ -0,0 +1,476 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 +.\" +.TH DBOPEN 3 1994-01-02 +.UC 7 +.SH NAME +dbopen \- database access methods +.SH SYNOPSIS +.nf +.ft B +#include +#include +#include + +DB * +dbopen(const char *file, int flags, int mode, DBTYPE type, +.ti +5 +const void *openinfo); +.ft R +.fi +.SH DESCRIPTION +.IR Dbopen +is the library interface to database files. +The supported file formats are btree, hashed and UNIX file oriented. +The btree format is a representation of a sorted, balanced tree structure. +The hashed format is an extensible, dynamic hashing scheme. +The flat-file format is a byte stream file with fixed or variable length +records. +The formats and file format specific information are described in detail +in their respective manual pages +.IR btree (3), +.IR hash (3) +and +.IR recno (3). +.PP +Dbopen opens +.I file +for reading and/or writing. +Files never intended to be preserved on disk may be created by setting +the file parameter to NULL. +.PP +The +.I flags +and +.I mode +arguments are as specified to the +.IR open (2) +routine, however, only the O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK, +O_RDONLY, O_RDWR, O_SHLOCK and O_TRUNC flags are meaningful. +(Note, opening a database file O_WRONLY is not possible.) +.\"Three additional options may be specified by +.\".IR or 'ing +.\"them into the +.\".I flags +.\"argument. +.\".TP +.\"DB_LOCK +.\"Do the necessary locking in the database to support concurrent access. +.\"If concurrent access isn't needed or the database is read-only this +.\"flag should not be set, as it tends to have an associated performance +.\"penalty. +.\".TP +.\"DB_SHMEM +.\"Place the underlying memory pool used by the database in shared +.\"memory. +.\"Necessary for concurrent access. +.\".TP +.\"DB_TXN +.\"Support transactions in the database. +.\"The DB_LOCK and DB_SHMEM flags must be set as well. +.PP +The +.I type +argument is of type DBTYPE (as defined in the include file) and +may be set to DB_BTREE, DB_HASH or DB_RECNO. +.PP +The +.I openinfo +argument is a pointer to an access method specific structure described +in the access method's manual page. +If +.I openinfo +is NULL, each access method will use defaults appropriate for the system +and the access method. +.PP +.I Dbopen +returns a pointer to a DB structure on success and NULL on error. +The DB structure is defined in the include file, and contains at +least the following fields: +.sp +.nf +typedef struct { +.RS +DBTYPE type; +int (*close)(const DB *db); +int (*del)(const DB *db, const DBT *key, u_int flags); +int (*fd)(const DB *db); +int (*get)(const DB *db, DBT *key, DBT *data, u_int flags); +int (*put)(const DB *db, DBT *key, const DBT *data, +.ti +5 +u_int flags); +int (*sync)(const DB *db, u_int flags); +int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags); +.RE +} DB; +.fi +.PP +These elements describe a database type and a set of functions performing +various actions. +These functions take a pointer to a structure as returned by +.IR dbopen , +and sometimes one or more pointers to key/data structures and a flag value. +.TP +type +The type of the underlying access method (and file format). +.TP +close +A pointer to a routine to flush any cached information to disk, free any +allocated resources, and close the underlying file(s). +Since key/data pairs may be cached in memory, failing to sync the file +with a +.I close +or +.I sync +function may result in inconsistent or lost information. +.I Close +routines return \-1 on error (setting +.IR errno ) +and 0 on success. +.TP +del +A pointer to a routine to remove key/data pairs from the database. +.IP +The parameter +.I flag +may be set to the following value: +.RS +.TP +R_CURSOR +Delete the record referenced by the cursor. +The cursor must have previously been initialized. +.RE +.IP +.I Delete +routines return \-1 on error (setting +.IR errno ), +0 on success, and 1 if the specified +.I key +was not in the file. +.TP +fd +A pointer to a routine which returns a file descriptor representative +of the underlying database. +A file descriptor referencing the same file will be returned to all +processes which call +.I dbopen +with the same +.I file +name. +This file descriptor may be safely used as an argument to the +.IR fcntl (2) +and +.IR flock (2) +locking functions. +The file descriptor is not necessarily associated with any of the +underlying files used by the access method. +No file descriptor is available for in memory databases. +.I Fd +routines return \-1 on error (setting +.IR errno ), +and the file descriptor on success. +.TP +get +A pointer to a routine which is the interface for keyed retrieval from +the database. +The address and length of the data associated with the specified +.I key +are returned in the structure referenced by +.IR data . +.I Get +routines return \-1 on error (setting +.IR errno ), +0 on success, and 1 if the +.I key +was not in the file. +.TP +put +A pointer to a routine to store key/data pairs in the database. +.IP +The parameter +.I flag +may be set to one of the following values: +.RS +.TP +R_CURSOR +Replace the key/data pair referenced by the cursor. +The cursor must have previously been initialized. +.TP +R_IAFTER +Append the data immediately after the data referenced by +.IR key , +creating a new key/data pair. +The record number of the appended key/data pair is returned in the +.I key +structure. +(Applicable only to the DB_RECNO access method.) +.TP +R_IBEFORE +Insert the data immediately before the data referenced by +.IR key , +creating a new key/data pair. +The record number of the inserted key/data pair is returned in the +.I key +structure. +(Applicable only to the DB_RECNO access method.) +.TP +R_NOOVERWRITE +Enter the new key/data pair only if the key does not previously exist. +.TP +R_SETCURSOR +Store the key/data pair, setting or initializing the position of the +cursor to reference it. +(Applicable only to the DB_BTREE and DB_RECNO access methods.) +.RE +.IP +R_SETCURSOR is available only for the DB_BTREE and DB_RECNO access +methods because it implies that the keys have an inherent order +which does not change. +.IP +R_IAFTER and R_IBEFORE are available only for the DB_RECNO +access method because they each imply that the access method is able to +create new keys. +This is only true if the keys are ordered and independent, record numbers +for example. +.IP +The default behavior of the +.I put +routines is to enter the new key/data pair, replacing any previously +existing key. +.IP +.I Put +routines return \-1 on error (setting +.IR errno ), +0 on success, and 1 if the R_NOOVERWRITE +.I flag +was set and the key already exists in the file. +.TP +seq +A pointer to a routine which is the interface for sequential +retrieval from the database. +The address and length of the key are returned in the structure +referenced by +.IR key , +and the address and length of the data are returned in the +structure referenced +by +.IR data . +.IP +Sequential key/data pair retrieval may begin at any time, and the +position of the ``cursor'' is not affected by calls to the +.IR del , +.IR get , +.IR put , +or +.I sync +routines. +Modifications to the database during a sequential scan will be reflected +in the scan, i.e. records inserted behind the cursor will not be returned +while records inserted in front of the cursor will be returned. +.IP +The flag value +.B must +be set to one of the following values: +.RS +.TP +R_CURSOR +The data associated with the specified key is returned. +This differs from the +.I get +routines in that it sets or initializes the cursor to the location of +the key as well. +(Note, for the DB_BTREE access method, the returned key is not necessarily an +exact match for the specified key. +The returned key is the smallest key greater than or equal to the specified +key, permitting partial key matches and range searches.) +.TP +R_FIRST +The first key/data pair of the database is returned, and the cursor +is set or initialized to reference it. +.TP +R_LAST +The last key/data pair of the database is returned, and the cursor +is set or initialized to reference it. +(Applicable only to the DB_BTREE and DB_RECNO access methods.) +.TP +R_NEXT +Retrieve the key/data pair immediately after the cursor. +If the cursor is not yet set, this is the same as the R_FIRST flag. +.TP +R_PREV +Retrieve the key/data pair immediately before the cursor. +If the cursor is not yet set, this is the same as the R_LAST flag. +(Applicable only to the DB_BTREE and DB_RECNO access methods.) +.RE +.IP +R_LAST and R_PREV are available only for the DB_BTREE and DB_RECNO +access methods because they each imply that the keys have an inherent +order which does not change. +.IP +.I Seq +routines return \-1 on error (setting +.IR errno ), +0 on success and 1 if there are no key/data pairs less than or greater +than the specified or current key. +If the DB_RECNO access method is being used, and if the database file +is a character special file and no complete key/data pairs are currently +available, the +.I seq +routines return 2. +.TP +sync +A pointer to a routine to flush any cached information to disk. +If the database is in memory only, the +.I sync +routine has no effect and will always succeed. +.IP +The flag value may be set to the following value: +.RS +.TP +R_RECNOSYNC +If the DB_RECNO access method is being used, this flag causes +the sync routine to apply to the btree file which underlies the +recno file, not the recno file itself. +(See the +.I bfname +field of the +.IR recno (3) +manual page for more information.) +.RE +.IP +.I Sync +routines return \-1 on error (setting +.IR errno ) +and 0 on success. +.SH "KEY/DATA PAIRS" +Access to all file types is based on key/data pairs. +Both keys and data are represented by the following data structure: +.PP +typedef struct { +.RS +void *data; +.br +size_t size; +.RE +} DBT; +.PP +The elements of the DBT structure are defined as follows: +.TP +data +A pointer to a byte string. +.TP +size +The length of the byte string. +.PP +Key and data byte strings may reference strings of essentially unlimited +length although any two of them must fit into available memory at the same +time. +It should be noted that the access methods provide no guarantees about +byte string alignment. +.SH ERRORS +The +.I dbopen +routine may fail and set +.I errno +for any of the errors specified for the library routines +.IR open (2) +and +.IR malloc (3) +or the following: +.TP +[EFTYPE] +A file is incorrectly formatted. +.TP +[EINVAL] +A parameter has been specified (hash function, pad byte etc.) that is +incompatible with the current file specification or which is not +meaningful for the function (for example, use of the cursor without +prior initialization) or there is a mismatch between the version +number of file and the software. +.PP +The +.I close +routines may fail and set +.I errno +for any of the errors specified for the library routines +.IR close (2), +.IR read (2), +.IR write (2), +.IR free (3), +or +.IR fsync (2). +.PP +The +.IR del , +.IR get , +.I put +and +.I seq +routines may fail and set +.I errno +for any of the errors specified for the library routines +.IR read (2), +.IR write (2), +.IR free (3) +or +.IR malloc (3). +.PP +The +.I fd +routines will fail and set +.I errno +to ENOENT for in memory databases. +.PP +The +.I sync +routines may fail and set +.I errno +for any of the errors specified for the library routine +.IR fsync (2). +.SH "SEE ALSO" +.IR btree (3), +.IR hash (3), +.IR mpool (3), +.IR recno (3) +.sp +.IR "LIBTP: Portable, Modular Transactions for UNIX" , +Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. +.SH BUGS +The typedef DBT is a mnemonic for ``data base thang'', and was used +because noone could think of a reasonable name that wasn't already used. +.PP +The file descriptor interface is a kludge and will be deleted in a +future version of the interface. +.PP +None of the access methods provide any form of concurrent access, +locking, or transactions. diff --git a/man3/des_crypt.3 b/man3/des_crypt.3 new file mode 100644 index 000000000..02f9c5104 --- /dev/null +++ b/man3/des_crypt.3 @@ -0,0 +1,132 @@ +.\" @(#)des_crypt.3 2.1 88/08/11 4.0 RPCSRC; from 1.16 88/03/02 SMI; +.\" +.\" Taken from libc4 sources, which say: +.\" Copyright (C) 1993 Eric Young - can be distributed under GPL. +.\" +.\" However, the above header line suggests that this file in fact is +.\" Copyright Sun Microsystems, Inc (and is provided for unrestricted use, +.\" see other Sun RPC sources). +.\" +.TH DES_CRYPT 3 "6 October 1987" +.SH NAME +des_crypt, ecb_crypt, cbc_crypt, des_setparity, DES_FAILED \- fast DES encryption +.SH SYNOPSIS +.nf +.\" Sun version +.\" .B #include +.B #include +.LP +.BI "int ecb_crypt(char *" key ", char *" data ", unsigned " datalen , +.BI " unsigned " mode ); +.LP +.BI "int cbc_crypt(char *" key ", char *" data ", unsigned " datalen , +.BI " unsigned " mode ", char *" ivec ); +.LP +.BI "void des_setparity(char *" key ); +.LP +.BI "int DES_FAILED(int " status ); +.fi +.SH DESCRIPTION +.B ecb_crypt(\|) +and +.B cbc_crypt(\|) +implement the +.SM NBS +.SM DES +(Data Encryption Standard). +These routines are faster and more general purpose than +.BR crypt (3). +They also are able to utilize +.SM DES +hardware if it is available. +.B ecb_crypt(\|) +encrypts in +.SM ECB +(Electronic Code Book) +mode, which encrypts blocks of data independently. +.B cbc_crypt(\|) +encrypts in +.SM CBC +(Cipher Block Chaining) +mode, which chains together +successive blocks. +.SM CBC +mode protects against insertions, deletions and +substitutions of blocks. Also, regularities in the clear text will +not appear in the cipher text. +.LP +Here is how to use these routines. The first parameter, +.IR key , +is the 8-byte encryption key with parity. +To set the key's parity, which for +.SM DES +is in the low bit of each byte, use +.BR des_setparity . +The second parameter, +.IR data , +contains the data to be encrypted or decrypted. The +third parameter, +.IR datalen , +is the length in bytes of +.IR data , +which must be a multiple of 8. The fourth parameter, +.IR mode , +is formed by +.SM OR\s0'ing +together some things. For the encryption direction 'or' in either +.SM DES_ENCRYPT +or +.SM DES_DECRYPT\s0. +For software versus hardware +encryption, 'or' in either +.SM DES_HW +or +.SM DES_SW\s0. +If +.SM DES_HW +is specified, and there is no hardware, then the encryption is performed +in software and the routine returns +.SM DESERR_NOHWDEVICE\s0. +For +.BR cbc_crypt , +the parameter +.I ivec +is the the 8-byte initialization +vector for the chaining. It is updated to the next initialization +vector upon return. +.LP +.SH "SEE ALSO" +.BR des (1), +.BR crypt (3) +.\" added, aeb +and +.BR xcrypt (3) +.SH DIAGNOSTICS +.PD 0 +.TP 20 +.SM DESERR_NONE +No error. +.TP +.SM DESERR_NOHWDEVICE +Encryption succeeded, but done in software instead of the requested hardware. +.TP +.SM DESERR_HWERROR +An error occurred in the hardware or driver. +.TP +.SM DESERR_BADPARAM +Bad parameter to routine. +.PD +.LP +Given a result status +.IR stat , +the macro +.\" .SM DES_FAILED\c +.\" .BR ( stat ) +.BI DES_FAILED( stat ) +is false only for the first two statuses. + +.\" So far the Sun page +.\" Some additions - aeb +.SH AVAILABILITY +These routines are present in libc 4.6.27 and later, and in +glibc 2.1 and later. diff --git a/man3/des_setparity.3 b/man3/des_setparity.3 new file mode 100644 index 000000000..853c9cbdf --- /dev/null +++ b/man3/des_setparity.3 @@ -0,0 +1 @@ +.so man3/des_crypt.3 diff --git a/man3/difftime.3 b/man3/difftime.3 new file mode 100644 index 000000000..21f0090f1 --- /dev/null +++ b/man3/difftime.3 @@ -0,0 +1,61 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:48:17 1993 by Rik Faith (faith@cs.unc.edu) +.TH DIFFTIME 3 1993-07-02 "GNU" "Linux Programmer's Manual" +.SH NAME +difftime \- calculate time difference +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double difftime(time_t " time1 ", time_t " time0 ); +.fi +.SH DESCRIPTION +The \fBdifftime()\fP function returns the number of seconds elapsed +between time \fItime1\fP and time \fItime0\fP, represented as a double. +The two times are specified in calendar time, which represents the time +elapsed since the Epoch +(00:00:00 on January 1, 1970, Coordinated Universal Time (UTC)). +.SH "CONFORMING TO" +SVID 3, BSD 4.3, ISO 9899 +.SH NOTES +This function is required by ANSI C. +On a POSIX system, time_t is an arithmetic type, and one could just +define +.RS +.nf +#define difftime(t1,t0) (double)(t1 - t0) +.fi +.RE +when the possible overflow in the subtraction is not a concern. +.SH "SEE ALSO" +.BR date (1), +.BR gettimeofday (2), +.BR time (2), +.BR ctime (3), +.BR gmtime (3), +.BR localtime (3) diff --git a/man3/dirfd.3 b/man3/dirfd.3 new file mode 100644 index 000000000..34ff06399 --- /dev/null +++ b/man3/dirfd.3 @@ -0,0 +1,69 @@ +.\" Copyright (C) 2002 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH DIRFD 3 2002-01-05 "Linux 2.5" "Linux Programmer's Manual" +.SH NAME +dirfd \- get directory stream file descriptor +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int dirfd(DIR *" dir ); +.SH DESCRIPTION +The function +.B dirfd() +returns the file descriptor associated with the directory stream +.IR dir . +.LP +This descriptor is the one used internally by the directory stream. +As a result, it is only useful for functions which do not depend on +or alter the file position, such as +.BR fstat (2) +and +.BR fchdir (2). +It will be automatically closed when +.BR closedir (3) +is called. +.SH ERRORS +On error \-1 is returned. +.SH NOTES +The prototype for +.B dirfd +is only available if +.B _BSD_SOURCE +or +.B _SVID_SOURCE +is defined (either explicitly, or implicitly, by not defining +_POSIX_SOURCE or compiling with the -ansi flag). +.SH "CONFORMING TO" +This is a BSD extension, present in 4.3BSD-Reno, not in 4.2BSD. +Present in libc5 (since 5.1.2) and in glibc2. +.SH "SEE ALSO" +.BR open (2), +.BR closedir (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) diff --git a/man3/dirname.3 b/man3/dirname.3 new file mode 100644 index 000000000..9099c1ad7 --- /dev/null +++ b/man3/dirname.3 @@ -0,0 +1 @@ +.so man3/basename.3 diff --git a/man3/div.3 b/man3/div.3 new file mode 100644 index 000000000..41dbc4919 --- /dev/null +++ b/man3/div.3 @@ -0,0 +1,72 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-10, 2003-11-01 Walter Harms, aeb +.\" +.TH DIV 3 2003-11-01 "" "Linux Programmer's Manual" +.SH NAME +div, ldiv, lldiv, imaxdiv \- compute quotient and remainder of an integer division +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "div_t div(int " numerator ", int " denominator ); +.br +.BI "ldiv_t ldiv(long " numerator ", long " denominator ); +.br +.BI "lldiv_t lldiv(long long " numerator ", long long " denominator ); +.sp +.B #include +.sp +.BI "imaxdiv_t imaxdiv(intmax_t " numerator ", intmax_t " denominator ); +.fi +.SH DESCRIPTION +The \fBdiv()\fP function computes the value \fInumerator\fP/\fIdenominator\fP and +returns the quotient and remainder in a structure named \fIdiv_t\fP that contains +two integer members (in unspecified order) named \fIquot\fP and \fIrem\fP. +The quotient is rounded towards zero. +The result satisfies \fIquot\fP*\fIdenominator\fP+\fIrem\fP = \fInumerator\fP. +.LP +The \fBldiv()\fP and \fBlldiv()\fP and \fBimaxdiv()\fP functions do the same, +dividing numbers of the indicated type and returning the result in a structure +of the indicated name, in all cases with fields \fIquot\fP and \fIrem\fP +of the same type as the function arguments. +.SH "RETURN VALUE" +The \fIdiv_t\fP (etc.) structure. +.SH EXAMPLE +After +.nf + div_t q = div(-5, 3); +.fi +the values \fIq.quot\fP and \fIq.rem\fP are \-1 and \-2, respectively. +.SH "CONFORMING TO" +SVID 3, BSD 4.3, ISO 9899. +The functions lldiv() and imaxdiv() were added in ISO C99. +.SH "SEE ALSO" +.BR abs (3) diff --git a/man3/dl_iterate_phdr.3 b/man3/dl_iterate_phdr.3 new file mode 100644 index 000000000..17cb9c655 --- /dev/null +++ b/man3/dl_iterate_phdr.3 @@ -0,0 +1,194 @@ +.\" Copyright (c) 2003 by Michael Kerrisk (mtk16@ext.canterbury.ac.nz) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" +.TH DL_ITERATE_PHDR 3 "Linux 2.4.21" "Linux Programmer's Manual" +.SH NAME +dl_iterate_phdr \- walk through list of shared objects +.SH SYNOPSIS +.nf +#define _GNU_SOURCE +.B #include + +\fBint dl_iterate_phdr(\fP + \fBint (*\fPcallback\fB) \ +(struct dl_phdr_info *\fPinfo\fB,\fP + \fBsize_t\fP size\fB, void *\fPdata\fB),\fP + \fBvoid *\fPdata\fB);\fP +.fi +.SH DESCRIPTION +The +.B dl_iterate_phdr +function allows an application to inquire at run-time to find +out which shared objects it has loaded. + +The +.B dl_iterate_phdr +function walks through the list of an +application's shared objects and calls the function +.I callback +once for each object, +until either all shared objects have been processed or +.I callback +returns a non-zero value. + +Each call to +.I callback +receives three arguments: +.IR info , +which is a pointer to a structure containing information +about the shared object; +.IR size , +which is the size of the structure pointed to by +.IR info ; +and +.IR data , +which is a copy of whatever value was passed by the calling +program as the second argument (also named +.IR data ) +in the call to +.BR dl_iterate_phdr. + +The +.I info +argument is a structure of the following type: + +.nf + struct dl_phdr_info { + ElfW(Addr) dlpi_addr; /* Base address of object */ + const char *dlpi_name; /* (Null-terminated) name of + object + const ElfW(Phdr) *dlpi_phdr; /* Pointer to array of + ELF program headers + for this object */ + ElfW(Half) dlpi_phnum; /* # of items in 'dlpi_phdr' */ + }; +.fi + +(The +.I ElfW() +macro definition turns its argument into the name of an ELF data +type suitable for the hardware architecture. +For example, on a 32-bit platform, +ElfW(Addr) yields the data type name Elf32_Addr. +Further information on these types can be found in the +.IR " and " +header files.) + +The +.I dlpi_addr +field indicates the base address of the shared object +(i.e., the difference between the virtual memory address of +the shared object and the offset of that object in the file +from which it was loaded). +The +.I dlpi_name +field is a null-terminated string giving the pathname +from which the shared object was loaded. + +To understand the meaning of the +.I dlpi_phdr +and +.I dlpi_phnum +fields, we need to be aware that an ELF shared object consists +of a number of segments, each of which has a corresponding +program header describing the segment. +The +.I dlpi_phdr +field is a pointer to an array of the program headers for this +shared object. +The +.I dlpi_phnum +field indicates the size of this array. + +These program headers are structures of the following form: +.nf + + typedef struct + { + Elf32_Word p_type; /* Segment type */ + Elf32_Off p_offset; /* Segment file offset */ + Elf32_Addr p_vaddr; /* Segment virtual address */ + Elf32_Addr p_paddr; /* Segment physical address */ + Elf32_Word p_filesz; /* Segment size in file */ + Elf32_Word p_memsz; /* Segment size in memory */ + Elf32_Word p_flags; /* Segment flags */ + Elf32_Word p_align; /* Segment alignment */ + } Elf32_Phdr; +.fi + +Note that we can calculate the location of a particular program header, +.IR x , +in virtual memory memory using the formula: + +.nf + addr == info->dlpi_addr + info->dlpi_phdr[x].p_vaddr; +.fi +.SH EXAMPLE PROGRAM +The following program displays a list of pathnames of the +shared objects it has loaded. +For each shared object, the program lists the virtual addresses +at which the object's ELF segments are loaded. + +.nf +#define _GNU_SOURCE +#include +#include +#include + +static int +callback(struct dl_phdr_info *info, size_t size, void *data) +{ + int j; + + printf("name=%s (%d segments)\\n", info->dlpi_name, + info->dlpi_phnum); + + for (j = 0; j < info->dlpi_phnum; j++) + printf("\\t\\t header %2d: address=%10p\\n", j, + (void *) (info->dlpi_addr + info->dlpi_phdr[j].p_vaddr)); + return 0; +} + +int +main(int argc, char *argv[]) +{ + dl_iterate_phdr(callback, NULL); + + exit(EXIT_SUCCESS); +} +.fi +.SH RETURN VALUE +The +.B dl_iterate_phdr +function returns whatever value was returned by the last call to +.IR callback . +.SH "CONFORMING TO" +The +.B dl_iterate_phdr +function is Linux specific and should be avoided in portable applications. +.SH "SEE ALSO" +.BR ldd (1), +.BR objdump (1), +.BR readelf (1), +.BR dlopen (3), +.BR ld.so (8), +and the +.I "Executable and Linking Format Specification" +available at various locations online. diff --git a/man3/dladdr.3 b/man3/dladdr.3 new file mode 100644 index 000000000..15d096806 --- /dev/null +++ b/man3/dladdr.3 @@ -0,0 +1 @@ +.so man3/dlopen.3 diff --git a/man3/dlclose.3 b/man3/dlclose.3 new file mode 100644 index 000000000..15d096806 --- /dev/null +++ b/man3/dlclose.3 @@ -0,0 +1 @@ +.so man3/dlopen.3 diff --git a/man3/dlerror.3 b/man3/dlerror.3 new file mode 100644 index 000000000..15d096806 --- /dev/null +++ b/man3/dlerror.3 @@ -0,0 +1 @@ +.so man3/dlopen.3 diff --git a/man3/dlopen.3 b/man3/dlopen.3 new file mode 100644 index 000000000..308f9c972 --- /dev/null +++ b/man3/dlopen.3 @@ -0,0 +1,378 @@ +.\" -*- nroff -*- +.\" Copyright 1995 Yggdrasil Computing, Incorporated. +.\" written by Adam J. Richter (adam@yggdrasil.com), +.\" with typesetting help from Daniel Quinlan (quinlan@yggdrasil.com). +.\" Additional material copyright 2003, Michael Kerrisk +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, +.\" USA. +.\" +.\" Modified by David A. Wheeler 2000-11-28. +.\" Applied patch by Terran Melconian, aeb, 2001-12-14. +.\" Modified by Hacksaw 2003-03-13. +.\" Modified by Matt Domsch, 2003-04-09: _init and _fini obsolete +.\" Modified by Michael Kerrisk 2003-05-16. +.\" Modified by Walter Harms: dladdr, dlvsym +.\" +.TH DLOPEN 3 2003-11-17 "Linux" "Linux Programmer's Manual" +.SH NAME +dladdr, dlclose, dlerror, dlopen, dlsym, dlvsym \- programming interface to +dynamic linking loader +.SH SYNOPSIS +.B #include +.sp +.BI "void *dlopen(const char *" filename ", int " flag ); +.sp +.BI "char *dlerror(void);" +.sp +.BI "void *dlsym(void *" handle ", const char *" symbol ); +.sp +.BI "int dlclose(void *" handle ); +.SH DESCRIPTION +The four functions +.BR dlopen() , +.BR dlsym() , +.BR dlclose() , +.BR dlerror() +implement the interface to the dynamic linking loader. +.SS "dlerror" +The function +.B dlerror() +returns a human readable string describing the most recent error +that occurred from any of the dl routines (dlopen, dlsym or dlclose) +since the last call to +.BR dlerror() . +It returns NULL if no errors have occurred since initialization or since +it was last called. +.SS "dlopen" +The function +.B dlopen() +loads the dynamic library file named by the null-terminated +string +.I filename +and returns an opaque "handle" for the dynamic library. +If +.I filename +is NULL, then the returned handle is for the main program. +If +.I filename +contains a slash ("/"), then it is interpreted as a (relative +or absolute) pathname. +Otherwise, the dynamic linker searches for the library as follows +(see +.BR ld.so (8) +for further details): +.IP o +(ELF only) If the executable file for the calling program +contains a DT_RPATH tag, and does not contain a DT_RUNPATH tag, +then the directories listed in the DT_RPATH tag are searched. +.IP o +If the environment variable +.BR LD_LIBRARY_PATH +is defined to contain a colon-separated list of directories, +then these are searched. +(As a security measure this variable is ignored for set-UID and +set-GID programs.) +.IP o +(ELF only) If the executable file for the calling program +contains a DT_RUNPATH tag, then the directories listed in that tag +are searched. +.IP o +The cache file +.BR /etc/ld.so.cache +(maintained by +.BR ldconfig (8)) +is checked to see whether it contains an entry for +.IR filename . +.IP o +The directories +.B /lib +and +.B /usr/lib +are searched (in that order). +.PP +If the library has dependencies on other shared libraries, +then these are also automatically loaded by the dynamic linker +using the same rules. (This process may occur recursively, +if those libraries in turn have dependencies, and so on.) +.PP +The value of +.I flag +can be either +.B RTLD_LAZY +or +.BR RTLD_NOW . +When +.B RTLD_NOW +is specified, or the environment variable +.B LD_BIND_NOW +is set to a non-empty string, +all undefined symbols in the library are resolved before +.B dlopen() +returns. If this cannot be done, an error is returned. +Otherwise binding is lazy: symbol values are first resolved +when needed. +.PP +Optionally, +.B RTLD_GLOBAL +may be or'ed into +.IR flag , +in which case the external symbols defined in the library will be +made available for symbol resolution of subsequently loaded libraries. +(The converse of +.B RTLD_GLOBAL +is +.BR RTLD_LOCAL . +.\" that indicates that the symbols in this library should not be made +.\" available for resolution of symbols of subsequently loaded libraries. +This is the default.) +.PP +If +.I filename +is a NULL pointer, then the returned handle is for the main program. +When given to +.BR dlsym() , +this handle causes a search for a symbol in the main program, +followed by all shared libraries loaded at program startup, +and then all shared libraries loaded by +.BR dlopen() +with the flag +.B RTLD_GLOBAL. +.PP +External references in the library are resolved using the libraries +in that library's dependency list and any other libraries previously +opened with the +.B RTLD_GLOBAL +flag. +If the executable was linked with the flag "-rdynamic" +(or, synonymously, "--export-dynamic"), +then the global symbols in the executable will also be used +to resolve references in a dynamically loaded library. +.PP +If the same library is loaded again with +.BR dlopen() , +the same file handle is returned. The dl library maintains reference +counts for library handles, so a dynamic library is not +deallocated until +.B dlclose() +has been called on it as many times as +.B dlopen() +has succeeded on it. The +.B _init +routine, if present, is only called once. But a subsequent call with +.B RTLD_NOW +may force symbol resolution for a library earlier loaded with +.BR RTLD_LAZY . +.PP +If +.B dlopen() +fails for any reason, it returns NULL. +.SS "dlsym" +The function +.B dlsym() +takes a "handle" of a dynamic library returned by dlopen and the +NUL-terminated symbol name, returning the address where that symbol is +loaded into memory. If the symbol is not found, in the specified +library or any of the libraries that were automatically loaded by +.B dlopen() +when that library was loaded, +.B dlsym() +returns NULL. +(The search performed by +.B dlsym() +is breadth first through the dependency tree of these libraries.) +Since the value of the symbol could actually be NULL (so that a +NULL return from +.B dlsym() +need not indicate an error), the correct way to test for an error +is to call +.B dlerror() +to clear any old error conditions, then call +.BR dlsym() , +and then call +.B dlerror() +again, saving its return value into a variable, and check whether +this saved value is not NULL. +.PP +There are two special pseudo-handles, +.B RTLD_DEFAULT +and +.BR RTLD_NEXT . +The former will find the first occurrence of the desired symbol +using the default library search order. The latter +will find the next occurrence of a function in the search order +after the current library. This allows one to provide a wrapper +around a function in another shared library. +.SS "dlclose" +The function +.B dlclose() +decrements the reference count on the dynamic library handle +.IR handle . +If the reference count drops to zero and no other loaded libraries use +symbols in it, then the dynamic library is unloaded. +.LP +The function +.B dlclose() +returns 0 on success, and non-zero on error. +.SS "The obsolete symbols _init and _fini" +The linker recognizes special symbols +.B _init +and +.BR _fini . +If a dynamic library exports a routine named +.BR _init , +then that code is executed after the loading, before +.B dlopen() +returns. If the dynamic library exports a routine named +.BR _fini , +then that routine is called just before the library is unloaded. +In case you need to avoid linking against the system startup files, +this can be done by giving gcc the "-nostartfiles" parameter on +the command line. +.LP +Using these routines, or the gcc +.B \-nostartupfiles +or +.B \-nostdlib +options, is not recommended. Their use may result in undesired behavior, +since the constructor/destructor routines will not be executed +(unless special measures are taken). +.\" void _init(void) __attribute__((constructor)); +.\" void _fini(void) __attribute__((destructor)); +.LP +Instead, libraries should export routines using the +.BR __attribute__((constructor)) +and +.BR __attribute__((destructor)) +function attributes. See the gcc info pages for information on these. +Constructor routines are executed before +.B dlopen +returns, and destructor routines are executed before +.B dlclose +returns. +.SH "GNU EXTENSIONS" +Glibc adds two functions not described by POSIX, with prototypes +.sp +.nf +.B #define GNU_SOURCE +.B #include +.sp +.BI "int dladdr(void *" addr ", Dl_info *" info ); +.sp +.BI "void *dlvsym(void *" handle ", char *" symbol ", char *" version ); +.fi +.PP +The function +.B dladdr() +takes a function pointer and tries to resolve name +and file where it is located. Information is stored in the +Dl_info structure: +.sp +.nf +typedef struct { + const char *dli_fname;/* File name of defining object */ + void *dli_fbase; /* Load address of that object */ + const char *dli_sname;/* Name of nearest lower symbol */ + void *dli_saddr; /* Exact value of nearest symbol */ +} Dl_info; +.fi +.sp +.B dladdr() +returns 0 on error, and non-zero on success. +.PP +The function +.B dlvsym() +does the same as +.B dlsym() +but takes a version string as additional argument. + +.SH EXAMPLE +.B Load the math library, and print the cosine of 2.0: +.RS +.nf +.if t .ft CW +#include +#include + +int main(int argc, char **argv) { + void *handle; + double (*cosine)(double); + char *error; + + handle = dlopen ("libm.so", RTLD_LAZY); + if (!handle) { + fprintf (stderr, "%s\en", dlerror()); + exit(1); + } + + dlerror(); /* Clear any existing error */ +.\" This is the (somewhat ugly) SUSv3 TC1 fix for +.\" the dlsym() typecasting problem + *(void **) (&cosine) = dlsym(handle, "cos"); + if ((error = dlerror()) != NULL) { + fprintf (stderr, "%s\en", error); + exit(1); + } + + printf ("%f\en", (*cosine)(2.0)); + dlclose(handle); + return 0; +} +.if t .ft P +.fi +.RE +.PP +If this program were in a file named "foo.c", you would build the program +with the following command: +.RS +.LP +gcc -rdynamic -o foo foo.c -ldl +.RE +.PP +Libraries exporting _init() and _fini() will want to be compiled as +follows, using bar.c as the example name: +.RS +.LP +gcc -shared -nostartfiles -o bar bar.c +.RE +.SH NOTES +The symbols RTLD_DEFAULT and RTLD_NEXT are defined by +.I +only when _GNU_SOURCE was defined before including it. +.\" .LP +.\" The string returned by +.\" .B dlerror() +.\" should not be modified. Some systems give the prototype as +.\" .sp +.\" .in +5 +.\" .B "const char *dlerror(void);" +.\" .in +.SH HISTORY +The dlopen interface standard comes from SunOS. That system also has +dladdr, but not dlvsym. +.SH "CONFORMING TO" +POSIX 1003.1-2003 describes dlclose, dlerror, dlopen, dlsym. +.SH "SEE ALSO" +.BR ld (1), +.BR ldd (1), +.BR dl_iterate_phdr (3), +.BR ld.so (8), +.BR ldconfig (8), +ld.so info pages, gcc info pages, ld info pages diff --git a/man3/dlsym.3 b/man3/dlsym.3 new file mode 100644 index 000000000..15d096806 --- /dev/null +++ b/man3/dlsym.3 @@ -0,0 +1 @@ +.so man3/dlopen.3 diff --git a/man3/dlvsym.3 b/man3/dlvsym.3 new file mode 100644 index 000000000..15d096806 --- /dev/null +++ b/man3/dlvsym.3 @@ -0,0 +1 @@ +.so man3/dlopen.3 diff --git a/man3/dn_comp.3 b/man3/dn_comp.3 new file mode 100644 index 000000000..87a6d0e83 --- /dev/null +++ b/man3/dn_comp.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/dn_expand.3 b/man3/dn_expand.3 new file mode 100644 index 000000000..87a6d0e83 --- /dev/null +++ b/man3/dn_expand.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/dprintf.3 b/man3/dprintf.3 new file mode 100644 index 000000000..f816ad52f --- /dev/null +++ b/man3/dprintf.3 @@ -0,0 +1,72 @@ +.\" Copyright (C) 2001 Andries Brouwer +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Text fragments inspired by Martin Schulze . +.\" +.TH DPRINTF 3 2001-12-18 "GNU" "Linux Programmer's Manual" +.SH NAME +dprintf, vdprintf \- print to a file descriptor +.SH SYNOPSIS +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "int dprintf(int " fd ", const char *" format ", ...);" +.sp +.BI "int vdprintf(int " fd ", const char *" format ", va_list " ap ); +.SH DESCRIPTION +The functions +.B dprintf +and +.B vdprintf +(as found in the glibc2 library) are exact analogues of +.B fprintf +and +.BR vfprintf , +except that they output to a file descriptor +.I fd +instead of to a given stream. +.SH NOTES +These functions are GNU extensions, not in C or POSIX. +Clearly, the names were badly chosen. +Many systems (like MacOS) have incompatible functions called +.IR dprintf , +usually some debugging version of +.IR printf , +perhaps with a prototype like + +.BI "void dprintf (int level, const char *" format ", ...);" + +where the first parameter is a debugging level (and output is to +.IR stderr ). +Moreover, +.B dprintf +(or +.BR DPRINTF ) +is also a popular macro name for a debugging printf. +So, probably, it is better to avoid this function in programs +intended to be portable. + +A better name would have been +.IR fdprintf . +.SH "SEE ALSO" +.BR printf (3) diff --git a/man3/drand48.3 b/man3/drand48.3 new file mode 100644 index 000000000..f4c7590b4 --- /dev/null +++ b/man3/drand48.3 @@ -0,0 +1,130 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:46:03 1993 by Rik Faith (faith@cs.unc.edu) +.TH DRAND48 3 1993-07-02 "" "Linux Programmer's Manual" +.SH NAME +drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, +lcong48 \- generate uniformly distributed pseudo-random numbers +.SH SYNOPSIS +.nf +.B #include +.sp +.B double drand48(void); +.sp +.BI "double erand48(unsigned short " xsubi [3]); +.sp +.B long int lrand48(void); +.sp +.BI "long int nrand48(unsigned short " xsubi [3]); +.sp +.B long int mrand48(void); +.sp +.BI "long int jrand48(unsigned short " xsubi [3]); +.sp +.BI "void srand48(long int " seedval ); +.sp +.BI "unsigned short *seed48(unsigned short " seed16v [3]); +.sp +.BI "void lcong48(unsigned short " param [7]); +.fi +.SH DESCRIPTION +These functions generate pseudo-random numbers using the linear congruential +algorithm and 48-bit integer arithmetic. +.PP +The \fBdrand48()\fP and \fBerand48()\fP functions return non-negative +double-precision floating-point values uniformly distributed between +[0.0, 1.0). +.PP +The \fBlrand48()\fP and \fBnrand48()\fP functions return non-negative +long integers uniformly distributed between 0 and 2^31. +.PP +The \fBmrand48()\fP and \fBjrand48()\fP functions return signed long +integers uniformly distributed between \-2^31 and 2^31. +.PP +The \fBsrand48()\fP, \fBseed48()\fP and \fBlcong48()\fP functions are +initialization functions, one of which should be called before using +\fBdrand48()\fP, \fBlrand48()\fP or \fBmrand48()\fP. The functions +\fBerand48()\fP, \fBnrand48()\fP and \fBjrand48()\fP do not require +an initialization function to be called first. +.PP +All the functions work by generating a sequence of 48-bit integers, +\fIXi\fP, according to the linear congruential formula: +.sp +.nf +.RS +.B Xn+1 = (aXn + c) mod m, where n >= 0 +.RE +.fi +.sp +The parameter \fIm\fP = 2^48, hence 48-bit integer arithmetic is performed. +Unless \fBlcong48()\fP is called, \fIa\fP and \fIc\fP are given by: +.sp +.nf +.RS +.B a = 0x5DEECE66D +.B c = 0xB +.RE +.fi +.sp +The value returned by any of the functions \fBdrand48()\fP, \fBerand48()\fP, +\fBlrand48()\fP, \fBnrand48()\fP, \fBmrand48()\fP or \fBjrand48()\fP is +computed by first generating the next 48-bit \fIXi\fP in the sequence. +Then the appropriate number of bits, according to the type of data item to +be returned, is copied from the high-order bits of \fIXi\fP and transformed +into the returned value. +.PP +The functions \fBdrand48()\fP, \fBlrand48()\fP and \fBmrand48()\fP store +the last 48-bit \fIXi\fP generated in an internal buffer. The functions +\fBerand48()\fP, \fBnrand48()\fP and \fBjrand48()\fP require the calling +program to provide storage for the successive \fIXi\fP values in the array +argument \fIxsubi\fP. The functions are initialized by placing the initial +value of \fIXi\fP into the array before calling the function for the first +time. +.PP +The initializer function \fBsrand48()\fP sets the high order 32-bits of +\fIXi\fP to the argument \fIseedval\fP. The low order 16-bits are set +to the arbitrary value 0x330E. +.PP +The initializer function \fBseed48()\fP sets the value of \fIXi\fP to +the 48-bit value specified in the array argument \fIseed16v\fP. The +previous value of \fIXi\fP is copied into an internal buffer and a +pointer to this buffer is returned by \fBseed48()\fP. +.PP +The initialization function \fBlcong48()\fP allows the user to specify +initial values for \fIXi\fP, \fIa\fP and \fIc\fP. Array argument +elements \fIparam[0-2]\fP specify \fIXi\fP, \fIparam[3-5]\fP specify +\fIa\fP, and \fIparam[6]\fP specifies \fIc\fP. After \fBlcong48()\fP +has been called, a subsequent call to either \fBsrand48()\fP or +\fBseed48()\fP will restore the standard values of \fIa\fP and \fIc\fP. +.SH "CONFORMING TO" +SVID 3 +.SH NOTES +These functions are declared obsolete by SVID 3, which states that +rand(3) should be used instead. +.SH "SEE ALSO" +.BR rand (3), +.BR random (3) diff --git a/man3/drand48_r.3 b/man3/drand48_r.3 new file mode 100644 index 000000000..0b033aa32 --- /dev/null +++ b/man3/drand48_r.3 @@ -0,0 +1,82 @@ +.\" Copyright 2003 Walter Harms, 2004 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Created 2004-10-31. Text taken from a page by Walter Harms, 2003-09-08 +.\" +.TH DRAND48_R 3 2004-10-31 "GNU" "Linux Programmer's Manual" +.SH NAME +drand48_r, erand48_r, lrand48_r, nrand48_r, mrand48_r, jrand48_r, +srand48_r, seed48_r, lcong48_r +\- generate uniformly distributed pseudo-random numbers reentrantly +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int drand48_r(struct drand48_data *" buffer ", double *" result ); +.sp +.BI "int erand48_r(unsigned short " xsubi [3] "," +.br +.BI " struct drand48_data *"buffer ", double *" result ");" +.sp +.BI "int lrand48_r(struct drand48_data *" buffer ", long int *" result ); +.sp +.BI "int nrand48_r(unsigned short int " xsubi[3] "," +.br +.BI " struct drand48_data *"buffer ", long int *" result ");" +.sp +.BI "int mrand48_r(struct drand48_data *" buffer ",long int *" result ");" +.sp +.BI "int jrand48_r(unsigned short int " xsubi[3] "," +.br +.BI " struct drand48_data *" buffer ", long int *" result ");" +.sp +.BI "int srand48_r(long int " seedval ", struct drand48_data *" buffer ");" +.sp +.BI "int seed48_r(unsigned short int " seed16v[3] "," +.br +.BI " struct drand48_data *" buffer ");" +.sp +.BI "int lcong48_r(unsigned short int " param[7] "," +.br +.BI " struct drand48_data *" buffer ");" +.fi +.SH DESCRIPTION +These functions are the reentrant analogs of the functions described in +.BR drand48 (3). +Instead of modifying the global random generator state, they use +the supplied data +.IR buffer . + +Before the first use, this struct must be initialized, e.g. +by filling it with zeroes, or by calling one of the functions +.BR srand48_r() , +.BR seed48_r() , +or +.BR lcong48_r() . +.SH "RETURN VALUE" +The return value is 0. +.SH "CONFORMING TO" +These functions are GNU extensions and are not portable. +.SH "SEE ALSO" +.BR drand48 (3), +.BR rand (3), +.BR random (3) diff --git a/man3/drem.3 b/man3/drem.3 new file mode 100644 index 000000000..b7a5b23bf --- /dev/null +++ b/man3/drem.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man3/dremf.3 b/man3/dremf.3 new file mode 100644 index 000000000..b7a5b23bf --- /dev/null +++ b/man3/dremf.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man3/dreml.3 b/man3/dreml.3 new file mode 100644 index 000000000..b7a5b23bf --- /dev/null +++ b/man3/dreml.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man3/dysize.3 b/man3/dysize.3 new file mode 100644 index 000000000..a10e52399 --- /dev/null +++ b/man3/dysize.3 @@ -0,0 +1,52 @@ +.\" Copyright 2001 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" aeb: some corrections +.TH DYSIZE 3 "November 12, 2001" "GNU" "Linux Programmer's Manual" +.SH NAME +dysize \- get number of days for a given year +.SH SYNOPSIS +.sp +.BR "#define _BSD_SOURCE" " /* or: #define _SVID_SOURCE */ +.br +.BR "#include +.sp +.BI "int dysize(int " year ); +.sp +.SH DESCRIPTION +The function returns 365 for a normal year and 366 for a leap year. +The calculation for leap year is based on: +.sp +(year) %4 == 0 && ((year) %100 != 0 || (year) %400 == 0) +.sp +The formula is defined in the macro +.I __isleap(year) +also found in +.IR . +.SH "CONFORMING TO" +This function occurs in SunOS 4.x. +.SH NOTES +This is a compatibility function only. Don't use it in new programs. +The SCO version of this function had a year-2000 problem. +.SH "SEE ALSO" +.BR strftime (3), +.BR time (3) diff --git a/man3/ecb_crypt.3 b/man3/ecb_crypt.3 new file mode 100644 index 000000000..853c9cbdf --- /dev/null +++ b/man3/ecb_crypt.3 @@ -0,0 +1 @@ +.so man3/des_crypt.3 diff --git a/man3/ecvt.3 b/man3/ecvt.3 new file mode 100644 index 000000000..a7671fd93 --- /dev/null +++ b/man3/ecvt.3 @@ -0,0 +1,81 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:40:39 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Jun 25 12:10:47 1999 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH ECVT 3 1999-06-25 "" "Linux Programmer's Manual" +.SH NAME +ecvt, fcvt \- convert a floating-point number to a string +.SH SYNOPSIS +.B #include +.sp +.BI "char *ecvt(double " number ", int " ndigits ", int *" decpt , +.BI "int *" sign ); +.sp +.BI "char *fcvt(double " number ", int " ndigits ", int *" decpt , +.BI "int *" sign ); +.SH DESCRIPTION +The \fBecvt()\fP function converts \fInumber\fP to a null-terminated +string of \fIndigits\fP digits (where \fIndigits\fP is reduced to an +system-specific limit determined by the precision of a double), +and returns a pointer to the string. The high-order digit is nonzero, +unless +.I number +is zero. The low order digit is rounded. +The string itself does not contain a decimal point; however, +the position of the decimal point relative to the start of the string +is stored in *\fIdecpt\fP. A negative value for *\fIdecpt\fP means that +the decimal point is to the left of the start of the string. If the sign of +\fInumber\fP is negative, *\fIsign\fP is set to a non-zero value, otherwise +it's set to 0. If +.I number +is zero, it is unspecified whether *\fIdecpt\fP is 0 or 1. +.PP +The \fBfcvt()\fP function is identical to \fBecvt()\fP, except that +\fIndigits\fP specifies the number of digits after the decimal point. +.SH "RETURN VALUE" +Both the \fBecvt()\fP and \fBfcvt()\fP functions return a pointer to a +static string containing the ASCII representation of \fInumber\fP. +The static string is overwritten by each call to \fBecvt()\fP or +\fBfcvt()\fP. +.SH NOTES +These functions are obsolete. Instead, +.IR sprintf () +is recommended. +Linux libc4 and libc5 specified the type of +.I ndigits +as +.BR size_t . +Not all locales use a point as the radix character (`decimal point'). +.SH "CONFORMING TO" +SysVR2, XPG2 +.SH "SEE ALSO" +.BR ecvt_r (3), +.BR gcvt (3), +.BR qecvt (3), +.BR setlocale (3), +.BR sprintf (3) diff --git a/man3/ecvt_r.3 b/man3/ecvt_r.3 new file mode 100644 index 000000000..9d0527d28 --- /dev/null +++ b/man3/ecvt_r.3 @@ -0,0 +1,78 @@ +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.\" +.\" Corrected return types; from Fabian; 2004-10-05 +.\" +.TH ECVT_R 3 2004-10-05 "GNU" "Linux Programmer's Manual" +.SH NAME +ecvt_r, fcvt_r, qecvt_r, qfcvt_r \- convert a floating-point number to a string +.SH SYNOPSIS +.B #include +.sp +.BI "int ecvt_r(double " number ", int " ndigits ", int *" decpt , +.BI "int *" sign ", char *" buf ", size_t " len ); +.sp +.BI "int fcvt_r(double " number ", int " ndigits ", int *" decpt , +.BI "int *" sign ", char *" buf ", size_t " len ); +.sp +.BI "int qecvt_r(long double " number ", int " ndigits ", int *" decpt , +.BI "int *" sign ", char *" buf ", size_t " len ); +.sp +.BI "int qfcvt_r(long double " number ", int " ndigits ", int *" decpt , +.BI "int *" sign ", char *" buf ", size_t " len ); +.SH DESCRIPTION +The functions +.BR ecvt_r , +.BR fcvt_r , +.BR qecvt_r +and +.BR qfcvt_r +are identical to +.BR ecvt , +.BR fcvt , +.BR qecvt +and +.BR qfcvt , +respectively, except that they do not return their result in a static +buffer, but instead use the supplied +.I buf +of size +.IR len . +See +.BR ecvt (3) +and +.BR qecvt (3). +.SH "RETURN VALUE" +These functions return 0 on success, and \-1 otherwise. +.SH NOTES +These functions are obsolete. Instead, +.IR sprintf () +is recommended. +.SH "CONFORMING TO" +These functions are GNU extensions. +.SH "SEE ALSO" +.BR ecvt (3), +.BR qecvt (3), +.BR sprintf (3) diff --git a/man3/encrypt.3 b/man3/encrypt.3 new file mode 100644 index 000000000..a1cad967b --- /dev/null +++ b/man3/encrypt.3 @@ -0,0 +1,140 @@ +.\" Copyright 2000 Nicolás Lichtmaier +.\" Created 2000-07-22 00:52-0300 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" Modified 2002-07-23 19:21:35 CEST 2002 Walter Harms +.\" +.\" +.\" Modified 2003-04-04, aeb +.\" +.TH ENCRYPT 3 2003-04-04 "glibc2" "Cryptographic Functions" +.SH NAME +encrypt, setkey, encrypt_r, setkey_r \- encrypt 64-bit messages +.SH SYNOPSIS +.B #define _XOPEN_SOURCE +.br +.B #include +.sp +.BI "void encrypt(char " block "[64], int " edflag ); +.sp +.B #define _XOPEN_SOURCE +.br +.B #include +.sp +.BI "void setkey(const char *" key ); +.sp +.B #define _GNU_SOURCE +.br +.BI "#include " +.sp +.BI "void setkey_r (const char *" key ", struct crypt_data *" data ); +.br +.BI "void encrypt_r (char *" block ", int " edflag ", struct crypt_data *" data ); +.sp +Each of these requires linking with +.BR -lcrypt . +.SH DESCRIPTION +These functions encrypt and decrypt 64-bit messages. The +.B setkey() +function sets the key used by +.BR encrypt() . +The +.I key +parameter used here is an array of 64 bytes, each of which has +numerical value 1 or 0. The bytes key[n] where n=8*i-1 are ignored, +so that the effective key length is 56 bits. +.PP +The encrypt() function modifies the passed buffer, encoding if +.I edflag +is 0, and decoding if 1 is being passed. Like the key parameter also +.I block +is a bit vector representation of the actual value that is encoded. +The result is returned in that same vector. +.PP +These two functions are not reentrant, that is, the key data is +kept in static storage. The functions +.B setkey_r() +and +.B encrypt_r() +are the reentrant versions. They use the following +structure to hold the key data: +.RS +.nf +struct crypt_data { + char keysched[16 * 8]; + char sb0[32768]; + char sb1[32768]; + char sb2[32768]; + char sb3[32768]; + char crypt_3_buf[14]; + char current_salt[2]; + long int current_saltbits; + int direction, initialized; +}; +.fi +.RE +Before calling +.B setkey_r() +set +.I data->initialized +to zero. +.SH "RETURN VALUE" +These functions do not return any value. +.SH ERRORS +Set +.I errno +to zero before calling the above functions. +On success, it is unchanged. +.TP +.BR ENOSYS +The function is not provided. +(For example because of former USA export restrictions.) +.SH EXAMPLE +You need to link with libcrypt to compile this example with glibc2.2. +To do useful work the key[] and txt[] array must be filled with a +useful bit pattern. Note that the header unconditionally +gives the prototypes for setkey() and encrypt(). +.sp +.nf +#include + +main() { + char key[64]; /* bit pattern for key */ + char txt[64]; /* bit pattern for messages */ + setkey(key); + encrypt(txt, 0); /* encode */ + encrypt(txt, 1); /* decode */ +} +.fi +.SH "NOTE" +In glibc2.2 these functions use the DES algorithm. +.SH "CONFORMING TO" +The functions +.B encrypt() +and +.B setkey() +conform to SVID, SUSv2, and POSIX 1003.1-2001. +The functions +.B encrypt_r() +and +.B setkey_r() +are GNU extensions. +.SH "SEE ALSO" +.BR cbc_crypt (3), +.BR crypt (3), +.BR ecb_crypt (3), +.BR fcrypt (3) diff --git a/man3/endaliasent.3 b/man3/endaliasent.3 new file mode 100644 index 000000000..37dcf1914 --- /dev/null +++ b/man3/endaliasent.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man3/endfsent.3 b/man3/endfsent.3 new file mode 100644 index 000000000..1e6a3eb7e --- /dev/null +++ b/man3/endfsent.3 @@ -0,0 +1 @@ +.so man3/getfsent.3 diff --git a/man3/endgrent.3 b/man3/endgrent.3 new file mode 100644 index 000000000..bde736fff --- /dev/null +++ b/man3/endgrent.3 @@ -0,0 +1 @@ +.so man3/getgrent.3 diff --git a/man3/endhostent.3 b/man3/endhostent.3 new file mode 100644 index 000000000..7d0fb4b7c --- /dev/null +++ b/man3/endhostent.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/endmntent.3 b/man3/endmntent.3 new file mode 100644 index 000000000..3c2bb35c9 --- /dev/null +++ b/man3/endmntent.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man3/endnetent.3 b/man3/endnetent.3 new file mode 100644 index 000000000..70f5670dc --- /dev/null +++ b/man3/endnetent.3 @@ -0,0 +1 @@ +.so man3/getnetent.3 diff --git a/man3/endnetgrent.3 b/man3/endnetgrent.3 new file mode 100644 index 000000000..34268f941 --- /dev/null +++ b/man3/endnetgrent.3 @@ -0,0 +1 @@ +.so man3/setnetgrent.3 diff --git a/man3/endprotoent.3 b/man3/endprotoent.3 new file mode 100644 index 000000000..f8cb4bba2 --- /dev/null +++ b/man3/endprotoent.3 @@ -0,0 +1 @@ +.so man3/getprotoent.3 diff --git a/man3/endpwent.3 b/man3/endpwent.3 new file mode 100644 index 000000000..f2d121b80 --- /dev/null +++ b/man3/endpwent.3 @@ -0,0 +1 @@ +.so man3/getpwent.3 diff --git a/man3/endrpcent.3 b/man3/endrpcent.3 new file mode 100644 index 000000000..923085e2e --- /dev/null +++ b/man3/endrpcent.3 @@ -0,0 +1 @@ +.so man3/getrpcent.3 diff --git a/man3/endservent.3 b/man3/endservent.3 new file mode 100644 index 000000000..eaafb1c1e --- /dev/null +++ b/man3/endservent.3 @@ -0,0 +1 @@ +.so man3/getservent.3 diff --git a/man3/endspent.3 b/man3/endspent.3 new file mode 100644 index 000000000..142c5a5ca --- /dev/null +++ b/man3/endspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/endttyent.3 b/man3/endttyent.3 new file mode 100644 index 000000000..1cd11e3d8 --- /dev/null +++ b/man3/endttyent.3 @@ -0,0 +1 @@ +.so man3/getttyent.3 diff --git a/man3/endusershell.3 b/man3/endusershell.3 new file mode 100644 index 000000000..718ed12e9 --- /dev/null +++ b/man3/endusershell.3 @@ -0,0 +1 @@ +.so man3/getusershell.3 diff --git a/man3/endutent.3 b/man3/endutent.3 new file mode 100644 index 000000000..29c36b72a --- /dev/null +++ b/man3/endutent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/endutxent.3 b/man3/endutxent.3 new file mode 100644 index 000000000..29c36b72a --- /dev/null +++ b/man3/endutxent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/envz_add.3 b/man3/envz_add.3 new file mode 100644 index 000000000..a6d37763e --- /dev/null +++ b/man3/envz_add.3 @@ -0,0 +1,138 @@ +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" based on the description in glibc source and infopages +.\" +.\" Corrections and additions, aeb +.TH ENVZ_ADD 3 +.SH NAME +envz_add, envz_entry, envz_get, envz_merge, +envz_remove, envz_strip \- environment string support +.SH SYNOPSIS +.nf +.sp +.B "#include " +.sp +.BI "error_t" +.BI "envz_add(char **" envz ", size_t *" envz_len , +.ti 16n +.BI "const char *" name ", const char *" value ); +.sp +.BI "char *" +.BI "envz_entry(const char *" envz ", size_t *" envz_len ", const char *" name ); +.sp +.BI "char *" +.BI "envz_get(const char *" envz ", size_t *" envz_len ", const char *" name ); +.sp +.BI "error_t" +.BI "envz_merge(char **" envz ", size_t *" envz_len , +.ti 16n +.BI "const char *" envz2 ", size_t " envz2_len ", int " override ); +.sp +.BI "void" +.BI "envz_remove(char **" envz ", size_t *" envz_len ", const char *" name ); +.sp +.BI "void" +.BI "envz_strip(char **" envz ", size_t *" envz_len ); +.sp +.SH DESCRIPTION +These functions are glibc-specific. +.LP +An argz vector is a pointer to a character buffer together with a length, +see +.BR argz_add (3). +An envz vector is a special argz vector, namely one where the strings +have the form "name=value". Everything after the first '=' is considered +to be the value. If there is no '=', the value is taken to be NULL. +(While the value in case of a trailing '=' is the empty string "".) +.LP +These functions are for handling envz vectors. +.LP +.B envz_add() +adds the string +.RI \&" name = value \&" +(in case +.I value +is non-NULL) or +.RI \&" name \&" +(in case +.I value +is NULL) to the envz vector +.RI (* envz ,* envz_len ) +and updates +.RI * envz +and +.RI * envz_len . +If an entry with the same +.I name +existed, it is removed. +.LP +.B envz_entry() +looks for +.I name +in the envz vector +.RI ( envz , envz_len ) +and returns the entry if found, or NULL if not. +.LP +.B envz_get() +looks for +.I name +in the envz vector +.RI ( envz , envz_len ) +and returns the value if found, or NULL if not. +(Note that the value can also be NULL, namely when there is +an entry for +.I name +without '=' sign.) +.LP +.B envz_merge() +adds each entry in +.I envz2 +to +.RI * envz , +as if with +.BR envz_add() . +If +.I override +is true, then values in +.I envz2 +will supersede those with the same name in +.RI * envz , +otherwise not. +.LP +.B envz_remove() +removes the entry for +.I name +from +.RI (* envz ,* envz_len ) +if there was one. +.LP +.B envz_strip +removes all entries with value NULL. +.SH "RETURN VALUE" +All envz functions that do memory allocation have a return type of +\fIerror_t\fP, and return \fB0\fP for success, and \fBENOMEM\fP +if an allocation error occurs. +.SH EXAMPLE +.sp +.nf +#include +#include +int +main(int argc, char *argv[], char *envp[]) { + int i, e_len = 0; + char *str; + + for (i=0; envp[i] != NULL; i++) + e_len += strlen(envp[i]) + 1; + + str = envz_entry(*envp, e_len, "HOME"); + printf("%s\en", str); + str = envz_get(*envp, e_len, "HOME"); + printf("%s\en", str); + return 0; +} +.fi +.SH NOTES +These functions are a GNU extension. Handle with care. +.SH "SEE ALSO" +.BR argz (3) diff --git a/man3/envz_entry.3 b/man3/envz_entry.3 new file mode 100644 index 000000000..12e0737e2 --- /dev/null +++ b/man3/envz_entry.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man3/envz_get.3 b/man3/envz_get.3 new file mode 100644 index 000000000..12e0737e2 --- /dev/null +++ b/man3/envz_get.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man3/envz_merge.3 b/man3/envz_merge.3 new file mode 100644 index 000000000..12e0737e2 --- /dev/null +++ b/man3/envz_merge.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man3/envz_remove.3 b/man3/envz_remove.3 new file mode 100644 index 000000000..12e0737e2 --- /dev/null +++ b/man3/envz_remove.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man3/envz_strip.3 b/man3/envz_strip.3 new file mode 100644 index 000000000..12e0737e2 --- /dev/null +++ b/man3/envz_strip.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man3/erand48.3 b/man3/erand48.3 new file mode 100644 index 000000000..3133f7d62 --- /dev/null +++ b/man3/erand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man3/erand48_r.3 b/man3/erand48_r.3 new file mode 100644 index 000000000..81e9d8ef7 --- /dev/null +++ b/man3/erand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man3/erf.3 b/man3/erf.3 new file mode 100644 index 000000000..6f7e827e8 --- /dev/null +++ b/man3/erf.3 @@ -0,0 +1,64 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ERF 3 2002-07-27 "BSD" "Linux Programmer's Manual" +.SH NAME +erf, erff, erfl, erfc, erfcf, erfcl \- error function and complementary error function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double erf(double " x ); +.sp +.BI "float erff(float " x ); +.sp +.BI "long double erfl(long double " x ); +.sp +.BI "double erfc(double " x ); +.sp +.BI "float erfcf(float " x ); +.sp +.BI "long double erfcl(long double " x ); +.sp +.fi +Link with \-lm. +.SH DESCRIPTION +The \fBerf()\fP function returns the error function of \fIx\fP; defined +as +.TP +erf(x) = 2/sqrt(pi)* integral from 0 to x of exp(-t*t) dt +.PP +The \fBerfc()\fP function returns the complementary error function of +\fIx\fP, that is 1.0 - erf(x). +.SH "CONFORMING TO" +SVID 3, BSD 4.3, C99. +The float and long double variants are requirements of C99. +.SH "SEE ALSO" +.BR exp (3) diff --git a/man3/erfc.3 b/man3/erfc.3 new file mode 100644 index 000000000..fc5471fcb --- /dev/null +++ b/man3/erfc.3 @@ -0,0 +1 @@ +.so man3/erf.3 diff --git a/man3/erfcf.3 b/man3/erfcf.3 new file mode 100644 index 000000000..fc5471fcb --- /dev/null +++ b/man3/erfcf.3 @@ -0,0 +1 @@ +.so man3/erf.3 diff --git a/man3/erfcl.3 b/man3/erfcl.3 new file mode 100644 index 000000000..fc5471fcb --- /dev/null +++ b/man3/erfcl.3 @@ -0,0 +1 @@ +.so man3/erf.3 diff --git a/man3/erff.3 b/man3/erff.3 new file mode 100644 index 000000000..fc5471fcb --- /dev/null +++ b/man3/erff.3 @@ -0,0 +1 @@ +.so man3/erf.3 diff --git a/man3/erfl.3 b/man3/erfl.3 new file mode 100644 index 000000000..fc5471fcb --- /dev/null +++ b/man3/erfl.3 @@ -0,0 +1 @@ +.so man3/erf.3 diff --git a/man3/err.3 b/man3/err.3 new file mode 100644 index 000000000..f32a3ad0e --- /dev/null +++ b/man3/err.3 @@ -0,0 +1,156 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)err.3 8.1 (Berkeley) 6/9/93 +.\" $FreeBSD: src/lib/libc/gen/err.3,v 1.11.2.5 2001/08/17 15:42:32 ru Exp $ +.\" +.Dd March 6, 1999 +.Dt ERR 3 +.Os +.Sh NAME +.Nm err , +.Nm verr , +.Nm errx , +.Nm verrx , +.Nm warn , +.Nm vwarn , +.Nm warnx , +.Nm vwarnx , +.Nd formatted error messages +.Sh SYNOPSIS +.Fd #include +.Ft void +.Fn err "int eval" "const char *fmt" "..." +.Ft void +.Fn errx "int eval" "const char *fmt" "..." +.Ft void +.Fn warn "const char *fmt" "..." +.Ft void +.Fn warnx "const char *fmt" "..." +.Fd #include +.Ft void +.Fn verr "int eval" "const char *fmt" "va_list args" +.Ft void +.Fn verrx "int eval" "const char *fmt" "va_list args" +.Ft void +.Fn vwarn "const char *fmt" "va_list args" +.Ft void +.Fn vwarnx "const char *fmt" "va_list args" +.Sh DESCRIPTION +The +.Fn err +and +.Fn warn +family of functions display a formatted error message on the standard +error output. +In all cases, the last component of the program name, a colon character, +and a space are output. +If the +.Fa fmt +argument is not NULL, the +.Xr printf 3 +-like formatted error message is output. +The output is terminated by a newline character. +.Pp +The +.Fn err , +.Fn verr , +.Fn warn , +and +.Fn vwarn +functions append an error message obtained from +.Xr strerror 3 +based on a code or the global variable +.Va errno , +preceded by another colon and space unless the +.Fa fmt +argument is +.Dv NULL . +.Pp +The +.Fn err , +.Fn verr , +.Fn warn , +and +.Fn vwarn +functions use the global variable +.Va errno +to look up the error message. +.Pp +The +.Fn errx +and +.Fn warnx +functions do not append an error message. +.Pp +The +.Fn err , +.Fn verr , +.Fn errx , +and +.Fn verrx +functions do not return, but exit with the value of the argument +.Fa eval . +.Sh EXAMPLES +Display the current errno information string and exit: +.Bd -literal -offset indent +if ((p = malloc(size)) == NULL) + err(1, NULL); +if ((fd = open(file_name, O_RDONLY, 0)) == -1) + err(1, "%s", file_name); +.Ed +.Pp +Display an error message and exit: +.Bd -literal -offset indent +if (tm.tm_hour < START_TIME) + errx(1, "too early, wait until %s", start_time_string); +.Ed +.Pp +Warn of an error: +.Bd -literal -offset indent +if ((fd = open(raw_device, O_RDONLY, 0)) == -1) + warnx("%s: %s: trying the block device", + raw_device, strerror(errno)); +if ((fd = open(block_device, O_RDONLY, 0)) == -1) + err(1, "%s", block_device); +.Ed +.Sh SEE ALSO +.Xr exit 3 , +.Xr printf 3 , +.Xr perror 3 , +.Xr strerror 3 +.Sh HISTORY +The +.Fn err +and +.Fn warn +functions first appeared in +.Bx 4.4 . diff --git a/man3/errno.3 b/man3/errno.3 new file mode 100644 index 000000000..52ab4b8e3 --- /dev/null +++ b/man3/errno.3 @@ -0,0 +1,335 @@ +.\" Copyright (c) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 5 Oct 2002, Modified by Michael Kerrisk +.\" Updated for POSIX 1003.1 2001 +.\" +.TH ERRNO 3 2002-10-05 "" "Library functions" +.SH NAME +errno \- number of last error +.SH SYNOPSIS +.B #include +.sp +.BI "extern int " errno ; +.SH DESCRIPTION +The integer +.B errno +is set by system calls (and some library functions) to indicate +what went wrong. Its value is significant only when the call +returned an error (usually \-1), and a library function that does succeed +is allowed to change +.BR errno . + +Sometimes, when \-1 is also a legal return value one has to zero +.B errno +before the call in order to detect possible errors. + +\fBerrno\fR is defined by the ISO C standard to be a modifiable lvalue +of type \fBint\fR, and must not be explicitly declared; \fBerrno\fR +may be a macro. \fBerrno\fR is thread-local; setting it in one thread +does not affect its value in any other thread. + +Valid error numbers are all non-zero; \fBerrno\fR is never set to zero +by any library function. All the error names specified by POSIX.1 +must have distinct values. + +.\" FIXME EILSEQ is in C99. +POSIX.1 (2001 edition) lists the following symbolic error names. Of +these, \fBEDOM\fR and \fBERANGE\fR are in the ISO C standard. ISO C +Amendment 1 defines the additional error number \fBEILSEQ\fR for +coding errors in multibyte or wide characters. + +.TP +.B E2BIG +Arg list too long +.TP +.B EACCES +Permission denied +.TP +.B EADDRINUSE +Address in use +.TP +.B EADDRNOTAVAIL +Address not available +.TP +.B EAFNOSUPPORT +Address family not supported +.TP +.B EAGAIN +Resource temporarily unavailable +.TP +.B EALREADY +Connection already in progress +.TP +.B EBADF +Bad file descriptor +.TP +.B EBADMSG +Bad message +.TP +.B EBUSY +Resource busy +.TP +.B ECANCELED +Operation canceled +.TP +.B ECHILD +No child processes +.TP +.B ECONNABORTED +Connection aborted +.TP +.B ECONNREFUSED +Connection refused +.TP +.B ECONNRESET +Connection reset +.TP +.B EDEADLK +Resource deadlock avoided +.TP +.B EDESTADDRREQ +Destination address required +.TP +.B EDOM +Domain error +.TP +.B EDQUOT +Reserved +.TP +.B EEXIST +File exists +.TP +.B EFAULT +Bad address +.TP +.B EFBIG +File too large +.TP +.B EHOSTUNREACH +Host is unreachable +.TP +.B EIDRM +Identifier removed +.TP +.B EILSEQ +Illegal byte sequence +.TP +.B EINPROGRESS +Operation in progress +.TP +.B EINTR +Interrupted function call +.TP +.B EINVAL +Invalid argument +.TP +.B EIO +Input/output error +.TP +.B EISCONN +Socket is connected +.TP +.B EISDIR +Is a directory +.TP +.B ELOOP +Too many levels of symbolic links +.TP +.B EMFILE +Too many open files +.TP +.B EMLINK +Too many links +.TP +.B EMSGSIZE +Inappropriate message buffer length +.TP +.B EMULTIHOP +Reserved +.TP +.B ENAMETOOLONG +Filename too long +.TP +.B ENETDOWN +Network is down +.TP +.B ENETRESET +Connection aborted by network +.TP +.B ENETUNREACH +Network unreachable +.TP +.B ENFILE +Too many open files in system +.TP +.B ENOBUFS +No buffer space available +.\" ENODATA is part of XSR option +.TP +.B ENODATA +No message is available on the STREAM head read queue +.TP +.B ENODEV +No such device +.TP +.B ENOENT +No such file or directory +.TP +.B ENOEXEC +Exec format error +.TP +.B ENOLCK +No locks available +.TP +.B ENOLINK +Reserved +.TP +.B ENOMEM +Not enough space +.TP +.B ENOMSG +No message of the desired type +.TP +.B ENOPROTOOPT +Protocol not available +.TP +.B ENOSPC +No space left on device +.\" ENOSR is part of XSR option +.TP +.B ENOSR +No STREAM resources +.\" ENOSTR is part of XSR option +.TP +.B ENOSTR +Not a STREAM +.TP +.B ENOSYS +Function not implemented +.TP +.B ENOTCONN +The socket is not connected +.TP +.B ENOTDIR +Not a directory +.TP +.B ENOTEMPTY +Directory not empty +.TP +.B ENOTSOCK +Not a socket +.TP +.B ENOTSUP +Not supported +.TP +.B ENOTTY +Inappropriate I/O control operation +.TP +.B ENXIO +No such device or address +.TP +.B EOPNOTSUPP +Operation not supported on socket +.TP +.B EOVERFLOW +Value too large to be stored in data type +.TP +.B EPERM +Operation not permitted +.TP +.B EPIPE +Broken pipe +.TP +.B EPROTO +Protocol error +.TP +.B EPROTONOSUPPORT +Protocol not supported +.TP +.B EPROTOTYPE +Protocol wrong type for socket +.TP +.B ERANGE +Result too large +.TP +.B EROFS +Read-only file system +.TP +.B ESPIPE +Invalid seek +.TP +.B ESRCH +No such process +.TP +.B ESTALE +Reserved +.\" ETIME is part of XSR option +.TP +.B ETIME +STREAM ioctl() timeout +.TP +.B ETIMEDOUT +Operation timed out +.TP +.B ETXTBSY +Test file busy +.TP +.B EWOULDBLOCK +Operation would block (may be same value as +.BR EAGAIN ) +.TP +.B EXDEV +Improper link +.SH NOTE +A common mistake is to do +.RS +.nf + +if (somecall() == -1) { + printf("somecall() failed\en"); + if (errno == ...) { ... } +} + +.fi +.RE +where +.I errno +no longer needs to have the value it had upon return from +.IR somecall() . +If the value of +.I errno +should be preserved across a library call, it must be saved: +.RS +.nf + +if (somecall() == -1) { + int errsv = errno; + printf("somecall() failed\en"); + if (errsv == ...) { ... } +} + +.fi +.RE +.SH "SEE ALSO" +.BR perror (3), +.BR strerror (3) diff --git a/man3/errx.3 b/man3/errx.3 new file mode 100644 index 000000000..3ee2e497a --- /dev/null +++ b/man3/errx.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man3/ether_aton.3 b/man3/ether_aton.3 new file mode 100644 index 000000000..a74e3515c --- /dev/null +++ b/man3/ether_aton.3 @@ -0,0 +1,116 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 2002 Ian Redfern (redferni@logica.com) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" FreeBSD 4.4 man pages +.\" +.\" Minor additions, aeb, 2002-07-20 +.\" +.TH ETHER_ATON 3 2002-07-20 "BSD" "Linux Programmer's Manual" +.SH NAME +ether_aton, ether_ntoa, ether_ntohost, ether_hostton, ether_line, +ether_ntoa_r, ether_aton_r \- Ethernet address manipulation routines +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *" +.BI "ether_ntoa(const struct ether_addr *" addr ); +.sp +.BI "struct ether_addr *" +.BI "ether_aton(const char *" asc ); +.sp +.BI "int" +.BI "ether_ntohost(char *" hostname ", const struct ether_addr *" addr ); +.sp +.BI "int" +.BI "ether_hostton(const char *" hostname ", struct ether_addr *" addr ); +.sp +.BI "int" +.BI "ether_line(const char *" line ", struct ether_addr *" addr , +.BI " char *" hostname ); +.sp +/* GNU extensions */ +.br +.BI "char *" +.BI "ether_ntoa_r(const struct ether_addr *" addr ", char *" buf ); +.sp +.BI "struct ether_addr *" +.BI "ether_aton_r(const char *" asc ", struct ether_addr *" addr ); +.fi +.SH DESCRIPTION +\fBether_aton()\fP converts the 48-bit Ethernet host address \fIasc\fP +from the standard hex-digits-and-colons notation into binary data in +network byte order and returns a pointer to it in a statically +allocated buffer, which subsequent calls will +overwrite. \fBether_aton\fP returns NULL if the address is invalid. +.PP +The \fBether_ntoa()\fP function converts the Ethernet host address +\fIaddr\fP given in network byte order to a string in standard +hex-digits-and-colons notation, omitting leading zeroes. +The string is returned in a statically allocated buffer, +which subsequent calls will overwrite. +.PP +The \fBether_ntohost()\fP function maps an Ethernet address to the +corresponding hostname in +.B /etc/ethers +and returns non-zero if it cannot be found. +.PP +The \fBether_hostton()\fP function maps a hostname to the +corresponding Ethernet address in +.B /etc/ethers +and returns non-zero if it cannot be found. +.PP +The \fBether_line()\fP function parses a line in +.B /etc/ethers +format (ethernet address followed by whitespace followed by +hostname; '#' introduces a comment) and returns an address +and hostname pair, or non-zero if it cannot be parsed. +The buffer pointed to by +.I hostname +must be sufficiently long, e.g., have the same length as +.IR line . +.PP +The functions \fBether_ntoa_r\fP and \fBether_aton_r\fP are re-entrant +threadsafe versions of \fBether_ntoa\fP and \fBether_aton\fP +respectively, and do not use static buffers. +.PP +The structure \fIether_addr\fP is defined in \fInet/ethernet.h\fP as: +.sp +.RS +.nf +.ta 8n 16n +struct ether_addr { + u_int8_t ether_addr_octet[6]; +} +.ta +.fi +.RE +.SH BUGS +The glibc 2.2.5 implementation of ether_line() is broken. +.SH "CONFORMING TO" +BSD 4.3, SunOS +.SH "SEE ALSO" +.BR ethers (5) diff --git a/man3/ether_aton_r.3 b/man3/ether_aton_r.3 new file mode 100644 index 000000000..f88e044ab --- /dev/null +++ b/man3/ether_aton_r.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man3/ether_hostton.3 b/man3/ether_hostton.3 new file mode 100644 index 000000000..f88e044ab --- /dev/null +++ b/man3/ether_hostton.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man3/ether_line.3 b/man3/ether_line.3 new file mode 100644 index 000000000..f88e044ab --- /dev/null +++ b/man3/ether_line.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man3/ether_ntoa.3 b/man3/ether_ntoa.3 new file mode 100644 index 000000000..f88e044ab --- /dev/null +++ b/man3/ether_ntoa.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man3/ether_ntoa_r.3 b/man3/ether_ntoa_r.3 new file mode 100644 index 000000000..f88e044ab --- /dev/null +++ b/man3/ether_ntoa_r.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man3/ether_ntohost.3 b/man3/ether_ntohost.3 new file mode 100644 index 000000000..f88e044ab --- /dev/null +++ b/man3/ether_ntohost.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man3/exec.3 b/man3/exec.3 new file mode 100644 index 000000000..34fc38f14 --- /dev/null +++ b/man3/exec.3 @@ -0,0 +1,210 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)exec.3 6.4 (Berkeley) 4/19/91 +.\" +.\" Converted for Linux, Mon Nov 29 11:12:48 1993, faith@cs.unc.edu +.\" Updated more for Linux, Tue Jul 15 11:54:18 1997, pacman@cqc.com +.\" Modified, 24 Jun 2004, Michael Kerrisk +.\" Added note on casting NULL +.\" +.TH EXEC 3 1993-11-29 "BSD MANPAGE" "Linux Programmer's Manual" +.SH NAME +execl, execlp, execle, execv, execvp \- execute a file +.SH SYNOPSIS +.B #include +.sp +.B extern char **environ; +.sp +.BI "int execl(const char *" path ", const char *" arg ", ...);" +.br +.BI "int execlp(const char *" file ", const char *" arg ", ...);" +.br +.BI "int execle(const char *" path ", const char *" arg +.BI ", ..., char * const " envp "[]);" +.br +.BI "int execv(const char *" path ", char *const " argv "[]);" +.br +.BI "int execvp(const char *" file ", char *const " argv "[]);" +.SH DESCRIPTION +The +.B exec +family of functions replaces the current process image with a new process +image. The functions described in this manual page are front-ends for the +function +.BR execve (2). +(See the manual page for +.B execve +for detailed information about the replacement of the current process.) +.PP +The initial argument for these functions is the pathname of a file which is +to be executed. +.PP +The +.I "const char *arg" +and subsequent ellipses in the +.BR execl , +.BR execlp , +and +.B execle +functions can be thought of as +.IR arg0 , +.IR arg1 , +\&..., +.IR argn . +Together they describe a list of one or more pointers to null-terminated +strings that represent the argument list available to the executed program. +The first argument, by convention, should point to the file name associated +with the file being executed. The list of arguments +.I must +be terminated by a +.B NULL +pointer, and, since these are variadic functions, this pointer must be cast +.BR "(char *) NULL" . +.PP +The +.B execv +and +.B execvp +functions provide an array of pointers to null-terminated strings that +represent the argument list available to the new program. The first +argument, by convention, should point to the file name associated with the +file being executed. The array of pointers +.I must +be terminated by a +.B NULL +pointer. +.PP +The +.B execle +function also specifies the environment of the executed process by following +the +.B NULL +pointer that terminates the list of arguments in the parameter list or the +pointer to the argv array with an additional parameter. This additional +parameter is an array of pointers to null-terminated strings and +.I must +be terminated by a +.B NULL +pointer. The other functions take the environment for the new process +image from the external variable +.I environ +in the current process. +.PP +Some of these functions have special semantics. +.PP +The functions +.B execlp +and +.B execvp +will duplicate the actions of the shell in searching for an executable file +if the specified file name does not contain a slash (/) character. The +search path is the path specified in the environment by the +.B PATH +variable. If this variable isn't specified, the default path +``:/bin:/usr/bin'' is used. In addition, certain +errors are treated specially. +.PP +If permission is denied for a file (the attempted +.B execve +returned +.BR EACCES ), +these functions will continue searching the rest of the search path. If no +other file is found, however, they will return with the global variable +.I errno +set to +.BR EACCES . +.PP +If the header of a file isn't recognized (the attempted +.B execve +returned +.BR ENOEXEC ), +these functions will execute the shell with the path of the file as its +first argument. (If this attempt fails, no further searching is done.) +.SH "RETURN VALUE" +If any of the +.B exec +functions returns, an error will have occurred. The return value is \-1, +and the global variable +.I errno +will be set to indicate the error. +.SH FILES +.I /bin/sh +.SH ERRORS +All of these functions may fail and set +.I errno +for any of the errors specified for the library function +.BR execve (2). +.SH "SEE ALSO" +.BR sh (1), +.BR execve (2), +.BR fork (2), +.BR ptrace (2), +.BR environ (5) +.SH COMPATIBILITY +On some other systems the default path (used when the environment +does not contain the variable \fBPATH\fR) has the current working +directory listed after +.I /bin +and +.IR /usr/bin , +as an anti-Trojan-horse measure. Linux uses here the +traditional "current directory first" default path. +.PP +The behavior of +.B execlp +and +.B execvp +when errors occur while attempting to execute the file is historic +practice, but has not traditionally been documented and is not specified by +the POSIX standard. BSD (and possibly other systems) do an automatic +sleep and retry if ETXTBSY is encountered. Linux treats it as a hard +error and returns immediately. +.PP +Traditionally, the functions +.B execlp +and +.B execvp +ignored all errors except for the ones described above and +.B ENOMEM +and +.BR E2BIG , +upon which they returned. They now return if any error other than the ones +described above occurs. +.SH "CONFORMING TO" +.BR execl , +.BR execv , +.BR execle , +.B execlp +and +.B execvp +conform to +IEEE Std1003.1-88 (``POSIX.1''). diff --git a/man3/execl.3 b/man3/execl.3 new file mode 100644 index 000000000..4bf4872a6 --- /dev/null +++ b/man3/execl.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man3/execle.3 b/man3/execle.3 new file mode 100644 index 000000000..4bf4872a6 --- /dev/null +++ b/man3/execle.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man3/execlp.3 b/man3/execlp.3 new file mode 100644 index 000000000..4bf4872a6 --- /dev/null +++ b/man3/execlp.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man3/execv.3 b/man3/execv.3 new file mode 100644 index 000000000..4bf4872a6 --- /dev/null +++ b/man3/execv.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man3/execvp.3 b/man3/execvp.3 new file mode 100644 index 000000000..4bf4872a6 --- /dev/null +++ b/man3/execvp.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man3/exit.3 b/man3/exit.3 new file mode 100644 index 000000000..1d5e0dec4 --- /dev/null +++ b/man3/exit.3 @@ -0,0 +1,96 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH EXIT 3 2001-11-17 "" "Linux Programmer's Manual" +.SH NAME +exit \- cause normal program termination +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void exit(int " status ); +.fi +.SH DESCRIPTION +The \fBexit()\fP function causes normal program termination and the +the value of \fIstatus & 0377\fP is returned to the parent +(see +.BR wait (2)). +All functions registered with \fBatexit()\fP and \fBon_exit()\fP +are called in the reverse order of their registration, +and all open streams are flushed and closed. +Files created by \fItmpfile()\fP are removed. +.LP +The C standard specifies two defines \fIEXIT_SUCCESS\fP and \fIEXIT_FAILURE\fP +that may be passed to \fBexit()\fP to indicate successful or unsuccessful +termination, respectively. +.SH "RETURN VALUE" +The \fBexit()\fP function does not return. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899 (``ANSI C'') +.SH NOTES +During the exit processing, it is possible to register additional +functions with \fBatexit()\fP and \fBon_exit()\fP. +Always the last-registered function is removed from the chain +of registered functions, and invoked. +It is undefined what happens if during this processing +either \fBexit()\fP or \fBlongjmp()\fP is called. +.LP +The use of EXIT_SUCCESS and EXIT_FAILURE is slightly more portable +(to non-Unix environments) than that of 0 and some nonzero value +like 1 or \-1. In particular, VMS uses a different convention. +.LP +BSD has attempted to standardize exit codes - see the file +.IR . +.LP +After \fBexit()\fP, the exit status must be transmitted to the +parent process. There are three cases. If the parent has set +SA_NOCLDWAIT, or has set the SIGCHLD handler to SIG_IGN, the +status is discarded. If the parent was waiting on the child +it is notified of the exit status. In both cases the exiting +process dies immediately. If the parent has not indicated that +it is not interested in the exit status, but is not waiting, +the exiting process turns into a "zombie" process +(which is nothing but a container for the single byte representing +the exit status) so that the parent can learn the exit status when +it later calls one of the \fIwait()\fP functions. +.LP +If the implementation supports the SIGCHLD signal, this signal +is sent to the parent. If the parent has set SA_NOCLDWAIT, +it is undefined whether a SIGCHLD signal is sent. +.LP +If the process is a session leader and its controlling terminal +the controlling terminal of the session, then each process in +the foreground process group of this controlling terminal +is sent a SIGHUP signal, and the terminal is disassociated +from this session, allowing it to be acquired by a new controlling +process. +.LP +If the exit of the process causes a process group to become orphaned, +and if any member of the newly-orphaned process group is stopped, +then a SIGHUP signal followed by a SIGCONT signal will be +sent to each process in this process group. +.SH "SEE ALSO" +.BR _exit (2), +.BR wait (2), +.BR atexit (3), +.BR on_exit (3), +.BR tmpfile (3) diff --git a/man3/exp.3 b/man3/exp.3 new file mode 100644 index 000000000..09bd7ec9a --- /dev/null +++ b/man3/exp.3 @@ -0,0 +1,57 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH EXP 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +exp, expf, expl \- base-e exponential function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double exp(double " x ); +.sp +.BI "float expf(float " x ); +.sp +.BI "long double expl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBexp()\fP function returns the value of e (the base of natural +logarithms) raised to the power of \fIx\fP. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR cbrt (3), +.BR exp10 (3), +.BR exp2 (3), +.BR sqrt (3) diff --git a/man3/exp10.3 b/man3/exp10.3 new file mode 100644 index 000000000..7bea192de --- /dev/null +++ b/man3/exp10.3 @@ -0,0 +1,57 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH EXP10 3 2002-07-27 "GNU" "Linux Programmer's Manual" +.SH NAME +exp10, exp10f, exp10l \- base-10 exponential function +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "double exp10(double " x ); +.sp +.BI "float exp10f(float " x ); +.sp +.BI "long double exp10l(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBexp10()\fP function returns the value of 10 +raised to the power of \fIx\fP. +.SH "CONFORMING TO" +The function is a GNU extension. +.SH "SEE ALSO" +.BR cbrt (3), +.BR exp (3), +.BR exp2 (3), +.BR sqrt (3) diff --git a/man3/exp10f.3 b/man3/exp10f.3 new file mode 100644 index 000000000..705b75e97 --- /dev/null +++ b/man3/exp10f.3 @@ -0,0 +1 @@ +.so man3/exp10.3 diff --git a/man3/exp10l.3 b/man3/exp10l.3 new file mode 100644 index 000000000..705b75e97 --- /dev/null +++ b/man3/exp10l.3 @@ -0,0 +1 @@ +.so man3/exp10.3 diff --git a/man3/exp2.3 b/man3/exp2.3 new file mode 100644 index 000000000..cf7b85b37 --- /dev/null +++ b/man3/exp2.3 @@ -0,0 +1,57 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH EXP2 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +exp2, exp2f, exp2l \- base-2 exponential function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double exp2(double " x ); +.sp +.BI "float exp2f(float " x ); +.sp +.BI "long double exp2l(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBexp2()\fP function returns the value of 2 +raised to the power of \fIx\fP. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR cbrt (3), +.BR exp (3), +.BR exp10 (3), +.BR sqrt (3) diff --git a/man3/exp2f.3 b/man3/exp2f.3 new file mode 100644 index 000000000..b69beeace --- /dev/null +++ b/man3/exp2f.3 @@ -0,0 +1 @@ +.so man3/exp2.3 diff --git a/man3/exp2l.3 b/man3/exp2l.3 new file mode 100644 index 000000000..b69beeace --- /dev/null +++ b/man3/exp2l.3 @@ -0,0 +1 @@ +.so man3/exp2.3 diff --git a/man3/expf.3 b/man3/expf.3 new file mode 100644 index 000000000..4b1efda66 --- /dev/null +++ b/man3/expf.3 @@ -0,0 +1 @@ +.so man3/exp.3 diff --git a/man3/expl.3 b/man3/expl.3 new file mode 100644 index 000000000..4b1efda66 --- /dev/null +++ b/man3/expl.3 @@ -0,0 +1 @@ +.so man3/exp.3 diff --git a/man3/expm1.3 b/man3/expm1.3 new file mode 100644 index 000000000..75aef678f --- /dev/null +++ b/man3/expm1.3 @@ -0,0 +1,53 @@ +.\" Copyright 1995 Jim Van Zandt +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 2002-07-27 Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH EXPM1 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +expm1, expm1f, expm1l \- exponential minus 1 +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double expm1(double " x ); +.sp +.BI "float expm1f(float " x ); +.sp +.BI "long double expm1l(long double " x ); +.sp +.fi +Link with \-lm. +.SH DESCRIPTION +.BI expm1( x ) +returns a value equivalent to `exp (\fIx\fP) - 1'. It is +computed in a way that is accurate even if the value of \fIx\fP is near +zero--a case where `exp (\fIx\fP) - 1' would be inaccurate due to +subtraction of two numbers that are nearly equal. +.SH "CONFORMING TO" +BSD, C99. +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR exp (3), +.BR log (3), +.BR log1p (3) diff --git a/man3/expm1f.3 b/man3/expm1f.3 new file mode 100644 index 000000000..2c9e4eac1 --- /dev/null +++ b/man3/expm1f.3 @@ -0,0 +1 @@ +.so man3/expm1.3 diff --git a/man3/expm1l.3 b/man3/expm1l.3 new file mode 100644 index 000000000..2c9e4eac1 --- /dev/null +++ b/man3/expm1l.3 @@ -0,0 +1 @@ +.so man3/expm1.3 diff --git a/man3/fabs.3 b/man3/fabs.3 new file mode 100644 index 000000000..17ef66745 --- /dev/null +++ b/man3/fabs.3 @@ -0,0 +1,60 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:42:04 1993 by Rik Faith (faith@cs.unc.edu) +.\" Added fabsl, fabsf, aeb, 2001-06-07 +.\" +.TH FABS 3 2001-06-07 "" "Linux Programmer's Manual" +.SH NAME +fabs, fabsf, fabsl \- absolute value of floating-point number +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double fabs(double " x ); +.br +.BI "float fabsf(float " x ); +.br +.BI "long double fabsl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBfabs\fP functions return the absolute value of the floating-point +number \fIx\fP. +.SH ERRORS +No errors can occur. +.SH "CONFORMING TO" +The +.B fabs() +function conforms to SVID 3, POSIX, BSD 4.3, ISO 9899. +The other functions are from C99. +.SH "SEE ALSO" +.BR abs (3), +.BR ceil (3), +.BR floor (3), +.BR labs (3), +.BR rint (3) diff --git a/man3/fabsf.3 b/man3/fabsf.3 new file mode 100644 index 000000000..0426cf0f2 --- /dev/null +++ b/man3/fabsf.3 @@ -0,0 +1 @@ +.so man3/fabs.3 diff --git a/man3/fabsl.3 b/man3/fabsl.3 new file mode 100644 index 000000000..0426cf0f2 --- /dev/null +++ b/man3/fabsl.3 @@ -0,0 +1 @@ +.so man3/fabs.3 diff --git a/man3/fclose.3 b/man3/fclose.3 new file mode 100644 index 000000000..ab56455a4 --- /dev/null +++ b/man3/fclose.3 @@ -0,0 +1,104 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fclose.3 6.7 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:19:14 1993, faith@cs.unc.edu +.\" +.\" Modified 2000-07-22 by Nicolás Lichtmaier +.\" +.TH FCLOSE 3 1993-11-29 "BSD MANPAGE" "Linux Programmer's Manual" +.SH NAME +fclose \- close a stream +.SH SYNOPSIS +.B #include +.sp +.BI "int fclose(FILE *" fp ); +.SH DESCRIPTION +The +.B fclose +function will flush the stream pointed to by +.IR fp +(writing any buffered output data using +.BR fflush (3)) +and close the underlying file descriptor. +.SH "RETURN VALUE" +Upon successful completion 0 is returned. Otherwise, +.B EOF +is returned and the global variable +.I errno +is set to indicate the error. In either case any further access +(including another call to +.BR fclose ()) +to the stream results in undefined behaviour. +.SH ERRORS +.TP +.B EBADF +The filedescriptor underlying +.I fp +is not valid. +.\" This error cannot occur unless you are mixing ANSI C stdio operations and +.\" low-level file operations on the same stream. If you do get this error, +.\" you must have closed the stream's low-level file descriptor using +.\" something like close(fileno(fp)). +.PP +The +.B fclose +function may also fail and set +.I errno +for any of the errors specified for the routines +.BR close (2), +.BR write (2) +or +.BR fflush (3). +.SH NOTES +Note that +.B fclose +only flushes the user space buffers provided by the +C library. To ensure that the data is physically stored +on disk the kernel buffers must be flushed too, e.g. with +.BR sync (2) +or +.BR fsync (2). +.SH "CONFORMING TO" +The +.B fclose +function conforms to ANSI X3.159-1989 (``ANSI C''). +.SH "SEE ALSO" +.BR close (2), +.BR fcloseall (3), +.BR fflush (3), +.BR fopen (3), +.BR setbuf (3) diff --git a/man3/fcloseall.3 b/man3/fcloseall.3 new file mode 100644 index 000000000..5e06805f8 --- /dev/null +++ b/man3/fcloseall.3 @@ -0,0 +1,70 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fclose.3 6.7 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:19:14 1993, faith@cs.unc.edu +.\" Modified to be fcloseall(3) by Nicolás Lichtmaier Fri Apr 10 1998 +.\" +.TH FCLOSE 3 1998-04-10 "GNU" "Linux Programmer's Manual" +.SH NAME +fcloseall \- close all open streams +.SH SYNOPSIS +.B #define _GNU_SOURCE +.sp +.B #include +.sp +.B int fcloseall(void); +.SH DESCRIPTION +The +.B fcloseall +function dissociates all open streams +from its underlying file or set of functions. Any buffered output data is +written first, using +.BR fflush (3). +Note that the standard streams (stdin, stdout +and stderr) are also closed. +.SH "RETURN VALUE" +This function always returns 0. +.SH "SEE ALSO" +.BR close (2), +.BR fclose (3), +.BR fflush (3), +.BR fopen (3), +.BR setbuf (3) +.SH "CONFORMING TO" +The +.B fcloseall +function is a GNU extension. diff --git a/man3/fcvt.3 b/man3/fcvt.3 new file mode 100644 index 000000000..39d377098 --- /dev/null +++ b/man3/fcvt.3 @@ -0,0 +1 @@ +.so man3/ecvt.3 diff --git a/man3/fcvt_r.3 b/man3/fcvt_r.3 new file mode 100644 index 000000000..41ce9ee8a --- /dev/null +++ b/man3/fcvt_r.3 @@ -0,0 +1 @@ +.so man3/ecvt_r.3 diff --git a/man3/fdim.3 b/man3/fdim.3 new file mode 100644 index 000000000..bfef9d656 --- /dev/null +++ b/man3/fdim.3 @@ -0,0 +1,27 @@ +.\" Copyright 2003 Walter Harms, Andries Brouwer +.\" Distributed under GPL. +.\" +.TH FDIM 3 2003-07-24 "" "math routines" +.SH NAME +fdim, fdimf, fdiml \- positive difference +.SH SYNOPSIS +.B #include +.sp +.BI "double fdim(double " x ", double " y ); +.sp +.BI "float fdimf(float " x ", float " y ); +.sp +.BI "long double fdiml(long double " x ", long double " y ); +.sp +Link with \-lm. +.SH DESCRIPTION +These functions return max(\fIx\fP-\fIy\fP,0). +If +.I x +or +.I y +or both are NaN, Nan is returned. +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR fmax (3) diff --git a/man3/fdimf.3 b/man3/fdimf.3 new file mode 100644 index 000000000..a4058e45d --- /dev/null +++ b/man3/fdimf.3 @@ -0,0 +1 @@ +.so man3/fdim.3 diff --git a/man3/fdiml.3 b/man3/fdiml.3 new file mode 100644 index 000000000..a4058e45d --- /dev/null +++ b/man3/fdiml.3 @@ -0,0 +1 @@ +.so man3/fdim.3 diff --git a/man3/fdopen.3 b/man3/fdopen.3 new file mode 100644 index 000000000..9a4012491 --- /dev/null +++ b/man3/fdopen.3 @@ -0,0 +1 @@ +.so man3/fopen.3 diff --git a/man3/feclearexcept.3 b/man3/feclearexcept.3 new file mode 100644 index 000000000..47668e719 --- /dev/null +++ b/man3/feclearexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fedisableexcept.3 b/man3/fedisableexcept.3 new file mode 100644 index 000000000..47668e719 --- /dev/null +++ b/man3/fedisableexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/feenableexcept.3 b/man3/feenableexcept.3 new file mode 100644 index 000000000..47668e719 --- /dev/null +++ b/man3/feenableexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fegetenv.3 b/man3/fegetenv.3 new file mode 100644 index 000000000..47668e719 --- /dev/null +++ b/man3/fegetenv.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fegetexcept.3 b/man3/fegetexcept.3 new file mode 100644 index 000000000..47668e719 --- /dev/null +++ b/man3/fegetexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fegetexceptflag.3 b/man3/fegetexceptflag.3 new file mode 100644 index 000000000..47668e719 --- /dev/null +++ b/man3/fegetexceptflag.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fegetround.3 b/man3/fegetround.3 new file mode 100644 index 000000000..47668e719 --- /dev/null +++ b/man3/fegetround.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/feholdexcept.3 b/man3/feholdexcept.3 new file mode 100644 index 000000000..47668e719 --- /dev/null +++ b/man3/feholdexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fenv.3 b/man3/fenv.3 new file mode 100644 index 000000000..bf6a44d61 --- /dev/null +++ b/man3/fenv.3 @@ -0,0 +1,259 @@ +.\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 2000-08-14 added GNU additions from Andreas Jaeger +.\" 2000-12-05 some changes inspired by acahalan's remarks +.\" +.TH FENV 3 2000-08-12 "Linux Manpage" "Linux Programmer's Manual" +.SH NAME +feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag, +fetestexcept, fegetenv, fegetround, feholdexcept, fesetround, +fesetenv, feupdateenv - C99 floating point rounding and exception handling +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int feclearexcept(int " excepts ); +.br +.BI "int fegetexceptflag(fexcept_t *" flagp ", int " excepts ); +.br +.BI "int feraiseexcept(int " excepts ); +.br +.BI "int fesetexceptflag(const fexcept_t *" flagp ", int " excepts ); +.br +.BI "int fetestexcept(int " excepts ); +.sp +.B "int fegetround(void);" +.br +.BI "int fesetround(int " rounding_mode ); +.sp +.BI "int fegetenv(fenv_t *" envp ); +.br +.BI "int feholdexcept(fenv_t *" envp ); +.br +.BI "int fesetenv(const fenv_t *" envp ); +.br +.BI "int feupdateenv(const fenv_t *" envp ); +.fi +.SH DESCRIPTION +These eleven functions were defined in C99, and describe the handling +of floating point rounding and exceptions (overflow, zero-divide etc.). +.SS Exceptions +The DivideByZero exception occurs when an operation on finite numbers +produces infinity as exact answer. +.LP +The Overflow exception occurs when a result has to be represented as a +floating point number, but has (much) larger absolute value than the +largest (finite) floating point number that is representable. +.LP +The Underflow exception occurs when a result has to be represented as a +floating point number, but has smaller absolute value than the smallest +positive normalized floating point number (and would lose much accuracy +when represented as a denormalized number). +.LP +The Inexact exception occurs when the rounded result of an operation +is not equal to the infinite precision result. +It may occur whenever Overflow or Underflow occurs. +.LP +The Invalid exception occurs when there is no well-defined result +for an operation, as for 0/0 or infinity - infinity or sqrt(-1). +.SS "Exception handling" +Exceptions are represented in two ways: as a single bit +(exception present/absent), and these bits correspond in some +implementation-defined way with bit positions in an integer, +and also as an opaque structure that may contain more information +about the exception (perhaps the code address where it occurred). +.LP +Each of the macros +.BR FE_DIVBYZERO , +.BR FE_INEXACT , +.BR FE_INVALID , +.BR FE_OVERFLOW , +.BR FE_UNDERFLOW +is defined when the implementation supports handling +of the corresponding exception, and if so then +defines the corresponding bit(s), so that one can call +exception handling functions e.g. using the integer argument +.BR FE_OVERFLOW | FE_UNDERFLOW . +Other exceptions may be supported. The macro +.B FE_ALL_EXCEPT +is the bitwise OR of all bits corresponding to supported exceptions. +.PP +The +.B feclearexcept +function clears the supported exceptions represented by the bits +in its argument. +.LP +The +.B fegetexceptflag +function stores a representation of the state of the exception flags +represented by the argument +.I excepts +in the opaque object +.RI * flagp . +.LP +The +.B feraiseexcept +function raises the supported exceptions represented by the bits in +.IR excepts . +.LP +The +.B fesetexceptflag +function sets the complete status for the exceptions represented by +.I excepts +to the value +.RI * flagp . +This value must have been obtained by an earlier call of +.B fegetexceptflag +with a last argument that contained all bits in +.IR excepts . +.LP +The +.B fetestexcept +function returns a word in which the bits are set that were +set in the argument +.I excepts +and for which the corresponding exception is currently set. +.SS Rounding +Each of the macros +.BR FE_DOWNWARD , +.BR FE_TONEAREST , +.BR FE_TOWARDZERO , +.BR FE_UPWARD +is defined when the implementation supports getting and setting +the corresponding rounding direction. +.LP +The +.B fegetround +function returns the macro corresponding to the current +rounding mode. +.LP +The +.B fesetround +function sets the rounding mode as specified by its argument +and returns zero when it was successful. +.SS "Floating point environment" +The entire floating point environment, including +control modes and status flags, can be handled +as one opaque object, of type +.IR fenv_t . +The default environment is denoted by +.B FE_DFL_ENV +(of type +.IR "const fenv_t *" ). +This is the environment setup at program start and it is defined by +ISO C to have round to nearest, all exceptions cleared and a non-stop +(continue on exceptions) mode. +.LP +The +.B fegetenv +function saves the current floating point environment in the object +.RI * envp . +.LP +The +.B feholdexcept +function does the same, then clears all exception flags, +and sets a non-stop (continue on exceptions) mode, +if available. It returns zero when successful. +.LP +The +.B fesetenv +function restores the floating point environment from +the object +.RI * envp . +This object must be known to be valid, e.g., the result of a call to +.B fegetenv +or +.B feholdexcept +or equal to +.BR FE_DFL_ENV . +This call does not raise exceptions. +.LP +The +.B feupdateenv +function installs the floating-point environment represented by +the object +.RI * envp , +except that currently raised exceptions are not cleared. +After calling this function, the raised exceptions will be a bitwise OR +of those previously set with those in +.RI * envp . +As before, the object +.RI * envp +must be known to be valid. + +.SH "RETURN VALUE" +These functions return zero on success and non-zero if an error occurred. +.\" Earlier seven of these functions were listed as returning void. +.\" This was corrected in Corrigendum 1 (ISO/IEC 9899:1999/Cor.1:2001(E)) +.\" of the C99 Standard. + +.SH "GNU DETAILS" +If possible, the GNU C Library defines a macro +.B FE_NOMASK_ENV +which represents an environment where every exception raised causes a +trap to occur. You can test for this macro using +.BR #ifdef . +It is only defined if +.B _GNU_SOURCE +is defined. +The C99 standard does not define a way to set individual bits in the +floating point mask, e.g. to trap on specific flags. +glibc 2.2 supports the functions +.I feenableexcept +and +.I fedisableexcept +to set individual floating point traps, and +.I fegetexcept +to query the state. +.sp +.nf +.B "#define _GNU_SOURCE" +.br +.B "#include " +.sp +.BI "int feenableexcept (int " excepts ); +.br +.BI "int fedisableexcept (int " excepts ); +.br +.BI "int fegetexcept (void);" +.br +.fi +.LP +The +.B feenableexcept +and +.B fedisableexcept +functions enable (disable) traps for each of the exceptions represented by +.I excepts +and return the previous set of enabled exceptions when successful, +and \-1 otherwise. +The +.B fegetexcept +function returns the set of all currently enabled exceptions. + +.SH NOTES +Link with +.BR \-lm . + +.SH "CONFORMING TO" +IEC 60559 (IEC 559:1989), ANSI/IEEE 854, ISO C99 (ISO/IEC 9899:1999). diff --git a/man3/feof.3 b/man3/feof.3 new file mode 100644 index 000000000..3a95cca9f --- /dev/null +++ b/man3/feof.3 @@ -0,0 +1 @@ +.so man3/ferror.3 diff --git a/man3/feof_unlocked.3 b/man3/feof_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/feof_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/feraiseexcept.3 b/man3/feraiseexcept.3 new file mode 100644 index 000000000..47668e719 --- /dev/null +++ b/man3/feraiseexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/ferror.3 b/man3/ferror.3 new file mode 100644 index 000000000..48eb69e50 --- /dev/null +++ b/man3/ferror.3 @@ -0,0 +1,106 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ferror.3 6.8 (Berkeley) 6/29/91 +.\" +.\" +.\" Converted for Linux, Mon Nov 29 14:24:40 1993, faith@cs.unc.edu +.\" Added remark on EBADF for fileno, aeb, 2001-03-22 +.\" +.TH FERROR 3 2001-10-16 "" "Linux Programmer's Manual" +.SH NAME +clearerr, feof, ferror, fileno \- check and reset stream status +.SH SYNOPSIS +.B #include +.sp +.BI "void clearerr(FILE *" stream ); +.br +.BI "int feof(FILE *" stream ); +.br +.BI "int ferror(FILE *" stream ); +.br +.BI "int fileno(FILE *" stream ); +.SH DESCRIPTION +The function +.B clearerr +clears the end-of-file and error indicators for the stream pointed to by +.IR stream . +.PP +The function +.B feof +tests the end-of-file indicator for the stream pointed to by +.IR stream , +returning non-zero if it is set. The end-of-file indicator can only be +cleared by the function +.BR clearerr . +.PP +The function +.B ferror +tests the error indicator for the stream pointed to by +.IR stream , +returning non-zero if it is set. The error indicator can only be reset by +the +.B clearerr +function. +.PP +The function +.B fileno +examines the argument +.I stream +and returns its integer descriptor. +.PP +For non-locking counterparts, see +.BR unlocked_stdio (3). +.SH ERRORS +These functions should not fail and do not set the external variable +.IR errno . +(However, in case +.B fileno +detects that its argument is not a valid stream, it must +return \-1 and set +.I errno +to +.BR EBADF .) +.SH "CONFORMING TO" +The functions +.BR clearerr , +.BR feof , +and +.BR ferror +conform to X3.159-1989 (``ANSI C''). +.SH "SEE ALSO" +.BR open (2), +.BR stdio (3), +.BR unlocked_stdio (3) diff --git a/man3/ferror_unlocked.3 b/man3/ferror_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/ferror_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fesetenv.3 b/man3/fesetenv.3 new file mode 100644 index 000000000..47668e719 --- /dev/null +++ b/man3/fesetenv.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fesetexceptflag.3 b/man3/fesetexceptflag.3 new file mode 100644 index 000000000..47668e719 --- /dev/null +++ b/man3/fesetexceptflag.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fesetround.3 b/man3/fesetround.3 new file mode 100644 index 000000000..47668e719 --- /dev/null +++ b/man3/fesetround.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fetestexcept.3 b/man3/fetestexcept.3 new file mode 100644 index 000000000..47668e719 --- /dev/null +++ b/man3/fetestexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/feupdateenv.3 b/man3/feupdateenv.3 new file mode 100644 index 000000000..47668e719 --- /dev/null +++ b/man3/feupdateenv.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fflush.3 b/man3/fflush.3 new file mode 100644 index 000000000..dfb94ae8b --- /dev/null +++ b/man3/fflush.3 @@ -0,0 +1,107 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fflush.3 5.4 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" +.\" Modified 2000-07-22 by Nicolás Lichtmaier +.\" Modified 2001-10-16 by John Levon +.\" +.TH FFLUSH 3 1993-11-29 "BSD MANPAGE" "Linux Programmer's Manual" +.SH NAME +fflush \- flush a stream +.SH SYNOPSIS +.B #include +.sp +.BI "int fflush(FILE *" stream ); +.SH DESCRIPTION +The function +.B fflush +forces a write of all user-space buffered data for the given output or update +.I stream +via the stream's underlying write function. The open status of the stream +is unaffected. +.PP +If the +.I stream +argument is +.BR NULL , +.B fflush +flushes +.I all +open output streams. +.PP +For a non-locking counterpart, see +.BR unlocked_stdio (3). +.SH "RETURN VALUE" +Upon successful completion 0 is returned. Otherwise, +.B EOF +is returned and the global variable +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I Stream +is not an open stream, or is not open for writing. +.PP +The function +.B fflush +may also fail and set +.I errno +for any of the errors specified for the routine +.BR write (2). +.SH NOTES +Note that +.B fflush() +only flushes the user space buffers provided by the C library. +To ensure that the data is physically stored on disk +the kernel buffers must be flushed too, e.g. with +.BR sync (2) +or +.BR fsync (2). +.SH "CONFORMING TO" +The function +.BR fflush() +conforms to ANSI X3.159-1989 (``ANSI C''). +.SH "SEE ALSO" +.BR fsync (2), +.BR sync (2), +.BR write (2), +.BR fclose (3), +.BR fopen (3), +.BR setbuf (3), +.BR unlocked_stdio (3) diff --git a/man3/fflush_unlocked.3 b/man3/fflush_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/fflush_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/ffs.3 b/man3/ffs.3 new file mode 100644 index 000000000..12aaef1b0 --- /dev/null +++ b/man3/ffs.3 @@ -0,0 +1,63 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:39:35 1993 by Rik Faith (faith@cs.unc.edu) +.\" +.\" Modified 2003 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH FFS 3 2003-08-05 "GNU" "Linux Programmer's Manual" +.SH NAME +ffs \- find first bit set in a word +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int ffs(int " i ); +.sp +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "int ffsl(long int " i ); +.sp +.BI "int ffsll(long long int " i ); +.fi +.SH DESCRIPTION +The \fBffs()\fP function returns the position of the first +(least significant) bit set in the word \fIi\fP. +The least significant bit is position 1 and the +most significant position e.g. 32 or 64. +.BR +The functions \fBffsll()\fP and \fBffsl()\fP do the same but take +arguments of possibly different size. +.SH "RETURN VALUE" +These functions return the position of the first bit set, +or 0 if no bits are set. +.SH "CONFORMING TO" +BSD 4.3, POSIX 1003.1-2001. +.SH NOTES +BSD systems have a prototype in +.IR . diff --git a/man3/ffsl.3 b/man3/ffsl.3 new file mode 100644 index 000000000..23c4024a5 --- /dev/null +++ b/man3/ffsl.3 @@ -0,0 +1 @@ +.so man3/ffs.3 diff --git a/man3/ffsll.3 b/man3/ffsll.3 new file mode 100644 index 000000000..23c4024a5 --- /dev/null +++ b/man3/ffsll.3 @@ -0,0 +1 @@ +.so man3/ffs.3 diff --git a/man3/fgetc.3 b/man3/fgetc.3 new file mode 100644 index 000000000..4636db712 --- /dev/null +++ b/man3/fgetc.3 @@ -0,0 +1 @@ +.so man3/gets.3 diff --git a/man3/fgetc_unlocked.3 b/man3/fgetc_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/fgetc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fgetgrent.3 b/man3/fgetgrent.3 new file mode 100644 index 000000000..842489887 --- /dev/null +++ b/man3/fgetgrent.3 @@ -0,0 +1,74 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:38:44 1993 by Rik Faith (faith@cs.unc.edu) +.TH FGETGRENT 3 1993-04-04 "GNU" "Linux Programmer's Manual" +.SH NAME +fgetgrent \- get group file entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.sp +.BI "struct group *fgetgrent(FILE *" stream ); +.fi +.SH DESCRIPTION +The \fBfgetgrent()\fP function returns a pointer to a structure containing +the group information from the file \fIstream\fP. The first time it is called +it returns the first entry; thereafter, it returns successive entries. The +file \fIstream\fP must have the same format as \fI/etc/group\fP. +.PP +The \fIgroup\fP structure is defined in \fI\fP as follows: +.sp +.RS +.nf +.ta 8n 16n 32n +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group id */ + char **gr_mem; /* group members */ +}; +.ta +.fi +.RE +.SH "RETURN VALUE" +The \fBfgetgrent()\fP function returns the group information structure, +or NULL if there are no more entries or an error occurs. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to allocate group information structure. +.SH "CONFORMING TO" +SVID 3 +.SH "SEE ALSO" +.BR endgrent (3), +.BR fgetgrent_r (3), +.BR getgrent (3), +.BR getgrgid (3), +.BR getgrnam (3), +.BR setgrent (3) diff --git a/man3/fgetgrent_r.3 b/man3/fgetgrent_r.3 new file mode 100644 index 000000000..7c6dfe43a --- /dev/null +++ b/man3/fgetgrent_r.3 @@ -0,0 +1 @@ +.so man3/getgrent_r.3 diff --git a/man3/fgetpos.3 b/man3/fgetpos.3 new file mode 100644 index 000000000..a1487b5a8 --- /dev/null +++ b/man3/fgetpos.3 @@ -0,0 +1 @@ +.so man3/fseek.3 diff --git a/man3/fgetpwent.3 b/man3/fgetpwent.3 new file mode 100644 index 000000000..07db54c6a --- /dev/null +++ b/man3/fgetpwent.3 @@ -0,0 +1,88 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified Sat Jul 24 19:37:37 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 27 22:40:48 1996 by Martin Schulze (joey@linux.de) +.\" +.TH FGETPWENT 3 1996-05-17 "GNU" "Linux Programmer's Manual" +.SH NAME +fgetpwent \- get password file entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.sp +.BI "struct passwd *fgetpwent(FILE *" stream ); +.fi +.SH DESCRIPTION +The \fBfgetpwent()\fP function returns a pointer to a structure containing +the broken out fields of a line in the file \fIstream\fP. The first time +it is called it returns the first entry; thereafter, it returns successive +entries. The file \fIstream\fP must have the same format as +\fI/etc/passwd\fP. +.PP +The \fIpasswd\fP structure is defined in \fI\fP as follows: +.sp +.RS +.nf +.ta 8n 16n 32n +struct passwd { + char *pw_name; /* user name */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user id */ + gid_t pw_gid; /* group id */ + char *pw_gecos; /* real name */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.ta +.fi +.RE +.SH "RETURN VALUE" +The \fBfgetpwent()\fP function returns the passwd structure, or NULL if +there are no more entries or an error occurs. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to allocate passwd structure. +.SH FILES +.TP +.I /etc/passwd +password database file +.SH "CONFORMING TO" +SVID 3 +.SH "SEE ALSO" +.BR endpwent (3), +.BR fgetpwent_r (3), +.BR getpw (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR setpwent (3), +.BR passwd (5) diff --git a/man3/fgetpwent_r.3 b/man3/fgetpwent_r.3 new file mode 100644 index 000000000..b2393bb64 --- /dev/null +++ b/man3/fgetpwent_r.3 @@ -0,0 +1 @@ +.so man3/getpwent_r.3 diff --git a/man3/fgets.3 b/man3/fgets.3 new file mode 100644 index 000000000..4636db712 --- /dev/null +++ b/man3/fgets.3 @@ -0,0 +1 @@ +.so man3/gets.3 diff --git a/man3/fgets_unlocked.3 b/man3/fgets_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/fgets_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fgetspent.3 b/man3/fgetspent.3 new file mode 100644 index 000000000..142c5a5ca --- /dev/null +++ b/man3/fgetspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/fgetspent_r.3 b/man3/fgetspent_r.3 new file mode 100644 index 000000000..142c5a5ca --- /dev/null +++ b/man3/fgetspent_r.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/fgetwc.3 b/man3/fgetwc.3 new file mode 100644 index 000000000..6b3033689 --- /dev/null +++ b/man3/fgetwc.3 @@ -0,0 +1,63 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.\" Modified Tue Oct 16 23:18:40 BST 2001 by John Levon +.TH FGETWC 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +fgetwc, getwc \- read a wide character from a FILE stream +.SH SYNOPSIS +.nf +.B #include +.br +.B #include +.sp +.BI "wint_t fgetwc(FILE *" stream ); +.BI "wint_t getwc(FILE *" stream ); +.fi +.SH DESCRIPTION +The \fBfgetwc\fP function is the wide-character equivalent of the \fBfgetc\fP +function. It reads a wide character from \fIstream\fP and returns it. If +the end of stream is reached, or if \fIferror(stream)\fP becomes true, +it returns WEOF. If a wide character conversion error occurs, it sets +\fBerrno\fP to \fBEILSEQ\fP and returns WEOF. +.PP +The \fBgetwc\fP function or macro functions identically to \fBfgetwc\fP. +It may be implemented as a macro, and may evaluate its argument +more than once. There is no reason ever to use it. +.PP +For non-locking counterparts, see +.BR unlocked_stdio (3). +.SH "RETURN VALUE" +The \fBfgetwc\fP function returns the next wide-character from the stream, or +WEOF. +.SH ERRORS +Apart from the usual ones, there is +.TP +.B EILSEQ +The data obtained from the input stream does not +form a valid character. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH NOTES +The behaviour of \fBfgetwc\fP depends on the LC_CTYPE category of the +current locale. +.PP +In the absence of additional information passed to the fopen call, it is +reasonable to expect that \fBfgetwc\fP will actually read a multibyte sequence +from the stream and then convert it to a wide character. +.SH "SEE ALSO" +.BR fgetws (3), +.BR fputwc (3), +.BR ungetwc (3), +.BR unlocked_stdio (3) diff --git a/man3/fgetwc_unlocked.3 b/man3/fgetwc_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/fgetwc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fgetws.3 b/man3/fgetws.3 new file mode 100644 index 000000000..b2b0eed90 --- /dev/null +++ b/man3/fgetws.3 @@ -0,0 +1,53 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.\" Modified Tue Oct 16 23:18:40 BST 2001 by John Levon +.TH FGETWS 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +fgetws \- read a wide character string from a FILE stream +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wchar_t *fgetws(wchar_t *" ws ", int " n ", FILE *" stream ); +.fi +.SH DESCRIPTION +The \fBfgetws\fP function is the wide-character equivalent of the \fBfgets\fP +function. It reads a string of at most \fIn-1\fP wide characters into the +wide-character array pointed to by \fIws\fP, and adds a terminating L'\\0' +character. It stops reading wide characters after it has encountered and +stored a newline wide character. It also stops when end of stream is reached. +.PP +The programmer must ensure that there is room for at least \fIn\fP wide +characters at \fIws\fP. +.PP +For a non-locking counterpart, see +.BR unlocked_stdio (3). +.SH "RETURN VALUE" +The \fBfgetws\fP function, if successful, returns \fIws\fP. If end of stream +was already reached or if an error occurred, it returns NULL. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH NOTES +The behaviour of \fBfgetws\fP depends on the LC_CTYPE category of the +current locale. +.PP +In the absence of additional information passed to the fopen call, it is +reasonable to expect that \fBfgetws\fP will actually read a multibyte string +from the stream and then convert it to a wide character string. +.PP +This function is unreliable, because it does not permit to deal properly with +null wide characters that may be present in the input. +.SH "SEE ALSO" +.BR fgetwc (3), +.BR unlocked_stdio (3) diff --git a/man3/fgetws_unlocked.3 b/man3/fgetws_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/fgetws_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fileno.3 b/man3/fileno.3 new file mode 100644 index 000000000..3a95cca9f --- /dev/null +++ b/man3/fileno.3 @@ -0,0 +1 @@ +.so man3/ferror.3 diff --git a/man3/fileno_unlocked.3 b/man3/fileno_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/fileno_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/finite.3 b/man3/finite.3 new file mode 100644 index 000000000..da8de5ee8 --- /dev/null +++ b/man3/finite.3 @@ -0,0 +1,87 @@ +.\" Copyright 2004 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH FINITE 3 2004-10-31 "" "Linux Programmer's Manual" +.SH NAME +finite, finitef, finitel, isinf, isinff, isinfl, isnan, isnanf, isnanl \- +BSD floating point classification functions +.SH SYNOPSIS +.nf +#define _BSD_SOURCE +.br +.B #include +.sp +.BI "int finite(double " x ); +.br +.BI "int finitef(float " x ); +.br +.BI "int finitel(long double " x ); +.sp +.BI "int isinf(double " x ); +.br +.BI "int isinff(float " x ); +.br +.BI "int isinfl(long double " x ); +.sp +.BI "int isnan(double " x ); +.br +.BI "int isnanf(float " x ); +.br +.BI "int isnanl(long double " x ); +.fi +.SH DESCRIPTION +The +.B finite +functions return a non-zero value if \fIx\fP is neither infinite +nor a "not-a-number" (NaN) value, and 0 otherwise. + +The +.B isnan +functions return a non-zero value if \fIx\fP is a NaN value, +and 0 otherwise. + +The +.B isinf +functions return 1 if \fIx\fP is plus infinity, \-1 is \fIx\fP +is minus infinity, and 0 otherwise. + +.SH NOTE +Note that these functions are obsolete. C99 defines macros +isfinite(), isinf() and isnan() (for all types) replacing them. +Further note that the C99 isinf() has weaker guarantees on the return value. +See +.BR fpclassify (3). +.\" +.\" finite* not on HP-UX; they exist on Tru64. +.SH AVAILABILITY +On a glibc system, these functions are declared by +.I +when _BSD_SOURCE or _SVID_SOURCE or _GNU_SOURCE is defined. +The isnan() functions will also be declared when _XOPEN_SOURCE +is defined. +.SH HISTORY +The +.B finite +function occurs in BSD 4.3. +.\" see IEEE.3 in the BSD 4.3 manual +.SH "SEE ALSO" +.BR fpclassify (3) diff --git a/man3/finitef.3 b/man3/finitef.3 new file mode 100644 index 000000000..19f709b1c --- /dev/null +++ b/man3/finitef.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man3/finitel.3 b/man3/finitel.3 new file mode 100644 index 000000000..19f709b1c --- /dev/null +++ b/man3/finitel.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man3/flockfile.3 b/man3/flockfile.3 new file mode 100644 index 000000000..91c503eef --- /dev/null +++ b/man3/flockfile.3 @@ -0,0 +1,88 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH LOCKFILE 3 2001-10-18 "" "Linux Programmer's Manual" +.SH NAME +flockfile, ftrylockfile, funlockfile \- lock FILE for stdio +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void flockfile(FILE *" filehandle ); +.br +.BI "int ftrylockfile(FILE *" filehandle ); +.br +.BI "void funlockfile(FILE *" filehandle ); +.fi +.SH DESCRIPTION +The stdio functions are thread-safe. This is achieved by assigning +to each FILE object a lockcount and (if the lockcount is nonzero) +an owning thread. +For each library call, these functions wait until the FILE object +is no longer locked by a different thread, then lock it, do the +requested I/O, and unlock the object again. +.LP +(Note: this locking has nothing to do with the file locking done +by functions like +.BR flock (2) +and +.BR lockf (3).) +.LP +All this is invisible to the C-programmer, but there may be two +reasons to wish for more detailed control. On the one hand, maybe +a series of I/O actions by one thread belongs together, and should +not be interrupted by the I/O of some other thread. +On the other hand, maybe the locking overhead should be avoided +for greater efficiency. +.LP +To this end, a thread can explicitly lock the FILE object, +then do its series of I/O actions, then unlock. This prevents +other threads from coming in between. If the reason for doing +this was to achieve greater efficiency, one does the I/O with +the non-locking versions of the stdio functions: with +\fIgetc_unlocked\fP() and \fIputc_unlocked\fP() instead of +\fIgetc\fP() and \fIputc\fP(). +.LP +The \fBflockfile()\fP function waits for *\fIfilehandle\fP to be +no longer locked by a different thread, then makes the +current thread owner of *\fIfilehandle\fP, and increments +the lockcount. +.LP +The \fBfunlockfile()\fP function decrements the lock count. +.LP +The \fBftrylockfile()\fP function is a non-blocking version +of \fBflockfile()\fP. It does nothing in case some other thread +owns *\fIfilehandle\fP, and it obtains ownership and increments +the lockcount otherwise. +.SH "RETURN VALUE" +The \fBftrylockfile()\fP function returns zero for success +(the lock was obtained), and nonzero for failure. +.SH ERRORS +None. +.SH AVAILABILITY +These functions are available when _POSIX_THREAD_SAFE_FUNCTIONS +is defined. They are in libc since libc 5.1.1 and in glibc +since glibc 2.0. +.SH "CONFORMING TO" +POSIX.1 +.SH "SEE ALSO" +.BR unlocked_stdio (3) diff --git a/man3/floor.3 b/man3/floor.3 new file mode 100644 index 000000000..055e451cb --- /dev/null +++ b/man3/floor.3 @@ -0,0 +1,70 @@ +.\" Copyright 2001 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH FLOOR 3 2001-05-31 "" "Linux Programmer's Manual" +.SH NAME +floor, floorf, floorl \- largest integral value not greater than argument +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double floor(double " x ); +.br +.BI "float floorf(float " x ); +.br +.BI "long double floorl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +These functions round \fIx\fP down to the nearest integer. +.SH "RETURN VALUE" +The rounded integer value. If \fIx\fP is integral or infinite, +\fIx\fP itself is returned. +.SH ERRORS +No errors other than EDOM and ERANGE can occur. +If \fIx\fP is NaN, then NaN is returned and +.I errno +may be set to EDOM. +.SH NOTES +SUSv2 and POSIX 1003.1-2001 contain text about overflow (which might set +.I errno +to ERANGE, or raise an exception). +In practice, the result cannot overflow on any current machine, +so this error-handling stuff is just nonsense. +(More precisely, overflow can happen only when the maximum value +of the exponent is smaller than the number of mantissa bits. +For the IEEE-754 standard 32-bit and 64-bit floating point numbers +the maximum value of the exponent is 128 (resp. 1024), and the number +of mantissa bits is 24 (resp. 53).) +.SH "CONFORMING TO" +The +.B floor() +function conforms to SVID 3, POSIX, BSD 4.3, ISO 9899. +The other functions are from C99. +.SH "SEE ALSO" +.BR ceil (3), +.BR lrint (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3), +.BR trunc (3) diff --git a/man3/floorf.3 b/man3/floorf.3 new file mode 100644 index 000000000..1d8e79b22 --- /dev/null +++ b/man3/floorf.3 @@ -0,0 +1 @@ +.so man3/floor.3 diff --git a/man3/floorl.3 b/man3/floorl.3 new file mode 100644 index 000000000..1d8e79b22 --- /dev/null +++ b/man3/floorl.3 @@ -0,0 +1 @@ +.so man3/floor.3 diff --git a/man3/fma.3 b/man3/fma.3 new file mode 100644 index 000000000..84a87bb02 --- /dev/null +++ b/man3/fma.3 @@ -0,0 +1,30 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL, 2002-07-27 Walter Harms +.\" +.TH FMA 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +fma, fmaf, fmal \- floating-point multiply and add +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double fma(double " x ", double " y ", double " z ); +.sp +.BI "float fmaf(float " x ", float " y ", float " z ); +.sp +.BI "long double fmal(long double " x ", long double " y ", long double " z ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The +.B fma() +function computes +.IR x " * " y " + " z . +The result is rounded according to the +rounding mode determined by the value of FLT_ROUNDS. +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR remainder (3), +.BR remquo (3) diff --git a/man3/fmaf.3 b/man3/fmaf.3 new file mode 100644 index 000000000..e050da05f --- /dev/null +++ b/man3/fmaf.3 @@ -0,0 +1 @@ +.so man3/fma.3 diff --git a/man3/fmal.3 b/man3/fmal.3 new file mode 100644 index 000000000..e050da05f --- /dev/null +++ b/man3/fmal.3 @@ -0,0 +1 @@ +.so man3/fma.3 diff --git a/man3/fmax.3 b/man3/fmax.3 new file mode 100644 index 000000000..5705e2a58 --- /dev/null +++ b/man3/fmax.3 @@ -0,0 +1,22 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH FMAX 3 2002-07-28 "" "math routines" +.SH NAME +fmax, fmaxf, fmaxl \- find maximum value +.SH SYNOPSIS +.B #include +.sp +.BI "double fmax(double " x ", double " y ); +.sp +.BI "float fmaxf(float " x ", float " y ); +.sp +.BI "long double fmaxl(long double " x ", long double " y ); +.sp +Link with \-lm. +.SH DESCRIPTION +Find the larger value of x and y. +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR fmin (3) diff --git a/man3/fmaxf.3 b/man3/fmaxf.3 new file mode 100644 index 000000000..5f68a861e --- /dev/null +++ b/man3/fmaxf.3 @@ -0,0 +1 @@ +.so man3/fmax.3 diff --git a/man3/fmaxl.3 b/man3/fmaxl.3 new file mode 100644 index 000000000..5f68a861e --- /dev/null +++ b/man3/fmaxl.3 @@ -0,0 +1 @@ +.so man3/fmax.3 diff --git a/man3/fmin.3 b/man3/fmin.3 new file mode 100644 index 000000000..b82d3df77 --- /dev/null +++ b/man3/fmin.3 @@ -0,0 +1,22 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH FMIN 3 2002-07-28 "" "math routines" +.SH NAME +fmin, fminf, fminl \- find minimum value +.SH SYNOPSIS +.B #include +.sp +.BI "double fmin(double " x ", double " y ); +.sp +.BI "float fminf(float " x ", float " y ); +.sp +.BI "long double fminl(long double " x ", long double " y ); +.sp +Link with \-lm. +.SH DESCRIPTION +Find the lesser value of x and y. +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR fmax (3) diff --git a/man3/fminf.3 b/man3/fminf.3 new file mode 100644 index 000000000..a86d77d74 --- /dev/null +++ b/man3/fminf.3 @@ -0,0 +1 @@ +.so man3/fmin.3 diff --git a/man3/fminl.3 b/man3/fminl.3 new file mode 100644 index 000000000..a86d77d74 --- /dev/null +++ b/man3/fminl.3 @@ -0,0 +1 @@ +.so man3/fmin.3 diff --git a/man3/fmod.3 b/man3/fmod.3 new file mode 100644 index 000000000..006d8a36f --- /dev/null +++ b/man3/fmod.3 @@ -0,0 +1,61 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH FMOD 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +fmod, fmodf, fmodl \- floating-point remainder function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double fmod(double " x ", double " y ); +.sp +.BI "float fmodf(float " x ", float " y ); +.sp +.BI "long double fmodl(long double " x ", long double " y ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBfmod()\fP function computes the remainder of dividing \fIx\fP by +\fIy\fP. The return value is \fIx\fP - \fIn\fP * \fIy\fP, where \fIn\fP +is the quotient of \fIx\fP / \fIy\fP, rounded towards zero to an integer. +.SH "RETURN VALUE" +The \fBfmod()\fP function returns the remainder, unless \fIy\fP is zero, +when the function fails and \fIerrno\fP is set. +.SH ERRORS +.TP +.B EDOM +The denominator \fIy\fP is zero. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR remainder (3) diff --git a/man3/fmodf.3 b/man3/fmodf.3 new file mode 100644 index 000000000..d014cc043 --- /dev/null +++ b/man3/fmodf.3 @@ -0,0 +1 @@ +.so man3/fmod.3 diff --git a/man3/fmodl.3 b/man3/fmodl.3 new file mode 100644 index 000000000..d014cc043 --- /dev/null +++ b/man3/fmodl.3 @@ -0,0 +1 @@ +.so man3/fmod.3 diff --git a/man3/fmtmsg.3 b/man3/fmtmsg.3 new file mode 100644 index 000000000..e2e1e09b4 --- /dev/null +++ b/man3/fmtmsg.3 @@ -0,0 +1,272 @@ +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" adapted glibc info page +.\" +.\" This should run as 'Guru Meditation' (amiga joke :) +.\" The function is quite complex an deserves an example +.\" +.\" Polished, aeb, 2003-11-01 +.TH fmtmsg 3 2003-11-01 "" "Linux Programmer's Manual" +.SH NAME +fmtmsg \- print formatted error messages +.SH SYNOPSIS +.nf +.sp +.B #include +.sp +.BI "int fmtmsg(long " classification ", const char *" label , +.br +.BI " int " severity ", const char *" text , +.br +.BI " const char *" action ", const char *" tag ); +.sp +.fi +.SH DESCRIPTION +This function displays a message described by its parameters on the device(s) +specified in the +.I classification +parameter. For messages written to +.IR stderr , +the format depends on the +.B MSGVERB +environment variable. +.LP +The +.I label +parameter identifies the source of the message. The string must consist +of two colon separated parts where the first part has not more +than 10 and the second part not more than 14 characters. +.LP +The +.I text +parameter describes the condition of the error. +.LP +The +.I action +parameter describes possible steps to recover from the error. +If it is printed, it is prefixed by "TO FIX: ". +.LP +The +.I tag +parameter is a reference to the online documentation where more +information can be found. It should contain the +.I label +value and a unique identification number. +.SS "Dummy parameters" +Each of the parameters can have a dummy value. The dummy classification value +.B MM_NULLMC +(0L) does not specify any output, so nothing is printed. +The dummy severity value +.B NO_SEV +(0) says that no severity is supplied. +The values +.BR MM_NULLLBL , +.BR MM_NULLTXT , +.BR MM_NULLACT , +.BR MM_NULLTAG +are synonyms for ((char *) 0), the empty string, and +.B MM_NULLSEV +is a synonym for +.BR NO_SEV . +.SS "The classification parameter" +The +.I classification +parameter is the sum of values describing 4 types of information. +.br +.sp +The first value defines the output channel. +.TP 12n +.B MM_PRINT +Output to +.IR stderr . +.TP +.B MM_CONSOLE +Output to the system console. +.TP +.B "MM_PRINT | MM_CONSOLE" +Output to both. +.PP +The second value is the source of the error: +.TP 12n +.B MM_HARD +A hardware error occurred. +.TP +.B MM_FIRM +A firmware error occurred. +.TP +.B MM_SOFT +A software error occurred. +.PP +The third value encodes the detector of the problem: +.TP 12n +.B MM_APPL +It is detected by an application. +.TP +.B MM_UTIL +It is detected by a utility. +.TP +.B MM_OPSYS +It is detected by the operating system. +.PP +The fourth value shows the severity of the incident: +.TP 12n +.B MM_RECOVER +It is a recoverable error. +.TP +.B MM_NRECOV +It is a non-recoverable error. +.SS "The severity parameter" +The +.I severity +parameter can take one of the following values: +.TP 12n +.B MM_NOSEV +No severity is printed. +.TP +.B MM_HALT +This value is printed as HALT. +.TP +.B MM_ERROR +This value is printed as ERROR. +.TP +.B MM_WARNING +This value is printed as WARNING. +.TP +.B MM_INFO +This value is printed as INFO. +.PP +The numeric values are between 0 and 4. Using +.B addseverity() +or the environment variable +.B SEV_LEVEL +you can add more levels and strings to print. +.SH ENVIRONMENT +The environment variable +.B MSGVERB +("message verbosity") can be used to suppress parts of +the output to +.IR stderr . +(It does not influence output to the console.) +When this variable is defined, is non-NULL, and is a colon-separated +list of valid keywords, then only the parts of the message corresponding +to these keywords is printed. +Valid keywords are "label", "severity", "text", "action" and "tag". +.PP +The environment variable +.B SEV_LEVEL +can be used to introduce new severity levels. +By default, only the five severity levels described +above are available. Any other numeric value would make fmtmsg() print +nothing. +If the user puts +.B SEV_LEVEL +with a format like +.sp +.RS +SEV_LEVEL=[description[:description[:...]]] +.RE +.sp +in the environment of the process before the first call to fmtmsg(), +where each description is of the form +.sp +.RS +severity-keyword,level,printstring +.RE +.sp +then +.I fmtmsg() +will also accept the indicated values for the level (in addition to +the standard levels 0-4), and use the indicated printstring when +such a level occurs. +.LP +The severity-keyword part is not used by +.I fmtmsg() +but it has to be present. +The level part is a string representation of a number. +The numeric value must be a number greater than 4. +This value must be used in the severity parameter of +.I fmtmsg() +to select this class. It is not possible to overwrite +any of the predefined classes. The printstring +is the string printed when a message of this class is processed by +.IR fmtmsg() . +.SH "RETURN VALUES" +The function can return 4 values: +.TP 12n +.B MM_OK +Everything went smooth. +.TP +.B MM_NOTOK +Complete failure. +.TP +.B MM_NOMSG +Error writing to +.IR stderr . +.TP +.B MM_NOCON +Error writing to the console. +.SH "CONFORMING TO" +The functions +.I fmtmsg() +and +.IR addseverity() , +and environment variables +.B MSGVERB +and +.B SEV_LEVEL +come from System V (XPG4-UNIX). +The function +.I fmtmsg() +and the environment variable +.B MSGVERB +are described in POSIX 1003.1-2001. +.SH NOTES +System V and Unixware man pages tell us that these functions +have been replaced by "pfmt() and addsev()" or by "pfmt(), +vpfmt(), lfmt(), and vlfmt()", and will be removed later. +.SH EXAMPLE +.nf +#include +#include + +int main() { + long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER; + int err; + err = fmtmsg(class, "util-linux:mount", MM_ERROR, + "unknown mount option", "See mount(8).", "util-linux:mount:017"); + switch(err) { + case MM_OK: + break; + case MM_NOTOK: + printf("Nothing printed\en"); + break; + case MM_NOMSG: + printf("Nothing printed to stderr\en"); + break; + case MM_NOCON: + printf("No console output\en"); + break; + default: + printf("Unknown error from fmtmsg()\en"); + } + return 0; +} +.fi +.PP +The output should be: +.nf + util-linux:mount: ERROR: unknown mount option + TO FIX: See mount(8). util-linux:mount:017 +.fi +and after +.nf + MSGVERB=text:action; export MSGVERB +.fi +the output becomes: +.nf + unknown mount option + TO FIX: See mount(8). +.fi +.SH "SEE ALSO" +.BR addseverity (3), +.BR perror (3) diff --git a/man3/fnmatch.3 b/man3/fnmatch.3 new file mode 100644 index 000000000..07e577843 --- /dev/null +++ b/man3/fnmatch.3 @@ -0,0 +1,99 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 19:35:54 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Oct 16 00:16:29 2000 following Joseph S. Myers +.\" +.TH FNMATCH 3 2000-10-15 "GNU" "Linux Programmer's Manual" +.SH NAME +fnmatch \- match filename or pathname +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int fnmatch(const char *" "pattern" ", const char *" string ", int " flags ); +.fi +.SH DESCRIPTION +The +.B fnmatch() +function checks whether the +.I string +argument matches the +.I pattern +argument, which is a shell wildcard pattern. +.PP +The +.I flags +argument modifies the behaviour; it is the bitwise OR of zero or more +of the following flags: +.TP +.B FNM_NOESCAPE +If this flag is set, treat backslash as an ordinary character, +instead of an escape character. +.TP +.B FNM_PATHNAME +If this flag is set, match a slash in +.I string +only with a slash in +.I pattern +and not, for example, with a [] \- sequence containing a slash. +.TP +.B FNM_PERIOD +If this flag is set, a leading period in +.I string +has to be matched exactly by a period in +.IR pattern . +A period is considered to be leading if it is the first character in +.IR string , +or if both +.B FNM_PATHNAME +is set and the period immediately follows a slash. +.TP +.B FNM_FILE_NAME +This is a GNU synonym for \fBFNM_PATHNAME\fR. +.TP +.B FNM_LEADING_DIR +If this flag (a GNU extension) is set, the pattern is considered to be +matched if it matches an initial segment of +.I string +which is followed by a slash. This flag is mainly for the internal +use of glibc and is only implemented in certain cases. +.TP +.B FNM_CASEFOLD +If this flag (a GNU extension) is set, the pattern is matched +case-insensitively. +.SH "RETURN VALUE" +Zero if +.I string +matches +.IR pattern , +.B FNM_NOMATCH +if there is no match or another non-zero value if there is an error. +.SH "CONFORMING TO" +ISO/IEC 9945-2: 1993 (POSIX.2). The +.BR FNM_FILE_NAME ", " FNM_LEADING_DIR ", and " FNM_CASEFOLD +flags are GNU extensions. +.SH "SEE ALSO" +.BR sh (1), +.BR glob (3), +.BR scandir (3), +.BR glob (7) diff --git a/man3/fopen.3 b/man3/fopen.3 new file mode 100644 index 000000000..7ecf6695e --- /dev/null +++ b/man3/fopen.3 @@ -0,0 +1,235 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fopen.3 6.8 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" Modified, aeb, 960421, 970806 +.\" Modified, joey, aeb, 2002-01-03 +.\" +.TH FOPEN 3 2002-01-03 "BSD MANPAGE" "Linux Programmer's Manual" +.SH NAME +fopen, fdopen, freopen \- stream open functions +.SH SYNOPSIS +.B #include +.sp +.BI "FILE *fopen(const char *" path ", const char *" mode ); +.br +.BI "FILE *fdopen(int " fildes ", const char *" mode ); +.br +.BI "FILE *freopen(const char *" path ", const char *" mode ", FILE *" stream ); +.SH DESCRIPTION +The +.B fopen +function opens the file whose name is the string pointed to by +.I path +and associates a stream with it. +.PP +The argument +.I mode +points to a string beginning with one of the following sequences +(Additional characters may follow these sequences.): +.TP +.B r +Open text file for reading. The stream is positioned at the beginning of +the file. +.TP +.B r+ +Open for reading and writing. The stream is positioned at the beginning of +the file. +.TP +.B w +Truncate file to zero length or create text file for writing. The stream +is positioned at the beginning of the file. +.TP +.B w+ +Open for reading and writing. The file is created if it does not exist, +otherwise it is truncated. The stream is positioned at the beginning of +the file. +.TP +.B a +Open for appending (writing at end of file). The file is created +if it does not exist. The stream is positioned at the end of the file. +.TP +.B a+ +Open for reading and appending (writing at end of file). The file +is created if it does not exist. +The stream is positioned at the end of the file. +.PP +The +.I mode +string can also include the letter ``b'' either as a last character or as +a character between the characters in any of the two-character strings +described above. This is strictly for compatibility with ANSI X3.159-1989 +(``ANSI C'') and has no effect; the ``b'' is ignored on all POSIX +conforming systems, including Linux. +(Other systems may treat text files and binary files differently, +and adding the ``b'' may be a good idea if you do I/O to a binary +file and expect that your program may be ported to non-Unix +environments.) +.PP +Any created files will have mode +.BR S_IRUSR \&| S_IWUSR \&| S_IRGRP \&| S_IWGRP \&| S_IROTH \&| S_IWOTH +(0666), as modified by the process' umask value (see +.BR umask (2)). +.PP +Reads and writes may be intermixed on read/write streams in any order. +Note that ANSI C requires that a file positioning function intervene +between output and input, unless an input operation encounters end-of-file. +(If this condition is not met, then a read is allowed to return the +result of writes other than the most recent.) +Therefore it is good practice (and indeed sometimes necessary +under Linux) to put an +.B fseek +or +.B fgetpos +operation between write and read operations on such a stream. This +operation may be an apparent no-op (as in \fIfseek(..., 0L, +SEEK_CUR)\fR called for its synchronizing side effect. +.PP +Opening a file in append mode (\fBa\fR as the first character of +.IR mode ) +causes all subsequent write operations to this stream to occur +at end-of-file, as if preceded by an +.RS +fseek(stream,0,SEEK_END); +.RE +call. +.PP +The +.B fdopen +function associates a stream with the existing file descriptor, +.IR fildes . +The +.I mode +of the stream (one of the values "r", "r+", "w", "w+", "a", "a+") +must be compatible with the mode of the file descriptor. +The file position indicator of the new stream is set to that +belonging to +.IR fildes , +and the error and end-of-file indicators are cleared. +Modes "w" or "w+" do not cause truncation of the file. +The file descriptor is not dup'ed, and will be closed when +the stream created by +.B fdopen +is closed. +The result of applying +.B fdopen +to a shared memory object is undefined. +.PP +The +.B freopen +function opens the file whose name is the string pointed to by +.I path +and associates the stream pointed to by +.I stream +with it. The original stream (if it exists) is closed. The +.I mode +argument is used just as in the +.B fopen +function. The primary use of the +.B freopen +function is to change the file associated with a standard text stream +.IR "" ( stderr ", " stdin ", or " stdout ). +.SH "RETURN VALUE" +Upon successful completion +.BR fopen , +.B fdopen +and +.B freopen +return a +.B FILE +pointer. Otherwise, +.B NULL +is returned and the global variable +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The +.I mode +provided to +.BR fopen , +.BR fdopen , +or +.B freopen +was invalid. +.PP +The +.BR fopen , +.B fdopen +and +.B freopen +functions may also fail and set +.I errno +for any of the errors specified for the routine +.BR malloc (3). +.PP +The +.B fopen +function may also fail and set +.I errno +for any of the errors specified for the routine +.BR open (2). +.PP +The +.B fdopen +function may also fail and set +.I errno +for any of the errors specified for the routine +.BR fcntl (2). +.PP +The +.B freopen +function may also fail and set +.I errno +for any of the errors specified for the routines +.BR open (2), +.BR fclose (3) +and +.BR fflush (3). +.SH "CONFORMING TO" +The +.B fopen +and +.B freopen +functions conform to ANSI X3.159-1989 (``ANSI C''). The +.B fdopen +function conforms to IEEE Std1003.1-1988 (``POSIX.1''). +.SH "SEE ALSO" +.BR open (2), +.BR fclose (3), +.BR fileno (3) diff --git a/man3/forkpty.3 b/man3/forkpty.3 new file mode 100644 index 000000000..fb4952d52 --- /dev/null +++ b/man3/forkpty.3 @@ -0,0 +1 @@ +.so man3/openpty.3 diff --git a/man3/fpathconf.3 b/man3/fpathconf.3 new file mode 100644 index 000000000..2ce1e4713 --- /dev/null +++ b/man3/fpathconf.3 @@ -0,0 +1,159 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Wed Jul 28 11:12:26 1993 by Rik Faith (faith@cs.unc.edu) +.TH FPATHCONF 3 1993-04-04 "GNU" "Linux Programmer's Manual" +.SH NAME +fpathconf, pathconf \- get configuration values for files +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "long fpathconf(int " filedes ", int " name ); +.nl +.BI "long pathconf(char *" path ", int " name ); +.fi +.SH DESCRIPTION +.B fpathconf() +gets a value for the configuration option +.I name +for the open file descriptor +.IR filedes . +.PP +.B pathconf() +gets a value for configuration option +.I name +for the file name +.IR path . +.PP +The corresponding macros defined in +.B +are minimum values; if an application wants to take advantage of values +which may change, a call to +.B fpathconf() +or +.B pathconf() +can be made, which may yield more liberal results. +.PP +Setting +.I name +equal to one of the following constants returns the following +configuration options: +.TP +.B _PC_LINK_MAX +returns the maximum number of links to the file. If +.I filedes +or +.I path +refer to a directory, then the value applies to the whole directory. +The corresponding macro is +.BR _POSIX_LINK_MAX . +.TP +.B _PC_MAX_CANON +returns the maximum length of a formatted input line, where +.I filedes +or +.I path +must refer to a terminal. +The corresponding macro is +.BR _POSIX_MAX_CANON . +.TP +.B _PC_MAX_INPUT +returns the maximum length of an input line, where +.I filedes +or +.I path +must refer to a terminal. +The corresponding macro is +.BR _POSIX_MAX_INPUT . +.TP +.B _PC_NAME_MAX +returns the maximum length of a filename in the directory +.I path +or +.IR filedes . +the process is allowed to create. +The corresponding macro is +.BR _POSIX_NAME_MAX . +.TP +.B _PC_PATH_MAX +returns the maximum length of a relative pathname when +.I path +or +.I filedes +is the current working directory. The corresponding macro is +.BR _POSIX_PATH_MAX . +.TP +.B _PC_PIPE_BUF +returns the size of the pipe buffer, where +.I filedes +must refer to a pipe or FIFO and +.I path +must refer to a FIFO. The corresponding macro is +.BR _POSIX_PIPE_BUF . +.TP +.B _PC_CHOWN_RESTRICTED +returns nonzero if the +.BR chown (2) +call may not be used on this file. If +.I filedes +or +.I path +refer to a directory, then this applies to all files in that +directory. The corresponding macro is +.BR _POSIX_CHOWN_RESTRICTED . +.TP +.B _PC_NO_TRUNC +returns nonzero if accessing filenames longer than +.B _POSIX_NAME_MAX +generates an error. The corresponding macro is +.BR _POSIX_NO_TRUNC . +.TP +.B _PC_VDISABLE +returns nonzero if special character processing can be disabled, where +.I filedes +or +.I path +must refer to a terminal. +.SH "RETURN VALUE" +The limit is returned, if one exists. If the system does not have a +limit for the requested resource, \-1 is returned, and +.I errno +is unchanged. If there is an error, \-1 is returned, and +.I errno +is set to reflect the nature of the error. +.SH "CONFORMING TO" +POSIX.1 +.SH NOTES +Files with name lengths longer than the value returned for +.I name +equal to +.B _PC_NAME_MAX +may exist in the given directory. +.PP +Some returned values may be huge; they are not suitable for allocating +memory. +.SH "SEE ALSO" +.BR getconf (1), +.BR open (2), +.BR statfs (2), +.BR sysconf (3) diff --git a/man3/fpclassify.3 b/man3/fpclassify.3 new file mode 100644 index 000000000..0c317f506 --- /dev/null +++ b/man3/fpclassify.3 @@ -0,0 +1,80 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL, 2002-07-27 Walter Harms +.\" This was done with the help of the glibc manual. +.\" +.\" 2004-10-31, aeb, corrected +.TH fpclassify 3 2004-10-31 "" "Linux Programmer's Manual" +.SH NAME +fpclassify, isfinite, isnormal, isnan \- floating-point classification macros +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int fpclassify(" x ); +.sp +.BI "int isfinite(" x ); +.sp +.BI "int isnormal(" x ); +.sp +.BI "int isnan(" x ); +.sp +.BI "int isinf(" x ); +.fi +.SH DESCRIPTION +Floating point numbers can have special values, such as +infinite or NaN. With the macro +.BI fpclassify( x ) +you can find out what type +.I x +is. The macro takes any floating-point expression as argument. +The result takes one of the following values: +.TP +FP_NAN +.I x +is "Not a Number". +.TP +FP_INFINITE +.I x +is either plus or minus infinity. +.TP +FP_ZERO +.I x +is zero. +.TP +FP_SUBNORMAL +.I x +is too small to be represented in normalized format. +.TP +FP_NORMAL +if nothing of the above is correct that it must be a +normal floating-point number. +.LP +The other macros provide a short answer to some standard questions. +.TP +.BI isfinite( x ) +returns a nonzero value if +.br +(fpclassify(x) != FP_NAN && fpclassify(x) != FP_INFINITE) +.TP +.BI isnormal( x ) +returns a nonzero value if +(fpclassify(x) == FP_NORMAL) +.TP +.BI isnan( x ) +returns a nonzero value if +(fpclassify(x) == FP_NAN) +.TP +.BI isinf( x ) +returns a nonzero value if +(fpclassify(x) == FP_INFINITE) +.SH NOTE +On systems conforming to BSD 4.3, +.B isinf() +will return 1 for positive, and \-1 for negative infinity. +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR finite (3), +.BR INFINITY (3), +.BR isgreater (3) + diff --git a/man3/fprintf.3 b/man3/fprintf.3 new file mode 100644 index 000000000..975530d90 --- /dev/null +++ b/man3/fprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man3/fpurge.3 b/man3/fpurge.3 new file mode 100644 index 000000000..7aa84847e --- /dev/null +++ b/man3/fpurge.3 @@ -0,0 +1,80 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH FPURGE 3 2001-12-15 "" "Linux Programmer's Manual" +.SH NAME +fpurge, __fpurge \- purge a stream +.SH SYNOPSIS +.nf +/* unsupported */ +.B #include +.sp +.BI "int fpurge(FILE *" stream ); +.sp +/* supported */ +.B #include +.br +.B #include +.sp +.BI "void __fpurge(FILE *" stream ); +.fi +.SH DESCRIPTION +The function +.B fpurge() +clears the buffers of the given stream. +For output streams this discards any unwritten output. +For input streams this discards any input read from the underlying object +but not yet obtained via +.BR getc (3); +this includes any text pushed back via \fIungetc\fP(). See also +.BR fflush (3). +.LP +The function +.B __fpurge() +does precisely the same, but without returning a value. +.SH "RETURN VALUE" +Upon successful completion +.B fpurge() +returns 0. +On error, it returns \-1 and sets +.I errno +appropriately. +.SH ERRORS +.TP +.B EBADF +.I stream +is not an open stream. +.SH "CONFORMING TO" +These functions are nonstandard and not portable. +The function +.IR fpurge () +was introduced in BSD 4.4 and is not available under Linux. +The function +.IR __fpurge () +was introduced in Solaris, and is present in glibc 2.1.95 and later. +.SH NOTES +Usually it is a mistake to want to discard input buffers. +.SH "SEE ALSO" +.BR fclean (3), +.BR fflush (3), +.BR setbuf (3), +.BR stdio_ext (3) diff --git a/man3/fputc.3 b/man3/fputc.3 new file mode 100644 index 000000000..a7c3b57fc --- /dev/null +++ b/man3/fputc.3 @@ -0,0 +1 @@ +.so man3/puts.3 diff --git a/man3/fputc_unlocked.3 b/man3/fputc_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/fputc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fputs.3 b/man3/fputs.3 new file mode 100644 index 000000000..a7c3b57fc --- /dev/null +++ b/man3/fputs.3 @@ -0,0 +1 @@ +.so man3/puts.3 diff --git a/man3/fputs_unlocked.3 b/man3/fputs_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/fputs_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fputwc.3 b/man3/fputwc.3 new file mode 100644 index 000000000..7c1f046b5 --- /dev/null +++ b/man3/fputwc.3 @@ -0,0 +1,59 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH FPUTWC 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +fputwc \- write a wide character to a FILE stream +.SH SYNOPSIS +.nf +.B #include +.br +.B #include +.sp +.BI "wint_t fputwc(wchar_t " wc ", FILE *" stream ); +.BI "wint_t putwc(wchar_t " wc ", FILE *" stream ); +.fi +.SH DESCRIPTION +The \fBfputwc\fP function is the wide-character equivalent of the \fBfputc\fP +function. It writes the wide character \fIwc\fP to \fIstream\fP. If +\fIferror(stream)\fP becomes true, it returns WEOF. If a wide character +conversion error occurs, it sets \fBerrno\fP to \fBEILSEQ\fP and returns WEOF. +Otherwise it returns \fIwc\fP. +.PP +The \fBputwc\fP function or macro functions identically to \fBfputwc\fP. +It may be implemented as a macro, and may evaluate its argument +more than once. There is no reason ever to use it. +.PP +For non-locking counterparts, see +.BR unlocked_stdio (3). +.SH "RETURN VALUE" +The \fBfputwc\fP function returns \fIwc\fP if no error occurred, or WEOF to +indicate an error. +.SH ERRORS +Apart from the usual ones, there is +.TP +.B EILSEQ +Conversion of \fIwc\fP to the stream's encoding fails. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH NOTES +The behaviour of \fBfputwc\fP depends on the LC_CTYPE category of the +current locale. +.PP +In the absence of additional information passed to the fopen call, it is +reasonable to expect that \fBfputwc\fP will actually write the multibyte +sequence corresponding to the wide character \fIwc\fP. +.SH "SEE ALSO" +.BR fgetwc (3), +.BR fputws (3), +.BR unlocked_stdio (3) diff --git a/man3/fputwc_unlocked.3 b/man3/fputwc_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/fputwc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fputws.3 b/man3/fputws.3 new file mode 100644 index 000000000..b6c90aa22 --- /dev/null +++ b/man3/fputws.3 @@ -0,0 +1,44 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH FPUTWS 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +fputws \- write a wide character string to a FILE stream +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int fputws(const wchar_t *" ws ", FILE *" stream ); +.fi +.SH DESCRIPTION +The \fBfputws\fP function is the wide-character equivalent of the \fBfputs\fP +function. It writes the wide character string starting at \fIws\fP, up to but +not including the terminating L'\\0' character, to \fIstream\fP. +.PP +For a non-locking counterpart, see +.BR unlocked_stdio (3). +.SH "RETURN VALUE" +The \fBfputws\fP function returns a nonnegative integer if the operation was +successful, or \-1 to indicate an error. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH NOTES +The behaviour of \fBfputws\fP depends on the LC_CTYPE category of the +current locale. +.PP +In the absence of additional information passed to the fopen call, it is +reasonable to expect that \fBfputws\fP will actually write the multibyte +string corresponding to the wide character string \fIws\fP. +.SH "SEE ALSO" +.BR fputwc (3), +.BR unlocked_stdio (3) diff --git a/man3/fputws_unlocked.3 b/man3/fputws_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/fputws_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fread.3 b/man3/fread.3 new file mode 100644 index 000000000..ab22719c3 --- /dev/null +++ b/man3/fread.3 @@ -0,0 +1,104 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fread.3 6.6 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:37:33 1993, faith@cs.unc.edu +.\" Sun Feb 19 21:26:54 1995 by faith, return values +.\" Modified Thu Apr 20 20:43:53 1995 by Jim Van Zandt +.\" Modified Fri May 17 10:21:51 1996 by Martin Schulze +.\" +.TH FREAD 3 1996-05-17 "BSD MANPAGE" "Linux Programmer's Manual" +.SH NAME +fread, fwrite \- binary stream input/output +.SH SYNOPSIS +.B #include +.sp +.BI "size_t fread(void *" ptr ", size_t " size ", size_t " nmemb , +.BI "FILE *" stream ); +.sp +.BI "size_t fwrite(const void *" ptr ", size_t " size ", size_t " nmemb , +.BI "FILE *" stream ); +.SH DESCRIPTION +The function +.B fread +reads +.I nmemb +elements of data, each +.I size +bytes long, from the stream pointed to by +.IR stream , +storing them at the location given by +.IR ptr . +.PP +The function +.B fwrite +writes +.I nmemb +elements of data, each +.I size +bytes long, to the stream pointed to by +.IR stream , +obtaining them from the location given by +.IR ptr . +.PP +For non-locking counterparts, see +.BR unlocked_stdio (3). +.SH "RETURN VALUE" +.B fread +and +.B fwrite +return the number of items successfully read or written (i.e., not the +number of characters). If an error occurs, or the end-of-file is +reached, the return value is a short item count (or zero). +.PP +.B fread +does not distinguish between end-of-file and error, and callers must use +.BR feof (3) +and +.BR ferror (3) +to determine which occurred. +.SH "CONFORMING TO" +The functions +.B fread +and +.B fwrite +conform to ANSI X3.159-1989 (``ANSI C''). +.SH "SEE ALSO" +.BR read (2), +.BR write (2), +.BR feof (3), +.BR ferror (3), +.BR unlocked_stdio (3) diff --git a/man3/fread_unlocked.3 b/man3/fread_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/fread_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/free.3 b/man3/free.3 new file mode 100644 index 000000000..a4b9d4455 --- /dev/null +++ b/man3/free.3 @@ -0,0 +1 @@ +.so man3/malloc.3 diff --git a/man3/freeaddrinfo.3 b/man3/freeaddrinfo.3 new file mode 100644 index 000000000..17f7236a7 --- /dev/null +++ b/man3/freeaddrinfo.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo.3 diff --git a/man3/freehostent.3 b/man3/freehostent.3 new file mode 100644 index 000000000..82e01df46 --- /dev/null +++ b/man3/freehostent.3 @@ -0,0 +1 @@ +.so man3/getipnodebyname.3 diff --git a/man3/freopen.3 b/man3/freopen.3 new file mode 100644 index 000000000..9a4012491 --- /dev/null +++ b/man3/freopen.3 @@ -0,0 +1 @@ +.so man3/fopen.3 diff --git a/man3/frexp.3 b/man3/frexp.3 new file mode 100644 index 000000000..36764dfbd --- /dev/null +++ b/man3/frexp.3 @@ -0,0 +1,81 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH FREXP 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +frexp, frexpf, frexpl \- convert floating-point number to fractional +and integral components +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double frexp(double " x ", int *" exp ); +.sp +.BI "float frexpf(float " x ", int *" exp ); +.sp +.BI "long double frexpl(long double " x ", int *" exp ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBfrexp()\fP function is used to split the number \fIx\fP into a +normalized fraction and an exponent which is stored in \fIexp\fP. +.SH "RETURN VALUE" +The \fBfrexp()\fP function returns the normalized fraction. If the +argument \fIx\fP is not zero, the normalized fraction is \fIx\fP +times a power of two, and is always in the range 1/2 (inclusive) to +1 (exclusive). If \fIx\fP is zero, then the normalized fraction is +zero and zero is stored in \fIexp\fP. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and the long double variants are C99 requirements. +.SH EXAMPLE +.nf +#include +#include +#include +int main () { + double d = 2560; + int e; + double f = frexp(d, &e); + printf("frexp(%g, &e) = %g: %g * %d^%d = %g\en", + d, f, f, FLT_RADIX, e, d); + return 0; +} +.fi +.sp +This program prints +.sp +.in +5 +frexp(2560, &e) = 0.625: 0.625 * 2^12 = 2560 +.in +.SH "SEE ALSO" +.BR ldexp (3), +.BR modf (3) diff --git a/man3/fscanf.3 b/man3/fscanf.3 new file mode 100644 index 000000000..9fd424bb2 --- /dev/null +++ b/man3/fscanf.3 @@ -0,0 +1 @@ +.so man3/scanf.3 diff --git a/man3/fseek.3 b/man3/fseek.3 new file mode 100644 index 000000000..6e35ffa99 --- /dev/null +++ b/man3/fseek.3 @@ -0,0 +1,170 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fseek.3 6.11 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" +.TH FSEEK 3 1993-11-29 "BSD MANPAGE" "Linux Programmer's Manual" +.SH NAME +fgetpos, fseek, fsetpos, ftell, rewind \- reposition a stream +.SH SYNOPSIS +.B #include +.sp +.BI "int fseek(FILE *" stream ", long " offset ", int " whence ); +.br +.BI "long ftell(FILE *" stream ); +.br +.BI "void rewind(FILE *" stream ); +.br +.BI "int fgetpos(FILE *" stream ", fpos_t *" pos ); +.br +.BI "int fsetpos(FILE *" stream ", fpos_t *" pos ); +.SH DESCRIPTION +The +.B fseek +function sets the file position indicator for the stream pointed to by +.IR stream . +The new position, measured in bytes, is obtained by adding +.I offset +bytes to the position specified by +.IR whence . +If +.I whence +is set to +.BR SEEK_SET , +.BR SEEK_CUR , +or +.BR SEEK_END , +the offset is relative to the start of the file, the current position +indicator, or end-of-file, respectively. A successful call to the +.B fseek +function clears the end-of-file indicator for the stream and undoes +any effects of the +.BR ungetc (3) +function on the same stream. +.PP +The +.B ftell +function obtains the current value of the file position indicator for the +stream pointed to by +.IR stream . +.PP +The +.B rewind +function sets the file position indicator for the stream pointed to by +.I stream +to the beginning of the file. It is equivalent to: +.PP +.RS +(void)fseek(stream, 0L, SEEK_SET) +.RE +.PP +except that the error indicator for the stream is also cleared (see +.BR clearerr (3)). +.PP +The +.B fgetpos +and +.B fsetpos +functions are alternate interfaces equivalent to +.B ftell +and +.B fseek +(with whence set to +.BR SEEK_SET ), +setting and storing the current value of the file offset into or from the +object referenced by +.IR pos . +On some non-UNIX systems an +.B fpos_t +object may be a complex object and these routines may be the only way to +portably reposition a text stream. +.SH "RETURN VALUE" +The +.B rewind +function returns no value. Upon successful completion, +.BR fgetpos , +.BR fseek , +.B fsetpos +return 0, +and +.B ftell +returns the current offset. Otherwise, \-1 is returned and the global +variable errno is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The +.I stream +specified is not a seekable stream. +.TP +.B EINVAL +The +.I whence +argument to +.B fseek +was not +.BR SEEK_SET , +.BR SEEK_END , +or +.BR SEEK_CUR . +.PP +The function +.BR fgetpos , +.BR fseek , +.BR fsetpos , +and +.B ftell +may also fail and set +.I errno +for any of the errors specified for the routines +.BR fflush (3), +.BR fstat (2), +.BR lseek (2), +and +.BR malloc (3). +.SH "CONFORMING TO" +The +.BR fgetpos , +.BR fsetpos , +.BR fseek , +.BR ftell , +and +.BR rewind +functions conform to ANSI X3.159-1989 (``ANSI C''). +.SH "SEE ALSO" +.BR lseek (2), +.BR fseeko (3) diff --git a/man3/fseeko.3 b/man3/fseeko.3 new file mode 100644 index 000000000..409844d97 --- /dev/null +++ b/man3/fseeko.3 @@ -0,0 +1,61 @@ +.\" Copyright 2001 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH FSEEKO 3 2001-11-05 "" "Linux Programmer's Manual" +.SH NAME +fseeko, ftello \- seek to or report file position +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int fseeko(FILE *" stream ", off_t " offset ", int " whence ); +.sp +.BI "off_t ftello(FILE *" stream ); +.BI +.fi +.SH DESCRIPTION +The \fBfseeko()\fP and \fBftello()\fP functions are identical to +\fBfseek()\fP and \fBftell()\fP (see +.BR fseek (3)), +respectively, except that the \fIoffset\fP argument of \fBfseeko()\fP +and the return value of \fBftello()\fP is of type \fBoff_t\fP +instead of \fBlong\fP. +.LP +On many architectures both \fBoff_t\fP and \fBlong\fP are 32-bit types, +but compilation with +.RS +.nf +#define _FILE_OFFSET_BITS 64 +.fi +.RE +will turn \fBoff_t\fP into a 64-bit type. +.SH NOTES +These functions are found on SysV-like systems. +They are not present in libc4, libc5, glibc 2.0 but available since glibc 2.1. +.SH "CONFORMING TO" +The +.B fseeko +and +.B ftello +functions conform to SUSv2. +.SH "SEE ALSO" +.BR fseek (3) diff --git a/man3/fsetpos.3 b/man3/fsetpos.3 new file mode 100644 index 000000000..a1487b5a8 --- /dev/null +++ b/man3/fsetpos.3 @@ -0,0 +1 @@ +.so man3/fseek.3 diff --git a/man3/ftell.3 b/man3/ftell.3 new file mode 100644 index 000000000..a1487b5a8 --- /dev/null +++ b/man3/ftell.3 @@ -0,0 +1 @@ +.so man3/fseek.3 diff --git a/man3/ftello.3 b/man3/ftello.3 new file mode 100644 index 000000000..d5628f46d --- /dev/null +++ b/man3/ftello.3 @@ -0,0 +1 @@ +.so man3/fseeko.3 diff --git a/man3/ftime.3 b/man3/ftime.3 new file mode 100644 index 000000000..77a6c4efc --- /dev/null +++ b/man3/ftime.3 @@ -0,0 +1,85 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de) +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 14:23:14 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Oct 18 17:31:43 1998 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH FTIME 3 2001-12-14 "Linux" "Linux Programmer's Manual" +.SH NAME +ftime \- return date and time +.SH SYNOPSIS +.B "#include " +.sp +.BI "int ftime(struct timeb *" tp ); +.SH DESCRIPTION +Return current date and time in +.IR tp , +which is declared as follows: +.sp +.in +1i +.nf +struct timeb { + time_t time; + unsigned short millitm; + short timezone; + short dstflag; +}; +.fi +.in -1i +.LP +Here \fItime\fP is the number of seconds since the epoch, +\fImillitm\fP is the number of milliseconds since \fItime\fP +seconds since the epoch, \fItimezone\fP is the local time zone +measured in minutes of time west of Greenwich, and \fIdstflag\fP +is a flag that, if nonzero, indicates that Daylight Saving time +applies locally during the appropriate part of the year. +.LP +These days the contents of the \fItimezone\fP and \fIdstflag\fP +fields are undefined. +.SH "RETURN VALUE" +This function always returns 0. +.SH BUGS +This function is obsolete. Don't use it. If the time in seconds +suffices, +.BR time (2) +can be used; +.BR gettimeofday (2) +gives microseconds; +.BR clock_gettime (3) +gives nanoseconds but is not yet widely available. +.LP +Under libc4 and libc5 the \fImillitm\fP field is meaningful. +But early glibc2 is buggy and returns 0 there; +glibc 2.1.1 is correct again. +.SH HISTORY +The +.B ftime() +function appeared in 4.2BSD. +.SH "CONFORMING TO" +BSD 4.2, POSIX 1003.1-2001. +.SH "SEE ALSO" +.BR gettimeofday (2), +.BR time (2) diff --git a/man3/ftok.3 b/man3/ftok.3 new file mode 100644 index 000000000..be287e3f8 --- /dev/null +++ b/man3/ftok.3 @@ -0,0 +1,100 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 2001-11-28, by Michael Kerrisk, mtk16@ext.canterbury.ac.nz +.\" Changed data type of proj_id; minor fixes +.\" aeb: further fixes; added notes. +.\" +.TH FTOK 3 2001-11-28 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +ftok \- convert a pathname and a project identifier to a System V IPC key +.SH SYNOPSIS +.nf +.B +# include +.B +# include +.fi +.sp +.BI "key_t ftok(const char *" pathname ", int " proj_id ); +.SH DESCRIPTION +The +.B ftok +function uses the identity of the file named by the given +.I pathname +(which must refer to an existing, accessible file) +and the least significant 8 bits of +.I proj_id +(which must be nonzero) to generate a +.B key_t +type System V IPC key, suitable for use with +.BR msgget (2), +.BR semget (2), +or +.BR shmget (2). +.LP +The resulting value is the same for all pathnames that +name the same file, when the same value of +.I proj_id +is used. The value returned should be different when the +(simultaneously existing) files or the project IDs differ. +.SH "RETURN VALUE" +On success the generated +.B key_t +value is returned. On failure \-1 is returned, with +.I errno +indicating the error as for the +.BR stat (2) +system call. +.SH "CONFORMING TO" +XPG4 +.SH NOTES +Under libc4 and libc5 (and under SunOS 4.x) the prototype was +.RS +.BI "key_t ftok(char *" pathname ", char " proj_id ); +.RE +Today +.I proj_id +is an +.BR int , +but still only 8 bits are used. Typical usage has an ASCII character +.IR proj_id , +that is why the behaviour is said to be undefined when +.I proj_id +is zero. +.LP +Of course no guarantee can be given that the resulting +.B key_t +is unique. Typically, a best effort attempt combines the given +.I proj_id +byte, the lower 16 bits of the i\-node number, and the +lower 8 bits of the device number into a 32\-bit result. +Collisions may easily happen, for example between files on +.I /dev/hda1 +and files on +.IR /dev/sda1 . +.SH "SEE ALSO" +.BR msgget (2), +.BR semget (2), +.BR shmget (2), +.BR stat (2), +.BR ipc (5) diff --git a/man3/ftrylockfile.3 b/man3/ftrylockfile.3 new file mode 100644 index 000000000..b33c2ee65 --- /dev/null +++ b/man3/ftrylockfile.3 @@ -0,0 +1 @@ +.so man3/flockfile.3 diff --git a/man3/fts.3 b/man3/fts.3 new file mode 100644 index 000000000..2fb451d97 --- /dev/null +++ b/man3/fts.3 @@ -0,0 +1,757 @@ +.\" $NetBSD: fts.3,v 1.13.2.1 1997/11/14 02:09:32 mrg Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fts.3 8.5 (Berkeley) 4/16/94 +.\" +.Dd April 16, 1994 +.Dt FTS 3 +.Os +.Sh NAME +.Nm fts , +.Nm fts_open , +.Nm fts_read , +.Nm fts_children , +.Nm fts_set , +.Nm fts_close +.Nd traverse a file hierarchy +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Ft FTS * +.Fn fts_open "char * const *path_argv" "int options" "int (*compar)(const FTSENT **, const FTSENT **)" +.Ft FTSENT * +.Fn fts_read "FTS *ftsp" +.Ft FTSENT * +.Fn fts_children "FTS *ftsp" "int options" +.Ft int +.Fn fts_set "FTS *ftsp" "FTSENT *f" "int options" +.Ft int +.Fn fts_close "FTS *ftsp" +.Sh DESCRIPTION +The +.Nm fts +functions are provided for traversing +.Tn UNIX +file hierarchies. +A simple overview is that the +.Fn fts_open +function returns a ``handle'' on a file hierarchy, which is then supplied to +the other +.Nm fts +functions. +The function +.Fn fts_read +returns a pointer to a structure describing one of the files in the file +hierarchy. +The function +.Fn fts_children +returns a pointer to a linked list of structures, each of which describes +one of the files contained in a directory in the hierarchy. +In general, directories are visited two distinguishable times; in pre-order +(before any of their descendants are visited) and in post-order (after all +of their descendants have been visited). +Files are visited once. +It is possible to walk the hierarchy ``logically'' (ignoring symbolic links) +or physically (visiting symbolic links), order the walk of the hierarchy or +prune and/or re-visit portions of the hierarchy. +.Pp +Two structures are defined (and typedef'd) in the include file +.Aq Pa fts.h . +The first is +.Fa FTS , +the structure that represents the file hierarchy itself. +The second is +.Fa FTSENT , +the structure that represents a file in the file +hierarchy. +Normally, an +.Fa FTSENT +structure is returned for every file in the file +hierarchy. +In this manual page, ``file'' and +.Dq Fa FTSENT No structure +are generally +interchangeable. +The +.Fa FTSENT +structure contains at least the following fields, which are +described in greater detail below: +.Bd -literal +typedef struct _ftsent { + u_short fts_info; /* flags for FTSENT structure */ + char *fts_accpath; /* access path */ + char *fts_path; /* root path */ + short fts_pathlen; /* strlen(fts_path) */ + char *fts_name; /* file name */ + short fts_namelen; /* strlen(fts_name) */ + short fts_level; /* depth (\-1 to N) */ + int fts_errno; /* file errno */ + long fts_number; /* local numeric value */ + void *fts_pointer; /* local address value */ + struct ftsent *fts_parent; /* parent directory */ + struct ftsent *fts_link; /* next file structure */ + struct ftsent *fts_cycle; /* cycle structure */ + struct stat *fts_statp; /* stat(2) information */ +} FTSENT; +.Ed +.Pp +These fields are defined as follows: +.Bl -tag -width "fts_namelen" +.It Fa fts_info +One of the following flags describing the returned +.Fa FTSENT +structure and +the file it represents. +With the exception of directories without errors +.Pq Dv FTS_D , +all of these +entries are terminal, that is, they will not be revisited, nor will any +of their descendants be visited. +.Bl -tag -width FTS_DEFAULT +.It Dv FTS_D +A directory being visited in pre-order. +.It Dv FTS_DC +A directory that causes a cycle in the tree. +(The +.Fa fts_cycle +field of the +.Fa FTSENT +structure will be filled in as well.) +.It Dv FTS_DEFAULT +Any +.Fa FTSENT +structure that represents a file type not explicitly described +by one of the other +.Fa fts_info +values. +.It Dv FTS_DNR +A directory which cannot be read. +This is an error return, and the +.Fa fts_errno +field will be set to indicate what caused the error. +.It Dv FTS_DOT +A file named +.Ql \&. +or +.Ql .. +which was not specified as a file name to +.Fn fts_open +(see +.Dv FTS_SEEDOT ) . +.It Dv FTS_DP +A directory being visited in post-order. +The contents of the +.Fa FTSENT +structure will be unchanged from when +it was returned in pre-order, i.e. with the +.Fa fts_info +field set to +.Dv FTS_D . +.It Dv FTS_ERR +This is an error return, and the +.Fa fts_errno +field will be set to indicate what caused the error. +.It Dv FTS_F +A regular file. +.It Dv FTS_NS +A file for which no +.Xr stat 2 +information was available. +The contents of the +.Fa fts_statp +field are undefined. +This is an error return, and the +.Fa fts_errno +field will be set to indicate what caused the error. +.It Dv FTS_NSOK +A file for which no +.Xr stat 2 +information was requested. +The contents of the +.Fa fts_statp +field are undefined. +.It Dv FTS_SL +A symbolic link. +.It Dv FTS_SLNONE +A symbolic link with a non-existent target. +The contents of the +.Fa fts_statp +field reference the file characteristic information for the symbolic link +itself. +.El +.It Fa fts_accpath +A path for accessing the file from the current directory. +.It Fa fts_path +The path for the file relative to the root of the traversal. +This path contains the path specified to +.Fn fts_open +as a prefix. +.It Fa fts_pathlen +The length of the string referenced by +.Fa fts_path . +.It Fa fts_name +The name of the file. +.It Fa fts_namelen +The length of the string referenced by +.Fa fts_name . +.It Fa fts_level +The depth of the traversal, numbered from \-1 to N, where this file +was found. +The +.Fa FTSENT +structure representing the parent of the starting point (or root) +of the traversal is numbered \-1, and the +.Fa FTSENT +structure for the root +itself is numbered 0. +.It Fa fts_errno +Upon return of a +.Fa FTSENT +structure from the +.Fn fts_children +or +.Fn fts_read +functions, with its +.Fa fts_info +field set to +.Dv FTS_DNR , +.Dv FTS_ERR +or +.Dv FTS_NS , +the +.Fa fts_errno +field contains the value of the external variable +.Va errno +specifying the cause of the error. +Otherwise, the contents of the +.Fa fts_errno +field are undefined. +.It Fa fts_number +This field is provided for the use of the application program and is +not modified by the +.Nm fts +functions. +It is initialized to 0. +.It Fa fts_pointer +This field is provided for the use of the application program and is +not modified by the +.Nm fts +functions. +It is initialized to +.Dv NULL . +.It Fa fts_parent +A pointer to the +.Fa FTSENT +structure referencing the file in the hierarchy +immediately above the current file, i.e. the directory of which this +file is a member. +A parent structure for the initial entry point is provided as well, +however, only the +.Fa fts_level , +.Fa fts_number +and +.Fa fts_pointer +fields are guaranteed to be initialized. +.It Fa fts_link +Upon return from the +.Fn fts_children +function, the +.Fa fts_link +field points to the next structure in the NULL-terminated linked list of +directory members. +Otherwise, the contents of the +.Fa fts_link +field are undefined. +.It Fa fts_cycle +If a directory causes a cycle in the hierarchy (see +.Dv FTS_DC ) , +either because +of a hard link between two directories, or a symbolic link pointing to a +directory, the +.Fa fts_cycle +field of the structure will point to the +.Fa FTSENT +structure in the hierarchy that references the same file as the current +.Fa FTSENT +structure. +Otherwise, the contents of the +.Fa fts_cycle +field are undefined. +.It Fa fts_statp +A pointer to +.Xr stat 2 +information for the file. +.El +.Pp +A single buffer is used for all of the paths of all of the files in the +file hierarchy. +Therefore, the +.Fa fts_path +and +.Fa fts_accpath +fields are guaranteed to be +.Dv NULL Ns -terminated +.Em only +for the file most recently returned by +.Fn fts_read . +To use these fields to reference any files represented by other +.Fa FTSENT +structures will require that the path buffer be modified using the +information contained in that +.Fa FTSENT +structure's +.Fa fts_pathlen +field. +Any such modifications should be undone before further calls to +.Fn fts_read +are attempted. +The +.Fa fts_name +field is always +.Dv NULL Ns -terminated. +.Sh FTS_OPEN +The +.Fn fts_open +function takes a pointer to an array of character pointers naming one +or more paths which make up a logical file hierarchy to be traversed. +The array must be terminated by a +.Dv NULL +pointer. +.Pp +There are +a number of options, at least one of which (either +.Dv FTS_LOGICAL +or +.Dv FTS_PHYSICAL ) +must be specified. +The options are selected by +.Em or Ns 'ing +the following values: +.Bl -tag -width "FTS_PHYSICAL" +.It Dv FTS_COMFOLLOW +This option causes any symbolic link specified as a root path to be +followed immediately whether or not +.Dv FTS_LOGICAL +is also specified. +.It Dv FTS_LOGICAL +This option causes the +.Nm fts +routines to return +.Fa FTSENT +structures for the targets of symbolic links +instead of the symbolic links themselves. +If this option is set, the only symbolic links for which +.Fa FTSENT +structures +are returned to the application are those referencing non-existent files. +Either +.Dv FTS_LOGICAL +or +.Dv FTS_PHYSICAL +.Em must +be provided to the +.Fn fts_open +function. +.It Dv FTS_NOCHDIR +As a performance optimization, the +.Nm fts +functions change directories as they walk the file hierarchy. +This has the side-effect that an application cannot rely on being +in any particular directory during the traversal. +The +.Dv FTS_NOCHDIR +option turns off this optimization, and the +.Nm fts +functions will not change the current directory. +Note that applications should not themselves change their current directory +and try to access files unless +.Dv FTS_NOCHDIR +is specified and absolute +pathnames were provided as arguments to +.Fn fts_open . +.It Dv FTS_NOSTAT +By default, returned +.Fa FTSENT +structures reference file characteristic information (the +.Fa statp +field) for each file visited. +This option relaxes that requirement as a performance optimization, +allowing the +.Nm fts +functions to set the +.Fa fts_info +field to +.Dv FTS_NSOK +and leave the contents of the +.Fa statp +field undefined. +.It Dv FTS_PHYSICAL +This option causes the +.Nm fts +routines to return +.Fa FTSENT +structures for symbolic links themselves instead +of the target files they point to. +If this option is set, +.Fa FTSENT +structures for all symbolic links in the +hierarchy are returned to the application. +Either +.Dv FTS_LOGICAL +or +.Dv FTS_PHYSICAL +.Em must +be provided to the +.Fn fts_open +function. +.It Dv FTS_SEEDOT +By default, unless they are specified as path arguments to +.Fn fts_open , +any files named +.Ql \&. +or +.Ql .. +encountered in the file hierarchy are ignored. +This option causes the +.Nm fts +routines to return +.Fa FTSENT +structures for them. +.It Dv FTS_XDEV +This option prevents +.Nm fts +from descending into directories that have a different device number +than the file from which the descent began. +.El +.Pp +The argument +.Fn compar +specifies a user-defined function which may be used to order the traversal +of the hierarchy. +It +takes two pointers to pointers to +.Fa FTSENT +structures as arguments and +should return a negative value, zero, or a positive value to indicate +if the file referenced by its first argument comes before, in any order +with respect to, or after, the file referenced by its second argument. +The +.Fa fts_accpath , +.Fa fts_path +and +.Fa fts_pathlen +fields of the +.Fa FTSENT +structures may +.Em never +be used in this comparison. +If the +.Fa fts_info +field is set to +.Dv FTS_NS +or +.Dv FTS_NSOK , +the +.Fa fts_statp +field may not either. +If the +.Fn compar +argument is +.Dv NULL , +the directory traversal order is in the order listed in +.Fa path_argv +for the root paths, and in the order listed in the directory for +everything else. +.Sh FTS_READ +The +.Fn fts_read +function returns a pointer to an +.Fa FTSENT +structure describing a file in +the hierarchy. +Directories (that are readable and do not cause cycles) are visited at +least twice, once in pre-order and once in post-order. +All other files are visited at least once. +(Hard links between directories that do not cause cycles or symbolic +links to symbolic links may cause files to be visited more than once, +or directories more than twice.) +.Pp +If all the members of the hierarchy have been returned, +.Fn fts_read +returns +.Dv NULL +and sets the external variable +.Va errno +to 0. +If an error unrelated to a file in the hierarchy occurs, +.Fn fts_read +returns +.Dv NULL +and sets +.Va errno +appropriately. +If an error related to a returned file occurs, a pointer to an +.Fa FTSENT +structure is returned, and +.Va errno +may or may not have been set (see +.Fa fts_info ) . +.Pp +The +.Fa FTSENT +structures returned by +.Fn fts_read +may be overwritten after a call to +.Fn fts_close +on the same file hierarchy stream, or, after a call to +.Fn fts_read +on the same file hierarchy stream unless they represent a file of type +directory, in which case they will not be overwritten until after a call to +.Fn fts_read +after the +.Fa FTSENT +structure has been returned by the function +.Fn fts_read +in post-order. +.Sh FTS_CHILDREN +The +.Fn fts_children +function returns a pointer to an +.Fa FTSENT +structure describing the first entry in a NULL-terminated linked list of +the files in the directory represented by the +.Fa FTSENT +structure most recently returned by +.Fn fts_read . +The list is linked through the +.Fa fts_link +field of the +.Fa FTSENT +structure, and is ordered by the user-specified comparison function, if any. +Repeated calls to +.Fn fts_children +will recreate this linked list. +.Pp +As a special case, if +.Fn fts_read +has not yet been called for a hierarchy, +.Fn fts_children +will return a pointer to the files in the logical directory specified to +.Fn fts_open , +i.e. the arguments specified to +.Fn fts_open . +Otherwise, if the +.Fa FTSENT +structure most recently returned by +.Fn fts_read +is not a directory being visited in pre-order, +or the directory does not contain any files, +.Fn fts_children +returns +.Dv NULL +and sets +.Va errno +to zero. +If an error occurs, +.Fn fts_children +returns +.Dv NULL +and sets +.Va errno +appropriately. +.Pp +The +.Fa FTSENT +structures returned by +.Fn fts_children +may be overwritten after a call to +.Fn fts_children , +.Fn fts_close +or +.Fn fts_read +on the same file hierarchy stream. +.Pp +.Em Option +may be set to the following value: +.Bl -tag -width FTS_NAMEONLY +.It Dv FTS_NAMEONLY +Only the names of the files are needed. +The contents of all the fields in the returned linked list of structures +are undefined with the exception of the +.Fa fts_name +and +.Fa fts_namelen +fields. +.El +.Sh FTS_SET +The function +.Fn fts_set +allows the user application to determine further processing for the +file +.Fa f +of the stream +.Fa ftsp . +The +.Fn fts_set +function +returns 0 on success, and \-1 if an error occurs. +.Em Option +must be set to one of the following values: +.Bl -tag -width FTS_PHYSICAL +.It Dv FTS_AGAIN +Re-visit the file; any file type may be re-visited. +The next call to +.Fn fts_read +will return the referenced file. +The +.Fa fts_stat +and +.Fa fts_info +fields of the structure will be reinitialized at that time, +but no other fields will have been changed. +This option is meaningful only for the most recently returned +file from +.Fn fts_read . +Normal use is for post-order directory visits, where it causes the +directory to be re-visited (in both pre and post-order) as well as all +of its descendants. +.It Dv FTS_FOLLOW +The referenced file must be a symbolic link. +If the referenced file is the one most recently returned by +.Fn fts_read , +the next call to +.Fn fts_read +returns the file with the +.Fa fts_info +and +.Fa fts_statp +fields reinitialized to reflect the target of the symbolic link instead +of the symbolic link itself. +If the file is one of those most recently returned by +.Fn fts_children , +the +.Fa fts_info +and +.Fa fts_statp +fields of the structure, when returned by +.Fn fts_read , +will reflect the target of the symbolic link instead of the symbolic link +itself. +In either case, if the target of the symbolic link does not exist the +fields of the returned structure will be unchanged and the +.Fa fts_info +field will be set to +.Dv FTS_SLNONE . +.Pp +If the target of the link is a directory, the pre-order return, followed +by the return of all of its descendants, followed by a post-order return, +is done. +.It Dv FTS_SKIP +No descendants of this file are visited. +The file may be one of those most recently returned by either +.Fn fts_children +or +.Fn fts_read . +.El +.Sh FTS_CLOSE +The +.Fn fts_close +function closes a file hierarchy stream +.Fa ftsp +and restores the current directory to the directory from which +.Fn fts_open +was called to open +.Fa ftsp . +The +.Fn fts_close +function +returns 0 on success, and \-1 if an error occurs. +.Sh ERRORS +The function +.Fn fts_open +may fail and set +.Va errno +for any of the errors specified for the library functions +.Xr open 2 +and +.Xr malloc 3 . +.Pp +The function +.Fn fts_close +may fail and set +.Va errno +for any of the errors specified for the library functions +.Xr chdir 2 +and +.Xr close 2 . +.Pp +The functions +.Fn fts_read +and +.Fn fts_children +may fail and set +.Va errno +for any of the errors specified for the library functions +.Xr chdir 2 , +.Xr malloc 3 , +.Xr opendir 3 , +.Xr readdir 3 +and +.Xr stat 2 . +.Pp +In addition, +.Fn fts_children , +.Fn fts_open +and +.Fn fts_set +may fail and set +.Va errno +as follows: +.Bl -tag -width Er +.It Bq Er EINVAL +The options were invalid. +.El +.Sh SEE ALSO +.Xr find 1 , +.Xr chdir 2 , +.Xr stat 2 , +.Xr qsort 3 +.Sh "CONFORMING TO" +BSD 4.4. The +.Nm fts +utility is expected to be included in a future +.St -p1003.1-88 +revision. +.Sh AVAILABILITY +These functions are available in Linux since glibc2. diff --git a/man3/fts_children.3 b/man3/fts_children.3 new file mode 100644 index 000000000..85caf7524 --- /dev/null +++ b/man3/fts_children.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man3/fts_close.3 b/man3/fts_close.3 new file mode 100644 index 000000000..85caf7524 --- /dev/null +++ b/man3/fts_close.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man3/fts_open.3 b/man3/fts_open.3 new file mode 100644 index 000000000..85caf7524 --- /dev/null +++ b/man3/fts_open.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man3/fts_read.3 b/man3/fts_read.3 new file mode 100644 index 000000000..85caf7524 --- /dev/null +++ b/man3/fts_read.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man3/fts_set.3 b/man3/fts_set.3 new file mode 100644 index 000000000..85caf7524 --- /dev/null +++ b/man3/fts_set.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man3/ftw.3 b/man3/ftw.3 new file mode 100644 index 000000000..04a102187 --- /dev/null +++ b/man3/ftw.3 @@ -0,0 +1,168 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de) +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) +.\" Fri Jun 25 00:34:07 CEST 1999 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu) +.TH FTW 3 1999-06-25 "Linux" "Linux Programmer's Manual" +.SH NAME +ftw, nftw \- file tree walk +.SH SYNOPSIS +.B #include +.sp +.BI "int ftw(const char *" dir ", int (*" fn ")(const" +.BI "char *" file ", const struct stat *" sb ", int " flag ), +.BI "int " nopenfd ); +.sp +.BI "int nftw(const char *" dir ", int (*" fn ")(const" +.BI "char *" file ", const struct stat *" sb ", int " flag , +.BI "struct FTW *" s ), +.BI "int " nopenfd ", int " flags ); +.SH DESCRIPTION +\fBftw\fP() walks through the directory tree starting from the indicated +directory \fIdir\fP. For each found entry in the tree, it calls +\fIfn\fP() with the full pathname of the entry, a pointer to the +.BR stat (2) +structure for the entry and an int \fIflag\fP, which value will be one of +the following: +.TP +.B FTW_F +Item is a normal file +.TP +.B FTW_D +Item is a directory +.TP +.B FTW_DNR +Item is a directory which can't be read +.TP +.B FTW_SL +Item is a symbolic link +.TP +.B FTW_NS +The stat failed on the item which is not a symbolic link +.LP +If the item is a symbolic link and stat failed, XPG4v2 states +that it is undefined whether FTW_NS or FTW_SL is used. +.PP +\fBftw\fP() recursively calls itself for traversing found directories, +handling a directory before its files or subdirectories. +To avoid using up all a program's file descriptors, \fInopenfd\fP +specifies the maximum number of simultaneous open directories. When +the search depth exceeds this, \fBftw\fP() will become slower because +directories have to be closed and reopened. \fBftw\fP() uses at most +one file descriptor for each level in the file hierarchy. +.PP +To stop the tree walk, \fIfn\fP() returns a non-zero value; this +value will become the return value of \fBftw\fP(). Otherwise, +\fBftw\fP() will continue until it has traversed the entire tree, in +which case it will return zero, or until it hits an error other than EACCES +(such as a +.BR malloc (3) +failure), in which case it will return \-1. +.PP +Because \fBftw()\fP uses dynamic data structures, the only safe way to +exit out of a tree walk is to return a non-zero value. To handle +interrupts, for example, mark that the interrupt occurred and return a +non-zero value\(emdon't use +.BR longjmp (3) +unless the program is going to terminate. + +The function \fBnftw\fP() does precisely the same as \fBftw\fP(), +except that it has one additional argument \fIflags\fP +(and calls the supplied function with one more argument). +This \fIflags\fP argument is an OR of zero or more of the following flags: +.TP +.B FTW_CHDIR +If set, do a +.IR chdir () +to each directory before handling its contents. +.TP +.B FTW_DEPTH +If set, do a depth-first search, that is, call the function for +the directory itself only after handling the contents of the directory +and its subdirectories. +.TP +.B FTW_MOUNT +If set, stay within the same file system. +.TP +.B FTW_PHYS +If set, do not follow symbolic links. +(This is what you want.) +If not set, symbolic links are followed, but no file is reported twice. +.LP +If FTW_PHYS is not set, but FTW_DEPTH is set, then the function +.IR fn () +is never called for a directory that would be a descendant of itself. +.LP +The function +.IR fn () +is called with four arguments: the pathname of the reported entry, +a pointer to a struct stat for this entry, an integer describing +its type, and a pointer to a struct FTW. The type will be one +of the following: FTW_F, FTW_D, FTW_DNR, FTW_SL, FTW_NS +(with meaning as above; FTW_SL occurs only with FTW_PHYS set) or +.TP +.B FTW_DP +Item is a directory and all its descendants have been handled +already. (This occurs only with FTW_DEPTH set.) +.TP +.B FTW_SLN +Item is a symbolic link pointing to a nonexisting file. +(This occurs only with FTW_PHYS unset.) +.LP +The struct FTW pointed to by the fourth argument to +.IR fn () +has at least the fields +.IR base , +the offset of the item's filename in the pathname +given as first argument of +.IR fn (), +and +.IR level , +the depth of the item relative to the starting point +(which has depth 0). +.SH NOTES +The function +.IR nftw () +and the use of FTW_SL with +.IR ftw () +were introduced in XPG4v2. +.LP +On some systems +.IR ftw () +will never use FTW_SL, on other systems FTW_SL occurs only +for symbolic links that do not point to an existing file, +and again on other systems +.IR ftw () +will use FTW_SL for each symbolic link. For predictable control, use +.IR nftw (). +.LP +Under Linux, libc4 and libc5 and glibc 2.0.6 will +use FTW_F for all objects (files, symbolic links, fifos, etc) +that can be stat'ed but are not a directory. +The function +.IR nftw () +is available since glibc 2.1. +.SH "CONFORMING TO" +AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4v2. +.SH "SEE ALSO" +.BR stat (2) diff --git a/man3/funlockfile.3 b/man3/funlockfile.3 new file mode 100644 index 000000000..b33c2ee65 --- /dev/null +++ b/man3/funlockfile.3 @@ -0,0 +1 @@ +.so man3/flockfile.3 diff --git a/man3/fwide.3 b/man3/fwide.3 new file mode 100644 index 000000000..350bca07e --- /dev/null +++ b/man3/fwide.3 @@ -0,0 +1,55 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH FWIDE 3 1999-11-17 "GNU" "Linux Programmer's Manual" +.SH NAME +fwide \- set and determine the orientation of a FILE stream +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int fwide(FILE *" stream ", int " mode ); +.fi +.SH DESCRIPTION +When \fImode\fP is zero, the \fBfwide\fP function determines the current +orientation of \fIstream\fP. It returns a value > 0 if \fIstream\fP is +wide-character oriented, i.e. if wide character I/O is permitted but char +I/O is disallowed. It returns a value < 0 if \fIstream\fP is byte oriented, +i.e. if char I/O is permitted but wide character I/O is disallowed. It +returns zero if \fIstream\fP has no orientation yet; in this case the next +I/O operation might change the orientation (to byte oriented if it is a char +I/O operation, or to wide-character oriented if it is a wide character I/O +operation). +.PP +Once a stream has an orientation, it cannot be changed and persists until +the stream is closed. +.PP +When \fImode\fP is non-zero, the \fBfwide\fP function first attempts to set +\fIstream\fP's orientation (to wide-character oriented if \fImode\fP > 0, or +to byte oriented if \fImode\fP < 0). It then returns a value denoting the +current orientation, as above. +.SH "RETURN VALUE" +The \fBfwide\fP function returns the stream's orientation, after possibly +changing it. A return value > 0 means wide-character oriented. A return value +< 0 means byte oriented. A return value zero means undecided. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR fprintf (3), +.BR fwprintf (3) +.SH NOTES +Wide-character output to a byte oriented stream can be performed through the +\fBfprintf\fP function with the %lc and %ls directives. +.PP +Char oriented output to a wide-character oriented stream can be performed +through the \fBfwprintf\fP function with the %c and %s directives. diff --git a/man3/fwprintf.3 b/man3/fwprintf.3 new file mode 100644 index 000000000..56ec9685b --- /dev/null +++ b/man3/fwprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man3/fwrite.3 b/man3/fwrite.3 new file mode 100644 index 000000000..86906ede5 --- /dev/null +++ b/man3/fwrite.3 @@ -0,0 +1 @@ +.so man3/fread.3 diff --git a/man3/fwrite_unlocked.3 b/man3/fwrite_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/fwrite_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/gai_strerror.3 b/man3/gai_strerror.3 new file mode 100644 index 000000000..17f7236a7 --- /dev/null +++ b/man3/gai_strerror.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo.3 diff --git a/man3/gamma.3 b/man3/gamma.3 new file mode 100644 index 000000000..65346fe70 --- /dev/null +++ b/man3/gamma.3 @@ -0,0 +1,67 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.\" Modified 2003-11-18, aeb: historical remarks +.\" +.TH GAMMA 3 2002-08-10 "GNU" "libc math functions" +.SH NAME +gamma, gammaf, gammal \- (logarithm of the) gamma function +.SH SYNOPSIS +.B #include +.sp +.BI "double gamma(double " x ");" +.sp +.BI "float gammaf(float " x ");" +.sp +.BI "long double gammal(long double " x ");" +.sp +Link with \-lm. +.SH DESCRIPTION +For the definition of the Gamma function, see +.BR tgamma (3). +.PP +.SS "*BSD version" +4.4BSD and FreeBSD libm have a +.B gamma() +function that computes the Gamma function, as one would expect. +.SS "glibc version" +Glibc has a +.B gamma() +function that is equivalent to +.B lgamma() +and computes the natural logarithm of the Gamma function. +(This is for compatibility reasons only. Don't use this function.) +.SH HISTORY +4.2BSD had a +.B gamma() +that computed +.RI ln(|Gamma(| x |)|), +leaving the sign of +.RI Gamma(| x |) +in the external integer +.IR signgam . +In 4.3BSD the name was changed to +.BR lgamma() , +and the man page promises +.sp +.in +3 +"At some time in the future the name gamma will be rehabilitated +and used for the Gamma function" +.in +.sp +This did indeed happen in 4.4BSD, where +.B gamma() +computes the Gamma function (with no effect on +.IR signgam ). +However, this came too late, and we now have +.BR tgamma() , +the "true gamma" function. +.\" The FreeBSD man page says about gamma() that it is like lgamma() +.\" except that is does not set signgam. +.\" Also, that 4.4BSD has a gamma() that computes the true gamma function. +.SH "CONFORMING TO" +4.2BSD. Compatible with previous mistakes. +.SH "SEE ALSO" +.BR lgamma (3), +.BR signgam (3), +.BR tgamma (3) diff --git a/man3/gammaf.3 b/man3/gammaf.3 new file mode 100644 index 000000000..64ab6eec3 --- /dev/null +++ b/man3/gammaf.3 @@ -0,0 +1 @@ +.so man3/gamma.3 diff --git a/man3/gammal.3 b/man3/gammal.3 new file mode 100644 index 000000000..64ab6eec3 --- /dev/null +++ b/man3/gammal.3 @@ -0,0 +1 @@ +.so man3/gamma.3 diff --git a/man3/gcvt.3 b/man3/gcvt.3 new file mode 100644 index 000000000..7d7c7aa2c --- /dev/null +++ b/man3/gcvt.3 @@ -0,0 +1,49 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:32:25 1993 by Rik Faith (faith@cs.unc.edu) +.TH GCVT 3 1993-03-29 "" "Linux Programmer's Manual" +.SH NAME +gcvt \- convert a floating-point number to a string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *gcvt(double " number ", size_t " ndigit ", char *" buf ); +.fi +.SH DESCRIPTION +The \fBgcvt()\fP function converts \fInumber\fP to a minimal length NULL +terminated ASCII string and stores the result in \fIbuf\fP. It produces +\fIndigit\fP significant digits in either +.BR printf (3) +F format or E format. +.SH "RETURN VALUE" +The \fBgcvt()\fP function returns the address of the string pointed to +by \fIbuf\fP. +.SH "SEE ALSO" +.BR ecvt (3), +.BR fcvt (3), +.BR sprintf (3) diff --git a/man3/get_current_dir_name.3 b/man3/get_current_dir_name.3 new file mode 100644 index 000000000..f73c1579c --- /dev/null +++ b/man3/get_current_dir_name.3 @@ -0,0 +1 @@ +.so man3/getcwd.3 diff --git a/man3/get_myaddress.3 b/man3/get_myaddress.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/get_myaddress.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/getaddrinfo.3 b/man3/getaddrinfo.3 new file mode 100644 index 000000000..eb48aeeb4 --- /dev/null +++ b/man3/getaddrinfo.3 @@ -0,0 +1,308 @@ +.\" Copyright 2000 Sam Varshavchik +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References: RFC 2553 +.TH getaddrinfo 3 2000-12-18 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +getaddrinfo, freeaddrinfo, gai_strerror \- network address and service translation +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.sp +.BI "int getaddrinfo(const char *" "node" ", const char *" "service" , +.BI " const struct addrinfo *" "hints" , +.BI " struct addrinfo **" "res" ); +.sp +.BI "void freeaddrinfo(struct addrinfo *" "res" ); +.sp +.BI "const char *gai_strerror(int " "errcode" ); +.fi +.SH DESCRIPTION +The +.BR getaddrinfo (3) +function combines the functionality provided by the +.BR getipnodebyname (3), +.BR getipnodebyaddr (3), +.BR getservbyname (3), +and +.BR getservbyport (3) +functions into a single interface. +The thread-safe +.BR getaddrinfo (3) +function creates one or more socket address structures that can be used by the +.BR bind (2) +and +.BR connect (2) +system calls to create a client or a server socket. +.PP +The +.BR getaddrinfo (3) +function is not limited to creating IPv4 socket address structures; +IPv6 socket address structures can be created if IPv6 support is available. +These socket address structures can be used directly by +.BR bind (2) +or +.BR connect (2), +to prepare a client or a server socket. +.PP +The +.B addrinfo +structure used by this function contains the following members: +.sp +.nf +.B struct addrinfo { +.BI " int " "ai_flags" ";" +.BI " int " "ai_family" ";" +.BI " int " "ai_socktype" ";" +.BI " int " "ai_protocol" ";" +.BI " size_t " "ai_addrlen" ";" +.BI " struct sockaddr *" "ai_addr" ";" +.BI " char *" "ai_canonname" ";" +.BI " struct addrinfo *" "ai_next" ";" +.B }; +.fi +.PP +.BR getaddrinfo (3) +sets +.I res +to point to a dynamically-allocated link list of +.B addrinfo +structures, linked by the +.I ai_next +member. +There are several reasons why +the link list may have more than one +.B addrinfo +structure, including: if the network host is +multi-homed; or if the same service +is available from multiple socket protocols (one +.B SOCK_STREAM +address and another +.B SOCK_DGRAM +address, for example). +.PP +The members +.IR ai_family , +.IR ai_socktype , +and +.I ai_protocol +have the same meaning as the corresponding parameters in the +.BR socket (2) +system call. +The +.BR getaddrinfo (3) +function returns socket addresses in either IPv4 or IPv6 +address family, +.RI "(" "ai_family" +will be set to either +.B PF_INET +or +.BR PF_INET6 ). +.PP +The +.I hints +parameter specifies +the preferred socket type, or protocol. +A NULL +.I hints +specifies that any network address or protocol is acceptable. +If this parameter is not +.B NULL +it points to an +.B addrinfo +structure +whose +.IR ai_family , +.IR ai_socktype , +and +.I ai_protocol +members specify the preferred socket type. +.B PF_UNSPEC +in +.I ai_family +specifies any protocol family (either IPv4 or IPv6, for example). +0 in +.I ai_socktype +or +.I ai_protocol +specifies that any socket type or protocol is acceptable as well. +The +.I ai_flags +member +specifies additional options, defined below. +Multiple flags are specified by logically OR-ing them together. +All the other members in the +.I hints +parameter must contain either 0, or a null pointer. +.PP +The +.I node +or +.I service +parameter, but not both, may be NULL. +.I node +specifies either a numerical network address +(dotted-decimal format for IPv4, hexadecimal format for IPv6) +or a network hostname, whose network addresses are looked up and resolved. +If the +.I ai_flags +member in the +.I hints +parameter contains the +.B AI_NUMERICHOST +flag then the +.I node +parameter must be a numerical network address. +The +.B AI_NUMERICHOST +flag suppresses any potentially lengthy network host address lookups. +.PP +The +.BR getaddrinfo (3) +function creates a link list of +.B addrinfo +structures, one for each network address subject to any restrictions +imposed by the +.I hints +parameter. +.I ai_canonname +is set to point to the official name of the host, if +.I ai_flags +in +.I hints +includes the +.B AI_CANONNAME +flag. +.IR ai_family , +.IR ai_socktype , +and +.I ai_protocol +specify the socket creation parameters. +A pointer to the socket address is placed in the +.I ai_addr +member, and the length of the socket address, in bytes, +is placed in the +.I ai_addrlen +member. +.PP +If +.I node +is NULL, +the +network address in each socket structure is initialized according to the +.B AI_PASSIVE +flag, which is set in the +.I ai_flags +member of the +.I hints +parameter. +The network address in each socket structure will be left unspecified +if +.B AI_PASSIVE +flag is set. +This is used by server applications, which intend to accept +client connections on any network address. +The network address will be set to the loopback interface address +if the +.B AI_PASSIVE +flag is not set. +This is used by client applications, which intend to connect +to a server running on the same network host. +.PP +.I service +sets the port number in the network address of each socket structure. +If +.I service +is NULL the port number will be left uninitialized. +.PP +The +.BR freeaddrinfo (3) +function frees the memory that was allocated +for the dynamically allocated link list +.IR res . +.SH "RETURN VALUE" +.BR getaddrinfo (3) +returns 0 if it succeeds, or one of the following non-zero error codes: +.TP +.B EAI_FAMILY +The requested address family is not supported at all. +.TP +.B EAI_SOCKTYPE +The requested socket type is not supported at all. +.TP +.B EAI_BADFLAGS +.I ai_flags +contains invalid flags. +.TP +.B EAI_NONAME +The +.I node +or +.I service +is not known. +This error is also returned if both +.I node +and +.I service +are NULL. +.TP +.B EAI_SERVICE +The requested service is not available for the requested socket type. +It may be available through another socket type. +.TP +.B EAI_ADDRFAMILY +The specified network host does not have any network addresses in the +requested address family. +.TP +.B EAI_NODATA +The specified network host exists, but does not have any +network addresses defined. +.TP +.B EAI_MEMORY +Out of memory. +.TP +.B EAI_FAIL +The name server returned a permanent failure indication. +.TP +.B EAI_AGAIN +The name server returned a temporary failure indication. +Try again later. +.TP +.B EAI_SYSTEM +Other system error, check +.I errno +for details. +.PP +The +.BR gai_strerror (3) +function translates these error codes to a human readable string, +suitable for error reporting. +.SH "CONFORMING TO" +POSIX 1003.1-2003. +The +.B getaddrinfo() +function is documented in RFC 2553. +.SH "SEE ALSO" +.BR getipnodebyaddr (3), +.BR getipnodebyname (3) diff --git a/man3/getaliasbyname.3 b/man3/getaliasbyname.3 new file mode 100644 index 000000000..37dcf1914 --- /dev/null +++ b/man3/getaliasbyname.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man3/getaliasbyname_r.3 b/man3/getaliasbyname_r.3 new file mode 100644 index 000000000..37dcf1914 --- /dev/null +++ b/man3/getaliasbyname_r.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man3/getaliasent.3 b/man3/getaliasent.3 new file mode 100644 index 000000000..37dcf1914 --- /dev/null +++ b/man3/getaliasent.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man3/getaliasent_r.3 b/man3/getaliasent_r.3 new file mode 100644 index 000000000..37dcf1914 --- /dev/null +++ b/man3/getaliasent_r.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man3/getc.3 b/man3/getc.3 new file mode 100644 index 000000000..4636db712 --- /dev/null +++ b/man3/getc.3 @@ -0,0 +1 @@ +.so man3/gets.3 diff --git a/man3/getc_unlocked.3 b/man3/getc_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/getc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/getchar.3 b/man3/getchar.3 new file mode 100644 index 000000000..4636db712 --- /dev/null +++ b/man3/getchar.3 @@ -0,0 +1 @@ +.so man3/gets.3 diff --git a/man3/getchar_unlocked.3 b/man3/getchar_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/getchar_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/getcwd.3 b/man3/getcwd.3 new file mode 100644 index 000000000..473c3255c --- /dev/null +++ b/man3/getcwd.3 @@ -0,0 +1,176 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Wed Jul 21 22:35:42 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 18 Mar 1996 by Martin Schulze (joey@infodrom.north.de): +.\" Corrected description of getwd(). +.\" Modified Sat Aug 21 12:32:12 MET 1999 by aeb - applied fix by aj +.\" Modified Mon Dec 11 13:32:51 MET 2000 by aeb +.\" Modified Thu Apr 22 03:49:15 CEST 2002 by Roger Luethi +.\" +.TH GETCWD 3 2002-04-22 "GNU" "Linux Programmer's Manual" +.SH NAME +getcwd, get_current_dir_name, getwd \- Get current working directory +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *getcwd(char *" buf ", size_t " size ); +.B "char *get_current_dir_name(void);" +.BI "char *getwd(char *" buf ); +.fi +.SH DESCRIPTION +The +.BR getcwd () +function copies an absolute pathname of the current working directory +to the array pointed to by +.IR buf , +which is of length +.IR size . +.PP +If the current absolute path name would require a buffer longer than +.I size +elements, +.B NULL +is returned, and +.I errno +is set to +.BR ERANGE ; +an application should check for this error, and allocate a larger +buffer if necessary. +.PP +If +.I buf +is NULL, the behaviour of +.BR getcwd () +is undefined. +.PP +As an extension to the POSIX.1 standard, Linux (libc4, libc5, glibc) +.B getcwd() +allocates the buffer dynamically using +.B malloc() +if +.I buf +is +.B NULL +on call. In this case, the allocated buffer has the length +.I size +unless +.I size +is zero, when +.I buf +is allocated as big as necessary. It is possible (and, indeed, +advisable) to +.B free() +the buffers if they have been obtained this way. + +.BR get_current_dir_name , +which is only prototyped if +.B _GNU_SOURCE +is defined, will +.BR malloc (3) +an array big enough to hold the current directory name. If the environment +variable +.B PWD +is set, and its value is correct, then that value will be returned. + +.BR getwd , +which is only prototyped if +.B _BSD_SOURCE +or +.B _XOPEN_SOURCE_EXTENDED +is defined, will not +.BR malloc (3) +any memory. The +.I buf +argument should be a pointer to an array at least +.B PATH_MAX +bytes long. +.BR getwd +does only return the first +.B PATH_MAX +bytes of the actual pathname. +Note that +.B PATH_MAX +need not be a compile-time constant; it may depend on the filesystem +and may even be unlimited. For portability and security reasons, use of +.B getwd +is deprecated. +.SH "RETURN VALUE" +.B NULL +on failure with +.I errno +set accordingly, and +.I buf +on success. The contents of the array pointed to by +.IR buf +is undefined on error. +.SH ERRORS +.TP +.B EACCES +Permission to read or search a component of the file name was denied. +.TP +.B EFAULT +.IR buf +points to a bad address. +.TP +.B EINVAL +The +.IR size +argument is zero and +.IR buf +is not a null pointer. +.TP +.B ENOENT +The current working directory has been unlinked. +.TP +.B ERANGE +The +.IR size +argument is less than the length of the working directory name. +You need to allocate a bigger array and try again. +.SH NOTES +Under Linux, the function +.BR getcwd () +is a system call (since 2.1.92). +On older systems it would query +.IR /proc/self/cwd . +If both system call and proc file system are missing, a +generic implementation is called. Only in that case can +these calls fail under Linux with +.BR EACCES . +.LP +These functions are often used to save the location of the current working +directory for the purpose of returning to it later. Opening the current +directory (".") and calling +.BR fchdir (2) +to return is usually a faster and more reliable alternative when sufficiently +many file descriptors are available, especially on platforms other than Linux. +.SH "CONFORMING TO" +POSIX.1 +.SH "SEE ALSO" +.BR chdir (2), +.BR fchdir (2), +.BR open (2), +.BR unlink (2), +.BR free (3), +.BR malloc (3) diff --git a/man3/getdate.3 b/man3/getdate.3 new file mode 100644 index 000000000..5743ffaa9 --- /dev/null +++ b/man3/getdate.3 @@ -0,0 +1,173 @@ +.\" Copyright 2001 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified, 2001-12-26, aeb +.TH GETDATE 3 2001-12-26 "" "Linux Programmer's Manual" +.SH NAME +getdate() \- convert a string to struct tm +.br +.SH SYNOPSIS +.B "#define _XOPEN_SOURCE" +.br +.B "#define _XOPEN_SOURCE_EXTENDED +.br +.B "#include " +.sp +.BI "struct tm *getdate (const char *" string ); +.sp +.BI "extern int getdate_err;" +.sp 2 +.B "#define _GNU_SOURCE" +.br +.B "#include " +.sp +.BI "int getdate_r (const char *" string ", struct tm *" res ); +.br +.SH DESCRIPTION +The function +.B getdate() +converts a string pointed to by +.I string +into the tm structure that it returns. +This tm structure may be found in static storage, so that +it will be overwritten by the next call. + +In contrast to +.BR strptime (3), +(which has a +.I format +argument), +.B getdate() +uses the formats found in the file +of which the full path name is given in the environment variable +.BR DATEMSK . +The first line in the file that matches the given input string +is used for the conversion. + +The matching is done case insensitively. +Superfluous whitespace, either in the pattern or in the string to +be converted, is ignored. + +The conversion specifications that a pattern can contain are those given for +.BR strptime (3). +One more conversion specification is accepted: +.TP +.B %Z +Timezone name. +.LP +When +.B %Z +is given, the value to be returned is initialised to the broken-down time +corresponding to the current time in the given time zone. +Otherwise, it is initialised to the broken-down time corresponding to +the current local time. +.LP +When only the weekday is given, the day is taken to be the first such day +on or after today. +.LP +When only the month is given (and no year), the month is taken to +be the first such month equal to or after the current month. +If no day is given, it is the first day of the month. +.LP +When no hour, minute and second are given, the current +hour, minute and second are taken. +.LP +If no date is given, but we know the hour, then that hour is taken +to be the first such hour equal to or after the current hour. +.SH "RETURN VALUE" +When successful, this function returns a pointer to a +.BR "struct tm" . +Otherwise, it returns NULL and sets the global variable +.BR getdate_err . +Changes to +.I errno +are unspecified. The following values for +.B getdate_err +are defined: +.TP 4n +.B 1 +The DATEMSK environment variable is null or undefined. +.TP +.B 2 +The template file cannot be opened for reading. +.TP +.B 3 +Failed to get file status information. +.TP +.B 4 +The template file is not a regular file. +.TP +.B 5 +An error is encountered while reading the template file. +.TP +.B 6 +Memory allocation failed (not enough memory available). +.TP +.B 7 +There is no line in the file that matches the input. +.TP +.B 8 +Invalid input specification. +.SH NOTES +Since +.B getdate() +is not reentrant because of the use of +.B getdate_err +and the static buffer to return the result in, glibc provides a +thread-safe variant. The functionality is the same. The result +is returned in the buffer pointed to by +.I res +and in case of an error the return value is nonzero with the same +values as given above for +.IR getdate_err . +.LP +The POSIX 1003.1-2001 specification for +.B strptime() +contains conversion specifications using the +.B %E +or +.B %O +modifier, while such specifications are not given for +.BR getdate() . +The glibc implementation implements +.B getdate() +using +.B strptime() +so that automatically precisely the same conversions are supported by both. +.LP +The glibc implementation does not support the +.B %Z +conversion specification. +.SH ENVIRONMENT +.TP +.B DATEMSK +File containing format patterns. +.TP +.BR TZ ", " LC_TIME +Variables used by \fBstrptime()\fP. +.SH "CONFORMING TO" +ISO 9899, POSIX 1003.1-2001 +.SH "SEE ALSO" +.BR localtime (3), +.BR strftime (3), +.BR strptime (3), +.BR time (3) diff --git a/man3/getdate_r.3 b/man3/getdate_r.3 new file mode 100644 index 000000000..c78ed340c --- /dev/null +++ b/man3/getdate_r.3 @@ -0,0 +1 @@ +.so man3/getdate.3 diff --git a/man3/getdelim.3 b/man3/getdelim.3 new file mode 100644 index 000000000..caf4e4894 --- /dev/null +++ b/man3/getdelim.3 @@ -0,0 +1 @@ +.so man3/getline.3 diff --git a/man3/getdirentries.3 b/man3/getdirentries.3 new file mode 100644 index 000000000..d83242ba3 --- /dev/null +++ b/man3/getdirentries.3 @@ -0,0 +1,61 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Portions extracted from /usr/include/dirent.h are: +.\" Copyright 1991, 1992 Free Software Foundation +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH GETDIRENTRIES 3 1993-07-22 "BSD/MISC" "Linux Programmer's Manual" +.SH NAME +getdirentries \- get directory entries in a filesystem independent format +.SH SYNOPSIS +.B #define _BSD_SOURCE +or +.B #define _SVID_SOURCE +.br +.B #include +.sp +.BI "ssize_t getdirentries(int " fd ", char *" buf ", size_t " nbytes +.BI ", off_t *" basep ); +.SH DESCRIPTION +Read directory entries from the directory specified by +.I fd +into +.IR buf . +At most +.I nbytes +are read. Reading starts at offset +.RI * basep , +and +.RI * basep +is updated with the new position after reading. +.SH "RETURN VALUE" +.B getdirentries +returns the number of bytes read or zero when at the end of the directory. +If an error occurs, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +See the Linux library source code for details. +.SH "SEE ALSO" +.BR lseek (2), +.BR open (2) diff --git a/man3/getenv.3 b/man3/getenv.3 new file mode 100644 index 000000000..e614d499a --- /dev/null +++ b/man3/getenv.3 @@ -0,0 +1,53 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:30:29 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH GETENV 3 1993-04-03 "GNU" "Linux Programmer's Manual" +.SH NAME +getenv \- get an environment variable +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *getenv(const char *" name ); +.fi +.SH DESCRIPTION +The \fBgetenv()\fP function searches the environment list for a string +that matches the string pointed to by \fIname\fP. The strings are of +the form \fIname = value\fP. +.SH "RETURN VALUE" +The \fBgetenv()\fP function returns a pointer to the value in the +environment, or NULL if there is no match. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899 +.SH "SEE ALSO" +.BR clearenv (3), +.BR putenv (3), +.BR setenv (3), +.BR unsetenv (3), +.BR environ (5) diff --git a/man3/getfsent.3 b/man3/getfsent.3 new file mode 100644 index 000000000..0436d2f97 --- /dev/null +++ b/man3/getfsent.3 @@ -0,0 +1,128 @@ +.\" Copyright (C) 2002 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Inspired by a page written by Walter Harms. +.\" +.TH GETFSENT 3 2002-02-28 "Linux 2.5" "Linux Programmer's Manual" +.SH NAME +getfsent, getfsspec, getfsfile, setfsent, endfsent \- handle fstab entries +.SH SYNOPSIS +.B #include +.sp +.BI "void endfsent(void);" +.sp +.BI "struct fstab *getfsent(void);" +.sp +.BI "struct fstab *getfsfile(const char *" mount_point ); +.sp +.BI "struct fstab *getfsspec(const char *" special_file ); +.sp +.BI "int setfsent(void);" +.SH DESCRIPTION +These functions read from the file +.IR /etc/fstab . +The struct fstab is defined by +.LP +.nf +struct fstab { + char *fs_spec; /* block device name */ + char *fs_file; /* mount point */ + char *fs_vfstype; /* filesystem type */ + char *fs_mntops; /* mount options */ + const char *fs_type; /* rw/rq/ro/sw/xx option */ + int fs_freq; /* dump frequency, in days */ + int fs_passno; /* pass number on parallel dump */ +}; +.fi +Here the field +.I fs_type +contains (on a *BSD system) +one of the five strings "rw", "rq", "ro", "sw", "xx" +(read-write, read-write with quota, read-only, swap, ignore). + +The function +.B setfsent() +opens the file when required and positions it at the first line. +.LP +The function +.B getfsent() +parses the next line from the file. +(After opening it when required.) +.LP +The function +.B endfsent() +closes the file when required. +.LP +The function +.B getfsspec() +searches the file from the start and returns the first entry found +for which the +.I fs_spec +field matches the +.I special_file +argument. +.LP +The function +.B getfsfile() +searches the file from the start and returns the first entry found +for which the +.I fs_file +field matches the +.I mount_point +argument. +.SH "RETURN VALUE" +Upon success, the functions +.BR getfsent() , +.BR getfsfile() , +and +.BR getfsspec() +return a pointer to a struct fstab, while +.BR setfsent() +returns 1. +Upon failure or end-of-file, these functions return NULL and 0, respectively. +.SH HISTORY +The +.B getfsent() +function appeared in 4.0BSD; the other four functions appeared in 4.3BSD. +.SH "CONFORMING TO" +These functions are not in POSIX. Several operating systems have them, +e.g., *BSD, SunOS, Digital Unix, AIX (which also has a +.IR getfstype() ). +HP-UX has functions of the same names, that however use a struct checklist +instead of a struct fstab, and calls these functions obsolete, superseded by +.BR getmntent (3). +.SH NOTES +These functions are not thread-safe. +.LP +Since Linux allows mounting a block special device in several places, +and since several devices can have the same mount point, where the +last device with a given mount point is the interesting one, +while +.B getfsfile() +and +.B getfsspec() +only return the first occurrence, these two functions are not suitable +for use under Linux. +.LP +.SH "SEE ALSO" +.BR getmntent (3), +.BR fstab (5) diff --git a/man3/getfsfile.3 b/man3/getfsfile.3 new file mode 100644 index 000000000..1e6a3eb7e --- /dev/null +++ b/man3/getfsfile.3 @@ -0,0 +1 @@ +.so man3/getfsent.3 diff --git a/man3/getfsspec.3 b/man3/getfsspec.3 new file mode 100644 index 000000000..1e6a3eb7e --- /dev/null +++ b/man3/getfsspec.3 @@ -0,0 +1 @@ +.so man3/getfsent.3 diff --git a/man3/getgrent.3 b/man3/getgrent.3 new file mode 100644 index 000000000..c86de5c25 --- /dev/null +++ b/man3/getgrent.3 @@ -0,0 +1,100 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:29:54 1993 by Rik Faith (faith@cs.unc.edu) +.TH GETGRENT 3 1993-04-04 "" "Linux Programmer's Manual" +.SH NAME +getgrent, setgrent, endgrent \- get group file entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.sp +.B struct group *getgrent(void); +.sp +.B void setgrent(void); +.sp +.B void endgrent(void); +.fi +.SH DESCRIPTION +The \fBgetgrent()\fP function returns a pointer to a structure containing +the group information from \fI/etc/group\fP. The first time it is called +it returns the first entry; thereafter, it returns successive entries. +.PP +The \fBsetgrent()\fP function rewinds the file pointer to the beginning +of the \fI/etc/group\fP file. +.PP +The \fBendgrent()\fP function closes the \fI/etc/group\fP file. +.PP +The \fIgroup\fP structure is defined in \fI\fP as follows: +.sp +.RS +.nf +.ta 8n 16n 32n +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group id */ + char **gr_mem; /* group members */ +}; +.ta +.fi +.RE +.SH "RETURN VALUE" +The \fBgetgrent()\fP function returns the group information structure, +or NULL if there are no more entries or an error occurs. +.LP +Upon error, +.I errno +may be set. If you want to check its value, set it to zero before the call. +.SH ERRORS +.TP +.B EINTR +A signal was caught. +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The calling process already has too many open files. +.TP +.B ENFILE +Too many open files in the system. +.TP +.\" not in POSIX +.B ENOMEM +Insufficient memory to allocate group information structure. +.SH FILES +.TP +.I /etc/group + group database file +.SH "CONFORMING TO" +SVID 3, BSD 4.3, POSIX 1003.1-2003. +.SH "SEE ALSO" +.BR fgetgrent (3), +.BR getgrent_r (3), +.BR getgrgid (3), +.BR getgrnam (3) diff --git a/man3/getgrent_r.3 b/man3/getgrent_r.3 new file mode 100644 index 000000000..56a5d5feb --- /dev/null +++ b/man3/getgrent_r.3 @@ -0,0 +1,171 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH GETGRENT 3 2003-11-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getgrent_r, fgetgrent_r \- get group file entry reentrantly +.SH SYNOPSIS +.nf +.B "#define _GNU_SOURCE" +.br +.B #include +.sp +.BI "int getgrent_r(struct group *" gbuf ", char *" buf , +.br +.BI " size_t " buflen ", struct group **" gbufp ); +.sp +.BI "int fgetgrent_r(FILE *" fp ", struct group *" gbuf ", char *" buf , +.br +.BI " size_t " buflen ", struct group **" gbufp ); +.SH DESCRIPTION +The functions +.B getgrent_r() +and +.B fgetgrent_r() +are the reentrant versions of +.BR getgrent (3) +and +.BR fgetgrent (3). +The former reads the next group entry from the stream initialized by +.BR setgrent (3). +The latter reads the next group entry from the stream +.I fp +given as parameter. +.PP +The \fIgroup\fP structure is defined in +.I +as follows: +.sp +.RS +.nf +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group id */ + char **gr_mem; /* group members */ +}; +.ta +.fi +.RE +.sp +The non-reentrant functions return a pointer to static storage, +where this static storage contains further pointers to group +name, password and members. +The reentrant functions described here return all of that in +caller-provided buffers. First of all there is the buffer +.I gbuf +that can hold a struct group. And next the buffer +.I buf +of size +.I buflen +that can hold additional strings. +The result of these functions, the struct group read from the stream, +is stored in the provided buffer +.RI * gbuf , +and a pointer to this struct group is returned in +.RI * gbufp . +.SH "RETURN VALUE" +On success, these functions return 0 and +.RI * gbufp +is a pointer to the struct group. +On error, these functions return an error value and +.RI * gbufp +is NULL. +.SH ERRORS +.TP +.B ENOENT +No more entries. +.TP +.B ERANGE +Insufficient buffer space supplied. Try again with larger buffer. +.SH EXAMPLE +.nf +#define _GNU_SOURCE +#include +#include +#define BUFLEN 4096 + +int main() { + struct group grp, *grpp; + char buf[BUFLEN]; + int i; + + setgrent(); + while (1) { + i = getgrent_r(&grp, buf, BUFLEN, &grpp); + if (i) + break; + printf("%s (%d):", grpp->gr_name, grpp->gr_gid); + for (i = 0; ; i++) { + if (grpp->gr_mem[i] == NULL) + break; + printf(" %s", grpp->gr_mem[i]); + } + printf("\en"); + } + endgrent(); + return 0; +} +.fi +.\" perhaps add error checking - should use strerror_r +.\" #include +.\" #include +.\" if (i) { +.\" if (i == ENOENT) +.\" break; +.\" printf("getgrent_r: %s", strerror(i)); +.\" exit(1); +.\" } +.SH "CONFORMING TO" +These functions are GNU extensions, done in a style resembling +the POSIX version of functions like +.BR getpwnam_r (3). +Other systems use prototype +.sp +.nf +.in +4 +struct group * +getgrent_r(struct group *grp, char *buf, int buflen); +.in +.fi +.sp +or, better, +.sp +.nf +.in +4 +int +getgrent_r(struct group *grp, char *buf, int buflen, + FILE **gr_fp); +.in +.fi +.sp +.SH NOTES +The function +.B getgrent_r() +is not really reentrant since it shares the reading position +in the stream with all other threads. +.SH "SEE ALSO" +.BR fgetgrent (3), +.BR getgrent (3), +.BR getgrgid (3), +.BR getgrnam (3), +.BR group (5) diff --git a/man3/getgrgid.3 b/man3/getgrgid.3 new file mode 100644 index 000000000..f9a97b451 --- /dev/null +++ b/man3/getgrgid.3 @@ -0,0 +1 @@ +.so man3/getgrnam.3 diff --git a/man3/getgrgid_r.3 b/man3/getgrgid_r.3 new file mode 100644 index 000000000..f9a97b451 --- /dev/null +++ b/man3/getgrgid_r.3 @@ -0,0 +1 @@ +.so man3/getgrnam.3 diff --git a/man3/getgrnam.3 b/man3/getgrnam.3 new file mode 100644 index 000000000..6e5bfe250 --- /dev/null +++ b/man3/getgrnam.3 @@ -0,0 +1,176 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2003-11-15 by aeb +.\" +.TH GETGRNAM 3 2003-11-15 "" "Linux Programmer's Manual" +.SH NAME +getgrnam, getgrnam_r, getgrgid, getgrgid_r \- get group file entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.sp +.BI "struct group *getgrnam(const char *" name ); +.sp +.BI "struct group *getgrgid(gid_t " gid ); +.sp +.BI "int getgrnam_r(const char *" name ", struct group *" gbuf , +.br +.BI " char *" buf ", size_t " buflen ", struct group **" gbufp ); +.sp +.BI "int getgrgid_r(gid_t " gid ", struct group *" gbuf , +.br +.BI " char *" buf ", size_t " buflen ", struct group **" gbufp ); +.fi +.SH DESCRIPTION +The +.B getgrnam() +function returns a pointer to a structure containing +the group information from +.I /etc/group +for the entry that matches the group name +.IR name . +.PP +The +.B getgrgid() +function returns a pointer to a structure containing +the group information from +.I /etc/group +for the entry that matches the group gid +.IR gid . +.PP +The +.B getgrnam_r() +and +.B getgrgid_r() +functions find the same information, but store the retrieved group structure +in the space pointed to by +.IR gbuf . +This group structure contains pointers to strings, and these strings +are stored in the buffer +.I buf +of size +.IR buflen . +A pointer to the result (in case of success) or NULL (in case no entry +was found or an error occurred) is stored in +.RI * gbufp . +.PP +The \fIgroup\fP structure is defined in \fI\fP as follows: +.sp +.RS +.nf +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group id */ + char **gr_mem; /* group members */ +}; +.fi +.RE +.PP +The maximum needed size for +.I buf +can be found using +.BR sysconf (3) +with the _SC_GETGR_R_SIZE_MAX parameter. +.SH "RETURN VALUE" +The \fBgetgrnam()\fP and \fBgetgrgid()\fP functions return a pointer +to the group information structure, or NULL if the matching entry +is not found or an error occurs. If an error occurs, +.I errno +is set appropriately. If one wants to check +.I errno +after the call, it should be set to zero before the call. +.LP +The return value may point to static area, and may be overwritten +by subsequent calls to +.BR getgrent() , +.BR getgrgid() , +or +.BR getgrnam() . +.LP +The \fBgetgrnam_r()\fP and \fBgetgrgid_r()\fP functions return +zero on success. In case of error, an error value is returned. +.SH ERRORS +.TP +.BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ... " +The given +.I name +or +.I gid +was not found. +.TP +.B EINTR +A signal was caught. +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The maximum number (OPEN_MAX) of files was open already in the calling process. +.TP +.B ENFILE +The maximum number of files was open already in the system. +.TP +.B ENOMEM +Insufficient memory. +.\" to allocate the group structure, or to allocate buffers +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/group +group database file +.SH "CONFORMING TO" +SVID 3, BSD 4.3, POSIX 1003.1-2003 +.SH NOTES +The formulation given above under "RETURN VALUE" is from POSIX 1003.1-2001. +It does not call "not found" an error, hence does not specify what value +.I errno +might have in this situation. But that makes it impossible to recognize +errors. One might argue that according to POSIX +.I errno +should be left unchanged if an entry is not found. Experiments on various +Unix-like systems shows that lots of different values occur in this +situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM and probably others. +.\" more precisely: +.\" AIX 5.1 - gives ESRCH +.\" OSF1 4.0g - gives EWOULDBLOCK +.\" libc, glibc, Irix 6.5 - give ENOENT +.\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM +.\" SunOS 5.8 - gives EBADF +.\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0 +.SH "SEE ALSO" +.BR endgrent (3), +.BR fgetgrent (3), +.BR getgrent (3), +.BR getpwnam (3), +.BR setgrent (3), +.BR group (5) diff --git a/man3/getgrnam_r.3 b/man3/getgrnam_r.3 new file mode 100644 index 000000000..f9a97b451 --- /dev/null +++ b/man3/getgrnam_r.3 @@ -0,0 +1 @@ +.so man3/getgrnam.3 diff --git a/man3/getgrouplist.3 b/man3/getgrouplist.3 new file mode 100644 index 000000000..604fd84e1 --- /dev/null +++ b/man3/getgrouplist.3 @@ -0,0 +1,73 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" Thanks to glibc info pages +.\" +.\" Modified 2003-11-18, aeb: glibc is broken +.TH GETGROUPLIST 2 2003-11-18 "GNU" "Linux Programmer's Manual" +.SH NAME +getgrouplist \- list of groups a user belongs to +.SH SYNOPSIS +.sp +.B #include +.sp +.BI "int getgrouplist (const char *" user ", gid_t " group , +.in 25 +.BI "gid_t *" groups ", int *" ngroups ); +.SH DESCRIPTION +The +.B getgrouplist() +function scans the group database for all the groups +.I user +belongs to. Up to +.RI * ngroups +group IDs corresponding to these groups are stored in the array +.IR groups ; +the return value from the function is the number of group IDs +actually stored. The group +.I group +is automatically included in the list of groups returned by +.BR getgroup\%list() . +.SH "RETURN VALUE" +If +.RI * ngroups +is smaller than the total number of groups found, then +.B getgrouplist() +returns a value of `-1'. +In all cases the actual number of groups is stored in +.RI * ngroups . +.SH BUGS +The glibc 2.3.2 implementation of this function is broken: +it overwrites memory when the actual number of groups is larger than +.RI * ngroups . +.SH "CONFORMING TO" +This function is present since glibc 2.2.4. +.SH EXAMPLE +.nf +/* This crashes with glibc 2.3.2 */ +#include +#include +#include +#include + +int main() { + int i, ng = 0; + char *user = "who"; /* username here */ + gid_t *groups = NULL; + struct passwd *pw = getpwnam(user); + if (pw == NULL) + return 0; + + if (getgrouplist(user, pw->pw_gid, NULL, &ng) < 0) { + groups = (gid_t *) malloc(ng * sizeof (gid_t)); + getgrouplist(user, pw->pw_gid, groups, &ng); + } + + for(i = 0; i < ng; i++) + printf("%d\en", groups[i]); + + return 0; +} +.fi +.SH "SEE ALSO" +.BR getgroups (3), +.BR setgroups (3) diff --git a/man3/gethostbyaddr.3 b/man3/gethostbyaddr.3 new file mode 100644 index 000000000..7d0fb4b7c --- /dev/null +++ b/man3/gethostbyaddr.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/gethostbyname.3 b/man3/gethostbyname.3 new file mode 100644 index 000000000..1ec28fa16 --- /dev/null +++ b/man3/gethostbyname.3 @@ -0,0 +1,328 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-05-22, David Metcalfe +.\" Modified 1993-07-25, Rik Faith (faith@cs.unc.edu) +.\" Modified 1997-02-16, Andries Brouwer (aeb@cwi.nl) +.\" Modified 1998-12-21, Andries Brouwer (aeb@cwi.nl) +.\" Modified 2000-08-12, Andries Brouwer (aeb@cwi.nl) +.\" Modified 2001-05-19, Andries Brouwer (aeb@cwi.nl) +.\" Modified 2002-08-05, Michael Kerrisk +.\" Modified 2004-10-31, Andries Brouwer +.\" +.TH GETHOSTBYNAME 3 2004-10-31 "" "Linux Programmer's Manual" +.SH NAME +gethostbyname, gethostbyaddr, sethostent, gethostend, endhostent, +herror, hstrerror \- get network host entry +.SH SYNOPSIS +.nf +.B #include +.B extern int h_errno; +.sp +.BI "struct hostent *gethostbyname(const char *" name ); +.sp +.BR "#include " " /* for AF_INET */" +.BI "struct hostent *" +.br +.BI "gethostbyaddr(const void *" addr ", int " len ", int " type ); +.sp +.BI "void sethostent(int " stayopen ); +.sp +.B void endhostent(void); +.sp +.BI "void herror(const char *" s ); +.sp +.BI "const char *hstrerror(int " err ); +.sp 2 +/* SYSV/POSIX extension */ +.br +.B struct hostent *gethostent(void); +.sp 2 +/* GNU extensions */ +.br +.BI "struct hostent *gethostbyname2(const char *" name ", int " af ); +.sp +.BI "int gethostent_r(" +.BI " struct hostent *" ret ", char *" buf ", size_t " buflen , +.BI " struct hostent **" result ", int *" h_errnop ); +.sp +.BI "int gethostbyname_r(const char *" name , +.BI " struct hostent *" ret ", char *" buf ", size_t " buflen , +.BI " struct hostent **" result ", int *" h_errnop ); +.sp +.BI "int gethostbyname2_r(const char *" name ", int " af, +.BI " struct hostent *" ret ", char *" buf ", size_t " buflen , +.BI " struct hostent **" result ", int *" h_errnop ); +.fi +.SH DESCRIPTION +The +.BR gethostbyname () +function returns a structure of type +.I hostent +for the given host +.IR name . +Here +.I name +is either a host name, or an IPv4 address in standard dot notation, +or an IPv6 address in colon (and possibly dot) notation. +(See RFC 1884 for the description of IPv6 addresses.) +If +.I name +is an IPv4 or IPv6 address, no lookup is performed and +.BR gethostbyname () +simply copies +.I name +into the +.I h_name +field and its +.I struct in_addr +equivalent into the +.I h_addr_list[0] +field of the returned +.I hostent +structure. +If +.I name +doesn't end in a dot and the environment variable +.B HOSTALIASES +is set, the alias file pointed to by +.B HOSTALIASES +will first be searched for +.I name +(see +.BR hostname (7) +for the file format). +The current domain and its parents are searched unless \fIname\fP +ends in a dot. +.PP +The \fBgethostbyaddr()\fP function returns a structure of type \fIhostent\fP +for the given host address \fIaddr\fP of length \fIlen\fP and address type +\fItype\fP. Valid address types are +.B AF_INET +and +.BR AF_INET6 . +The host address argument is a pointer to a struct of a type depending +on the address type, for example a \fBstruct in_addr *\fP (probably +obtained via a call to \fIinet_addr()\fP) for address type AF_INET. +.PP +The \fBsethostent()\fP function specifies, if \fIstayopen\fP is true (1), +that a connected TCP socket should be used for the name server queries and +that the connection should remain open during successive queries. Otherwise, +name server queries will use UDP datagrams. +.PP +The \fBendhostent()\fP function ends the use of a TCP connection for name +server queries. +.PP +The (obsolete) \fBherror()\fP function prints the error message associated +with the current value of \fIh_errno\fP on stderr. +.PP +The (obsolete) \fBhstrerror()\fP function takes an error number +(typically \fIh_errno\fP) and returns the corresponding message string. +.PP +The domain name queries carried out by \fBgethostbyname()\fP and +\fBgethostbyaddr()\fP use a combination of any or all of the name server +.BR named (8), +a broken out line from \fI/etc/hosts\fP, and the Network +Information Service (NIS or YP), depending upon the contents of the +\fIorder\fP line in +.IR /etc/host.conf . +(See +.BR resolv+ (8)). +The default action is to query +.BR named (8), +followed by +.IR /etc/hosts . +.PP +The \fIhostent\fP structure is defined in \fI\fP as follows: +.sp +.RS +.nf +.ne 7 +.ta 8n 16n 32n +struct hostent { + char *h_name; /* official name of host */ + char **h_aliases; /* alias list */ + int h_addrtype; /* host address type */ + int h_length; /* length of address */ + char **h_addr_list; /* list of addresses */ +} +#define h_addr h_addr_list[0] /* for backward compatibility */ +.ta +.fi +.RE +.PP +The members of the \fIhostent\fP structure are: +.TP +.I h_name +The official name of the host. +.TP +.I h_aliases +A zero-terminated array of alternative names for the host. +.TP +.I h_addrtype +The type of address; always +.B AF_INET +or +.B AF_INET6 +at present. +.TP +.I h_length +The length of the address in bytes. +.TP +.I h_addr_list +A zero-terminated array of network addresses for the host in network byte +order. +.TP +.I h_addr +The first address in \fIh_addr_list\fP for backward compatibility. +.SH "RETURN VALUE" +The +.BR gethostbyname () +and +.BR gethostbyaddr() +functions return the +.I hostent +structure or a NULL pointer if an error occurs. On error, the +.I h_errno +variable holds an error number. +When non-NULL, the return value may point at static data, see the notes below. +.SH ERRORS +The variable \fIh_errno\fP can have the following values: +.TP +.B HOST_NOT_FOUND +The specified host is unknown. +.TP +.BR NO_ADDRESS " or " NO_DATA +The requested name is valid but does not have an IP address. +.TP +.B NO_RECOVERY +A non-recoverable name server error occurred. +.TP +.B TRY_AGAIN +A temporary error occurred on an authoritative name server. Try again +later. +.SH FILES +.TP +.I /etc/host.conf +resolver configuration file +.TP +.I /etc/hosts +host database file +.SH "CONFORMING TO" +BSD 4.3. +.SH "SYSV/POSIX EXTENSION" +POSIX requires the +.BR gethostent () +call, that should return the next entry in the host data base. +When using DNS/BIND this does not make much sense, but it may +be reasonable if the host data base is a file that can be read +line by line. On many systems a routine of this name reads +from the file +.IR /etc/hosts . +.\" e.g. Linux, FreeBSD, Unixware, HP-UX +It may be available only when the library was built without DNS support. +.\" e.g. FreeBSD, AIX +The glibc version will ignore ipv6 entries. This function is not reentrant, +and glibc adds a reentrant version +.BR gethostent_r (). +.SH "GNU EXTENSIONS" +Glibc2 also has a +.B gethostbyname2() +that works like +.BR gethostbyname() , +but permits to specify the address family to which the address must belong. +.LP +Glibc2 also has reentrant versions +.B gethostbyname_r() +and +.BR gethostbyname2_r() . +These return 0 on success and nonzero on error. The result of the call +is now stored in the struct with address +.IR ret . +After the call, +.RI * result +will be NULL on error or point to the result on success. +Auxiliary data is stored in the buffer +.I buf +of length +.IR buflen . +(If the buffer is too small, these functions will return +.BR ERANGE .) +No global variable +.I h_errno +is modified, but the address of a variable in which to store error numbers +is passed in +.IR h_errnop . +.SH NOTES +The functions +.BR gethostbyname () +and +.BR gethostbyaddr () +may return pointers to static data, which may be overwritten by +later calls. Copying the +.I struct hostent +does not suffice, since it contains pointers - a deep copy is required. +.LP +The SUS-v2 standard is buggy and declares the +.I len +parameter of +.B gethostbyaddr() +to be of type +.IR size_t . +(That is wrong, because it has to be +.IR int , +and +.I size_t +is not. POSIX 1003.1-2001 makes it +.IR socklen_t , +which is OK.) +.LP +The BSD prototype for +.B gethostbyaddr() +uses +.I const char * +for the first argument. +.LP +POSIX 1003.1-2001 marks +.B gethostbyaddr() +and +.B gethostbyname() +obsolescent. See +.BR getaddrinfo (3), +.BR getnameinfo (3), +.BR gai_strerror (3). +.SH "SEE ALSO" +.BR getaddrinfo (3), +.BR getipnodebyaddr (3), +.BR getipnodebyname (3), +.BR getnameinfo (3), +.BR inet_ntop (3), +.BR inet_pton (3), +.BR resolver (3), +.BR hosts (5), +.BR hostname (7), +.BR named (8), +.BR resolv+ (8) diff --git a/man3/gethostbyname2.3 b/man3/gethostbyname2.3 new file mode 100644 index 000000000..7d0fb4b7c --- /dev/null +++ b/man3/gethostbyname2.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/gethostbyname2_r.3 b/man3/gethostbyname2_r.3 new file mode 100644 index 000000000..7d0fb4b7c --- /dev/null +++ b/man3/gethostbyname2_r.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/gethostbyname_r.3 b/man3/gethostbyname_r.3 new file mode 100644 index 000000000..7d0fb4b7c --- /dev/null +++ b/man3/gethostbyname_r.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/gethostent.3 b/man3/gethostent.3 new file mode 100644 index 000000000..7d0fb4b7c --- /dev/null +++ b/man3/gethostent.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/gethostent_r.3 b/man3/gethostent_r.3 new file mode 100644 index 000000000..7d0fb4b7c --- /dev/null +++ b/man3/gethostent_r.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/getipnodebyaddr.3 b/man3/getipnodebyaddr.3 new file mode 100644 index 000000000..82e01df46 --- /dev/null +++ b/man3/getipnodebyaddr.3 @@ -0,0 +1 @@ +.so man3/getipnodebyname.3 diff --git a/man3/getipnodebyname.3 b/man3/getipnodebyname.3 new file mode 100644 index 000000000..264a39d3a --- /dev/null +++ b/man3/getipnodebyname.3 @@ -0,0 +1,262 @@ +.\" Copyright 2000 Sam Varshavchik +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References: RFC 2553 +.TH getipnodebyname 3 2002-04-03 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +getipnodebyname, getipnodebyaddr, freehostent \- get network host names and addresses +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.sp +.BI "struct hostent *getipnodebyname(const char *" "name" , +.BI " int " "af" ", int " "flags" , +.BI " int *" "error_num" ); +.sp +.BI "struct hostent *getipnodebyaddr(const void *" "addr" , +.BI " size_t " "len" ", int " "af" , +.BI " int *" "error_num" ); +.sp +.BI "void freehostent(struct hostent *" "ip" ); +.fi +.SH DESCRIPTION +These functions are deprecated. Use +.BR getaddrinfo (3) +and +.BR getnameinfo (3) +instead. +.LP +The +.BR getipnodebyname (3) +and +.BR getipnodebyaddr (3) +functions return the names and addresses of a network host. +These functions return a pointer to the +following structure: +.sp +.nf +.B struct hostent { +.BI " char *" "h_name" ";" +.BI " char **" "h_aliases" ";" +.BI " int " "h_addrtype" ";" +.BI " int " "h_length" ";" +.BI " char **" "h_addr_list" ";" +.BI "};" +.fi +.PP +These functions replace the +.BR gethostbyname (3) +and +.BR gethostbyaddr (3) +functions, which could only access the IPv4 network address family. +The +.BR getipnodebyname (3) +and +.BR getipnodebyaddr (3) +functions can access multiple network address families. +.PP +Unlike the +.B gethostby +functions, +these +functions return pointers to dynamically allocated memory. +The +.BR freehostent (3) +function is used to release the dynamically allocated memory +after the caller no longer needs the +.B hostent +structure. +.SS getipnodebyname parameters +The +.BR getipnodebyname (3) +function +looks up network addresses for the host +specified by the +.I name +parameter. +The +.I af +parameter specifies one of the following values: +.TP +.B AF_INET +The +.I name +parameter points to a dotted-quad IPv4 address or a name +of an IPv4 network host. +.TP +.B AF_INET6 +The +.I name +parameter points to a hexadecimal IPv6 address or a name +of an IPv6 network host. +.PP +The +.I flags +parameter specifies additional options. +More than one option can be specified by logically OR-ing +them together. +.I flags +should be set to 0 +if no options are desired. +.TP +.B AI_V4MAPPED +This flag is used with +.B AF_INET6 +to request a query for IPv4 addresses instead of +IPv6 addresses; the IPv4 addresses will +be mapped to IPv6 addresses. +.TP +.B AI_ALL +This flag is used with +.B AI_V4MAPPED +to request a query for both IPv4 and IPv6 addresses. +Any IPv4 address found will be mapped to an IPv6 address. +.TP +.B AI_ADDRCONFIG +This flag is used with +.B AF_INET6 +to +further request that queries for IPv6 addresses should not be made unless +the system has at least one IPv6 address assigned to a network interface, +and that queries for IPv4 addresses should not be made unless the +system has at least one IPv4 address assigned to a network interface. +This flag may be used by itself or with the +.B AI_V4MAPPED +flag. +.TP +.B AI_DEFAULT +This flag is equivalent to +.BR "(AI_ADDRCONFIG | AI_V4MAPPED)" . +.SS getipnodebyaddr parameters +The +.BR getipnodebyaddr (3) +function +looks up the name of the host whose +network address is +specified by the +.I addr +parameter. +The +.I af +parameter specifies one of the following values: +.TP +.B AF_INET +The +.I addr +parameter points to a +.B struct in_addr +and +.I len +must be set to +.BR "sizeof(struct in_addr)" . +.TP +.B AF_INET6 +The +.I addr +parameter points to a +.B struct in6_addr +and +.I len +must be set to +.BR "sizeof(struct in6_addr)" . +.SH "RETURN VALUE" +A null pointer is returned if an error occurred, and +.I error_num +will contain an error code from the following list: +.TP +.B HOST_NOT_FOUND +The host name or network address was not found. +.TP +.B NO_ADDRESS +The domain name server recognized the network address or name, +but no answer was returned. +This can happen if the network host has only IPv4 addresses and +a request has been made for IPv6 information only, or vice versa. +.TP +.B NO_RECOVERY +The domain name server returned a permanent failure response. +.TP +.B TRY_AGAIN +The domain name server returned a temporary failure response. +You might have better luck next time. +.PP +A successful query returns a pointer to a +.B hostent +structure that contains the following fields: +.TP +.B h_name +This is the official name of this network host. +.TP +.B h_aliases +This is an array of pointers to unofficial aliases for the same host. +The array is terminated by a null pointer. +.TP +.B h_addrtype +This is a copy of the +.I af +parameter to +.BR getipnodebyname (3) +or +.BR getipnodebyaddr (3). +.I h_addrtype +will always be +.B AF_INET +if the +.I af +parameter was +.BR AF_INET . +.I h_addrtype +will always be +.B AF_INET6 +if the +.I af +parameter was +.BR AF_INET6 . +.TP +.B h_length +This field will be set to +.B sizeof(struct in_addr) +if +.I h_addrtype +is AF_INET, and to +.B sizeof(struct in6_addr) +if +.I h_addrtype +is AF_INET6. +.TP +.B h_addr_list +This is an array of one or more pointers to network address structures for the +network host. +The array is terminated by a null pointer. +.SH NOTES +These functions have been present in glibc 2.1.91-95, but were +removed again. Several Unix-like systems support them, but all +call them deprecated. +.SH "CONFORMING TO" +RFC 2553. +.SH "SEE ALSO" +.BR getaddrinfo (3), +.BR getnameinfo (3), +.BR inet_ntop (3), +.BR inet_pton (3) diff --git a/man3/getline.3 b/man3/getline.3 new file mode 100644 index 000000000..5a51b141d --- /dev/null +++ b/man3/getline.3 @@ -0,0 +1,141 @@ +.\" Copyright (c) 2001 John Levon +.\" Based in part on GNU libc documentation +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.TH GETLINE 3 2001-10-07 "GNU" "Linux Programmer's Manual" +.SH NAME +getline, getdelim \- delimited string input +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include +.sp +.BI "ssize_t getline(char **" lineptr ", size_t *" n ", FILE *" stream ); +.nl +.BI "ssize_t getdelim(char **" lineptr ", size_t *" n ", int " delim ", FILE *" stream ); +.SH DESCRIPTION +.B getline() +reads an entire line, storing the address of the buffer containing +the text into +.IR "*lineptr". +The buffer is null-terminated and includes the newline character, if a +newline delimiter was found. + +.\" FIXME: what happens if *lineptr is NULL but *n isn't zero ? +.\" Answer: *n is ignored and a new buffer is allocated +If +.IR "*lineptr" +is +.BR "NULL", +the +.BR getline() +routine will allocate a buffer for containing the line, which must be freed +by the user program. +Alternatively, before calling +.BR "getline()", +.IR "*lineptr" +can contain a pointer to a +.BR "malloc()"\-allocated +buffer +.IR "*n" +bytes in size. If the buffer is not large enough to hold the line read in, +.B getline() +resizes the buffer to fit with +.BR "realloc()", +updating +.IR "*lineptr" +and +.IR "*n" +as necessary. In either case, on a successful call, +.IR "*lineptr" +and +.IR "*n" +will be updated to reflect the buffer address and size respectively. + +.BR getdelim() +works like +.BR "getline()", +except a line delimiter other than newline can be specified as the +.IR delimiter +argument. As with +.BR "getline()", +a delimiter character is not added if one was not present +in the input before end of file was reached. + +.SH "RETURN VALUE" +On success, +.B "getline()" +and +.B "getdelim()" +return the number of characters read, including the delimiter character, +but not including the terminating null character. This value can be used +to handle embedded null characters in the line read. + +Both functions return \-1 on failure to read a line (including end of file +condition). + +.SH ERRORS +.TP +.B EINVAL +Bad parameters +.RI ( n +or +.I lineptr +is NULL, or +.I stream +is not valid). + +.SH "EXAMPLE" +.nf +#define _GNU_SOURCE +#include +#include + +int main(void) +{ + FILE * fp; + char * line = NULL; + size_t len = 0; + ssize_t read; + fp = fopen("/etc/motd", "r"); + if (fp == NULL) + exit(EXIT_FAILURE); + while ((read = getline(&line, &len, fp)) != -1) { + printf("Retrieved line of length %zu :\en", read); + printf("%s", line); + } + if (line) + free(line); + return EXIT_SUCCESS; +} +.fi +.SH "CONFORMING TO" +Both getline() and getdelim() are GNU extensions. +They are available since libc 4.6.27. + +.SH "SEE ALSO" +.BR read (2), +.BR fgets (3), +.BR fopen (3), +.BR fread (3), +.BR gets (3), +.BR scanf (3) diff --git a/man3/getloadavg.3 b/man3/getloadavg.3 new file mode 100644 index 000000000..8a756f5b6 --- /dev/null +++ b/man3/getloadavg.3 @@ -0,0 +1,62 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getloadavg.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt GETLOADAVG 3 +.Os BSD 4.3 +.Sh NAME +.Nm getloadavg +.Nd get system load averages +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn getloadavg "double loadavg[]" "int nelem" +.Sh DESCRIPTION +The +.Fn getloadavg +function returns the number of processes in the system run queue +averaged over various periods of time. +Up to +.Fa nelem +samples are retrieved and assigned to successive elements of +.Fa loadavg Ns Bq . +The system imposes a maximum of 3 samples, representing averages +over the last 1, 5, and 15 minutes, respectively. +.Sh DIAGNOSTICS +If the load average was unobtainable, \-1 is returned; otherwise, +the number of samples actually retrieved is returned. +.Sh SEE ALSO +.Xr uptime 1 , +.Xr proc 5 +.Sh HISTORY +The +.Fn getloadavg +function appeared in +.Bx 4.3 Reno . +.\" mdoc seems to have a bug - there must be no newline here \ No newline at end of file diff --git a/man3/getlogin.3 b/man3/getlogin.3 new file mode 100644 index 000000000..aed1b80e7 --- /dev/null +++ b/man3/getlogin.3 @@ -0,0 +1,135 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1995 James R. Van Zandt +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Changed Tue Sep 19 01:49:29 1995, aeb: moved from man2 to man3 +.\" added ref to /etc/utmp, added BUGS section, etc. +.\" modified 2003 Walter Harms, aeb - added getlogin_r, note on stdin use +.TH GETLOGIN 3 2003-08-24 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +getlogin, getlogin_r, cuserid \- get user name +.SH SYNOPSIS +.B #include +.sp +.B "char *getlogin(void);" +.br +.BI "int getlogin_r(char *" buf ", size_t " bufsize ); +.sp +.B #include +.sp +.BI "char *cuserid(char *" string ); +.SH DESCRIPTION +\fBgetlogin\fP returns a pointer to a string containing the name of +the user logged in on the controlling terminal of the process, or a +null pointer if this information cannot be determined. The string is +statically allocated and might be overwritten on subsequent calls to +this function or to \fBcuserid\fP. +.PP +\fBgetlogin_r\fP returns this same user name in the array +.I buf +of size +.IR bufsize . +.PP +\fBcuserid\fP returns a pointer to a string containing a user name +associated with the effective user ID of the process. If \fIstring\fP +is not a null pointer, it should be an array that can hold at least +\fBL_cuserid\fP characters; the string is returned in this array. +Otherwise, a pointer to a string in a static area is returned. This +string is statically allocated and might be overwritten on subsequent +calls to this function or to \fBgetlogin\fP. +.PP +The macro \fBL_cuserid\fP is an integer constant that indicates how +long an array you might need to store a user name. \fBL_cuserid\fP is +declared in \fBstdio.h\fP. +.PP +These functions let your program identify positively the user who is +running (\fBcuserid\fP) or the user who logged in this session +(\fBgetlogin\fP). (These can differ when setuid programs are +involved.) +.PP +For most purposes, it is more useful to use the environment variable +\fBLOGNAME\fP to find out who the user is. This is more flexible +precisely because the user can set \fBLOGNAME\fP arbitrarily. +.SH "RETURN VALUE" +\fBgetlogin\fP returns a pointer to the user name when successful, +and NULL on failure. +\fBgetlogin_r\fP returns 0 when successful, and nonzero on failure. +.SH ERRORS +POSIX specifies +.TP +.B EMFILE +The calling process already has the maximum allowed number of open files. +.TP +.B ENFILE +The system already has the maximum allowed number of open files. +.TP +.B ENXIO +The calling process has no controlling tty. +.TP +.B ERANGE +(getlogin_r) +The length of the user name, including final NUL, is larger than +.IR bufsize . +.LP +Linux/glibc also has +.TP +.B ENOENT +There was no corresponding entry in the utmp-file. +.TP +.B ENOMEM +Insufficient memory to allocate passwd structure. +.SH FILES +.nf +\fI/etc/passwd\fP password database file +.br +\fI/var/run/utmp\fP (traditionally \fI/etc/utmp\fP; + some libc versions used \fI/var/adm/utmp\fP) +.fi +.SH "CONFORMING TO" +POSIX.1. System V has a \fBcuserid\fP function which uses the real +user ID rather than the effective user ID. The \fBcuserid\fP function +was included in the 1988 version of POSIX, but removed from the 1990 version. +.LP +OpenBSD has \fBgetlogin\fP and \fBsetlogin\fP, and a username +associated with a session, even if it has no controlling tty. +.SH BUGS +Unfortunately, it is often rather easy to fool getlogin(). +Sometimes it does not work at all, because some program messed up +the utmp file. Often, it gives only the first 8 characters of +the login name. The user currently logged in on the controlling tty +of our program need not be the user who started it. +Avoid getlogin() for security-related purposes. +.LP +Note that glibc does not follow the POSIX spec and uses stdin +instead of +.IR /dev/tty . +A bug. (Other recent systems, like SunOS 5.8 and HPUX 11.11 and FreeBSD 4.8 +all return the login name also when stdin is redirected.) +.LP +Nobody knows precisely what cuserid() does - avoid it in portable programs - +avoid it altogether - use getpwuid(geteuid()) instead, if that is +what you meant. +DO NOT USE cuserid(). +.SH "SEE ALSO" +.BR geteuid (2), +.BR getuid (2) diff --git a/man3/getlogin_r.3 b/man3/getlogin_r.3 new file mode 100644 index 000000000..b6d53bf72 --- /dev/null +++ b/man3/getlogin_r.3 @@ -0,0 +1 @@ +.so man3/getlogin.3 diff --git a/man3/getmntent.3 b/man3/getmntent.3 new file mode 100644 index 000000000..a59f62a19 --- /dev/null +++ b/man3/getmntent.3 @@ -0,0 +1,154 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:46:57 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 961109, 031115, aeb +.\" +.TH GETMNTENT 3 2003-11-15 "" "Linux Programmer's Manual" +.SH NAME +getmntent, setmntent, addmntent, endmntent, hasmntopt, +getmntent_r \- get file system descriptor file entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.sp +.BI "FILE *setmntent(const char *" filename ", const char *" type ); +.sp +.BI "struct mntent *getmntent(FILE *" fp ); +.sp +.BI "int addmntent(FILE *" fp ", const struct mntent *" mnt ); +.sp +.BI "int endmntent(FILE *" fp ); +.sp +.BI "char *hasmntopt(const struct mntent *" mnt ", const char *" opt ); +.sp +/* GNU extension */ +.BR "#define _GNU_SOURCE" " /* or _SVID_SOURCE or _BSD_SOURCE */ +.B #include +.sp +.BI "struct mntent *getmntent_r(FILE *" fp ", struct mntent *" mntbuf , +.BI " char *" buf ", int " buflen ); +.fi +.SH DESCRIPTION +These routines are used to access the file system description file +\fI/etc/fstab\fP and the mounted file system description file +\fI/etc/mtab\fP. +.PP +The \fBsetmntent()\fP function opens the file system description file +\fIfp\fP and returns a file pointer which can be used by +\fBgetmntent()\fP. The argument \fItype\fP is the type of access +required and can take the same values as the \fImode\fP argument of +.BR fopen (3). +.PP +The \fBgetmntent()\fP function reads the next line from the file system +description file \fIfp\fP and returns a pointer to a structure +containing the broken out fields from a line in the file. The pointer +points to a static area of memory which is overwritten by subsequent +calls to \fBgetmntent()\fP. +.PP +The \fBaddmntent()\fP function adds the mntent structure \fImnt\fP to +the end of the open file \fIfp\fP. +.PP +The \fBendmntent()\fP function closes the file system description file +\fIfp\fP. +.PP +The \fBhasmntopt()\fP function scans the \fImnt_opts\fP field (see below) +of the mntent structure \fImnt\fP for a substring that matches \fIopt\fP. +See \fI\fP and +.BR mount (8) +for valid mount options. +.PP +The reentrant \fBgetmntent_r()\fP function is similar to \fBgetmntent()\fP, +but stores the struct mount in the provided +.RI * mntbuf +and stores the strings pointed to by the entries in that struct +in the provided array +.I buf +of size +.IR buflen . +.PP +The \fImntent\fP structure is defined in \fI\fP as follows: +.sp +.RS +.nf +.ne 8 +.ta 8n 16n 32n +struct mntent { + char *mnt_fsname; /* name of mounted file system */ + char *mnt_dir; /* file system path prefix */ + char *mnt_type; /* mount type (see mntent.h) */ + char *mnt_opts; /* mount options (see mntent.h) */ + int mnt_freq; /* dump frequency in days */ + int mnt_passno; /* pass number on parallel fsck */ +}; +.ta +.fi +.RE + +Since fields in the mtab and fstab files are separated by whitespace, +octal escapes are used to represent the four characters space (\e040), +tab (\e011), newline (\e012) and backslash (\e134) in those files +when they occur in one of the four strings in a mntent structure. +The routines \fBaddmntent()\fP and \fBgetmntent()\fP will convert +from string representation to escaped representation and back. +.SH "RETURN VALUE" +The \fBgetmntent()\fP and \fBgetmntent_r()\fP functions return +a pointer to the mntent structure or NULL on failure. +.PP +The \fBaddmntent()\fP function returns 0 on success and 1 on failure. +.PP +The \fBendmntent()\fP function always returns 1. +.PP +The \fBhasmntopt()\fP function returns the address of the substring if +a match is found and NULL otherwise. +.SH FILES +.nf +/etc/fstab file system description file +/etc/mtab mounted file system description file +.fi +.SH "CONFORMING TO" +The non-reentrant functions are from SunOS 4.1.3. +A routine +.B getmntent_r() +was introduced in HPUX 10, but it returns an int. The prototype +shown above is glibc-only. +LSB deprecates the functions +.BR endhostent() , +.BR sethostent() +and +.BR setmntent() . +.SH NOTES +SysV also has a \fBgetmntent()\fP function but the calling sequence +differs, and the returned structure is different. Under SysV +.I /etc/mnttab +is used. +BSD 4.4 and Digital Unix have a routine \fBgetmntinfo()\fP, +a wrapper around the system call \fBgetfsstat()\fP. +.SH "SEE ALSO" +.BR fopen (3), +.BR fstab (5), +.BR mount (8) diff --git a/man3/getnameinfo.3 b/man3/getnameinfo.3 new file mode 100644 index 000000000..b4f269b31 --- /dev/null +++ b/man3/getnameinfo.3 @@ -0,0 +1,202 @@ +.\" This page is in the public domain. +.\" Almost all details are from RFC 2553. +.\" +.TH getnameinfo 3 2000-12-11 "Linux Man Page" "UNIX Programmer's Manual" +.SH NAME +getnameinfo \- address-to-name translation in protocol-independent manner +.SH SYNOPSIS +.nf +.B #include +.B #include +.sp +.BI "int getnameinfo(const struct sockaddr *" "sa" ", socklen_t " "salen" , +.BI " char *" "host" ", size_t " "hostlen" , +.BI " char *" "serv" ", size_t " "servlen" ", int " "flags" ); +.fi +.SH DESCRIPTION +The +.BR getnameinfo (3) +function is defined for protocol-independent address-to-nodename translation. +It combines the functionality of +.BR gethostbyaddr (3) +and +.BR getservbyport (3) +and is the inverse of +.BR getaddrinfo (3). +The +.I sa +argument is a pointer to a generic socket address structure +(of type +.I sockaddr_in +or +.IR sockaddr_in6 ) +of size +.IR salen +that holds the input IP address and port number. +The arguments +.I host +and +.I serv +are pointers to buffers (of size +.I hostlen +and +.I servlen +respectively) to hold the return values. + +The caller can specify that no hostname (or no service name) +is required by providing a NULL +.I host +(or +.IR serv ) +argument or a zero +.I hostlen +(or +.IR servlen ) +parameter. However, at least one of hostname or service name +must be requested. + +The +.I flags +argument modifies the behaviour of +.BR getnameinfo (3) +as follows: +.TP +.B NI_NOFQDN +If set, return only the hostname part of the FQDN for local hosts. +.TP +.B NI_NUMERICHOST +If set, then the numeric form of the hostname is returned. +.\" For example, by calling +.\" .I inet_ntop() +.\" instead of +.\" .IR gethostbyaddr() . +(When not set, this will still happen in case the node's name +cannot be looked up.) +.TP +.B NI_NAMEREQD +If set, then a error is returned if the hostname cannot be looked up. +.TP +.B NI_NUMERICSERV +If set, then the service address is returned in numeric form, +for example by its port number. +.TP +.B NI_DGRAM +If set, then the service is datagram (UDP) based rather than +stream (TCP) based. This is required for the few ports (512-514) +that have different services for UDP and TCP. +.SH "RETURN VALUE" +On success 0 is returned, and node and service names, if requested, +are filled with NUL-terminated strings, possibly truncated to fit +the specified buffer lengths. +On error a nonzero value is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EAI_AGAIN +The name could not be resolved at this time. Try again later. +.TP +.B EAI_BADFLAGS +The +.I flags +parameter has an invalid value. +.TP +.B EAI_FAIL +A non-recoverable error occurred. +.TP +.B EAI_FAMILY +The address family was not recognized, +or the address length was invalid for the specified family. +.TP +.B EAI_MEMORY +Out of memory. +.TP +.B EAI_NONAME +The name does not resolve for the supplied parameters. +NI_NAMEREQD is set and the host's name cannot be located, +or neither hostname nor service name were requested. +.TP +.B EAI_SYSTEM +A system error occurred. The error code can be found in +.IR errno . +.SH FILES +/etc/hosts +.br +/etc/nsswitch.conf +.br +/etc/resolv.conf +.SH NOTE +In order to assist the programmer in choosing reasonable sizes +for the supplied buffers, +.I +defines the constants +.RS +.nf +# define NI_MAXHOST 1025 +.br +# define NI_MAXSERV 32 +.fi +.RE +The former is the constant MAXDNAME in recent versions of BIND's +.I +header file. The latter is a guess based on the services listed +in the current Assigned Numbers RFC. +.SH EXAMPLES +The following code tries to get the numeric hostname and service name, for +a given socket address. Note that there is no hardcoded reference to +a particular address family. + +.RS +.nf + struct sockaddr *sa; /* input */ + char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; + + if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf, + sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0) + printf("host=%s, serv=%s\en", hbuf, sbuf); +.fi +.RE + +The following version checks if the socket address has a +reverse address mapping. + +.RS +.fi + struct sockaddr *sa; /* input */ + char hbuf[NI_MAXHOST]; + + if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), + NULL, 0, NI_NAMEREQD)) + printf("could not resolve hostname"); + else + printf("host=%s\en", hbuf); +.fi +.RE +.SH "CONFORMING TO" +RFC 2553. (See also XNS, issue 5.2.) +.SH "SEE ALSO" +.BR getaddrinfo (3), +.BR gethostbyaddr (3), +.BR getservbyname (3), +.BR getservbyport (3), +.BR inet_ntop (3), +.BR socket (3), +.BR hosts (5), +.BR services (5), +.BR hostname (7), +.BR named (8) +.LP +R. Gilligan, S. Thomson, J. Bound and W. Stevens, +.IR "Basic Socket Interface Extensions for IPv6" , +RFC 2553, March 1999. +.LP +Tatsuya Jinmei and Atsushi Onoe, +.IR "An Extension of Format for IPv6 Scoped Addresses" , +internet draft, work in progress. +ftp://ftp.ietf.org/internet-drafts/draft-ietf-ipngwg-scopedaddr-format-02.txt +.LP +Craig Metz, +.IR "Protocol Independence Using the Sockets API" , +Proceedings of the freenix track: +2000 USENIX annual technical conference, June 2000. +http://www.usenix.org/publications/library/proceedings/usenix2000/freenix/metzprotocol.html diff --git a/man3/getnetbyaddr.3 b/man3/getnetbyaddr.3 new file mode 100644 index 000000000..70f5670dc --- /dev/null +++ b/man3/getnetbyaddr.3 @@ -0,0 +1 @@ +.so man3/getnetent.3 diff --git a/man3/getnetbyname.3 b/man3/getnetbyname.3 new file mode 100644 index 000000000..70f5670dc --- /dev/null +++ b/man3/getnetbyname.3 @@ -0,0 +1 @@ +.so man3/getnetent.3 diff --git a/man3/getnetent.3 b/man3/getnetent.3 new file mode 100644 index 000000000..41fa510b6 --- /dev/null +++ b/man3/getnetent.3 @@ -0,0 +1,111 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:48:06 1993 by Rik Faith (faith@cs.unc.edu) +.TH GETNETENT 3 1993-05-15 "BSD" "Linux Programmer's Manual" +.SH NAME +getnetent, getnetbyname, getnetbyaddr, setnetent, endnetent \- +get network entry +.SH SYNOPSIS +.nf +.B #include +.sp +.B struct netent *getnetent(void); +.sp +.BI "struct netent *getnetbyname(const char *" name ); +.sp +.BI "struct netent *getnetbyaddr(long " net ", int " type ); +.sp +.BI "void setnetent(int " stayopen ); +.sp +.B void endnetent(void); +.fi +.SH DESCRIPTION +The \fBgetnetent()\fP function reads the next line from the file +\fI/etc/networks\fP and returns a structure \fInetent\fP containing +the broken out fields from the line. The \fI/etc/networks\fP file +is opened if necessary. +.PP +The \fBgetnetbyname()\fP function returns a \fInetent\fP structure +for the line from \fI/etc/networks\fP that matches the network +\fIname\fP. +.PP +The \fBgetnetbyaddr()\fP function returns a \fInetent\fP structure +for the line that matches the network number \fInet\fP of type +\fItype\fP. +.PP +The \fBsetnetent()\fP function opens and rewinds the +\fI/etc/networks\fP file. If \fIstayopen\fP is true (1), then the +file will not be closed between calls to \fBgetnetbyname()\fP and +\fBgetnetbyaddr()\fP. +.PP +The \fBendservent()\fP function closes \fI/etc/networks\fP. +.PP +The \fInetent\fP structure is defined in \fI\fP as follows: +.sp +.RS +.nf +.ne 6 +.ta 8n 16n 34n +struct netent { + char *n_name; /* official network name */ + char **n_aliases; /* alias list */ + int n_addrtype; /* net address type */ + unsigned long int n_net; /* network number */ +} +.ta +.fi +.RE +.PP +The members of the \fInetent\fP structure are: +.TP +.I n_name +The official name of the network. +.TP +.I n_aliases +A zero terminated list of alternative names for the network. +.TP +.I n_addrtype +The type of the network number; always AF_INET. +.TP +.I n_net +The network number in host byte order. +.SH "RETURN VALUE" +The \fBgetnetent()\fP, \fBgetnetbyname()\fP and \fBgetnetbyaddr()\fP +functions return the \fInetent\fP structure, or a NULL pointer if an +error occurs or the end of the file is reached. +.SH FILES +.TP +.I /etc/networks +networks database file +.SH "CONFORMING TO" +BSD 4.3 +.SH "SEE ALSO" +.BR getprotoent (3), +.BR getservent (3), +.BR networks (5) +.br +RFC 1101 diff --git a/man3/getnetgrent.3 b/man3/getnetgrent.3 new file mode 100644 index 000000000..34268f941 --- /dev/null +++ b/man3/getnetgrent.3 @@ -0,0 +1 @@ +.so man3/setnetgrent.3 diff --git a/man3/getnetgrent_r.3 b/man3/getnetgrent_r.3 new file mode 100644 index 000000000..34268f941 --- /dev/null +++ b/man3/getnetgrent_r.3 @@ -0,0 +1 @@ +.so man3/setnetgrent.3 diff --git a/man3/getopt.3 b/man3/getopt.3 new file mode 100644 index 000000000..6c113df1e --- /dev/null +++ b/man3/getopt.3 @@ -0,0 +1,332 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 19:27:50 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Aug 30 22:02:34 1995 by Jim Van Zandt +.\" longindex is a pointer, has_arg can take 3 values, using consistent +.\" names for optstring and longindex, "\n" in formats fixed. Documenting +.\" opterr and getopt_long_only. Clarified explanations (borrowing heavily +.\" from the source code). +.\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" Modified 990715, aeb: changed `EOF' into `-1' since that is what POSIX +.\" says; moreover, EOF is not defined in . +.\" Modified 2002-02-16, joey: added information about non-existing +.\" option character and colon as first option character +.\" Modified 2004-07-28, Michael Kerrisk +.\" Added text to explain how to order both '[-+]' and ':' at +.\" the start of optstring +.\" +.TH GETOPT 3 2004-07-28 "GNU" "Linux Programmer's Manual" +.SH NAME +getopt \- Parse command line options +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int getopt(int " argc ", char * const " argv[] , +.BI " const char *" optstring ); +.sp +.BI "extern char *" optarg ; +.BI "extern int " optind ", " opterr ", " optopt ; +.sp +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "int getopt_long(int " argc ", char * const " argv[] , +.BI " const char *" optstring , +.BI " const struct option *" longopts ", int *" longindex ); +.sp +.BI "int getopt_long_only(int " argc ", char * const " argv[] , +.BI " const char *" optstring , +.BI " const struct option *" longopts ", int *" longindex ); +.fi +.SH DESCRIPTION +The +.B getopt() +function parses the command line arguments. Its arguments +.I argc +and +.I argv +are the argument count and array as passed to the +.B main() +function on program invocation. +An element of \fIargv\fP that starts with '\-' +(and is not exactly "\-" or "\-\-") +is an option element. The characters of this element +(aside from the initial '\-') are option characters. If \fBgetopt()\fP +is called repeatedly, it returns successively each of the option characters +from each of the option elements. +.PP +If \fBgetopt()\fP finds another option character, it returns that +character, updating the external variable \fIoptind\fP and a static +variable \fInextchar\fP so that the next call to \fBgetopt()\fP can +resume the scan with the following option character or +\fIargv\fP-element. +.PP +If there are no more option characters, \fBgetopt()\fP returns \-1. +Then \fIoptind\fP is the index in \fIargv\fP of the first +\fIargv\fP-element that is not an option. +.PP +.I optstring +is a string containing the legitimate option characters. If such a +character is followed by a colon, the option requires an argument, so +\fBgetopt\fP places a pointer to the following text in the same +\fIargv\fP-element, or the text of the following \fIargv\fP-element, in +.IR optarg . +Two colons mean an option takes +an optional arg; if there is text in the current \fIargv\fP-element, +it is returned in \fIoptarg\fP, otherwise \fIoptarg\fP is set to zero. +This is a GNU extension. If +.I optstring +contains +.B W +followed by a semicolon, then +.B \-W foo +is treated as the long option +.BR \-\-foo . +(The +.B \-W +option is reserved by POSIX.2 for implementation extensions.) +This behaviour is a GNU extension, not available with libraries before +GNU libc 2. +.PP +By default, \fBgetopt()\fP permutes the contents of \fIargv\fP as it +scans, so that eventually all the non-options are at the end. Two +other modes are also implemented. If the first character of +\fIoptstring\fP is '+' or the environment variable POSIXLY_CORRECT is +set, then option processing stops as soon as a non-option argument is +encountered. If the first character of \fIoptstring\fP is '\-', then +each non-option \fIargv\fP-element is handled as if it were the argument of +an option with character code 1. (This is used by programs that were +written to expect options and other \fIargv\fP-elements in any order +and that care about the ordering of the two.) +The special argument "\-\-" forces an end of option-scanning regardless +of the scanning mode. +.PP +If \fBgetopt()\fP does not recognize an option character, it prints an +error message to stderr, stores the character in \fIoptopt\fP, and +returns '?'. The calling program may prevent the error message by +setting \fIopterr\fP to 0. +.PP +If \fBgetopt()\fP finds an option character in \fIargv\fP that was not +included in \fIoptstring\fP, or if it detects a missing option argument, +it returns '?' and sets the external variable \fIoptopt\fP to the +actual option character. If the first character +(following any optional '+'or '\-' described above) +of \fIoptstring\fP +is a colon (':'), then \fBgetopt()\fP returns ':' instead of '?' to +indicate a missing option argument. If an error was detected, and +the first character of \fIoptstring\fP is not a colon, and +the external variable \fIopterr\fP is nonzero (which is the default), +\fBgetopt()\fP prints an error message. +.PP +The +.B getopt_long() +function works like +.B getopt() +except that it also accepts long options, started out by two dashes. +Long option names may be abbreviated if the abbreviation is +unique or is an exact match for some defined option. A long option +may take a parameter, of the form +.B \-\-arg=param +or +.BR "\-\-arg param" . +.PP +.I longopts +is a pointer to the first element of an array of +.B struct option +declared in +.B +as +.nf +.sp +.in 10 +struct option { +.in 14 +const char *name; +int has_arg; +int *flag; +int val; +.in 10 +}; +.fi +.PP +The meanings of the different fields are: +.TP +.I name +is the name of the long option. +.TP +.I has_arg +is: +\fBno_argument\fP (or 0) if the option does not take an argument, +\fBrequired_argument\fP (or 1) if the option requires an argument, or +\fBoptional_argument\fP (or 2) if the option takes an optional argument. +.TP +.I flag +specifies how results are returned for a long option. If \fIflag\fP +is \fBNULL\fP, then \fBgetopt_long()\fP returns \fIval\fP. (For +example, the calling program may set \fIval\fP to the equivalent short +option character.) Otherwise, \fBgetopt_long()\fP returns 0, and +\fIflag\fP points to a variable which is set to \fIval\fP if the +option is found, but left unchanged if the option is not found. +.TP +\fIval\fP +is the value to return, or to load into the variable pointed +to by \fIflag\fP. +.PP +The last element of the array has to be filled with zeroes. +.PP +If \fIlongindex\fP is not \fBNULL\fP, it +points to a variable which is set to the index of the long option relative to +.IR longopts . +.PP +\fBgetopt_long_only()\fP is like \fBgetopt_long()\fP, but '\-' as well +as '\-\-' can indicate a long option. If an option that starts with '\-' +(not '\-\-') doesn't match a long option, but does match a short option, +it is parsed as a short option instead. +.SH "RETURN VALUE" +The +.B getopt() +function returns the option character if the option was found +successfully, ':' if there was a missing parameter for one of the +options, '?' for an unknown option character, or \-1 +for the end of the option list. +.PP +\fBgetopt_long()\fP and \fBgetopt_long_only()\fP also return the option +character when a short option is recognized. For a long option, they +return \fIval\fP if \fIflag\fP is \fBNULL\fP, and 0 otherwise. Error +and \-1 returns are the same as for \fBgetopt()\fP, plus '?' for an +ambiguous match or an extraneous parameter. +.SH "ENVIRONMENT VARIABLES" +.TP +.SM +.B POSIXLY_CORRECT +If this is set, then option processing stops as soon as a non-option +argument is encountered. +.TP +.SM +.B __GNU_nonoption_argv_flags_ +This variable was used by +.B bash +2.0 to communicate to GNU libc which arguments are the results of +wildcard expansion and so should not be considered as options. This +behaviour was removed in +.B bash +version 2.01, but the support remains in GNU libc. +.SH EXAMPLE +The following example program illustrates the use of +.BR getopt_long() +with most of its features. +.nf +.sp +#include /* for printf */ +#include /* for exit */ +#include + +int +main (int argc, char **argv) { + int c; + int digit_optind = 0; + + while (1) { + int this_option_optind = optind ? optind : 1; + int option_index = 0; + static struct option long_options[] = { + {"add", 1, 0, 0}, + {"append", 0, 0, 0}, + {"delete", 1, 0, 0}, + {"verbose", 0, 0, 0}, + {"create", 1, 0, 'c'}, + {"file", 1, 0, 0}, + {0, 0, 0, 0} + }; + + c = getopt_long (argc, argv, "abc:d:012", + long_options, &option_index); + if (c == \-1) + break; + + switch (c) { + case 0: + printf ("option %s", long_options[option_index].name); + if (optarg) + printf (" with arg %s", optarg); + printf ("\\n"); + break; + + case '0': + case '1': + case '2': + if (digit_optind != 0 && digit_optind != this_option_optind) + printf ("digits occur in two different argv-elements.\\n"); + digit_optind = this_option_optind; + printf ("option %c\\n", c); + break; + + case 'a': + printf ("option a\\n"); + break; + + case 'b': + printf ("option b\\n"); + break; + + case 'c': + printf ("option c with value '%s'\\n", optarg); + break; + + case 'd': + printf ("option d with value '%s'\\n", optarg); + break; + + case '?': + break; + + default: + printf ("?? getopt returned character code 0%o ??\\n", c); + } + } + + if (optind < argc) { + printf ("non-option ARGV-elements: "); + while (optind < argc) + printf ("%s ", argv[optind++]); + printf ("\\n"); + } + + exit (0); +} +.fi +.SH BUGS +The POSIX.2 specification of +.B getopt() +has a technical error described in POSIX.2 Interpretation 150. The GNU +implementation (and probably all other implementations) implements the +correct behaviour rather than that specified. +.SH "CONFORMING TO" +.TP +\fBgetopt()\fP: +POSIX.2, provided the environment variable POSIXLY_CORRECT is set. +Otherwise, the elements of \fIargv\fP aren't really const, because we +permute them. We pretend they're const in the prototype to be +compatible with other systems. diff --git a/man3/getopt_long.3 b/man3/getopt_long.3 new file mode 100644 index 000000000..7612d3f67 --- /dev/null +++ b/man3/getopt_long.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man3/getopt_long_only.3 b/man3/getopt_long_only.3 new file mode 100644 index 000000000..7612d3f67 --- /dev/null +++ b/man3/getopt_long_only.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man3/getpass.3 b/man3/getpass.3 new file mode 100644 index 000000000..832727ef2 --- /dev/null +++ b/man3/getpass.3 @@ -0,0 +1,104 @@ +.\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH GETPASS 3 2000-12-05 "Linux Manpage" "Linux Programmer's Manual" +.SH NAME +getpass \- get a password +.SH SYNOPSIS +.B #include +.sp +.B "char *getpass( const char *" prompt ); +.SH DESCRIPTION +This function is obsolete. Do not use it. +.PP +The +.BR getpass () +function opens +.I /dev/tty +(the controlling terminal of the process), outputs the string +.IR prompt , +turns off echoing, reads one line (the "password"), +restores the terminal state and closes +.I /dev/tty +again. +.SH "RETURN VALUE" +The function +.B getpass +returns a pointer to a static buffer containing the +(first PASS_MAX bytes of) the password without the trailing +newline, terminated by a NUL. +This buffer may be overwritten by a following call. +On error, the terminal state is restored, +.I errno +is set appropriately, and NULL is returned. +.SH ERRORS +The function may fail if +.TP +.B ENXIO +The process does not have a controlling terminal. +.SH NOTES +For libc4 and libc5, the prompt is not written to +.I /dev/tty +but to +.IR stderr . +Moreover, if +.I /dev/tty +cannot be opened, the password is read from +.IR stdin . +The static buffer has length 128 so that only the first 127 +bytes of the password are returned. +While reading the password, signal generation (SIGINT, SIGQUIT, +SIGSTOP, SIGTSTOP) is disabled and the corresponding characters +(usually control-C, control-\e, control-Z and control-Y) +are transmitted as part of the password. +Since libc 5.4.19 also line editing is disabled, so that also +backspace and the like will be seen as part of the password. +.PP +For glibc2, if +.I /dev/tty +cannot be opened, the prompt is written to +.I stderr +and the password is read from +.IR stdin . +There is no limit on the length of the password. +Line editing is not disabled. +.PP +According to the SUSv2, the value of PASS_MAX must be defined in +.I +in case it is smaller than 8, and can in any case be obtained using +.IR sysconf(_SC_PASS_MAX) . +However, POSIX.2 withdraws the constants PASS_MAX +and _SC_PASS_MAX, and the function +.B getpass (). +Libc4 and libc5 have never supported PASS_MAX or _SC_PASS_MAX. +Glibc2 accepts _SC_PASS_MAX and returns BUFSIZ (e.g., 8192). +.SH FILES +.I /dev/tty +.SH "SEE ALSO" +.BR crypt (3) +.SH HISTORY +A +.B getpass +function appeared in Version 7 AT&T UNIX. +.SH BUGS +The calling process should zero the password as soon as possible to avoid +leaving the cleartext password visible in the process's address space. diff --git a/man3/getprotobyname.3 b/man3/getprotobyname.3 new file mode 100644 index 000000000..f8cb4bba2 --- /dev/null +++ b/man3/getprotobyname.3 @@ -0,0 +1 @@ +.so man3/getprotoent.3 diff --git a/man3/getprotobynumber.3 b/man3/getprotobynumber.3 new file mode 100644 index 000000000..f8cb4bba2 --- /dev/null +++ b/man3/getprotobynumber.3 @@ -0,0 +1 @@ +.so man3/getprotoent.3 diff --git a/man3/getprotoent.3 b/man3/getprotoent.3 new file mode 100644 index 000000000..8b4787842 --- /dev/null +++ b/man3/getprotoent.3 @@ -0,0 +1,106 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:26:03 1993 by Rik Faith (faith@cs.unc.edu) +.TH GETPROTOENT 3 1993-04-24 "BSD" "Linux Programmer's Manual" +.SH NAME +getprotoent, getprotobyname, getprotobynumber, setprotoent, +endprotoent \- get protocol entry +.SH SYNOPSIS +.nf +.B #include +.sp +.B struct protoent *getprotoent(void); +.sp +.BI "struct protoent *getprotobyname(const char *" name ); +.sp +.BI "struct protoent *getprotobynumber(int " proto ); +.sp +.BI "void setprotoent(int " stayopen ); +.sp +.B void endprotoent(void); +.fi +.SH DESCRIPTION +The \fBgetprotoent()\fP function reads the next line from the file +\fI/etc/protocols\fP and returns a structure \fIprotoent\fP +containing the broken out fields from the line. The +\fI/etc/protocols\fP file is opened if necessary. +.PP +The \fBgetprotobyname()\fP function returns a \fIprotoent\fP +structure for the line from \fI/etc/protocols\fP that matches +the protocol name \fIname\fP. +.PP +The \fBgetprotobynumber()\fP function returns a \fIprotoent\fP +structure for the line that matches the protocol number \fInumber\fP. +.PP +The \fBsetprotoent()\fP function opens and rewinds the +\fI/etc/protocols\fP file. If \fIstayopen\fP is true (1), then +the file will not be closed between calls to \fBgetprotobyname()\fP +or \fBgetprotobynumber()\fP. +.PP +The \fBendprotoent()\fP function closes \fI/etc/protocols\fP. +.PP +The \fIprotoent\fP structure is defined in \fI\fP as follows: +.sp +.RS +.nf +.ne 5 +.ta 8n 16n 32n +struct protoent { + char *p_name; /* official protocol name */ + char **p_aliases; /* alias list */ + int p_proto; /* protocol number */ +} +.ta +.fi +.RE +.PP +The members of the \fIprotoent\fP structure are: +.TP +.I p_name +The official name of the protocol. +.TP +.I p_aliases +A zero terminated list of alternative names for the protocol. +.TP +.I p_proto +The protocol number. +.SH "RETURN VALUE" +The \fBgetprotoent()\fP, \fBgetprotobyname()\fP and \fBgetprotobynumber()\fP +functions return the \fIprotoent\fP structure, or a NULL pointer if an +error occurs or the end of the file is reached. +.SH FILES +.PD 0 +.TP +.I /etc/protocols +protocol database file +.PD +.SH "CONFORMING TO" +BSD 4.3 +.SH "SEE ALSO" +.BR getnetent (3), +.BR getservent (3), +.BR protocols (5) diff --git a/man3/getpt.3 b/man3/getpt.3 new file mode 100644 index 000000000..a60c8dcba --- /dev/null +++ b/man3/getpt.3 @@ -0,0 +1,35 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" This man page was written by Jeremy Phelps . +.\" Redistribute and modify at will. +.\" +.TH GETPT 3 "2002-10-09" "PTY Control" "Linux Programmer's Manual" +.SH NAME +getpt \- open the pseudo-terminal master (PTM) +.SH SYNOPSIS +.nf +.B #include +.sp +.B "int getpt(void)" +.fi +.SH DESCRIPTION +.B getpt() +opens a pseudo-terminal master and returns its file descriptor. +It is equivalent to +.BI "open(" \fI"/dev/ptmx" , O_RDWR|O_NOCTTY ) +on Linux systems, though the pseudo-terminal master is located +elsewhere on some systems that use GNU Libc. + +.SH "RETURN VALUE" +.B getpt() +returns an open file descriptor upon successful completion. Otherwise, it +returns -1 and sets +.I errno +to indicate the error. +.SH CONFORMING TO +.B getpt() +is specific to GNU Libc. +.SH "SEE ALSO" +.BR grantpt (3), +.BR ptsname (3), +.BR unlockpt (3), +.BR ptmx (4) diff --git a/man3/getpw.3 b/man3/getpw.3 new file mode 100644 index 000000000..bf6973ecc --- /dev/null +++ b/man3/getpw.3 @@ -0,0 +1,94 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:23:25 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 27 21:37:47 1996 by Martin Schulze (joey@linux.de) +.\" +.TH GETPW 3 1996-05-27 "GNU" "Linux Programmer's Manual" +.SH NAME +getpw \- Re-construct password line entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.sp +.BI "int getpw(uid_t " uid ", char *" buf ); +.fi +.SH DESCRIPTION +The \fBgetpw()\fP function re-constructs the password line entry for +the given user uid \fIuid\fP in the buffer \fIbuf\fP. The returned +buffer contains a line of format +.sp +.RS +.B name:passwd:uid:gid:gecos:dir:shell +.RE +.PP +The \fIpasswd\fP structure is defined in \fI\fP as follows: +.sp +.RS +.nf +.ta 8n 16n 32n +struct passwd { + char *pw_name; /* user name */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user id */ + gid_t pw_gid; /* group id */ + char *pw_gecos; /* real name */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.ta +.fi +.RE +.SH "RETURN VALUE" +The \fBgetpw()\fP function returns 0 on success, or \-1 if an error +occurs. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to allocate passwd structure. +.SH FILES +.TP +.I /etc/passwd +password database file +.SH "CONFORMING TO" +SYSVr2. +.SH BUGS +The +.BR getpw () +function is dangerous as it may overflow the provided buffer +.IR buf . +It is obsoleted by +.BR getpwuid (). +.SH "SEE ALSO" +.BR endpwent (3), +.BR fgetpwent (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR setpwent (3), +.BR passwd (5) diff --git a/man3/getpwent.3 b/man3/getpwent.3 new file mode 100644 index 000000000..2c8880150 --- /dev/null +++ b/man3/getpwent.3 @@ -0,0 +1,91 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified Sat Jul 24 19:22:14 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 27 21:37:47 1996 by Martin Schulze (joey@linux.de) +.\" +.TH GETPWENT 3 1996-05-27 "GNU" "Linux Programmer's Manual" +.SH NAME +getpwent, setpwent, endpwent \- get password file entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.sp +.B struct passwd *getpwent(void); +.sp +.B void setpwent(void); +.sp +.B void endpwent(void); +.fi +.SH DESCRIPTION +The \fBgetpwent()\fP function returns a pointer to a structure containing +the broken out fields of a line from \fI/etc/passwd\fP. The first time it +is called it returns the first entry; thereafter, it returns successive +entries. +.PP +The \fBsetpwent()\fP function rewinds the file pointer to the beginning +of the \fI/etc/passwd\fP file. +.PP +The \fBendpwent()\fP function closes the \fI/etc/passwd\fP file. +.PP +The \fIpasswd\fP structure is defined in \fI\fP as follows: +.sp +.RS +.nf +struct passwd { + char *pw_name; /* user name */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user id */ + gid_t pw_gid; /* group id */ + char *pw_gecos; /* real name */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.fi +.RE +.SH "RETURN VALUE" +The \fBgetpwent()\fP function returns the \fIpasswd\fP structure, or NULL if +there are no more entries or an error occurs. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to allocate passwd structure. +.SH FILES +.TP +.I /etc/passwd +password database file +.SH "CONFORMING TO" +SVID 3, BSD 4.3 +.SH "SEE ALSO" +.BR fgetpwent (3), +.BR getpw (3), +.BR getpwent_r (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR passwd (5) diff --git a/man3/getpwent_r.3 b/man3/getpwent_r.3 new file mode 100644 index 000000000..c0b700b38 --- /dev/null +++ b/man3/getpwent_r.3 @@ -0,0 +1,171 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH GETPWENT_R 3 2003-11-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getpwent_r, fgetpwent_r \- get passwd file entry reentrantly +.SH SYNOPSIS +.nf +.B "#define _GNU_SOURCE" +.br +.B #include +.sp +.BI "int getpwent_r(struct passwd *" pwbuf ", char *" buf , +.br +.BI " size_t " buflen ", struct passwd **" pwbufp ); +.sp +.BI "int fgetpwent_r(FILE *" fp ", struct passwd *" pwbuf ", char *" buf , +.br +.BI " size_t " buflen ", struct passwd **" pwbufp ); +.SH DESCRIPTION +The functions +.B getpwent_r() +and +.B fgetpwent_r() +are the reentrant versions of +.BR getpwent (3) +and +.BR fgetpwent (3). +The former reads the next passwd entry from the stream initialized by +.BR setpwent (3). +The latter reads the next passwd entry from the stream +.I fp +given as parameter. +.PP +The \fIpasswd\fP structure is defined in +.I +as follows: +.sp +.RS +.nf +struct passwd { + char *pw_name; /* user name */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user id */ + gid_t pw_gid; /* group id */ + char *pw_gecos; /* real name */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.fi +.RE +.sp +The non-reentrant functions return a pointer to static storage, +where this static storage contains further pointers to user +name, password, gecos field, home directory and shell. +The reentrant functions described here return all of that in +caller-provided buffers. First of all there is the buffer +.I pwbuf +that can hold a struct passwd. And next the buffer +.I buf +of size +.I buflen +that can hold additional strings. +The result of these functions, the struct passwd read from the stream, +is stored in the provided buffer +.RI * pwbuf , +and a pointer to this struct passwd is returned in +.RI * pwbufp . +.SH "RETURN VALUE" +On success, these functions return 0 and +.RI * pwbufp +is a pointer to the struct passwd. +On error, these functions return an error value and +.RI * pwbufp +is NULL. +.SH ERRORS +.TP +.B ENOENT +No more entries. +.TP +.B ERANGE +Insufficient buffer space supplied. Try again with larger buffer. +.SH EXAMPLE +.nf +#define _GNU_SOURCE +#include +#include +#define BUFLEN 4096 + +int main() { + struct passwd pw, *pwp; + char buf[BUFLEN]; + int i; + + setpwent(); + while (1) { + i = getpwent_r(&pw, buf, BUFLEN, &pwp); + if (i) + break; + printf("%s (%d)\etHOME %s\etSHELL %s\en", + pwp->pw_name, pwp->pw_uid, + pwp->pw_dir, pwp->pw_shell); + } + endpwent(); + return 0; +} +.fi +.\" perhaps add error checking - should use strerror_r +.\" #include +.\" #include +.\" if (i) { +.\" if (i == ENOENT) +.\" break; +.\" printf("getpwent_r: %s", strerror(i)); +.\" exit(1); +.\" } +.SH "CONFORMING TO" +These functions are GNU extensions, done in a style resembling +the POSIX version of functions like +.BR getpwnam_r (3). +Other systems use prototype +.sp +.nf +.in +4 +struct passwd * +getpwent_r(struct passwd *pwd, char *buf, int buflen); +.in +.fi +.sp +or, better, +.sp +.nf +.in +4 +int +getpwent_r(struct passwd *pwd, char *buf, int buflen, + FILE **pw_fp); +.in +.fi +.sp +.SH NOTES +The function +.B getpwent_r() +is not really reentrant since it shares the reading position +in the stream with all other threads. +.SH "SEE ALSO" +.BR fgetpwent (3), +.BR getpw (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR passwd (5) diff --git a/man3/getpwnam.3 b/man3/getpwnam.3 new file mode 100644 index 000000000..ba716ed99 --- /dev/null +++ b/man3/getpwnam.3 @@ -0,0 +1,183 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1996-05-27 by Martin Schulze (joey@linux.de) +.\" Modified 2003-11-15 by aeb +.\" +.TH GETPWNAM 3 1996-05-27 "GNU" "Linux Programmer's Manual" +.SH NAME +getpwnam, getpwnam_r, getpwuid, getpwuid_r \- get password file entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.sp +.BI "struct passwd *getpwnam(const char *" name ); +.sp +.BI "struct passwd *getpwuid(uid_t " uid ); +.sp +.BI "int getpwnam_r(const char *" name ", struct passwd *" pwbuf , +.br +.BI " char *" buf ", size_t " buflen ", struct passwd **" pwbufp ); +.sp +.BI "int getpwuid_r(uid_t " uid ", struct passwd *" pwbuf , +.br +.BI " char *" buf ", size_t " buflen ", struct passwd **" pwbufp ); +.fi +.SH DESCRIPTION +The +.B getpwnam() +function returns a pointer to a structure containing +the broken out fields of a line from +.I /etc/passwd +for the entry that matches the user name +.IR name . +.PP +The +.B getpwuid() +function returns a pointer to a structure containing +the broken out fields of a line from +.I /etc/passwd +for the entry that matches the user uid +.IR uid . +.PP +The +.B getpwnam_r() +and +.B getpwuid_r() +functions find the same information, but store the retrieved passwd structure +in the space pointed to by +.IR pwbuf . +This passwd structure contains pointers to strings, and these strings +are stored in the buffer +.I buf +of size +.IR buflen . +A pointer to the result (in case of success) or NULL (in case no entry +was found or an error occurred) is stored in +.RI * pwbufp . +.PP +The \fIpasswd\fP structure is defined in \fI\fP as follows: +.sp +.RS +.nf +struct passwd { + char *pw_name; /* user name */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user id */ + gid_t pw_gid; /* group id */ + char *pw_gecos; /* real name */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.fi +.RE +.PP +The maximum needed size for +.I buf +can be found using +.BR sysconf (3) +with the _SC_GETPW_R_SIZE_MAX parameter. +.SH "RETURN VALUE" +The \fBgetpwnam()\fP and \fBgetpwuid()\fP functions return a pointer to +the passwd structure, or NULL if the matching entry is not found or +an error occurs. If an error occurs, +.I errno +is set appropriately. If one wants to check +.I errno +after the call, it should be set to zero before the call. +.LP +The return value may point to static area, and may be overwritten +by subsequent calls to +.BR getpwent() , +.BR getpwnam() , +or +.BR getpwuid() . +.LP +The \fBgetpwnam_r()\fP and \fBgetpwuid_r()\fP functions return +zero on success. In case of error, an error value is returned. +.SH ERRORS +.TP +.BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ... " +The given +.I name +or +.I uid +was not found. +.TP +.B EINTR +A signal was caught. +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The maximum number (OPEN_MAX) of files was open already in the calling process. +.TP +.B ENFILE +The maximum number of files was open already in the system. +.TP +.B ENOMEM +Insufficient memory to allocate passwd structure. +.\" This structure is static, allocated 0 or 1 times. No memory leak. (libc45) +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/passwd +password database file +.fi +.SH "CONFORMING TO" +SVID 3, BSD 4.3, POSIX 1003.1-2003 +.SH NOTES +The formulation given above under "RETURN VALUE" is from POSIX 1003.1-2001. +It does not call "not found" an error, hence does not specify what value +.I errno +might have in this situation. But that makes it impossible to recognize +errors. One might argue that according to POSIX +.I errno +should be left unchanged if an entry is not found. Experiments on various +Unix-like systems shows that lots of different values occur in this +situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM and probably others. +.\" more precisely: +.\" AIX 5.1 - gives ESRCH +.\" OSF1 4.0g - gives EWOULDBLOCK +.\" libc, glibc, Irix 6.5 - give ENOENT +.\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM +.\" SunOS 5.8 - gives EBADF +.\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0 +.SH "SEE ALSO" +.BR endpwent (3), +.BR fgetpwent (3), +.BR getgrnam (3), +.BR getpw (3), +.BR getpwent (3), +.BR putpwent (3), +.BR setpwent (3), +.BR passwd (5) diff --git a/man3/getpwnam_r.3 b/man3/getpwnam_r.3 new file mode 100644 index 000000000..e83dcaf7e --- /dev/null +++ b/man3/getpwnam_r.3 @@ -0,0 +1 @@ +.so man3/getpwnam.3 diff --git a/man3/getpwuid.3 b/man3/getpwuid.3 new file mode 100644 index 000000000..e83dcaf7e --- /dev/null +++ b/man3/getpwuid.3 @@ -0,0 +1 @@ +.so man3/getpwnam.3 diff --git a/man3/getpwuid_r.3 b/man3/getpwuid_r.3 new file mode 100644 index 000000000..e83dcaf7e --- /dev/null +++ b/man3/getpwuid_r.3 @@ -0,0 +1 @@ +.so man3/getpwnam.3 diff --git a/man3/getrpcbyname.3 b/man3/getrpcbyname.3 new file mode 100644 index 000000000..923085e2e --- /dev/null +++ b/man3/getrpcbyname.3 @@ -0,0 +1 @@ +.so man3/getrpcent.3 diff --git a/man3/getrpcbynumber.3 b/man3/getrpcbynumber.3 new file mode 100644 index 000000000..923085e2e --- /dev/null +++ b/man3/getrpcbynumber.3 @@ -0,0 +1 @@ +.so man3/getrpcent.3 diff --git a/man3/getrpcent.3 b/man3/getrpcent.3 new file mode 100644 index 000000000..bca818f0d --- /dev/null +++ b/man3/getrpcent.3 @@ -0,0 +1,109 @@ +.\" @(#)getrpcent.3n 2.2 88/08/02 4.0 RPCSRC; from 1.11 88/03/14 SMI +.TH GETRPCENT 3 1987-12-14 +.SH NAME +getrpcent, getrpcbyname, getrpcbynumber \- get RPC entry +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +struct rpcent *getrpcent() +.LP +.ft B +struct rpcent *getrpcbyname(name) +char *name; +.LP +.ft B +struct rpcent *getrpcbynumber(number) +int number; +.LP +.ft B +setrpcent (stayopen) +int stayopen; +.LP +.ft B +endrpcent () +.fi +.SH DESCRIPTION +.LP +.BR getrpcent() , +.BR getrpcbyname() , +and +.B getrpcbynumber() +each return a pointer to an object with the +following structure +containing the broken-out +fields of a line in the rpc program number data base, +.BR /etc/rpc . +.RS +.LP +.nf +.ft B +struct rpcent { + char *r_name; /* name of server for this rpc program */ + char **r_aliases; /* alias list */ + long r_number; /* rpc program number */ +}; +.ft R +.fi +.RE +.LP +The members of this structure are: +.RS +.PD 0 +.TP 20 +.B r_name +The name of the server for this rpc program. +.TP 20 +.B r_aliases +A zero terminated list of alternate names for the rpc program. +.TP 20 +.B r_number +The rpc program number for this service. +.PD +.RE +.LP +.B getrpcent() +reads the next line of the file, opening the file if necessary. +.LP +.B getrpcent() +opens and rewinds the file. If the +.I stayopen +flag is non-zero, +the net data base will not be closed after each call to +.B getrpcent() +(either directly, or indirectly through one of +the other \*(lqgetrpc\*(rq calls). +.LP +.B endrpcent +closes the file. +.LP +.B getrpcbyname() +and +.B getrpcbynumber() +sequentially search from the beginning +of the file until a matching rpc program name or +program number is found, or until end-of-file is encountered. +.SH FILES +.PD 0 +.TP 20 +.B /etc/rpc +.PD +.SH "SEE ALSO" +.BR rpc (5), +.BR rpcinfo (8), +.BR ypserv (8) +.SH DIAGNOSTICS +.LP +A +.SM NULL +pointer is returned on +.SM EOF +or error. +.SH BUGS +.LP +All information +is contained in a static area +so it must be copied if it is +to be saved. diff --git a/man3/getrpcport.3 b/man3/getrpcport.3 new file mode 100644 index 000000000..a299fe60a --- /dev/null +++ b/man3/getrpcport.3 @@ -0,0 +1,30 @@ +.\" @(#)getrpcport.3r 2.2 88/08/02 4.0 RPCSRC; from 1.12 88/02/26 SMI +.TH GETRPCPORT 3R 1987-10-06 +.SH NAME +getrpcport \- get RPC port number +.SH SYNOPSIS +.ft B +.nf +int getrpcport(host, prognum, versnum, proto) + char *host; + int prognum, versnum, proto; +.fi +.SH DESCRIPTION +.B getrpcport() +returns the port number for version +.I versnum +of the RPC program +.I prognum +running on +.I host +and using protocol +.IR proto . +It returns 0 if it cannot contact the portmapper, or if +.I prognum +is not registered. If +.I prognum +is registered but not with version +.IR versnum , +it will still return a port number (for some version of the program) +indicating that the program is indeed registered. +The version mismatch will be detected upon the first call to the service. diff --git a/man3/gets.3 b/man3/gets.3 new file mode 100644 index 000000000..4f9671fd9 --- /dev/null +++ b/man3/gets.3 @@ -0,0 +1,164 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Wed Jul 28 11:12:07 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Sep 8 15:48:13 1995 by Andries Brouwer (aeb@cwi.nl) +.TH GETS 3 1993-04-04 "GNU" "Linux Programmer's Manual" +.SH NAME +fgetc, fgets, getc, getchar, gets, ungetc \- input of characters and strings +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int fgetc(FILE *" stream ); +.nl +.BI "char *fgets(char *" "s" ", int " "size" ", FILE *" "stream" ); +.nl +.BI "int getc(FILE *" stream ); +.nl +.BI "int getchar(void);" +.nl +.BI "char *gets(char *" "s" ); +.nl +.BI "int ungetc(int " c ", FILE *" stream ); +.SH DESCRIPTION +.B fgetc() +reads the next character from +.I stream +and returns it as an +.B unsigned char +cast to an +.BR int , +or +.B EOF +on end of file or error. +.PP +.B getc() +is equivalent to +.B fgetc() +except that it may be implemented as a macro which evaluates +.I stream +more than once. +.PP +.B getchar() +is equivalent to +.BI "getc(" stdin ) \fR. +.PP +.BR gets() " reads" +a line from +.I stdin +into the buffer pointed to by +.I s +until either a terminating newline or +.BR EOF , +which it replaces with +.BR '\e0' . +No check for buffer overrun is performed (see +.B BUGS +below). +.PP +.B fgets() +reads in at most one less than +.I size +characters from +.I stream +and stores them into the buffer pointed to by +.IR s . +Reading stops after an +.B EOF +or a newline. If a newline is read, it is stored into the buffer. A +.B '\e0' +is stored after the last character in the buffer. +.PP +.B ungetc() +pushes +.I c +back to +.IR stream , +cast to +.BR "unsigned char" , +where it is available for subsequent read operations. Pushed - back characters +will be returned in reverse order; only one pushback is guaranteed. +.PP +Calls to the functions described here can be mixed with each other and with +calls to other input functions from the +.B stdio +library for the same input stream. +.PP +For non-locking counterparts, see +.BR unlocked_stdio (3). +.SH "RETURN VALUE" +.BR fgetc() , " getc() " and " getchar()" +return the character read as an +.B unsigned char +cast to an +.B int +or +.B EOF +on end of file or error. +.PP +.BR gets() " and " fgets() +return +.I s +on success, and +.B NULL +on error or when end of file occurs while no characters have been read. +.PP +.B ungetc() +returns +.I c +on success, or +.B EOF +on error. +.SH "CONFORMING TO" +ANSI - C, POSIX.1. +LSB deprecates +.BR gets() . +.SH BUGS +Never use +.BR gets() . +Because it is impossible to tell without knowing the data in advance how many +characters +.B gets() +will read, and because +.B gets() +will continue to store characters past the end of the buffer, it is extremely +dangerous to use. It has been used to break computer security. Use +.B fgets() +instead. +.PP +It is not advisable to mix calls to input functions from the +.B stdio +library with low - level calls to +.B read() +for the file descriptor associated with the input stream; the results +will be undefined and very probably not what you want. +.SH "SEE ALSO" +.BR read (2), +.BR write (2), +.BR ferror (3), +.BR fopen (3), +.BR fread (3), +.BR fseek (3), +.BR puts (3), +.BR scanf (3), +.BR unlocked_stdio (3) diff --git a/man3/getservbyname.3 b/man3/getservbyname.3 new file mode 100644 index 000000000..eaafb1c1e --- /dev/null +++ b/man3/getservbyname.3 @@ -0,0 +1 @@ +.so man3/getservent.3 diff --git a/man3/getservbyport.3 b/man3/getservbyport.3 new file mode 100644 index 000000000..eaafb1c1e --- /dev/null +++ b/man3/getservbyport.3 @@ -0,0 +1 @@ +.so man3/getservent.3 diff --git a/man3/getservent.3 b/man3/getservent.3 new file mode 100644 index 000000000..5500f5933 --- /dev/null +++ b/man3/getservent.3 @@ -0,0 +1,115 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:19:11 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Wed Oct 18 20:23:54 1995 by Martin Schulze +.\" Modified Mon Apr 22 01:50:54 1996 by Martin Schulze +.\" 2001-07-25 added a clause about NULL proto (Martin Michlmayr or David N. Welton) +.\" +.TH GETSERVENT 3 2001-07-25 "BSD" "Linux Programmer's Manual" +.SH NAME +getservent, getservbyname, getservbyport, setservent, endservent \- +get service entry +.SH SYNOPSIS +.nf +.B #include +.sp +.B struct servent *getservent(void); +.sp +.BI "struct servent *getservbyname(const char *" name ", const char *" proto ); +.sp +.BI "struct servent *getservbyport(int " port ", const char *" proto ); +.sp +.BI "void setservent(int " stayopen ); +.sp +.B void endservent(void); +.fi +.SH DESCRIPTION +The \fBgetservent()\fP function reads the next line from the file +\fI/etc/services\fP and returns a structure \fIservent\fP containing +the broken out fields from the line. The \fI/etc/services\fP file +is opened if necessary. +.PP +The \fBgetservbyname()\fP function returns a \fIservent\fP structure +for the line from \fI/etc/services\fP that matches the service +\fIname\fP using protocol \fIproto\fP. If \fIproto\fP is NULL, +any protocol will be matched. +.PP +The \fBgetservbyport()\fP function returns a \fIservent\fP structure +for the line that matches the port \fIport\fP given in network byte order +using protocol \fIproto\fP. If \fIproto\fP is NULL, +any protocol will be matched. +.PP +The \fBsetservent()\fP function opens and rewinds the +\fI/etc/services\fP file. If \fIstayopen\fP is true (1), then the +file will not be closed between calls to \fBgetservbyname()\fP and +\fBgetservbyport()\fP. +.PP +The \fBendservent()\fP function closes \fI/etc/services\fP. +.PP +The \fIservent\fP structure is defined in \fI\fP as follows: +.sp +.RS +.nf +.ne 6 +.ta 8n 16n 32n +struct servent { + char *s_name; /* official service name */ + char **s_aliases; /* alias list */ + int s_port; /* port number */ + char *s_proto; /* protocol to use */ +} +.ta +.fi +.RE +.PP +The members of the \fIservent\fP structure are: +.TP +.I s_name +The official name of the service. +.TP +.I s_aliases +A zero terminated list of alternative names for the service. +.TP +.I s_port +The port number for the service given in network byte order. +.TP +.I s_proto +The name of the protocol to use with this service. +.SH "RETURN VALUE" +The \fBgetservent()\fP, \fBgetservbyname()\fP and \fBgetservbyport()\fP +functions return the \fIservent\fP structure, or a NULL pointer if an +error occurs or the end of the file is reached. +.SH FILES +.TP +.I /etc/services +services database file +.SH "CONFORMING TO" +BSD 4.3 +.SH "SEE ALSO" +.BR getnetent (3), +.BR getprotoent (3), +.BR services (5) diff --git a/man3/getspent.3 b/man3/getspent.3 new file mode 100644 index 000000000..142c5a5ca --- /dev/null +++ b/man3/getspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/getspent_r.3 b/man3/getspent_r.3 new file mode 100644 index 000000000..142c5a5ca --- /dev/null +++ b/man3/getspent_r.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/getspnam.3 b/man3/getspnam.3 new file mode 100644 index 000000000..1b6b1232c --- /dev/null +++ b/man3/getspnam.3 @@ -0,0 +1,212 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) and +.\" Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" Distributed under GPL +.\" +.TH GETSPNAM 3 2003-11-15 "Shadow" "Linux Programmer's Manual" +.SH NAME +getspnam, getspnam_r, getspent, getspent_r, setspent, endspent, +fgetspent, fgetspent_r, sgetspent, sgetspent_r, putspent, +lckpwdf, ulckpwdf \- get shadow password file entry +.SH SYNOPSIS +.nf +/* General shadow password file API */ +.br +.B #include +.sp +.BI "struct spwd *getspnam(const char *" name ); +.sp +.B struct spwd *getspent(void); +.sp +.B void setspent(void); +.sp +.B void endspent(void); +.sp +.BI "struct spwd *fgetspent(FILE *" fp ); +.sp +.BI "struct spwd *sgetspent(const char *" s ); +.sp +.BI "int putspent(struct spwd *" p ", FILE *" fp ); +.sp +.B int lckpwdf(void); +.sp +.B int ulckpwdf(void); +.sp +/* GNU extension */ +.br +.BR "#define _SVID_SOURCE" " /* or _BSD_SOURCE */ +.br +.B #include +.sp +.BI "int getspent_r(struct spwd *" spbuf , +.br +.BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); +.sp +.BI "int getspnam_r(const char *" name ", struct spwd *" spbuf , +.br +.BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); +.sp +.BI "int fgetspent_r(FILE *" fp ", struct spwd *" spbuf , +.br +.BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); +.sp +.BI "int sgetspent_r(const char *" s ", struct spwd *" spbuf , +.br +.BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); +.sp +.fi +.SH DESCRIPTION +Long ago it was considered safe to have encrypted passwords openly +visible in the password file. When computers got faster and people +got more security-conscious, this was no longer acceptable. +Julianne Frances Haugh implemented the shadow password suite +that keeps the encrypted passwords in +.IR /etc/shadow , +readable only by root. +.LP +The access routines described below resemble those for +.IR /etc/passwd . +This shadow password setup has been superseded by PAM +(pluggable authentication modules), and the file +.I /etc/nsswitch.conf +now describes the sources to be used. +.LP +The +.B getspnam() +function returns a pointer to a structure containing +the broken out fields of a line from +.I /etc/shadow +for the entry that matches the user name +.IR name . +.LP +The +.B getspent() +function returns a pointer to the next entry in the shadow password file. +The position in the input stream is initialized by +.BR setspent() . +When done reading, the program may call +.BR endspent() +so that resources can be deallocated. +.\" some systems require a call of setspent() before the first getspent() +.\" glibc does not +.LP +The +.B fgetspent() +function is similar to +.B getspent() +but uses the supplied stream instead of the one implicitly opened by +.BR setspent() . +.LP +The +.B sgetspent() +function parses the supplied string +.I s +into a struct spwd. +.LP +The +.B putspent() +function writes the contents of the supplied struct spwd +.RI * p +as a text line in the shadow password file format to the stream +.IR fp . +String entries with value NULL and numerical entries with value \-1 +are written as an empty string. +.LP +The +.B lckpwdf() +function is intended to protect against multiple access of the shadow +password database. It tries to acquire a lock, and returns 0 on success, +\-1 on failure (lock not obtained within 15 seconds). +The +.B ulckpwdf() +function releases the lock again. +Note that there is no protection against direct access of the shadow +password file. Only programs that use +.B lckpwdf() +will notice the lock. +.LP +These were the routines that formed the original shadow API. +They are widely available. +.\" Also in libc5 +.\" SUN doesn't have sgetspent() +.SS "Reentrant versions" +Analogous to the "reentrant" routines for the password file, glibc +also has reentrant versions here. +The +.B getspnam_r() +function is like +.B getspnam() +but stores the retrieved shadow passwd structure in the space pointed to by +.IR spbuf . +This shadow passwd structure contains pointers to strings, and these strings +are stored in the buffer +.I buf +of size +.IR buflen . +A pointer to the result (in case of success) or NULL (in case no entry +was found or an error occurred) is stored in +.RI * spbufp . +.LP +The functions +.BR getspent_r() , +.BR fgetspent_r() , +and +.BR sgetspent_r() +are completely analogous. +.LP +Some non-glibc systems also have functions with these names, +often with different prototypes. +.\" SUN doesn't have sgetspent_r() +.SS Structure +The shadow passwd structure is defined in \fI\fP as follows: +.sp +.nf +struct spwd { + char *sp_namp; /* Login name */ + char *sp_pwdp; /* Encrypted password */ + long sp_lstchg; /* Date of last change */ + long sp_min; /* Min #days between changes */ + long sp_max; /* Max #days between changes */ + long sp_warn; /* #days before pwd expires + to warn user to change it */ + long sp_inact; /* #days after pwd expires + until account is disabled */ + long sp_expire; /* #days since 1970-01-01 + until account is disabled */ + unsigned long sp_flag; /* Reserved */ +}; +.fi +.SH "RETURN VALUE" +Routines return NULL if no more entries are available or if an +error occurs during processing. +Routines which have \fBint\fR as the return value return 0 for +success and -1 for failure. +.LP +For the non-reentrant functions, the return value may point to static area, +and may be overwritten by subsequent calls to these functions. +.LP +The reentrant functions return zero on success. +In case of error, an error value is returned. +.SH ERRORS +.TP +.B ERANGE +Supplied buffer is too small. +.SH FILES +.TP +.I /etc/shadow +shadow password database file +.TP +.I /etc/.pwd.lock +lock file +.LP +The include file +.I +defines the constant _PATH_SHADOW to the pathname of the shadow +password file. +.SH "CONFORMING TO" + +.SH "SEE ALSO" +.BR getgrnam (3), +.BR getpwnam (3), +.BR getpwnam_r (3), +.BR shadow (5) diff --git a/man3/getspnam_r.3 b/man3/getspnam_r.3 new file mode 100644 index 000000000..142c5a5ca --- /dev/null +++ b/man3/getspnam_r.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/getttyent.3 b/man3/getttyent.3 new file mode 100644 index 000000000..0c8e74702 --- /dev/null +++ b/man3/getttyent.3 @@ -0,0 +1,67 @@ +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH GETTTYENT 3 2002-07-18 "glibc" +.SH NAME +getttyent, getttynam, setttyent, endttyent - get ttys file entry +.SH SYNOPSIS +.sp +.B "#include " +.sp +.B "struct ttyent *getttyent(void);" +.sp +.BI "struct ttyent *getttynam(const char *" name ); +.sp +.B "int setttyent(void);" +.sp +.B "int endttyent(void);" +.SH DESCRIPTION +These functions provide an interface to the file +.B _PATH_TTYS +(e.g., +.IR /etc/ttys ). + +The function +.BR setttyent () +opens the file or rewinds it if already open. + +The function +.BR endttyent () +closes the file. + +The function +.BR getttynam () +searches for a given ttyname in the file. It returns a pointer to a +struct ttyent (description below). + +The function +.BR getttyent () +opens the file _PATH_TTYS (if necessary) and returns the first entry. +If the file is already open, the next entry. + +.SS "The ttyent structure" +.nf +struct ttyent { + char *ty_name; /* terminal device name */ + char *ty_getty; /* command to execute, usually getty */ + char *ty_type; /* terminal type for termcap */ + int ty_status; /* status flags */ + char *ty_window; /* command to start up window manager */ + char *ty_comment; /* comment field */ +}; +.fi + +.I ty_status +can be +.br +.nf +#define TTY_ON 0x01 /* enable logins (start ty_getty program) */ +#define TTY_SECURE 0x02 /* allow uid 0 to login */ +.fi +.SH NOTES +Under Linux the file +.IR /etc/ttys , +and the functions described above, are not used. +.SH "SEE ALSO" +.BR ttyname (3), +.BR ttyslot (3) diff --git a/man3/getttynam.3 b/man3/getttynam.3 new file mode 100644 index 000000000..1cd11e3d8 --- /dev/null +++ b/man3/getttynam.3 @@ -0,0 +1 @@ +.so man3/getttyent.3 diff --git a/man3/getumask.3 b/man3/getumask.3 new file mode 100644 index 000000000..78b373809 --- /dev/null +++ b/man3/getumask.3 @@ -0,0 +1,56 @@ +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.\" +.TH GETUMASK 3 2002-08-25 "GNU" "Linux Programmer's Manual" +.SH NAME +getumask \- get file creation mask +.SH SYNOPSIS +.B "#include " +.br +.B "#include " +.sp +.B "mode_t getumask(void);" +.SH DESCRIPTION +This function returns the current file creation mask. +It is equivalent to +.RS +.nf +mode_t getumask(void) { + mode_t mask = umask(0); + umask(mask); + return mask; +} +.fi +.RE +except that it is documented to be thread-safe (that is, shares +a lock with the +.I umask() +library call). +.SH NOTES +This function is documented but not implemented yet in glibc 2.2.5. +.SH "CONFORMING TO" +This is a vapourware GNU extension. +.SH "SEE ALSO" +.BR umask (2) diff --git a/man3/getusershell.3 b/man3/getusershell.3 new file mode 100644 index 000000000..95728c17f --- /dev/null +++ b/man3/getusershell.3 @@ -0,0 +1,60 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:17:53 1993 by Rik Faith (faith@cs.unc.edu) +.TH GETUSERSHELL 3 1993-07-04 "BSD" "Linux Programmer's Manual" +.SH NAME +getusershell, setusershell, endusershell \- get legal user shells +.SH SYNOPSIS +.nf +.B #include +.sp +.B char *getusershell(void); +.sp +.B void setusershell(void); +.sp +.B void endusershell(void); +.fi +.SH DESCRIPTION +The \fBgetusershell()\fP function returns the next line from the file +\fI/etc/shells\fP, opening the file if necessary. The line should contain +the pathname of a valid user shell. If \fI/etc/shells\fP does not exist or +is unreadable, \fBgetusershell()\fP behaves as if \fI/bin/sh\fP and +\fI/bin/csh\fP were listed in the file. +.PP +The \fBsetusershell()\fP function rewinds \fI/etc/shells\fP. +.PP +The \fBendusershell()\fP function closes \fI/etc/shells\fP. +.SH "RETURN VALUE" +The \fBgetusershell()\fP function returns a NULL pointer on end-of-file. +.SH FILES +.nf +/etc/shells +.fi +.SH "CONFORMING TO" +BSD 4.3 +.SH "SEE ALSO" +.BR shells (5) diff --git a/man3/getutent.3 b/man3/getutent.3 new file mode 100644 index 000000000..128577562 --- /dev/null +++ b/man3/getutent.3 @@ -0,0 +1,197 @@ +.\" Copyright 1995 Mark D. Roth (roth@uiuc.edu) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Solaris manpages +.\" +.\" Modified Thu Jul 25 14:43:46 MET DST 1996 by Michael Haardt +.\" +.TH GETUTENT 3 1996-07-25 "" "Library functions" +.SH NAME +getutent, getutid, getutline, pututline, setutent, endutent, utmpname \- access utmp file entries +.SH SYNOPSIS +.B #include +.sp +.B struct utmp *getutent(void); +.br +.BI "struct utmp *getutid(struct utmp *" ut ); +.br +.BI "struct utmp *getutline(struct utmp *" ut ); +.sp +.BI "struct utmp *pututline(struct utmp *" ut ); +.sp +.B void setutent(void); +.br +.B void endutent(void); +.sp +.BI "void utmpname(const char *" file ); +.SH DESCRIPTION +\fButmpname\fP() sets the name of the utmp-format file for the other utmp +functions to access. If \fButmpname\fP() is not used to set the filename +before the other functions are used, they assume \fB_PATH_UTMP\fP, as +defined in \fI\fP. +.PP +\fBsetutent\fP() rewinds the file pointer to the beginning of the utmp file. +It is generally a Good Idea to call it before any of the other +functions. +.PP +\fBendutent\fP() closes the utmp file. It should be called when the user +code is done accessing the file with the other functions. +.PP +\fBgetutent\fP() reads a line from the current file position in the utmp +file. It returns a pointer to a structure containing the fields of +the line. +.PP +\fBgetutid\fP() searches forward from the current file position in the utmp +file based upon \fIut\fP. If \fIut\fP->ut_type is one of \fBRUN_LVL\fP, +\fBBOOT_TIME\fP, \fBNEW_TIME\fP, or \fBOLD_TIME\fP, \fBgetutid\fP() will +find the first entry whose \fIut_type\fP field matches \fIut\fP->ut_type. +If \fIut\fP->ut_type is one of \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP, +\fBUSER_PROCESS\fP, or \fBDEAD_PROCESS\fP, \fBgetutid\fP() will find the +first entry whose ut_id field matches \fIut\fP->ut_id. +.PP +\fBgetutline\fP() searches forward from the current file position in the +utmp file. It scans entries whose ut_type is \fBUSER_PROCESS\fP +or \fBLOGIN_PROCESS\fP and returns the first one whose ut_line field +matches \fIut\fP->ut_line. +.PP +\fBpututline\fP() writes the utmp structure \fIut\fP into the utmp file. It +uses \fBgetutid\fP() to search for the proper place in the file to insert +the new entry. If it cannot find an appropriate slot for \fIut\fP, +\fBpututline\fP() will append the new entry to the end of the file. +.SH "RETURN VALUE" +\fBgetutent\fP(), \fBgetutid\fP(), \fBgetutline\fP() and \fBpututline\fP() +return a pointer to a \fBstruct utmp\fP on success, and NULL on failure. +This \fBstruct utmp\fP is allocated in static storage, and may be +overwritten by subsequent calls. +.SH "REENTRANT VERSIONS" +These above functions are not thread-safe. Glibc adds reentrant versions +.sp +.nf +.BR "#define _GNU_SOURCE" " /* or _SVID_SOURCE or _BSD_SOURCE */ +.B #include +.sp +.BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp ); +.sp +.BI "int getutid_r(struct utmp *" ut , +.BI " struct utmp *" ubuf ", struct utmp **" ubufp ); +.sp +.BI "int getutline_r(struct utmp *" ut , +.BI " struct utmp *" ubuf ", struct utmp **" ubufp ); +.fi +.sp +These functions are GNU extensions, analogs of the functions of the +same name without the _r suffix. The +.I ubuf +parameter gives these functions a place to store their result. +On success they return 0, and a pointer to the result is written in +.RI * ubufp . +On error these functions return \-1. +.SH EXAMPLE +The following example adds and removes a utmp record, assuming it is run +from within a pseudo terminal. For usage in a real application, you +should check the return values of getpwuid() and ttyname(). +.PP +.nf +#include +#include +#include +#include +#include + +int main(int argc, char *argv[]) +{ + struct utmp entry; + + system("echo before adding entry:;who"); + + entry.ut_type=USER_PROCESS; + entry.ut_pid=getpid(); + strcpy(entry.ut_line,ttyname(0)+strlen("/dev/")); + /* only correct for ptys named /dev/tty[pqr][0-9a-z] */ + strcpy(entry.ut_id,ttyname(0)+strlen("/dev/tty")); + time(&entry.ut_time); + strcpy(entry.ut_user,getpwuid(getuid())->pw_name); + memset(entry.ut_host,0,UT_HOSTSIZE); + entry.ut_addr=0; + setutent(); + pututline(&entry); + + system("echo after adding entry:;who"); + + entry.ut_type=DEAD_PROCESS; + memset(entry.ut_line,0,UT_LINESIZE); + entry.ut_time=0; + memset(entry.ut_user,0,UT_NAMESIZE); + setutent(); + pututline(&entry); + + system("echo after removing entry:;who"); + + endutent(); + return 0; +} +.fi +.SH FILES +/var/run/utmp database of currently logged-in users +.br +/var/log/wtmp database of past user logins +.SH "CONFORMING TO" +XPG 2, SVID 2, Linux FSSTND 1.2 +.LP +In XPG2 and SVID2 the function \fIpututline()\fP is documented +to return void, and that is what it does on many systems +(AIX, HPUX, Linux libc5). +HPUX introduces a new function \fI_pututline()\fP with the prototype +given above for \fIpututline()\fP (also found in Linux libc5). +.LP +All these functions are obsolete now on non-Linux systems. +POSIX 1003.1-2001, following XPG4.2, +does not have any of these functions, but instead uses +.sp +.B #include +.sp +.B struct utmpx *getutxent(void); +.br +.B struct utmpx *getutxid(const struct utmpx *); +.br +.B struct utmpx *getutxline(const struct utmpx *); +.br +.B struct utmpx *pututxline(const struct utmpx *); +.br +.B void setutxent(void); +.br +.B void endutxent(void); +.sp +The \fIutmpx\fP structure is a superset of the \fIutmp\fP structure, +with additional fields, and larger versions of the existing fields. +The corresponding files are often +.I /var/*/utmpx +and +.IR /var/*/wtmpx . +.LP +Linux glibc on the other hand does not use \fIutmpx\fP since its +\fIutmp\fP structure is already large enough. The functions \fIgetutxent\fP +etc. are aliases for \fIgetutent\fP etc. +.SH "SEE ALSO" +.BR utmp (5) diff --git a/man3/getutent_r.3 b/man3/getutent_r.3 new file mode 100644 index 000000000..29c36b72a --- /dev/null +++ b/man3/getutent_r.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/getutid.3 b/man3/getutid.3 new file mode 100644 index 000000000..29c36b72a --- /dev/null +++ b/man3/getutid.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/getutid_r.3 b/man3/getutid_r.3 new file mode 100644 index 000000000..29c36b72a --- /dev/null +++ b/man3/getutid_r.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/getutline.3 b/man3/getutline.3 new file mode 100644 index 000000000..29c36b72a --- /dev/null +++ b/man3/getutline.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/getutline_r.3 b/man3/getutline_r.3 new file mode 100644 index 000000000..29c36b72a --- /dev/null +++ b/man3/getutline_r.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/getutxent.3 b/man3/getutxent.3 new file mode 100644 index 000000000..29c36b72a --- /dev/null +++ b/man3/getutxent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/getutxid.3 b/man3/getutxid.3 new file mode 100644 index 000000000..29c36b72a --- /dev/null +++ b/man3/getutxid.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/getutxline.3 b/man3/getutxline.3 new file mode 100644 index 000000000..29c36b72a --- /dev/null +++ b/man3/getutxline.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/getw.3 b/man3/getw.3 new file mode 100644 index 000000000..cda186812 --- /dev/null +++ b/man3/getw.3 @@ -0,0 +1,55 @@ +.\" (c) 1995 by Jim Van Zandt +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.TH GETW 3 1995-09-16 "GNU" "Linux Programmer's Manual" +.SH NAME +getw, putw \- input and output of words (ints) +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int getw(FILE *" stream ); +.nl +.BI "int putw(int " w ", FILE *" stream ); +.nl +.SH DESCRIPTION +\fBgetw\fP reads a word (that is, an \fBint\fP) from \fIstream\fP. It's +provided for compatibility with SVID. We recommend you use +\fBfread\fP(3) instead. +.P +\fBputw\fP writes the word \fIw\fP (that is, an \fBint\fP) to \fIstream\fP. It +is provided for compatibility with SVID, but we recommend you use +\fBfwrite\fP(3) instead. +.SH "RETURN VALUE" +Normally, \fBgetw\fP returns the word read, and \fBputw\fP returns 0. +On error, they return \fBEOF\fP. +.SH BUGS +The value returned on error is also a legitimate data value. +\fBferror\fP(3) can be used to distinguish between the two cases. +.SH "CONFORMING TO" +SVID +.SH "SEE ALSO" +.BR ferror (3), +.BR fread (3), +.BR fwrite (3), +.BR getc (3), +.BR putc (3) diff --git a/man3/getwc.3 b/man3/getwc.3 new file mode 100644 index 000000000..358c2d214 --- /dev/null +++ b/man3/getwc.3 @@ -0,0 +1 @@ +.so man3/fgetwc.3 diff --git a/man3/getwc_unlocked.3 b/man3/getwc_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/getwc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/getwchar.3 b/man3/getwchar.3 new file mode 100644 index 000000000..24bab9dfd --- /dev/null +++ b/man3/getwchar.3 @@ -0,0 +1,46 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH GETWCHAR 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +getwchar \- read a wide character from standard input +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wint_t getwchar(void);" +.fi +.SH DESCRIPTION +The \fBgetwchar\fP function is the wide-character equivalent of the +\fBgetchar\fP function. It reads a wide character from \fBstdin\fP and returns +it. If the end of stream is reached, or if \fIferror(stdin)\fP becomes +true, it returns WEOF. If a wide character conversion error occurs, it sets +\fBerrno\fP to \fBEILSEQ\fP and returns WEOF. +.PP +For a non-locking counterpart, see +.BR unlocked_stdio (3). +.SH "RETURN VALUE" +The \fBgetwchar\fP function returns the next wide-character from +standard input, or WEOF. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH NOTES +The behaviour of \fBgetwchar\fP depends on the LC_CTYPE category of the +current locale. +.PP +It is reasonable to expect that \fBgetwchar\fP will actually read a multibyte +sequence from standard input and then convert it to a wide character. +.SH "SEE ALSO" +.BR fgetwc (3), +.BR unlocked_stdio (3) diff --git a/man3/getwchar_unlocked.3 b/man3/getwchar_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/getwchar_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/getwd.3 b/man3/getwd.3 new file mode 100644 index 000000000..f73c1579c --- /dev/null +++ b/man3/getwd.3 @@ -0,0 +1 @@ +.so man3/getcwd.3 diff --git a/man3/glob.3 b/man3/glob.3 new file mode 100644 index 000000000..e64277bd7 --- /dev/null +++ b/man3/glob.3 @@ -0,0 +1,252 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Wed Jul 28 11:12:17 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 13 23:08:50 1996 by Martin Schulze (joey@linux.de) +.\" Modified 11 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" Modified 990912 by aeb +.\" +.TH GLOB 3 1999-09-12 "GNU" "Linux Programmer's Manual" +.SH NAME +glob, globfree \- find pathnames matching a pattern, free memory from glob() +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int glob(const char *" pattern ", int " flags , +.nl +.BI " int " errfunc "(const char *" epath ", int " eerrno ), +.nl +.BI " glob_t *" pglob ); +.nl +.BI "void globfree(glob_t *" pglob ); +.fi +.SH DESCRIPTION +The +.B glob() +function searches for all the pathnames matching +.I pattern +according to the rules used by the shell (see +.BR glob (7)). +No tilde expansion or parameter substitution is done; if you want +these, use +.BR wordexp (3). +.PP +The +.B globfree() +function frees the dynamically allocated storage from an earlier call +to +.BR glob() . +.PP +The results of a +.B glob() +call are stored in the structure pointed to by +.IR pglob , +which is a +.B glob_t +which is declared in +.B +and includes the following elements defined by POSIX.2 (more may be +present as an extension): +.PP +.br +.nf +.in 10 +typedef struct +{ +.in 14 + size_t gl_pathc; /* Count of paths matched so far */ + char **gl_pathv; /* List of matched pathnames. */ + size_t gl_offs; /* Slots to reserve in `gl_pathv'. */ +.in 10 +} glob_t; +.fi +.PP +Results are stored in dynamically allocated storage. +.PP +The parameter +.I flags +is made up of bitwise OR of zero or more the following symbolic +constants, which modify the of behaviour of +.BR glob() : +.TP +.B GLOB_ERR +which means to return upon read error (because a directory does not +have read permission, for example), +.TP +.B GLOB_MARK +which means to append a slash to each path which corresponds to a directory, +.TP +.B GLOB_NOSORT +which means don't sort the returned pathnames (they are by default), +.TP +.B GLOB_DOOFFS +which means that +.I pglob->gl_offs +slots will be reserved at the beginning of the list of strings in +.IR pglob->pathv , +.TP +.B GLOB_NOCHECK +which means that, if no pattern matches, to return the original pattern, +.TP +.B GLOB_APPEND +which means to append to the results of a previous call. Do not set +this flag on the first invocation of +.BR glob() . +.TP +.B GLOB_NOESCAPE +which means that meta characters cannot be quoted by backslashes. +.PP +The flags may also include some of the following, which are GNU +extensions and not defined by POSIX.2: +.TP +.B GLOB_PERIOD +which means that a leading period can be matched by meta characters, +.TP +.B GLOB_ALTDIRFUNC +which means that alternative functions +.IR pglob->gl_closedir , +.IR pglob->gl_readdir , +.IR pglob->gl_opendir , +.IR pglob->gl_lstat ", and" +.I pglob->gl_stat +are used for file system access instead of the normal library +functions, +.TP +.B GLOB_BRACE +which means that +.BR csh (1) +style brace expresions \fB{a,b}\fR are expanded, +.TP +.B GLOB_NOMAGIC +which means that the pattern is returned if it contains no metacharacters, +.TP +.B GLOB_TILDE +which means that tilde expansion is carried out, and +.TP +.B GLOB_ONLYDIR +which means that only directories are matched. +.PP +If +.I errfunc +is not +.BR NULL , +it will be called in case of an error with the arguments +.IR epath , +a pointer to the path which failed, and +.IR eerrno , +the value of +.I errno +as returned from one of the calls to +.BR opendir() ", " readdir() ", or " stat() . +If +.I errfunc +returns non-zero, or if +.B GLOB_ERR +is set, +.B glob() +will terminate after the call to +.IR errfunc . +.PP +Upon successful return, +.I pglob->gl_pathc +contains the number of matched pathnames and +.I pglob->gl_pathv +a pointer to the list of matched pathnames. The first pointer after +the last pathname is +.BR NULL . +.PP +It is possible to call +.B glob() +several times. In that case, the +.B GLOB_APPEND +flag has to be set in +.I flags +on the second and later invocations. +.PP +As a GNU extension, +.I pglob->gl_flags +is set to the flags specified, \fBor\fRed with +.B GLOB_MAGCHAR +if any metacharacters were found. +.SH "RETURN VALUE" +On successful completion, +.B glob() +returns zero. +Other possible returns are: +.TP +.B GLOB_NOSPACE +for running out of memory, +.TP +.B GLOB_ABORTED +for a read error, and +.TP +.B GLOB_NOMATCH +for no found matches. +.SH EXAMPLES +One example of use is the following code, which simulates typing +.nl +.B ls -l *.c ../*.c +.nl +in the shell. +.nf +.in 10 + +glob_t globbuf; + +globbuf.gl_offs = 2; +glob("*.c", GLOB_DOOFFS, NULL, &globbuf); +glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf); +globbuf.gl_pathv[0] = "ls"; +globbuf.gl_pathv[1] = "-l"; +execvp("ls", &globbuf.gl_pathv[0]); +.fi +.SH "CONFORMING TO" +POSIX.2 +.SH BUGS +The +.B glob() +function may fail due to failure of underlying function calls, such as +.BR malloc() " or " opendir() . +These will store their error code in +.IR errno . +.SH NOTES +The structure elements +.I gl_pathc +and +.I gl_offs +are declared as +.BR size_t +in glibc 2.1, as they should according to POSIX.2, +but are declared as +.B int +in libc4, libc5 and glibc 2.0. +.SH "SEE ALSO" +.BR ls (1), +.BR sh (1), +.BR stat (2), +.BR exec (3), +.BR malloc (3), +.BR opendir (3), +.BR readdir (3), +.BR wordexp (3), +.BR glob (7) diff --git a/man3/globfree.3 b/man3/globfree.3 new file mode 100644 index 000000000..20056c69a --- /dev/null +++ b/man3/globfree.3 @@ -0,0 +1 @@ +.so man3/glob.3 diff --git a/man3/gmtime.3 b/man3/gmtime.3 new file mode 100644 index 000000000..84a3baa92 --- /dev/null +++ b/man3/gmtime.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man3/gmtime_r.3 b/man3/gmtime_r.3 new file mode 100644 index 000000000..84a3baa92 --- /dev/null +++ b/man3/gmtime_r.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man3/grantpt.3 b/man3/grantpt.3 new file mode 100644 index 000000000..761ee8a4c --- /dev/null +++ b/man3/grantpt.3 @@ -0,0 +1,60 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" This page is in the public domain. - aeb +.\" +.TH GRANTPT 3 "2003-01-30" "PTY Control" "Linux Programmer's Manual" +.SH NAME +grantpt \- grant access to the slave pseudotty +.SH SYNOPSIS +.nf +.B #define _XOPEN_SOURCE +.br +.B #include +.sp +.BI "int grantpt(int " fd ");" +.fi +.SH DESCRIPTION +The +.BR grantpt () +function changes the mode and owner of the slave pseudo-terminal device +(pty) corresponding to the master pty referred to by +.IR fd . +The user ID of the slave is set to the real UID of the calling process. +The group ID is set to an unspecified value (e.g. tty). +The mode of the slave is set to 0620 (crw\-\-w\-\-\-\-). +.PP +The behavior of +.BR grantpt () +is unspecified if a signal handler is installed to catch SIGCHLD signals. +.SH "RETURN VALUE" +When successful, +.BR grantpt () +returns 0. Otherwise, it returns \-1 and sets +.I errno +appropriately. +.SH ERRORS +.TP +.B EACCES +The corresponding slave pty could not be accessed. +.TP +.B EBADF +The +.I fd +argument is not a valid open file descriptor. +.TP +.B EINVAL +The +.I fd +argument is valid but not associated with a master pty. +.SH "CONFORMING TO" +POSIX 1003.1-2001 +.SH NOTES +This is part of the Unix98 pty support, see +.BR pts (4). +Many systems implement this function via a setuid helper binary +called "pt_chown". With Linux devpts no such helper binary is required. +.SH "SEE ALSO" +.BR open (2), +.BR getpt (3), +.BR ptsname (3), +.BR unlockpt (3), +.BR pts (4) diff --git a/man3/gsignal.3 b/man3/gsignal.3 new file mode 100644 index 000000000..60bc23c12 --- /dev/null +++ b/man3/gsignal.3 @@ -0,0 +1,84 @@ +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.TH GSIGNAL 3 2002-08-25 "notGNU" "Linux Programmer's Manual" +.SH NAME +gsignal, ssignal \- software signal facility +.SH SYNOPSIS +.nf +.B #include +.sp +.B typedef void (*sighandler_t)(int); +.sp +.BI "int gsignal(" signum ); +.sp +.BI "sighandler_t ssignal(int " signum ", sighandler_t " action ); +.SH DESCRIPTION +Don't use these functions under Linux. +Due to a historical mistake, under Linux these functions are +aliases for +.I raise() +and +.IR signal() , +respectively. +.LP +Elsewhere, on SYSV-like systems, these functions implement +software signalling, entirely independent of the classical +signal and kill functions. The function +.B ssignal() +defines the action to take when the software signal with +number +.I signum +is raised using the function +.BR gsignal() , +and returns the previous such action or SIG_DFL. +The function +.B gsignal() +does the following: if no action (or the action SIG_DFL) was +specified for +.IR signum , +then it does nothing and returns 0. +If the action SIG_IGN was specified for +.IR signum , +then it does nothing and returns 1. +Otherwise, it resets the action to SIG_DFL and calls +the action function with parameter +.IR signum , +and returns the value returned by that function. +The range of possible values +.I signum +varies (often 1-15 or 1-17). +.SH "CONFORMING TO" +SVID2, XPG2. +These functions are available under AIX, DG-UX, HPUX, SCO, Solaris, Tru64. +They are called obsolete under most of these systems, and are +broken under Linux libc and glibc. +Some systems also have +.I gsignal_r() +and +.IR ssignal_r() . +.SH "SEE ALSO" +.BR kill (2), +.BR signal (2), +.BR raise (3) diff --git a/man3/hash.3 b/man3/hash.3 new file mode 100644 index 000000000..b5ec7ea7e --- /dev/null +++ b/man3/hash.3 @@ -0,0 +1,159 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)hash.3 8.6 (Berkeley) 8/18/94 +.\" +.TH HASH 3 1994-08-18 +.UC 7 +.SH NAME +hash \- hash database access method +.SH SYNOPSIS +.nf +.ft B +#include +#include +.ft R +.fi +.SH DESCRIPTION +The routine +.IR dbopen +is the library interface to database files. +One of the supported file formats is hash files. +The general description of the database access methods is in +.IR dbopen (3), +this manual page describes only the hash specific information. +.PP +The hash data structure is an extensible, dynamic hashing scheme. +.PP +The access method specific data structure provided to +.I dbopen +is defined in the include file as follows: +.sp +typedef struct { +.RS +u_int bsize; +.br +u_int ffactor; +.br +u_int nelem; +.br +u_int cachesize; +.br +u_int32_t (*hash)(const void *, size_t); +.br +int lorder; +.RE +} HASHINFO; +.PP +The elements of this structure are as follows: +.TP +bsize +.I Bsize +defines the hash table bucket size, and is, by default, 256 bytes. +It may be preferable to increase the page size for disk-resident tables +and tables with large data items. +.TP +ffactor +.I Ffactor +indicates a desired density within the hash table. +It is an approximation of the number of keys allowed to accumulate in any +one bucket, determining when the hash table grows or shrinks. +The default value is 8. +.TP +nelem +.I Nelem +is an estimate of the final size of the hash table. +If not set or set too low, hash tables will expand gracefully as keys +are entered, although a slight performance degradation may be noticed. +The default value is 1. +.TP +cachesize +A suggested maximum size, in bytes, of the memory cache. +This value is +.B only +advisory, and the access method will allocate more memory rather +than fail. +.TP +hash +.I Hash +is a user defined hash function. +Since no hash function performs equally well on all possible data, the +user may find that the built-in hash function does poorly on a particular +data set. +User specified hash functions must take two arguments (a pointer to a byte +string and a length) and return a 32-bit quantity to be used as the hash +value. +.TP +lorder +The byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.I lorder +is 0 (no order is specified) the current host order is used. +If the file already exists, the specified value is ignored and the +value specified when the tree was created is used. +.PP +If the file already exists (and the O_TRUNC flag is not specified), the +values specified for the parameters bsize, ffactor, lorder and nelem are +ignored and the values specified when the tree was created are used. +.PP +If a hash function is specified, +.I hash_open +will attempt to determine if the hash function specified is the same as +the one with which the database was created, and will fail if it is not. +.PP +Backward compatible interfaces to the routines described in +.IR dbm (3), +and +.IR ndbm (3) +are provided, however these interfaces are not compatible with +previous file formats. +.SH ERRORS +The +.I hash +access method routines may fail and set +.I errno +for any of the errors specified for the library routine +.IR dbopen (3). +.SH "SEE ALSO" +.IR btree (3), +.IR dbopen (3), +.IR mpool (3), +.IR recno (3) +.sp +.IR "Dynamic Hash Tables" , +Per-Ake Larson, Communications of the ACM, April 1988. +.sp +.IR "A New Hash Package for UNIX" , +Margo Seltzer, USENIX Proceedings, Winter 1991. +.SH BUGS +Only big and little endian byte order is supported. diff --git a/man3/hasmntopt.3 b/man3/hasmntopt.3 new file mode 100644 index 000000000..3c2bb35c9 --- /dev/null +++ b/man3/hasmntopt.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man3/hcreate.3 b/man3/hcreate.3 new file mode 100644 index 000000000..f4a0405da --- /dev/null +++ b/man3/hcreate.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man3/hcreate_r.3 b/man3/hcreate_r.3 new file mode 100644 index 000000000..f4a0405da --- /dev/null +++ b/man3/hcreate_r.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man3/hdestroy.3 b/man3/hdestroy.3 new file mode 100644 index 000000000..f4a0405da --- /dev/null +++ b/man3/hdestroy.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man3/hdestroy_r.3 b/man3/hdestroy_r.3 new file mode 100644 index 000000000..f4a0405da --- /dev/null +++ b/man3/hdestroy_r.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man3/herror.3 b/man3/herror.3 new file mode 100644 index 000000000..7d0fb4b7c --- /dev/null +++ b/man3/herror.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/hsearch.3 b/man3/hsearch.3 new file mode 100644 index 000000000..b7d6e47d1 --- /dev/null +++ b/man3/hsearch.3 @@ -0,0 +1,197 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" Copyright 1993 Ulrich Drepper (drepper@karlsruhe.gmd.de) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" References consulted: +.\" SunOS 4.1.1 man pages +.\" Modified Sat Sep 30 21:52:01 1995 by Jim Van Zandt +.\" Remarks from dhw@gamgee.acad.emich.edu Fri Jun 19 06:46:31 1998 +.\" Modified 2001-12-26, 2003-11-28, 2004-05-20, aeb +.\" +.TH HSEARCH 3 2004-05-20 "GNU" "Linux Programmer's Manual" +.SH NAME +hcreate, hdestroy, hsearch \- hash table management +.SH SYNOPSIS +.B #include +.sp +.BI "int hcreate(size_t " nel ); +.sp +.BI "ENTRY *hsearch(ENTRY " item ", ACTION " action ); +.sp +.B "void hdestroy(void);" +.sp 2 +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "int hcreate_r(size_t " nel ", struct hsearch_data *" tab ); +.sp +.BI "int *hsearch_r(ENTRY " item ", ACTION " action , +.BI "ENTRY **" ret ", struct hsearch_data *" tab ); +.sp +.BI "void hdestroy_r(struct hsearch_data *" tab ); +.SH DESCRIPTION +The three functions +.BR hcreate , +.BR hsearch , +and +.BR hdestroy +allow the user to create a hash table (only one at a time) +which associates a key with any data. +.PP +First the table must be created with the function \fBhcreate()\fP. +The argument \fInel\fP is an estimate of the maximum number of entries +in the table. +The function \fBhcreate()\fP may adjust this value upward to improve the +performance of the resulting hash table. +.PP +The corresponding function \fBhdestroy()\fP frees the memory occupied by +the hash table so that a new table can be constructed. +.PP +The argument \fIitem\fP is of type \fBENTRY\fP, which is a typedef defined in +\fI\fP and includes these elements: +.sp +.nf + typedef struct entry { + char *\fIkey\fP; + void *\fIdata\fP; + } ENTRY; +.fi +.sp +The field \fIkey\fP points to the NUL-terminated string which is the +search key. +The field \fIdata\fP points to the data associated with that key. +The function \fBhsearch()\fP searches the hash table for an +item with the same key as \fIitem\fP (where "the same" is determined using +.BR strcmp (3)), +and if successful returns a pointer to it. +The argument \fIaction\fP determines what \fBhsearch()\fP does +after an unsuccessful search. A value of \fBENTER\fP instructs it to +insert a copy of \fIitem\fP, while a value of \fBFIND\fP means to return +\fBNULL\fP. +.PP +The three functions +.BR hcreate_r , +.BR hsearch_r , +.BR hdestroy_r +are reentrant versions that allow the use of more than one table. +The last argument used identifies the table. The struct it points to +must be zeroed before the first call to +.BR hcreate_r() . +.SH "RETURN VALUE" +\fBhcreate()\fP and \fBhcreate_r()\fP return 0 when allocation of the memory +for the hash table fails, nonzero otherwise. +.LP +\fBhsearch()\fP returns \fBNULL\fP if \fIaction\fP is \fBENTER\fP and +the hash table is full, or \fIaction\fP is \fBFIND\fP and \fIitem\fP +cannot be found in the hash table. +.LP +\fBhsearch_r()\fP returns 0 if \fIaction\fP is \fBENTER\fP and +the hash table is full, and nonzero otherwise. +.SH ERRORS +POSIX documents +.TP +.B ENOMEM +Out of memory. +.LP +The glibc implementation will return the following two errors. +.TP +.B ENOMEM +Table full with \fIaction\fP set to \fBENTER\fP. +.TP +.B ESRCH +The \fIaction\fP parameter is \fBFIND\fP and no corresponding element +is found in the table. +.SH "CONFORMS TO" +The functions +.BR hcreate , +.BR hsearch , +and +.BR hdestroy +are from SVID, and are described in POSIX 1003.1-2001. +The functions +.BR hcreate_r , +.BR hsearch_r , +.BR hdestroy_r +are GNU extensions. +.SH BUGS +SVID and POSIX 1003.1-2001 specify that \fIaction\fP +is significant only for unsuccessful searches, so that an ENTER +should not do anything for a successful search. The libc and glibc +implementations update the \fIdata\fP for the given \fIkey\fP +in this case. +.\" Tue Jan 29 09:27:40 2002: fixed in latest glibc snapshot +.LP +Individual hash table entries can be added, but not deleted. +.SH EXAMPLE +.PP +The following program inserts 24 items in to a hash table, then prints +some of them. +.nf + + #include + #include + #include + + char *data[] = { "alpha", "bravo", "charlie", "delta", + "echo", "foxtrot", "golf", "hotel", "india", "juliet", + "kilo", "lima", "mike", "november", "oscar", "papa", + "quebec", "romeo", "sierra", "tango", "uniform", + "victor", "whisky", "x-ray", "yankee", "zulu" + }; + + int main() { + ENTRY e, *ep; + int i; + + /* starting with small table, and letting it grow does not work */ + hcreate(30); + for (i = 0; i < 24; i++) { + e.key = data[i]; + /* data is just an integer, instead of a + pointer to something */ + e.data = (char *)i; + ep = hsearch(e, ENTER); + /* there should be no failures */ + if (ep == NULL) { + fprintf(stderr, "entry failed\\n"); + exit(1); + } + } + for (i = 22; i < 26; i++) { + /* print two entries from the table, and + show that two are not in the table */ + e.key = data[i]; + ep = hsearch(e, FIND); + printf("%9.9s -> %9.9s:%d\\n", e.key, + ep ? ep->key : "NULL", + ep ? (int)(ep->data) : 0); + } + return 0; + } + +.fi +.SH "SEE ALSO" +.BR bsearch (3), +.BR lsearch (3), +.BR malloc (3), +.BR tsearch (3) diff --git a/man3/hsearch_r.3 b/man3/hsearch_r.3 new file mode 100644 index 000000000..f4a0405da --- /dev/null +++ b/man3/hsearch_r.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man3/hstrerror.3 b/man3/hstrerror.3 new file mode 100644 index 000000000..7d0fb4b7c --- /dev/null +++ b/man3/hstrerror.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/htonl.3 b/man3/htonl.3 new file mode 100644 index 000000000..ba374e841 --- /dev/null +++ b/man3/htonl.3 @@ -0,0 +1 @@ +.so man3/byteorder.3 diff --git a/man3/htons.3 b/man3/htons.3 new file mode 100644 index 000000000..ba374e841 --- /dev/null +++ b/man3/htons.3 @@ -0,0 +1 @@ +.so man3/byteorder.3 diff --git a/man3/hypot.3 b/man3/hypot.3 new file mode 100644 index 000000000..457b7e013 --- /dev/null +++ b/man3/hypot.3 @@ -0,0 +1,64 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH HYPOT 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +hypot, hypotf, hypotl \- Euclidean distance function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double hypot(double " x ", double " y ); +.sp +.BI "float hypotf(float " x ", float " y ); +.sp +.BI "long double hypotl (long double " x ", long double " y ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The +.B hypot() +function returns +.RI sqrt( x * x + y * y ). +This is the length of the hypotenuse of a right-angle triangle +with sides of length +.I x +and +.IR y , +or the distance of the point +.RI ( x , y ) +from the origin. +.SH "CONFORMING TO" +SVID 3, BSD 4.3, C99. +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR cabs (3), +.BR sqrt (3) diff --git a/man3/hypotf.3 b/man3/hypotf.3 new file mode 100644 index 000000000..e5c8ab887 --- /dev/null +++ b/man3/hypotf.3 @@ -0,0 +1 @@ +.so man3/hypot.3 diff --git a/man3/hypotl.3 b/man3/hypotl.3 new file mode 100644 index 000000000..e5c8ab887 --- /dev/null +++ b/man3/hypotl.3 @@ -0,0 +1 @@ +.so man3/hypot.3 diff --git a/man3/iconv.3 b/man3/iconv.3 new file mode 100644 index 000000000..e7a50f814 --- /dev/null +++ b/man3/iconv.3 @@ -0,0 +1,91 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.\" 2000-06-30 correction by Yuichi SATO +.\" 2000-11-15 aeb, fixed prototype +.\" +.TH ICONV 3 2001-11-15 "GNU" "Linux Programmer's Manual" +.SH NAME +iconv \- perform character set conversion +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t iconv(iconv_t " cd , +.BI " char **" inbuf ", size_t *" inbytesleft , +.BI " char **" outbuf ", size_t *" outbytesleft ); +.fi +.SH DESCRIPTION +The argument \fIcd\fP must be a conversion descriptor created using the +function \fBiconv_open\fP. +.PP +The main case is when \fIinbuf\fP is not NULL and \fI*inbuf\fP is not NULL. +In this case, the \fBiconv\fP function converts the multibyte sequence +starting at \fI*inbuf\fP to a multibyte sequence starting at \fI*outbuf\fP. +At most \fI*inbytesleft\fP bytes, starting at \fI*inbuf\fP, will be read. +At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written. +.PP +The \fBiconv\fP function converts one multibyte character at a time, and for +each character conversion it increments \fI*inbuf\fP and decrements +\fI*inbytesleft\fP by the number of converted input bytes, it increments +\fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of converted +output bytes, and it updates the conversion state contained in \fIcd\fP. +The conversion can stop for four reasons: +.PP +1. An invalid multibyte sequence is encountered in the input. In this case +it sets \fBerrno\fP to \fBEILSEQ\fP and returns (size_t)(-1). \fI*inbuf\fP +is left pointing to the beginning of the invalid multibyte sequence. +.PP +2. The input byte sequence has been entirely converted, i.e. \fI*inbytesleft\fP +has gone down to 0. In this case \fBiconv\fP returns the number of +non-reversible conversions performed during this call. +.PP +3. An incomplete multibyte sequence is encountered in the input, and the +input byte sequence terminates after it. In this case it sets \fBerrno\fP to +\fBEINVAL\fP and returns (size_t)(-1). \fI*inbuf\fP is left pointing to the +beginning of the incomplete multibyte sequence. +.PP +4. The output buffer has no more room for the next converted character. In +this case it sets \fBerrno\fP to \fBE2BIG\fP and returns (size_t)(-1). +.PP +A different case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, but +\fIoutbuf\fP is not NULL and \fI*outbuf\fP is not NULL. In this case, the +\fBiconv\fP function attempts to set \fIcd\fP's conversion state to the +initial state and store a corresponding shift sequence at \fI*outbuf\fP. +At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written. +If the output buffer has no more room for this reset sequence, it sets +\fBerrno\fP to \fBE2BIG\fP and returns (size_t)(-1). Otherwise it increments +\fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of bytes +written. +.PP +A third case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, and +\fIoutbuf\fP is NULL or \fI*outbuf\fP is NULL. In this case, the \fBiconv\fP +function sets \fIcd\fP's conversion state to the initial state. +.SH "RETURN VALUE" +The \fBiconv\fP function returns the number of characters converted in a +non-reversible way during this call; reversible conversions are not counted. +In case of error, it sets \fBerrno\fP and returns (size_t)(-1). +.SH ERRORS +The following errors can occur, among others: +.TP +.B E2BIG +There is not sufficient room at \fI*outbuf\fP. +.TP +.B EILSEQ +An invalid multibyte sequence has been encountered in the input. +.TP +.B EINVAL +An incomplete multibyte sequence has been encountered in the input. +.SH "CONFORMING TO" +UNIX98 +.SH "SEE ALSO" +.BR iconv_close (3), +.BR iconv_open (3) diff --git a/man3/iconv_close.3 b/man3/iconv_close.3 new file mode 100644 index 000000000..9b31ffd81 --- /dev/null +++ b/man3/iconv_close.3 @@ -0,0 +1,33 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.TH ICONV_CLOSE 3 1999-11-27 "GNU" "Linux Programmer's Manual" +.SH NAME +iconv_close \- deallocate descriptor for character set conversion +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int iconv_close(iconv_t " cd ); +.fi +.SH DESCRIPTION +The \fBiconv_close\fP function deallocates a conversion descriptor \fIcd\fP +previously allocated using \fBiconv_open\fP. +.SH "RETURN VALUE" +When successful, the \fBiconv_close\fP function returns 0. +In case of error, it sets +.I errno +and returns \-1. +.SH "CONFORMING TO" +UNIX98 +.SH "SEE ALSO" +.BR iconv (3), +.BR iconv_open (3) diff --git a/man3/iconv_open.3 b/man3/iconv_open.3 new file mode 100644 index 000000000..b798a18d2 --- /dev/null +++ b/man3/iconv_open.3 @@ -0,0 +1,54 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.TH ICONV_OPEN 3 1999-11-27 "GNU" "Linux Programmer's Manual" +.SH NAME +iconv_open \- allocate descriptor for character set conversion +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "iconv_t iconv_open(const char *" tocode ", const char *" fromcode ); +.fi +.SH DESCRIPTION +The \fBiconv_open\fP function allocates a conversion descriptor suitable +for converting byte sequences from character encoding \fIfromcode\fP to +character encoding \fItocode\fP. +.PP +The values permitted for \fIfromcode\fP and \fItocode\fP and the supported +combinations are system dependent. For the GNU C library, the permitted +values are listed by the \fBiconv --list\fP command, and all combinations +of the listed values are supported. +.PP +The resulting conversion descriptor can be used with \fBiconv\fP any number +of times. It remains valid until deallocated using \fBiconv_close\fP. +.PP +A conversion descriptor contains a conversion state. After creation using +\fBiconv_open\fP, the state is in the initial state. Using \fBiconv\fP +modifies the descriptor's conversion state. (This implies that a conversion +descriptor can not be used in multiple threads simultaneously.) To bring the +state back to the initial state, use \fBiconv\fP with NULL as \fIinbuf\fP +argument. +.SH "RETURN VALUE" +The \fBiconv_open\fP function returns a freshly allocated conversion +descriptor. In case of error, it sets \fBerrno\fP and returns (iconv_t)(-1). +.SH ERRORS +The following error can occur, among others: +.TP +.B EINVAL +The conversion from \fIfromcode\fP to \fItocode\fP is not supported by the +implementation. +.SH "CONFORMING TO" +UNIX98 +.SH "SEE ALSO" +.BR iconv (1), +.BR iconv (3), +.BR iconv_close (3) diff --git a/man3/ilogb.3 b/man3/ilogb.3 new file mode 100644 index 000000000..ce375c323 --- /dev/null +++ b/man3/ilogb.3 @@ -0,0 +1,95 @@ +.\" Copyright 2004 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Inspired by a page by Walter Harms created 2002-08-10 +.\" +.TH ILOGB 3 2004-10-31 "" "Linux Programmer's Manual" +.SH NAME +ilogb, ilogbf, ilogbl \- get integer exponent of a floating point value +.SH SYNOPSIS +.B #include +.sp +.BI "int ilogb(double " x ); +.br +.BI "int ilogbf(float " x ); +.br +.BI "int ilogbl(long double " x ); +.sp +Link with \-lm. +.SH DESCRIPTION +These functions return the exponent part of their argument +as a signed integer. When no error occurs, these functions +are equivalent to the corresponding +.B logb() +functions, cast to (int). +An error will occur for zero and infinity and NaN, +and possibly for overflow. +.\" .SH "RETURN VALUE" +.\" These functions return the exponent part of their argument +.\" as a signed integer. +.SH ERRORS +In order to check for errors, set +.I errno +to zero and call +.I feclearexcept(FE_ALL_EXCEPT) +before calling these functions. On return, if +.I errno +is non-zero or +.I fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.LP +If an error occurs and +.I "(math_errhandling & MATH_ERRNO)" +is non-zero, then +.I errno +is set to +.BR EDOM . +If an error occurs and +.I "(math_errhandling & MATH_ERREXCEPT)" +is non-zero, then the invalid floating-point exception is raised. +.LP +A domain error occurs when +.I x +is zero or infinite (or too large, or too small) or NaN. +If +.I x +is zero, the constant +.B FP_ILOGB0 +is returned. +.\" glibc: The numeric value is either `INT_MIN' or `-INT_MAX'. +If +.I x +is NaN, the constant +.B FP_ILOGBNAN +is returned. +.\" glibc: The numeric value is either `INT_MIN' or `INT_MAX'. +If +.I x +is infinite (or too large), INT_MAX is returned. +If +.I x +is too small, INT_MIN is returned. +.SH "CONFORMING TO" +ISO C99 +.SH "SEE ALSO" +.BR log (3), +.BR logb (3) diff --git a/man3/ilogbf.3 b/man3/ilogbf.3 new file mode 100644 index 000000000..213d00afa --- /dev/null +++ b/man3/ilogbf.3 @@ -0,0 +1 @@ +.so man3/ilogb.3 diff --git a/man3/ilogbl.3 b/man3/ilogbl.3 new file mode 100644 index 000000000..213d00afa --- /dev/null +++ b/man3/ilogbl.3 @@ -0,0 +1 @@ +.so man3/ilogb.3 diff --git a/man3/imaxabs.3 b/man3/imaxabs.3 new file mode 100644 index 000000000..97db8d2b6 --- /dev/null +++ b/man3/imaxabs.3 @@ -0,0 +1 @@ +.so man3/abs.3 diff --git a/man3/imaxdiv.3 b/man3/imaxdiv.3 new file mode 100644 index 000000000..934824e3e --- /dev/null +++ b/man3/imaxdiv.3 @@ -0,0 +1 @@ +.so man3/div.3 diff --git a/man3/index.3 b/man3/index.3 new file mode 100644 index 000000000..f6143017e --- /dev/null +++ b/man3/index.3 @@ -0,0 +1,62 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Apr 12 12:54:34 1993, David Metcalfe +.\" Modified Sat Jul 24 19:13:52 1993, Rik Faith (faith@cs.unc.edu) +.TH INDEX 3 1993-04-12 "GNU" "Linux Programmer's Manual" +.SH NAME +index, rindex \- locate character in string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *index(const char *" s ", int " c ); +.sp +.BI "char *rindex(const char *" s ", int " c ); +.fi +.SH DESCRIPTION +The \fBindex()\fP function returns a pointer to the first occurrence +of the character \fIc\fP in the string \fIs\fP. +.PP +The \fBrindex()\fP function returns a pointer to the last occurrence +of the character \fIc\fP in the string \fIs\fP. +.PP +The terminating NULL character is considered to be a part of the +strings. +.SH "RETURN VALUE" +The \fBindex()\fP and \fBrindex()\fP functions return a pointer to +the matched character or NULL if the character is not found. +.SH "CONFORMING TO" +BSD 4.3 +.SH "SEE ALSO" +.BR memchr (3), +.BR strchr (3), +.BR strpbrk (3), +.BR strrchr (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3) diff --git a/man3/inet.3 b/man3/inet.3 new file mode 100644 index 000000000..eaee847ba --- /dev/null +++ b/man3/inet.3 @@ -0,0 +1,121 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" libc.info (from glibc distribution) +.\" Modified Sat Jul 24 19:12:00 1993 by Rik Faith +.\" Modified Sun Sep 3 20:29:36 1995 by Jim Van Zandt +.\" Changed network into host byte order (for inet_network), +.\" Andreas Jaeger , 980130. +.\" +.TH INET 3 2001-07-25 "BSD" "Linux Programmer's Manual" +.SH NAME +inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof, +inet_netof \- Internet address manipulation routines +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.sp +.BI "int inet_aton(const char *" cp ", struct in_addr *" inp ); +.sp +.BI "in_addr_t inet_addr(const char *" cp ); +.sp +.BI "in_addr_t inet_network(const char *" cp ); +.sp +.BI "char *inet_ntoa(struct in_addr " in ); +.sp +.BI "struct in_addr inet_makeaddr(int " net ", int " host ); +.sp +.BI "in_addr_t inet_lnaof(struct in_addr " in ); +.sp +.BI "in_addr_t inet_netof(struct in_addr " in ); +.fi +.SH DESCRIPTION +\fBinet_aton()\fP converts the Internet host address \fIcp\fP from the +standard numbers-and-dots notation into binary data and stores it in +the structure that \fIinp\fP points to. \fBinet_aton\fP returns +nonzero if the address is valid, zero if not. +.PP +The \fBinet_addr()\fP function converts the Internet host address +\fIcp\fP from numbers-and-dots notation into binary data in network +byte order. If the input is invalid, INADDR_NONE (usually \-1) is returned. +This is an \fIobsolete\fP interface to \fBinet_aton\fP, described +immediately above; it is obsolete because \-1 is a valid address +(255.255.255.255), and \fBinet_aton\fP provides a cleaner way +to indicate error return. +.PP +The \fBinet_network()\fP function extracts the network number in +host byte order from the address \fIcp\fP in numbers-and-dots +notation. If the input is invalid, \-1 is returned. +.PP +The \fBinet_ntoa()\fP function converts the Internet host address +\fIin\fP given in network byte order to a string in standard +numbers-and-dots notation. The string is returned in a statically +allocated buffer, which subsequent calls will overwrite. +.PP +The \fBinet_makeaddr()\fP function makes an Internet host address +in network byte order by combining the network number \fInet\fP +with the local address \fIhost\fP in network \fInet\fP, both in +local host byte order. +.PP +The \fBinet_lnaof()\fP function returns the local host address part +of the Internet address \fIin\fP. The local host address is returned +in local host byte order. +.PP +The \fBinet_netof()\fP function returns the network number part of +the Internet Address \fIin\fP. The network number is returned in +local host byte order. +.PP +The structure \fIin_addr\fP as used in \fBinet_ntoa()\fP, +\fBinet_makeaddr()\fP, \fBinet_lnoaf()\fP and \fBinet_netof()\fP +is defined in \fInetinet/in.h\fP as: +.sp +.RS +.nf +.ne 7 +.ta 8n 16n +struct in_addr { + unsigned long int s_addr; +} +.ta +.fi +.RE +.PP +Note that on the i80x86 the host byte order is Least Significant Byte +first, whereas the network byte order, as used on the Internet, is +Most Significant Byte first. +.SH "CONFORMING TO" +BSD 4.3 +.SH "SEE ALSO" +.BR gethostbyname (3), +.BR getnetent (3), +.BR inet_ntop (3), +.BR inet_pton (3), +.BR hosts (5), +.BR networks (5) diff --git a/man3/inet_addr.3 b/man3/inet_addr.3 new file mode 100644 index 000000000..0eba30eb9 --- /dev/null +++ b/man3/inet_addr.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man3/inet_aton.3 b/man3/inet_aton.3 new file mode 100644 index 000000000..0eba30eb9 --- /dev/null +++ b/man3/inet_aton.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man3/inet_lnaof.3 b/man3/inet_lnaof.3 new file mode 100644 index 000000000..0eba30eb9 --- /dev/null +++ b/man3/inet_lnaof.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man3/inet_makeaddr.3 b/man3/inet_makeaddr.3 new file mode 100644 index 000000000..4a9e0fd11 --- /dev/null +++ b/man3/inet_makeaddr.3 @@ -0,0 +1 @@ +.so man3/inet_addr.3 diff --git a/man3/inet_netof.3 b/man3/inet_netof.3 new file mode 100644 index 000000000..0eba30eb9 --- /dev/null +++ b/man3/inet_netof.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man3/inet_network.3 b/man3/inet_network.3 new file mode 100644 index 000000000..0eba30eb9 --- /dev/null +++ b/man3/inet_network.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man3/inet_ntoa.3 b/man3/inet_ntoa.3 new file mode 100644 index 000000000..0eba30eb9 --- /dev/null +++ b/man3/inet_ntoa.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man3/inet_ntop.3 b/man3/inet_ntop.3 new file mode 100644 index 000000000..ae9d963f2 --- /dev/null +++ b/man3/inet_ntop.3 @@ -0,0 +1,111 @@ +.\" Copyright 2000 Sam Varshavchik +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References: RFC 2553 +.TH inet_ntop 3 2000-12-18 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +inet_ntop \- Parse network address structures +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.sp +.BI "const char *inet_ntop(int " "af" ", const void *" "src" , +.BI " char *" "dst" ", socklen_t " "cnt" ); +.SH DESCRIPTION +This function converts the network address structure +.I src +in the +.I af +address family into a character string, which is copied to a character buffer +.IR dst , +which is +.I cnt +bytes long. +.PP +.BR inet_ntop (3) +extends the +.BR inet_ntoa (3) +function to support multiple address families, +.BR inet_ntoa (3) +is now considered to be deprecated in favor of +.BR inet_ntop (3). +The following address families are currently supported: +.TP +.B AF_INET +.I src +points to a +.I struct in_addr +(network byte order format) +which is converted to an IPv4 network address in +the dotted-quad format, "\fIddd.ddd.ddd.ddd\fP". +The buffer +.I dst +must be at least +.B INET_ADDRSTRLEN +bytes long. +.TP +.B AF_INET6 +.I src +points to a +.I struct in6_addr +(network byte order format) +which is converted to a representation of this address in the +most appropriate IPv6 network address format for this address. +The buffer +.I dst +must be at least +.B INET6_ADDRSTRLEN +bytes long. +.SH "RETURN VALUE" +.B inet_ntop +returns a non-null pointer to +.IR dst . +NULL is returned if there was an error, with +.I errno +set to +.B EAFNOSUPPORT +if +.I af +was not set to a valid address family, +or to +.B ENOSPC +if the converted address string would exceed the size of +.IR dst +given by the +.I cnt +argument. +.SH "CONFORMING TO" +POSIX 1003.1-2001. +Note that RFC 2553 defines a prototype where the last parameter +.I cnt +is of type +.BR size_t . +Many systems follow RFC 2553. +Glibc 2.0 and 2.1 have size_t, but 2.2 has socklen_t. +.\" 2.1.3: size_t, 2.1.91: socklen_t +.SH "SEE ALSO" +.BR inet_pton (3) +.SH BUGS +.B AF_INET6 +converts IPv6-mapped IPv4 addresses into an IPv6 format. diff --git a/man3/inet_pton.3 b/man3/inet_pton.3 new file mode 100644 index 000000000..edc07d9db --- /dev/null +++ b/man3/inet_pton.3 @@ -0,0 +1,106 @@ +.\" Copyright 2000 Sam Varshavchik +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References: RFC 2553 +.TH inet_pton 3 2000-12-18 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +inet_pton \- Create a network address structure +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.sp +.BI "int inet_pton(int " "af" ", const char *" "src" ", void *" "dst" ); +.SH DESCRIPTION +This function converts the character string +.I src +into a network address structure in the +.I af +address family, then +copies +the network address structure to +.IR dst . +.PP +.BR inet_pton (3) +extends the +.BR inet_addr (3) +function to support multiple address families, +.BR inet_addr (3) +is now considered to be deprecated in favor of +.BR inet_pton (3). +The following address families are currently supported: +.TP +.B AF_INET +.I src +points to a character string containing an IPv4 network address in +the dotted-quad format, "\fIddd.ddd.ddd.ddd\fP". +The address is converted +to a +.I struct in_addr +and copied to +.IR dst, +which must be +.I sizeof(struct in_addr) +bytes long. +.TP +.B AF_INET6 +.I src +points to a character string containing an IPv6 network address in +any allowed IPv6 address format. +The address is converted +to a +.I struct in6_addr +and copied to +.IR dst, +which must be +.I sizeof(struct in6_addr) +bytes long. +.PP +Certain legacy hex and octal formats of +.B AF_INET +addresses are not supported by +.IR inet_pton , +which rejects them. +.SH "RETURN VALUE" +.B inet_pton +returns a negative value and sets +.I errno +to +.B EAFNOSUPPORT +if +.I af +does not contain a valid address family. +0 is returned if +.I src +does not contain a character string representing a valid network +address in the specified address family. +A positive value is returned if the network address was successfully +converted. +.SH "SEE ALSO" +.BR inet_ntop (3) +.SH BUGS +.B AF_INET6 +does not recognize IPv4 addresses. +An explicit IPv6-mapped IPv4 address must be supplied in +.I src +instead. diff --git a/man3/infnan.3 b/man3/infnan.3 new file mode 100644 index 000000000..ac49c2219 --- /dev/null +++ b/man3/infnan.3 @@ -0,0 +1,58 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:11:11 1993 by Rik Faith (faith@cs.unc.edu) +.TH INFNAN 3 1993-06-02 "GNU" "Linux Programmer's Manual" +.SH NAME +infnan \- deal with infinite or not-a-number (NaN) result +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double infnan(int " error ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBinfnan()\fP function returns a suitable value for infinity and +"not-a-number" (NaN) results. The value of \fIerror\fP can be ERANGE +to represent infinity or anything else to represent NaN. \fIerrno\fP +is also set. +.SH "RETURN VALUE" +If \fIerror\fP is ERANGE (Infinity), HUGE_VAL is returned. +.PP +If \fIerror\fP is -ERANGE (-Infinity), -HUGE_VAL is returned. +.PP +If \fIerror\fP is anything else, NAN is returned. +.SH ERRORS +.TP +.B EDOM +The value of \fIerror\fP is "not-a-number" (NaN). +.TP +.B ERANGE +The value of \fIerror\fP is positive or negative infinity. +.SH "CONFORMING TO" +BSD 4.3 diff --git a/man3/initgroups.3 b/man3/initgroups.3 new file mode 100644 index 000000000..94f76a412 --- /dev/null +++ b/man3/initgroups.3 @@ -0,0 +1,75 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 2004-10-10 by aeb +.\" +.TH INITGROUPS 3 2004-10-10 "GNU" "Linux Programmer's Manual" +.SH NAME +initgroups \- initialize the supplementary group access list +.SH SYNOPSIS +.nf +.B #include +.B #include +.sp +.BI "int initgroups(const char *" user ", gid_t " group ); +.fi +.SH DESCRIPTION +The \fBinitgroups()\fP function initializes the group access list by +reading the group database \fI/etc/group\fP and using all groups of +which \fIuser\fP is a member. The additional group \fIgroup\fP is +also added to the list. + +The +.I user +argument must be non-NULL. +.SH "RETURN VALUE" +The \fBinitgroups()\fP function returns 0 on success, or \-1 if an error +occurs. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to allocate group information structure. +.TP +.B EPERM +The calling process has insufficient privilege. See the underlying system call +.BR setgroups (2). +.SH FILES +.nf +\fI/etc/group\fP group database file +.fi +.SH "CONFORMING TO" +SVID 3, BSD 4.3 +.SH NOTES +The prototype for +.B initgroups +is only available if +.B _BSD_SOURCE +is defined (either explicitly, or implicitly, by not defining +_POSIX_SOURCE or compiling with the -ansi flag). +.SH "SEE ALSO" +.BR getgroups (2), +.BR setgroups (2) diff --git a/man3/initstate.3 b/man3/initstate.3 new file mode 100644 index 000000000..6e34104e2 --- /dev/null +++ b/man3/initstate.3 @@ -0,0 +1 @@ +.so man3/random.3 diff --git a/man3/innetgr.3 b/man3/innetgr.3 new file mode 100644 index 000000000..34268f941 --- /dev/null +++ b/man3/innetgr.3 @@ -0,0 +1 @@ +.so man3/setnetgrent.3 diff --git a/man3/insque.3 b/man3/insque.3 new file mode 100644 index 000000000..c33575436 --- /dev/null +++ b/man3/insque.3 @@ -0,0 +1,75 @@ +.\" peter memishian -- meem@gnu.ai.mit.edu +.\" $Id: insque.3,v 1.2 1996/10/30 21:03:39 meem Exp meem $ +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code (5.4.7) +.\" Solaris 2.x, OSF/1, and HP-UX manpages +.\" Curry's "UNIX Systems Programming for SVR4" (O'Reilly & Associates 1996) +.\" +.\" Changed to POSIX, 2003-08-11, aeb+wh +.\" +.TH INSQUE 3 2003-08-11 "" "Linux Programmer's Manual" +.SH NAME +insque, remque \- insert/remove an item from a queue +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void insque(void *" elem ", void *" prev ); +.BI "void remque(void *" elem ); +.SH DESCRIPTION +\fBinsque()\fP and \fBremque()\fP are functions for manipulating +doubly-linked lists. Each element in the list is a structure of +which the first two structure elements are a forward and a +backward pointer. + +\fBinsque()\fP inserts the element pointed to by \fIelem\fP +immediately after the element pointed to by \fIprev\fP, which must +not be NULL. + +\fBremque()\fP removes the element pointed to by \fIelem\fP from the +doubly-linked list. +.SH "CONFORMING TO" +POSIX 1003.1-2001 +.SH "HISTORICAL NOTES" +Traditionally (e.g. SunOS, Linux libc 4,5) the parameters of these +functions were of type \fBstruct qelem *\fP, where the struct +is defined as + +.RS +.nf +struct qelem { + struct qelem *q_forw; + struct qelem *q_back; + char q_data[1]; +}; +.fi +.RE + +This is still what you will get if _GNU_SOURCE is defined before +including . + +The location of the prototypes for these functions differs among several +versions of UNIX. The above is the POSIX version. +Some systems place them in . Linux libc4,5 placed them +in . diff --git a/man3/intro.3 b/man3/intro.3 new file mode 100644 index 000000000..df9a511f5 --- /dev/null +++ b/man3/intro.3 @@ -0,0 +1,57 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 17:37:50 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Wed Apr 27 13:33:53 MET DST 1994 by Michael Haardt. +.TH INTRO 3 1995-12-13 "Linux" "Linux Programmer's Manual" +.SH NAME +intro \- Introduction to library functions +.SH DESCRIPTION +This chapter describes all library functions excluding the library +functions described in chapter 2, which implement system calls. There +are various function groups which can be identified by a letter which +is appended to the chapter number: +.IP (3C) +These functions, the functions from chapter 2 and from chapter 3S are +contained in the C standard library libc, which will be used by +.BR cc (1) +by default. +.IP (3S) +These functions are parts of the +.BR stdio (3) +library. They are contained in the standard C library libc. +.IP (3M) +These functions are contained in the arithmetic library libm. They are +used by the +.BR f77 (1) +FORTRAN compiler by default, but not by the +.BR cc (1) +C compiler, which needs the option \fI\-lm\fP. +.IP (3F) +These functions are part of the FORTRAN library libF77. There are no +special compiler flags needed to use these functions. +.IP (3X) +Various special libraries. The manual pages documenting their functions +specify the library names. +.SH AUTHORS +Look at the header of the manual page for the author(s) and copyright +conditions. Note that these can be different from page to page! diff --git a/man3/iruserok.3 b/man3/iruserok.3 new file mode 100644 index 000000000..b58efefab --- /dev/null +++ b/man3/iruserok.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man3/isalnum.3 b/man3/isalnum.3 new file mode 100644 index 000000000..0b69c7544 --- /dev/null +++ b/man3/isalnum.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isalpha.3 b/man3/isalpha.3 new file mode 100644 index 000000000..fc0622309 --- /dev/null +++ b/man3/isalpha.3 @@ -0,0 +1,160 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" +.\" Modified Sat Jul 24 19:10:00 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Aug 21 17:51:50 1994 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sat Sep 2 21:52:01 1995 by Jim Van Zandt +.\" Modified Mon May 27 22:55:26 1996 by Martin Schulze (joey@linux.de) +.\" +.TH ISALPHA 3 1995-09-02 "GNU" "Linux Programmer's Manual" +.SH NAME +isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, +isprint, ispunct, isspace, isupper, isxdigit \- character +classification routines +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int isalnum(int " "c" ); +.nl +.BI "int isalpha(int " "c" ); +.nl +.BI "int isascii(int " "c" ); +.nl +.BI "int isblank(int " "c" ); +.nl +.BI "int iscntrl(int " "c" ); +.nl +.BI "int isdigit(int " "c" ); +.nl +.BI "int isgraph(int " "c" ); +.nl +.BI "int islower(int " "c" ); +.nl +.BI "int isprint(int " "c" ); +.nl +.BI "int ispunct(int " "c" ); +.nl +.BI "int isspace(int " "c" ); +.nl +.BI "int isupper(int " "c" ); +.nl +.BI "int isxdigit(int " "c" ); +.fi +.SH DESCRIPTION +These functions check whether +.IR c , +which must have the value of an +.B unsigned char +or +.BR EOF , +falls into a certain character class according to the current locale. +.TP +.B "isalnum()" +checks for an alphanumeric character; it is equivalent to +.BI "(isalpha(" c ") || isdigit(" c "))" \fR. +.TP +.B "isalpha()" +checks for an alphabetic character; in the standard \fB"C"\fP +locale, it is equivalent to +.BI "(isupper(" c ") || islower(" c "))" \fR. +In some locales, there may be additional characters for which +.B isalpha() +is true--letters which are neither upper case nor lower +case. +.TP +.B "isascii()" +checks whether \fIc\fP is a 7-bit +.I unsigned char +value that fits into +the ASCII character set. This function is a BSD extension +and is also an SVID extension. +.TP +.B "isblank()" +checks for a blank character; that is, a space or a tab. +.TP +.B "iscntrl()" +checks for a control character. +.TP +.B "isdigit()" +checks for a digit (0 through 9). +.TP +.B "isgraph()" +checks for any printable character except space. +.TP +.B "islower()" +checks for a lower-case character. +.TP +.B "isprint()" +checks for any printable character including space. +.TP +.B "ispunct()" +checks for any printable character which is not a space or an +alphanumeric character. +.TP +.B "isspace()" +checks for white-space characters. In the +.B """C""" +and +.B """POSIX""" +locales, these are: space, form-feed +.RB ( '\ef' ), +newline +.RB ( '\en' ), +carriage return +.RB ( '\er' ), +horizontal tab +.RB ( '\et' ), +and vertical tab +.RB ( '\ev' ). +.TP +.B "isupper()" +checks for an uppercase letter. +.TP +.B "isxdigit()" +checks for a hexadecimal digits, i.e. one of +.nl +.BR "0 1 2 3 4 5 6 7 8 9 a b c d e f A B C D E F" . +.SH "RETURN VALUE" +The values returned are nonzero if the character +.I c +falls into the tested class, and a zero value +if not. +.SH "CONFORMING TO" +ANSI - C, BSD 4.3. +\fBisascii()\fP is a BSD extension +and is also an SVID extension. +\fBisblank()\fP conforms to ISO C99 7.4.1.3. +.SH NOTE +The details of what characters belong into which class depend on the current +locale. For example, +.B isupper() +will not recognize an A - umlaut as an uppercase letter in the default +.B "C" +locale. +.SH "SEE ALSO" +.BR setlocale (3), +.BR tolower (3), +.BR toupper (3), +.BR ascii (7), +.BR locale (7) diff --git a/man3/isascii.3 b/man3/isascii.3 new file mode 100644 index 000000000..0b69c7544 --- /dev/null +++ b/man3/isascii.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isatty.3 b/man3/isatty.3 new file mode 100644 index 000000000..66be66ce6 --- /dev/null +++ b/man3/isatty.3 @@ -0,0 +1,43 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 17:38:23 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Thu Apr 20 20:43:53 1995 by Jim Van Zandt +.TH ISATTY 3 1995-04-20 "Linux" "Linux Programmer's Manual" +.SH NAME +isatty \- does this descriptor refer to a terminal +.SH SYNOPSIS +.ad l +.nf +.B #include +.sp +.BI "int isatty(int " desc ); +.fi +.ad b +.SH DESCRIPTION +returns 1 if \fIdesc\fP is an open descriptor connected to a terminal and +0 else. +.SH "CONFORMING TO" +SVID, AT&T, X/OPEN, BSD 4.3 +.SH "SEE ALSO" +.BR fstat (2), +.BR ttyname (3) diff --git a/man3/isblank.3 b/man3/isblank.3 new file mode 100644 index 000000000..0b69c7544 --- /dev/null +++ b/man3/isblank.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/iscntrl.3 b/man3/iscntrl.3 new file mode 100644 index 000000000..0b69c7544 --- /dev/null +++ b/man3/iscntrl.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isdigit.3 b/man3/isdigit.3 new file mode 100644 index 000000000..0b69c7544 --- /dev/null +++ b/man3/isdigit.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isfinite.3 b/man3/isfinite.3 new file mode 100644 index 000000000..17676c2c7 --- /dev/null +++ b/man3/isfinite.3 @@ -0,0 +1 @@ +.so man3/fpclassify.3 diff --git a/man3/isgraph.3 b/man3/isgraph.3 new file mode 100644 index 000000000..0b69c7544 --- /dev/null +++ b/man3/isgraph.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isgreater.3 b/man3/isgreater.3 new file mode 100644 index 000000000..1ae6978cd --- /dev/null +++ b/man3/isgreater.3 @@ -0,0 +1,61 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" 2002-07-27 Walter Harms +.\" this was done with the help of the glibc manual +.\" +.TH ISGREATER 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +isgreater, isgreaterequal, isless, islessgreater, isunordered \- macros +to test a relation +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int isgreater(x,y); +.sp +.BI "int isgreaterequal(x,y); +.sp +.BI "int isless(x,y); +.sp +.BI "int islessequal(x,y); +.sp +.BI "int islessgreater(x,y); +.sp +.BI "int isunordered(x,y); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The normal relation operations (like less) will fail if one of the +operands is NaN. This will cause an exception. To avoid this, C99 defines +these macros. The macros are guaranteed to evaluate their operands only once. +The operand can be of any real floating-point type. +.TP +isgreater() +determines (x) > (y) without an exception if x or y is NaN. +.TP +isgreaterequal() +determines (x) >= (y) without an exception if x or y is NaN. +.TP +isless() +determines (x) < (y) without an exception if x or y is NaN. +.TP +islessequal() +determines (x) <= (y) without an exception if x or y is NaN. +.TP +islessgreater() +determines (x) < (y) || (x) > (y) without an exception if x or y is NaN. +This macro is not equivalent to x != y because that expression is +true if x or y is NaN. +.TP +isunordered() +is true if x or y is NaN and false otherwise. +.SH NOTE +Not all hardware supports these functions, and where it doesn't, they +will be emulated by macros. This will give you a performance penalty. +Don't use these functions if NaN is of no concern for you. +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR fpclassify (3) +.BR isnan(3) diff --git a/man3/isgreaterequal.3 b/man3/isgreaterequal.3 new file mode 100644 index 000000000..24410b964 --- /dev/null +++ b/man3/isgreaterequal.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man3/isinf.3 b/man3/isinf.3 new file mode 100644 index 000000000..17676c2c7 --- /dev/null +++ b/man3/isinf.3 @@ -0,0 +1 @@ +.so man3/fpclassify.3 diff --git a/man3/isinff.3 b/man3/isinff.3 new file mode 100644 index 000000000..19f709b1c --- /dev/null +++ b/man3/isinff.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man3/isinfl.3 b/man3/isinfl.3 new file mode 100644 index 000000000..19f709b1c --- /dev/null +++ b/man3/isinfl.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man3/isless.3 b/man3/isless.3 new file mode 100644 index 000000000..24410b964 --- /dev/null +++ b/man3/isless.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man3/islessequal.3 b/man3/islessequal.3 new file mode 100644 index 000000000..24410b964 --- /dev/null +++ b/man3/islessequal.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man3/islessgreater.3 b/man3/islessgreater.3 new file mode 100644 index 000000000..24410b964 --- /dev/null +++ b/man3/islessgreater.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man3/islower.3 b/man3/islower.3 new file mode 100644 index 000000000..0b69c7544 --- /dev/null +++ b/man3/islower.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isnan.3 b/man3/isnan.3 new file mode 100644 index 000000000..17676c2c7 --- /dev/null +++ b/man3/isnan.3 @@ -0,0 +1 @@ +.so man3/fpclassify.3 diff --git a/man3/isnormal.3 b/man3/isnormal.3 new file mode 100644 index 000000000..17676c2c7 --- /dev/null +++ b/man3/isnormal.3 @@ -0,0 +1 @@ +.so man3/fpclassify.3 diff --git a/man3/isprint.3 b/man3/isprint.3 new file mode 100644 index 000000000..0b69c7544 --- /dev/null +++ b/man3/isprint.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/ispunct.3 b/man3/ispunct.3 new file mode 100644 index 000000000..0b69c7544 --- /dev/null +++ b/man3/ispunct.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isspace.3 b/man3/isspace.3 new file mode 100644 index 000000000..0b69c7544 --- /dev/null +++ b/man3/isspace.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isunordered.3 b/man3/isunordered.3 new file mode 100644 index 000000000..24410b964 --- /dev/null +++ b/man3/isunordered.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man3/isupper.3 b/man3/isupper.3 new file mode 100644 index 000000000..0b69c7544 --- /dev/null +++ b/man3/isupper.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/iswalnum.3 b/man3/iswalnum.3 new file mode 100644 index 000000000..394b7e96d --- /dev/null +++ b/man3/iswalnum.3 @@ -0,0 +1,57 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWALNUM 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +iswalnum \- test for alphanumeric wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int iswalnum(wint_t " wc ); +.fi +.SH DESCRIPTION +The \fBiswalnum\fP function is the wide-character equivalent of the +\fBisalnum\fP function. It tests whether \fIwc\fP is a wide character +belonging to the wide character class "alnum". +.PP +The wide character class "alnum" is a subclass of the wide character class +"graph", and therefore also a subclass of the wide character class "print". +.PP +Being a subclass of the wide character class "print", the wide character class +"alnum" is disjoint from the wide character class "cntrl". +.PP +Being a subclass of the wide character class "graph", the wide character class +"alnum" is disjoint from the wide character class "space" and its subclass +"blank". +.PP +The wide character class "alnum" is disjoint from the wide character class +"punct". +.PP +The wide character class "alnum" is the union of the wide character classes +"alpha" and "digit". As such, it also contains the wide character class +"xdigit". +.PP +The wide character class "alnum" always contains at least the letters 'A' +to 'Z', 'a' to 'z' and the digits '0' to '9'. +.SH "RETURN VALUE" +The \fBiswalnum\fP function returns non-zero if \fIwc\fP is a wide character +belonging to the wide character class "alnum". Otherwise it returns zero. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR isalnum (3), +.BR iswctype (3) +.SH NOTES +The behaviour of \fBiswalnum\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/iswalpha.3 b/man3/iswalpha.3 new file mode 100644 index 000000000..e2265e066 --- /dev/null +++ b/man3/iswalpha.3 @@ -0,0 +1,60 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWALPHA 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +iswalpha \- test for alphabetic wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int iswalpha(wint_t " wc ); +.fi +.SH DESCRIPTION +The \fBiswalpha\fP function is the wide-character equivalent of the +\fBisalpha\fP function. It tests whether \fIwc\fP is a wide character +belonging to the wide character class "alpha". +.PP +The wide character class "alpha" is a subclass of the wide character class +"alnum", and therefore also a subclass of the wide character class "graph" and +of the wide character class "print". +.PP +Being a subclass of the wide character class "print", the wide character class +"alpha" is disjoint from the wide character class "cntrl". +.PP +Being a subclass of the wide character class "graph", the wide character class +"alpha" is disjoint from the wide character class "space" and its subclass +"blank". +.PP +Being a subclass of the wide character class "alnum", the wide character class +"alpha" is disjoint from the wide character class "punct". +.PP +The wide character class "alpha" is disjoint from the wide character class +"digit". +.PP +The wide character class "alpha" contains the wide character classes "upper" +and "lower". +.PP +The wide character class "alpha" always contains at least the letters 'A' +to 'Z' and 'a' to 'z'. +.SH "RETURN VALUE" +The \fBiswalpha\fP function returns non-zero if \fIwc\fP is a wide character +belonging to the wide character class "alpha". Otherwise it returns zero. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR isalpha (3), +.BR iswctype (3) +.SH NOTES +The behaviour of \fBiswalpha\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/iswblank.3 b/man3/iswblank.3 new file mode 100644 index 000000000..4e3d8a87c --- /dev/null +++ b/man3/iswblank.3 @@ -0,0 +1,48 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWBLANK 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +iswblank \- test for whitespace wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int iswblank(wint_t " wc ); +.fi +.SH DESCRIPTION +The \fBiswblank\fP function is the wide-character equivalent of the +\fBisblank\fP function. It tests whether \fIwc\fP is a wide character +belonging to the wide character class "blank". +.PP +The wide character class "blank" is a subclass of the wide character class +"space". +.PP +Being a subclass of the wide character class "space", the wide character class +"blank" is disjoint from the wide character class "graph" and therefore also +disjoint from its subclasses "alnum", "alpha", "upper", "lower", "digit", +"xdigit", "punct". +.PP +The wide character class "blank" always contains at least the space character +and the control character '\\t'. +.SH "RETURN VALUE" +The \fBiswblank\fP function returns non-zero if \fIwc\fP is a wide character +belonging to the wide character class "blank". Otherwise it returns zero. +.SH "CONFORMING TO" +This function is a GNU extension. +.SH "SEE ALSO" +.BR isblank (3), +.BR iswctype (3) +.SH NOTES +The behaviour of \fBiswblank\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/iswcntrl.3 b/man3/iswcntrl.3 new file mode 100644 index 000000000..22ce225f1 --- /dev/null +++ b/man3/iswcntrl.3 @@ -0,0 +1,44 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWCNTRL 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +iswcntrl \- test for control wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int iswcntrl(wint_t " wc ); +.fi +.SH DESCRIPTION +The \fBiswcntrl\fP function is the wide-character equivalent of the +\fBiscntrl\fP function. It tests whether \fIwc\fP is a wide character +belonging to the wide character class "cntrl". +.PP +The wide character class "cntrl" is disjoint from the wide character class +"print" and therefore also disjoint from its subclasses "graph", "alpha", +"upper", "lower", "digit", "xdigit", "punct". +.PP +For an unsigned char \fIc\fP, \fIiscntrl(c)\fP implies \fIiswcntrl(btowc(c))\fP, +but not vice versa. +.SH "RETURN VALUE" +The \fBiswcntrl\fP function returns non-zero if \fIwc\fP is a wide character +belonging to the wide character class "cntrl". Otherwise it returns zero. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR iscntrl (3), +.BR iswctype (3) +.SH NOTES +The behaviour of \fBiswcntrl\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/iswctype.3 b/man3/iswctype.3 new file mode 100644 index 000000000..913c4613a --- /dev/null +++ b/man3/iswctype.3 @@ -0,0 +1,52 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWCTYPE 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +iswctype \- wide character classification +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int iswctype(wint_t " wc ", wctype_t " desc ); +.fi +.SH DESCRIPTION +If \fIwc\fP is a wide character having the character property designated by +\fIdesc\fP (or in other words: belongs to the character class designated by +\fIdesc\fP), the \fBiswctype\fP function returns non-zero. Otherwise it +returns zero. If \fIwc\fP is WEOF, zero is returned. +.PP +\fIdesc\fP must be a character property descriptor returned by the \fBwctype\fP +function. +.SH "RETURN VALUE" +The \fBiswctype\fP function returns non-zero if the \fIwc\fP has the designated +property. Otherwise it returns 0. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR iswalnum (3), +.BR iswalpha (3), +.BR iswblank (3), +.BR iswcntrl (3), +.BR iswdigit (3), +.BR iswgraph (3), +.BR iswlower (3), +.BR iswprint (3), +.BR iswpunct (3), +.BR iswspace (3), +.BR iswupper (3), +.BR iswxdigit (3), +.BR wctype (3) +.SH NOTES +The behaviour of \fBiswctype\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/iswdigit.3 b/man3/iswdigit.3 new file mode 100644 index 000000000..cb75cc7e8 --- /dev/null +++ b/man3/iswdigit.3 @@ -0,0 +1,56 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWDIGIT 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +iswdigit \- test for decimal digit wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int iswdigit(wint_t " wc ); +.fi +.SH DESCRIPTION +The \fBiswdigit\fP function is the wide-character equivalent of the +\fBisdigit\fP function. It tests whether \fIwc\fP is a wide character +belonging to the wide character class "digit". +.PP +The wide character class "digit" is a subclass of the wide character class +"xdigit", and therefore also a subclass of the wide character class "alnum", of +the wide character class "graph" and of the wide character class "print". +.PP +Being a subclass of the wide character class "print", the wide character class +"digit" is disjoint from the wide character class "cntrl". +.PP +Being a subclass of the wide character class "graph", the wide character class +"digit" is disjoint from the wide character class "space" and its subclass +"blank". +.PP +Being a subclass of the wide character class "alnum", the wide character class +"digit" is disjoint from the wide character class "punct". +.PP +The wide character class "digit" is disjoint from the wide character class +"alpha" and therefore also disjoint from its subclasses "lower", "upper". +.PP +The wide character class "digit" always contains exactly the digits '0' to '9'. +.SH "RETURN VALUE" +The \fBiswdigit\fP function returns non-zero if \fIwc\fP is a wide character +belonging to the wide character class "digit". Otherwise it returns zero. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR isdigit (3), +.BR iswctype (3) +.SH NOTES +The behaviour of \fBiswdigit\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/iswgraph.3 b/man3/iswgraph.3 new file mode 100644 index 000000000..9b42c5bd0 --- /dev/null +++ b/man3/iswgraph.3 @@ -0,0 +1,53 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWGRAPH 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +iswgraph \- test for graphic wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int iswgraph(wint_t " wc ); +.fi +.SH DESCRIPTION +The \fBiswgraph\fP function is the wide-character equivalent of the +\fBisgraph\fP function. It tests whether \fIwc\fP is a wide character +belonging to the wide character class "graph". +.PP +The wide character class "graph" is a subclass of the wide character class +"print". +.PP +Being a subclass of the wide character class "print", the wide character class +"graph" is disjoint from the wide character class "cntrl". +.PP +The wide character class "graph" is disjoint from the wide character class +"space" and therefore also disjoint from its subclass "blank". +.\" Note: UNIX98 (susv2/xbd/locale.html) says that "graph" and "space" may +.\" have characters in common, except U+0020. But ISO C99 (ISO/IEC 9899:1999 +.\" section 7.25.2.1.10) says that "space" and "graph" are disjoint. +.PP +The wide character class "graph" contains all the wide characters from the +wide character class "print" except the space character. It therefore contains +the wide character classes "alnum" and "punct". +.SH "RETURN VALUE" +The \fBiswgraph\fP function returns non-zero if \fIwc\fP is a wide character +belonging to the wide character class "graph". Otherwise it returns zero. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR isgraph (3), +.BR iswctype (3) +.SH NOTES +The behaviour of \fBiswgraph\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/iswlower.3 b/man3/iswlower.3 new file mode 100644 index 000000000..31dcfff6d --- /dev/null +++ b/man3/iswlower.3 @@ -0,0 +1,64 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWLOWER 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +iswlower \- test for lowercase wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int iswlower(wint_t " wc ); +.fi +.SH DESCRIPTION +The \fBiswlower\fP function is the wide-character equivalent of the +\fBislower\fP function. It tests whether \fIwc\fP is a wide character +belonging to the wide character class "lower". +.PP +The wide character class "lower" is a subclass of the wide character class +"alpha", and therefore also a subclass of the wide character class "alnum", of +the wide character class "graph" and of the wide character class "print". +.PP +Being a subclass of the wide character class "print", the wide character class +"lower" is disjoint from the wide character class "cntrl". +.PP +Being a subclass of the wide character class "graph", the wide character class +"lower" is disjoint from the wide character class "space" and its subclass +"blank". +.PP +Being a subclass of the wide character class "alnum", the wide character class +"lower" is disjoint from the wide character class "punct". +.PP +Being a subclass of the wide character class "alpha", the wide character class +"lower" is disjoint from the wide character class "digit". +.PP +The wide character class "lower" contains at least those characters \fIwc\fP +which are equal to \fItowlower(wc)\fP and different from \fItowupper(wc)\fP. +.PP +The wide character class "lower" always contains at least the letters 'a' +to 'z'. +.SH "RETURN VALUE" +The \fBiswlower\fP function returns non-zero if \fIwc\fP is a wide character +belonging to the wide character class "lower". Otherwise it returns zero. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR islower (3), +.BR iswctype (3), +.BR towlower (3) +.SH NOTES +The behaviour of \fBiswlower\fP depends on the LC_CTYPE category of the +current locale. +.PP +This function is not very appropriate for dealing with Unicode characters, +because Unicode knows about three cases: upper, lower and title case. diff --git a/man3/iswprint.3 b/man3/iswprint.3 new file mode 100644 index 000000000..765e5dee1 --- /dev/null +++ b/man3/iswprint.3 @@ -0,0 +1,42 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWPRINT 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +iswprint \- test for printing wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int iswprint(wint_t " wc ); +.fi +.SH DESCRIPTION +The \fBiswprint\fP function is the wide-character equivalent of the +\fBisprint\fP function. It tests whether \fIwc\fP is a wide character +belonging to the wide character class "print". +.PP +The wide character class "print" is disjoint from the wide character class +"cntrl". +.PP +The wide character class "print" contains the wide character class "graph". +.SH "RETURN VALUE" +The \fBiswprint\fP function returns non-zero if \fIwc\fP is a wide character +belonging to the wide character class "print". Otherwise it returns zero. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR isprint (3), +.BR iswctype (3) +.SH NOTES +The behaviour of \fBiswprint\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/iswpunct.3 b/man3/iswpunct.3 new file mode 100644 index 000000000..d930b311a --- /dev/null +++ b/man3/iswpunct.3 @@ -0,0 +1,55 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWPUNCT 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +iswpunct \- test for punctuation or symbolic wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int iswpunct(wint_t " wc ); +.fi +.SH DESCRIPTION +The \fBiswpunct\fP function is the wide-character equivalent of the +\fBispunct\fP function. It tests whether \fIwc\fP is a wide character +belonging to the wide character class "punct". +.PP +The wide character class "punct" is a subclass of the wide character class +"graph", and therefore also a subclass of the wide character class "print". +.PP +The wide character class "punct" is disjoint from the wide character class +"alnum" and therefore also disjoint from its subclasses "alpha", "upper", +"lower", "digit", "xdigit". +.PP +Being a subclass of the wide character class "print", the wide character class +"punct" is disjoint from the wide character class "cntrl". +.PP +Being a subclass of the wide character class "graph", the wide character class +"punct" is disjoint from the wide character class "space" and its subclass +"blank". +.SH "RETURN VALUE" +The \fBiswpunct\fP function returns non-zero if \fIwc\fP is a wide character +belonging to the wide character class "punct". Otherwise it returns zero. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR ispunct (3), +.BR iswctype (3) +.SH NOTES +The behaviour of \fBiswpunct\fP depends on the LC_CTYPE category of the +current locale. +.PP +This function's name is a misnomer when dealing with Unicode characters, +because the wide character class "punct" contains both punctuation characters +and symbol (math, currency, etc.) characters. diff --git a/man3/iswspace.3 b/man3/iswspace.3 new file mode 100644 index 000000000..3829b3e00 --- /dev/null +++ b/man3/iswspace.3 @@ -0,0 +1,49 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWSPACE 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +iswspace \- test for whitespace wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int iswspace(wint_t " wc ); +.fi +.SH DESCRIPTION +The \fBiswspace\fP function is the wide-character equivalent of the +\fBisspace\fP function. It tests whether \fIwc\fP is a wide character +belonging to the wide character class "space". +.PP +The wide character class "space" is disjoint from the wide character class +"graph" and therefore also disjoint from its subclasses "alnum", "alpha", +"upper", "lower", "digit", "xdigit", "punct". +.\" Note: UNIX98 (susv2/xbd/locale.html) says that "space" and "graph" may +.\" have characters in common, except U+0020. But ISO C99 (ISO/IEC 9899:1999 +.\" section 7.25.2.1.10) says that "space" and "graph" are disjoint. +.PP +The wide character class "space" contains the wide character class "blank". +.PP +The wide character class "space" always contains at least the space character +and the control characters '\\f', '\\n', '\\r', '\\t', '\\v'. +.SH "RETURN VALUE" +The \fBiswspace\fP function returns non-zero if \fIwc\fP is a wide character +belonging to the wide character class "space". Otherwise it returns zero. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR isspace (3), +.BR iswctype (3) +.SH NOTES +The behaviour of \fBiswspace\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/iswupper.3 b/man3/iswupper.3 new file mode 100644 index 000000000..fae00f075 --- /dev/null +++ b/man3/iswupper.3 @@ -0,0 +1,64 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWUPPER 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +iswupper \- test for uppercase wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int iswupper(wint_t " wc ); +.fi +.SH DESCRIPTION +The \fBiswupper\fP function is the wide-character equivalent of the +\fBisupper\fP function. It tests whether \fIwc\fP is a wide character +belonging to the wide character class "upper". +.PP +The wide character class "upper" is a subclass of the wide character class +"alpha", and therefore also a subclass of the wide character class "alnum", of +the wide character class "graph" and of the wide character class "print". +.PP +Being a subclass of the wide character class "print", the wide character class +"upper" is disjoint from the wide character class "cntrl". +.PP +Being a subclass of the wide character class "graph", the wide character class +"upper" is disjoint from the wide character class "space" and its subclass +"blank". +.PP +Being a subclass of the wide character class "alnum", the wide character class +"upper" is disjoint from the wide character class "punct". +.PP +Being a subclass of the wide character class "alpha", the wide character class +"upper" is disjoint from the wide character class "digit". +.PP +The wide character class "upper" contains at least those characters \fIwc\fP +which are equal to \fItowupper(wc)\fP and different from \fItowlower(wc)\fP. +.PP +The wide character class "upper" always contains at least the letters 'A' +to 'Z'. +.SH "RETURN VALUE" +The \fBiswupper\fP function returns non-zero if \fIwc\fP is a wide character +belonging to the wide character class "upper". Otherwise it returns zero. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR isupper (3), +.BR iswctype (3), +.BR towupper (3) +.SH NOTES +The behaviour of \fBiswupper\fP depends on the LC_CTYPE category of the +current locale. +.PP +This function is not very appropriate for dealing with Unicode characters, +because Unicode knows about three cases: upper, lower and title case. diff --git a/man3/iswxdigit.3 b/man3/iswxdigit.3 new file mode 100644 index 000000000..9a562707a --- /dev/null +++ b/man3/iswxdigit.3 @@ -0,0 +1,54 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWXDIGIT 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +iswxdigit \- test for hexadecimal digit wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int iswxdigit(wint_t " wc ); +.fi +.SH DESCRIPTION +The \fBiswxdigit\fP function is the wide-character equivalent of the +\fBisxdigit\fP function. It tests whether \fIwc\fP is a wide character +belonging to the wide character class "xdigit". +.PP +The wide character class "xdigit" is a subclass of the wide character class +"alnum", and therefore also a subclass of the wide character class "graph" and +of the wide character class "print". +.PP +Being a subclass of the wide character class "print", the wide character class +"xdigit" is disjoint from the wide character class "cntrl". +.PP +Being a subclass of the wide character class "graph", the wide character class +"xdigit" is disjoint from the wide character class "space" and its subclass +"blank". +.PP +Being a subclass of the wide character class "alnum", the wide character class +"xdigit" is disjoint from the wide character class "punct". +.PP +The wide character class "xdigit" always contains at least the letters 'A' +to 'F', 'a' to 'f' and the digits '0' to '9'. +.SH "RETURN VALUE" +The \fBiswxdigit\fP function returns non-zero if \fIwc\fP is a wide character +belonging to the wide character class "xdigit". Otherwise it returns zero. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR iswctype (3), +.BR isxdigit (3) +.SH NOTES +The behaviour of \fBiswxdigit\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/isxdigit.3 b/man3/isxdigit.3 new file mode 100644 index 000000000..0b69c7544 --- /dev/null +++ b/man3/isxdigit.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/j0.3 b/man3/j0.3 new file mode 100644 index 000000000..a8a0407b1 --- /dev/null +++ b/man3/j0.3 @@ -0,0 +1,96 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:08:17 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-25, aeb +.\" +.TH J0 3 2002-08-25 "" "Linux Programmer's Manual" +.SH NAME +j0, j0f, j0l, j1, j1f, j1l, jn, jnf, jnl, +y0, y0f, y0l, y1, y1f, y1l, yn, ynf, ynl \- Bessel functions +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double j0(double " x ); +.br +.BI "double j1(double " x ); +.br +.BI "double jn(int " n ", double " x ); +.br +.BI "double y0(double " x ); +.br +.BI "double y1(double " x ); +.br +.BI "double yn(int " n ", double " x ); +.sp +.BI "float j0f(float " x ); +.br +.BI "float j1f(float " x ); +.br +.BI "float jnf(int " n ", float " x ); +.br +.BI "float y0f(float " x ); +.br +.BI "float y1f(float " x ); +.br +.BI "float ynf(int " n ", float " x ); +.sp +.BI "long double j0l(long double " x ); +.br +.BI "long double j1l(long double " x ); +.br +.BI "long double jnl(int " n ", long double " x ); +.br +.BI "long double y0l(long double " x ); +.br +.BI "long double y1l(long double " x ); +.br +.BI "long double ynl(int " n ", long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBj0()\fP and \fBj1()\fP functions return Bessel functions of \fIx\fP +of the first kind of orders 0 and 1, respectively. The \fBjn()\fP function +returns the Bessel function of \fIx\fP of the first kind of order \fIn\fP. +.PP +The \fBy0()\fP and \fBy1()\fP functions return Bessel functions of \fIx\fP +of the second kind of orders 0 and 1, respectively. The \fByn()\fP function +returns the Bessel function of \fIx\fP of the second kind of order \fIn\fP. +.PP +For the functions \fBy0()\fP, \fBy1()\fP and \fByn()\fP, the value of \fIx\fP +must be positive. For negative values of \fIx\fP, these functions return +\-HUGE_VAL. +.PP +The \fBj0f()\fP etc. and \fBj0l()\fP etc. functions are versions that take +and return float and long double values, respectively. +.SH "CONFORMING TO" +The functions returning double conform to SVID 3, BSD 4.3, XPG4, +POSIX 1003.1-2001. The other functions are C99 requirements. +.SH BUGS +There are errors of up to 2e\-16 in the values returned by \fBj0()\fP, +\fBj1()\fP and \fBjn()\fP for values of \fIx\fP between \-8 and 8. diff --git a/man3/j0f.3 b/man3/j0f.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/j0f.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/j0l.3 b/man3/j0l.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/j0l.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/j1.3 b/man3/j1.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/j1.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/j1f.3 b/man3/j1f.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/j1f.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/j1l.3 b/man3/j1l.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/j1l.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/jn.3 b/man3/jn.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/jn.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/jnf.3 b/man3/jnf.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/jnf.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/jnl.3 b/man3/jnl.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/jnl.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/jrand48.3 b/man3/jrand48.3 new file mode 100644 index 000000000..3133f7d62 --- /dev/null +++ b/man3/jrand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man3/jrand48_r.3 b/man3/jrand48_r.3 new file mode 100644 index 000000000..81e9d8ef7 --- /dev/null +++ b/man3/jrand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man3/key_decryptsession.3 b/man3/key_decryptsession.3 new file mode 100644 index 000000000..bc4bb02b2 --- /dev/null +++ b/man3/key_decryptsession.3 @@ -0,0 +1 @@ +.so man3/key_setsecret.3 diff --git a/man3/key_encryptsession.3 b/man3/key_encryptsession.3 new file mode 100644 index 000000000..bc4bb02b2 --- /dev/null +++ b/man3/key_encryptsession.3 @@ -0,0 +1 @@ +.so man3/key_setsecret.3 diff --git a/man3/key_gendes.3 b/man3/key_gendes.3 new file mode 100644 index 000000000..bc4bb02b2 --- /dev/null +++ b/man3/key_gendes.3 @@ -0,0 +1 @@ +.so man3/key_setsecret.3 diff --git a/man3/key_secretkey_is_set.3 b/man3/key_secretkey_is_set.3 new file mode 100644 index 000000000..bc4bb02b2 --- /dev/null +++ b/man3/key_secretkey_is_set.3 @@ -0,0 +1 @@ +.so man3/key_setsecret.3 diff --git a/man3/key_setsecret.3 b/man3/key_setsecret.3 new file mode 100644 index 000000000..36fb656b7 --- /dev/null +++ b/man3/key_setsecret.3 @@ -0,0 +1,67 @@ +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" I had no way the check the functions out +.\" be carefull +.TH KEY_SETSECRET 3 2002-07-18 "secure rpc" +.SH NAME +key_decryptsession, key_encryptsession, key_setsecret, key_gendes, +key_secretkey_is_set \- interfaces to rpc keyserver daemon +.SH SYNOPSIS +.sp +.BR "#include " +.sp +.BI "int key_decryptsession(const char *" remotename , +.BI "des_block *" deskey ); +.sp +.BI "int key_encryptsession(const char *" remotename , +.BI "des_block *" deskey ); +.sp +.BI "int key_gendes(des_block *" deskey ); +.sp +.BI "int key_setsecret(const char *" key ); +.sp +.B "int key_secretkey_is_set(void);" +.sp +.SH DESCRIPTION +The functions here are used within the RPC's secure authentication +mechanism (AUTH_DES). There should be no need for user programs to +use this functions. + +The function +.BR key_decryptsession () +uses the (remote) server netname and takes the DES key +for decrypting. It uses the public key of the server and the +secret key associated with the effective UID of the calling process. + +The function +.BR key_encryptsession () +is the inverse of +.BR key_decryptsession (). +It encrypts the DES keys with the public key of the server and +the secret key associated with the effective UID of the calling process. + +The function +.BR key_gendes () +is used to ask the keyserver for a secure conversation key. + +The function +.BR key_setsecret () +is used to set the key for the effective UID of the calling process. + +The function +.BR key_secretkey_is_set () +can be used to determine whether a key has been +set for the effective UID of the calling process. + +.SH NOTE +Please note that we talk about two types of encryption here. One is +asymmetric using a public and secret key. The other is symmetric, the +64-bit DES. +.br +The routines were part of the linux/doors-project, abandoned by now. + +.SH "RETURN VALUES" +The functions return 1 on success and 0 on failure. + +.SH "SEE ALSO" +.BR crypt (3) diff --git a/man3/killpg.3 b/man3/killpg.3 new file mode 100644 index 000000000..0a477c022 --- /dev/null +++ b/man3/killpg.3 @@ -0,0 +1,73 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 19:04:55 1993 by Rik Faith (faith@cs.unc.edu) +.TH KILLPG 3 1993-04-04 "GNU" "Linux Programmer's Manual" +.SH NAME +killpg \- send signal to all members of a process group +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int killpg(pid_t " pgrp ", int " signal ); +.fi +.SH DESCRIPTION +The +.B killpg() +function causes signal +.I signal +to be sent to all the processes in the process group +.I pgrp +or to the processes' own process group if +.I pgrp +is equal to zero. +.PP +If +.I pgrp +is greater than 1, it is equivalent to +.nf +.sp +.BI kill(- pgrp , signal ); +.fi +.SH "RETURN VALUE" +The value returned is \-1 on error, or 0 for success. +.SH ERRORS +Errors are returned in +.I errno +and can be one of the following: +.TP +.B EINVAL +for an invalid signal, +.TP +.B EPERM +if the userid of the calling process is not equal to that of the +process the signal is sent to, and the userid is not that of the +superuser. +.TP +.B ESRCH +for a process group which does not exist, and +.SH "CONFORMING TO" +POSIX +.SH "SEE ALSO" +.BR kill (2), +.BR signal (2), +.BR signal (7) diff --git a/man3/klogctl.3 b/man3/klogctl.3 new file mode 100644 index 000000000..bbe6ab283 --- /dev/null +++ b/man3/klogctl.3 @@ -0,0 +1 @@ +.so man2/syslog.2 diff --git a/man3/l64a.3 b/man3/l64a.3 new file mode 100644 index 000000000..e54ce2724 --- /dev/null +++ b/man3/l64a.3 @@ -0,0 +1 @@ +.so man3/a64l.3 diff --git a/man3/labs.3 b/man3/labs.3 new file mode 100644 index 000000000..97db8d2b6 --- /dev/null +++ b/man3/labs.3 @@ -0,0 +1 @@ +.so man3/abs.3 diff --git a/man3/lckpwdf.3 b/man3/lckpwdf.3 new file mode 100644 index 000000000..142c5a5ca --- /dev/null +++ b/man3/lckpwdf.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/lcong48.3 b/man3/lcong48.3 new file mode 100644 index 000000000..3133f7d62 --- /dev/null +++ b/man3/lcong48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man3/lcong48_r.3 b/man3/lcong48_r.3 new file mode 100644 index 000000000..81e9d8ef7 --- /dev/null +++ b/man3/lcong48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man3/ldexp.3 b/man3/ldexp.3 new file mode 100644 index 000000000..7fe2ba239 --- /dev/null +++ b/man3/ldexp.3 @@ -0,0 +1,58 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2004-10-31 by aeb +.\" +.TH LDEXP 3 2004-10-31 "" "Linux Programmer's Manual" +.SH NAME +ldexp, ldexpf, ldexpl \- multiply floating-point number by integral power of 2 +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double ldexp(double " x ", int " exp ); +.br +.BI "float ldexpf(float " x ", int " exp ); +.br +.BI "long double ldexpl(long double " x ", int " exp ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The +.B ldexp() +function returns the result of multiplying the floating-point number +.I x +by 2 raised to the power +.IR exp . +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR frexp (3), +.BR modf (3), +.BR scalb (3) diff --git a/man3/ldexpf.3 b/man3/ldexpf.3 new file mode 100644 index 000000000..0e74a023e --- /dev/null +++ b/man3/ldexpf.3 @@ -0,0 +1 @@ +.so man3/ldexp.3 diff --git a/man3/ldexpl.3 b/man3/ldexpl.3 new file mode 100644 index 000000000..0e74a023e --- /dev/null +++ b/man3/ldexpl.3 @@ -0,0 +1 @@ +.so man3/ldexp.3 diff --git a/man3/ldiv.3 b/man3/ldiv.3 new file mode 100644 index 000000000..934824e3e --- /dev/null +++ b/man3/ldiv.3 @@ -0,0 +1 @@ +.so man3/div.3 diff --git a/man3/lfind.3 b/man3/lfind.3 new file mode 100644 index 000000000..24179b4d9 --- /dev/null +++ b/man3/lfind.3 @@ -0,0 +1 @@ +.so man3/lsearch.3 diff --git a/man3/lgamma.3 b/man3/lgamma.3 new file mode 100644 index 000000000..25cd79896 --- /dev/null +++ b/man3/lgamma.3 @@ -0,0 +1,64 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" based on glibc infopages +.\" +.TH LGAMMA 3 2002-08-10 "" "Linux Programmer's Manual" +.SH NAME +lgamma, lgammaf, lgammal, lgamma_r, lgammaf_r, lgammal_r \- log gamma function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double lgamma(double " x ); +.br +.BI "float lgammaf(float " x ); +.br +.BI "long double lgammal(long double " x ); +.sp +.BI "double lgamma_r(double " x ", int *" signp ); +.br +.BI "float lgammaf_r(float " x ", int *" signp ); +.br +.BI "long double lgammal_r(long double " x ", int *" signp ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +For the definition of the Gamma function, see +.BR tgamma (3). +.PP +The \fBlgamma()\fP function returns the natural logarithm of +the absolute value of the Gamma function. +The sign of the Gamma function is returned in the +external integer \fIsigngam\fP declared in +.IR . +It is 1 when the Gamma function is positive or zero, \-1 +when it is negative. +.PP +Since using a constant location +.I signgam +is not thread-safe, the functions \fBlgamma_r()\fP etc. have +been introduced; they return this sign via the parameter +.IR signp . +.PP +For nonpositive integer values of \fIx\fP, \fBlgamma()\fP returns HUGE_VAL, +sets \fIerrno\fP to ERANGE and raises the zero divide exception. +(Similarly, \fBlgammaf()\fP returns HUGE_VALF and \fBlgammal()\fP returns +HUGE_VALL.) +.SH ERRORS +In order to check for errors, set +.I errno +to zero and call +.I feclearexcept(FE_ALL_EXCEPT) +before calling these functions. On return, if +.I errno +is non-zero or +.I fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.LP +A range error occurs if x is too large. +A pole error occurs if x is a negative integer or zero. +.SH "CONFORMING TO" +C99, SVID 3, BSD 4.3 +.SH "SEE ALSO" +.BR tgamma (3) diff --git a/man3/lgamma_r.3 b/man3/lgamma_r.3 new file mode 100644 index 000000000..be0ed98e0 --- /dev/null +++ b/man3/lgamma_r.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man3/lgammaf.3 b/man3/lgammaf.3 new file mode 100644 index 000000000..be0ed98e0 --- /dev/null +++ b/man3/lgammaf.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man3/lgammaf_r.3 b/man3/lgammaf_r.3 new file mode 100644 index 000000000..be0ed98e0 --- /dev/null +++ b/man3/lgammaf_r.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man3/lgammal.3 b/man3/lgammal.3 new file mode 100644 index 000000000..be0ed98e0 --- /dev/null +++ b/man3/lgammal.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man3/lgammal_r.3 b/man3/lgammal_r.3 new file mode 100644 index 000000000..be0ed98e0 --- /dev/null +++ b/man3/lgammal_r.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man3/llabs.3 b/man3/llabs.3 new file mode 100644 index 000000000..97db8d2b6 --- /dev/null +++ b/man3/llabs.3 @@ -0,0 +1 @@ +.so man3/abs.3 diff --git a/man3/lldiv.3 b/man3/lldiv.3 new file mode 100644 index 000000000..934824e3e --- /dev/null +++ b/man3/lldiv.3 @@ -0,0 +1 @@ +.so man3/div.3 diff --git a/man3/llrint.3 b/man3/llrint.3 new file mode 100644 index 000000000..d1c0af3b8 --- /dev/null +++ b/man3/llrint.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man3/llrintf.3 b/man3/llrintf.3 new file mode 100644 index 000000000..d1c0af3b8 --- /dev/null +++ b/man3/llrintf.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man3/llrintl.3 b/man3/llrintl.3 new file mode 100644 index 000000000..d1c0af3b8 --- /dev/null +++ b/man3/llrintl.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man3/llround.3 b/man3/llround.3 new file mode 100644 index 000000000..bcc9b0fda --- /dev/null +++ b/man3/llround.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man3/llroundf.3 b/man3/llroundf.3 new file mode 100644 index 000000000..bcc9b0fda --- /dev/null +++ b/man3/llroundf.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man3/llroundl.3 b/man3/llroundl.3 new file mode 100644 index 000000000..bcc9b0fda --- /dev/null +++ b/man3/llroundl.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man3/localeconv.3 b/man3/localeconv.3 new file mode 100644 index 000000000..317826398 --- /dev/null +++ b/man3/localeconv.3 @@ -0,0 +1,62 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 19:01:20 1993 by Rik Faith (faith@cs.unc.edu) +.TH LOCALECONV 3 1993-04-25 "GNU" "Linux Programmer's Manual" +.SH NAME +localeconv \- get numeric formatting information +.SH SYNOPSIS +.nf +.B #include +.sp +.B struct lconv *localeconv(void); +.fi +.SH DESCRIPTION +The +.B localeconv() +function returns a pointer to a +.B struct lconv +for the current locale. This structure is defined in the header-file +.B locale.h +and contains all values associated with the locale categories +.B LC_NUMERIC +and +.BR LC_MONETARY . +Programs may also use the functions +.B printf() +and +.B strfmon() +that behave according the the actual locale in use. +.SH "CONFORMING TO" +ANSI C, POSIX.1 +.SH BUGS +The +.B printf() +family of functions may or may not honor the current locale. +.SH "SEE ALSO" +.BR locale (1), +.BR localedef (1), +.BR isalpha (3), +.BR setlocale (3), +.BR strcoll (3), +.BR strftime (3), +.BR locale (7) diff --git a/man3/localtime.3 b/man3/localtime.3 new file mode 100644 index 000000000..84a3baa92 --- /dev/null +++ b/man3/localtime.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man3/localtime_r.3 b/man3/localtime_r.3 new file mode 100644 index 000000000..84a3baa92 --- /dev/null +++ b/man3/localtime_r.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man3/lockf.3 b/man3/lockf.3 new file mode 100644 index 000000000..58b4e7544 --- /dev/null +++ b/man3/lockf.3 @@ -0,0 +1,124 @@ +.\" Copyright 1997 Nicolás Lichtmaier +.\" Created Thu Aug 7 00:44:00 ART 1997 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" Added section stuff, aeb, 2002-04-22. +.\" Corrected include file, drepper, 2003-06-15. +.\" +.TH LOCKF 3 2002-04-22 "Linux 2.0" "Linux Programmer's Manual" +.SH NAME +lockf \- apply, test or remove a POSIX lock on an open file +.SH SYNOPSIS +.B #include +.sp +.BR "int lockf(int " fd ", int " cmd ", off_t " len ); +.SH DESCRIPTION +Apply, test or remove a POSIX lock on a section of an open file. +The file is specified by +.IR fd , +a file descriptor open for writing, the action by +.IR cmd , +and the section consists of byte positions +.IR pos .. pos + len -1 +if len is positive, and +.IR pos - len .. pos -1 +if len is negative, where +.I pos +is the current file position, and if +.I len +is zero, the section extends from the current file position to +infinity, encompassing the present and future end-of-file positions. +In all cases, the section may extend past current end-of-file. +.LP +On Linux, this call is just an interface for +.BR fcntl (2). +(In general, the relation between +.B lockf +and +.B fcntl +is unspecified.) +.LP +Valid operations are given below: +.TP +.B F_LOCK +Set an exclusive lock on the specified section of the file. +If (part of) this section is already locked, the call +blocks until the previous lock is released. +If this section overlaps an earlier locked section, +both are merged. +File locks are released as soon as the process holding the locks +closes some file descriptor for the file. A child process does not +inherit these locks. +.TP +.B F_TLOCK +Same as +.B F_LOCK +but the call never blocks and returns an error instead if the file is +already locked. +.TP +.B F_ULOCK +Unlock the indicated section of the file. +This may cause a locked section to be split into two locked sections. +.TP +.B F_TEST +Test the lock: return 0 if the specified section +is unlocked or locked by this process; return \-1, set +.I errno +to +.BR EACCES , +if another process holds a lock. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EAGAIN +The file is locked and +.B F_TLOCK +or +.B F_TEST +was specified, or the operation is prohibited because the file has +been memory-mapped by another process. +.TP +.B EBADF +.I fd +is not an open file descriptor. +.TP +.B EDEADLK +The command was +.B T_LOCK +and this lock operation would cause a deadlock. +.TP +.B EINVAL +An invalid operation was specified in +.IR fd . +.TP +.B ENOLCK +Too many segment locks open, lock table is full. +.SH "CONFORMING TO" +SYSV, POSIX 1003.1-2001 +.SH "SEE ALSO" +.BR fcntl (2), +.BR flock (2) +.br +There are also +.I locks.txt +and +.I mandatory.txt +in +.IR /usr/src/linux/Documentation . diff --git a/man3/log.3 b/man3/log.3 new file mode 100644 index 000000000..ab4d2bb51 --- /dev/null +++ b/man3/log.3 @@ -0,0 +1,63 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH EXP 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +log, logf, logl \- natural logarithmic function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double log(double " x ); +.sp +.BI "float logf(float " x ); +.sp +.BI "long double logl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBlog()\fP function returns the natural logarithm of \fIx\fP. +.SH ERRORS +The \fBlog()\fP function can return the following errors: +.TP +.B EDOM +The argument \fIx\fP is negative. +.TP +.B ERANGE +The argument \fIx\fP is zero. The log of zero is not defined +(minus infinity). +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR cbrt (3), +.BR sqrt (3) diff --git a/man3/log10.3 b/man3/log10.3 new file mode 100644 index 000000000..8af6f2948 --- /dev/null +++ b/man3/log10.3 @@ -0,0 +1,62 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH EXP 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +log10, log10f, log10l \- base-10 logarithmic function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double log10(double " x ); +.sp +.BI "float log10f(float " x ); +.sp +.BI "long double log10l(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBlog10()\fP function returns the base 10 logarithm of \fIx\fP. +.SH ERRORS +The \fBlog10()\fP function can return the following errors: +.TP +.B EDOM +The argument \fIx\fP is negative. +.TP +.B ERANGE +The argument \fIx\fP is zero. The log of zero is not defined. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR cbrt (3), +.BR sqrt (3) diff --git a/man3/log10f.3 b/man3/log10f.3 new file mode 100644 index 000000000..dfa5796ed --- /dev/null +++ b/man3/log10f.3 @@ -0,0 +1 @@ +.so man3/log10.3 diff --git a/man3/log10l.3 b/man3/log10l.3 new file mode 100644 index 000000000..dfa5796ed --- /dev/null +++ b/man3/log10l.3 @@ -0,0 +1 @@ +.so man3/log10.3 diff --git a/man3/log1p.3 b/man3/log1p.3 new file mode 100644 index 000000000..b7a50a7bf --- /dev/null +++ b/man3/log1p.3 @@ -0,0 +1,50 @@ +.\" Copyright 1995 Jim Van Zandt +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH LOG1P 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +log1p \- logarithm of 1 plus argument +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double log1p(double " x ); +.sp +.BI "float log1pf(float " x ); +.sp +.BI "long double log1pl(long double " x ); +.sp +.fi +Link with \-lm. +.SH DESCRIPTION +.BI log1p( x ) +returns a value equivalent to `log (1 + \fIx\fP)'. It is computed in a way +that is accurate even if the value of \fIx\fP is near zero. +.SH "CONFORMING TO" +BSD, C99. +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR exp (3), +.BR expm1 (3), +.BR log (3) diff --git a/man3/log1pf.3 b/man3/log1pf.3 new file mode 100644 index 000000000..a4dec80e7 --- /dev/null +++ b/man3/log1pf.3 @@ -0,0 +1 @@ +.so man3/log1p.3 diff --git a/man3/log1pl.3 b/man3/log1pl.3 new file mode 100644 index 000000000..a4dec80e7 --- /dev/null +++ b/man3/log1pl.3 @@ -0,0 +1 @@ +.so man3/log1p.3 diff --git a/man3/log2.3 b/man3/log2.3 new file mode 100644 index 000000000..d62340046 --- /dev/null +++ b/man3/log2.3 @@ -0,0 +1,59 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH LOG2 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +log2, log2f, log2l \- base-2 logarithmic function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double log2(double " x ); +.br +.BI "float log2f(float " x ); +.br +.BI "long double log2l(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBlog2()\fP function returns the base 2 logarithm of \fIx\fP. +.SH ERRORS +The \fBlog2()\fP function can return the following error: +.TP +.B EDOM +The argument \fIx\fP is negative. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR cbrt (3), +.BR sqrt (3) diff --git a/man3/log2f.3 b/man3/log2f.3 new file mode 100644 index 000000000..23aeb4ad0 --- /dev/null +++ b/man3/log2f.3 @@ -0,0 +1 @@ +.so man3/log2.3 diff --git a/man3/log2l.3 b/man3/log2l.3 new file mode 100644 index 000000000..23aeb4ad0 --- /dev/null +++ b/man3/log2l.3 @@ -0,0 +1 @@ +.so man3/log2.3 diff --git a/man3/logb.3 b/man3/logb.3 new file mode 100644 index 000000000..88d8f22cb --- /dev/null +++ b/man3/logb.3 @@ -0,0 +1,101 @@ +.\" Copyright 2004 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Inspired by a page by Walter Harms created 2002-08-10 +.\" +.TH LOGB 3 2004-10-31 "" "Linux Programmer's Manual" +.SH NAME +logb, logbf, logbl \- get exponent of a floating point value +.SH SYNOPSIS +.B #include +.sp +.BI "double logb(double " x ); +.br +.BI "float logbf(float " x ); +.br +.BI "long double logbl(long double " x ); +.sp +Link with \-lm. +.SH DESCRIPTION +These functions extract the exponent of +.I x +and return it as a floating-point value. If +.B FLT_RADIX +is two, +.BI logb( x ) +is equal to +.BI floor(log2( x ))\fR, +except it's probably faster. +.LP +If +.I x +is de-normalized, +.B logb() +returns the exponent +.I x +would have if it were normalized. +.LP +If +.I x +is zero, -HUGE_VAL (resp. -HUGE_VALF, -HUGE_VALL) +is returned, and a pole error occurs. +If +.I x +is infinite, plus infinity is returned. +If +.I x +is NaN, NaN is returned. +.\" .SH "RETURN VALUE" +.\" These functions return the exponent part of their argument. +.SH ERRORS +In order to check for errors, set +.I errno +to zero and call +.I feclearexcept(FE_ALL_EXCEPT) +before calling these functions. On return, if +.I errno +is non-zero or +.I fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.LP +If an error occurs and +.I "(math_errhandling & MATH_ERRNO)" +is non-zero, then +.I errno is set to +.BR ERANGE . +If an error occurs and +.I "(math_errhandling & MATH_ERREXCEPT)" +is non-zero, then the divide-by-zero floating-point exception is raised. +.LP +A pole error occurs when +.I x +is zero. +.SH HISTORY +The +.B logb +function occurs in BSD 4.3. +.\" see IEEE.3 in the BSD 4.3 manual +.SH "CONFORMING TO" +ISO C99 +.SH "SEE ALSO" +.BR log (3), +.BR ilogb (3) diff --git a/man3/logbf.3 b/man3/logbf.3 new file mode 100644 index 000000000..4a70936a4 --- /dev/null +++ b/man3/logbf.3 @@ -0,0 +1 @@ +.so man3/logb.3 diff --git a/man3/logbl.3 b/man3/logbl.3 new file mode 100644 index 000000000..4a70936a4 --- /dev/null +++ b/man3/logbl.3 @@ -0,0 +1 @@ +.so man3/logb.3 diff --git a/man3/logf.3 b/man3/logf.3 new file mode 100644 index 000000000..7807e7642 --- /dev/null +++ b/man3/logf.3 @@ -0,0 +1 @@ +.so man3/log.3 diff --git a/man3/login.3 b/man3/login.3 new file mode 100644 index 000000000..d9c1e9b6d --- /dev/null +++ b/man3/login.3 @@ -0,0 +1,114 @@ +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, +.\" USA. +.\" +.\" Derived from text written by Martin Schulze (or taken from glibc.info) +.\" and text written by Paul Thompson - both copyright 2002. +.\" +.TH LOGIN 3 2004-05-06 "GNU/Linux" "Linux System Administration" +.SH NAME +login, logout \- write utmp and wtmp entries +.SH SYNOPSIS +.B #include +.sp +.BI "void login(const struct utmp *" ut ); +.br +.BI "int logout(const char *" ut_line ); +.SH DESCRIPTION +The utmp file records who is currently using the system. +The wtmp file records all logins and logouts. See +.BR utmp (5). +.LP +The function +.BR login () +takes the supplied struct utmp +.IR ut , +and writes it to both utmp and wtmp file. +.LP +The function +.BR logout () +clears the entry in the utmp file again. +.SH "GNU DETAILS" +More precisely, +.BR login () +takes the argument +.I ut +struct, fills the field +.I ut->ut_type +(if there is such a field) with the value +.BR USER_PROCESS , +and fills the field +.I ut->ut_pid +(if there is such a field) with the process ID of the calling process. +Then it tries to fill the field +.IR ut->ut_line . +It takes the first of stdin, stdout, stderr that is a tty, and +stores the corresponding pathname minus a possible leading /dev/ +into this field, and then writes the struct to the utmp file. +On the other hand, if no tty name was found, this field is filled with "???" +and the struct is not written to the utmp file. +After this, the struct is written to the wtmp file. +.LP +The +.BR logout () +function searches the utmp file for an entry matching the +.I ut_line +argument. If a record is found, it is updated by zeroing out the +.I ut_name +and +.I ut_host +fields, updating the +.I ut_tv +timestamp field and setting +.I ut_type +(if there is such a field) to +.BR DEAD_PROCESS . +.SH "RETURN VALUES" +The +.BR logout () +function returns 1 if the entry was successfully written to the +database, or 0 if an error occurred. +.SH NOTE +These functions are included in libutil, hence you'll need to add +.B \-lutil +to your compiler commandline. + +Note that the +member +.B ut_user +of struct utmp is called +.B ut_name +in BSD. Therefore, +.B ut_name +is defined as an alias for +.B ut_user +in +.IR utmp.h . +.SH FILES +.TP +.I /var/run/utmp +user accounting database, configured through _PATH_UTMP in +.I +.TP +.I /var/log/wtmp +user accounting log file, configured through _PATH_WTMP in +.I +.SH "SEE ALSO" +.BR getutent (3), +.BR utmp (5) diff --git a/man3/login_tty.3 b/man3/login_tty.3 new file mode 100644 index 000000000..fb4952d52 --- /dev/null +++ b/man3/login_tty.3 @@ -0,0 +1 @@ +.so man3/openpty.3 diff --git a/man3/logl.3 b/man3/logl.3 new file mode 100644 index 000000000..7807e7642 --- /dev/null +++ b/man3/logl.3 @@ -0,0 +1 @@ +.so man3/log.3 diff --git a/man3/logout.3 b/man3/logout.3 new file mode 100644 index 000000000..a1ee67257 --- /dev/null +++ b/man3/logout.3 @@ -0,0 +1 @@ +.so man3/login.3 diff --git a/man3/logwtmp.3 b/man3/logwtmp.3 new file mode 100644 index 000000000..0dc4dea39 --- /dev/null +++ b/man3/logwtmp.3 @@ -0,0 +1 @@ +.so man3/updwtmp.3 diff --git a/man3/longjmp.3 b/man3/longjmp.3 new file mode 100644 index 000000000..db3ae71e0 --- /dev/null +++ b/man3/longjmp.3 @@ -0,0 +1,65 @@ +.\" Written by Michael Haardt, Fri Nov 25 14:51:42 MET 1994 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Added siglongjmp, Sun Mar 2 22:03:05 EST 1997, jrv@vanzandt.mv.com +.\" Modifications, Sun Feb 26 14:39:45 1995, faith@cs.unc.edu +.\" " +.TH LONGJMP 3 1997-03-02 "" "Library functions" +.SH NAME +longjmp, siglongjmp \- non-local jump to a saved stack context +.SH SYNOPSIS +.ad l +.B #include +.sp +.nf +.BI "void longjmp(jmp_buf " env ", int " val ); +.BI "void siglongjmp(sigjmp_buf " env ", int " val ); +.fi +.ad b +.SH DESCRIPTION +\fBlongjmp()\fP and \fBsetjmp()\fP are useful for dealing with errors +and interrupts encountered in a low-level subroutine of a program. +\fBlongjmp()\fP restores the environment saved by the last call of +\fBsetjmp()\fP with the corresponding \fIenv\fP argument. After +\fBlongjmp()\fP is completed, program execution continues as if the +corresponding call of \fBsetjmp()\fP had just returned the value +\fIval\fP. \fBlongjmp()\fP cannot cause 0 to be returned. If longjmp +is invoked with a second argument of 0, 1 will be returned instead. +.P +\fBsiglongjmp()\fP is similar to \fBlongjmp()\fP except for the type of +its \fIenv\fP argument. If the \fBsigsetjmp()\fP call that set this +\fIenv\fP used a nonzero \fIsavesigs\fP flag, \fBsiglongjmp()\fP also +restores the set of blocked signals. +.SH "RETURN VALUE" +These functions never return. +.SH "CONFORMING TO" +POSIX +.SH NOTES +POSIX does not specify whether \fBlongjmp\fP will restore the signal +context. If you want to save and restore signal masks, use +\fBsiglongjmp\fP. +.P +\fBlongjmp()\fP and \fBsiglongjmp()\fP make programs hard to +understand and maintain. If possible an alternative should be used. +.SH "SEE ALSO" +.BR setjmp (3), +.BR sigsetjmp (3) diff --git a/man3/lrand48.3 b/man3/lrand48.3 new file mode 100644 index 000000000..3133f7d62 --- /dev/null +++ b/man3/lrand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man3/lrand48_r.3 b/man3/lrand48_r.3 new file mode 100644 index 000000000..81e9d8ef7 --- /dev/null +++ b/man3/lrand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man3/lrint.3 b/man3/lrint.3 new file mode 100644 index 000000000..e28c76ea7 --- /dev/null +++ b/man3/lrint.3 @@ -0,0 +1,66 @@ +.\" Copyright 2001 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH LRINT 3 2001-05-31 "" "Linux Programmer's Manual" +.SH NAME +lrint, lrintf, lrintl, llrint, llrintf, llrintl \- round to nearest integer +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "long int lrint(double " x ); +.br +.BI "long int lrintf(float " x ); +.br +.BI "long int lrintl(long double " x ); +.sp +.BI "long long int llrint(double " x ); +.br +.BI "long long int llrintf(float " x ); +.br +.BI "long long int llrintl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +These functions round their argument to the nearest integer value, +using the current rounding direction. +If \fIx\fP is infinite or NaN, or if the rounded value is outside +the range of the return type, the numeric result is unspecified. +A domain error may occur if the magnitude of \fIx\fP is too large. +.SH "RETURN VALUE" +The rounded integer value. +.SH ERRORS +.TP +.B EDOM +The magnitude of \fIx\fP is too large and +.I "(math_errhandling & MATH_ERRNO)" +is non-zero. +.SH "CONFORMING TO" +C99. +.SH "SEE ALSO" +.BR ceil (3), +.BR floor (3), +.BR lround (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3) diff --git a/man3/lrintf.3 b/man3/lrintf.3 new file mode 100644 index 000000000..d1c0af3b8 --- /dev/null +++ b/man3/lrintf.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man3/lrintl.3 b/man3/lrintl.3 new file mode 100644 index 000000000..d1c0af3b8 --- /dev/null +++ b/man3/lrintl.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man3/lround.3 b/man3/lround.3 new file mode 100644 index 000000000..5796109d5 --- /dev/null +++ b/man3/lround.3 @@ -0,0 +1,66 @@ +.\" Copyright 2001 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH LROUND 3 2001-05-31 "" "Linux Programmer's Manual" +.SH NAME +lround, lroundf, lroundl, llround, llroundf, llroundl \- round to nearest integer, away from zero +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "long int lround(double " x ); +.br +.BI "long int lroundf(float " x ); +.br +.BI "long int lroundl(long double " x ); +.sp +.BI "long long int llround(double " x ); +.br +.BI "long long int llroundf(float " x ); +.br +.BI "long long int llroundl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +These functions round their argument to the nearest integer value, +rounding away from zero, regardless of the current rounding direction. +If \fIx\fP is infinite or NaN, or if the rounded value is outside +the range of the return type, the numeric result is unspecified. +A domain error may occur if the magnitude of \fIx\fP is too large. +.SH "RETURN VALUE" +The rounded integer value. +.SH ERRORS +.TP +.B EDOM +The magnitude of \fIx\fP is too large and +.I "(math_errhandling & MATH_ERRNO)" +is non-zero. +.SH "CONFORMING TO" +C99. +.SH "SEE ALSO" +.BR ceil (3), +.BR floor (3), +.BR lrint (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3) diff --git a/man3/lroundf.3 b/man3/lroundf.3 new file mode 100644 index 000000000..bcc9b0fda --- /dev/null +++ b/man3/lroundf.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man3/lroundl.3 b/man3/lroundl.3 new file mode 100644 index 000000000..bcc9b0fda --- /dev/null +++ b/man3/lroundl.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man3/lsearch.3 b/man3/lsearch.3 new file mode 100644 index 000000000..96b2d8485 --- /dev/null +++ b/man3/lsearch.3 @@ -0,0 +1,69 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" Copyright 1995 Jim Van Zandt +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Corrected prototype and include, aeb, 990927 +.TH LSEARCH 3 1999-09-27 "GNU" "Linux Programmer's Manual" +.SH NAME +lfind, lsearch \- linear search of an array +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void *lfind(const void *" key ", const void *" base ", size_t *" nmemb , +.RS +.BI "size_t " size ", int(*" compar ")(const void *, const void *));" +.RE +.sp +.BI "void *lsearch(const void *" key ", void *" base ", size_t *" nmemb , +.RS +.BI "size_t " size ", int(*" compar ")(const void *, const void *));" +.RE +.fi +.SH DESCRIPTION +\fBlfind()\fP and \fBlsearch()\fP perform a linear search for +\fIkey\fP in the array \fIbase\fP which has *\fInmemb\fP elements of +\fIsize\fP bytes each. The comparison function referenced by +\fIcompar\fP is expected to have two arguments which point to the +\fIkey\fP object and to an array member, in that order, and which +returns zero if the \fIkey\fP object matches the array member, and +non-zero otherwise. +.PP +If \fBlsearch()\fP does not find a matching element, then the \fIkey\fP +object is inserted at the end of the table, and *\fInmemb\fP is +incremented. +In particular, one should know that a matching element +exists, or that more room is available. +.SH "RETURN VALUE" +\fBlfind()\fP returns a pointer to a matching member of the array, or +\fBNULL\fP if no match is found. \fBlsearch()\fP returns a pointer to +a matching member of the array, or to the newly added member if no +match is found. +.SH "CONFORMING TO" +SVID 1, SVID 3, BSD 4.3, POSIX 1003.1-2003. +Present in libc since libc-4.6.27. +.SH BUGS +The naming is unfortunate. +.SH "SEE ALSO" +.BR bsearch (3), +.BR hsearch (3), +.BR tsearch (3) diff --git a/man3/makecontext.3 b/man3/makecontext.3 new file mode 100644 index 000000000..34f0998e6 --- /dev/null +++ b/man3/makecontext.3 @@ -0,0 +1,82 @@ +.\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH MAKECONTEXT 3 2001-11-15 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +makecontext, swapcontext \- manipulate user context +.SH SYNOPSIS +.B #include +.sp +.BI "void makecontext(ucontext_t *" ucp ", void *" func "(), +.BI "int " argc ", ...);" +.br +.BI "int swapcontext (ucontext_t *" oucp ", ucontext_t *" ucp ); +.SH DESCRIPTION +In a SysV-like environment, one has the type \fBucontext_t\fP defined in +.I +and the four functions +\fBgetcontext()\fP, \fBsetcontext()\fP, \fBmakecontext()\fP +and \fBswapcontext()\fP that allow user-level context switching +between multiple threads of control within a process. +.LP +For the type and the first two functions, see +.BR getcontext (2). +.LP +The \fBmakecontext()\fP function modifies the context pointed to +by \fIucp\fP (which was obtained from a call to \fBgetcontext()\fP). +Before calling \fBmakecontext()\fP, one should allocate a new stack +for this context, assigning to \fIucp->uc_stack\fP, and define a +successor context, assigning to \fIucp->uc_link\fP. +When this context is later activated (using \fBsetcontext()\fP or +\fBswapcontext()\fP) then first the function \fIfunc\fP is called, +with the arguments specified following \fIargc\fP (where \fIargc\fP +must contain the number of these arguments), and when this function +returns, the successor context is activated. When the successor context +pointer is NULL, the thread exits. +.LP +The \fBswapcontext()\fP function saves the current context in +the structure pointed to by \fIoucp\fP, and then activates the +context pointed to by \fIucp\fP. +.SH "RETURN VALUE" +When successful, \fBmakecontext()\fP returns 0 and \fBswapcontext()\fP +does not return. (But we may return later, in case \fIoucp\fP is +activated, in which case it looks like \fBswapcontext()\fP returns 0.) +On error, both return \-1 and set \fIerrno\fP appropriately. +.SH ERRORS +.TP +.B ENOMEM +Insufficient stack space left. +.SH NOTES +The interpretation of \fIucp->uc_stack\fP is just as in +.BR sigaltstack (2), +namely, this struct contains start and length of a memory area +to be used as stack, regardless of the direction of growth of +the stack. So, it is not necessary for the user program to +worry about this direction. +.SH "CONFORMING TO" +SUSv2, POSIX 1003.1-2001. +.SH "SEE ALSO" +.BR getcontext (2), +.BR sigaction (2), +.BR sigaltstack (2), +.BR sigprocmask (2), +.BR sigsetjmp (3) diff --git a/man3/malloc.3 b/man3/malloc.3 new file mode 100644 index 000000000..548dc1d8f --- /dev/null +++ b/man3/malloc.3 @@ -0,0 +1,194 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 19:00:59 1993 by Rik Faith (faith@cs.unc.edu) +.\" Clarification concerning realloc, iwj10@cus.cam.ac.uk (Ian Jackson), 950701 +.\" Documented MALLOC_CHECK_, Wolfram Gloger (wmglo@dent.med.uni-muenchen.de) +.\" +.TH MALLOC 3 1993-04-04 "GNU" "Linux Programmer's Manual" +.SH NAME +calloc, malloc, free, realloc \- Allocate and free dynamic memory +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void *calloc(size_t " "nmemb" ", size_t " "size" ); +.nl +.BI "void *malloc(size_t " "size" ); +.nl +.BI "void free(void " "*ptr" ); +.nl +.BI "void *realloc(void " "*ptr" ", size_t " "size" ); +.fi +.SH DESCRIPTION +.B calloc() +allocates memory for an array of +.I nmemb +elements of +.I size +bytes each and returns a pointer to the allocated memory. +The memory is set to zero. +.PP +.B malloc() +allocates +.I size +bytes and returns a pointer to the allocated memory. +The memory is not cleared. +.PP +.B free() +frees the memory space pointed to by +.IR ptr , +which must have been returned by a previous call to +.BR malloc() , +.B calloc() +or +.BR realloc() . +Otherwise, or if +.BI "free(" "ptr" ) +has already been called before, undefined behaviour occurs. +If +.I ptr +is +.BR NULL , +no operation is performed. +.PP +.B realloc() +changes the size of the memory block pointed to by +.I ptr +to +.I size +bytes. +The contents will be unchanged to the minimum of the old and new sizes; +newly allocated memory will be uninitialized. +If +.I ptr +is +.BR NULL , +the call is equivalent to +.BR malloc(size) ; +if size is equal to zero, +the call is equivalent to +.BI "free(" "ptr" ) . +Unless +.I ptr +is +.BR NULL , +it must have been returned by an earlier call to +.BR malloc() , +.BR calloc() +or +.BR realloc() . +If the area pointed to was moved, a +.BI "free(" "ptr" ) +is done. +.SH "RETURN VALUE" +For +.BR calloc() " and " malloc() , +the value returned is a pointer to the allocated memory, which is suitably +aligned for any kind of variable, or +.B NULL +if the request fails. +.PP +.B free() +returns no value. +.PP +.B realloc() +returns a pointer to the newly allocated memory, which is suitably +aligned for any kind of variable and may be different from +.IR ptr , +or +.B NULL +if the request fails. If +.I size +was equal to 0, either NULL or a pointer suitable to be passed to +.IR free () +is returned. If +.B realloc() +fails the original block is left untouched - it is not freed or moved. +.SH "CONFORMING TO" +ANSI-C +.SH "SEE ALSO" +.BR brk (2), +.BR posix_memalign (3) +.SH NOTES +The Unix98 standard requires +.BR malloc() , +.BR calloc() , +and +.BR realloc () +to set +.I errno +to ENOMEM upon failure. Glibc assumes that this is done +(and the glibc versions of these routines do this); if you +use a private malloc implementation that does not set +.IR errno , +then certain library routines may fail without having +a reason in +.IR errno . +.LP +Crashes in +.BR malloc() , +.BR free() +or +.BR realloc() +are almost always related to heap corruption, such as overflowing +an allocated chunk or freeing the same pointer twice. +.PP +Recent versions of Linux libc (later than 5.4.23) and GNU libc (2.x) +include a malloc implementation which is tunable via environment +variables. When +.BR MALLOC_CHECK_ +is set, a special (less efficient) implementation is used which +is designed to be tolerant against simple errors, such as double +calls of +.BR free() +with the same argument, or overruns of a single byte (off-by-one +bugs). Not all such errors can be protected against, however, and +memory leaks can result. +If +.BR MALLOC_CHECK_ +is set to 0, any detected heap corruption is silently ignored; +if set to 1, a diagnostic is printed on stderr; +if set to 2, +.BR abort() +is called immediately. This can be useful because otherwise +a crash may happen much later, and the true cause for the problem +is then very hard to track down. +.SH BUGS +By default, Linux follows an optimistic memory allocation strategy. +This means that when +.B malloc() +returns non-NULL there is no guarantee that the memory really +is available. This is a really bad bug. +In case it turns out that the system is out of memory, +one or more processes will be killed by the infamous OOM killer. +In case Linux is employed under circumstances where it would be +less desirable to suddenly lose some randomly picked processes, +and moreover the kernel version is sufficiently recent, +one can switch off this overcommitting behavior using a command like +.RS +# echo 2 > /proc/sys/vm/overcommit_memory +.RE +See also the kernel Documentation directory, files +.I vm/overcommit-accounting +and +.IR sysctl/vm.txt . diff --git a/man3/malloc_hook.3 b/man3/malloc_hook.3 new file mode 100644 index 000000000..ffbc3fb32 --- /dev/null +++ b/man3/malloc_hook.3 @@ -0,0 +1,126 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" Heavily based on glibc documentation +.\" Polished, added docs, removed glibc doc bug, 2002-07-20, aeb +.TH MALLOC_HOOK 3 2002-07-20 "GNU" "Linux Programmer's Manual" +.SH NAME +__malloc_hook, __malloc_initialize_hook, +__memalign_hook, __free_hook, __realloc_hook, +__after_morecore_hook \- malloc debugging variables +.SH SYNOPSIS +.sp +.BR "#include " +.sp +.BI "void *(*__malloc_hook)(size_t " size , +.BI "const void *" caller ); +.sp +.BI "void *(*__realloc_hook)(void *" ptr , +.BI "size_t " size , +.BI "const void *" caller ); +.sp +.BI "void *(*__memalign_hook)(size_t " alignment , +.BI "size_t " size , +.BI "const void *" caller ); +.sp +.BI "void (*__free_hook)(void *" ptr , +.BI "const void *" caller ); +.sp +.BI "void (*__malloc_initialize_hook)(void);" +.sp +.BI "void (*__after_morecore_hook)(void);" +.SH DESCRIPTION +The GNU C library lets you modify the behavior of +.IR malloc (), +.IR realloc (), +and +.IR free () +by specifying appropriate hook functions. You can use these hooks +to help you debug programs that use dynamic memory allocation, +for example. +.LP +The variable +.B __malloc_initialize_hook +points at a function that is called once when the malloc implementation +is initialized. This is a weak variable, so it can be overridden in +the application with a definition like the following: +.br +.nf + void (*__malloc_initialize_hook)(void) = my_init_hook; +.fi +.br +Now the function +.IR my_init_hook () +can do the initialization of all hooks. +.LP +The four functions pointed to by +.BR __malloc_hook , +.BR __realloc_hook , +.BR __memalign_hook , +.BR __free_hook +have a prototype like the functions +.IR malloc (), +.IR realloc (), +.IR memalign (), +.IR free (), +respectively, except that they have a final argument +.I caller +that gives the address of the caller of +.IR malloc (), +etc. +.LP +The variable +.B __after_morecore_hook +points at a function that is called each time after +.IR sbrk () +was asked for more core. +.SH "EXAMPLE" +Here a short example how to use these variables. +.sp +.nf +#include +#include + +/* Prototypes for our hooks. */ +static void my_init_hook(void); +static void *my_malloc_hook(size_t, const void *); + +/* Variables to save original hooks. */ +static void *(*old_malloc_hook)(size_t, const void *); + +/* Override initialising hook from the C library. */ +void (*__malloc_initialize_hook) (void) = my_init_hook; + +static void +my_init_hook(void) { + old_malloc_hook = __malloc_hook; + __malloc_hook = my_malloc_hook; +} + +static void * +my_malloc_hook (size_t size, const void *caller) { + void *result; + + /* Restore all old hooks */ + __malloc_hook = old_malloc_hook; + + /* Call recursively */ + result = malloc (size); + + /* Save underlying hooks */ + old_malloc_hook = __malloc_hook; + + /* `printf' might call `malloc', so protect it too. */ + printf ("malloc(%u) called from %p returns %p\n", + (unsigned int) size, caller, result); + + /* Restore our own hooks */ + __malloc_hook = my_malloc_hook; + + return result; +} +.fi +.SH "SEE ALSO" +.BR mallinfo (3), +.BR malloc (3), +.BR mcheck (3), +.BR mtrace (3) diff --git a/man3/mblen.3 b/man3/mblen.3 new file mode 100644 index 000000000..7e1df33e7 --- /dev/null +++ b/man3/mblen.3 @@ -0,0 +1,60 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH MBLEN 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +mblen \- determine number of bytes in next multibyte character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int mblen(const char *" s ", size_t " n ); +.fi +.SH DESCRIPTION +If \fIs\fP is not a NULL pointer, the \fBmblen\fP function inspects at most +\fIn\fP bytes of the multibyte string starting at \fIs\fP and extracts the +next complete multibyte character. It uses a static anonymous shift state only +known to the mblen function. If the multibyte character is not the null wide +character, it returns the number of bytes that were consumed from \fIs\fP. If +the multibyte character is the null wide character, it returns 0. +.PP +If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte +character, \fBmblen\fP returns \fI-1\fP. This can happen even if +\fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift +sequences. +.PP +If the multibyte string starting at \fIs\fP contains an invalid multibyte +sequence before the next complete character, \fBmblen\fP also returns \fI-1\fP. +.PP +If \fIs\fP is a NULL pointer, the \fBmblen\fP function +.\" The Dinkumware doc and the Single Unix specification say this, but +.\" glibc doesn't implement this. +resets the shift state, only known to this function, to the initial state, and +returns non-zero if the encoding has non-trivial shift state, or zero if the +encoding is stateless. +.SH "RETURN VALUE" +The \fBmblen\fP function returns the number of bytes parsed from the multibyte +sequence starting at \fIs\fP, if a non-null wide character was recognized. +It returns 0, if a null wide character was recognized. It returns \-1, if an +invalid multibyte sequence was encountered or if it couldn't parse a complete +multibyte character. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR mbrlen (3) +.SH NOTES +The behaviour of \fBmblen\fP depends on the LC_CTYPE category of the +current locale. +.PP +The function \fBmbrlen\fP provides a better interface to the same +functionality. diff --git a/man3/mbrlen.3 b/man3/mbrlen.3 new file mode 100644 index 000000000..ca9ecc0c1 --- /dev/null +++ b/man3/mbrlen.3 @@ -0,0 +1,56 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH MBRLEN 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +mbrlen \- determine number of bytes in next multibyte character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t mbrlen(const char *" s ", size_t " n ", mbstate_t *" ps ); +.fi +.SH DESCRIPTION +The \fBmbrlen\fP function inspects at most \fIn\fP bytes of the multibyte +string starting at \fIs\fP and extracts the next complete multibyte character. +It updates the shift state \fI*ps\fP. If the multibyte character is not the +null wide character, it returns the number of bytes that were consumed from +\fIs\fP. If the multibyte character is the null wide character, it resets the +shift state \fI*ps\fP to the initial state and returns 0. +.PP +If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte +character, \fBmbrlen\fP returns \fI(size_t)(-2)\fP. This can happen even if +\fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift +sequences. +.PP +If the multibyte string starting at \fIs\fP contains an invalid multibyte +sequence before the next complete character, \fBmbrlen\fP returns +\fI(size_t)(-1)\fP and sets \fBerrno\fP to \fBEILSEQ\fP. In this case, +the effects on \fI*ps\fP are undefined. +.PP +If \fIps\fP is a NULL pointer, a static anonymous state only known to the +mbrlen function is used instead. +.SH "RETURN VALUE" +The \fBmbrlen\fP function returns the number of bytes parsed from the multibyte +sequence starting at \fIs\fP, if a non-null wide character was recognized. +It returns 0, if a null wide character was recognized. It returns (size_t)(-1) +and sets \fBerrno\fP to \fBEILSEQ\fP, if an invalid multibyte sequence was +encountered. It returns (size_t)(-2) if it couldn't parse a complete multibyte +character, meaning that \fIn\fP should be increased. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR mbrtowc (3) +.SH NOTES +The behaviour of \fBmbrlen\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/mbrtowc.3 b/man3/mbrtowc.3 new file mode 100644 index 000000000..d32e93768 --- /dev/null +++ b/man3/mbrtowc.3 @@ -0,0 +1,78 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH MBRTOWC 3 2001-11-22 "GNU" "Linux Programmer's Manual" +.SH NAME +mbrtowc \- convert a multibyte sequence to a wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t mbrtowc(wchar_t *" pwc ", const char *" s ", size_t " n ", mbstate_t *" ps ); +.fi +.SH DESCRIPTION +The main case for this function is when \fIs\fP is not NULL and \fIpwc\fP is +not NULL. In this case, the \fBmbrtowc\fP function inspects at most \fIn\fP +bytes of the multibyte string starting at \fIs\fP, extracts the next complete +multibyte character, converts it to a wide character and stores it at +\fI*pwc\fP. It updates the shift state \fI*ps\fP. If the converted wide +character is not L'\\0', it returns the number of bytes that were consumed +from \fIs\fP. If the converted wide character is L'\\0', it resets the shift +state \fI*ps\fP to the initial state and returns 0. +.PP +If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte +character, \fBmbrtowc\fP returns \fI(size_t)(-2)\fP. This can happen even if +\fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift +sequences. +.PP +If the multibyte string starting at \fIs\fP contains an invalid multibyte +sequence before the next complete character, \fBmbrtowc\fP returns +\fI(size_t)(-1)\fP and sets \fBerrno\fP to \fBEILSEQ\fP. In this case, +the effects on \fI*ps\fP are undefined. +.PP +A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL. In this +case the \fBmbrtowc\fP function behaves as above, excepts that it does not +store the converted wide character in memory. +.PP +A third case is when \fIs\fP is NULL. In this case, \fIpwc\fP and \fIn\fP are +ignored. If the conversion state represented by \fI*ps\fP denotes an +incomplete multibyte character conversion, the \fBmbrtowc\fP function +returns \fI(size_t)(-1)\fP, sets \fBerrno\fP to \fBEILSEQ\fP, and +leaves \fI*ps\fP in an undefined state. Otherwise, the \fBmbrtowc\fP function +puts \fI*ps\fP in the initial state and returns 0. +.PP +In all of the above cases, if \fIps\fP is a NULL pointer, a static anonymous +state only known to the mbrtowc function is used instead. +Otherwise, \fI*ps\fP must be a valid \fBmbstate_t\fP object. +An \fBmbstate_t\fP object \fIa\fP can be initialized to the initial state +by zeroing it, for example using +.sp +.RS +memset(&a, 0, sizeof(a)); +.RE +.SH "RETURN VALUE" +The \fBmbrtowc\fP function returns the number of bytes parsed from the +multibyte sequence starting at \fIs\fP, if a non-L'\\0' wide character +was recognized. +It returns 0, if a L'\\0' wide character was recognized. It returns (size_t)(-1) +and sets \fBerrno\fP to \fBEILSEQ\fP, if an invalid multibyte sequence was +encountered. It returns (size_t)(-2) if it couldn't parse a complete multibyte +character, meaning that \fIn\fP should be increased. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR mbsrtowcs (3) +.SH NOTES +The behaviour of \fBmbrtowc\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/mbsinit.3 b/man3/mbsinit.3 new file mode 100644 index 000000000..12b602362 --- /dev/null +++ b/man3/mbsinit.3 @@ -0,0 +1,66 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH MBSINIT 3 2000-11-20 "GNU" "Linux Programmer's Manual" +.SH NAME +mbsinit \- test for initial shift state +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int mbsinit(const mbstate_t *" ps ); +.fi +.SH DESCRIPTION +Character conversion between the multibyte representation and the wide +character representation uses conversion state, of type \fBmbstate_t\fP. +Conversion of a string uses a finite-state machine; when it is interrupted +after the complete conversion of a number of characters, it may need to +save a state for processing the remaining characters. Such a conversion +state is needed for the sake of encodings such as ISO-2022 and UTF-7. +.PP +The initial state is the state at the beginning of conversion of a string. +There are two kinds of state: The one used by multibyte to wide character +conversion functions, such as \fBmbsrtowcs\fP, and the one used by wide +character to multibyte conversion functions, such as \fBwcsrtombs\fP, +but they both fit in a \fBmbstate_t\fP, and they both have the same +representation for an initial state. +.PP +For 8-bit encodings, all states are equivalent to the initial state. +For multibyte encodings like UTF-8, EUC-*, BIG5 or SJIS, the wide character +to multibyte conversion functions never produce non-initial states, but the +multibyte to wide character conversion functions like \fBmbrtowc\fP do +produce non-initial states when interrupted in the middle of a character. +.PP +One possible way to create an mbstate_t in initial state is to set it to zero: +.nf + mbstate_t state; + memset(&state,0,sizeof(mbstate_t)); +.fi +On Linux, the following works as well, but might generate compiler warnings: +.nf + mbstate_t state = { 0 }; +.fi +.PP +The function \fBmbsinit\fP tests whether \fI*ps\fP corresponds to an +initial state. +.SH "RETURN VALUE" +\fBmbsinit\fP returns non-zero if \fI*ps\fP is an initial state, or if +\fIps\fP is a null pointer. Otherwise it returns 0. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR mbsrtowcs (3), +.BR wcsrtombs (3) +.SH NOTES +The behaviour of \fBmbsinit\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/mbsnrtowcs.3 b/man3/mbsnrtowcs.3 new file mode 100644 index 000000000..42a912c64 --- /dev/null +++ b/man3/mbsnrtowcs.3 @@ -0,0 +1,76 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.TH MBSNRTOWCS 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +mbsnrtowcs \- convert a multibyte string to a wide character string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t mbsnrtowcs(wchar_t *" dest ", const char **" src , +.BI " size_t " nms ", size_t " len ", mbstate_t *" ps ); +.fi +.SH DESCRIPTION +The \fBmbsnrtowcs\fP function is like the \fBmbsrtowcs\fP function, except that +the number of bytes to be converted, starting at \fI*src\fP, is limited to +\fInms\fP. +.PP +If \fIdest\fP is not a NULL pointer, the \fBmbsnrtowcs\fP function converts at +most \fInms\fP bytes from the +multibyte string \fI*src\fP to a wide-character string starting at \fIdest\fP. +At most \fIlen\fP wide characters are written to \fIdest\fP. The shift state +\fI*ps\fP is updated. The conversion is effectively performed by repeatedly +calling mbrtowc(\fIdest\fP,\fI*src\fP,\fIn\fP,\fIps\fP) where \fIn\fP is some +positive number, as long as this call succeeds, and then incrementing +\fIdest\fP by one and \fI*src\fP by the number of bytes consumed. The +conversion can stop for three reasons: +.PP +1. An invalid multibyte sequence has been encountered. In this case \fI*src\fP +is left pointing to the invalid multibyte sequence, (size_t)(-1) is returned, +and \fBerrno\fP is set to \fBEILSEQ\fP. +.PP +2. The \fInms\fP limit forces a stop, or \fIlen\fP non-L'\\0' wide characters +have been stored at \fIdest\fP. In this case \fI*src\fP is left pointing to the +next multibyte sequence to be converted, and the number of wide characters +written to \fIdest\fP is returned. +.PP +3. The multibyte string has been completely converted, including the +terminating '\\0' (which has the side effect of bringing back \fI*ps\fP to the +initial state). In this case \fI*src\fP is set to NULL, and the number of wide +characters written to \fIdest\fP, excluding the terminating L'\\0' character, +is returned. +.PP +If \fIdest\fP is NULL, \fIlen\fP is ignored, and the conversion proceeds as +above, except that the converted wide characters are not written out to memory, +and that no destination length limit exists. +.PP +In both of the above cases, if \fIps\fP is a NULL pointer, a static anonymous +state only known to the mbsnrtowcs function is used instead. +.PP +The programmer must ensure that there is room for at least \fIlen\fP wide +characters at \fIdest\fP. +.SH "RETURN VALUE" +The \fBmbsnrtowcs\fP function returns the number of wide characters that make +up the converted part of the wide character string, not including the +terminating null wide character. If an invalid multibyte sequence was +encountered, (size_t)(-1) is returned, and \fBerrno\fP set to \fBEILSEQ\fP. +.SH "CONFORMING TO" +This function is a GNU extension. +.SH "SEE ALSO" +.BR iconv (3), +.BR mbsrtowcs (3) +.SH NOTES +The behaviour of \fBmbsnrtowcs\fP depends on the LC_CTYPE category of the +current locale. +.PP +Passing NULL as \fIps\fP is not multi-thread safe. diff --git a/man3/mbsrtowcs.3 b/man3/mbsrtowcs.3 new file mode 100644 index 000000000..a7cea5cdb --- /dev/null +++ b/man3/mbsrtowcs.3 @@ -0,0 +1,72 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH MBSRTOWCS 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +mbsrtowcs \- convert a multibyte string to a wide character string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t mbsrtowcs(wchar_t *" dest ", const char **" src , +.BI " size_t " len ", mbstate_t *" ps ); +.fi +.SH DESCRIPTION +If \fIdest\fP is not a NULL pointer, the \fBmbsrtowcs\fP function converts the +multibyte string \fI*src\fP to a wide-character string starting at \fIdest\fP. +At most \fIlen\fP wide characters are written to \fIdest\fP. The shift state +\fI*ps\fP is updated. The conversion is effectively performed by repeatedly +calling mbrtowc(\fIdest\fP,\fI*src\fP,\fIn\fP,\fIps\fP) where \fIn\fP is some +positive number, as long as this call succeeds, and then incrementing +\fIdest\fP by one and \fI*src\fP by the number of bytes consumed. The +conversion can stop for three reasons: +.PP +1. An invalid multibyte sequence has been encountered. In this case \fI*src\fP +is left pointing to the invalid multibyte sequence, (size_t)(-1) is returned, +and \fBerrno\fP is set to \fBEILSEQ\fP. +.PP +2. \fIlen\fP non-L'\\0' wide characters have been stored at \fIdest\fP. In this +case \fI*src\fP is left pointing to the next multibyte sequence to be converted, +and the number of wide characters written to \fIdest\fP is returned. +.PP +3. The multibyte string has been completely converted, including the +terminating '\\0' (which has the side effect of bringing back \fI*ps\fP to the +initial state). In this case \fI*src\fP is set to NULL, and the number of wide +characters written to \fIdest\fP, excluding the terminating L'\\0' character, +is returned. +.PP +If \fIdest\fP is NULL, \fIlen\fP is ignored, and the conversion proceeds as +above, except that the converted wide characters are not written out to memory, +and that no length limit exists. +.PP +In both of the above cases, if \fIps\fP is a NULL pointer, a static anonymous +state only known to the mbsrtowcs function is used instead. +.PP +The programmer must ensure that there is room for at least \fIlen\fP wide +characters at \fIdest\fP. +.SH "RETURN VALUE" +The \fBmbsrtowcs\fP function returns the number of wide characters that make +up the converted part of the wide character string, not including the +terminating null wide character. If an invalid multibyte sequence was +encountered, (size_t)(-1) is returned, and \fBerrno\fP set to \fBEILSEQ\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR iconv (3), +.BR mbsnrtowcs (3), +.BR mbstowcs (3) +.SH NOTES +The behaviour of \fBmbsrtowcs\fP depends on the LC_CTYPE category of the +current locale. +.PP +Passing NULL as \fIps\fP is not multi-thread safe. diff --git a/man3/mbstowcs.3 b/man3/mbstowcs.3 new file mode 100644 index 000000000..59dc61bd7 --- /dev/null +++ b/man3/mbstowcs.3 @@ -0,0 +1,63 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH MBSTOWCS 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +mbstowcs \- convert a multibyte string to a wide character string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t mbstowcs(wchar_t *" dest ", const char *" src ", size_t " n ); +.fi +.SH DESCRIPTION +If \fIdest\fP is not a NULL pointer, the \fBmbstowcs\fP function converts the +multibyte string \fIsrc\fP to a wide-character string starting at \fIdest\fP. +At most \fIn\fP wide characters are written to \fIdest\fP. The conversion starts +in the initial state. The conversion can stop for three reasons: +.PP +1. An invalid multibyte sequence has been encountered. In this case +(size_t)(-1) is returned. +.PP +2. \fIn\fP non-L'\\0' wide characters have been stored at \fIdest\fP. In this +case the number of wide characters written to \fIdest\fP is returned, but the +shift state at this point is lost. +.PP +3. The multibyte string has been completely converted, including the +terminating '\\0'. In this case the number of wide characters written to +\fIdest\fP, excluding the terminating L'\\0' character, is returned. +.PP +The programmer must ensure that there is room for at least \fIn\fP wide +characters at \fIdest\fP. +.PP +If \fIdest\fP is NULL, \fIn\fP is ignored, and the conversion proceeds as +above, except that the converted wide characters are not written out to memory, +and that no length limit exists. +.PP +In order to avoid the case 2 above, the programmer should make sure \fIn\fP is +greater or equal to \fImbstowcs(NULL,src,0)+1\fP. +.SH "RETURN VALUE" +The \fBmbstowcs\fP function returns the number of wide characters that make +up the converted part of the wide character string, not including the +terminating null wide character. If an invalid multibyte sequence was +encountered, (size_t)(-1) is returned. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR mbsrtowcs (3) +.SH NOTES +The behaviour of \fBmbstowcs\fP depends on the LC_CTYPE category of the +current locale. +.PP +The function \fBmbsrtowcs\fP provides a better interface to the same +functionality. diff --git a/man3/mbtowc.3 b/man3/mbtowc.3 new file mode 100644 index 000000000..4934e8d24 --- /dev/null +++ b/man3/mbtowc.3 @@ -0,0 +1,66 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH MBTOWC 3 2001-07-04 "GNU" "Linux Programmer's Manual" +.SH NAME +mbtowc \- convert a multibyte sequence to a wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int mbtowc(wchar_t *" pwc ", const char *" s ", size_t " n ); +.fi +.SH DESCRIPTION +The main case for this function is when \fIs\fP is not NULL and \fIpwc\fP is +not NULL. In this case, the \fBmbtowc\fP function inspects at most \fIn\fP +bytes of the multibyte string starting at \fIs\fP, extracts the next complete +multibyte character, converts it to a wide character and stores it at +\fI*pwc\fP. It updates an internal shift state only known to the mbtowc +function. If \fIs\fP does not point to a '\\0' byte, it returns the number +of bytes that were consumed from \fIs\fP, otherwise it returns 0. +.PP +If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte +character, or if they contain an invalid multibyte sequence, \fBmbtowc\fP +returns \fI-1\fP. This can happen even if \fIn\fP >= \fIMB_CUR_MAX\fP, +if the multibyte string contains redundant shift sequences. +.PP +A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL. In this +case the \fBmbtowc\fP function behaves as above, excepts that it does not +store the converted wide character in memory. +.PP +A third case is when \fIs\fP is NULL. In this case, \fIpwc\fP and \fIn\fP are +ignored. The \fBmbtowc\fP function +.\" The Dinkumware doc and the Single Unix specification say this, but +.\" glibc doesn't implement this. +resets the shift state, only known to this function, to the initial state, and +returns non-zero if the encoding has non-trivial shift state, or zero if the +encoding is stateless. +.SH "RETURN VALUE" +If \fIs\fP is not NULL, the \fBmbtowc\fP function returns the number of +consumed bytes starting at \fIs\fP, or 0 if \fIs\fP points to a null byte, +or \-1 upon failure. +.PP +If \fIs\fP is NULL, the \fBmbtowc\fP function returns non-zero if the encoding +has non-trivial shift state, or zero if the encoding is stateless. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR MB_CUR_MAX (3), +.BR mbrtowc (3), +.BR mbstowcs (3) +.SH NOTES +The behaviour of \fBmbtowc\fP depends on the LC_CTYPE category of the +current locale. +.PP +This function is not multi-thread safe. The function \fBmbrtowc\fP provides +a better interface to the same functionality. diff --git a/man3/memalign.3 b/man3/memalign.3 new file mode 100644 index 000000000..791d4c801 --- /dev/null +++ b/man3/memalign.3 @@ -0,0 +1 @@ +.so man3/posix_memalign.3 diff --git a/man3/memccpy.3 b/man3/memccpy.3 new file mode 100644 index 000000000..f29e4e2c2 --- /dev/null +++ b/man3/memccpy.3 @@ -0,0 +1,52 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:57:24 1993 by Rik Faith (faith@cs.unc.edu) +.TH MEMCCPY 3 1993-04-10 "GNU" "Linux Programmer's Manual" +.SH NAME +memccpy \- copy memory area +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void *memccpy(void *" dest ", const void *" src ", int " c ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBmemccpy()\fP function copies no more than \fIn\fP bytes from +memory area \fIsrc\fP to memory area \fIdest\fP, stopping when the +character \fIc\fP is found. +.SH "RETURN VALUE" +The \fBmemccpy()\fP function returns a pointer to the next character +in \fIdest\fP after \fIc\fP, or NULL if \fIc\fP was not found in the +first \fIn\fP characters of \fIsrc\fP. +.SH "CONFORMING TO" +SVID 3, BSD 4.3 +.SH "SEE ALSO" +.BR bcopy (3), +.BR memcpy (3), +.BR memmove (3), +.BR strcpy (3), +.BR strncpy (3) diff --git a/man3/memchr.3 b/man3/memchr.3 new file mode 100644 index 000000000..23968005e --- /dev/null +++ b/man3/memchr.3 @@ -0,0 +1,72 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Mon Apr 12 12:49:57 1993, David Metcalfe +.\" Modified Sat Jul 24 18:56:22 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified Wed Feb 20 21:09:36 2002, Ian Redfern (redferni@logica.com) +.\" +.TH MEMCHR 3 2003-11-01 "" "Linux Programmer's Manual" +.SH NAME +memchr, memrchr \- scan memory for a character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void *memchr(const void *" s ", int " c ", size_t " n ); +.sp +.BI "void *memrchr(const void *" s ", int " c ", size_t " n ); +.fi +.SH DESCRIPTION +The +.B memchr() +function scans the first \fIn\fP bytes of the memory +area pointed to by \fIs\fP for the character \fIc\fP. The first byte to +match \fIc\fP (interpreted as an unsigned character) stops the operation. +.PP +The +.B memrchr() +function is like the +.B memchr() +function, +except that it searches backwards from the end of the \fIn\fP bytes +pointed to by \fIs\fP instead of forwards from the front. +.SH "RETURN VALUE" +The \fBmemchr()\fP and \fBmemrchr()\fP functions return a pointer +to the matching byte or NULL if the character does not occur in +the given memory area. +.SH "CONFORMING TO" +The +.B memchr() +function conforms to SVID 3, BSD 4.3, ISO 9899, POSIX. +The +.B memrchr() +function is a GNU extension, available since glibc 2.1.91. +.SH "SEE ALSO" +.BR index (3), +.BR rindex (3), +.BR strchr (3), +.BR strpbrk (3), +.BR strrchr (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR wmemchr (3) diff --git a/man3/memcmp.3 b/man3/memcmp.3 new file mode 100644 index 000000000..d6a968733 --- /dev/null +++ b/man3/memcmp.3 @@ -0,0 +1,56 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:55:27 1993 by Rik Faith (faith@cs.unc.edu) +.TH MEMCMP 3 1993-04-10 "" "Linux Programmer's Manual" +.SH NAME +memcmp \- compare memory areas +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int memcmp(const void *" s1 ", const void *" s2 ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBmemcmp()\fP function compares the first \fIn\fP bytes of the +memory areas \fIs1\fP and \fIs2\fP. It returns an integer less than, +equal to, or greater than zero if \fIs1\fP is found, respectively, to +be less than, to match, or be greater than \fIs2\fP. +.SH "RETURN VALUE" +The \fBmemcmp()\fP function returns an integer less than, equal to, or +greater than zero if the first \fIn\fP bytes of \fIs1\fP is found, +respectively, to be less than, to match, or be greater than the first +\fIn\fP bytes of \fIs2\fP. +.SH "CONFORMING TO" +SVID 3, BSD 4.3, ISO 9899 (C99) +.SH "SEE ALSO" +.BR bcmp (3), +.BR strcasecmp (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strncasecmp (3), +.BR strncmp (3), +.BR wmemcmp (3) diff --git a/man3/memcpy.3 b/man3/memcpy.3 new file mode 100644 index 000000000..098838596 --- /dev/null +++ b/man3/memcpy.3 @@ -0,0 +1,52 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:41:09 1993 by Rik Faith (faith@cs.unc.edu) +.TH MEMCPY 3 1993-04-10 "" "Linux Programmer's Manual" +.SH NAME +memcpy \- copy memory area +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void *memcpy(void *" dest ", const void *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBmemcpy()\fP function copies \fIn\fP bytes from memory area +\fIsrc\fP to memory area \fIdest\fP. The memory areas may not +overlap. Use \fBmemmove\fP(3) if the memory areas do overlap. +.SH "RETURN VALUE" +The \fBmemcpy()\fP function returns a pointer to \fIdest\fP. +.SH "CONFORMING TO" +SVID 3, BSD 4.3, ISO 9899 +.SH "SEE ALSO" +.BR bcopy (3), +.BR memccpy (3), +.BR memmove (3), +.BR mempcpy (3), +.BR strcpy (3), +.BR strncpy (3), +.BR wmemcpy (3) diff --git a/man3/memfrob.3 b/man3/memfrob.3 new file mode 100644 index 000000000..d86434335 --- /dev/null +++ b/man3/memfrob.3 @@ -0,0 +1,52 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:54:45 1993 by Rik Faith (faith@cs.unc.edu) +.TH MEMFROB 3 1993-04-12 "GNU" "Linux Programmer's Manual" +.SH NAME +memfrob \- frobnicate (encrypt) a memory area +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void *memfrob(void *" s ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBmemfrob()\fP function encrypts the first \fIn\fP bytes of the +memory area \fIs\fP by exclusive-ORing each character with the number +42. The effect can be reversed by using \fBmemfrob()\fP on the +encrypted memory area. +.PP +Note that this function is not a proper encryption routine as the XOR +constant is fixed, and is only suitable for hiding strings. +.SH "RETURN VALUE" +The \fBmemfrob()\fP function returns a pointer to the encrypted memory +area. +.SH "CONFORMING TO" +The \fBmemfrob()\fP function is unique to the Linux C Library and +GNU C Library. +.SH "SEE ALSO" +.BR strfry (3) diff --git a/man3/memmem.3 b/man3/memmem.3 new file mode 100644 index 000000000..3cfa2127c --- /dev/null +++ b/man3/memmem.3 @@ -0,0 +1,63 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:50:48 1993 by Rik Faith (faith@cs.unc.edu) +.\" Interchanged `needle' and `haystack'; added history, aeb, 980113. +.TH MEMMEM 3 1998-01-13 "GNU" "Linux Programmer's Manual" +.SH NAME +memmem \- locate a substring +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "void *memmem(const void *" haystack ", size_t " haystacklen , +.in +\w'void *memmem('u +.BI "const void *" needle ", size_t " needlelen ); +.in +.fi +.SH DESCRIPTION +The \fBmemmem()\fP function finds the start of the first occurrence +of the substring \fIneedle\fP of length \fIneedlelen\fP in the memory +area \fIhaystack\fP of length \fIhaystacklen\fP. +.SH "RETURN VALUE" +The \fBmemmem()\fP function returns a pointer to the beginning of the +substring, or NULL if the substring is not found. +.SH "CONFORMING TO" +This function is a GNU extension. +.SH BUGS +This function was broken in Linux libraries up to and including libc 5.0.9; +there the `needle' and `haystack' arguments were interchanged, +and a pointer to the end of the first occurrence of \fIneedle\fP +was returned. Since libc 5.0.9 is still widely used, this is a +dangerous function to use. +.br +Both old and new libc's have the bug that if \fIneedle\fP is empty +\fIhaystack\fP-1 (instead of \fIhaystack\fP) is returned. +And glibc 2.0 makes it worse, and returns a pointer to the +last byte of `haystack'. This is fixed in glibc 2.1. +.SH "SEE ALSO" +.BR strstr (3) diff --git a/man3/memmove.3 b/man3/memmove.3 new file mode 100644 index 000000000..3fd58bab5 --- /dev/null +++ b/man3/memmove.3 @@ -0,0 +1,50 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:49:59 1993 by Rik Faith (faith@cs.unc.edu) +.TH MEMMOVE 3 1993-04-10 "GNU" "Linux Programmer's Manual" +.SH NAME +memmove \- copy memory area +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void *memmove(void *" dest ", const void *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBmemmove()\fP function copies \fIn\fP bytes from memory area +\fIsrc\fP to memory area \fIdest\fP. The memory areas may overlap. +.SH "RETURN VALUE" +The \fBmemmove()\fP function returns a pointer to \fIdest\fP. +.SH "CONFORMING TO" +SVID 3, BSD 4.3, ISO 9899 +.SH "SEE ALSO" +.BR bcopy (3), +.BR memccpy (3), +.BR memcpy (3), +.BR strcpy (3), +.BR strncpy (3), +.BR wmemmove (3) diff --git a/man3/mempcpy.3 b/man3/mempcpy.3 new file mode 100644 index 000000000..b249262f4 --- /dev/null +++ b/man3/mempcpy.3 @@ -0,0 +1,64 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" based on glibc infopages +.\" +.\" aeb, 2003, polished a little +.TH mempcpy 3 2003-11-11 "GNU" "Linux Programmer's Manual" +.SH NAME +mempcpy, wmempcpy \- copy memory area +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "void *mempcpy(void *" dest ", const void *" src ", size_t " n ); +.sp +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "wchar_t *wmempcpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The +.B mempcpy() +function is nearly identical to the +.B memcpy() +function. It copies +.I n +bytes from the object beginning at +.I src +into the object pointed to by +.I dest. +But instead of returning the value of +.I dest +it returns a pointer to the byte following the last written byte. +.PP +This function is useful in situations where a number of objects +shall be copied to consecutive memory positions. +.PP +The +.B wmempcpy() +function is identical but takes wchar_t type arguments and copies +.I n +wide characters. +.SH "RETURN VALUE" +\fIdest\fP + \fIn\fP . +.SH "EXAMPLE" +.nf +void * +combine (void *o1, size_t s1, void *o2, size_t s2) { + void *result = malloc(s1 + s2); + if (result != NULL) + mempcpy(mempcpy(result, o1, s1), o2, s2); + return result; +} +.fi +.SH "CONFIRMING TO" +This function is a GNU extension. +.SH "SEE ALSO" +.BR memccpy (3), +.BR memcpy (3), +.BR memmove (3), +.BR wmemcpy (3) diff --git a/man3/memrchr.3 b/man3/memrchr.3 new file mode 100644 index 000000000..b62c8f10a --- /dev/null +++ b/man3/memrchr.3 @@ -0,0 +1 @@ +.so man3/memchr.3 diff --git a/man3/memset.3 b/man3/memset.3 new file mode 100644 index 000000000..208362024 --- /dev/null +++ b/man3/memset.3 @@ -0,0 +1,48 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:49:23 1993 by Rik Faith (faith@cs.unc.edu) +.TH MEMSET 3 1993-04-11 "GNU" "Linux Programmer's Manual" +.SH NAME +memset \- fill memory with a constant byte +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void *memset(void *" s ", int " c ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBmemset()\fP function fills the first \fIn\fP bytes of the +memory area pointed to by \fIs\fP with the constant byte \fIc\fP. +.SH "RETURN VALUE" +The \fBmemset()\fP function returns a pointer to the memory area +\fIs\fP. +.SH "CONFORMING TO" +SVID 3, BSD 4.3, ISO 9899 +.SH "SEE ALSO" +.BR bzero (3), +.BR swab (3), +.BR wmemset (3) diff --git a/man3/mkdtemp.3 b/man3/mkdtemp.3 new file mode 100644 index 000000000..66505422b --- /dev/null +++ b/man3/mkdtemp.3 @@ -0,0 +1,67 @@ +.\" Copyright 2001 John Levon +.\" Based on mkstemp(3), Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and GNU libc documentation +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.TH MKDTEMP 3 2001-10-07 "GNU" "Linux Programmer's Manual" +.SH NAME +mkdtemp \- create a unique temporary directory +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *mkdtemp(char *" template ); +.fi +.SH DESCRIPTION +The \fBmkdtemp()\fP function generates a uniquely-named temporary +directory from \fItemplate\fP. The last six characters of \fItemplate\fP +must be XXXXXX and these are replaced with a string that makes the +.\" FIXME: were the permissions 0700 in all glibc versions ? +directory name unique. The directory is then created with +permissions 0700. +Since it will be modified, +.I template +must not be a string constant, but should be declared as a character array. +.SH "RETURN VALUE" +The \fBmkdtemp()\fP function returns a pointer to the modified template +string on success, and \fBNULL\fP on failure, in which case +.IR errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +The last six characters of \fItemplate\fP were not XXXXXX. +Now \fItemplate\fP is unchanged. + +.TP +Also see \fBmkdir(2)\fP for other possible values for \fIerrno\fP. + +.SH "CONFORMING TO" +Introduced in OpenBSD 2.2. +.\" Also in NetBSD 1.4. +Available since glibc 2.1.91. +.SH "SEE ALSO" +.BR mkdir (2), +.BR mkstemp (3), +.BR mktemp (3), +.BR tempnam (3), +.BR tmpfile (3), +.BR tmpnam (3) diff --git a/man3/mkfifo.3 b/man3/mkfifo.3 new file mode 100644 index 000000000..d646fc6e7 --- /dev/null +++ b/man3/mkfifo.3 @@ -0,0 +1,99 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1995 James R. Van Zandt +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" changed section from 2 to 3, aeb, 950919 +.\" +.TH MKFIFO 3 1995-09-03 "Linux 1.2.13" "Linux Programmer's Manual" +.SH NAME +mkfifo \- make a FIFO special file (a named pipe) +.SH SYNOPSIS +.nf +.B #include +.B #include +.sp +.BI "int mkfifo(const char *" pathname ", mode_t " mode ); +.fi +.SH DESCRIPTION +\fBmkfifo\fP makes a FIFO special file with name \fIpathname\fP. +\fImode\fP specifies the FIFO's permissions. It is modified by the +process's \fBumask\fP in the usual way: the permissions of the created +file are \fB(\fP\fImode\fP\fB & ~umask)\fP. +.PP +A FIFO special file is similar to a pipe, except that it is created +in a different way. Instead of being an anonymous communications +channel, a FIFO special file is entered into the file system by +calling \fBmkfifo\fP. +.PP +Once you have created a FIFO special file in this way, any process can +open it for reading or writing, in the same way as an ordinary file. +However, it has to be open at both ends simultaneously before you can +proceed to do any input or output operations on it. Opening a FIFO +for reading normally blocks until some other process opens the same +FIFO for writing, and vice versa. See +.BR fifo (4) +for non-blocking handling of FIFO special files. +.SH "RETURN VALUE" +The normal, successful return value from \fImkfifo\fP is \fB0\fP. In +the case of an error, \fB-1\fP is returned (in which case, \fIerrno\fP +is set appropriately). +.SH ERRORS +.TP +.B EACCES +One of the directories in \fIpathname\fP did not allow search +(execute) permission. +.TP +.B EEXIST +\fIpathname\fP already exists. +.TP +.B ENAMETOOLONG +Either the total length of \fIpathname\fP is greater than +\fBPATH_MAX\fP, or an individual file name component has a length +greater than \fBNAME_MAX\fP. In the GNU system, there is no imposed +limit on overall file name length, but some file systems may place +limits on the length of a component. +.TP +.B ENOENT +A directory component in \fIpathname\fP does not exist or is a +dangling symbolic link. +.TP +.B ENOSPC +The directory or filesystem has no room for the new file. +.TP +.B ENOTDIR +A component used as a directory in \fIpathname\fP is not, in fact, a +directory. +.TP +.B EROFS +\fIpathname\fP refers to a read-only filesystem. +.SH "CONFORMING TO" +POSIX.1 +.SH "SEE ALSO" +.BR mkfifo (1), +.BR close (2), +.BR open (2), +.BR read (2), +.BR stat (2), +.BR umask (2), +.BR write (2), +.BR fifo (4) diff --git a/man3/mkstemp.3 b/man3/mkstemp.3 new file mode 100644 index 000000000..e4a5b8de8 --- /dev/null +++ b/man3/mkstemp.3 @@ -0,0 +1,86 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:48:48 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 980310, aeb +.\" Modified 990328, aeb +.\" +.TH MKSTEMP 3 2001-12-23 "GNU" "Linux Programmer's Manual" +.SH NAME +mkstemp \- create a unique temporary file +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int mkstemp(char *" template ); +.fi +.SH DESCRIPTION +The \fBmkstemp()\fP function generates a unique temporary file name +from \fItemplate\fP. The last six characters of \fItemplate\fP must +be XXXXXX and these are replaced with a string that makes the +filename unique. The file is then created with mode read/write and +permissions 0666 (glibc 2.0.6 and earlier), 0600 (glibc 2.0.7 and later). +Since it will be modified, +.I template +must not be a string constant, but should be declared as a character array. +The file is opened with the O_EXCL flag, guaranteeing that when +.B mkstemp +returns successfully we are the only user. +.SH "RETURN VALUE" +The \fBmkstemp()\fP function returns the file descriptor fd of the +temporary file or \-1 on error. +.SH ERRORS +.TP +.B EEXIST +Could not create a unique temporary filename. +Now the contents of \fItemplate\fP are undefined. +.TP +.B EINVAL +The last six characters of \fItemplate\fP were not XXXXXX. +Now \fItemplate\fP is unchanged. +.SH NOTES +The old behaviour (creating a file with mode 0666) may be +a security risk, especially since other Unix flavours use 0600, +and somebody might overlook this detail when porting programs. + +More generally, the POSIX specification does not say anything +about file modes, so the application should make sure its umask +is set appropriately before calling +.BR mkstemp . +.SH "CONFORMING TO" +BSD 4.3, POSIX 1003.1-2001 +.SH NOTE +The prototype is in +.I +for libc4, libc5, glibc1; glibc2 follows the Single Unix Specification +and has the prototype in +.IR . +.SH "SEE ALSO" +.BR mkdtemp (3), +.BR mktemp (3), +.BR tempnam (3), +.BR tmpfile (3), +.BR tmpnam (3) diff --git a/man3/mktemp.3 b/man3/mktemp.3 new file mode 100644 index 000000000..4f04ba1dc --- /dev/null +++ b/man3/mktemp.3 @@ -0,0 +1,82 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:48:06 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Jun 23 01:26:34 1995 by Andries Brouwer (aeb@cwi.nl) +.\" (prompted by Scott Burkett ) +.\" Modified Sun Mar 28 23:44:38 1999 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH MKTEMP 3 1993-04-03 "GNU" "Linux Programmer's Manual" +.SH NAME +mktemp \- make a unique temporary file name +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *mktemp(char *" template ); +.fi +.SH DESCRIPTION +The \fBmktemp()\fP function generates a unique temporary file name +from \fItemplate\fP. The last six characters of \fItemplate\fP must +be XXXXXX and these are replaced with a string that makes the +filename unique. Since it will be modified, +.I template +must not be a string constant, but should be declared as a character array. +.SH "RETURN VALUE" +The \fBmktemp()\fP function returns NULL on error (\fItemplate\fP did not +end in XXXXXX) and \fItemplate\fP otherwise. +If the call was successful, the last six bytes of \fItemplate\fP will +have been modified in such a way that the resulting name is unique +(does not exist already). If the call was unsuccessful, \fItemplate\fP +is made an empty string. + +.SH ERRORS +.TP +.B EINVAL +The last six characters of \fItemplate\fP were not XXXXXX. +.SH "CONFORMING TO" +BSD 4.3. POSIX dictates +.BR tmpnam (3). +.SH NOTE +The prototype is in +.I +for libc4, libc5, glibc1; glibc2 follows the Single Unix Specification +and has the prototype in +.IR . +.SH BUGS +Never use \fBmktemp()\fP. Some implementations follow BSD 4.3 +and replace XXXXXX by the current process id and a single letter, +so that at most 26 different names can be returned. +Since on the one hand the names are easy to guess, and on the other +hand there is a race between testing whether the name exists and +opening the file, every use of \fBmktemp()\fP is a security risk. +The race is avoided by +.BR mkstemp (3). +.SH "SEE ALSO" +.BR mkstemp (3), +.BR tempnam (3), +.BR tmpfile (3), +.BR tmpnam (3) diff --git a/man3/mktime.3 b/man3/mktime.3 new file mode 100644 index 000000000..84a3baa92 --- /dev/null +++ b/man3/mktime.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man3/modf.3 b/man3/modf.3 new file mode 100644 index 000000000..f94acf54c --- /dev/null +++ b/man3/modf.3 @@ -0,0 +1,58 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH MODF 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +modf, modff, modfl \- extract signed integral and fractional values from floating-point +number +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double modf(double " x ", double *" iptr ); +.sp +.BI "float modff(float " x ", float *" iptr ); +.sp +.BI "long double modfl(long double " x ", long double *" iptr ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBmodf()\fP function breaks the argument \fIx\fP into an integral +part and a fractional part, each of which has the same sign as \fIx\fP. +The integral part is stored in \fIiptr\fP. +.SH "RETURN VALUE" +The \fBmodf()\fP function returns the fractional part of \fIx\fP. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR frexp (3), +.BR ldexp (3) diff --git a/man3/modff.3 b/man3/modff.3 new file mode 100644 index 000000000..84af2e33e --- /dev/null +++ b/man3/modff.3 @@ -0,0 +1 @@ +.so man3/modf.3 diff --git a/man3/modfl.3 b/man3/modfl.3 new file mode 100644 index 000000000..84af2e33e --- /dev/null +++ b/man3/modfl.3 @@ -0,0 +1 @@ +.so man3/modf.3 diff --git a/man3/mpool.3 b/man3/mpool.3 new file mode 100644 index 000000000..c081872a6 --- /dev/null +++ b/man3/mpool.3 @@ -0,0 +1,219 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mpool.3 8.1 (Berkeley) 6/4/93 +.\" +.TH MPOOL 3 1993-06-04 +.UC 7 +.SH NAME +mpool \- shared memory buffer pool +.SH SYNOPSIS +.nf +.ft B +#include +#include + +MPOOL * +mpool_open (DBT *key, int fd, pgno_t pagesize, pgno_t maxcache); + +void +mpool_filter (MPOOL *mp, void (*pgin)(void *, pgno_t, void *), +.ti +5 +void (*pgout)(void *, pgno_t, void *), void *pgcookie); + +void * +mpool_new (MPOOL *mp, pgno_t *pgnoaddr); + +void * +mpool_get (MPOOL *mp, pgno_t pgno, u_int flags); + +int +mpool_put (MPOOL *mp, void *pgaddr, u_int flags); + +int +mpool_sync (MPOOL *mp); + +int +mpool_close (MPOOL *mp); +.ft R +.fi +.SH DESCRIPTION +.IR Mpool +is the library interface intended to provide page oriented buffer management +of files. +The buffers may be shared between processes. +.PP +The function +.I mpool_open +initializes a memory pool. +The +.I key +argument is the byte string used to negotiate between multiple +processes wishing to share buffers. +If the file buffers are mapped in shared memory, all processes using +the same key will share the buffers. +If +.I key +is NULL, the buffers are mapped into private memory. +The +.I fd +argument is a file descriptor for the underlying file, which must be seekable. +If +.I key +is non-NULL and matches a file already being mapped, the +.I fd +argument is ignored. +.PP +The +.I pagesize +argument is the size, in bytes, of the pages into which the file is broken up. +The +.I maxcache +argument is the maximum number of pages from the underlying file to cache +at any one time. +This value is not relative to the number of processes which share a file's +buffers, but will be the largest value specified by any of the processes +sharing the file. +.PP +The +.I mpool_filter +function is intended to make transparent input and output processing of the +pages possible. +If the +.I pgin +function is specified, it is called each time a buffer is read into the memory +pool from the backing file. +If the +.I pgout +function is specified, it is called each time a buffer is written into the +backing file. +Both functions are are called with the +.I pgcookie +pointer, the page number and a pointer to the page to being read or written. +.PP +The function +.I mpool_new +takes an MPOOL pointer and an address as arguments. +If a new page can be allocated, a pointer to the page is returned and +the page number is stored into the +.I pgnoaddr +address. +Otherwise, NULL is returned and errno is set. +.PP +The function +.I mpool_get +takes a MPOOL pointer and a page number as arguments. +If the page exists, a pointer to the page is returned. +Otherwise, NULL is returned and errno is set. +The flags parameter is not currently used. +.PP +The function +.I mpool_put +unpins the page referenced by +.IR pgaddr . +.I Pgaddr +must be an address previously returned by +.I mpool_get +or +.IR mpool_new . +The flag value is specified by +.IR or 'ing +any of the following values: +.TP +MPOOL_DIRTY +The page has been modified and needs to be written to the backing file. +.PP +.I Mpool_put +returns 0 on success and \-1 if an error occurs. +.PP +The function +.I mpool_sync +writes all modified pages associated with the MPOOL pointer to the +backing file. +.I Mpool_sync +returns 0 on success and \-1 if an error occurs. +.PP +The +.I mpool_close +function free's up any allocated memory associated with the memory pool +cookie. +Modified pages are +.B not +written to the backing file. +.I Mpool_close +returns 0 on success and \-1 if an error occurs. +.SH ERRORS +The +.I mpool_open +function may fail and set +.I errno +for any of the errors specified for the library routine +.IR malloc (3). +.PP +The +.I mpool_get +function may fail and set +.I errno +for the following: +.TP 15 +[EINVAL] +The requested record doesn't exist. +.PP +The +.I mpool_new +and +.I mpool_get +functions may fail and set +.I errno +for any of the errors specified for the library routines +.IR read (2) , +.IR write (2) , +and +.IR malloc (3). +.PP +The +.I mpool_sync +function may fail and set +.I errno +for any of the errors specified for the library routine +.IR write (2). +.PP +The +.I mpool_close +function may fail and set +.I errno +for any of the errors specified for the library routine +.IR free (3). +.SH "SEE ALSO" +.IR dbopen (3), +.IR btree (3), +.IR hash (3), +.IR recno (3) diff --git a/man3/mrand48.3 b/man3/mrand48.3 new file mode 100644 index 000000000..3133f7d62 --- /dev/null +++ b/man3/mrand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man3/mrand48_r.3 b/man3/mrand48_r.3 new file mode 100644 index 000000000..81e9d8ef7 --- /dev/null +++ b/man3/mrand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man3/mtrace.3 b/man3/mtrace.3 new file mode 100644 index 000000000..ab9e23bf1 --- /dev/null +++ b/man3/mtrace.3 @@ -0,0 +1,44 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" the glibc-info pages are very helpful here +.TH MTRACE 3 2002-07-20 "GNU" "Linux Programmer's Manual" +.SH NAME +mtrace, muntrace \- malloc debugging +.SH SYNOPSIS +.sp +.B "#include " +.sp +.B "void mtrace(void);" +.sp +.B "void muntrace(void);" +.SH DESCRIPTION +The function +.BR mtrace () +installs handlers for +.IR malloc (), +.IR realloc () +and +.IR free (). +The function +.BR muntrace () +disables these handlers. +.br +The environment variable +.B MALLOC_TRACE +defines a file where +.BR mtrace () +writes its output. +This file must be writable to the user or +.BR mtrace () +will do nothing. +If the file is not empty it will be truncated. +.SH NOTE +The output of +.BR mtrace () +will be ASCII but not in a friendly format. +So glibc comes with a perl-script called mtrace to make sense of it. +.SH "CONFORMS TO" +These are GNU extensions. +.SH "SEE ALSO" +.BR malloc (3), +.BR malloc_hook (3) diff --git a/man3/muntrace.3 b/man3/muntrace.3 new file mode 100644 index 000000000..2b03d1071 --- /dev/null +++ b/man3/muntrace.3 @@ -0,0 +1 @@ +.so man3/mtrace.3 diff --git a/man3/nan.3 b/man3/nan.3 new file mode 100644 index 000000000..885dd13ea --- /dev/null +++ b/man3/nan.3 @@ -0,0 +1,49 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" Based on glibc infopages +.\" +.\" Corrections by aeb +.TH NAN 3 2002-08-10 "GNU" "libc math functions" +.SH NAME +nan, nanf, nanl \- return 'Not a Number' +.SH SYNOPSIS +.B #include +.sp +.BI "double nan(const char *" tagp ); +.sp +.BI "float nanf(const char *" tagp ); +.sp +.BI "long double nanl(const char *" tagp ); +.sp +Link with \-lm. +.SH DESCRIPTION +These functions return a representation (determined by +.IR tagp ) +of a quiet NaN. If the implementation does not support +quiet NaNs, these functions return zero. +.LP +The call +.I nan("char-sequence") +is equivalent to +.I strtod ("NAN(char-sequence)",NULL) +and similarly calls to +.I nanf +and +.I nanl +are equivalent to analogous calls to +.I strtof +and +.IR strtold . +.PP +The argument +.I tagp +is used in an unspecified manner. On IEEE 754 systems, there are +many representations of NaN, and +.I tagp +selects one. On other systems it may do nothing. +.SH "CONFORMING TO" +C99. See also IEC 559 and the appendix with +recommended functions in IEEE 754/IEEE 854. +.SH "SEE ALSO" +.BR isnan (3), +.BR strtod (3) diff --git a/man3/nanf.3 b/man3/nanf.3 new file mode 100644 index 000000000..08e9aa7c6 --- /dev/null +++ b/man3/nanf.3 @@ -0,0 +1 @@ +.so man3/nan.3 diff --git a/man3/nanl.3 b/man3/nanl.3 new file mode 100644 index 000000000..08e9aa7c6 --- /dev/null +++ b/man3/nanl.3 @@ -0,0 +1 @@ +.so man3/nan.3 diff --git a/man3/nearbyint.3 b/man3/nearbyint.3 new file mode 100644 index 000000000..3300c2c40 --- /dev/null +++ b/man3/nearbyint.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man3/nearbyintf.3 b/man3/nearbyintf.3 new file mode 100644 index 000000000..3300c2c40 --- /dev/null +++ b/man3/nearbyintf.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man3/nearbyintl.3 b/man3/nearbyintl.3 new file mode 100644 index 000000000..3300c2c40 --- /dev/null +++ b/man3/nearbyintl.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man3/netlink.3 b/man3/netlink.3 new file mode 100644 index 000000000..5d7526c50 --- /dev/null +++ b/man3/netlink.3 @@ -0,0 +1,80 @@ +.\" This manpage copyright 1998 by Andi Kleen. Subject to the GPL. +.\" Based on the original comments from Alexey Kuznetsov +.\" $Id: netlink.3,v 1.1 1999/05/14 17:17:24 freitag Exp $ +.TH NETLINK 3 1999-05-14 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +netlink \- Netlink macros +.SH SYNOPSIS +.nf +.\" XXX what will glibc 2.1 use here? +.B #include +.br +.B #include +.br +.BI "int NLMSG_ALIGN(size_t " len ); +.br +.BI "int NLMSG_LENGTH(size_t " len ); +.br +.BI "int NLMSG_SPACE(size_t " len ); +.br +.BI "void *NLMSG_DATA(struct nlmsghdr *" nlh ); +.br +.BI "struct nlmsghdr *NLMSG_NEXT(struct nlmsghdr *" nlh ", int " len ); +.br +.BI "int NLMSG_OK(struct nlmsghdr *" nlh ", int " len ); +.br +.BI "int NLMSG_PAYLOAD(struct nlmsghdr *" nlh ", int " len ); +.fi +.SH DESCRIPTION +.I netlink.h +defines several standard macros to access or create a netlink datagram. +They are similar in spirit to the macros defined in +.BR cmsg (3) +for auxiliary data. The buffer passed to and from a netlink socket should +be only accessed using these macros. +.TP +.TP +NLMSG_ALIGN +Round the length of a netlink message up to align it properly. +.TP +NLMSG_LENGTH +Gets the payload length as argument and returns the aligned length to store +in the +.B nlmsg_len +field of the +.IR nlmsghdr . + +.TP +NLMSG_SPACE +Return the number of bytes a netlink message with payload of the passed length +would occupy. +.TP +NLMSG_DATA +Return a pointer to the payload associated with the passed +.IR nlmsghdr . +.TP +.\" XXX this is bizarre, maybe the interface should be fixed. +NLMSG_NEXT +Get the next +.I nlmsghdr +in a multipart message. The caller must check if the current nlmsghdr +didn't have the NLMSG_DONE set - this function doesn't return NULL on end. The +length parameter is an lvalue containing the remaining length of the message +buffer. This macro decrements it by the length of the message header. +.TP +NLMSG_OK +Return true if the netlink message is not truncated and ok to parse. +.TP +NLMSG_PAYLOAD +Return the length of the payload associated with the +.IR nlmsghdr . + +.SH NOTES +It is often better to use netlink via +.B libnetlink +than via the low level kernel interface. + +.SH "SEE ALSO" +.BR netlink (7) +.PP +and ftp://ftp.inr.ac.ru/ip-routing/iproute2* for libnetlink diff --git a/man3/nextafter.3 b/man3/nextafter.3 new file mode 100644 index 000000000..40baea4ec --- /dev/null +++ b/man3/nextafter.3 @@ -0,0 +1,50 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" Based on glibc infopages +.TH NEXTAFTER 3 2002-08-10 "GNU" "libc math functions" +.SH NAME +nextafter, nextafterf, nextafterl, nexttoward, nexttowardf, nexttowardl \- floating point number manipulation +.SH SYNOPSIS +.B #include +.sp +.BI "double nextafter(double " x ", double " y ); +.br +.BI "float nextafterf(float " x ", float " y ); +.br +.BI "long double nextafterl(long double " x ", long double " y ); +.sp +.BI "double nexttoward(double " x ", long double " y ); +.br +.BI "float nexttowardf(float " x ", long double " y ); +.br +.BI "long double nexttowardl(long double " x ", long double " y ); +.sp +Link with \-lm. +.SH DESCRIPTION +The +.B nextafter() +functions return the next representable neighbor of +\fIx\fP in the direction towards \fIy\fP. The size of the step +between \fIx\fP and the result depends on the type of the result. +If \fIx\fP = \fIy\fP the function simply returns \fIy\fP. +If either value is +.IR NaN , +then +.I NaN +is returned. Otherwise a value corresponding to the value of the +least significant bit in the mantissa is added or subtracted, +depending on the direction. +.PP +The +.B nexttoward() +functions do the same as the +.B nextafter() +functions, except that they have a long double second argument. +.PP +These functions will signal overflow or underflow if the result +goes outside of the range of normalized numbers. +.SH "CONFORMING TO" +C99. This function is defined in IEC 559 (and the appendix with +recommended functions in IEEE 754/IEEE 854). +.SH "SEE ALSO" +.BR nearbyint (3) diff --git a/man3/nextafterf.3 b/man3/nextafterf.3 new file mode 100644 index 000000000..531e48f47 --- /dev/null +++ b/man3/nextafterf.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man3/nextafterl.3 b/man3/nextafterl.3 new file mode 100644 index 000000000..531e48f47 --- /dev/null +++ b/man3/nextafterl.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man3/nexttoward.3 b/man3/nexttoward.3 new file mode 100644 index 000000000..531e48f47 --- /dev/null +++ b/man3/nexttoward.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man3/nexttowardf.3 b/man3/nexttowardf.3 new file mode 100644 index 000000000..531e48f47 --- /dev/null +++ b/man3/nexttowardf.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man3/nexttowardl.3 b/man3/nexttowardl.3 new file mode 100644 index 000000000..531e48f47 --- /dev/null +++ b/man3/nexttowardl.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man3/nftw.3 b/man3/nftw.3 new file mode 100644 index 000000000..1a5c9c928 --- /dev/null +++ b/man3/nftw.3 @@ -0,0 +1 @@ +.so man3/ftw.3 diff --git a/man3/nl_langinfo.3 b/man3/nl_langinfo.3 new file mode 100644 index 000000000..2fa25baf2 --- /dev/null +++ b/man3/nl_langinfo.3 @@ -0,0 +1,124 @@ +.\" Copyright (c) 2001 Markus Kuhn +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 manual +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.\" Corrected prototype, 2002-10-18, aeb +.\" +.TH NL_LANGINFO 3 2001-05-11 "GNU" "Linux Programmer's Manual" +.SH NAME +nl_langinfo \- query language and locale information +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *nl_langinfo(nl_item " item ); +.fi +.SH DESCRIPTION +The \fBnl_langinfo\fP function provides access to locale information +in a more flexible way than +.BR localeconv (3) +does. Individual and additional elements of the locale categories can +be queried. +.PP +Examples for the locale elements that can be specified in \fIitem\fP +using the constants defined in are: + +.TP +.BR CODESET \ (LC_CTYPE) +Return a string with the name of the character encoding used in the +selected locale, such as "UTF-8", "ISO-8859-1", or "ANSI_X3.4-1968" +(better known as US-ASCII). This is the same string that you get with +"locale charmap". For a list of character encoding names, +try "locale \-m", cf.\& +.BR locale (1). + +.TP +.BR D_T_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent time and date in a locale-specific way. + +.TP +.BR D_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent a date in a locale-specific way. + +.TP +.BR T_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent a time in a locale-specific way. + +.TP +.BR DAY_ "{1\(en7} (LC_TIME)" +Return name of the \fIn\fP-th day of the week. [Warning: this follows +the US convention DAY_1 = Sunday, not the international convention +(ISO 8601) that Monday is the first day of the week.] + +.TP +.BR ABDAY_ "{1\(en7} (LC_TIME)" +Return abbreviated name of the \fIn\fP-th day of the week. + +.TP +.BR MON_ "{1\(en12} (LC_TIME)" +Return name of the \fIn\fP-th month. + +.TP +.BR ABMON_ "{1\(en12} (LC_TIME)" +Return abbreviated name of the \fIn\fP-th month. + +.TP +.BR RADIXCHAR \ (LC_NUMERIC) +Return radix character (decimal dot, decimal comma, etc.). + +.TP +.BR THOUSEP \ (LC_NUMERIC) +Return separator character for thousands (groups of three digits). + +.TP +.BR YESEXPR \ (LC_MESSAGES) +Return a regular expression that can be used with the +.BR regex (3) +function to recognize a positive response to a yes/no question. + +.TP +.BR NOEXPR \ (LC_MESSAGES) +Return a regular expression that can be used with the +.BR regex (3) +function to recognize a negative response to a yes/no question. + +.TP +.BR CRNCYSTR \ (LC_MONETARY) +Return the currency symbol, preceded by "\-" if the symbol should +appear before the value, "+" if the symbol should appear after the +value, or "." if the symbol should replace the radix character. +.PP +The above list covers just some examples of items that can be +requested. For a more detailed list, please consult +.IR "The GNU C Library Reference Manual" . +.SH "RETURN VALUE" +If no locale has been selected for the appropriate category, +\fBnl_langinfo\fP returns a pointer to the corresponding string in the +"C" locale. +.PP +If \fIitem\fP is not valid, a pointer to an empty string is returned. +.PP +This pointer may point to static data that may be overwritten on the +next call to \fBnl_langinfo\fP or \fBsetlocale\fP. +.SH "CONFORMING TO" +The Single UNIX\*R Specification, Version 2 +.SH "SEE ALSO" +.BR locale (1), +.BR localeconv (3), +.BR setlocale (3), +.BR charsets (7), +.BR locale (7) +The GNU C Library Reference Manual diff --git a/man3/nrand48.3 b/man3/nrand48.3 new file mode 100644 index 000000000..3133f7d62 --- /dev/null +++ b/man3/nrand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man3/nrand48_r.3 b/man3/nrand48_r.3 new file mode 100644 index 000000000..81e9d8ef7 --- /dev/null +++ b/man3/nrand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man3/ntohl.3 b/man3/ntohl.3 new file mode 100644 index 000000000..ba374e841 --- /dev/null +++ b/man3/ntohl.3 @@ -0,0 +1 @@ +.so man3/byteorder.3 diff --git a/man3/ntohs.3 b/man3/ntohs.3 new file mode 100644 index 000000000..ba374e841 --- /dev/null +++ b/man3/ntohs.3 @@ -0,0 +1 @@ +.so man3/byteorder.3 diff --git a/man3/on_exit.3 b/man3/on_exit.3 new file mode 100644 index 000000000..6ebd75d01 --- /dev/null +++ b/man3/on_exit.3 @@ -0,0 +1,58 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-04-02, David Metcalfe +.\" Modified 1993-07-25, Rik Faith (faith@cs.unc.edu) +.TH ON_EXIT 3 1993-04-02 "GNU" "Linux Programmer's Manual" +.SH NAME +on_exit \- register a function to be called at normal program termination +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int on_exit(void (*" function ")(int , void *), void *" arg ); +.fi +.SH DESCRIPTION +The \fBon_exit()\fP function registers the given \fIfunction\fP to be +called at normal program termination, whether via +.BR exit (3) +or via return from the program's \fBmain\fP. +The \fIfunction\fP is passed the argument to +.BR exit (3) +and the \fIarg\fP argument from \fBon_exit()\fP. +.SH "RETURN VALUE" +The \fBon_exit()\fP function returns the value 0 if successful; otherwise +it returns a non-zero value. +.SH "CONFORMING TO" +This function comes from SunOS 4, but is also present in +libc4, libc5 and glibc. It no longer occurs in Solaris (SunOS 5). +Avoid this function, and use the standard +.BR atexit (3) +instead. +.SH "SEE ALSO" +.BR _exit (3), +.BR atexit (3), +.BR exit (3) diff --git a/man3/opendir.3 b/man3/opendir.3 new file mode 100644 index 000000000..c67782706 --- /dev/null +++ b/man3/opendir.3 @@ -0,0 +1,79 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:46:01 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.TH OPENDIR 3 1995-06-11 "" "Linux Programmer's Manual" +.SH NAME +opendir \- open a directory +.SH SYNOPSIS +.nf +.B #include +.br +.B #include +.sp +.BI "DIR *opendir(const char *" name ); +.fi +.SH DESCRIPTION +The \fBopendir()\fP function opens a directory stream corresponding to the +directory \fIname\fP, and returns a pointer to the directory stream. The +stream is positioned at the first entry in the directory. +.SH "RETURN VALUE" +The \fBopendir()\fP function returns a pointer to the directory stream or +NULL if an error occurred. +.SH ERRORS +.TP +.B EACCES +Permission denied. +.TP +.B EMFILE +Too many file descriptors in use by process. +.TP +.B ENFILE +Too many files are currently open in the system. +.TP +.B ENOENT +Directory does not exist, or \fIname\fP is an empty string. +.TP +.B ENOMEM +Insufficient memory to complete the operation. +.TP +.B ENOTDIR +\fIname\fP is not a directory. +.SH NOTES +The underlying file descriptor of the directory stream can be obtained using +.BR dirfd (3). +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3 +.SH "SEE ALSO" +.BR open (2), +.BR closedir (3), +.BR dirfd (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) diff --git a/man3/openlog.3 b/man3/openlog.3 new file mode 100644 index 000000000..ec352b291 --- /dev/null +++ b/man3/openlog.3 @@ -0,0 +1 @@ +.so man3/syslog.3 diff --git a/man3/openpty.3 b/man3/openpty.3 new file mode 100644 index 000000000..65abed969 --- /dev/null +++ b/man3/openpty.3 @@ -0,0 +1,160 @@ +.\" Copyright (c) OpenBSD Group +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Converted into a manpage again by Martin Schulze +.\" +.\" Added -lutil remark, 030718 +.\" +.TH OPENPTY 3 "2003-07-18" "BSD" "Linux Programmer's Manual" +.SH NAME +openpty, login_tty, forkpty \- tty utility functions +.SH SYNOPSIS +.B #include +\ /* for openpty and forkpty */ +.br +.B #include +/* for login_tty */ +.sp +.BI "int openpty(int *" amaster ", int *" aslave ", char *" name ", struct termios *" termp ", struct winsize * " winp ); +.sp +.BI "int login_tty(int " fd ); +.sp +.BI "pid_t forkpty(int *" amaster ", char *" name ", struct termios *" termp ", struct winsize *" winp ); +.sp +Link with -lutil. +.SH DESCRIPTION +The +.B openpty() +function finds an available pseudo-tty and returns file descriptors +for the master and slave in +.I amaster +and +.IR aslave . +If +.I name +is not NULL, the filename of the slave is returned in +.IR name . +If +.I termp +is not NULL, the terminal parameters of the slave will be set to the +values in +.IR termp . +If +.I winp +is not NULL, the window size of the slave will be set to the values in +.IR winp . + +The +.B login_tty() +function prepares for a login on the tty +.I fd +(which may be a real tty device, or the slave of a pseudo-tty as +returned by +.BR openpty() ) +by creating a new session, making +.I fd +the controlling terminal for the current process, setting +.I fd +to be the standard input, output, and error streams of the current +process, and closing +.IR fd . + +The +.B forkpty() +function combines +.BR openpty() , +.BR fork() , +and +.B login_tty() +to create a new process operating in a pseudo-tty. The file +descriptor of the master side of the pseudo-tty is returned in +.IR amaster , +and the filename of the slave in +.I name +if it is not NULL. The +.I termp +and +.I winp +parameters, if not NULL, +will determine the terminal attributes and window size of the slave +side of the pseudo-tty. +.SH "RETURN VALUES" +If a call to +.BR openpty() , +.BR login_tty() , +or +.B forkpty() +is not successful, -1 is returned and +.I errno +is set to indicate the error. Otherwise, +.BR openpty() , +.BR login_tty() , +and the child process of +.B forkpty() +return 0, and the parent process of +.B forkpty() +returns the process ID of the child process. +.SH ERRORS +.B openpty() +will fail if: +.TP +.B ENOENT +There are no available ttys. +.LP +.B login_pty() +will fail if +.B ioctl() +fails to set +.I fd +to the controlling terminal of the current process. +.LP +.B forkpty() +will fail if either +.B openpty() +or +.B fork() +fails. +.SH NOTE +These functions are included in libutil, hence you'll need to add +.B \-lutil +to your compiler commandline. +.SH FILES +.I /dev/[pt]ty[pqrstuwxyzabcdePQRST][0123456789abcdef] +.SH "CONFORMING TO" +These are BSD functions, present in libc5 and glibc2. +.SH BUGS +Nobody knows how much space should be reserved for +.IR name . +So, calling +.B openpty() +or +.B forkpty() +with non-NULL +.I name +may not be secure. +.SH "SEE ALSO" +.BR fork (2) diff --git a/man3/passwd2des.3 b/man3/passwd2des.3 new file mode 100644 index 000000000..01b6ce65a --- /dev/null +++ b/man3/passwd2des.3 @@ -0,0 +1 @@ +.so man3/xcrypt.3 diff --git a/man3/pathconf.3 b/man3/pathconf.3 new file mode 100644 index 000000000..46d8c8b17 --- /dev/null +++ b/man3/pathconf.3 @@ -0,0 +1 @@ +.so man3/fpathconf.3 diff --git a/man3/pclose.3 b/man3/pclose.3 new file mode 100644 index 000000000..663d4a081 --- /dev/null +++ b/man3/pclose.3 @@ -0,0 +1 @@ +.so man3/popen.3 diff --git a/man3/perror.3 b/man3/perror.3 new file mode 100644 index 000000000..ef8740aac --- /dev/null +++ b/man3/perror.3 @@ -0,0 +1,125 @@ +.\" Copyright (c) 1994 Michael Haardt (michael@moria.de), 1994-06-04 +.\" Copyright (c) 1995 Michael Haardt +.\" (michael@cantor.informatik.rwth-aachen.de), 1995-03-16 +.\" Copyright (c) 1996 Andries Brouwer (aeb@cwi.nl), 1996-01-13 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 1996-01-13 aeb: merged in some text contributed by Melvin Smith +.\" (msmith@falcon.mercer.peachnet.edu) and various other changes. +.\" Modified 1996-05-16 by Martin Schulze (joey@infodrom.north.de) +.\" +.TH PERROR 3 2001-12-14 "" "Library functions" +.SH NAME +perror \- print a system error message +.SH SYNOPSIS +.B #include +.sp +.BI "void perror(const char " *s ); +.sp +.B #include +.sp +.BI "const char *" sys_errlist []; +.br +.BI "int " sys_nerr ; +.br +.BI "int " errno ; +.SH DESCRIPTION +The routine +.B perror() +produces a message on the standard error output, describing the last +error encountered during a call to a system or library function. +First (if +.I s +is not NULL and +.RI * s +is not NUL) the argument string +.I s +is printed, followed by a colon and a blank. +Then the message and a new-line. + +To be of most use, the argument string should include the name +of the function that incurred the error. The error number is taken from +the external variable +.IR errno , +which is set when errors occur but not +cleared when non-erroneous calls are made. + +The global error list +.IR sys_errlist "[]" +indexed by +.I errno +can be used to obtain the error message without the newline. +The largest message number provided in the table is +.IR sys_nerr " \-1." +Be careful when directly accessing this list because new error values +may not have been added to +.IR sys_errlist "[]." + +When a system call fails, it usually returns \-1 and sets the +variable +.I errno +to a value describing what went wrong. (These values can be found in +.IR "" .) +Many library functions do likewise. +The function +.B perror() +serves to translate this error code into human-readable form. +Note that +.I errno +is undefined after a successful library call: +this call may well change this variable, even though it succeeds, +for example because it internally used some other library function that failed. +Thus, if a failing call is not immediately followed by a call to +.BR perror , +the value of +.I errno +should be saved. + +.SH "CONFORMING TO" +The function +.B perror() +and the external +.I errno +(see +.BR errno (3)) +conform to ANSI C, BSD 4.3, POSIX, X/OPEN. +The externals +.I sys_nerr +and +.I sys_errlist +conform to BSD. +.SH NOTE +The externals +.I sys_nerr +and +.I sys_errlist +are defined by glibc, but in +.IR . +.\" and only when _BSD_SOURCE is defined. +.\" When _GNU_SOURCE is defined, the symbols +.\" .I _sys_nerr +.\" and +.\" .I _sys_errlist +.\" are provided. +.SH "SEE ALSO" +.BR errno (3), +.BR strerror (3) diff --git a/man3/pmap_getmaps.3 b/man3/pmap_getmaps.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/pmap_getmaps.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/pmap_getport.3 b/man3/pmap_getport.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/pmap_getport.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/pmap_rmtcall.3 b/man3/pmap_rmtcall.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/pmap_rmtcall.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/pmap_set.3 b/man3/pmap_set.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/pmap_set.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/pmap_unset.3 b/man3/pmap_unset.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/pmap_unset.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/popen.3 b/man3/popen.3 new file mode 100644 index 000000000..0f164919a --- /dev/null +++ b/man3/popen.3 @@ -0,0 +1,168 @@ +.\" Copyright 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)popen.3 6.4 (Berkeley) 4/30/91 +.\" +.\" Converted for Linux, Mon Nov 29 14:45:38 1993, faith@cs.unc.edu +.\" Modified Sat May 18 20:37:44 1996 by Martin Schulze (joey@linux.de) +.\" Modified 7 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" +.TH POPEN 3 1998-05-07 "BSD MANPAGE" "Linux Programmer's Manual" +.SH NAME +popen, pclose \- process I/O +.SH SYNOPSIS +.B #include +.sp +.BI "FILE *popen(const char *" command ", const char *" type ); +.sp +.BI "int pclose(FILE *" stream ); +.SH DESCRIPTION +The +.B popen() +function opens a process by creating a pipe, forking, and invoking the +shell. Since a pipe is by definition unidirectional, the +.I type +argument may specify only reading or writing, not both; the resulting +stream is correspondingly read-only or write-only. +.PP +The +.I command +argument is a pointer to a null-terminated string containing a shell +command line. This command is passed to +.I /bin/sh +using the +.B \-c +flag; interpretation, if any, is performed by the shell. The +.I type +argument is a pointer to a null-terminated string which must be either `r' +for reading or `w' for writing. +.PP +The return value from +.B popen() +is a normal standard I/O stream in all respects save that it must be closed +with +.B pclose() +rather than +.BR fclose() . +Writing to such a stream writes to the standard input of the command; the +command's standard output is the same as that of the process that called +.BR popen() , +unless this is altered by the command itself. Conversely, reading from a +``popened'' stream reads the command's standard output, and the command's +standard input is the same as that of the process that called +.BR popen . +.PP +Note that output +.B popen +streams are fully buffered by default. +.PP +The +.B pclose +function waits for the associated process to terminate and returns the exit +status of the command as returned by +.BR wait4 . +.SH "RETURN VALUE" +The +.B popen +function returns +.B NULL +if the +.BR fork (2) +or +.BR pipe (2) +calls fail, or if it cannot allocate memory. +.PP +The +.B pclose +function returns \-1 if +.\" These conditions actually give undefined results, so I commented +.\" them out. +.\" .I stream +.\" is not associated with a ``popened'' command, if +.\".I stream +.\" already ``pclosed'', or if +.B wait4 +returns an error, or some other error is detected. +.SH ERRORS +The +.B popen +function does not set +.I errno +if memory allocation fails. If the underlying +.BR fork() " or " pipe() +fails, +.I errno +is set appropriately. If the +.I type +argument is invalid, and this condition is detected, +.I errno +is set to +.BR EINVAL . +.PP +If +.B pclose() +cannot obtain the child status, +.I errno +is set to +.BR ECHILD . +.SH "CONFORMING TO" +POSIX.2 +.SH BUGS +Since the standard input of a command opened for reading shares its seek +offset with the process that called +.BR popen() , +if the original process has done a buffered read, the command's input +position may not be as expected. Similarly, the output from a command +opened for writing may become intermingled with that of the original +process. The latter can be avoided by calling +.BR fflush (3) +before +.BR popen . +.PP +Failure to execute the shell is indistinguishable from the shell's failure +to execute command, or an immediate exit of the command. The only hint is +an exit status of 127. +.SH HISTORY +A +.B popen() +and a +.B pclose() +function appeared in Version 7 AT&T UNIX. +.SH "SEE ALSO" +.BR sh (1), +.BR fork (2), +.BR pipe (2), +.BR wait4 (2), +.BR fclose (3), +.BR fflush (3), +.BR fopen (3), +.BR stdio (3), +.BR system (3) diff --git a/man3/posix_memalign.3 b/man3/posix_memalign.3 new file mode 100644 index 000000000..2713727bd --- /dev/null +++ b/man3/posix_memalign.3 @@ -0,0 +1,192 @@ +.\" (c) 2001 by John Levon +.\" Based in part on GNU libc documentation. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" +.\" 2001-10-11, 2003-08-22, aeb, added some details +.TH POSIX_MEMALIGN 3 2003-08-22 "GNU" "Linux Programmer's Manual" +.SH NAME +posix_memalign, memalign, valloc \- Allocate aligned memory +.SH SYNOPSIS +.nf +.B #define _XOPEN_SOURCE 600 +.B #include +.sp +.BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size ); +.sp +.B #include +.sp +.BI "void *valloc(size_t " size ); +.BI "void *memalign(size_t " boundary ", size_t " size ); +.nl +.fi +.SH DESCRIPTION +The function +.B posix_memalign() +allocates +.I size +bytes and places the address of the allocated memory in +.IR "*memptr". +The address of the allocated memory will be a multiple of +.IR "alignment", +which must be a power of two and a multiple of +.IR "sizeof(void *)". + +The obsolete function +.B memalign() +allocates +.I size +bytes and returns a pointer to the allocated memory. +The memory address will be a multiple of +.IR "boundary", +which must be a power of two. + +The obsolete function +.B valloc() +allocates +.I size +bytes and returns a pointer to the allocated memory. +The memory address will be a multiple of the page size. +It is equivalent to +.IR "memalign(sysconf(_SC_PAGESIZE),size)" . + +For all three routines, the memory is not zeroed. + +.SH "RETURN VALUE" +.BR memalign() +and +.BR valloc() +return the pointer to the allocated memory, or +.B NULL +if the request fails. + +.BR posix_memalign() +returns zero on success, or one of the error values listed in the +next section on failure. Note that +.IR errno +is not set. + +.SH "ERRORS" +.TP +.B EINVAL +The +.IR alignment +parameter was not a power of two, or was not a multiple of +.IR "sizeof(void *)" . +.TP +.B ENOMEM +There was insufficient memory to fulfill the allocation request. + +.SH NOTES +On many systems there are alignment restrictions, e.g. on buffers +used for direct block device I/O. POSIX specifies the +.I "pathconf(path,_PC_REC_XFER_ALIGN)" +call that tells what alignment is needed. Now one can use +.BR posix_memalign () +to satisfy this requirement. + +.BR posix_memalign () +verifies that +.IR alignment +matches the requirements detailed above. +.BR memalign() +may not check that the +.IR boundary +parameter is correct. + +POSIX requires that memory obtained from +.BR posix_memalign() +can be freed using +.IR free (). +Some systems provide no way to reclaim memory allocated with +.IR memalign () +or +.IR valloc () +(because one can only pass to +.IR free () +a pointer gotten from +.IR malloc (), +while e.g. +.IR memalign () +would call +.IR malloc () +and then align the obtained value). +.\" Other systems allow passing the result of +.\" .IR valloc () +.\" to +.\" .IR free (), +.\" but not to +.\" .IR realloc (). +GNU libc allows memory obtained from any of these three routines to be +reclaimed with +.IR free (). + +GNU libc +.BR "malloc()" +always returns 8-byte aligned memory addresses, so these routines are only +needed if you require larger alignment values. + +.SH AVAILABILITY +The functions +.IR memalign () +and +.IR valloc () +have been available in all Linux libc libraries. +The function +.IR posix_memalign () +is available since glibc 2.1.91. + +.SH "CONFORMING TO" +The function +.IR valloc () +appeared in 3.0 BSD. It is documented as being obsolete in BSD 4.3, +and as legacy in SUSv2. It no longer occurs in SUSv3. +The function +.IR memalign () +appears in SunOS 4.1.3 but not in BSD 4.4. +The function +.IR posix_memalign () +comes from POSIX 1003.1d. + +.SH HEADERS +Everybody agrees that +.IR posix_memalign () +is declared in . In order to declare it, glibc needs +_GNU_SOURCE defined, or _XOPEN_SOURCE defined to a value not less than 600. + +Everybody agrees that +.IR memalign () +is declared in . + +According to SUSv2, +.IR valloc () +is declared in . +Libc4,5 and glibc declare it in and perhaps also in +(namely, if _GNU_SOURCE is defined, or _BSD_SOURCE is defined, or, +for glibc, if _XOPEN_SOURCE_EXTENDED is defined, or, equivalently, +_XOPEN_SOURCE is defined to a value not less than 500). + +.SH "SEE ALSO" +.BR brk (2), +.BR getpagesize (2), +.BR free (3), +.BR malloc (3) diff --git a/man3/pow.3 b/man3/pow.3 new file mode 100644 index 000000000..db2cbe89a --- /dev/null +++ b/man3/pow.3 @@ -0,0 +1,60 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH POW 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +pow, powf, powl \- power functions +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double pow(double " x ", double " y ); +.sp +.BI "float powf(float " x ", float " y ); +.sp +.BI "long double powl(long double " x ", long double " y ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBpow()\fP function returns the value of \fIx\fP raised to the +power of \fIy\fP. +.SH ERRORS +The \fBpow()\fP function can return the following error: +.TP +.B EDOM +The argument \fIx\fP is negative and \fIy\fP is not an integral value. +This would result in a complex number. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR cbrt (3), +.BR sqrt (3) diff --git a/man3/pow10.3 b/man3/pow10.3 new file mode 100644 index 000000000..5f431b6e5 --- /dev/null +++ b/man3/pow10.3 @@ -0,0 +1,49 @@ +.\" Copyright 2004 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH POW10 3 2004-10-05 "" "Linux Programmer's Manual" +.SH NAME +pow10, pow10f, pow10l \- base-10 power functions +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include +.sp +.BI "double pow10(double " x ); +.sp +.BI "float pow10f(float " x ); +.sp +.BI "long double pow10l(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBpow10()\fP function returns the value of 10 raised to the +power \fIx\fP. +.SH "CONFORMING TO" +This is a GNU extension. +.SH NOTE +These functions are identical to the functions listed under +.BR exp10 (3). +.SH "SEE ALSO" +.BR exp10 (3), +.BR pow (3) diff --git a/man3/pow10f.3 b/man3/pow10f.3 new file mode 100644 index 000000000..8a7158015 --- /dev/null +++ b/man3/pow10f.3 @@ -0,0 +1 @@ +.so man3/pow10.3 diff --git a/man3/pow10l.3 b/man3/pow10l.3 new file mode 100644 index 000000000..8a7158015 --- /dev/null +++ b/man3/pow10l.3 @@ -0,0 +1 @@ +.so man3/pow10.3 diff --git a/man3/powf.3 b/man3/powf.3 new file mode 100644 index 000000000..63da756f5 --- /dev/null +++ b/man3/powf.3 @@ -0,0 +1 @@ +.so man3/pow.3 diff --git a/man3/powl.3 b/man3/powl.3 new file mode 100644 index 000000000..63da756f5 --- /dev/null +++ b/man3/powl.3 @@ -0,0 +1 @@ +.so man3/pow.3 diff --git a/man3/printf.3 b/man3/printf.3 new file mode 100644 index 000000000..a5daac871 --- /dev/null +++ b/man3/printf.3 @@ -0,0 +1,931 @@ +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" +.\" Earlier versions of this page influenced the present text. +.\" It was derived from a Berkeley page with version +.\" @(#)printf.3 6.14 (Berkeley) 7/30/91 +.\" converted for Linux by faith@cs.unc.edu, updated by +.\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible. +.\" +.\" 1999-11-25 aeb - Rewritten, using SUSv2 and C99. +.\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes +.\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes +.\" +.TH PRINTF 3 2000-10-16 "Linux Manpage" "Linux Programmer's Manual" +.SH NAME +printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf \- formatted output conversion +.SH SYNOPSIS +.B #include +.sp +.BI "int printf(const char *" format ", ...);" +.br +.BI "int fprintf(FILE *" stream ", const char *" format ", ...);" +.br +.BI "int sprintf(char *" str ", const char *" format ", ...);" +.br +.BI "int snprintf(char *" str ", size_t " size ", const char *" format ", ...);" +.sp +.B #include +.sp +.BI "int vprintf(const char *" format ", va_list " ap ); +.br +.BI "int vfprintf(FILE *" stream ", const char *" format ", va_list " ap ); +.br +.BI "int vsprintf(char *" str ", const char *" format ", va_list " ap ); +.br +.BI "int vsnprintf(char *" str ", size_t " size ", const char *" format ", va_list " ap ); +.SH DESCRIPTION +The functions in the +.B printf +family produce output according to a +.I format +as described below. The functions +.B printf +and +.B vprintf +write output to +.IR stdout , +the standard output stream; +.B fprintf +and +.B vfprintf +write output to the given output +.IR stream ; +.BR sprintf , +.BR snprintf , +.B vsprintf +and +.B vsnprintf +write to the character string +.IR str . +.PP +The functions +.BR vprintf , +.BR vfprintf , +.BR vsprintf , +.B vsnprintf +are equivalent to the functions +.BR printf , +.BR fprintf , +.BR sprintf , +.BR snprintf , +respectively, except that they are called with a va_list instead +of a variable number of arguments. These functions do not call the +.I va_end +macro. Consequently, the value of +.I ap +is undefined after the call. The application should call +.I va_end(ap) +itself afterwards. +.PP +These eight functions write the output under the control of a +.I format +string that specifies how subsequent arguments (or arguments accessed via +the variable-length argument facilities of +.BR stdarg (3)) +are converted for output. +.SS "Return value" +Upon successful return, these functions return the number of characters +printed (not including the trailing '\e0' used to end output to strings). +The functions +.BR snprintf " and " vsnprintf +do not write more than +.I size +bytes (including the trailing '\e0'). +If the output was truncated due to this limit then the return value +is the number of characters (not including the trailing '\e0') +which would have been written to the final string if enough space +had been available. Thus, a return value of +.I size +or more means that the output was truncated. (See also below +under NOTES.) +If an output error is encountered, a negative value is returned. +.SS "Format of the format string" +The format string is a character string, beginning and ending +in its initial shift state, if any. +The format string is composed of zero or more directives: ordinary +characters (not +.BR % ), +which are copied unchanged to the output stream; +and conversion specifications, each of which results in fetching zero or +more subsequent arguments. Each conversion specification is introduced by +the character +.BR % , +and ends with a +.IR "conversion specifier" . +In between there may be (in this order) zero or more +.IR flags , +an optional minimum +.IR "field width" , +an optional +.I precision +and an optional +.IR "length modifier" . + +The arguments must correspond properly (after type promotion) with the +conversion specifier. By default, the arguments are used in the order +given, where each `*' and each conversion specifier asks for the next +argument (and it is an error if insufficiently many arguments are given). +One can also specify explicitly which argument is taken, +at each place where an argument is required, by writing `%m$' instead +of `%' and `*m$' instead of `*', where the decimal integer m denotes +the position in the argument list of the desired argument, indexed starting +from 1. Thus, +.RS +.nf + printf("%*d", width, num); +.fi +.RE +and +.RS +.nf + printf("%2$*1$d", width, num); +.fi +.RE +are equivalent. The second style allows repeated references to the +same argument. The C99 standard does not include the style using `$', +which comes from the Single Unix Specification. If the style using +`$' is used, it must be used throughout for all conversions taking an +argument and all width and precision arguments, but it may be mixed +with `%%' formats which do not consume an argument. There may be no +gaps in the numbers of arguments specified using `$'; for example, if +arguments 1 and 3 are specified, argument 2 must also be specified +somewhere in the format string. + +For some numeric conversions a radix character (`decimal point') or +thousands' grouping character is used. The actual character used +depends on the LC_NUMERIC part of the locale. The POSIX locale +uses `.' as radix character, and does not have a grouping character. +Thus, +.RS +.nf + printf("%'.2f", 1234567.89); +.fi +.RE +results in `1234567.89' in the POSIX locale, in `1234567,89' in the +nl_NL locale, and in `1.234.567,89' in the da_DK locale. +.SS "The flag characters" +The character % is followed by zero or more of the following flags: +.TP +.B # +The value should be converted to an ``alternate form''. +For +.BR o +conversions, the first character of the output string is made zero +(by prefixing a 0 if it was not zero already). +For +.B x +and +.B X +conversions, a non\-zero result has the string `0x' (or `0X' for +.B X +conversions) prepended to it. For +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.B G +conversions, the result will always contain a decimal point, even if no +digits follow it (normally, a decimal point appears in the results of those +conversions only if a digit follows). For +.B g +and +.B G +conversions, trailing zeros are not removed from the result as they would +otherwise be. +For other conversions, the result is undefined. +.TP +.B \&0 +The value should be zero padded. For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.B G +conversions, the converted value is padded on the left with zeros rather +than blanks. +If the +.B \&0 +and +.B \- +flags both appear, the +.B \&0 +flag is ignored. +If a precision is given with a numeric conversion +.BR "" ( d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.BR X ), +the +.B \&0 +flag is ignored. +For other conversions, the behavior is undefined. +.TP +.B \- +The converted value is to be left adjusted on the field boundary. +(The default is right justification.) Except for +.B n +conversions, the converted value is padded on the right with blanks, rather +than on the left with blanks or zeros. A +.B \- +overrides a +.B \&0 +if both are given. +.TP +.B ' ' +(a space) A blank should be left before a positive number +(or empty string) produced by a signed conversion. +.TP +.B + +A sign (+ or -) always be placed before a number produced by a signed +conversion. By default a sign is used only for negative numbers. A +.B + +overrides a space if both are used. +.PP +The five flag characters above are defined in the C standard. +The SUSv2 specifies one further flag character. +.TP +.B ' +For decimal conversion +.BR "" ( i , +.BR d , +.BR u , +.BR f , +.BR F , +.BR g , +.BR G ) +the output is to be grouped with thousands' grouping characters +if the locale information indicates any. Note that many versions of +.B gcc +cannot parse this option and will issue a warning. SUSv2 does not +include %'F. +.PP +glibc 2.2 adds one further flag character. +.TP +.B I +For decimal integer conversion +.BR "" ( i , +.BR d , +.BR u ) +the output uses the locale's alternative output digits, if any. +For example, since glibc 2.2.3 this will give Arabic-Indic digits +in the Persian (`fa_IR') locale. +.\" outdigits keyword in locale file +.SS "The field width" +An optional decimal digit string (with nonzero first digit) specifying +a minimum field width. If the converted value has fewer characters +than the field width, it will be padded with spaces on the left +(or right, if the left-adjustment flag has been given). +Instead of a decimal digit string one may write `*' or `*m$' +(for some decimal integer m) to specify that the field width +is given in the next argument, or in the m-th argument, respectively, +which must be of type +.IR int . +A negative field width is taken as a `-' flag followed by a +positive field width. +In no case does a non-existent or small field width cause truncation of a +field; if the result of a conversion is wider than the field width, the +field is expanded to contain the conversion result. +.SS "The precision" +An optional precision, in the form of a period (`\&.') followed by an +optional decimal digit string. +Instead of a decimal digit string one may write `*' or `*m$' +(for some decimal integer m) to specify that the precision +is given in the next argument, or in the m-th argument, respectively, +which must be of type +.IR int . +If the precision is given as just `.', or the precision is negative, +the precision is taken to be zero. +This gives the minimum number of digits to appear for +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.B X +conversions, the number of digits to appear after the radix character for +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +and +.B F +conversions, the maximum number of significant digits for +.B g +and +.B G +conversions, or the maximum number of characters to be printed from a +string for +.B s +and +.B S +conversions. +.SS "The length modifier" +Here, `integer conversion' stands for +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion. +.TP +.B hh +A following integer conversion corresponds to a +.I signed char +or +.I unsigned char +argument, or a following +.B n +conversion corresponds to a pointer to a +.I signed char +argument. +.TP +.B h +A following integer conversion corresponds to a +.I short int +or +.I unsigned short int +argument, or a following +.B n +conversion corresponds to a pointer to a +.I short int +argument. +.TP +.B l +(ell) A following integer conversion corresponds to a +.I long int +or +.I unsigned long int +argument, or a following +.B n +conversion corresponds to a pointer to a +.I long int +argument, or a following +.B c +conversion corresponds to a +.I wint_t +argument, or a following +.B s +conversion corresponds to a pointer to +.I wchar_t +argument. +.TP +.B ll +(ell-ell). +A following integer conversion corresponds to a +.I long long int +or +.I unsigned long long int +argument, or a following +.B n +conversion corresponds to a pointer to a +.I long long int +argument. +.TP +.BR L +A following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.B G +conversion corresponds to a +.I long double +argument. +(C99 allows %LF, but SUSv2 does not.) +.TP +.B q +(`quad'. BSD 4.4 and Linux libc5 only. Don't use.) +This is a synonym for +.BR ll . +.TP +.B j +A following integer conversion corresponds to an +.I intmax_t +or +.I uintmax_t +argument. +.TP +.B z +A following integer conversion corresponds to a +.I size_t +or +.I ssize_t +argument. (Linux libc5 has +.B Z +with this meaning. Don't use it.) +.TP +.B t +A following integer conversion corresponds to a +.I ptrdiff_t +argument. +.PP +The SUSv2 only knows about the length modifiers +.B h +(in +.BR hd , +.BR hi , +.BR ho , +.BR hx , +.BR hX , +.BR hn ) +and +.B l +(in +.BR ld , +.BR li , +.BR lo , +.BR lx , +.BR lX , +.BR ln , +.BR lc , +.BR ls ) +and +.B L +(in +.BR Le , +.BR LE , +.BR Lf , +.BR Lg , +.BR LG ). + +.SS "The conversion specifier" +A character that specifies the type of conversion to be applied. +The conversion specifiers and their meanings are: +.TP +.BR d , i +The +.I int +argument is converted to signed decimal notation. +The precision, if any, gives the minimum number of digits +that must appear; if the converted value requires fewer digits, it is +padded on the left with zeros. The default precision is 1. +When 0 is printed with an explicit precision 0, the output is empty. +.TP +.BR o , u , x , X +The +.I "unsigned int" +argument is converted to unsigned octal +.BR "" ( o ), +unsigned decimal +.BR "" ( u ), +or unsigned hexadecimal +.BR "" ( x +and +.BR X ) +notation. The letters +.B abcdef +are used for +.B x +conversions; the letters +.B ABCDEF +are used for +.B X +conversions. The precision, if any, gives the minimum number of digits +that must appear; if the converted value requires fewer digits, it is +padded on the left with zeros. The default precision is 1. +When 0 is printed with an explicit precision 0, the output is empty. +.TP +.BR e , E +The +.I double +argument is rounded and converted in the style +.if \w'\*(Pm'=0 .ds Pm \(+- +.BR "" [\-]d \&. ddd e \\*(Pmdd +where there is one digit before the decimal\-point character and the number +of digits after it is equal to the precision; if the precision is missing, +it is taken as 6; if the precision is zero, no decimal\-point character +appears. An +.B E +conversion uses the letter +.B E +(rather than +.BR e ) +to introduce the exponent. The exponent always contains at least two +digits; if the value is zero, the exponent is 00. +.TP +.BR f , F +The +.I double +argument is rounded and converted to decimal notation in the style +.BR "" [\-]ddd \&. ddd, +where the number of digits after the decimal\-point character is equal to +the precision specification. If the precision is missing, it is taken as +6; if the precision is explicitly zero, no decimal\-point character appears. +If a decimal point appears, at least one digit appears before it. + +(The SUSv2 does not know about +.B F +and says that character string representations for infinity and NaN +may be made available. The C99 standard specifies `[-]inf' or `[-]infinity' +for infinity, and a string starting with `nan' for NaN, in the case of +.B f +conversion, and `[-]INF' or `[-]INFINITY' or `NAN*' in the case of +.B F +conversion.) +.TP +.BR g , G +The +.I double +argument is converted in style +.B f +or +.B e +(or +.B F +or +.B E +for +.B G +conversions). The precision specifies the number of significant digits. +If the precision is missing, 6 digits are given; if the precision is zero, +it is treated as 1. Style +.B e +is used if the exponent from its conversion is less than \-4 or greater +than or equal to the precision. Trailing zeros are removed from the +fractional part of the result; a decimal point appears only if it is +followed by at least one digit. +.TP +.BR a , A +(C99; not in SUSv2) For +.B a +conversion, the +.I double +argument is converted to hexadecimal notation (using the letters abcdef) +in the style +.BR "" [-] 0x h \&. hhhh p \\*(Pmd; +for +.B A +conversion the prefix +.BR 0X , +the letters ABCDEF, and the exponent separator +.B P +is used. +There is one hexadecimal digit before the decimal point, +and the number of digits after it is equal to the precision. +The default precision suffices for an exact representation of the value +if an exact representation in base 2 exists +and otherwise is sufficiently large to distinguish values of type +.IR double . +The digit before the decimal point is unspecified for non-normalized +numbers, and nonzero but otherwise unspecified for normalized numbers. +.TP +.B c +If no +.B l +modifier is present, the +.I int +argument is converted to an +.IR "unsigned char" , +and the resulting character is written. +If an +.B l +modifier is present, the +.I wint_t +(wide character) argument is converted to a multibyte sequence by a call +to the +.B wcrtomb +function, with a conversion state starting in the initial state, and the +resulting multibyte string is written. +.TP +.B s +If no +.B l +modifier is present: The +.I "const char *" +argument is expected to be a pointer to an array of character type (pointer +to a string). Characters from the array are written up to (but not +including) a terminating +.B NUL +character; if a precision is specified, no more than the number specified +are written. If a precision is given, no null character need be present; +if the precision is not specified, or is greater than the size of the +array, the array must contain a terminating +.B NUL +character. + +If an +.B l +modifier is present: The +.I "const wchar_t *" +argument is expected to be a pointer to an array of wide characters. +Wide characters from the array are converted to multibyte characters +(each by a call to the +.B wcrtomb +function, with a conversion state starting in the initial state before +the first wide character), up to and including a terminating null +wide character. The resulting multibyte characters are written up to +(but not including) the terminating null byte. If a precision is +specified, no more bytes than the number specified are written, but +no partial multibyte characters are written. Note that the precision +determines the number of +.I bytes +written, not the number of +.I wide characters +or +.IR "screen positions" . +The array must contain a terminating null wide character, unless a +precision is given and it is so small that the number of bytes written +exceeds it before the end of the array is reached. +.TP +.B C +(Not in C99, but in SUSv2.) +Synonym for +.BR lc . +Don't use. +.TP +.B S +(Not in C99, but in SUSv2.) +Synonym for +.BR ls . +Don't use. +.TP +.B p +The +.I "void *" +pointer argument is printed in hexadecimal (as if by +.B %#x +or +.BR %#lx ). +.TP +.B n +The number of characters written so far is stored into the integer +indicated by the +.I "int *" +(or variant) pointer argument. No argument is converted. +.TP +.B % +A `%' is written. No argument is converted. The complete conversion +specification is `%%'. +.PP +.SH EXAMPLES +.br +.if \w'\*(Pi'=0 .ds Pi pi +To print \*(Pi to five decimal places: +.RS +.nf +#include +#include +fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); +.fi +.RE +.PP +To print a date and time in the form `Sunday, July 3, 10:02', +where +.I weekday +and +.I month +are pointers to strings: +.RS +.nf +#include +fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", + weekday, month, day, hour, min); +.fi +.RE +.PP +Many countries use the day-month-year order. +Hence, an internationalized version must be able to print +the arguments in an order specified by the format: +.RS +.nf +#include +fprintf(stdout, format, + weekday, month, day, hour, min); +.fi +.RE +where +.I format +depends on locale, and may permute the arguments. With the value +.RS +.nf +"%1$s, %3$d. %2$s, %4$d:%5$.2d\en" +.fi +.RE +one might obtain `Sonntag, 3. Juli, 10:02'. +.PP +To allocate a sufficiently large string and print into it +(code correct for both glibc 2.0 and glibc 2.1): +.RS +.nf +#include +#include +#include +char * +make_message(const char *fmt, ...) { + /* Guess we need no more than 100 bytes. */ + int n, size = 100; + char *p; + va_list ap; + if ((p = malloc (size)) == NULL) + return NULL; + while (1) { + /* Try to print in the allocated space. */ + va_start(ap, fmt); + n = vsnprintf (p, size, fmt, ap); + va_end(ap); + /* If that worked, return the string. */ + if (n > -1 && n < size) + return p; + /* Else try again with more space. */ + if (n > -1) /* glibc 2.1 */ + size = n+1; /* precisely what is needed */ + else /* glibc 2.0 */ + size *= 2; /* twice the old size */ + if ((p = realloc (p, size)) == NULL) + return NULL; + } +} +.fi +.RE + +.SH NOTES +The glibc implementation of the functions +.B snprintf +and +.B vsnprintf +conforms to the C99 standard, i.e., behaves as described above, +since glibc version 2.1. Until glibc 2.0.6 they would return \-1 +when the output was truncated. +.SH "CONFORMING TO" +The +.BR fprintf , +.BR printf , +.BR sprintf , +.BR vprintf , +.BR vfprintf , +and +.B vsprintf +functions conform to ANSI X3.159-1989 (``ANSI C'') and ISO/IEC 9899:1999 +(``ISO C99''). +The +.B snprintf +and +.B vsnprintf +functions conform to ISO/IEC 9899:1999. +.PP +Concerning the return value of +.BR snprintf , +the SUSv2 and the C99 standard contradict each other: when +.B snprintf +is called with +.IR size =0 +then SUSv2 stipulates an unspecified return value less than 1, +while C99 allows +.I str +to be NULL in this case, and gives the return value (as always) +as the number of characters that would have been written in case +the output string has been large enough. +.PP +Linux libc4 knows about the five C standard flags. +It knows about the length modifiers h,l,L, and the conversions +cdeEfFgGinopsuxX, where F is a synonym for f. +Additionally, it accepts D,O,U as synonyms for ld,lo,lu. +(This is bad, and caused serious bugs later, when +support for %D disappeared.) No locale-dependent radix character, +no thousands' separator, no NaN or infinity, no %m$ and *m$. +.PP +Linux libc5 knows about the five C standard flags and the ' flag, +locale, %m$ and *m$. +It knows about the length modifiers h,l,L,Z,q, but accepts L and q +both for long doubles and for long long integers (this is a bug). +It no longer recognizes FDOU, but adds a new conversion character +.BR m , +which outputs +.IR strerror(errno) . +.PP +glibc 2.0 adds conversion characters C and S. +.PP +glibc 2.1 adds length modifiers hh,j,t,z and conversion characters a,A. +.PP +glibc 2.2 adds the conversion character F with C99 semantics, and the +flag character I. +.SH HISTORY +Unix V7 defines the three routines +.BR printf , +.BR fprintf , +.BR sprintf , +and has the flag -, the width or precision *, the length modifier l, +and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx. +This is still true for BSD 2.9.1, but BSD 2.10 has the flags +#, + and and no longer mentions D,O,U,X. +BSD 2.11 has +.BR vprintf , +.BR vfprintf , +.BR vsprintf , +and warns not to use D,O,U,X. +BSD 4.3 Reno has the flag 0, the length modifiers h and L, +and the conversions n, p, E, G, X (with current meaning) +and deprecates D,O,U. +BSD 4.4 introduces the functions +.B snprintf +and +.BR vsnprintf , +and the length modifier q. +FreeBSD also has functions +.I asprintf +and +.IR vasprintf , +that allocate a buffer large enough for +.BR sprintf . +In glibc there are functions +.I dprintf +and +.I vdprintf +that print to a file descriptor instead of a stream. +.SH BUGS +Because +.B sprintf +and +.B vsprintf +assume an arbitrarily long string, callers must be careful not to overflow +the actual space; this is often impossible to assure. Note that the length +of the strings produced is locale-dependent and difficult to predict. +Use +.B snprintf +and +.B vsnprintf +instead (or +.B asprintf +and +.BR vasprintf ). +.PP +Linux libc4.[45] does not have a +.BR snprintf , +but provides a libbsd that contains an +.B snprintf +equivalent to +.BR sprintf , +i.e., one that ignores the +.I size +argument. +Thus, the use of +.B snprintf +with early libc4 leads to serious security problems. +.PP +Code such as +.BI printf( foo ); +often indicates a bug, since +.I foo +may contain a % character. If +.I foo +comes from untrusted user input, it may contain %n, causing the +.B printf +call to write to memory and creating a security hole. +.\" .PP +.\" Some floating point conversions under early libc4 +.\" caused memory leaks. + +.SH "SEE ALSO" +.BR printf (1), +.BR asprintf (3), +.BR dprintf (3), +.BR scanf (3), +.BR wcrtomb (3), +.BR wprintf (3), +.BR locale (5) diff --git a/man3/profil.3 b/man3/profil.3 new file mode 100644 index 000000000..b7a6425b5 --- /dev/null +++ b/man3/profil.3 @@ -0,0 +1,71 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Fri Jun 23 01:35:19 1995 Andries Brouwer +.\" (prompted by Bas V. de Bakker ) +.\" Corrected (and moved to man3), 980612, aeb +.TH PROFIL 3 1993-07-23 "Linux 2.0" "Linux Programmer's Manual" +.SH NAME +profil \- execution time profile +.SH SYNOPSIS +.B #include +.sp +.BI "int profil(u_short *" buf ", size_t " bufsiz ", size_t " offset ", u_int " scale ); +.SH DESCRIPTION +This routine provides a means to find out in what areas your program +spends most of its time. The argument +.I buf +points to +.I bufsiz +bytes of core. Every virtual 10 milliseconds, the user's program counter (PC) +is examined: +.I offset +is subtracted and the result is multiplied by +.IR scale +and divided by 65536. +If the resulting value is less than +.IR bufsiz , +then the corresponding entry in +.I buf +is incremented. +If +.I buf +is NULL, profiling is disabled. +.SH "RETURN VALUE" +Zero is always returned. +.SH BUGS +.B profil +cannot be used on a program that also uses +.B ITIMER_PROF +itimers. + +True kernel profiling provides more accurate results. +Libc 4.4 contained a kernel patch providing a system call profil. +.SH "CONFORMING TO" +Similar to a call in SVr4 (but not POSIX.1). +.SH "SEE ALSO" +.BR gprof (1), +.BR setitimer (2), +.BR sigaction (2), +.BR signal (2) diff --git a/man3/psignal.3 b/man3/psignal.3 new file mode 100644 index 000000000..baeb4e9e9 --- /dev/null +++ b/man3/psignal.3 @@ -0,0 +1,53 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:45:17 1993 by Rik Faith (faith@cs.unc.edu) +.TH PSIGNAL 3 1993-04-13 "GNU" "Linux Programmer's Manual" +.SH NAME +psignal \- print signal message +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void psignal(int " sig ", const char *" s ); +.sp +.BI "extern const char *const " sys_siglist []; +.fi +.SH DESCRIPTION +The \fBpsignal()\fP function displays a message on \fIstderr\fP +consisting of the string \fIs\fP, a colon, a space, and a string +describing the signal number \fIsig\fP. If \fIsig\fP is invalid, +the message displayed will indicate an unknown signal. +.PP +The array \fIsys_siglist\fP holds the signal description strings +indexed by signal number. +.SH "RETURN VALUE" +The \fBpsignal()\fP function returns no value. +.SH "CONFORMING TO" +BSD 4.3 +.SH "SEE ALSO" +.BR perror (3), +.BR strsignal (3) diff --git a/man3/ptsname.3 b/man3/ptsname.3 new file mode 100644 index 000000000..97d743f6f --- /dev/null +++ b/man3/ptsname.3 @@ -0,0 +1,37 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" This page is in the public domain. - aeb +.\" +.TH PTSNAME 3 "2003-01-30" "PTY Control" "Linux Programmer's Manual" +.SH NAME +ptsname \- get the name of the slave pseudotty +.SH SYNOPSIS +.nf +.B #define _XOPEN_SOURCE +.br +.B #include +.sp +.BI "char *ptsname(int " fd ");" +.fi +.SH DESCRIPTION +The +.BR ptsname () +function returns the name of the slave pseudo-terminal device (pty) +corresponding to the master pty referred to by +.IR fd . +.SH "RETURN VALUE" +When successful, +.BR ptsname () +returns a pointer to a string in static storage. This pointer +must not be freed. +.PP +Upon failure, +.BR ptsname () +returns a NULL pointer. +.SH "CONFORMING TO" +POSIX 1003.1-2001. +This is part of the Unix98 pty support, see +.BR pts (4). +.SH "SEE ALSO" +.BR grantpt (3), +.BR ttyname (3), +.BR pts (4) diff --git a/man3/putc.3 b/man3/putc.3 new file mode 100644 index 000000000..a7c3b57fc --- /dev/null +++ b/man3/putc.3 @@ -0,0 +1 @@ +.so man3/puts.3 diff --git a/man3/putc_unlocked.3 b/man3/putc_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/putc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/putchar.3 b/man3/putchar.3 new file mode 100644 index 000000000..a7c3b57fc --- /dev/null +++ b/man3/putchar.3 @@ -0,0 +1 @@ +.so man3/puts.3 diff --git a/man3/putchar_unlocked.3 b/man3/putchar_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/putchar_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/putenv.3 b/man3/putenv.3 new file mode 100644 index 000000000..3a97a95c3 --- /dev/null +++ b/man3/putenv.3 @@ -0,0 +1,94 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Single UNIX Specification, Version 2 +.\" Modified Thu Apr 8 15:00:12 1993, David Metcalfe +.\" Modified Sat Jul 24 18:44:45 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Mon Oct 11 11:11:11 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Wed Nov 10 00:02:26 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sun May 20 22:17:20 2001 by Andries Brouwer (aeb@cwi.nl) +.TH PUTENV 3 1993-04-08 "GNU" "Linux Programmer's Manual" +.SH NAME +putenv \- change or add an environment variable +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int putenv(char *" string ); +.\" Not: const char * +.fi +.SH DESCRIPTION +The \fBputenv()\fP function adds or changes the value of environment +variables. The argument \fIstring\fP is of the form \fIname\fP=\fIvalue\fP. +If \fIname\fP does not already exist in the environment, then +\fIstring\fP is added to the environment. If \fIname\fP does exist, +then the value of \fIname\fP in the environment is changed to +\fIvalue\fP. +The string pointed to by \fIstring\fP becomes part of the environment, +so altering the string changes the environment. +.SH "RETURN VALUE" +The \fBputenv()\fP function returns zero on success, or \-1 if an error +occurs. +.SH ERRORS +.TP +.B ENOMEM +Insufficient space to allocate new environment. +.SH NOTES +The \fBputenv()\fP function is not required to be reentrant, and the +one in libc4, libc5 and glibc2.0 is not, but the glibc2.1 version is. +.LP +Description for libc4, libc5, glibc: +If the argument \fIstring\fP is of the form \fIname\fP, +and does not contain an `=' character, then the variable \fIname\fP +is removed from the environment. +If \fBputenv()\fP has to allocate a new array \fIenviron\fP, +and the previous array was also allocated by \fBputenv()\fP, +then it will be freed. In no case will the old storage associated +to the environment variable itself be freed. +.LP +The libc4 and libc5 and glibc 2.1.2 versions conform to SUSv2: +the pointer \fIstring\fP given to \fBputenv()\fP is used. +In particular, this string becomes part of the environment; +changing it later will change the environment. +(Thus, it is an error is to call \fBputenv()\fP with an automatic variable +as the argument, then return from the calling function while \fIstring\fP +is still part of the environment.) +However, glibc 2.0-2.1.1 differs: a copy of the string is used. +On the one hand this causes a memory leak, and on the other hand +it violates SUSv2. This has been fixed in glibc2.1.2. +.LP +The BSD4.4 version, like glibc 2.0, uses a copy. +.LP +SUSv2 removes the `const' from the prototype, and so does glibc 2.1.3. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3 +.SH "SEE ALSO" +.BR clearenv (3), +.BR getenv (3), +.BR setenv (3), +.BR unsetenv (3), +.BR environ (5) diff --git a/man3/putgrent.3 b/man3/putgrent.3 new file mode 100644 index 000000000..6e4832d55 --- /dev/null +++ b/man3/putgrent.3 @@ -0,0 +1,41 @@ +.\" Copyright 2003 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH PUTGRENT 3 2003-09-09 "GNU" "group Database Access" +.SH NAME +putgrent \- write a group database entry to a file +.SH SYNOPSIS +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "int putgrent(const struct group *" grp ", FILE *" fp ); +.sp +.SH DESCRIPTION +The +.B putgrent() +function is the the counterpart for +.BR fgetgrent() . +The function writes the content of the provided struct group into the +file pointed to by +.IR fp . +The list of group members must be NULL terminated or NULL initialized. +.sp +The struct group is defined as follows: +.sp +.RS +.nf +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group id */ + char **gr_mem; /* group members */ +}; +.fi +.RE +.SH "RETURN VALUE" +The function returns zero on success, and a non-zero value on error. +.SH "SEE ALSO" +.BR fgetgrent (3), +.BR getgrent (3), +.BR group (5) diff --git a/man3/putpwent.3 b/man3/putpwent.3 new file mode 100644 index 000000000..9ce3453e1 --- /dev/null +++ b/man3/putpwent.3 @@ -0,0 +1,76 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:43:46 1993 by Rik Faith (faith@cs.unc.edu) +.TH PUTPWENT 3 1993-04-09 "GNU" "Linux Programmer's Manual" +.SH NAME +putpwent \- write a password file entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.sp +.BI "int putpwent(const struct passwd *" p ", FILE *" stream ); +.fi +.SH DESCRIPTION +The \fBputpwent()\fP function writes a password entry from the +structure \fIp\fP in the file associated with \fIstream\fP. +.PP +The \fIpasswd\fP structure is defined in \fI\fP as follows: +.sp +.RS +.nf +.ta 8n 16n 32n +struct passwd { + char *pw_name; /* user name */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user id */ + gid_t pw_gid; /* group id */ + char *pw_gecos; /* real name */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.ta +.fi +.RE +.SH "RETURN VALUE" +The \fBputpwent()\fP function returns 0 on success, or \-1 if an error +occurs. +.SH ERRORS +.TP +.B EINVAL +Invalid (NULL) argument given. +.SH "CONFORMING TO" +SVID 3 +.SH "SEE ALSO" +.BR endpwent (3), +.BR fgetpwent (3), +.BR getpw (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR setpwent (3) diff --git a/man3/puts.3 b/man3/puts.3 new file mode 100644 index 000000000..8f33ef26c --- /dev/null +++ b/man3/puts.3 @@ -0,0 +1,114 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 18:42:59 1993 by Rik Faith (faith@cs.unc.edu) +.TH PUTS 3 1993-04-04 "GNU" "Linux Programmer's Manual" +.SH NAME +fputc, fputs, putc, putchar, puts \- output of characters and strings +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int fputc(int " c ", FILE *" stream ); +.nl +.BI "int fputs(const char *" "s" ", FILE *" "stream" ); +.nl +.BI "int putc(int " c ", FILE *" stream ); +.nl +.BI "int putchar(int " c ); +.nl +.BI "int puts(const char *" "s" ); +.SH DESCRIPTION +.B fputc() +writes the character +.IR c , +cast to an +.BR "unsigned char" , +to +.IR stream . +.PP +.B fputs() +writes the string +.I s +to +.IR stream , +without its trailing +.BR '\e0' . +.PP +.B putc() +is equivalent to +.B fputc() +except that it may be implemented as a macro which evaluates +.I stream +more than once. +.PP +.BI "putchar(" c ); +is equivalent to +.BI "putc(" c , stdout ). +.PP +.BR puts() +writes the string +.I s +and a trailing newline +to +.IR stdout . +.PP +Calls to the functions described here can be mixed with each other and with +calls to other output functions from the +.B stdio +library for the same output stream. +.PP +For non-locking counterparts, see +.BR unlocked_stdio (3). +.SH "RETURN VALUE" +.BR fputc() , " putc() " and " putchar()" +return the character written as an +.B unsigned char +cast to an +.B int +or +.B EOF +on error. +.PP +.BR puts() " and " fputs() +return a non-negative number on success, or +.B EOF +on error. +.PP +.SH "CONFORMING TO" +ANSI - C, POSIX.1 +.SH BUGS +It is not advisable to mix calls to output functions from the +.B stdio +library with low - level calls to +.B write() +for the file descriptor associated with the same output stream; the results +will be undefined and very probably not what you want. +.SH "SEE ALSO" +.BR write (2), +.BR ferror (3), +.BR fopen (3), +.BR fseek (3), +.BR fwrite (3), +.BR gets (3), +.BR scanf (3), +.BR unlocked_stdio (3) diff --git a/man3/putspent.3 b/man3/putspent.3 new file mode 100644 index 000000000..142c5a5ca --- /dev/null +++ b/man3/putspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/pututline.3 b/man3/pututline.3 new file mode 100644 index 000000000..29c36b72a --- /dev/null +++ b/man3/pututline.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/pututxline.3 b/man3/pututxline.3 new file mode 100644 index 000000000..29c36b72a --- /dev/null +++ b/man3/pututxline.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/putw.3 b/man3/putw.3 new file mode 100644 index 000000000..750934559 --- /dev/null +++ b/man3/putw.3 @@ -0,0 +1 @@ +.so man3/getw.3 diff --git a/man3/putwc.3 b/man3/putwc.3 new file mode 100644 index 000000000..81826be5d --- /dev/null +++ b/man3/putwc.3 @@ -0,0 +1 @@ +.so man3/fputwc.3 diff --git a/man3/putwc_unlocked.3 b/man3/putwc_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/putwc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/putwchar.3 b/man3/putwchar.3 new file mode 100644 index 000000000..ec8a1a24b --- /dev/null +++ b/man3/putwchar.3 @@ -0,0 +1,46 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH PUTWCHAR 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +putwchar \- write a wide character to standard output +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wint_t putwchar(wchar_t " wc ); +.fi +.SH DESCRIPTION +The \fBputwchar\fP function is the wide-character equivalent of the +\fBputchar\fP function. It writes the wide character \fIwc\fP to \fBstdout\fP. +If \fIferror(stdout)\fP becomes true, it returns WEOF. If a wide character +conversion error occurs, it sets \fBerrno\fP to \fBEILSEQ\fP and returns WEOF. +Otherwise it returns \fIwc\fP. +.PP +For a non-locking counterpart, see +.BR unlocked_stdio (3). +.SH "RETURN VALUE" +The \fBputwchar\fP function returns \fIwc\fP if no error occurred, or WEOF to +indicate an error. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH NOTES +The behaviour of \fBputwchar\fP depends on the LC_CTYPE category of the +current locale. +.PP +It is reasonable to expect that \fBputwchar\fP will actually write +the multibyte sequence corresponding to the wide character \fIwc\fP. +.SH "SEE ALSO" +.BR fputwc (3), +.BR unlocked_stdio (3) diff --git a/man3/putwchar_unlocked.3 b/man3/putwchar_unlocked.3 new file mode 100644 index 000000000..858bd0849 --- /dev/null +++ b/man3/putwchar_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/qecvt.3 b/man3/qecvt.3 new file mode 100644 index 000000000..551c68799 --- /dev/null +++ b/man3/qecvt.3 @@ -0,0 +1,70 @@ +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.\" +.TH QECVT 3 2002-08-25 "GNU" "Linux Programmer's Manual" +.SH NAME +qecvt, qfcvt, qgcvt \- convert a floating-point number to a string +.SH SYNOPSIS +.B #include +.sp +.BI "char *qecvt(long double " number ", int " ndigits ", int *" decpt , +.BI "int *" sign ); +.sp +.BI "char *qfcvt(long double " number ", int " ndigits ", int *" decpt , +.BI "int *" sign ); +.sp +.BI "char *qgcvt(long double " number ", int " ndigit ", char *" buf ); +.SH DESCRIPTION +The functions +.BR qecvt , +.BR qfcvt +and +.BR qgcvt +are identical to +.BR ecvt , +.BR fcvt +and +.BR gcvt +respectively, except that they use a +.B "long double" +argument +.IR number . +See +.BR ecvt (3) +and +.BR gcvt (3). +.SH NOTES +These functions are obsolete. Instead, +.IR sprintf () +is recommended. +.SH "CONFORMING TO" +SysVr4.0. Not seen in most common Unix implementations, +but occurs in SunOS. Not supported by libc4 and libc5. +Supported by glibc. +.SH "SEE ALSO" +.BR ecvt (3), +.BR ecvt_r (3), +.BR gcvt (3), +.BR sprintf (3) diff --git a/man3/qecvt_r.3 b/man3/qecvt_r.3 new file mode 100644 index 000000000..41ce9ee8a --- /dev/null +++ b/man3/qecvt_r.3 @@ -0,0 +1 @@ +.so man3/ecvt_r.3 diff --git a/man3/qfcvt.3 b/man3/qfcvt.3 new file mode 100644 index 000000000..7e583109e --- /dev/null +++ b/man3/qfcvt.3 @@ -0,0 +1 @@ +.so man3/qecvt.3 diff --git a/man3/qfcvt_r.3 b/man3/qfcvt_r.3 new file mode 100644 index 000000000..41ce9ee8a --- /dev/null +++ b/man3/qfcvt_r.3 @@ -0,0 +1 @@ +.so man3/ecvt_r.3 diff --git a/man3/qgcvt.3 b/man3/qgcvt.3 new file mode 100644 index 000000000..7e583109e --- /dev/null +++ b/man3/qgcvt.3 @@ -0,0 +1 @@ +.so man3/qecvt.3 diff --git a/man3/qsort.3 b/man3/qsort.3 new file mode 100644 index 000000000..eecca1629 --- /dev/null +++ b/man3/qsort.3 @@ -0,0 +1,76 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" +.TH QSORT 3 2003-11-15 "" "Linux Programmer's Manual" +.SH NAME +qsort \- sorts an array +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void qsort(void *" base ", size_t " nmemb ", size_t " size , +.in +\w'void qsort('u +.BI "int(*" compar ")(const void *, const void *));" +.in +.fi +.SH DESCRIPTION +The \fBqsort()\fP function sorts an array with \fInmemb\fP elements of +size \fIsize\fP. The \fIbase\fP argument points to the start of the +array. +.PP +The contents of the array are sorted in ascending order according to a +comparison function pointed to by \fIcompar\fP, which is called with two +arguments that point to the objects being compared. +.PP +The comparison function must return an integer less than, equal to, or +greater than zero if the first argument is considered to be respectively +less than, equal to, or greater than the second. If two members compare +as equal, their order in the sorted array is undefined. +.SH "RETURN VALUE" +The \fBqsort()\fP function returns no value. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899 +.SH NOTE +Library routines suitable for use as the +.I compar +argument include +.IR strcmp , +.IR alphasort , +and +.IR versionsort . +.SH EXAMPLE +For an example of use, see the example on the +.BR bsearch (3) +page. +.SH "SEE ALSO" +.BR sort (1), +.BR alphasort (3), +.BR strcmp (3), +.BR versionsort (3) diff --git a/man3/queue.3 b/man3/queue.3 new file mode 100644 index 000000000..755e70940 --- /dev/null +++ b/man3/queue.3 @@ -0,0 +1,456 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)queue.3 8.2 (Berkeley) 1/24/94 +.\" +.\" hch, 2002-03-25 +.Dd January 24, 1994 +.Dt QUEUE 3 +.Os BSD 4 +.Sh NAME +.Nm LIST_ENTRY , +.Nm LIST_HEAD , +.Nm LIST_INIT , +.Nm LIST_INSERT_AFTER , +.Nm LIST_INSERT_HEAD , +.Nm LIST_REMOVE , +.Nm TAILQ_ENTRY , +.Nm TAILQ_HEAD , +.Nm TAILQ_INIT , +.Nm TAILQ_INSERT_AFTER , +.Nm TAILQ_INSERT_HEAD , +.Nm TAILQ_INSERT_TAIL , +.Nm TAILQ_REMOVE , +.Nm CIRCLEQ_ENTRY , +.Nm CIRCLEQ_HEAD , +.Nm CIRCLEQ_INIT , +.Nm CIRCLEQ_INSERT_AFTER , +.Nm CIRCLEQ_INSERT_BEFORE , +.Nm CIRCLEQ_INSERT_HEAD , +.Nm CIRCLEQ_INSERT_TAIL , +.Nm CIRCLEQ_REMOVE +.Nd implementations of lists, tail queues, and circular queues +.Sh SYNOPSIS +.Fd #include +.\" +.Fn LIST_ENTRY "TYPE" +.Fn LIST_HEAD "HEADNAME" "TYPE" +.Fn LIST_INIT "LIST_HEAD *head" +.Fn LIST_INSERT_AFTER "LIST_ENTRY *listelm" "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_INSERT_HEAD "LIST_HEAD *head" "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME" +.\" +.Fn TAILQ_ENTRY "TYPE" +.Fn TAILQ_HEAD "HEADNAME" "TYPE" +.Fn TAILQ_INIT "TAILQ_HEAD *head" +.Fn TAILQ_INSERT_AFTER "TAILQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_INSERT_HEAD "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_INSERT_TAIL "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_REMOVE "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" +.\" +.Fn CIRCLEQ_ENTRY "TYPE" +.Fn CIRCLEQ_HEAD "HEADNAME" "TYPE" +.Fn CIRCLEQ_INIT "CIRCLEQ_HEAD *head" +.Fn CIRCLEQ_INSERT_AFTER "CIRCLEQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "CIRCLEQ_ENTRY NAME" +.Fn CIRCLEQ_INSERT_BEFORE "CIRCLEQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "CIRCLEQ_ENTRY NAME" +.Fn CIRCLEQ_INSERT_HEAD "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY NAME" +.Fn CIRCLEQ_INSERT_TAIL "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY NAME" +.Fn CIRCLEQ_REMOVE "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY NAME" +.Sh DESCRIPTION +These macros define and operate on three types of data structures: +lists, tail queues, and circular queues. +All three structures support the following functionality: +.Bl -enum -compact -offset indent +.It +Insertion of a new entry at the head of the list. +.It +Insertion of a new entry after any element in the list. +.It +Removal of any entry in the list. +.It +Forward traversal through the list. +.El +.Pp +Lists are the simplest of the three data structures and support +only the above functionality. +.Pp +Tail queues add the following functionality: +.Bl -enum -compact -offset indent +.It +Entries can be added at the end of a list. +.El +However: +.Bl -enum -compact -offset indent +.It +All list insertions and removals must specify the head of the list. +.It +Each head entry requires two pointers rather than one. +.It +Code size is about 15% greater and operations run about 20% slower +than lists. +.El +.Pp +Circular queues add the following functionality: +.Bl -enum -compact -offset indent +.It +Entries can be added at the end of a list. +.It +Entries can be added before another entry. +.It +They may be traversed backwards, from tail to head. +.El +However: +.Bl -enum -compact -offset indent +.It +All list insertions and removals must specify the head of the list. +.It +Each head entry requires two pointers rather than one. +.It +The termination condition for traversal is more complex. +.It +Code size is about 40% greater and operations run about 45% slower +than lists. +.El +.Pp +In the macro definitions, +.Fa TYPE +is the name of a user defined structure, +that must contain a field of type +.Li LIST_ENTRY , +.Li TAILQ_ENTRY , +or +.Li CIRCLEQ_ENTRY , +named +.Fa NAME . +The argument +.Fa HEADNAME +is the name of a user defined structure that must be declared +using the macros +.Li LIST_HEAD , +.Li TAILQ_HEAD , +or +.Li CIRCLEQ_HEAD . +See the examples below for further explanation of how these +macros are used. +.Sh LISTS +A list is headed by a structure defined by the +.Nm LIST_HEAD +macro. +This structure contains a single pointer to the first element +on the list. +The elements are doubly linked so that an arbitrary element can be +removed without traversing the list. +New elements can be added to the list after an existing element or +at the head of the list. +A +.Fa LIST_HEAD +structure is declared as follows: +.Bd -literal -offset indent +LIST_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Fa HEADNAME +is the name of the structure to be defined, and +.Fa TYPE +is the type of the elements to be linked into the list. +A pointer to the head of the list can later be declared as: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm LIST_ENTRY +declares a structure that connects the elements in +the list. +.Pp +The macro +.Nm LIST_INIT +initializes the list referenced by +.Fa head . +.Pp +The macro +.Nm LIST_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the list. +.Pp +The macro +.Nm LIST_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm LIST_REMOVE +removes the element +.Fa elm +from the list. +.Sh LIST EXAMPLE +.Bd -literal +LIST_HEAD(listhead, entry) head; +struct listhead *headp; /* List head. */ +struct entry { + ... + LIST_ENTRY(entry) entries; /* List. */ + ... +} *n1, *n2, *np; + +LIST_INIT(&head); /* Initialize the list. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +LIST_INSERT_HEAD(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +LIST_INSERT_AFTER(n1, n2, entries); + /* Forward traversal. */ +for (np = head.lh_first; np != NULL; np = np->entries.le_next) + np-> ... + +while (head.lh_first != NULL) /* Delete. */ + LIST_REMOVE(head.lh_first, entries); +.Ed +.Sh TAIL QUEUES +A tail queue is headed by a structure defined by the +.Nm TAILQ_HEAD +macro. +This structure contains a pair of pointers, +one to the first element in the tail queue and the other to +the last element in the tail queue. +The elements are doubly linked so that an arbitrary element can be +removed without traversing the tail queue. +New elements can be added to the tail queue after an existing element, +at the head of the tail queue, or at the end of the tail queue. +A +.Fa TAILQ_HEAD +structure is declared as follows: +.Bd -literal -offset indent +TAILQ_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Li HEADNAME +is the name of the structure to be defined, and +.Li TYPE +is the type of the elements to be linked into the tail queue. +A pointer to the head of the tail queue can later be declared as: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm TAILQ_ENTRY +declares a structure that connects the elements in +the tail queue. +.Pp +The macro +.Nm TAILQ_INIT +initializes the tail queue referenced by +.Fa head . +.Pp +The macro +.Nm TAILQ_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the tail queue. +.Pp +The macro +.Nm TAILQ_INSERT_TAIL +inserts the new element +.Fa elm +at the end of the tail queue. +.Pp +The macro +.Nm TAILQ_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm TAILQ_REMOVE +removes the element +.Fa elm +from the tail queue. +.Sh TAIL QUEUE EXAMPLE +.Bd -literal +TAILQ_HEAD(tailhead, entry) head; +struct tailhead *headp; /* Tail queue head. */ +struct entry { + ... + TAILQ_ENTRY(entry) entries; /* Tail queue. */ + ... +} *n1, *n2, *np; + +TAILQ_INIT(&head); /* Initialize the queue. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +TAILQ_INSERT_HEAD(&head, n1, entries); + +n1 = malloc(sizeof(struct entry)); /* Insert at the tail. */ +TAILQ_INSERT_TAIL(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +TAILQ_INSERT_AFTER(&head, n1, n2, entries); + /* Forward traversal. */ +for (np = head.tqh_first; np != NULL; np = np->entries.tqe_next) + np-> ... + /* Delete. */ +while (head.tqh_first != NULL) + TAILQ_REMOVE(&head, head.tqh_first, entries); +.Ed +.Sh CIRCULAR QUEUES +A circular queue is headed by a structure defined by the +.Nm CIRCLEQ_HEAD +macro. +This structure contains a pair of pointers, +one to the first element in the circular queue and the other to the +last element in the circular queue. +The elements are doubly linked so that an arbitrary element can be +removed without traversing the queue. +New elements can be added to the queue after an existing element, +before an existing element, at the head of the queue, or at the end +of the queue. +A +.Fa CIRCLEQ_HEAD +structure is declared as follows: +.Bd -literal -offset indent +CIRCLEQ_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Li HEADNAME +is the name of the structure to be defined, and +.Li TYPE +is the type of the elements to be linked into the circular queue. +A pointer to the head of the circular queue can later be declared as: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm CIRCLEQ_ENTRY +declares a structure that connects the elements in +the circular queue. +.Pp +The macro +.Nm CIRCLEQ_INIT +initializes the circular queue referenced by +.Fa head . +.Pp +The macro +.Nm CIRCLEQ_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the circular queue. +.Pp +The macro +.Nm CIRCLEQ_INSERT_TAIL +inserts the new element +.Fa elm +at the end of the circular queue. +.Pp +The macro +.Nm CIRCLEQ_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm CIRCLEQ_INSERT_BEFORE +inserts the new element +.Fa elm +before the element +.Fa listelm . +.Pp +The macro +.Nm CIRCLEQ_REMOVE +removes the element +.Fa elm +from the circular queue. +.Sh CIRCULAR QUEUE EXAMPLE +.Bd -literal +CIRCLEQ_HEAD(circleq, entry) head; +struct circleq *headp; /* Circular queue head. */ +struct entry { + ... + CIRCLEQ_ENTRY(entry) entries; /* Circular queue. */ + ... +} *n1, *n2, *np; + +CIRCLEQ_INIT(&head); /* Initialize the circular queue. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +CIRCLEQ_INSERT_HEAD(&head, n1, entries); + +n1 = malloc(sizeof(struct entry)); /* Insert at the tail. */ +CIRCLEQ_INSERT_TAIL(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +CIRCLEQ_INSERT_AFTER(&head, n1, n2, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert before. */ +CIRCLEQ_INSERT_BEFORE(&head, n1, n2, entries); + /* Forward traversal. */ +for (np = head.cqh_first; np != (void *)&head; np = np->entries.cqe_next) + np-> ... + /* Reverse traversal. */ +for (np = head.cqh_last; np != (void *)&head; np = np->entries.cqe_prev) + np-> ... + /* Delete. */ +while (head.cqh_first != (void *)&head) + CIRCLEQ_REMOVE(&head, head.cqh_first, entries); +.Ed +.Sh HISTORY +The +.Nm queue +functions first appeared in +.Bx 4.4 . diff --git a/man3/raise.3 b/man3/raise.3 new file mode 100644 index 000000000..5b76c2747 --- /dev/null +++ b/man3/raise.3 @@ -0,0 +1,51 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 18:40:56 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995 by Mike Battersby (mib@deakin.edu.au) +.\" +.TH RAISE 3 1995-08-31 "GNU" "Linux Programmer's Manual" +.SH NAME +raise \- send a signal to the current process +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int raise(int " sig ); +.fi +.SH DESCRIPTION +The +.B raise() +function sends a signal to the current process. +It is equivalent to +.sp +.RS +.BI "kill(getpid(), " "sig" ); +.RE +.SH "RETURN VALUE" +0 on success, nonzero for failure. +.SH "CONFORMING TO" +ANSI\-C +.SH "SEE ALSO" +.BR getpid (2), +.BR kill (2), +.BR signal (2) diff --git a/man3/rand.3 b/man3/rand.3 new file mode 100644 index 000000000..b13076bc0 --- /dev/null +++ b/man3/rand.3 @@ -0,0 +1,167 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-04-28, Lars Wirzenius +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-05-18, Rik Faith (faith@cs.unc.edu) to add +.\" better discussion of problems with rand on other systems. +.\" (Thanks to Esa Hyyti{ (ehyytia@snakemail.hut.fi).) +.\" Modified 1998-04-10, Nicolás Lichtmaier +.\" with contribution from Francesco Potorti +.\" Modified 2003-11-15, aeb, added rand_r +.\" +.TH RAND 3 2003-11-15 "" "Linux Programmer's Manual" +.SH NAME +rand, rand_r, srand \- pseudo-random number generator +.SH SYNOPSIS +.nf +.B #include +.sp +.B int rand(void); +.sp +.BI "int rand_r(unsigned int *" seedp ); +.sp +.BI "void srand(unsigned int " seed ); +.fi +.SH DESCRIPTION +The \fBrand()\fP function returns a pseudo-random integer between 0 +and \fBRAND_MAX\fR. +.PP +The \fBsrand()\fP function sets its argument as the seed for a new +sequence of pseudo-random integers to be returned by \fBrand()\fP. +These sequences are repeatable by calling \fBsrand()\fP with the same +seed value. +.PP +If no seed value is provided, the \fBrand()\fP function is automatically +seeded with a value of 1. +.PP +The function +.B rand() +is not reentrant or thread-safe, since it +uses hidden state that is modified on each call. This might just be +the seed value to be used by the next call, or it might be something +more elaborate. In order to get reproducible behaviour in a threaded +application, this state must be made explicit. The function +.B rand_r() +is supplied with a pointer to an unsigned int, to be used as state. +This is a very small amount of state, so this function will be a weak +pseudo-random generator. Try +.BR drand48_r (3) +instead. +.SH "RETURN VALUE" +The \fBrand()\fP and \fBrand_r()\fP functions return a value +between 0 and RAND_MAX. +The \fBsrand()\fP function returns no value. +.SH EXAMPLE +POSIX 1003.1-2003 gives the following example of an implementation of +.B rand() +and +.BR srand() , +possibly useful when one needs the same sequence on two different machines. +.sp +.nf + static unsigned long next = 1; + + /* RAND_MAX assumed to be 32767 */ + int myrand(void) { + next = next * 1103515245 + 12345; + return((unsigned)(next/65536) % 32768); + } + + void mysrand(unsigned seed) { + next = seed; + } +.fi +.SH NOTES +The versions of \fBrand()\fP and \fBsrand()\fP in the Linux C Library use +the same random number generator as \fBrandom()\fP and \fBsrandom()\fP, so +the lower-order bits should be as random as the higher-order bits. +However, on older +.B rand() +implementations, and on current implementations on different systems, +the lower-order bits are much less random than the higher-order bits. +Do not use this function in applications intended to be portable +when good randomness is needed. +.PP +FreeBSD adds a function +.sp +.in +5 +.B void sranddev(void); +.in +.sp +that initializes the seed for their bad random generator +.B rand() +with a value obtained from their good random generator +.BR random() . +Strange. +.PP +In +.I Numerical Recipes in C: The Art of Scientific Computing +(William H. Press, Brian P. Flannery, Saul A. Teukolsky, William +T. Vetterling; New York: Cambridge University Press, 1992 (2nd ed., +p. 277)), the following comments are made: +.RS +"If you want to generate a random integer between 1 and 10, you should +always do it by using high-order bits, as in +.RS +.sp +j=1+(int) (10.0*rand()/(RAND_MAX+1.0)); +.sp +.RE +and never by anything resembling +.RS +.sp +j=1+(rand() % 10); +.sp +.RE +(which uses lower-order bits)." +.RE +.PP +Random-number generation is a complex topic. The +.I Numerical Recipes in C +book (see reference above) +provides an excellent discussion of practical random-number generation +issues in Chapter 7 (Random Numbers). +.PP +For a more theoretical discussion which also covers many practical issues +in depth, please see Chapter 3 (Random Numbers) in Donald E. Knuth's +.IR "The Art of Computer Programming" , +volume 2 (Seminumerical Algorithms), 2nd ed.; Reading, Massachusetts: +Addison-Wesley Publishing Company, 1981. +.SH "CONFORMING TO" +The functions +.B rand() +and +.B srand() +conform to SVID 3, BSD 4.3, ISO 9899, POSIX 1003.1-2003. +The function +.B rand_r() +is from POSIX 1003.1-2003. +.SH "SEE ALSO" +.BR drand48 (3), +.BR random (3) diff --git a/man3/rand_r.3 b/man3/rand_r.3 new file mode 100644 index 000000000..b007c2fc2 --- /dev/null +++ b/man3/rand_r.3 @@ -0,0 +1 @@ +.so man3/rand.3 diff --git a/man3/random.3 b/man3/random.3 new file mode 100644 index 000000000..37e53e9ae --- /dev/null +++ b/man3/random.3 @@ -0,0 +1,91 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Mar 28 00:25:51 1993, David Metcalfe +.\" Modified Sat Jul 24 18:13:39 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Aug 20 21:47:07 2000, aeb +.\" +.TH RANDOM 3 2000-08-20 "GNU" "Linux Programmer's Manual" +.SH NAME +random, srandom, initstate, setstate \- random number generator +.SH SYNOPSIS +.nf +.B #include +.sp +.B long int random(void); +.nl +.BI "void srandom(unsigned int " seed ); +.nl +.BI "char *initstate(unsigned int " seed ", char *" state ", size_t " n ); +.nl +.BI "char *setstate(char *" state ); +.fi +.SH DESCRIPTION +The \fBrandom()\fP function uses a non-linear additive feedback random +number generator employing a default table of size 31 long integers to +return successive pseudo-random numbers in the range from 0 to \fBRAND_MAX\fR. +The period of this random number generator is very large, approximately +16*((2**31)\-1). +.PP +The \fBsrandom()\fP function sets its argument as the seed for a new +sequence of pseudo-random integers to be returned by \fBrandom()\fP. +These sequences are repeatable by calling \fBsrandom()\fP with the same +seed value. If no seed value is provided, the \fBrandom()\fP function +is automatically seeded with a value of 1. +.PP +The \fBinitstate()\fP function allows a state array \fIstate\fP to +be initialized for use by \fBrandom()\fP. The size of the state array +\fIn\fP is used by \fBinitstate()\fP to decide how sophisticated a +random number generator it should use \(em the larger the state array, +the better the random numbers will be. \fIseed\fP is the seed for the +initialization, which specifies a starting point for the random number +sequence, and provides for restarting at the same point. +.PP +The \fBsetstate()\fP function changes the state array used by the +\fBrandom()\fP function. The state array \fIstate\fP is used for +random number generation until the next call to \fBinitstate()\fP +or \fBsetstate()\fP. \fIstate\fP must first have been initialized +using \fBinitstate()\fP or be the result of a previous call of +\fBsetstate()\fP. +.SH "RETURN VALUE" +The \fBrandom()\fP function returns a value between 0 and RAND_MAX. +The \fBsrandom()\fP function returns no value. The \fBinitstate()\fP +and \fBsetstate()\fP functions return a pointer to the previous state +array, or NULL on error. +.SH ERRORS +.TP +.B EINVAL +A state array of less than 8 bytes was specified to \fBinitstate()\fP. +.SH NOTES +Current "optimal" values for the size of the state array \fIn\fP are +8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to +the nearest known amount. Using less than 8 bytes will cause an +error. +.SH "CONFORMING TO" +BSD 4.3 +.SH "SEE ALSO" +.BR rand (3), +.BR srand (3) diff --git a/man3/rcmd.3 b/man3/rcmd.3 new file mode 100644 index 000000000..f8f99f4c9 --- /dev/null +++ b/man3/rcmd.3 @@ -0,0 +1,206 @@ +.\" $NetBSD: rcmd.3,v 1.9 1996/05/28 02:07:39 mrg Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)rcmd.3 8.1 (Berkeley) 6/4/93 +.\" +.\" Contributed as Linux man page by David A. Holland, 970908 +.\" I have not checked whether the Linux situation is exactly the same. +.Dd June 4, 1993 +.Dt RCMD 3 +.Os BSD 4.2 +.Sh NAME +.Nm rcmd , +.Nm rresvport , +.Nm iruserok , +.Nm ruserok +.Nd routines for returning a stream to a remote command +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" +.Ft int +.Fn rresvport "int *port" +.Ft int +.Fn iruserok "u_int32_t raddr" "int superuser" "const char *ruser" "const char *luser" +.Ft int +.Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser" +.Sh DESCRIPTION +The +.Fn rcmd +function +is used by the super-user to execute a command on +a remote machine using an authentication scheme based +on reserved port numbers. +The +.Fn rresvport +function +returns a descriptor to a socket +with an address in the privileged port space. +The +.Fn iruserok +and +.Fn ruserok +functions are used by servers +to authenticate clients requesting service with +.Fn rcmd . +All four functions are present in the same file and are used +by the +.Xr rshd 8 +server (among others). +.Pp +The +.Fn rcmd +function +looks up the host +.Fa *ahost +using +.Xr gethostbyname 3 , +returning \-1 if the host does not exist. +Otherwise +.Fa *ahost +is set to the standard name of the host +and a connection is established to a server +residing at the well-known Internet port +.Fa inport . +.Pp +If the connection succeeds, +a socket in the Internet domain of type +.Dv SOCK_STREAM +is returned to the caller, and given to the remote +command as +.Em stdin +and +.Em stdout . +If +.Fa fd2p +is non-zero, then an auxiliary channel to a control +process will be set up, and a descriptor for it will be placed +in +.Fa *fd2p . +The control process will return diagnostic +output from the command (unit 2) on this channel, and will also +accept bytes on this channel as being +.Tn UNIX +signal numbers, to be +forwarded to the process group of the command. +If +.Fa fd2p +is 0, then the +.Em stderr +(unit 2 of the remote +command) will be made the same as the +.Em stdout +and no +provision is made for sending arbitrary signals to the remote process, +although you may be able to get its attention by using out-of-band data. +.Pp +The protocol is described in detail in +.Xr rshd 8 . +.Pp +The +.Fn rresvport +function is used to obtain a socket with a privileged +address bound to it. This socket is suitable for use +by +.Fn rcmd +and several other functions. Privileged Internet ports are those +in the range 0 to 1023. Only the super-user +is allowed to bind an address of this sort to a socket. +.Pp +The +.Fn iruserok +and +.Fn ruserok +functions take a remote host's IP address or name, respectively, +two user names and a flag indicating whether the local user's +name is that of the super-user. +Then, if the user is +.Em NOT +the super-user, it checks the +.Pa /etc/hosts.equiv +file. +If that lookup is not done, or is unsuccessful, the +.Pa .rhosts +in the local user's home directory is checked to see if the request for +service is allowed. +.Pp +If this file does not exist, is not a regular file, is owned by anyone +other than the user or the super-user, or is writeable by anyone other +than the owner, the check automatically fails. +Zero is returned if the machine name is listed in the +.Dq Pa hosts.equiv +file, or the host and remote user name are found in the +.Dq Pa .rhosts +file; otherwise +.Fn iruserok +and +.Fn ruserok +return \-1. +If the local domain (as obtained from +.Xr gethostname 2 ) +is the same as the remote domain, only the machine name need be specified. +.Pp +If the IP address of the remote host is known, +.Fn iruserok +should be used in preference to +.Fn ruserok , +as it does not require trusting the DNS server for the remote host's domain. +.Sh DIAGNOSTICS +The +.Fn rcmd +function +returns a valid socket descriptor on success. +It returns \-1 on error and prints a diagnostic message on the standard error. +.Pp +The +.Fn rresvport +function +returns a valid, bound socket descriptor on success. +It returns \-1 on error with the global value +.Va errno +set according to the reason for failure. +The error code +.Dv EAGAIN +is overloaded to mean ``All network ports in use.'' +.Sh SEE ALSO +.Xr rlogin 1 , +.Xr rsh 1 , +.Xr intro 2 , +.Xr rexec 3 , +.Xr rexecd 8 , +.Xr rlogind 8 , +.Xr rshd 8 +.Sh HISTORY +These +functions appeared in +.Bx 4.2 . diff --git a/man3/re_comp.3 b/man3/re_comp.3 new file mode 100644 index 000000000..d5976332f --- /dev/null +++ b/man3/re_comp.3 @@ -0,0 +1,69 @@ +.\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Wed Jun 14 16:10:28 BST 1995 Wilf. (G.Wilford@@ee.surrey.ac.uk) +.\" +.TH re_comp 3 1995-07-14 Linux "GNU" +.SH NAME +re_comp, re_exec \- BSD regex functions +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "char *re_comp(char *" regex ); +.br +.BI "int re_exec(char *" string ); +.SH DESCRIPTION +.B re_comp +is used to compile the null-terminated regular expression pointed to by +.IR regex . +The compiled pattern occupies a static area, the pattern buffer, +which is overwritten by subsequent use of +.BR re_comp . +If +.I regex +is +.BR NULL , +no operation is performed and the pattern buffer's contents are not +altered. + +.B re_exec +is used to assess whether the null-terminated string pointed to by +.I string +matches the previously compiled +.IR regex . +.SH "RETURN VALUE" +.B re_comp +returns +.B NULL +on successful compilation of +.I regex +otherwise it returns a pointer to an appropriate error message. + +.B re_exec +returns 1 for a successful match, zero for failure. +.SH "CONFORMING TO" +BSD 4.3 +.SH "SEE ALSO" +.BR regex (7) +.B "GNU regex manual" diff --git a/man3/re_exec.3 b/man3/re_exec.3 new file mode 100644 index 000000000..36aba3917 --- /dev/null +++ b/man3/re_exec.3 @@ -0,0 +1 @@ +.so man3/re_comp.3 diff --git a/man3/readdir.3 b/man3/readdir.3 new file mode 100644 index 000000000..95ba9c3a6 --- /dev/null +++ b/man3/readdir.3 @@ -0,0 +1,79 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 16:09:49 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 22 July 1996 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH READDIR 3 1996-04-22 "" "Linux Programmer's Manual" +.SH NAME +readdir \- read a directory +.SH SYNOPSIS +.nf +.B #include +.sp +.B #include +.sp +.BI "struct dirent *readdir(DIR *" dir ); +.fi +.SH DESCRIPTION +The \fBreaddir()\fP function returns a pointer to a dirent structure +representing the next directory entry in the directory stream pointed +to by \fIdir\fP. It returns NULL on reaching the end-of-file or if +an error occurred. +.PP +According to POSIX, the +.I dirent +structure contains a field +.I "char d_name[]" +of unspecified size, with at most +.B NAME_MAX +characters preceding the terminating null character. +Use of other fields will harm the portability of your programs. +POSIX 1003.1-2001 also documents the field +.I "ino_t d_ino" +as an XSI extension. +.PP +The data returned by \fBreaddir()\fP may be overwritten by subsequent +calls to \fBreaddir()\fP for the same directory stream. +.SH "RETURN VALUE" +The \fBreaddir()\fP function returns a pointer to a dirent structure, or +NULL if an error occurs or end-of-file is reached. +.SH ERRORS +.TP +.B EBADF +Invalid directory stream descriptor \fIdir\fP. +.SH "CONFORMING TO" +SVID 3, BSD 4.3, POSIX 1003.1-2001 +.SH "SEE ALSO" +.BR read (2), +.BR closedir (3), +.BR dirfd (3), +.BR opendir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) diff --git a/man3/realloc.3 b/man3/realloc.3 new file mode 100644 index 000000000..a4b9d4455 --- /dev/null +++ b/man3/realloc.3 @@ -0,0 +1 @@ +.so man3/malloc.3 diff --git a/man3/realpath.3 b/man3/realpath.3 new file mode 100644 index 000000000..66de0a11b --- /dev/null +++ b/man3/realpath.3 @@ -0,0 +1,149 @@ +.\" Copyright (C) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Rewritten old page, 990824, aeb@cwi.nl +.\" +.TH REALPATH 3 1999-08-24 "" "Linux Programmer's Manual" +.SH NAME +realpath \- return the canonicalized absolute pathname +.SH SYNOPSIS +.nf +.B #include +.B #include +.sp +.BI "char *realpath(const char *" path ", char *" resolved_path ); +.SH DESCRIPTION +.B realpath +expands all symbolic links and resolves references +to +.IR '/./' ", " '/../' +and extra +.I '/' +characters in the null terminated string named by +.I path +and stores the canonicalized absolute pathname in the buffer of size +.B PATH_MAX +named by +.IR resolved_path . +The resulting path will have no symbolic link, +.I '/./' +or +.I '/../' +components. +.SH "RETURN VALUE" +If there is no error, it returns a pointer to the +.IR resolved_path . + +Otherwise it returns a NULL pointer, and the contents +of the array +.I resolved_path +are undefined. The global variable +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Read or search permission was denied for a component of the path prefix. +.TP +.B EINVAL +Either +.I path +or +.I resolved_path +is NULL. (In libc5 this would just cause a segfault.) +.TP +.B EIO +An I/O error occurred while reading from the file system. +.TP +.B ELOOP +Too many symbolic links were encountered in translating the pathname. +.TP +.B ENAMETOOLONG +A component of a path name exceeded +.B NAME_MAX +characters, or an entire path name exceeded +.B PATH_MAX +characters. +.TP +.B ENOENT +The named file does not exist. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.SH BUGS +Never use this function. It is broken by design since it is +impossible to determine a suitable size for the output buffer. +According to POSIX a buffer of size PATH_MAX suffices, but +PATH_MAX need not be a defined constant, and may have to be +obtained using +.IR pathconf() . +And asking +.I pathconf() +does not really help, since on the one hand POSIX warns that +the result of +.I pathconf() +may be huge and unsuitable for mallocing memory. And on the other +hand +.I pathconf() +may return \-1 to signify that PATH_MAX is not bounded. +.LP +The libc4 and libc5 implementation contains a buffer overflow +(fixed in libc-5.4.13). +Thus, suid programs like mount need a private version. +.SH HISTORY +The +.B realpath +function first appeared in BSD 4.4, contributed by Jan-Simon Pendry. +In Linux this function appears in libc 4.5.21. +.SH "CONFORMING TO" +In BSD 4.4 and Solaris the limit on the pathname length is MAXPATHLEN +(found in ). The SUSv2 prescribes PATH_MAX and +NAME_MAX, as found in or provided by the +.I pathconf() +function. A typical source fragment would be +.LP +.RS +.nf +#ifdef PATH_MAX + path_max = PATH_MAX; +#else + path_max = pathconf (path, _PC_PATH_MAX); + if (path_max <= 0) + path_max = 4096; +#endif +.fi +.RE +(But see the BUGS section.) +.LP +The BSD 4.4, Linux and SUSv2 versions always return an absolute +path name. Solaris may return a relative path name when the +.I path +argument is relative. +The prototype of +.B realpath +is given in in libc4 and libc5, +but in everywhere else. +.SH "SEE ALSO" +.BR readlink (2), +.BR getcwd (3), +.BR pathconf (3), +.BR sysconf (3) diff --git a/man3/recno.3 b/man3/recno.3 new file mode 100644 index 000000000..edacdc96a --- /dev/null +++ b/man3/recno.3 @@ -0,0 +1,216 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)recno.3 8.5 (Berkeley) 8/18/94 +.\" +.TH RECNO 3 1994-08-18 +.UC 7 +.SH NAME +recno \- record number database access method +.SH SYNOPSIS +.nf +.ft B +#include +#include +.ft R +.fi +.SH DESCRIPTION +The routine +.IR dbopen +is the library interface to database files. +One of the supported file formats is record number files. +The general description of the database access methods is in +.IR dbopen (3), +this manual page describes only the recno specific information. +.PP +The record number data structure is either variable or fixed-length +records stored in a flat-file format, accessed by the logical record +number. +The existence of record number five implies the existence of records +one through four, and the deletion of record number one causes +record number five to be renumbered to record number four, as well +as the cursor, if positioned after record number one, to shift down +one record. +.PP +The recno access method specific data structure provided to +.I dbopen +is defined in the include file as follows: +.PP +typedef struct { +.RS +u_long flags; +.br +u_int cachesize; +.br +u_int psize; +.br +int lorder; +.br +size_t reclen; +.br +u_char bval; +.br +char *bfname; +.RE +} RECNOINFO; +.PP +The elements of this structure are defined as follows: +.TP +flags +The flag value is specified by +.IR or 'ing +any of the following values: +.RS +.TP +R_FIXEDLEN +The records are fixed-length, not byte delimited. +The structure element +.I reclen +specifies the length of the record, and the structure element +.I bval +is used as the pad character. +Any records, inserted into the database, that are less than +.I reclen +bytes long are automatically padded. +.TP +R_NOKEY +In the interface specified by +.IR dbopen , +the sequential record retrieval fills in both the caller's key and +data structures. +If the R_NOKEY flag is specified, the +.I cursor +routines are not required to fill in the key structure. +This permits applications to retrieve records at the end of files without +reading all of the intervening records. +.TP +R_SNAPSHOT +This flag requires that a snapshot of the file be taken when +.I dbopen +is called, instead of permitting any unmodified records to be read from +the original file. +.RE +.TP +cachesize +A suggested maximum size, in bytes, of the memory cache. +This value is +.B only +advisory, and the access method will allocate more memory rather than fail. +If +.I cachesize +is 0 (no size is specified) a default cache is used. +.TP +psize +The recno access method stores the in-memory copies of its records +in a btree. +This value is the size (in bytes) of the pages used for nodes in that tree. +If +.I psize +is 0 (no page size is specified) a page size is chosen based on the +underlying file system I/O block size. +See +.IR btree (3) +for more information. +.TP +lorder +The byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.I lorder +is 0 (no order is specified) the current host order is used. +.TP +reclen +The length of a fixed-length record. +.TP +bval +The delimiting byte to be used to mark the end of a record for +variable-length records, and the pad character for fixed-length +records. +If no value is specified, newlines (``\en'') are used to mark the end +of variable-length records and fixed-length records are padded with +spaces. +.TP +bfname +The recno access method stores the in-memory copies of its records +in a btree. +If bfname is non-NULL, it specifies the name of the btree file, +as if specified as the file name for a dbopen of a btree file. +.PP +The data part of the key/data pair used by the recno access method +is the same as other access methods. +The key is different. +The +.I data +field of the key should be a pointer to a memory location of type +.IR recno_t , +as defined in the include file. +This type is normally the largest unsigned integral type available to +the implementation. +The +.I size +field of the key should be the size of that type. +.PP +Because there can be no meta-data associated with the underlying +recno access method files, any changes made to the default values +(e.g. fixed record length or byte separator value) must be explicitly +specified each time the file is opened. +.PP +In the interface specified by +.IR dbopen , +using the +.I put +interface to create a new record will cause the creation of multiple, +empty records if the record number is more than one greater than the +largest record currently in the database. +.SH ERRORS +The +.I recno +access method routines may fail and set +.I errno +for any of the errors specified for the library routine +.IR dbopen (3) +or the following: +.TP +[EINVAL] +An attempt was made to add a record to a fixed-length database that +was too large to fit. +.SH "SEE ALSO" +.IR btree (3) +.IR dbopen (3), +.IR hash (3), +.IR mpool (3), +.sp +.IR "Document Processing in a Relational Database System" , +Michael Stonebraker, Heidi Stettner, Joseph Kalash, Antonin Guttman, +Nadene Lynn, Memorandum No. UCB/ERL M82/32, May 1982. +.SH BUGS +Only big and little endian byte order is supported. diff --git a/man3/regcomp.3 b/man3/regcomp.3 new file mode 100644 index 000000000..c0daaf0ff --- /dev/null +++ b/man3/regcomp.3 @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man3/regerror.3 b/man3/regerror.3 new file mode 100644 index 000000000..c0daaf0ff --- /dev/null +++ b/man3/regerror.3 @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man3/regex.3 b/man3/regex.3 new file mode 100644 index 000000000..e7c873905 --- /dev/null +++ b/man3/regex.3 @@ -0,0 +1,300 @@ +.\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Wed Jun 14 16:10:28 BST 1995 Wilf. (G.Wilford@ee.surrey.ac.uk) +.\" Tiny change in formatting - aeb, 950812 +.\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" +.\" show the synopsis section nicely +.de xx +.in \\n(INu+\\$1 +.ti -\\$1 +.. +.TH REGCOMP 3 1998-05-08 GNU "Linux Programmer's Manual" +.SH NAME +regcomp, regexec, regerror, regfree \- POSIX regex functions +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.xx \w'\fBint\ regcomp(\fR'u +.BI "int\ regcomp(regex_t *" preg ", const char *" regex , +.BI "int " cflags ); +.xx \w'\fBint\ regexec(\fR'u +.BI "int\ regexec(const regex_t *" preg ", const char *" string , +.BI "size_t " nmatch ", regmatch_t " pmatch[] , +.BI "int " eflags ); +.xx \w'\fBsize_t\ regerror(\fR'u +.BI "size_t\ regerror(int " errcode , +.BI "const regex_t *" preg ", char *" errbuf , +.BI "size_t " errbuf_size ); +.xx \w'\fBvoid\ regfree(\fR' +.BI "void\ regfree(regex_t *" preg ); +.SH "POSIX REGEX COMPILING" +.B regcomp +is used to compile a regular expression into a form that is suitable +for subsequent +.B regexec +searches. + +.B regcomp +is supplied with +.IR preg , +a pointer to a pattern buffer storage area; +.IR regex , +a pointer to the null-terminated string and +.IR cflags , +flags used to determine the type of compilation. + +All regular expression searching must be done via a compiled pattern +buffer, thus +.B regexec +must always be supplied with the address of a +.B regcomp +initialized pattern buffer. + +.I cflags +may be the +.RB bitwise- or +of one or more of the following: +.TP +.B REG_EXTENDED +Use +.B POSIX +Extended Regular Expression syntax when interpreting +.IR regex . +If not set, +.B POSIX +Basic Regular Expression syntax is used. +.TP +.B REG_ICASE +Do not differentiate case. Subsequent +.B regexec +searches using this pattern buffer will be case insensitive. +.TP +.B REG_NOSUB +Support for substring addressing of matches is not required. +The +.I nmatch +and +.I pmatch +parameters to +.B regexec +are ignored if the pattern buffer supplied was compiled with this flag set. +.TP +.B REG_NEWLINE +Match-any-character operators don't match a newline. + +A non-matching list +.RB ( [^...] ) +not containing a newline does not match a newline. + +Match-beginning-of-line operator +.RB ( ^ ) +matches the empty string immediately after a newline, regardless of +whether +.IR eflags , +the execution flags of +.BR regexec , +contains +.BR REG_NOTBOL . + +Match-end-of-line operator +.RB ( $ ) +matches the empty string immediately before a newline, regardless of +whether +.IR eflags +contains +.BR REG_NOTEOL . +.SH "POSIX REGEX MATCHING" +.B regexec +is used to match a null-terminated string +against the precompiled pattern buffer, +.IR preg . +.I nmatch +and +.I pmatch +are used to provide information regarding the location of any matches. +.I eflags +may be the +.RB bitwise- or +of one or both of +.B REG_NOTBOL +and +.B REG_NOTEOL +which cause changes in matching behaviour described below. +.TP +.B REG_NOTBOL +The match-beginning-of-line operator always fails to match (but see the +compilation flag +.B REG_NEWLINE +above) +This flag may be used when different portions of a string are passed to +.B regexec +and the beginning of the string should not be interpreted as the +beginning of the line. +.TP +.B REG_NOTEOL +The match-end-of-line operator always fails to match (but see the +compilation flag +.B REG_NEWLINE +above) +.SS "BYTE OFFSETS" +Unless +.B REG_NOSUB +was set for the compilation of the pattern buffer, it is possible to +obtain substring match addressing information. +.I pmatch +must be dimensioned to have at least +.I nmatch +elements. +These are filled in by +.BR regexec +with substring match addresses. Any unused structure elements +will contain the value -1. + +The +.B regmatch_t +structure which is the type of +.I pmatch +is defined in +.IR regex.h . + +.RS +.B typedef struct +.br +.B { +.br +.BI " regoff_t " rm_so ; +.br +.BI " regoff_t " rm_eo ; +.br +.B } +.B regmatch_t; +.RE + +Each +.I rm_so +element that is not -1 indicates the start offset of the next largest +substring match within the string. The relative +.I rm_eo +element indicates the end offset of the match. +.SH "POSIX ERROR REPORTING" +.B regerror +is used to turn the error codes that can be returned by both +.B regcomp +and +.B regexec +into error message strings. + +.B regerror +is passed the error code, +.IR errcode , +the pattern buffer, +.IR preg , +a pointer to a character string buffer, +.IR errbuf , +and the size of the string buffer, +.IR errbuf_size . +It returns the size of the +.I errbuf +required to contain the null-terminated error message string. If both +.I errbuf +and +.I errbuf_size +are non-zero, +.I errbuf +is filled in with the first +.I "errbuf_size - 1" +characters of the error message and a terminating null. +.SH "POSIX PATTERN BUFFER FREEING" +Supplying +.B regfree +with a precompiled pattern buffer, +.I preg +will free the memory allocated to the pattern buffer by the compiling +process, +.BR regcomp . +.SH "RETURN VALUE" +.B regcomp +returns zero for a successful compilation or an error code for failure. + +.B regexec +returns zero for a successful match or +.B REG_NOMATCH +for failure. +.SH ERRORS +The following errors can be returned by +.BR regcomp : +.TP +.B REG_BADBR +Invalid use of back reference operator. +.TP +.B REG_BADPAT +Invalid use of pattern operators such as group or list. +.TP +.B REG_BADRPT +Invalid use of repetition operators such as using +.RB ` * ' +as the first character. +.TP +.B REG_EBRACE +Un-matched brace interval operators. +.TP +.B REG_EBRACK +Un-matched bracket list operators. +.TP +.B REG_ECOLLATE +Invalid collating element. +.TP +.B REG_ECTYPE +Unknown character class name. +.TP +.B REG_EEND +Non specific error. This is not defined by POSIX.2. +.TP +.B REG_EESCAPE +Trailing backslash. +.TP +.B REG_EPAREN +Un-matched parenthesis group operators. +.TP +.B REG_ERANGE +Invalid use of the range operator, eg. the ending point of the range +occurs prior to the starting point. +.TP +.B REG_ESIZE +Compiled regular expression requires a pattern buffer larger than 64Kb. +This is not defined by POSIX.2. +.TP +.B REG_ESPACE +The regex routines ran out of memory. +.TP +.B REG_ESUBREG +Invalid back reference to a subexpression. +.SH "CONFORMING TO" +POSIX.2 +.SH "SEE ALSO" +.BR regex (7), +GNU regex manual + diff --git a/man3/regexec.3 b/man3/regexec.3 new file mode 100644 index 000000000..c0daaf0ff --- /dev/null +++ b/man3/regexec.3 @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man3/regfree.3 b/man3/regfree.3 new file mode 100644 index 000000000..c0daaf0ff --- /dev/null +++ b/man3/regfree.3 @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man3/registerrpc.3 b/man3/registerrpc.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/registerrpc.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/remainder.3 b/man3/remainder.3 new file mode 100644 index 000000000..34fad7e53 --- /dev/null +++ b/man3/remainder.3 @@ -0,0 +1,101 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-10 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Modified 2003-11-18, 2004-10-05 aeb +.\" +.TH REMAINDER 3 2003-11-18 "" "Linux Programmer's Manual" +.SH NAME +drem, dremf, dreml, remainder, remainderf, remainderl \- floating-point remainder function +.SH SYNOPSIS +.nf +.B #include +.sp +/* The C99 versions */ +.BI "double remainder(double " x ", double " y ); +.BI "float remainderf(float " x ", float " y ); +.BI "long double remainderl(long double " x ", long double " y ); +.sp +/* Obsolete synonyms */ +.BI "double drem(double " x ", double " y ); +.BI "float dremf(float " x ", float " y ); +.BI "long double dreml(long double " x ", long double " y ); +.sp +.fi +Link with \-lm. +.SH DESCRIPTION +The +.B remainder() +function computes the remainder of dividing +.I x +by +.IR y . +The return value is +.IR x " - " n " * " y , +where +.I n +is the value +.IR x " / " y , +rounded to the nearest integer. +If this quotient is 1/2 (mod 1), it is rounded to the nearest even number +(independent of the current rounding mode). +If the return value is 0, it has the sign of +.IR x . +.LP +The +.B drem() +function does precisely the same thing. +.SH "RETURN VALUE" +The +.B remainder() +function returns the remainder, unless +.I y +is zero, when the function fails and +.I errno +is set. +.SH ERRORS +.TP +.B EDOM +The denominator +.I y +is zero. +.SH "CONFORMING TO" +IEC 60559. The three +.B remainder*() +functions are from C99. +The function +.B drem() +is from BSD 4.3. The float and long double variants +.B dremf() +and +.B dreml() +exist on some systems, such as Tru64 and glibc2. +.SH EXAMPLE +The call "remainder(29.0, 3.0)" returns \-1. +.SH "SEE ALSO" +.BR fmod (3) diff --git a/man3/remainderf.3 b/man3/remainderf.3 new file mode 100644 index 000000000..b7a5b23bf --- /dev/null +++ b/man3/remainderf.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man3/remainderl.3 b/man3/remainderl.3 new file mode 100644 index 000000000..b7a5b23bf --- /dev/null +++ b/man3/remainderl.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man3/remove.3 b/man3/remove.3 new file mode 100644 index 000000000..e8417fe61 --- /dev/null +++ b/man3/remove.3 @@ -0,0 +1,87 @@ +.\" This file is derived from unlink.2, which has the following copyright: +.\" +.\" --snip-- +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Ian Jackson. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" --snip-- +.\" +.\" Edited into remove.3 shape by: +.\" Graeme W. Wilford (G.Wilford@ee.surrey.ac.uk) on 13th July 1994 +.\" +.TH REMOVE 3 1994-07-13 Linux "GNU" +.SH NAME +remove \- delete a name and possibly the file it refers to +.SH SYNOPSIS +.B #include +.sp +.BI "int remove(const char *" pathname ); +.SH DESCRIPTION +.B remove +deletes a name from the filesystem. +It calls +.I unlink +for files, and +.I rmdir +for directories. + +If the removed name was the +last link to a file and no processes have the file open the file is +deleted and the space it was using is made available for reuse. + +If the name was the last link to a file but any processes still have +the file open the file will remain in existence until the last file +descriptor referring to it is closed. + +If the name referred to a symbolic link the link is removed. + +If the name referred to a socket, fifo or device the name for it is +removed but processes which have the object open may continue to use +it. +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +The errors that occur are those for +.BR unlink (2) +and +.BR rmdir (2). +.SH "CONFORMING TO" +ANSI C, SVID, AT&T, POSIX, X/OPEN, BSD 4.3 +.SH BUGS +Infelicities in the protocol underlying NFS can cause the unexpected +disappearance of files which are still being used. +.SH NOTE +Under libc4 and libc5, +.B remove +was an alias for unlink (and hence would not remove directories). +.SH "SEE ALSO" +.BR rm (1), +.BR link (2), +.BR mknod (2), +.BR open (2), +.BR rename (2), +.BR rmdir (2), +.BR unlink (2), +.BR mkfifo (3), +.BR unlink (8) diff --git a/man3/remque.3 b/man3/remque.3 new file mode 100644 index 000000000..a0c88361a --- /dev/null +++ b/man3/remque.3 @@ -0,0 +1 @@ +.so man3/insque.3 diff --git a/man3/remquo.3 b/man3/remquo.3 new file mode 100644 index 000000000..ea4911f78 --- /dev/null +++ b/man3/remquo.3 @@ -0,0 +1,54 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" based on glibc infopages +.\" polished, aeb +.TH REMQUO 3 2002-08-10 "gnu" "Linux Programmer's Manual" +.SH NAME +remquo, remquof, remquol \- remainder and part of quotient +.SH SYNOPSIS +.nf +#define _ISOC99_SOURCE +.br +.B #include +.sp +.BI "double remquo(double " x ", double " y ", int *" quo ); +.sp +.BI "float remquof(float " x ", float " y ", int *" quo ); +.sp +.BI "long double remquol(long double " x ", long double " y ", int *" quo ); +.sp +.fi +.SH DESCRIPTION +These functions compute the remainder and part of the quotient +upon division of +.I x +by +.IR y . +A few bits of the quotient are stored via the +.I quo +pointer. The remainder is returned as function value. + +The value of the remainder is the same as that computed by the +.BR remainder (3) +function. + +The value stored via the +.I quo +pointer has the sign of +.IR x / y +and agrees with the quotient in at least the low order 3 bits. + +For example, remquo(29.0,3.0) returns \-1.0 and might store 2. +Note that the actual quotient might not fit in an integer. + +.\" A possible application of this function might be the computation +.\" of sin(x). Compute remquo(x, pi/2, &quo) or so. +.\" +.\" glibc, UnixWare: return 3 bits +.\" MacOS 10: return 7 bits +.SH "CONFORMING TO" +C99 +.SH "SEE ALSO" +.BR fmod (3), +.BR logb (3), +.BR remainder (3) diff --git a/man3/remquof.3 b/man3/remquof.3 new file mode 100644 index 000000000..458f05120 --- /dev/null +++ b/man3/remquof.3 @@ -0,0 +1 @@ +.so man3/remquo.3 diff --git a/man3/remquol.3 b/man3/remquol.3 new file mode 100644 index 000000000..458f05120 --- /dev/null +++ b/man3/remquol.3 @@ -0,0 +1 @@ +.so man3/remquo.3 diff --git a/man3/res_init.3 b/man3/res_init.3 new file mode 100644 index 000000000..87a6d0e83 --- /dev/null +++ b/man3/res_init.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/res_mkquery.3 b/man3/res_mkquery.3 new file mode 100644 index 000000000..87a6d0e83 --- /dev/null +++ b/man3/res_mkquery.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/res_query.3 b/man3/res_query.3 new file mode 100644 index 000000000..87a6d0e83 --- /dev/null +++ b/man3/res_query.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/res_querydomain.3 b/man3/res_querydomain.3 new file mode 100644 index 000000000..87a6d0e83 --- /dev/null +++ b/man3/res_querydomain.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/res_search.3 b/man3/res_search.3 new file mode 100644 index 000000000..87a6d0e83 --- /dev/null +++ b/man3/res_search.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/res_send.3 b/man3/res_send.3 new file mode 100644 index 000000000..87a6d0e83 --- /dev/null +++ b/man3/res_send.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/resolver.3 b/man3/resolver.3 new file mode 100644 index 000000000..874e1ed2e --- /dev/null +++ b/man3/resolver.3 @@ -0,0 +1,203 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2004-10-31 by aeb +.\" +.TH RESOLVER 3 2004-10-31 "BSD" "Linux Programmer's Manual" +.SH NAME +res_init, res_query, res_search, res_querydomain, res_mkquery, res_send, +dn_comp, dn_expand \- resolver routines +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.B extern struct state _res; +.sp +.B int res_init(void); +.sp +.BI "int res_query(const char *" dname ", int " class ", int " type , +.RS +.BI "unsigned char *" answer ", int " anslen ); +.RE +.sp +.BI "int res_search(const char *" dname ", int " class ", int " type , +.RS +.BI "unsigned char *" answer ", int " anslen ); +.RE +.sp +.BI "int res_querydomain(const char *" name ", const char *" domain , +.RS +.BI "int " class ", int " type ", unsigned char *" answer , +.BI "int " anslen ); +.RE +.sp +.BI "int res_mkquery(int " op ", const char *" dname ", int " class , +.RS +.BI "int " type ", char *" data ", int " datalen ", struct rrec *" newrr , +.BI "char *" buf ", int " buflen ); +.RE +.sp +.BI "int res_send(const char *" msg ", int " msglen ", char *" answer , +.RS +.BI "int " anslen ); +.RE +.sp +.BI "int dn_comp(unsigned char *" exp_dn ", unsigned char *" comp_dn , +.RS +.BI "int " length ", unsigned char **" dnptrs ", unsigned char *" exp_dn , +.BI "unsigned char **" lastdnptr ); +.RE +.sp +.BI "int dn_expand(unsigned char *" msg ", unsigned char *" eomorig , +.RS +.BI "unsigned char *" comp_dn ", unsigned char *" exp_dn , +.BI "int " length ); +.RE +.fi +.sp +Link with \-lresolv. +.SH DESCRIPTION +These functions make queries to and interpret the responses from Internet +domain name servers. +.PP +The \fBres_init()\fP function reads the configuration files (see +resolv+(8)) to get the default domain name, search order and name +server address(es). If no server is given, the local host is tried. +If no domain is given, that associated with the local host is used. +It can be overridden with the environment variable LOCALDOMAIN. +\fBres_init()\fP is normally executed by the first call to one of the +other functions. +.PP +The \fBres_query()\fP function queries the name server for the +fully-qualified domain name \fIname\fP of specified \fItype\fP and +\fIclass\fP. The reply is left in the buffer \fIanswer\fP of length +\fIanslen\fP supplied by the caller. +.PP +The \fBres_search()\fP function makes a query and waits for the response +like \fBres_query()\fP, but in addition implements the default and search +rules controlled by RES_DEFNAMES and RES_DNSRCH (see description of +\fI_res\fP options below). +.PP +The \fBres_querydomain()\fP function makes a query using \fBres_query()\fP +on the concatenation of \fIname\fP and \fIdomain\fP. +.PP +The following functions are lower-level routines used by \fBres_query()\fP. +.PP +The \fBres_mkquery()\fP function constructs a query message in \fIbuf\fP +of length \fIbuflen\fP for the domain name \fIdname\fP. The query type +\fIop\fP is usually QUERY, but can be any of the types defined in +\fI\fP. \fInewrr\fP is currently unused. +.PP +The \fBres_send()\fP function sends a pre-formatted query given in +\fImsg\fP of length \fImsglen\fP and returns the answer in \fIanswer\fP +which is of length \fIanslen\fP. It will call \fBres_init()\fP, if it +has not already been called. +.PP +The \fBdn_comp()\fP function compresses the domain name \fIexp_dn\fP +and stores it in the buffer \fIcomp_dn\fP of length \fIlength\fP. +The compression uses an array of pointers \fIdnptrs\fP to previously +compressed names in the current message. The first pointer points +to the beginning of the message and the list ends with NULL. The limit +of the array is specified by \fIlastdnptr\fP. if \fIdnptr\fP is NULL, +domain names are not compressed. If \fIlastdnptr\fP is NULL, the list +of labels is not updated. +.PP +The \fPdn_expand()\fP function expands the compressed domain name +\fIcomp_dn\fP to a full domain name, which is placed in the buffer +\fIexp_dn\fP of size \fIlength\fP. The compressed name is contained +in a query or reply message, and \fImsg\fP points to the beginning of +the message. +.PP +The resolver routines use global configuration and state information +contained in the structure \fI_res\fP, which is defined in +\fI\fP. The only field that is normally manipulated by the +user is \fI_res.options\fP. This field can contain the bitwise ``or'' +of the following options: +.sp +.TP +.B RES_INIT +True if \fBres_init()\fP has been called. +.TP +.B RES_DEBUG +Print debugging messages. +.TP +.B RES_AAONLY +Accept authoritative answers only. \fBres_send()\fP continues until +it fins an authoritative answer or returns an error. [Not currently +implemented]. +.TP +.B RES_USEVC +Use TCP connections for queries rather than UDP datagrams. +.TP +.B RES_PRIMARY +Query primary domain name server only. +.TP +.B RES_IGNTC +Ignore truncation errors. Don't retry with TCP. [Not currently +implemented]. +.TP +.B RES_RECURSE +Set the recursion desired bit in queries. Recursion is carried out +by the domain name server, not by \fBres_send()\fP. [Enabled by +default]. +.TP +.B RES_DEFNAMES +If set, \fBres_search()\fP will append the default domain name to +single component names, ie. those that do not contain a dot. +[Enabled by default]. +.TP +.B RES_STAYOPEN +Used with RES_USEVC to keep the TCP connection open between queries. +.TP +.B RES_DNSRCH +If set, \fBres_search()\fP will search for host names in the current +domain and in parent domains. This option is used by +.BR gethostbyname (3). +[Enabled by default]. +.SH "RETURN VALUE" +The \fBres_init()\fP function returns 0 on success, or \-1 if an error +occurs. +.PP +The \fBres_query()\fP, \fBres_search()\fP, \fBres_querydomain()\fP, +\fBres_mkquery()\fP and \fBres_send()\fP functions return the length +of the response, or \-1 if an error occurs. +.PP +The \fBdn_comp()\fP and \fBdn_expand()\fP functions return the length +of the compressed name, or \-1 if an error occurs. +.SH FILES +.nf +/etc/resolv.conf resolver configuration file +/etc/host.conf resolver configuration file +.fi +.SH "CONFORMING TO" +BSD 4.3 +.SH "SEE ALSO" +.BR gethostbyname (3), +.BR hostname (7), +.BR named (8), +.BR resolv+ (8) diff --git a/man3/rewind.3 b/man3/rewind.3 new file mode 100644 index 000000000..a1487b5a8 --- /dev/null +++ b/man3/rewind.3 @@ -0,0 +1 @@ +.so man3/fseek.3 diff --git a/man3/rewinddir.3 b/man3/rewinddir.3 new file mode 100644 index 000000000..f8224c4bd --- /dev/null +++ b/man3/rewinddir.3 @@ -0,0 +1,53 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:29:11 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.TH REWINDDIR 3 1995-06-11 "" "Linux Programmer's Manual" +.SH NAME +rewinddir \- reset directory stream +.SH SYNOPSIS +.nf +.B #include +.sp +.B #include +.sp +.BI "void rewinddir(DIR *" dir ); +.fi +.SH DESCRIPTION +The \fBrewinddir()\fP function resets the position of the directory +stream \fIdir\fP to the beginning of the directory. +.SH "RETURN VALUE" +The \fBrewinddir()\fP function returns no value. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3 +.SH "SEE ALSO" +.BR closedir (3), +.BR opendir (3), +.BR readdir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) diff --git a/man3/rindex.3 b/man3/rindex.3 new file mode 100644 index 000000000..a9cd4b342 --- /dev/null +++ b/man3/rindex.3 @@ -0,0 +1 @@ +.so man3/index.3 diff --git a/man3/rint.3 b/man3/rint.3 new file mode 100644 index 000000000..e8a4a9c78 --- /dev/null +++ b/man3/rint.3 @@ -0,0 +1,87 @@ +.\" Copyright 2001 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH RINT 3 2001-05-31 "" "Linux Programmer's Manual" +.SH NAME +nearbyint, nearbyintf, nearbyintl, rint, rintf, rintl \- round to nearest integer +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double nearbyint(double " x ); +.br +.BI "float nearbyintf(float " x ); +.br +.BI "long double nearbyintl(long double " x ); +.sp +.BI "double rint(double " x ); +.br +.BI "float rintf(float " x ); +.br +.BI "long double rintl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The +.B nearbyint +functions round their argument to an integer value in floating point +format, using the current rounding direction and without raising the +.I inexact +exception. +.LP +The +.B rint +functions do the same, but will raise the +.I inexact +exception when the result differs in value from the argument. +.SH "RETURN VALUE" +The rounded integer value. If \fIx\fP is integral or infinite, +\fIx\fP itself is returned. +.SH ERRORS +No errors other than EDOM and ERANGE can occur. +If \fIx\fP is NaN, then NaN is returned and +.I errno +may be set to EDOM. +.SH NOTES +SUSv2 and POSIX 1003.1-2001 contain text about overflow (which might set +.I errno +to ERANGE, or raise an exception). +In practice, the result cannot overflow on any current machine, +so this error-handling stuff is just nonsense. +(More precisely, overflow can happen only when the maximum value +of the exponent is smaller than the number of mantissa bits. +For the IEEE-754 standard 32-bit and 64-bit floating point numbers +the maximum value of the exponent is 128 (resp. 1024), and the number +of mantissa bits is 24 (resp. 53).) +.SH "CONFORMING TO" +The +.B rint() +function conforms to BSD 4.3. +The other functions are from C99. +.SH "SEE ALSO" +.BR ceil (3), +.BR floor (3), +.BR lrint (3), +.BR nearbyint (3), +.BR round (3), +.BR trunc (3) diff --git a/man3/rintf.3 b/man3/rintf.3 new file mode 100644 index 000000000..3300c2c40 --- /dev/null +++ b/man3/rintf.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man3/rintl.3 b/man3/rintl.3 new file mode 100644 index 000000000..3300c2c40 --- /dev/null +++ b/man3/rintl.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man3/round.3 b/man3/round.3 new file mode 100644 index 000000000..6b376094f --- /dev/null +++ b/man3/round.3 @@ -0,0 +1,69 @@ +.\" Copyright 2001 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH ROUND 3 2001-05-31 "" "Linux Programmer's Manual" +.SH NAME +round, roundf, roundl \- round to nearest integer, away from zero +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double round(double " x ); +.br +.BI "float roundf(float " x ); +.br +.BI "long double roundl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +These functions round \fIx\fP to the nearest integer, but +round halfway cases away from zero (regardless of the current rounding +direction), instead of to the nearest even integer like rint(). +.SH "RETURN VALUE" +The rounded integer value. If \fIx\fP is integral or infinite, +\fIx\fP itself is returned. +.SH ERRORS +No errors other than EDOM and ERANGE can occur. +If \fIx\fP is NaN, then NaN is returned and +.I errno +may be set to EDOM. +.SH NOTES +POSIX 1003.1-2001 contains text about overflow (which might set +.I errno +to ERANGE, or raise an exception). +In practice, the result cannot overflow on any current machine, +so this error-handling stuff is just nonsense. +(More precisely, overflow can happen only when the maximum value +of the exponent is smaller than the number of mantissa bits. +For the IEEE-754 standard 32-bit and 64-bit floating point numbers +the maximum value of the exponent is 128 (resp. 1024), and the number +of mantissa bits is 24 (resp. 53).) +.SH "CONFORMING TO" +C99. +.SH "SEE ALSO" +.BR ceil (3), +.BR floor (3), +.BR lround (3), +.BR nearbyint (3), +.BR rint (3), +.BR trunc (3) diff --git a/man3/roundf.3 b/man3/roundf.3 new file mode 100644 index 000000000..f7ab38670 --- /dev/null +++ b/man3/roundf.3 @@ -0,0 +1 @@ +.so man3/round.3 diff --git a/man3/roundl.3 b/man3/roundl.3 new file mode 100644 index 000000000..f7ab38670 --- /dev/null +++ b/man3/roundl.3 @@ -0,0 +1 @@ +.so man3/round.3 diff --git a/man3/rpc.3 b/man3/rpc.3 new file mode 100644 index 000000000..35d673ce6 --- /dev/null +++ b/man3/rpc.3 @@ -0,0 +1,1743 @@ +.\" @(#)rpc.3n 2.4 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI +.TH RPC 3 1988-02-16 +.SH NAME +rpc \- library routines for remote procedure calls +.SH "SYNOPSIS AND DESCRIPTION" +These routines allow C programs to make procedure +calls on other machines across the network. +First, the client calls a procedure to send a +data packet to the server. +Upon receipt of the packet, the server calls a dispatch routine +to perform the requested service, and then sends back a +reply. +Finally, the procedure call returns to the client. +.LP +Routines that are used for Secure RPC (DES authentication) are described in +.BR rpc_secure (3). +Secure RPC can be used only if DES encryption is available. +.LP +.ft B +.nf +.sp .5 +#include +.fi +.ft R +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +void +auth_destroy(auth) +\s-1AUTH\s0 *auth; +.fi +.ft R +.IP +A macro that destroys the authentication information associated with +.IR auth . +Destruction usually involves deallocation of private data +structures. The use of +.I auth +is undefined after calling +.BR auth_destroy() . +.br +.if t .ne 6 +.LP +.ft B +.nf +.sp .5 +\s-1AUTH\s0 * +authnone_create() +.fi +.ft R +.IP +Create and returns an +.SM RPC +authentication handle that passes nonusable authentication +information with each remote procedure call. This is the +default authentication used by +.SM RPC. +.if t .ne 10 +.LP +.ft B +.nf +.sp .5 +\s-1AUTH\s0 * +authunix_create(host, uid, gid, len, aup_gids) +char *host; +int uid, gid, len, *aup.gids; +.fi +.ft R +.IP +Create and return an +.SM RPC +authentication handle that contains +.UX +authentication information. +The parameter +.I host +is the name of the machine on which the information was +created; +.I uid +is the user's user +.SM ID ; +.I gid +is the user's current group +.SM ID ; +.I len +and +.I aup_gids +refer to a counted array of groups to which the user belongs. +It is easy to impersonate a user. +.br +.if t .ne 5 +.LP +.ft B +.nf +.sp .5 +\s-1AUTH\s0 * +authunix_create_default() +.fi +.ft R +.IP +Calls +.B authunix_create() +with the appropriate parameters. +.br +.if t .ne 13 +.LP +.ft B +.nf +.sp .5 +callrpc(host, prognum, versnum, procnum, inproc, in, outproc, out) +char *host; +u_long prognum, versnum, procnum; +char *in, *out; +xdrproc_t inproc, outproc; +.fi +.ft R +.IP +Call the remote procedure associated with +.IR prognum , +.IR versnum , +and +.I procnum +on the machine, +.IR host . +The parameter +.I in +is the address of the procedure's argument(s), and +.I out +is the address of where to place the result(s); +.I inproc +is used to encode the procedure's parameters, and +.I outproc +is used to decode the procedure's results. +This routine returns zero if it succeeds, or the value of +.B "enum clnt_stat" +cast to an integer if it fails. +The routine +.B clnt_perrno() +is handy for translating failure statuses into messages. +.IP +Warning: calling remote procedures with this routine +uses +.SM UDP/IP +as a transport; see +.B clntudp_create() +for restrictions. +You do not have control of timeouts or authentication using +this routine. +.br +.if t .ne 16 +.LP +.ft B +.nf +.sp .5 +enum clnt_stat +clnt_broadcast(prognum, versnum, procnum, inproc, in, outproc, out, eachresult) +u_long prognum, versnum, procnum; +char *in, *out; +xdrproc_t inproc, outproc; +resultproc_t eachresult; +.fi +.ft R +.IP +Like +.BR callrpc() , +except the call message is broadcast to all locally +connected broadcast nets. Each time it receives a +response, this routine calls +.BR eachresult() , +whose form is: +.IP +.RS 1i +.ft B +.nf +eachresult(out, addr) +char *out; +struct sockaddr_in *addr; +.ft R +.fi +.RE +.IP +where +.I out +is the same as +.I out +passed to +.BR clnt_broadcast() , +except that the remote procedure's output is decoded there; +.I addr +points to the address of the machine that sent the results. +If +.B eachresult() +returns zero, +.B clnt_broadcast() +waits for more replies; otherwise it returns with appropriate +status. +.IP +Warning: broadcast sockets are limited in size to the +maximum transfer unit of the data link. For ethernet, +this value is 1500 bytes. +.br +.if t .ne 13 +.LP +.ft B +.nf +.sp .5 +enum clnt_stat +clnt_call(clnt, procnum, inproc, in, outproc, out, tout) +\s-1CLIENT\s0 *clnt; +u_long +procnum; +xdrproc_t inproc, outproc; +char *in, *out; +struct timeval tout; +.fi +.ft R +.IP +A macro that calls the remote procedure +.I procnum +associated with the client handle, +.IR clnt , +which is obtained with an +.SM RPC +client creation routine such as +.BR clnt_create() . +The parameter +.I in +is the address of the procedure's argument(s), and +.I out +is the address of where to place the result(s); +.I inproc +is used to encode the procedure's parameters, and +.I outproc +is used to decode the procedure's results; +.I tout +is the time allowed for results to come back. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +clnt_destroy(clnt) +\s-1CLIENT\s0 *clnt; +.fi +.ft R +.IP +A macro that destroys the client's +.SM RPC +handle. Destruction usually involves deallocation +of private data structures, including +.I clnt +itself. Use of +.I clnt +is undefined after calling +.BR clnt_destroy() . +If the +.SM RPC +library opened the associated socket, it will close it also. +Otherwise, the socket remains open. +.br +.if t .ne 10 +.LP +.ft B +.nf +.sp .5 +\s-1CLIENT\s0 * +clnt_create(host, prog, vers, proto) +char *host; +u_long prog, vers; +char *proto; +.fi +.ft R +.IP +Generic client creation routine. +.I host +identifies the name of the remote host where the server +is located. +.I proto +indicates which kind of transport protocol to use. The +currently supported values for this field are \(lqudp\(rq +and \(lqtcp\(rq. +Default timeouts are set, but can be modified using +.BR clnt_control() . +.IP +Warning: Using +.SM UDP +has its shortcomings. Since +.SM UDP\s0-based +.SM RPC +messages can only hold up to 8 Kbytes of encoded data, +this transport cannot be used for procedures that take +large arguments or return huge results. +.br +.if t .ne 10 +.LP +.ft B +.nf +.sp .5 +bool_t +clnt_control(cl, req, info) +\s-1CLIENT\s0 *cl; +char *info; +.fi +.ft R +.IP +A macro used to change or retrieve various information +about a client object. +.I req +indicates the type of operation, and +.I info +is a pointer to the information. For both +.SM UDP +and +.SM TCP\s0, +the supported values of +.I req +and their argument types and what they do are: +.IP +.nf +.ta +2.0i +2.0i +2.0i +.SM CLSET_TIMEOUT\s0 struct timeval set total timeout +.SM CLGET_TIMEOUT\s0 struct timeval get total timeout +.fi +.IP +Note: if you set the timeout using +.BR clnt_control() , +the timeout parameter passed to +.B clnt_call() +will be ignored in all future calls. +.IP +.nf +.SM CLGET_SERVER_ADDR\s0 struct sockaddr_in get server's address +.fi +.br +.IP +The following operations are valid for +.SM UDP +only: +.IP +.nf +.ta +2.0i +2.0i +2.0i +.SM CLSET_RETRY_TIMEOUT\s0 struct timeval set the retry timeout +.SM CLGET_RETRY_TIMEOUT\s0 struct timeval get the retry timeout +.fi +.br +.IP +The retry timeout is the time that +.SM "UDP RPC" +waits for the server to reply before +retransmitting the request. +.br +.if t .ne 10 +.LP +.ft B +.nf +.sp .5 +clnt_freeres(clnt, outproc, out) +\s-1CLIENT\s0 *clnt; +xdrproc_t outproc; +char *out; +.fi +.ft R +.IP +A macro that frees any data allocated by the +.SM RPC/XDR +system when it decoded the results of an +.SM RPC +call. The +parameter +.I out +is the address of the results, and +.I outproc +is the +.SM XDR +routine describing the results. +This routine returns one if the results were successfully +freed, +and zero otherwise. +.br +.if t .ne 6 +.LP +.ft B +.nf +.sp .5 +void +clnt_geterr(clnt, errp) +\s-1CLIENT\s0 *clnt; +struct rpc_err *errp; +.fi +.ft R +.IP +A macro that copies the error structure out of the client +handle +to the structure at address +.IR errp . +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +void +clnt_pcreateerror(s) +char *s; +.fi +.ft R +.IP +Print a message to standard error indicating +why a client +.SM RPC +handle could not be created. +The message is prepended with string +.I s +and a colon. +Used when a +.BR clnt_create() , +.BR clntraw_create() , +.BR clnttcp_create() , +or +.B clntudp_create() +call fails. +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +void +clnt_perrno(stat) +enum clnt_stat stat; +.fi +.ft R +.IP +Print a message to standard error corresponding +to the condition indicated by +.IR stat . +Used after +.BR callrpc() . +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +clnt_perror(clnt, s) +\s-1CLIENT\s0 *clnt; +char *s; +.fi +.ft R +.IP +Print a message to standard error indicating why an +.SM RPC +call failed; +.I clnt +is the handle used to do the call. +The message is prepended with string +.I s +and a colon. +Used after +.BR clnt_call() . +.br +.if t .ne 9 +.LP +.ft B +.nf +.sp .5 +char * +clnt_spcreateerror +char *s; +.fi +.ft R +.IP +Like +.BR clnt_pcreateerror() , +except that it returns a string +instead of printing to the standard error. +.IP +Bugs: returns pointer to static data that is overwritten +on each call. +.br +.if t .ne 9 +.LP +.ft B +.nf +.sp .5 +char * +clnt_sperrno(stat) +enum clnt_stat stat; +.fi +.ft R +.IP +Take the same arguments as +.BR clnt_perrno() , +but instead of sending a message to the standard error +indicating why an +.SM RPC +call failed, return a pointer to a string which contains +the message. The string ends with a +.SM NEWLINE\s0. +.IP +.B clnt_sperrno() +is used instead of +.B clnt_perrno() +if the program does not have a standard error (as a program +running as a server quite likely does not), or if the +programmer +does not want the message to be output with +.BR printf , +or if a message format different than that supported by +.B clnt_perrno() +is to be used. +Note: unlike +.B clnt_sperror() +and +.BR clnt_spcreaterror() , +.B clnt_sperrno() +returns pointer to static data, but the +result will not get overwritten on each call. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +char * +clnt_sperror(rpch, s) +\s-1CLIENT\s0 *rpch; +char *s; +.fi +.ft R +.IP +Like +.BR clnt_perror() , +except that (like +.BR clnt_sperrno() ) +it returns a string instead of printing to standard error. +.IP +Bugs: returns pointer to static data that is overwritten +on each call. +.br +.if t .ne 10 +.LP +.ft B +.nf +.sp .5 +\s-1CLIENT\s0 * +clntraw_create(prognum, versnum) +u_long prognum, versnum; +.fi +.ft R +.IP +This routine creates a toy +.SM RPC +client for the remote program +.IR prognum , +version +.IR versnum . +The transport used to pass messages to the service is +actually a buffer within the process's address space, so the +corresponding +.SM RPC +server should live in the same address space; see +.BR svcraw_create() . +This allows simulation of +.SM RPC +and acquisition of +.SM RPC +overheads, such as round trip times, without any +kernel interference. This routine returns +.SM NULL +if it fails. +.br +.if t .ne 15 +.LP +.ft B +.nf +.sp .5 +\s-1CLIENT\s0 * +clnttcp_create(addr, prognum, versnum, sockp, sendsz, recvsz) +struct sockaddr_in *addr; +u_long prognum, versnum; +int *sockp; +u_int sendsz, recvsz; +.fi +.ft R +.IP +This routine creates an +.SM RPC +client for the remote program +.IR prognum , +version +.IR versnum ; +the client uses +.SM TCP/IP +as a transport. The remote program is located at Internet +address +.IR *addr . +If +.\"The following in-line font conversion is necessary for the hyphen indicator +\fB\%addr\->sin_port\fR +is zero, then it is set to the actual port that the remote +program is listening on (the remote +.B portmap +service is consulted for this information). The parameter +.I sockp +is a socket; if it is +.BR \s-1RPC_ANYSOCK\s0 , +then this routine opens a new one and sets +.IR sockp . +Since +.SM TCP\s0-based +.SM RPC +uses buffered +.SM I/O , +the user may specify the size of the send and receive buffers +with the parameters +.I sendsz +and +.IR recvsz ; +values of zero choose suitable defaults. +This routine returns +.SM NULL +if it fails. +.br +.if t .ne 15 +.LP +.ft B +.nf +.sp .5 +\s-1CLIENT\s0 * +clntudp_create(addr, prognum, versnum, wait, sockp) +struct sockaddr_in *addr; +u_long prognum, versnum; +struct timeval wait; +int *sockp; +.fi +.ft R +.IP +This routine creates an +.SM RPC +client for the remote program +.IR prognum , +version +.IR versnum ; +the client uses use +.SM UDP/IP +as a transport. The remote program is located at Internet +address +.IR addr . +If +\fB\%addr\->sin_port\fR +is zero, then it is set to actual port that the remote +program is listening on (the remote +.B portmap +service is consulted for this information). The parameter +.I sockp +is a socket; if it is +.BR \s-1RPC_ANYSOCK\s0 , +then this routine opens a new one and sets +.IR sockp . +The +.SM UDP +transport resends the call message in intervals of +.B wait +time until a response is received or until the call times +out. +The total time for the call to time out is specified by +.BR clnt_call() . +.IP +Warning: since +.SM UDP\s0-based +.SM RPC +messages can only hold up to 8 Kbytes +of encoded data, this transport cannot be used for procedures +that take large arguments or return huge results. +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +\s-1CLIENT\s0 * +clntudp_bufcreate(addr, prognum, versnum, wait, sockp, sendsize, recosize) +struct sockaddr_in *addr; +u_long prognum, versnum; +struct timeval wait; +int *sockp; +unsigned int sendsize; +unsigned int recosize; +.fi +.ft R +.IP +This routine creates an +.SM RPC +client for the remote program +.IR prognum , +on +.IR versnum ; +the client uses use +.SM UDP/IP +as a transport. The remote program is located at Internet +address +.IR addr . +If +\fB\%addr\->sin_port\fR +is zero, then it is set to actual port that the remote +program is listening on (the remote +.B portmap +service is consulted for this information). The parameter +.I sockp +is a socket; if it is +.BR \s-1RPC_ANYSOCK\s0 , +then this routine opens a new one and sets +.BR sockp . +The +.SM UDP +transport resends the call message in intervals of +.B wait +time until a response is received or until the call times +out. +The total time for the call to time out is specified by +.BR clnt_call() . +.IP +This allows the user to specify the maximum packet size for sending and receiving +.SM UDP\s0-based +.SM RPC +messages. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +void +get_myaddress(addr) +struct sockaddr_in *addr; +.fi +.ft R +.IP +Stuff the machine's +.SM IP +address into +.IR *addr , +without consulting the library routines that deal with +.BR /etc/hosts . +The port number is always set to +.BR htons(\s-1PMAPPORT\s0) . +.br +.if t .ne 10 +.LP +.ft B +.nf +.sp .5 +struct pmaplist * +pmap_getmaps(addr) +struct sockaddr_in *addr; +.fi +.ft R +.IP +A user interface to the +.B portmap +service, which returns a list of the current +.SM RPC +program-to-port mappings +on the host located at +.SM IP +address +.IR *addr . +This routine can return +.SM NULL . +The command +.RB ` "rpcinfo \-p" ' +uses this routine. +.br +.if t .ne 12 +.LP +.ft B +.nf +.sp .5 +u_short +pmap_getport(addr, prognum, versnum, protocol) +struct sockaddr_in *addr; +u_long prognum, versnum, protocol; +.fi +.ft R +.IP +A user interface to the +.B portmap +service, which returns the port number +on which waits a service that supports program number +.IR prognum , +version +.IR versnum , +and speaks the transport protocol associated with +.IR protocol . +The value of +.I protocol +is most likely +.B +.SM IPPROTO_UDP +or +.BR \s-1IPPROTO_TCP\s0 . +A return value of zero means that the mapping does not exist +or that +the +.SM RPC +system failed to contact the remote +.B portmap +service. In the latter case, the global variable +.B rpc_createerr() +contains the +.SM RPC +status. +.br +.if t .ne 15 +.LP +.ft B +.nf +.sp .5 +enum clnt_stat +pmap_rmtcall(addr, prognum, versnum, procnum, inproc, in, outproc, out, tout, portp) +struct sockaddr_in *addr; +u_long prognum, versnum, procnum; +char *in, *out; +xdrproc_t inproc, outproc; +struct timeval tout; +u_long *portp; +.fi +.ft R +.IP +A user interface to the +.B portmap +service, which instructs +.B portmap +on the host at +.SM IP +address +.I *addr +to make an +.SM RPC +call on your behalf to a procedure on that host. +The parameter +.I *portp +will be modified to the program's port number if the +procedure +succeeds. The definitions of other parameters are discussed +in +.B callrpc() +and +.BR clnt_call() . +This procedure should be used for a \(lqping\(rq and nothing +else. +See also +.BR clnt_broadcast() . +.br +.if t .ne 9 +.LP +.ft B +.nf +.sp .5 +pmap_set(prognum, versnum, protocol, port) +u_long prognum, versnum, protocol; +u_short port; +.fi +.ft R +.IP +A user interface to the +.B portmap +service, which establishes a mapping between the triple +.RI [ prognum , versnum , protocol\fR] +and +.I port +on the machine's +.B portmap +service. The value of +.I protocol +is most likely +.B +.SM IPPROTO_UDP +or +.BR \s-1IPPROTO_TCP\s0 . +This routine returns one if it succeeds, zero otherwise. +Automatically done by +.BR svc_register() . +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +pmap_unset(prognum, versnum) +u_long prognum, versnum; +.fi +.ft R +.IP +A user interface to the +.B portmap +service, which destroys all mapping between the triple +.RI [ prognum , versnum , *\fR] +and +.B ports +on the machine's +.B portmap +service. This routine returns one if it succeeds, zero +otherwise. +.br +.if t .ne 15 +.LP +.ft B +.nf +.sp .5 +registerrpc(prognum, versnum, procnum, procname, inproc, outproc) +u_long prognum, versnum, procnum; +char *(*procname) () ; +xdrproc_t inproc, outproc; +.fi +.ft R +.IP +Register procedure +.I procname +with the +.SM RPC +service package. If a request arrives for program +.IR prognum , +version +.IR versnum , +and procedure +.IR procnum , +.I procname +is called with a pointer to its parameter(s); +.I progname +should return a pointer to its static result(s); +.I inproc +is used to decode the parameters while +.I outproc +is used to encode the results. +This routine returns zero if the registration succeeded, \-1 +otherwise. +.IP +Warning: remote procedures registered in this form +are accessed using the +.SM UDP/IP +transport; see +.B svcudp_create() +for restrictions. +.br +.if t .ne 5 +.LP +.ft B +.nf +.sp .5 +struct rpc_createerr rpc_createerr; +.fi +.ft R +.IP +A global variable whose value is set by any +.SM RPC +client creation routine +that does not succeed. Use the routine +.B clnt_pcreateerror() +to print the reason why. +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +svc_destroy(xprt) +\s-1SVCXPRT\s0 * +xprt; +.fi +.ft R +.IP +A macro that destroys the +.SM RPC +service transport handle, +.IR xprt . +Destruction usually involves deallocation +of private data structures, including +.I xprt +itself. Use of +.I xprt +is undefined after calling this routine. +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +fd_set svc_fdset; +.fi +.ft R +.IP +A global variable reflecting the +.SM RPC +service side's +read file descriptor bit mask; it is suitable as a parameter +to the +.B select +system call. This is only of interest +if a service implementor does not call +.BR svc_run() , +but rather does his own asynchronous event processing. +This variable is read-only (do not pass its address to +.BR select !), +yet it may change after calls to +.B svc_getreqset() +or any creation routines. +.br +.if t .ne 6 +.LP +.ft B +.nf +.sp .5 +int svc_fds; +.fi +.ft R +.IP +Similar to +.BR svc_fdset , +but limited to 32 descriptors. This +interface is obsoleted by +.BR svc_fdset . +.br +.if t .ne 9 +.LP +.ft B +.nf +.sp .5 +svc_freeargs(xprt, inproc, in) +\s-1SVCXPRT\s0 *xprt; +xdrproc_t inproc; +char *in; +.fi +.ft R +.IP +A macro that frees any data allocated by the +.SM RPC/XDR +system when it decoded the arguments to a service procedure +using +.BR svc_getargs() . +This routine returns 1 if the results were successfully +freed, +and zero otherwise. +.br +.if t .ne 10 +.LP +.ft B +.nf +.sp .5 +svc_getargs(xprt, inproc, in) +\s-1SVCXPRT\s0 *xprt; +xdrproc_t inproc; +char *in; +.fi +.ft R +.IP +A macro that decodes the arguments of an +.SM RPC +request +associated with the +.SM RPC +service transport handle, +.IR xprt . +The parameter +.I in +is the address where the arguments will be placed; +.I inproc +is the +.SM XDR +routine used to decode the arguments. +This routine returns one if decoding succeeds, and zero +otherwise. +.br +.if t .ne 9 +.LP +.ft B +.nf +.sp .5 +struct sockaddr_in * +svc_getcaller(xprt) +\s-1SVCXPRT\s0 *xprt; +.fi +.ft R +.IP +The approved way of getting the network address of the caller +of a procedure associated with the +.SM RPC +service transport handle, +.IR xprt . +.br +.if t .ne 9 +.LP +.ft B +.nf +.sp .5 +svc_getreqset(rdfds) +fd_set *rdfds; +.fi +.ft R +.IP +This routine is only of interest if a service implementor +does not call +.BR svc_run() , +but instead implements custom asynchronous event processing. +It is called when the +.B select +system call has determined that an +.SM RPC +request has arrived on some +.SM RPC +.B socket(s) ; +.I rdfds +is the resultant read file descriptor bit mask. +The routine returns when all sockets associated with the +value of +.I rdfds +have been serviced. +.br +.if t .ne 6 +.LP +.ft B +.nf +.sp .5 +svc_getreq(rdfds) +int rdfds; +.fi +.ft R +.IP +Similar to +.BR svc_getreqset() , +but limited to 32 descriptors. This interface is obsoleted by +.BR svc_getreqset() . +.br +.if t .ne 17 +.LP +.ft B +.nf +.sp .5 +svc_register(xprt, prognum, versnum, dispatch, protocol) +\s-1SVCXPRT\s0 *xprt; +u_long prognum, versnum; +void (*dispatch) (); +u_long protocol; +.fi +.ft R +.IP +Associates +.I prognum +and +.I versnum +with the service dispatch procedure, +.IR dispatch . +If +.I protocol +is zero, the service is not registered with the +.B portmap +service. If +.I protocol +is non-zero, then a mapping of the triple +.RI [ prognum , versnum , protocol\fR] +to +\fB\%xprt\->xp_port\fR +is established with the local +.B portmap +service (generally +.I protocol +is zero, +.B +.SM IPPROTO_UDP +or +.B +.SM IPPROTO_TCP +). +The procedure +.I dispatch +has the following form: +.RS 1i +.ft B +.nf +dispatch(request, xprt) +struct svc_req *request; +\s-1SVCXPRT\s0 *xprt; +.ft R +.fi +.RE +.IP +The +.B svc_register() +routine returns one if it succeeds, and zero otherwise. +.br +.if t .ne 6 +.LP +.ft B +.nf +.sp .5 +svc_run() +.fi +.ft R +.IP +This routine never returns. It waits for +.SM RPC +requests to arrive, and calls the appropriate service +procedure using +.B svc_getreq() +when one arrives. This procedure is usually waiting for a +.B select() +system call to return. +.br +.if t .ne 9 +.LP +.ft B +.nf +.sp .5 +svc_sendreply(xprt, outproc, out) +\s-1SVCXPRT\s0 *xprt; +xdrproc_t outproc; +char *out; +.fi +.ft R +.IP +Called by an +.SM RPC +service's dispatch routine to send the results of a +remote procedure call. The parameter +.I xprt +is the request's associated transport handle; +.I outproc +is the +.SM XDR +routine which is used to encode the results; and +.I out +is the address of the results. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +void +svc_unregister(prognum, versnum) +u_long prognum, versnum; +.fi +.ft R +.IP +Remove all mapping of the double +.RI [ prognum , versnum ] +to dispatch routines, and of the triple +.RI [ prognum , versnum , *\fR] +to port number. +.br +.if t .ne 9 +.LP +.ft B +.nf +.sp .5 +void +svcerr_auth(xprt, why) +\s-1SVCXPRT\s0 *xprt; +enum auth_stat why; +.fi +.ft R +.IP +Called by a service dispatch routine that refuses to perform +a remote procedure call due to an authentication error. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +void +svcerr_decode(xprt) +\s-1SVCXPRT\s0 *xprt; +.fi +.ft R +.IP +Called by a service dispatch routine that cannot successfully +decode its parameters. See also +.BR svc_getargs() . +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +void +svcerr_noproc(xprt) +\s-1SVCXPRT\s0 *xprt; +.fi +.ft R +.IP +Called by a service dispatch routine that does not implement +the procedure number that the caller requests. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +void +svcerr_noprog(xprt) +\s-1SVCXPRT\s0 *xprt; +.fi +.ft R +.IP +Called when the desired program is not registered with the +.SM RPC +package. Service implementors usually do not need this routine. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +void +svcerr_progvers(xprt) +\s-1SVCXPRT\s0 *xprt; +.fi +.ft R +.IP +Called when the desired version of a program is not registered +with the +.SM RPC +package. Service implementors usually do not need this routine. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +void +svcerr_systemerr(xprt) +\s-1SVCXPRT\s0 *xprt; +.fi +.ft R +.IP +Called by a service dispatch routine when it detects a system +error +not covered by any particular protocol. +For example, if a service can no longer allocate storage, +it may call this routine. +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +void +svcerr_weakauth(xprt) +\s-1SVCXPRT\s0 *xprt; +.fi +.ft R +.IP +Called by a service dispatch routine that refuses to perform +a remote procedure call due to insufficient +authentication parameters. The routine calls +.BR "svcerr_auth(xprt, \s-1AUTH_TOOWEAK\s0)" . +.br +.if t .ne 11 +.LP +.ft B +.nf +.sp .5 +\s-1SVCXPRT\s0 * +svcfd_create(fd, sendsize, recvsize) +int fd; +u_int sendsize; +u_int recvsize; +.fi +.ft R +.IP +Create a service on top of any open descriptor. Typically, +this +descriptor is a connected socket for a stream protocol such +as +.SM TCP\s0. +.I sendsize +and +.I recvsize +indicate sizes for the send and receive buffers. If they are +zero, a reasonable default is chosen. +.br +.if t .ne 11 +.LP +.ft B +.nf +.sp .5 +\s-1SVCXPRT\s0 * +svcraw_create() +.fi +.ft R +.IP +This routine creates a toy +.SM RPC +service transport, to which it returns a pointer. The +transport +is really a buffer within the process's address space, +so the corresponding +.SM RPC +client should live in the same +address space; +see +.BR clntraw_create() . +This routine allows simulation of +.SM RPC +and acquisition of +.SM RPC +overheads (such as round trip times), without any kernel +interference. +This routine returns +.SM NULL +if it fails. +.br +.if t .ne 11 +.LP +.ft B +.nf +.sp .5 +\s-1SVCXPRT\s0 * +svctcp_create(sock, send_buf_size, recv_buf_size) +int sock; +u_int send_buf_size, recv_buf_size; +.fi +.ft R +.IP +This routine creates a +.SM TCP/IP\s0-based +.SM RPC +service transport, to which it returns a pointer. +The transport is associated with the socket +.IR sock , +which may be +.BR \s-1RPC_ANYSOCK\s0 , +in which case a new socket is created. +If the socket is not bound to a local +.SM TCP +port, then this routine binds it to an arbitrary port. Upon +completion, +\fB\%xprt\->xp_sock\fR +is the transport's socket descriptor, and +\fB\%xprt\->xp_port\fR +is the transport's port number. +This routine returns +.SM NULL +if it fails. Since +.SM TCP\s0-based +.SM RPC +uses buffered +.SM I/O , +users may specify the size of buffers; values of zero +choose suitable defaults. +.br +.if t .ne 10 +.LP +.ft B +.nf +.sp .5 +\s-1SVCXPRT\s0 * +svcudp_bufcreate(sock, sendsize, recosize) +int sock; +.fi +.ft R +.IP +This routine creates a +.SM UDP/IP\s0-based +.SM RPC +service transport, to which it returns a pointer. +The transport is associated with the socket +.IR sock , +which may be +.B \s-1RPC_ANYSOCK\s0 , +in which case a new socket is created. +If the socket is not bound to a local +.SM UDP +port, then this routine binds it to an arbitrary port. Upon +completion, +\fB\%xprt\->xp_sock\fR +is the transport's socket descriptor, and +\fB\%xprt\->xp_port\fR +is the transport's port number. +This routine returns +.SM NULL +if it fails. +.IP +This allows the user to specify the maximum packet size for sending and +receiving +.SM UDP\s0-based +.SM RPC messages. +.br +.if t .ne 5 +.LP +.ft B +.nf +.sp .5 +\s-1SVCXPRT\s0 * +svcudp_create(sock) +int sock; +.fi +.ft R +.IP +This call is equivalent to +\fIsvcudp_bufcreate(sock,SZ,SZ)\fP +for some default size \fISZ\fP. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +xdr_accepted_reply(xdrs, ar) +\s-1XDR\s0 *xdrs; +struct accepted_reply *ar; +.fi +.ft R +.IP +Used for encoding +.SM RPC +reply messages. This routine is useful for users who +wish to generate +\s-1RPC\s0-style +messages without using the +.SM RPC +package. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +xdr_authunix_parms(xdrs, aupp) +\s-1XDR\s0 *xdrs; +struct authunix_parms *aupp; +.fi +.ft R +.IP +Used for describing +.SM UNIX +credentials. This routine is useful for users +who wish to generate these credentials without using the +.SM RPC +authentication package. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +void +xdr_callhdr(xdrs, chdr) +\s-1XDR\s0 *xdrs; +struct rpc_msg *chdr; +.fi +.ft R +.IP +Used for describing +.SM RPC +call header messages. +This routine is useful for users who wish to generate +.SM RPC\s0-style +messages without using the +.SM RPC +package. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +xdr_callmsg(xdrs, cmsg) +\s-1XDR\s0 *xdrs; +struct rpc_msg *cmsg; +.fi +.ft R +.IP +Used for describing +.SM RPC +call messages. +This routine is useful for users who wish to generate +.SM RPC\s0-style +messages without using the +.SM RPC +package. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +xdr_opaque_auth(xdrs, ap) +\s-1XDR\s0 *xdrs; +struct opaque_auth *ap; +.fi +.ft R +.IP +Used for describing +.SM RPC +authentication information messages. +This routine is useful for users who wish to generate +.SM RPC\s0-style +messages without using the +.SM RPC +package. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +xdr_pmap(xdrs, regs) +\s-1XDR\s0 *xdrs; +struct pmap *regs; +.fi +.ft R +.IP +Used for describing parameters to various +.B portmap +procedures, externally. +This routine is useful for users who wish to generate +these parameters without using the +.B pmap +interface. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +xdr_pmaplist(xdrs, rp) +\s-1XDR\s0 *xdrs; +struct pmaplist **rp; +.fi +.ft R +.IP +Used for describing a list of port mappings, externally. +This routine is useful for users who wish to generate +these parameters without using the +.B pmap +interface. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +xdr_rejected_reply(xdrs, rr) +\s-1XDR\s0 *xdrs; +struct rejected_reply *rr; +.fi +.ft R +.IP +Used for describing +.SM RPC +reply messages. +This routine is useful for users who wish to generate +.SM RPC\s0-style +messages without using the +.SM RPC +package. +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +xdr_replymsg(xdrs, rmsg) +\s-1XDR\s0 *xdrs; +struct rpc_msg *rmsg; +.fi +.ft R +.IP +Used for describing +.SM RPC +reply messages. +This routine is useful for users who wish to generate +.SM RPC +style messages without using the +.SM RPC +package. +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +void +xprt_register(xprt) +\s-1SVCXPRT\s0 *xprt; +.fi +.ft R +.IP +After +.SM RPC +service transport handles are created, +they should register themselves with the +.SM RPC +service package. +This routine modifies the global variable +.BR svc_fds() . +Service implementors usually do not need this routine. +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +void +xprt_unregister(xprt) +\s-1SVCXPRT\s0 *xprt; +.fi +.ft R +.IP +Before an +.SM RPC +service transport handle is destroyed, +it should unregister itself with the +.SM RPC +service package. +This routine modifies the global variable +.BR svc_fds() . +Service implementors usually do not need this routine. +.SH "SEE ALSO" +.BR rpc_secure (3), +.BR xdr (3) +.br +The following manuals: +.RS +.ft I +Remote Procedure Calls: Protocol Specification +.br +Remote Procedure Call Programming Guide +.br +rpcgen Programming Guide +.br +.ft R +.RE +.IR "\s-1RPC\s0: Remote Procedure Call Protocol Specification" , +.SM RFC1050, Sun Microsystems, Inc., +.SM USC-ISI\s0. diff --git a/man3/rresvport.3 b/man3/rresvport.3 new file mode 100644 index 000000000..b58efefab --- /dev/null +++ b/man3/rresvport.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man3/rtime.3 b/man3/rtime.3 new file mode 100644 index 000000000..e78695a9a --- /dev/null +++ b/man3/rtime.3 @@ -0,0 +1,112 @@ +.\" Copyright 2003 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" Modified 2003-04-04 Walter Harms +.\" +.\" +.\" Slightly polished, aeb, 2003-04-06 +.\" +.TH RTIME 3 2003-04-04 "sunrpc" "RPC time function" +.SH NAME +rtime \- get time from a remote machine +.SH SYNOPSIS +.sp +.B "#include " +.sp +.BI "int rtime(struct sockaddr_in *" addrp , +.BI "struct rpc_timeval *" timep , +.BI "struct rpc_timeval *" timeout ); +.sp +.SH DESCRIPTION +This function uses the Time Server Protocol as described in +RFC 868 to obtain the time from a remote machine. +.LP +The Time Server Protocol gives the time in seconds since midnight 1900-01-01, +and this function subtracts the appropriate constant in order to +convert the result to seconds since midnight 1970-01-01, the Unix epoch. +.LP +When +.I timeout +is non-NULL, the udp/time socket (port 37) is used. +Otherwise, the tcp/time socket (port 37) is used. +.SH "RETURN VALUE" +On success, 0 is returned, and the obtained 32-bit time value is stored in +.IR timep->tv_sec . +In case of error -1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +All errors for underlying functions (sendto, poll, recvfrom, connect, read) +can occur. Moreover: +.TP +.B EIO +The number of returned bytes is not 4. +.TP +.B ETIMEDOUT +The waiting time as defined in timeout has expired. +.SH "EXAMPLE" +This example requires that port 37 is up and open. You may check +that the time entry within +.I /etc/inetd.conf +is not commented out. +.br +The program connects to a computer called 'linux'. +Using 'localhost' does not work. +The result is the localtime of the computer 'linux'. +.sp +.nf +#include +#include +#include +#include +#include +#include + +int use_tcp = 0; +char *servername = "linux"; + +int main() { + struct sockaddr_in name; + struct rpc_timeval time1 = {0,0}; + struct rpc_timeval timeout = {1,0}; + struct hostent *hent; + int ret; + + memset((char *)&name, 0, sizeof(name)); + sethostent(1); + hent = gethostbyname(servername); + memcpy((char *)&name.sin_addr, hent->h_addr, hent->h_length); + + ret = rtime(&name, &time1, use_tcp ? NULL : &timeout); + if (ret < 0) + perror("rtime error"); + else + printf("%s", ctime((time_t *)&time1.tv_sec)); + + return 0; +} +.fi +.SH "NOTES" +Only IPV4 is supported. +.LP +Some +.I in.timed +versions only support TCP. Try the above example program with +.I use_tcp +set to 1. +.LP +Libc5 uses the prototype +.br +int rtime(struct sockaddr_in *, struct timeval *, struct timeval *); +.br +and requires +.I +instead of +.IR . + +.SH "BUGS" +rtime() in glibc <= 2.2.5 does not work properly on 64bit machines. +.SH "SEE ALSO" +.BR netdate (1), +.BR ntpdate (1), +.BR rdate (1), +.BR inetd (8) diff --git a/man3/rtnetlink.3 b/man3/rtnetlink.3 new file mode 100644 index 000000000..51b998a77 --- /dev/null +++ b/man3/rtnetlink.3 @@ -0,0 +1,115 @@ +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" $Id: rtnetlink.3,v 1.2 1999/05/18 10:35:10 freitag Exp $ +.TH RTNETLINK 3 1999-05-14 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +rtnetlink \- Macros to manipuate rtnetlink messages +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include + +.BI "rtnetlink_socket = socket(PF_NETLINK, int " socket_type ", NETLINK_ROUTE);" +.br +.B int RTA_OK(struct rtattr *rta, int rtabuflen); +.br +.B void *RTA_DATA(struct rtattr *rta); +.br +.B unsigned int RTA_PAYLOAD(struct rtattr *rta); +.br +.B struct rtattr *RTA_NEXT(struct rtattr *rta, unsigned int rtabuflen); +.br +.B unsigned int RTA_LENGTH(unsigned int length); +.br +.B unsigned int RTA_SPACE(unsigned int length); +.br +.SH DESCRIPTION +All +.BR rtnetlink (7) +messages consist of a +.BR netlink (7) +message header and appended attributes. The attributes should be only +manipulated using the macros provided here. + +.PP +.BI RTA_OK( rta ", " attrlen ) +returns true if +.I rta +points to a valid routing attribute; +.I attrlen +is the running length of the attribute buffer. +When not true then you must assume there are no more attributes in the +message, even if +.I attrlen +is non-zero. +.br +.BI RTA_DATA( rta ) +returns a pointer to the start of this attribute's data. +.br +.BI RTA_PAYLOAD( rta ) +returns the length of this attribute's data. +.br +.BI RTA_NEXT( rta ", " attrlen ) +gets the next attribute after +.IR rta . +Calling this macro will update +.IR attrlen . +You should use +.B RTA_OK +to check for the validity of the returned pointer. +.br +.BI RTA_LENGTH( len ) +returns the length which is required for +.I len +bytes of data plus the header. +.br +.BI RTA_SPACE( len ) +returns the amount of space which will be needed in the message with +.I len +bytes of data. + +.SH EXAMPLE +.\" XXX would be better to use libnetlink here + +Creating a rtnetlink message to set a MTU of a device. +.nf + struct { + struct nlmsghdr nh; + struct ifinfomsg if; + char attrbuf[512]; + } req; + struct rtattr *rta; + unsigned int mtu = 1000; + int rtnetlink_sk = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_ROUTE); + + memset(&req, 0, sizeof(req)); + req.nh.nlmsg_len = NLMSG_LENGTH(sizeof(struct ifinfomsg)); + req.nh.nlmsg_flags = NLM_F_REQUEST; + req.nh.nlmsg_type = RTML_NEWLINK; + req.if.ifi_family = AF_UNSPEC; + req.if.ifi_index = INTERFACE_INDEX; + req.if.ifi_change = 0xffffffff; /* ???*/ + rta = (struct rtattr *)(((char *) &req) + + NLMSG_ALIGN(n->nlmsg_len)); + rta->rta_type = IFLA_MTU; + rta->rta_len = sizeof(unsigned int); + req.n.nlmsg_len = NLMSG_ALIGN(req.n.nlmsg_len) + + RTA_LENGTH(sizeof(mtu)); + memcpy(RTA_DATA(rta), &mtu, sizeof (mtu)); + send(rtnetlink_sk, &req, req.n.nlmsg_len); +.fi + +.SH BUGS +This manual page is lacking and incomplete. + +.SH "SEE ALSO" +.BR netlink (3), +.BR netlink (7), +.BR rtnetlink (7) diff --git a/man3/ruserok.3 b/man3/ruserok.3 new file mode 100644 index 000000000..b58efefab --- /dev/null +++ b/man3/ruserok.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man3/scalb.3 b/man3/scalb.3 new file mode 100644 index 000000000..4b6416f18 --- /dev/null +++ b/man3/scalb.3 @@ -0,0 +1,76 @@ +.\" Copyright 2004 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH SCALB 3 2004-10-31 "" "Linux Programmer's Manual" +.SH NAME +scalb, scalbf, scalbl, scalbn, scalbnf, scalbnl, scalbln, scalblnf, scalblnl \- +multiply floating-point number by integral power of radix +.SH SYNOPSIS +.B #include +.sp +.BI "double scalb(double " x ", double " exp ); +.br +.BI "float scalbf(float " x ", double " exp ); +.br +.BI "long double scalbl(long double " x ", double " exp ); +.sp +.BI "double scalbn(double " x ", int " exp ); +.br +.BI "float scalbnf(float " x ", int " exp ); +.br +.BI "long double scalbnl(long double " x ", int " exp ); +.sp +.BI "double scalbln(double " x ", long int " exp ); +.br +.BI "float scalblnf(float " x ", long int " exp ); +.br +.BI "long double scalblnl(long double " x ", long int " exp ); +.sp +Link with -lm. +.SH DESCRIPTION +These functions multiply their first argument +.I x +by FLT_RADIX (probably 2) to the power +.IR exp . + +If FLT_RADIX equals 2, then +.B scalbn() +is equivalent to +.BR ldexp() . + +The value of FLT_RADIX is found in +.I . +.\" not in /usr/include but in a gcc lib +.SH "CONFORMING TO" +The +.B scalb() +function is from BSD 4.3. +The +.B scalbn() +and +.B scalbln() +functions are from C99. +All three are in POSIX 1003.1-2003. The +.B scalb() +function is marked obsolescent. +.SH "SEE ALSO" +.BR ldexp (3) diff --git a/man3/scalbf.3 b/man3/scalbf.3 new file mode 100644 index 000000000..5a33fb820 --- /dev/null +++ b/man3/scalbf.3 @@ -0,0 +1 @@ +.so man3/scalb.3 diff --git a/man3/scalbl.3 b/man3/scalbl.3 new file mode 100644 index 000000000..5a33fb820 --- /dev/null +++ b/man3/scalbl.3 @@ -0,0 +1 @@ +.so man3/scalb.3 diff --git a/man3/scalbln.3 b/man3/scalbln.3 new file mode 100644 index 000000000..5a33fb820 --- /dev/null +++ b/man3/scalbln.3 @@ -0,0 +1 @@ +.so man3/scalb.3 diff --git a/man3/scalblnf.3 b/man3/scalblnf.3 new file mode 100644 index 000000000..5a33fb820 --- /dev/null +++ b/man3/scalblnf.3 @@ -0,0 +1 @@ +.so man3/scalb.3 diff --git a/man3/scalblnl.3 b/man3/scalblnl.3 new file mode 100644 index 000000000..5a33fb820 --- /dev/null +++ b/man3/scalblnl.3 @@ -0,0 +1 @@ +.so man3/scalb.3 diff --git a/man3/scalbn.3 b/man3/scalbn.3 new file mode 100644 index 000000000..5a33fb820 --- /dev/null +++ b/man3/scalbn.3 @@ -0,0 +1 @@ +.so man3/scalb.3 diff --git a/man3/scalbnf.3 b/man3/scalbnf.3 new file mode 100644 index 000000000..5a33fb820 --- /dev/null +++ b/man3/scalbnf.3 @@ -0,0 +1 @@ +.so man3/scalb.3 diff --git a/man3/scalbnl.3 b/man3/scalbnl.3 new file mode 100644 index 000000000..5a33fb820 --- /dev/null +++ b/man3/scalbnl.3 @@ -0,0 +1 @@ +.so man3/scalb.3 diff --git a/man3/scandir.3 b/man3/scandir.3 new file mode 100644 index 000000000..27b725684 --- /dev/null +++ b/man3/scandir.3 @@ -0,0 +1,145 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:26:16 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Thu Apr 11 17:11:33 1996 by Andries Brouwer (aeb@cwi.nl): +.\" Corrected type of compar routines, as suggested by +.\" Miguel Barreiro (enano@avalon.yaix.es). Added example. +.\" Modified Sun Sep 24 20:15:46 2000 by aeb, following Petter Reinholdtsen. +.\" Modified 2001-12-26 by aeb, following Joey. Added versionsort. +.\" +.TH SCANDIR 3 2001-12-26 "GNU" "Linux Programmer's Manual" +.SH NAME +scandir, alphasort, versionsort \- scan a directory for matching entries +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int scandir(const char *" dir ", struct dirent ***" namelist , +.RS +.BI "int(*" filter ")(const struct dirent *)," +.BI "int(*" compar ")(const struct dirent **, const struct dirent **));" +.RE +.sp +.BI "int alphasort(const void *" a ", const void *" b ); +.br +.BI "int versionsort(const void *" a ", const void *" b ); +.fi +.SH DESCRIPTION +The \fBscandir()\fP function scans the directory \fIdir\fP, calling +\fIfilter()\fP on each directory entry. Entries for which +\fIfilter()\fP returns non-zero are stored in strings allocated via +\fBmalloc()\fP, sorted using \fBqsort()\fP with the comparison +function \fIcompar()\fP, and collected in array \fInamelist\fP +which is allocated via \fBmalloc()\fP. +If \fIfilter\fP is NULL, all entries are selected. +.LP +The +.B alphasort() +and +.B versionsort() +functions can be used as the comparison function +.IR compar() . +The former sorts directory entries using +.BR strcoll (3), +the latter using +.BR strvers\%cmp (3) +on the strings \fI(*a)->d_name\fP and \fI(*b)->d_name\fP. +.SH "RETURN VALUE" +The \fBscandir()\fP function returns the number of directory entries +selected or \-1 if an error occurs. +.PP +The +.B alphasort() +and +.B versionsort() +functions return an integer less than, equal to, +or greater than zero if the first argument is considered to be +respectively less than, equal to, or greater than the second. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to complete the operation. +.SH "CONFORMING TO" +None of these functions is in POSIX. +LSB has deprecated the library call +.B alphasort() +and never contained +.BR scandir() . +.LP +The functions +.B scandir() +and +.B alphasort() +are from BSD 4.3, and have been available under Linux since libc4. +Libc4 and libc5 use the more precise prototype +.sp +.nf +.BI "int alphasort(const struct dirent **" a ", const struct dirent **" b ); +.fi +.sp +but glibc 2.0 returns to the imprecise BSD prototype. +.LP +The function +.B versionsort() +is a GNU extension, available since glibc 2.1. +Since glibc 2.1, +.B alphasort() +calls +.BR strcoll (3); +earlier it used +.BR strcmp (3). +.SH EXAMPLE +.nf +/* print files in current directory in reverse order */ +#include +main(){ + struct dirent **namelist; + int n; + + n = scandir(".", &namelist, 0, alphasort); + if (n < 0) + perror("scandir"); + else { + while(n--) { + printf("%s\en", namelist[n]->d_name); + free(namelist[n]); + } + free(namelist); + } +} +.fi +.SH "SEE ALSO" +.BR closedir (3), +.BR fnmatch (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR seekdir (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strverscmp (3), +.BR telldir (3) diff --git a/man3/scanf.3 b/man3/scanf.3 new file mode 100644 index 000000000..c9e0a639d --- /dev/null +++ b/man3/scanf.3 @@ -0,0 +1,417 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)scanf.3 6.14 (Berkeley) 1/8/93 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" modified to resemble the GNU libio setup used in the Linux libc +.\" used in versions 4.x (x>4) and 5 Helmut.Geyer@iwr.uni-heidelberg.de +.\" Modified, aeb, 970121 +.\" +.TH SCANF 3 1995-11-01 "LINUX MANPAGE" "Linux Programmer's Manual" +.SH NAME +scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf \- input format conversion +.SH SYNOPSIS +.nf +.B #include +.na +.BI "int scanf(const char *" format ", ..." ); +.br +.BI "int fscanf(FILE *" stream ", const char *" format ", ..." ); +.br +.BI "int sscanf(const char *" str ", const char *" format ", ..." ); +.sp +.B #include +.BI "int vscanf(const char *" format ", va_list " ap ); +.br +.BI "int vsscanf(const char *" str ", const char *" format ", va_list " ap ); +.br +.BI "int vfscanf(FILE *" stream ", const char *" format ", va_list " ap ); +.ad +.SH DESCRIPTION +The +.B scanf +family of functions scans input according to a +.I format +as described below. This format may contain +.IR "conversion specifiers" ; +the results from such conversions, if any, are stored through the +.I pointer +arguments. The +.B scanf +function reads input from the standard input stream +.IR stdin , +.B fscanf +reads input from the stream pointer +.IR stream , +and +.B sscanf +reads its input from the character string pointed to by +.IR str . +.PP +The +.B vfscanf +function is analogous to +.BR vfprintf (3) +and reads input from the stream pointer +.I stream +using a variable argument list of pointers (see +.BR stdarg (3). +The +.B vscanf +function scans a variable argument list from the standard input and the +.B vsscanf +function scans it from a string; these are analogous to the +.B vprintf +and +.B vsprintf +functions respectively. +.PP +Each successive +.I pointer +argument must correspond properly with each successive conversion specifier +(but see `suppression' below). All conversions are introduced by the +.B % +(percent sign) character. The +.I format +string may also contain other characters. White space (such as blanks, +tabs, or newlines) in the +.I format +string match any amount of white space, including none, in the input. +Everything else matches only itself. Scanning stops when an input +character does not match such a format character. Scanning also stops when +an input conversion cannot be made (see below). +.SH CONVERSIONS +Following the +.B % +character introducing a conversion there may be a number of +.I flag +characters, as follows: +.TP +.B * +Suppresses assignment. The conversion that follows occurs as usual, but no +pointer is used; the result of the conversion is simply discarded. +.TP +.B a +(glibc) Indicates that the conversion will be +.BR s , +the needed memory space for the string will be malloc'ed and +the pointer to it will be assigned to the +.I char +pointer variable, which does not have to be initialized before. +This flag does not exist in +.IR "ANSI C" +(C89) and has a different meaning in C99. +.TP +.B a +(C99) Equivalent to +.BR f . +.TP +.B h +Indicates that the conversion will be one of +.B dioux +or +.B n +and the next pointer is a pointer to a +.I short int +(rather than +.IR int ). +.TP +.B l +Indicates either that the conversion will be one of +.B dioux +or +.B n +and the next pointer is a pointer to a +.I long int +(rather than +.IR int ), +or that the conversion will be one of +.B efg +and the next pointer is a pointer to +.I double +(rather than +.IR float ). +Specifying two +.B l +flags is equivalent to the +.B L +flag. +.TP +.B L +Indicates that the conversion will be either +.B efg +and the next pointer is a pointer to +.IR "long double" +or the conversion will be +.B dioux +and the next pointer is a pointer to +.IR "long long" . +(Note that long long is not an +.I ANSI C +type. Any program using this will not be portable to all +architectures). +.TP +.B q +equivalent to L. +This flag does not exist in +.IR "ANSI C" . +.PP +In addition to these flags, there may be an optional maximum field width, +expressed as a decimal integer, between the +.B % +and the conversion. If no width is given, a default of `infinity' is used +(with one exception, below); otherwise at most this many characters are +scanned in processing the conversion. Before conversion begins, most +conversions skip white space; this white space is not counted against the +field width. +.PP +The following conversions are available: +.TP +.B % +Matches a literal `%'. That is, `%\&%' in the format string matches a +single input `%' character. No conversion is done, and assignment does not +occur. +.TP +.B d +Matches an optionally signed decimal integer; +the next pointer must be a pointer to +.IR int . +.TP +.B D +Equivalent to +.BR ld ; +this exists only for backwards compatibility. +(Note: thus only in libc4. In libc5 and glibc the %D is +silently ignored, causing old programs to fail mysteriously.) +.TP +.B i +Matches an optionally signed integer; the next pointer must be a pointer to +.IR int . +The integer is read in base 16 if it begins with `0x' or `0X', in base 8 if +it begins with `0', and in base 10 otherwise. Only characters that +correspond to the base are used. +.TP +.B o +Matches an unsigned octal integer; the next pointer must be a pointer to +.IR "unsigned int" . +.TP +.B u +Matches an unsigned decimal integer; the next pointer must be a +pointer to +.IR "unsigned int" . +.TP +.B x +Matches an unsigned hexadecimal integer; the next pointer must +be a pointer to +.IR "unsigned int" . +.TP +.B X +Equivalent to +.BR x . +.TP +.B f +Matches an optionally signed floating-point number; the next pointer must +be a pointer to +.IR float . +.TP +.B e +Equivalent to +.BR f . +.TP +.B g +Equivalent to +.BR f . +.TP +.B E +Equivalent to +.BR f . +.TP +.B s +Matches a sequence of non-white-space characters; the next pointer must be +a pointer to +.IR char , +and the array must be large enough to accept all the sequence and the +terminating +.B NUL +character. The input string stops at white space or at the maximum field +width, whichever occurs first. +.TP +.B c +Matches a sequence of +.I width +count characters (default 1); the next pointer must be a pointer to +.IR char , +and there must be enough room for all the characters (no terminating +.B NUL +is added). The usual skip of leading white space is suppressed. To skip +white space first, use an explicit space in the format. +.TP +.B \&[ +Matches a nonempty sequence of characters from the specified set of +accepted characters; the next pointer must be a pointer to +.IR char , +and there must be enough room for all the characters in the string, plus a +terminating +.B NUL +character. The usual skip of leading white space is suppressed. The +string is to be made up of characters in (or not in) a particular set; the +set is defined by the characters between the open bracket +.B [ +character and a close bracket +.B ] +character. The set +.I excludes +those characters if the first character after the open bracket is a +circumflex +.BR ^ . +To include a close bracket in the set, make it the first character after +the open bracket or the circumflex; any other position will end the set. +The hyphen character +.B - +is also special; when placed between two other characters, it adds all +intervening characters to the set. To include a hyphen, make it the last +character before the final close bracket. For instance, `[^]0-9-]' means +the set `everything except close bracket, zero through nine, and hyphen'. +The string ends with the appearance of a character not in the (or, with a +circumflex, in) set or when the field width runs out. +.TP +.B p +Matches a pointer value (as printed by `%p' in +.BR printf (3); +the next pointer must be a pointer to +.IR void . +.TP +.B n +Nothing is expected; instead, the number of characters consumed thus far +from the input is stored through the next pointer, which must be a pointer +to +.IR int . +This is +.I not +a conversion, although it can be suppressed with the +.B * +flag. +The C standard says: `Execution of a %n directive does not increment +the assignment count returned at the completion of execution' +but the Corrigendum seems to contradict this. Probably it is wise +not to make any assumptions on the effect of %n conversions on +the return value. + +.PP +.SH "RETURN VALUE" +These functions return the number of input items assigned, which can be +fewer than provided for, or even zero, in the event of a matching failure. +Zero indicates that, while there was input available, no conversions were +assigned; typically this is due to an invalid input character, such as an +alphabetic character for a `%d' conversion. The value +.B EOF +is returned if an input failure occurs before any conversion such as an +end-of-file occurs. If an error or end-of-file occurs after conversion has +begun, the number of conversions which were successfully completed is +returned. +.SH "SEE ALSO" +.BR getc (3), +.BR printf (3), +.BR strtod (3), +.BR strtol (3), +.BR strtoul (3) +.SH "CONFORMING TO" +The functions +.BR fscanf , +.BR scanf , +and +.BR sscanf +conform to ANSI X3.159-1989 (``ANSI C''). +.PP +The +.B q +flag is the +.I BSD 4.4 +notation for +.IR "long long" , +while +.B ll +or the usage of +.B L +in integer conversions is the GNU notation. +.PP +The Linux version of these functions is based on the +.I GNU +.I libio +library. Take a look at the +.I info +documentation of +.I GNU +.I libc (glibc-1.08) +for a more concise description. +.SH BUGS +All functions are fully ANSI X3.159-1989 conformant, but provide the +additional flags +.B q +and +.B a +as well as an additional behaviour of the +.B L +and +.B l +flags. The latter may be considered to be a bug, as it changes the +behaviour of flags defined in ANSI X3.159-1989. +.PP +Some combinations of flags defined by +.I ANSI C +are not making sense in +.IR "ANSI C" +(e.g. +.BR "%Ld" ). +While they may have a well-defined behaviour on Linux, this need not +to be so on other architectures. Therefore it usually is better to use +flags that are not defined by +.I ANSI C +at all, i.e. use +.B q +instead of +.B L +in combination with +.B diouxX +conversions or +.BR ll . +.PP +The usage of +.B q +is not the same as on +.IR "BSD 4.4" , +as it may be used in float conversions equivalently to +.BR L . diff --git a/man3/seed48.3 b/man3/seed48.3 new file mode 100644 index 000000000..3133f7d62 --- /dev/null +++ b/man3/seed48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man3/seed48_r.3 b/man3/seed48_r.3 new file mode 100644 index 000000000..81e9d8ef7 --- /dev/null +++ b/man3/seed48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man3/seekdir.3 b/man3/seekdir.3 new file mode 100644 index 000000000..246d980eb --- /dev/null +++ b/man3/seekdir.3 @@ -0,0 +1,53 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:25:21 1993 by Rik Faith (faith@cs.unc.edu) +.TH SEEKDIR 3 1993-03-31 "" "Linux Programmer's Manual" +.SH NAME +seekdir \- set the position of the next readdir() call in the directory +stream. +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void seekdir(DIR *" dir ", off_t " offset ); +.fi +.SH DESCRIPTION +The \fBseekdir()\fP function sets the location in the directory stream +from which the next \fBreaddir()\fP call will start. \fBseekdir()\fP +should be used with an offset returned by \fBtelldir()\fP. +.SH "RETURN VALUE" +The \fBseekdir()\fP function returns no value. +.SH "CONFORMING TO" +BSD 4.3 +.SH "SEE ALSO" +.BR lseek (2), +.BR closedir (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR telldir (3) diff --git a/man3/setaliasent.3 b/man3/setaliasent.3 new file mode 100644 index 000000000..e1c660e43 --- /dev/null +++ b/man3/setaliasent.3 @@ -0,0 +1,135 @@ +.\" Copyright 2003 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.\" Polished a bit, added a little, aeb +.\" +.TH SETALIASENT 3 2003-09-09 "GNU" "access mail aliases database" +.SH NAME +setaliasent, endaliasent, getaliasent, getaliasent_r, +getaliasbyname, getaliasbyname_r \- read an alias entry +.SH SYNOPSIS +.B #include +.sp +.BI "void setaliasent(void);" +.sp +.BI "void endaliasent(void);" +.sp +.BI "struct aliasent *getaliasent(void);" +.sp +.BI "int getaliasent_r(struct aliasent *" result "," +.br +.BI " char *" buffer ", size_t " buflen ", struct aliasent **" res ); +.sp +.BI "struct aliasent *getaliasbyname(const char *" name ); +.sp +.BI "int getaliasbyname_r(const char *" name , +.br +.BI " struct aliasent *" result , +.br +.BI " char *" buffer ", size_t " buflen ", struct aliasent **" res ); +.sp +.SH DESCRIPTION +One of the databases available with the Name Service Switch (NSS) +is the aliases database, that contains mail aliases. (To find out +which databases are supported, try getent \-\-help .) +Six functions are provided to access the aliases database. +.PP +The +.B getaliasent() +function returns a pointer to a structure containing +the group information from the aliases database. +The first time it is called it returns the first entry; +thereafter, it returns successive entries. +.PP +The +.B setaliasent() +function rewinds the file pointer to the beginning of the +aliases database. +.PP +The +.B endaliasent() +function closes the aliases database. +.PP +.B getaliasent_r() +is the reentrant version of the previous function. The requested structure +is stored via the first argument but the programmer needs to fill the other +arguments also. Not providing enough space causes the function to fail. +.PP +The function +.B getaliasbyname() +takes the name argument and searches the aliases database. The entry is +returned as a pointer to a struct aliasent. +.PP +.B getaliasbyname_r() +is the reentrant version of the previous function. The requested structure +is stored via the second argument but the programmer need to fill the other +arguments also. Not providing enough space causes the function to fail. +.PP +The struct aliasent is defined in . +.nf +struct aliasent { + char *alias_name; /* alias name */ + size_t alias_members_len; + char **alias_members; /* alias name list */ + int alias_local; +}; +.fi +.SH FILES +The default alias database is the file +.IR /etc/aliases . +This can be changed in the +.I /etc/nsswitch.conf +file. +.SH "RETURN VALUE" +The functions +.B getaliasent_r() +and +.B getaliasbyname_r() +return a non-zero value on error. +.SH EXAMPLE +The following example compiles with gcc example.c -o example . +It will dump all names in the alias database. +.sp +.nf +#include +#include +#include +#include + +int main() { + struct aliasent *al; + setaliasent(); + for (;;) { + al = getaliasent(); + if (al == NULL) break; + printf("Name: %s\\n", al->alias_name); + } + if (errno) { + perror("reading alias"); + exit(EXIT_FAILURE); + } + endaliasent(); + exit(EXIT_SUCCESS); +} +.fi +.SH "CONFORMING TO" +These routines are glibc-specific. +The NeXT has similar routines +.RS +.nf +#include +void alias_setent(void); +void alias_endent(void); +alias_ent *alias_getent(void); +alias_ent *alias_getbyname(char *name); +.fi +.RE +.SH "SEE ALSO" +.BR getgrent (3), +.BR getpwent (3), +.BR getspent (3), +.BR aliases (5) +.\" +.\" /etc/sendmail/aliases +.\" Yellow Pages +.\" newaliases, postalias diff --git a/man3/setbuf.3 b/man3/setbuf.3 new file mode 100644 index 000000000..5c58a43db --- /dev/null +++ b/man3/setbuf.3 @@ -0,0 +1,190 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)setbuf.3 6.10 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 14:55:24 1993, faith@cs.unc.edu +.\" Added section to BUGS, Sun Mar 12 22:28:33 MET 1995, +.\" Thomas.Koenig@ciw.uni-karlsruhe.de +.\" Correction, Sun, 11 Apr 1999 15:55:18, +.\" Martin Vicente +.\" Correction, 2000-03-03, Andreas Jaeger +.\" Added return value for setvbuf, aeb, +.\" +.TH SETBUF 3 2001-06-09 "Linux" "Linux Programmer's Manual" +.SH NAME +setbuf, setbuffer, setlinebuf, setvbuf \- stream buffering operations +.SH SYNOPSIS +.na +.B #include +.sp +.BI "void setbuf(FILE *" stream ", char *" buf ); +.br +.BI "void setbuffer(FILE *" stream ", char *" buf ", size_t " size ); +.br +.BI "void setlinebuf(FILE *" stream ); +.br +.BI "int setvbuf(FILE *" stream ", char *" buf ", int " mode +.BI ", size_t " size ); +.ad +.SH DESCRIPTION +The three types of buffering available are unbuffered, block buffered, and +line buffered. When an output stream is unbuffered, information appears on +the destination file or terminal as soon as written; when it is block +buffered many characters are saved up and written as a block; when it is +line buffered characters are saved up until a newline is output or input is +read from any stream attached to a terminal device (typically stdin). The +function +.BR fflush (3) +may be used to force the block out early. +(See +.BR fclose (3).) +Normally all files are block buffered. When the first I/O operation occurs +on a file, +.BR malloc (3) +is called, and a buffer is obtained. If a stream refers to a terminal (as +.I stdout +normally does) it is line buffered. The standard error stream +.I stderr +is always unbuffered by default. +.PP +The +.B setvbuf +function may be used on any open stream to change its buffer. +The +.I mode +parameter must be one of the following three macros: +.RS +.TP +.B _IONBF +unbuffered +.TP +.B _IOLBF +line buffered +.TP +.B _IOFBF +fully buffered +.RE +.PP +Except for unbuffered files, the +.I buf +argument should point to a buffer at least +.I size +bytes long; this buffer will be used instead of the current buffer. If the +argument +.I buf +is +.BR NULL , +only the mode is affected; a new buffer will be allocated on the next read +or write operation. The +.B setvbuf +function may only be used after opening a stream and before any other +operations have been performed on it. +.PP +The other three calls are, in effect, simply aliases for calls to +.BR setvbuf . +The +.B setbuf +function is exactly equivalent to the call +.PP +.RS +setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); +.RE +.PP +The +.B setbuffer +function is the same, except that the size of the buffer is up to the +caller, rather than being determined by the default +.BR BUFSIZ . +The +.B setlinebuf +function is exactly equivalent to the call: +.PP +.RS +setvbuf(stream, (char *)NULL, _IOLBF, 0); +.RE +.SH "RETURN VALUE" +The function +.B setvbuf +returns 0 on success. +It can return any value on failure, but returns nonzero when +.I mode +is invalid or the request cannot be honoured. It may set +.I errno +on failure. +The other functions are void. +.SH "CONFORMING TO" +The +.B setbuf +and +.B setvbuf +functions conform to ANSI X3.159-1989 (``ANSI C''). +.SH BUGS +The +.B setbuffer +and +.B setlinebuf +functions are not portable to versions of BSD before 4.2BSD, and +are available under Linux since libc 4.5.21. On 4.2BSD and 4.3BSD systems, +.B setbuf +always uses a suboptimal buffer size and should be avoided. +.P +You must make sure that both +.I buf +and the space it points to still exist by the time +.I stream +is closed, which also happens at program termination. +.P +For example, the following is illegal: +.nf +.sp +#include +int main() +{ + char buf[BUFSIZ]; + setbuf(stdin, buf); + printf("Hello, world!\\n"); + return 0; +} +.fi +.sp +.SH "SEE ALSO" +.BR fclose (3), +.BR fflush (3), +.BR fopen (3), +.BR fread (3), +.BR malloc (3), +.BR printf (3), +.BR puts (3) diff --git a/man3/setbuffer.3 b/man3/setbuffer.3 new file mode 100644 index 000000000..dc02d9e88 --- /dev/null +++ b/man3/setbuffer.3 @@ -0,0 +1 @@ +.so man3/setbuf.3 diff --git a/man3/setenv.3 b/man3/setenv.3 new file mode 100644 index 000000000..3064e8afc --- /dev/null +++ b/man3/setenv.3 @@ -0,0 +1,86 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:20:58 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 9 Jun 2004, Michael Kerrisk +.\" Changed unsetenv() prototype; added EINVAL error +.\" Noted non-standard behaviour of setenv() if name contains '=' +.\" +.TH SETENV 3 2004-05-09 "BSD" "Linux Programmer's Manual" +.SH NAME +setenv \- change or add an environment variable +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int setenv(const char *" name ", const char *" value ", int " overwrite ); +.sp +.BI "int unsetenv(const char *" name ); +.fi +.SH DESCRIPTION +The \fBsetenv()\fP function adds the variable \fIname\fP to the +environment with the value \fIvalue\fP, if \fIname\fP does not +already exist. If \fIname\fP does exist in the environment, then +its value is changed to \fIvalue\fP if \fIoverwrite\fP is non-zero; +if \fIoverwrite\fP is zero, then the value of \fIname\fP is not +changed. +.PP +The \fBunsetenv()\fP function deletes the variable \fIname\fP from +the environment. +.SH "RETURN VALUE" +The \fBsetenv()\fP function returns zero on success, or \-1 if there +was insufficient space in the environment. +The \fBunsetenv()\fP function returns zero on success, +or \-1 on error, with +.I errno +set to indicate the cause of the error. +.SH "ERRORS" +.TP +.B EINVAL +.I name +contained an '=' character. +.SH "CONFORMING TO" +BSD 4.3 +.SH "NOTES" +Prior to glibc 2.2.2, \fBunsetenv()\fP was prototyped +as returning \fIvoid\fP; more recent glibc versions follow the +SUSv3-compliant prototype shown in the SYNOPSIS. +.SH BUGS +SUSv3 specifies that if +.I name +contains an '=' character, then +.BR setenv () +should fail with the error +.BR EINVAL ; +however, glibc currently (v2.3.3) allows an '=' sign in +.IR name . +Portable applications should avoid this! +.SH "SEE ALSO" +.BR clearenv (3), +.BR getenv (3), +.BR putenv (3), +.BR environ (5) diff --git a/man3/setfsent.3 b/man3/setfsent.3 new file mode 100644 index 000000000..1e6a3eb7e --- /dev/null +++ b/man3/setfsent.3 @@ -0,0 +1 @@ +.so man3/getfsent.3 diff --git a/man3/setgrent.3 b/man3/setgrent.3 new file mode 100644 index 000000000..bde736fff --- /dev/null +++ b/man3/setgrent.3 @@ -0,0 +1 @@ +.so man3/getgrent.3 diff --git a/man3/sethostent.3 b/man3/sethostent.3 new file mode 100644 index 000000000..7d0fb4b7c --- /dev/null +++ b/man3/sethostent.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/setjmp.3 b/man3/setjmp.3 new file mode 100644 index 000000000..9f7096034 --- /dev/null +++ b/man3/setjmp.3 @@ -0,0 +1,63 @@ +.\" Written by Michael Haardt, Fri Nov 25 14:51:42 MET 1994 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Added sigsetjmp, Sun Mar 2 22:03:05 EST 1997, jrv@vanzandt.mv.com +.\" Modifications, Sun Feb 26 14:39:45 1995, faith@cs.unc.edu +.\" " +.TH SETJMP 3 1997-03-02 "" "Library functions" +.SH NAME +setjmp, sigsetjmp \- save stack context for non-local goto +.SH SYNOPSIS +.ad l +.B #include +.sp +.nf +.BI "int setjmp(jmp_buf " env ); +.BI "int sigsetjmp(sigjmp_buf " env ", int " savesigs ); +.fi +.ad b +.SH DESCRIPTION +\fBsetjmp()\fP and \fBlongjmp()\fP are useful for dealing with errors +and interrupts encountered in a low-level subroutine of a program. +\fBsetjmp()\fP saves the stack context/environment in \fIenv\fP for +later use by \fBlongjmp()\fP. The stack context will be invalidated +if the function which called \fBsetjmp()\fP returns. +.P +\fBsigsetjmp()\fP is similar to \fBsetjmp()\fP. If \fIsavesigs\fP is nonzero, +the set of blocked signals is saved in \fIenv\fP and will be restored +if a \fBsiglongjmp()\fP is later performed with this \fIenv\fP. +.SH "RETURN VALUE" +\fBsetjmp()\fP and \fBsigsetjmp()\fP return 0 if returning directly, and +non-zero when returning from \fBlongjmp()\fP using the saved context. +.SH "CONFORMING TO" +POSIX, ISO 9899 (C99) +.SH NOTES +POSIX does not specify whether \fBsetjmp\fP will save the +signal context. (In SYSV it will not. In BSD4.3 it will, and there +is a function \fB_setjmp\fP that will not.) +If you want to save signal masks, use \fBsigsetjmp\fP. +.P +\fBsetjmp()\fP and \fBsigsetjmp\fP make programs hard to understand +and maintain. If possible an alternative should be used. +.SH "SEE ALSO" +.BR longjmp (3), +.BR siglongjmp (3) diff --git a/man3/setkey.3 b/man3/setkey.3 new file mode 100644 index 000000000..e34c9e911 --- /dev/null +++ b/man3/setkey.3 @@ -0,0 +1 @@ +.so man3/encrypt.3 diff --git a/man3/setlinebuf.3 b/man3/setlinebuf.3 new file mode 100644 index 000000000..dc02d9e88 --- /dev/null +++ b/man3/setlinebuf.3 @@ -0,0 +1 @@ +.so man3/setbuf.3 diff --git a/man3/setlocale.3 b/man3/setlocale.3 new file mode 100644 index 000000000..a121409c4 --- /dev/null +++ b/man3/setlocale.3 @@ -0,0 +1,189 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and 1999 by Bruno Haible (haible@clisp.cons.org) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 18:20:12 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Tue Jul 15 16:49:10 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sun Jul 4 14:52:16 1999 by Bruno Haible (haible@clisp.cons.org) +.\" Modified Tue Aug 24 17:11:01 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Tue Feb 6 03:31:55 2001 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH SETLOCALE 3 1999-07-04 "GNU" "Linux Programmer's Manual" +.SH NAME +setlocale \- set the current locale +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *setlocale(int " category ", const char *" locale ); +.fi +.SH DESCRIPTION +The +.B setlocale() +function is used to set or query the program's current locale. +.PP +If +.I locale +is not +.BR NULL , +the program's current locale is modified according to the arguments. +The argument +.I category +determines which parts of the program's current locale should be modified. +.TP +.B LC_ALL +for all of the locale. +.TP +.B LC_COLLATE +for regular expression matching (it determines the meaning +of range expressions and equivalence classes) and string collation. +.TP +.B LC_CTYPE +for regular expression matching, character classification, conversion, +case-sensitive comparison, and wide character functions. +.TP +.B LC_MESSAGES +for localizable natural-language messages. +.TP +.B LC_MONETARY +for monetary formatting. +.TP +.B LC_NUMERIC +for number formatting (such as the decimal point and the thousands separator). +.TP +.B LC_TIME +for time and date formatting. +.PP +The argument +.I locale +is a pointer to a character string containing the +required setting of +.IR category . +Such a string is either a well-known constant like "C" or "da_DK" +(see below), or an opaque string that was returned by another call of +.BR setlocale . +.PP +If +.I locale +is +.BR """""" , +each part of the locale that should be modified is set according to the +environment variables. The details are implementation dependent. +For glibc, first +.\" [This is false on my system - must check which library versions do this] +.\" if +.\" .I category +.\" is LC_MESSAGES, the environment variable LANGUAGE is inspected, +.\" then +(regardless of +.IR category ), +the environment variable LC_ALL is inspected, +next the environment variable with the same name as the category +(LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME) +and finally the environment variable LANG. +The first existing environment variable is used. +If its value is not a valid locale specification, the locale +is unchanged, and +.B setlocale +returns NULL. +.\" The environment variable LANGUAGE may contain several, colon-separated, +.\" locale names. +.PP +The locale +.B """C""" +or +.B """POSIX""" +is a portable locale; its LC_CTYPE part corresponds to the 7-bit ASCII +character set. +.PP +A locale name is typically of the form +.IR language "[_" territory "][." codeset "][@" modifier "]," +where +.I language +is an ISO 639 language code, +.I territory +is an ISO 3166 country code, and +.I codeset +is a character set or encoding identifier like +.B "ISO-8859-1" +or +.BR "UTF-8" . +For a list of all supported locales, try "locale -a", cf.\& +.BR locale (1). +.PP +If +.I locale +is +.BR NULL , +the current locale is only queried, not modified. +.PP +On startup of the main program, the portable +.B """C""" +locale is selected as default. +A program may be made portable to all locales by calling +.B setlocale(LC_ALL, """""") +after program initialization, by using the values returned +from a +.B localeconv() +call +for locale \- dependent information, by using the multi-byte and wide +character functions for text processing if +.BR "MB_CUR_MAX > 1" , +and by using +.BR strcoll() ", " wcscoll() +or +.BR strxfrm() ", " wcsxfrm() +to compare strings. +.SH "RETURN VALUE" +A successful call to +.B setlocale() +returns an opaque string that corresponds to the locale set. +This string may be allocated in static storage. +The string returned is such that a subsequent call with that string +and its associated category will restore that part of the process's +locale. The return value is +.B NULL +if the request cannot be honored. +.SH "CONFORMING TO" +ANSI C, POSIX.1 +.SH NOTES +Linux (that is, GNU libc) supports the portable locales +.BR """C""" " and " """POSIX""" . +In the good old days there used to be support for +the European Latin-1 +.B """ISO-8859-1""" +locale (e.g. in libc-4.5.21 and libc-4.6.27), and the Russian +.B """KOI-8""" +(more precisely, "koi-8r") locale (e.g. in libc-4.6.27), +so that having an environment variable LC_CTYPE=ISO-8859-1 +sufficed to make isprint() return the right answer. +These days non-English speaking Europeans have to work a bit harder, +and must install actual locale files. +.SH "SEE ALSO" +.BR locale (1), +.BR localedef (1), +.BR isalpha (3), +.BR localeconv (3), +.BR strcoll (3), +.BR strftime (3), +.BR charsets (4), +.BR locale (7) diff --git a/man3/setlogmask.3 b/man3/setlogmask.3 new file mode 100644 index 000000000..7050e7593 --- /dev/null +++ b/man3/setlogmask.3 @@ -0,0 +1,64 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH SETLOGMASK 3 2001-10-05 "" "Linux Programmer's Manual" +.SH NAME +setlogmask \- set log priority mask +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int setlogmask(int " mask ); +.fi +.SH DESCRIPTION +A process has a log priority mask that determines which calls to +.BR syslog (3) +may be logged. All other calls will be ignored. +Logging is enabled for the priorities that have the corresponding +bit set in +.IR mask . +The initial mask is such that logging is enabled for all priorities. +.LP +The +.B setlogmask() +function sets this logmask for the current process, +and returns the previous mask. +If the mask argument is 0, the current logmask is not modified. +.LP +The eight priorities are LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR, +LOG_WARNING, LOG_NOTICE, LOG_INFO and LOG_DEBUG. +The bit corresponding to a priority \fIp\fP is LOG_MASK(\fIp\fP). +Some systems also provide a macro LOG_UPTO(\fIp\fP) for the mask +of all priorities in the above list up to and including \fIp\fP. +.SH "RETURN VALUE" +This function returns the previous log priority mask. +.SH ERRORS +None. +.\" .SH NOTES +.\" The glibc logmask handling was broken in versions before glibc 2.1.1. +.SH "CONFORMING TO" +XPG4. +Note that the description in POSIX 1003.1-2001 is flawed. +.SH "SEE ALSO" +.BR closelog (3), +.BR openlog (3), +.BR syslog (3) diff --git a/man3/setmntent.3 b/man3/setmntent.3 new file mode 100644 index 000000000..3c2bb35c9 --- /dev/null +++ b/man3/setmntent.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man3/setnetent.3 b/man3/setnetent.3 new file mode 100644 index 000000000..70f5670dc --- /dev/null +++ b/man3/setnetent.3 @@ -0,0 +1 @@ +.so man3/getnetent.3 diff --git a/man3/setnetgrent.3 b/man3/setnetgrent.3 new file mode 100644 index 000000000..2739b63ce --- /dev/null +++ b/man3/setnetgrent.3 @@ -0,0 +1,78 @@ +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" based on glibc infopages +.\" polished - aeb +.TH SETNETGRENT 3 2002-08-20 "GNU" "Linux Programmer's Manual" +.SH NAME +setnetgrent, endnetgrent, getnetgrent, getnetgrent_r, innetgr \- +handle network group entries +.SH SYNOPSIS +.B #include +.sp +.BI "int setnetgrent(const char *" netgroup ); +.br +.BI "void endnetgrent(void);" +.br +.BI "int getnetgrent(char **" host ", char **" user ", char **" domain ); +.sp +.BI "int getnetgrent_r(char **" host ", char **" user "," +.in +18 +.BI "char **" domain ", char *" buf ", int " buflen ); +.in -18 +.sp +.BI "int innetgr(const char *" netgroup ", const char *" host "," +.in +12 +.BI "const char *" user ", const char *" domain ); +.in -12 +.SH DESCRIPTION +The +.B netgroup +is a SunOS invention. A netgroup database is a list of string triples +.BR (hostname "," username "," domainname) +or other netgroup names. Any of the elements in a triple can be empty, +which means that anything matches. +The functions described here allow access to the netgroup databases. +The file +.I /etc/nsswitch.conf +defines what database is searched. +.PP +The +.B setnetgrent() +call defines the netgroup that will be searched by subsequent +.B getnetgrent() +calls. The +.B getnetgrent() +function retrieves the next netgroup entry, and returns pointers in +.IR host , +.IR user , +.IR domain . +A NULL pointer means that the corresponding entry matches any string. +The pointers are valid only as long as there is no call to other +netgroup related functions. +To avoid this problem you can use the GNU function +.B getnetgrent_r() +that stores the strings in the supplied buffer. +To free all allocated buffers use +.BR endnetgrent() . +.PP +In most cases you only want to check if the triplet +.BR (hostname "," username "," domainname) +is a member of a netgroup. The function +.B innetgr() +can be used for this without calling the above three functions. +Again, a NULL pointer is a wildcard and matches any string. +The function is thread-safe. +.SH FILES +.I /etc/netgroup +.br +.I /etc/nsswitch.conf +.SH "RETURN VALUES" +These functions return 1 on success and 0 for failure. +.SH NOTES +In the BSD implementation, +.B setnetgrent() +returns void. +.SH "SEE ALSO" +.BR sethostent (3), +.BR setservent (3), +.BR setprotoent (3) diff --git a/man3/setprotoent.3 b/man3/setprotoent.3 new file mode 100644 index 000000000..f8cb4bba2 --- /dev/null +++ b/man3/setprotoent.3 @@ -0,0 +1 @@ +.so man3/getprotoent.3 diff --git a/man3/setpwent.3 b/man3/setpwent.3 new file mode 100644 index 000000000..f2d121b80 --- /dev/null +++ b/man3/setpwent.3 @@ -0,0 +1 @@ +.so man3/getpwent.3 diff --git a/man3/setrpcent.3 b/man3/setrpcent.3 new file mode 100644 index 000000000..923085e2e --- /dev/null +++ b/man3/setrpcent.3 @@ -0,0 +1 @@ +.so man3/getrpcent.3 diff --git a/man3/setservent.3 b/man3/setservent.3 new file mode 100644 index 000000000..eaafb1c1e --- /dev/null +++ b/man3/setservent.3 @@ -0,0 +1 @@ +.so man3/getservent.3 diff --git a/man3/setspent.3 b/man3/setspent.3 new file mode 100644 index 000000000..142c5a5ca --- /dev/null +++ b/man3/setspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/setstate.3 b/man3/setstate.3 new file mode 100644 index 000000000..6e34104e2 --- /dev/null +++ b/man3/setstate.3 @@ -0,0 +1 @@ +.so man3/random.3 diff --git a/man3/setttyent.3 b/man3/setttyent.3 new file mode 100644 index 000000000..1cd11e3d8 --- /dev/null +++ b/man3/setttyent.3 @@ -0,0 +1 @@ +.so man3/getttyent.3 diff --git a/man3/setusershell.3 b/man3/setusershell.3 new file mode 100644 index 000000000..718ed12e9 --- /dev/null +++ b/man3/setusershell.3 @@ -0,0 +1 @@ +.so man3/getusershell.3 diff --git a/man3/setutent.3 b/man3/setutent.3 new file mode 100644 index 000000000..29c36b72a --- /dev/null +++ b/man3/setutent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/setutxent.3 b/man3/setutxent.3 new file mode 100644 index 000000000..29c36b72a --- /dev/null +++ b/man3/setutxent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/setvbuf.3 b/man3/setvbuf.3 new file mode 100644 index 000000000..dc02d9e88 --- /dev/null +++ b/man3/setvbuf.3 @@ -0,0 +1 @@ +.so man3/setbuf.3 diff --git a/man3/sgetspent.3 b/man3/sgetspent.3 new file mode 100644 index 000000000..142c5a5ca --- /dev/null +++ b/man3/sgetspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/sgetspent_r.3 b/man3/sgetspent_r.3 new file mode 100644 index 000000000..142c5a5ca --- /dev/null +++ b/man3/sgetspent_r.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/shm_open.3 b/man3/shm_open.3 new file mode 100644 index 000000000..63601fc30 --- /dev/null +++ b/man3/shm_open.3 @@ -0,0 +1,252 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 2002 Michael Kerrisk (mtk16@ext.canterbury.ac.nz) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH SHM_OPEN 3 2002-02-22 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +shm_open, shm_unlink \- Create/open or unlink POSIX shared memory objects +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int shm_open(const char *" name ", int " oflag ", mode_t " mode ); +.sp +.BI "int shm_unlink(const char *" name ); +.SH DESCRIPTION +.B shm_open +creates and opens a new, or opens an existing, POSIX shared memory object. +A POSIX shared memory object is in effect a handle which can +be used by unrelated processes to +.BR mmap (2) +the same region of shared memory. +The +.B shm_unlink +function performs the converse operation, +removing an object previously created by +.BR shm_open . +.LP +The operation of +.B shm_open +is analogous to that of +.BR open (2). +.I name +specifies the shared memory object to be created or opened. +For portable use, +.I name +should have an initial slash (/) and contain no embedded slashes. +.\" The names used may or may not live in a file system, and may or may not +.\" survive a reboot. Names starting with a slash are also visible to other +.\" processes. Other names have implementation-defined effect. +.LP +.I oflag +is a bit mask created by ORing together exactly one of +.B O_RDONLY +or +.B O_RWDR +and any of the other flags listed here: +.TP 1.1i +.B O_RDONLY +Open the object for read access. +A shared memory object opened in this way can only be +.BR mmap (2)ed +for read (\fBPROT_READ\fP) access. +.TP +.B O_RDWR +Open the object for read-write access. +.TP +.B O_CREAT +Create the shared memory object if it does not exist. +The user and group ownership of the object are set as for +.BR open (2), +and the object's +permission bits are set according to the low-order 9 bits of +.IR mode , +except that those bits set in the process file mode +creation mask (see +.BR umask (2)) +are cleared for the new object. +(A set of macro constants which can be used to define +.I mode +is listed in +.BR open (2).) +.sp +A new shared memory object initially has zero length \- the size of the +object can be set using +.BR ftruncate (2). +(The newly-allocated bytes of a shared memory +object are automatically initialised to 0.) +.TP +.B O_EXCL +If +.B O_CREAT +was also specified, and a share memory object with the given +.I name +already exists, return an error. +The check for the existence of the object, and its creation if it +does not exist, are performed atomically. +.TP +.B O_TRUNC +If the shared memory object already exists, truncate it to zero bytes. +.LP +On successful completion +.B shm_open +returns a new file descriptor referring to the shared memory object. +This file descriptor is guaranteed to be the lowest-numbered file descriptor +not previously opened within the process. +The +.B FD_CLOEXEC +flag (see +.BR fcntl (2)) +is set for the file descriptor. + +The file descriptor is normally used in subsequent calls +to +.BR ftruncate (2) +(for a newly-created object) and +.BR mmap (2). +After a call to +.BR mmap (2) +the file descriptor may be closed without affecting the memory mapping. + +The operation +of +.B shm_unlink +is analogous to +.BR unlink (2): +it removes a shared memory object name, and, once all processes +have unmapped the object, de-allocates and +destroys the contents of the associated memory region. +After a successful +.BR shm_unlink , +attempts to +.B shm_open +an object with the same +.I name +will fail (unless +.B O_CREAT +was specified, in which case a new, distinct object is created). +.SH "RETURN VALUE" +On success, +.B shm_open +returns a non-negative file descriptor. On failure, +.B shm_open +returns \-1. +.B shm_unlink +returns 0 on success, or \-1 on error. +.SH ERRORS +On failure, +.I errno +is set to indicate the cause of the error. Values which may appear in +.I errno +include the following: +.TP +.B EACCES +Permission to +.B shm_unlink +the shared memory object was denied. +.TP +.B EACCES +Permission was denied to +.B shm_open +.I name +in the specified +.IR mode, +or +.B O_TRUNC +was specified and the caller does not have write permission on the object. +.TP +.B EEXIST +Both +.B O_CREAT +and +.B O_EXCL +were specified to +.B shm_open +and the shared memory object specified by +.I name +already exists. +.TP +.B EINVAL +The +.I name +argument to +.B shm_open +was invalid. +.TP +.B EMFILE +The process already has the maximum number of files open. +.TP +.B ENAMETOOLONG +The length of +.I name +exceeds +.BR PATH_MAX . +.TP +.B ENFILE +The limit on the total number of files open on the system has been +reached. +.TP +.B ENOENT +An attempt was made to +.B shm_open +a +.I name +that did not exist, and +.B O_CREAT +was not specified. +.TP +.B ENOENT +An attempt was to made to +.B shm_unlink +a +.I name +that does not exist. +.SH "NOTES" +These functions are provided in glibc 2.2 and later. Programs using these +functions must specify the +.B \-lrt +flag to +.B cc +in order to link against the required ("realtime") library. +.LP +POSIX leaves the behavior of the combination of +.B O_RDONLY +and +.B O_TRUNC +unspecified. On Linux, this will successfully truncate an existing +shared memory object \- this may not be so on other Unices. +.LP +The POSIX shared memory object implementation on Linux 2.4 makes use +of a dedicated file system, which is normally +mounted under +.BR /dev/shm . +.SH "CONFORMING TO" +POSIX 1003.1 (2001). +.SH "SEE ALSO" +.BR close (2), +.BR fchmod (2), +.BR fchown (2), +.BR fcntl (2), +.BR fstat (2), +.BR ftruncate (2), +.BR mmap (2), +.BR open (2), +.BR umask (2) diff --git a/man3/sigaddset.3 b/man3/sigaddset.3 new file mode 100644 index 000000000..c73078101 --- /dev/null +++ b/man3/sigaddset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man3/sigdelset.3 b/man3/sigdelset.3 new file mode 100644 index 000000000..c73078101 --- /dev/null +++ b/man3/sigdelset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man3/sigemptyset.3 b/man3/sigemptyset.3 new file mode 100644 index 000000000..c73078101 --- /dev/null +++ b/man3/sigemptyset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man3/sigfillset.3 b/man3/sigfillset.3 new file mode 100644 index 000000000..c73078101 --- /dev/null +++ b/man3/sigfillset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man3/siginterrupt.3 b/man3/siginterrupt.3 new file mode 100644 index 000000000..aa5b20e33 --- /dev/null +++ b/man3/siginterrupt.3 @@ -0,0 +1,63 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:40:51 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Apr 14 16:20:34 1996 by Andries Brouwer (aeb@cwi.nl) +.TH SIGINTERRUPT 3 1993-04-13 "" "Linux Programmer's Manual" +.SH NAME +siginterrupt \- allow signals to interrupt system calls +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int siginterrupt(int " sig ", int " flag ); +.fi +.SH DESCRIPTION +The \fBsiginterrupt()\fP function changes the restart behaviour when +a system call is interrupted by the signal \fIsig\fP. If the \fIflag\fP +argument is false (0), then system calls will be restarted if interrupted +by the specified signal \fIsig\fP. This is the default behaviour in +Linux. However, when a new signal handler is specified with the +\fBsignal\fP(2) function, the system call is interrupted by default. +.PP +If the \fIflags\fP argument is true (1) and no data has been transferred, +then a system call interrupted by the signal \fIsig\fP will return \-1 +and the global variable \fIerrno\fP will be set to \fBEINTR\fP. +.PP +If the \fIflags\fP argument is true (1) and data transfer has started, +then the system call will be interrupted and will return the actual +amount of data transferred. +.SH "RETURN VALUE" +The \fBsiginterrupt()\fP function returns 0 on success, or \-1 if the +signal number \fIsig\fP is invalid. +.SH ERRORS +.TP +.B EINVAL +The specified signal number is invalid. +.SH "CONFORMING TO" +BSD 4.3 +.SH "SEE ALSO" +.BR signal (2) diff --git a/man3/sigismember.3 b/man3/sigismember.3 new file mode 100644 index 000000000..c73078101 --- /dev/null +++ b/man3/sigismember.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man3/siglongjmp.3 b/man3/siglongjmp.3 new file mode 100644 index 000000000..183a76043 --- /dev/null +++ b/man3/siglongjmp.3 @@ -0,0 +1 @@ +.so man3/longjmp.3 diff --git a/man3/signbit.3 b/man3/signbit.3 new file mode 100644 index 000000000..428dd4eaa --- /dev/null +++ b/man3/signbit.3 @@ -0,0 +1,25 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" Based on glibc infopages +.TH SIGNBIT 3 2002-08-10 "GNU" "libc math functions" +.SH NAME +signbit \- test sign of a real floating point number +.SH SYNOPSIS +.B "#include " +.sp +.BI "int signbit (" X ");" +.sp +Link with \-lm. +.SH DESCRIPTION +`signbit' is a generic macro which can work on all real floating-point +types. It returns a nonzero value if the value of X has its sign +bit set. +.PP +This is not the same as `x < 0.0', because IEEE 754 floating point +allows zero to be signed. The comparison `-0.0 < 0.0' is false, +but `signbit (-0.0)' will return a nonzero value. +.SH "CONFORMING TO" +This function is defined in IEC 559 (and the appendix with +recommended functions in IEEE 754/IEEE 854). +.SH "SEE ALSO" +.BR copysign (3) diff --git a/man3/significand.3 b/man3/significand.3 new file mode 100644 index 000000000..0bd2d34c4 --- /dev/null +++ b/man3/significand.3 @@ -0,0 +1,36 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" based on glibc infopages +.TH SIGNIFICAND 3 2002-08-10 "gnu" "Linux Programmer's Manual" +.SH NAME +significand, significandf, significandl \- +get mantissa of floating point number +.SH SYNOPSIS +.B #include +.sp +.BI "double significand(double " x ); +.br +.BI "float significandf(float " x ); +.br +.BI "long double significandl(long double " x ); +.sp +Link with \-lm. +.SH DESCRIPTION +The +.B significand() +function returns the mantissa of +.I x +scaled to the range [1,2). +It is equivalent to +.sp +.in +8 +scalb(x, (double) -ilogb(x)) +.in -8 +.PP +This function exists mainly for use in certain standardized tests +for IEEE 754 conformance. +.SH HISTORY +This function came from BSD. +.SH "SEE ALSO" +.BR ilogb (3), +.BR scalb (3) diff --git a/man3/significandf.3 b/man3/significandf.3 new file mode 100644 index 000000000..4ae39f580 --- /dev/null +++ b/man3/significandf.3 @@ -0,0 +1 @@ +.so man3/significand.3 diff --git a/man3/significandl.3 b/man3/significandl.3 new file mode 100644 index 000000000..4ae39f580 --- /dev/null +++ b/man3/significandl.3 @@ -0,0 +1 @@ +.so man3/significand.3 diff --git a/man3/sigsetjmp.3 b/man3/sigsetjmp.3 new file mode 100644 index 000000000..7cf497fc3 --- /dev/null +++ b/man3/sigsetjmp.3 @@ -0,0 +1 @@ +.so man3/setjmp.3 diff --git a/man3/sigsetops.3 b/man3/sigsetops.3 new file mode 100644 index 000000000..b6fea3e31 --- /dev/null +++ b/man3/sigsetops.3 @@ -0,0 +1,97 @@ +.\" Copyright (c) 1994 Mike Battersby +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified by aeb, 960721 +.\" +.TH SIGSETOPS 3 1994-09-24 "Linux 1.0" "Linux Programmer's Manual" + +.SH NAME +sigemptyset, sigfillset, sigaddset, sigdelset, sigismember \- POSIX +signal set operations. + +.SH SYNOPSIS +.B #include +.sp 2 +.BI "int sigemptyset(sigset_t *" set ); +.sp +.BI "int sigfillset(sigset_t *" set ); +.sp +.BI "int sigaddset(sigset_t *" set ", int " signum ); +.sp +.BI "int sigdelset(sigset_t *" set ", int " signum ); +.sp +.BI "int sigismember(const sigset_t *" set ", int " signum ); + +.SH DESCRIPTION +The +.BR sigsetops (3) +functions allow the manipulation of POSIX signal sets. +.PP +.B sigemptyset +initializes the signal set given by +.I set +to empty, with all signals excluded from the set. +.PP +.B sigfillset +initializes +.I set +to full, including all signals. +.PP +.B sigaddset +and +.B sigdelset +add and delete respectively signal +.I signum +from +.IR set . +.PP +.B sigismember +tests whether +.I signum +is a member of +.I set. +.SH "RETURN VALUE" +.BR sigemptyset ", " sigfillset ", " sigaddset +and +.B sigdelset +return 0 on success and \-1 on error. +.PP +.B sigismember +returns 1 if +.I signum +is a member of +.IR set , +0 if +.I signum +is not a member, and \-1 on error. +.SH ERRORS +.TP +.B EINVAL +.I sig +is not a valid signal. +.SH "CONFORMING TO" +POSIX +.SH "SEE ALSO" +.BR sigaction (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigsuspend (2) diff --git a/man3/sin.3 b/man3/sin.3 new file mode 100644 index 000000000..b1691b4c4 --- /dev/null +++ b/man3/sin.3 @@ -0,0 +1,59 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH SIN 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +sin, sinf, sinl \- sine function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double sin(double " x ); +.sp +.BI "float sinf(float " x ); +.sp +.BI "long double sinl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBsin()\fP function returns the sine of \fIx\fP, where \fIx\fP is +given in radians. +.SH "RETURN VALUE" +The \fBsin()\fP function returns a value between \-1 and 1. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR acos (3), +.BR asin (3), +.BR atan (3), +.BR atan2 (3), +.BR cos (3), +.BR tan (3) diff --git a/man3/sincos.3 b/man3/sincos.3 new file mode 100644 index 000000000..9dc7a107a --- /dev/null +++ b/man3/sincos.3 @@ -0,0 +1,29 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL, 2002-07-27 Walter Harms +.\" +.TH sincos 3 2004-10-05 "GNU" "Linux Programmer's Manual" +.SH NAME +sincos, sincosf, sincosl \- calculate sin and cos simultaneously +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void sincos(double " x ", double *" sin ", double *" cos ); +.sp +.BI "void sincosf(float " x ", float *" sin ", float *" cos ); +.sp +.BI "void sincosl(long double " x ", long double *" sin ", long double *" cos ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +Several applications need sine and cosine of the same angle +.IR x . +This function computes both at the same time, and stores the results +via the given pointers. +.SH "CONFORMING TO" +This function is a GNU extension. +.SH "SEE ALSO" +.BR cos (3), +.BR sin (3), +.BR tan (3) diff --git a/man3/sincosf.3 b/man3/sincosf.3 new file mode 100644 index 000000000..9faef654f --- /dev/null +++ b/man3/sincosf.3 @@ -0,0 +1 @@ +.so man3/sincos.3 diff --git a/man3/sincosl.3 b/man3/sincosl.3 new file mode 100644 index 000000000..9faef654f --- /dev/null +++ b/man3/sincosl.3 @@ -0,0 +1 @@ +.so man3/sincos.3 diff --git a/man3/sinf.3 b/man3/sinf.3 new file mode 100644 index 000000000..eab51f4a7 --- /dev/null +++ b/man3/sinf.3 @@ -0,0 +1 @@ +.so man3/sin.3 diff --git a/man3/sinh.3 b/man3/sinh.3 new file mode 100644 index 000000000..05ac95f4b --- /dev/null +++ b/man3/sinh.3 @@ -0,0 +1,58 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1996-06-08 by aeb +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH SINH 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +sinh, sinhf, sinhl \- hyperbolic sine function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double sinh(double " x ); +.sp +.BI "float sinhf(float " x ); +.sp +.BI "long double sinhl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBsinh()\fP function returns the hyperbolic sine of \fIx\fP, which +is defined mathematically as (exp(x) - exp(-x)) / 2. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899 (C99). +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR acosh (3), +.BR asinh (3), +.BR atanh (3), +.BR cosh (3), +.BR tanh (3) diff --git a/man3/sinhf.3 b/man3/sinhf.3 new file mode 100644 index 000000000..dc3ce9415 --- /dev/null +++ b/man3/sinhf.3 @@ -0,0 +1 @@ +.so man3/sinh.3 diff --git a/man3/sinhl.3 b/man3/sinhl.3 new file mode 100644 index 000000000..dc3ce9415 --- /dev/null +++ b/man3/sinhl.3 @@ -0,0 +1 @@ +.so man3/sinh.3 diff --git a/man3/sinl.3 b/man3/sinl.3 new file mode 100644 index 000000000..eab51f4a7 --- /dev/null +++ b/man3/sinl.3 @@ -0,0 +1 @@ +.so man3/sin.3 diff --git a/man3/sleep.3 b/man3/sleep.3 new file mode 100644 index 000000000..8a906ad80 --- /dev/null +++ b/man3/sleep.3 @@ -0,0 +1,59 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 18:16:02 1993 by Rik Faith (faith@cs.unc.edu) +.TH SLEEP 3 1993-04-07 "GNU" "Linux Programmer's Manual" +.SH NAME +sleep \- Sleep for the specified number of seconds +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "unsigned int sleep(unsigned int " "seconds" ); +.fi +.SH DESCRIPTION +.B sleep() +makes the current process sleep until +.I seconds +seconds have elapsed or a signal arrives which is not ignored. +.SH "RETURN VALUE" +Zero if the requested time has elapsed, or the number of seconds left to sleep. +.SH "CONFORMING TO" +POSIX.1 +.SH BUGS +.B sleep() +may be implemented using +.BR SIGALRM ; +mixing calls to +.B alarm() +and +.B sleep() +is a bad idea. +.PP +Using +.B longjmp() +from a signal handler or modifying the handling of +.B SIGALRM +while sleeping will cause undefined results. +.SH "SEE ALSO" +.BR alarm (2), +.BR signal (2) diff --git a/man3/snprintf.3 b/man3/snprintf.3 new file mode 100644 index 000000000..975530d90 --- /dev/null +++ b/man3/snprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man3/sprintf.3 b/man3/sprintf.3 new file mode 100644 index 000000000..975530d90 --- /dev/null +++ b/man3/sprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man3/sqrt.3 b/man3/sqrt.3 new file mode 100644 index 000000000..e39fb564d --- /dev/null +++ b/man3/sqrt.3 @@ -0,0 +1,56 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH SQRT 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +sqrt, sqrtf, sqrtl \- square root function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double sqrt(double " x ); +.sp +.BI "float sqrtf(float " x ); +.sp +.BI "long double sqrtl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBsqrt()\fP function returns the non-negative square root of \fIx\fP. +It fails and sets \fIerrno\fP to EDOM, if \fIx\fP is negative. +.SH ERRORS +.TP +.B EDOM +\fIx\fP is negative. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR hypot (3) diff --git a/man3/sqrtf.3 b/man3/sqrtf.3 new file mode 100644 index 000000000..81258bbc0 --- /dev/null +++ b/man3/sqrtf.3 @@ -0,0 +1 @@ +.so man3/sqrt.3 diff --git a/man3/sqrtl.3 b/man3/sqrtl.3 new file mode 100644 index 000000000..81258bbc0 --- /dev/null +++ b/man3/sqrtl.3 @@ -0,0 +1 @@ +.so man3/sqrt.3 diff --git a/man3/srand.3 b/man3/srand.3 new file mode 100644 index 000000000..b007c2fc2 --- /dev/null +++ b/man3/srand.3 @@ -0,0 +1 @@ +.so man3/rand.3 diff --git a/man3/srand48.3 b/man3/srand48.3 new file mode 100644 index 000000000..3133f7d62 --- /dev/null +++ b/man3/srand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man3/srand48_r.3 b/man3/srand48_r.3 new file mode 100644 index 000000000..81e9d8ef7 --- /dev/null +++ b/man3/srand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man3/srandom.3 b/man3/srandom.3 new file mode 100644 index 000000000..6e34104e2 --- /dev/null +++ b/man3/srandom.3 @@ -0,0 +1 @@ +.so man3/random.3 diff --git a/man3/sscanf.3 b/man3/sscanf.3 new file mode 100644 index 000000000..9fd424bb2 --- /dev/null +++ b/man3/sscanf.3 @@ -0,0 +1 @@ +.so man3/scanf.3 diff --git a/man3/ssignal.3 b/man3/ssignal.3 new file mode 100644 index 000000000..047cab287 --- /dev/null +++ b/man3/ssignal.3 @@ -0,0 +1 @@ +.so man3/gsignal.3 diff --git a/man3/stdarg.3 b/man3/stdarg.3 new file mode 100644 index 000000000..833e972d4 --- /dev/null +++ b/man3/stdarg.3 @@ -0,0 +1,290 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)stdarg.3 6.8 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:11:11 1993, faith@cs.unc.edu +.\" Additions, 2001-10-14, aeb +.\" +.TH STDARG 3 2001-10-14 "" "Linux Programmer's Manual" +.SH NAME +stdarg \- variable argument lists +.SH SYNOPSIS +.B #include +.sp +.BI "void va_start(va_list " ap ", " last ); +.br +.BI "" type " va_arg(va_list " ap ", " type ); +.br +.BI "void va_end(va_list " ap ); +.br +.BI "void va_copy(va_list " dest ", va_list " src ); +.SH DESCRIPTION +A function may be called with a varying number of arguments of varying +types. The include file +.I stdarg.h +declares a type +.B va_list +and defines three macros for stepping through a list of arguments whose +number and types are not known to the called function. +.PP +The called function must declare an object of type +.B va_list +which is used by the macros +.BR va_start , +.BR va_arg , +and +.BR va_end . +.SS va_start +The +.B va_start +macro initializes +.I ap +for subsequent use by +.B va_arg +and +.BR va_end , +and must be called first. +.PP +The parameter +.I last +is the name of the last parameter before the variable argument list, i.e., +the last parameter of which the calling function knows the type. +.PP +Because the address of this parameter may be used in the +.B va_start +macro, it should not be declared as a register variable, +or as a function or an array type. +.SS va_arg +The +.B va_arg +macro expands to an expression that has the type and value of the next +argument in the call. The parameter +.I ap +is the +.B va_list +.I ap +initialized by +.BR va_start . +Each call to +.B va_arg +modifies +.I ap +so that the next call returns the next argument. The parameter +.I type +is a type name specified so that the type of a pointer to an object that +has the specified type can be obtained simply by adding a * to +.IR type . +.PP +The first use of the +.B va_arg +macro after that of the +.B va_start +macro returns the argument after +.IR last . +Successive invocations return the values of the remaining arguments. +.PP +If there is no next argument, or if +.I type +is not compatible with the type of the actual next argument (as promoted +according to the default argument promotions), random errors will occur. +.PP +If +.I ap +is passed to a function that uses +.BI va_arg( ap , type ) +then the value of +.I ap +is undefined after the return of that function. +.SS va_end +Each invocation of +.B va_start +must be matched by a corresponding invocation of +.B va_end +in the same function. After the call +.BI va_end( ap ) +the variable +.I ap +is undefined. Multiple transversals of the list, each +bracketed by +.B va_start +and +.B va_end +are possible. +.B va_end +may be a macro or a function. +.SS va_copy +.\" Proposal from clive@demon.net, 1997-02-28 +An obvious implementation would have a +.B va_list +a pointer to the stack frame of the variadic function. +In such a setup (by far the most common) there seems +nothing against an assignment +.RS +.nf + va_list aq = ap; +.fi +.RE +Unfortunately, there are also systems that make it an +array of pointers (of length 1), and there one needs +.RS +.nf + va_list aq; + *aq = *ap; +.fi +.RE +Finally, on systems where parameters are passed in registers, +it may be necessary for +.B va_start +to allocate memory, store the parameters there, and also +an indication of which parameter is next, so that +.B va_arg +can step through the list. Now +.B va_end +can free the allocated memory again. +To accommodate this situation, C99 adds a macro +.BR va_copy , +so that the above assignment can be replaced by +.RS +.nf + va_list aq; + va_copy(aq, ap); + ... + va_end(aq); +.fi +.RE +Each invocation of +.B va_copy +must be matched by a corresponding invocation of +.B va_end +in the same function. +Some systems that do not supply +.B va_copy +have +.B __va_copy +instead, since that was the name used in the draft proposal. +.SH EXAMPLES +The function +.I foo +takes a string of format characters and prints out the argument associated +with each format character based on the type. +.RS +.nf +#include +#include + +void foo(char *fmt, ...) { + va_list ap; + int d; + char c, *p, *s; + + va_start(ap, fmt); + while (*fmt) + switch(*fmt++) { + case 's': /* string */ + s = va_arg(ap, char *); + printf("string %s\en", s); + break; + case 'd': /* int */ + d = va_arg(ap, int); + printf("int %d\en", d); + break; + case 'c': /* char */ + /* need a cast here since va_arg only + takes fully promoted types */ + c = (char) va_arg(ap, int); + printf("char %c\en", c); + break; + } + va_end(ap); +} +.fi +.RE +.SH "CONFORMING TO" +The +.BR va_start , +.BR va_arg , +and +.B va_end +macros conform to ANSI X3.159-1989 (``C89''). +C99 defines the +.B va_copy +macro. +.SH COMPATIBILITY +These macros are +.I not +compatible with the historic macros they replace. A backward compatible +version can be found in the include file +.IR varargs.h . +.SH COMPARISON +The historic setup is: +.RS +.nf +#include + +void foo(va_alist) va_dcl { + va_list ap; + + va_start(ap); + while(...) { + ... + x = va_arg(ap, type); + ... + } + va_end(ap); +} +.fi +.RE +On some systems, +.I va_end +contains a closing '}' matching a '{' in +.IR va_start , +so that both macros must occur in the same function, and in a way +that allows this. +.SH BUGS +Unlike the +.B varargs +macros, the +.B stdarg +macros do not permit programmers to code a function with no fixed +arguments. This problem generates work mainly when converting +.B varargs +code to +.B stdarg +code, but it also creates difficulties for variadic functions that wish to +pass all of their arguments on to a function that takes a +.B va_list +argument, such as +.BR vfprintf (3). diff --git a/man3/stderr.3 b/man3/stderr.3 new file mode 100644 index 000000000..752ae2794 --- /dev/null +++ b/man3/stderr.3 @@ -0,0 +1 @@ +.so man3/stdin.3 diff --git a/man3/stdin.3 b/man3/stdin.3 new file mode 100644 index 000000000..42d027175 --- /dev/null +++ b/man3/stdin.3 @@ -0,0 +1,130 @@ +.\" From dholland@burgundy.eecs.harvard.edu Tue Mar 24 18:08:15 1998 +.\" +.\" This man page was written in 1998 by David A. Holland +.\" and placed in the Public Domain. Polished a bit by aeb. +.\" +.Dd March 24, 1998 +.Dt STDIN 3 +.Os "Linux 2.0" +.Sh NAME +.Nm stdin , +.Nm stdout , +.Nm stderr +.Nd standard I/O streams +.Sh SYNOPSIS +.Fd #include +.Fd extern FILE *stdin; +.Fd extern FILE *stdout; +.Fd extern FILE *stderr; +.Sh DESCRIPTION +Under normal circumstances every Unix program has three streams opened +for it when it starts up, one for input, one for output, and one for +printing diagnostic or error messages. These are typically attached to +the user's terminal (see +.Xr tty 4 ) +but might instead refer to files or other devices, depending on what +the parent process chose to set up. (See also the ``Redirection'' section of +.Xr sh 1 .) +.Pp +The input stream is referred to as ``standard input''; the output stream is +referred to as ``standard output''; and the error stream is referred to +as ``standard error''. These terms are abbreviated to form the symbols +used to refer to these files, namely +.Nm stdin , +.Nm stdout , +and +.Nm stderr . +.Pp +Each of these symbols is a +.Xr stdio 3 +macro of type pointer to FILE, and can be used with functions like +.Xr fprintf 3 +or +.Xr fread 3 . +.Pp +Since FILEs are a buffering wrapper around Unix file descriptors, the +same underlying files may also be accessed using the raw Unix file +interface, that is, the functions like +.Xr read 2 +and +.Xr lseek 2 . +The integer file descriptors associated with the streams +.Nm stdin , +.Nm stdout , +and +.Nm stderr +are 0, 1, and 2, respectively. The preprocessor symbols STDIN_FILENO, +STDOUT_FILENO, and STDERR_FILENO are defined with these values in +. +.Pp +Note that mixing use of FILEs and raw file descriptors can produce +unexpected results and should generally be avoided. +(For the masochistic among you: POSIX.1, section 8.2.3, describes +in detail how this interaction is supposed to work.) +A general rule is that file descriptors are handled in the kernel, +while stdio is just a library. This means for example, that after an +exec, the child inherits all open file descriptors, but all old streams +have become inaccessible. +.Pp +Since the symbols +.Nm stdin , +.Nm stdout , +and +.Nm stderr +are specified to be macros, assigning to them is non-portable. +The standard streams can be made to refer to different files +with help of the library function +.Xr freopen 3 , +specially introduced to make it possible to reassign +.Nm stdin , +.Nm stdout , +and +.Nm stderr . +The standard streams are closed by a call to +.Xr exit 3 +and by normal program termination. +.Sh SEE ALSO +.Xr sh 1 , +.Xr csh 1 , +.Xr open 2 , +.Xr fopen 3 , +.Xr stdio 3 +.Sh CONSIDERATIONS +The stream +.Nm stderr +is unbuffered. The stream +.Nm stdout +is line-buffered when it points to a terminal. Partial lines will not +appear until +.Xr fflush 3 +or +.Xr exit 3 +is called, or a newline is printed. This can produce unexpected +results, especially with debugging output. +The buffering mode of the standard streams (or any other stream) +can be changed using the +.Xr setbuf 3 +or +.Xr setvbuf 3 +call. +Note that in case +.Nm stdin +is associated with a terminal, there may also be input buffering +in the terminal driver, entirely unrelated to stdio buffering. +(Indeed, normally terminal input is line buffered in the kernel.) +This kernel input handling can be modified using calls like +.Xr tcsetattr 3 ; +see also +.Xr stty 1 , +and +.Xr termios 3 . +.Sh "CONFORMING TO" +The +.Nm stdin , +.Nm stdout , +and +.Nm stderr +macros conform to +.St -ansiC , +and this standard also stipulates that these three +streams shall be open at program startup. diff --git a/man3/stdio.3 b/man3/stdio.3 new file mode 100644 index 000000000..512f8574b --- /dev/null +++ b/man3/stdio.3 @@ -0,0 +1,353 @@ +.\" Copyright (c) 1990, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)stdio.3 6.5 (Berkeley) 5/6/91 +.\" +.\" Converted for Linux, Mon Nov 29 16:07:22 1993, faith@cs.unc.edu +.\" Modified, 2001-12-26, aeb +.\" +.TH STDIO 3 2001-12-26 "" "Linux Programmer's Manual" +.SH NAME +stdio \- standard input/output library functions +.SH SYNOPSIS +.B #include +.sp +.B FILE *stdin; +.br +.B FILE *stdout; +.br +.B FILE *stderr; +.SH DESCRIPTION +The standard I/O library provides a simple and efficient buffered stream +I/O interface. Input and output is mapped into logical data streams and the +physical I/O characteristics are concealed. The functions and macros are +listed below; more information is available from the individual man pages. +.PP +A stream is associated with an external file (which may be a physical +device) by +.I opening +a file, which may involve creating a new file. Creating an existing file +causes its former contents to be discarded. If a file can support +positioning requests (such as a disk file, as opposed to a terminal) then a +.I file position indicator +associated with the stream is positioned at the start of the file (byte +zero), unless the file is opened with append mode. If append mode is used, +it is unspecified whether the position indicator will be placed at the +start or the end of the file. The position indicator is maintained by +subsequent reads, writes and positioning requests. All input occurs +as if the characters were read by successive calls to the +.BR fgetc (3) +function; all output takes place as if all characters were written by +successive calls to the +.BR fputc (3) +function. +.PP +A file is disassociated from a stream by +.I closing +the file. Output streams are flushed (any unwritten buffer contents are +transferred to the host environment) before the stream is disassociated from +the file. The value of a pointer to a +.B FILE +object is indeterminate after a file is closed (garbage). +.PP +A file may be subsequently reopened, by the same or another program +execution, and its contents reclaimed or modified (if it can be +repositioned at the start). If the main function returns to its original +caller, or the +.BR exit (3) +function is called, all open files are closed (hence all output streams are +flushed) before program termination. Other methods of program termination, +such as +.BR abort (3) +do not bother about closing files properly. +.PP +At program startup, three text streams are predefined and need not be +opened explicitly \(em +.I standard input +(for reading conventional input), \(em +.I standard output +(for writing conventional input), and +.I standard error +(for writing diagnostic output). These streams are abbreviated +.IR stdin , stdout +and +.IR stderr . +When opened, the standard error stream is not fully buffered; the standard +input and output streams are fully buffered if and only if the streams do +not to refer to an interactive device. +.PP +Output streams that refer to terminal devices are always line buffered by +default; pending output to such streams is written automatically whenever +an input stream that refers to a terminal device is read. In cases where a +large amount of computation is done after printing part of a line on an +output terminal, it is necessary to +.BR fflush (3) +the standard output before going off and computing so that the output will +appear. +.PP +The +.B stdio +library is a part of the library +.B libc +and routines are automatically loaded as needed by the compilers +.BR cc (1) +and +.BR pc (1). +The +.B SYNOPSIS +sections of the following manual pages indicate which include files are to +be used, what the compiler declaration for the function looks like and +which external variables are of interest. +.PP +The following are defined as macros; these names may not be re-used without +first removing their current definitions with +.BR #undef : +.BR BUFSIZ , +.BR EOF , +.BR FILENAME_MAX , +.BR FOPEN_MAX , +.BR L_cuserid , +.BR L_ctermid , +.BR L_tmpnam, +.BR NULL , +.BR SEEK_END , +.BR SEEK_SET , +.BR SEE_CUR , +.BR TMP_MAX , +.BR clearerr , +.BR feof , +.BR ferror , +.BR fileno , +.BR fropen , +.BR fwopen , +.BR getc , +.BR getchar , +.BR putc , +.BR putchar , +.BR stderr , +.BR stdin , +.BR stdout . +Function versions of the macro functions +.BR feof , +.BR ferror , +.BR clearerr , +.BR fileno , +.BR getc , +.BR getchar , +.BR putc , +and +.B putchar +exist and will be used if the macros definitions are explicitly removed. +.SH "LIST OF FUNCTIONS" +.TP 10n +.B Function +.B Description +.TP +.B clearerr +check and reset stream status +.TP +.B fclose +close a stream +.TP +.B fdopen +stream open functions +.TP +.B feof +check and reset stream status +.TP +.B ferror +check and reset stream status +.TP +.B fflush +flush a stream +.TP +.B fgetc +get next character or word from input stream +.\" .TP +.\" .B fgetline +.\" get a line from a stream (BSD only; renamed to fgetln()) +.TP +.B fgetpos +reposition a stream +.TP +.B fgets +get a line from a stream +.TP +.B fileno +return the integer descriptor of the argument stream +.TP +.B fopen +stream open functions +.TP +.B fprintf +formatted output conversion +.TP +.B fpurge +flush a stream +.TP +.B fputc +output a character or word to a stream +.TP +.B fputs +output a line to a stream +.TP +.B fread +binary stream input/output +.TP +.B freopen +stream open functions +.TP +.B fropen +open a stream +.TP +.B fscanf +input format conversion +.TP +.B fseek +reposition a stream +.TP +.B fsetpos +reposition a stream +.TP +.B ftell +reposition a stream +.TP +.B fwrite +binary stream input/output +.TP +.B getc +get next character or word from input stream +.TP +.B getchar +get next character or word from input stream +.TP +.B gets +get a line from a stream +.TP +.B getw +get next character or word from input stream +.TP +.B mktemp +make temporary file name (unique) +.TP +.B perror +system error messages +.TP +.B printf +formatted output conversion +.TP +.B putc +output a character or word to a stream +.TP +.B putchar +output a character or word to a stream +.TP +.B puts +output a line to a stream +.TP +.B putw +output a character or word to a stream +.TP +.B remove +remove directory entry +.TP +.B rewind +reposition a stream +.TP +.B scanf +input format conversion +.TP +.B setbuf +stream buffering operations +.TP +.B setbuffer +stream buffering operations +.TP +.B setlinebuf +stream buffering operations +.TP +.B setvbuf +stream buffering operations +.TP +.B sprintf +formatted output conversion +.TP +.B sscanf +input format conversion +.TP +.B strerror +system error messages +.TP +.B sys_errlist +system error messages +.TP +.B sys_nerr +system error messages +.TP +.B tempnam +temporary file routines +.TP +.B tmpfile +temporary file routines +.TP +.B tmpnam +temporary file routines +.TP +.B ungetc +un-get character from input stream +.TP +.B vfprintf +formatted output conversion +.TP +.B vfscanf +input format conversion +.TP +.B vprintf +formatted output conversion +.TP +.B vscanf +input format conversion +.TP +.B vsprintf +formatted output conversion +.TP +.B vsscanf +input format conversion +.SH "CONFORMING TO" +The +.B stdio +library conforms to ANSI X3.159-1989 (``ANSI C''). +.SH "SEE ALSO" +.BR close (2), +.BR open (2), +.BR read (2), +.BR write (2), +.BR stdout (3) diff --git a/man3/stdio_ext.3 b/man3/stdio_ext.3 new file mode 100644 index 000000000..d8cb85de6 --- /dev/null +++ b/man3/stdio_ext.3 @@ -0,0 +1,123 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH STDIO_EXT 3 2001-12-16 "" "Linux Programmer's Manual" +.SH NAME +__fbufsize, __flbf, __fpending, __fpurge, __freadable, __freading, __fsetlocking, __fwritable, __fwriting, _flushlbf \- interfaces to stdio FILE structure +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "size_t __fbufsize(FILE *" stream ); +.br +.BI "size_t __fpending(FILE *" stream ); +.br +.BI "int __flbf(FILE *" stream ); +.br +.BI "int __freadable(FILE *" stream ); +.br +.BI "int __fwritable(FILE *" stream ); +.br +.BI "int __freading(FILE *" stream ); +.br +.BI "int __fwriting(FILE *" stream ); +.br +.BI "int __fsetlocking(FILE *" stream ", int " type ); +.br +.BI "void _flushlbf(void); +.br +.BI "void __fpurge(FILE *" stream ); +.SH DESCRIPTION +Solaris introduced routines to allow portable access to the +internals of the FILE structure, and glibc also implemented these. +.LP +The +.B __fbufsize() +function returns the size of the buffer currently used +by the given stream. +.LP +The +.B __fpending() +function returns the number of bytes in the output buffer. +For wide-oriented streams the unit is wide characters. +This function is undefined on buffers in reading mode, +or opened read-only. +.LP +The +.B __flbf() +function returns a nonzero value if the stream is line-buffered, +and zero otherwise. +.LP +The +.B __freadable() +function returns a nonzero value if the stream allows reading, +and zero otherwise. +.LP +The +.B __fwritable() +function returns a nonzero value if the stream allows writing, +and zero otherwise. +.LP +The +.B __freading() +function returns a nonzero value if the stream is read-only, or +if the last operation on the stream was a read operation, +and zero otherwise. +.LP +The +.B __fwriting() +function returns a nonzero value if the stream is write-only (or +append-only), or if the last operation on the stream was a write +operation, and zero otherwise. +.LP +The +.B __fsetlocking() +function can be used to select the desired type of locking on the stream. +It returns the current type. The +.I type +parameter can take the following three values: +.TP +.B FSETLOCKING_INTERNAL +Perform implicit locking around every operation on the given stream +(except for the *_unlocked ones). This is the default. +.TP +.B FSETLOCKING_BYCALLER +The caller will take care of the locking (possibly using +.BR flockfile (3) +in case there is more than one thread), and the stdio routines +will not do locking until the state is reset to FSETLOCKING_INTERNAL. +.TP +.B FSETLOCKING_QUERY +Don't change the type of locking. (Only return it.) +.LP +The +.B _flushlbf() +function flushes all line-buffered streams. (Presumably so that +output to a terminal is forced out, say before reading keyboard input.) +.LP +The +.B __fpurge() +function discards the contents of the stream's buffer. +.SH "SEE ALSO" +.BR flockfile (3), +.BR fpurge (3) diff --git a/man3/stdout.3 b/man3/stdout.3 new file mode 100644 index 000000000..752ae2794 --- /dev/null +++ b/man3/stdout.3 @@ -0,0 +1 @@ +.so man3/stdin.3 diff --git a/man3/stpcpy.3 b/man3/stpcpy.3 new file mode 100644 index 000000000..2694e7821 --- /dev/null +++ b/man3/stpcpy.3 @@ -0,0 +1,70 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1995 James R. Van Zandt +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH STPCPY 3 1995-09-03 "GNU" "Linux Programmer's Manual" +.SH NAME +stpcpy \- copy a string returning a pointer to its end +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "char *stpcpy(char *" dest ", const char *" src ); +.fi +.SH DESCRIPTION +The \fBstpcpy()\fP function copies the string pointed to by \fIsrc\fP +(including the terminating `\\0' character) to the array pointed to by +\fIdest\fP. The strings may not overlap, and the destination string +\fIdest\fP must be large enough to receive the copy. +.SH "RETURN VALUE" +\fBstpcpy()\fP returns a pointer to the \fBend\fP of the string +\fIdest\fP (that is, the address of the terminating null character) +rather than the beginning. +.SH EXAMPLE +For example, this program uses \fBstpcpy\fP to concatenate \fBfoo\fP and +\fBbar\fP to produce \fBfoobar\fP, which it then prints. +.nf + + #include + + int + main (void) + { + char *to = buffer; + to = stpcpy (to, "foo"); + to = stpcpy (to, "bar"); + printf ("%s\\n", buffer); + } +.fi +.SH "CONFORMING TO" +This function is not part of the ANSI or POSIX standards, and is +not customary on Unix systems, but is not a GNU invention either. +Perhaps it comes from MS-DOS. +.SH "SEE ALSO" +.BR bcopy (3), +.BR memccpy (3), +.BR memcpy (3), +.BR memmove (3), +.BR strcpy (3) diff --git a/man3/stpncpy.3 b/man3/stpncpy.3 new file mode 100644 index 000000000..fe758a6f8 --- /dev/null +++ b/man3/stpncpy.3 @@ -0,0 +1,43 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" +.\" Corrected, aeb, 990824 +.TH STPNCPY 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +stpncpy \- copy a fixed-size string, returning a pointer to its end +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "char *stpncpy(char *" dest ", const char *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBstpncpy\fP function copies at most \fIn\fP characters from the string +pointed to by \fIsrc\fP, including the terminating '\\0' character, to the +array pointed to by \fIdest\fP. Exactly \fIn\fP characters are written at +\fIdest\fP. If the length \fIstrlen(src)\fP is smaller than \fIn\fP, the +remaining characters in the array pointed to by \fIdest\fP are filled +with '\\0' characters. If the length \fIstrlen(src)\fP is greater or equal to +\fIn\fP, the string pointed to by \fIdest\fP will not be '\\0' terminated. +.PP +The strings may not overlap. +.PP +The programmer must ensure that there is room for at least \fIn\fP characters +at \fIdest\fP. +.SH "RETURN VALUE" +\fBstpncpy\fP returns a pointer to the terminating null +in \fIdest\fP, or, if \fIdest\fP is not null-terminated, +\fIdest + n\fP. +.SH "CONFORMING TO" +This function is a GNU extension. +.SH "SEE ALSO" +.BR strncpy (3) diff --git a/man3/strcasecmp.3 b/man3/strcasecmp.3 new file mode 100644 index 000000000..70e05c7ec --- /dev/null +++ b/man3/strcasecmp.3 @@ -0,0 +1,61 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:12:45 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRCASECMP 3 1993-04-11 "" "Linux Programmer's Manual" +.SH NAME +strcasecmp, strncasecmp \- compare two strings ignoring case +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int strcasecmp(const char *" s1 ", const char *" s2 ); +.sp +.BI "int strncasecmp(const char *" s1 ", const char *" s2 ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBstrcasecmp()\fP function compares the two strings \fIs1\fP and +\fIs2\fP, ignoring the case of the characters. It returns an integer +less than, equal to, or greater than zero if \fIs1\fP is found, +respectively, to be less than, to match, or be greater than \fIs2\fP. +.PP +The \fBstrncasecmp()\fP function is similar, except it only compares +the first \fIn\fP characters of \fIs1\fP. +.SH "RETURN VALUE" +The \fBstrcasecmp()\fP and \fBstrncasecmp()\fP functions return +an integer less than, equal to, or greater than zero if \fIs1\fP +(or the first \fIn\fP bytes thereof) is found, respectively, to be +less than, to match, or be greater than \fIs2\fP. +.SH "CONFORMING TO" +BSD 4.4 +.SH "SEE ALSO" +.BR bcmp (3), +.BR memcmp (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strncmp (3), +.BR wcscasecmp (3), +.BR wcsncasecmp (3) diff --git a/man3/strcat.3 b/man3/strcat.3 new file mode 100644 index 000000000..fbb370130 --- /dev/null +++ b/man3/strcat.3 @@ -0,0 +1,62 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:11:47 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRCAT 3 1993-04-11 "GNU" "Linux Programmer's Manual" +.SH NAME +strcat, strncat \- concatenate two strings +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *strcat(char *" dest ", const char *" src ); +.sp +.BI "char *strncat(char *" dest ", const char *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBstrcat()\fP function appends the \fIsrc\fP string to the +\fIdest\fP string overwriting the `\\0' character at the end of +\fIdest\fP, and then adds a terminating `\\0' character. The +strings may not overlap, and the \fIdest\fP string must have +enough space for the result. +.PP +The \fBstrncat()\fP function is similar, except that it will use +at most \fIn\fP characters from \fIsrc\fP. +Since the result is always terminated with `\\0', at most \fIn\fP+1 +characters are written. +.SH "RETURN VALUE" +The \fBstrcat()\fP and \fBstrncat()\fP functions return a pointer +to the resulting string \fIdest\fP. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899 +.SH "SEE ALSO" +.BR bcopy (3), +.BR memccpy (3), +.BR memcpy (3), +.BR strcpy (3), +.BR strncpy (3), +.BR wcscat (3), +.BR wcsncat (3) diff --git a/man3/strchr.3 b/man3/strchr.3 new file mode 100644 index 000000000..c5a430a2b --- /dev/null +++ b/man3/strchr.3 @@ -0,0 +1,63 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Apr 12 12:51:24 1993, David Metcalfe +.TH STRCHR 3 1993-04-12 "" "Linux Programmer's Manual" +.SH NAME +strchr, strrchr \- locate character in string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *strchr(const char *" s ", int " c ); +.sp +.BI "char *strrchr(const char *" s ", int " c ); +.fi +.SH DESCRIPTION +The \fBstrchr()\fP function returns a pointer to the first occurrence +of the character \fIc\fP in the string \fIs\fP. +.PP +The \fBstrrchr()\fP function returns a pointer to the last occurrence +of the character \fIc\fP in the string \fIs\fP. +.PP +Here "character" means "byte" - these functions do not work with +wide or multi-byte characters. +.SH "RETURN VALUE" +The \fBstrchr()\fP and \fBstrrchr()\fP functions return a pointer to +the matched character or NULL if the character is not found. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899 +.SH "SEE ALSO" +.BR index (3), +.BR memchr (3), +.BR rindex (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3), +.BR wcschr (3), +.BR wcsrchr (3) diff --git a/man3/strcmp.3 b/man3/strcmp.3 new file mode 100644 index 000000000..80081d7e1 --- /dev/null +++ b/man3/strcmp.3 @@ -0,0 +1,61 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:08:52 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-08-31, aeb +.\" +.TH STRCMP 3 1993-04-11 "" "Linux Programmer's Manual" +.SH NAME +strcmp, strncmp \- compare two strings +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int strcmp(const char *" s1 ", const char *" s2 ); +.sp +.BI "int strncmp(const char *" s1 ", const char *" s2 ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBstrcmp()\fP function compares the two strings \fIs1\fP and +\fIs2\fP. It returns an integer less than, equal to, or greater +than zero if \fIs1\fP is found, respectively, to be less than, +to match, or be greater than \fIs2\fP. +.PP +The \fBstrncmp()\fP function is similar, except it only compares +the first (at most) \fIn\fP characters of \fIs1\fP and \fIs2\fP. +.SH "RETURN VALUE" +The \fBstrcmp()\fP and \fBstrncmp()\fP functions return an integer +less than, equal to, or greater than zero if \fIs1\fP (or the first +\fIn\fP bytes thereof) is found, respectively, to be less than, to +match, or be greater than \fIs2\fP. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899 +.SH "SEE ALSO" +.BR bcmp (3), +.BR memcmp (3), +.BR strcasecmp (3), +.BR strcoll (3), +.BR strncasecmp (3) diff --git a/man3/strcoll.3 b/man3/strcoll.3 new file mode 100644 index 000000000..3dc989f11 --- /dev/null +++ b/man3/strcoll.3 @@ -0,0 +1,60 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:40:44 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRCOLL 3 1993-04-12 "GNU" "Linux Programmer's Manual" +.SH NAME +strcoll \- compare two strings using the current locale +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int strcoll(const char *" s1 ", const char *" s2 ); +.fi +.SH DESCRIPTION +The \fBstrcoll()\fP function compares the two strings \fIs1\fP and +\fIs2\fP. It returns an integer less than, equal to, or greater +than zero if \fIs1\fP is found, respectively, to be less than, +to match, or be greater than \fIs2\fP. The comparison is based on +strings interpreted as appropriate for the program's current locale +for category \fILC_COLLATE\fP. (See \fBsetlocale\fP(3)). +.SH "RETURN VALUE" +The \fBstrcoll()\fP function returns an integer less than, equal to, +or greater than zero if \fIs1\fP is found, respectively, to be less +than, to match, or be greater than \fIs2\fP, when both are interpreted +as appropriate for the current locale. +.SH "CONFORMING TO" +SVID 3, BSD 4.3, ISO 9899 +.SH NOTES +In the \fI"POSIX"\fP or \fI"C"\fP locales \fBstrcoll()\fP is equivalent to +\fBstrcmp()\fP. +.SH "SEE ALSO" +.BR bcmp (3), +.BR memcmp (3), +.BR setlocale (3), +.BR strcasecmp (3), +.BR strcmp (3), +.BR strxfrm (3) diff --git a/man3/strcpy.3 b/man3/strcpy.3 new file mode 100644 index 000000000..7e6a54438 --- /dev/null +++ b/man3/strcpy.3 @@ -0,0 +1,76 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:06:49 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Aug 25 23:17:51 1995 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Wed Dec 18 00:47:18 1996 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH STRCPY 3 1993-04-11 "GNU" "Linux Programmer's Manual" +.SH NAME +strcpy, strncpy \- copy a string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *strcpy(char *" dest ", const char *" src ); +.sp +.BI "char *strncpy(char *" dest ", const char *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBstrcpy()\fP function copies the string pointed to by \fIsrc\fP +(including the terminating `\\0' character) to the array pointed to by +\fIdest\fP. The strings may not overlap, and the destination string +\fIdest\fP must be large enough to receive the copy. +.PP +The \fBstrncpy()\fP function is similar, except that not more than +\fIn\fP bytes of \fIsrc\fP are copied. Thus, if there is no null byte +among the first \fIn\fP bytes of \fIsrc\fP, the result will not be +null-terminated. +.PP +In the case where the length of +.I src +is less than that of +.IR n , +the remainder of +.I dest +will be padded with nulls. +.SH "RETURN VALUE" +The \fBstrcpy()\fP and \fBstrncpy()\fP functions return a pointer to +the destination string \fIdest\fP. +.SH BUGS +If the destination string of a \fBstrcpy()\fP is not large enough +(that is, if the programmer was stupid/lazy, and failed to check +the size before copying) then anything might happen. +Overflowing fixed length strings is a favourite cracker technique. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899 +.SH "SEE ALSO" +.BR bcopy (3), +.BR memccpy (3), +.BR memcpy (3), +.BR memmove (3), +.BR wcscpy (3), +.BR wcsncpy (3) diff --git a/man3/strcspn.3 b/man3/strcspn.3 new file mode 100644 index 000000000..26284f29a --- /dev/null +++ b/man3/strcspn.3 @@ -0,0 +1 @@ +.so man3/strspn.3 diff --git a/man3/strdup.3 b/man3/strdup.3 new file mode 100644 index 000000000..b15db54f2 --- /dev/null +++ b/man3/strdup.3 @@ -0,0 +1,78 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:41:34 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Wed Oct 17 01:12:26 2001 by John Levon +.TH STRDUP 3 1993-04-12 "GNU" "Linux Programmer's Manual" +.SH NAME +strdup, strndup, strdupa, strndupa \- duplicate a string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *strdup(const char *" s ); +.sp +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "char *strndup(const char *" s ", size_t " n ); +.br +.BI "char *strdupa(const char *" s ); +.br +.BI "char *strndupa(const char *" s ", size_t " n ); +.sp +.fi +.SH DESCRIPTION +The \fBstrdup()\fP function returns a pointer to a new string which +is a duplicate of the string \fIs\fP. Memory for the new string is +obtained with \fBmalloc\fP(3), and can be freed with \fBfree\fP(3). + +The \fBstrndup()\fP function is similar, but only copies at most +\fIn\fP characters. If \fIs\fP is longer than \fIn\fP, only \fIn\fP +characters are copied, and a terminating NUL is added. + +\fBstrdupa\fP and \fBstrndupa\fP are similar, but use \fBalloca(3)\fP +to allocate the buffer. They are only available when using the GNU +GCC suite, and suffer from the same limitations described in \fBalloca(3)\fP. + +.SH "RETURN VALUE" +The \fBstrdup()\fP function returns a pointer to the duplicated +string, or NULL if insufficient memory was available. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory available to allocate duplicate string. +.SH "CONFORMING TO" +.\" 4.3BSD-Reno, not (first) BSD 4.3. +SVID 3, BSD 4.3. +\fBstrndup()\fP, \fBstrdupa()\fP, and \fBstrndupa()\fP are GNU extensions. +.SH "SEE ALSO" +.BR alloca (3), +.BR calloc (3), +.BR free (3), +.BR malloc (3), +.BR realloc (3) diff --git a/man3/strdupa.3 b/man3/strdupa.3 new file mode 100644 index 000000000..2dd8f88c3 --- /dev/null +++ b/man3/strdupa.3 @@ -0,0 +1 @@ +.so man3/strdup.3 diff --git a/man3/strerror.3 b/man3/strerror.3 new file mode 100644 index 000000000..5b9f2d0c3 --- /dev/null +++ b/man3/strerror.3 @@ -0,0 +1,94 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:05:30 1993 by Rik Faith +.\" Modified Fri Feb 16 14:25:17 1996 by Andries Brouwer +.\" Modified Sun Jul 21 20:55:44 1996 by Andries Brouwer +.\" Modified Mon Oct 15 21:16:25 2001 by John Levon +.\" Modified Tue Oct 16 00:04:43 2001 by Andries Brouwer +.\" Modified Fri Jun 20 03:04:30 2003 by Andries Brouwer +.\" +.TH STRERROR 3 2001-10-16 "" "Linux Programmer's Manual" +.SH NAME +strerror, strerror_r \- return string describing error code +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *strerror(int " errnum ); +.br +.BI "int strerror_r(int " errnum ", char *" buf ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBstrerror()\fP function returns a string describing the error +code passed in the argument \fIerrnum\fP, possibly using the LC_MESSAGES +part of the current locale to select the appropriate language. +This string must not be modified by the application, but may be +modified by a subsequent call to \fBperror()\fP or \fBstrerror()\fP. +No library function will modify this string. + +The \fBstrerror_r()\fP function is similar to \fBstrerror()\fP, but is +thread safe. It returns the string in the user-supplied buffer +.I buf +of length +.IR n . + +.SH "RETURN VALUE" +The \fBstrerror()\fP function returns the appropriate error description +string, or an unknown error message if the error code is unknown. +The value of \fIerrno\fP is not changed for a successful call, and is +set to a nonzero value upon error. +The \fBstrerror_r()\fP function returns 0 on success and \-1 on failure, +setting \fIerrno\fP. + +.SH ERRORS +.TP +.B EINVAL +The value of +.I errnum +is not a valid error number. +.TP +.B ERANGE +Insufficient storage was supplied to contain the error description string. + +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO/IEC 9899:1990 (C89). +.br +.BR strerror_r() +with prototype as given above is specified by SUSv3, and was in use +under Digital Unix and HP Unix. An incompatible function, with prototype +.sp +.BI "char *strerror_r(int " errnum ", char *" buf ", size_t " n ); +.sp +is a GNU extension used by glibc (since 2.0), +and must be regarded as obsolete in view of SUSv3. +The GNU version may, but need not, use the user-supplied buffer. +If it does, the result may be truncated in case the supplied buffer +is too small. The result is always NUL-terminated. +.SH "SEE ALSO" +.BR errno (3), +.BR perror (3), +.BR strsignal (3) diff --git a/man3/strerror_r.3 b/man3/strerror_r.3 new file mode 100644 index 000000000..649dd6d91 --- /dev/null +++ b/man3/strerror_r.3 @@ -0,0 +1 @@ +.so man3/strerror.3 diff --git a/man3/strfmon.3 b/man3/strfmon.3 new file mode 100644 index 000000000..9a87a08f3 --- /dev/null +++ b/man3/strfmon.3 @@ -0,0 +1,142 @@ +.\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH STRFMON 3 2000-12-05 "Linux" "Linux Programmer's Manual" +.SH NAME +strfmon \- convert monetary value to a string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "ssize_t strfmon(char *" s ", size_t " max ", const char *" format , +.B "...);" +.fi +.SH DESCRIPTION +The \fBstrfmon()\fP function formats the specified amounts +according to the format specification \fIformat\fP and places the +result in the character array \fIs\fP of size \fImax\fP. +.PP +Ordinary characters in \fIformat\fP are copied to \fIs\fP +without conversion. Conversion specifiers are introduced by a `%' +character. Immediately following it there can be zero or more +of the following flags: +.TP +.BI = f +The single-byte character +.I f +is used as the numeric fill character (to be used with +a left precision, see below). +When not specified, the space character is used. +.TP +.B ^ +Do not use any grouping characters that might be defined +for the current locale. By default, grouping is enabled. +.TP +.BR ( " or " + +The ( flag indicates that negative amounts should be enclosed between +parentheses. The + flag indicates that signs should be handled +in the default way, that is, amounts are preceded by the locale's +sign indication, e.g., nothing for positive, "-" for negative. +.TP +.BR ! +Omit the currency symbol. +.TP +.BR \- +Left justify all fields. The default is right justification. +.LP +Next, there may be a field width: a decimal digit string specifying +a minimum field width in bytes. The default is 0. +A result smaller than this width is padded with spaces +(on the left, unless the left-justify flag was given). +.LP +Next, there may be a left precision of the form "#" followed by +a decimal digit string. If the number of digits left of the +radix character is smaller than this, the representation is +padded on the left with the numeric fill character. +Grouping characters are not counted in this field width. +.LP +Next, there may be a right precision of the form "." followed by +a decimal digit string. The amount being formatted is rounded to +the specified number of digits prior to formatting. +The default is specified in the +.I frac_digits +and +.I int_frac_digits +items of the current locale. +If the right precision is 0, no radix character is printed. +(The radix character here is determined by LC_MONETARY, and may +differ from that specified by LC_NUMERIC.) +.LP +Finally, the conversion specification must be ended with a +conversion character. The three conversion characters are +.TP +.B % +(In this case the entire specification must be exactly "%%".) +Put a `%' character in the result string. +.TP +.B i +One argument of type double is converted using the locale's +international currency format. +.TP +.B n +One argument of type double is converted using the locale's +national currency format. +.SH "RETURN VALUE" +The \fBstrfmon()\fP function returns the number of characters placed +in the array \fIs\fP, not including the terminating NUL character, +provided the string, including the terminating NUL, fits. +Otherwise, it sets +.I errno +to E2BIG, returns \-1, and the contents of the array is undefined. +.SH EXAMPLE +The call +.RS +.nf +strfmon(buf, sizeof(buf), "[%^=*#6n] [%=*#6i]", + 1234.567, 1234.567); +.fi +.RE +outputs +.RS +[ fl **1234,57] [ NLG **1 234,57] +.RE +in the Dutch locale (with fl for "florijnen" and NLG for Netherlands Guilders). +The grouping character is very ugly because it takes as much space +as a digit, while it should not take more than half that, +and will no doubt cause confusion. +Surprisingly, the "fl" is preceded and followed by a space, +and "NLG" is preceded by one and followed by two spaces. +This may be a bug in the locale files. The Italian, Australian, Swiss +and Portuguese locales yield +.RS +[ L. **1235] [ ITL **1.235] +.br +[ $**1234.57] [ AUD **1,234.57] +.br +[Fr. **1234,57] [CHF **1.234,57] +.br +[ **1234$57Esc] [ **1.234$57PTE ] +.RE +.SH "SEE ALSO" +.BR setlocale (3), +.BR sprintf (3), +.BR locale (7) diff --git a/man3/strfry.3 b/man3/strfry.3 new file mode 100644 index 000000000..c4e84e99b --- /dev/null +++ b/man3/strfry.3 @@ -0,0 +1,48 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:39:43 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRFRY 3 1993-04-12 "GNU" "Linux Programmer's Manual" +.SH NAME +strfry \- randomize a string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *strfry(char *" string ); +.fi +.SH DESCRIPTION +The \fBstrfry()\fP function randomizes the contents of \fIstring\fP by +using \fBrand\fP(3) to randomly swap characters in the string. The +result is an anagram of \fIstring\fP. +.SH "RETURN VALUE" +The \fBstrfry()\fP functions returns a pointer to the randomized +string. +.SH "CONFORMING TO" +The \fBstrfry()\fP function is unique to the Linux C Library and +GNU C Library. +.SH "SEE ALSO" +.BR memfrob (3) diff --git a/man3/strftime.3 b/man3/strftime.3 new file mode 100644 index 000000000..45029e2f7 --- /dev/null +++ b/man3/strftime.3 @@ -0,0 +1,272 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" GNU texinfo documentation on glibc date/time functions. +.\" Modified Sat Jul 24 18:03:44 1993 by Rik Faith (faith@cs.unc.edu) +.\" Applied fix by Wolfgang Franke, aeb, 961011 +.\" Corrected return value, aeb, 970307 +.\" Added Single Unix Spec conversions and %z, aeb/esr, 990329. +.\" +.TH STRFTIME 3 1999-03-29 "GNU" "Linux Programmer's Manual" +.SH NAME +strftime \- format date and time +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t strftime(char *" s ", size_t " max ", const char *" format , +.BI " const struct tm *" tm ); +.fi +.SH DESCRIPTION +The \fBstrftime()\fP function formats the broken-down time \fItm\fP +according to the format specification \fIformat\fP and places the +result in the character array \fIs\fP of size \fImax\fP. +.PP +Ordinary characters placed in the format string are copied to \fIs\fP +without conversion. Conversion specifiers are introduced by a `%' +character, and are replaced in \fIs\fP as follows: +.TP +.B %a +The abbreviated weekday name according to the current locale. +.TP +.B %A +The full weekday name according to the current locale. +.TP +.B %b +The abbreviated month name according to the current locale. +.TP +.B %B +The full month name according to the current locale. +.TP +.B %c +The preferred date and time representation for the current locale. +.TP +.B %C +The century number (year/100) as a 2-digit integer. (SU) +.TP +.B %d +The day of the month as a decimal number (range 01 to 31). +.TP +.B %D +Equivalent to %m/%d/%y. (Yecch - for Americans only. +Americans should note that in other countries %d/%m/%y is rather +common. This means that in international context this format is +ambiguous and should not be used.) (SU) +.TP +.B %e +Like %d, the day of the month as a decimal number, but a leading +zero is replaced by a space. (SU) +.TP +.B %E +Modifier: use alternative format, see below. (SU) +.TP +.B %F +Equivalent to %Y-%m-%d (the ISO 8601 date format). (C99) +.TP +.B %G +The ISO 8601 year with century as a decimal number. +The 4-digit year corresponding to the ISO week number (see %V). +This has the same format and value as %y, except that if the +ISO week number belongs to the previous or next year, +that year is used instead. (TZ) +.TP +.B %g +Like %G, but without century, i.e., with a 2-digit year (00-99). (TZ) +.TP +.B %h +Equivalent to %b. (SU) +.TP +.B %H +The hour as a decimal number using a 24-hour clock (range 00 to 23). +.TP +.B %I +The hour as a decimal number using a 12-hour clock (range 01 to 12). +.TP +.B %j +The day of the year as a decimal number (range 001 to 366). +.TP +.B %k +The hour (24-hour clock) as a decimal number (range 0 to 23); +single digits are preceded by a blank. (See also %H.) (TZ) +.TP +.B %l +The hour (12-hour clock) as a decimal number (range 1 to 12); +single digits are preceded by a blank. (See also %I.) (TZ) +.TP +.B %m +The month as a decimal number (range 01 to 12). +.TP +.B %M +The minute as a decimal number (range 00 to 59). +.TP +.B %n +A newline character. (SU) +.TP +.B %O +Modifier: use alternative format, see below. (SU) +.TP +.B %p +Either `AM' or `PM' according to the given time value, or the +corresponding strings for the current locale. +Noon is treated as `pm' and midnight as `am'. +.TP +.B %P +Like %p but in lowercase: `am' or `pm' or a corresponding +string for the current locale. (GNU) +.TP +.B %r +The time in a.m. or p.m. notation. +In the POSIX locale this is equivalent to `%I:%M:%S %p'. (SU) +.TP +.B %R +The time in 24-hour notation (%H:%M). (SU) +For a version including the seconds, see %T below. +.TP +.B %s +The number of seconds since the Epoch, i.e., since 1970-01-01 +00:00:00 UTC. (TZ) +.TP +.B %S +The second as a decimal number (range 00 to 61). +.TP +.B %t +A tab character. (SU) +.TP +.B %T +The time in 24-hour notation (%H:%M:%S). (SU) +.TP +.B %u +The day of the week as a decimal, range 1 to 7, Monday being 1. +See also %w. (SU) +.TP +.B %U +The week number of the current year as a decimal number, +range 00 to 53, starting with the first Sunday as the first day +of week 01. See also %V and %W. +.TP +.B %V +The ISO 8601:1988 week number of the current year as a decimal number, +range 01 to 53, where week 1 is the first week that has at least +4 days in the current year, and with Monday as the first day of +the week. See also %U and %W. (SU) +.TP +.B %w +The day of the week as a decimal, range 0 to 6, Sunday being 0. +See also %u. +.TP +.B %W +The week number of the current year as a decimal number, +range 00 to 53, starting with the first Monday as the first day of week 01. +.TP +.B %x +The preferred date representation for the current locale without the time. +.TP +.B %X +The preferred time representation for the current locale without the date. +.TP +.B %y +The year as a decimal number without a century (range 00 to 99). +.TP +.B %Y +The year as a decimal number including the century. +.TP +.B %z +The time-zone as hour offset from GMT. +Required to emit RFC822-conformant dates +(using "%a, %d %b %Y %H:%M:%S %z"). (GNU) +.TP +.B %Z +The time zone or name or abbreviation. +.TP +.B %+ +The date and time in date(1) format. (TZ) +.TP +.B %% +A literal `%' character. +.PP +Some conversion specifiers can be modified by preceding them +by the E or O modifier to indicate that an alternative format +should be used. +If the alternative format or specification does not exist for +the current locale, the behaviour will be as if the unmodified +conversion specification were used. (SU) +The Single Unix Specification mentions %Ec, %EC, %Ex, %EX, +%Ry, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, +%Ow, %OW, %Oy, where the effect of the O modifier is to use +alternative numeric symbols (say, roman numerals), and that of the +E modifier is to use a locale-dependent alternative representation. +.PP +The broken-down time structure \fItm\fP is defined in \fI\fP. +See also +.BR ctime (3). + +.SH "RETURN VALUE" +The \fBstrftime()\fP function returns the number of characters placed +in the array \fIs\fP, not including the terminating NUL character, +provided the string, including the terminating NUL, fits. +Otherwise, it returns 0, and the contents of the array is undefined. +(Thus at least since libc 4.4.4; very old versions of libc, +such as libc 4.4.1, would return \fImax\fP if the array was too small.) +.LP +Note that the return value 0 does not necessarily indicate an error; +for example, in many locales %p yields an empty string. +.SH ENVIRONMENT +The environment variables TZ and LC_TIME are used. +.SH "CONFORMING TO" +ANSI C, SVID 3, ISO 9899. +There are strict inclusions between the set of conversions +given in ANSI C (unmarked), those given in the Single Unix Specification +(marked SU), those given in Olson's timezone package (marked TZ), +and those given in glibc (marked GNU), except that %+ is not supported +in glibc2. On the other hand glibc2 has several more extensions. +POSIX.1 only refers to ANSI C; POSIX.2 describes under +.BR date (1) +several extensions that could apply to +.B strftime +as well. +The %F conversion is in C99 and POSIX 1003.1-2001. +.SH BUGS +Some buggy versions of gcc complain about the use of %c: +.IR "warning: `%c' yields only last 2 digits of year in some locales" . +Of course programmers are encouraged to use %c, it gives the preferred +date and time representation. One meets all kinds of strange obfuscations +to circumvent this gcc problem. A relatively clean one is to add an +intermediate function +.RS +size_t my_strftime(char *s, size_t max, const char *fmt, +const struct tm *tm) { +.br + return strftime(s, max, fmt, tm); +.br +} +.RE +.SH "SEE ALSO" +.BR date (1), +.BR time (2), +.BR ctime (3), +.BR setlocale (3), +.BR sprintf (3), +.BR strptime (3) diff --git a/man3/string.3 b/man3/string.3 new file mode 100644 index 000000000..ac5cf8504 --- /dev/null +++ b/man3/string.3 @@ -0,0 +1,113 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:54:31 1993, Rik Faith (faith@cs.unc.edu) +.TH STRING 3 1993-04-09 "" "Linux Programmer's Manual" +.SH NAME +strcasecmp, strcat, strchr, strcmp, strcoll, strcpy, strcspn, +strdup, strfry, strlen, strncat, strncmp, strncpy, strncasecmp, strpbrk, +strrchr, strsep, strspn, strstr, strtok, strxfrm, index, rindex +\- string operations +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int strcasecmp(const char *" s1 ", const char *" s2 ); +.sp +.BI "int strncasecmp(const char *" s1 ", const char *" s2 ", size_t " n ); +.sp +.BI "char *index(const char *" s ", int " c ); +.sp +.BI "char *rindex(const char *" s ", int " c ); +.sp +.B #include +.sp +.BI "char *strcat(char *" dest ", const char *" src ); +.sp +.BI "char *strchr(const char *" s ", int " c ); +.sp +.BI "int strcmp(const char *" s1 ", const char *" s2 ); +.sp +.BI "int strcoll(const char *" s1 ", const char *" s2 ); +.sp +.BI "char *strcpy(char *" dest ", const char *" src ); +.sp +.BI "size_t strcspn(const char *" s ", const char *" reject ); +.sp +.BI "char *strdup(const char *" s ); +.sp +.BI "char *strfry(char *" string ); +.sp +.BI "size_t strlen(const char *" s ); +.sp +.BI "char *strncat(char *" dest ", const char *" src ", size_t " n ); +.sp +.BI "int strncmp(const char *" s1 ", const char *" s2 ", size_t " n ); +.sp +.BI "char *strncpy(char *" dest ", const char *" src ", size_t " n ); +.sp +.BI "char *strpbrk(const char *" s ", const char *" accept ); +.sp +.BI "char *strrchr(const char *" s ", int " c ); +.sp +.BI "char *strsep(char **" stringp ", const char *" delim ); +.sp +.BI "size_t strspn(const char *" s ", const char *" accept ); +.sp +.BI "char *strstr(const char *" haystack ", const char *" needle ); +.sp +.BI "char *strtok(char *" s ", const char *" delim ); +.sp +.BI "size_t strxfrm(char *" dest ", const char *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The string functions perform string operations on NUL-terminated +strings. See the individual man pages for descriptions of each +function. +.SH "SEE ALSO" +.BR index (3), +.BR rindex (3), +.BR strcasecmp (3), +.BR strcat (3), +.BR strchr (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strcpy (3), +.BR strcspn (3), +.BR strdup (3), +.BR strfry (3), +.BR strlen (3), +.BR strncasecmp (3), +.BR strncat (3), +.BR strncmp (3), +.BR strncpy (3), +.BR strpbrk (3), +.BR strrchr (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3), +.BR strxfrm (3) diff --git a/man3/strlen.3 b/man3/strlen.3 new file mode 100644 index 000000000..38582131f --- /dev/null +++ b/man3/strlen.3 @@ -0,0 +1,45 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:02:26 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRLEN 3 1993-04-12 "" "Linux Programmer's Manual" +.SH NAME +strlen \- calculate the length of a string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t strlen(const char *" s ); +.fi +.SH DESCRIPTION +The \fBstrlen()\fP function calculates the length of the string +\fIs\fP, not including the terminating `\\0' character. +.SH "RETURN VALUE" +The \fBstrlen()\fP function returns the number of characters in \fIs\fP. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899 +.SH "SEE ALSO" +.BR string (3) diff --git a/man3/strncasecmp.3 b/man3/strncasecmp.3 new file mode 100644 index 000000000..fd3b6715e --- /dev/null +++ b/man3/strncasecmp.3 @@ -0,0 +1 @@ +.so man3/strcasecmp.3 diff --git a/man3/strncat.3 b/man3/strncat.3 new file mode 100644 index 000000000..dc3a1ca1c --- /dev/null +++ b/man3/strncat.3 @@ -0,0 +1 @@ +.so man3/strcat.3 diff --git a/man3/strncmp.3 b/man3/strncmp.3 new file mode 100644 index 000000000..1007f4346 --- /dev/null +++ b/man3/strncmp.3 @@ -0,0 +1 @@ +.so man3/strcmp.3 diff --git a/man3/strncpy.3 b/man3/strncpy.3 new file mode 100644 index 000000000..ff7476a84 --- /dev/null +++ b/man3/strncpy.3 @@ -0,0 +1 @@ +.so man3/strcpy.3 diff --git a/man3/strndup.3 b/man3/strndup.3 new file mode 100644 index 000000000..2dd8f88c3 --- /dev/null +++ b/man3/strndup.3 @@ -0,0 +1 @@ +.so man3/strdup.3 diff --git a/man3/strndupa.3 b/man3/strndupa.3 new file mode 100644 index 000000000..2dd8f88c3 --- /dev/null +++ b/man3/strndupa.3 @@ -0,0 +1 @@ +.so man3/strdup.3 diff --git a/man3/strnlen.3 b/man3/strnlen.3 new file mode 100644 index 000000000..c14de55ba --- /dev/null +++ b/man3/strnlen.3 @@ -0,0 +1,32 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" +.TH STRNLEN 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +strnlen \- determine the length of a fixed-size string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t strnlen(const char *" s ", size_t " maxlen ); +.fi +.SH DESCRIPTION +The \fBstrnlen\fP function returns the number of characters in the string +pointed to by \fIs\fP, not including the terminating '\\0' character, but +at most \fImaxlen\fP. In doing this, \fBstrnlen\fP looks only at the first +\fImaxlen\fP characters at \fIs\fP and never beyond \fIs+maxlen\fP. +.SH "RETURN VALUE" +The \fBstrnlen\fP function returns \fIstrlen(s)\fP, if that is less than +\fImaxlen\fP, or \fImaxlen\fP if there is no '\\0' character among the first +\fImaxlen\fP characters pointed to by \fIs\fP. +.SH "CONFORMING TO" +This function is a GNU extension. +.SH "SEE ALSO" +.BR strlen (3) diff --git a/man3/strpbrk.3 b/man3/strpbrk.3 new file mode 100644 index 000000000..480d7ff8c --- /dev/null +++ b/man3/strpbrk.3 @@ -0,0 +1,54 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:01:24 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRPBRK 3 1993-04-12 "" "Linux Programmer's Manual" +.SH NAME +strpbrk \- search a string for any of a set of characters +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *strpbrk(const char *" s ", const char *" accept ); +.fi +.SH DESCRIPTION +The \fBstrpbrk()\fP function locates the first occurrence in the +string \fIs\fP of any of the characters in the string \fIaccept\fP. +.SH "RETURN VALUE" +The \fBstrpbrk()\fP function returns a pointer to the character in +\fIs\fP that matches one of the characters in \fIaccept\fP, or NULL +if no such character is found. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899 +.SH "SEE ALSO" +.BR index (3), +.BR memchr (3), +.BR rindex (3), +.BR strchr (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3) diff --git a/man3/strptime.3 b/man3/strptime.3 new file mode 100644 index 000000000..1c3baf869 --- /dev/null +++ b/man3/strptime.3 @@ -0,0 +1,367 @@ +.\" Copyright 1993 Mitchum DSouza +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified, jmv@lucifer.dorms.spbu.ru, 1999-11-08 +.\" Modified, aeb, 2000-04-07 +.\" Updated from glibc docs, C. Scott Ananian, 2001-08-25 +.\" Modified, aeb, 2001-08-31 +.\" Modified, wharms 2001-11-12, remark on white space and example +.\" +.TH STRPTIME 3 2001-11-12 "GNU" "Linux Programmer's Manual" +.SH NAME +strptime \- convert a string representation of time to a time tm structure +.SH SYNOPSIS +.BR "#define _XOPEN_SOURCE" " /* glibc2 needs this */" +.br +.B #include +.sp +.BI "char *strptime(const char *" s ", const char *" format , +.BI "struct tm *" tm ); +.SH DESCRIPTION +The +.B strptime() +function is the converse function to +.B strftime() +and converts the character string pointed to by +.I s +to values which are stored in the +.B tm +structure pointed to by +.IR tm , +using the format specified by +.IR format . +Here +.I format +is a character string that consists of field descriptors and text characters, +reminiscent of +.BR scanf (3). +Each field descriptor consists of a +.B % +character followed by another character that specifies the replacement +for the field descriptor. +All other characters in the +.I format +string must have a matching character in the input string, +except for whitespace, which matches zero or more +whitespace characters in the input string. +There should be white\%space or other alphanumeric characters +between any two field descriptors. +.PP +The \fBstrptime()\fP function processes the input string from left +to right. Each of the three possible input elements (whitespace, +literal, or format) are handled one after the other. If the input +cannot be matched to the format string the function stops. The +remainder of the format and input strings are not processed. +.PP +The supported input field descriptors are listed below. +In case a text string (such as a weekday or month name) +is to be matched, the comparison is case insensitive. +In case a number is to be matched, leading zeros are +permitted but not required. +.TP +.B %% +The +.B % +character. +.TP +.BR %a " or " %A +The weekday name according to the current locale, +in abbreviated form or the full name. +.TP +.BR %b " or " %B " or " %h +The month name according to the current locale, +in abbreviated form or the full name. +.TP +.B %c +The date and time representation for the current locale. +.TP +.B %C +The century number (0-99). +.TP +.BR %d " or " %e +The day of month (1-31). +.TP +.B %D +Equivalent to %m/%d/%y. (This is the American style date, very confusing +to non-Americans, especially since %d/%m/%y is widely used in Europe. +The ISO 8601 standard format is %Y-%m-%d.) +.TP +.BR %H +The hour (0-23). +.TP +.BR %I +The hour on a 12-hour clock (1-12). +.TP +.B %j +The day number in the year (1-366). +.TP +.B %m +The month number (1-12). +.TP +.B %M +The minute (0-59). +.TP +.B %n +Arbitrary whitespace. +.TP +.B %p +The locale's equivalent of AM or PM. (Note: there may be none.) +.TP +.B %r +The 12-hour clock time (using the locale's AM or PM). +In the POSIX locale equivalent to %I:%M:%S %p. +If \fIt_fmt_ampm\fP is empty in the LC_TIME part of the current locale +then the behaviour is undefined. +.TP +.B %R +Equivalent to %H:%M. +.TP +.B %S +The second (0-60; 60 may occur for leap seconds; earlier also 61 was allowed). +.TP +.B %t +Arbitrary whitespace. +.TP +.B %T +Equivalent to %H:%M:%S. +.TP +.B %U +The week number with Sunday the first day of the week (0-53). +The first Sunday of January is the first day of week 1. +.TP +.B %w +The weekday number (0-6) with Sunday = 0. +.TP +.B %W +The week number with Monday the first day of the week (0-53). +The first Monday of January is the first day of week 1. +.TP +.B %x +The date, using the locale's date format. +.TP +.B %X +The time, using the locale's time format. +.TP +.B %y +The year within century (0-99). +When a century is not otherwise specified, values in the range 69-99 refer +to years in the twentieth century (1969-1999); values in the +range 00-68 refer to years in the twenty-first century (2000-2068). +.TP +.B %Y +The year, including century (for example, 1991). +.LP +Some field descriptors can be modified by the E or O modifier characters +to indicate that an alternative format or specification should be used. If the +alternative format or specification does not exist in the current locale, the +unmodified field descriptor is used. +.LP +The E modifier specifies that the input string may contain +alternative locale-dependent versions of the date and time representation: +.TP +.B %Ec +The locale's alternative date and time representation. +.TP +.B %EC +The name of the base year (period) in the locale's alternative representation. +.TP +.B %Ex +The locale's alternative date representation. +.TP +.B %EX +The locale's alternative time representation. +.TP +.B %Ey +The offset from %EC (year only) in the locale's alternative representation. +.TP +.B %EY +The full alternative year representation. +.LP +The O modifier specifies that the numerical input may be in an +alternative locale-dependent format: +.TP +.BR %Od " or " %Oe +The day of the month using the locale's alternative numeric symbols; +leading zeros are permitted but not required. +.TP +.B %OH +The hour (24-hour clock) using the locale's alternative numeric symbols. +.TP +.B %OI +The hour (12-hour clock) using the locale's alternative numeric symbols. +.TP +.B %Om +The month using the locale's alternative numeric symbols. +.TP +.B %OM +The minutes using the locale's alternative numeric symbols. +.TP +.B %OS +The seconds using the locale's alternative numeric symbols. +.TP +.B %OU +The week number of the year (Sunday as the first day of the week) +using the locale's alternative numeric symbols. +.TP +.B %Ow +The number of the weekday (Sunday=0) using the locale's alternative +numeric symbols. +.TP +.B %OW +The week number of the year (Monday as the first day of the week) +using the locale's alternative numeric symbols. +.TP +.B %Oy +The year (offset from %C) using the locale's alternative numeric symbols. +.LP +The broken-down time structure \fItm\fP is defined in \fI\fP +as follows: +.sp +.RS +.nf +.ne 12 +.ta 8n 16n 32n +struct tm { + int tm_sec; /* seconds */ + int tm_min; /* minutes */ + int tm_hour; /* hours */ + int tm_mday; /* day of the month */ + int tm_mon; /* month */ + int tm_year; /* year */ + int tm_wday; /* day of the week */ + int tm_yday; /* day in the year */ + int tm_isdst; /* daylight saving time */ +}; +.ta +.fi +.RE +.SH "RETURN VALUE" +The return value of the function is a pointer to the first character +not processed in this function call. In case the input string +contains more characters than required by the format string the return +value points right after the last consumed input character. In case +the whole input string is consumed the return value points to the NUL +byte at the end of the string. If \fBstrptime()\fP fails to match all +of the format string and therefore an error occurred the function +returns \fBNULL\fP. +.SH "CONFORMING TO" +XPG4, SUSv2, POSIX 1003.1-2001. +.SH EXAMPLE +The following example demonstrates the use of \fBstrptime()\fP +and \fBstrftime()\fP. +.sp +.nf +.ne 12 +.ta 8n 16n +#include +#include + +int main() { + struct tm tm; + char buf[255]; + + strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm); + strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm); + puts(buf); + return 0; +} +.ta +.fi +.SH "GNU EXTENSIONS" +For reasons of symmetry, glibc tries to support for +.B strptime +the same format characters as for +.BR strftime. +(In most cases the corresponding fields are parsed, but no field in \fItm\fP +is changed.) +This leads to +.TP +.B %F +Equivalent to \fB%Y-%m-%d\fP, the ISO 8601 date format. +.TP +.B %g +The year corresponding to the ISO week number, but without the century +(0-99). +.TP +.B %G +The year corresponding to the ISO week number. (For example, 1991.) +.TP +.B %u +The day of the week as a decimal number (1-7, where Monday = 1). +.TP +.B %V +The ISO 8601:1988 week number as a decimal number (1-53). +If the week (starting on Monday) containing 1 January has four or more days +in the new year, then it is considered week 1. Otherwise, it is the last week +of the previous year, and the next week is week 1. +.TP +.B %z +An RFC-822/ISO 8601 standard time zone specification. +.TP +.B %Z +The timezone name. +.LP +Similarly, because of GNU extensions to \fIstrftime\fP, +%k is accepted as a synonym for %H, and %l should be accepted +as a synonym for %I, and %P is accepted as a synonym for %p. +Finally +.TP +.B %s +The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. +Leap seconds are not counted unless leap second support is available. +.LP +The GNU libc implementation does not require whitespace between +two field descriptors. +.SH NOTES +.LP +In principle, this function does not initialize \fBtm\fP but +only stores the values specified. +This means that \fBtm\fP should be initialized before the call. +Details differ a bit between different Unix systems. +The GNU libc implementation does not touch those fields which are not +explicitly specified, except that it recomputes the +.IR tm_wday +and +.IR tm_yday +field if any of the year, month, or day elements changed. +.PP +This function is available since libc 4.6.8. +Linux libc4 and libc5 includes define the prototype unconditionally; +glibc2 includes provide a prototype only when _XOPEN_SOURCE or _GNU_SOURCE +are defined. +.PP +Before libc 5.4.13 whitespace (and the 'n' and 't' specifications) +was not handled, no 'E' and 'O' locale modifier characters were accepted, +and the 'C' specification was a synonym for the 'c' specification. +.PP +The 'y' (year in century) specification is taken to specify a year +in the 20th century by libc4 and libc5. It is taken to be a year +in the range 1950-2049 by glibc 2.0. It is taken to be a year in +1969-2068 since glibc 2.1. +.\" In libc4 and libc5 the code for %I is broken (fixed in glibc; +.\" %OI was fixed in glibc 2.2.4). +.SH "SEE ALSO" +.BR time (2), +.BR getdate (3), +.BR scanf (3), +.BR setlocale (3), +.BR strftime (3) diff --git a/man3/strrchr.3 b/man3/strrchr.3 new file mode 100644 index 000000000..322b7a896 --- /dev/null +++ b/man3/strrchr.3 @@ -0,0 +1 @@ +.so man3/strchr.3 diff --git a/man3/strsep.3 b/man3/strsep.3 new file mode 100644 index 000000000..0bb001bfb --- /dev/null +++ b/man3/strsep.3 @@ -0,0 +1,70 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:00:10 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Jan 20 12:04:18 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Tue Jan 23 20:23:07 2001 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH STRSEP 3 1993-04-12 "GNU" "Linux Programmer's Manual" +.SH NAME +strsep \- extract token from string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *strsep(char **" stringp ", const char *" delim ); +.fi +.SH DESCRIPTION +If *\fIstringp\fP is NULL, the \fBstrsep()\fP function returns NULL +and does nothing else. Otherwise, this function finds the first token +in the string *\fIstringp\fP, where tokens +are delimited by symbols in the string \fIdelim\fP. +This token is terminated with a `\\0' character +(by overwriting the delimiter) +and *\fIstringp\fP is updated to point past the token. +In case no delimiter was found, the token is taken to be +the entire string *\fIstringp\fP, and *\fIstringp\fP is made NULL. +.SH "RETURN VALUE" +The \fBstrsep()\fP function returns a pointer to the token, +that is, it returns the original value of *\fIstringp\fP. +.SH NOTES +The \fBstrsep()\fP function was introduced as a replacement for +\fBstrtok()\fP, since the latter cannot handle empty fields. +However, \fBstrtok()\fP conforms to ANSI-C and hence is more portable. +.SH BUGS +This function suffers from the same problems as \fBstrtok()\fP. +In particular, it modifies the original string. Avoid it. +.SH "CONFORMING TO" +BSD 4.4 +.SH "SEE ALSO" +.BR index (3), +.BR memchr (3), +.BR rindex (3), +.BR strchr (3), +.BR strpbrk (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3) diff --git a/man3/strsignal.3 b/man3/strsignal.3 new file mode 100644 index 000000000..c68e4e57c --- /dev/null +++ b/man3/strsignal.3 @@ -0,0 +1,59 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:59:03 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRSIGNAL 3 1999-02-08 "GNU" "Linux Programmer's Manual" +.SH NAME +strsignal \- return string describing signal +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "char *strsignal(int " sig ); +.sp +.BI "extern const char * const " sys_siglist []; +.fi +.SH DESCRIPTION +The \fBstrsignal()\fP function returns a string describing the signal +number passed in the argument \fIsig\fP. The string can only be used +until the next call to \fBstrsignal()\fP. +.PP +The array \fIsys_siglist\fP holds the signal description strings +indexed by signal number. The \fBstrsignal()\fP function should be +used if possible instead of this array. +.SH "RETURN VALUE" +The \fBstrsignal()\fP function returns the appropriate description +string, or an unknown signal message if the signal number is invalid. +On some systems (but not on Linux), a \fBNULL\fP pointer may be +returned instead for an invalid signal number. +.SH "CONFORMING TO" +This function is not part of any standard, but may be found on Linux +systems and some UNIX systems (such as Solaris). +.SH "SEE ALSO" +.BR psignal (3), +.BR strerror (3) diff --git a/man3/strspn.3 b/man3/strspn.3 new file mode 100644 index 000000000..ba29cf3e1 --- /dev/null +++ b/man3/strspn.3 @@ -0,0 +1,65 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:57:50 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRSPN 3 1993-04-12 "" "Linux Programmer's Manual" +.SH NAME +strspn, strcspn \- search a string for a set of characters +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t strspn(const char *" s ", const char *" accept ); +.sp +.BI "size_t strcspn(const char *" s ", const char *" reject ); +.fi +.SH DESCRIPTION +The \fBstrspn()\fP function calculates the length of the initial +segment of \fIs\fP which consists entirely of characters in +\fIaccept\fP. +.PP +The \fBstrcspn()\fP function calculates the length of the initial +segment of \fIs\fP which consists entirely of characters not in +\fIreject\fP. +.SH "RETURN VALUE" +The \fBstrspn()\fP function returns the number of characters in +the initial segment of \fIs\fP which consist only of characters +from \fIaccept\fP. +.PP +The \fBstrcspn()\fP function returns the number of characters in +the initial segment of \fIs\fP which are not in the string +\fIreject\fP. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899 +.SH "SEE ALSO" +.BR index (3), +.BR memchr (3), +.BR rindex (3), +.BR strchr (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strstr (3), +.BR strtok (3) diff --git a/man3/strstr.3 b/man3/strstr.3 new file mode 100644 index 000000000..bc9f150a9 --- /dev/null +++ b/man3/strstr.3 @@ -0,0 +1,60 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:56:43 1993 by Rik Faith (faith@cs.unc.edu) +.\" Added history, aeb, 980113. +.\" +.TH STRSTR 3 1993-04-12 "GNU" "Linux Programmer's Manual" +.SH NAME +strstr \- locate a substring +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *strstr(const char *" haystack ", const char *" needle ); +.fi +.SH DESCRIPTION +The \fBstrstr()\fP function finds the first occurrence of the substring +\fIneedle\fP in the string \fIhaystack\fP. The terminating `\\0' +characters are not compared. +.SH "RETURN VALUE" +The \fBstrstr()\fP function returns a pointer to the beginning of the +substring, or NULL if the substring is not found. +.SH BUGS +Early versions of Linux libc (like 4.5.26) would not allow +an empty argument. Later versions (like 4.6.27) work correctly, +and return \fIhaystack\fP when \fIneedle\fP is empty. +.SH "CONFORMING TO" +ISO 9899 +.SH "SEE ALSO" +.BR index (3), +.BR memchr (3), +.BR rindex (3), +.BR strchr (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strspn (3), +.BR strtok (3) diff --git a/man3/strtod.3 b/man3/strtod.3 new file mode 100644 index 000000000..be28a7abb --- /dev/null +++ b/man3/strtod.3 @@ -0,0 +1,148 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)strtod.3 5.3 (Berkeley) 6/29/91 +.\" +.\" Modified Sun Aug 21 17:16:22 1994 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sat May 04 19:34:31 MET DST 1996 by Michael Haardt +.\" (michael@cantor.informatik.rwth-aachen.de) +.\" Added strof, strold, aeb, 2001-06-07 +.\" +.TH STRTOD 3 2001-06-07 "Linux" "Library functions" +.SH NAME +strtod, strtof, strtold \- convert ASCII string to floating point number +.SH SYNOPSIS +.B #include +.sp +.BI "double strtod(const char *" nptr ", char **" endptr ); +.br +.BI "float strtof(const char *" nptr ", char **" endptr ); +.br +.BI "long double strtold(const char *" nptr ", char **" endptr ); +.SH DESCRIPTION +The +.BR strtod , +.BR strtof , +and +.B strtold +functions convert the initial portion of the string pointed to by +.I nptr +to +.BR double , +.BR float , +and +.B long double +representation, respectively. + +The expected form of the (initial portion of the) string is +optional leading white space as recognized by \fIis\%space\fP(3), +an optional plus (``+'') or minus sign (``-'') and then either +(i) a decimal number, or (ii) a hexadecimal number, +or (iii) an infinity, or (iv) a NAN (not-a-number). +.LP +A +.I "decimal number" +consists of a nonempty sequence of decimal digits +possibly containing a radix character (decimal point, locale dependent, +usually ``.''), optionally followed by a decimal exponent. A +decimal exponent consists of an ``E'' or ``e'', followed by an +optional plus or minus sign, followed by a non-empty sequence of +decimal digits, and indicates multiplication by a power of 10. +.LP +A +.I "hexadecimal number" +consists of a ``0x'' or ``0X'' followed by a nonempty sequence of +hexadecimal digits possibly containing a radix character, +optionally followed by a binary exponent. A binary exponent +consists of a ``P'' or ``p'', followed by an optional +plus or minus sign, followed by a non-empty sequence of +decimal digits, and indicates multiplication by a power of 2. +At least one of radix character and binary exponent must be present. +.LP +An +.I infinity +is either ``INF'' or ``INFINITY'', disregarding case. +.LP +A +.I NAN +is ``NAN'' (disregarding case) optionally followed by `(', +a sequence of characters, followed by ')'. +The character string specifies in an implementation-dependent +way the type of NAN. + +.SH "RETURN VALUE" +These functions return the converted value, if any. + +If +.I endptr +is not +.BR NULL , +a pointer to the character after the last character used in the conversion +is stored in the location referenced by +.IR endptr . + +If no conversion is performed, zero is returned and the value of +.I nptr +is stored in the location referenced by +.IR endptr . + +If the correct value would cause overflow, plus or minus +.B HUGE_VAL +.RB ( HUGE_VALF , +.BR HUGE_VALL ) +is returned (according to the sign of the value), and +.B ERANGE +is stored in +.IR errno . +If the correct value would cause underflow, zero is +returned and +.B ERANGE +is stored in +.IR errno . +.SH ERRORS +.TP +.B ERANGE +Overflow or underflow occurred. +.SH "CONFORMING TO" +ANSI C describes +.BR strtod , +C99 +describes the other two functions. +.SH "SEE ALSO" +.BR atof (3), +.BR atoi (3), +.BR atol (3), +.BR strtol (3), +.BR strtoul (3) diff --git a/man3/strtof.3 b/man3/strtof.3 new file mode 100644 index 000000000..ac3e4a55c --- /dev/null +++ b/man3/strtof.3 @@ -0,0 +1 @@ +.so man3/strtod.3 diff --git a/man3/strtoimax.3 b/man3/strtoimax.3 new file mode 100644 index 000000000..0db4360e6 --- /dev/null +++ b/man3/strtoimax.3 @@ -0,0 +1,64 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH STRTOIMAX 3 2003-11-28 "" "Linux Programmer's Manual" +.SH NAME +strtoimax, strtoumax \- convert string to integer +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "intmax_t strtoimax (const char *" nptr ", char **" endptr ", int " base ); +.br +.BI "uintmax_t strtoumax (const char *" nptr ", char **" endptr ", int " base ); +.fi +.SH DESCRIPTION +These functions are just like +.B strtol() +and +.BR strtoul() , +except that they return a value of type +.B intmax_t +and +.BR uintmax_t , +respectively. +.SH "RETURN VALUE" +On success, the converted value is returned. +If nothing was found to convert, zero is returned. +On overflow or underflow +.B INTMAX_MAX +or +.B INTMAX_MIN +or +.B UINTMAX_MAX +is returned, and +.I errno +is set to +.BR ERANGE . +.SH "CONFORMING TO" +C99, POSIX 1003.1-2003. +.SH "SEE ALSO" +.BR imaxabs (3), +.BR imaxdiv (3), +.BR strtol (3), +.BR strtoul (3), +.BR wcstoimax (3) diff --git a/man3/strtok.3 b/man3/strtok.3 new file mode 100644 index 000000000..44014e3ff --- /dev/null +++ b/man3/strtok.3 @@ -0,0 +1,110 @@ +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Rewritten old page, 960210, aeb@cwi.nl +.\" Updated, added strtok_r. 2000-02-13 Nicolás Lichtmaier +.TH STRTOK 3 2000-02-13 "GNU" "Linux Programmer's Manual" +.SH NAME +strtok, strtok_r \- extract tokens from strings +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *strtok(char *" s ", const char *" delim ); +.sp +.BI "char *strtok_r(char *" s ", const char *" delim ", char **" ptrptr ); +.fi +.SH DESCRIPTION +A `token' is a nonempty string of characters not occurring in +the string \fIdelim\fP, followed by \e0 or by a character occurring +in \fIdelim\fP. +.PP +The \fBstrtok()\fP function can be used to parse the string \fIs\fP +into tokens. The first call to \fBstrtok()\fP should have \fIs\fP +as its first argument. Subsequent calls should have the first argument +set to NULL. Each call returns a pointer to the next token, or NULL +when no more tokens are found. +.PP +If a token ends with a delimiter, this delimiting character is +overwritten with a \e0 and a pointer to the next character is +saved for the next call to \fBstrtok()\fP. +The delimiter string \fIdelim\fP may be different for each call. +.PP +The +.B strtok_r() +function is a reentrant version of the +.B strtok() +function, which instead of using its own static buffer, requires a pointer +to a user allocated char*. This pointer, the +.I ptrptr +parameter, must be the same while parsing the same string. +.\" .SH EXAMPLE +.\" The following parses words out of a string, using 'white space' +.\" separators, with +.\" .BR strtok_r() : +.\" .PP +.\" .nf +.\" char buf[128]; +.\" char *sep = " \\t\\n"; +.\" char *tok, *cb; +.\" +.\" snprintf(buf, sizeof(buf), "%s", " One Two\\tThree\\nFour\\n\\n"); +.\" +.\" for ( tok = strtok_r(buf, sep, &cb); tok; +.\" tok = strtok_r(NULL, sep, &cb) ) +.\" printf("%s\\n", tok); +.\" .fi +.SH BUGS +Never use these functions. If you do, note that: +.PP +.RS +These functions modify their first argument. +.PP +These functions cannot be used on constant strings. +.PP +The identity of the delimiting character is lost. +.PP +The +.BR strtok () +function uses a static buffer while parsing, so it's not thread safe. Use +.BR strtok_r () +if this matters to you. +.RE +.SH "RETURN VALUE" +The \fBstrtok()\fP function returns a pointer to the next token, or +NULL if there are no more tokens. +.SH "CONFORMING TO" +.TP +strtok() +SVID 3, POSIX, BSD 4.3, ISO 9899 +.TP +strtok_r() +POSIX.1c +.SH "SEE ALSO" +.BR index (3), +.BR memchr (3), +.BR rindex (3), +.BR strchr (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3) diff --git a/man3/strtok_r.3 b/man3/strtok_r.3 new file mode 100644 index 000000000..19095a017 --- /dev/null +++ b/man3/strtok_r.3 @@ -0,0 +1 @@ +.so man3/strtok.3 diff --git a/man3/strtol.3 b/man3/strtol.3 new file mode 100644 index 000000000..e05cef145 --- /dev/null +++ b/man3/strtol.3 @@ -0,0 +1,125 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:53:39 1993 by Rik Faith (faith@cs.unc.edu) +.\" Added correction due to nsd@bbc.com (Nick Duffek) - aeb, 950610 +.TH STRTOL 3 2002-05-30 "GNU" "Linux Programmer's Manual" +.SH NAME +strtol, strtoll, strtoq \- convert a string to a long integer +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "long int" +.BI "strtol(const char *" nptr ", char **" endptr ", int " base ); +.sp +.BI "long long int" +.BI "strtoll(const char *" nptr ", char **" endptr ", int " base ); +.fi +.SH DESCRIPTION +The \fBstrtol()\fP function converts the initial part of the string +in \fInptr\fP to a long integer value according to the given \fIbase\fP, +which must be between 2 and 36 inclusive, or be the special value 0. +.PP +The string must begin with an arbitrary amount of white space (as +determined by +.BR isspace (3)) +followed by a single optional `+' or `-' +sign. If \fIbase\fP is zero or 16, the string may then include a +`0x' prefix, and the number will be read in base 16; otherwise, a +zero \fIbase\fP is taken as 10 (decimal) unless the next character +is `0', in which case it is taken as 8 (octal). +.PP +The remainder of the string is converted to a long int value +in the obvious manner, stopping at the first character which is not a +valid digit in the given base. (In bases above 10, the letter `A' in +either upper or lower case represents 10, `B' represents 11, and so +forth, with `Z' representing 35.) +.PP +If \fIendptr\fP is not NULL, \fBstrtol()\fP stores the address of the +first invalid character in \fI*endptr\fP. If there were no digits at +all, \fBstrtol()\fP stores the original value of \fInptr\fP in +\fI*endptr\fP (and returns 0). +In particular, if \fI*nptr\fP is not `\\0' but \fI**endptr\fP +is `\\0' on return, the entire string is valid. +.PP +The +.B strtoll() +function works just like the +.B strtol() +function but returns a long long integer value. +.SH "RETURN VALUE" +The \fBstrtol()\fP function returns the result of the conversion, +unless the value would underflow or overflow. If an underflow occurs, +\fBstrtol()\fP returns LONG_MIN. If an overflow occurs, \fBstrtol()\fP +returns LONG_MAX. In both cases, \fIerrno\fP is set to ERANGE. +Precisely the same holds for +.B strtoll() +(with LLONG_MIN and LLONG_MAX instead of LONG_MIN and LONG_MAX). +.SH ERRORS +.TP +.B EINVAL +(not in C99) +The given +.I base +contains an unsupported value. +.TP +.B ERANGE +The resulting value was out of range. +.LP +The implementation may also set \fIerrno\fP to \fBEINVAL\fP in case +no conversion was performed (no digits seen, and 0 returned). +.SH NOTES +In locales other than the "C" locale, also other strings may be accepted. +(For example, the thousands separator of the current locale may be +supported.) +.LP +BSD also has +.sp +.in +4n +.nf +.BI "quad_t" +.BI "strtoq(const char *" nptr ", char **" endptr ", int " base ); +.sp +.in -4n +.fi +with completely analogous definition. +Depending on the wordsize of the current architecture, this +may be equivalent to +.B strtoll() +or to +.BR strtol() . +.SH "CONFORMING TO" +.B strtol() +conforms to SVID 3, BSD 4.3, ISO 9899 (C99) and POSIX, and +.B strtoll() +to ISO 9899 (C99) and POSIX 1003.1-2001. +.SH "SEE ALSO" +.BR atof (3), +.BR atoi (3), +.BR atol (3), +.BR strtod (3), +.BR strtoul (3) diff --git a/man3/strtold.3 b/man3/strtold.3 new file mode 100644 index 000000000..ac3e4a55c --- /dev/null +++ b/man3/strtold.3 @@ -0,0 +1 @@ +.so man3/strtod.3 diff --git a/man3/strtoll.3 b/man3/strtoll.3 new file mode 100644 index 000000000..d09039391 --- /dev/null +++ b/man3/strtoll.3 @@ -0,0 +1 @@ +.so man3/strtol.3 diff --git a/man3/strtoq.3 b/man3/strtoq.3 new file mode 100644 index 000000000..d09039391 --- /dev/null +++ b/man3/strtoq.3 @@ -0,0 +1 @@ +.so man3/strtol.3 diff --git a/man3/strtoul.3 b/man3/strtoul.3 new file mode 100644 index 000000000..a2cd1e33f --- /dev/null +++ b/man3/strtoul.3 @@ -0,0 +1,129 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:54:03 1993 by Rik Faith (faith@cs.unc.edu) +.\" Fixed typo, aeb, 950823 +.\" 2002-02-22, joey, mihtjel: Added strtoull() +.\" +.TH STRTOUL 3 2002-05-30 "GNU" "Linux Programmer's Manual" +.SH NAME +strtoul, strtoull, strtouq \- convert a string to an unsigned long integer +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "unsigned long int" +.BI "strtoul(const char *" nptr ", char **" endptr ", int " base ); +.sp +.BI "unsigned long long int" +.BI "strtoull(const char *" nptr ", char **" endptr ", int " base ); +.fi +.SH DESCRIPTION +The \fBstrtoul()\fP function converts the initial part of the string +in \fInptr\fP to an unsigned long integer value according to the +given \fIbase\fP, which must be between 2 and 36 inclusive, or be +the special value 0. +.PP +The string must begin with an arbitrary amount of white space (as +determined by +.BR isspace (3)) +followed by a single optional `+' or `-' +sign. If \fIbase\fP is zero or 16, the string may then include a +`0x' prefix, and the number will be read in base 16; otherwise, a +zero \fIbase\fP is taken as 10 (decimal) unless the next character +is `0', in which case it is taken as 8 (octal). +.PP +The remainder of the string is converted to an unsigned long int value +in the obvious manner, stopping at the first character which is not a +valid digit in the given base. (In bases above 10, the letter `A' in +either upper or lower case represents 10, `B' represents 11, and so +forth, with `Z' representing 35.) +.PP +If \fIendptr\fP is not NULL, \fBstrtoul()\fP stores the address of the +first invalid character in \fI*endptr\fP. If there were no digits at +all, \fBstrtoul()\fP stores the original value of \fInptr\fP in +\fI*endptr\fP (and returns 0). +In particular, if \fI*nptr\fP is not `\\0' but \fI**endptr\fP +is `\\0' on return, the entire string is valid. +.PP +The +.B strtoull() +function works just like the +.B strtoul() +function but returns an unsigned long long integer value. +.SH "RETURN VALUE" +The \fBstrtoul()\fP function returns either the result of the conversion +or, if there was a leading minus sign, the negation of the result of the +conversion, unless the original (non-negated) value would overflow; in +the latter case, \fBstrtoul()\fP returns ULONG_MAX and sets the global +variable \fIerrno\fP to ERANGE. +Precisely the same holds for +.B strtoull() +(with ULLONG_MAX instead of ULONG_MAX). +.SH ERRORS +.TP +.B EINVAL +(not in C99) +The given +.I base +contains an unsupported value. +.TP +.B ERANGE +The resulting value was out of range. +.LP +The implementation may also set \fIerrno\fP to \fBEINVAL\fP in case +no conversion was performed (no digits seen, and 0 returned). +.SH NOTES +In locales other than the "C" locale, also other strings may be accepted. +(For example, the thousands separator of the current locale may be +supported.) +.LP +BSD also has +.sp +.in +4n +.nf +.BI "u_quad_t" +.BI "strtouq(const char *" nptr ", char **" endptr ", int base" ); +.sp +.in -4n +.fi +with completely analogous definition. +Depending on the wordsize of the current architecture, this +may be equivalent to +.B strtoull() +or to +.BR strtoul() . +.SH "CONFORMING TO" +.B strtoul() +conforms to SVID 3, BSD 4.3, ISO 9899 (C99) and POSIX, and +.BR strtoull() +to ISO 9899 (C99) and POSIX 1003.1-2001. +.SH "SEE ALSO" +.BR atof (3), +.BR atoi (3), +.BR atol (3), +.BR strtod (3), +.BR strtol (3) diff --git a/man3/strtoull.3 b/man3/strtoull.3 new file mode 100644 index 000000000..3340a8373 --- /dev/null +++ b/man3/strtoull.3 @@ -0,0 +1 @@ +.so man3/strtoul.3 diff --git a/man3/strtoumax.3 b/man3/strtoumax.3 new file mode 100644 index 000000000..753be84df --- /dev/null +++ b/man3/strtoumax.3 @@ -0,0 +1 @@ +.so man3/strtoimax.3 diff --git a/man3/strtouq.3 b/man3/strtouq.3 new file mode 100644 index 000000000..3340a8373 --- /dev/null +++ b/man3/strtouq.3 @@ -0,0 +1 @@ +.so man3/strtoul.3 diff --git a/man3/strverscmp.3 b/man3/strverscmp.3 new file mode 100644 index 000000000..47ac44272 --- /dev/null +++ b/man3/strverscmp.3 @@ -0,0 +1,85 @@ +.\" Copyright (C) 2001 Andries Brouwer +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH STRVERSCMP 3 2001-12-19 "GNU" "Linux Programmer's Manual" +.SH NAME +strverscmp \- compare two version strings +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "int strverscmp(const char *" s1 ", const char *" s2 ); +.fi +.SH DESCRIPTION +Often one has files +.IR jan1 ", " jan2 ", ..., " jan9 ", " jan10 ", ..." +and it feels wrong when +.B ls +orders them +.IR jan1 ", " jan10 ", ..., " jan2 ", ..., " jan9 ". +.\" classical solution: "rename jan jan0 jan?" +In order to rectify this, GNU introduced the +.B \-v +option to +.BR ls (1), +which is implemented using +.BR versionsort (3), +which again uses +.BR strverscmp . + +Thus, the task of +.B strverscmp +is to compare two strings and find the "right" order, while +.B strcmp +only finds the lexicographic order. This function does not use +the locale category LC_COLLATE, so is meant mostly for situations +where the strings are expected to be in ASCII. + +What this function does is the following. +If both strings are equal, return 0. Otherwise find the position +between two bytes with the property that before it both strings are equal, +while directly after it there is a difference. +Find the largest consecutive digit strings containing (or starting at, +or ending at) this position. If one or both of these is empty, +then return what +.B strcmp +would have returned (numerical ordering of byte values). +Otherwise, compare both digit strings numerically, where digit strings with +one or more leading zeroes are interpreted as if they have a decimal point +in front (so that in particular digit strings with more leading zeroes +come before digit strings with fewer leading zeroes). +Thus, the ordering is +.IR 000 ", " 00 ", " 01 ", " 010 ", " 09 ", " 0 ", " 1 ", " 9 ", " 10 . +.SH "RETURN VALUE" +The \fBstrverscmp()\fP function returns an integer +less than, equal to, or greater than zero if \fIs1\fP +is found, respectively, to be earlier than, equal to, +or later than \fIs2\fP. +.SH "CONFORMING TO" +This function is a GNU extension. +.SH "SEE ALSO" +.BR rename (1), +.BR strcasecmp (3), +.BR strcmp (3), +.BR strcoll (3) diff --git a/man3/strxfrm.3 b/man3/strxfrm.3 new file mode 100644 index 000000000..242367d1b --- /dev/null +++ b/man3/strxfrm.3 @@ -0,0 +1,61 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:41:28 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRXFRM 3 1993-04-12 "GNU" "Linux Programmer's Manual" +.SH NAME +strxfrm \- string transformation +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t strxfrm(char *" dest ", const char *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBstrxfrm()\fP function transforms the \fIsrc\fP string into a +form such that the result of \fBstrcmp()\fP on two strings that have +been transformed with \fBstrxfrm()\fP is the same as the result of +\fBstrcoll()\fP on the two strings before their transformation. The +first \fIn\fP characters of the transformed string are placed in +\fIdest\fP. The transformation is based on the program's current +locale for category \fILC_COLLATE\fP. (See \fBsetlocale\fP(3)). +.SH "RETURN VALUE" +The \fBstrxfrm()\fP function returns the number of bytes required to +store the transformed string in \fIdest\fP excluding the terminating +`\\0' character. If the value returned is \fIn\fP or more, the +contents of \fIdest\fP are indeterminate. +.SH "CONFORMING TO" +SVID 3, BSD 4.3, ISO 9899 +.SH NOTES +In the \fI"POSIX"\fP or \fI"C"\fP locales \fBstrxfrm()\fP is equivalent to +copying the string with \fBstrncpy()\fP. +.SH "SEE ALSO" +.BR bcmp (3), +.BR memcmp (3), +.BR setlocale (3), +.BR strcasecmp (3), +.BR strcmp (3), +.BR strcoll (3) diff --git a/man3/svc_destroy.3 b/man3/svc_destroy.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svc_destroy.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_freeargs.3 b/man3/svc_freeargs.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svc_freeargs.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_getargs.3 b/man3/svc_getargs.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svc_getargs.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_getcaller.3 b/man3/svc_getcaller.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svc_getcaller.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_getreq.3 b/man3/svc_getreq.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svc_getreq.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_getreqset.3 b/man3/svc_getreqset.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svc_getreqset.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_register.3 b/man3/svc_register.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svc_register.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_run.3 b/man3/svc_run.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svc_run.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_sendreply.3 b/man3/svc_sendreply.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svc_sendreply.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_unregister.3 b/man3/svc_unregister.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svc_unregister.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcerr_auth.3 b/man3/svcerr_auth.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svcerr_auth.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcerr_decode.3 b/man3/svcerr_decode.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svcerr_decode.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcerr_noproc.3 b/man3/svcerr_noproc.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svcerr_noproc.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcerr_noprog.3 b/man3/svcerr_noprog.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svcerr_noprog.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcerr_progvers.3 b/man3/svcerr_progvers.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svcerr_progvers.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcerr_systemerr.3 b/man3/svcerr_systemerr.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svcerr_systemerr.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcerr_weakauth.3 b/man3/svcerr_weakauth.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svcerr_weakauth.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcfd_create.3 b/man3/svcfd_create.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svcfd_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcraw_create.3 b/man3/svcraw_create.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svcraw_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svctcp_create.3 b/man3/svctcp_create.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svctcp_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcudp_bufcreate.3 b/man3/svcudp_bufcreate.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svcudp_bufcreate.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcudp_create.3 b/man3/svcudp_create.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/svcudp_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/swab.3 b/man3/swab.3 new file mode 100644 index 000000000..4b0c0cffd --- /dev/null +++ b/man3/swab.3 @@ -0,0 +1,53 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:52:15 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-12-15, aeb +.TH SWAB 3 2001-12-15 "" "Linux Programmer's Manual" +.SH NAME +swab \- swap adjacent bytes +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void swab(const void *" from ", void *" to ", ssize_t " n ); +.fi +.SH DESCRIPTION +The \fBswab()\fP function copies \fIn\fP bytes from the array pointed +to by \fIfrom\fP to the array pointed to by \fIto\fP, exchanging +adjacent even and odd bytes. This function is used to exchange data +between machines that have different low/high byte ordering. +.LP +This function does nothing when \fIn\fP is negative. +When \fIn\fP is positive and odd, it handles \fIn\fP-1 bytes +as above, and does something unspecified with the last byte. +(In other words, \fIn\fP should be even.) +.SH "RETURN VALUE" +The \fBswab()\fP function returns no value. +.SH "CONFORMING TO" +SVID 3, BSD 4.3, POSIX 1003.1-2001 +.SH "SEE ALSO" +.BR bstring (3) diff --git a/man3/swapcontext.3 b/man3/swapcontext.3 new file mode 100644 index 000000000..cdccd64ec --- /dev/null +++ b/man3/swapcontext.3 @@ -0,0 +1 @@ +.so man3/makecontext.3 diff --git a/man3/swprintf.3 b/man3/swprintf.3 new file mode 100644 index 000000000..56ec9685b --- /dev/null +++ b/man3/swprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man3/sysconf.3 b/man3/sysconf.3 new file mode 100644 index 000000000..aeda39a38 --- /dev/null +++ b/man3/sysconf.3 @@ -0,0 +1,303 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 17:51:42 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Tue Aug 17 11:42:20 1999 by Ariel Scolnicov (ariels@compugen.co.il) +.TH SYSCONF 3 1993-04-18 "GNU" "Linux Programmer's Manual" +.SH NAME +sysconf \- Get configuration information at runtime +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "long sysconf(int " "name" ); +.fi +.SH DESCRIPTION +POSIX allows an application to test at compile- or run-time +whether certain options are supported, or what the value is +of certain configurable constants or limits. +.LP +At compile time this is done by including +.I +and/or +.I +and testing the value of certain macros. +.LP +At run time, one can ask for numerical values using the present function +.BR sysconf (). +On can ask for numerical values that may depend +on the filesystem a file is in using the calls +.BR fpathconf (3) +and +.BR pathconf (3). +One can ask for string values using +.BR confstr (3). +.LP +The values obtained from these functions are system configuration constants. +They do not change during the lifetime of a process. +.\" except that sysconf(_SC_OPEN_MAX) may change answer after a call +.\" to setrlimit( ) which changes the RLIMIT_NOFILE soft limit +.LP +For options, typically, there is a constant +.B _POSIX_FOO +that may be defined in +.IR . +If it is undefined, one should ask at run-time. +If it is defined to \-1, then the option is not supported. +If it is defined to 0, then relevant functions and headers exist, +but one has to ask at runtime what degree of support is available. +If it is defined to a value other than \-1 or 0, then the option is +supported. Usually the value (such as 200112L) indicates the year and month +of the POSIX revision describing the option. Glibc uses the value 1 +to indicate support as long as the POSIX revision has not been published yet. +.\" and 999 to indicate support for options no longer present in the latest +.\" standard. (?) +The +.B sysconf() +argument will be +.BR _SC_FOO . +For a list of options, see +.BR posixoptions (7). +.LP +For variables or limits, typically, there is a constant +.BR _FOO , +maybe defined in +.IR , +or +.BR _POSIX_FOO , +maybe defined in +.IR . +The constant will not be defined if the limit is unspecified. +If the constant is defined, it gives a guaranteed value, and +more might actually be supported. +If an application wants to take advantage of values which may change +between systems, a call to +.B sysconf() +can be made. +The +.B +sysconf() +argument will be +.BR _SC_FOO . +.SH "POSIX.1 VARIABLES" +We give the name of the variable, the name of the +.B sysconf() +parameter used to inquire about its value, +and a short description. +.LP +First, the POSIX.1 compatible values. +.\" [for the moment: only the things that are unconditionally present] +.\" .TP +.\" .BR AIO_LISTIO_MAX " - " _SC_AIO_LISTIO_MAX +.\" (if _POSIX_ASYNCHRONOUS_IO) +.\" Maximum number of I/O operations in a single list I/O call. +.\" Must not be less than _POSIX_AIO_LISTIO_MAX. +.\" .TP +.\" .BR AIO_MAX " - " _SC_AIO_MAX +.\" (if _POSIX_ASYNCHRONOUS_IO) +.\" Maximum number of outstanding asynchronous I/O operations. +.\" Must not be less than _POSIX_AIO_MAX. +.\" .TP +.\" .BR AIO_PRIO_DELTA_MAX " - " _SC_AIO_PRIO_DELTA_MAX +.\" (if _POSIX_ASYNCHRONOUS_IO) +.\" The maximum amount by which a process can decrease its +.\" asynchronous I/O priority level from its own scheduling priority. +.\" Must be nonnegative. +.TP +.BR ARG_MAX " - " _SC_ARG_MAX +The maximum length of the arguments to the +.B exec() +family of functions. +Must not be less than _POSIX_ARG_MAX (4096). +.TP +.BR CHILD_MAX " - " _SC_CHILD_MAX +The max number of simultaneous processes per user id. +Must not be less than _POSIX_CHILD_MAX (25). +.TP +.BR HOST_NAME_MAX " - " _SC_HOST_NAME_MAX +Max length of a hostname, not including the final NUL, as returned by +.BR gethostname (2). +Must not be less than _POSIX_HOST_NAME_MAX (255). +.TP +.BR LOGIN_NAME_MAX " - " _SC_LOGIN_NAME_MAX +Maximum length of a login name, including the final NUL. +Must not be less than _POSIX_LOGIN_NAME_MAX (9). +.TP +.BR "" "clock ticks - " _SC_CLK_TCK +The number of clock ticks per second. +The corresponding variable is obsolete. It was of course called +.BR CLK_TCK . +(Note: the macro +.B CLOCKS_PER_SEC +does not give information: it must equal 1000000.) +.TP +.BR OPEN_MAX " - " _SC_OPEN_MAX +The maximum number of files that a process can have open at any time. +Must not be less than _POSIX_OPEN_MAX (20). +.TP +.BR PAGESIZE " - " _SC_PAGESIZE +Size of a page in bytes. Must not be less than 1. +(Some systems use PAGE_SIZE instead.) +.TP +.BR RE_DUP_MAX " - " _SC_RE_DUP_MAX +The number of repeated occurrences of a BRE permitted by +.BR regexec (3) +and +.BR regcomp (3). +Must not be less than _POSIX2_RE_DUP_MAX (255). +.TP +.BR STREAM_MAX " - " _SC_STREAM_MAX +The maximum number of streams that a process can have open at any +time. If defined, it has the same value as the standard C macro +.BR FOPEN_MAX . +Must not be less than _POSIX_STREAM_MAX (8). +.TP +.BR SYMLOOP_MAX +The maximum number of symbolic links seen in a pathname before resolution +returns ELOOP. Must not be less than _POSIX_SYMLOOP_MAX (8). +.TP +.BR TTY_NAME_MAX " - " _SC_TTY_NAME_MAX +The maximum length of terminal device name, including final NUL. +Must not be less than _POSIX_TTY_NAME_MAX (9). +.TP +.BR TZNAME_MAX " - " _SC_TZNAME_MAX +The maximum number of bytes in a timezone name. +Must not be less than _POSIX_TZNAME_MAX (6). +.TP +.BR _POSIX_VERSION " - " _SC_VERSION +indicates the year and month the POSIX.1 standard was approved in the +format +.BR YYYYMML ; the +value +.B 199009L +indicates the Sept. 1990 revision. +.SH "POSIX.2 VARIABLES" +Next, the POSIX.2 values, giving limits for utilities. +.TP +.BR BC_BASE_MAX " - " _SC_BC_BASE_MAX +indicates the maximum +.I obase +value accepted by the +.BR bc (1) +utility. +.TP +.BR BC_DIM_MAX " - " _SC_BC_DIM_MAX +indicates the maximum value of elements permitted in an array by +.BR bc (1). +.TP +.BR BC_SCALE_MAX " - " _SC_BC_SCALE_MAX +indicates the maximum +.I scale +value allowed by +.BR bc (1). +.TP +.BR BC_STRING_MAX " - " _SC_BC_STRING_MAX +indicates the maximum length of a string accepted by +.BR bc (1). +.TP +.BR COLL_WEIGHTS_MAX " - " _SC_COLL_WEIGHTS_MAX +indicates the maximum numbers of weights that can be assigned to an +entry of the +.B LC_COLLATE order +keyword in the locale definition file, +.TP +.BR EXPR_NEST_MAX " - " _SC_EXPR_NEST_MAX +is the maximum number of expressions which can be nested within +parentheses by +.BR expr (1). +.TP +.BR LINE_MAX " - " _SC_LINE_MAX +The maximum length of a utility's input line length, either from +standard input or from a file. This includes length for a trailing +newline. +.TP +.BR RE_DUP_MAX " - " _SC_RE_DUP_MAX +The maximum number of repeated occurrences of a regular expression when +the interval notation +.B \e{m,n\e} +is used. +.TP +.BR POSIX2_VERSION " - " _SC_2_VERSION +indicates the version of the POSIX.2 standard in the format of +YYYYMML. +.TP +.BR POSIX2_C_DEV " - " _SC_2_DEV +indicates whether the POSIX.2 C language development facilities are +supported. +.TP +.BR POSIX2_FORT_RUN " - " _SC_2_FORT_DEV +indicates whether the POSIX.2 FORTRAN development utilities are +supported. +.TP +.BR POSIX2_FORT_RUN " - " _SC_2_FORT_RUN +indicates whether the POSIX.2 FORTRAN runtime utilities are supported. +.TP +.BR _POSIX2_LOCALEDEF " - " _SC_2_LOCALEDEF +indicates whether the POSIX.2 creation of locates via +.BR localedef (1) +is supported. +.TP +.BR POSIX2_SW_DEV " - " _SC_2_SW_DEV +indicates whether the POSIX.2 software development utilities option is +supported. +.PP +These values also exist, but may not be standard. +.TP +.BR "" " - " _SC_PHYS_PAGES +The number of pages of physical memory. Note that it is possible +for the product of this value and the value of +.B _SC_PAGE_SIZE +to overflow. +.TP +.BR "" " - " _SC_AVPHYS_PAGES +The number of currently available pages of physical memory. +.SH "RETURN VALUE" +If +.I name +is invalid, \-1 is returned, and +.I errno +is set to +.BR EINVAL . +Otherwise, the value returned is the value of the system resource and +.I errno +is not changed. +In the case of options, a positive value is returned if a queried option +is available, and \-1 if it is not. +In the case of limits, \-1 means that there is no definite limit. +.SH "CONFORMING TO" +POSIX.1. +.SH BUGS +It is difficult to use +.B ARG_MAX +because it is not specified how much of the argument space for +.B exec() +is consumed by the user's environment variables. +.PP +Some returned values may be huge; they are not suitable for allocating +memory. +.SH "SEE ALSO" +.BR bc (1), +.BR expr (1), +.BR locale (1), +.BR fpathconf (3), +.BR pathconf (3), +.BR posixoptions (7) diff --git a/man3/syslog.3 b/man3/syslog.3 new file mode 100644 index 000000000..59fe02430 --- /dev/null +++ b/man3/syslog.3 @@ -0,0 +1,294 @@ +.\" Written Feb 1994 by Steve Greenland (stevegr@neosoft.com) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Updated 1999.12.19 by Karl M. Hegbloom +.\" +.\" Updated 13 Oct 2001, Michael Kerrisk +.\" Added description of vsyslog +.\" Added descriptions of (SUSv3-specified) LOG_ODELAY and LOG_NOWAIT +.\" Added brief description of facility and option arguments +.\" Added CONFORMING TO section +.\" 2001-10-13, aeb, minor changes +.\" Modified 13 Dec 2001, Martin Schulze +.\" Modified 3 Jan 2002, Michael Kerrisk +.\" +.TH SYSLOG 3 2002-01-03 "Linux" "Linux Programmer's Manual" +.SH NAME +closelog, openlog, syslog \- send messages to the system logger +.SH SYNOPSIS +.B #include +.sp +.BI "void openlog(const char *" ident ", int " option ", int " facility ); +.br +.BI "void syslog(int " priority ", const char *" format ", ...);" +.br +.BI "void closelog(void);" +.sp +.B #include +.sp +.BI "void vsyslog(int " priority ", const char *" format ", va_list " ap ); +.br +.SH DESCRIPTION +.B closelog() +closes the descriptor being used to write to the system logger. The use of +.B closelog() +is optional. +.sp +.B openlog() +opens a connection to the system logger for a program. The string pointed +to by +.I ident +is prepended to every message, and is typically set to the program name. +The +.I option +argument specifies flags which control the operation of +.B openlog() +and subsequent calls to +.BR syslog() . +The +.I facility +argument establishes a default to be used if +none is specified in subsequent calls to +.BR syslog() . +Values for +.I option +and +.I facility +are given below. The use of +.B openlog() +is optional; it will automatically be called by +.B syslog() +if necessary, in which case +.I ident +will default to NULL. +.sp +.B syslog() +generates a log message, which will be distributed by +.BR syslogd (8). +The +.I priority +argument is formed by ORing the +.I facility +and the +.I level +values (explained below). The remaining arguments +are a +.IR format , +as in +.BR printf (3) +and any arguments required by the +.IR format , +except that the two character sequence %m will be replaced by +the error message string +.IR strerror ( errno ). +A trailing newline is added when needed. + +The function +.B vsyslog() +performs the same task as +.B syslog() +with the difference that it takes a set of arguments which have +been obtained using the +.BR stdarg (3) +variable argument list macros. +.SH PARAMETERS +This section lists the parameters used to set the values of +.IR option , " facility" ", and " priority . +.SS option +The +.I option +argument to +.B openlog() +is an OR of any of these: +.TP +.B LOG_CONS +Write directly to system console if there is an error while sending to +system logger. +.TP +.B LOG_NDELAY +Open the connection immediately (normally, the connection is opened when +the first message is logged). +.TP +.B LOG_NOWAIT +Don't wait for child processes that may have been created while logging +the message. (The GNU C library does not create a child process, so this +option has no effect on Linux.) +.TP +.B LOG_ODELAY +The converse of +.BR LOG_NDELAY ; +opening of the connection is delayed until +.B syslog() +is called. (This is the default, and need not be specified.) +.TP +.B LOG_PERROR +(Not in SUSv3.) Print to stderr as well. +.TP +.B LOG_PID +Include PID with each message. +.SS facility +The +.I facility +argument is used to specify what type of program is logging the message. +This lets the configuration file specify that messages from different +facilities will be handled differently. +.TP +.B LOG_AUTH +security/authorization messages (DEPRECATED Use +.B LOG_AUTHPRIV +instead) +.TP +.B LOG_AUTHPRIV +security/authorization messages (private) +.TP +.B LOG_CRON +clock daemon +.RB ( cron " and " at ) +.TP +.B LOG_DAEMON +system daemons without separate facility value +.TP +.B LOG_FTP +ftp daemon +.TP +.B LOG_KERN +kernel messages +.TP +.BR LOG_LOCAL0 " through " LOG_LOCAL7 +reserved for local use +.TP +.B LOG_LPR +line printer subsystem +.TP +.B LOG_MAIL +mail subsystem +.TP +.B LOG_NEWS +USENET news subsystem +.TP +.B LOG_SYSLOG +messages generated internally by +.B syslogd +.TP +.BR LOG_USER " (default)" +generic user-level messages +.TP +.B LOG_UUCP +UUCP subsystem + +.SS level +This determines the importance of the message. The levels are, in order +of decreasing importance: +.TP +.B LOG_EMERG +system is unusable +.TP +.B LOG_ALERT +action must be taken immediately +.TP +.B LOG_CRIT +critical conditions +.TP +.B LOG_ERR +error conditions +.TP +.B LOG_WARNING +warning conditions +.TP +.B LOG_NOTICE +normal, but significant, condition +.TP +.B LOG_INFO +informational message +.TP +.B LOG_DEBUG +debug-level message +.LP +The function +.BR setlogmask (3) +can be used to restrict logging to specified levels only. +.SH "CONFORMING TO" +The functions +.BR openlog() , +.BR closelog() , +and +.BR syslog() +(but not +.BR vsyslog() ) +are specified in SUSv2 and POSIX 1003.1-2001. +POSIX 1003.1-2001 specifies only the +.B LOG_USER +and +.BR LOG_LOCAL* +values for +.IR facility . +However, with the exception of +.BR LOG_AUTHPRIV +and +.BR LOG_FTP , +the other +.I facility +values appear on most Unix systems. +The +.B LOG_PERROR +value for +.I option +is not specified by POSIX 1003.1-2001, but is available +in most versions of Unix. +.SH HISTORY +A +.B syslog +function call appeared in BSD 4.2. +BSD 4.3 documents +.IR openlog (), +.IR syslog (), +.IR closelog (), +and +.IR setlogmask (). +4.3BSD-Reno also documents +.IR vsyslog (). +Of course early v* functions used the +.I +mechanism, which is not compatible with +.IR . +.SH NOTES +The parameter +.I ident +in the call of +.B openlog() +is probably stored as-is. Thus, if the string it points to +is changed, +.B syslog() +may start prepending the changed string, and if the string +it points to ceases to exist, the results are undefined. +Most portable is to use a string constant. +.LP +Never pass a string with user-supplied data as a format, use +.RS +syslog(priority, "%s", string); +.RE +instead. +.SH "SEE ALSO" +.BR logger (1), +.BR setlogmask (3), +.BR syslog.conf (5), +.BR syslogd (8) diff --git a/man3/system.3 b/man3/system.3 new file mode 100644 index 000000000..add7bc6d6 --- /dev/null +++ b/man3/system.3 @@ -0,0 +1,128 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 17:51:15 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" Modified 14 May 2001, 23 Sep 2001 by aeb +.\" +.TH SYSTEM 3 2001-09-23 "" "Linux Programmer's Manual" +.SH NAME +system \- execute a shell command +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int system(const char *" "string" ); +.fi +.SH DESCRIPTION +.B system() +executes a command specified in +.I string +by calling +.BR "/bin/sh -c" +.IR string , +and returns after the command has been completed. +During execution of the command, +.B SIGCHLD +will be blocked, and +.B SIGINT +and +.B SIGQUIT +will be ignored. +.SH "RETURN VALUE" +The value returned is \-1 on error (e.g. fork failed), +and the return status of the command otherwise. +This latter return status is in the format +specified in +.BR wait (2). +Thus, the exit code of the command will be +.IR WEXITSTATUS(status) . +In case +.B "/bin/sh" +could not be executed, the exit status will be that of +a command that does +.IR exit(127) . +.PP +If the value of +.I string +is +.BR NULL , +.B system() +returns nonzero if the shell is available, and zero if not. +.PP +.B system() +does not affect the wait status of any other children. +.SH "CONFORMING TO" +ANSI C, POSIX.2, BSD 4.3 +.SH NOTES +.PP +As mentioned, +.B system() +ignores SIGINT and SIGQUIT. This may make programs that call it +from a loop uninterruptable, unless they take care themselves +to check the exit status of the child. E.g. +.br +.nf + + while(something) { + int ret = system("foo"); + + if (WIFSIGNALED(ret) && + (WTERMSIG(ret) == SIGINT || WTERMSIG(ret) == SIGQUIT)) + break; + } +.fi +.PP +Do not use +.B system() +from a program with suid or sgid privileges, because strange values for +some environment variables might be used to subvert system integrity. +Use the +.BR exec (3) +family of functions instead, but not +.BR execlp (3) +or +.BR execvp (3). +.B system() +will not, in fact, work properly from programs with suid or sgid +privileges on systems on which +.B /bin/sh +is bash version 2, since bash 2 drops privileges on startup. +(Debian uses a modified bash which does not do this when invoked as +.BR sh .) +.PP +The check for the availability of +.B /bin/sh +is not actually performed; it is always assumed to be available. ISO +C specifies the check, but POSIX.2 specifies that the return shall +always be non-zero, since a system without the shell is not +conforming, and it is this that is implemented. +.PP +It is possible for the shell command to return 127, so that code is not +a sure indication that the +.B execve() +call failed. +.SH "SEE ALSO" +.BR sh (1), +.BR signal (2), +.BR wait (2), +.BR exec (3) diff --git a/man3/tan.3 b/man3/tan.3 new file mode 100644 index 000000000..c42b0a57c --- /dev/null +++ b/man3/tan.3 @@ -0,0 +1,58 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH TAN 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +tan, tanf, tanl \- tangent function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double tan(double " x ); +.sp +.BI "float tanf(float " x ); +.sp +.BI "long double tanl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBtan()\fP function returns the tangent of \fIx\fP, where \fIx\fP is +given in radians. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899. +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR acos (3), +.BR asin (3), +.BR atan (3), +.BR atan2 (3), +.BR cos (3), +.BR sin (3) diff --git a/man3/tanf.3 b/man3/tanf.3 new file mode 100644 index 000000000..58e5a1659 --- /dev/null +++ b/man3/tanf.3 @@ -0,0 +1 @@ +.so man3/tan.3 diff --git a/man3/tanh.3 b/man3/tanh.3 new file mode 100644 index 000000000..45a29757b --- /dev/null +++ b/man3/tanh.3 @@ -0,0 +1,57 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH TANH 3 2002-07-27 "" "Linux Programmer's Manual" +.SH NAME +tanh, tanhf, tanhl \- hyperbolic tangent function +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double tanh(double " x ); +.sp +.BI "float tanhf(float " x ); +.sp +.BI "long double tanhl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +The \fBtanh()\fP function returns the hyperbolic tangent of \fIx\fP, which +is defined mathematically as sinh(x) / cosh(x). +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899 (C99). +The float and the long double variants are C99 requirements. +.SH "SEE ALSO" +.BR acosh (3), +.BR asinh (3), +.BR atanh (3), +.BR cosh (3), +.BR sinh (3) diff --git a/man3/tanhf.3 b/man3/tanhf.3 new file mode 100644 index 000000000..3556edba4 --- /dev/null +++ b/man3/tanhf.3 @@ -0,0 +1 @@ +.so man3/tanh.3 diff --git a/man3/tanhl.3 b/man3/tanhl.3 new file mode 100644 index 000000000..3556edba4 --- /dev/null +++ b/man3/tanhl.3 @@ -0,0 +1 @@ +.so man3/tanh.3 diff --git a/man3/tanl.3 b/man3/tanl.3 new file mode 100644 index 000000000..58e5a1659 --- /dev/null +++ b/man3/tanl.3 @@ -0,0 +1 @@ +.so man3/tan.3 diff --git a/man3/tcdrain.3 b/man3/tcdrain.3 new file mode 100644 index 000000000..eb472496d --- /dev/null +++ b/man3/tcdrain.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/tcflow.3 b/man3/tcflow.3 new file mode 100644 index 000000000..eb472496d --- /dev/null +++ b/man3/tcflow.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/tcflush.3 b/man3/tcflush.3 new file mode 100644 index 000000000..eb472496d --- /dev/null +++ b/man3/tcflush.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/tcgetattr.3 b/man3/tcgetattr.3 new file mode 100644 index 000000000..eb472496d --- /dev/null +++ b/man3/tcgetattr.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/tcgetpgrp.3 b/man3/tcgetpgrp.3 new file mode 100644 index 000000000..d4c832780 --- /dev/null +++ b/man3/tcgetpgrp.3 @@ -0,0 +1,110 @@ +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH TCGETPGRP 3 2003-01-28 "POSIX" "Linux Programmer's Manual" +.SH NAME +tcgetpgrp, tcsetpgrp \- get and set terminal foreground process group +.SH SYNOPSIS +.sp +.BR "#include " +.sp +.BI "pid_t tcgetpgrp(int " fd ); +.sp +.BI "int tcsetpgrp(int " fd ", pid_t " pgrp ); +.SH DESCRIPTION +The function +.B tcgetpgrp() +returns the process group ID of the foreground process group on the +terminal associated to +.IR fd , +which must be the controlling terminal of the calling process. +.\" The process itself may be a background process. +.LP +The function +.B tcsetpgrp() +makes the process group with process group ID \fIpgrp\fP +the foreground process group on the terminal associated to +.IR fd , +which must be the controlling terminal of the calling process, +and still be associated with its session. +Moreover, \fIpgrp\fP must be a (nonempty) process group belonging to +the same session as the calling process. +.LP +If +.B tcsetpgrp() +is called by a member of a background process group in its session, +and the calling process is not blocking or ignoring SIGTTOU, +a SIGTTOU signal is sent to all members of this background process group. +.SH "RETURN VALUE" +When +.I fd +refers to the controlling terminal of the calling process, +the function +.B tcgetpgrp() +will return the foreground process group ID of that terminal +if there is one, and some value larger than 1 that is not +presently a process group ID otherwise. +When +.I fd +does not refer to the controlling terminal of the calling process, +\-1 is returned, and +.I errno +is set appropriately. +.LP +When successful, +.B tcsetpgrp() +returns 0. Otherwise, it returns \-1, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EINVAL +.I pgrp +has an unsupported value. +.TP +.B ENOTTY +The calling process does not have a controlling terminal, or +it has one but it is not described by +.IR fd , +or, for +.BR tcsetpgrp() , +this controlling terminal is no longer associated with the session +of the calling process. +.TP +.B EPERM +.I pgrp +has a supported value, but is not the process group ID of a +process in the same session as the calling process. +.SH NOTES +These functions are implemented via the TIOCGPGRP and +TIOCSPGRP ioctls. +.SH HISTORY +These ioctls appeared in 4.2 BSD. The functions are POSIX inventions. +.SH "CONFORMS TO" +POSIX.1 +.SH "SEE ALSO" +.BR setpgid (2), +.BR setsid (2) diff --git a/man3/tcgetsid.3 b/man3/tcgetsid.3 new file mode 100644 index 000000000..d0cc71446 --- /dev/null +++ b/man3/tcgetsid.3 @@ -0,0 +1,65 @@ +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH TCGETSID 3 2003-01-30 "POSIX" "Linux Programmer's Manual" +.SH NAME +tcgetsid \- get session ID +.SH SYNOPSIS +.sp +.BR "#include " +.sp +.BI "pid_t tcgetsid(int " fd ); +.SH DESCRIPTION +The function +.B tcgetsid() +returns the session ID of the current session that has the +terminal associated to +.I fd +as controlling terminal. +This terminal must be the controlling terminal of the calling process. +.SH "RETURN VALUE" +When +.I fd +refers to the controlling terminal of our session, +the function +.B tcgetsid() +will return the session ID of this session. +Otherwise, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B ENOTTY +The calling process does not have a controlling terminal, or +it has one but it is not described by +.IR fd . +.SH NOTES +This function is implemented via the TIOCGSID ioctl, present +since Linux 2.1.71. +.SH "CONFORMS TO" +POSIX 1003.1-2001 +.SH "SEE ALSO" +.BR getsid (2) diff --git a/man3/tcsendbreak.3 b/man3/tcsendbreak.3 new file mode 100644 index 000000000..eb472496d --- /dev/null +++ b/man3/tcsendbreak.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/tcsetattr.3 b/man3/tcsetattr.3 new file mode 100644 index 000000000..eb472496d --- /dev/null +++ b/man3/tcsetattr.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/tcsetpgrp.3 b/man3/tcsetpgrp.3 new file mode 100644 index 000000000..1a8b3604a --- /dev/null +++ b/man3/tcsetpgrp.3 @@ -0,0 +1 @@ +.so man3/tcgetpgrp.3 diff --git a/man3/tdelete.3 b/man3/tdelete.3 new file mode 100644 index 000000000..72f125195 --- /dev/null +++ b/man3/tdelete.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man3/telldir.3 b/man3/telldir.3 new file mode 100644 index 000000000..73f094120 --- /dev/null +++ b/man3/telldir.3 @@ -0,0 +1,55 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:48:42 1993 by Rik Faith (faith@cs.unc.edu) +.TH TELLDIR 3 1993-03-31 "" "Linux Programmer's Manual" +.SH NAME +telldir \- return current location in directory stream +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "off_t telldir(DIR *" dir ); +.fi +.SH DESCRIPTION +The \fBtelldir()\fP function returns the current location associated with +the directory stream \fIdir\fP. +.SH "RETURN VALUE" +The \fBtelldir()\fP function returns the current location in the directory +stream or \-1 if an error occurs. +.SH ERRORS +.TP +.B EBADF +Invalid directory stream descriptor \fIdir\fP. +.SH "CONFORMING TO" +BSD 4.3 +.SH "SEE ALSO" +.BR closedir (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3) diff --git a/man3/tempnam.3 b/man3/tempnam.3 new file mode 100644 index 000000000..b200cf324 --- /dev/null +++ b/man3/tempnam.3 @@ -0,0 +1,105 @@ +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH TEMPNAM 3 1999-06-14 "" "Linux Programmer's Manual" +.SH NAME +tempnam \- create a name for a temporary file +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *tempnam(const char *" dir ", const char *" pfx ); +.fi +.SH DESCRIPTION +The +.B tempnam() +function returns a pointer to a string that is a valid filename, +and such that a file with this name did not exist when +.B tempnam() +checked. +The filename suffix of the pathname generated will start with +.I pfx +in case +.I pfx +is a non-NULL string of at most five bytes. +The directory prefix part of the pathname generated is required to +be `appropriate' (often that at least implies writable). +Attempts to find an appropriate directory go through the following +steps: (i) In case the environment variable TMPDIR exists and +contains the name of an appropriate directory, that is used. +(ii) Otherwise, if the +.I dir +argument is non-NULL and appropriate, it is used. +(iii) Otherwise, +.I P_tmpdir +(as defined in +.IR ) +is used when appropriate. +(iv) Finally an implementation-defined directory may be used. +.SH "RETURN VALUE" +The +.B tempnam() +function returns a pointer to a unique temporary +filename, or NULL if a unique name cannot be generated. +.SH ERRORS +.TP +.B ENOMEM +Allocation of storage failed. +.LP +.SH NOTES +SUSv2 does not mention the use of TMPDIR; glibc will use it only +when the program is not suid. +SVID2 specifies that the directory used under (iv) is +.IR /tmp . +SVID2 specifies that the string returned by +.B tempnam() +was allocated using +.BR malloc (3) +and hence can be freed by +.BR free (3). +.LP +The +.B tempnam() +function generates a different string each time it is called, +up to TMP_MAX (defined in +.IR ) +times. If it is called more than TMP_MAX times, +the behaviour is implementation defined. +.LP +In case the +.I pfx +argument has length larger than five, glibc will use the first +five bytes. +Upon failure to find a unique name, glibc will return EEXIST. +.SH BUGS +The precise meaning of `appropriate' is undefined; +it is unspecified how accessibility of a directory is determined. +Never use this function. Use +.BR mkstemp (3) +instead. +.SH "CONFORMING TO" +SVID 2, BSD 4.3, POSIX 1003.1-2003 +.SH "SEE ALSO" +.BR mkstemp (3), +.BR mktemp (3), +.BR tmpfile (3), +.BR tmpnam (3) diff --git a/man3/termios.3 b/man3/termios.3 new file mode 100644 index 000000000..c63ea166c --- /dev/null +++ b/man3/termios.3 @@ -0,0 +1,635 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de) +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-02-25 by Jim Van Zandt +.\" Modified 1995-09-02 by Jim Van Zandt +.\" moved to man3, aeb, 950919 +.\" Modified 2001-09-22 by Michael Kerrisk +.\" Modified 2001-12-17, aeb +.\" Modified 2004-10-31, aeb +.\" +.TH TERMIOS 3 2004-10-31 "Linux" "Linux Programmer's Manual" +.SH NAME +termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, +cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, cfsetspeed \- +get and set terminal attributes, line control, get and set baud rate +.SH SYNOPSIS +.ad l +.ft B +#include +.br +#include +.sp +.BI "int tcgetattr(int " fd ", struct termios *" termios_p ); +.sp +.BI "int tcsetattr(int " fd ", int " optional_actions ", const struct termios *" termios_p ); +.sp +.BI "int tcsendbreak(int " fd ", int " duration ); +.sp +.BI "int tcdrain(int " fd ); +.sp +.BI "int tcflush(int " fd ", int " queue_selector ); +.sp +.BI "int tcflow(int " fd ", int " action ); +.sp +.BI "void cfmakeraw(struct termios *" termios_p ); +.sp +.BI "speed_t cfgetispeed(const struct termios *" termios_p ); +.sp +.BI "speed_t cfgetospeed(const struct termios *" termios_p ); +.sp +.BI "int cfsetispeed(struct termios *" termios_p ", speed_t " speed ); +.sp +.BI "int cfsetospeed(struct termios *" termios_p ", speed_t " speed ); +.ft P +.ad b +.SH DESCRIPTION +The termios functions describe a general terminal interface that is +provided to control asynchronous communications ports. +.LP +Many of the functions described here have a \fItermios_p\fP argument +that is a pointer to a \fBtermios\fP structure. This structure contains +at least the following members: +.ne 9 +.sp +.RS +.nf +tcflag_t \fIc_iflag\fP; /* input modes */ +tcflag_t \fIc_oflag\fP; /* output modes */ +tcflag_t \fIc_cflag\fP; /* control modes */ +tcflag_t \fIc_lflag\fP; /* local modes */ +cc_t \fIc_cc\fP[\fBNCCS\fP]; /* control chars */ +.fi +.RE +.PP +\fIc_iflag\fP flag constants: +.TP +.B IGNBRK +Ignore BREAK condition on input. +.TP +.B BRKINT +If \fBIGNBRK\fP is set, a BREAK is ignored. If it is not set +but \fBBRKINT\fP is set, then a BREAK causes the input and output +queues to be flushed, and if the terminal is the controlling +terminal of a foreground process group, it will cause a +\fBSIGINT\fP to be sent to this foreground process group. +When neither \fBIGNBRK\fP nor \fBBRKINT\fP are set, a BREAK +reads as a NUL character, except when \fBPARMRK\fP is set, +in which case it reads as the sequence \\377 \\0 \\0. +.TP +.B IGNPAR +Ignore framing errors and parity errors. +.TP +.B PARMRK +If \fBIGNPAR\fP is not set, prefix a character with a parity error or +framing error with \\377 \\0. If neither \fBIGNPAR\fP nor \fBPARMRK\fP +is set, read a character with a parity error or framing error +as \\0. +.TP +.B INPCK +Enable input parity checking. +.TP +.B ISTRIP +Strip off eighth bit. +.TP +.B INLCR +Translate NL to CR on input. +.TP +.B IGNCR +Ignore carriage return on input. +.TP +.B ICRNL +Translate carriage return to newline on input (unless \fBIGNCR\fP is set). +.TP +.B IUCLC +(not in POSIX) Map uppercase characters to lowercase on input. +.TP +.B IXON +Enable XON/XOFF flow control on output. +.TP +.B IXANY +(not in POSIX.1; XSI) Enable any character to restart output. +.TP +.B IXOFF +Enable XON/XOFF flow control on input. +.TP +.B IMAXBEL +(not in POSIX) Ring bell when input queue is full. +Linux does not implement this bit, and acts as if it is always set. +.PP +\fIc_oflag\fP flag constants defined in POSIX.1: +.TP +.B OPOST +Enable implementation-defined output processing. +.PP +The remaining \fIc_oflag\fP flag constants are defined in POSIX 1003.1-2001, +unless marked otherwise. +.TP +.B OLCUC +(not in POSIX) Map lowercase characters to uppercase on output. +.TP +.B ONLCR +(XSI) Map NL to CR-NL on output. +.TP +.B OCRNL +Map CR to NL on output. +.TP +.B ONOCR +Don't output CR at column 0. +.TP +.B ONLRET +Don't output CR. +.TP +.B OFILL +Send fill characters for a delay, rather than using a timed delay. +.TP +.B OFDEL +(not in POSIX) Fill character is ASCII DEL (0177). +If unset, fill character is ASCII NUL. +.TP +.B NLDLY +Newline delay mask. Values are \fBNL0\fP and \fBNL1\fP. +.TP +.B CRDLY +Carriage return delay mask. +Values are \fBCR0\fP, \fBCR1\fP, \fBCR2\fP, or \fBCR3\fP. +.TP +.B TABDLY +Horizontal tab delay mask. +Values are \fBTAB0\fP, \fBTAB1\fP, \fBTAB2\fP, \fBTAB3\fP (or \fBXTABS\fP). +A value of TAB3, that is, XTABS, expands tabs to spaces +(with tab stops every eight columns). +.TP +.B BSDLY +Backspace delay mask. Values are \fBBS0\fP or \fBBS1\fP. +(Has never been implemented.) +.TP +.B VTDLY +Vertical tab delay mask. Values are \fBVT0\fP or \fBVT1\fP. +.TP +.B FFDLY +Form feed delay mask. Values are \fBFF0\fP or \fBFF1\fP. +.PP +\fIc_cflag\fP flag constants: +.TP +.B CBAUD +(not in POSIX) Baud speed mask (4+1 bits). +.TP +.B CBAUDEX +(not in POSIX) Extra baud speed mask (1 bit), included in CBAUD. +.LP +(POSIX says that the baud speed is stored in the termios structure +without specifying where precisely, and provides +.B cfgetispeed() +and +.B cfsetispeed() +for getting at it. Some systems use bits selected by CBAUD in +.IR c_cflag , +other systems use separate fields, e.g. +.I sg_ispeed +and +.IR sg_ospeed .) +.TP +.B CSIZE +Character size mask. +Values are \fBCS5\fP, \fBCS6\fP, \fBCS7\fP, or \fBCS8\fP. +.TP +.B CSTOPB +Set two stop bits, rather than one. +.TP +.B CREAD +Enable receiver. +.TP +.B PARENB +Enable parity generation on output and parity checking for input. +.TP +.B PARODD +Parity for input and output is odd. +.TP +.B HUPCL +Lower modem control lines after last process closes the device (hang up). +.TP +.B CLOCAL +Ignore modem control lines. +.TP +.B LOBLK +(not in POSIX) Block output from a noncurrent shell layer. +(For use by \fBshl\fP.) +.TP +.B CIBAUD +(not in POSIX) Mask for input speeds. The values for the CIBAUD bits are +the same as the values for the CBAUD bits, shifted left IBSHIFT bits. +.TP +.B CRTSCTS +(not in POSIX) Enable RTS/CTS (hardware) flow control. +.PP +\fIc_lflag\fP flag constants: +.TP +.B ISIG +When any of the characters INTR, QUIT, SUSP, or DSUSP are received, +generate the corresponding signal. +.TP +.B ICANON +Enable canonical mode. This enables the special characters +EOF, EOL, EOL2, ERASE, KILL, LNEXT, REPRINT, STATUS, and WERASE, and +buffers by lines. +.TP +.B XCASE +(not in POSIX; not supported under Linux) +If \fBICANON\fP is also set, terminal is uppercase only. +Input is converted to lowercase, except for characters preceded by \\. +On output, uppercase characters are preceded by \\ and lowercase +characters are converted to uppercase. +.TP +.B ECHO +Echo input characters. +.TP +.B ECHOE +If \fBICANON\fP is also set, the ERASE character erases the preceding +input character, and WERASE erases the preceding word. +.TP +.B ECHOK +If \fBICANON\fP is also set, the KILL character erases the current line. +.TP +.B ECHONL +If \fBICANON\fP is also set, echo the NL character even if ECHO is not set. +.TP +.B ECHOCTL +(not in POSIX) If \fBECHO\fP is also set, ASCII control signals other than +TAB, NL, START, and STOP are echoed as ^X, where X is the character with +ASCII code 0x40 greater than the control signal. For example, character +0x08 (BS) is echoed as ^H. +.TP +.B ECHOPRT +(not in POSIX) If \fBICANON\fP and \fBIECHO\fP are also set, characters +are printed as they are being erased. +.TP +.B ECHOKE +(not in POSIX) If \fBICANON\fP is also set, KILL is echoed by erasing +each character on the line, as specified by \fBECHOE\fP and \fBECHOPRT\fP. +.TP +.B DEFECHO +(not in POSIX) Echo only when a process is reading. +.TP +.B FLUSHO +(not in POSIX; not supported under Linux) +Output is being flushed. This flag is toggled by typing +the DISCARD character. +.TP +.B NOFLSH +Disable flushing the input and output queues when generating the SIGINT, +SIGQUIT and SIGSUSP signals. +.\" Stevens lets SIGSUSP only flush the input queue +.TP +.B TOSTOP +Send the SIGTTOU signal to the process group of a background process +which tries to write to its controlling terminal. +.TP +.B PENDIN +(not in POSIX; not supported under Linux) +All characters in the input queue are reprinted when +the next character is read. (\fBbash\fP handles typeahead this way.) +.TP +.B IEXTEN +Enable implementation-defined input processing. +This flag, as well as \fBICANON\fP must be enabled for the +special characters EOL2, LNEXT, REPRINT, WERASE to be interpreted, +and for the \fBIUCLC\fP flag to be effective. +.PP +The \fIc_cc\fP array defines the special control characters. +The symbolic indices (initial values) and meaning are: +.TP +.B VINTR +(003, ETX, Ctrl-C, or also 0177, DEL, rubout) +Interrupt character. Send a SIGINT signal. +Recognized when ISIG is set, and then not passed as input. +.TP +.B VQUIT +(034, FS, Ctrl-\e) +Quit character. Send SIGQUIT signal. +Recognized when ISIG is set, and then not passed as input. +.TP +.B VERASE +(0177, DEL, rubout, or 010, BS, Ctrl-H, or also #) +Erase character. This erases the previous not-yet-erased character, +but does not erase past EOF or beginning-of-line. +Recognized when ICANON is set, and then not passed as input. +.TP +.B VKILL +(025, NAK, Ctrl-U, or Ctrl-X, or also @) +Kill character. This erases the input since the last EOF or beginning-of-line. +Recognized when ICANON is set, and then not passed as input. +.TP +.B VEOF +(004, EOT, Ctrl-D) +End-of-file character. +More precisely: this character causes the pending tty buffer to be sent +to the waiting user program without waiting for end-of-line. +If it is the first character of the line, the \fIread()\fP in the +user program returns 0, which signifies end-of-file. +Recognized when ICANON is set, and then not passed as input. +.TP +.B VMIN +Minimum number of characters for non-canonical read. +.TP +.B VEOL +(0, NUL) +Additional end-of-line character. +Recognized when ICANON is set. +.TP +.B VTIME +Timeout in deciseconds for non-canonical read. +.TP +.B VEOL2 +(not in POSIX; 0, NUL) +Yet another end-of-line character. +Recognized when ICANON is set. +.TP +.B VSWTCH +(not in POSIX; not supported under Linux; 0, NUL) +Switch character. (Used by \fBshl\fP only.) +.TP +.B VSTART +(021, DC1, Ctrl-Q) +Start character. Restarts output stopped by the Stop character. +Recognized when IXON is set, and then not passed as input. +.TP +.B VSTOP +(023, DC3, Ctrl-S) +Stop character. Stop output until Start character typed. +Recognized when IXON is set, and then not passed as input. +.TP +.B VSUSP +(032, SUB, Ctrl-Z) +Suspend character. Send SIGTSTP signal. +Recognized when ISIG is set, and then not passed as input. +.TP +.B VDSUSP +(not in POSIX; not supported under Linux; 031, EM, Ctrl-Y) +Delayed suspend character: +send SIGTSTP signal when the character is read by the user program. +Recognized when IEXTEN and ISIG are set, and the system supports +job control, and then not passed as input. +.TP +.B VLNEXT +(not in POSIX; 026, SYN, Ctrl-V) +Literal next. Quotes the next input character, depriving it of +a possible special meaning. +Recognized when IEXTEN is set, and then not passed as input. +.TP +.B VWERASE +(not in POSIX; 027, ETB, Ctrl-W) +Word erase. +Recognized when ICANON and IEXTEN are set, and then not passed as input. +.TP +.B VREPRINT +(not in POSIX; 022, DC2, Ctrl-R) +Reprint unread characters. +Recognized when ICANON and IEXTEN are set, and then not passed as input. +.TP +.B VDISCARD +(not in POSIX; not supported under Linux; 017, SI, Ctrl-O) +Toggle: start/stop discarding pending output. +Recognized when IEXTEN is set, and then not passed as input. +.TP +.B VSTATUS +(not in POSIX; not supported under Linux; +status request: 024, DC4, Ctrl-T). +.LP +These symbolic subscript values are all different, except that +VTIME, VMIN may have the same value as VEOL, VEOF, respectively. +(In non-canonical mode the special character meaning is replaced +by the timeout meaning. MIN represents the minimum number of characters +that should be received to satisfy the read. TIME is a decisecond-valued +timer. When both are set, a read will wait until at least one character +has been received, and then return as soon as either MIN characters +have been received or time TIME has passed since the last character +was received. If only MIN is set, the read will not return before +MIN characters have been received. If only TIME is set, the read will +return as soon as either at least one character has been received, +or the timer times out. If neither is set, the read will return +immediately, only giving the currently already available characters.) +.PP +.B tcgetattr() +gets the parameters associated with the object referred by \fIfd\fP and +stores them in the \fBtermios\fP structure referenced by +\fItermios_p\fP. This function may be invoked from a background process; +however, the terminal attributes may be subsequently changed by a +foreground process. +.LP +.B tcsetattr() +sets the parameters associated with the terminal (unless support is +required from the underlying hardware that is not available) from the +\fBtermios\fP structure referred to by \fItermios_p\fP. +\fIoptional_actions\fP specifies when the changes take effect: +.IP \fBTCSANOW\fP +the change occurs immediately. +.IP \fBTCSADRAIN\fP +the change occurs after all output written to +.I fd +has been transmitted. This function should be used when changing +parameters that affect output. +.IP \fBTCSAFLUSH\fP +the change occurs after all output written to the object referred by +.I fd +has been transmitted, and all input that has been received but not read +will be discarded before the change is made. +.LP +.B tcsendbreak() +transmits a continuous stream of zero-valued bits for a specific +duration, if the terminal is using asynchronous serial data +transmission. If \fIduration\fP is zero, it transmits zero-valued bits +for at least 0.25 seconds, and not more that 0.5 seconds. If +\fIduration\fP is not zero, it sends zero-valued bits for some +implementation-defined length of time. +.LP +If the terminal is not using asynchronous serial data transmission, +\fBtcsendbreak()\fP returns without taking any action. +.LP +.B tcdrain() +waits until all output written to the object referred to by +.I fd +has been transmitted. +.LP +.B tcflush() +discards data written to the object referred to by +.I fd +but not transmitted, or data received but not read, depending on the +value of +.IR queue_selector : +.IP \fBTCIFLUSH\fP +flushes data received but not read. +.IP \fBTCOFLUSH\fP +flushes data written but not transmitted. +.IP \fBTCIOFLUSH\fP +flushes both data received but not read, and data written but not +transmitted. +.LP +.B tcflow() +suspends transmission or reception of data on the object referred to by +.IR fd , +depending on the value of +.IR action : +.IP \fBTCOOFF\fP +suspends output. +.IP \fBTCOON\fP +restarts suspended output. +.IP \fBTCIOFF\fP +transmits a STOP character, which stops the terminal device from transmitting data to the +system. +.IP \fBTCION\fP +transmits a START character, which starts the terminal device transmitting data to the +system. +.LP +The default on open of a terminal file is that neither its input nor its +output is suspended. +.LP +The baud rate functions are provided for getting and setting the values +of the input and output baud rates in the \fBtermios\fP structure. The +new values do not take effect +until \fBtcsetattr()\fP is successfully called. + +Setting the speed to \fBB0\fP instructs the modem to "hang up". +The actual bit rate corresponding to \fBB38400\fP may be altered with +\fBsetserial\fP(8). +.LP +The input and output baud rates are stored in the \fBtermios\fP +structure. +.LP +\fBcfmakeraw\fP sets the terminal attributes as follows: +.nf + termios_p->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP + |INLCR|IGNCR|ICRNL|IXON); + termios_p->c_oflag &= ~OPOST; + termios_p->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN); + termios_p->c_cflag &= ~(CSIZE|PARENB); + termios_p->c_cflag |= CS8; +.fi +.LP +.B cfgetospeed() +returns the output baud rate stored in the \fBtermios\fP structure +pointed to by +.IR termios_p . +.LP +.B cfsetospeed() +sets the output baud rate stored in the \fBtermios\fP structure pointed +to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants: +.nf +.ft B + B0 + B50 + B75 + B110 + B134 + B150 + B200 + B300 + B600 + B1200 + B1800 + B2400 + B4800 + B9600 + B19200 + B38400 + B57600 + B115200 + B230400 +.ft P +.fi +The zero baud rate, \fBB0\fP, +is used to terminate the connection. If B0 +is specified, the modem control lines shall no longer be asserted. +Normally, this will disconnect the line. \fBCBAUDEX\fP is a mask +for the speeds beyond those defined in POSIX.1 (57600 and above). +Thus, \fBB57600\fP & \fBCBAUDEX\fP is nonzero. +.LP +.B cfgetispeed() +returns the input baud rate stored in the \fBtermios\fP structure. +.LP +.B cfsetispeed() +sets the input baud rate stored in the \fBtermios\fP structure to +.IR speed . +If the input baud rate is set to zero, the input baud rate will be +equal to the output baud rate. +.LP +.B cfsetspeed() +is a 4.4 BSD extension. It will set both input and output speed. +.SH "RETURN VALUE" +.LP +.B cfgetispeed() +returns the input baud rate stored in the +\fBtermios\fP +structure. +.LP +.B cfgetospeed() +returns the output baud rate stored in the \fBtermios\fP structure. +.LP +All other functions return: +.IP 0 +on success. +.IP \-1 +on failure and set +.I errno +to indicate the error. +.LP +Note that +.BI tcsetattr() +returns success if \fIany\fP of the requested changes could be +successfully carried out. Therefore, when making multiple changes +it may be necessary to follow this call with a further call to +.BI tcgetattr() +to check that all changes have been performed successfully. + +.SH NOTES +Unix V7 and several later systems have a list of baud rates +where after the fourteen values B0, ..., B9600 one finds the +two constants EXTA, EXTB ("External A" and "External B"). +Many systems extend the list with much higher baud rates. +.LP +The effect of a nonzero \fIduration\fP with \fBtcsendbreak\fP varies. +SunOS specifies a break of +.IB duration * N +seconds, where \fIN\fP is at least 0.25, and not more than 0.5. +Linux, AIX, DU, Tru64 send a break of +.I duration +milliseconds. +FreeBSD and NetBSD and HP-UX and MacOS ignore the value of +.IR duration . +Under Solaris and Unixware, +.B tcsendbreak +with nonzero +.I duration +behaves like +.BR tcdrain . +.\" libc4 until 4.7.5, glibc for sysv: EINVAL for duration > 0. +.\" libc4.7.6, libc5, glibc for unix: duration in ms. +.\" glibc for bsd: duration in us +.\" glibc for sunos4: ignore duration +.SH "SEE ALSO" +.BR stty (1), +.BR setserial (8) diff --git a/man3/tfind.3 b/man3/tfind.3 new file mode 100644 index 000000000..72f125195 --- /dev/null +++ b/man3/tfind.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man3/tgamma.3 b/man3/tgamma.3 new file mode 100644 index 000000000..0ee7f4768 --- /dev/null +++ b/man3/tgamma.3 @@ -0,0 +1,58 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" Based on glibc infopages +.TH TGAMMA 3 2002-08-10 "GNU" "libc math functions" +.SH NAME +tgamma, tgammaf, tgammal \- true gamma function +.SH SYNOPSIS +.B #include +.sp +.BI "double tgamma(double " x ); +.br +.BI "float tgammaf(float " x ); +.br +.BI "long double tgammal(long double " x ); +.sp +Link with \-lm. +.SH DESCRIPTION +The Gamma function is defined by +.sp + Gamma(x) = integral from 0 to infinity of t^(x-1) e^-t dt +.sp +It is defined for every real number except for nonpositive integers. +For nonnegative integral \fIm\fP one has +.sp + Gamma(m+1) = m! +.sp +and, more generally, for all \fIx\fP: +.sp + Gamma(x+1) = x * Gamma(x) +.sp +For \fIx\fP < 0.5 one can use +.sp + Gamma(x) * Gamma(1-x) = PI/sin(PI*x) +.PP +This function returns the value of the Gamma function for the +argument \fIx\fP. It had to be called "true gamma function" +since there is already a function +.I gamma() +that returns something else. +.SH ERRORS +In order to check for errors, set +.I errno +to zero and call +.I feclearexcept(FE_ALL_EXCEPT) +before calling these functions. On return, if +.I errno +is non-zero or +.I fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.LP +A range error occurs if x is too large. +A pole error occurs if x is zero. +A domain error (or a pole error) occurs if x is a negative integer. +.SH "CONFORMING TO" +C99. +.SH "SEE ALSO" +.BR gamma (3), +.BR lgamma (3) diff --git a/man3/tgammaf.3 b/man3/tgammaf.3 new file mode 100644 index 000000000..4a0248a0d --- /dev/null +++ b/man3/tgammaf.3 @@ -0,0 +1 @@ +.so man3/tgamma.3 diff --git a/man3/tgammal.3 b/man3/tgammal.3 new file mode 100644 index 000000000..4a0248a0d --- /dev/null +++ b/man3/tgammal.3 @@ -0,0 +1 @@ +.so man3/tgamma.3 diff --git a/man3/timegm.3 b/man3/timegm.3 new file mode 100644 index 000000000..f5fd3eb62 --- /dev/null +++ b/man3/timegm.3 @@ -0,0 +1,86 @@ +.\" Copyright (C) 2001 Andries Brouwer +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH TIMEGM 3 2001-12-26 "GNU" "Linux Programmer's Manual" +.SH NAME +timegm, timelocal \- inverses for gmtime and localtime +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "time_t timelocal (struct tm *" tm ); +.sp +.BI "time_t timegm (struct tm *" tm ); +.SH DESCRIPTION +The functions +.B timelocal() +and +.B timegm() +are the inverses to +.BR localtime (3) +and +.BR gmtime (3). +.SH NOTES +These functions are GNU extensions. +The +.B timelocal() +function is equivalent to the POSIX standard function +.BR mktime (3). +There is no reason to ever use it. +.LP +For a portable version of +.BR timegm() , +set the +.B TZ +environment variable to UTC, call +.B mktime() +and restore the value of +.BR TZ . +Something like + +.RS +.nf +#include +#include + +time_t my_timegm (struct tm *tm) { + time_t ret; + char *tz; + + tz = getenv("TZ"); + setenv("TZ", "", 1); + tzset(); + ret = mktime(tm); + if (tz) + setenv("TZ", tz, 1); + else + unsetenv("TZ"); + tzset(); + return ret; +} +.fi +.RE +.SH "SEE ALSO" +.BR gmtime (3), +.BR localtime (3), +.BR mktime (3), +.BR tzset (3) diff --git a/man3/timelocal.3 b/man3/timelocal.3 new file mode 100644 index 000000000..45d4c0907 --- /dev/null +++ b/man3/timelocal.3 @@ -0,0 +1 @@ +.so man3/timegm.3 diff --git a/man3/tmpfile.3 b/man3/tmpfile.3 new file mode 100644 index 000000000..f51528290 --- /dev/null +++ b/man3/tmpfile.3 @@ -0,0 +1,83 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:46:57 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-11-17, aeb +.TH TMPFILE 3 2001-11-17 "" "Linux Programmer's Manual" +.SH NAME +tmpfile \- create a temporary file +.SH SYNOPSIS +.nf +.B #include +.sp +.B FILE *tmpfile (void); +.fi +.SH DESCRIPTION +The \fBtmpfile()\fP function generates a unique temporary filename. +The temporary file is then opened in binary read/write (w+b) mode. +The file will be automatically deleted when it is closed or the +program terminates normally. +.SH "RETURN VALUE" +The \fBtmpfile()\fP function returns a stream descriptor, or NULL if +a unique filename cannot be generated or the unique file cannot be +opened. In the latter case, \fIerrno\fP is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Search permission denied for directory in file's path prefix. +.TP +.B EEXIST +Unable to generate a unique filename. +.TP +.B EINTR +The call was interrupted by a signal. +.TP +.B EMFILE +Too many file descriptors in use by the process. +.TP +.B ENFILE +Too many files open in the system. +.TP +.B ENOSPC +There was no room in the directory to add the new filename. +.TP +.B EROFS +Read-only filesystem. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3, ISO 9899, SUSv2 +.SH NOTES +An error message may be written to \fIstdout\fP if the stream +cannot be opened. +.LP +The standard does not specify the directory that \fItmpfile()\fP +will use. Glibc will try the path prefix \fIP_tmpdir\fP defined +in \fI\fP, and if that fails the directory \fI/tmp\fP. +.SH "SEE ALSO" +.BR exit (3), +.BR mkstemp (3), +.BR mktemp (3), +.BR tempnam (3), +.BR tmpnam (3) diff --git a/man3/tmpnam.3 b/man3/tmpnam.3 new file mode 100644 index 000000000..e42c49865 --- /dev/null +++ b/man3/tmpnam.3 @@ -0,0 +1,110 @@ +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" 2003-11-15, aeb, added tmpnam_r +.\" +.TH TMPNAM 3 2003-11-15 "" "Linux Programmer's Manual" +.SH NAME +tmpnam, tmpnam_r \- create a name for a temporary file +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *tmpnam(char *" s ); +.fi +.SH DESCRIPTION +The +.B tmpnam() +function returns a pointer to a string that is a valid filename, +and such that a file with this name did not exist at some point +in time, so that naive programmers may think it +a suitable name for a temporary file. If the argument +.I s +is NULL this name is generated in an internal static buffer +and may be overwritten by the next call to +.BR tmpnam() . +If +.I s +is not NULL, the name is copied to the character array (of length +at least +.IR L_tmpnam ) +pointed to by +.I s +and the value +.I s +is returned in case of success. +.LP +The path name that is created, has a directory prefix +.IR P_tmpdir . +(Both +.I L_tmpnam +and +.I P_tmpdir +are defined in +.IR , +just like the TMP_MAX mentioned below.) +.SH "RETURN VALUE" +The +.B tmpnam() +function returns a pointer to a unique temporary +filename, or NULL if a unique name cannot be generated. +.SH ERRORS +No errors are defined. +.SH NOTES +The +.B tmpnam() +function generates a different string each time it is called, +up to TMP_MAX times. If it is called more than TMP_MAX times, +the behaviour is implementation defined. +.LP +Portable applications that use threads cannot call +.B tmpnam() +with NULL parameter if either _POSIX_THREADS or +_POSIX_THREAD_SAFE_FUNCTIONS is defined. +.LP +A POSIX draft proposed to use a function +.B tmpnam_r() +defined by +.sp +.nf +.in +5 +char *tmpnam_r(char *s) { + return s ? tmpnam(s) : NULL; +} +.in +.fi +.sp +apparently as a warning not to use NULL. +A few systems implement it. To get a glibc prototype, +define _SVID_SOURCE or _BSD_SOURCE before including +.IR "" . +.SH BUGS +Never use this function. Use +.BR mkstemp (3) +instead. +.SH "CONFORMING TO" +SVID 2, POSIX, BSD 4.3, ISO 9899 +.SH "SEE ALSO" +.BR mkstemp (3), +.BR mktemp (3), +.BR tempnam (3), +.BR tmpfile (3) diff --git a/man3/tmpnam_r.3 b/man3/tmpnam_r.3 new file mode 100644 index 000000000..c1bd6dc1a --- /dev/null +++ b/man3/tmpnam_r.3 @@ -0,0 +1 @@ +.so man3/tmpnam.3 diff --git a/man3/toascii.3 b/man3/toascii.3 new file mode 100644 index 000000000..5180bc70d --- /dev/null +++ b/man3/toascii.3 @@ -0,0 +1,50 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" (c) 1995 by Jim Van Zandt +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" +.\" Added BUGS section, aeb, 950919 +.\" +.TH TOASCII 3 1995-09-16 "GNU" "Linux Programmer's Manual" +.SH NAME +toascii \- convert character to ASCII +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int toascii(int " "c" ); +.fi +.SH DESCRIPTION +\fBtoascii\fP() converts \fIc\fP to a 7-bit \fBunsigned char\fP value +that fits into the ASCII character set, by clearing the +high-order bits. +.SH "RETURN VALUE" +The value returned is that of the converted character. +.SH "CONFORMING TO" +SVID, BSD +.SH BUGS +Many people will be unhappy if you use this function. +This function will convert accented letters into random characters. +.SH "SEE ALSO" +.BR isascii (3), +.BR tolower (3), +.BR toupper (3) diff --git a/man3/tolower.3 b/man3/tolower.3 new file mode 100644 index 000000000..033f16e9e --- /dev/null +++ b/man3/tolower.3 @@ -0,0 +1 @@ +.so man3/toupper.3 diff --git a/man3/toupper.3 b/man3/toupper.3 new file mode 100644 index 000000000..50365002c --- /dev/null +++ b/man3/toupper.3 @@ -0,0 +1,69 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 17:45:39 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2000-02-13 by Nicolás Lichtmaier +.TH TOUPPER 3 1993-04-04 "GNU" "Linux Programmer's Manual" +.SH NAME +toupper, tolower \- convert letter to upper or lower case +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int toupper(int " "c" ); +.nl +.BI "int tolower(int " "c" ); +.fi +.SH DESCRIPTION +.B toupper() +converts the letter +.I c +to upper case, if possible. +.PP +.B tolower() +converts the letter +.I c +to lower case, if possible. +.PP +If +.I c +is not an unsigned char value, or EOF, the behaviour of these functions +is undefined. +.SH "RETURN VALUE" +The value returned is that of the converted letter, or +.I c +if the conversion was not possible. +.SH "CONFORMING TO" +ANSI C, BSD 4.3 +.SH BUGS +The details of what constitutes an uppercase or lowercase letter depend +on the current locale. For example, the default +.B """C""" +locale does not know about umlauts, so no conversion is done for them. +.PP +In some non - English locales, there are lowercase letters with no +corresponding uppercase equivalent; the German sharp s is one +example. +.SH "SEE ALSO" +.BR isalpha (3), +.BR setlocale (3), +.BR locale (7) diff --git a/man3/towctrans.3 b/man3/towctrans.3 new file mode 100644 index 000000000..1634a7b5d --- /dev/null +++ b/man3/towctrans.3 @@ -0,0 +1,41 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH TOWCTRANS 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +towctrans \- wide-character transliteration +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wint_t towctrans(wint_t " wc ", wctrans_t " desc ); +.fi +.SH DESCRIPTION +If \fIwc\fP is a wide character, the \fBtowctrans\fP function translates it +according to the transliteration descriptor \fIdesc\fP. If \fIwc\fP is WEOF, +WEOF is returned. +.PP +\fIdesc\fP must be a transliteration descriptor returned by the \fBwctrans\fP +function. +.SH "RETURN VALUE" +The \fBtowctrans\fP function returns the translated wide character, or WEOF if +\fIwc\fP is WEOF. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR towlower (3), +.BR towupper (3), +.BR wctrans (3) +.SH NOTES +The behaviour of \fBtowctrans\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/towlower.3 b/man3/towlower.3 new file mode 100644 index 000000000..e4f1b292c --- /dev/null +++ b/man3/towlower.3 @@ -0,0 +1,42 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH TOWLOWER 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +towlower \- convert a wide character to lowercase +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wint_t towlower(wint_t " wc ); +.fi +.SH DESCRIPTION +The \fBtowlower\fP function is the wide-character equivalent of the +\fBtolower\fP function. If \fIwc\fP is a wide character, it is converted to +lowercase. Characters which do not have case are returned unchanged. +If \fIwc\fP is WEOF, WEOF is returned. +.SH "RETURN VALUE" +The \fBtowlower\fP function returns the lowercase equivalent of \fIwc\fP, +or WEOF if \fIwc\fP is WEOF. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR iswlower (3), +.BR towctrans (3), +.BR towupper (3) +.SH NOTES +The behaviour of \fBtowlower\fP depends on the LC_CTYPE category of the +current locale. +.PP +This function is not very appropriate for dealing with Unicode characters, +because Unicode knows about three cases: upper, lower and title case. diff --git a/man3/towupper.3 b/man3/towupper.3 new file mode 100644 index 000000000..c34831f47 --- /dev/null +++ b/man3/towupper.3 @@ -0,0 +1,42 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH TOWUPPER 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +towupper \- convert a wide character to uppercase +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wint_t towupper(wint_t " wc ); +.fi +.SH DESCRIPTION +The \fBtowupper\fP function is the wide-character equivalent of the +\fBtoupper\fP function. If \fIwc\fP is a wide character, it is converted to +uppercase. Characters which do not have case are returned unchanged. +If \fIwc\fP is WEOF, WEOF is returned. +.SH "RETURN VALUE" +The \fBtowupper\fP function returns the uppercase equivalent of \fIwc\fP, +or WEOF if \fIwc\fP is WEOF. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR iswupper (3), +.BR towctrans (3), +.BR towlower (3) +.SH NOTES +The behaviour of \fBtowupper\fP depends on the LC_CTYPE category of the +current locale. +.PP +This function is not very appropriate for dealing with Unicode characters, +because Unicode knows about three cases: upper, lower and title case. diff --git a/man3/trunc.3 b/man3/trunc.3 new file mode 100644 index 000000000..1e722c1b4 --- /dev/null +++ b/man3/trunc.3 @@ -0,0 +1,54 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH TRUNC 3 2001-05-31 "" "Linux Programmer's Manual" +.SH NAME +trunc, truncf, truncl \- round to integer, towards zero +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "double trunc(double " x ); +.br +.BI "float truncf(float " x ); +.br +.BI "long double truncl(long double " x ); +.fi +.sp +Link with \-lm. +.SH DESCRIPTION +These functions round \fIx\fP to the nearest integer +not larger in absolute value. +.SH "RETURN VALUE" +The rounded integer value. +If \fIx\fP is integral, infinite or NaN, \fIx\fP itself is returned. +.SH ERRORS +None. +.SH "CONFORMING TO" +C99. +.SH "SEE ALSO" +.BR ceil (3), +.BR floor (3), +.BR lrint (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3) diff --git a/man3/truncf.3 b/man3/truncf.3 new file mode 100644 index 000000000..b85934168 --- /dev/null +++ b/man3/truncf.3 @@ -0,0 +1 @@ +.so man3/trunc.3 diff --git a/man3/truncl.3 b/man3/truncl.3 new file mode 100644 index 000000000..b85934168 --- /dev/null +++ b/man3/truncl.3 @@ -0,0 +1 @@ +.so man3/trunc.3 diff --git a/man3/tsearch.3 b/man3/tsearch.3 new file mode 100644 index 000000000..f592f3bf8 --- /dev/null +++ b/man3/tsearch.3 @@ -0,0 +1,200 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" Copyright 1995 by Jim Van Zandt +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH TSEARCH 3 1995-09-24 "GNU" "Linux Programmer's Manual" +.SH NAME +tsearch, tfind, tdelete, twalk \- manage a binary tree +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void *tsearch(const void *" key ", void **" rootp , +.BI " int(*" compar ")(const void *, const void *));" +.sp +.BI "void *tfind(const void *" key ", const void **" rootp , +.BI " int(*" compar ")(const void *, const void *));" +.sp +.BI "void *tdelete(const void *" key ", void **" rootp , +.BI " int(*" compar ")(const void *, const void *));" +.sp +.BI "void twalk(const void *" root ", void(*" action ")(const void *" nodep , +.BI " const VISIT " which , +.BI " const int " depth "));" +.sp +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "void tdestroy (void *" root ", void (*" free_node ")(void *" nodep )); +.RE +.fi +.SH DESCRIPTION +\fBtsearch\fP, \fBtfind\fP, \fBtwalk\fP, and \fBtdelete\fP manage a +binary tree. They are generalized from Knuth (6.2.2) Algorithm T. +The first field in each node of the tree is a pointer to the +corresponding data item. (The calling program must store the actual +data.) \fIcompar\fP points to a comparison routine, which takes +pointers to two items. It should return an integer which is negative, +zero, or positive, depending on whether the first item is less than, +equal to, or greater than the second. +.PP +\fBtsearch\fP searches the tree for an item. \fIkey\fP +points to the item to be searched for. \fIrootp\fP points to a +variable which points to the root of the tree. If the tree is empty, +then the variable that \fIrootp\fP points to should be set to \fBNULL\fP. +If the item is found in the tree, then \fBtsearch\fP returns a pointer +to it. If it is not found, then \fBtsearch\fP adds it, and returns a +pointer to the newly added item. +.PP +\fBtfind\fP is like \fBtsearch\fP, except that if the item is not +found, then \fBtfind\fP returns \fBNULL\fP. +.PP +\fBtdelete\fP deletes an item from the tree. Its arguments are the +same as for \fBtsearch\fP. +.PP +\fBtwalk\fP performs depth-first, left-to-right traversal of a binary +tree. \fIroot\fP points to the starting node for the traversal. If +that node is not the root, then only part of the tree will be visited. +\fBtwalk\fP calls the user function \fIaction\fP each time a node is +visited (that is, three times for an internal node, and once for a +leaf). \fIaction\fP, in turn, takes three arguments. The first is a +pointer to the node being visited. The second is an integer which +takes on the values \fBpreorder\fP, \fBpostorder\fP, and +\fBendorder\fP depending on whether this is the first, second, or +third visit to the internal node, or \fBleaf\fP if it is the single +visit to a leaf node. (These symbols are defined in +\fI\fP.) The third argument is the depth of the node, with +zero being the root. +.PP +(More commonly, \fBpreorder\fP, \fBpostorder\fP, and \fBendorder\fP +are known as \fBpreorder\fP, \fBinorder\fP, and \fBpostorder\fP: +before visiting the children, after the first and before the second, +and after visiting the children. Thus, the choice of name \fBpost\%order\fP +is rather confusing.) +.PP +\fBtdestroy\fP removes the whole tree pointed to by \fIrootp\fP, +freeing all resources allocated by the \fBtsearch\fP function. For +the data in each tree node the function \fIfree_node\fP is called. +The pointer to the data is passed as the argument to the function. If +no such work is necessary \fIfree_node\fP must point to a function +doing nothing. +.SH "RETURN VALUE" +\fBtsearch\fP returns a pointer to a matching item in the tree, or to +the newly added item, or \fBNULL\fP if there was insufficient memory +to add the item. \fBtfind\fP returns a pointer to the item, or +\fBNULL\fP if no match is found. If there +are multiple elements that match the key, the element returned is +unspecified. +.PP +\fBtdelete\fP returns a pointer to the parent of the item deleted, or +\fBNULL\fP if the item was not found. +.PP +\fBtsearch\fP, \fBtfind\fP, and \fBtdelete\fP also +return \fBNULL\fP if \fIrootp\fP was \fBNULL\fP on entry. +.SH WARNINGS +\fBtwalk\fP takes a pointer to the root, while the other functions +take a pointer to a variable which points to the root. +.PP +\fBtwalk\fP uses \fBpostorder\fP to mean "after the left subtree, but +before the right subtree". Some authorities would call this +"inorder", and reserve "postorder" to mean "after both subtrees". +.PP +\fBtdelete\fP frees the memory required for the node in the tree. +The user is responsible for freeing the memory for the corresponding +data. +.PP +The example program depends on the fact that \fBtwalk\fP makes no +further reference to a node after calling the user function with +argument "endorder" or "leaf". This works with the GNU library +implementation, but is not in the SysV documentation. +.SH EXAMPLE +The following program inserts twelve random numbers into a binary +tree, where duplicate numbers are collapsed, then prints the numbers +in order. +.sp +.nf + #include + #include + #include + #include + + void *root = NULL; + + void *xmalloc(unsigned n) { + void *p; + p = malloc(n); + if (p) return p; + fprintf(stderr, "insufficient memory\\n"); + exit(1); + } + + int compare(const void *pa, const void *pb) { + if (*(int *)pa < *(int *)pb) return -1; + if (*(int *)pa > *(int *)pb) return 1; + return 0; + } + + void action(const void *nodep, const VISIT which, const int depth) { + int *datap; + + switch(which) { + case preorder: + break; + case postorder: + datap = *(int **)nodep; + printf("%6d\\n", *datap); + break; + case endorder: + break; + case leaf: + datap = *(int **)nodep; + printf("%6d\\n", *datap); + break; + } + } + + int main() { + int i, *ptr; + void *val; + + srand(time(NULL)); + for (i = 0; i < 12; i++) { + ptr = (int *)xmalloc(sizeof(int)); + *ptr = rand()&0xff; + val = tsearch((void *)ptr, &root, compare); + if (val == NULL) exit(1); + } + twalk(root, action); + return 0; + } +.fi +.SH "CONFORMING TO" +SVID. +The function +.B tdestroy() +is a GNU extension. +.SH "SEE ALSO" +.BR bsearch (3), +.BR hsearch (3), +.BR lsearch (3), +.BR qsort (3) diff --git a/man3/ttyname.3 b/man3/ttyname.3 new file mode 100644 index 000000000..5cc1521ec --- /dev/null +++ b/man3/ttyname.3 @@ -0,0 +1,84 @@ +.\" Copyright (c) 1995 Jim Van Zandt +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified 2001-12-13, Martin Schulze +.\" Added ttyname_r, aeb, 2002-07-20 +.\" +.TH TTYNAME 3 2002-07-20 "Linux" "Linux Programmer's Manual" +.SH NAME +ttyname, ttyname_r \- return name of a terminal +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *ttyname(int " fd ); +.br +.BI "int ttyname_r(int " fd ", char *" buf ", size_t " buflen ); +.fi +.SH DESCRIPTION +The function +.BR ttyname () +returns a pointer to the NUL-terminated pathname of the terminal device +that is open on the file descriptor \fIfd\fP, or \fBNULL\fP on error +(for example, if \fIfd\fP is not connected to a terminal). +The return value may point to static data, possibly overwritten by the +next call. +The function +.BR ttyname_r () +stores this pathname in the buffer +.I buf +of length +.IR buflen . +.SH "RETURN VALUE" +The function +.BR ttyname () +returns a pointer to a pathname on success. On error, +.B NULL +is returned, and +.I errno +is set appropriately. +The function +.BR ttyname_r () +returns 0 on success, and an error number upon error. +.SH ERRORS +Values stored in +.I errno +by a failing +.BR ttyname () +or returned by a failing +.BR ttyname_r (): +.TP +.B EBADF +Bad file descriptor. +.TP +.B ENOTTY +File descriptor does not refer to a terminal device. +.TP +.B ERANGE +.I buflen +was too small to allow storing the pathname. +.SH "CONFORMING TO" +POSIX.1 +.\" don't know about these: SVID, AT&T, X/OPEN, BSD 4.3 +.SH "SEE ALSO" +.BR fstat (2), +.BR isatty (3) diff --git a/man3/ttyname_r.3 b/man3/ttyname_r.3 new file mode 100644 index 000000000..aaa18ee8b --- /dev/null +++ b/man3/ttyname_r.3 @@ -0,0 +1 @@ +.so man3/ttyname.3 diff --git a/man3/ttyslot.3 b/man3/ttyslot.3 new file mode 100644 index 000000000..4b2570062 --- /dev/null +++ b/man3/ttyslot.3 @@ -0,0 +1,129 @@ +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.\" +.TH TTYSLOT 3 2002-07-20 "GNU" "Linux Programmer's Manual" +.SH NAME +ttyslot \- find the slot of the current user's terminal in some file +.SH SYNOPSIS +.sp +.BR "#include " " /* on BSD-like systems */" +.br +.BR "#include " " /* on SYSV-like systems */" +.sp +.B "int ttyslot(void);" +.SH DESCRIPTION +The legacy function +.BR ttyslot () +returns the index of the current user's entry in some file. +.LP +Now "What file?" you ask. Well, let's first look at some history. +.SS "Ancient History" +There used to be a file +.I /etc/ttys +in Unix V6, that was read by the +.BR init (8) +program to find out what to do with each terminal line. +Each line consisted of three characters. +The first character was either '0' or '1', where '0' meant "ignore". +The second character denoted the terminal: '8' stood for "/dev/tty8". +The third character was an argument to +.BR getty (8) +indicating the sequence of line speeds to try ('-' was: start trying +110 baud). Thus a typical line was "18-". +A hang on some line was solved by changing the '1' to a '0', +signalling init, changing back again, and signalling init again. +.LP +In Unix V7 the format was changed: here the second character +was the argument to +.BR getty (8) +indicating the sequence of line speeds to try ('0' was: cycle through +300-1200-150-110 baud; '4' was for the on-line console DECwriter) +while the rest of the line contained the name of the tty. +Thus a typical line was "14console". +.LP +Later systems have more elaborate syntax. +SYSV-like systems have +.I /etc/inittab +instead. +.SS "Ancient History (2)" +On the other hand, there is the file +.I /etc/utmp +listing the people currently logged in. It is maintained by +.BR login (8). +It has a fixed size, and the appropriate index in the file was +determined by +.BR login (8) +using the +.BR ttyslot () +call to find the number of the line in +.IR /etc/ttys +(counting from 1). +.SS "The semantics of ttyslot" +Thus, the function +.BR ttyslot () +returns the index of the controlling terminal of the current process +in the file +.IR /etc/ttys , +and that is (usually) the same as the index of the entry for the +current user in the file +.IR /etc/utmp . +BSD still has the +.I /etc/ttys +file, but SYSV-like systems do not, and hence cannot refer to it. +Thus, on such systems the documentation says that +.BR ttyslot () +returns the current user's index in the user accounting data base. +.SH "RETURN VALUE" +If successful, this function returns the slot number. +On error (e.g., if none of the file descriptors 0, 1 or 2 is +associated with a terminal that occurs in this data base) +it returns 0 on Unix V6 and V7 and BSD-like systems, +but \-1 on SYSV-like systems. +.SH NOTES +The utmp file is found various places on various systems, such as +.IR /etc/utmp , +.IR /var/adm/utmp , +.IR /var/run/utmp . +.LP +The glibc2 implementation of this function reads the file +.BR _PATH_TTYS , +defined in +.I +as "/etc/ttys". It returns 0 on error. +Since Linux systems do not usually have "/etc/ttys", it will +always return 0. +.LP +Minix also has +.IR fttyslot ( fd ). +.SH HISTORY +.BR ttyslot () +appeared in Unix V7. +.SH "CONFORMS TO" +XPG2. Legacy in SUSv2. Deleted in SUSv3. +SUSv2 requires \-1 on error. +.SH "SEE ALSO" +.BR getttyent (3), +.BR ttyname (3), +.BR utmp (5) diff --git a/man3/twalk.3 b/man3/twalk.3 new file mode 100644 index 000000000..72f125195 --- /dev/null +++ b/man3/twalk.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man3/tzset.3 b/man3/tzset.3 new file mode 100644 index 000000000..171b98abf --- /dev/null +++ b/man3/tzset.3 @@ -0,0 +1,173 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 11:01:58 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-11-13, aeb +.TH TZSET 3 2001-11-13 "" "Linux Programmer's Manual" +.SH NAME +tzset, tzname, timezone, daylight \- initialize time conversion information +.SH SYNOPSIS +.nf +.B #include +.sp +.B void tzset (void); +.sp +.BI "extern char *" tzname [2]; +.BI "extern long " timezone ; +.BI "extern int " daylight ; +.fi +.SH DESCRIPTION +The \fBtzset()\fP function initializes the \fItzname\fP variable from the +TZ environment variable. This function is automatically called by the +other time conversion functions that depend on the time zone. +In a SysV-like environment it will also set the variables \fItimezone\fP +(seconds West of GMT) and \fIdaylight\fP (0 if this time zone does not +have any daylight savings time rules, nonzero if there is a time during +the year when daylight savings time applies). +.PP +If the TZ variable does not appear in the environment, the \fItzname\fP +variable is initialized with the best approximation of local wall clock +time, as specified by the +.BR tzfile (5)-format +file \fIlocaltime\fP +found in the system timezone directory (see below). +(One also often sees +.I /etc/localtime +used here, a symlink to the right file in the system timezone directory.) +.PP +If the TZ variable does appear in the environment but its value is NULL +or its value cannot be interpreted using any of the formats specified +below, Coordinated Universal Time (UTC) is used. +.PP +The value of TZ can be one of three formats. The first format is used +when there is no daylight saving time in the local time zone: +.sp +.RS +.I std offset +.RE +.sp +The \fIstd\fP string specifies the name of the time zone and must be +three or more alphabetic characters. The \fIoffset\fP string immediately +follows \fIstd\fP and specifies the time value to be added to the local +time to get Coordinated Universal Time (UTC). The \fIoffset\fP is positive +if the local time zone is west of the Prime Meridian and negative if it is +east. The hour must be between 0 and 24, and the minutes and seconds +0 and 59. +.PP +The second format is used when there is daylight saving time: +.sp +.RS +.I std offset dst [offset],start[/time],end[/time] +.RE +.sp +There are no spaces in the specification. The initial \fIstd\fP and +\fIoffset\fP specify the standard time zone, as described above. The +\fIdst\fP string and \fIoffset\fP specify the name and offset for the +corresponding daylight savings time zone. If the offset is omitted, +it defaults to one hour ahead of standard time. +.PP +The \fIstart\fP field specifies when daylight savings time goes into +effect and the \fIend\fP field specifies when the change is made back to +standard time. These fields may have the following formats: +.TP +J\fIn\fP +This specifies the Julian day with \fIn\fP between 1 and 365. February +29 is never counted even in leap years. +.TP +.I n +This specifies the Julian day with \fIn\fP between 1 and 365. February +29 is counted in leap years. +.TP +M\fIm\fP.\fIw\fP.\fId\fP +This specifies day \fId\fP (0 <= \fId\fP <= 6) of week \fIw\fP +(1 <= \fIw\fP <= 5) of month \fIm\fP (1 <= \fIm\fP <= 12). Week 1 is +the first week in which day \fId\fP occurs and week 5 is the last week +in which day \fId\fP occurs. Day 0 is a Sunday. +.PP +The \fItime\fP fields specify when, in the local time currently in effect, +the change to the other time occurs. If omitted, the default is 02:00:00. +.PP +The third format specifies that the time zone information should be read +from a file: +.sp +.RS +:[filespec] +.RE +.sp +If the file specification \fIfilespec\fP is omitted, the time zone +information is read from the file +.I localtime +in the system timezone directory, which nowadays usually is +.IR /usr/share/zoneinfo . +This file is in +.BR tzfile (5) +format. If \fIfilespec\fP is given, it specifies another +.BR tzfile (5)-format +file to read the time zone information from. If +\fIfilespec\fP does not begin with a `/', the file specification is +relative to the system timezone directory. +.SH FILES +The system time zone directory used depends on the (g)libc version. +Libc4 and libc5 use +.IR /usr/lib/zoneinfo , +and, since libc-5.4.6, +when this doesn't work, will try +.IR /usr/share/zoneinfo . +Glibc2 will use the environment variable TZDIR, when that exists. +Its default depends on how it was installed, but normally is +.IR /usr/share/zoneinfo . +.LP +This timezone directory contains the files +.nf +localtime local time zone file +posixrules rules for POSIX-style TZ's +.fi +.LP +Often +.I /etc/localtime +is a symlink to the file +.I localtime +or to the correct time zone file in the system time zone directory. +.SH "CONFORMING TO" +SVID 3, POSIX, BSD 4.3 +.SH NOTES +Note that the variable \fIdaylight\fP does not indicate that daylight +savings time applies right now. It used to give the number of some +algorithm (see the variable \fItz_dsttime\fP in +.BR gettimeofday (2)). +It has been obsolete for many years but is required by SUSv2. +.LP +BSD4.3 had a routine \fIchar *timezone(zone,dst)\fP that returned the +name of the time zone corresponding to its first argument (minutes +West of GMT). If the second argument was 0, the standard name was used, +otherwise the daylight savings time version. +.SH "SEE ALSO" +.BR date (1), +.BR gettimeofday (2), +.BR time (2), +.BR ctime (3), +.BR getenv (3), +.BR tzfile (5) diff --git a/man3/ualarm.3 b/man3/ualarm.3 new file mode 100644 index 000000000..19e57b86f --- /dev/null +++ b/man3/ualarm.3 @@ -0,0 +1,111 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH UALARM 3 2003-07-24 "" "Linux Programmer's Manual" +.SH NAME +ualarm \- schedule signal after given number of microseconds +.SH SYNOPSIS +.nf +/* BSD version */ +.B "#include " +.sp +.BI "unsigned int" +.br +.BI "ualarm(unsigned int " usecs ", unsigned int " interval ); +.sp +/* SUSv2 version */ +.B "#define _XOPEN_SOURCE 500" +.br +.B "#include " +.sp +.BI "useconds_t ualarm(useconds_t " usecs ", useconds_t " interval ); +.fi +.SH DESCRIPTION +The \fBualarm()\fP function causes the signal SIGALRM to be sent +to the invoking process after (not less than) +.I usecs +microseconds. +The delay may be lengthened slightly by any system activity +or by the time spent processing the call or by the +granularity of system timers. +.LP +Unless caught or ignored, this signal will terminate the process. +.LP +If the +.I interval +argument is nonzero, further SIGALRM signals will be sent every +.I interval +microseconds after the first. +.SH "RETURN VALUE" +This function returns the number of microseconds remaining from +the previous call, or 0 when no alarm is pending. +.SH ERRORS +.TP +EINTR +Interrupted by a signal. +.TP +EINVAL +\fIusecs\fP or \fIinterval\fP is not smaller than 1000000. +(On systems where that is considered an error.) +.SH "CONFORMING TO" +BSD 4.3, POSIX 1003.1-2003. +BSD 4.3, SUSv2 and POSIX do not define any errors. +.SH NOTES +The type +.B useconds_t +is an unsigned integer type capable of holding integers +in the range [0,1000000]. +This type is defined by +.I +included by +.I +but glibc defines it only when _XOPEN_SOURCE has a value not less than 500, +or both _XOPEN_SOURCE and _XOPEN_SOURCE_EXTENDED are defined. +.\" useconds_t also gives problems on HPUX 10. +Programs will be more portable if they never mention this type explicitly. +.LP +The interaction of this function with +other timer functions such as +.IR alarm (), +.IR sleep (), +.IR nanosleep (), +.IR setitimer (), +.IR timer_create (), +.IR timer_delete (), +.IR timer_getoverrun (), +.IR timer_gettime (), +.IR timer_settime (), +.IR usleep () +is unspecified. +.LP +This function is obsolete. Use +.BR nanosleep (2) +or +.BR setitimer (2) +instead. +.SH "SEE ALSO" +.BR alarm (2), +.BR getitimer (2), +.BR nanosleep (2), +.BR select (2), +.BR setitimer (2), +.BR usleep (3) diff --git a/man3/ulckpwdf.3 b/man3/ulckpwdf.3 new file mode 100644 index 000000000..142c5a5ca --- /dev/null +++ b/man3/ulckpwdf.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/ulimit.3 b/man3/ulimit.3 new file mode 100644 index 000000000..7fd0efa90 --- /dev/null +++ b/man3/ulimit.3 @@ -0,0 +1,81 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Moved to man3, aeb, 980612 +.\" +.TH ULIMIT 3 1998-06-12 "Linux 2.0" "Linux Programmer's Manual" +.SH NAME +ulimit \- get and set user limits +.SH SYNOPSIS +.B #include +.sp +.BI "long ulimit(int " cmd ", long " newlimit ); +.SH DESCRIPTION +Warning: This routine is obsolete. The include file is no longer +provided by glibc. Use getrlimit(2), setrlimit(2) and sysconf(3) +instead. +For the shell command +.BR ulimit , +see +.BR bash (1). + +The +.B ulimit +call will get or set some limit for the current process. +The +.I cmd +argument can have one of the following values. +.TP +.B UL_GETFSIZE +Return the limit on the size of a file, in units of 512 bytes. +.TP +.B UL_SETFSIZE +Set the limit on the size of a file. +.TP +.B 3 +(Not implemented for Linux.) +Return the maximum possible address of the data segment. +.TP +.B 4 +(Implemented but no symbolic constant provided.) +Return the maximum number of files that the calling process can open. + +.SH "RETURN VALUE" +On success, +.B ulimit +returns a nonnegative value. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EPERM +A non-root process tried to increase a limit. +.SH "CONFORMING TO" +SVID. +.SH "SEE ALSO" +.BR bash (1), +.BR getrlimit (2), +.BR setrlimit (2), +.BR sysconf (3) diff --git a/man3/undocumented.3 b/man3/undocumented.3 new file mode 100644 index 000000000..dd10de558 --- /dev/null +++ b/man3/undocumented.3 @@ -0,0 +1,225 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright 1995 Jim Van Zandt +.\" From jrv@vanzandt.mv.com Mon Sep 4 21:11:50 1995 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" 1996-11-08, meem@sherilyn.wustl.edu, corrections +.\" 2004-10-31, aeb, changed maintainer address, updated list +.\" +.TH UNDOCUMENTED 3 2004-10-31 "Linux" "Linux Programmer's Manual" +.SH NAME +none \- undocumented library functions +.SH SYNOPSIS +Undocumented library functions +.SH DESCRIPTION +This man page mentions those library functions which are implemented in +the standard libraries but not yet documented in man pages. +.SH SOLICITATION +If you have information about these functions, +please look in the source code, write a man page (using a style +similar to that of the other Linux section 3 man pages), and send it to +.B mtk-manpages@gmx.net +for inclusion in the next man page release. +.SH "THE LIST" + +authdes_create +authdes_getucred +authdes_pk_create +backtrace +backtrace_symbols +backtrace_symbols_fd +canonicalize_file_name +chflags +clntunix_create +creat64 +dn_skipname +fattach +fchflags +fclean +fcrypt +fdetach +fexecve +fmemopen +fopencookie +fp_nquery +fp_query +fp_resstat +freadable +freading +freeifaddrs +freopen64 +fseeko64 +fstatvfs +ftello64 +ftw64 +fwriteable +fwriting +fwscanf +get_avphys_pages +getdirentries64 +getgrid_r +getgrname_r +getgrouplist +getmsg +getnetname +get_nprocs +get_nprocs_conf +get_phys_pages +getpublickey +getsecretkey +getutmp +getutmpx +h_errlist +host2netname +hostalias +if_freenameindex +if_indextoname +if_nameindex +if_nametoindex +inet_nsap_addr +inet_nsap_ntoa +init_des +initstate_r +libc_nls_init +lio_listio +mallinfo +mallopt +mcheck +mprobe +mstats +netname2host +netname2user +nlist +obstack_free +obstack stuff +offsetof +open_memstream +parse_printf_format +p_cdname +p_cdnname +p_class +p_fqname +p_option +p_query +printf_size +printf_size_info +program_invocation_name +program_invocation_short_name +p_rr +p_time +ptsname_r +p_type +putlong +putshort +rawmemchr +readdir_r +re_compile_fastmap +re_compile_pattern +register_printf_function +re_match +re_match_2 +re_rx_search +re_search +re_search_2 +re_set_registers +re_set_syntax +res_send_setqhook +res_send_setrhook +rexec +rpmatch +ruserpass +setfileno +sethostfile +setkey_r +setstate_r +statvfs +strchrnul +svc_exit +svcudp_enablecache +syscall +sysv_signal +tell +tmpnam_r +tr_break +tzsetwall +ufc_dofinalperm +ufc_doit +user2netname +utmpxname +vlimit +vtimes +wcschrnul +wcsftime +wscanf +xdr_authdes_cred +xdr_authdes_verf +xdr_cryptkeyarg +xdr_cryptkeyres +xdr_datum +xdr_des_block +xdr_domainname +xdr_getcredres +xdr_keybuf +xdr_keystatus +xdr_mapname +xdr_netnamestr +xdr_netobj +xdr_passwd +xdr_peername +xdr_rmtcall_args +xdr_rmtcallres +xdr_unixcred +xdr_yp_buf +xdr_yp_inaddr +xdr_ypbind_binding +xdr_ypbind_resp +xdr_ypbind_resptype +xdr_ypbind_setdom +xdr_ypdelete_args +xdr_ypmaplist +xdr_ypmaplist_str +xdr_yppasswd +xdr_ypreq_key +xdr_ypreq_nokey +xdr_ypresp_all +xdr_ypresp_all_seq +xdr_ypresp_key_val +xdr_ypresp_maplist +xdr_ypresp_master +xdr_ypresp_order +xdr_ypresp_val +xdr_ypstat +xdr_ypupdate_args +yp_all +yp_bind +yperr_string +yp_first +yp_get_default_domain +yp_maplist +yp_master +yp_match +yp_next +yp_order +ypprot_err +yp_unbind +yp_update diff --git a/man3/ungetc.3 b/man3/ungetc.3 new file mode 100644 index 000000000..4636db712 --- /dev/null +++ b/man3/ungetc.3 @@ -0,0 +1 @@ +.so man3/gets.3 diff --git a/man3/ungetwc.3 b/man3/ungetwc.3 new file mode 100644 index 000000000..d7be9b92a --- /dev/null +++ b/man3/ungetwc.3 @@ -0,0 +1,50 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH UNGETWC 3 1999-09-19 "GNU" "Linux Programmer's Manual" +.SH NAME +ungetwc \- push back a wide character onto a FILE stream +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wint_t ungetwc(wint_t " wc ", FILE *" stream ); +.fi +.SH DESCRIPTION +The \fBungetwc\fP function is the wide-character equivalent of the \fBungetc\fP +function. It pushes back a wide character onto \fIstream\fP and returns it. +.PP +If \fIwc\fP is WEOF, it returns WEOF. If \fIwc\fP is an invalid wide character, +it sets \fBerrno\fP to \fBEILSEQ\fP and returns WEOF. +.PP +If \fIwc\fP is a valid wide character, it is pushed back onto the stream +and thus becomes available for future wide character read operations. +The file-position indicator is decremented by one or more. The end-of-file +indicator is cleared. The backing storage of the file is not affected. +.PP +Note: \fIwc\fP need not be the last wide character read from the stream; +it can be any other valid wide character. +.PP +If the implementation supports multiple push-back operations in a row, the +pushed-back wide characters will be read in reverse order; however, only one +level of push-back is guaranteed. +.SH "RETURN VALUE" +The \fBungetwc\fP function returns \fIwc\fP when successful, or WEOF upon +failure. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR fgetwc (3) +.SH NOTES +The behaviour of \fBungetwc\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/unlocked_stdio.3 b/man3/unlocked_stdio.3 new file mode 100644 index 000000000..46a26ed2e --- /dev/null +++ b/man3/unlocked_stdio.3 @@ -0,0 +1,94 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH UNLOCKED_STDIO 3 2001-10-18 "" "Linux Programmer's Manual" +.SH NAME +*_unlocked \- non-locking stdio functions +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int getc_unlocked(FILE *" stream ); +.BI "int getchar_unlocked(void);" +.BI "int putc_unlocked(int " c ", FILE *" stream ); +.BI "int putchar_unlocked(int " c ); +.sp +.BR "#define _BSD_SOURCE" " /* or _SVID_SOURCE or _GNU_SOURCE */ +.B #include +.sp +.BI "void clearerr_unlocked(FILE *" stream ); +.BI "int feof_unlocked(FILE *" stream ); +.BI "int ferror_unlocked(FILE *" stream ); +.BI "int fileno_unlocked(FILE *" stream ); +.BI "int fflush_unlocked(FILE *" stream ); +.BI "int fgetc_unlocked(FILE *" stream ); +.BI "int fputc_unlocked(int " c ", FILE *" stream ); +.BI "size_t fread_unlocked(void *" ptr ", size_t " size ", size_t " n , +.BI " FILE *" stream ); +.BI "size_t fwrite_unlocked(const void *" ptr ", size_t " size ", size_t " n , +.BI " FILE *" stream ); +.sp +.B #define _GNU_SOURCE +.B #include +.sp +.BI "char *fgets_unlocked(char *" s ", int " n ", FILE *" stream ); +.BI "int fputs_unlocked(const char *" s ", FILE *" stream ); +.sp +.B #define _GNU_SOURCE +.B #include +.sp +.BI "wint_t getwc_unlocked(FILE *" stream ); +.BI "wint_t getwchar_unlocked(void);" +.BI "wint_t fgetwc_unlocked(FILE *" stream ); +.BI "wint_t fputwc_unlocked(wchar_t " wc ", FILE *" stream ); +.BI "wint_t putwc_unlocked(wchar_t " wc ", FILE *" stream ); +.BI "wint_t putwchar_unlocked(wchar_t " wc ); +.BI "wchar_t *fgetws_unlocked(wchar_t *" ws ", int " n ", FILE *" stream ); +.BI "int fputws_unlocked(const wchar_t *" ws ", FILE *" stream ); +.fi +.SH DESCRIPTION +Each of these functions has the same behaviour as its counterpart +without the `_unlocked' suffix, except that they do not use locking +(they do not set locks themselves, and do not test for the presence +of locks set by others) and hence are thread-unsafe. +See +.BR flockfile (3). +.SH "CONFORMING TO" +The four functions \fIgetc_unlocked\fP(), \fIgetchar_unlocked\fP(), +\fIputc_unlocked\fP(), \fIputchar_unlocked\fP() are in POSIX.1. +The nonstandard +.BR *_unlocked() +variants occur on a few Unix systems, and are available in recent glibc. +.\" E.g., in HPUX 10.0. In HPUX 10.30 they are called obsolescent, and +.\" moved to a compatibility library. +.\" Available in HPUX 10.0: clearerr_unlocked, fclose_unlocked, +.\" feof_unlocked, ferror_unlocked, fflush_unlocked, fgets_unlocked, +.\" fgetwc_unlocked, fgetws_unlocked, fileno_unlocked, fputs_unlocked, +.\" fputwc_unlocked, fputws_unlocked, fread_unlocked, fseek_unlocked, +.\" ftell_unlocked, fwrite_unlocked, getc_unlocked, getchar_unlocked, +.\" getw_unlocked, getwc_unlocked, getwchar_unlocked, putc_unlocked, +.\" putchar_unlocked, puts_unlocked, putws_unlocked, putw_unlocked, +.\" putwc_unlocked, putwchar_unlocked, rewind_unlocked, setvbuf_unlocked, +.\" ungetc_unlocked, ungetwc_unlocked. +They should probably not be used. +.SH "SEE ALSO" +.BR flockfile (3) diff --git a/man3/unlockpt.3 b/man3/unlockpt.3 new file mode 100644 index 000000000..f1d1a6309 --- /dev/null +++ b/man3/unlockpt.3 @@ -0,0 +1,45 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" This page is in the public domain. - aeb +.\" +.TH UNLOCKPT 3 "2003-01-30" "PTY Control" "Linux Programmer's Manual" +.SH NAME +unlockpt \- unlock a pseudotty master/slave pair +.SH SYNOPSIS +.nf +.B #define _XOPEN_SOURCE +.br +.B #include +.sp +.BI "int unlockpt(int " fd ");" +.fi +.SH DESCRIPTION +The +.IR unlockpt () +function unlocks the slave pseudo-terminal device +(pty) corresponding to the master pty referred to by +.IR fd . +.PP +.IR unlockpt () +should be called before opening the slave side of a pty. +.SH "RETURN VALUE" +When successful, +.IR unlockpt () +returns 0. Otherwise, it returns \-1 and sets +.I errno +appropriately. +.SH ERRORS +.TP +.B EBADF +The +.I fd +argument is not a file descriptor open for writing. +.TP +.B EINVAL +The +.I fd +argument is not associated with a master pty. +.SH "CONFORMING TO" +POSIX 1003.1-2001. +.SH "SEE ALSO" +.IR grantpt (3), +.IR ptsname (3) diff --git a/man3/unsetenv.3 b/man3/unsetenv.3 new file mode 100644 index 000000000..19ec56c24 --- /dev/null +++ b/man3/unsetenv.3 @@ -0,0 +1 @@ +.so man3/setenv.3 diff --git a/man3/updwtmp.3 b/man3/updwtmp.3 new file mode 100644 index 000000000..e7bb3aa3b --- /dev/null +++ b/man3/updwtmp.3 @@ -0,0 +1,56 @@ +.\" Copyright 1997 Nicolás Lichtmaier +.\" Created Wed Jul 2 23:27:34 ART 1997 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" Added info on availability, aeb, 971207 +.\" Added -lutil remark, 030718 +.\" +.TH UPDWTMP 3 2003-07-18 "GNU" "Linux Programmer's Manual" +.SH NAME +updwtmp, logwtmp \- append an entry to the wtmp file +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void updwtmp(const char *" wtmp_file ", const struct utmp *" ut ); +.br +.BI "void logwtmp(const char *" line ", const char *" name ", const char *" host ); +.fi +.SH DESCRIPTION +\fBupdwtmp\fR() appends the utmp structure +.I ut +to the wtmp file. +.PP +\fBlogwtmp\fR() constructs an utmp structure using +.IR line ", " name ", " host , +current time and current process id. +Then it calls \fBupdwtmp\fR() to append the structure to the utmp file. +.SH AVAILABILITY +Both functions are available under glibc2, but not under libc5. +However, +.B logwtmp +used to occur in the old libbsd. These days, the +.B logwtmp +function is included in libutil. (Hence you'll need to add +.B \-lutil +to your compiler commandline to get it.) +.SH FILES +.TP +.I /var/log/wtmp +database of past user logins +.SH "SEE ALSO" +.BR wtmp (5) diff --git a/man3/usleep.3 b/man3/usleep.3 new file mode 100644 index 000000000..bebc1127a --- /dev/null +++ b/man3/usleep.3 @@ -0,0 +1,119 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-04-01 by aeb +.\" Modified 2003-07-23 by aeb +.\" +.TH USLEEP 3 2003-07-23 "" "Linux Programmer's Manual" +.SH NAME +usleep \- suspend execution for microsecond intervals +.SH SYNOPSIS +.nf +/* BSD version */ +.B "#include " +.sp +.BI "void usleep(unsigned long " usec ); +.sp +/* SUSv2 version */ +.B "#define _XOPEN_SOURCE 500" +.br +.B "#include " +.sp +.BI "int usleep(useconds_t " usec "); +.fi +.SH DESCRIPTION +The \fBusleep()\fP function suspends execution of the calling process for +(at least) \fIusec\fP microseconds. The sleep may be lengthened slightly +by any system activity or by the time spent processing the call or by the +granularity of system timers. +.SH "RETURN VALUE" +None (BSD). Or: 0 on success, \-1 on error (SUSv2). +.SH ERRORS +.TP +EINTR +Interrupted by a signal. +.TP +EINVAL +\fIusec\fP is not smaller than 1000000. +(On systems where that is considered an error.) +.SH "CONFORMING TO" +BSD 4.3. +The SUSv2 version returns int, and this is also the prototype +used by glibc 2.2.2. +Only the EINVAL error return is documented by SUSv2. +.SH NOTES +The type +.B useconds_t +is an unsigned integer type capable of holding integers +in the range [0,1000000]. Programs will be more portable +if they never mention this type explicitly. Use +.RS +.nf +.ta 8 +.sp +#include +\&... + unsigned int usecs; +\&... + usleep(usecs); +.sp +.fi +.RE +This type is defined by +.I +included by +.I +but glibc defines it only when _XOPEN_SOURCE has a value not less than 500, +or both _XOPEN_SOURCE and _XOPEN_SOURCE_EXTENDED are defined. +.\" useconds_t also gives problems on HPUX 10. +.LP +The interaction of this function with the SIGALRM signal, and with +other timer functions such as +.IR alarm (), +.IR sleep (), +.IR nanosleep (), +.IR setitimer (), +.IR timer_create (), +.IR timer_delete (), +.IR timer_getoverrun (), +.IR timer_gettime (), +.IR timer_settime (), +.IR ualarm () +is unspecified. +.LP +This function is obsolete. Use +.BR nanosleep (2) +or +.BR setitimer (2) +instead. +.SH "SEE ALSO" +.BR alarm (2), +.BR getitimer (2), +.BR nanosleep (2), +.BR select (2), +.BR setitimer (2), +.BR sleep (3) diff --git a/man3/utmpname.3 b/man3/utmpname.3 new file mode 100644 index 000000000..29c36b72a --- /dev/null +++ b/man3/utmpname.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/va_arg.3 b/man3/va_arg.3 new file mode 100644 index 000000000..c419248e8 --- /dev/null +++ b/man3/va_arg.3 @@ -0,0 +1 @@ +.so man3/stdarg.3 diff --git a/man3/va_copy.3 b/man3/va_copy.3 new file mode 100644 index 000000000..c419248e8 --- /dev/null +++ b/man3/va_copy.3 @@ -0,0 +1 @@ +.so man3/stdarg.3 diff --git a/man3/va_end.3 b/man3/va_end.3 new file mode 100644 index 000000000..c419248e8 --- /dev/null +++ b/man3/va_end.3 @@ -0,0 +1 @@ +.so man3/stdarg.3 diff --git a/man3/va_start.3 b/man3/va_start.3 new file mode 100644 index 000000000..c419248e8 --- /dev/null +++ b/man3/va_start.3 @@ -0,0 +1 @@ +.so man3/stdarg.3 diff --git a/man3/valloc.3 b/man3/valloc.3 new file mode 100644 index 000000000..791d4c801 --- /dev/null +++ b/man3/valloc.3 @@ -0,0 +1 @@ +.so man3/posix_memalign.3 diff --git a/man3/vasprintf.3 b/man3/vasprintf.3 new file mode 100644 index 000000000..5a8753a9c --- /dev/null +++ b/man3/vasprintf.3 @@ -0,0 +1 @@ +.so man3/asprintf.3 diff --git a/man3/vdprintf.3 b/man3/vdprintf.3 new file mode 100644 index 000000000..fa36f35d8 --- /dev/null +++ b/man3/vdprintf.3 @@ -0,0 +1 @@ +.so man3/dprintf.3 diff --git a/man3/verr.3 b/man3/verr.3 new file mode 100644 index 000000000..3ee2e497a --- /dev/null +++ b/man3/verr.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man3/verrx.3 b/man3/verrx.3 new file mode 100644 index 000000000..3ee2e497a --- /dev/null +++ b/man3/verrx.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man3/versionsort.3 b/man3/versionsort.3 new file mode 100644 index 000000000..7e757c7a0 --- /dev/null +++ b/man3/versionsort.3 @@ -0,0 +1 @@ +.so man3/scandir.3 diff --git a/man3/vfprintf.3 b/man3/vfprintf.3 new file mode 100644 index 000000000..975530d90 --- /dev/null +++ b/man3/vfprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man3/vfscanf.3 b/man3/vfscanf.3 new file mode 100644 index 000000000..9fd424bb2 --- /dev/null +++ b/man3/vfscanf.3 @@ -0,0 +1 @@ +.so man3/scanf.3 diff --git a/man3/vfwprintf.3 b/man3/vfwprintf.3 new file mode 100644 index 000000000..56ec9685b --- /dev/null +++ b/man3/vfwprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man3/vprintf.3 b/man3/vprintf.3 new file mode 100644 index 000000000..975530d90 --- /dev/null +++ b/man3/vprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man3/vscanf.3 b/man3/vscanf.3 new file mode 100644 index 000000000..9fd424bb2 --- /dev/null +++ b/man3/vscanf.3 @@ -0,0 +1 @@ +.so man3/scanf.3 diff --git a/man3/vsnprintf.3 b/man3/vsnprintf.3 new file mode 100644 index 000000000..975530d90 --- /dev/null +++ b/man3/vsnprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man3/vsprintf.3 b/man3/vsprintf.3 new file mode 100644 index 000000000..975530d90 --- /dev/null +++ b/man3/vsprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man3/vsscanf.3 b/man3/vsscanf.3 new file mode 100644 index 000000000..9fd424bb2 --- /dev/null +++ b/man3/vsscanf.3 @@ -0,0 +1 @@ +.so man3/scanf.3 diff --git a/man3/vswprintf.3 b/man3/vswprintf.3 new file mode 100644 index 000000000..56ec9685b --- /dev/null +++ b/man3/vswprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man3/vsyslog.3 b/man3/vsyslog.3 new file mode 100644 index 000000000..ec352b291 --- /dev/null +++ b/man3/vsyslog.3 @@ -0,0 +1 @@ +.so man3/syslog.3 diff --git a/man3/vwarn.3 b/man3/vwarn.3 new file mode 100644 index 000000000..3ee2e497a --- /dev/null +++ b/man3/vwarn.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man3/vwarnx.3 b/man3/vwarnx.3 new file mode 100644 index 000000000..3ee2e497a --- /dev/null +++ b/man3/vwarnx.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man3/vwprintf.3 b/man3/vwprintf.3 new file mode 100644 index 000000000..56ec9685b --- /dev/null +++ b/man3/vwprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man3/warn.3 b/man3/warn.3 new file mode 100644 index 000000000..3ee2e497a --- /dev/null +++ b/man3/warn.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man3/warnx.3 b/man3/warnx.3 new file mode 100644 index 000000000..3ee2e497a --- /dev/null +++ b/man3/warnx.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man3/wcpcpy.3 b/man3/wcpcpy.3 new file mode 100644 index 000000000..6c780be93 --- /dev/null +++ b/man3/wcpcpy.3 @@ -0,0 +1,41 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.TH WCPCPY 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcpcpy \- copy a wide character string, returning a pointer to its end +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "wchar_t *wcpcpy(wchar_t *" dest ", const wchar_t *" src ); +.fi +.SH DESCRIPTION +The \fBwcpcpy\fP function is the wide-character equivalent of the \fBstpcpy\fP +function. It copies the wide character string pointed to by \fIsrc\fP, +including the terminating L'\\0' character, to the array pointed to by +\fIdest\fP. +.PP +The strings may not overlap. +.PP +The programmer must ensure that there is room for at least \fIwcslen(src)+1\fP +wide characters at \fIdest\fP. +.SH "RETURN VALUE" +\fBwcpcpy\fP returns a pointer to the end of the wide-character string +\fIdest\fP, that is, a pointer to the terminating L'\\0' character. +.SH "CONFORMING TO" +This function is a GNU extension. +.SH "SEE ALSO" +.BR strcpy (3), +.BR wcscpy (3) diff --git a/man3/wcpncpy.3 b/man3/wcpncpy.3 new file mode 100644 index 000000000..ce379a93f --- /dev/null +++ b/man3/wcpncpy.3 @@ -0,0 +1,45 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.TH WCPNCPY 3 2003-11-01 "GNU" "Linux Programmer's Manual" +.SH NAME +wcpncpy \- copy a fixed-size string of wide characters, returning a pointer to its end +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "wchar_t *wcpncpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBwcpncpy\fP function is the wide-character equivalent of the \fBstpncpy\fP +function. It copies at most \fIn\fP wide characters from the wide-character +string pointed to by \fIsrc\fP, including the terminating L'\\0' character, +to the array pointed to by \fIdest\fP. Exactly \fIn\fP wide characters are +written at \fIdest\fP. If the length \fIwcslen(src)\fP is smaller than \fIn\fP, +the remaining wide characters in the array pointed to by \fIdest\fP are filled +with L'\\0' characters. If the length \fIwcslen(src)\fP is greater or equal +to \fIn\fP, the string pointed to by \fIdest\fP will not be L'\\0' terminated. +.PP +The strings may not overlap. +.PP +The programmer must ensure that there is room for at least \fIn\fP wide +characters at \fIdest\fP. +.SH "RETURN VALUE" +\fBwcpncpy\fP returns a pointer to the last wide character written, i.e. +\fIdest + n - 1\fP. +.SH "CONFORMING TO" +This function is a GNU extension. +.SH "SEE ALSO" +.BR stpncpy (3), +.BR wcsncpy (3) diff --git a/man3/wcrtomb.3 b/man3/wcrtomb.3 new file mode 100644 index 000000000..fdac276d8 --- /dev/null +++ b/man3/wcrtomb.3 @@ -0,0 +1,58 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCRTOMB 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcrtomb \- convert a wide character to a multibyte sequence +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t wcrtomb(char *" s ", wchar_t " wc ", mbstate_t *" ps ); +.fi +.SH DESCRIPTION +The main case for this function is when \fIs\fP is not NULL and \fIwc\fP is not +L'\\0'. +In this case, the \fBwcrtomb\fP function converts the wide character \fIwc\fP +to its multibyte representation and stores it at the beginning of the character +array pointed to by \fIs\fP. It updates the shift state \fI*ps\fP, and +returns the length of said multibyte representation, i.e. the number of bytes +written at \fIs\fP. +.PP +A different case is when \fIs\fP is not NULL but \fIwc\fP is L'\\0'. In this +case the \fBwcrtomb\fP function stores at the character array pointed to by +\fIs\fP the shift sequence needed to bring \fI*ps\fP back to the initial state, +followed by a '\\0' byte. It updates the shift state \fI*ps\fP (i.e. brings +it into the initial state), and returns the length of the shift sequence plus +one, i.e. the number of bytes written at \fIs\fP. +.PP +A third case is when \fIs\fP is NULL. In this case \fIwc\fP is ignored, +and the function effectively returns wcrtomb(buf,L'\\0',\fIps\fP) where +buf is an internal anonymous buffer. +.PP +In all of the above cases, if \fIps\fP is a NULL pointer, a static anonymous +state only known to the wcrtomb function is used instead. +.SH "RETURN VALUE" +The \fBwcrtomb\fP function returns the number of bytes that have been or would +have been written to the byte array at \fIs\fP. If \fIwc\fP can not be +represented as a multibyte sequence (according to the current locale), +(size_t)(-1) is returned, and \fBerrno\fP set to \fBEILSEQ\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR wcsrtombs (3) +.SH NOTES +The behaviour of \fBwcrtomb\fP depends on the LC_CTYPE category of the +current locale. +.PP +Passing NULL as \fIps\fP is not multi-thread safe. diff --git a/man3/wcscasecmp.3 b/man3/wcscasecmp.3 new file mode 100644 index 000000000..4f46483ff --- /dev/null +++ b/man3/wcscasecmp.3 @@ -0,0 +1,39 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.TH WCSCASECMP 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcscasecmp \- compare two wide-character strings, ignoring case +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int wcscasecmp(const wchar_t *" s1 ", const wchar_t *" s2 ); +.fi +.SH DESCRIPTION +The \fBwcscasecmp\fP function is the wide-character equivalent of the +\fBstrcasecmp\fP function. It compares the wide-character string pointed to +by \fIs1\fP and the wide-character string pointed to by \fIs2\fP, ignoring +case differences (\fBtowupper\fP, \fBtowlower\fP). +.SH "RETURN VALUE" +The \fBwcscasecmp\fP function returns zero if the wide-character strings at +\fIs1\fP and \fIs2\fP are equal except for case distinctions. It returns a +positive integer if \fIs1\fP is greater than \fIs2\fP, ignoring case. It +returns a negative integer if \fIs1\fP is smaller than \fIs2\fP, ignoring case. +.SH "CONFORMING TO" +This function is a GNU extension. +.SH "SEE ALSO" +.BR strcasecmp (3), +.BR wcscmp (3) +.SH NOTES +The behaviour of \fBwcscasecmp\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/wcscat.3 b/man3/wcscat.3 new file mode 100644 index 000000000..512b342ab --- /dev/null +++ b/man3/wcscat.3 @@ -0,0 +1,41 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSCAT 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcscat \- concatenate two wide-character strings +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wchar_t *wcscat(wchar_t *" dest ", const wchar_t *" src ); +.fi +.SH DESCRIPTION +The \fBwcscat\fP function is the wide-character equivalent of the \fBstrcat\fP +function. It copies the wide-character string pointed to by \fIsrc\fP, +including the terminating L'\\0' character, to the end of the wide-character +string pointed to by \fIdest\fP. +.PP +The strings may not overlap. +.PP +The programmer must ensure that there is room for at least +\fIwcslen(dest)+wcslen(src)+1\fP wide characters at \fIdest\fP. +.SH "RETURN VALUE" +\fBwcscat\fP returns \fIdest\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR strcat (3), +.BR wcpcpy (3), +.BR wcscpy (3), +.BR wcsncat (3) diff --git a/man3/wcschr.3 b/man3/wcschr.3 new file mode 100644 index 000000000..9afbd8e88 --- /dev/null +++ b/man3/wcschr.3 @@ -0,0 +1,38 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSCHR 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcschr \- search a wide character in a wide-character string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wchar_t *wcschr(const wchar_t *" wcs ", wchar_t " wc ); +.fi +.SH DESCRIPTION +The \fBwcschr\fP function is the wide-character equivalent of the \fBstrchr\fP +function. It searches the first occurrence of \fIwc\fP in the wide-character +string pointed to by \fIwcs\fP. +.SH "RETURN VALUE" +The \fBwcschr\fP function returns a pointer to the first occurrence of +\fIwc\fP in the wide-character string pointed to by \fIwcs\fP, or NULL if +\fIwc\fP does not occur in the string. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR strchr (3), +.BR wcspbrk (3), +.BR wcsrchr (3), +.BR wcsstr (3), +.BR wmemchr (3) diff --git a/man3/wcscmp.3 b/man3/wcscmp.3 new file mode 100644 index 000000000..f8c213fee --- /dev/null +++ b/man3/wcscmp.3 @@ -0,0 +1,39 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSCMP 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcscmp \- compare two wide-character strings +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int wcscmp(const wchar_t *" s1 ", const wchar_t *" s2 ); +.fi +.SH DESCRIPTION +The \fBwcscmp\fP function is the wide-character equivalent of the \fBstrcmp\fP +function. It compares the wide-character string pointed to by \fIs1\fP and the +wide-character string pointed to by \fIs2\fP. +.SH "RETURN VALUE" +The \fBwcscmp\fP function returns zero if the wide-character strings at +\fIs1\fP and \fIs2\fP are equal. It returns an integer greater than zero if +at the first differing position \fIi\fP, the corresponding wide-character +\fIs1[i]\fP is greater than \fIs2[i]\fP. It returns an integer less than zero if +at the first differing position \fIi\fP, the corresponding wide-character +\fIs1[i]\fP is less than \fIs2[i]\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR strcmp (3), +.BR wcscasecmp (3), +.BR wmemcmp (3) diff --git a/man3/wcscpy.3 b/man3/wcscpy.3 new file mode 100644 index 000000000..a64919ece --- /dev/null +++ b/man3/wcscpy.3 @@ -0,0 +1,42 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSCPY 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcscpy \- copy a wide character string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wchar_t *wcscpy(wchar_t *" dest ", const wchar_t *" src ); +.fi +.SH DESCRIPTION +The \fBwcscpy\fP function is the wide-character equivalent of the \fBstrcpy\fP +function. It copies the wide character string pointed to by \fIsrc\fP, +including the terminating L'\\0' character, to the array pointed to by +\fIdest\fP. +.PP +The strings may not overlap. +.PP +The programmer must ensure that there is room for at least \fIwcslen(src)+1\fP +wide characters at \fIdest\fP. +.SH "RETURN VALUE" +\fBwcscpy\fP returns \fIdest\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR strcpy (3), +.BR wcpcpy (3), +.BR wcscat (3), +.BR wcsdup (3), +.BR wmemcpy (3) diff --git a/man3/wcscspn.3 b/man3/wcscspn.3 new file mode 100644 index 000000000..33dd0d223 --- /dev/null +++ b/man3/wcscspn.3 @@ -0,0 +1,41 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSCSPN 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcscspn \- search a wide-character string for any of a set of wide characters +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t wcscspn(const wchar_t *" wcs ", const wchar_t *" reject ); +.fi +.SH DESCRIPTION +The \fBwcscspn\fP function is the wide-character equivalent of the \fBstrcspn\fP +function. It determines the length of the longest initial segment of \fIwcs\fP +which consists entirely of wide-characters not listed in \fIreject\fP. In +other words, it searches for the first occurrence in the wide-character +string \fIwcs\fP of any of the characters in the wide-character string +\fIreject\fP. +.SH "RETURN VALUE" +The \fBwcscspn\fP function returns the number of wide characters in the longest +initial segment of \fIwcs\fP which consists entirely of wide-characters not +listed in \fIreject\fP. In other words, it returns the position of the first +occurrence in the wide-character string \fIwcs\fP of any of the characters in +the wide-character string \fIreject\fP, or \fIwcslen(wcs)\fP if there is none. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR strcspn (3), +.BR wcspbrk (3), +.BR wcsspn (3) diff --git a/man3/wcsdup.3 b/man3/wcsdup.3 new file mode 100644 index 000000000..ade46e811 --- /dev/null +++ b/man3/wcsdup.3 @@ -0,0 +1,43 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.TH WCSDUP 3 2003-11-01 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsdup \- duplicate a wide-character string +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.br +.B #include +.sp +.BI "wchar_t *wcsdup(const wchar_t *" s ); +.fi +.SH DESCRIPTION +The \fBwcsdup\fP function is the wide-character equivalent of the \fBstrdup\fP +function. It allocates and returns a new wide-character string whose initial +contents is a duplicate of the wide-character string pointed to by \fIs\fP. +.PP +Memory for the new wide-character string is obtained with \fBmalloc\fP(3), and +can be freed with \fBfree\fP(3). +.SH "RETURN VALUE" +The \fBwcsdup\fP function returns a pointer to the new wide-character string, +or NULL if sufficient memory was not available. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory available to allocate duplicate string. +.SH "CONFORMING TO" +This function is a GNU extension. +.\" present in libc5 and glibc 2.0 and later +.SH "SEE ALSO" +.BR strdup (3), +.BR wcscpy (3) diff --git a/man3/wcslen.3 b/man3/wcslen.3 new file mode 100644 index 000000000..c29833be5 --- /dev/null +++ b/man3/wcslen.3 @@ -0,0 +1,32 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSLEN 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcslen \- determine the length of a wide-character string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t wcslen(const wchar_t *" s ); +.fi +.SH DESCRIPTION +The \fBwcslen\fP function is the wide-character equivalent of the \fBstrlen\fP +function. It determines the length of the wide-character string pointed to +by \fIs\fP, not including the terminating L'\\0' character. +.SH "RETURN VALUE" +The \fBwcslen\fP function returns the number of wide characters in \fIs\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR strlen (3) diff --git a/man3/wcsncasecmp.3 b/man3/wcsncasecmp.3 new file mode 100644 index 000000000..73abfa236 --- /dev/null +++ b/man3/wcsncasecmp.3 @@ -0,0 +1,41 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.TH WCSNCASECMP 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsncasecmp \- compare two fixed-size wide-character strings, ignoring case +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int wcsncasecmp(const wchar_t *" s1 ", const wchar_t *" s2 ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBwcsncasecmp\fP function is the wide-character equivalent of the +\fBstrncasecmp\fP function. It compares the wide-character string pointed to +by \fIs1\fP and the wide-character string pointed to by \fIs2\fP, but at most +\fIn\fP wide characters from each string, ignoring case differences +(\fBtowupper\fP, \fBtowlower\fP). +.SH "RETURN VALUE" +The \fBwcsncasecmp\fP function returns zero if the wide-character strings at +\fIs1\fP and \fIs2\fP, truncated to at most length \fIn\fP, are equal except +for case distinctions. It returns a positive integer if truncated \fIs1\fP is +greater than truncated \fIs2\fP, ignoring case. It returns a negative integer +if truncated \fIs1\fP is smaller than truncated \fIs2\fP, ignoring case. +.SH "CONFORMING TO" +This function is a GNU extension. +.SH "SEE ALSO" +.BR strncasecmp (3), +.BR wcsncmp (3) +.SH NOTES +The behaviour of \fBwcsncasecmp\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/wcsncat.3 b/man3/wcsncat.3 new file mode 100644 index 000000000..25ac34dfe --- /dev/null +++ b/man3/wcsncat.3 @@ -0,0 +1,39 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSNCAT 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsncat \- concatenate two wide-character strings +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wchar_t *wcsncat(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBwcsncat\fP function is the wide-character equivalent of the \fBstrncat\fP +function. It copies at most \fIn\fP wide characters from the wide-character +string pointed to by \fIsrc\fP to the end of the wide-character string pointed +to by \fIdest\fP, and adds a terminating L'\\0' character. +.PP +The strings may not overlap. +.PP +The programmer must ensure that there is room for at least +\fIwcslen(dest)+n+1\fP wide characters at \fIdest\fP. +.SH "RETURN VALUE" +\fBwcsncat\fP returns \fIdest\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR strncat (3), +.BR wcscat (3) diff --git a/man3/wcsncmp.3 b/man3/wcsncmp.3 new file mode 100644 index 000000000..75a10d137 --- /dev/null +++ b/man3/wcsncmp.3 @@ -0,0 +1,41 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSNCMP 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsncmp \- compare two fixed-size wide-character strings +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int wcsncmp(const wchar_t *" s1 ", const wchar_t *" s2 ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBwcsncmp\fP function is the wide-character equivalent of the \fBstrncmp\fP +function. It compares the wide-character string pointed to by \fIs1\fP and the +wide-character string pointed to by \fIs2\fP, but at most \fIn\fP wide +characters from each string. In each string, the comparison extends only up +to the first occurrence of a L'\\0' character, if any. +.SH "RETURN VALUE" +The \fBwcsncmp\fP function returns zero if the wide-character strings at +\fIs1\fP and \fIs2\fP, truncated to at most length \fIn\fP, are equal. +It returns an integer greater than zero if at the first differing position +\fIi\fP (\fIi\fP < \fIn\fP), the corresponding wide-character \fIs1[i]\fP is +greater than \fIs2[i]\fP. It returns an integer less than zero if at the first +differing position \fIi\fP (\fIi\fP < \fIn\fP), the corresponding +wide-character \fIs1[i]\fP is less than \fIs2[i]\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR strncmp (3), +.BR wcsncasecmp (3) diff --git a/man3/wcsncpy.3 b/man3/wcsncpy.3 new file mode 100644 index 000000000..5a3fabd07 --- /dev/null +++ b/man3/wcsncpy.3 @@ -0,0 +1,42 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSNCPY 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsncpy \- copy a fixed-size string of wide characters +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wchar_t *wcsncpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBwcsncpy\fP function is the wide-character equivalent of the \fBstrncpy\fP +function. It copies at most \fIn\fP wide characters from the wide-character +string pointed to by \fIsrc\fP, including the terminating L'\\0' character, +to the array pointed to by \fIdest\fP. Exactly \fIn\fP wide characters are +written at \fIdest\fP. If the length \fIwcslen(src)\fP is smaller than \fIn\fP, +the remaining wide characters in the array pointed to by \fIdest\fP are filled +with L'\\0' characters. If the length \fIwcslen(src)\fP is greater or equal +to \fIn\fP, the string pointed to by \fIdest\fP will not be L'\\0' terminated. +.PP +The strings may not overlap. +.PP +The programmer must ensure that there is room for at least \fIn\fP wide +characters at \fIdest\fP. +.SH "RETURN VALUE" +\fBwcsncpy\fP returns \fIdest\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR strncpy (3) diff --git a/man3/wcsnlen.3 b/man3/wcsnlen.3 new file mode 100644 index 000000000..fed21f11e --- /dev/null +++ b/man3/wcsnlen.3 @@ -0,0 +1,36 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.TH WCSNLEN 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsnlen \- determine the length of a fixed-size wide-character string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t wcsnlen(const wchar_t *" s ", size_t " maxlen ); +.fi +.SH DESCRIPTION +The \fBwcsnlen\fP function is the wide-character equivalent of the \fBstrnlen\fP +function. It returns the number of wide-characters in the string pointed to by +\fIs\fP, not including the terminating L'\\0' character, but at most +\fImaxlen\fP. In doing this, \fBwcsnlen\fP looks only at the first \fImaxlen\fP +wide-characters at \fIs\fP and never beyond \fIs+maxlen\fP. +.SH "RETURN VALUE" +The \fBwcsnlen\fP function returns \fIwcslen(s)\fP, if that is less than +\fImaxlen\fP, or \fImaxlen\fP if there is no L'\\0' character among the +first \fImaxlen\fP wide characters pointed to by \fIs\fP. +.SH "CONFORMING TO" +This function is a GNU extension. +.SH "SEE ALSO" +.BR strnlen (3), +.BR wcslen (3) diff --git a/man3/wcsnrtombs.3 b/man3/wcsnrtombs.3 new file mode 100644 index 000000000..3ed536773 --- /dev/null +++ b/man3/wcsnrtombs.3 @@ -0,0 +1,76 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.TH WCSNRTOMBS 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsnrtombs \- convert a wide character string to a multibyte string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t wcsnrtombs(char *" dest ", const wchar_t **" src ", size_t " nwc , +.BI " size_t " len ", mbstate_t *" ps ); +.fi +.SH DESCRIPTION +The \fBwcsnrtombs\fP function is like the \fBwcsrtombs\fP function, except that +the number of wide characters to be converted, starting at \fI*src\fP, is +limited to \fInwc\fP. +.PP +If \fIdest\fP is not a NULL pointer, the \fBwcsnrtombs\fP function converts +at most \fInwc\fP wide characters from +the wide-character string \fI*src\fP to a multibyte string starting at +\fIdest\fP. At most \fIlen\fP bytes are written to \fIdest\fP. The shift state +\fI*ps\fP is updated. The conversion is effectively performed by repeatedly +calling wcrtomb(\fIdest\fP,\fI*src\fP,\fIps\fP), as long as this call succeeds, +and then incrementing \fIdest\fP by the number of bytes written and \fI*src\fP +by one. The conversion can stop for three reasons: +.PP +1. A wide character has been encountered that can not be represented as a +multibyte sequence (according to the current locale). In this case \fI*src\fP +is left pointing to the invalid wide character, (size_t)(-1) is returned, +and \fBerrno\fP is set to \fBEILSEQ\fP. +.PP +2. \fInwc\fP wide characters have been converted without encountering a L'\\0', +or the length limit forces a stop. In this case \fI*src\fP is left pointing +to the next wide character to be converted, and the number of bytes written +to \fIdest\fP is returned. +.PP +3. The wide-character string has been completely converted, including the +terminating L'\\0' (which has the side effect of bringing back \fI*ps\fP +to the initial state). In this case \fI*src\fP is set to NULL, and the number +of bytes written to \fIdest\fP, excluding the terminating '\\0' byte, is +returned. +.PP +If \fIdest\fP is NULL, \fIlen\fP is ignored, and the conversion proceeds as +above, except that the converted bytes are not written out to memory, and that +no destination length limit exists. +.PP +In both of the above cases, if \fIps\fP is a NULL pointer, a static anonymous +state only known to the wcsnrtombs function is used instead. +.PP +The programmer must ensure that there is room for at least \fIlen\fP bytes +at \fIdest\fP. +.SH "RETURN VALUE" +The \fBwcsnrtombs\fP function returns the number of bytes that make up the +converted part of multibyte sequence, not including the terminating null byte. +If a wide character was encountered which could not be converted, (size_t)(-1) +is returned, and \fBerrno\fP set to \fBEILSEQ\fP. +.SH "CONFORMING TO" +This function is a GNU extension. +.SH "SEE ALSO" +.BR iconv (3), +.BR wcsrtombs (3) +.SH NOTES +The behaviour of \fBwcsnrtombs\fP depends on the LC_CTYPE category of the +current locale. +.PP +Passing NULL as \fIps\fP is not multi-thread safe. diff --git a/man3/wcspbrk.3 b/man3/wcspbrk.3 new file mode 100644 index 000000000..f3ecf2592 --- /dev/null +++ b/man3/wcspbrk.3 @@ -0,0 +1,37 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSPBRK 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcspbrk \- search a wide-character string for any of a set of wide characters +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wchar_t *wcspbrk(const wchar_t *" wcs ", const wchar_t *" accept ); +.fi +.SH DESCRIPTION +The \fBwcspbrk\fP function is the wide-character equivalent of the \fBstrpbrk\fP +function. It searches for the first occurrence in the wide-character +string pointed to by \fIwcs\fP of any of the characters in the wide-character +string pointed to by \fIaccept\fP. +.SH "RETURN VALUE" +The \fBwcspbrk\fP function returns a pointer to the first occurrence in +\fIwcs\fP of any of the characters listed in \fIaccept\fP. If \fIwcs\fP +contains none of these characters, NULL is returned. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR strpbrk (3), +.BR wcschr (3), +.BR wcscspn (3) diff --git a/man3/wcsrchr.3 b/man3/wcsrchr.3 new file mode 100644 index 000000000..85c2e8b91 --- /dev/null +++ b/man3/wcsrchr.3 @@ -0,0 +1,35 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSRCHR 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsrchr \- search a wide character in a wide-character string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wchar_t *wcsrchr(const wchar_t *" wcs ", wchar_t " wc ); +.fi +.SH DESCRIPTION +The \fBwcsrchr\fP function is the wide-character equivalent of the \fBstrrchr\fP +function. It searches the last occurrence of \fIwc\fP in the wide-character +string pointed to by \fIwcs\fP. +.SH "RETURN VALUE" +The \fBwcsrchr\fP function returns a pointer to the last occurrence of +\fIwc\fP in the wide-character string pointed to by \fIwcs\fP, or NULL if +\fIwc\fP does not occur in the string. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR strrchr (3), +.BR wcschr (3) diff --git a/man3/wcsrtombs.3 b/man3/wcsrtombs.3 new file mode 100644 index 000000000..51d5d099a --- /dev/null +++ b/man3/wcsrtombs.3 @@ -0,0 +1,76 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSRTOMBS 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsrtombs \- convert a wide character string to a multibyte string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t wcsrtombs(char *" dest ", const wchar_t **" src , +.BI " size_t " len ", mbstate_t *" ps ); +.fi +.SH DESCRIPTION +If \fIdest\fP is not a NULL pointer, the \fBwcsrtombs\fP function converts +the wide-character string \fI*src\fP to a multibyte string starting at +\fIdest\fP. At most \fIlen\fP bytes are written to \fIdest\fP. The shift state +\fI*ps\fP is updated. The conversion is effectively performed by repeatedly +calling wcrtomb(\fIdest\fP,\fI*src\fP,\fIps\fP), as long as this call succeeds, +and then incrementing \fIdest\fP by the number of bytes written and \fI*src\fP +by one. The conversion can stop for three reasons: +.PP +1. A wide character has been encountered that can not be represented as a +multibyte sequence (according to the current locale). In this case \fI*src\fP +is left pointing to the invalid wide character, (size_t)(-1) is returned, +and +.I errno +is set to \fBEILSEQ\fP. +.PP +2. The length limit forces a stop. In this case \fI*src\fP is left pointing +to the next wide character to be converted, and the number of bytes written to +\fIdest\fP is returned. +.PP +3. The wide-character string has been completely converted, including the +terminating L'\\0' (which has the side effect of bringing back \fI*ps\fP +to the initial state). In this case \fI*src\fP is set to NULL, and the number +of bytes written to \fIdest\fP, excluding the terminating '\\0' byte, is +returned. +.PP +If \fIdest\fP is NULL, \fIlen\fP is ignored, and the conversion proceeds as +above, except that the converted bytes are not written out to memory, and that +no length limit exists. +.PP +In both of the above cases, if \fIps\fP is a NULL pointer, a static anonymous +state only known to the wcsrtombs function is used instead. +.PP +The programmer must ensure that there is room for at least \fIlen\fP bytes +at \fIdest\fP. +.SH "RETURN VALUE" +The \fBwcsrtombs\fP function returns the number of bytes that make up the +converted part of multibyte sequence, not including the terminating null byte. +If a wide character was encountered which could not be converted, (size_t)(-1) +is returned, and +.I errno +set to \fBEILSEQ\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR iconv (3), +.BR wcsnrtombs (3), +.BR wcstombs (3) +.SH NOTES +The behaviour of \fBwcsrtombs\fP depends on the LC_CTYPE category of the +current locale. +.PP +Passing NULL as \fIps\fP is not multi-thread safe. diff --git a/man3/wcsspn.3 b/man3/wcsspn.3 new file mode 100644 index 000000000..c797827bb --- /dev/null +++ b/man3/wcsspn.3 @@ -0,0 +1,41 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSSPN 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsspn \- advance in a wide-character string, skipping any of a set of wide characters +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wcsspn(const wchar_t *" wcs ", const wchar_t *" accept ); +.fi +.SH DESCRIPTION +The \fBwcsspn\fP function is the wide-character equivalent of the \fBstrspn\fP +function. It determines the length of the longest initial segment of \fIwcs\fP +which consists entirely of wide-characters listed in \fIaccept\fP. In other +words, it searches for the first occurrence in the wide-character string +\fIwcs\fP of a wide-character not contained in the wide-character string +\fIaccept\fP. +.SH "RETURN VALUE" +The \fBwcsspn\fP function returns the number of wide characters in the longest +initial segment of \fIwcs\fP which consists entirely of wide-characters listed +in \fIaccept\fP. In other words, it returns the position of the first +occurrence in the wide-character string \fIwcs\fP of a wide-character not +contained in the wide-character string \fIaccept\fP, or \fIwcslen(wcs)\fP +if there is none. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR strspn (3), +.BR wcscspn (3) diff --git a/man3/wcsstr.3 b/man3/wcsstr.3 new file mode 100644 index 000000000..2e94f52c8 --- /dev/null +++ b/man3/wcsstr.3 @@ -0,0 +1,39 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSSTR 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsstr \- locate a substring in a wide-character string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wchar_t *wcsstr(const wchar_t *" haystack ", const wchar_t *" needle ); +.fi +.SH DESCRIPTION +The \fBwcsstr\fP function is the wide-character equivalent of the \fBstrstr\fP +function. It searches for the first occurrence of the wide-character string +\fIneedle\fP (without its terminating L'\\0' character) as a substring in +the wide-character string \fIhaystack\fP. +.SH "RETURN VALUE" +The \fBwcsstr\fP function returns a pointer to the first occurrence of +\fIneedle\fP in \fIhaystack\fP. It returns NULL if \fIneedle\fP does not occur +as a substring in \fIhaystack\fP. +.PP +Note the special case: If \fIneedle\fP is the empty wide-character string, +the return value is always \fIhaystack\fP itself. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR strstr (3), +.BR wcschr (3) diff --git a/man3/wcstoimax.3 b/man3/wcstoimax.3 new file mode 100644 index 000000000..2bb1cd49e --- /dev/null +++ b/man3/wcstoimax.3 @@ -0,0 +1,54 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH WCSTOIMAX 3 2003-11-01 "" "Linux Programmer's Manual" +.SH NAME +wcstoimax, wcstoumax \- convert wide-character string to integer +.SH SYNOPSIS +.nf +.B #include +.br +.B #include +.sp +.BI "intmax_t wcstoimax (const wchar_t *" nptr ", wchar_t **" endptr ", int " base ); +.br +.BI "uintmax_t wcstoumax (const wchar_t *" nptr ", wchar_t **" endptr ", int " base ); +.fi +.SH DESCRIPTION +These functions are just like +.B wcstol() +and +.BR wcstoul() , +except that they return a value of type +.B intmax_t +and +.BR uintmax_t , +respectively. +.SH "CONFORMING TO" +C99, POSIX 1003.1-2003. +.SH "SEE ALSO" +.BR imaxabs (3), +.BR imaxdiv (3), +.BR strtoimax (3), +.BR strtoumax (3), +.BR wcstol (3), +.BR wcstoul (3) diff --git a/man3/wcstok.3 b/man3/wcstok.3 new file mode 100644 index 000000000..f2fcf40fe --- /dev/null +++ b/man3/wcstok.3 @@ -0,0 +1,63 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSTOK 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcstok \- split wide-character string into tokens +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wchar_t *wcstok(wchar_t *" wcs ", const wchar_t *" delim ", wchar_t **" ptr ); +.fi +.SH DESCRIPTION +The \fBwcstok\fP function is the wide-character equivalent of the \fBstrtok\fP +function, with an added argument to make it multithread-safe. It can be used +to split a wide-character string \fIwcs\fP into tokens, where a token is +defined as a substring not containing any wide-characters from \fIdelim\fP. +.PP +The search starts at \fIwcs\fP, if \fIwcs\fP is not NULL, or at \fI*ptr\fP, if +\fIwcs\fP is NULL. First, any delimiter wide-characters are skipped, i.e. the +pointer is advanced beyond any wide-characters which occur in \fIdelim\fP. +If the end of the wide-character string is now reached, \fBwcstok\fP returns +NULL, to indicate that no tokens were found, and stores an appropriate value +in \fI*ptr\fP, so that subsequent calls to \fBwcstok\fP will continue to return +NULL. Otherwise, the \fBwcstok\fP function recognizes the beginning of a token +and returns a pointer to it, but before doing that, it zero-terminates the +token by replacing the next wide-character which occurs in \fIdelim\fP with +a L'\\0' character, and it updates \fI*ptr\fP so that subsequent calls will +continue searching after the end of recognized token. +.SH "RETURN VALUE" +The \fBwcstok\fP function returns a pointer to the next token, or NULL if no +further token was found. +.SH NOTES +The original \fIwcs\fP wide-character string is destructively modified during +the operation. +.SH EXAMPLE +The following code loops over the tokens contained in a wide-character string. +.sp +.nf +wchar_t *wcs = ...; +wchar_t *token; +wchar_t *state; +for (token = wcstok(wcs, " \\t\\n", &state); + token != NULL; + token = wcstok(NULL, " \\t\\n", &state)) { + ... +} +.fi +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR strtok (3), +.BR wcschr (3) diff --git a/man3/wcstombs.3 b/man3/wcstombs.3 new file mode 100644 index 000000000..17ce12ea2 --- /dev/null +++ b/man3/wcstombs.3 @@ -0,0 +1,64 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSTOMBS 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcstombs \- convert a wide character string to a multibyte string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "size_t wcstombs(char *" dest ", const wchar_t *" src ", size_t " n ); +.fi +.SH DESCRIPTION +If \fIdest\fP is not a NULL pointer, the \fBwcstombs\fP function converts +the wide-character string \fIsrc\fP to a multibyte string starting at +\fIdest\fP. At most \fIn\fP bytes are written to \fIdest\fP. The conversion +starts in the initial state. The conversion can stop for three reasons: +.PP +1. A wide character has been encountered that can not be represented as a +multibyte sequence (according to the current locale). In this case +(size_t)(-1) is returned. +.PP +2. The length limit forces a stop. In this case the number of bytes written to +\fIdest\fP is returned, but the shift state at this point is lost. +.PP +3. The wide-character string has been completely converted, including the +terminating L'\\0'. In this case the conversion ends in the initial state. +The number of bytes written to \fIdest\fP, excluding the terminating '\\0' +byte, is returned. +.PP +The programmer must ensure that there is room for at least \fIn\fP bytes +at \fIdest\fP. +.PP +If \fIdest\fP is NULL, \fIn\fP is ignored, and the conversion proceeds as +above, except that the converted bytes are not written out to memory, and that +no length limit exists. +.PP +In order to avoid the case 2 above, the programmer should make sure \fIn\fP +is greater or equal to \fIwcstombs(NULL,src,0)+1\fP. +.SH "RETURN VALUE" +The \fBwcstombs\fP function returns the number of bytes that make up the +converted part of multibyte sequence, not including the terminating null byte. +If a wide character was encountered which could not be converted, (size_t)(-1) +is returned. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR wcsrtombs (3) +.SH NOTES +The behaviour of \fBwcstombs\fP depends on the LC_CTYPE category of the +current locale. +.PP +The function \fBwcsrtombs\fP provides a thread safe interface to the same +functionality. diff --git a/man3/wcstoumax.3 b/man3/wcstoumax.3 new file mode 100644 index 000000000..f3aa5d2a0 --- /dev/null +++ b/man3/wcstoumax.3 @@ -0,0 +1 @@ +.so man3/wcstoimax.3 diff --git a/man3/wcswidth.3 b/man3/wcswidth.3 new file mode 100644 index 000000000..e02b4bf22 --- /dev/null +++ b/man3/wcswidth.3 @@ -0,0 +1,37 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.TH WCSWIDTH 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcswidth \- determine columns needed for a fixed-size wide character string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int wcswidth(const wchar_t *" s ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBwcswidth\fP function returns the number of columns needed to represent +the wide-character string pointed to by \fIs\fP, but at most \fIn\fP wide +characters. If a non-printable wide character occurs among these characters, +-1 is returned. +.SH "RETURN VALUE" +The \fBwcswidth\fP function returns the number of column positions for the +wide-character string \fIs\fP, truncated to at most length \fIn\fP. +.SH "CONFORMING TO" +UNIX98 +.SH "SEE ALSO" +.BR iswprint (3), +.BR wcwidth (3) +.SH NOTES +The behaviour of \fBwcswidth\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/wctob.3 b/man3/wctob.3 new file mode 100644 index 000000000..38be45c81 --- /dev/null +++ b/man3/wctob.3 @@ -0,0 +1,44 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCTOB 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wctob \- try to represent a wide character as a single byte +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int wctob(wint_t " c ); +.fi +.SH DESCRIPTION +The \fBwctob\fP function tests whether the multi-byte representation of the +wide character \fIc\fP, starting in the initial state, consists of a single +byte. If so, it is returned as an unsigned char. +.PP +Never use this function. It cannot help you in writing internationalized +programs. Internationalized programs must never distinguish single-byte and +multi-byte characters. +.SH "RETURN VALUE" +The \fBwctob\fP function returns the single-byte representation of \fIc\fP, +if it exists, of EOF otherwise. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR wctomb (3) +.SH NOTES +The behaviour of \fBwctob\fP depends on the LC_CTYPE category of the +current locale. +.PP +This function should never be used. Internationalized programs must never +distinguish single-byte and multi-byte characters. Use the function +\fBwctomb\fP instead. diff --git a/man3/wctomb.3 b/man3/wctomb.3 new file mode 100644 index 000000000..89b17f835 --- /dev/null +++ b/man3/wctomb.3 @@ -0,0 +1,59 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCTOMB 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wctomb \- convert a wide character to a multibyte sequence +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int wctomb(char *" s ", wchar_t " wc ); +.fi +.SH DESCRIPTION +If \fIs\fP is not NULL, the \fBwctomb\fP function converts the wide character +\fIwc\fP to its multibyte representation and stores it at the beginning of +the character array pointed to by \fIs\fP. It updates the shift state, which +is stored in a static anonymous variable only known to the wctomb function, +and returns the length of said multibyte representation, i.e. the number of +bytes written at \fIs\fP. +.PP +The programmer must ensure that there is room for at least \fBMB_CUR_MAX\fP +bytes at \fIs\fP. +.PP +If \fIs\fP is NULL, the \fBwctomb\fP function +.\" The Dinkumware doc and the Single Unix specification say this, but +.\" glibc doesn't implement this. +resets the shift state, only known to this function, to the initial state, and +returns non-zero if the encoding has non-trivial shift state, or zero if the +encoding is stateless. +.SH "RETURN VALUE" +If \fIs\fP is not NULL, the \fBwctomb\fP function returns the number of bytes +that have been written to the byte array at \fIs\fP. If \fIwc\fP can not be +represented as a multibyte sequence (according to the current locale), \-1 is +returned. +.PP +If \fIs\fP is NULL, the \fBwctomb\fP function returns non-zero if the +encoding has non-trivial shift state, or zero if the encoding is stateless. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR MB_CUR_MAX (3), +.BR wcrtomb (3), +.BR wcstombs (3) +.SH NOTES +The behaviour of \fBwctomb\fP depends on the LC_CTYPE category of the +current locale. +.PP +This function is not multi-thread safe. The function \fBwcrtomb\fP provides +a better interface to the same functionality. diff --git a/man3/wctrans.3 b/man3/wctrans.3 new file mode 100644 index 000000000..832ded37b --- /dev/null +++ b/man3/wctrans.3 @@ -0,0 +1,46 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCTRANS 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wctrans \- wide character translation mapping +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wctrans_t wctrans(const char *" name ); +.fi +.SH DESCRIPTION +The \fBwctrans_t\fP type represents a mapping which can map a wide character to +another wide character. Its nature is implementation dependent, but the special +value \fI(wctrans_t)0\fP denotes an invalid mapping. Nonzero \fBwctrans_t\fP +values can be passed to the \fBtowctrans\fP function to actually perform +the wide character mapping. +.PP +The \fBwctrans\fP function returns a mapping, given by its name. The set of +valid names depends on the LC_CTYPE category of the current locale, but the +following names are valid in all locales. +.nf + "tolower" - realizes the \fBtolower\fP(3) mapping + "toupper" - realizes the \fBtoupper\fP(3) mapping +.fi +.SH "RETURN VALUE" +The \fBwctrans\fP function returns a mapping descriptor if the \fIname\fP +is valid. Otherwise it returns \fI(wctrans_t)0\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR wctrans (3) +.SH NOTES +The behaviour of \fBwctrans\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/wctype.3 b/man3/wctype.3 new file mode 100644 index 000000000..c6fba8e92 --- /dev/null +++ b/man3/wctype.3 @@ -0,0 +1,57 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCTYPE 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wctype \- wide character classification +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wctype_t wctype(const char *" name ); +.fi +.SH DESCRIPTION +The \fBwctype_t\fP type represents a property which a wide character may or +may not have. In other words, it represents a class of wide characters. +This type's nature is implementation dependent, but the special value +\fI(wctype_t)0\fP denotes an invalid property. Nonzero \fBwctype_t\fP values +can be passed to the \fBiswctype\fP function to actually test whether a given +wide character has the property. +.PP +The \fBwctype\fP function returns a property, given by its name. The set of +valid names depends on the LC_CTYPE category of the current locale, but the +following names are valid in all locales. +.nf + "alnum" - realizes the \fBisalnum\fP classification function + "alpha" - realizes the \fBisalpha\fP classification function + "blank" - realizes the \fBisblank\fP classification function + "cntrl" - realizes the \fBiscntrl\fP classification function + "digit" - realizes the \fBisdigit\fP classification function + "graph" - realizes the \fBisgraph\fP classification function + "lower" - realizes the \fBislower\fP classification function + "print" - realizes the \fBisprint\fP classification function + "punct" - realizes the \fBispunct\fP classification function + "space" - realizes the \fBisspace\fP classification function + "upper" - realizes the \fBisupper\fP classification function + "xdigit" - realizes the \fBisxdigit\fP classification function +.fi +.SH "RETURN VALUE" +The \fBwctype\fP function returns a property descriptor if the \fIname\fP is +valid. Otherwise it returns \fI(wctype_t)0\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR iswctype (3) +.SH NOTES +The behaviour of \fBwctype\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/wcwidth.3 b/man3/wcwidth.3 new file mode 100644 index 000000000..5d31b95e8 --- /dev/null +++ b/man3/wcwidth.3 @@ -0,0 +1,40 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.TH WCWIDTH 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcwidth \- determine columns needed for a wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int wcwidth(wchar_t " c ); +.fi +.SH DESCRIPTION +The \fBwcwidth\fP function returns the number of columns needed to represent +the wide character \fIc\fP. If \fIc\fP is a printable wide character, the value +is at least 0. If \fIc\fP is L'\\0', the value is 0. Otherwise \-1 is returned. +.SH "RETURN VALUE" +The \fBwcwidth\fP function returns the number of column positions for \fIc\fP. +.SH "CONFORMING TO" +UNIX98, POSIX 1003.1-2001 +Note that glibc before 2.2.5 used the prototype +.br +.nf +.BI "int wcwidth(wint_t " c ); +.fi +.SH "SEE ALSO" +.BR iswprint (3), +.BR wcswidth (3) +.SH NOTES +The behaviour of \fBwcwidth\fP depends on the LC_CTYPE category of the +current locale. diff --git a/man3/wmemchr.3 b/man3/wmemchr.3 new file mode 100644 index 000000000..77732e306 --- /dev/null +++ b/man3/wmemchr.3 @@ -0,0 +1,35 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WMEMCHR 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wmemchr \- search a wide character in a wide-character array +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wchar_t *wmemchr(const wchar_t *" s ", wchar_t " c ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBwmemchr\fP function is the wide-character equivalent of the \fBmemchr\fP +function. It searches the \fIn\fP wide characters starting at \fIs\fP for +the first occurrence of the wide character \fIc\fP. +.SH "RETURN VALUE" +The \fBwmemchr\fP function returns a pointer to the first occurrence of \fIc\fP +among the \fIn\fP wide characters starting at \fIs\fP, or NULL if \fIc\fP does +not occur among these. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR memchr (3), +.BR wcschr (3) diff --git a/man3/wmemcmp.3 b/man3/wmemcmp.3 new file mode 100644 index 000000000..b0bf3ed84 --- /dev/null +++ b/man3/wmemcmp.3 @@ -0,0 +1,38 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" +.TH WMEMCMP 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wmemcmp \- compare two arrays of wide-characters +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int wmemcmp(const wchar_t *" s1 ", const wchar_t *" s2 ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBwmemcmp\fP function is the wide-character equivalent of the \fBmemcmp\fP +function. It compares the \fIn\fP wide-characters starting at \fIs1\fP and the +\fIn\fP wide-characters starting at \fIs2\fP. +.SH "RETURN VALUE" +The \fBwmemcmp\fP function returns zero if the wide-character arrays of size +\fIn\fP at \fIs1\fP and \fIs2\fP are equal. It returns an integer greater than +zero if at the first differing position \fIi\fP (\fIi\fP < \fIn\fP), the +corresponding wide-character \fIs1[i]\fP is greater than \fIs2[i]\fP. It +returns an integer less than zero if at the first differing position \fIi\fP +(\fIi\fP < \fIn\fP), the corresponding wide-character \fIs1[i]\fP is less than +\fIs2[i]\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR memcmp (3), +.BR wcscmp (3) diff --git a/man3/wmemcpy.3 b/man3/wmemcpy.3 new file mode 100644 index 000000000..4ec9859be --- /dev/null +++ b/man3/wmemcpy.3 @@ -0,0 +1,41 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WMEMCPY 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wmemcpy \- copy an array of wide-characters +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wchar_t *wmemcpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBwmemcpy\fP function is the wide-character equivalent of the \fBmemcpy\fP +function. It copies \fIn\fP wide characters from the array starting at +\fIsrc\fP to the array starting at \fIdest\fP. +.PP +The arrays may not overlap; use \fBwmemmove\fP(3) to copy between overlapping +arrays. +.PP +The programmer must ensure that there is room for at least \fIn\fP wide +characters at \fIdest\fP. +.SH "RETURN VALUE" +\fBwmemcpy\fP returns \fIdest\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR memcpy (3), +.BR wcscpy (3), +.BR wmemmove (3), +.BR wmempcpy (3) diff --git a/man3/wmemmove.3 b/man3/wmemmove.3 new file mode 100644 index 000000000..c19fc5ed9 --- /dev/null +++ b/man3/wmemmove.3 @@ -0,0 +1,37 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WMEMMOVE 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wmemmove \- copy an array of wide-characters +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wchar_t *wmemmove(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBwmemmove\fP function is the wide-character equivalent of the +\fBmemmove\fP function. It copies \fIn\fP wide characters from the array +starting at \fIsrc\fP to the array starting at \fIdest\fP. The arrays may +overlap. +.PP +The programmer must ensure that there is room for at least \fIn\fP wide +characters at \fIdest\fP. +.SH "RETURN VALUE" +\fBwmemmove\fP returns \fIdest\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR memmove (3), +.BR wmemcpy (3) diff --git a/man3/wmempcpy.3 b/man3/wmempcpy.3 new file mode 100644 index 000000000..26750cb64 --- /dev/null +++ b/man3/wmempcpy.3 @@ -0,0 +1 @@ +.so man3/mempcpy.3 diff --git a/man3/wmemset.3 b/man3/wmemset.3 new file mode 100644 index 000000000..f6d55f929 --- /dev/null +++ b/man3/wmemset.3 @@ -0,0 +1,32 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WMEMSET 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wmemset \- fill an array of wide-characters with a constant wide character +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "wchar_t *wmemset(wchar_t *" wcs ", wchar_t " wc ", size_t " n ); +.fi +.SH DESCRIPTION +The \fBwmemset\fP function is the wide-character equivalent of the \fBmemset\fP +function. It fills the array of \fIn\fP wide-characters starting at \fIwcs\fP +with \fIn\fP copies of the wide character \fIwc\fP. +.SH "RETURN VALUE" +\fBwmemset\fP returns \fIwcs\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR memset (3) diff --git a/man3/wordexp.3 b/man3/wordexp.3 new file mode 100644 index 000000000..880539721 --- /dev/null +++ b/man3/wordexp.3 @@ -0,0 +1,198 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH WORDEXP 3 2003-11-11 "" "Linux Programmer's Manual" +.SH NAME +wordexp, wordfree \- perform word expansion like a posix-shell +.SH SYNOPSIS +.sp +.B "#include " +.sp +.BI "int wordexp(const char *" s ", wordexp_t *" p ", int " flags ); +.sp +.BI "void wordfree(wordexp_t *" p ); +.sp +.SH DESCRIPTION +The function +.B wordexp() +performs a shell-like expansion of the string +.I s +and returns the result in the structure pointed to by +.IR p . +The data type +.B wordexp_t +is a structure that at least has the fields +.IR we_wordc , +.IR we_wordv , +and +.IR we_offs . +The field +.I we_wordc +is a +.B size_t +that gives the number of words in the expansion of +.IR s . +The field +.I we_wordv +is a +.B char ** +that points to the array of words found. +The field +.I we_offs +of type +.B size_t +is sometimes (depending on +.IR flags , +see below) used to indicate the number of initial elements in the +.I we_wordv +array that should be filled with NULLs. +.LP +The function +.B wordfree() +frees the allocated memory again. More precisely, it does not free +its argument, but it frees the array +.I we_wordv +and the strings that points to. + +.SH EXAMPLE +First a small example. The output is approximately that of "ls [a-c]*.c". +.LP +.nf +#include +#include + +int main(int argc, char **argv) { + wordexp_t p; + char **w; + int i; + + wordexp("[a-c]*.c", &p, 0); + w = p.we_wordv; + for (i=0; i, (, ), {, } characters +outside a command substitution or parameter substitution context. +.LP +If the argument +.I s +contains a word that starts with an unquoted comment character #, +then it is unspecified whether that word and all following words +are ignored, or the # is treated as a non-comment character. + +.SS "The expansion" +The expansion done consists of the following stages: +tilde expansion (replacing ~user by user's home directory), +variable substitution (replacing $FOO by the value of the environment +variable FOO), command substitution (replacing $(command) or `command` +by the output of command), arithmetic expansion, field splitting, +wildcard expansion, quote removal. +.LP +The result of expansion of special parameters +($@, $*, $#, $?, $-, $$, $!, $0) is unspecified. +.LP +Field splitting is done using the environment variable $IFS. +If it is not set, the field separators are space, tab and newline. + +.SS "The output array" +The array +.I we_wordv +contains the words found, followed by a NULL. + +.SS "The flags argument" +The +.I flag +argument is a bitwise inclusive OR of the following values: +.TP +.B WRDE_APPEND +Append the words found to the array resulting from a previous call. +.TP +.B WRDE_DOOFFS +Insert +.I we_offs +initial NULLs in the array +.IR we_wordv . +(These are not counted in the returned +.IR we_wordc .) +.TP +.B WRDE_NOCMD +Don't do command substitution. +.TP +.B WRDE_REUSE +The parameter +.I p +resulted from a previous call to +.BR wordexp() , +and +.BR wordfree() +was not called. Reuse the allocated storage. +.TP +.B WRDE_SHOWERR +Normally during command substitution +.I stderr +is redirected to +.IR /dev/null . +This flag specifies that +.I stderr +is not to be redirected. +.TP +.B WRDE_UNDEF +Consider it an error if an undefined shell variable is expanded. +.SH "RETURN VALUE" +In case of success 0 is returned. In case of error +one of the following five values is returned. +.TP +.B WRDE_BADCHAR +Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }. +.TP +.B WRDE_BADVAL +An undefined shell variable was referenced, and the WRDE_UNDEF flag +told us to consider this an error. +.TP +.B WRDE_CMDSUB +Command substitution occurred, and the WRDE_NOCMD flag +told us to consider this an error. +.TP +.B WRDE_NOSPACE +Out of memory. +.TP +.B WRDE_SYNTAX +Shell syntax error, such as unbalanced parentheses or +unmatched quotes. + +.SH "CONFORMING TO" +XPG4, POSIX 1003.1-2003 + +.SH "SEE ALSO" +.BR fnmatch (3), +.BR glob (3) diff --git a/man3/wordfree.3 b/man3/wordfree.3 new file mode 100644 index 000000000..f0035e0ba --- /dev/null +++ b/man3/wordfree.3 @@ -0,0 +1 @@ +.so man3/wordexp.3 diff --git a/man3/wprintf.3 b/man3/wprintf.3 new file mode 100644 index 000000000..c98a912dd --- /dev/null +++ b/man3/wprintf.3 @@ -0,0 +1,149 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WPRINTF 3 1999-11-20 "GNU" "Linux Programmer's Manual" +.SH NAME +wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted wide character output conversion +.SH SYNOPSIS +.nf +.B #include +.B #include +.sp +.BI "int wprintf(const wchar_t *" format ", ...);" +.BI "int fwprintf(FILE *" stream ", const wchar_t *" format ", ...);" +.BI "int swprintf(wchar_t *" wcs ", size_t " maxlen , +.BI " const wchar_t *" format ", ...);" +.sp +.B #include +.sp +.BI "int vwprintf(const wchar_t *" format ", va_list " args ); +.BI "int vfwprintf(FILE *" stream ", const wchar_t *" format ", va_list " args ); +.BI "int vswprintf(wchar_t *" wcs ", size_t " maxlen , +.BI " const wchar_t *" format ", va_list " args ); +.fi +.SH DESCRIPTION +The \fBwprintf\fP family of functions is the wide-character equivalent of the +\fBprintf\fP family of functions. It performs formatted output of wide +characters. +.PP +The \fBwprintf\fP and \fBvwprintf\fP functions perform wide character output +to \fBstdout\fP. \fBstdout\fP must not be byte oriented; see function +\fBfwide\fP for more information. +.PP +The \fBfwprintf\fP and \fBvfwprintf\fP functions perform wide character output +to \fIstream\fP. \fIstream\fP must not be byte oriented; see function +\fBfwide\fP for more information. +.PP +The \fBswprintf\fP and \fBvswprintf\fP functions perform wide character output +to an array of wide characters. +The programmer must ensure that there is room for at least \fImaxlen\fP wide +characters at \fIwcs\fP. +.PP +These functions are like the \fBprintf\fP, \fBvprintf\fP, \fBfprintf\fP, +\fBvfprintf\fP, \fBsprintf\fP, \fBvsprintf\fP functions except for the +following differences: +.TP +.B \(bu +The \fIformat\fP string is a wide character string. +.TP +.B \(bu +The output consists of wide characters, not bytes. +.TP +.B \(bu +\fBswprintf\fP and \fBvswprintf\fP take a \fImaxlen\fP argument, +\fBsprintf\fP and \fBvsprintf\fP do not. (\fBsnprintf\fP and \fBvsnprintf\fP +take a \fImaxlen\fP argument, but these functions do not return \-1 upon +buffer overflow on Linux.) +.PP +The treatment of the conversion characters \fBc\fP and \fBs\fP is different: +.TP +.B c +If no +.B l +modifier is present, the +.I int +argument is converted to a wide character by a call to the +.B btowc +function, and the resulting wide character is written. +If an +.B l +modifier is present, the +.I wint_t +(wide character) argument is written. +.TP +.B s +If no +.B l +modifier is present: The +.IR "" `` "const char *" '' +argument is expected to be a pointer to an array of character type +(pointer to a string) containing a multibyte character sequence beginning +in the initial shift state. Characters from the array are converted to +wide characters (each by a call to the +.B mbrtowc +function with a conversion state starting in the initial state before +the first byte). The resulting wide characters are written up to +(but not including) the terminating null wide character. If a precision is +specified, no more wide characters than the number specified are written. +Note that the precision determines the number of +.I wide characters +written, not the number of +.I bytes +or +.IR "screen positions" . +The array must contain a terminating null byte, unless a precision is given +and it is so small that the number of converted wide characters reaches it +before the end of the array is reached. -- If an +.B l +modifier is present: The +.IR "" `` "const wchar_t *" '' +argument is expected to be a pointer to an array of wide characters. +Wide characters from the array are written up to (but not including) a +terminating null wide character. If a precision is specified, no more than +the number specified are written. The array must contain a terminating null +wide character, unless a precision is given and it is smaller than or equal +to the number of wide characters in the array. +.SH "RETURN VALUE" +The functions return the number of wide characters written, excluding the +terminating null wide character in case of the functions \fBswprintf\fP and +\fBvswprintf\fP. They return \-1 when an error occurs. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR fprintf (3), +.BR fputwc (3), +.BR fwide (3), +.BR printf (3), +.BR snprintf (3), +.BR wscanf (3) +.SH NOTES +The behaviour of \fBwprintf\fP et al. depends on the LC_CTYPE category of the +current locale. +.PP +If the \fIformat\fP string contains non-ASCII wide characters, the program +will only work correctly if the LC_CTYPE category of the current locale at +run time is the same as the LC_CTYPE category of the current locale at +compile time. This is because the +.B wchar_t +representation is platform and locale dependent. (The GNU libc represents +wide characters using their Unicode (ISO-10646) code point, but other +platforms don't do this. Also, the use of ISO C99 universal character names +of the form \\unnnn does not solve this problem.) Therefore, in +internationalized programs, the \fIformat\fP string should consist of ASCII +wide characters only, or should be constructed at run time in an +internationalized way (e.g. using +.B gettext +or +.BR iconv , +followed by +.BR mbstowcs ). diff --git a/man3/xcrypt.3 b/man3/xcrypt.3 new file mode 100644 index 000000000..ae0efada1 --- /dev/null +++ b/man3/xcrypt.3 @@ -0,0 +1,69 @@ +.\" Copyright 2003 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" this is the 3rd type of interface for cryptographic routines +.\" 1. encrypt() expects a bitfield +.\" 2. cbc_crypt() byte values +.\" 3. xencrypt() a hexstring +.\" to bad to be true :( +.\" +.TH xcrypt 3 2003-04-04 "" "RPC cryptography" +.SH NAME +xencrypt, xdecrypt, passwd2des \- RFS password encryption +.SH SYNOPSIS +.sp +.B "#include " +.sp +.BR "void passwd2des (char " *passwd ", char *" key ");" +.sp +.BR "int xencrypt (char " *secret ", char *" passwd ");" +.sp +.BR "int xdecrypt (char " *secret ", char *" passwd ");" +.sp +.SH DESCRIPTION +The function +.B passwd2des() +takes a character string +.I passwd +of arbitrary length and fills a character array +.I key +of length 8. The array +.I key +is suitable for use as DES key. It has odd parity set in bit 0 of each byte. +Both other functions described here use this function to turn their +argument +.I passwd +into a DES key. +.LP +The +.B xencrypt() +function takes the ASCII character string +.I secret +given in hex, +.\" (over the alphabet 0123456789abcdefABCDEF), +which must have a length that is a multiple of 16, +encrypts it using the DES key derived from +.I passwd +by +.BR passwd2des() , +and outputs the result again in +.I secret +as a hex string +.\" (over the alphabet 0123456789abcdef) +of the same length. +.LP +The +.B xdecrypt() +function performs the converse operation. +.SH "RETURN VALUE" +The functions +.B xencrypt() +and +.B xdecrypt() +return 1 on success and 0 on error. +.SH AVAILABILITY +These routines are present in libc 4.6.27 and later, and in +glibc 2.1 and later. +.SH BUGS +The prototypes are missing from the abovementioned include file. +.SH "SEE ALSO" +.BR cbc_crypt (3) diff --git a/man3/xdecrypt.3 b/man3/xdecrypt.3 new file mode 100644 index 000000000..01b6ce65a --- /dev/null +++ b/man3/xdecrypt.3 @@ -0,0 +1 @@ +.so man3/xcrypt.3 diff --git a/man3/xdr.3 b/man3/xdr.3 new file mode 100644 index 000000000..77ca1865f --- /dev/null +++ b/man3/xdr.3 @@ -0,0 +1,822 @@ +.\" @(#)xdr.3n 2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI +.TH XDR 3 1988-02-16 +.SH NAME +xdr \- library routines for external data representation +.SH "SYNOPSIS AND DESCRIPTION" +.LP +These routines allow C programmers to describe +arbitrary data structures in a machine-independent fashion. +Data for remote procedure calls are transmitted using these +routines. +.LP +.ft B +.nf +.sp .5 +xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc) +\s-1XDR\s0 *xdrs; +char **arrp; +u_int *sizep, maxsize, elsize; +xdrproc_t elproc; +.fi +.ft R +.IP +A filter primitive that translates between variable-length +arrays +and their corresponding external representations. The +parameter +.I arrp +is the address of the pointer to the array, while +.I sizep +is the address of the element count of the array; +this element count cannot exceed +.IR maxsize . +The parameter +.I elsize +is the +.I sizeof +each of the array's elements, and +.I elproc +is an +.SM XDR +filter that translates between +the array elements' C form, and their external +representation. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +xdr_bool(xdrs, bp) +\s-1XDR\s0 *xdrs; +bool_t *bp; +.fi +.ft R +.IP +A filter primitive that translates between booleans (C +integers) +and their external representations. When encoding data, this +filter produces values of either one or zero. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 10 +.LP +.ft B +.nf +.sp .5 +xdr_bytes(xdrs, sp, sizep, maxsize) +\s-1XDR\s0 *xdrs; +char **sp; +u_int *sizep, maxsize; +.fi +.ft R +.IP +A filter primitive that translates between counted byte +strings and their external representations. +The parameter +.I sp +is the address of the string pointer. The length of the +string is located at address +.IR sizep ; +strings cannot be longer than +.IR maxsize . +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +xdr_char(xdrs, cp) +\s-1XDR\s0 *xdrs; +char *cp; +.fi +.ft R +.IP +A filter primitive that translates between C characters +and their external representations. +This routine returns one if it succeeds, zero otherwise. +Note: encoded characters are not packed, and occupy 4 bytes +each. For arrays of characters, it is worthwhile to +consider +.BR xdr_bytes() , +.B xdr_opaque() +or +.BR xdr_string() . +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +void +xdr_destroy(xdrs) +\s-1XDR\s0 *xdrs; +.fi +.ft R +.IP +A macro that invokes the destroy routine associated with the +.SM XDR +stream, +.IR xdrs . +Destruction usually involves freeing private data structures +associated with the stream. Using +.I xdrs +after invoking +.B xdr_destroy() +is undefined. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +xdr_double(xdrs, dp) +\s-1XDR\s0 *xdrs; +double *dp; +.fi +.ft R +.IP +A filter primitive that translates between C +.B double +precision numbers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +xdr_enum(xdrs, ep) +\s-1XDR\s0 *xdrs; +enum_t *ep; +.fi +.ft R +.IP +A filter primitive that translates between C +.BR enum s +(actually integers) and their external representations. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +xdr_float(xdrs, fp) +\s-1XDR\s0 *xdrs; +float *fp; +.fi +.ft R +.IP +A filter primitive that translates between C +.BR float s +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 9 +.LP +.ft B +.nf +.sp .5 +void +xdr_free(proc, objp) +xdrproc_t proc; +char *objp; +.fi +.ft R +.IP +Generic freeing routine. The first argument is the +.SM XDR +routine for the object being freed. The second argument +is a pointer to the object itself. Note: the pointer passed +to this routine is +.I not +freed, but what it points to +.I is +freed (recursively). +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +u_int +xdr_getpos(xdrs) +\s-1XDR\s0 *xdrs; +.fi +.ft R +.IP +A macro that invokes the get-position routine +associated with the +.SM XDR +stream, +.IR xdrs . +The routine returns an unsigned integer, +which indicates the position of the +.SM XDR +byte stream. +A desirable feature of +.SM XDR +streams is that simple arithmetic works with this number, +although the +.SM XDR +stream instances need not guarantee this. +.br +.if t .ne 4 +.LP +.ft B +.nf +.sp .5 +.br +long * +xdr_inline(xdrs, len) +\s-1XDR\s0 *xdrs; +int len; +.fi +.ft R +.IP +A macro that invokes the in-line routine associated with the +.SM XDR +stream, +.IR xdrs . +The routine returns a pointer +to a contiguous piece of the stream's buffer; +.I len +is the byte length of the desired buffer. +Note: pointer is cast to +.BR "long *" . +.IP +Warning: +.B xdr_inline() +may return +.SM NULL +(0) +if it cannot allocate a contiguous piece of a buffer. +Therefore the behavior may vary among stream instances; +it exists for the sake of efficiency. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +xdr_int(xdrs, ip) +\s-1XDR\s0 *xdrs; +int *ip; +.fi +.ft R +.IP +A filter primitive that translates between C integers +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +xdr_long(xdrs, lp) +\s-1XDR\s0 *xdrs; +long *lp; +.fi +.ft R +.IP +A filter primitive that translates between C +.B long +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 12 +.LP +.ft B +.nf +.sp .5 +void +xdrmem_create(xdrs, addr, size, op) +\s-1XDR\s0 *xdrs; +char *addr; +u_int size; +enum xdr_op op; +.fi +.ft R +.IP +This routine initializes the +.SM XDR +stream object pointed to by +.IR xdrs . +The stream's data is written to, or read from, +a chunk of memory at location +.I addr +whose length is no more than +.I size +bytes long. The +.I op +determines the direction of the +.SM XDR +stream +(either +.BR \s-1XDR_ENCODE\s0 , +.BR \s-1XDR_DECODE\s0 , +or +.BR \s-1XDR_FREE\s0 ). +.br +.if t .ne 10 +.LP +.ft B +.nf +.sp .5 +xdr_opaque(xdrs, cp, cnt) +\s-1XDR\s0 *xdrs; +char *cp; +u_int cnt; +.fi +.ft R +.IP +A filter primitive that translates between fixed size opaque data +and its external representation. +The parameter +.I cp +is the address of the opaque object, and +.I cnt +is its size in bytes. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 10 +.LP +.ft B +.nf +.sp .5 +xdr_pointer(xdrs, objpp, objsize, xdrobj) +\s-1XDR\s0 *xdrs; +char **objpp; +u_int objsize; +xdrproc_t xdrobj; +.fi +.ft R +.IP +Like +.B xdr_reference() +except that it serializes +.SM NULL +pointers, whereas +.B xdr_reference() +does not. Thus, +.B xdr_pointer() +can represent +recursive data structures, such as binary trees or +linked lists. +.br +.if t .ne 15 +.LP +.ft B +.nf +.sp .5 +void +xdrrec_create(xdrs, sendsize, recvsize, handle, readit, writeit) +\s-1XDR\s0 *xdrs; +u_int sendsize, recvsize; +char *handle; +int (*readit) (), (*writeit) (); +.fi +.ft R +.IP +This routine initializes the +.SM XDR +stream object pointed to by +.IR xdrs . +The stream's data is written to a buffer of size +.IR sendsize ; +a value of zero indicates the system should use a suitable +default. The stream's data is read from a buffer of size +.IR recvsize ; +it too can be set to a suitable default by passing a zero +value. +When a stream's output buffer is full, +.I writeit +is called. Similarly, when a stream's input buffer is empty, +.I readit +is called. The behavior of these two routines is similar to +the +system calls +.B read +and +.BR write , +except that +.I handle +is passed to the former routines as the first parameter. +Note: the +.SM XDR +stream's +.I op +field must be set by the caller. +.IP +Warning: this +.SM XDR +stream implements an intermediate record stream. +Therefore there are additional bytes in the stream +to provide record boundary information. +.br +.if t .ne 9 +.LP +.ft B +.nf +.sp .5 +xdrrec_endofrecord(xdrs, sendnow) +\s-1XDR\s0 *xdrs; +int sendnow; +.fi +.ft R +.IP +This routine can be invoked only on +streams created by +.BR xdrrec_create() . +The data in the output buffer is marked as a completed +record, +and the output buffer is optionally written out if +.I sendnow +is non-zero. This routine returns one if it succeeds, zero +otherwise. +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +xdrrec_eof(xdrs) +\s-1XDR\s0 *xdrs; +int empty; +.fi +.ft R +.IP +This routine can be invoked only on +streams created by +.BR xdrrec_create() . +After consuming the rest of the current record in the stream, +this routine returns one if the stream has no more input, +zero otherwise. +.br +.if t .ne 3 +.LP +.ft B +.nf +.sp .5 +xdrrec_skiprecord(xdrs) +\s-1XDR\s0 *xdrs; +.fi +.ft R +.IP +This routine can be invoked only on +streams created by +.BR xdrrec_create() . +It tells the +.SM XDR +implementation that the rest of the current record +in the stream's input buffer should be discarded. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 11 +.LP +.ft B +.nf +.sp .5 +xdr_reference(xdrs, pp, size, proc) +\s-1XDR\s0 *xdrs; +char **pp; +u_int size; +xdrproc_t proc; +.fi +.ft R +.IP +A primitive that provides pointer chasing within structures. +The parameter +.I pp +is the address of the pointer; +.I size +is the +.I sizeof +the structure that +.I *pp +points to; and +.I proc +is an +.SM XDR +procedure that filters the structure +between its C form and its external representation. +This routine returns one if it succeeds, zero otherwise. +.IP +Warning: this routine does not understand +.SM NULL +pointers. Use +.B xdr_pointer() +instead. +.br +.if t .ne 10 +.LP +.ft B +.nf +.sp .5 +xdr_setpos(xdrs, pos) +\s-1XDR\s0 *xdrs; +u_int pos; +.fi +.ft R +.IP +A macro that invokes the set position routine associated with +the +.SM XDR +stream +.IR xdrs . +The parameter +.I pos +is a position value obtained from +.BR xdr_getpos() . +This routine returns one if the +.SM XDR +stream could be repositioned, +and zero otherwise. +.IP +Warning: it is difficult to reposition some types of +.SM XDR +streams, so this routine may fail with one +type of stream and succeed with another. +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +xdr_short(xdrs, sp) +\s-1XDR\s0 *xdrs; +short *sp; +.fi +.ft R +.IP +A filter primitive that translates between C +.B short +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 10 +.LP +.ft B +.nf +.sp .5 +void +xdrstdio_create(xdrs, file, op) +\s-1XDR\s0 *xdrs; +\s-1FILE\s0 *file; +enum xdr_op op; +.fi +.ft R +.IP +This routine initializes the +.SM XDR +stream object pointed to by +.IR xdrs . +The +.SM XDR +stream data is written to, or read from, the Standard +.B I/O +stream +.IR file . +The parameter +.I op +determines the direction of the +.SM XDR +stream (either +.BR \s-1XDR_ENCODE\s0 , +.BR \s-1XDR_DECODE\s0 , +or +.BR \s-1XDR_FREE\s0 ). +.IP +Warning: the destroy routine associated with such +.SM XDR +streams calls +.B fflush() +on the +.I file +stream, but never +.BR fclose() . +.br +.if t .ne 9 +.LP +.ft B +.nf +.sp .5 +xdr_string(xdrs, sp, maxsize) +\s-1XDR\s0 +*xdrs; +char **sp; +u_int maxsize; +.fi +.ft R +.IP +A filter primitive that translates between C strings and +their +corresponding external representations. +Strings cannot be longer than +.IR maxsize . +Note: +.I sp +is the address of the string's pointer. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 8 +.LP +.ft B +.nf +.sp .5 +xdr_u_char(xdrs, ucp) +\s-1XDR\s0 *xdrs; +unsigned char *ucp; +.fi +.ft R +.IP +A filter primitive that translates between +.B unsigned +C characters and their external representations. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 9 +.LP +.ft B +.nf +.sp .5 +xdr_u_int(xdrs, up) +\s-1XDR\s0 *xdrs; +unsigned *up; +.fi +.ft R +.IP +A filter primitive that translates between C +.B unsigned +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +xdr_u_long(xdrs, ulp) +\s-1XDR\s0 *xdrs; +unsigned long *ulp; +.fi +.ft R +.IP +A filter primitive that translates between C +.B "unsigned long" +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 7 +.LP +.ft B +.nf +.sp .5 +xdr_u_short(xdrs, usp) +\s-1XDR\s0 *xdrs; +unsigned short *usp; +.fi +.ft R +.IP +A filter primitive that translates between C +.B "unsigned short" +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 16 +.LP +.ft B +.nf +.sp .5 +xdr_union(xdrs, dscmp, unp, choices, dfault) +\s-1XDR\s0 *xdrs; +int *dscmp; +char *unp; +struct xdr_discrim *choices; +bool_t (*defaultarm) (); /* may equal \s-1NULL\s0 */ +.fi +.ft R +.IP +A filter primitive that translates between a discriminated C +.B union +and its corresponding external representation. It first +translates the discriminant of the union located at +.IR dscmp . +This discriminant is always an +.BR enum_t . +Next the union located at +.I unp +is translated. The parameter +.I choices +is a pointer to an array of +.B xdr_discrim() +structures. Each structure contains an ordered pair of +.RI [ value , proc ]. +If the union's discriminant is equal to the associated +.IR value , +then the +.I proc +is called to translate the union. The end of the +.B xdr_discrim() +structure array is denoted by a routine of value +.SM NULL\s0. +If the discriminant is not found in the +.I choices +array, then the +.I defaultarm +procedure is called (if it is not +.SM NULL\s0). +Returns one if it succeeds, zero otherwise. +.br +.if t .ne 6 +.LP +.ft B +.nf +.sp .5 +xdr_vector(xdrs, arrp, size, elsize, elproc) +\s-1XDR\s0 *xdrs; +char *arrp; +u_int size, elsize; +xdrproc_t elproc; +.fi +.ft R +.IP +A filter primitive that translates between fixed-length +arrays +and their corresponding external representations. The +parameter +.I arrp +is the address of the pointer to the array, while +.I size +is is the element count of the array. The parameter +.I elsize +is the +.I sizeof +each of the array's elements, and +.I elproc +is an +.SM XDR +filter that translates between +the array elements' C form, and their external +representation. +This routine returns one if it succeeds, zero otherwise. +.br +.if t .ne 5 +.LP +.ft B +.nf +.sp .5 +xdr_void() +.fi +.ft R +.IP +This routine always returns one. +It may be passed to +.SM RPC +routines that require a function parameter, +where nothing is to be done. +.br +.if t .ne 10 +.LP +.ft B +.nf +.sp .5 +xdr_wrapstring(xdrs, sp) +\s-1XDR\s0 *xdrs; +char **sp; +.fi +.ft R +.IP +A primitive that calls +.B "xdr_string(xdrs, sp,\s-1MAXUN.UNSIGNED\s0 );" +where +.B +.SM MAXUN.UNSIGNED +is the maximum value of an unsigned integer. +.B xdr_wrapstring() +is handy because the +.SM RPC +package passes a maximum of two +.SM XDR +routines as parameters, and +.BR xdr_string() , +one of the most frequently used primitives, requires three. +Returns one if it succeeds, zero otherwise. +.SH "SEE ALSO" +.BR rpc (3) +.LP +The following manuals: +.RS +.ft I +eXternal Data Representation Standard: Protocol Specification +.br +eXternal Data Representation: Sun Technical Notes +.ft R +.br +.IR "\s-1XDR\s0: External Data Representation Standard" , +.SM RFC1014, Sun Microsystems, Inc., +.SM USC-ISI\s0. diff --git a/man3/xdr_accepted_reply.3 b/man3/xdr_accepted_reply.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/xdr_accepted_reply.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_array.3 b/man3/xdr_array.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_array.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_authunix_parms.3 b/man3/xdr_authunix_parms.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/xdr_authunix_parms.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_bool.3 b/man3/xdr_bool.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_bool.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_bytes.3 b/man3/xdr_bytes.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_bytes.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_callhdr.3 b/man3/xdr_callhdr.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/xdr_callhdr.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_callmsg.3 b/man3/xdr_callmsg.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/xdr_callmsg.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_char.3 b/man3/xdr_char.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_char.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_destroy.3 b/man3/xdr_destroy.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_destroy.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_double.3 b/man3/xdr_double.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_double.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_enum.3 b/man3/xdr_enum.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_enum.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_float.3 b/man3/xdr_float.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_float.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_free.3 b/man3/xdr_free.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_free.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_getpos.3 b/man3/xdr_getpos.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_getpos.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_inline.3 b/man3/xdr_inline.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_inline.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_int.3 b/man3/xdr_int.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_int.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_long.3 b/man3/xdr_long.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_long.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_opaque.3 b/man3/xdr_opaque.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_opaque.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_opaque_auth.3 b/man3/xdr_opaque_auth.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/xdr_opaque_auth.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_pmap.3 b/man3/xdr_pmap.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/xdr_pmap.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_pmaplist.3 b/man3/xdr_pmaplist.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/xdr_pmaplist.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_pointer.3 b/man3/xdr_pointer.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_pointer.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_reference.3 b/man3/xdr_reference.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_reference.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_rejected_reply.3 b/man3/xdr_rejected_reply.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/xdr_rejected_reply.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_replymsg.3 b/man3/xdr_replymsg.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/xdr_replymsg.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_setpos.3 b/man3/xdr_setpos.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_setpos.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_short.3 b/man3/xdr_short.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_short.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_string.3 b/man3/xdr_string.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_string.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_u_char.3 b/man3/xdr_u_char.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_u_char.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_u_int.3 b/man3/xdr_u_int.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_u_int.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_u_long.3 b/man3/xdr_u_long.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_u_long.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_u_short.3 b/man3/xdr_u_short.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_u_short.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_union.3 b/man3/xdr_union.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_union.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_vector.3 b/man3/xdr_vector.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_vector.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_void.3 b/man3/xdr_void.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_void.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_wrapstring.3 b/man3/xdr_wrapstring.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdr_wrapstring.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdrmem_create.3 b/man3/xdrmem_create.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdrmem_create.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdrrec_create.3 b/man3/xdrrec_create.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdrrec_create.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdrrec_endofrecord.3 b/man3/xdrrec_endofrecord.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdrrec_endofrecord.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdrrec_eof.3 b/man3/xdrrec_eof.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdrrec_eof.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdrrec_skiprecord.3 b/man3/xdrrec_skiprecord.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdrrec_skiprecord.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdrstdio_create.3 b/man3/xdrstdio_create.3 new file mode 100644 index 000000000..7ff092d05 --- /dev/null +++ b/man3/xdrstdio_create.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xencrypt.3 b/man3/xencrypt.3 new file mode 100644 index 000000000..01b6ce65a --- /dev/null +++ b/man3/xencrypt.3 @@ -0,0 +1 @@ +.so man3/xcrypt.3 diff --git a/man3/xprt_register.3 b/man3/xprt_register.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/xprt_register.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xprt_unregister.3 b/man3/xprt_unregister.3 new file mode 100644 index 000000000..b18471167 --- /dev/null +++ b/man3/xprt_unregister.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/y0.3 b/man3/y0.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/y0.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/y0f.3 b/man3/y0f.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/y0f.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/y0l.3 b/man3/y0l.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/y0l.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/y1.3 b/man3/y1.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/y1.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/y1f.3 b/man3/y1f.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/y1f.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/y1l.3 b/man3/y1l.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/y1l.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/yn.3 b/man3/yn.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/yn.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/ynf.3 b/man3/ynf.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/ynf.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/ynl.3 b/man3/ynl.3 new file mode 100644 index 000000000..6dc181883 --- /dev/null +++ b/man3/ynl.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3p/FD_CLR.3p b/man3p/FD_CLR.3p new file mode 100644 index 000000000..24347e495 --- /dev/null +++ b/man3p/FD_CLR.3p @@ -0,0 +1 @@ +.so man3p/select.3p diff --git a/man3p/FD_ISSET.3p b/man3p/FD_ISSET.3p new file mode 100644 index 000000000..24347e495 --- /dev/null +++ b/man3p/FD_ISSET.3p @@ -0,0 +1 @@ +.so man3p/select.3p diff --git a/man3p/FD_SET.3p b/man3p/FD_SET.3p new file mode 100644 index 000000000..24347e495 --- /dev/null +++ b/man3p/FD_SET.3p @@ -0,0 +1 @@ +.so man3p/select.3p diff --git a/man3p/FD_ZERO.3p b/man3p/FD_ZERO.3p new file mode 100644 index 000000000..24347e495 --- /dev/null +++ b/man3p/FD_ZERO.3p @@ -0,0 +1 @@ +.so man3p/select.3p diff --git a/man3p/_Exit.3p b/man3p/_Exit.3p new file mode 100644 index 000000000..1e29b70dc --- /dev/null +++ b/man3p/_Exit.3p @@ -0,0 +1 @@ +.so man3p/exit.3p diff --git a/man3p/_exit.3p b/man3p/_exit.3p new file mode 100644 index 000000000..1e29b70dc --- /dev/null +++ b/man3p/_exit.3p @@ -0,0 +1 @@ +.so man3p/exit.3p diff --git a/man3p/_longjmp.3p b/man3p/_longjmp.3p new file mode 100644 index 000000000..bf3b21e56 --- /dev/null +++ b/man3p/_longjmp.3p @@ -0,0 +1 @@ +.so man3p/_setjmp.3p diff --git a/man3p/_setjmp.3p b/man3p/_setjmp.3p new file mode 100644 index 000000000..8ddc0c897 --- /dev/null +++ b/man3p/_setjmp.3p @@ -0,0 +1,84 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "_LONGJMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" _longjmp +.SH NAME +_longjmp, _setjmp \- non-local goto +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void _longjmp(jmp_buf\fP \fIenv\fP\fB, int\fP \fIval\fP\fB); +.br +int _setjmp(jmp_buf\fP \fIenv\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fI_longjmp\fP() and \fI_setjmp\fP() functions shall be equivalent +to \fIlongjmp\fP() and \fIsetjmp\fP(), respectively, with the +additional restriction that \fI_longjmp\fP() and \fI_setjmp\fP() shall +not manipulate the signal mask. +.LP +If \fI_longjmp\fP() is called even though \fIenv\fP was never initialized +by a call to \fI_setjmp\fP(), or when the last such +call was in a function that has since returned, the results are undefined. +.SH RETURN VALUE +.LP +Refer to \fIlongjmp\fP() and \fIsetjmp\fP() . +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +If \fI_longjmp\fP() is executed and the environment in which \fI_setjmp\fP() +was executed no longer exists, errors can occur. +The conditions under which the environment of the \fI_setjmp\fP() +no longer exists include exiting the function that contains the +\fI_setjmp\fP() call, and exiting an inner block with temporary storage. +This condition might not be detectable, in which case the +\fI_longjmp\fP() occurs and, if the environment no longer exists, +the contents of the temporary storage of an inner block are +unpredictable. This condition might also cause unexpected process +termination. If the function has returned, the results are +undefined. +.LP +Passing \fIlongjmp\fP() a pointer to a buffer not created by \fIsetjmp\fP(), +passing \fI_longjmp\fP() a pointer to a buffer not created by \fI_setjmp\fP(), +passing \fIsiglongjmp\fP() a pointer to a buffer not created by \fIsigsetjmp\fP(), +or passing any of these three functions a buffer that has been modified +by +the user can cause all the problems listed above, and more. +.LP +The \fI_longjmp\fP() and \fI_setjmp\fP() functions are included to +support programs written to historical system interfaces. +New applications should use \fIsiglongjmp\fP() and \fIsigsetjmp\fP() +respectively. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +The \fI_longjmp\fP() and \fI_setjmp\fP() functions may be marked LEGACY +in a future version. +.SH SEE ALSO +.LP +\fIlongjmp\fP() , \fIsetjmp\fP() , \fIsiglongjmp\fP() , \fIsigsetjmp\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/_tolower.3p b/man3p/_tolower.3p new file mode 100644 index 000000000..b2d871873 --- /dev/null +++ b/man3p/_tolower.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "_TOLOWER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" _tolower +.SH NAME +_tolower \- transliterate uppercase characters to lowercase +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int _tolower(int\fP \fIc\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fI_tolower\fP() macro shall be equivalent to \fItolower\fP(\fIc\fP) +except that the application shall ensure that the +argument \fIc\fP is an uppercase letter. +.SH RETURN VALUE +.LP +Upon successful completion, \fI_tolower\fP() shall return the lowercase +letter corresponding to the argument passed. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fItolower\fP() , \fIisupper\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/_toupper.3p b/man3p/_toupper.3p new file mode 100644 index 000000000..9e5d36872 --- /dev/null +++ b/man3p/_toupper.3p @@ -0,0 +1,55 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "_TOUPPER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" _toupper +.SH NAME +_toupper \- transliterate lowercase characters to uppercase +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int _toupper(int\fP \fIc\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fI_toupper\fP() macro shall be equivalent to \fItoupper\fP() +except that the +application shall ensure that the argument \fIc\fP is a lowercase +letter. +.SH RETURN VALUE +.LP +Upon successful completion, \fI_toupper\fP() shall return the uppercase +letter corresponding to the argument passed. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIislower\fP() , \fItoupper\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/a64l.3p b/man3p/a64l.3p new file mode 100644 index 000000000..b373ad5c5 --- /dev/null +++ b/man3p/a64l.3p @@ -0,0 +1,102 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "A64L" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" a64l +.SH NAME +a64l, l64a \- convert between a 32-bit integer and a radix-64 ASCII +string +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +long a64l(const char *\fP\fIs\fP\fB); +.br +char *l64a(long\fP \fIvalue\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +These functions maintain numbers stored in radix-64 ASCII characters. +This is a notation by which 32-bit integers can be +represented by up to six characters; each character represents a digit +in radix-64 notation. If the type \fBlong\fP contains more +than 32 bits, only the low-order 32 bits shall be used for these operations. +.LP +The characters used to represent digits are \fB'.'\fP (dot) for 0, +\fB'/'\fP for 1, \fB'0'\fP through \fB'9'\fP for +[2,11], \fB'A'\fP through \fB'Z'\fP for [12,37], and \fB'a'\fP through +\fB'z'\fP for [38,63]. +.LP +The \fIa64l\fP() function shall take a pointer to a radix-64 representation, +in which the first digit is the least significant, +and return the corresponding \fBlong\fP value. If the string pointed +to by \fIs\fP contains more than six characters, +\fIa64l\fP() shall use the first six. If the first six characters +of the string contain a null terminator, \fIa64l\fP() shall use +only characters preceding the null terminator. The \fIa64l\fP() function +shall scan the character string from left to right with +the least significant digit on the left, decoding each character as +a 6-bit radix-64 number. If the type \fBlong\fP contains more +than 32 bits, the resulting value is sign-extended. The behavior of +\fIa64l\fP() is unspecified if \fIs\fP is a null pointer or +the string pointed to by \fIs\fP was not generated by a previous call +to \fIl64a\fP(). +.LP +The \fIl64a\fP() function shall take a \fBlong\fP argument and return +a pointer to the corresponding radix-64 representation. +The behavior of \fIl64a\fP() is unspecified if \fIvalue\fP is negative. +.LP +The value returned by \fIl64a\fP() may be a pointer into a static +buffer. Subsequent calls to \fIl64a\fP() may overwrite the +buffer. +.LP +The \fIl64a\fP() function need not be reentrant. A function that is +not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +Upon successful completion, \fIa64l\fP() shall return the \fBlong\fP +value resulting from conversion of the input string. If a +string pointed to by \fIs\fP is an empty string, \fIa64l\fP() shall +return 0L. +.LP +The \fIl64a\fP() function shall return a pointer to the radix-64 representation. +If \fIvalue\fP is 0L, \fIl64a\fP() shall +return a pointer to an empty string. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +If the type \fBlong\fP contains more than 32 bits, the result of \fIa64l\fP(\fIl64a\fP(\fIx\fP)) +is \fIx\fP in the +low-order 32 bits. +.SH RATIONALE +.LP +This is not the same encoding as used by either encoding variant of +the \fIuuencode\fP +utility. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrtoul\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, the Shell and Utilities volume of IEEE\ Std\ 1003.1-2001, +\fIuuencode\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/abort.3p b/man3p/abort.3p new file mode 100644 index 000000000..9c42a05b8 --- /dev/null +++ b/man3p/abort.3p @@ -0,0 +1,105 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ABORT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" abort +.SH NAME +abort \- generate an abnormal process abort +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void abort(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fIabort\fP() function shall cause abnormal process termination +to occur, unless the signal SIGABRT is being caught and the +signal handler does not return. +.LP +The +abnormal termination processing shall include the default actions +defined for SIGABRT and may include an attempt to effect \fIfclose\fP() +on all open streams. +.LP +The SIGABRT signal shall be sent to the calling process as if by means +of \fIraise\fP() +with the argument SIGABRT. +.LP +The +status made available to \fIwait\fP() or \fIwaitpid\fP() by \fIabort\fP() +shall be that of a process terminated by the SIGABRT signal. +The \fIabort\fP() function shall override blocking or ignoring the +SIGABRT signal. +.SH RETURN VALUE +.LP +The \fIabort\fP() function shall not return. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Catching the signal is intended to provide the application writer +with a portable means to abort processing, free from possible +interference from any implementation-defined functions. +.SH RATIONALE +.LP +The ISO/IEC\ 9899:1999 standard requires the \fIabort\fP() function +to be async-signal-safe. Since +IEEE\ Std\ 1003.1-2001 defers to the ISO\ C standard, this required +a change to the DESCRIPTION from ``shall include +the effect of \fIfclose\fP()'' to ``may include an attempt to effect +\fIfclose\fP().'' +.LP +The revised wording permits some backwards-compatibility and avoids +a potential deadlock situation. +.LP +The Open Group Base Resolution bwg2002-003 is applied, removing the +following XSI shaded paragraph from the DESCRIPTION: +.LP +``On XSI-conformant systems, in addition the abnormal termination +processing shall include the effect of \fIfclose\fP() on message catalog +descriptors.'' +.LP +There were several reasons to remove this paragraph: +.IP " *" 3 +No special processing of open message catalogs needs to be performed +prior to abnormal process termination. +.LP +.IP " *" 3 +The main reason to specifically mention that \fIabort\fP() includes +the effect of \fIfclose\fP() on open streams is to flush output queued +on the stream. Message catalogs in this +context are read-only and, therefore, do not need to be flushed. +.LP +.IP " *" 3 +The effect of \fIfclose\fP() on a message catalog descriptor is unspecified. +Message +catalog descriptors are allowed, but not required to be implemented +using a file descriptor, but there is no mention in +IEEE\ Std\ 1003.1-2001 of a message catalog descriptor using a standard +I/O stream FILE object as would be expected by \fIfclose\fP(). +.LP +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexit\fP() , \fIkill\fP() , \fIraise\fP() , \fIsignal\fP() , \fIwait\fP() +, \fIwaitpid\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/abs.3p b/man3p/abs.3p new file mode 100644 index 000000000..2c2561a6e --- /dev/null +++ b/man3p/abs.3p @@ -0,0 +1,55 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ABS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" abs +.SH NAME +abs \- return an integer absolute value +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int abs(int\fP \fIi\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIabs\fP() function shall compute the absolute value of its integer +operand, \fIi\fP. If the result cannot be +represented, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIabs\fP() function shall return the absolute value of its integer +operand. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +In two's-complement representation, the absolute value of the negative +integer with largest magnitude {INT_MIN} might not be +representable. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfabs\fP() , \fIlabs\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/accept.3p b/man3p/accept.3p new file mode 100644 index 000000000..aa0fc7ae7 --- /dev/null +++ b/man3p/accept.3p @@ -0,0 +1,149 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ACCEPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" accept +.SH NAME +accept \- accept a new connection on a socket +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int accept(int\fP \fIsocket\fP\fB, struct sockaddr *restrict\fP \fIaddress\fP\fB, +.br +\ \ \ \ \ \ socklen_t *restrict\fP \fIaddress_len\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIaccept\fP() function shall extract the first connection on +the queue of pending connections, create a new socket with +the same socket type protocol and address family as the specified +socket, and allocate a new file descriptor for that socket. +.LP +The \fIaccept\fP() function takes the following arguments: +.TP 7 +\fIsocket\fP +Specifies a socket that was created with \fIsocket\fP(), has been +bound to an address +with \fIbind\fP(), and has issued a successful call to \fIlisten\fP(). +.TP 7 +\fIaddress\fP +Either a null pointer, or a pointer to a \fBsockaddr\fP structure +where the address of the connecting socket shall be +returned. +.TP 7 +\fIaddress_len\fP +Points to a \fBsocklen_t\fP structure which on input specifies the +length of the supplied \fBsockaddr\fP structure, and on +output specifies the length of the stored address. +.sp +.LP +If \fIaddress\fP is not a null pointer, the address of the peer for +the accepted connection shall be stored in the +\fBsockaddr\fP structure pointed to by \fIaddress\fP, and the length +of this address shall be stored in the object pointed to by +\fIaddress_len\fP. +.LP +If the actual length of the address is greater than the length of +the supplied \fBsockaddr\fP structure, the stored address +shall be truncated. +.LP +If the protocol permits connections by unbound clients, and the peer +is not bound, then the value stored in the object pointed +to by \fIaddress\fP is unspecified. +.LP +If the listen queue is empty of connection requests and O_NONBLOCK +is not set on the file descriptor for the socket, +\fIaccept\fP() shall block until a connection is present. If the \fIlisten\fP() +queue is +empty of connection requests and O_NONBLOCK is set on the file descriptor +for the socket, \fIaccept\fP() shall fail and set +\fIerrno\fP to [EAGAIN] or [EWOULDBLOCK]. +.LP +The accepted socket cannot itself accept more connections. The original +socket remains open and can accept more connections. +.SH RETURN VALUE +.LP +Upon successful completion, \fIaccept\fP() shall return the non-negative +file descriptor of the accepted socket. Otherwise, -1 +shall be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIaccept\fP() function shall fail if: +.TP 7 +.B EAGAIN \fRor\fP EWOULDBLOCK +.sp +O_NONBLOCK is set for the socket file descriptor and no connections +are present to be accepted. +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid file descriptor. +.TP 7 +.B ECONNABORTED +.sp +A connection has been aborted. +.TP 7 +.B EINTR +The \fIaccept\fP() function was interrupted by a signal that was caught +before a valid connection arrived. +.TP 7 +.B EINVAL +The \fIsocket\fP is not accepting connections. +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENFILE +The maximum number of file descriptors in the system are already open. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.TP 7 +.B EOPNOTSUPP +The socket type of the specified socket does not support accepting +connections. +.sp +.LP +The \fIaccept\fP() function may fail if: +.TP 7 +.B ENOBUFS +No buffer space is available. +.TP 7 +.B ENOMEM +There was insufficient memory available to complete the operation. +.TP 7 +.B EPROTO +A protocol error has occurred; for example, the STREAMS protocol stack +has not been initialized. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +When a connection is available, \fIselect\fP() indicates that the +file descriptor for +the socket is ready for reading. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIbind\fP() , \fIconnect\fP() , \fIlisten\fP() +, \fIsocket\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/access.3p b/man3p/access.3p new file mode 100644 index 000000000..871fe2178 --- /dev/null +++ b/man3p/access.3p @@ -0,0 +1,159 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ACCESS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" access +.SH NAME +access \- determine accessibility of a file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int access(const char *\fP\fIpath\fP\fB, int\fP \fIamode\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIaccess\fP() function shall check the file named by the pathname +pointed to by the \fIpath\fP argument for accessibility +according to the bit pattern contained in \fIamode\fP, using the real +user ID in place of the effective user ID and the real group +ID in place of the effective group ID. +.LP +The value of \fIamode\fP is either the bitwise-inclusive OR of the +access permissions to be checked (R_OK, W_OK, X_OK) or the +existence test (F_OK). +.LP +If any access permissions are checked, each shall be checked individually, +as described in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 3, Definitions. If the process has +appropriate +privileges, an implementation may indicate success for X_OK even if +none of the execute file permission bits are set. +.SH RETURN VALUE +.LP +If the requested access is permitted, \fIaccess\fP() succeeds and +shall return 0; otherwise, -1 shall be returned and +\fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +The \fIaccess\fP() function shall fail if: +.TP 7 +.B EACCES +Permission bits of the file mode do not permit the requested access, +or search permission is denied on a component of the path +prefix. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.TP 7 +.B EROFS +Write access is requested for a file on a read-only file system. +.sp +.LP +The \fIaccess\fP() function may fail if: +.TP 7 +.B EINVAL +The value of the \fIamode\fP argument is invalid. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.TP 7 +.B ETXTBSY +Write access is requested for a pure procedure (shared text) file +that is being executed. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Testing for the Existence of a File +.LP +The following example tests whether a file named \fBmyfile\fP exists +in the \fB/tmp\fP directory. +.sp +.RS +.nf + +\fB#include +\&... +int result; +const char *filename = "/tmp/myfile"; +.sp + +result = access (filename, F_OK); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +Additional values of \fIamode\fP other than the set defined in the +description may be valid; for example, if a system has +extended access controls. +.SH RATIONALE +.LP +In early proposals, some inadequacies in the \fIaccess\fP() function +led to the creation of an \fIeaccess\fP() function +because: +.IP " 1." 4 +Historical implementations of \fIaccess\fP() do not test file access +correctly when the process' real user ID is superuser. In +particular, they always return zero when testing execute permissions +without regard to whether the file is executable. +.LP +.IP " 2." 4 +The superuser has complete access to all files on a system. As a consequence, +programs started by the superuser and switched to +the effective user ID with lesser privileges cannot use \fIaccess\fP() +to test their file access permissions. +.LP +.LP +However, the historical model of \fIeaccess\fP() does not resolve +problem (1), so this volume of IEEE\ Std\ 1003.1-2001 +now allows \fIaccess\fP() to behave in the desired way because several +implementations have corrected the problem. It was also +argued that problem (2) is more easily solved by using \fIopen\fP(), +\fIchdir\fP(), or one of the \fIexec\fP functions as +appropriate and responding to the error, rather than creating a new +function that would not be as reliable. Therefore, +\fIeaccess\fP() is not included in this volume of IEEE\ Std\ 1003.1-2001. +.LP +The sentence concerning appropriate privileges and execute permission +bits reflects the two possibilities implemented by +historical implementations when checking superuser access for X_OK. +.LP +New implementations are discouraged from returning X_OK unless at +least one execution permission bit is set. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchmod\fP() , \fIstat\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/acos.3p b/man3p/acos.3p new file mode 100644 index 000000000..a5f25f153 --- /dev/null +++ b/man3p/acos.3p @@ -0,0 +1,94 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ACOS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" acos +.SH NAME +acos, acosf, acosl \- arc cosine functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double acos(double\fP \fIx\fP\fB); +.br +float acosf(float\fP \fIx\fP\fB); +.br +long double acosl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the principal value of the arc cosine +of their argument \fIx\fP. The value of \fIx\fP should be +in the range [-1,1]. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the arc cosine +of \fIx\fP, in the range [0,pi] radians. +.LP +For finite values of \fIx\fP not in the range [-1,1], a domain error +shall occur, and \ either a NaN +(if supported), or \ an implementation-defined value shall be +returned. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is +1, +0 shall be returned. +.LP +If \fIx\fP is \(+-Inf, a domain error shall occur, and either a NaN +(if supported), or an implementation-defined value +shall be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The \fIx\fP argument is finite and is not in the range [-1,1], \ or +is \(+-Inf. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcos\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/acosf.3p b/man3p/acosf.3p new file mode 100644 index 000000000..1a7b62b8d --- /dev/null +++ b/man3p/acosf.3p @@ -0,0 +1 @@ +.so man3p/acos.3p diff --git a/man3p/acosh.3p b/man3p/acosh.3p new file mode 100644 index 000000000..fad3f6758 --- /dev/null +++ b/man3p/acosh.3p @@ -0,0 +1,91 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ACOSH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" acosh +.SH NAME +acosh, acoshf, acoshl \- inverse hyperbolic cosine functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double acosh(double\fP \fIx\fP\fB); +.br +float acoshf(float\fP \fIx\fP\fB); +.br +long double acoshl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the inverse hyperbolic cosine of their +argument \fIx\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the inverse +hyperbolic cosine of their argument. +.LP +For finite values of \fIx\fP < 1, a domain error shall occur, and +\ either a NaN (if supported), or \ an implementation-defined value +shall be returned. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is +1, +0 shall be returned. +.LP +If \fIx\fP is +Inf, +Inf shall be returned. +.LP +If \fIx\fP is -Inf, a domain error shall occur, and either a NaN (if +supported), or an implementation-defined value shall be +returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The \fIx\fP argument is finite and less than +1.0, \ or is -Inf. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcosh\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/acoshf.3p b/man3p/acoshf.3p new file mode 100644 index 000000000..1a98b08d9 --- /dev/null +++ b/man3p/acoshf.3p @@ -0,0 +1 @@ +.so man3p/acosh.3p diff --git a/man3p/acoshl.3p b/man3p/acoshl.3p new file mode 100644 index 000000000..1a98b08d9 --- /dev/null +++ b/man3p/acoshl.3p @@ -0,0 +1 @@ +.so man3p/acosh.3p diff --git a/man3p/acosl.3p b/man3p/acosl.3p new file mode 100644 index 000000000..1a7b62b8d --- /dev/null +++ b/man3p/acosl.3p @@ -0,0 +1 @@ +.so man3p/acos.3p diff --git a/man3p/aio_cancel.3p b/man3p/aio_cancel.3p new file mode 100644 index 000000000..015b53ca3 --- /dev/null +++ b/man3p/aio_cancel.3p @@ -0,0 +1,94 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "AIO_CANCEL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" aio_cancel +.SH NAME +aio_cancel \- cancel an asynchronous I/O request (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int aio_cancel(int\fP \fIfildes\fP\fB, struct aiocb *\fP\fIaiocbp\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIaio_cancel\fP() function shall attempt to cancel one or more +asynchronous I/O requests currently outstanding against +file descriptor \fIfildes\fP. The \fIaiocbp\fP argument points to +the asynchronous I/O control block for a particular request to +be canceled. If \fIaiocbp\fP is NULL, then all outstanding cancelable +asynchronous I/O requests against \fIfildes\fP shall be +canceled. +.LP +Normal asynchronous notification shall occur for asynchronous I/O +operations that are successfully canceled. If there are +requests that cannot be canceled, then the normal asynchronous completion +process shall take place for those requests when they are +completed. +.LP +For requested operations that are successfully canceled, the associated +error status shall be set to [ECANCELED] and the return +status shall be -1. For requested operations that are not successfully +canceled, the \fIaiocbp\fP shall not be modified by +\fIaio_cancel\fP(). +.LP +If \fIaiocbp\fP is not NULL, then if \fIfildes\fP does not have the +same value as the file descriptor with which the +asynchronous operation was initiated, unspecified results occur. +.LP +Which operations are cancelable is implementation-defined. +.SH RETURN VALUE +.LP +The \fIaio_cancel\fP() function shall return the value AIO_CANCELED +to the calling process if the requested operation(s) were +canceled. The value AIO_NOTCANCELED shall be returned if at least +one of the requested operation(s) cannot be canceled because it +is in progress. In this case, the state of the other operations, if +any, referenced in the call to \fIaio_cancel\fP() is not +indicated by the return value of \fIaio_cancel\fP(). The application +may determine the state of affairs for these operations by +using \fIaio_error\fP(). The value AIO_ALLDONE is returned if all +of the operations have +already completed. Otherwise, the function shall return -1 and set +\fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIaio_cancel\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIaio_cancel\fP() function is part of the Asynchronous Input +and Output option and need not be available on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIaio_read\fP() , \fIaio_write\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/aio_error.3p b/man3p/aio_error.3p new file mode 100644 index 000000000..9ea474aa2 --- /dev/null +++ b/man3p/aio_error.3p @@ -0,0 +1,75 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "AIO_ERROR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" aio_error +.SH NAME +aio_error \- retrieve errors status for an asynchronous I/O operation +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int aio_error(const struct aiocb *\fP\fIaiocbp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIaio_error\fP() function shall return the error status associated +with the \fBaiocb\fP structure referenced by the +\fIaiocbp\fP argument. The error status for an asynchronous I/O operation +is the \fIerrno\fP value that would be set by the +corresponding \fIread\fP(), \fIwrite\fP(), \fIfdatasync\fP(), or +\fIfsync\fP() operation. If the operation has not yet completed, then +the error status shall be +equal to [EINPROGRESS]. +.SH RETURN VALUE +.LP +If the asynchronous I/O operation has completed successfully, then +0 shall be returned. If the asynchronous operation has +completed unsuccessfully, then the error status, as described for +\fIread\fP(), \fIwrite\fP(), \fIfdatasync\fP(), and \fIfsync\fP(), +shall be returned. +If the asynchronous I/O operation has not yet completed, then [EINPROGRESS] +shall be returned. +.SH ERRORS +.LP +The \fIaio_error\fP() function may fail if: +.TP 7 +.B EINVAL +The \fIaiocbp\fP argument does not refer to an asynchronous operation +whose return status has not yet been retrieved. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIaio_error\fP() function is part of the Asynchronous Input and +Output option and need not be available on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIaio_cancel\fP() , \fIaio_fsync\fP() , \fIaio_read\fP() , \fIaio_return\fP() +, \fIaio_write\fP() , \fIclose\fP() , \fIexec\fP() , \fIexit\fP() +, \fIfork\fP() , \fIlio_listio\fP() , \fIlseek\fP() , \fIread\fP() +, +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/aio_fsync.3p b/man3p/aio_fsync.3p new file mode 100644 index 000000000..d2fd398b8 --- /dev/null +++ b/man3p/aio_fsync.3p @@ -0,0 +1,128 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "AIO_FSYNC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" aio_fsync +.SH NAME +aio_fsync \- asynchronous file synchronization (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int aio_fsync(int\fP \fIop\fP\fB, struct aiocb *\fP\fIaiocbp\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIaio_fsync\fP() function shall asynchronously force all I/O +operations associated with the file indicated by the file +descriptor \fIaio_fildes\fP member of the \fBaiocb\fP structure referenced +by the \fIaiocbp\fP argument and queued at the time +of the call to \fIaio_fsync\fP() to the synchronized I/O completion +state. The function call shall return when the synchronization +request has been initiated or queued to the file or device (even when +the data cannot be synchronized immediately). +.LP +If \fIop\fP is O_DSYNC, all currently queued I/O operations shall +be completed as if by a call to \fIfdatasync\fP(); that is, as defined +for synchronized I/O data integrity completion. If +\fIop\fP is O_SYNC, all currently queued I/O operations shall be completed +as if by a call to \fIfsync\fP(); that is, as defined for synchronized +I/O file integrity completion. If the +\fIaio_fsync\fP() function fails, or if the operation queued by \fIaio_fsync\fP() +fails, then, as for \fIfsync\fP() and \fIfdatasync\fP(), outstanding +I/O +operations are not guaranteed to have been completed. +.LP +If \fIaio_fsync\fP() succeeds, then it is only the I/O that was queued +at the time of the call to \fIaio_fsync\fP() that is +guaranteed to be forced to the relevant completion state. The completion +of subsequent I/O on the file descriptor is not guaranteed +to be completed in a synchronized fashion. +.LP +The \fIaiocbp\fP argument refers to an asynchronous I/O control block. +The \fIaiocbp\fP value may be used as an argument to \fIaio_error\fP() +and \fIaio_return\fP() in +order to determine the error status and return status, respectively, +of the asynchronous operation while it is proceeding. When the +request is queued, the error status for the operation is [EINPROGRESS]. +When all data has been successfully transferred, the error +status shall be reset to reflect the success or failure of the operation. +If the operation does not complete successfully, the +error status for the operation shall be set to indicate the error. +The \fIaio_sigevent\fP member determines the asynchronous +notification to occur as specified in \fISignal Generation and Delivery\fP +when all +operations have achieved synchronized I/O completion. All other members +of the structure referenced by \fIaiocbp\fP are ignored. +If the control block referenced by \fIaiocbp\fP becomes an illegal +address prior to asynchronous I/O completion, then the behavior +is undefined. +.LP +If the \fIaio_fsync\fP() function fails or \fIaiocbp\fP indicates +an error condition, data is not guaranteed to have been +successfully transferred. +.SH RETURN VALUE +.LP +The \fIaio_fsync\fP() function shall return the value 0 to the calling +process if the I/O operation is successfully queued; +otherwise, the function shall return the value -1 and set \fIerrno\fP +to indicate the error. +.SH ERRORS +.LP +The \fIaio_fsync\fP() function shall fail if: +.TP 7 +.B EAGAIN +The requested asynchronous operation was not queued due to temporary +resource limitations. +.TP 7 +.B EBADF +The \fIaio_fildes\fP member of the \fBaiocb\fP structure referenced +by the \fIaiocbp\fP argument is not a valid file +descriptor open for writing. +.TP 7 +.B EINVAL +This implementation does not support synchronized I/O for this file. +.TP 7 +.B EINVAL +A value of \fIop\fP other than O_DSYNC or O_SYNC was specified. +.sp +.LP +In the event that any of the queued I/O operations fail, \fIaio_fsync\fP() +shall return the error condition defined for \fIread\fP() and \fIwrite\fP(). +The error is returned in +the error status for the asynchronous \fIfsync\fP() operation, which +can be retrieved using +\fIaio_error\fP(). +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIaio_fsync\fP() function is part of the Asynchronous Input and +Output option and need not be available on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfcntl\fP() , \fIfdatasync\fP() , \fIfsync\fP() , \fIopen\fP() , +\fIread\fP() , \fIwrite\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/aio_read.3p b/man3p/aio_read.3p new file mode 100644 index 000000000..f95d32134 --- /dev/null +++ b/man3p/aio_read.3p @@ -0,0 +1,164 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "AIO_READ" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" aio_read +.SH NAME +aio_read \- asynchronous read from a file (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int aio_read(struct aiocb *\fP\fIaiocbp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIaio_read\fP() function shall read \fIaiocbp\fP->\fIaio_nbytes\fP +from the file associated with +\fIaiocbp\fP->\fIaio_fildes\fP into the buffer pointed to by \fIaiocbp\fP->\fIaio_buf\fP. +The function call shall return +when the read request has been initiated or queued to the file or +device (even when the data cannot be delivered immediately). +.LP +If prioritized I/O is supported for this file, then the asynchronous +operation shall be submitted at a priority equal to the +scheduling priority of the process minus \fIaiocbp\fP->\fIaio_reqprio\fP. +.LP +The \fIaiocbp\fP value may be used as an argument to \fIaio_error\fP() +and \fIaio_return\fP() in order to determine the error status and +return status, respectively, of +the asynchronous operation while it is proceeding. If an error condition +is encountered during queuing, the function call shall +return without having initiated or queued the request. The requested +operation takes place at the absolute position in the file as +given by \fIaio_offset\fP, as if \fIlseek\fP() were called immediately +prior to the +operation with an \fIoffset\fP equal to \fIaio_offset\fP and a \fIwhence\fP +equal to SEEK_SET. After a successful call to +enqueue an asynchronous I/O operation, the value of the file offset +for the file is unspecified. +.LP +The \fIaiocbp\fP->\fIaio_lio_opcode\fP field shall be ignored by \fIaio_read\fP(). +.LP +The \fIaiocbp\fP argument points to an \fBaiocb\fP structure. If the +buffer pointed to by \fIaiocbp\fP->\fIaio_buf\fP or +the control block pointed to by \fIaiocbp\fP becomes an illegal address +prior to asynchronous I/O completion, then the behavior is +undefined. +.LP +Simultaneous asynchronous operations using the same \fIaiocbp\fP produce +undefined results. +.LP +If synchronized I/O is enabled on the file associated with \fIaiocbp\fP->\fIaio_fildes\fP, +the behavior of this function shall +be according to the definitions of synchronized I/O data integrity +completion and synchronized I/O file integrity completion. +.LP +For any system action that changes the process memory space while +an asynchronous I/O is outstanding to the address range being +changed, the result of that action is undefined. +.LP +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +\fIaiocbp\fP->\fIaio_fildes\fP. +.SH RETURN VALUE +.LP +The \fIaio_read\fP() function shall return the value zero to the calling +process if the I/O operation is successfully queued; +otherwise, the function shall return the value -1 and set \fIerrno\fP +to indicate the error. +.SH ERRORS +.LP +The \fIaio_read\fP() function shall fail if: +.TP 7 +.B EAGAIN +The requested asynchronous I/O operation was not queued due to system +resource limitations. +.sp +.LP +Each of the following conditions may be detected synchronously at +the time of the call to \fIaio_read\fP(), or asynchronously. +If any of the conditions below are detected synchronously, the \fIaio_read\fP() +function shall return -1 and set \fIerrno\fP to +the corresponding value. If any of the conditions below are detected +asynchronously, the return status of the asynchronous +operation is set to -1, and the error status of the asynchronous operation +is set to the corresponding value. +.TP 7 +.B EBADF +The \fIaiocbp\fP->\fIaio_fildes\fP argument is not a valid file descriptor +open for reading. +.TP 7 +.B EINVAL +The file offset value implied by \fIaiocbp\fP->\fIaio_offset\fP would +be invalid, \fIaiocbp\fP->\fIaio_reqprio\fP is +not a valid value, or \fIaiocbp\fP->\fIaio_nbytes\fP is an invalid +value. +.sp +.LP +In the case that the \fIaio_read\fP() successfully queues the I/O +operation but the operation is subsequently canceled or +encounters an error, the return status of the asynchronous operation +is one of the values normally returned by the \fIread\fP() function +call. In addition, the error status of the asynchronous operation +is set to one +of the error statuses normally set by the \fIread\fP() function call, +or one of the following +values: +.TP 7 +.B EBADF +The \fIaiocbp\fP->\fIaio_fildes\fP argument is not a valid file descriptor +open for reading. +.TP 7 +.B ECANCELED +The requested I/O was canceled before the I/O completed due to an +explicit \fIaio_cancel\fP() request. +.TP 7 +.B EINVAL +The file offset value implied by \fIaiocbp\fP->\fIaio_offset\fP would +be invalid. +.sp +.LP +The following condition may be detected synchronously or asynchronously: +.TP 7 +.B EOVERFLOW +The file is a regular file, \fIaiobcp\fP->\fIaio_nbytes\fP is greater +than 0, and the starting offset in +\fIaiobcp\fP->\fIaio_offset\fP is before the end-of-file and is at +or beyond the offset maximum in the open file description +associated with \fIaiocbp\fP->\fIaio_fildes\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIaio_read\fP() function is part of the Asynchronous Input and +Output option and need not be available on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIaio_cancel\fP() , \fIaio_error\fP() , \fIlio_listio\fP() , \fIaio_return\fP() +, \fIaio_write\fP() , \fIclose\fP() , \fIexec\fP() , \fIexit\fP() +, \fIfork\fP() , \fIlseek\fP() , \fIread\fP() , the Base Definitions +volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/aio_return.3p b/man3p/aio_return.3p new file mode 100644 index 000000000..a3d85d8d9 --- /dev/null +++ b/man3p/aio_return.3p @@ -0,0 +1,81 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "AIO_RETURN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" aio_return +.SH NAME +aio_return \- retrieve return status of an asynchronous I/O operation +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +ssize_t aio_return(struct aiocb *\fP\fIaiocbp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIaio_return\fP() function shall return the return status associated +with the \fBaiocb\fP structure referenced by the +\fIaiocbp\fP argument. The return status for an asynchronous I/O operation +is the value that would be returned by the +corresponding \fIread\fP(), \fIwrite\fP(), or \fIfsync\fP() function +call. If the error status for the operation is equal to [EINPROGRESS], +then +the return status for the operation is undefined. The \fIaio_return\fP() +function may be called exactly once to retrieve the +return status of a given asynchronous operation; thereafter, if the +same \fBaiocb\fP structure is used in a call to +\fIaio_return\fP() or \fIaio_error\fP(), an error may be returned. +When the +\fBaiocb\fP structure referred to by \fIaiocbp\fP is used to submit +another asynchronous operation, then \fIaio_return\fP() may +be successfully used to retrieve the return status of that operation. +.SH RETURN VALUE +.LP +If the asynchronous I/O operation has completed, then the return status, +as described for \fIread\fP(), \fIwrite\fP(), and \fIfsync\fP(), shall +be returned. If the asynchronous I/O operation has not yet completed, +the +results of \fIaio_return\fP() are undefined. +.SH ERRORS +.LP +The \fIaio_return\fP() function may fail if: +.TP 7 +.B EINVAL +The \fIaiocbp\fP argument does not refer to an asynchronous operation +whose return status has not yet been retrieved. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIaio_return\fP() function is part of the Asynchronous Input +and Output option and need not be available on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIaio_cancel\fP() , \fIaio_error\fP() , \fIaio_fsync\fP() , \fIaio_read\fP() +, \fIaio_write\fP() , \fIclose\fP() , \fIexec\fP() , \fIexit\fP() +, \fIfork\fP() , \fIlio_listio\fP() , \fIlseek\fP() , \fIread\fP() +, +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/aio_suspend.3p b/man3p/aio_suspend.3p new file mode 100644 index 000000000..730c09b2a --- /dev/null +++ b/man3p/aio_suspend.3p @@ -0,0 +1,101 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "AIO_SUSPEND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" aio_suspend +.SH NAME +aio_suspend \- wait for an asynchronous I/O request (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int aio_suspend(const struct aiocb * const\fP \fIlist\fP\fB[], int\fP +\fInent\fP\fB, +.br +\ \ \ \ \ \ const struct timespec *\fP\fItimeout\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIaio_suspend\fP() function shall suspend the calling thread +until at least one of the asynchronous I/O operations +referenced by the \fIlist\fP argument has completed, until a signal +interrupts the function, or, if \fItimeout\fP is not NULL, +until the time interval specified by \fItimeout\fP has passed. If +any of the \fBaiocb\fP structures in the list correspond to +completed asynchronous I/O operations (that is, the error status for +the operation is not equal to [EINPROGRESS]) at the time of +the call, the function shall return without suspending the calling +thread. The \fIlist\fP argument is an array of pointers to +asynchronous I/O control blocks. The \fInent\fP argument indicates +the number of elements in the array. Each \fBaiocb\fP +structure pointed to has been used in initiating an asynchronous I/O +request via \fIaio_read\fP(), \fIaio_write\fP(), or \fIlio_listio\fP(). +This array may contain NULL pointers, which are ignored. If this array +contains pointers that refer to \fBaiocb\fP structures that have not +been used in submitting asynchronous I/O, the effect is +undefined. +.LP +If the time interval indicated in the \fBtimespec\fP structure pointed +to by \fItimeout\fP passes before any of the I/O +operations referenced by \fIlist\fP are completed, then \fIaio_suspend\fP() +shall return with an error. \ If the +Monotonic Clock option is supported, the clock that shall be used +to measure this time interval shall be the CLOCK_MONOTONIC clock. +.SH RETURN VALUE +.LP +If the \fIaio_suspend\fP() function returns after one or more asynchronous +I/O operations have completed, the function shall +return zero. Otherwise, the function shall return a value of -1 and +set \fIerrno\fP to indicate the error. +.LP +The application may determine which asynchronous I/O completed by +scanning the associated error and return status using \fIaio_error\fP() +and \fIaio_return\fP(), +respectively. +.SH ERRORS +.LP +The \fIaio_suspend\fP() function shall fail if: +.TP 7 +.B EAGAIN +No asynchronous I/O indicated in the list referenced by \fIlist\fP +completed in the time interval indicated by +\fItimeout\fP. +.TP 7 +.B EINTR +A signal interrupted the \fIaio_suspend\fP() function. Note that, +since each asynchronous I/O operation may possibly provoke a +signal when it completes, this error return may be caused by the completion +of one (or more) of the very I/O operations being +awaited. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIaio_suspend\fP() function is part of the Asynchronous Input +and Output option and need not be available on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIaio_read\fP() , \fIaio_write\fP() , \fIlio_listio\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/aio_write.3p b/man3p/aio_write.3p new file mode 100644 index 000000000..17a2c55ae --- /dev/null +++ b/man3p/aio_write.3p @@ -0,0 +1,166 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "AIO_WRITE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" aio_write +.SH NAME +aio_write \- asynchronous write to a file (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int aio_write(struct aiocb *\fP\fIaiocbp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIaio_write\fP() function shall write \fIaiocbp\fP->\fIaio_nbytes\fP +to the file associated with +\fIaiocbp\fP->\fIaio_fildes\fP from the buffer pointed to by \fIaiocbp\fP->\fIaio_buf\fP. +The function shall return when +the write request has been initiated or, at a minimum, queued to the +file or device. +.LP +If prioritized I/O is supported for this file, then the asynchronous +operation shall be submitted at a priority equal to the +scheduling priority of the process minus \fIaiocbp\fP->\fIaio_reqprio\fP. +.LP +The \fIaiocbp\fP argument may be used as an argument to \fIaio_error\fP() +and \fIaio_return\fP() in order to determine the error status and +return status, respectively, +of the asynchronous operation while it is proceeding. +.LP +The \fIaiocbp\fP argument points to an \fBaiocb\fP structure. If the +buffer pointed to by \fIaiocbp\fP->\fIaio_buf\fP or +the control block pointed to by \fIaiocbp\fP becomes an illegal address +prior to asynchronous I/O completion, then the behavior is +undefined. +.LP +If O_APPEND is not set for the file descriptor \fIaio_fildes\fP, then +the requested operation shall take place at the absolute +position in the file as given by \fIaio_offset\fP, as if \fIlseek\fP() +were called +immediately prior to the operation with an \fIoffset\fP equal to \fIaio_offset\fP +and a \fIwhence\fP equal to SEEK_SET. If +O_APPEND is set for the file descriptor, write operations append to +the file in the same order as the calls were made. After a +successful call to enqueue an asynchronous I/O operation, the value +of the file offset for the file is unspecified. +.LP +The \fIaiocbp\fP->\fIaio_lio_opcode\fP field shall be ignored by \fIaio_write\fP(). +.LP +Simultaneous asynchronous operations using the same \fIaiocbp\fP produce +undefined results. +.LP +If synchronized I/O is enabled on the file associated with \fIaiocbp\fP->\fIaio_fildes\fP, +the behavior of this function shall +be according to the definitions of synchronized I/O data integrity +completion, and synchronized I/O file integrity completion. +.LP +For any system action that changes the process memory space while +an asynchronous I/O is outstanding to the address range being +changed, the result of that action is undefined. +.LP +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +\fIaiocbp\fP->\fIaio_fildes\fP. +.SH RETURN VALUE +.LP +The \fIaio_write\fP() function shall return the value zero to the +calling process if the I/O operation is successfully queued; +otherwise, the function shall return the value -1 and set \fIerrno\fP +to indicate the error. +.SH ERRORS +.LP +The \fIaio_write\fP() function shall fail if: +.TP 7 +.B EAGAIN +The requested asynchronous I/O operation was not queued due to system +resource limitations. +.sp +.LP +Each of the following conditions may be detected synchronously at +the time of the call to \fIaio_write\fP(), or asynchronously. +If any of the conditions below are detected synchronously, the \fIaio_write\fP() +function shall return -1 and set \fIerrno\fP to +the corresponding value. If any of the conditions below are detected +asynchronously, the return status of the asynchronous +operation shall be set to -1, and the error status of the asynchronous +operation is set to the corresponding value. +.TP 7 +.B EBADF +The \fIaiocbp\fP->\fIaio_fildes\fP argument is not a valid file descriptor +open for writing. +.TP 7 +.B EINVAL +The file offset value implied by \fIaiocbp\fP->\fIaio_offset\fP would +be invalid, \fIaiocbp\fP->\fIaio_reqprio\fP is +not a valid value, or \fIaiocbp\fP->\fIaio_nbytes\fP is an invalid +value. +.sp +.LP +In the case that the \fIaio_write\fP() successfully queues the I/O +operation, the return status of the asynchronous operation +shall be one of the values normally returned by the \fIwrite\fP() +function call. If the +operation is successfully queued but is subsequently canceled or encounters +an error, the error status for the asynchronous +operation contains one of the values normally set by the \fIwrite\fP() +function call, or one +of the following: +.TP 7 +.B EBADF +The \fIaiocbp\fP->\fIaio_fildes\fP argument is not a valid file descriptor +open for writing. +.TP 7 +.B EINVAL +The file offset value implied by \fIaiocbp\fP->\fIaio_offset\fP would +be invalid. +.TP 7 +.B ECANCELED +The requested I/O was canceled before the I/O completed due to an +explicit \fIaio_cancel\fP() request. +.sp +.LP +The following condition may be detected synchronously or asynchronously: +.TP 7 +.B EFBIG +The file is a regular file, \fIaiobcp\fP->\fIaio_nbytes\fP is greater +than 0, and the starting offset in +\fIaiobcp\fP->\fIaio_offset\fP is at or beyond the offset maximum +in the open file description associated with +\fIaiocbp\fP->\fIaio_fildes\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIaio_write\fP() function is part of the Asynchronous Input and +Output option and need not be available on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIaio_cancel\fP() , \fIaio_error\fP() , \fIaio_read\fP() , \fIaio_return\fP() +, \fIclose\fP() +, \fIexec\fP() , \fIexit\fP() , \fIfork\fP() , \fIlio_listio\fP() +, \fIlseek\fP() , \fIwrite\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/alarm.3p b/man3p/alarm.3p new file mode 100644 index 000000000..4c44b28bf --- /dev/null +++ b/man3p/alarm.3p @@ -0,0 +1,120 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ALARM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" alarm +.SH NAME +alarm \- schedule an alarm signal +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +unsigned alarm(unsigned\fP \fIseconds\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIalarm\fP() function shall cause the system to generate a SIGALRM +signal for the process after the number of realtime +seconds specified by \fIseconds\fP have elapsed. Processor scheduling +delays may prevent the process from handling the signal as +soon as it is generated. +.LP +If \fIseconds\fP is 0, a pending alarm request, if any, is canceled. +.LP +Alarm requests are not stacked; only one SIGALRM generation can be +scheduled in this manner. If the SIGALRM signal has not yet +been generated, the call shall result in rescheduling the time at +which the SIGALRM signal is generated. +.LP +Interactions between \fIalarm\fP() and any of \fIsetitimer\fP(), \fIualarm\fP(), +or \fIusleep\fP() are unspecified. +.SH RETURN VALUE +.LP +If there is a previous \fIalarm\fP() request with time remaining, +\fIalarm\fP() shall return a non-zero value that is the +number of seconds until the previous request would have generated +a SIGALRM signal. Otherwise, \fIalarm\fP() shall return 0. +.SH ERRORS +.LP +The \fIalarm\fP() function is always successful, and no return value +is reserved to indicate an error. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIfork\fP() function clears pending alarms in the child process. +A new process image +created by one of the \fIexec\fP functions inherits the time left +to an alarm signal in the +old process' image. +.LP +Application writers should note that the type of the argument \fIseconds\fP +and the return value of \fIalarm\fP() is +\fBunsigned\fP. That means that a Strictly Conforming POSIX System +Interfaces Application cannot pass a value greater than the +minimum guaranteed value for {UINT_MAX}, which the ISO\ C standard +sets as 65535, and any application passing a larger value is +restricting its portability. A different type was considered, but +historical implementations, including those with a 16-bit +\fBint\fP type, consistently use either \fBunsigned\fP or \fBint\fP. +.LP +Application writers should be aware of possible interactions when +the same process uses both the \fIalarm\fP() and \fIsleep\fP() functions. +.SH RATIONALE +.LP +Many historical implementations (including Version 7 and System V) +allow an alarm to occur up to a second early. Other +implementations allow alarms up to half a second or one clock tick +early or do not allow them to occur early at all. The latter is +considered most appropriate, since it gives the most predictable behavior, +especially since the signal can always be delayed for an +indefinite amount of time due to scheduling. Applications can thus +choose the \fIseconds\fP argument as the minimum amount of time +they wish to have elapse before the signal. +.LP +The term "realtime" here and elsewhere ( \fIsleep\fP(), \fItimes\fP()) +is intended to mean "wall clock" time as common English usage, and +has nothing to +do with "realtime operating systems". It is in contrast to \fIvirtual +time\fP, which could be misinterpreted if just \fItime\fP +were used. +.LP +In some implementations, including 4.3 BSD, very large values of the +\fIseconds\fP argument are silently rounded down to an +implementation-defined maximum value. This maximum is large enough +(to the order of several months) that the effect is not +noticeable. +.LP +There were two possible choices for alarm generation in multi-threaded +applications: generation for the calling thread or +generation for the process. The first option would not have been particularly +useful since the alarm state is maintained on a +per-process basis and the alarm that is established by the last invocation +of \fIalarm\fP() is the only one that would be +active. +.LP +Furthermore, allowing generation of an asynchronous signal for a thread +would have introduced an exception to the overall signal +model. This requires a compelling reason in order to be justified. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +alarm , \fIexec\fP() , \fIfork\fP() , \fIgetitimer\fP() , \fIpause\fP() +, \fIsigaction\fP() , \fIsleep\fP() , \fIualarm\fP() +, \fIusleep\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/asctime.3p b/man3p/asctime.3p new file mode 100644 index 000000000..5da1ee786 --- /dev/null +++ b/man3p/asctime.3p @@ -0,0 +1,140 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ASCTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" asctime +.SH NAME +asctime, asctime_r \- convert date and time to a string +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *asctime(const struct tm *\fP\fItimeptr\fP\fB); +.br +\fP +.LP +\fBchar *asctime_r(const struct tm *restrict\fP \fItm\fP\fB, char +*restrict\fP \fIbuf\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +For \fIasctime\fP(): The functionality described on this reference +page is aligned with the ISO\ C standard. Any +conflict between the requirements described here and the ISO\ C standard +is unintentional. This volume of +IEEE\ Std\ 1003.1-2001 defers to the ISO\ C standard. +.LP +The \fIasctime\fP() function shall convert the broken-down time in +the structure pointed to by \fItimeptr\fP into a string in +the form: +.sp +.RS +.nf + +\fBSun Sep 16 01:03:52 1973\\n\\0 +\fP +.fi +.RE +.LP +using the equivalent of the following algorithm: +.sp +.RS +.nf + +\fBchar *asctime(const struct tm *timeptr) +{ + static char wday_name[7][3] = { + "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" + }; + static char mon_name[12][3] = { + "Jan", "Feb", "Mar", "Apr", "May", "Jun", + "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" + }; + static char result[26]; +.sp + + sprintf(result, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\\n", + wday_name[timeptr->tm_wday], + mon_name[timeptr->tm_mon], + timeptr->tm_mday, timeptr->tm_hour, + timeptr->tm_min, timeptr->tm_sec, + 1900 + timeptr->tm_year); + return result; +} +\fP +.fi +.RE +.LP +The \fBtm\fP structure is defined in the \fI\fP header. +.LP +The +\fIasctime\fP(), \fIctime\fP(), \fIgmtime\fP(), and +\fIlocaltime\fP() functions shall return values in one of two static +objects: a +broken-down time structure and an array of type \fBchar\fP. Execution +of any of the functions may overwrite the information +returned in either of these objects by any of the other functions. +.LP +The \fIasctime\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.LP +The \fIasctime_r\fP() function shall convert the broken-down time +in the structure pointed to by \fItm\fP into a string (of the +same form as that returned by \fIasctime\fP()) that is placed in the +user-supplied buffer pointed to by \fIbuf\fP (which shall +contain at least 26 bytes) and then return \fIbuf\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIasctime\fP() shall return a pointer +to the string. +.LP +Upon successful completion, \fIasctime_r\fP() shall return a pointer +to a character string containing the date and time. This +string is pointed to by the argument \fIbuf\fP. If the function is +unsuccessful, it shall return NULL. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Values for the broken-down time structure can be obtained by calling +\fIgmtime\fP() or +\fIlocaltime\fP(). This function is included for compatibility with +older +implementations, and does not support localized date and time formats. +Applications should use \fIstrftime\fP() to achieve maximum portability. +.LP +The \fIasctime_r\fP() function is thread-safe and shall return values +in a user-supplied buffer instead of possibly using a +static data area that may be overwritten by each call. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclock\fP() , \fIctime\fP() , \fIdifftime\fP() , \fIgmtime\fP() +, \fIlocaltime\fP() +, \fImktime\fP() , \fIstrftime\fP() , \fIstrptime\fP() , \fItime\fP() +, \fIutime\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/asctime_r.3p b/man3p/asctime_r.3p new file mode 100644 index 000000000..bec3ea3c2 --- /dev/null +++ b/man3p/asctime_r.3p @@ -0,0 +1 @@ +.so man3p/asctime.3p diff --git a/man3p/asin.3p b/man3p/asin.3p new file mode 100644 index 000000000..46f30ccc4 --- /dev/null +++ b/man3p/asin.3p @@ -0,0 +1,109 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ASIN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" asin +.SH NAME +asin, asinf, asinl \- arc sine function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double asin(double\fP \fIx\fP\fB); +.br +float asinf(float\fP \fIx\fP\fB); +.br +long double asinl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the principal value of the arc sine +of their argument \fIx\fP. The value of \fIx\fP should be in +the range [-1,1]. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the arc sine +of \fIx\fP, in the range [-pi/2,pi/2] radians. +.LP +For finite values of \fIx\fP not in the range [-1,1], a domain error +shall occur, and \ either a NaN +(if supported), or \ an implementation-defined value shall be +returned. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, \fIx\fP shall be returned. +.LP +If \fIx\fP is \(+-Inf, a domain error shall occur, and either a NaN +(if supported), or an implementation-defined value +shall be returned. +.LP +If \fIx\fP is subnormal, a range error may occur and \fIx\fP should +be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The \fIx\fP argument is finite and is not in the range [-1,1], \ or +is \(+-Inf. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be +raised. +.sp +.LP +These functions may fail if: +.TP 7 +Range\ Error +The value of \fIx\fP is subnormal. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() , \fIsin\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/asinf.3p b/man3p/asinf.3p new file mode 100644 index 000000000..6af1cbea5 --- /dev/null +++ b/man3p/asinf.3p @@ -0,0 +1 @@ +.so man3p/asin.3p diff --git a/man3p/asinh.3p b/man3p/asinh.3p new file mode 100644 index 000000000..597102083 --- /dev/null +++ b/man3p/asinh.3p @@ -0,0 +1,84 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ASINH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" asinh +.SH NAME +asinh, asinhf, asinhl \- inverse hyperbolic sine functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double asinh(double\fP \fIx\fP\fB); +.br +float asinhf(float\fP \fIx\fP\fB); +.br +long double asinhl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the inverse hyperbolic sine of their +argument \fIx\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the inverse +hyperbolic sine of their argument. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, or \(+-Inf, \fIx\fP shall be returned. +.LP +If \fIx\fP is subnormal, a range error may occur and \fIx\fP should +be returned. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +Range\ Error +The value of \fIx\fP is subnormal. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIsinh\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/asinhf.3p b/man3p/asinhf.3p new file mode 100644 index 000000000..7932c6603 --- /dev/null +++ b/man3p/asinhf.3p @@ -0,0 +1 @@ +.so man3p/asinh.3p diff --git a/man3p/asinhl.3p b/man3p/asinhl.3p new file mode 100644 index 000000000..7932c6603 --- /dev/null +++ b/man3p/asinhl.3p @@ -0,0 +1 @@ +.so man3p/asinh.3p diff --git a/man3p/asinl.3p b/man3p/asinl.3p new file mode 100644 index 000000000..6af1cbea5 --- /dev/null +++ b/man3p/asinl.3p @@ -0,0 +1 @@ +.so man3p/asin.3p diff --git a/man3p/assert.3p b/man3p/assert.3p new file mode 100644 index 000000000..a26efffee --- /dev/null +++ b/man3p/assert.3p @@ -0,0 +1,67 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ASSERT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" assert +.SH NAME +assert \- insert program diagnostics +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void assert(scalar\fP \fIexpression\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIassert\fP() macro shall insert diagnostics into programs; it +shall expand to a \fBvoid\fP expression. When it is +executed, if \fIexpression\fP (which shall have a \fBscalar\fP type) +is false (that is, compares equal to 0), \fIassert\fP() +shall write information about the particular call that failed on \fIstderr\fP +and shall call \fIabort\fP(). +.LP +The information written about the call that failed shall include the +text of the argument, the name of the source file, the +source file line number, and the name of the enclosing function; the +latter are, respectively, the values of the preprocessing +macros __FILE__ and __LINE__ and of the identifier __func__. +.LP +Forcing a definition of the name NDEBUG, either from the compiler +command line or with the preprocessor control statement +\fB#define\fP NDEBUG ahead of the \fB#include\fP \fI\fP +statement, shall +stop assertions from being compiled into the program. +.SH RETURN VALUE +.LP +The \fIassert\fP() macro shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIabort\fP() , \fIstderr\fP, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/atan.3p b/man3p/atan.3p new file mode 100644 index 000000000..26d50cd40 --- /dev/null +++ b/man3p/atan.3p @@ -0,0 +1,87 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ATAN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" atan +.SH NAME +atan, atanf, atanl \- arc tangent function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double atan(double\fP \fIx\fP\fB); +.br +float atanf(float\fP \fIx\fP\fB); +.br +long double atanl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the principal value of the arc tangent +of their argument \fIx\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the arc tangent +of \fIx\fP in the range [-pi/2,pi/2] radians. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, \fIx\fP shall be returned. +.LP +If \fIx\fP is \(+-Inf, \(+-pi/2 shall be returned. +.LP +If \fIx\fP is subnormal, a range error may occur and \fIx\fP should +be returned. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +Range\ Error +The value of \fIx\fP is subnormal. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIatan2\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() +, \fItan\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/atan2.3p b/man3p/atan2.3p new file mode 100644 index 000000000..81c838cdd --- /dev/null +++ b/man3p/atan2.3p @@ -0,0 +1,115 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ATAN2" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" atan2 +.SH NAME +atan2, atan2f, atan2l \- arc tangent functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double atan2(double\fP \fIy\fP\fB, double\fP \fIx\fP\fB); +.br +float atan2f(float\fP \fIy\fP\fB, float\fP \fIx\fP\fB); +.br +long double atan2l(long double\fP \fIy\fP\fB, long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the principal value of the arc tangent +of \fIy\fP/ \fIx\fP, using the signs of both arguments to +determine the quadrant of the return value. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the arc tangent +of \fIy\fP/ \fIx\fP in the range [-pi,pi] radians. +.LP +If \fIy\fP is \(+-0 and \fIx\fP is < 0, \(+-pi shall be returned. +.LP +If \fIy\fP is \(+-0 and \fIx\fP is > 0, \(+-0 shall be returned. +.LP +If \fIy\fP is < 0 and \fIx\fP is \(+-0, -pi/2 shall be returned. +.LP +If \fIy\fP is > 0 and \fIx\fP is \(+-0, pi/2 shall be returned. +.LP +If \fIx\fP is 0, a pole error shall not occur. +.LP +If +either \fIx\fP or \fIy\fP is NaN, a NaN shall be returned. +.LP +If the result underflows, a range error may occur and \fIy\fP/ \fIx\fP +should be returned. +.LP +If \fIy\fP is \(+-0 and \fIx\fP is -0, \(+-pi shall be returned. +.LP +If \fIy\fP is \(+-0 and \fIx\fP is +0, \(+-0 shall be returned. +.LP +For finite values of \(+- \fIy\fP > 0, if \fIx\fP is -Inf, \(+-pi +shall be +returned. +.LP +For finite values of \(+- \fIy\fP > 0, if \fIx\fP is +Inf, \(+-0 shall +be returned. +.LP +For finite values of \fIx\fP, if \fIy\fP is \(+-Inf, \(+-pi/2 shall +be +returned. +.LP +If \fIy\fP is \(+-Inf and \fIx\fP is -Inf, \(+-3pi/4 shall be returned. +.LP +If \fIy\fP is \(+-Inf and \fIx\fP is +Inf, \(+-pi/4 shall be returned. +.LP +If both arguments are 0, a domain error shall not occur. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +Range\ Error +The result underflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIatan\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() +, \fItan\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/atan2f.3p b/man3p/atan2f.3p new file mode 100644 index 000000000..6a6dd83f1 --- /dev/null +++ b/man3p/atan2f.3p @@ -0,0 +1 @@ +.so man3p/atan2.3p diff --git a/man3p/atan2l.3p b/man3p/atan2l.3p new file mode 100644 index 000000000..6a6dd83f1 --- /dev/null +++ b/man3p/atan2l.3p @@ -0,0 +1 @@ +.so man3p/atan2.3p diff --git a/man3p/atanf.3p b/man3p/atanf.3p new file mode 100644 index 000000000..b87fd3aa7 --- /dev/null +++ b/man3p/atanf.3p @@ -0,0 +1 @@ +.so man3p/atan.3p diff --git a/man3p/atanh.3p b/man3p/atanh.3p new file mode 100644 index 000000000..18f7cc75d --- /dev/null +++ b/man3p/atanh.3p @@ -0,0 +1,120 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ATANH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" atanh +.SH NAME +atanh, atanhf, atanhl \- inverse hyperbolic tangent functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double atanh(double\fP \fIx\fP\fB); +.br +float atanhf(float\fP \fIx\fP\fB); +.br +long double atanhl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the inverse hyperbolic tangent of their +argument \fIx\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the inverse +hyperbolic tangent of their argument. +.LP +If \fIx\fP is \(+-1, a pole error shall occur, and \fIatanh\fP(), +\fIatanhf\fP(), and \fIatanhl\fP() shall return the +value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, respectively, +with the same sign as the correct value of the function. +.LP +For finite |\fIx\fP|>1, a domain error shall occur, and \ either +a NaN (if supported), or \ an implementation-defined value shall +be returned. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, \fIx\fP shall be returned. +.LP +If \fIx\fP is \(+-Inf, a domain error shall occur, and either a NaN +(if supported), or an implementation-defined value +shall be returned. +.LP +If \fIx\fP is subnormal, a range error may occur and \fIx\fP should +be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The \fIx\fP argument is finite and not in the range [-1,1], \ or +is \(+-Inf. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be +raised. +.TP 7 +Pole\ Error +The \fIx\fP argument is \(+-1. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the divide-by-zero floating-point exception shall be +raised. +.sp +.sp +.LP +These functions may fail if: +.TP 7 +Range\ Error +The value of \fIx\fP is subnormal. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fItanh\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/atanhf.3p b/man3p/atanhf.3p new file mode 100644 index 000000000..a7a2ec15a --- /dev/null +++ b/man3p/atanhf.3p @@ -0,0 +1 @@ +.so man3p/atanh.3p diff --git a/man3p/atanhl.3p b/man3p/atanhl.3p new file mode 100644 index 000000000..a7a2ec15a --- /dev/null +++ b/man3p/atanhl.3p @@ -0,0 +1 @@ +.so man3p/atanh.3p diff --git a/man3p/atanl.3p b/man3p/atanl.3p new file mode 100644 index 000000000..b87fd3aa7 --- /dev/null +++ b/man3p/atanl.3p @@ -0,0 +1 @@ +.so man3p/atan.3p diff --git a/man3p/atexit.3p b/man3p/atexit.3p new file mode 100644 index 000000000..f7de705cf --- /dev/null +++ b/man3p/atexit.3p @@ -0,0 +1,71 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ATEXIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" atexit +.SH NAME +atexit \- register a function to run at process termination +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int atexit(void (*\fP\fIfunc\fP\fB)(void)); +.br +\fP +.SH DESCRIPTION +.LP +The \fIatexit\fP() function shall register the function pointed to +by \fIfunc\fP, to be called without arguments at normal +program termination. At normal program termination, all functions +registered by the \fIatexit\fP() function shall be called, in +the reverse order of their registration, except that a function is +called after any previously registered functions that had +already been called at the time it was registered. Normal termination +occurs either by a call to \fIexit\fP() or a return from \fImain\fP(). +.LP +At least 32 functions can be registered with \fIatexit\fP(). +.LP +After a successful call to any of the \fIexec\fP functions, any functions +previously +registered by \fIatexit\fP() shall no longer be registered. +.SH RETURN VALUE +.LP +Upon successful completion, \fIatexit\fP() shall return 0; otherwise, +it shall return a non-zero value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The functions registered by a call to \fIatexit\fP() must return to +ensure that all registered functions are called. +.LP +The application should call \fIsysconf\fP() to obtain the value of +{ATEXIT_MAX}, the +number of functions that can be registered. There is no way for an +application to tell how many functions have already been +registered with \fIatexit\fP(). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexit\fP() , \fIsysconf\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/atof.3p b/man3p/atof.3p new file mode 100644 index 000000000..1f6237826 --- /dev/null +++ b/man3p/atof.3p @@ -0,0 +1,67 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ATOF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" atof +.SH NAME +atof \- convert a string to a double-precision number +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double atof(const char *\fP\fIstr\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The call \fIatof\fP(\fIstr\fP) shall be equivalent to: +.sp +.RS +.nf + +\fBstrtod(\fP\fIstr\fP\fB,(char **)NULL), +\fP +.fi +.RE +.LP +except that the handling of errors may differ. If the value cannot +be represented, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIatof\fP() function shall return the converted value if the +value can be represented. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIatof\fP() function is subsumed by \fIstrtod\fP() but is retained +because it is +used extensively in existing code. If the number is not known to be +in range, \fIstrtod\fP() should be used because \fIatof\fP() is not +required to perform any error +checking. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrtod\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/atoi.3p b/man3p/atoi.3p new file mode 100644 index 000000000..78375b66a --- /dev/null +++ b/man3p/atoi.3p @@ -0,0 +1,87 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ATOI" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" atoi +.SH NAME +atoi \- convert a string to an integer +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int atoi(const char *\fP\fIstr\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The call \fIatoi\fP(\fIstr\fP) shall be equivalent to: +.sp +.RS +.nf + +\fB(int) strtol(str, (char **)NULL, 10) +\fP +.fi +.RE +.LP +except that the handling of errors may differ. If the value cannot +be represented, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIatoi\fP() function shall return the converted value if the +value can be represented. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Converting an Argument +.LP +The following example checks for proper usage of the program. If there +is an argument and the decimal conversion of this +argument (obtained using \fIatoi\fP()) is greater than 0, then the +program has a valid number of minutes to wait for an event. +.sp +.RS +.nf + +\fB#include +#include +\&... +int minutes_to_event; +\&... +if (argc < 2 || ((minutes_to_event = atoi (argv[1]))) <= 0) { + fprintf(stderr, "Usage: %s minutes\\n", argv[0]); exit(1); +} +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIatoi\fP() function is subsumed by \fIstrtol\fP() but is retained +because it is +used extensively in existing code. If the number is not known to be +in range, \fIstrtol\fP() should be used because \fIatoi\fP() is not +required to perform any error +checking. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrtol\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/atol.3p b/man3p/atol.3p new file mode 100644 index 000000000..855b656ef --- /dev/null +++ b/man3p/atol.3p @@ -0,0 +1,79 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ATOL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" atol +.SH NAME +atol, atoll \- convert a string to a long integer +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +long atol(const char *\fP\fIstr\fP\fB); +.br +long long atoll(const char *\fP\fInptr\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The call \fIatol\fP(\fIstr\fP) shall be equivalent to: +.sp +.RS +.nf + +\fBstrtol(str, (char **)NULL, 10) +\fP +.fi +.RE +.LP +The call \fIatoll\fP(\fIstr\fP) shall be equivalent to: +.sp +.RS +.nf + +\fBstrtoll(nptr, (char **)NULL, 10) +\fP +.fi +.RE +.LP +except that the handling of errors may differ. If the value cannot +be represented, the behavior is undefined. +.SH RETURN VALUE +.LP +These functions shall return the converted value if the value can +be represented. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIatol\fP() function is subsumed by \fIstrtol\fP() but is retained +because it is +used extensively in existing code. If the number is not known to be +in range, \fIstrtol\fP() should be used because \fIatol\fP() is not +required to perform any error +checking. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrtol\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/atoll.3p b/man3p/atoll.3p new file mode 100644 index 000000000..b46543304 --- /dev/null +++ b/man3p/atoll.3p @@ -0,0 +1 @@ +.so man3p/atol.3p diff --git a/man3p/basename.3p b/man3p/basename.3p new file mode 100644 index 000000000..aba37f64f --- /dev/null +++ b/man3p/basename.3p @@ -0,0 +1,104 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "BASENAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" basename +.SH NAME +basename \- return the last component of a pathname +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *basename(char *\fP\fIpath\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIbasename\fP() function shall take the pathname pointed to by +\fIpath\fP and return a pointer to the final component of +the pathname, deleting any trailing \fB'/'\fP characters. +.LP +If the string consists entirely of the \fB'/'\fP character, \fIbasename\fP() +shall return a pointer to the string +\fB"/"\fP . If the string is exactly \fB"//"\fP , it is implementation-defined +whether \fB'/'\fP or \fB"//"\fP is +returned. +.LP +If \fIpath\fP is a null pointer or points to an empty string, \fIbasename\fP() +shall return a pointer to the string +\fB"."\fP . +.LP +The \fIbasename\fP() function may modify the string pointed to by +\fIpath\fP, and may return a pointer to static storage that +may then be overwritten by a subsequent call to \fIbasename\fP(). +.LP +The \fIbasename\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +The \fIbasename\fP() function shall return a pointer to the final +component of \fIpath\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Using basename() +.LP +The following program fragment returns a pointer to the value \fIlib\fP, +which is the base name of \fB/usr/lib\fP. +.sp +.RS +.nf + +\fB#include +\&... +char *name = "/usr/lib"; +char *base; +.sp + +base = basename(name); +\&... +\fP +.fi +.RE +.SS Sample Input and Output Strings for basename() +.LP +In the following table, the input string is the value pointed to by +\fIpath\fP, and the output string is the return value of +the \fIbasename\fP() function. +.TS C +center; l l. +\fBInput String\fP \fBOutput String\fP +"/usr/lib" "lib" +"/usr/" "usr" +"/" "/" +"///" "/" +"//usr//lib//" "lib" +.TE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIdirname\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, the Shell and Utilities volume of IEEE\ Std\ 1003.1-2001, +\fIbasename\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/bcmp.3p b/man3p/bcmp.3p new file mode 100644 index 000000000..ae0417e28 --- /dev/null +++ b/man3p/bcmp.3p @@ -0,0 +1,68 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "BCMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" bcmp +.SH NAME +bcmp \- memory operations (\fBLEGACY\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int bcmp(const void *\fP\fIs1\fP\fB, const void *\fP\fIs2\fP\fB, size_t\fP +\fIn\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIbcmp\fP() function shall compare the first \fIn\fP bytes of +the area pointed to by \fIs1\fP with the area pointed to +by \fIs2\fP. +.SH RETURN VALUE +.LP +The \fIbcmp\fP() function shall return 0 if \fIs1\fP and \fIs2\fP +are identical; otherwise, it shall return non-zero. Both +areas are assumed to be \fIn\fP bytes long. If the value of \fIn\fP +is 0, \fIbcmp\fP() shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fImemcmp\fP() function is preferred over this function. +.LP +For maximum portability, it is recommended to replace the function +call to \fIbcmp\fP() as follows: +.sp +.RS +.nf + +\fB#define bcmp(b1,b2,len) memcmp((b1), (b2), (size_t)(len)) +\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +This function may be withdrawn in a future version. +.SH SEE ALSO +.LP +\fImemcmp\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/bcopy.3p b/man3p/bcopy.3p new file mode 100644 index 000000000..a34e92013 --- /dev/null +++ b/man3p/bcopy.3p @@ -0,0 +1,79 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "BCOPY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" bcopy +.SH NAME +bcopy \- memory operations (\fBLEGACY\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void bcopy(const void *\fP\fIs1\fP\fB, void *\fP\fIs2\fP\fB, size_t\fP +\fIn\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIbcopy\fP() function shall copy \fIn\fP bytes from the area +pointed to by \fIs1\fP to the area pointed to by +\fIs2\fP. +.LP +The bytes are copied correctly even if the area pointed to by \fIs1\fP +overlaps the area pointed to by \fIs2\fP. +.SH RETURN VALUE +.LP +The \fIbcopy\fP() function shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fImemmove\fP() function is preferred over this function. +.LP +The following are approximately equivalent (note the order of the +arguments): +.sp +.RS +.nf + +\fBbcopy(s1,s2,n) ~= memmove(s2,s1,n) +\fP +.fi +.RE +.LP +For maximum portability, it is recommended to replace the function +call to \fIbcopy\fP() as follows: +.sp +.RS +.nf + +\fB#define bcopy(b1,b2,len) (memmove((b2), (b1), (len)), (void) 0) +\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +This function may be withdrawn in a future version. +.SH SEE ALSO +.LP +\fImemmove\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/bind.3p b/man3p/bind.3p new file mode 100644 index 000000000..2659c7589 --- /dev/null +++ b/man3p/bind.3p @@ -0,0 +1,164 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "BIND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" bind +.SH NAME +bind \- bind a name to a socket +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int bind(int\fP \fIsocket\fP\fB, const struct sockaddr *\fP\fIaddress\fP\fB, +.br +\ \ \ \ \ \ socklen_t\fP \fIaddress_len\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIbind\fP() function shall assign a local socket address \fIaddress\fP +to a socket identified by descriptor \fIsocket\fP +that has no local socket address assigned. Sockets created with the +\fIsocket\fP() function +are initially unnamed; they are identified only by their address family. +.LP +The \fIbind\fP() function takes the following arguments: +.TP 7 +\fIsocket\fP +Specifies the file descriptor of the socket to be bound. +.TP 7 +\fIaddress\fP +Points to a \fBsockaddr\fP structure containing the address to be +bound to the socket. The length and format of the address +depend on the address family of the socket. +.TP 7 +\fIaddress_len\fP +Specifies the length of the \fBsockaddr\fP structure pointed to by +the \fIaddress\fP argument. +.sp +.LP +The socket specified by \fIsocket\fP may require the process to have +appropriate privileges to use the \fIbind\fP() +function. +.SH RETURN VALUE +.LP +Upon successful completion, \fIbind\fP() shall return 0; otherwise, +-1 shall be returned and \fIerrno\fP set to indicate the +error. +.SH ERRORS +.LP +The \fIbind\fP() function shall fail if: +.TP 7 +.B EADDRINUSE +The specified address is already in use. +.TP 7 +.B EADDRNOTAVAIL +The specified address is not available from the local machine. +.TP 7 +.B EAFNOSUPPORT +The specified address is not a valid address for the address family +of the specified socket. +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid file descriptor. +.TP 7 +.B EINVAL +The socket is already bound to an address, and the protocol does not +support binding to a new address; or the socket has been +shut down. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.TP 7 +.B EOPNOTSUPP +The socket type of the specified socket does not support binding to +an address. +.sp +.LP +If the address family of the socket is AF_UNIX, then \fIbind\fP() +shall fail if: +.TP 7 +.B EACCES +A component of the path prefix denies search permission, or the requested +name requires writing in a directory with a mode that +denies write permission. +.TP 7 +.B EDESTADDRREQ \fRor\fP EISDIR +The \fIaddress\fP argument is a null pointer. +.TP 7 +.B EIO +An I/O error occurred. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +pathname in \fIaddress\fP. +.TP 7 +.B ENAMETOOLONG +A component of a pathname exceeded {NAME_MAX} characters, or an entire +pathname exceeded {PATH_MAX} characters. +.TP 7 +.B ENOENT +A component of the pathname does not name an existing file or the +pathname is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix of the pathname in \fIaddress\fP is +not a directory. +.TP 7 +.B EROFS +The name would reside on a read-only file system. +.sp +.LP +The \fIbind\fP() function may fail if: +.TP 7 +.B EACCES +The specified address is protected and the current user does not have +permission to bind to it. +.TP 7 +.B EINVAL +The \fIaddress_len\fP argument is not a valid length for the address +family. +.TP 7 +.B EISCONN +The socket is already connected. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the pathname in \fIaddress\fP. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.TP 7 +.B ENOBUFS +Insufficient resources were available to complete the call. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +An application program can retrieve the assigned socket name with +the \fIgetsockname\fP() function. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIconnect\fP() , \fIgetsockname\fP() , \fIlisten\fP() , \fIsocket\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/bsd_signal.3p b/man3p/bsd_signal.3p new file mode 100644 index 000000000..b6a0e5992 --- /dev/null +++ b/man3p/bsd_signal.3p @@ -0,0 +1,108 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "BSD_SIGNAL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" bsd_signal +.SH NAME +bsd_signal \- simplified signal facilities +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void (*bsd_signal(int\fP \fIsig\fP\fB, void (*\fP\fIfunc\fP\fB)(int)))(int); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIbsd_signal\fP() function provides a partially compatible interface +for programs written to historical system interfaces +(see APPLICATION USAGE). +.LP +The function call \fIbsd_signal\fP(\fIsig\fP, \fIfunc\fP) shall be +equivalent to the following: +.sp +.RS +.nf + +\fBvoid (*bsd_signal(int sig, void (*func)(int)))(int) +{ + struct sigaction act, oact; +.sp + + act.sa_handler =\fP \fIfunc\fP\fB; + act.sa_flags = SA_RESTART; + + sigemptyset(&act.sa_mask); + sigaddset(&act.sa_mask,\fP \fIsig\fP\fB); + if (sigaction(\fP\fIsig\fP\fB, &act, &oact) == -1) + return(SIG_ERR); + + return(oact.sa_handler); +} +\fP +.fi +.RE +.LP +The handler function should be declared: +.sp +.RS +.nf + +\fBvoid handler(int\fP \fIsig\fP\fB); +\fP +.fi +.RE +.LP +where \fIsig\fP is the signal number. The behavior is undefined if +\fIfunc\fP is a function that takes more than one argument, +or an argument of a different type. +.SH RETURN VALUE +.LP +Upon successful completion, \fIbsd_signal\fP() shall return the previous +action for \fIsig\fP. Otherwise, SIG_ERR shall be +returned and \fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +Refer to \fIsigaction\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +This function is a direct replacement for the BSD \fIsignal\fP() function +for simple +applications that are installing a single-argument signal handler +function. If a BSD signal handler function is being installed +that expects more than one argument, the application has to be modified +to use \fIsigaction\fP(). The \fIbsd_signal\fP() function differs +from \fIsignal\fP() in that the SA_RESTART flag is set and the SA_RESETHAND +is clear when +\fIbsd_signal\fP() is used. The state of these flags is not specified +for \fIsignal\fP(). +.LP +It is recommended that new applications use the \fIsigaction\fP() +function. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsigaction\fP() , \fIsigaddset\fP() , \fIsigemptyset\fP() , \fIsignal\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/bsearch.3p b/man3p/bsearch.3p new file mode 100644 index 000000000..de8aa8f5f --- /dev/null +++ b/man3p/bsearch.3p @@ -0,0 +1,173 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "BSEARCH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" bsearch +.SH NAME +bsearch \- binary search a sorted table +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void *bsearch(const void *\fP\fIkey\fP\fB, const void *\fP\fIbase\fP\fB, +size_t\fP \fInel\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIwidth\fP\fB, int (*\fP\fIcompar\fP\fB)(const +void *, const void *)); +.br +\fP +.SH DESCRIPTION +.LP +The \fIbsearch\fP() function shall search an array of \fInel\fP objects, +the initial element of which is pointed to by +\fIbase\fP, for an element that matches the object pointed to by \fIkey\fP. +The size of each element in the array is specified by +\fIwidth\fP. If the \fInel\fP argument has the value zero, the comparison +function pointed to by \fIcompar\fP shall not be +called and no match shall be found. +.LP +The comparison function pointed to by \fIcompar\fP shall be called +with two arguments that point to the \fIkey\fP object and +to an array element, in that order. +.LP +The application shall ensure that the comparison function pointed +to by \fIcompar\fP does not alter the contents of the array. +The implementation may reorder elements of the array between calls +to the comparison function, but shall not alter the contents of +any individual element. +.LP +The implementation shall ensure that the first argument is always +a pointer to the key. +.LP +When the same objects (consisting of width bytes, irrespective of +their current positions in the array) are passed more than +once to the comparison function, the results shall be consistent with +one another. That is, the same object shall always compare +the same way with the key. +.LP +The application shall ensure that the function returns an integer +less than, equal to, or greater than 0 if the \fIkey\fP +object is considered, respectively, to be less than, to match, or +to be greater than the array element. The application shall +ensure that the array consists of all the elements that compare less +than, all the elements that compare equal to, and all the +elements that compare greater than the \fIkey\fP object, in that order. +.SH RETURN VALUE +.LP +The \fIbsearch\fP() function shall return a pointer to a matching +member of the array, or a null pointer if no match is found. +If two or more members compare equal, which member is returned is +unspecified. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The example below searches a table containing pointers to nodes consisting +of a string and its length. The table is ordered +alphabetically on the string in the node pointed to by each entry. +.LP +The code fragment below reads in strings and either finds the corresponding +node and prints out the string and its length, or +prints an error message. +.sp +.RS +.nf + +\fB#include +#include +#include +.sp + +#define TABSIZE 1000 + +.sp + +struct node { /* These are stored in the table. */ + char *string; + int length; +}; +struct node table[TABSIZE]; /* Table to be searched. */ + . + . + . +{ + struct node *node_ptr, node; + /* Routine to compare 2 nodes. */ + int node_compare(const void *, const void *); + char str_space[20]; /* Space to read string into. */ + . + . + . + node.string = str_space; + while (scanf("%s", node.string) != EOF) { + node_ptr = (struct node *)bsearch((void *)(&node), + (void *)table, TABSIZE, + sizeof(struct node), node_compare); + if (node_ptr != NULL) { + (void)printf("string = %20s, length = %d\\n", + node_ptr->string, node_ptr->length); + } else { + (void)printf("not found: %s\\n", node.string); + } + } +} +/* + This routine compares two nodes based on an + alphabetical ordering of the string field. +*/ +int +node_compare(const void *node1, const void *node2) +{ + return strcoll(((const struct node *)node1)->string, + ((const struct node *)node2)->string); +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The pointers to the key and the element at the base of the table should +be of type pointer-to-element. +.LP +The comparison function need not compare every byte, so arbitrary +data may be contained in the elements in addition to the +values being compared. +.LP +In practice, the array is usually sorted according to the comparison +function. +.SH RATIONALE +.LP +The requirement that the second argument (hereafter referred to as +\fIp\fP) to the comparison function is a pointer to an +element of the array implies that for every call all of the following +expressions are non-zero: +.sp +.RS +.nf + +\fB((char *)p - (char *(base) % width == 0 +(char *)p >= (char *)base +(char *)p < (char *)base + nel * width +\fP +.fi +.RE +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIhcreate\fP() , \fIlsearch\fP() , \fIqsort\fP() , \fItsearch\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/btowc.3p b/man3p/btowc.3p new file mode 100644 index 000000000..b25a77b05 --- /dev/null +++ b/man3p/btowc.3p @@ -0,0 +1,61 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "BTOWC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" btowc +.SH NAME +btowc \- single byte to wide character conversion +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +wint_t btowc(int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIbtowc\fP() function shall determine whether \fIc\fP constitutes +a valid (one-byte) character in the initial shift +state. +.LP +The behavior of this function shall be affected by the \fILC_CTYPE\fP +category of the current locale. +.SH RETURN VALUE +.LP +The \fIbtowc\fP() function shall return WEOF if \fIc\fP has the value +EOF or if \fB(unsigned char)\fP \fIc\fP does not +constitute a valid (one-byte) character in the initial shift state. +Otherwise, it shall return the wide-character representation of +that character. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwctob\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/bzero.3p b/man3p/bzero.3p new file mode 100644 index 000000000..49c6bd21a --- /dev/null +++ b/man3p/bzero.3p @@ -0,0 +1,63 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "BZERO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" bzero +.SH NAME +bzero \- memory operations (\fBLEGACY\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void bzero(void *\fP\fIs\fP\fB, size_t\fP \fIn\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIbzero\fP() function shall place \fIn\fP zero-valued bytes in +the area pointed to by \fIs\fP. +.SH RETURN VALUE +.LP +The \fIbzero\fP() function shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fImemset\fP() function is preferred over this function. +.LP +For maximum portability, it is recommended to replace the function +call to \fIbzero\fP() as follows: +.sp +.RS +.nf + +\fB#define bzero(b,len) (memset((b), '\\0', (len)), (void) 0) +\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +This function may be withdrawn in a future version. +.SH SEE ALSO +.LP +\fImemset\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/cabs.3p b/man3p/cabs.3p new file mode 100644 index 000000000..7c3b4853d --- /dev/null +++ b/man3p/cabs.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CABS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cabs +.SH NAME +cabs, cabsf, cabsl \- return a complex absolute value +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double cabs(double complex\fP \fIz\fP\fB); +.br +float cabsf(float complex\fP \fIz\fP\fB); +.br +long double cabsl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex absolute value (also called +norm, modulus, or magnitude) of \fIz\fP. +.SH RETURN VALUE +.LP +These functions shall return the complex absolute value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/cabsf.3p b/man3p/cabsf.3p new file mode 100644 index 000000000..c1bf1c682 --- /dev/null +++ b/man3p/cabsf.3p @@ -0,0 +1 @@ +.so man3p/cabs.3p diff --git a/man3p/cabsl.3p b/man3p/cabsl.3p new file mode 100644 index 000000000..c1bf1c682 --- /dev/null +++ b/man3p/cabsl.3p @@ -0,0 +1 @@ +.so man3p/cabs.3p diff --git a/man3p/cacos.3p b/man3p/cacos.3p new file mode 100644 index 000000000..4a238734a --- /dev/null +++ b/man3p/cacos.3p @@ -0,0 +1,58 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CACOS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cacos +.SH NAME +cacos, cacosf, cacosl \- complex arc cosine functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex cacos(double complex\fP \fIz\fP\fB); +.br +float complex cacosf(float complex\fP \fIz\fP\fB); +.br +long double complex cacosl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex arc cosine of \fIz\fP, with +branch cuts outside the interval [-1,\ +1] along the +real axis. +.SH RETURN VALUE +.LP +These functions shall return the complex arc cosine value, in the +range of a strip mathematically unbounded along the imaginary +axis and in the interval [0,\ pi] along the real axis. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIccos\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/cacosf.3p b/man3p/cacosf.3p new file mode 100644 index 000000000..8d774f328 --- /dev/null +++ b/man3p/cacosf.3p @@ -0,0 +1 @@ +.so man3p/cacos.3p diff --git a/man3p/cacosh.3p b/man3p/cacosh.3p new file mode 100644 index 000000000..a452f6c0c --- /dev/null +++ b/man3p/cacosh.3p @@ -0,0 +1,59 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CACOSH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cacosh +.SH NAME +cacosh, cacoshf, cacoshl \- complex arc hyperbolic cosine functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex cacosh(double complex\fP \fIz\fP\fB); +.br +float complex cacoshf(float complex\fP \fIz\fP\fB); +.br +long double complex cacoshl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex arc hyperbolic cosine of +\fIz\fP, with a branch cut at values less than 1 along the +real axis. +.SH RETURN VALUE +.LP +These functions shall return the complex arc hyperbolic cosine value, +in the range of a half-strip of non-negative values along +the real axis and in the interval [-\fIi\fPpi,\ +\fIi\fPpi] along +the imaginary axis. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIccosh\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/cacoshf.3p b/man3p/cacoshf.3p new file mode 100644 index 000000000..a5fb1e0e0 --- /dev/null +++ b/man3p/cacoshf.3p @@ -0,0 +1 @@ +.so man3p/cacosh.3p diff --git a/man3p/cacoshl.3p b/man3p/cacoshl.3p new file mode 100644 index 000000000..a5fb1e0e0 --- /dev/null +++ b/man3p/cacoshl.3p @@ -0,0 +1 @@ +.so man3p/cacosh.3p diff --git a/man3p/cacosl.3p b/man3p/cacosl.3p new file mode 100644 index 000000000..8d774f328 --- /dev/null +++ b/man3p/cacosl.3p @@ -0,0 +1 @@ +.so man3p/cacos.3p diff --git a/man3p/calloc.3p b/man3p/calloc.3p new file mode 100644 index 000000000..17a4368e6 --- /dev/null +++ b/man3p/calloc.3p @@ -0,0 +1,76 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CALLOC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" calloc +.SH NAME +calloc \- a memory allocator +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void *calloc(size_t\fP \fInelem\fP\fB, size_t\fP \fIelsize\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIcalloc\fP() function shall allocate unused space for an array +of \fInelem\fP elements each of whose size in bytes is +\fIelsize\fP. The space shall be initialized to all bits 0. +.LP +The order and contiguity of storage allocated by successive calls +to \fIcalloc\fP() is unspecified. The pointer returned if the +allocation succeeds shall be suitably aligned so that it may be assigned +to a pointer to any type of object and then used to access +such an object or an array of such objects in the space allocated +(until the space is explicitly freed or reallocated). Each such +allocation shall yield a pointer to an object disjoint from any other +object. The pointer returned shall point to the start (lowest +byte address) of the allocated space. If the space cannot be allocated, +a null pointer shall be returned. If the size of the space +requested is 0, the behavior is implementation-defined: the value +returned shall be either a null pointer or a unique pointer. +.SH RETURN VALUE +.LP +Upon successful completion with both \fInelem\fP and \fIelsize\fP +non-zero, \fIcalloc\fP() shall return a pointer to the +allocated space. If either \fInelem\fP or \fIelsize\fP is 0, then +either a null pointer or a unique pointer value that can be +successfully passed to \fIfree\fP() shall be returned. Otherwise, +it shall return a null +pointer \ and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIcalloc\fP() function shall fail if: +.TP 7 +.B ENOMEM +Insufficient memory is available. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +There is now no requirement for the implementation to support the +inclusion of \fI\fP. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfree\fP() , \fImalloc\fP() , \fIrealloc\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/carg.3p b/man3p/carg.3p new file mode 100644 index 000000000..39063a8a4 --- /dev/null +++ b/man3p/carg.3p @@ -0,0 +1,57 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CARG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" carg +.SH NAME +carg, cargf, cargl \- complex argument functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double carg(double complex\fP \fIz\fP\fB); +.br +float cargf(float complex\fP \fIz\fP\fB); +.br +long double cargl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the argument (also called phase angle) +of \fIz\fP, with a branch cut along the negative real +axis. +.SH RETURN VALUE +.LP +These functions shall return the value of the argument in the interval +[-pi,\ +pi]. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcimag\fP() , \fIconj\fP() , \fIcproj\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/cargf.3p b/man3p/cargf.3p new file mode 100644 index 000000000..4c2eb67ce --- /dev/null +++ b/man3p/cargf.3p @@ -0,0 +1 @@ +.so man3p/carg.3p diff --git a/man3p/cargl.3p b/man3p/cargl.3p new file mode 100644 index 000000000..4c2eb67ce --- /dev/null +++ b/man3p/cargl.3p @@ -0,0 +1 @@ +.so man3p/carg.3p diff --git a/man3p/casin.3p b/man3p/casin.3p new file mode 100644 index 000000000..6f0cd7b33 --- /dev/null +++ b/man3p/casin.3p @@ -0,0 +1,59 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CASIN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" casin +.SH NAME +casin, casinf, casinl \- complex arc sine functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex casin(double complex\fP \fIz\fP\fB); +.br +float complex casinf(float complex\fP \fIz\fP\fB); +.br +long double complex casinl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex arc sine of \fIz\fP, with +branch cuts outside the interval [-1,\ +1] along the +real axis. +.SH RETURN VALUE +.LP +These functions shall return the complex arc sine value, in the range +of a strip mathematically unbounded along the imaginary +axis and in the interval [-pi/2,\ +pi/2] along the +real axis. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcsin\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/casinf.3p b/man3p/casinf.3p new file mode 100644 index 000000000..eb51f53df --- /dev/null +++ b/man3p/casinf.3p @@ -0,0 +1 @@ +.so man3p/casin.3p diff --git a/man3p/casinh.3p b/man3p/casinh.3p new file mode 100644 index 000000000..35ef94c75 --- /dev/null +++ b/man3p/casinh.3p @@ -0,0 +1,59 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CASINH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" casinh +.SH NAME +casinh, casinhf, casinhl \- complex arc hyperbolic sine functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex casinh(double complex\fP \fIz\fP\fB); +.br +float complex casinhf(float complex\fP \fIz\fP\fB); +.br +long double complex casinhl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex arc hyperbolic sine of \fIz\fP, +with branch cuts outside the interval +[-\fIi\fP,\ +\fIi\fP] along the imaginary axis. +.SH RETURN VALUE +.LP +These functions shall return the complex arc hyperbolic sine value, +in the range of a strip mathematically unbounded along the +real axis and in the interval [-\fIi\fPpi/2,\ +\fIi\fPpi/2] along +the imaginary axis. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcsinh\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/casinhf.3p b/man3p/casinhf.3p new file mode 100644 index 000000000..7c274ad0d --- /dev/null +++ b/man3p/casinhf.3p @@ -0,0 +1 @@ +.so man3p/casinh.3p diff --git a/man3p/casinhl.3p b/man3p/casinhl.3p new file mode 100644 index 000000000..7c274ad0d --- /dev/null +++ b/man3p/casinhl.3p @@ -0,0 +1 @@ +.so man3p/casinh.3p diff --git a/man3p/casinl.3p b/man3p/casinl.3p new file mode 100644 index 000000000..eb51f53df --- /dev/null +++ b/man3p/casinl.3p @@ -0,0 +1 @@ +.so man3p/casin.3p diff --git a/man3p/catan.3p b/man3p/catan.3p new file mode 100644 index 000000000..69857eb2c --- /dev/null +++ b/man3p/catan.3p @@ -0,0 +1,59 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CATAN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" catan +.SH NAME +catan, catanf, catanl \- complex arc tangent functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex catan(double complex\fP \fIz\fP\fB); +.br +float complex catanf(float complex\fP \fIz\fP\fB); +.br +long double complex catanl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex arc tangent of \fIz\fP, +with branch cuts outside the interval +[-\fIi\fP,\ +\fIi\fP] along the imaginary axis. +.SH RETURN VALUE +.LP +These functions shall return the complex arc tangent value, in the +range of a strip mathematically unbounded along the imaginary +axis and in the interval [-pi/2,\ +pi/2] along the +real axis. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIctan\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/catanf.3p b/man3p/catanf.3p new file mode 100644 index 000000000..de428f79d --- /dev/null +++ b/man3p/catanf.3p @@ -0,0 +1 @@ +.so man3p/catan.3p diff --git a/man3p/catanh.3p b/man3p/catanh.3p new file mode 100644 index 000000000..f5a692b06 --- /dev/null +++ b/man3p/catanh.3p @@ -0,0 +1,59 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CATANH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" catanh +.SH NAME +catanh, catanhf, catanhl \- complex arc hyperbolic tangent functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex catanh(double complex\fP \fIz\fP\fB); +.br +float complex catanhf(float complex\fP \fIz\fP\fB); +.br +long double complex catanhl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex arc hyperbolic tangent of +\fIz\fP, with branch cuts outside the interval +[-1,\ +1] along the real axis. +.SH RETURN VALUE +.LP +These functions shall return the complex arc hyperbolic tangent value, +in the range of a strip mathematically unbounded along +the real axis and in the interval [-\fIi\fPpi/2,\ +\fIi\fPpi/2] along +the imaginary axis. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIctanh\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/catanhf.3p b/man3p/catanhf.3p new file mode 100644 index 000000000..c843fca4c --- /dev/null +++ b/man3p/catanhf.3p @@ -0,0 +1 @@ +.so man3p/catanh.3p diff --git a/man3p/catanhl.3p b/man3p/catanhl.3p new file mode 100644 index 000000000..c843fca4c --- /dev/null +++ b/man3p/catanhl.3p @@ -0,0 +1 @@ +.so man3p/catanh.3p diff --git a/man3p/catanl.3p b/man3p/catanl.3p new file mode 100644 index 000000000..de428f79d --- /dev/null +++ b/man3p/catanl.3p @@ -0,0 +1 @@ +.so man3p/catan.3p diff --git a/man3p/catclose.3p b/man3p/catclose.3p new file mode 100644 index 000000000..d62fb82b0 --- /dev/null +++ b/man3p/catclose.3p @@ -0,0 +1,62 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CATCLOSE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" catclose +.SH NAME +catclose \- close a message catalog descriptor +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int catclose(nl_catd\fP \fIcatd\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIcatclose\fP() function shall close the message catalog identified +by \fIcatd\fP. If a file descriptor is used to +implement the type \fBnl_catd\fP, that file descriptor shall be closed. +.SH RETURN VALUE +.LP +Upon successful completion, \fIcatclose\fP() shall return 0; otherwise, +-1 shall be returned, and \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +The \fIcatclose\fP() function may fail if: +.TP 7 +.B EBADF +The catalog descriptor is not valid. +.TP 7 +.B EINTR +The \fIcatclose\fP() function was interrupted by a signal. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcatgets\fP() , \fIcatopen\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/catgets.3p b/man3p/catgets.3p new file mode 100644 index 000000000..ef4fcb387 --- /dev/null +++ b/man3p/catgets.3p @@ -0,0 +1,87 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CATGETS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" catgets +.SH NAME +catgets \- read a program message +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *catgets(nl_catd\fP \fIcatd\fP\fB, int s\fP\fIet_id\fP\fB, int\fP +\fImsg_id\fP\fB, const char +*\fP\fIs\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIcatgets\fP() function shall attempt to read message \fImsg_id\fP, +in set \fIset_id\fP, from the message catalog +identified by \fIcatd\fP. The \fIcatd\fP argument is a message catalog +descriptor returned from an earlier call to \fIcatopen\fP(). The \fIs\fP +argument points to a default message string which shall be returned +by \fIcatgets\fP() if it cannot retrieve the identified message. +.LP +The \fIcatgets\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +If the identified message is retrieved successfully, \fIcatgets\fP() +shall return a pointer to an internal buffer area +containing the null-terminated message string. If the call is unsuccessful +for any reason, \fIs\fP shall be returned and +\fIerrno\fP may be set to indicate the error. +.SH ERRORS +.LP +The \fIcatgets\fP() function may fail if: +.TP 7 +.B EBADF +The \fIcatd\fP argument is not a valid message catalog descriptor +open for reading. +.TP 7 +.B EBADMSG +The message identified by \fIset_id\fP and \fImsg_id\fP in the specified +message catalog did not satisfy +implementation-defined security criteria. +.TP 7 +.B EINTR +The read operation was terminated due to the receipt of a signal, +and no data was transferred. +.TP 7 +.B EINVAL +The message catalog identified by \fIcatd\fP is corrupted. +.TP 7 +.B ENOMSG +The message identified by \fIset_id\fP and \fImsg_id\fP is not in +the message catalog. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcatclose\fP() , \fIcatopen\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/catopen.3p b/man3p/catopen.3p new file mode 100644 index 000000000..d48da23cd --- /dev/null +++ b/man3p/catopen.3p @@ -0,0 +1,131 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CATOPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" catopen +.SH NAME +catopen \- open a message catalog +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +nl_catd catopen(const char *\fP\fIname\fP\fB, int\fP \fIoflag\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIcatopen\fP() function shall open a message catalog and return +a message catalog descriptor. The \fIname\fP argument +specifies the name of the message catalog to be opened. If \fIname\fP +contains a \fB'/'\fP , then \fIname\fP specifies a +complete name for the message catalog. Otherwise, the environment +variable \fINLSPATH\fP is used with \fIname\fP substituted for +the \fB%N\fP conversion specification (see the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables). If \fINLSPATH\fP +exists in the environment when the process +starts, then if the process has appropriate privileges, the behavior +of \fIcatopen\fP() is undefined. If \fINLSPATH\fP does not +exist in the environment, or if a message catalog cannot be found +in any of the components specified by \fINLSPATH\fP, then an +implementation-defined default path shall be used. This default may +be affected by the setting of \fILC_MESSAGES\fP if the value +of \fIoflag\fP is NL_CAT_LOCALE, or the \fILANG\fP environment variable +if \fIoflag\fP is 0. +.LP +A message catalog descriptor shall remain valid in a process until +that process closes it, or a successful call to one of the +\fIexec\fP functions. A change in the setting of the \fILC_MESSAGES\fP +category may +invalidate existing open catalogs. +.LP +If a file descriptor is used to implement message catalog descriptors, +the FD_CLOEXEC flag shall be set; see \fI\fP. +.LP +If the value of the \fIoflag\fP argument is 0, the \fILANG\fP environment +variable is used to locate the catalog without +regard to the \fILC_MESSAGES\fP category. If the \fIoflag\fP argument +is NL_CAT_LOCALE, the \fILC_MESSAGES\fP category is used +to locate the message catalog (see the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables). +.SH RETURN VALUE +.LP +Upon successful completion, \fIcatopen\fP() shall return a message +catalog descriptor for use on subsequent calls to \fIcatgets\fP() +and \fIcatclose\fP(). Otherwise, +\fIcatopen\fP() shall return ( \fBnl_catd\fP) -1 and set \fIerrno\fP +to indicate the error. +.SH ERRORS +.LP +The \fIcatopen\fP() function may fail if: +.TP 7 +.B EACCES +Search permission is denied for the component of the path prefix of +the message catalog or read permission is denied for the +message catalog. +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENAMETOOLONG +The length of a pathname of the message catalog exceeds {PATH_MAX} +or a pathname component is longer than {NAME_MAX}. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.TP 7 +.B ENFILE +Too many files are currently open in the system. +.TP 7 +.B ENOENT +The message catalog does not exist or the \fIname\fP argument points +to an empty string. +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.TP 7 +.B ENOTDIR +A component of the path prefix of the message catalog is not a directory. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Some implementations of \fIcatopen\fP() use \fImalloc\fP() to allocate +space for +internal buffer areas. The \fIcatopen\fP() function may fail if there +is insufficient storage space available to accommodate these +buffers. +.LP +Conforming applications must assume that message catalog descriptors +are not valid after a call to one of the \fIexec\fP functions. +.LP +Application writers should be aware that guidelines for the location +of message catalogs have not yet been developed. Therefore +they should take care to avoid conflicting with catalogs used by other +applications and the standard utilities. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcatclose\fP() , \fIcatgets\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP, the Shell +and Utilities volume of IEEE\ Std\ 1003.1-2001 +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/cbrt.3p b/man3p/cbrt.3p new file mode 100644 index 000000000..7a04b6708 --- /dev/null +++ b/man3p/cbrt.3p @@ -0,0 +1,63 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CBRT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cbrt +.SH NAME +cbrt, cbrtf, cbrtl \- cube root functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double cbrt(double\fP \fIx\fP\fB); +.br +float cbrtf(float\fP \fIx\fP\fB); +.br +long double cbrtl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the real cube root of their argument +\fIx\fP. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the cube +root of \fIx\fP. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0 or \(+-Inf, \fIx\fP shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +For some applications, a true cube root function, which returns negative +results for negative arguments, is more appropriate +than \fIpow\fP( \fIx\fP, 1.0/3.0), which returns a NaN for \fIx\fP +less than 0. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/cbrtf.3p b/man3p/cbrtf.3p new file mode 100644 index 000000000..1ec7d4a34 --- /dev/null +++ b/man3p/cbrtf.3p @@ -0,0 +1 @@ +.so man3p/cbrt.3p diff --git a/man3p/cbrtl.3p b/man3p/cbrtl.3p new file mode 100644 index 000000000..1ec7d4a34 --- /dev/null +++ b/man3p/cbrtl.3p @@ -0,0 +1 @@ +.so man3p/cbrt.3p diff --git a/man3p/ccos.3p b/man3p/ccos.3p new file mode 100644 index 000000000..7362291d0 --- /dev/null +++ b/man3p/ccos.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CCOS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ccos +.SH NAME +ccos, ccosf, ccosl \- complex cosine functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex ccos(double complex\fP \fIz\fP\fB); +.br +float complex ccosf(float complex\fP \fIz\fP\fB); +.br +long double complex ccosl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex cosine of \fIz\fP. +.SH RETURN VALUE +.LP +These functions shall return the complex cosine value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcacos\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ccosf.3p b/man3p/ccosf.3p new file mode 100644 index 000000000..06b2076d1 --- /dev/null +++ b/man3p/ccosf.3p @@ -0,0 +1 @@ +.so man3p/ccos.3p diff --git a/man3p/ccosh.3p b/man3p/ccosh.3p new file mode 100644 index 000000000..c9b7c98f4 --- /dev/null +++ b/man3p/ccosh.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CCOSH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ccosh +.SH NAME +ccosh, ccoshf, ccoshl \- complex hyperbolic cosine functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex ccosh(double complex\fP \fIz\fP\fB); +.br +float complex ccoshf(float complex\fP \fIz\fP\fB); +.br +long double complex ccoshl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex hyperbolic cosine of \fIz\fP. +.SH RETURN VALUE +.LP +These functions shall return the complex hyperbolic cosine value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcacosh\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ccoshf.3p b/man3p/ccoshf.3p new file mode 100644 index 000000000..2ca803a96 --- /dev/null +++ b/man3p/ccoshf.3p @@ -0,0 +1 @@ +.so man3p/ccosh.3p diff --git a/man3p/ccoshl.3p b/man3p/ccoshl.3p new file mode 100644 index 000000000..2ca803a96 --- /dev/null +++ b/man3p/ccoshl.3p @@ -0,0 +1 @@ +.so man3p/ccosh.3p diff --git a/man3p/ccosl.3p b/man3p/ccosl.3p new file mode 100644 index 000000000..06b2076d1 --- /dev/null +++ b/man3p/ccosl.3p @@ -0,0 +1 @@ +.so man3p/ccos.3p diff --git a/man3p/ceil.3p b/man3p/ceil.3p new file mode 100644 index 000000000..bd34bfcab --- /dev/null +++ b/man3p/ceil.3p @@ -0,0 +1,97 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CEIL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ceil +.SH NAME +ceil, ceilf, ceill \- ceiling value function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double ceil(double\fP \fIx\fP\fB); +.br +float ceilf(float\fP \fIx\fP\fB); +.br +long double ceill(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the smallest integral value not less +than \fIx\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, \fIceil\fP(), \fIceilf\fP(), and \fIceill\fP() +shall return the smallest integral value not less +than \fIx\fP, expressed as a type \fBdouble\fP, \fBfloat\fP, or \fBlong +double\fP, respectively. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0 or \(+-Inf, \fIx\fP shall be returned. +.LP +If the correct value would cause overflow, a range error shall occur +and \fIceil\fP(), \fIceilf\fP(), and \fIceill\fP() shall +return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Range\ Error +The result overflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The integral value returned by these functions need not be expressible +as an \fBint\fP or \fBlong\fP. The return value should +be tested before assigning it to an integer type to avoid the undefined +results of an integer overflow. +.LP +The \fIceil\fP() function can only overflow when the floating-point +representation has DBL_MANT_DIG > DBL_MAX_EXP. +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIfloor\fP() , \fIisnan\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ceilf.3p b/man3p/ceilf.3p new file mode 100644 index 000000000..cc8c8cc9c --- /dev/null +++ b/man3p/ceilf.3p @@ -0,0 +1 @@ +.so man3p/ceil.3p diff --git a/man3p/ceill.3p b/man3p/ceill.3p new file mode 100644 index 000000000..cc8c8cc9c --- /dev/null +++ b/man3p/ceill.3p @@ -0,0 +1 @@ +.so man3p/ceil.3p diff --git a/man3p/cexp.3p b/man3p/cexp.3p new file mode 100644 index 000000000..2e36d7524 --- /dev/null +++ b/man3p/cexp.3p @@ -0,0 +1,55 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CEXP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cexp +.SH NAME +cexp, cexpf, cexpl \- complex exponential functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex cexp(double complex\fP \fIz\fP\fB); +.br +float complex cexpf(float complex\fP \fIz\fP\fB); +.br +long double complex cexpl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex exponent of \fIz\fP, defined +as \fIe**z\fP. +.SH RETURN VALUE +.LP +These functions shall return the complex exponential value of \fIz\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclog\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/cexpf.3p b/man3p/cexpf.3p new file mode 100644 index 000000000..4831ba798 --- /dev/null +++ b/man3p/cexpf.3p @@ -0,0 +1 @@ +.so man3p/cexp.3p diff --git a/man3p/cexpl.3p b/man3p/cexpl.3p new file mode 100644 index 000000000..4831ba798 --- /dev/null +++ b/man3p/cexpl.3p @@ -0,0 +1 @@ +.so man3p/cexp.3p diff --git a/man3p/cfgetispeed.3p b/man3p/cfgetispeed.3p new file mode 100644 index 000000000..9c7952d9c --- /dev/null +++ b/man3p/cfgetispeed.3p @@ -0,0 +1,106 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CFGETISPEED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cfgetispeed +.SH NAME +cfgetispeed \- get input baud rate +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +speed_t cfgetispeed(const struct termios *\fP\fItermios_p\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIcfgetispeed\fP() function shall extract the input baud rate +from the \fBtermios\fP structure to which the +\fItermios_p\fP argument points. +.LP +This function shall return exactly the value in the \fBtermios\fP +data structure, without interpretation. +.SH RETURN VALUE +.LP +Upon successful completion, \fIcfgetispeed\fP() shall return a value +of type \fBspeed_t\fP representing the input baud +rate. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The term "baud" is used historically here, but is not technically +correct. This is properly "bits per second", which may not +be the same as baud. However, the term is used because of the historical +usage and understanding. +.LP +The \fIcfgetospeed\fP(), \fIcfgetispeed\fP(), \fIcfsetospeed\fP(), +and \fIcfsetispeed\fP() +functions do not take arguments as numbers, but rather as symbolic +names. There are two reasons for this: +.IP " 1." 4 +Historically, numbers were not used because of the way the rate was +stored in the data structure. This is retained even though a +function is now used. +.LP +.IP " 2." 4 +More importantly, only a limited set of possible rates is at all portable, +and this constrains the application to that set. +.LP +.LP +There is nothing to prevent an implementation accepting as an extension +a number (such as 126), and since the encoding of the +Bxxx symbols is not specified, this can be done to avoid introducing +ambiguity. +.LP +Setting the input baud rate to zero was a mechanism to allow for split +baud rates. Clarifications in this volume of +IEEE\ Std\ 1003.1-2001 have made it possible to determine whether +split rates are supported and to support them without +having to treat zero as a special case. Since this functionality is +also confusing, it has been declared obsolescent. The 0 +argument referred to is the literal constant 0, not the symbolic constant +B0. This volume of IEEE\ Std\ 1003.1-2001 does +not preclude B0 from being defined as the value 0; in fact, implementations +would likely benefit from the two being equivalent. +This volume of IEEE\ Std\ 1003.1-2001 does not fully specify whether +the previous \fIcfsetispeed\fP() value is retained after a \fItcgetattr\fP() +as the actual value or as zero. Therefore, conforming applications +should +always set both the input speed and output speed when setting either. +.LP +In historical implementations, the baud rate information is traditionally +kept in \fBc_cflag\fP. Applications should be written +to presume that this might be the case (and thus not blindly copy +\fBc_cflag\fP), but not to rely on it in case it is in some +other field of the structure. Setting the \fBc_cflag\fP field absolutely +after setting a baud rate is a non-portable action +because of this. In general, the unused parts of the flag fields might +be used by the implementation and should not be blindly +copied from the descriptions of one terminal device to another. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcfgetospeed\fP() , \fIcfsetispeed\fP() , \fIcfsetospeed\fP() , +\fItcgetattr\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/cfgetospeed.3p b/man3p/cfgetospeed.3p new file mode 100644 index 000000000..794708d7c --- /dev/null +++ b/man3p/cfgetospeed.3p @@ -0,0 +1,58 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CFGETOSPEED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cfgetospeed +.SH NAME +cfgetospeed \- get output baud rate +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +speed_t cfgetospeed(const struct termios *\fP\fItermios_p\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIcfgetospeed\fP() function shall extract the output baud rate +from the \fBtermios\fP structure to which the +\fItermios_p\fP argument points. +.LP +This function shall return exactly the value in the \fBtermios\fP +data structure, without interpretation. +.SH RETURN VALUE +.LP +Upon successful completion, \fIcfgetospeed\fP() shall return a value +of type \fBspeed_t\fP representing the output baud +rate. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Refer to \fIcfgetispeed\fP() . +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcfgetispeed\fP() , \fIcfsetispeed\fP() , \fIcfsetospeed\fP() , +\fItcgetattr\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/cfsetispeed.3p b/man3p/cfsetispeed.3p new file mode 100644 index 000000000..24f974657 --- /dev/null +++ b/man3p/cfsetispeed.3p @@ -0,0 +1,70 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CFSETISPEED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cfsetispeed +.SH NAME +cfsetispeed \- set input baud rate +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int cfsetispeed(struct termios *\fP\fItermios_p\fP\fB, speed_t\fP +\fIspeed\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIcfsetispeed\fP() function shall set the input baud rate stored +in the structure pointed to by \fItermios_p\fP to +\fIspeed.\fP +.LP +There shall be no effect on the baud rates set in the hardware until +a subsequent successful call to \fItcsetattr\fP() with the same \fBtermios\fP +structure. Similarly, errors resulting from +attempts to set baud rates not supported by the terminal device need +not be detected until the \fItcsetattr\fP() function is called. +.SH RETURN VALUE +.LP +Upon successful completion, \fIcfsetispeed\fP() shall return 0; otherwise, +-1 shall be returned, and \fIerrno\fP may be set to +indicate the error. +.SH ERRORS +.LP +The \fIcfsetispeed\fP() function may fail if: +.TP 7 +.B EINVAL +The \fIspeed\fP value is not a valid baud rate. +.TP 7 +.B EINVAL +The value of \fIspeed\fP is outside the range of possible speed values +as specified in \fI\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Refer to \fIcfgetispeed\fP() . +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcfgetispeed\fP() , \fIcfgetospeed\fP() , \fIcfsetospeed\fP() , +\fItcsetattr\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/cfsetospeed.3p b/man3p/cfsetospeed.3p new file mode 100644 index 000000000..4a827f62d --- /dev/null +++ b/man3p/cfsetospeed.3p @@ -0,0 +1,70 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CFSETOSPEED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cfsetospeed +.SH NAME +cfsetospeed \- set output baud rate +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int cfsetospeed(struct termios *\fP\fItermios_p\fP\fB, speed_t\fP +\fIspeed\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIcfsetospeed\fP() function shall set the output baud rate stored +in the structure pointed to by \fItermios_p\fP to +\fIspeed\fP. +.LP +There shall be no effect on the baud rates set in the hardware until +a subsequent successful call to \fItcsetattr\fP() with the same \fBtermios\fP +structure. Similarly, errors resulting from +attempts to set baud rates not supported by the terminal device need +not be detected until the \fItcsetattr\fP() function is called. +.SH RETURN VALUE +.LP +Upon successful completion, \fIcfsetospeed\fP() shall return 0; otherwise, +it shall return -1 and \fIerrno\fP may be set to +indicate the error. +.SH ERRORS +.LP +The \fIcfsetospeed\fP() function may fail if: +.TP 7 +.B EINVAL +The \fIspeed\fP value is not a valid baud rate. +.TP 7 +.B EINVAL +The value of \fIspeed\fP is outside the range of possible speed values +as specified in \fI\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Refer to \fIcfgetispeed\fP() . +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcfgetispeed\fP() , \fIcfgetospeed\fP() , \fIcfsetispeed\fP() , +\fItcsetattr\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/chdir.3p b/man3p/chdir.3p new file mode 100644 index 000000000..899901f12 --- /dev/null +++ b/man3p/chdir.3p @@ -0,0 +1,103 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CHDIR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" chdir +.SH NAME +chdir \- change working directory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int chdir(const char *\fP\fIpath\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIchdir\fP() function shall cause the directory named by the +pathname pointed to by the \fIpath\fP argument to become the +current working directory; that is, the starting point for path searches +for pathnames not beginning with \fB'/'\fP . +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned, the current working directory shall remain +unchanged, and \fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +The \fIchdir\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied for any component of the pathname. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing directory or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of the pathname is not a directory. +.sp +.LP +The \fIchdir\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Changing the Current Working Directory +.LP +The following example makes the value pointed to by \fBdirectory\fP, +\fB/tmp\fP, the current working directory. +.sp +.RS +.nf + +\fB#include +\&... +char *directory = "/tmp"; +int ret; +.sp + +ret = chdir (directory); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIchdir\fP() function only affects the working directory of the +current process. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetcwd\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/chmod.3p b/man3p/chmod.3p new file mode 100644 index 000000000..58280d68f --- /dev/null +++ b/man3p/chmod.3p @@ -0,0 +1,216 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CHMOD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" chmod +.SH NAME +chmod \- change mode of a file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int chmod(const char *\fP\fIpath\fP\fB, mode_t\fP \fImode\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIchmod\fP() function shall change S_ISUID, S_ISGID, \ S_ISVTX, +and the file permission bits of the file named by the pathname pointed +to by the \fIpath\fP argument to the +corresponding bits in the \fImode\fP argument. The application shall +ensure that the effective user ID of the process matches the +owner of the file or the process has appropriate privileges in order +to do this. +.LP +S_ISUID, S_ISGID, \ S_ISVTX, and the file permission +bits are described in \fI\fP. +.LP +If the calling process does not have appropriate privileges, and if +the group ID of the file does not match the effective group +ID or one of the supplementary group IDs and if the file is a regular +file, bit S_ISGID (set-group-ID on execution) in the file's +mode shall be cleared upon successful return from \fIchmod\fP(). +.LP +Additional implementation-defined restrictions may cause the S_ISUID +and S_ISGID bits in \fImode\fP to be ignored. +.LP +The effect on file descriptors for files open at the time of a call +to \fIchmod\fP() is implementation-defined. +.LP +Upon successful completion, \fIchmod\fP() shall mark for update the +\fIst_ctime\fP field of the file. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned; otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. If +-1 is returned, no change to the file mode occurs. +.SH ERRORS +.LP +The \fIchmod\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied on a component of the path prefix. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B EPERM +The effective user ID does not match the owner of the file and the +process does not have appropriate privileges. +.TP 7 +.B EROFS +The named file resides on a read-only file system. +.sp +.LP +The \fIchmod\fP() function may fail if: +.TP 7 +.B EINTR +A signal was caught during execution of the function. +.TP 7 +.B EINVAL +The value of the \fImode\fP argument is invalid. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +strings exceeded {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Setting Read Permissions for User, Group, and Others +.LP +The following example sets read permissions for the owner, group, +and others. +.sp +.RS +.nf + +\fB#include +.sp + +const char *path; +\&... +chmod(path, S_IRUSR|S_IRGRP|S_IROTH); +\fP +.fi +.RE +.SS Setting Read, Write, and Execute Permissions for the Owner Only +.LP +The following example sets read, write, and execute permissions for +the owner, and no permissions for group and others. +.sp +.RS +.nf + +\fB#include +.sp + +const char *path; +\&... +chmod(path, S_IRWXU); +\fP +.fi +.RE +.SS Setting Different Permissions for Owner, Group, and Other +.LP +The following example sets owner permissions for CHANGEFILE to read, +write, and execute, group permissions to read and execute, +and other permissions to read. +.sp +.RS +.nf + +\fB#include +.sp + +#define CHANGEFILE "/etc/myfile" +\&... +chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH); +\fP +.fi +.RE +.SS Setting and Checking File Permissions +.LP +The following example sets the file permission bits for a file named +\fB/home/cnd/mod1\fP, then calls the \fIstat\fP() function to verify +the permissions. +.sp +.RS +.nf + +\fB#include +#include +.sp + +int status; +struct stat buffer +\&... +chmod("home/cnd/mod1", S_IRWXU|S_IRWXG|S_IROTH|S_IWOTH); +status = stat("home/cnd/mod1", &buffer;); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +In order to ensure that the S_ISUID and S_ISGID bits are set, an application +requiring this should use \fIstat\fP() after a successful \fIchmod\fP() +to verify this. +.LP +Any file descriptors currently open by any process on the file could +possibly become invalid if the mode of the file is changed +to a value which would deny access to that process. One situation +where this could occur is on a stateless file system. This +behavior will not occur in a conforming environment. +.SH RATIONALE +.LP +This volume of IEEE\ Std\ 1003.1-2001 specifies that the S_ISGID bit +is cleared by \fIchmod\fP() on a regular file +under certain conditions. This is specified on the assumption that +regular files may be executed, and the system should prevent +users from making executable \fIsetgid\fP() files perform with privileges +that the caller +does not have. On implementations that support execution of other +file types, the S_ISGID bit should be cleared for those file +types under the same circumstances. +.LP +Implementations that use the S_ISUID bit to indicate some other function +(for example, mandatory record locking) on +non-executable files need not clear this bit on writing. They should +clear the bit for executable files and any other cases where +the bit grants special powers to processes that change the file contents. +Similar comments apply to the S_ISGID bit. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchown\fP() , \fImkdir\fP() , \fImkfifo\fP() , +\fIopen\fP() , \fIstat\fP() , \fIstatvfs\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/chown.3p b/man3p/chown.3p new file mode 100644 index 000000000..6244a76ed --- /dev/null +++ b/man3p/chown.3p @@ -0,0 +1,174 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CHOWN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" chown +.SH NAME +chown \- change owner and group of a file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int chown(const char *\fP\fIpath\fP\fB, uid_t\fP \fIowner\fP\fB, gid_t\fP +\fIgroup\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIchown\fP() function shall change the user and group ownership +of a file. +.LP +The \fIpath\fP argument points to a pathname naming a file. The user +ID and group ID of the named file shall be set to the +numeric values contained in \fIowner\fP and \fIgroup\fP, respectively. +.LP +Only processes with an effective user ID equal to the user ID of the +file or with appropriate privileges may change the +ownership of a file. If _POSIX_CHOWN_RESTRICTED is in effect for \fIpath\fP: +.IP " *" 3 +Changing the user ID is restricted to processes with appropriate privileges. +.LP +.IP " *" 3 +Changing the group ID is permitted to a process with an effective +user ID equal to the user ID of the file, but without +appropriate privileges, if and only if \fIowner\fP is equal to the +file's user ID or ( \fBuid_t\fP)-1 and \fIgroup\fP is equal +either to the calling process' effective group ID or to one of its +supplementary group IDs. +.LP +.LP +If the specified file is a regular file, one or more of the S_IXUSR, +S_IXGRP, or S_IXOTH bits of the file mode are set, and the +process does not have appropriate privileges, the set-user-ID (S_ISUID) +and set-group-ID (S_ISGID) bits of the file mode shall be +cleared upon successful return from \fIchown\fP(). If the specified +file is a regular file, one or more of the S_IXUSR, S_IXGRP, +or S_IXOTH bits of the file mode are set, and the process has appropriate +privileges, it is implementation-defined whether the +set-user-ID and set-group-ID bits are altered. If the \fIchown\fP() +function is successfully invoked on a file that is not a +regular file and one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits +of the file mode are set, the set-user-ID and set-group-ID +bits may be cleared. +.LP +If \fIowner\fP or \fIgroup\fP is specified as ( \fBuid_t\fP)-1 or +( \fBgid_t\fP)-1, respectively, the corresponding ID of +the file shall not be changed. If both owner and group are -1, the +times need not be updated. +.LP +Upon successful completion, \fIchown\fP() shall mark for update the +\fIst_ctime\fP field of the file. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned; otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. If +-1 is returned, no changes are made in the user ID and group ID of +the file. +.SH ERRORS +.LP +The \fIchown\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied on a component of the path prefix. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B EPERM +The effective user ID does not match the owner of the file, or the +calling process does not have appropriate privileges and +_POSIX_CHOWN_RESTRICTED indicates that such privilege is required. +.TP 7 +.B EROFS +The named file resides on a read-only file system. +.sp +.LP +The \fIchown\fP() function may fail if: +.TP 7 +.B EIO +An I/O error occurred while reading or writing to the file system. +.TP 7 +.B EINTR +The \fIchown\fP() function was interrupted by a signal which was caught. +.TP 7 +.B EINVAL +The owner or group ID supplied is not a value supported by the implementation. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Although \fIchown\fP() can be used on some implementations by the +file owner to change the owner and group to any desired +values, the only portable use of this function is to change the group +of a file to the effective GID of the calling process or to a +member of its group set. +.SH RATIONALE +.LP +System III and System V allow a user to give away files; that is, +the owner of a file may change its user ID to anything. This +is a serious problem for implementations that are intended to meet +government security regulations. Version 7 and 4.3 BSD permit +only the superuser to change the user ID of a file. Some government +agencies (usually not ones concerned directly with security) +find this limitation too confining. This volume of IEEE\ Std\ 1003.1-2001 +uses \fImay\fP to permit secure implementations +while not disallowing System V. +.LP +System III and System V allow the owner of a file to change the group +ID to anything. Version 7 permits only the superuser to +change the group ID of a file. 4.3 BSD permits the owner to change +the group ID of a file to its effective group ID or to any of +the groups in the list of supplementary group IDs, but to no others. +.LP +The POSIX.1-1990 standard requires that the \fIchown\fP() function +invoked by a non-appropriate privileged process clear the +S_ISGID and the S_ISUID bits for regular files, and permits them to +be cleared for other types of files. This is so that changes in +accessibility do not accidentally cause files to become security holes. +Unfortunately, requiring these bits to be cleared on +non-executable data files also clears the mandatory file locking bit +(shared with S_ISGID), which is an extension on many +implementations (it first appeared in System V). These bits should +only be required to be cleared on regular files that have one or +more of their execute bits set. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchmod\fP() , \fIpathconf\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/cimag.3p b/man3p/cimag.3p new file mode 100644 index 000000000..237821150 --- /dev/null +++ b/man3p/cimag.3p @@ -0,0 +1,62 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CIMAG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cimag +.SH NAME +cimag, cimagf, cimagl \- complex imaginary functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double cimag(double complex\fP \fIz\fP\fB); +.br +float cimagf(float complex\fP \fIz\fP\fB); +.br +long double cimagl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the imaginary part of \fIz\fP. +.SH RETURN VALUE +.LP +These functions shall return the imaginary part value (as a real). +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +For a variable \fIz\fP of complex type: +.sp +.RS +.nf + +\fBz == creal(z) + cimag(z)*I +\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcarg\fP() , \fIconj\fP() , \fIcproj\fP() , \fIcreal\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/cimagf.3p b/man3p/cimagf.3p new file mode 100644 index 000000000..855d9d082 --- /dev/null +++ b/man3p/cimagf.3p @@ -0,0 +1 @@ +.so man3p/cimag.3p diff --git a/man3p/cimagl.3p b/man3p/cimagl.3p new file mode 100644 index 000000000..855d9d082 --- /dev/null +++ b/man3p/cimagl.3p @@ -0,0 +1 @@ +.so man3p/cimag.3p diff --git a/man3p/clearerr.3p b/man3p/clearerr.3p new file mode 100644 index 000000000..adb96ab27 --- /dev/null +++ b/man3p/clearerr.3p @@ -0,0 +1,51 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CLEARERR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" clearerr +.SH NAME +clearerr \- clear indicators on a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void clearerr(FILE *\fP\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIclearerr\fP() function shall clear the end-of-file and error +indicators for the stream to which \fIstream\fP +points. +.SH RETURN VALUE +.LP +The \fIclearerr\fP() function shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/clock.3p b/man3p/clock.3p new file mode 100644 index 000000000..fb7c65ce4 --- /dev/null +++ b/man3p/clock.3p @@ -0,0 +1,71 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CLOCK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" clock +.SH NAME +clock \- report CPU time used +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +clock_t clock(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fIclock\fP() function shall return the implementation's best +approximation to the processor time used by the process since +the beginning of an implementation-defined era related only to the +process invocation. +.SH RETURN VALUE +.LP +To determine the time in seconds, the value returned by \fIclock\fP() +should be divided by the value of the macro +CLOCKS_PER_SEC. \ CLOCKS_PER_SEC is defined to be one million in +\fI\fP. If the processor time used is not available or its +value cannot be +represented, the function shall return the value ( \fBclock_t\fP)-1. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +In order to measure the time spent in a program, \fIclock\fP() should +be called at the start of the program and its return +value subtracted from the value returned by subsequent calls. The +value returned by \fIclock\fP() is defined for compatibility +across systems that have clocks with different resolutions. The resolution +on any particular system need not be to microsecond +accuracy. +.LP +The value returned by \fIclock\fP() may wrap around on some implementations. +For example, on a machine with 32-bit values for +\fBclock_t\fP, it wraps after 2147 seconds or 36 minutes. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIasctime\fP() , \fIctime\fP() , \fIdifftime\fP() , \fIgmtime\fP() +, \fIlocaltime\fP() +, \fImktime\fP() , \fIstrftime\fP() , \fIstrptime\fP() , \fItime\fP() +, \fIutime\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/clock_getcpuclockid.3p b/man3p/clock_getcpuclockid.3p new file mode 100644 index 000000000..627a8a7ca --- /dev/null +++ b/man3p/clock_getcpuclockid.3p @@ -0,0 +1,81 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CLOCK_GETCPUCLOCKID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" clock_getcpuclockid +.SH NAME +clock_getcpuclockid \- access a process CPU-time clock (\fBADVANCED +REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int clock_getcpuclockid(pid_t\fP \fIpid\fP\fB, clockid_t *\fP\fIclock_id\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIclock_getcpuclockid\fP() function shall return the clock ID +of the CPU-time clock of the process specified by +\fIpid\fP. If the process described by \fIpid\fP exists and the calling +process has permission, the clock ID of this clock shall +be returned in \fIclock_id\fP. +.LP +If \fIpid\fP is zero, the \fIclock_getcpuclockid\fP() function shall +return the clock ID of the CPU-time clock of the process +making the call, in \fIclock_id\fP. +.LP +The conditions under which one process has permission to obtain the +CPU-time clock ID of other processes are +implementation-defined. +.SH RETURN VALUE +.LP +Upon successful completion, \fIclock_getcpuclockid\fP() shall return +zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +.LP +The \fIclock_getcpuclockid\fP() function shall fail if: +.TP 7 +.B EPERM +The requesting process does not have permission to access the CPU-time +clock for the process. +.sp +.LP +The \fIclock_getcpuclockid\fP() function may fail if: +.TP 7 +.B ESRCH +No process can be found corresponding to the process specified by +\fIpid\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIclock_getcpuclockid\fP() function is part of the Process CPU-Time +Clocks option and need not be provided on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclock_getres\fP() , \fItimer_create\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/clock_getres.3p b/man3p/clock_getres.3p new file mode 100644 index 000000000..5d09cb525 --- /dev/null +++ b/man3p/clock_getres.3p @@ -0,0 +1 @@ +.so man3p/clock_gettime.3p diff --git a/man3p/clock_gettime.3p b/man3p/clock_gettime.3p new file mode 100644 index 000000000..228428a98 --- /dev/null +++ b/man3p/clock_gettime.3p @@ -0,0 +1,205 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CLOCK_GETRES" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" clock_getres +.SH NAME +clock_getres, clock_gettime, clock_settime \- clock and timer functions +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int clock_getres(clockid_t\fP \fIclock_id\fP\fB, struct timespec *\fP\fIres\fP\fB); +.br +int clock_gettime(clockid_t\fP \fIclock_id\fP\fB, struct timespec +*\fP\fItp\fP\fB); +.br +int clock_settime(clockid_t\fP \fIclock_id\fP\fB, const struct timespec +*\fP\fItp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIclock_getres\fP() function shall return the resolution of any +clock. Clock resolutions are implementation-defined and +cannot be set by a process. If the argument \fIres\fP is not NULL, +the resolution of the specified clock shall be stored in the +location pointed to by \fIres\fP. If \fIres\fP is NULL, the clock +resolution is not returned. If the \fItime\fP argument of +\fIclock_settime\fP() is not a multiple of \fIres\fP, then the value +is truncated to a multiple of \fIres\fP. +.LP +The \fIclock_gettime\fP() function shall return the current value +\fItp\fP for the specified clock, \fIclock_id\fP. +.LP +The \fIclock_settime\fP() function shall set the specified clock, +\fIclock_id\fP, to the value specified by \fItp\fP. Time +values that are between two consecutive non-negative integer multiples +of the resolution of the specified clock shall be truncated +down to the smaller multiple of the resolution. +.LP +A clock may be system-wide (that is, visible to all processes) or +per-process (measuring time that is meaningful only within a +process). All implementations shall support a \fIclock_id\fP of CLOCK_REALTIME +as defined in \fI\fP. This clock represents the realtime clock +for the system. For this clock, the +values returned by \fIclock_gettime\fP() and specified by \fIclock_settime\fP() +represent the amount of time (in seconds and +nanoseconds) since the Epoch. An implementation may also support additional +clocks. The interpretation of time values for these +clocks is unspecified. +.LP +If the value of the CLOCK_REALTIME clock is set via \fIclock_settime\fP(), +the new value of the clock shall be used to +determine the time of expiration for absolute time services based +upon the CLOCK_REALTIME clock. This applies to the time at which +armed absolute timers expire. If the absolute time requested at the +invocation of such a time service is before the new value of +the clock, the time service shall expire immediately as if the clock +had reached the requested time normally. +.LP +Setting the value of the CLOCK_REALTIME clock via \fIclock_settime\fP() +shall have no effect on threads that are blocked +waiting for a relative time service based upon this clock, including +the \fInanosleep\fP() function; nor on the expiration of relative +timers based upon this clock. +Consequently, these time services shall expire when the requested +relative interval elapses, independently of the new or old value +of the clock. +.LP +If the Monotonic Clock option is supported, all implementations shall +support a \fIclock_id\fP of CLOCK_MONOTONIC defined in \fI\fP. +This clock represents the monotonic clock for the system. For this +clock, +the value returned by \fIclock_gettime\fP() represents the amount +of time (in seconds and nanoseconds) since an unspecified point +in the past (for example, system start-up time, or the Epoch). This +point does not change after system start-up time. The value of +the CLOCK_MONOTONIC clock cannot be set via \fIclock_settime\fP(). +This function shall fail if it is invoked with a +\fIclock_id\fP argument of CLOCK_MONOTONIC. +.LP +The effect of setting a clock via \fIclock_settime\fP() on armed per-process +timers associated with a clock other than +CLOCK_REALTIME is implementation-defined. +.LP +If +the value of the CLOCK_REALTIME clock is set via \fIclock_settime\fP(), +the new value of the clock shall be used to determine the +time at which the system shall awaken a thread blocked on an absolute +\fIclock_nanosleep\fP() call based upon the CLOCK_REALTIME clock. +If the absolute time +requested at the invocation of such a time service is before the new +value of the clock, the call shall return immediately as if +the clock had reached the requested time normally. +.LP +Setting the value of the CLOCK_REALTIME clock via \fIclock_settime\fP() +shall have no effect on any thread that is blocked on a +relative \fIclock_nanosleep\fP() call. Consequently, the call shall +return when +the requested relative interval elapses, independently of the new +or old value of the clock. +.LP +The appropriate privilege to set a particular clock is implementation-defined. +.LP +If _POSIX_CPUTIME is defined, implementations shall support clock +ID values obtained by invoking \fIclock_getcpuclockid\fP(), which +represent the CPU-time clock of a given process. +Implementations shall also support the special \fBclockid_t\fP value +CLOCK_PROCESS_CPUTIME_ID, which represents the CPU-time clock +of the calling process when invoking one of the \fIclock_*\fP() or +\fItimer_*\fP() functions. For these clock IDs, the values returned +by \fIclock_gettime\fP() and +specified by \fIclock_settime\fP() represent the amount of execution +time of the process associated with the clock. Changing the +value of a CPU-time clock via \fIclock_settime\fP() shall have no +effect on the behavior of the sporadic server scheduling policy +(see \fIScheduling Policies\fP ). +.LP +If _POSIX_THREAD_CPUTIME is defined, implementations shall support +clock ID values obtained by invoking \fIpthread_getcpuclockid\fP(), +which represent the CPU-time clock of a given thread. +Implementations shall also support the special \fBclockid_t\fP value +CLOCK_THREAD_CPUTIME_ID, which represents the CPU-time clock +of the calling thread when invoking one of the \fIclock_*\fP() or +\fItimer_*\fP() functions. For these clock IDs, the values returned +by \fIclock_gettime\fP() and +specified by \fIclock_settime\fP() shall represent the amount of execution +time of the thread associated with the clock. Changing +the value of a CPU-time clock via \fIclock_settime\fP() shall have +no effect on the behavior of the sporadic server scheduling +policy (see \fIScheduling Policies\fP ). +.SH RETURN VALUE +.LP +A return value of 0 shall indicate that the call succeeded. A return +value of -1 shall indicate that an error occurred, and +\fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +The \fIclock_getres\fP(), \fIclock_gettime\fP(), and \fIclock_settime\fP() +functions shall fail if: +.TP 7 +.B EINVAL +The \fIclock_id\fP argument does not specify a known clock. +.sp +.LP +The \fIclock_settime\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fItp\fP argument to \fIclock_settime\fP() is outside the range +for the given clock ID. +.TP 7 +.B EINVAL +The \fItp\fP argument specified a nanosecond value less than zero +or greater than or equal to 1000 million. +.TP 7 +.B EINVAL +The value of the \fIclock_id\fP argument is CLOCK_MONOTONIC. +.sp +.LP +The \fIclock_settime\fP() function may fail if: +.TP 7 +.B EPERM +The requesting process does not have the appropriate privilege to +set the specified clock. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +These functions are part of the Timers option and need not be available +on all implementations. +.LP +Note that the absolute value of the monotonic clock is meaningless +(because its origin is arbitrary), and thus there is no need +to set it. Furthermore, realtime applications can rely on the fact +that the value of this clock is never set and, therefore, that +time intervals measured with this clock will not be affected by calls +to \fIclock_settime\fP(). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclock_getcpuclockid\fP() , \fIclock_nanosleep\fP() , \fIctime\fP() +, \fImq_timedreceive\fP() , \fImq_timedsend\fP() , \fInanosleep\fP() +, \fIpthread_mutex_timedlock\fP() , \fIsem_timedwait\fP() , \fItime\fP() +, \fItimer_create\fP() , \fItimer_getoverrun\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/clock_nanosleep.3p b/man3p/clock_nanosleep.3p new file mode 100644 index 000000000..a678624d4 --- /dev/null +++ b/man3p/clock_nanosleep.3p @@ -0,0 +1,189 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CLOCK_NANOSLEEP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" clock_nanosleep +.SH NAME +clock_nanosleep \- high resolution sleep with specifiable clock (\fBADVANCED +REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int clock_nanosleep(clockid_t\fP \fIclock_id\fP\fB, int\fP \fIflags\fP\fB, +.br +\ \ \ \ \ \ const struct timespec *\fP\fIrqtp\fP\fB, struct timespec +*\fP\fIrmtp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +If the flag TIMER_ABSTIME is not set in the \fIflags\fP argument, +the \fIclock_nanosleep\fP() function shall cause the current +thread to be suspended from execution until either the time interval +specified by the \fIrqtp\fP argument has elapsed, or a signal +is delivered to the calling thread and its action is to invoke a signal-catching +function, or the process is terminated. The clock +used to measure the time shall be the clock specified by \fIclock_id\fP. +.LP +If the flag TIMER_ABSTIME is set in the \fIflags\fP argument, the +\fIclock_nanosleep\fP() function shall cause the current +thread to be suspended from execution until either the time value +of the clock specified by \fIclock_id\fP reaches the absolute +time specified by the \fIrqtp\fP argument, or a signal is delivered +to the calling thread and its action is to invoke a +signal-catching function, or the process is terminated. If, at the +time of the call, the time value specified by \fIrqtp\fP is +less than or equal to the time value of the specified clock, then +\fIclock_nanosleep\fP() shall return immediately and the calling +process shall not be suspended. +.LP +The suspension time caused by this function may be longer than requested +because the argument value is rounded up to an integer +multiple of the sleep resolution, or because of the scheduling of +other activity by the system. But, except for the case of being +interrupted by a signal, the suspension time for the relative \fIclock_nanosleep\fP() +function (that is, with the TIMER_ABSTIME +flag not set) shall not be less than the time interval specified by +\fIrqtp\fP, as measured by the corresponding clock. The +suspension for the absolute \fIclock_nanosleep\fP() function (that +is, with the TIMER_ABSTIME flag set) shall be in effect at +least until the value of the corresponding clock reaches the absolute +time specified by \fIrqtp\fP, except for the case of being +interrupted by a signal. +.LP +The use of the \fIclock_nanosleep\fP() function shall have no effect +on the action or blockage of any signal. +.LP +The \fIclock_nanosleep\fP() function shall fail if the \fIclock_id\fP +argument refers to the CPU-time clock of the calling +thread. It is unspecified whether \fIclock_id\fP values of other CPU-time +clocks are allowed. +.SH RETURN VALUE +.LP +If the \fIclock_nanosleep\fP() function returns because the requested +time has elapsed, its return value shall be zero. +.LP +If the \fIclock_nanosleep\fP() function returns because it has been +interrupted by a signal, it shall return the corresponding +error value. For the relative \fIclock_nanosleep\fP() function, if +the \fIrmtp\fP argument is non-NULL, the \fBtimespec\fP +structure referenced by it shall be updated to contain the amount +of time remaining in the interval (the requested time minus the +time actually slept). If the \fIrmtp\fP argument is NULL, the remaining +time is not returned. The absolute +\fIclock_nanosleep\fP() function has no effect on the structure referenced +by \fIrmtp\fP. +.LP +If \fIclock_nanosleep\fP() fails, it shall return the corresponding +error value. +.SH ERRORS +.LP +The \fIclock_nanosleep\fP() function shall fail if: +.TP 7 +.B EINTR +The \fIclock_nanosleep\fP() function was interrupted by a signal. +.TP 7 +.B EINVAL +The \fIrqtp\fP argument specified a nanosecond value less than zero +or greater than or equal to 1000 million; or the +TIMER_ABSTIME flag was specified in flags and the \fIrqtp\fP argument +is outside the range for the clock specified by +\fIclock_id\fP; or the \fIclock_id\fP argument does not specify a +known clock, or specifies the CPU-time clock of the calling +thread. +.TP 7 +.B ENOTSUP +The \fIclock_id\fP argument specifies a clock for which \fIclock_nanosleep\fP() +is not supported, such as a CPU-time +clock. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Calling \fIclock_nanosleep\fP() with the value TIMER_ABSTIME not set +in the \fIflags\fP argument and with a \fIclock_id\fP of +CLOCK_REALTIME is equivalent to calling \fInanosleep\fP() with the +same \fIrqtp\fP and +\fIrmtp\fP arguments. +.SH RATIONALE +.LP +The \fInanosleep\fP() function specifies that the system-wide clock +CLOCK_REALTIME is +used to measure the elapsed time for this time service. However, with +the introduction of the monotonic clock CLOCK_MONOTONIC a new +relative sleep function is needed to allow an application to take +advantage of the special characteristics of this clock. +.LP +There are many applications in which a process needs to be suspended +and then activated multiple times in a periodic way; for +example, to poll the status of a non-interrupting device or to refresh +a display device. For these cases, it is known that precise +periodic activation cannot be achieved with a relative \fIsleep\fP() +or \fInanosleep\fP() function call. Suppose, for example, a periodic +process that is activated at +time \fIT\fP0, executes for a while, and then wants to suspend itself +until time \fIT\fP0+ \fIT\fP, the period being \fIT\fP. +If this process wants to use the \fInanosleep\fP() function, it must +first call \fIclock_gettime\fP() to get the current time, then calculate +the difference between the +current time and \fIT\fP0+ \fIT\fP and, finally, call \fInanosleep\fP() +using the +computed interval. However, the process could be preempted by a different +process between the two function calls, and in this case +the interval computed would be wrong; the process would wake up later +than desired. This problem would not occur with the absolute +\fIclock_nanosleep\fP() function, since only one function call would +be necessary to suspend the process until the desired time. +In other cases, however, a relative sleep is needed, and that is why +both functionalities are required. +.LP +Although it is possible to implement periodic processes using the +timers interface, this implementation would require the use of +signals, and the reservation of some signal numbers. In this regard, +the reasons for including an absolute version of the +\fIclock_nanosleep\fP() function in IEEE\ Std\ 1003.1-2001 are the +same as for the inclusion of the relative \fInanosleep\fP(). +.LP +It is also possible to implement precise periodic processes using +\fIpthread_cond_timedwait\fP(), in which an absolute timeout is specified +that +takes effect if the condition variable involved is never signaled. +However, the use of this interface is unnatural, and involves +performing other operations on mutexes and condition variables that +imply an unnecessary overhead. Furthermore, \fIpthread_cond_timedwait\fP() +is not available in implementations that do not +support threads. +.LP +Although the interface of the relative and absolute versions of the +new high resolution sleep service is the same +\fIclock_nanosleep\fP() function, the \fIrmtp\fP argument is only +used in the relative sleep. This argument is needed in the +relative \fIclock_nanosleep\fP() function to reissue the function +call if it is interrupted by a signal, but it is not needed in +the absolute \fIclock_nanosleep\fP() function call; if the call is +interrupted by a signal, the absolute \fIclock_nanosleep\fP() +function can be invoked again with the same \fIrqtp\fP argument used +in the interrupted call. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclock_getres\fP() , \fInanosleep\fP() , \fIpthread_cond_timedwait\fP() +, \fIsleep\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/clock_settime.3p b/man3p/clock_settime.3p new file mode 100644 index 000000000..5d09cb525 --- /dev/null +++ b/man3p/clock_settime.3p @@ -0,0 +1 @@ +.so man3p/clock_gettime.3p diff --git a/man3p/clog.3p b/man3p/clog.3p new file mode 100644 index 000000000..7c19d2ea0 --- /dev/null +++ b/man3p/clog.3p @@ -0,0 +1,59 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CLOG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" clog +.SH NAME +clog, clogf, clogl \- complex natural logarithm functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex clog(double complex\fP \fIz\fP\fB); +.br +float complex clogf(float complex\fP \fIz\fP\fB); +.br +long double complex clogl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex natural (base \fIe\fP) logarithm +of \fIz\fP, with a branch cut along the negative +real axis. +.SH RETURN VALUE +.LP +These functions shall return the complex natural logarithm value, +in the range of a strip mathematically unbounded along the +real axis and in the interval [-\fIi\fPpi,\ +\fIi\fPpi] along the +imaginary axis. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcexp\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/clogf.3p b/man3p/clogf.3p new file mode 100644 index 000000000..354caa31b --- /dev/null +++ b/man3p/clogf.3p @@ -0,0 +1 @@ +.so man3p/clog.3p diff --git a/man3p/clogl.3p b/man3p/clogl.3p new file mode 100644 index 000000000..354caa31b --- /dev/null +++ b/man3p/clogl.3p @@ -0,0 +1 @@ +.so man3p/clog.3p diff --git a/man3p/close.3p b/man3p/close.3p new file mode 100644 index 000000000..3f06fee6f --- /dev/null +++ b/man3p/close.3p @@ -0,0 +1,220 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CLOSE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" close +.SH NAME +close \- close a file descriptor +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int close(int\fP \fIfildes\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIclose\fP() function shall deallocate the file descriptor indicated +by \fIfildes\fP. To deallocate means to make the +file descriptor available for return by subsequent calls to \fIopen\fP() +or other functions +that allocate file descriptors. All outstanding record locks owned +by the process on the file associated with the file descriptor +shall be removed (that is, unlocked). +.LP +If \fIclose\fP() is interrupted by a signal that is to be caught, +it shall return -1 with \fIerrno\fP set to [EINTR] and the +state of \fIfildes\fP is unspecified. If an I/O error occurred while +reading from or writing to the file system during +\fIclose\fP(), it may return -1 with \fIerrno\fP set to [EIO]; if +this error is returned, the state of \fIfildes\fP is +unspecified. +.LP +When all file descriptors associated with a pipe or FIFO special file +are closed, any data remaining in the pipe or FIFO shall +be discarded. +.LP +When all file descriptors associated with an open file description +have been closed, the open file description shall be +freed. +.LP +If the link count of the file is 0, when all file descriptors associated +with the file are closed, the space occupied by the +file shall be freed and the file shall no longer be accessible. +.LP +If a STREAMS-based \fIfildes\fP is closed and the calling process +was previously registered to receive a SIGPOLL signal for events +associated with that STREAM, the calling process shall be unregistered +for events associated with the STREAM. The last +\fIclose\fP() for a STREAM shall cause the STREAM associated with +\fIfildes\fP to be dismantled. If O_NONBLOCK is not set and +there have been no signals posted for the STREAM, and if there is +data on the module's write queue, \fIclose\fP() shall wait for +an unspecified time (for each module and driver) for any output to +drain before dismantling the STREAM. The time delay can be +changed via an I_SETCLTIME \fIioctl\fP() request. If the O_NONBLOCK +flag is set, or if there +are any pending signals, \fIclose\fP() shall not wait for output to +drain, and shall dismantle the STREAM immediately. +.LP +If the implementation supports STREAMS-based pipes, and \fIfildes\fP +is associated with one end of a pipe, the last +\fIclose\fP() shall cause a hangup to occur on the other end of the +pipe. In addition, if the other end of the pipe has been named +by \fIfattach\fP(), then the last \fIclose\fP() shall force the named +end to be detached +by \fIfdetach\fP(). If the named end has no open file descriptors +associated with it and +gets detached, the STREAM associated with that end shall also be dismantled. +.LP +If \fIfildes\fP refers to the master side of a pseudo-terminal, and +this is the last close, a SIGHUP signal shall be sent to the +controlling process, if any, for which the slave side of the pseudo-terminal +is the controlling terminal. It is unspecified whether +closing the master side of the pseudo-terminal flushes all queued +input and output. +.LP +If \fIfildes\fP refers to the slave side of a STREAMS-based pseudo-terminal, +a zero-length message may be sent to the master. +.LP +When there is an outstanding cancelable asynchronous I/O operation +against \fIfildes\fP when \fIclose\fP() is called, that I/O +operation may be canceled. An I/O operation that is not canceled completes +as if the \fIclose\fP() operation had not yet occurred. +All operations that are not canceled shall complete as if the \fIclose\fP() +blocked until the operations completed. The +\fIclose\fP() operation itself need not block awaiting such I/O completion. +Whether any I/O operation is canceled, and which I/O +operation may be canceled upon \fIclose\fP(), is implementation-defined. +.LP +If a shared memory object or a memory mapped file remains referenced +at the last close (that is, a process has it mapped), then the +entire contents of the memory object shall persist until the memory +object becomes unreferenced. If this is the last close of a +shared memory object or a memory mapped file and the close results +in the memory object becoming unreferenced, and the memory +object has been unlinked, then the memory object shall be removed. +.LP +If \fIfildes\fP refers to a socket, \fIclose\fP() shall cause the +socket to be destroyed. If the socket is in connection-mode, +and the SO_LINGER option is set for the socket with non-zero linger +time, and the socket has untransmitted data, then +\fIclose\fP() shall block for up to the current linger interval until +all data is transmitted. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned; otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIclose\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B EINTR +The \fIclose\fP() function was interrupted by a signal. +.sp +.LP +The \fIclose\fP() function may fail if: +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to the file system. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Reassigning a File Descriptor +.LP +The following example closes the file descriptor associated with standard +output for the current process, re-assigns standard +output to a new file descriptor, and closes the original file descriptor +to clean up. This example assumes that the file descriptor +0 (which is the descriptor for standard input) is not closed. +.sp +.RS +.nf + +\fB#include +\&... +int pfd; +\&... +close(1); +dup(pfd); +close(pfd); +\&... +\fP +.fi +.RE +.LP +Incidentally, this is exactly what could be achieved using: +.sp +.RS +.nf + +\fBdup2(pfd, 1); +close(pfd); +\fP +.fi +.RE +.SS Closing a File Descriptor +.LP +In the following example, \fIclose\fP() is used to close a file descriptor +after an unsuccessful attempt is made to associate +that file descriptor with a stream. +.sp +.RS +.nf + +\fB#include +#include +#include +.sp + +#define LOCKFILE "/etc/ptmp" +\&... +int pfd; +FILE *fpfd; +\&... +if ((fpfd = fdopen (pfd, "w")) == NULL) { + close(pfd); + unlink(LOCKFILE); + exit(1); +} +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +An application that had used the \fIstdio\fP routine \fIfopen\fP() +to open a file should +use the corresponding \fIfclose\fP() routine rather than \fIclose\fP(). +Once a file is +closed, the file descriptor no longer exists, since the integer corresponding +to it no longer refers to a file. +.SH RATIONALE +.LP +The use of interruptible device close routines should be discouraged +to avoid problems with the implicit closes of file +descriptors by \fIexec\fP and \fIexit\fP(). This volume +of IEEE\ Std\ 1003.1-2001 only intends to permit such behavior by +specifying the [EINTR] error condition. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISTREAMS\fP , \fIfattach\fP() , \fIfclose\fP() , \fIfdetach\fP() +, \fIfopen\fP() , \fIioctl\fP() , \fIopen\fP() , the Base Definitions +volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/closedir.3p b/man3p/closedir.3p new file mode 100644 index 000000000..d5ddb4ecf --- /dev/null +++ b/man3p/closedir.3p @@ -0,0 +1,88 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CLOSEDIR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" closedir +.SH NAME +closedir \- close a directory stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int closedir(DIR *\fP\fIdirp\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIclosedir\fP() function shall close the directory stream referred +to by the argument \fIdirp\fP. Upon return, the value +of \fIdirp\fP may no longer point to an accessible object of the type +\fBDIR\fP. If a file descriptor is used to implement type +\fBDIR\fP, that file descriptor shall be closed. +.SH RETURN VALUE +.LP +Upon successful completion, \fIclosedir\fP() shall return 0; otherwise, +-1 shall be returned and \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +The \fIclosedir\fP() function may fail if: +.TP 7 +.B EBADF +The \fIdirp\fP argument does not refer to an open directory stream. +.TP 7 +.B EINTR +The \fIclosedir\fP() function was interrupted by a signal. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Closing a Directory Stream +.LP +The following program fragment demonstrates how the \fIclosedir\fP() +function is used. +.sp +.RS +.nf + +\fB\&... + DIR *dir; + struct dirent *dp; +\&... + if ((dir = opendir (".")) == NULL) { +\&... + } +.sp + + while ((dp = readdir (dir)) != NULL) { +\&... + } +.sp + + closedir(dir); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIopendir\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/closelog.3p b/man3p/closelog.3p new file mode 100644 index 000000000..904d7e950 --- /dev/null +++ b/man3p/closelog.3p @@ -0,0 +1 @@ +.so man3p/syslog.3p diff --git a/man3p/confstr.3p b/man3p/confstr.3p new file mode 100644 index 000000000..1f3a33cd3 --- /dev/null +++ b/man3p/confstr.3p @@ -0,0 +1,220 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CONFSTR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" confstr +.SH NAME +confstr \- get configurable variables +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t confstr(int\fP \fIname\fP\fB, char *\fP\fIbuf\fP\fB, size_t\fP +\fIlen\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIconfstr\fP() function shall return configuration-defined string +values. Its use and purpose are similar to \fIsysconf\fP(), but it +is used where string values rather than numeric values are returned. +.LP +The \fIname\fP argument represents the system variable to be queried. +The implementation shall support the following name +values, defined in \fI\fP. It may support others: +.LP +.sp +_CS_PATH +.br +_CS_POSIX_V6_ILP32_OFF32_CFLAGS +.br +_CS_POSIX_V6_ILP32_OFF32_LDFLAGS +.br +_CS_POSIX_V6_ILP32_OFF32_LIBS +.br +_CS_POSIX_V6_ILP32_OFFBIG_CFLAGS +.br +_CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS +.br +_CS_POSIX_V6_ILP32_OFFBIG_LIBS +.br +_CS_POSIX_V6_LP64_OFF64_CFLAGS +.br +_CS_POSIX_V6_LP64_OFF64_LDFLAGS +.br +_CS_POSIX_V6_LP64_OFF64_LIBS +.br +_CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS +.br +_CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS +.br +_CS_POSIX_V6_LPBIG_OFFBIG_LIBS +.br +_CS_POSIX_V6_WIDTH_RESTRICTED_ENVS +.br +.sp +_CS_XBS5_ILP32_OFF32_CFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_ILP32_OFF32_LDFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_ILP32_OFF32_LIBS (\fBLEGACY\fP) +.br +_CS_XBS5_ILP32_OFF32_LINTFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_ILP32_OFFBIG_CFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_ILP32_OFFBIG_LDFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_ILP32_OFFBIG_LIBS (\fBLEGACY\fP) +.br +_CS_XBS5_ILP32_OFFBIG_LINTFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_LP64_OFF64_CFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_LP64_OFF64_LDFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_LP64_OFF64_LIBS (\fBLEGACY\fP) +.br +_CS_XBS5_LP64_OFF64_LINTFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_LPBIG_OFFBIG_CFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_LPBIG_OFFBIG_LDFLAGS (\fBLEGACY\fP) +.br +_CS_XBS5_LPBIG_OFFBIG_LIBS (\fBLEGACY\fP) +.br +_CS_XBS5_LPBIG_OFFBIG_LINTFLAGS (\fBLEGACY\fP) +.br +.sp +.LP +If \fIlen\fP is not 0, and if \fIname\fP has a configuration-defined +value, \fIconfstr\fP() shall copy that value into the +\fIlen\fP-byte buffer pointed to by \fIbuf\fP. If the string to be +returned is longer than \fIlen\fP bytes, including the +terminating null, then \fIconfstr\fP() shall truncate the string to +\fIlen\fP-1 bytes and null-terminate the result. The +application can detect that the string was truncated by comparing +the value returned by \fIconfstr\fP() with \fIlen\fP. +.LP +If \fIlen\fP is 0 and \fIbuf\fP is a null pointer, then \fIconfstr\fP() +shall still return the integer value as defined +below, but shall not return a string. If \fIlen\fP is 0 but \fIbuf\fP +is not a null pointer, the result is unspecified. +.LP +If the implementation supports the POSIX shell option, the string +stored in \fIbuf\fP after a call to: +.sp +.RS +.nf + +\fBconfstr(_CS_PATH, buf, sizeof(buf)) +\fP +.fi +.RE +.LP +can be used as a value of the \fIPATH\fP environment variable that +accesses all of the standard utilities of +IEEE\ Std\ 1003.1-2001, if the return value is less than or equal +to \fIsizeof\fP( \fIbuf\fP). +.SH RETURN VALUE +.LP +If \fIname\fP has a configuration-defined value, \fIconfstr\fP() shall +return the size of buffer that would be needed to hold +the entire configuration-defined value including the terminating null. +If this return value is greater than \fIlen\fP, the string +returned in \fIbuf\fP is truncated. +.LP +If \fIname\fP is invalid, \fIconfstr\fP() shall return 0 and set \fIerrno\fP +to indicate the error. +.LP +If \fIname\fP does not have a configuration-defined value, \fIconfstr\fP() +shall return 0 and leave \fIerrno\fP +unchanged. +.SH ERRORS +.LP +The \fIconfstr\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of the \fIname\fP argument is invalid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +An application can distinguish between an invalid \fIname\fP parameter +value and one that corresponds to a configurable +variable that has no configuration-defined value by checking if \fIerrno\fP +is modified. This mirrors the behavior of \fIsysconf\fP(). +.LP +The original need for this function was to provide a way of finding +the configuration-defined default value for the environment +variable \fIPATH .\fP Since \fIPATH\fP can be modified by the user +to include directories that could contain utilities replacing +the standard utilities in the Shell and Utilities volume of IEEE\ Std\ 1003.1-2001, +applications need a way to determine +the system-supplied \fIPATH\fP environment variable value that contains +the correct search path for the standard utilities. +.LP +An application could use: +.sp +.RS +.nf + +\fBconfstr(name, (char *)NULL, (size_t)0) +\fP +.fi +.RE +.LP +to find out how big a buffer is needed for the string value; use \fImalloc\fP() +to +allocate a buffer to hold the string; and call \fIconfstr\fP() again +to get the string. Alternately, it could allocate a fixed, +static buffer that is big enough to hold most answers (perhaps 512 +or 1024 bytes), but then use \fImalloc\fP() to allocate a larger buffer +if it finds that this is too small. +.SH RATIONALE +.LP +Application developers can normally determine any configuration variable +by means of reading from the stream opened by a call +to: +.sp +.RS +.nf + +\fBpopen("command -p getconf variable", "r"); +\fP +.fi +.RE +.LP +The \fIconfstr\fP() function with a \fIname\fP argument of _CS_PATH +returns a string that can be used as a \fIPATH\fP +environment variable setting that will reference the standard shell +and utilities as described in the Shell and Utilities volume of +IEEE\ Std\ 1003.1-2001. +.LP +The \fIconfstr\fP() function copies the returned string into a buffer +supplied by the application instead of returning a +pointer to a string. This allows a cleaner function in some implementations +(such as those with lightweight threads) and resolves +questions about when the application must copy the string returned. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpathconf\fP() , \fIsysconf\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, the Shell and Utilities +volume of +IEEE\ Std\ 1003.1-2001, \fIc99\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/conj.3p b/man3p/conj.3p new file mode 100644 index 000000000..994acab46 --- /dev/null +++ b/man3p/conj.3p @@ -0,0 +1,55 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CONJ" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" conj +.SH NAME +conj, conjf, conjl \- complex conjugate functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex conj(double complex\fP \fIz\fP\fB); +.br +float complex conjf(float complex\fP \fIz\fP\fB); +.br +long double complex conjl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex conjugate of \fIz\fP, by +reversing the sign of its imaginary part. +.SH RETURN VALUE +.LP +These functions return the complex conjugate value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcarg\fP() , \fIcimag\fP() , \fIcproj\fP() , \fIcreal\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/conjf.3p b/man3p/conjf.3p new file mode 100644 index 000000000..965b61011 --- /dev/null +++ b/man3p/conjf.3p @@ -0,0 +1 @@ +.so man3p/conj.3p diff --git a/man3p/conjl.3p b/man3p/conjl.3p new file mode 100644 index 000000000..965b61011 --- /dev/null +++ b/man3p/conjl.3p @@ -0,0 +1 @@ +.so man3p/conj.3p diff --git a/man3p/connect.3p b/man3p/connect.3p new file mode 100644 index 000000000..69ff3b761 --- /dev/null +++ b/man3p/connect.3p @@ -0,0 +1,220 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CONNECT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" connect +.SH NAME +connect \- connect a socket +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int connect(int\fP \fIsocket\fP\fB, const struct sockaddr *\fP\fIaddress\fP\fB, +.br +\ \ \ \ \ \ socklen_t\fP \fIaddress_len\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIconnect\fP() function shall attempt to make a connection on +a socket. The function takes the following arguments: +.TP 7 +\fIsocket\fP +Specifies the file descriptor associated with the socket. +.TP 7 +\fIaddress\fP +Points to a \fBsockaddr\fP structure containing the peer address. +The length and format of the address depend on the address +family of the socket. +.TP 7 +\fIaddress_len\fP +Specifies the length of the \fBsockaddr\fP structure pointed to by +the \fIaddress\fP argument. +.sp +.LP +If the socket has not already been bound to a local address, \fIconnect\fP() +shall bind it to an address which, unless the +socket's address family is AF_UNIX, is an unused local address. +.LP +If the initiating socket is not connection-mode, then \fIconnect\fP() +shall set the socket's peer address, and no connection is +made. For SOCK_DGRAM sockets, the peer address identifies where all +datagrams are sent on subsequent \fIsend\fP() functions, and limits +the remote sender for subsequent \fIrecv\fP() functions. If \fIaddress\fP +is a null address for the protocol, the socket's peer +address shall be reset. +.LP +If the initiating socket is connection-mode, then \fIconnect\fP() +shall attempt to establish a connection to the address +specified by the \fIaddress\fP argument. If the connection cannot +be established immediately and O_NONBLOCK is not set for the +file descriptor for the socket, \fIconnect\fP() shall block for up +to an unspecified timeout interval until the connection is +established. If the timeout interval expires before the connection +is established, \fIconnect\fP() shall fail and the connection +attempt shall be aborted. If \fIconnect\fP() is interrupted by a signal +that is caught while blocked waiting to establish a +connection, \fIconnect\fP() shall fail and set \fIerrno\fP to [EINTR], +but the connection request shall not be aborted, and the +connection shall be established asynchronously. +.LP +If the connection cannot be established immediately and O_NONBLOCK +is set for the file descriptor for the socket, +\fIconnect\fP() shall fail and set \fIerrno\fP to [EINPROGRESS], but +the connection request shall not be aborted, and the +connection shall be established asynchronously. Subsequent calls to +\fIconnect\fP() for the same socket, before the connection is +established, shall fail and set \fIerrno\fP to [EALREADY]. +.LP +When the connection has been established asynchronously, \fIselect\fP() +and \fIpoll\fP() shall indicate that the file descriptor for the socket +is ready for writing. +.LP +The socket in use may require the process to have appropriate privileges +to use the \fIconnect\fP() function. +.SH RETURN VALUE +.LP +Upon successful completion, \fIconnect\fP() shall return 0; otherwise, +-1 shall be returned and \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +The \fIconnect\fP() function shall fail if: +.TP 7 +.B EADDRNOTAVAIL +The specified address is not available from the local machine. +.TP 7 +.B EAFNOSUPPORT +The specified address is not a valid address for the address family +of the specified socket. +.TP 7 +.B EALREADY +A connection request is already in progress for the specified socket. +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid file descriptor. +.TP 7 +.B ECONNREFUSED +The target address was not listening for connections or refused the +connection request. +.TP 7 +.B EINPROGRESS +O_NONBLOCK is set for the file descriptor for the socket and the connection +cannot be immediately established; the connection +shall be established asynchronously. +.TP 7 +.B EINTR +The attempt to establish a connection was interrupted by delivery +of a signal that was caught; the connection shall be +established asynchronously. +.TP 7 +.B EISCONN +The specified socket is connection-mode and is already connected. +.TP 7 +.B ENETUNREACH +No route to the network is present. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.TP 7 +.B EPROTOTYPE +The specified address has a different type than the socket bound to +the specified peer address. +.TP 7 +.B ETIMEDOUT +The attempt to connect timed out before a connection was made. +.sp +.LP +If the address family of the socket is AF_UNIX, then \fIconnect\fP() +shall fail if: +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to the file system. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +pathname in \fIaddress\fP. +.TP 7 +.B ENAMETOOLONG +A component of a pathname exceeded {NAME_MAX} characters, or an entire +pathname exceeded {PATH_MAX} characters. +.TP 7 +.B ENOENT +A component of the pathname does not name an existing file or the +pathname is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix of the pathname in \fIaddress\fP is +not a directory. +.sp +.LP +The \fIconnect\fP() function may fail if: +.TP 7 +.B EACCES +Search permission is denied for a component of the path prefix; or +write access to the named socket is denied. +.TP 7 +.B EADDRINUSE +Attempt to establish a connection that uses addresses that are already +in use. +.TP 7 +.B ECONNRESET +Remote host reset the connection request. +.TP 7 +.B EHOSTUNREACH +The destination host cannot be reached (probably because the host +is down or a remote router cannot reach it). +.TP 7 +.B EINVAL +The \fIaddress_len\fP argument is not a valid length for the address +family; or invalid address family in the \fBsockaddr\fP +structure. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the pathname in \fIaddress\fP. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.TP 7 +.B ENETDOWN +The local network interface used to reach the destination is down. +.TP 7 +.B ENOBUFS +No buffer space is available. +.TP 7 +.B EOPNOTSUPP +The socket is listening and cannot be connected. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +If \fIconnect\fP() fails, the state of the socket is unspecified. +Conforming applications should close the file descriptor and +create a new socket before attempting to reconnect. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIaccept\fP() , \fIbind\fP() , \fIclose\fP() , \fIgetsockname\fP() +, \fIpoll\fP() , \fIselect\fP() , \fIsend\fP() , \fIshutdown\fP() +, \fIsocket\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/copysign.3p b/man3p/copysign.3p new file mode 100644 index 000000000..a0ef7c0ae --- /dev/null +++ b/man3p/copysign.3p @@ -0,0 +1,59 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "COPYSIGN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" copysign +.SH NAME +copysign, copysignf, copysignl \- number manipulation function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double copysign(double\fP \fIx\fP\fB, double\fP \fIy\fP\fB); +.br +float copysignf(float\fP \fIx\fP\fB, float\fP \fIy\fP\fB); +.br +long double copysignl(long double\fP \fIx\fP\fB, long double\fP \fIy\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall produce a value with the magnitude of \fIx\fP +and the sign of \fIy\fP. On implementations that represent +a signed zero but do not treat negative zero consistently in arithmetic +operations, these functions regard the sign of zero as +positive. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return a value with +the magnitude of \fIx\fP and the sign of \fIy\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsignbit\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/copysignf.3p b/man3p/copysignf.3p new file mode 100644 index 000000000..83a43feaf --- /dev/null +++ b/man3p/copysignf.3p @@ -0,0 +1 @@ +.so man3p/copysign.3p diff --git a/man3p/copysignl.3p b/man3p/copysignl.3p new file mode 100644 index 000000000..83a43feaf --- /dev/null +++ b/man3p/copysignl.3p @@ -0,0 +1 @@ +.so man3p/copysign.3p diff --git a/man3p/cos.3p b/man3p/cos.3p new file mode 100644 index 000000000..b751fe7b9 --- /dev/null +++ b/man3p/cos.3p @@ -0,0 +1,101 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "COS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cos +.SH NAME +cos, cosf, cosl \- cosine function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double cos(double\fP \fIx\fP\fB); +.br +float cosf(float\fP \fIx\fP\fB); +.br +long double cosl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the cosine of their argument \fIx\fP, +measured in radians. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the cosine +of \fIx\fP. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, the value 1.0 shall be returned. +.LP +If \fIx\fP is \(+-Inf, a domain error shall occur, and either a NaN +(if supported), or an implementation-defined value +shall be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The \fIx\fP argument is \(+-Inf. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Taking the Cosine of a 45-Degree Angle +.sp +.RS +.nf + +\fB#include +\&... +double radians = 45 * M_PI / 180; +double result; +\&... +result = cos(radians); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +These functions may lose accuracy when their argument is near an odd +multiple of pi/2 or is +far from 0. +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIacos\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() +, \fIsin\fP() , \fItan\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 4.18, Treatment of Error Conditions for Mathematical Functions, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/cosf.3p b/man3p/cosf.3p new file mode 100644 index 000000000..6cff53cb9 --- /dev/null +++ b/man3p/cosf.3p @@ -0,0 +1 @@ +.so man3p/cos.3p diff --git a/man3p/cosh.3p b/man3p/cosh.3p new file mode 100644 index 000000000..39eb5b777 --- /dev/null +++ b/man3p/cosh.3p @@ -0,0 +1,93 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "COSH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cosh +.SH NAME +cosh, coshf, coshl \- hyperbolic cosine functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double cosh(double\fP \fIx\fP\fB); +.br +float coshf(float\fP \fIx\fP\fB); +.br +long double coshl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the hyperbolic cosine of their argument +\fIx\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the hyperbolic +cosine of \fIx\fP. +.LP +If the correct value would cause overflow, a range error shall occur +and \fIcosh\fP(), \fIcoshf\fP(), and \fIcoshl\fP() shall +return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, the value 1.0 shall be returned. +.LP +If \fIx\fP is \(+-Inf, +Inf shall be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Range\ Error +The result would cause an overflow. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.LP +For IEEE\ Std\ 754-1985 \fBdouble\fP, 710.5 < |\fIx\fP| implies that +\fIcosh\fP( \fIx\fP) has overflowed. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIacosh\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() +, \fIsinh\fP() , +\fItanh\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 4.18, Treatment of Error Conditions for Mathematical Functions, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/coshf.3p b/man3p/coshf.3p new file mode 100644 index 000000000..49cd5d095 --- /dev/null +++ b/man3p/coshf.3p @@ -0,0 +1 @@ +.so man3p/cosh.3p diff --git a/man3p/coshl.3p b/man3p/coshl.3p new file mode 100644 index 000000000..49cd5d095 --- /dev/null +++ b/man3p/coshl.3p @@ -0,0 +1 @@ +.so man3p/cosh.3p diff --git a/man3p/cosl.3p b/man3p/cosl.3p new file mode 100644 index 000000000..6cff53cb9 --- /dev/null +++ b/man3p/cosl.3p @@ -0,0 +1 @@ +.so man3p/cos.3p diff --git a/man3p/cpow.3p b/man3p/cpow.3p new file mode 100644 index 000000000..f765aebf0 --- /dev/null +++ b/man3p/cpow.3p @@ -0,0 +1,60 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CPOW" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cpow +.SH NAME +cpow, cpowf, cpowl \- complex power functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex cpow(double complex\fP \fIx\fP\fB, double complex\fP +\fIy\fP\fB); +.br +float complex cpowf(float complex\fP \fIx\fP\fB, float complex\fP +\fIy\fP\fB); +.br +long double complex cpowl(long double complex\fP \fIx\fP\fB, +.br +\ \ \ \ \ \ long double complex\fP \fIy\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex power function \fIx**y\fP, +with a branch cut for the first +parameter along the negative real axis. +.SH RETURN VALUE +.LP +These functions shall return the complex power function value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcabs\fP() , \fIcsqrt\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/cpowf.3p b/man3p/cpowf.3p new file mode 100644 index 000000000..a5c741eb0 --- /dev/null +++ b/man3p/cpowf.3p @@ -0,0 +1 @@ +.so man3p/cpow.3p diff --git a/man3p/cpowl.3p b/man3p/cpowl.3p new file mode 100644 index 000000000..a5c741eb0 --- /dev/null +++ b/man3p/cpowl.3p @@ -0,0 +1 @@ +.so man3p/cpow.3p diff --git a/man3p/cproj.3p b/man3p/cproj.3p new file mode 100644 index 000000000..b2b463b2a --- /dev/null +++ b/man3p/cproj.3p @@ -0,0 +1,83 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CPROJ" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cproj +.SH NAME +cproj, cprojf, cprojl \- complex projection functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex cproj(double complex\fP \fIz\fP\fB); +.br +float complex cprojf(float complex\fP \fIz\fP\fB); +.br +long double complex cprojl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute a projection of \fIz\fP onto the Riemann +sphere: \fIz\fP projects to \fIz\fP, except that all +complex infinities (even those with one infinite part and one NaN +part) project to positive infinity on the real axis. If \fIz\fP +has an infinite part, then \fIcproj\fP( \fIz\fP) shall be equivalent +to: +.sp +.RS +.nf + +\fBINFINITY + I * copysign(0.0, cimag(z)) +\fP +.fi +.RE +.SH RETURN VALUE +.LP +These functions shall return the value of the projection onto the +Riemann sphere. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Two topologies are commonly used in complex mathematics: the complex +plane with its continuum of infinities, and the Riemann +sphere with its single infinity. The complex plane is better suited +for transcendental functions, the Riemann sphere for algebraic +functions. The complex types with their multiplicity of infinities +provide a useful (though imperfect) model for the complex plane. +The \fIcproj\fP() function helps model the Riemann sphere by mapping +all infinities to one, and should be used just before any +operation, especially comparisons, that might give spurious results +for any of the other infinities. Note that a complex value with +one infinite part and one NaN part is regarded as an infinity, not +a NaN, because if one part is infinite, the complex value is +infinite independent of the value of the other part. For the same +reason, \fIcabs\fP() +returns an infinity if its argument has an infinite part and a NaN +part. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcarg\fP() , \fIcimag\fP() , \fIconj\fP() , \fIcreal\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/cprojf.3p b/man3p/cprojf.3p new file mode 100644 index 000000000..f2a22c967 --- /dev/null +++ b/man3p/cprojf.3p @@ -0,0 +1 @@ +.so man3p/cproj.3p diff --git a/man3p/cprojl.3p b/man3p/cprojl.3p new file mode 100644 index 000000000..f2a22c967 --- /dev/null +++ b/man3p/cprojl.3p @@ -0,0 +1 @@ +.so man3p/cproj.3p diff --git a/man3p/creal.3p b/man3p/creal.3p new file mode 100644 index 000000000..2d14c6f54 --- /dev/null +++ b/man3p/creal.3p @@ -0,0 +1,62 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CREAL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" creal +.SH NAME +creal, crealf, creall \- complex real functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double creal(double complex\fP \fIz\fP\fB); +.br +float crealf(float complex\fP \fIz\fP\fB); +.br +long double creall(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the real part of \fIz\fP. +.SH RETURN VALUE +.LP +These functions shall return the real part value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +For a variable \fIz\fP of type \fBcomplex\fP: +.sp +.RS +.nf + +\fBz == creal(z) + cimag(z)*I +\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcarg\fP() , \fIcimag\fP() , \fIconj\fP() , \fIcproj\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/crealf.3p b/man3p/crealf.3p new file mode 100644 index 000000000..634392493 --- /dev/null +++ b/man3p/crealf.3p @@ -0,0 +1 @@ +.so man3p/creal.3p diff --git a/man3p/creall.3p b/man3p/creall.3p new file mode 100644 index 000000000..634392493 --- /dev/null +++ b/man3p/creall.3p @@ -0,0 +1 @@ +.so man3p/creal.3p diff --git a/man3p/creat.3p b/man3p/creat.3p new file mode 100644 index 000000000..9dbba7b5c --- /dev/null +++ b/man3p/creat.3p @@ -0,0 +1,95 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CREAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" creat +.SH NAME +creat \- create a new file or rewrite an existing one +.SH SYNOPSIS +.LP +\fB#include \fP +\fB +.br +#include +.br +.sp +int creat(const char *\fP\fIpath\fP\fB, mode_t\fP \fImode\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The function call: +.sp +.RS +.nf + +\fBcreat(path, mode) +\fP +.fi +.RE +.LP +shall be equivalent to: +.sp +.RS +.nf + +\fBopen(path, O_WRONLY|O_CREAT|O_TRUNC, mode) +\fP +.fi +.RE +.SH RETURN VALUE +.LP +Refer to \fIopen\fP() . +.SH ERRORS +.LP +Refer to \fIopen\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Creating a File +.LP +The following example creates the file \fB/tmp/file\fP with read and +write permissions for the file owner and read permission +for group and others. The resulting file descriptor is assigned to +the \fIfd\fP variable. +.sp +.RS +.nf + +\fB#include +\&... +int fd; +mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH; +char *filename = "/tmp/file"; +\&... +fd = creat(filename, mode); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIcreat\fP() function is redundant. Its services are also provided +by the \fIopen\fP() function. It has been included primarily for historical +purposes since many existing +applications depend on it. It is best considered a part of the C binding +rather than a function that should be provided in other +languages. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIopen\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/crypt.3p b/man3p/crypt.3p new file mode 100644 index 000000000..1f8aa8dd3 --- /dev/null +++ b/man3p/crypt.3p @@ -0,0 +1,132 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CRYPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" crypt +.SH NAME +crypt \- string encoding function (\fBCRYPT\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *crypt(const char *\fP\fIkey\fP\fB, const char *\fP\fIsalt\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIcrypt\fP() function is a string encoding function. The algorithm +is implementation-defined. +.LP +The \fIkey\fP argument points to a string to be encoded. The \fIsalt\fP +argument is a string chosen from the set: +.sp +.RS +.nf + +\fBa b c d e f g h i j k l m n o p q r s t u v w x y z +A B C D E F G H I J K L M N O P Q R S T U V W X Y Z +0 1 2 3 4 5 6 7 8 9 . / +\fP +.fi +.RE +.LP +The first two characters of this string may be used to perturb the +encoding algorithm. +.LP +The return value of \fIcrypt\fP() points to static data that is overwritten +by each call. +.LP +The \fIcrypt\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +Upon successful completion, \fIcrypt\fP() shall return a pointer to +the encoded string. The first two characters of the +returned value shall be those of the \fIsalt\fP argument. Otherwise, +it shall return a null pointer and set \fIerrno\fP to +indicate the error. +.SH ERRORS +.LP +The \fIcrypt\fP() function shall fail if: +.TP 7 +.B ENOSYS +The functionality is not supported on this implementation. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Encoding Passwords +.LP +The following example finds a user database entry matching a particular +user name and changes the current password to a new +password. The \fIcrypt\fP() function generates an encoded version +of each password. The first call to \fIcrypt\fP() produces an +encoded version of the old password; that encoded password is then +compared to the password stored in the user database. The second +call to \fIcrypt\fP() encodes the new password before it is stored. +.LP +The \fIputpwent\fP() function, used in the following example, is not +part of IEEE\ Std\ 1003.1-2001. +.sp +.RS +.nf + +\fB#include +#include +#include +#include +\&... +int valid_change; +int pfd; /* Integer for file descriptor returned by open(). */ +FILE *fpfd; /* File pointer for use in putpwent(). */ +struct passwd *p; +char user[100]; +char oldpasswd[100]; +char newpasswd[100]; +char savepasswd[100]; +\&... +valid_change = 0; +while ((p = getpwent()) != NULL) { + /* Change entry if found. */ + if (strcmp(p->pw_name, user) == 0) { + if (strcmp(p->pw_passwd, crypt(oldpasswd, p->pw_passwd)) == 0) { + strcpy(savepasswd, crypt(newpasswd, user)); + p->pw_passwd = savepasswd; + valid_change = 1; + } + else { + fprintf(stderr, "Old password is not valid\\n"); + } + } + /* Put passwd entry into ptmp. */ + putpwent(p, fpfd); +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The values returned by this function need not be portable among XSI-conformant +systems. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIencrypt\fP() , \fIsetkey\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/csin.3p b/man3p/csin.3p new file mode 100644 index 000000000..ba9c2950d --- /dev/null +++ b/man3p/csin.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CSIN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" csin +.SH NAME +csin, csinf, csinl \- complex sine functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex csin(double complex\fP \fIz\fP\fB); +.br +float complex csinf(float complex\fP \fIz\fP\fB); +.br +long double complex csinl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex sine of \fIz\fP. +.SH RETURN VALUE +.LP +These functions shall return the complex sine value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcasin\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/csinf.3p b/man3p/csinf.3p new file mode 100644 index 000000000..b42a764b4 --- /dev/null +++ b/man3p/csinf.3p @@ -0,0 +1 @@ +.so man3p/csin.3p diff --git a/man3p/csinh.3p b/man3p/csinh.3p new file mode 100644 index 000000000..d0c37c5a1 --- /dev/null +++ b/man3p/csinh.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CSINH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" csinh +.SH NAME +csinh, csinhf, csinhl \- complex hyperbolic sine functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex csinh(double complex\fP \fIz\fP\fB); +.br +float complex csinhf(float complex\fP \fIz\fP\fB); +.br +long double complex csinhl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex hyperbolic sine of \fIz\fP. +.SH RETURN VALUE +.LP +These functions shall return the complex hyperbolic sine value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcasinh\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/csinhf.3p b/man3p/csinhf.3p new file mode 100644 index 000000000..23497d863 --- /dev/null +++ b/man3p/csinhf.3p @@ -0,0 +1 @@ +.so man3p/csinh.3p diff --git a/man3p/csinhl.3p b/man3p/csinhl.3p new file mode 100644 index 000000000..23497d863 --- /dev/null +++ b/man3p/csinhl.3p @@ -0,0 +1 @@ +.so man3p/csinh.3p diff --git a/man3p/csinl.3p b/man3p/csinl.3p new file mode 100644 index 000000000..b42a764b4 --- /dev/null +++ b/man3p/csinl.3p @@ -0,0 +1 @@ +.so man3p/csin.3p diff --git a/man3p/csqrt.3p b/man3p/csqrt.3p new file mode 100644 index 000000000..2543b2638 --- /dev/null +++ b/man3p/csqrt.3p @@ -0,0 +1,57 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CSQRT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" csqrt +.SH NAME +csqrt, csqrtf, csqrtl \- complex square root functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex csqrt(double complex\fP \fIz\fP\fB); +.br +float complex csqrtf(float complex\fP \fIz\fP\fB); +.br +long double complex csqrtl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex square root of \fIz\fP, +with a branch cut along the negative real axis. +.SH RETURN VALUE +.LP +These functions shall return the complex square root value, in the +range of the right half-plane (including the imaginary +axis). +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcabs\fP() , \fIcpow\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/csqrtf.3p b/man3p/csqrtf.3p new file mode 100644 index 000000000..5b87b5bef --- /dev/null +++ b/man3p/csqrtf.3p @@ -0,0 +1 @@ +.so man3p/csqrt.3p diff --git a/man3p/csqrtl.3p b/man3p/csqrtl.3p new file mode 100644 index 000000000..5b87b5bef --- /dev/null +++ b/man3p/csqrtl.3p @@ -0,0 +1 @@ +.so man3p/csqrt.3p diff --git a/man3p/ctan.3p b/man3p/ctan.3p new file mode 100644 index 000000000..fbd027ca3 --- /dev/null +++ b/man3p/ctan.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CTAN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ctan +.SH NAME +ctan, ctanf, ctanl \- complex tangent functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex ctan(double complex\fP \fIz\fP\fB); +.br +float complex ctanf(float complex\fP \fIz\fP\fB); +.br +long double complex ctanl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex tangent of \fIz\fP. +.SH RETURN VALUE +.LP +These functions shall return the complex tangent value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcatan\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ctanf.3p b/man3p/ctanf.3p new file mode 100644 index 000000000..785dedacb --- /dev/null +++ b/man3p/ctanf.3p @@ -0,0 +1 @@ +.so man3p/ctan.3p diff --git a/man3p/ctanh.3p b/man3p/ctanh.3p new file mode 100644 index 000000000..23c4dacd8 --- /dev/null +++ b/man3p/ctanh.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CTANH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ctanh +.SH NAME +ctanh, ctanhf, ctanhl \- complex hyperbolic tangent functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double complex ctanh(double complex\fP \fIz\fP\fB); +.br +float complex ctanhf(float complex\fP \fIz\fP\fB); +.br +long double complex ctanhl(long double complex\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complex hyperbolic tangent of \fIz\fP. +.SH RETURN VALUE +.LP +These functions shall return the complex hyperbolic tangent value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcatanh\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ctanhf.3p b/man3p/ctanhf.3p new file mode 100644 index 000000000..0599a3a89 --- /dev/null +++ b/man3p/ctanhf.3p @@ -0,0 +1 @@ +.so man3p/ctanh.3p diff --git a/man3p/ctanhl.3p b/man3p/ctanhl.3p new file mode 100644 index 000000000..0599a3a89 --- /dev/null +++ b/man3p/ctanhl.3p @@ -0,0 +1 @@ +.so man3p/ctanh.3p diff --git a/man3p/ctanl.3p b/man3p/ctanl.3p new file mode 100644 index 000000000..785dedacb --- /dev/null +++ b/man3p/ctanl.3p @@ -0,0 +1 @@ +.so man3p/ctan.3p diff --git a/man3p/ctermid.3p b/man3p/ctermid.3p new file mode 100644 index 000000000..b829fd802 --- /dev/null +++ b/man3p/ctermid.3p @@ -0,0 +1,110 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CTERMID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ctermid +.SH NAME +ctermid \- generate a pathname for the controlling terminal +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *ctermid(char *\fP\fIs\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIctermid\fP() function shall generate a string that, when used +as a pathname, refers to the current controlling terminal +for the current process. If \fIctermid\fP() returns a pathname, access +to the file is not guaranteed. +.LP +If the application uses any of the _POSIX_THREAD_SAFE_FUNCTIONS or +_POSIX_THREADS functions, it shall ensure that the +\fIctermid\fP() function is called with a non-NULL parameter. +.SH RETURN VALUE +.LP +If \fIs\fP is a null pointer, the string shall be generated in an +area that may be static (and therefore may be overwritten by +each call), the address of which shall be returned. Otherwise, \fIs\fP +is assumed to point to a character array of at least +L_ctermid bytes; the string is placed in this array and the value +of \fIs\fP shall be returned. The symbolic constant L_ctermid is +defined in \fI\fP, and shall have a value greater than 0. +.LP +The \fIctermid\fP() function shall return an empty string if the pathname +that would refer to the controlling terminal cannot +be determined, or if the function is unsuccessful. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Determining the Controlling Terminal for the Current Process +.LP +The following example returns a pointer to a string that identifies +the controlling terminal for the current process. The +pathname for the terminal is stored in the array pointed to by the +\fIptr\fP argument, which has a size of L_ctermid bytes, as +indicated by the \fIterm\fP argument. +.sp +.RS +.nf + +\fB#include +\&... +char term[L_ctermid]; +char *ptr; +.sp + +ptr = ctermid(term); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The difference between \fIctermid\fP() and \fIttyname\fP() is that +\fIttyname\fP() must be handed a file descriptor and return a path +of the terminal associated with +that file descriptor, while \fIctermid\fP() returns a string (such +as \fB"/dev/tty"\fP ) that refers to the current controlling +terminal if used as a pathname. +.SH RATIONALE +.LP +L_ctermid must be defined appropriately for a given implementation +and must be greater than zero so that array declarations +using it are accepted by the compiler. The value includes the terminating +null byte. +.LP +Conforming applications that use threads cannot call \fIctermid\fP() +with NULL as the parameter if either +_POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS is defined. If \fIs\fP +is not NULL, the \fIctermid\fP() function generates a +string that, when used as a pathname, refers to the current controlling +terminal for the current process. If \fIs\fP is NULL, the +return value of \fIctermid\fP() is undefined. +.LP +There is no additional burden on the programmer-changing to use a +hypothetical thread-safe version of \fIctermid\fP() along +with allocating a buffer is more of a burden than merely allocating +a buffer. Application code should not assume that the returned +string is short, as some implementations have more than two pathname +components before reaching a logical device name. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIttyname\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ctime.3p b/man3p/ctime.3p new file mode 100644 index 000000000..a72847658 --- /dev/null +++ b/man3p/ctime.3p @@ -0,0 +1,112 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ctime +.SH NAME +ctime, ctime_r \- convert a time value to a date and time string +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *ctime(const time_t *\fP\fIclock\fP\fB); +.br +\fP +.LP +\fBchar *ctime_r(const time_t *\fP\fIclock\fP\fB, char *\fP\fIbuf\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +For \fIctime\fP(): The functionality described on this reference +page is aligned with the ISO\ C standard. Any +conflict between the requirements described here and the ISO\ C standard +is unintentional. This volume of +IEEE\ Std\ 1003.1-2001 defers to the ISO\ C standard. +.LP +The \fIctime\fP() function shall convert the time pointed to by \fIclock\fP, +representing time in seconds since the Epoch, to +local time in the form of a string. It shall be equivalent to: +.sp +.RS +.nf + +\fBasctime(localtime(clock)) +\fP +.fi +.RE +.LP +The +\fIasctime\fP(), \fIctime\fP(), \fIgmtime\fP(), +and \fIlocaltime\fP() functions shall return values in one of two +static objects: a +broken-down time structure and an array of \fBchar\fP. Execution of +any of the functions may overwrite the information returned in +either of these objects by any of the other functions. +.LP +The \fIctime\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.LP +The \fIctime_r\fP() function shall convert the calendar time pointed +to by \fIclock\fP to local time in exactly the same form as +\fIctime\fP() and put the string into the array pointed to by \fIbuf\fP +(which shall be at least 26 bytes in size) and return +\fIbuf\fP. +.LP +Unlike \fIctime\fP(), the thread-safe version \fIctime_r\fP() is not +required to set \fItzname\fP. +.SH RETURN VALUE +.LP +The \fIctime\fP() function shall return the pointer returned by \fIasctime\fP() +with +that broken-down time as an argument. +.LP +Upon successful completion, \fIctime_r\fP() shall return a pointer +to the string pointed to by \fIbuf\fP. When an error is +encountered, a null pointer shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Values for the broken-down time structure can be obtained by calling +\fIgmtime\fP() or +\fIlocaltime\fP(). The \fIctime\fP() function is included for compatibility +with older +implementations, and does not support localized date and time formats. +Applications should use the \fIstrftime\fP() function to achieve maximum +portability. +.LP +The \fIctime_r\fP() function is thread-safe and shall return values +in a user-supplied buffer instead of possibly using a +static data area that may be overwritten by each call. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIasctime\fP() , \fIclock\fP() , \fIdifftime\fP() , \fIgmtime\fP() +, \fIlocaltime\fP() +, \fImktime\fP() , \fIstrftime\fP() , \fIstrptime\fP() , \fItime\fP() +, \fIutime\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ctime_r.3p b/man3p/ctime_r.3p new file mode 100644 index 000000000..e48210d6e --- /dev/null +++ b/man3p/ctime_r.3p @@ -0,0 +1 @@ +.so man3p/ctime.3p diff --git a/man3p/daylight.3p b/man3p/daylight.3p new file mode 100644 index 000000000..3c5f1bc17 --- /dev/null +++ b/man3p/daylight.3p @@ -0,0 +1 @@ +.so man3p/tzset.3p diff --git a/man3p/dbm_clearerr.3p b/man3p/dbm_clearerr.3p new file mode 100644 index 000000000..3e739bc5b --- /dev/null +++ b/man3p/dbm_clearerr.3p @@ -0,0 +1 @@ +.so man3p/dbm_open.3p diff --git a/man3p/dbm_close.3p b/man3p/dbm_close.3p new file mode 100644 index 000000000..3e739bc5b --- /dev/null +++ b/man3p/dbm_close.3p @@ -0,0 +1 @@ +.so man3p/dbm_open.3p diff --git a/man3p/dbm_delete.3p b/man3p/dbm_delete.3p new file mode 100644 index 000000000..3e739bc5b --- /dev/null +++ b/man3p/dbm_delete.3p @@ -0,0 +1 @@ +.so man3p/dbm_open.3p diff --git a/man3p/dbm_error.3p b/man3p/dbm_error.3p new file mode 100644 index 000000000..3e739bc5b --- /dev/null +++ b/man3p/dbm_error.3p @@ -0,0 +1 @@ +.so man3p/dbm_open.3p diff --git a/man3p/dbm_fetch.3p b/man3p/dbm_fetch.3p new file mode 100644 index 000000000..3e739bc5b --- /dev/null +++ b/man3p/dbm_fetch.3p @@ -0,0 +1 @@ +.so man3p/dbm_open.3p diff --git a/man3p/dbm_firstkey.3p b/man3p/dbm_firstkey.3p new file mode 100644 index 000000000..3e739bc5b --- /dev/null +++ b/man3p/dbm_firstkey.3p @@ -0,0 +1 @@ +.so man3p/dbm_open.3p diff --git a/man3p/dbm_nextkey.3p b/man3p/dbm_nextkey.3p new file mode 100644 index 000000000..3e739bc5b --- /dev/null +++ b/man3p/dbm_nextkey.3p @@ -0,0 +1 @@ +.so man3p/dbm_open.3p diff --git a/man3p/dbm_open.3p b/man3p/dbm_open.3p new file mode 100644 index 000000000..26de73b85 --- /dev/null +++ b/man3p/dbm_open.3p @@ -0,0 +1,238 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DBM_CLEARERR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" dbm_clearerr +.SH NAME +dbm_clearerr, dbm_close, dbm_delete, dbm_error, dbm_fetch, dbm_firstkey, +dbm_nextkey, dbm_open, dbm_store \- database +functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int dbm_clearerr(DBM *\fP\fIdb\fP\fB); +.br +void dbm_close(DBM *\fP\fIdb\fP\fB); +.br +int dbm_delete(DBM *\fP\fIdb\fP\fB, datum\fP \fIkey\fP\fB); +.br +int dbm_error(DBM *\fP\fIdb\fP\fB); +.br +datum dbm_fetch(DBM *\fP\fIdb\fP\fB, datum\fP \fIkey\fP\fB); +.br +datum dbm_firstkey(DBM *\fP\fIdb\fP\fB); +.br +datum dbm_nextkey(DBM *\fP\fIdb\fP\fB); +.br +DBM *dbm_open(const char *\fP\fIfile\fP\fB, int\fP \fIopen_flags\fP\fB, +mode_t\fP \fIfile_mode\fP\fB); +.br +int dbm_store(DBM *\fP\fIdb\fP\fB, datum\fP \fIkey\fP\fB, datum\fP +\fIcontent\fP\fB, int\fP +\fIstore_mode\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions create, access, and modify a database. +.LP +A \fBdatum\fP consists of at least two members, \fIdptr\fP and \fIdsize\fP. +The \fIdptr\fP member points to an object that +is \fIdsize\fP bytes in length. Arbitrary binary data, as well as +character strings, may be stored in the object pointed to by +\fIdptr\fP. +.LP +The database is stored in two files. One file is a directory containing +a bitmap of keys and has \fB.dir\fP as its suffix. The +second file contains all data and has \fB.pag\fP as its suffix. +.LP +The \fIdbm_open\fP() function shall open a database. The \fIfile\fP +argument to the function is the pathname of the database. +The function opens two files named \fIfile\fP\fB.dir\fP and \fIfile\fP\fB.pag\fP. +The \fIopen_flags\fP argument has the same +meaning as the \fIflags\fP argument of \fIopen\fP() except that a +database opened for +write-only access opens the files for read and write access and the +behavior of the O_APPEND flag is unspecified. The +\fIfile_mode\fP argument has the same meaning as the third argument +of \fIopen\fP(). +.LP +The \fIdbm_close\fP() function shall close a database. The application +shall ensure that argument \fIdb\fP is a pointer to a +\fBdbm\fP structure that has been returned from a call to \fIdbm_open\fP(). +.LP +These database functions shall support an internal block size large +enough to support key/content pairs of at least 1023 +bytes. +.LP +The \fIdbm_fetch\fP() function shall read a record from a database. +The argument \fIdb\fP is a pointer to a database structure +that has been returned from a call to \fIdbm_open\fP(). The argument +\fIkey\fP is a \fBdatum\fP that has been initialized by the +application to the value of the key that matches the key of the record +the program is fetching. +.LP +The \fIdbm_store\fP() function shall write a record to a database. +The argument \fIdb\fP is a pointer to a database structure +that has been returned from a call to \fIdbm_open\fP(). The argument +\fIkey\fP is a \fBdatum\fP that has been initialized by the +application to the value of the key that identifies (for subsequent +reading, writing, or deleting) the record the application is +writing. The argument \fIcontent\fP is a \fBdatum\fP that has been +initialized by the application to the value of the record the +program is writing. The argument \fIstore_mode\fP controls whether +\fIdbm_store\fP() replaces any pre-existing record that has +the same key that is specified by the \fIkey\fP argument. The application +shall set \fIstore_mode\fP to either DBM_INSERT or +DBM_REPLACE. If the database contains a record that matches the \fIkey\fP +argument and \fIstore_mode\fP is DBM_REPLACE, the +existing record shall be replaced with the new record. If the database +contains a record that matches the \fIkey\fP argument and +\fIstore_mode\fP is DBM_INSERT, the existing record shall be left +unchanged and the new record ignored. If the database does not +contain a record that matches the \fIkey\fP argument and \fIstore_mode\fP +is either DBM_INSERT or DBM_REPLACE, the new record +shall be inserted in the database. +.LP +If the sum of a key/content pair exceeds the internal block size, +the result is unspecified. Moreover, the application shall +ensure that all key/content pairs that hash together fit on a single +block. The \fIdbm_store\fP() function shall return an error +in the event that a disk block fills with inseparable data. +.LP +The \fIdbm_delete\fP() function shall delete a record and its key +from the database. The argument \fIdb\fP is a pointer to a +database structure that has been returned from a call to \fIdbm_open\fP(). +The argument \fIkey\fP is a \fBdatum\fP that has been +initialized by the application to the value of the key that identifies +the record the program is deleting. +.LP +The \fIdbm_firstkey\fP() function shall return the first key in the +database. The argument \fIdb\fP is a pointer to a database +structure that has been returned from a call to \fIdbm_open\fP(). +.LP +The \fIdbm_nextkey\fP() function shall return the next key in the +database. The argument \fIdb\fP is a pointer to a database +structure that has been returned from a call to \fIdbm_open\fP(). +The application shall ensure that the \fIdbm_firstkey\fP() +function is called before calling \fIdbm_nextkey\fP(). Subsequent +calls to \fIdbm_nextkey\fP() return the next key until all of +the keys in the database have been returned. +.LP +The \fIdbm_error\fP() function shall return the error condition of +the database. The argument \fIdb\fP is a pointer to a +database structure that has been returned from a call to \fIdbm_open\fP(). +.LP +The \fIdbm_clearerr\fP() function shall clear the error condition +of the database. The argument \fIdb\fP is a pointer to a +database structure that has been returned from a call to \fIdbm_open\fP(). +.LP +The \fIdptr\fP pointers returned by these functions may point into +static storage that may be changed by subsequent calls. +.LP +These functions need not be reentrant. A function that is not required +to be reentrant is not required to be thread-safe. +.SH RETURN VALUE +.LP +The \fIdbm_store\fP() and \fIdbm_delete\fP() functions shall return +0 when they succeed and a negative value when they +fail. +.LP +The \fIdbm_store\fP() function shall return 1 if it is called with +a \fIflags\fP value of DBM_INSERT and the function finds an +existing record with the same key. +.LP +The \fIdbm_error\fP() function shall return 0 if the error condition +is not set and return a non-zero value if the error +condition is set. +.LP +The return value of \fIdbm_clearerr\fP() is unspecified. +.LP +The \fIdbm_firstkey\fP() and \fIdbm_nextkey\fP() functions shall return +a key \fBdatum\fP. When the end of the database is +reached, the \fIdptr\fP member of the key is a null pointer. If an +error is detected, the \fIdptr\fP member of the key shall be a +null pointer and the error condition of the database shall be set. +.LP +The \fIdbm_fetch\fP() function shall return a content \fBdatum\fP. +If no record in the database matches the key or if an error +condition has been detected in the database, the \fIdptr\fP member +of the content shall be a null pointer. +.LP +The \fIdbm_open\fP() function shall return a pointer to a database +structure. If an error is detected during the operation, +\fIdbm_open\fP() shall return a ( \fBDBM *\fP)0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The following code can be used to traverse the database: +.sp +.RS +.nf + +\fBfor(key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db)) +\fP +.fi +.RE +.LP +The \fIdbm_\fP* functions provided in this library should not be confused +in any way with those of a general-purpose database +management system. These functions do not provide for multiple search +keys per entry, they do not protect against multi-user access +(in other words they do not lock records or files), and they do not +provide the many other useful database functions that are found +in more robust database management systems. Creating and updating +databases by use of these functions is relatively slow because of +data copies that occur upon hash collisions. These functions are useful +for applications requiring fast lookup of relatively static +information that is to be indexed by a single key. +.LP +Note that a strictly conforming application is extremely limited by +these functions: since there is no way to determine that the +keys in use do not all hash to the same value (although that would +be rare), a strictly conforming application cannot be guaranteed +that it can store more than one block's worth of data in the database. +As long as a key collision does not occur, additional data +may be stored, but because there is no way to determine whether an +error is due to a key collision or some other error condition ( +\fIdbm_error\fP() being effectively a Boolean), once an error is detected, +the application is effectively limited to guessing what +the error might be if it wishes to continue using these functions. +.LP +The \fIdbm_delete\fP() function need not physically reclaim file space, +although it does make it available for reuse by the +database. +.LP +After calling \fIdbm_store\fP() or \fIdbm_delete\fP() during a pass +through the keys by \fIdbm_firstkey\fP() and +\fIdbm_nextkey\fP(), the application should reset the database by +calling \fIdbm_firstkey\fP() before again calling +\fIdbm_nextkey\fP(). The contents of these files are unspecified and +may not be portable. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIopen\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/dbm_store.3p b/man3p/dbm_store.3p new file mode 100644 index 000000000..3e739bc5b --- /dev/null +++ b/man3p/dbm_store.3p @@ -0,0 +1 @@ +.so man3p/dbm_open.3p diff --git a/man3p/difftime.3p b/man3p/difftime.3p new file mode 100644 index 000000000..86f740c68 --- /dev/null +++ b/man3p/difftime.3p @@ -0,0 +1,55 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DIFFTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" difftime +.SH NAME +difftime \- compute the difference between two calendar time values +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double difftime(time_t\fP \fItime1\fP\fB, time_t\fP \fItime0\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIdifftime\fP() function shall compute the difference between +two calendar times (as returned by \fItime\fP()): \fItime\fP1- \fItime\fP0. +.SH RETURN VALUE +.LP +The \fIdifftime\fP() function shall return the difference expressed +in seconds as a type \fBdouble\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIasctime\fP() , \fIclock\fP() , \fIctime\fP() +, \fIgmtime\fP() , \fIlocaltime\fP() , \fImktime\fP() , \fIstrftime\fP() +, \fIstrptime\fP() , +\fItime\fP() , \fIutime\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/dirname.3p b/man3p/dirname.3p new file mode 100644 index 000000000..f55e878d2 --- /dev/null +++ b/man3p/dirname.3p @@ -0,0 +1,136 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DIRNAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" dirname +.SH NAME +dirname \- report the parent directory name of a file pathname +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *dirname(char *\fP\fIpath\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIdirname\fP() function shall take a pointer to a character string +that contains a pathname, and return a pointer to a +string that is a pathname of the parent directory of that file. Trailing +\fB'/'\fP characters in the path are not counted as +part of the path. +.LP +If \fIpath\fP does not contain a \fB'/'\fP , then \fIdirname\fP() +shall return a pointer to the string \fB"."\fP . If +\fIpath\fP is a null pointer or points to an empty string, \fIdirname\fP() +shall return a pointer to the string \fB"."\fP +\&. +.LP +The \fIdirname\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +The \fIdirname\fP() function shall return a pointer to a string that +is the parent directory of \fIpath\fP. If \fIpath\fP is +a null pointer or points to an empty string, a pointer to a string +\fB"."\fP is returned. +.LP +The \fIdirname\fP() function may modify the string pointed to by \fIpath\fP, +and may return a pointer to static storage that +may then be overwritten by subsequent calls to \fIdirname\fP(). +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The following code fragment reads a pathname, changes the current +working directory to the parent directory, and opens the +file. +.sp +.RS +.nf + +\fBchar path[PATH_MAX], *pathcopy; +int fd; +fgets(path, PATH_MAX, stdin); +pathcopy = strdup(path); +chdir(dirname(pathcopy)); +fd = open(basename(path), O_RDONLY); +\fP +.fi +.RE +.SS Sample Input and Output Strings for dirname() +.LP +In the following table, the input string is the value pointed to by +\fIpath\fP, and the output string is the return value of +the \fIdirname\fP() function. +.TS C +center; l l. +\fBInput String\fP \fBOutput String\fP +"/usr/lib" "/usr" +"/usr/" "/" +"usr" "." +"/" "/" +"." "." +".." "." +.TE +.SS Changing the Current Directory to the Parent Directory +.LP +The following program fragment reads a pathname, changes the current +working directory to the parent directory, and opens the +file. +.sp +.RS +.nf + +\fB#include +#include +#include +#include +#include +#include +\&... +char path[PATH_MAX], *pathcopy; +int fd; +\&... +fgets(path, PATH_MAX, stdin); +pathcopy = strdup(path); +chdir(dirname(pathcopy)); +fd = open(basename(path), O_RDONLY); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIdirname\fP() and \fIbasename\fP() functions together yield +a complete +pathname. The expression \fIdirname\fP(\fIpath\fP) obtains the pathname +of the directory where \fIbasename\fP(\fIpath\fP) is +found. +.LP +Since the meaning of the leading \fB"//"\fP is implementation-defined, +\fIdirname\fP(" \fB//foo\fP) may return either +\fB"//"\fP or \fB'/'\fP (but nothing else). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIbasename\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/div.3p b/man3p/div.3p new file mode 100644 index 000000000..8917fcc66 --- /dev/null +++ b/man3p/div.3p @@ -0,0 +1,67 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DIV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" div +.SH NAME +div \- compute the quotient and remainder of an integer division +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +div_t div(int\fP \fInumer\fP\fB, int\fP \fIdenom\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIdiv\fP() function shall compute the quotient and remainder +of the division of the numerator \fInumer\fP by the +denominator \fIdenom\fP. If the division is inexact, the resulting +quotient is the integer of lesser magnitude that is the nearest +to the algebraic quotient. If the result cannot be represented, the +behavior is undefined; otherwise, \fIquot\fP* \fIdenom\fP+ +\fIrem\fP shall equal \fInumer\fP. +.SH RETURN VALUE +.LP +The \fIdiv\fP() function shall return a structure of type \fBdiv_t\fP, +comprising both the quotient and the remainder. The +structure includes the following members, in any order: +.sp +.RS +.nf + +\fBint quot; /* quotient */ +int rem; /* remainder */ +\fP +.fi +.RE +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIldiv\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/dlclose.3p b/man3p/dlclose.3p new file mode 100644 index 000000000..bde49e45a --- /dev/null +++ b/man3p/dlclose.3p @@ -0,0 +1,110 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DLCLOSE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" dlclose +.SH NAME +dlclose \- close a dlopen object +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int dlclose(void *\fP\fIhandle\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIdlclose\fP() function shall inform the system that the object +referenced by a \fIhandle\fP returned from a previous \fIdlopen\fP() +invocation is no longer needed by the application. +.LP +The use of \fIdlclose\fP() reflects a statement of intent on the part +of the process, but does not create any requirement upon +the implementation, such as removal of the code or symbols referenced +by \fIhandle\fP. Once an object has been closed using +\fIdlclose\fP() an application should assume that its symbols are +no longer available to \fIdlsym\fP(). All objects loaded automatically +as a result of invoking \fIdlopen\fP() on the referenced object shall +also be closed if this is the last reference to +it. +.LP +Although a \fIdlclose\fP() operation is not required to remove structures +from an address space, neither is an implementation +prohibited from doing so. The only restriction on such a removal is +that no object shall be removed to which references have been +relocated, until or unless all such references are removed. For instance, +an object that had been loaded with a \fIdlopen\fP() operation specifying +the RTLD_GLOBAL flag might provide a target for dynamic +relocations performed in the processing of other objects-in such environments, +an application may assume that no relocation, once +made, shall be undone or remade unless the object requiring the relocation +has itself been removed. +.SH RETURN VALUE +.LP +If the referenced object was successfully closed, \fIdlclose\fP() +shall return 0. If the object could not be closed, or if +\fIhandle\fP does not refer to an open object, \fIdlclose\fP() shall +return a non-zero value. More detailed diagnostic +information shall be available through \fIdlerror\fP(). +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The following example illustrates use of \fIdlopen\fP() and \fIdlclose\fP(): +.sp +.RS +.nf + +\fB\&... +/* Open a dynamic library and then close it ... */ +.sp + +#include +void *mylib; +int eret; +.sp + +mylib = dlopen("mylib.so", RTLD_LOCAL | RTLD_LAZY); +\&... +eret = dlclose(mylib); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +A conforming application should employ a \fIhandle\fP returned from +a \fIdlopen\fP() +invocation only within a given scope bracketed by the \fIdlopen\fP() +and \fIdlclose\fP() +operations. Implementations are free to use reference counting or +other techniques such that multiple calls to \fIdlopen\fP() referencing +the same object may return the same object for \fIhandle\fP. +Implementations are also free to reuse a \fIhandle\fP. For these reasons, +the value of a \fIhandle\fP must be treated as an +opaque object by the application, used only in calls to \fIdlsym\fP() +and +\fIdlclose\fP(). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIdlerror\fP() , \fIdlopen\fP() , \fIdlsym\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/dlerror.3p b/man3p/dlerror.3p new file mode 100644 index 000000000..05da3c22a --- /dev/null +++ b/man3p/dlerror.3p @@ -0,0 +1,88 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DLERROR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" dlerror +.SH NAME +dlerror \- get diagnostic information +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *dlerror(void); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIdlerror\fP() function shall return a null-terminated character +string (with no trailing ) that describes +the last error that occurred during dynamic linking processing. If +no dynamic linking errors have occurred since the last +invocation of \fIdlerror\fP(), \fIdlerror\fP() shall return NULL. +Thus, invoking \fIdlerror\fP() a second time, immediately +following a prior invocation, shall result in NULL being returned. +.LP +The \fIdlerror\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +If successful, \fIdlerror\fP() shall return a null-terminated character +string; otherwise, NULL shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The following example prints out the last dynamic linking error: +.sp +.RS +.nf + +\fB\&... +#include +.sp + +char *errstr; +.sp + +errstr = dlerror(); +if (errstr != NULL) +printf ("A dynamic linking error occurred: (%s)\\n", errstr); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The messages returned by \fIdlerror\fP() may reside in a static buffer +that is overwritten on each call to \fIdlerror\fP(). +Application code should not write to this buffer. Programs wishing +to preserve an error message should make their own copies of +that message. Depending on the application environment with respect +to asynchronous execution events, such as signals or other +asynchronous computation sharing the address space, conforming applications +should use a critical section to retrieve the error +pointer and buffer. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIdlclose\fP() , \fIdlopen\fP() , \fIdlsym\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/dlopen.3p b/man3p/dlopen.3p new file mode 100644 index 000000000..3ae0d5797 --- /dev/null +++ b/man3p/dlopen.3p @@ -0,0 +1,194 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DLOPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" dlopen +.SH NAME +dlopen \- gain access to an executable object file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void *dlopen(const char *\fP\fIfile\fP\fB, int\fP \fImode\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIdlopen\fP() function shall make an executable object file specified +by \fIfile\fP available to the calling program. The +class of files eligible for this operation and the manner of their +construction are implementation-defined, though typically such +files are executable objects such as shared libraries, relocatable +files, or programs. Note that some implementations permit the +construction of dependencies between such objects that are embedded +within files. In such cases, a \fIdlopen\fP() operation shall +load such dependencies in addition to the object referenced by \fIfile\fP. +Implementations may also impose specific constraints on +the construction of programs that can employ \fIdlopen\fP() and its +related services. +.LP +A successful \fIdlopen\fP() shall return a \fIhandle\fP which the +caller may use on subsequent calls to \fIdlsym\fP() and \fIdlclose\fP(). +The value of this +\fIhandle\fP should not be interpreted in any way by the caller. +.LP +The \fIfile\fP argument is used to construct a pathname to the object +file. If \fIfile\fP contains a slash character, the +\fIfile\fP argument is used as the pathname for the file. Otherwise, +\fIfile\fP is used in an implementation-defined manner to +yield a pathname. +.LP +If the value of \fIfile\fP is 0, \fIdlopen\fP() shall provide a \fIhandle\fP +on a global symbol object. This object shall +provide access to the symbols from an ordered set of objects consisting +of the original program image file, together with any +objects loaded at program start-up as specified by that process image +file (for example, shared libraries), and the set of objects +loaded using a \fIdlopen\fP() operation together with the RTLD_GLOBAL +flag. As the latter set of objects can change during +execution, the set identified by \fIhandle\fP can also change dynamically. +.LP +Only a single copy of an object file is brought into the address space, +even if \fIdlopen\fP() is invoked multiple times in +reference to the file, and even if different pathnames are used to +reference the file. +.LP +The \fImode\fP parameter describes how \fIdlopen\fP() shall operate +upon \fIfile\fP with respect to the processing of +relocations and the scope of visibility of the symbols provided within +\fIfile\fP. When an object is brought into the address +space of a process, it may contain references to symbols whose addresses +are not known until the object is loaded. These references +shall be relocated before the symbols can be accessed. The \fImode\fP +parameter governs when these relocations take place and may +have the following values: +.TP 7 +RTLD_LAZY +Relocations shall be performed at an implementation-defined time, +ranging from the time of the \fIdlopen\fP() call until the +first reference to a given symbol occurs. Specifying RTLD_LAZY should +improve performance on implementations supporting dynamic +symbol binding as a process may not reference all of the functions +in any given object. And, for systems supporting dynamic symbol +resolution for normal process execution, this behavior mimics the +normal handling of process execution. +.TP 7 +RTLD_NOW +All necessary relocations shall be performed when the object is first +loaded. This may waste some processing if relocations are +performed for functions that are never referenced. This behavior may +be useful for applications that need to know as soon as an +object is loaded that all symbols referenced during execution are +available. +.sp +.LP +Any object loaded by \fIdlopen\fP() that requires relocations against +global symbols can reference the symbols in the original +process image file, any objects loaded at program start-up, from the +object itself as well as any other object included in the same +\fIdlopen\fP() invocation, and any objects that were loaded in any +\fIdlopen\fP() invocation and which specified the RTLD_GLOBAL +flag. To determine the scope of visibility for the symbols loaded +with a \fIdlopen\fP() invocation, the \fImode\fP parameter +should be a bitwise-inclusive OR with one of the following values: +.TP 7 +RTLD_GLOBAL +The object's symbols shall be made available for the relocation processing +of any other object. In addition, symbol lookup +using \fIdlopen\fP(\fI0, mode\fP) and an associated \fIdlsym\fP() +allows objects loaded +with this \fImode\fP to be searched. +.TP 7 +RTLD_LOCAL +The object's symbols shall not be made available for the relocation +processing of any other object. +.sp +.LP +If neither RTLD_GLOBAL nor RTLD_LOCAL are specified, then an implementation-defined +default behavior shall be applied. +.LP +If a \fIfile\fP is specified in multiple \fIdlopen\fP() invocations, +\fImode\fP is interpreted at each invocation. Note, +however, that once RTLD_NOW has been specified all relocations shall +have been completed rendering further RTLD_NOW operations +redundant and any further RTLD_LAZY operations irrelevant. Similarly, +note that once RTLD_GLOBAL has been specified the object +shall maintain the RTLD_GLOBAL status regardless of any previous or +future specification of RTLD_LOCAL, as long as the object +remains in the address space (see \fIdlclose\fP() ). +.LP +Symbols introduced into a program through calls to \fIdlopen\fP() +may be used in relocation activities. Symbols so introduced +may duplicate symbols already defined by the program or previous \fIdlopen\fP() +operations. To resolve the ambiguities such a +situation might present, the resolution of a symbol reference to symbol +definition is based on a symbol resolution order. Two such +resolution orders are defined: \fIload\fP or \fIdependency\fP ordering. +Load order establishes an ordering among symbol +definitions, such that the definition first loaded (including definitions +from the image file and any dependent objects loaded with +it) has priority over objects added later (via \fIdlopen\fP()). Load +ordering is used in relocation processing. Dependency +ordering uses a breadth-first order starting with a given object, +then all of its dependencies, then any dependents of those, +iterating until all dependencies are satisfied. With the exception +of the global symbol object obtained via a \fIdlopen\fP() +operation on a \fIfile\fP of 0, dependency ordering is used by the +\fIdlsym\fP() function. +Load ordering is used in \fIdlsym\fP() operations upon the global +symbol object. +.LP +When an object is first made accessible via \fIdlopen\fP() it and +its dependent objects are added in dependency order. Once all +the objects are added, relocations are performed using load order. +Note that if an object or its dependencies had been previously +loaded, the load and dependency orders may yield different resolutions. +.LP +The symbols introduced by \fIdlopen\fP() operations and available +through \fIdlsym\fP() +are at a minimum those which are exported as symbols of global scope +by the object. Typically such symbols shall be those that were +specified in (for example) C source code as having \fIextern\fP linkage. +The precise manner in which an implementation constructs +the set of exported symbols for a \fIdlopen\fP() object is specified +by that implementation. +.SH RETURN VALUE +.LP +If \fIfile\fP cannot be found, cannot be opened for reading, is not +of an appropriate object format for processing by +\fIdlopen\fP(), or if an error occurs during the process of loading +\fIfile\fP or relocating its symbolic references, +\fIdlopen\fP() shall return NULL. More detailed diagnostic information +shall be available through \fIdlerror\fP() . +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIdlclose\fP() , \fIdlerror\fP() , \fIdlsym\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/dlsym.3p b/man3p/dlsym.3p new file mode 100644 index 000000000..e6b8bfa67 --- /dev/null +++ b/man3p/dlsym.3p @@ -0,0 +1,148 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DLSYM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" dlsym +.SH NAME +dlsym \- obtain the address of a symbol from a dlopen object +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void *dlsym(void *restrict\fP \fIhandle\fP\fB, const char *restrict\fP +\fIname\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIdlsym\fP() function shall obtain the address of a symbol defined +within an object made accessible through a \fIdlopen\fP() call. The +\fIhandle\fP argument is the value returned from a call to \fIdlopen\fP() +(and which has not since been released via a call to \fIdlclose\fP()), +and \fIname\fP is the symbol's name as a character string. +.LP +The \fIdlsym\fP() function shall search for the named symbol in all +objects loaded automatically as a result of loading the +object referenced by \fIhandle\fP (see \fIdlopen\fP() ). Load ordering +is used in \fIdlsym\fP() +operations upon the global symbol object. The symbol resolution algorithm +used shall be dependency order as described in \fIdlopen\fP() . +.LP +The RTLD_DEFAULT and RTLD_NEXT flags are reserved for future use. +.SH RETURN VALUE +.LP +If \fIhandle\fP does not refer to a valid object opened by \fIdlopen\fP(), +or if the +named symbol cannot be found within any of the objects associated +with \fIhandle\fP, \fIdlsym\fP() shall return NULL. More +detailed diagnostic information shall be available through \fIdlerror\fP() +\&. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The following example shows how \fIdlopen\fP() and \fIdlsym\fP() can +be used to access +either function or data objects. For simplicity, error checking has +been omitted. +.sp +.RS +.nf + +\fBvoid *handle; +int *iptr, (*fptr)(int); +.sp + +/* open the needed object */ +handle = dlopen("/usr/home/me/libfoo.so", RTLD_LOCAL | RTLD_LAZY); +.sp + +/* find the address of function and data objects */ +*(void **)(&fptr) = dlsym(handle, "my_function"); +iptr = (int *)dlsym(handle, "my_object"); +.sp + +/* invoke function, passing value of integer as a parameter */ +(*fptr)(*iptr); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +Special purpose values for \fIhandle\fP are reserved for future use. +These values and their meanings are: +.TP 7 +RTLD_DEFAULT +The symbol lookup happens in the normal global scope; that is, a search +for a symbol using this handle would find the same +definition as a direct use of this symbol in the program code. +.TP 7 +RTLD_NEXT +Specifies the next object after this one that defines \fIname\fP. +\fIThis one\fP refers to the object containing the +invocation of \fIdlsym\fP(). The \fInext\fP object is the one found +upon the application of a load order symbol resolution +algorithm (see \fIdlopen\fP() ). The next object is either one of +global scope (because it was +introduced as part of the original process image or because it was +added with a \fIdlopen\fP() operation including the RTLD_GLOBAL flag), +or is an object that was included in the +same \fIdlopen\fP() operation that loaded this one. +.LP +The RTLD_NEXT flag is useful to navigate an intentionally created +hierarchy of multiply-defined symbols created through +\fIinterposition\fP. For example, if a program wished to create an +implementation of \fImalloc\fP() that embedded some statistics gathering +about memory allocations, such an +implementation could use the real \fImalloc\fP() definition to perform +the memory +allocation-and itself only embed the necessary logic to implement +the statistics gathering function. +.sp +.SH RATIONALE +.LP +The ISO\ C standard does not require that pointers to functions can +be cast back and forth to pointers to data. Indeed, the +ISO\ C standard does not require that an object of type \fBvoid *\fP +can hold a pointer to a function. Implementations +supporting the XSI extension, however, do require that an object of +type \fBvoid *\fP can hold a pointer to a function. The result +of converting a pointer to a function into a pointer to another data +type (except \fBvoid *\fP) is still undefined, however. Note +that compilers conforming to the ISO\ C standard are required to generate +a warning if a conversion from a \fBvoid *\fP +pointer to a function pointer is attempted as in: +.sp +.RS +.nf + +\fBfptr = (int (*)(int))dlsym(handle, "my_function"); +\fP +.fi +.RE +.LP +Due to the problem noted here, a future version may either add a new +function to return function pointers, or the current +interface may be deprecated in favor of two new functions: one that +returns data pointers and the other that returns function +pointers. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIdlclose\fP() , \fIdlerror\fP() , \fIdlopen\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/drand48.3p b/man3p/drand48.3p new file mode 100644 index 000000000..d82e57204 --- /dev/null +++ b/man3p/drand48.3p @@ -0,0 +1,167 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DRAND48" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" drand48 +.SH NAME +drand48, erand48, jrand48, lcong48, lrand48, mrand48, nrand48, seed48, +srand48 \- generate uniformly distributed +pseudo\-random numbers +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double drand48(void); +.br +double erand48(unsigned short\fP \fIxsubi\fP\fB[3]); +.br +long jrand48(unsigned short\fP \fIxsubi\fP\fB[3]); +.br +void lcong48(unsigned short\fP \fIparam\fP\fB[7]); +.br +long lrand48(void); +.br +long mrand48(void); +.br +long nrand48(unsigned short\fP \fIxsubi\fP\fB[3]); +.br +unsigned short *seed48(unsigned short\fP \fIseed16v\fP\fB[3]); +.br +void srand48(long\fP \fIseedval\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +This family of functions shall generate pseudo-random numbers using +a linear congruential algorithm and 48-bit integer +arithmetic. +.LP +The \fIdrand48\fP() and \fIerand48\fP() functions shall return non-negative, +double-precision, floating-point values, +uniformly distributed over the interval [0.0,1.0). +.LP +The \fIlrand48\fP() and \fInrand48\fP() functions shall return non-negative, +long integers, uniformly distributed over the +interval [0,2**31). +.LP +The \fImrand48\fP() and \fIjrand48\fP() functions shall return signed +long integers uniformly distributed over the interval +[-2**31,2**31). +.LP +The \fIsrand48\fP(), \fIseed48\fP(), and \fIlcong48\fP() functions +are initialization entry points, one of which should be +invoked before either \fIdrand48\fP(), \fIlrand48\fP(), or \fImrand48\fP() +is called. (Although it is not recommended practice, +constant default initializer values shall be supplied automatically +if \fIdrand48\fP(), \fIlrand48\fP(), or \fImrand48\fP() is +called without a prior call to an initialization entry point.) The +\fIerand48\fP(), \fInrand48\fP(), and \fIjrand48\fP() +functions do not require an initialization entry point to be called +first. +.LP +All the routines work by generating a sequence of 48-bit integer values, +X_i , according to the linear congruential +formula: +X_n+1 = (aX_n + c)_mod m\ \ \ n>= 0 +.LP +The parameter \fIm\fP = 2**48; hence 48-bit integer arithmetic is +performed. Unless \fIlcong48\fP() is invoked, the multiplier +value \fIa\fP and the addend value \fIc\fP are given by: +\fIa\fP = 5DEECE66D_16 = 273673163155_8 +.LP +\fIc\fP = B_16 = 13_8 +.LP +The value returned by any of the \fIdrand48\fP(), \fIerand48\fP(), +\fIjrand48\fP(), \fIlrand48\fP(), \fImrand48\fP(), or +\fInrand48\fP() functions is computed by first generating the next +48-bit X_i in the sequence. Then the appropriate number +of bits, according to the type of data item to be returned, are copied +from the high-order (leftmost) bits of X_i and +transformed into the returned value. +.LP +The \fIdrand48\fP(), \fIlrand48\fP(), and \fImrand48\fP() functions +store the last 48-bit X_i generated in an internal +buffer; that is why the application shall ensure that these are initialized +prior to being invoked. The \fIerand48\fP(), +\fInrand48\fP(), and \fIjrand48\fP() functions require the calling +program to provide storage for the successive X_i values +in the array specified as an argument when the functions are invoked. +That is why these routines do not have to be initialized; the +calling program merely has to place the desired initial value of X_i +into the array and pass it as an argument. By using +different arguments, \fIerand48\fP(), \fInrand48\fP(), and \fIjrand48\fP() +allow separate modules of a large program to generate +several \fIindependent\fP streams of pseudo-random numbers; that is, +the sequence of numbers in each stream shall \fInot\fP +depend upon how many times the routines are called to generate numbers +for the other streams. +.LP +The initializer function \fIsrand48\fP() sets the high-order 32 bits +of X_i to the low-order 32 bits contained in its +argument. The low-order 16 bits of X_i are set to the arbitrary value +330E_16. +.LP +The initializer function \fIseed48\fP() sets the value of X_i to the +48-bit value specified in the argument array. The +low-order 16 bits of X_i are set to the low-order 16 bits of \fIseed16v\fP[\fI0\fP]. +The mid-order 16 bits of X_i are +set to the low-order 16 bits of \fIseed16v\fP[\fI1\fP]. The high-order +16 bits of X_i are set to the low-order 16 bits of +\fIseed16v\fP[\fI2\fP]. In addition, the previous value of X_i is +copied into a 48-bit internal buffer, used only by +\fIseed48\fP(), and a pointer to this buffer is the value returned +by \fIseed48\fP(). This returned pointer, which can just be +ignored if not needed, is useful if a program is to be restarted from +a given point at some future time-use the pointer to get at +and store the last X_i value, and then use this value to reinitialize +via \fIseed48\fP() when the program is restarted. +.LP +The initializer function \fIlcong48\fP() allows the user to specify +the initial X_i , the multiplier value \fIa\fP, and the +addend value \fIc\fP. +Argument array elements \fIparam\fP[\fI0-2\fP] specify X_i , \fIparam\fP[\fI3-5\fP] +specify the +multiplier \fIa\fP, and \fIparam\fP[\fI6\fP] specifies the 16-bit +addend \fIc\fP. After \fIlcong48\fP() is called, a subsequent call +to +either \fIsrand48\fP() or \fIseed48\fP() shall restore the standard +multiplier and addend values, \fIa\fP and \fIc,\fP +specified above. +.LP +The \fIdrand48\fP(), \fIlrand48\fP(), and \fImrand48\fP() functions +need not be reentrant. A function that is not required to +be reentrant is not required to be thread-safe. +.SH RETURN VALUE +.LP +As described in the DESCRIPTION above. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIrand\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/dup.3p b/man3p/dup.3p new file mode 100644 index 000000000..138da196a --- /dev/null +++ b/man3p/dup.3p @@ -0,0 +1,194 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DUP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" dup +.SH NAME +dup, dup2 \- duplicate an open file descriptor +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int dup(int\fP \fIfildes\fP\fB); +.br +int dup2(int\fP \fIfildes\fP\fB, int\fP \fIfildes2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIdup\fP() and \fIdup2\fP() functions provide an alternative +interface to the service provided by \fIfcntl\fP() using the F_DUPFD +command. The call: +.sp +.RS +.nf + +\fBfid = dup(\fP\fIfildes\fP\fB); +\fP +.fi +.RE +.LP +shall be equivalent to: +.sp +.RS +.nf + +\fBfid = fcntl(\fP\fIfildes\fP\fB, F_DUPFD, 0); +\fP +.fi +.RE +.LP +The call: +.sp +.RS +.nf + +\fBfid = dup2(\fP\fIfildes\fP\fB,\fP \fIfildes2\fP\fB); +\fP +.fi +.RE +.LP +shall be equivalent to: +.sp +.RS +.nf + +\fBclose(\fP\fIfildes2\fP\fB); +fid = fcntl(\fP\fIfildes\fP\fB, F_DUPFD,\fP \fIfildes2\fP\fB); +\fP +.fi +.RE +.LP +except for the following: +.IP " *" 3 +If \fIfildes2\fP is less than 0 or greater than or equal to {OPEN_MAX}, +\fIdup2\fP() shall return -1 with \fIerrno\fP set to +[EBADF]. +.LP +.IP " *" 3 +If \fIfildes\fP is a valid file descriptor and is equal to \fIfildes2\fP, +\fIdup2\fP() shall return \fIfildes2\fP without +closing it. +.LP +.IP " *" 3 +If \fIfildes\fP is not a valid file descriptor, \fIdup2\fP() shall +return -1 and shall not close \fIfildes2\fP. +.LP +.IP " *" 3 +The value returned shall be equal to the value of \fIfildes2\fP upon +successful completion, or -1 upon failure. +.LP +.SH RETURN VALUE +.LP +Upon successful completion a non-negative integer, namely the file +descriptor, shall be returned; otherwise, -1 shall be +returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIdup\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid open file descriptor. +.TP 7 +.B EMFILE +The number of file descriptors in use by this process would exceed +{OPEN_MAX}. +.sp +.LP +The \fIdup2\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid open file descriptor or the +argument \fIfildes2\fP is negative or greater than or +equal to {OPEN_MAX}. +.TP 7 +.B EINTR +The \fIdup2\fP() function was interrupted by a signal. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Redirecting Standard Output to a File +.LP +The following example closes standard output for the current processes, +re-assigns standard output to go to the file referenced +by \fIpfd\fP, and closes the original file descriptor to clean up. +.sp +.RS +.nf + +\fB#include +\&... +int pfd; +\&... +close(1); +dup(pfd); +close(pfd); +\&... +\fP +.fi +.RE +.SS Redirecting Error Messages +.LP +The following example redirects messages from \fIstderr\fP to \fIstdout\fP. +.sp +.RS +.nf + +\fB#include +\&... +dup2(1, 2); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIdup\fP() and \fIdup2\fP() functions are redundant. Their services +are also provided by the \fIfcntl\fP() function. They have been included +in this volume of IEEE\ Std\ 1003.1-2001 +primarily for historical reasons, since many existing applications +use them. +.LP +While the brief code segment shown is very similar in behavior to +\fIdup2\fP(), a conforming implementation based on other +functions defined in this volume of IEEE\ Std\ 1003.1-2001 is significantly +more complex. Least obvious is the possible +effect of a signal-catching function that could be invoked between +steps and allocate or deallocate file descriptors. This could be +avoided by blocking signals. +.LP +The \fIdup2\fP() function is not marked obsolescent because it presents +a type-safe version of functionality provided in a +type-unsafe version by \fIfcntl\fP(). It is used in the POSIX Ada +binding. +.LP +The \fIdup2\fP() function is not intended for use in critical regions +as a synchronization mechanism. +.LP +In the description of [EBADF], the case of \fIfildes\fP being out +of range is covered by the given case of \fIfildes\fP not +being valid. The descriptions for \fIfildes\fP and \fIfildes2\fP are +different because the only kind of invalidity that is +relevant for \fIfildes2\fP is whether it is out of range; that is, +it does not matter whether \fIfildes2\fP refers to an open +file when the \fIdup2\fP() call is made. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclose\fP() , \fIfcntl\fP() , \fIopen\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/dup2.3p b/man3p/dup2.3p new file mode 100644 index 000000000..8ee51a99f --- /dev/null +++ b/man3p/dup2.3p @@ -0,0 +1 @@ +.so man3p/dup.3p diff --git a/man3p/ecvt.3p b/man3p/ecvt.3p new file mode 100644 index 000000000..6dd617130 --- /dev/null +++ b/man3p/ecvt.3p @@ -0,0 +1,119 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ECVT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ecvt +.SH NAME +ecvt, fcvt, gcvt \- convert a floating-point number to a string (\fBLEGACY\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *ecvt(double\fP \fIvalue\fP\fB, int\fP \fIndigit\fP\fB, int *restrict\fP +\fIdecpt\fP\fB, +.br +\ \ \ \ \ \ int *restrict\fP \fIsign\fP\fB); +.br +char *fcvt(double\fP \fIvalue\fP\fB, int\fP \fIndigit\fP\fB, int *restrict\fP +\fIdecpt\fP\fB, +.br +\ \ \ \ \ \ int *restrict\fP \fIsign\fP\fB); +.br +char *gcvt(double\fP \fIvalue\fP\fB, int\fP \fIndigit\fP\fB, char +*\fP\fIbuf\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIecvt\fP(), \fIfcvt\fP(), and \fIgcvt\fP() functions shall convert +floating-point numbers to null-terminated +strings. +.LP +The \fIecvt\fP() function shall convert \fIvalue\fP to a null-terminated +string of \fIndigit\fP digits (where \fIndigit\fP +is reduced to an unspecified limit determined by the precision of +a \fBdouble\fP) and return a pointer to the string. The +high-order digit shall be non-zero, unless the value is 0. The low-order +digit shall be rounded in an implementation-defined +manner. The position of the radix character relative to the beginning +of the string shall be stored in the integer pointed to by +\fIdecpt\fP (negative means to the left of the returned digits). If +\fIvalue\fP is zero, it is unspecified whether the integer +pointed to by \fIdecpt\fP would be 0 or 1. The radix character shall +not be included in the returned string. If the sign of the +result is negative, the integer pointed to by \fIsign\fP shall be +non-zero; otherwise, it shall be 0. +.LP +If the converted value is out of range or is not representable, the +contents of the returned string are unspecified. +.LP +The \fIfcvt\fP() function shall be equivalent to \fIecvt\fP(), except +that \fIndigit\fP specifies the number of digits +desired after the radix character. The total number of digits in the +result string is restricted to an unspecified limit as +determined by the precision of a \fBdouble\fP. +.LP +The \fIgcvt\fP() function shall convert \fIvalue\fP to a null-terminated +string (similar to that of the \fB%g\fP conversion +specification format of \fIprintf\fP()) in the array pointed to by +\fIbuf\fP and shall +return \fIbuf\fP. It shall produce \fIndigit\fP significant digits +(limited to an unspecified value determined by the precision +of a \fBdouble\fP) in the \fB%f\fP conversion specification format +of \fIprintf\fP() if +possible, or the \fB%e\fP conversion specification format of \fIprintf\fP() +(scientific +notation) otherwise. A minus sign shall be included in the returned +string if \fIvalue\fP is less than 0. A radix character shall +be included in the returned string if \fIvalue\fP is not a whole number. +Trailing zeros shall be suppressed where \fIvalue\fP is +not a whole number. The radix character is determined by the current +locale. If \fIsetlocale\fP() has not been called successfully, the +default locale, POSIX, is used. The +default locale specifies a period ( \fB'.'\fP ) as the radix character. +The \fILC_NUMERIC\fP category determines the value of +the radix character within the current locale. +.LP +These functions need not be reentrant. A function that is not required +to be reentrant is not required to be thread-safe. +.SH RETURN VALUE +.LP +The \fIecvt\fP() and \fIfcvt\fP() functions shall return a pointer +to a null-terminated string of digits. +.LP +The \fIgcvt\fP() function shall return \fIbuf\fP. +.LP +The return values from \fIecvt\fP() and \fIfcvt\fP() may point to +static data which may be overwritten by subsequent calls to +these functions. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIsprintf\fP() function is preferred over this function. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +These functions may be withdrawn in a future version. +.SH SEE ALSO +.LP +\fIprintf\fP() , \fIsetlocale\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/encrypt.3p b/man3p/encrypt.3p new file mode 100644 index 000000000..81ebee925 --- /dev/null +++ b/man3p/encrypt.3p @@ -0,0 +1,84 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ENCRYPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" encrypt +.SH NAME +encrypt \- encoding function (\fBCRYPT\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void encrypt(char\fP \fIblock\fP\fB[64], int\fP \fIedflag\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIencrypt\fP() function shall provide access to an implementation-defined +encoding algorithm. The key generated by \fIsetkey\fP() is used to +encrypt the string \fIblock\fP with \fIencrypt\fP(). +.LP +The \fIblock\fP argument to \fIencrypt\fP() shall be an array of length +64 bytes containing only the bytes with values of 0 +and 1. The array is modified in place to a similar array using the +key set by \fIsetkey\fP(). If \fIedflag\fP is 0, the argument is encoded. +If \fIedflag\fP is 1, the argument +may be decoded (see the APPLICATION USAGE section); if the argument +is not decoded, \fIerrno\fP shall be set to [ENOSYS]. +.LP +The \fIencrypt\fP() function shall not change the setting of \fIerrno\fP +if successful. An application wishing to check for +error situations should set \fIerrno\fP to 0 before calling \fIencrypt\fP(). +If \fIerrno\fP is non-zero on return, an error has +occurred. +.LP +The \fIencrypt\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +The \fIencrypt\fP() function shall not return a value. +.SH ERRORS +.LP +The \fIencrypt\fP() function shall fail if: +.TP 7 +.B ENOSYS +The functionality is not supported on this implementation. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Historical implementations of the \fIencrypt\fP() function used a +rather primitive encoding algorithm. +.LP +In some environments, decoding might not be implemented. This is related +to some Government restrictions on encryption and +decryption routines. Historical practice has been to ship a different +version of the encryption library without the decryption +feature in the routines supplied. Thus the exported version of \fIencrypt\fP() +does encoding but not decoding. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcrypt\fP() , \fIsetkey\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/endgrent.3p b/man3p/endgrent.3p new file mode 100644 index 000000000..8dc5addf7 --- /dev/null +++ b/man3p/endgrent.3p @@ -0,0 +1 @@ +.so man3p/getgrent.3p diff --git a/man3p/endhostent.3p b/man3p/endhostent.3p new file mode 100644 index 000000000..490b7646b --- /dev/null +++ b/man3p/endhostent.3p @@ -0,0 +1 @@ +.so man3p/gethostent.3p diff --git a/man3p/endnetent.3p b/man3p/endnetent.3p new file mode 100644 index 000000000..17b642ad2 --- /dev/null +++ b/man3p/endnetent.3p @@ -0,0 +1 @@ +.so man3p/getnetent.3p diff --git a/man3p/endprotoent.3p b/man3p/endprotoent.3p new file mode 100644 index 000000000..82a414026 --- /dev/null +++ b/man3p/endprotoent.3p @@ -0,0 +1 @@ +.so man3p/getprotoent.3p diff --git a/man3p/endpwent.3p b/man3p/endpwent.3p new file mode 100644 index 000000000..235cf8b3e --- /dev/null +++ b/man3p/endpwent.3p @@ -0,0 +1 @@ +.so man3p/getpwent.3p diff --git a/man3p/endservent.3p b/man3p/endservent.3p new file mode 100644 index 000000000..dc6b5d8e9 --- /dev/null +++ b/man3p/endservent.3p @@ -0,0 +1 @@ +.so man3p/getservent.3p diff --git a/man3p/endutxent.3p b/man3p/endutxent.3p new file mode 100644 index 000000000..f7769c373 --- /dev/null +++ b/man3p/endutxent.3p @@ -0,0 +1 @@ +.so man3p/getutxid.3p diff --git a/man3p/environ.3p b/man3p/environ.3p new file mode 100644 index 000000000..fe3e7ef50 --- /dev/null +++ b/man3p/environ.3p @@ -0,0 +1 @@ +.so man3p/exec.3p diff --git a/man3p/erand48.3p b/man3p/erand48.3p new file mode 100644 index 000000000..a71d5ed19 --- /dev/null +++ b/man3p/erand48.3p @@ -0,0 +1 @@ +.so man3p/drand48.3p diff --git a/man3p/erf.3p b/man3p/erf.3p new file mode 100644 index 000000000..bdb18c9a5 --- /dev/null +++ b/man3p/erf.3p @@ -0,0 +1,91 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ERF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" erf +.SH NAME +erf, erff, erfl \- error functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double erf(double\fP \fIx\fP\fB); +.br +float erff(float\fP \fIx\fP\fB); +.br +long double erfl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the error function of their argument +\fIx\fP, defined as: +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the value +of the error function. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, \(+-0 shall be returned. +.LP +If \fIx\fP is \(+-Inf, \(+-1 shall be returned. +.LP +If \fIx\fP is subnormal, a range error may occur, and 2 * \fIx\fP/ +\fIsqrt\fP(pi) should +be returned. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +Range\ Error +The result underflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Underflow occurs when |\fIx\fP| < DBL_MIN * ( \fIsqrt\fP(pi)/2). +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIerfc\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/erfc.3p b/man3p/erfc.3p new file mode 100644 index 000000000..ec1f39f73 --- /dev/null +++ b/man3p/erfc.3p @@ -0,0 +1,103 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ERFC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" erfc +.SH NAME +erfc, erfcf, erfcl \- complementary error functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double erfc(double\fP \fIx\fP\fB); +.br +float erfcf(float\fP \fIx\fP\fB); +.br +long double erfcl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the complementary error function 1.0 +- \fIerf\fP(\fIx\fP). +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the value +of the complementary error function. +.LP +If the correct value would cause underflow and is not representable, +a range error may occur and \ either 0.0 (if +representable), or an implementation-defined value shall be +returned. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, +1 shall be returned. +.LP +If \fIx\fP is -Inf, +2 shall be returned. +.LP +If \fIx\fP is +Inf, +0 shall be returned. +.LP +If the correct value would cause underflow and is representable, a +range error may occur and the correct value shall be +returned. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +Range\ Error +The result underflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIerfc\fP() function is provided because of the extreme loss +of relative accuracy if \fIerf\fP(\fIx\fP) is called for +large \fIx\fP and the result subtracted from 1.0. +.LP +Note for IEEE\ Std\ 754-1985 \fBdouble\fP, 26.55 < \fIx\fP implies +\fIerfc\fP( \fIx\fP) has underflowed. +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIerf\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/erfcf.3p b/man3p/erfcf.3p new file mode 100644 index 000000000..6f5479687 --- /dev/null +++ b/man3p/erfcf.3p @@ -0,0 +1 @@ +.so man3p/erfc.3p diff --git a/man3p/erfcl.3p b/man3p/erfcl.3p new file mode 100644 index 000000000..6f5479687 --- /dev/null +++ b/man3p/erfcl.3p @@ -0,0 +1 @@ +.so man3p/erfc.3p diff --git a/man3p/erff.3p b/man3p/erff.3p new file mode 100644 index 000000000..044e4c99a --- /dev/null +++ b/man3p/erff.3p @@ -0,0 +1 @@ +.so man3p/erf.3p diff --git a/man3p/erfl.3p b/man3p/erfl.3p new file mode 100644 index 000000000..044e4c99a --- /dev/null +++ b/man3p/erfl.3p @@ -0,0 +1 @@ +.so man3p/erf.3p diff --git a/man3p/errno.3p b/man3p/errno.3p new file mode 100644 index 000000000..951a1428b --- /dev/null +++ b/man3p/errno.3p @@ -0,0 +1,74 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ERRNO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" errno +.SH NAME +errno \- error return value +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +The lvalue \fIerrno\fP is used by many functions to return error values. +.LP +Many functions provide an error number in \fIerrno\fP, which has type +\fBint\fP and is defined in \fI\fP. The value of \fIerrno\fP +shall be defined only after a call to a function +for which it is explicitly stated to be set and until it is changed +by the next function call or if the application assigns it a +value. The value of \fIerrno\fP should only be examined when it is +indicated to be valid by a function's return value. +Applications shall obtain the definition of \fIerrno\fP by the inclusion +of \fI\fP. No function in this volume of IEEE\ Std\ 1003.1-2001 +shall set +\fIerrno\fP to 0. +.LP +It is unspecified whether \fIerrno\fP is a macro or an identifier +declared with external linkage. If a macro definition is +suppressed in order to access an actual object, or a program defines +an identifier with the name \fIerrno\fP, the behavior is +undefined. +.LP +The symbolic values stored in \fIerrno\fP are documented in the ERRORS +sections on all relevant pages. +.SH RETURN VALUE +.LP +None. +.SH ERRORS +.LP +None. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Previously both POSIX and X/Open documents were more restrictive than +the ISO\ C standard in that they required \fIerrno\fP +to be defined as an external variable, whereas the ISO\ C standard +required only that \fIerrno\fP be defined as a modifiable +lvalue with type \fBint\fP. +.LP +An application that needs to examine the value of \fIerrno\fP to determine +the error should set it to 0 before a function call, +then inspect it before a subsequent function call. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIError Numbers\fP , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/exec.3p b/man3p/exec.3p new file mode 100644 index 000000000..1eaa026b0 --- /dev/null +++ b/man3p/exec.3p @@ -0,0 +1,863 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "EXEC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" exec +.SH NAME +environ, execl, execv, execle, execve, execlp, execvp \- execute a +file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +extern char **environ; +.br +int execl(const char *\fP\fIpath\fP\fB, const char *\fP\fIarg0\fP\fB, +\&... /*, (char *)0 */); +.br +int execv(const char *\fP\fIpath\fP\fB, char *const\fP \fIargv\fP\fB[]); +.br +int execle(const char *\fP\fIpath\fP\fB, const char *\fP\fIarg0\fP\fB, +\&... /*, +.br +\ \ \ \ \ \ (char *)0, char *const\fP \fIenvp\fP\fB[]*/); +.br +int execve(const char *\fP\fIpath\fP\fB, char *const\fP \fIargv\fP\fB[], +char *const\fP \fIenvp\fP\fB[]); +.br +int execlp(const char *\fP\fIfile\fP\fB, const char *\fP\fIarg0\fP\fB, +\&... /*, (char *)0 */); +.br +int execvp(const char *\fP\fIfile\fP\fB, char *const\fP \fIargv\fP\fB[]); +.br +\fP +.SH DESCRIPTION +.LP +The \fIexec\fP family of functions shall replace the current process +image with a new process image. The new image shall be +constructed from a regular, executable file called the \fInew process +image file\fP. There shall be no return from a successful +\fIexec\fP, because the calling process image is overlaid by the new +process image. +.LP +When a C-language program is executed as a result of this call, it +shall be entered as a C-language function call as +follows: +.sp +.RS +.nf + +\fBint main (\fP\fIint argc, char *argv\fP\fB[]); +\fP +.fi +.RE +.LP +where \fIargc\fP is the argument count and \fIargv\fP is an array +of character pointers to the arguments themselves. In +addition, the following variable: +.sp +.RS +.nf + +\fBextern char **environ; +\fP +.fi +.RE +.LP +is initialized as a pointer to an array of character pointers to the +environment strings. The \fIargv\fP and \fIenviron\fP +arrays are each terminated by a null pointer. The null pointer terminating +the \fIargv\fP array is not counted in \fIargc\fP. +.LP +Conforming multi-threaded applications shall not use the \fIenviron\fP +variable to access or modify any environment variable while +any other thread is concurrently modifying any environment variable. +A call to any function dependent on any environment variable +shall be considered a use of the \fIenviron\fP variable to access +that environment variable. +.LP +The arguments specified by a program with one of the \fIexec\fP functions +shall be passed on to the new process image in the +corresponding \fImain\fP() arguments. +.LP +The argument \fIpath\fP points to a pathname that identifies the new +process image file. +.LP +The argument \fIfile\fP is used to construct a pathname that identifies +the new process image file. If the \fIfile\fP argument +contains a slash character, the \fIfile\fP argument shall be used +as the pathname for this file. Otherwise, the path prefix for +this file is obtained by a search of the directories passed as the +environment variable \fIPATH\fP (see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables). +If this +environment variable is not present, the results of the search are +implementation-defined. +.LP +There are two distinct ways in which the contents of the process image +file may cause the execution to fail, distinguished by +the setting of \fIerrno\fP to either [ENOEXEC] or [EINVAL] (see the +ERRORS section). In the cases where the other members of the +\fIexec\fP family of functions would fail and set \fIerrno\fP to [ENOEXEC], +the \fIexeclp\fP() and \fIexecvp\fP() functions +shall execute a command interpreter and the environment of the executed +command shall be as if the process invoked the \fIsh\fP utility using +\fIexecl\fP() as follows: +.sp +.RS +.nf + +\fBexecl(, arg0, file, arg1, ..., (char *)0); +\fP +.fi +.RE +.LP +where <\fIshell\ path\fP> is an unspecified pathname for the \fIsh\fP +utility, +\fIfile\fP is the process image file, and for \fIexecvp\fP(), where +\fIarg\fP0, \fIarg\fP1, and so on correspond to the values +passed to \fIexecvp\fP() in \fIargv\fP[0], \fIargv\fP[1], and so on. +.LP +The arguments represented by \fIarg0\fP,... are pointers to null-terminated +character strings. These strings shall constitute +the argument list available to the new process image. The list is +terminated by a null pointer. The argument \fIarg0\fP should +point to a filename that is associated with the process being started +by one of the \fIexec\fP functions. +.LP +The argument \fIargv\fP is an array of character pointers to null-terminated +strings. The application shall ensure that the +last member of this array is a null pointer. These strings shall constitute +the argument list available to the new process image. +The value in \fIargv\fP[0] should point to a filename that is associated +with the process being started by one of the \fIexec\fP +functions. +.LP +The argument \fIenvp\fP is an array of character pointers to null-terminated +strings. These strings shall constitute the +environment for the new process image. The \fIenvp\fP array is terminated +by a null pointer. +.LP +For those forms not containing an \fIenvp\fP pointer ( \fIexecl\fP(), +\fIexecv\fP(), \fIexeclp\fP(), and \fIexecvp\fP()), +the environment for the new process image shall be taken from the +external variable \fIenviron\fP in the calling process. +.LP +The number of bytes available for the new process' combined argument +and environment lists is {ARG_MAX}. It is +implementation-defined whether null terminators, pointers, and/or +any alignment bytes are included in this total. +.LP +File descriptors open in the calling process image shall remain open +in the new process image, except for those whose close-on- +\fIexec\fP flag FD_CLOEXEC is set. For those file descriptors that +remain open, all attributes of the open file description remain +unchanged. For any file descriptor that is closed for this reason, +file locks are removed as a result of the close as described in +\fIclose\fP() . Locks that are not removed by closing of file descriptors +remain unchanged. +.LP +If file descriptors 0, 1, and 2 would otherwise be closed after a +successful call to one of the \fIexec\fP family of functions, +and the new process image file has the set-user-ID or set-group-ID +file mode bits set, \ and the +ST_NOSUID bit is not set for the file system containing the new process +image file, implementations may open an unspecified file for each +of these file descriptors in the new process +image. +.LP +Directory streams open in the calling process image shall be closed +in the new process image. +.LP +The state of the floating-point environment in the new process image +shall be set to the default. +.LP +The state of conversion descriptors and message catalog descriptors +in the new process image is undefined. \ For the new process image, +the equivalent of: +.sp +.RS +.nf + +\fBsetlocale(LC_ALL, "C") +\fP +.fi +.RE +.LP +shall be executed at start-up. +.LP +Signals set to the default action (SIG_DFL) in the calling process +image shall be set to the default action in the new process +image. Except for SIGCHLD, signals set to be ignored (SIG_IGN) by +the calling process image shall be set to be ignored by the new +process image. Signals set to be caught by the calling process image +shall be set to the default action in the new process image +(see \fI\fP). If the SIGCHLD signal is set to be ignored +by the calling +process image, it is unspecified whether the SIGCHLD signal is set +to be ignored or to the default action in the new process image. +\ After a successful call to any of the \fIexec\fP functions, alternate +signal stacks are not preserved and the SA_ONSTACK +flag shall be cleared for all signals. +.LP +After a successful call to any of the \fIexec\fP functions, any functions +previously registered by \fIatexit\fP() are no longer registered. +.LP +If the ST_NOSUID bit is set for the file system containing the new +process image file, then the effective user ID, effective group +ID, saved set-user-ID, and saved set-group-ID are unchanged in the +new process image. Otherwise, if the set-user-ID mode bit of the +new process image file is set, the effective user ID of the new +process image shall be set to the user ID of the new process image +file. Similarly, if the set-group-ID mode bit of the new process +image file is set, the effective group ID of the new process image +shall be set to the group ID of the new process image file. The +real user ID, real group ID, and supplementary group IDs of the new +process image shall remain the same as those of the calling +process image. The effective user ID and effective group ID of the +new process image shall be saved (as the saved set-user-ID and +the saved set-group-ID) for use by \fIsetuid\fP(). +.LP +Any shared memory segments attached to the calling process image shall +not be attached to the new process image. +.LP +Any named semaphores open in the calling process shall be closed as +if by appropriate calls to \fIsem_close\fP(). +.LP +Any blocks of typed memory that were mapped in the calling process +are unmapped, as if \fImunmap\fP() was implicitly called to unmap +them. +.LP +Memory locks established by the calling process via calls to \fImlockall\fP() +or \fImlock\fP() shall be removed. If locked pages in the address +space of the calling process are also +mapped into the address spaces of other processes and are locked by +those processes, the locks established by the other processes +shall be unaffected by the call by this process to the \fIexec\fP +function. If the \fIexec\fP function fails, the effect on +memory locks is unspecified. +.LP +Memory mappings created in the process are unmapped before the address +space is rebuilt for the new process image. +.LP +For +the SCHED_FIFO and SCHED_RR scheduling policies, the policy and priority +settings shall not be changed by a call to an \fIexec\fP +function. For other scheduling policies, the policy and priority settings +on \fIexec\fP are implementation-defined. +.LP +Per-process timers created by the calling process shall be deleted +before replacing the current process image with the new process +image. +.LP +All open message queue descriptors in the calling process shall be +closed, as described in \fImq_close\fP() . +.LP +Any outstanding asynchronous I/O operations may be canceled. Those +asynchronous I/O operations that are not canceled shall complete +as if the \fIexec\fP function had not yet occurred, but any associated +signal notifications shall be suppressed. It is unspecified +whether the \fIexec\fP function itself blocks awaiting such I/O completion. +In no event, however, shall the new process image +created by the \fIexec\fP function be affected by the presence of +outstanding asynchronous I/O operations at the time the +\fIexec\fP function is called. Whether any I/O is canceled, and which +I/O may be canceled upon \fIexec\fP, is +implementation-defined. +.LP +The new process image shall inherit the CPU-time clock of the calling +process image. This inheritance means that the process +CPU-time clock of the process being \fIexec\fP-ed shall not be reinitialized +or altered as a result of the \fIexec\fP function +other than to reflect the time spent by the process executing the +\fIexec\fP function itself. +.LP +The initial value of the CPU-time clock of the initial thread of the +new process image shall be set to zero. +.LP +If the calling process is being traced, the new process image shall +continue to be traced into the same trace stream as the +original process image, but the new process image shall not inherit +the mapping of trace event names to trace event type +identifiers that was defined by calls to the \fIposix_trace_eventid_open\fP() +or the \fIposix_trace_trid_eventid_open\fP() functions in the calling +process +image. +.LP +If the calling process is a trace controller process, any trace streams +that were created by the calling process shall be shut +down as described in the \fIposix_trace_shutdown\fP() function. +.LP +The new process shall inherit at least the following attributes from +the calling process image: +.IP " *" 3 +Nice value (see \fInice\fP() ) +.LP +.IP " *" 3 +\fIsemadj\fP values (see \fIsemop\fP() ) +.LP +.IP " *" 3 +Process ID +.LP +.IP " *" 3 +Parent process ID +.LP +.IP " *" 3 +Process group ID +.LP +.IP " *" 3 +Session membership +.LP +.IP " *" 3 +Real user ID +.LP +.IP " *" 3 +Real group ID +.LP +.IP " *" 3 +Supplementary group IDs +.LP +.IP " *" 3 +Time left until an alarm clock signal (see \fIalarm\fP() ) +.LP +.IP " *" 3 +Current working directory +.LP +.IP " *" 3 +Root directory +.LP +.IP " *" 3 +File mode creation mask (see \fIumask\fP() ) +.LP +.IP " *" 3 +File size limit (see \fIulimit\fP() ) +.LP +.IP " *" 3 +Process signal mask (see \fIsigprocmask\fP() ) +.LP +.IP " *" 3 +Pending signal (see \fIsigpending\fP() ) +.LP +.IP " *" 3 +\fItms_utime\fP, \fItms_stime\fP, \fItms_cutime\fP, and \fItms_cstime\fP +(see \fItimes\fP() ) +.LP +.IP " *" 3 +Resource limits +.LP +.IP " *" 3 +Controlling terminal +.LP +.IP " *" 3 +Interval timers +.LP +.LP +All other process attributes defined in this volume of IEEE\ Std\ 1003.1-2001 +shall be the same in the new and old +process images. The inheritance of process attributes not defined +by this volume of IEEE\ Std\ 1003.1-2001 is +implementation-defined. +.LP +A call to any \fIexec\fP function from a process with more than one +thread shall result in all threads being terminated and the +new executable image being loaded and executed. No destructor functions +shall be called. +.LP +Upon successful completion, the \fIexec\fP functions shall mark for +update the \fIst_atime\fP field of the file. If an +\fIexec\fP function failed but was able to locate the process image +file, whether the \fIst_atime\fP field is marked for update +is unspecified. Should the \fIexec\fP function succeed, the process +image file shall be considered to have been opened with \fIopen\fP(). +The corresponding \fIclose\fP() shall be +considered to occur at a time after this open, but before process +termination or successful completion of a subsequent call to one +of the \fIexec\fP functions, \fIposix_spawn\fP(), or \fIposix_spawnp\fP(). +The \fIargv\fP[] and \fIenvp\fP[] arrays of pointers and the strings +to which those arrays point shall not be modified by a call to one +of the \fIexec\fP functions, except as a consequence of +replacing the process image. +.LP +The saved resource limits in the new process image are set to be a +copy of the process' corresponding hard and soft limits. +.SH RETURN VALUE +.LP +If one of the \fIexec\fP functions returns to the calling process +image, an error has occurred; the return value shall be -1, +and \fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +The \fIexec\fP functions shall fail if: +.TP 7 +.B E2BIG +The number of bytes used by the new process image's argument list +and environment list is greater than the system-imposed limit +of {ARG_MAX} bytes. +.TP 7 +.B EACCES +Search permission is denied for a directory listed in the new process +image file's path prefix, or the new process image file +denies execution permission, or the new process image file is not +a regular file and the implementation does not support execution +of files of its type. +.TP 7 +.B EINVAL +The new process image file has the appropriate permission and has +a recognized executable binary format, but the system does +not support execution of a file with this format. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP or \fIfile\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP or \fIfile\fP arguments exceeds {PATH_MAX} +or a pathname component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP or \fIfile\fP does not name an existing +file or \fIpath\fP or \fIfile\fP is an empty string. +.TP 7 +.B ENOTDIR +A component of the new process image file's path prefix is not a directory. +.sp +.LP +The \fIexec\fP functions, except for \fIexeclp\fP() and \fIexecvp\fP(), +shall fail if: +.TP 7 +.B ENOEXEC +The new process image file has the appropriate access permission but +has an unrecognized format. +.sp +.LP +The \fIexec\fP functions may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP or \fIfile\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.TP 7 +.B ENOMEM +The new process image requires more memory than is allowed by the +hardware or system-imposed memory management +constraints. +.TP 7 +.B ETXTBSY +The new process image file is a pure procedure (shared text) file +that is currently open for writing by some process. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Using execl() +.LP +The following example executes the \fIls\fP command, specifying the +pathname of the +executable ( \fB/bin/ls\fP) and using arguments supplied directly +to the command to produce single-column output. +.sp +.RS +.nf + +\fB#include +.sp + +int ret; +\&... +ret = execl ("/bin/ls", "ls", "-1", (char *)0); +\fP +.fi +.RE +.SS Using execle() +.LP +The following example is similar to Using execl() . In addition, it +specifies the environment +for the new process image using the \fIenv\fP argument. +.sp +.RS +.nf + +\fB#include +.sp + +int ret; +char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 }; +\&... +ret = execle ("/bin/ls", "ls", "-l", (char *)0, env); +\fP +.fi +.RE +.SS Using execlp() +.LP +The following example searches for the location of the \fIls\fP command +among the +directories specified by the \fIPATH\fP environment variable. +.sp +.RS +.nf + +\fB#include +.sp + +int ret; +\&... +ret = execlp ("ls", "ls", "-l", (char *)0); +\fP +.fi +.RE +.SS Using execv() +.LP +The following example passes arguments to the \fIls\fP command in +the \fIcmd\fP array. +.sp +.RS +.nf + +\fB#include +.sp + +int ret; +char *cmd[] = { "ls", "-l", (char *)0 }; +\&... +ret = execv ("/bin/ls", cmd); +\fP +.fi +.RE +.SS Using execve() +.LP +The following example passes arguments to the \fIls\fP command in +the \fIcmd\fP array, and +specifies the environment for the new process image using the \fIenv\fP +argument. +.sp +.RS +.nf + +\fB#include +.sp + +int ret; +char *cmd[] = { "ls", "-l", (char *)0 }; +char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 }; +\&... +ret = execve ("/bin/ls", cmd, env); +\fP +.fi +.RE +.SS Using execvp() +.LP +The following example searches for the location of the \fIls\fP command +among the +directories specified by the \fIPATH\fP environment variable, and +passes arguments to the \fIls\fP command in the \fIcmd\fP array. +.sp +.RS +.nf + +\fB#include +.sp + +int ret; +char *cmd[] = { "ls", "-l", (char *)0 }; +\&... +ret = execvp ("ls", cmd); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +As the state of conversion descriptors and message catalog descriptors +in the new process image is undefined, conforming +applications should not rely on their use and should close them prior +to calling one of the \fIexec\fP functions. +.LP +Applications that require other than the default POSIX locale should +call \fIsetlocale\fP() with the appropriate parameters to establish +the locale of the new +process. +.LP +The \fIenviron\fP array should not be accessed directly by the application. +.LP +Applications should not depend on file descriptors 0, 1, and 2 being +closed after an \fIexec\fP. A future version may allow +these file descriptors to be automatically opened for any process. +.SH RATIONALE +.LP +Early proposals required that the value of \fIargc\fP passed to \fImain\fP() +be "one or greater". This was driven by the +same requirement in drafts of the ISO\ C standard. In fact, historical +implementations have passed a value of zero when no +arguments are supplied to the caller of the \fIexec\fP functions. +This requirement was removed from the ISO\ C standard and +subsequently removed from this volume of IEEE\ Std\ 1003.1-2001 as +well. The wording, in particular the use of the word +\fIshould\fP, requires a Strictly Conforming POSIX Application to +pass at least one argument to the \fIexec\fP function, thus +guaranteeing that \fIargc\fP be one or greater when invoked by such +an application. In fact, this is good practice, since many +existing applications reference \fIargv\fP[0] without first checking +the value of \fIargc\fP. +.LP +The requirement on a Strictly Conforming POSIX Application also states +that the value passed as the first argument be a filename +associated with the process being started. Although some existing +applications pass a pathname rather than a filename in some +circumstances, a filename is more generally useful, since the common +usage of \fIargv\fP[0] is in printing diagnostics. In some +cases the filename passed is not the actual filename of the file; +for example, many implementations of the \fIlogin\fP utility use +a convention of prefixing a hyphen ( \fB'-'\fP ) to the actual filename, +which indicates to the command interpreter being +invoked that it is a "login shell". +.LP +Historically there have been two ways that implementations can \fIexec\fP +shell scripts. +.LP +One common historical implementation is that the \fIexecl\fP(), \fIexecv\fP(), +\fIexecle\fP(), and \fIexecve\fP() functions +return an [ENOEXEC] error for any file not recognizable as executable, +including a shell script. When the \fIexeclp\fP() and +\fIexecvp\fP() functions encounter such a file, they assume the file +to be a shell script and invoke a known command interpreter +to interpret such files. This is now required by IEEE\ Std\ 1003.1-2001. +These implementations of \fIexecvp\fP() and +\fIexeclp\fP() only give the [ENOEXEC] error in the rare case of a +problem with the command interpreter's executable file. Because +of these implementations, the [ENOEXEC] error is not mentioned for +\fIexeclp\fP() or \fIexecvp\fP(), although implementations can +still give it. +.LP +Another way that some historical implementations handle shell scripts +is by recognizing the first two bytes of the file as the +character string \fB"#!"\fP and using the remainder of the first line +of the file as the name of the command interpreter to +execute. +.LP +One potential source of confusion noted by the standard developers +is over how the contents of a process image file affect the +behavior of the \fIexec\fP family of functions. The following is a +description of the actions taken: +.IP " 1." 4 +If the process image file is a valid executable (in a format that +is executable and valid and having appropriate permission) for +this system, then the system executes the file. +.LP +.IP " 2." 4 +If the process image file has appropriate permission and is in a format +that is executable but not valid for this system (such +as a recognized binary for another architecture), then this is an +error and \fIerrno\fP is set to [EINVAL] (see later RATIONALE on +[EINVAL]). +.LP +.IP " 3." 4 +If the process image file has appropriate permission but is not otherwise +recognized: +.RS +.IP " a." 4 +If this is a call to \fIexeclp\fP() or \fIexecvp\fP(), then they invoke +a command interpreter assuming that the process image +file is a shell script. +.LP +.IP " b." 4 +If this is not a call to \fIexeclp\fP() or \fIexecvp\fP(), then an +error occurs and \fIerrno\fP is set to [ENOEXEC]. +.LP +.RE +.LP +.LP +Applications that do not require to access their arguments may use +the form: +.sp +.RS +.nf + +\fBmain(void) +\fP +.fi +.RE +as specified in the ISO\ C standard. However, the implementation will +always provide the two arguments \fIargc\fP and +\fIargv\fP, even if they are not used. +.LP +Some implementations provide a third argument to \fImain\fP() called +\fIenvp\fP. This is defined as a pointer to the +environment. The ISO\ C standard specifies invoking \fImain\fP() with +two arguments, so implementations must support +applications written this way. Since this volume of IEEE\ Std\ 1003.1-2001 +defines the global variable \fIenviron\fP, +which is also provided by historical implementations and can be used +anywhere that \fIenvp\fP could be used, there is no +functional need for the \fIenvp\fP argument. Applications should use +the \fIgetenv\fP() +function rather than accessing the environment directly via either +\fIenvp\fP or \fIenviron\fP. Implementations are required to +support the two-argument calling sequence, but this does not prohibit +an implementation from supporting \fIenvp\fP as an optional +third argument. +.LP +This volume of IEEE\ Std\ 1003.1-2001 specifies that signals set to +SIG_IGN remain set to SIG_IGN, and that the process +signal mask be unchanged across an \fIexec\fP. This is consistent +with historical implementations, and it permits some useful +functionality, such as the \fInohup\fP command. However, it should +be noted that many +existing applications wrongly assume that they start with certain +signals set to the default action and/or unblocked. In +particular, applications written with a simpler signal model that +does not include blocking of signals, such as the one in the +ISO\ C standard, may not behave properly if invoked with some signals +blocked. Therefore, it is best not to block or ignore +signals across \fIexec\fPs without explicit reason to do so, and especially +not to block signals across \fIexec\fPs of arbitrary +(not closely co-operating) programs. +.LP +The \fIexec\fP functions always save the value of the effective user +ID and effective group ID of the process at the completion +of the \fIexec\fP, whether or not the set-user-ID or the set-group-ID +bit of the process image file is set. +.LP +The statement about \fIargv\fP[] and \fIenvp\fP[] being constants +is included to make explicit to future writers of language +bindings that these objects are completely constant. Due to a limitation +of the ISO\ C standard, it is not possible to state +that idea in standard C. Specifying two levels of \fIconst\fP- \fIqualification\fP +for the \fIargv\fP[] and \fIenvp\fP[] +parameters for the \fIexec\fP functions may seem to be the natural +choice, given that these functions do not modify either the +array of pointers or the characters to which the function points, +but this would disallow existing correct code. Instead, only the +array of pointers is noted as constant. The table of assignment compatibility +for \fIdst\fP= \fIsrc\fP derived from the +ISO\ C standard summarizes the compatibility: +.TS C +center; l1 l1 l1 l1 l. +\fIdst\fP: \fBchar *[]\fP \fBconst char *[]\fP \fBchar *const[]\fP \fBconst char *const[]\fP +\fB\fIsrc\fP:\fP \ \ \ \ +\fBchar *[]\fP VALID - VALID - +\fBconst char *[]\fP - VALID - VALID +\fBchar * const []\fP - - VALID - +\fBconst char *const[]\fP - - - VALID +.TE +.LP +Since all existing code has a source type matching the first row, +the column that gives the most valid combinations is the third +column. The only other possibility is the fourth column, but using +it would require a cast on the \fIargv\fP or \fIenvp\fP +arguments. It is unfortunate that the fourth column cannot be used, +because the declaration a non-expert would naturally use would +be that in the second row. +.LP +The ISO\ C standard and this volume of IEEE\ Std\ 1003.1-2001 do not +conflict on the use of \fIenviron\fP, but some +historical implementations of \fIenviron\fP may cause a conflict. +As long as \fIenviron\fP is treated in the same way as an entry +point (for example, \fIfork\fP()), it conforms to both standards. +A library can contain \fIfork\fP(), but if there is a user-provided +\fIfork\fP(), that \fIfork\fP() is given precedence and no +problem ensues. The situation is similar for \fIenviron\fP: the definition +in this volume of IEEE\ Std\ 1003.1-2001 is to +be used if there is no user-provided \fIenviron\fP to take precedence. +At least three implementations are known to exist that +solve this problem. +.TP 7 +.B E2BIG +The limit {ARG_MAX} applies not just to the size of the argument list, +but to the sum of that and the size of the environment +list. +.TP 7 +.B EFAULT +Some historical systems return [EFAULT] rather than [ENOEXEC] when +the new process image file is corrupted. They are +non-conforming. +.TP 7 +.B EINVAL +This error condition was added to IEEE\ Std\ 1003.1-2001 to allow +an implementation to detect executable files +generated for different architectures, and indicate this situation +to the application. Historical implementations of shells, +\fIexecvp\fP(), and \fIexeclp\fP() that encounter an [ENOEXEC] error +will execute a shell on the assumption that the file is a +shell script. This will not produce the desired effect when the file +is a valid executable for a different architecture. An +implementation may now choose to avoid this problem by returning [EINVAL] +when a valid executable for a different architecture is +encountered. Some historical implementations return [EINVAL] to indicate +that the \fIpath\fP argument contains a character with +the high order bit set. The standard developers chose to deviate from +historical practice for the following reasons: +.RS +.IP " 1." 4 +The new utilization of [EINVAL] will provide some measure of utility +to the user community. +.LP +.IP " 2." 4 +Historical use of [EINVAL] is not acceptable in an internationalized +operating environment. +.LP +.RE +.TP 7 +.B ENAMETOOLONG +Since the file pathname may be constructed by taking elements in the +\fIPATH\fP variable and putting them together with the +filename, the [ENAMETOOLONG] error condition could also be reached +this way. +.TP 7 +.B ETXTBSY +System V returns this error when the executable file is currently +open for writing by some process. This volume of +IEEE\ Std\ 1003.1-2001 neither requires nor prohibits this behavior. +.sp +.LP +Other systems (such as System V) may return [EINTR] from \fIexec\fP. +This is not addressed by this volume of +IEEE\ Std\ 1003.1-2001, but implementations may have a window between +the call to \fIexec\fP and the time that a signal +could cause one of the \fIexec\fP calls to return with [EINTR]. +.LP +An explicit statement regarding the floating-point environment (as +defined in the \fI\fP header) was added to make it clear that +the floating-point environment is set +to its default when a call to one of the \fIexec\fP functions succeeds. +The requirements for inheritance or setting to the default +for other process and thread start-up functions is covered by more +generic statements in their descriptions and can be summarized +as follows: +.TP 7 +\fIposix_spawn\fP() +Set to default. +.TP 7 +\fIfork\fP() +Inherit. +.TP 7 +\fIpthread_create\fP() +Inherit. +.sp +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIalarm\fP() , \fIatexit\fP() , \fIchmod\fP() , +\fIclose\fP() , \fIexit\fP() , \fIfcntl\fP() , \fIfork\fP() , \fIfstatvfs\fP() +, \fIgetenv\fP() , \fIgetitimer\fP() , \fIgetrlimit\fP() , \fImmap\fP() +, \fInice\fP() , \fIposix_spawn\fP() , \fIposix_trace_eventid_open\fP() +, \fIposix_trace_shutdown\fP() , \fIposix_trace_trid_eventid_open\fP() +, \fIputenv\fP() , \fIsemop\fP() , \fIsetlocale\fP() , \fIshmat\fP() +, +\fIsigaction\fP() , \fIsigaltstack\fP() , \fIsigpending\fP() , \fIsigprocmask\fP() +, \fIsystem\fP() , \fItimes\fP() , \fIulimit\fP() , \fIumask\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 11, +General Terminal Interface, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/execl.3p b/man3p/execl.3p new file mode 100644 index 000000000..fe3e7ef50 --- /dev/null +++ b/man3p/execl.3p @@ -0,0 +1 @@ +.so man3p/exec.3p diff --git a/man3p/execle.3p b/man3p/execle.3p new file mode 100644 index 000000000..fe3e7ef50 --- /dev/null +++ b/man3p/execle.3p @@ -0,0 +1 @@ +.so man3p/exec.3p diff --git a/man3p/execlp.3p b/man3p/execlp.3p new file mode 100644 index 000000000..fe3e7ef50 --- /dev/null +++ b/man3p/execlp.3p @@ -0,0 +1 @@ +.so man3p/exec.3p diff --git a/man3p/execv.3p b/man3p/execv.3p new file mode 100644 index 000000000..fe3e7ef50 --- /dev/null +++ b/man3p/execv.3p @@ -0,0 +1 @@ +.so man3p/exec.3p diff --git a/man3p/execve.3p b/man3p/execve.3p new file mode 100644 index 000000000..fe3e7ef50 --- /dev/null +++ b/man3p/execve.3p @@ -0,0 +1 @@ +.so man3p/exec.3p diff --git a/man3p/execvp.3p b/man3p/execvp.3p new file mode 100644 index 000000000..fe3e7ef50 --- /dev/null +++ b/man3p/execvp.3p @@ -0,0 +1 @@ +.so man3p/exec.3p diff --git a/man3p/exit.3p b/man3p/exit.3p new file mode 100644 index 000000000..e8de2d325 --- /dev/null +++ b/man3p/exit.3p @@ -0,0 +1,380 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "EXIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" exit +.SH NAME +exit, _Exit, _exit \- terminate a process +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void exit(int\fP \fIstatus\fP\fB); +.br +void _Exit(int\fP \fIstatus\fP\fB); +.br +.sp +.sp +#include +.br +void _exit(int\fP \fIstatus\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +For \fIexit\fP() and \fI_Exit\fP(): The functionality described +on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here +and the ISO\ C standard is unintentional. This volume +of IEEE\ Std\ 1003.1-2001 defers to the ISO\ C standard. +.LP +The value of \fIstatus\fP may be 0, EXIT_SUCCESS, EXIT_FAILURE, +\ or any other value, though only the least significant 8 bits +(that is, \fIstatus\fP & 0377) shall be available to a waiting parent +process. +.LP +The \fIexit\fP() function shall first call all functions registered +by \fIatexit\fP(), +in the reverse order of their registration, except that a function +is called after any previously registered functions that had +already been called at the time it was registered. Each function is +called as many times as it was registered. If, during the call +to any such function, a call to the \fIlongjmp\fP() function is made +that would terminate +the call to the registered function, the behavior is undefined. +.LP +If a function registered by a call to \fIatexit\fP() fails to return, +the remaining +registered functions shall not be called and the rest of the \fIexit\fP() +processing shall not be completed. If \fIexit\fP() is +called more than once, the behavior is undefined. +.LP +The \fIexit\fP() function shall then flush all open streams with unwritten +buffered data, close all open streams, and remove +all files created by \fItmpfile\fP(). Finally, control shall be terminated +with the +consequences described below. +.LP +The +\fI_Exit\fP() and \fI_exit\fP() functions shall be functionally equivalent. +.LP +The \fI_Exit\fP() \ and \fI_exit\fP() functions +shall not call functions registered with \fIatexit\fP() nor any registered +signal handlers. +Whether open streams are flushed or closed, or temporary files are +removed is implementation-defined. Finally, the calling process +is terminated with the consequences described below. +.LP +These functions shall terminate the calling process \ with the following +consequences: +.TP 7 +\fBNote:\fP +These consequences are all extensions to the ISO\ C standard and are +not further CX shaded. However, XSI extensions are +shaded. +.sp +.IP " *" 3 +All of the file descriptors, directory streams, \ conversion descriptors, +and message catalog descriptors \ open in the calling process shall +be closed. +.LP +.IP " *" 3 +If the parent process of the calling process is executing a \fIwait\fP() +or \fIwaitpid\fP(), \ and has neither set its SA_NOCLDWAIT flag +nor set SIGCHLD to +SIG_IGN, it shall be notified of the calling process' termination +and the low-order eight bits (that is, bits 0377) of \fIstatus\fP +shall be made available to it. If the parent is not waiting, the +child's status shall be made available to it when the parent subsequently +executes \fIwait\fP() or \fIwaitpid\fP(). +.LP +The semantics of the \fIwaitid\fP() function shall be equivalent to +\fIwait\fP(). +.LP +.IP " *" 3 +If the parent process of the calling process is not executing a \fIwait\fP() +or \fIwaitpid\fP(), \ and has neither set its SA_NOCLDWAIT flag +nor set SIGCHLD to +SIG_IGN, the calling process shall be transformed into a \fIzombie +process\fP. A \fIzombie process\fP is an inactive process and it shall +be deleted at some later time when its parent process +executes \fIwait\fP() or \fIwaitpid\fP(). +.LP +The semantics of the \fIwaitid\fP() function shall be equivalent to +\fIwait\fP(). +.LP +.IP " *" 3 +Termination of a process does not directly terminate its children. +The sending of a SIGHUP signal as described below indirectly +terminates children in some circumstances. +.LP +.IP " *" 3 +Either: +.LP +If the implementation supports the SIGCHLD signal, a SIGCHLD shall +be sent to the parent process. +.LP +Or: +.LP +If the parent process has set its SA_NOCLDWAIT flag, or set SIGCHLD +to SIG_IGN, the status shall be discarded, and the lifetime of +the calling process shall end immediately. If SA_NOCLDWAIT is set, +it is implementation-defined whether a SIGCHLD signal is sent to +the parent process. +.LP +.IP " *" 3 +The parent process ID of all of the calling process' existing child +processes and zombie processes shall be set to the process +ID of an implementation-defined system process. That is, these processes +shall be inherited by a special system process. +.LP +.IP " *" 3 +Each attached shared-memory segment is detached and the value of \fIshm_nattch\fP +(see \fIshmget\fP()) in the data structure associated with its shared +memory ID shall be decremented by +1. +.LP +.IP " *" 3 +For each semaphore for which the calling process has set a \fIsemadj\fP +value (see \fIsemop\fP() ), that +value shall be added to the \fIsemval\fP of the specified semaphore. +.LP +.IP " *" 3 +If the process is a controlling process, the SIGHUP signal shall be +sent to each process in the foreground process group of the +controlling terminal belonging to the calling process. +.LP +.IP " *" 3 +If the process is a controlling process, the controlling terminal +associated with the session shall be disassociated from the +session, allowing it to be acquired by a new controlling process. +.LP +.IP " *" 3 +If the exit of the process causes a process group to become orphaned, +and if any member of the newly-orphaned process group is +stopped, then a SIGHUP signal followed by a SIGCONT signal shall be +sent to each process in the newly-orphaned process group. +.LP +.IP " *" 3 +All open named semaphores in the calling process shall be closed as +if by appropriate calls to \fIsem_close\fP(). +.LP +.IP " *" 3 +Any +memory locks established by the process via calls to \fImlockall\fP() +or \fImlock\fP() shall be removed. If locked pages in the address +space of the calling process are also +mapped into the address spaces of other processes and are locked by +those processes, the locks established by the other processes +shall be unaffected by the call by this process to \fI_Exit\fP() or +\fI_exit\fP(). +.LP +.IP " *" 3 +Memory mappings that were created in the process shall be unmapped +before the process is destroyed. +.LP +.IP " *" 3 +Any blocks of typed memory that were mapped in the calling process +shall be unmapped, as if \fImunmap\fP() was implicitly called to unmap +them. +.LP +.IP " *" 3 +All open message queue descriptors in the calling process shall be +closed as if by appropriate calls to \fImq_close\fP(). +.LP +.IP " *" 3 +Any outstanding cancelable asynchronous I/O operations may be canceled. +Those asynchronous I/O operations that are not canceled +shall complete as if the \fI_Exit\fP() or \fI_exit\fP() operation +had not yet occurred, but any associated signal notifications +shall be suppressed. The \fI_Exit\fP() or \fI_exit\fP() operation +may block awaiting such I/O completion. Whether any I/O is +canceled, and which I/O may be canceled upon \fI_Exit\fP() or \fI_exit\fP(), +is implementation-defined. +.LP +.IP " *" 3 +Threads terminated by a call to \fI_Exit\fP() or \fI_exit\fP() shall +not invoke their cancellation cleanup handlers or +per-thread data destructors. +.LP +.IP " *" 3 +If the calling process is a trace controller process, any trace streams +that were created by the calling process shall be shut down +as described by the \fIposix_trace_shutdown\fP() function, and any +process' +mapping of trace event names to trace event type identifiers built +for these trace streams may be deallocated. +.LP +.SH RETURN VALUE +.LP +These functions do not return. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Normally applications should use \fIexit\fP() rather than \fI_Exit\fP() +or \fI_exit\fP(). +.SH RATIONALE +.SS Process Termination +.LP +Early proposals drew a distinction between normal and abnormal process +termination. Abnormal termination was caused only by +certain signals and resulted in implementation-defined "actions", +as discussed below. Subsequent proposals distinguished three +types of termination: \fInormal termination\fP (as in the current +specification), \fIsimple abnormal termination\fP, and +\fIabnormal termination with actions\fP. Again the distinction between +the two types of abnormal termination was that they were +caused by different signals and that implementation-defined actions +would result in the latter case. Given that these actions were +completely implementation-defined, the early proposals were only saying +when the actions could occur and how their occurrence could +be detected, but not what they were. This was of little or no use +to conforming applications, and thus the distinction is not made +in this volume of IEEE\ Std\ 1003.1-2001. +.LP +The implementation-defined actions usually include, in most historical +implementations, the creation of a file named \fBcore\fP +in the current working directory of the process. This file contains +an image of the memory of the process, together with +descriptive information about the process, perhaps sufficient to reconstruct +the state of the process at the receipt of the +signal. +.LP +There is a potential security problem in creating a \fBcore\fP file +if the process was set-user-ID and the current user is not +the owner of the program, if the process was set-group-ID and none +of the user's groups match the group of the program, or if the +user does not have permission to write in the current directory. In +this situation, an implementation either should not create a +\fBcore\fP file or should make it unreadable by the user. +.LP +Despite the silence of this volume of IEEE\ Std\ 1003.1-2001 on this +feature, applications are advised not to create +files named \fBcore\fP because of potential conflicts in many implementations. +Some implementations use a name other than +\fBcore\fP for the file; for example, by appending the process ID +to the filename. +.SS Terminating a Process +.LP +It is important that the consequences of process termination as described +occur regardless of whether the process called +\fI_exit\fP() (perhaps indirectly through \fIexit\fP()) or instead +was terminated due to a signal or for some other reason. Note +that in the specific case of \fIexit\fP() this means that the \fIstatus\fP +argument to \fIexit\fP() is treated in the same way +as the \fIstatus\fP argument to \fI_exit\fP(). +.LP +A language other than C may have other termination primitives than +the C-language \fIexit\fP() function, and programs written +in such a language should use its native termination primitives, but +those should have as part of their function the behavior of +\fI_exit\fP() as described. Implementations in languages other than +C are outside the scope of this version of this volume of +IEEE\ Std\ 1003.1-2001, however. +.LP +As required by the ISO\ C standard, using \fBreturn\fP from \fImain\fP() +has the same behavior (other than with respect to +language scope issues) as calling \fIexit\fP() with the returned value. +Reaching the end of the \fImain\fP() function has the +same behavior as calling \fIexit\fP(0). +.LP +A value of zero (or EXIT_SUCCESS, which is required to be zero) for +the argument \fIstatus\fP conventionally indicates +successful termination. This corresponds to the specification for +\fIexit\fP() in the ISO\ C standard. The convention is +followed by utilities such as \fImake\fP and various shells, which +interpret a zero status +from a child process as success. For this reason, applications should +not call \fIexit\fP(0) or \fI_exit\fP(0) when they +terminate unsuccessfully; for example, in signal-catching functions. +.LP +Historically, the implementation-defined process that inherits children +whose parents have terminated without waiting on them is +called \fIinit\fP and has a process ID of 1. +.LP +The sending of a SIGHUP to the foreground process group when a controlling +process terminates corresponds to somewhat different +historical implementations. In System V, the kernel sends a SIGHUP +on termination of (essentially) a controlling process. In 4.2 +BSD, the kernel does not send SIGHUP in a case like this, but the +termination of a controlling process is usually noticed by a +system daemon, which arranges to send a SIGHUP to the foreground process +group with the \fIvhangup\fP() function. However, in 4.2 +BSD, due to the behavior of the shells that support job control, the +controlling process is usually a shell with no other processes +in its process group. Thus, a change to make \fI_exit\fP() behave +this way in such systems should not cause problems with existing +applications. +.LP +The termination of a process may cause a process group to become orphaned +in either of two ways. The connection of a process +group to its parent(s) outside of the group depends on both the parents +and their children. Thus, a process group may be orphaned +by the termination of the last connecting parent process outside of +the group or by the termination of the last direct descendant +of the parent process(es). In either case, if the termination of a +process causes a process group to become orphaned, processes +within the group are disconnected from their job control shell, which +no longer has any information on the existence of the process +group. Stopped processes within the group would languish forever. +In order to avoid this problem, newly orphaned process groups +that contain stopped processes are sent a SIGHUP signal and a SIGCONT +signal to indicate that they have been disconnected from +their session. The SIGHUP signal causes the process group members +to terminate unless they are catching or ignoring SIGHUP. Under +most circumstances, all of the members of the process group are stopped +if any of them are stopped. +.LP +The action of sending a SIGHUP and a SIGCONT signal to members of +a newly orphaned process group is similar to the action of 4.2 +BSD, which sends SIGHUP and SIGCONT to each stopped child of an exiting +process. If such children exit in response to the SIGHUP, +any additional descendants receive similar treatment at that time. +In this volume of IEEE\ Std\ 1003.1-2001, the signals +are sent to the entire process group at the same time. Also, in this +volume of IEEE\ Std\ 1003.1-2001, but not in 4.2 BSD, +stopped processes may be orphaned, but may be members of a process +group that is not orphaned; therefore, the action taken at +\fI_exit\fP() must consider processes other than child processes. +.LP +It is possible for a process group to be orphaned by a call to \fIsetpgid\fP() +or \fIsetsid\fP(), as well as by process termination. This volume +of +IEEE\ Std\ 1003.1-2001 does not require sending SIGHUP and SIGCONT +in those cases, because, unlike process termination, +those cases are not caused accidentally by applications that are unaware +of job control. An implementation can choose to send +SIGHUP and SIGCONT in those cases as an extension; such an extension +must be documented as required in \fI\fP. +.LP +The ISO/IEC\ 9899:1999 standard adds the \fI_Exit\fP() function that +results in immediate program termination without +triggering signals or \fIatexit\fP()-registered functions. In +IEEE\ Std\ 1003.1-2001, this is equivalent to the \fI_exit\fP() function. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIatexit\fP() , \fIclose\fP() , \fIfclose\fP() +, \fIlongjmp\fP() , \fIposix_trace_shutdown\fP() , \fIposix_trace_trid_eventid_open\fP() +, \fIsemop\fP() , \fIshmget\fP() , \fIsigaction\fP() , \fIwait\fP() +, +\fIwaitid\fP() , \fIwaitpid\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/exp.3p b/man3p/exp.3p new file mode 100644 index 000000000..2e86b302f --- /dev/null +++ b/man3p/exp.3p @@ -0,0 +1,116 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "EXP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" exp +.SH NAME +exp, expf, expl \- exponential function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double exp(double\fP \fIx\fP\fB); +.br +float expf(float\fP \fIx\fP\fB); +.br +long double expl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the base- \fIe\fP exponential of \fIx\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the exponential +value of \fIx\fP. +.LP +If the correct value would cause overflow, a range error shall occur +and \fIexp\fP(), \fIexpf\fP(), and \fIexpl\fP() shall +return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.LP +If the correct value would cause underflow, and is not representable, +a range error may occur, and \ either 0.0 (if +supported), or \ an implementation-defined value shall be +returned. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, 1 shall be returned. +.LP +If \fIx\fP is -Inf, +0 shall be returned. +.LP +If \fIx\fP is +Inf, \fIx\fP shall be returned. +.LP +If the correct value would cause underflow, and is representable, +a range error may occur and the correct value shall be +returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Range\ Error +The result overflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be +raised. +.sp +.LP +These functions may fail if: +.TP 7 +Range\ Error +The result underflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Note that for IEEE\ Std\ 754-1985 \fBdouble\fP, 709.8 < \fIx\fP implies +\fIexp\fP( \fIx\fP) has overflowed. The +value \fIx\fP <\ -708.4 implies \fIexp\fP( \fIx\fP) has underflowed. +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() , \fIlog\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/exp2.3p b/man3p/exp2.3p new file mode 100644 index 000000000..c71e76103 --- /dev/null +++ b/man3p/exp2.3p @@ -0,0 +1,114 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "EXP2" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" exp2 +.SH NAME +exp2, exp2f, exp2l \- exponential base 2 functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double exp2(double\fP \fIx\fP\fB); +.br +float exp2f(float\fP \fIx\fP\fB); +.br +long double exp2l(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the base-2 exponential of \fIx\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return 2\fI**x\fP. +.LP +If the correct value would cause overflow, a range error shall occur +and \fIexp2\fP(), \fIexp2f\fP(), and \fIexp2l\fP() shall +return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.LP +If the correct value would cause underflow, and is not representable, +a range error may occur, and \ either 0.0 (if +supported), or \ an implementation-defined value shall be +returned. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, 1 shall be returned. +.LP +If \fIx\fP is -Inf, +0 shall be returned. +.LP +If \fIx\fP is +Inf, \fIx\fP shall be returned. +.LP +If the correct value would cause underflow, and is representable, +a range error may occur and the correct value shall be +returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Range\ Error +The result overflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be +raised. +.sp +.LP +These functions may fail if: +.TP 7 +Range\ Error +The result underflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +For IEEE\ Std\ 754-1985 \fBdouble\fP, 1024 <= \fIx\fP implies \fIexp2\fP( +\fIx\fP) has overflowed. The value +\fIx\fP <\ -1022 implies \fIexp\fP( \fIx\fP) has underflowed. +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexp\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() +, \fIlog\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/exp2f.3p b/man3p/exp2f.3p new file mode 100644 index 000000000..8bfc3a9ed --- /dev/null +++ b/man3p/exp2f.3p @@ -0,0 +1 @@ +.so man3p/exp2.3p diff --git a/man3p/exp2l.3p b/man3p/exp2l.3p new file mode 100644 index 000000000..8bfc3a9ed --- /dev/null +++ b/man3p/exp2l.3p @@ -0,0 +1 @@ +.so man3p/exp2.3p diff --git a/man3p/expf.3p b/man3p/expf.3p new file mode 100644 index 000000000..768bad236 --- /dev/null +++ b/man3p/expf.3p @@ -0,0 +1 @@ +.so man3p/exp.3p diff --git a/man3p/expl.3p b/man3p/expl.3p new file mode 100644 index 000000000..768bad236 --- /dev/null +++ b/man3p/expl.3p @@ -0,0 +1 @@ +.so man3p/exp.3p diff --git a/man3p/expm1.3p b/man3p/expm1.3p new file mode 100644 index 000000000..0c6e4453d --- /dev/null +++ b/man3p/expm1.3p @@ -0,0 +1,125 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "EXPM1" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" expm1 +.SH NAME +expm1, expm1f, expm1l \- compute exponential functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double expm1(double\fP \fIx\fP\fB); +.br +float expm1f(float\fP \fIx\fP\fB); +.br +long double expm1l(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute \fIe**x\fP-1.0. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions return \fIe**x\fP-1.0. +.LP +If the correct value would cause overflow, a range error shall occur +and \fIexpm1\fP(), \fIexpm1f\fP(), and \fIexpm1l\fP() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, \(+-0 shall be returned. +.LP +If \fIx\fP is -Inf, -1 shall be returned. +.LP +If \fIx\fP is +Inf, \fIx\fP shall be returned. +.LP +If \fIx\fP is subnormal, a range error may occur and \fIx\fP should +be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Range\ Error +The result overflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be +raised. +.sp +.LP +These functions may fail if: +.TP 7 +Range\ Error +The value of \fIx\fP is subnormal. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The value of \fIexpm1\fP(\fIx\fP) may be more accurate than \fIexp\fP(\fIx\fP)-1.0 +for small values of \fIx\fP. +.LP +The \fIexpm1\fP() and \fIlog1p\fP() functions are useful for financial +calculations of +((1+\fIx\fP)**\fIn\fP-1)/\fIx\fP, namely: +.sp +.RS +.nf + +\fBexpm1(\fP\fIn\fP \fB* log1p(\fP\fIx\fP\fB))/\fP\fIx\fP +.fi +.RE +.LP +when \fIx\fP is very small (for example, when calculating small daily +interest rates). These functions also simplify writing +accurate inverse hyperbolic functions. +.LP +For IEEE\ Std\ 754-1985 \fBdouble\fP, 709.8 < \fIx\fP implies \fIexpm1\fP( +\fIx\fP) has overflowed. +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexp\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIilogb\fP() +, \fIlog1p\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, +Treatment of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/expm1f.3p b/man3p/expm1f.3p new file mode 100644 index 000000000..ad120c7b7 --- /dev/null +++ b/man3p/expm1f.3p @@ -0,0 +1 @@ +.so man3p/expm1.3p diff --git a/man3p/expm1l.3p b/man3p/expm1l.3p new file mode 100644 index 000000000..ad120c7b7 --- /dev/null +++ b/man3p/expm1l.3p @@ -0,0 +1 @@ +.so man3p/expm1.3p diff --git a/man3p/fabs.3p b/man3p/fabs.3p new file mode 100644 index 000000000..2d30274b0 --- /dev/null +++ b/man3p/fabs.3p @@ -0,0 +1,63 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FABS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fabs +.SH NAME +fabs, fabsf, fabsl \- absolute value function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double fabs(double\fP \fIx\fP\fB); +.br +float fabsf(float\fP \fIx\fP\fB); +.br +long double fabsl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the absolute value of their argument +\fIx\fP,| \fIx\fP|. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the absolute +value of \fIx\fP. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, +0 shall be returned. +.LP +If \fIx\fP is \(+-Inf, +Inf shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisnan\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fabsf.3p b/man3p/fabsf.3p new file mode 100644 index 000000000..61d8218e1 --- /dev/null +++ b/man3p/fabsf.3p @@ -0,0 +1 @@ +.so man3p/fabs.3p diff --git a/man3p/fabsl.3p b/man3p/fabsl.3p new file mode 100644 index 000000000..61d8218e1 --- /dev/null +++ b/man3p/fabsl.3p @@ -0,0 +1 @@ +.so man3p/fabs.3p diff --git a/man3p/fattach.3p b/man3p/fattach.3p new file mode 100644 index 000000000..54e9ceee9 --- /dev/null +++ b/man3p/fattach.3p @@ -0,0 +1,166 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FATTACH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fattach +.SH NAME +fattach \- attach a STREAMS-based file descriptor to a file in the +file system name space (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fattach(int\fP \fIfildes\fP\fB, const char *\fP\fIpath\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIfattach\fP() function shall attach a STREAMS-based file descriptor +to a file, effectively associating a pathname with +\fIfildes\fP. The application shall ensure that the \fIfildes\fP argument +is a valid open file descriptor associated with a +STREAMS file. The \fIpath\fP argument points to a pathname of an existing +file. The application shall have the appropriate +privileges or be the owner of the file named by \fIpath\fP and have +write permission. A successful call to \fIfattach\fP() shall +cause all pathnames that name the file named by \fIpath\fP to name +the STREAMS file associated with \fIfildes\fP, until the +STREAMS file is detached from the file. A STREAMS file can be attached +to more than one file and can have several pathnames +associated with it. +.LP +The attributes of the named STREAMS file shall be initialized as follows: +the permissions, user ID, group ID, and times are set +to those of the file named by \fIpath\fP, the number of links is set +to 1, and the size and device identifier are set to those of +the STREAMS file associated with \fIfildes\fP. If any attributes of +the named STREAMS file are subsequently changed (for example, +by \fIchmod\fP()), neither the attributes of the underlying file nor +the attributes of the +STREAMS file to which \fIfildes\fP refers shall be affected. +.LP +File descriptors referring to the underlying file, opened prior to +an \fIfattach\fP() call, shall continue to refer to the +underlying file. +.SH RETURN VALUE +.LP +Upon successful completion, \fIfattach\fP() shall return 0. Otherwise, +-1 shall be returned and \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +The \fIfattach\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied for a component of the path prefix, or +the process is the owner of \fIpath\fP but does not have +write permissions on the file named by \fIpath\fP. +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid open file descriptor. +.TP 7 +.B EBUSY +The file named by \fIpath\fP is currently a mount point or has a STREAMS +file attached to it. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The size of \fIpath\fP exceeds {PATH_MAX} or a component of \fIpath\fP +is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.TP 7 +.B EPERM +The effective user ID of the process is not the owner of the file +named by \fIpath\fP and the process does not have +appropriate privilege. +.sp +.LP +The \fIfattach\fP() function may fail if: +.TP 7 +.B EINVAL +The \fIfildes\fP argument does not refer to a STREAMS file. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.TP 7 +.B EXDEV +A link to a file on another file system was attempted. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Attaching a File Descriptor to a File +.LP +In the following example, \fIfd\fP refers to an open STREAMS file. +The call to \fIfattach\fP() associates this STREAM with the +file \fB/tmp/named-STREAM\fP, such that any future calls to open \fB/tmp/named-STREAM\fP, +prior to breaking the attachment via a +call to \fIfdetach\fP(), will instead create a new file handle referring +to the STREAMS +file associated with \fIfd\fP. +.sp +.RS +.nf + +\fB#include +\&... + int fd; + char *filename = "/tmp/named-STREAM"; + int ret; +.sp + + ret = fattach(fd, filename); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIfattach\fP() function behaves similarly to the traditional +\fImount\fP() function in the way a file is temporarily +replaced by the root directory of the mounted file system. In the +case of \fIfattach\fP(), the replaced file need not be a +directory and the replacing file is a STREAMS file. +.SH RATIONALE +.LP +The file attributes of a file which has been the subject of an \fIfattach\fP() +call are specifically set because of an artefact +of the original implementation. The internal mechanism was the same +as for the \fImount\fP() function. Since \fImount\fP() is +typically only applied to directories, the effects when applied to +a regular file are a little surprising, especially as regards +the link count which rigidly remains one, even if there were several +links originally and despite the fact that all original links +refer to the STREAM as long as the \fIfattach\fP() remains in effect. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfdetach\fP() , \fIisastream\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fchdir.3p b/man3p/fchdir.3p new file mode 100644 index 000000000..b02d484a6 --- /dev/null +++ b/man3p/fchdir.3p @@ -0,0 +1,80 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FCHDIR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fchdir +.SH NAME +fchdir \- change working directory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fchdir(int\fP \fIfildes\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIfchdir\fP() function shall be equivalent to \fIchdir\fP() except +that the +directory that is to be the new current working directory is specified +by the file descriptor \fIfildes\fP. +.LP +A conforming application can obtain a file descriptor for a file of +type directory using \fIopen\fP(), provided that the file status flags +and access modes do not contain O_WRONLY or +O_RDWR. +.SH RETURN VALUE +.LP +Upon successful completion, \fIfchdir\fP() shall return 0. Otherwise, +it shall return -1 and set \fIerrno\fP to indicate the +error. On failure the current working directory shall remain unchanged. +.SH ERRORS +.LP +The \fIfchdir\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied for the directory referenced by \fIfildes\fP. +.TP 7 +.B EBADF +The \fIfildes\fP argument is not an open file descriptor. +.TP 7 +.B ENOTDIR +The open file descriptor \fIfildes\fP does not refer to a directory. +.sp +.LP +The \fIfchdir\fP() may fail if: +.TP 7 +.B EINTR +A signal was caught during the execution of \fIfchdir\fP(). +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to the file system. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchdir\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fchmod.3p b/man3p/fchmod.3p new file mode 100644 index 000000000..632d7e519 --- /dev/null +++ b/man3p/fchmod.3p @@ -0,0 +1,114 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FCHMOD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fchmod +.SH NAME +fchmod \- change mode of a file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fchmod(int\fP \fIfildes\fP\fB, mode_t\fP \fImode\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfchmod\fP() function shall be equivalent to \fIchmod\fP() except +that the file +whose permissions are changed is specified by the file descriptor +\fIfildes\fP. +.LP +If \fIfildes\fP references a shared memory object, the \fIfchmod\fP() +function need only affect the S_IRUSR, S_IWUSR, S_IRGRP, +S_IWGRP, S_IROTH, and S_IWOTH file permission bits. +.LP +If \fIfildes\fP references a typed memory object, the behavior of +\fIfchmod\fP() is unspecified. +.LP +If \fIfildes\fP refers to a socket, the behavior of \fIfchmod\fP() +is unspecified. +.LP +If \fIfildes\fP refers to a STREAM (which is \fIfattach\fP()-ed into +the file system name +space) the call returns successfully, doing nothing. +.SH RETURN VALUE +.LP +Upon successful completion, \fIfchmod\fP() shall return 0. Otherwise, +it shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fIfchmod\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not an open file descriptor. +.TP 7 +.B EPERM +The effective user ID does not match the owner of the file and the +process does not have appropriate privilege. +.TP 7 +.B EROFS +The file referred to by \fIfildes\fP resides on a read-only file system. +.sp +.LP +The \fIfchmod\fP() function may fail if: +.TP 7 +.B EINTR +The \fIfchmod\fP() function was interrupted by a signal. +.TP 7 +.B EINVAL +The value of the \fImode\fP argument is invalid. +.TP 7 +.B EINVAL +The \fIfildes\fP argument refers to a pipe and the implementation +disallows execution of \fIfchmod\fP() on a pipe. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Changing the Current Permissions for a File +.LP +The following example shows how to change the permissions for a file +named \fB/home/cnd/mod1\fP so that the owner and group +have read/write/execute permissions, but the world only has read/write +permissions. +.sp +.RS +.nf + +\fB#include +#include +.sp + +mode_t mode; +int fildes; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +fchmod(fildes, S_IRWXU | S_IRWXG | S_IROTH | S_IWOTH); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchmod\fP() , \fIchown\fP() , \fIcreat\fP() , \fIfcntl\fP() , \fIfstatvfs\fP() +, \fImknod\fP() , \fIopen\fP() , \fIread\fP() , \fIstat\fP() , \fIwrite\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fchown.3p b/man3p/fchown.3p new file mode 100644 index 000000000..d3375e455 --- /dev/null +++ b/man3p/fchown.3p @@ -0,0 +1,115 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FCHOWN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fchown +.SH NAME +fchown \- change owner and group of a file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fchown(int\fP \fIfildes\fP\fB, uid_t\fP \fIowner\fP\fB, gid_t\fP +\fIgroup\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfchown\fP() function shall be equivalent to \fIchown\fP() except +that the file +whose owner and group are changed is specified by the file descriptor +\fIfildes\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIfchown\fP() shall return 0. Otherwise, +it shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fIfchown\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not an open file descriptor. +.TP 7 +.B EPERM +The effective user ID does not match the owner of the file or the +process does not have appropriate privilege and +_POSIX_CHOWN_RESTRICTED indicates that such privilege is required. +.TP 7 +.B EROFS +The file referred to by \fIfildes\fP resides on a read-only file system. +.sp +.LP +The \fIfchown\fP() function may fail if: +.TP 7 +.B EINVAL +The owner or group ID is not a value supported by the implementation. +The \fIfildes\fP argument refers to a pipe or socket +\ or an \fIfattach\fP()-ed STREAM \ and the implementation disallows +execution of \fIfchown\fP() on a pipe. +.TP 7 +.B EIO +A physical I/O error has occurred. +.TP 7 +.B EINTR +The \fIfchown\fP() function was interrupted by a signal which was +caught. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Changing the Current Owner of a File +.LP +The following example shows how to change the owner of a file named +\fB/home/cnd/mod1\fP to "jones" and the group to +"cnd". +.LP +The numeric value for the user ID is obtained by extracting the user +ID from the user database entry associated with "jones". +Similarly, the numeric value for the group ID is obtained by extracting +the group ID from the group database entry associated with +"cnd". This example assumes the calling program has appropriate privileges. +.sp +.RS +.nf + +\fB#include +#include +#include +#include +#include +.sp + +struct passwd *pwd; +struct group *grp; +int fildes; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +pwd = getpwnam("jones"); +grp = getgrnam("cnd"); +fchown(fildes, pwd->pw_uid, grp->gr_gid); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchown\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fclose.3p b/man3p/fclose.3p new file mode 100644 index 000000000..0bcfb8ed4 --- /dev/null +++ b/man3p/fclose.3p @@ -0,0 +1,122 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FCLOSE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fclose +.SH NAME +fclose \- close a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fclose(FILE *\fP\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfclose\fP() function shall cause the stream pointed to by \fIstream\fP +to be flushed and the associated file to be +closed. Any unwritten buffered data for the stream shall be written +to the file; any unread buffered data shall be discarded. +Whether or not the call succeeds, the stream shall be disassociated +from the file and any buffer set by the \fIsetbuf\fP() or \fIsetvbuf\fP() +function shall be +disassociated from the stream. If the associated buffer was automatically +allocated, it shall be deallocated. +.LP +The +\fIfclose\fP() function shall mark for update the \fIst_ctime\fP and +\fIst_mtime\fP fields of the underlying file, if the stream +was writable, and if buffered data remains that has not yet been written +to the file. The \fIfclose\fP() function shall perform +the equivalent of a \fIclose\fP() on the file descriptor that is associated +with the stream +pointed to by \fIstream\fP. +.LP +After the call to \fIfclose\fP(), any use of \fIstream\fP results +in undefined behavior. +.SH RETURN VALUE +.LP +Upon successful completion, \fIfclose\fP() shall return 0; otherwise, +it shall return EOF \ and set +\fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIfclose\fP() function shall fail if: +.TP 7 +.B EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying \fIstream\fP +and the process would be delayed in the write +operation. +.TP 7 +.B EBADF +The file descriptor underlying stream is not valid. +.TP 7 +.B EFBIG +An +attempt was made to write a file that exceeds the maximum file size. +.TP 7 +.B EFBIG +An attempt was made to write a file that exceeds the process' file +size limit. +.TP 7 +.B EFBIG +The file is a regular file and an attempt was made to write at or +beyond the offset maximum associated with the corresponding +stream. +.TP 7 +.B EINTR +The \fIfclose\fP() function was interrupted by a signal. +.TP 7 +.B EIO +The process is a member of a background process group attempting to +write to its controlling terminal, TOSTOP is set, the process +is neither ignoring nor blocking SIGTTOU, and the process group of +the process is orphaned. This error may also be returned under +implementation-defined conditions. +.TP 7 +.B ENOSPC +There was no free space remaining on the device containing the file. +.TP 7 +.B EPIPE +An +attempt is made to write to a pipe or FIFO that is not open for reading +by any process. A SIGPIPE signal shall also be sent to the +thread. +.sp +.LP +The \fIfclose\fP() function may fail if: +.TP 7 +.B ENXIO +A +request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclose\fP() , \fIfopen\fP() , \fIgetrlimit\fP() , \fIulimit\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fcntl.3p b/man3p/fcntl.3p new file mode 100644 index 000000000..459000132 --- /dev/null +++ b/man3p/fcntl.3p @@ -0,0 +1,476 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FCNTL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fcntl +.SH NAME +fcntl \- file control +.SH SYNOPSIS +.LP +\fB#include \fP +\fB +.br +#include +.br +.sp +int fcntl(int\fP \fIfildes\fP\fB, int\fP \fIcmd\fP\fB, ...); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfcntl\fP() function shall perform the operations described +below on open files. The \fIfildes\fP argument is a file +descriptor. +.LP +The available values for \fIcmd\fP are defined in \fI\fP +and are as +follows: +.TP 7 +F_DUPFD +Return a new file descriptor which shall be the lowest numbered available +(that is, not already open) file descriptor greater +than or equal to the third argument, \fIarg\fP, taken as an integer +of type \fBint\fP. The new file descriptor shall refer to the +same open file description as the original file descriptor, and shall +share any locks. The FD_CLOEXEC flag associated with the new +file descriptor shall be cleared to keep the file open across calls +to one of the \fIexec\fP +functions. +.TP 7 +F_GETFD +Get the file descriptor flags defined in \fI\fP that are +associated with +the file descriptor \fIfildes\fP. File descriptor flags are associated +with a single file descriptor and do not affect other file +descriptors that refer to the same file. +.TP 7 +F_SETFD +Set the file descriptor flags defined in \fI\fP, that are +associated +with \fIfildes\fP, to the third argument, \fIarg\fP, taken as type +\fBint\fP. If the FD_CLOEXEC flag in the third argument is 0, +the file shall remain open across the \fIexec\fP functions; otherwise, +the file shall be +closed upon successful execution of one of the \fIexec\fP functions. +.TP 7 +F_GETFL +Get the file status flags and file access modes, defined in \fI\fP, +for +the file description associated with \fIfildes\fP. The file access +modes can be extracted from the return value using the mask +O_ACCMODE, which is defined in \fI\fP. File status flags +and file access +modes are associated with the file description and do not affect other +file descriptors that refer to the same file with different +open file descriptions. +.TP 7 +F_SETFL +Set the file status flags, defined in \fI\fP, for the file +description +associated with \fIfildes\fP from the corresponding bits in the third +argument, \fIarg\fP, taken as type \fBint\fP. Bits +corresponding to the file access mode and the file creation flags, +as defined in \fI\fP, that are set in \fIarg\fP shall be +ignored. If any bits in \fIarg\fP other +than those mentioned here are changed by the application, the result +is unspecified. +.TP 7 +F_GETOWN +If \fIfildes\fP refers to a socket, get the process or process group +ID specified to receive SIGURG signals when out-of-band +data is available. Positive values indicate a process ID; negative +values, other than -1, indicate a process group ID. If +\fIfildes\fP does not refer to a socket, the results are unspecified. +.TP 7 +F_SETOWN +If \fIfildes\fP refers to a socket, set the process or process group +ID specified to receive SIGURG signals when out-of-band +data is available, using the value of the third argument, \fIarg\fP, +taken as type \fBint\fP. Positive values indicate a process +ID; negative values, other than -1, indicate a process group ID. If +\fIfildes\fP does not refer to a socket, the results are +unspecified. +.sp +.LP +The following values for \fIcmd\fP are available for advisory record +locking. Record locking shall be supported for regular +files, and may be supported for other files. +.TP 7 +F_GETLK +Get the first lock which blocks the lock description pointed to by +the third argument, \fIarg\fP, taken as a pointer to type +\fBstruct flock\fP, defined in \fI\fP. The information retrieved +shall +overwrite the information passed to \fIfcntl\fP() in the structure +\fBflock\fP. If no lock is found that would prevent this lock +from being created, then the structure shall be left unchanged except +for the lock type which shall be set to F_UNLCK. +.TP 7 +F_SETLK +Set or clear a file segment lock according to the lock description +pointed to by the third argument, \fIarg\fP, taken as a +pointer to type \fBstruct flock\fP, defined in \fI\fP. F_SETLK +can +establish shared (or read) locks (F_RDLCK) or exclusive (or write) +locks (F_WRLCK), as well as to remove either type of lock +(F_UNLCK). F_RDLCK, F_WRLCK, and F_UNLCK are defined in \fI\fP. +If a shared +or exclusive lock cannot be set, \fIfcntl\fP() shall return immediately +with a return value of -1. +.TP 7 +F_SETLKW +This command shall be equivalent to F_SETLK except that if a shared +or exclusive lock is blocked by other locks, the thread +shall wait until the request can be satisfied. If a signal that is +to be caught is received while \fIfcntl\fP() is waiting for a +region, \fIfcntl\fP() shall be interrupted. Upon return from the signal +handler, \fIfcntl\fP() shall return -1 with \fIerrno\fP +set to [EINTR], and the lock operation shall not be done. +.sp +.LP +Additional implementation-defined values for \fIcmd\fP may be defined +in \fI\fP. Their names shall start with F_. +.LP +When a shared lock is set on a segment of a file, other processes +shall be able to set shared locks on that segment or a portion +of it. A shared lock prevents any other process from setting an exclusive +lock on any portion of the protected area. A request for +a shared lock shall fail if the file descriptor was not opened with +read access. +.LP +An exclusive lock shall prevent any other process from setting a shared +lock or an exclusive lock on any portion of the +protected area. A request for an exclusive lock shall fail if the +file descriptor was not opened with write access. +.LP +The structure \fBflock\fP describes the type ( \fIl_type\fP), starting +offset ( \fIl_whence\fP), relative offset ( +\fIl_start\fP), size ( \fIl_len\fP), and process ID ( \fIl_pid\fP) +of the segment of the file to be affected. +.LP +The value of \fIl_whence\fP is SEEK_SET, SEEK_CUR, or SEEK_END, to +indicate that the relative offset \fIl_start\fP bytes shall +be measured from the start of the file, current position, or end of +the file, respectively. The value of \fIl_len\fP is the number +of consecutive bytes to be locked. The value of \fIl_len\fP may be +negative (where the definition of \fBoff_t\fP permits negative +values of \fIl_len\fP). The \fIl_pid\fP field is only used with F_GETLK +to return the process ID of the process holding a +blocking lock. After a successful F_GETLK request, when a blocking +lock is found, the values returned in the \fBflock\fP structure +shall be as follows: +.TP 7 +\fIl_type\fP +Type of blocking lock found. +.TP 7 +\fIl_whence\fP +SEEK_SET. +.TP 7 +\fIl_start\fP +Start of the blocking lock. +.TP 7 +\fIl_len\fP +Length of the blocking lock. +.TP 7 +\fIl_pid\fP +Process ID of the process that holds the blocking lock. +.sp +.LP +If the command is F_SETLKW and the process must wait for another process +to release a lock, then the range of bytes to be locked +shall be determined before the \fIfcntl\fP() function blocks. If the +file size or file descriptor seek offset change while +\fIfcntl\fP() is blocked, this shall not affect the range of bytes +locked. +.LP +If \fIl_len\fP is positive, the area affected shall start at \fIl_start\fP +and end at \fIl_start\fP+ \fIl_len\fP-1. If +\fIl_len\fP is negative, the area affected shall start at \fIl_start\fP+ +\fIl_len\fP and end at \fIl_start\fP-1. Locks may +start and extend beyond the current end of a file, but shall not extend +before the beginning of the file. A lock shall be set to +extend to the largest possible value of the file offset for that file +by setting \fIl_len\fP to 0. If such a lock also has +\fIl_start\fP set to 0 and \fIl_whence\fP is set to SEEK_SET, the +whole file shall be locked. +.LP +There shall be at most one type of lock set for each byte in the file. +Before a successful return from an F_SETLK or an F_SETLKW +request when the calling process has previously existing locks on +bytes in the region specified by the request, the previous lock +type for each byte in the specified region shall be replaced by the +new lock type. As specified above under the descriptions of +shared locks and exclusive locks, an F_SETLK or an F_SETLKW request +(respectively) shall fail or block when another process has +existing locks on bytes in the specified region and the type of any +of those locks conflicts with the type specified in the +request. +.LP +All locks associated with a file for a given process shall be removed +when a file descriptor for that file is closed by that +process or the process holding that file descriptor terminates. Locks +are not inherited by a child process. +.LP +A potential for deadlock occurs if a process controlling a locked +region is put to sleep by attempting to lock another process' +locked region. If the system detects that sleeping until a locked +region is unlocked would cause a deadlock, \fIfcntl\fP() shall +fail with an [EDEADLK] error. +.LP +An unlock (F_UNLCK) request in which \fIl_len\fP is non-zero and the +offset of the last byte of the requested segment is the +maximum value for an object of type \fBoff_t\fP, when the process +has an existing lock in which \fIl_len\fP is 0 and which +includes the last byte of the requested segment, shall be treated +as a request to unlock from the start of the requested segment +with an \fIl_len\fP equal to 0. Otherwise, an unlock (F_UNLCK) request +shall attempt to unlock only the requested segment. +.LP +When the file descriptor \fIfildes\fP refers to a shared memory object, +the behavior of \fIfcntl\fP() shall be the same as for a +regular file except the effect of the following values for the argument +\fIcmd\fP shall be unspecified: F_SETFL, F_GETLK, F_SETLK, +and F_SETLKW. +.LP +If \fIfildes\fP refers to a typed memory object, the result of the +\fIfcntl\fP() function is unspecified. +.SH RETURN VALUE +.LP +Upon successful completion, the value returned shall depend on \fIcmd\fP +as follows: +.TP 7 +F_DUPFD +A new file descriptor. +.TP 7 +F_GETFD +Value of flags defined in \fI\fP. The return value shall +not be +negative. +.TP 7 +F_SETFD +Value other than -1. +.TP 7 +F_GETFL +Value of file status flags and access modes. The return value is not +negative. +.TP 7 +F_SETFL +Value other than -1. +.TP 7 +F_GETLK +Value other than -1. +.TP 7 +F_SETLK +Value other than -1. +.TP 7 +F_SETLKW +Value other than -1. +.TP 7 +F_GETOWN +Value of the socket owner process or process group; this will not +be -1. +.TP 7 +F_SETOWN +Value other than -1. +.sp +.LP +Otherwise, -1 shall be returned and \fIerrno\fP set to indicate the +error. +.SH ERRORS +.LP +The \fIfcntl\fP() function shall fail if: +.TP 7 +.B EACCES \fRor\fP EAGAIN +.sp +The \fIcmd\fP argument is F_SETLK; the type of lock ( \fIl_type\fP) +is a shared (F_RDLCK) or exclusive (F_WRLCK) lock and the +segment of a file to be locked is already exclusive-locked by another +process, or the type is an exclusive lock and some portion of +the segment of a file to be locked is already shared-locked or exclusive-locked +by another process. +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid open file descriptor, or +the argument \fIcmd\fP is F_SETLK or F_SETLKW, the type of +lock, \fIl_type\fP, is a shared lock (F_RDLCK), and \fIfildes\fP is +not a valid file descriptor open for reading, or the type of +lock, \fIl_type\fP, is an exclusive lock (F_WRLCK), and \fIfildes\fP +is not a valid file descriptor open for writing. +.TP 7 +.B EINTR +The \fIcmd\fP argument is F_SETLKW and the function was interrupted +by a signal. +.TP 7 +.B EINVAL +The \fIcmd\fP argument is invalid, or the \fIcmd\fP argument is F_DUPFD +and \fIarg\fP is negative or greater than or equal +to {OPEN_MAX}, or the \fIcmd\fP argument is F_GETLK, F_SETLK, or F_SETLKW +and the data pointed to by \fIarg\fP is not valid, or +\fIfildes\fP refers to a file that does not support locking. +.TP 7 +.B EMFILE +The argument \fIcmd\fP is F_DUPFD and {OPEN_MAX} file descriptors +are currently open in the calling process, or no file +descriptors greater than or equal to \fIarg\fP are available. +.TP 7 +.B ENOLCK +The argument \fIcmd\fP is F_SETLK or F_SETLKW and satisfying the lock +or unlock request would result in the number of locked +regions in the system exceeding a system-imposed limit. +.TP 7 +.B EOVERFLOW +One of the values to be returned cannot be represented correctly. +.TP 7 +.B EOVERFLOW +The \fIcmd\fP argument is F_GETLK, F_SETLK, or F_SETLKW and the smallest +or, if \fIl_len\fP is non-zero, the largest offset +of any byte in the requested segment cannot be represented correctly +in an object of type \fBoff_t\fP. +.sp +.LP +The \fIfcntl\fP() function may fail if: +.TP 7 +.B EDEADLK +The \fIcmd\fP argument is F_SETLKW, the lock is blocked by a lock +from another process, and putting the calling process to +sleep to wait for that lock to become free would cause a deadlock. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The ellipsis in the SYNOPSIS is the syntax specified by the ISO\ C +standard for a variable number of arguments. It is used +because System V uses pointers for the implementation of file locking +functions. +.LP +The \fIarg\fP values to F_GETFD, F_SETFD, F_GETFL, and F_SETFL all +represent flag values to allow for future growth. +Applications using these functions should do a read-modify-write operation +on them, rather than assuming that only the values +defined by this volume of IEEE\ Std\ 1003.1-2001 are valid. It is +a common error to forget this, particularly in the case +of F_SETFD. +.LP +This volume of IEEE\ Std\ 1003.1-2001 permits concurrent read and +write access to file data using the \fIfcntl\fP() +function; this is a change from the 1984 /usr/group standard and early +proposals. Without concurrency controls, this feature may +not be fully utilized without occasional loss of data. +.LP +Data losses occur in several ways. One case occurs when several processes +try to update the same record, without sequencing +controls; several updates may occur in parallel and the last writer +"wins". Another case is a bit-tree or other internal +list-based database that is undergoing reorganization. Without exclusive +use to the tree segment by the updating process, other +reading processes chance getting lost in the database when the index +blocks are split, condensed, inserted, or deleted. While +\fIfcntl\fP() is useful for many applications, it is not intended +to be overly general and does not handle the bit-tree example +well. +.LP +This facility is only required for regular files because it is not +appropriate for many devices such as terminals and network +connections. +.LP +Since \fIfcntl\fP() works with "any file descriptor associated with +that file, however it is obtained", the file descriptor +may have been inherited through a \fIfork\fP() or \fIexec\fP operation +and thus may affect a file that another process also has open. +.LP +The use of the open file description to identify what to lock requires +extra calls and presents problems if several processes +are sharing an open file description, but there are too many implementations +of the existing mechanism for this volume of +IEEE\ Std\ 1003.1-2001 to use different specifications. +.LP +Another consequence of this model is that closing any file descriptor +for a given file (whether or not it is the same open file +description that created the lock) causes the locks on that file to +be relinquished for that process. Equivalently, any close for +any file/process pair relinquishes the locks owned on that file for +that process. But note that while an open file description may +be shared through \fIfork\fP(), locks are not inherited through \fIfork\fP(). +Yet locks may be inherited through one of the \fIexec\fP functions. +.LP +The identification of a machine in a network environment is outside +the scope of this volume of IEEE\ Std\ 1003.1-2001. +Thus, an \fIl_sysid\fP member, such as found in System V, is not included +in the locking structure. +.LP +Changing of lock types can result in a previously locked region being +split into smaller regions. +.LP +Mandatory locking was a major feature of the 1984 /usr/group standard. +.LP +For advisory file record locking to be effective, all processes that +have access to a file must cooperate and use the advisory +mechanism before doing I/O on the file. Enforcement-mode record locking +is important when it cannot be assumed that all processes +are cooperating. For example, if one user uses an editor to update +a file at the same time that a second user executes another +process that updates the same file and if only one of the two processes +is using advisory locking, the processes are not +cooperating. Enforcement-mode record locking would protect against +accidental collisions. +.LP +Secondly, advisory record locking requires a process using locking +to bracket each I/O operation with lock (or test) and unlock +operations. With enforcement-mode file and record locking, a process +can lock the file once and unlock when all I/O operations have +been completed. Enforcement-mode record locking provides a base that +can be enhanced; for example, with sharable locks. That is, +the mechanism could be enhanced to allow a process to lock a file +so other processes could read it, but none of them could write +it. +.LP +Mandatory locks were omitted for several reasons: +.IP " 1." 4 +Mandatory lock setting was done by multiplexing the set-group-ID bit +in most implementations; this was confusing, at best. +.LP +.IP " 2." 4 +The relationship to file truncation as supported in 4.2 BSD was not +well specified. +.LP +.IP " 3." 4 +Any publicly readable file could be locked by anyone. Many historical +implementations keep the password database in a publicly +readable file. A malicious user could thus prohibit logins. Another +possibility would be to hold open a long-distance telephone +line. +.LP +.IP " 4." 4 +Some demand-paged historical implementations offer memory mapped files, +and enforcement cannot be done on that type of file. +.LP +.LP +Since sleeping on a region is interrupted with any signal, \fIalarm\fP() +may be used to +provide a timeout facility in applications requiring it. This is useful +in deadlock detection. Since implementation of full +deadlock detection is not always feasible, the [EDEADLK] error was +made optional. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIalarm\fP() , \fIclose\fP() , \fIexec\fP() , \fIopen\fP() , \fIsigaction\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fcvt.3p b/man3p/fcvt.3p new file mode 100644 index 000000000..ad49771fb --- /dev/null +++ b/man3p/fcvt.3p @@ -0,0 +1 @@ +.so man3p/ecvt.3p diff --git a/man3p/fdatasync.3p b/man3p/fdatasync.3p new file mode 100644 index 000000000..867f997d7 --- /dev/null +++ b/man3p/fdatasync.3p @@ -0,0 +1,74 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FDATASYNC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fdatasync +.SH NAME +fdatasync \- synchronize the data of a file (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fdatasync(int\fP \fIfildes\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIfdatasync\fP() function shall force all currently queued I/O +operations associated with the file indicated by file +descriptor \fIfildes\fP to the synchronized I/O completion state. +.LP +The functionality shall be equivalent to \fIfsync\fP() with the symbol +_POSIX_SYNCHRONIZED_IO defined, with the exception that all I/O operations +shall be completed as defined for synchronized I/O data +integrity completion. +.SH RETURN VALUE +.LP +If successful, the \fIfdatasync\fP() function shall return the value +0; otherwise, the function shall return the value -1 and +set \fIerrno\fP to indicate the error. If the \fIfdatasync\fP() function +fails, outstanding I/O operations are not guaranteed to +have been completed. +.SH ERRORS +.LP +The \fIfdatasync\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor open for +writing. +.TP 7 +.B EINVAL +This implementation does not support synchronized I/O for this file. +.sp +.LP +In the event that any of the queued I/O operations fail, \fIfdatasync\fP() +shall return the error conditions defined for \fIread\fP() and \fIwrite\fP(). +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIaio_fsync\fP() , \fIfcntl\fP() , \fIfsync\fP() , \fIopen\fP() , +\fIread\fP() , \fIwrite\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fdetach.3p b/man3p/fdetach.3p new file mode 100644 index 000000000..0754758d3 --- /dev/null +++ b/man3p/fdetach.3p @@ -0,0 +1,126 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FDETACH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fdetach +.SH NAME +fdetach \- detach a name from a STREAMS-based file descriptor (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fdetach(const char *\fP\fIpath\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIfdetach\fP() function shall detach a STREAMS-based file from +the file to which it was attached by a previous call to \fIfattach\fP(). +The \fIpath\fP argument points to the pathname of the attached STREAMS +file. The process shall have appropriate privileges or be the owner +of the file. A successful call to \fIfdetach\fP() shall cause +all pathnames that named the attached STREAMS file to again name the +file to which the STREAMS file was attached. All subsequent +operations on \fIpath\fP shall operate on the underlying file and +not on the STREAMS file. +.LP +All open file descriptions established while the STREAMS file was +attached to the file referenced by \fIpath\fP shall still +refer to the STREAMS file after the \fIfdetach\fP() has taken effect. +.LP +If there are no open file descriptors or other references to the STREAMS +file, then a successful call to \fIfdetach\fP() shall +be equivalent to performing the last \fIclose\fP() on the attached +file. +.SH RETURN VALUE +.LP +Upon successful completion, \fIfdetach\fP() shall return 0; otherwise, +it shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fIfdetach\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied on a component of the path prefix. +.TP 7 +.B EINVAL +The \fIpath\fP argument names a file that is not currently attached. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The size of a pathname exceeds {PATH_MAX} or a pathname component +is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.TP 7 +.B EPERM +The effective user ID is not the owner of \fIpath\fP and the process +does not have appropriate privileges. +.sp +.LP +The \fIfdetach\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Detaching a File +.LP +The following example detaches the STREAMS-based file \fB/tmp/named-STREAM\fP +from the file to which it was attached by a +previous, successful call to \fIfattach\fP(). Subsequent calls to +open this file refer to +the underlying file, not to the STREAMS file. +.sp +.RS +.nf + +\fB#include +\&... + char *filename = "/tmp/named-STREAM"; + int ret; +.sp + + ret = fdetach(filename); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfattach\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fdim.3p b/man3p/fdim.3p new file mode 100644 index 000000000..5aef036d2 --- /dev/null +++ b/man3p/fdim.3p @@ -0,0 +1,111 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FDIM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fdim +.SH NAME +fdim, fdimf, fdiml \- compute positive difference between two floating-point +numbers +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double fdim(double\fP \fIx\fP\fB, double\fP \fIy\fP\fB); +.br +float fdimf(float\fP \fIx\fP\fB, float\fP \fIy\fP\fB); +.br +long double fdiml(long double\fP \fIx\fP\fB, long double\fP \fIy\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall determine the positive difference between their +arguments. If \fIx\fP is greater than \fIy\fP, \fIx\fP- +\fIy\fP is returned. If \fIx\fP is less than or equal to \fIy\fP, ++0 is returned. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the positive +difference value. +.LP +If \fIx\fP- \fIy\fP is positive and overflows, a range error shall +occur and \fIfdim\fP(), \fIfdimf\fP(), and \fIfdiml\fP() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.LP +If \fIx\fP- \fIy\fP is positive and underflows, a range error may +occur, and either ( \fIx\fP- \fIy\fP) (if representable), +\ or 0.0 (if supported), or an implementation-defined value +shall be returned. +.LP +If +\fIx\fP or \fIy\fP is NaN, a NaN shall be returned. +.SH ERRORS +.LP +The \fIfdim\fP() function shall fail if: +.TP 7 +Range\ Error +The result overflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be +raised. +.sp +.LP +The \fIfdim\fP() function may fail if: +.TP 7 +Range\ Error +The result underflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On implementations supporting IEEE\ Std\ 754-1985, \fIx\fP- \fIy\fP +cannot underflow, and hence the 0.0 return value +is shaded as an extension for implementations supporting the XSI extension +rather than an MX extension. +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIfmax\fP() , \fIfmin\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fdimf.3p b/man3p/fdimf.3p new file mode 100644 index 000000000..f4eb10474 --- /dev/null +++ b/man3p/fdimf.3p @@ -0,0 +1 @@ +.so man3p/fdim.3p diff --git a/man3p/fdiml.3p b/man3p/fdiml.3p new file mode 100644 index 000000000..f4eb10474 --- /dev/null +++ b/man3p/fdiml.3p @@ -0,0 +1 @@ +.so man3p/fdim.3p diff --git a/man3p/fdopen.3p b/man3p/fdopen.3p new file mode 100644 index 000000000..f3c3b5db7 --- /dev/null +++ b/man3p/fdopen.3p @@ -0,0 +1,138 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FDOPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fdopen +.SH NAME +fdopen \- associate a stream with a file descriptor +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +FILE *fdopen(int\fP \fIfildes\fP\fB, const char *\fP\fImode\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIfdopen\fP() function shall associate a stream with a file descriptor. +.LP +The \fImode\fP argument is a character string having one of the following +values: +.TP 7 +\fIr\fP\ or\ \fIrb\fP +Open a file for reading. +.TP 7 +\fIw\fP\ or\ \fIwb\fP +Open a file for writing. +.TP 7 +\fIa\fP\ or\ \fIab\fP +Open a file for writing at end-of-file. +.TP 7 +\fIr\fP+\ or\ \fIrb\fP+\ or\ \fIr\fP+\fIb\fP +Open a file for update (reading and writing). +.TP 7 +\fIw\fP+\ or\ \fIwb\fP+\ or\ \fIw\fP+\fIb\fP +Open a file for update (reading and writing). +.TP 7 +\fIa\fP+\ or\ \fIab\fP+\ or\ \fIa\fP+\fIb\fP +Open a file for update (reading and writing) at end-of-file. +.sp +.LP +The meaning of these flags is exactly as specified in \fIfopen\fP(), +except that modes +beginning with \fIw\fP shall not cause truncation of the file. +.LP +Additional values for the \fImode\fP argument may be supported by +an implementation. +.LP +The application shall ensure that the mode of the stream as expressed +by the \fImode\fP argument is allowed by the file access +mode of the open file description to which \fIfildes\fP refers. The +file position indicator associated with the new stream is set +to the position indicated by the file offset associated with the file +descriptor. +.LP +The error and end-of-file indicators for the stream shall be cleared. +The \fIfdopen\fP() function may cause the \fIst_atime\fP +field of the underlying file to be marked for update. +.LP +If \fIfildes\fP refers to a shared memory object, the result of the +\fIfdopen\fP() function is unspecified. +.LP +If \fIfildes\fP refers to a typed memory object, the result of the +\fIfdopen\fP() function is unspecified. +.LP +The \fIfdopen\fP() function shall preserve the offset maximum previously +set for the open file description corresponding to +\fIfildes\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIfdopen\fP() shall return a pointer +to a stream; otherwise, a null pointer shall be returned and +\fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIfdopen\fP() function may fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B EINVAL +The \fImode\fP argument is not a valid mode. +.TP 7 +.B EMFILE +{FOPEN_MAX} streams are currently open in the calling process. +.TP 7 +.B EMFILE +{STREAM_MAX} streams are currently open in the calling process. +.TP 7 +.B ENOMEM +Insufficient space to allocate a buffer. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +File descriptors are obtained from calls like \fIopen\fP(), \fIdup\fP(), +\fIcreat\fP(), or \fIpipe\fP(), which open files but do not return +streams. +.SH RATIONALE +.LP +The file descriptor may have been obtained from \fIopen\fP(), \fIcreat\fP(), +\fIpipe\fP(), \fIdup\fP(), or \fIfcntl\fP(); inherited through \fIfork\fP() +or \fIexec\fP; or perhaps obtained by +implementation-defined means, such as the 4.3 BSD \fIsocket\fP() call. +.LP +The meanings of the \fImode\fP arguments of \fIfdopen\fP() and \fIfopen\fP() +differ. +With \fIfdopen\fP(), open for write (\fIw\fP or \fIw+\fP) does not +truncate, and append (\fIa\fP or \fIa+\fP) cannot create +for writing. The \fImode\fP argument formats that include \fIa b\fP +are allowed for consistency with the ISO\ C standard +function \fIfopen\fP(). The \fIb\fP has no effect on the resulting +stream. Although not +explicitly required by this volume of IEEE\ Std\ 1003.1-2001, a good +implementation of append (\fIa\fP) mode would cause +the O_APPEND flag to be set. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIInteraction of File Descriptors and Standard I/O Streams\fP , \fIfclose\fP() +, \fIfopen\fP() , \fIopen\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/feclearexcept.3p b/man3p/feclearexcept.3p new file mode 100644 index 000000000..b57791fcb --- /dev/null +++ b/man3p/feclearexcept.3p @@ -0,0 +1,55 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FECLEAREXCEPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" feclearexcept +.SH NAME +feclearexcept \- clear floating-point exception +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int feclearexcept(int\fP \fIexcepts\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfeclearexcept\fP() function shall attempt to clear the supported +floating-point exceptions represented by +\fIexcepts\fP. +.SH RETURN VALUE +.LP +If the argument is zero or if all the specified exceptions were successfully +cleared, \fIfeclearexcept\fP() shall return zero. +Otherwise, it shall return a non-zero value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfegetexceptflag\fP() , \fIferaiseexcept\fP() , \fIfesetexceptflag\fP() +, \fIfetestexcept\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fegetenv.3p b/man3p/fegetenv.3p new file mode 100644 index 000000000..41bc8875b --- /dev/null +++ b/man3p/fegetenv.3p @@ -0,0 +1,67 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FEGETENV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fegetenv +.SH NAME +fegetenv, fesetenv \- get and set current floating-point environment +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fegetenv(fenv_t *\fP\fIenvp\fP\fB); +.br +int fesetenv(const fenv_t *\fP\fIenvp\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfegetenv\fP() function shall attempt to store the current floating-point +environment in the object pointed to by +\fIenvp\fP. +.LP +The \fIfesetenv\fP() function shall attempt to establish the floating-point +environment represented by the object pointed to by +\fIenvp\fP. The argument \fIenvp\fP shall point to an object set by +a call to \fIfegetenv\fP() or \fIfeholdexcept\fP(), or equal a floating-point +environment macro. The \fIfesetenv\fP() +function does not raise floating-point exceptions, but only installs +the state of the floating-point status flags represented +through its argument. +.SH RETURN VALUE +.LP +If the representation was successfully stored, \fIfegetenv\fP() shall +return zero. Otherwise, it shall return a non-zero value. +If the environment was successfully established, \fIfesetenv\fP() +shall return zero. Otherwise, it shall return a non-zero +value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeholdexcept\fP() , \fIfeupdateenv\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fegetexceptflag.3p b/man3p/fegetexceptflag.3p new file mode 100644 index 000000000..fe397daf8 --- /dev/null +++ b/man3p/fegetexceptflag.3p @@ -0,0 +1,70 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FEGETEXCEPTFLAG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fegetexceptflag +.SH NAME +fegetexceptflag, fesetexceptflag \- get and set floating-point status +flags +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fegetexceptflag(fexcept_t *\fP\fIflagp\fP\fB, int\fP \fIexcepts\fP\fB); +.br +int fesetexceptflag(const fexcept_t *\fP\fIflagp\fP\fB, int\fP \fIexcepts\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfegetexceptflag\fP() function shall attempt to store an implementation-defined +representation of the states of the +floating-point status flags indicated by the argument \fIexcepts\fP +in the object pointed to by the argument \fIflagp\fP. +.LP +The \fIfesetexceptflag\fP() function shall attempt to set the floating-point +status flags indicated by the argument +\fIexcepts\fP to the states stored in the object pointed to by \fIflagp\fP. +The value pointed to by \fIflagp\fP shall have been +set by a previous call to \fIfegetexceptflag\fP() whose second argument +represented at least those floating-point exceptions +represented by the argument \fIexcepts\fP. This function does not +raise floating-point exceptions, but only sets the state of the +flags. +.SH RETURN VALUE +.LP +If the representation was successfully stored, \fIfegetexceptflag\fP() +shall return zero. Otherwise, it shall return a non-zero +value. If the \fIexcepts\fP argument is zero or if all the specified +exceptions were successfully set, \fIfesetexceptflag\fP() +shall return zero. Otherwise, it shall return a non-zero value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIferaiseexcept\fP() , \fIfetestexcept\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fegetround.3p b/man3p/fegetround.3p new file mode 100644 index 000000000..ead5052f7 --- /dev/null +++ b/man3p/fegetround.3p @@ -0,0 +1,86 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FEGETROUND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fegetround +.SH NAME +fegetround, fesetround \- get and set current rounding direction +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fegetround(void); +.br +int fesetround(int\fP \fIround\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfegetround\fP() function shall get the current rounding direction. +.LP +The \fIfesetround\fP() function shall establish the rounding direction +represented by its argument \fIround\fP. If the +argument is not equal to the value of a rounding direction macro, +the rounding direction is not changed. +.SH RETURN VALUE +.LP +The \fIfegetround\fP() function shall return the value of the rounding +direction macro representing the current rounding +direction or a negative value if there is no such rounding direction +macro or the current rounding direction is not +determinable. +.LP +The \fIfesetround\fP() function shall return a zero value if and only +if the requested rounding direction was established. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The following example saves, sets, and restores the rounding direction, +reporting an error and aborting if setting the rounding +direction fails: +.sp +.RS +.nf + +\fB#include +#include +void f(int round_dir) +{ + #pragma STDC FENV_ACCESS ON + int save_round; + int setround_ok; + save_round = fegetround(); + setround_ok = fesetround(round_dir); + assert(setround_ok == 0); + /* ... */ + fesetround(save_round); + /* ... */ +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/feholdexcept.3p b/man3p/feholdexcept.3p new file mode 100644 index 000000000..bd105d732 --- /dev/null +++ b/man3p/feholdexcept.3p @@ -0,0 +1,60 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FEHOLDEXCEPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" feholdexcept +.SH NAME +feholdexcept \- save current floating-point environment +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int feholdexcept(fenv_t *\fP\fIenvp\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfeholdexcept\fP() function shall save the current floating-point +environment in the object pointed to by \fIenvp\fP, +clear the floating-point status flags, and then install a non-stop +(continue on floating-point exceptions) mode, if available, for +all floating-point exceptions. +.SH RETURN VALUE +.LP +The \fIfeholdexcept\fP() function shall return zero if and only if +non-stop floating-point exception handling was successfully +installed. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIfeholdexcept\fP() function should be effective on typical IEC\ 60559:1989 +standard implementations which have the +default non-stop mode and at least one other mode for trap handling +or aborting. If the implementation provides only the non-stop +mode, then installing the non-stop mode is trivial. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfegetenv\fP() , \fIfesetenv\fP() , \fIfeupdateenv\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/feof.3p b/man3p/feof.3p new file mode 100644 index 000000000..0f2032066 --- /dev/null +++ b/man3p/feof.3p @@ -0,0 +1,52 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FEOF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" feof +.SH NAME +feof \- test end-of-file indicator on a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int feof(FILE *\fP\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfeof\fP() function shall test the end-of-file indicator for +the stream pointed to by \fIstream\fP. +.SH RETURN VALUE +.LP +The \fIfeof\fP() function shall return non-zero if and only if the +end-of-file indicator is set for \fIstream\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclearerr\fP() , \fIferror\fP() , \fIfopen\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/feraiseexcept.3p b/man3p/feraiseexcept.3p new file mode 100644 index 000000000..49b4ad2ec --- /dev/null +++ b/man3p/feraiseexcept.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FERAISEEXCEPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" feraiseexcept +.SH NAME +feraiseexcept \- raise floating-point exception +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int feraiseexcept(int\fP \fIexcepts\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIferaiseexcept\fP() function shall attempt to raise the supported +floating-point exceptions represented by the argument +\fIexcepts\fP. The order in which these floating-point exceptions +are raised is unspecified. Whether the \fIferaiseexcept\fP() +function additionally raises the inexact floating-point exception +whenever it raises the overflow or underflow floating-point +exception is implementation-defined. +.SH RETURN VALUE +.LP +If the argument is zero or if all the specified exceptions were successfully +raised, \fIferaiseexcept\fP() shall return zero. +Otherwise, it shall return a non-zero value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The effect is intended to be similar to that of floating-point exceptions +raised by arithmetic operations. Hence, enabled traps +for floating-point exceptions raised by this function are taken. +.SH RATIONALE +.LP +Raising overflow or underflow is allowed to also raise inexact because +on some architectures the only practical way to raise an +exception is to execute an instruction that has the exception as a +side effect. The function is not restricted to accept only valid +coincident expressions for atomic operations, so the function can +be used to raise exceptions accrued over several operations. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfegetexceptflag\fP() , \fIfesetexceptflag\fP() +, \fIfetestexcept\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ferror.3p b/man3p/ferror.3p new file mode 100644 index 000000000..52a9c9ec7 --- /dev/null +++ b/man3p/ferror.3p @@ -0,0 +1,52 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FERROR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ferror +.SH NAME +ferror \- test error indicator on a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int ferror(FILE *\fP\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIferror\fP() function shall test the error indicator for the +stream pointed to by \fIstream\fP. +.SH RETURN VALUE +.LP +The \fIferror\fP() function shall return non-zero if and only if the +error indicator is set for \fIstream\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclearerr\fP() , \fIfeof\fP() , \fIfopen\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fesetenv.3p b/man3p/fesetenv.3p new file mode 100644 index 000000000..9ab2a3122 --- /dev/null +++ b/man3p/fesetenv.3p @@ -0,0 +1 @@ +.so man3p/fegetenv.3p diff --git a/man3p/fesetexceptflag.3p b/man3p/fesetexceptflag.3p new file mode 100644 index 000000000..43b52daec --- /dev/null +++ b/man3p/fesetexceptflag.3p @@ -0,0 +1 @@ +.so man3p/fegetexceptflag.3p diff --git a/man3p/fesetround.3p b/man3p/fesetround.3p new file mode 100644 index 000000000..18c87399d --- /dev/null +++ b/man3p/fesetround.3p @@ -0,0 +1 @@ +.so man3p/fegetround.3p diff --git a/man3p/fetestexcept.3p b/man3p/fetestexcept.3p new file mode 100644 index 000000000..1c8867895 --- /dev/null +++ b/man3p/fetestexcept.3p @@ -0,0 +1,77 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FETESTEXCEPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fetestexcept +.SH NAME +fetestexcept \- test floating-point exception flags +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fetestexcept(int\fP \fIexcepts\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfetestexcept\fP() function shall determine which of a specified +subset of the floating-point exception flags are +currently set. The \fIexcepts\fP argument specifies the floating-point +status flags to be queried. +.SH RETURN VALUE +.LP +The \fIfetestexcept\fP() function shall return the value of the bitwise-inclusive +OR of the floating-point exception macros +corresponding to the currently set floating-point exceptions included +in \fIexcepts\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The following example calls function \fIf\fP() if an invalid exception +is set, and then function \fIg\fP() if an overflow +exception is set: +.sp +.RS +.nf + +\fB#include +/* ... */ +{ + #pragma STDC FENV_ACCESS ON + int set_excepts; + feclearexcept(FE_INVALID | FE_OVERFLOW); + // maybe raise exceptions + set_excepts = fetestexcept(FE_INVALID | FE_OVERFLOW); + if (set_excepts & FE_INVALID) f(); + if (set_excepts & FE_OVERFLOW) g(); + /* ... */ +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfegetexceptflag\fP() , \fIferaiseexcept\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/feupdateenv.3p b/man3p/feupdateenv.3p new file mode 100644 index 000000000..c31aa0c7b --- /dev/null +++ b/man3p/feupdateenv.3p @@ -0,0 +1,80 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FEUPDATEENV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" feupdateenv +.SH NAME +feupdateenv \- update floating-point environment +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int feupdateenv(const fenv_t *\fP\fIenvp\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfeupdateenv\fP() function shall attempt to save the currently +raised floating-point exceptions in its automatic storage, +attempt to install the floating-point environment represented by the +object pointed to by \fIenvp\fP, and then attempt to raise +the saved floating-point exceptions. The argument \fIenvp\fP shall +point to an object set by a call to \fIfeholdexcept\fP() or \fIfegetenv\fP(), +or equal +a floating-point environment macro. +.SH RETURN VALUE +.LP +The \fIfeupdateenv\fP() function shall return a zero value if and +only if all the required actions were successfully carried +out. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The following example shows sample code to hide spurious underflow +floating-point exceptions: +.sp +.RS +.nf + +\fB#include +double f(double x) +{ + #pragma STDC FENV_ACCESS ON + double result; + fenv_t save_env; + feholdexcept(&save_env); + // compute result + if (/* test spurious underflow */) + feclearexcept(FE_UNDERFLOW); + feupdateenv(&save_env); + return result; +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfegetenv\fP() , \fIfeholdexcept\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fflush.3p b/man3p/fflush.3p new file mode 100644 index 000000000..0747ddd6f --- /dev/null +++ b/man3p/fflush.3p @@ -0,0 +1,150 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FFLUSH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fflush +.SH NAME +fflush \- flush a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fflush(FILE *\fP\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If \fIstream\fP points to an output stream or an update stream in +which the most recent operation was not input, +\fIfflush\fP() shall cause any unwritten data for that stream to be +written to the file, \ and the +\fIst_ctime\fP and \fIst_mtime\fP fields of the underlying file shall +be marked for update. +.LP +If \fIstream\fP is a null pointer, \fIfflush\fP() shall perform this +flushing action on all streams for which the behavior is +defined above. +.SH RETURN VALUE +.LP +Upon successful completion, \fIfflush\fP() shall return 0; otherwise, +it shall set the error indicator for the stream, return +EOF, +\ and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIfflush\fP() function shall fail if: +.TP 7 +.B EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying \fIstream\fP +and the process would be delayed in the write +operation. +.TP 7 +.B EBADF +The file descriptor underlying \fIstream\fP is not valid. +.TP 7 +.B EFBIG +An +attempt was made to write a file that exceeds the maximum file size. +.TP 7 +.B EFBIG +An attempt was made to write a file that exceeds the process' file +size limit. +.TP 7 +.B EFBIG +The file is a regular file and an attempt was made to write at or +beyond the offset maximum associated with the corresponding +stream. +.TP 7 +.B EINTR +The \fIfflush\fP() function was interrupted by a signal. +.TP 7 +.B EIO +The process is a member of a background process group attempting to +write to its controlling terminal, TOSTOP is set, the process +is neither ignoring nor blocking SIGTTOU, and the process group of +the process is orphaned. This error may also be returned under +implementation-defined conditions. +.TP 7 +.B ENOSPC +There was no free space remaining on the device containing the file. +.TP 7 +.B EPIPE +An +attempt is made to write to a pipe or FIFO that is not open for reading +by any process. A SIGPIPE signal shall also be sent to the +thread. +.sp +.LP +The \fIfflush\fP() function may fail if: +.TP 7 +.B ENXIO +A +request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Sending Prompts to Standard Output +.LP +The following example uses \fIprintf\fP() calls to print a series +of prompts for +information the user must enter from standard input. The \fIfflush\fP() +calls force the output to standard output. The +\fIfflush\fP() function is used because standard output is usually +buffered and the prompt may not immediately be printed on the +output or terminal. The \fIgets\fP() calls read strings from standard +input and place the +results in variables, for use later in the program. +.sp +.RS +.nf + +\fB#include +\&... +char user[100]; +char oldpasswd[100]; +char newpasswd[100]; +\&... +printf("User name: "); +fflush(stdout); +gets(user); +.sp + +printf("Old password: "); +fflush(stdout); +gets(oldpasswd); +.sp + +printf("New password: "); +fflush(stdout); +gets(newpasswd); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Data buffered by the system may make determining the validity of the +position of the current file descriptor impractical. Thus, +enforcing the repositioning of the file descriptor after \fIfflush\fP() +on streams open for \fIread\fP() is not mandated by IEEE\ Std\ 1003.1-2001. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetrlimit\fP() , \fIulimit\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ffs.3p b/man3p/ffs.3p new file mode 100644 index 000000000..418d0e04c --- /dev/null +++ b/man3p/ffs.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FFS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ffs +.SH NAME +ffs \- find first set bit +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int ffs(int\fP \fIi\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIffs\fP() function shall find the first bit set (beginning with +the least significant bit) in \fIi\fP, and return the +index of that bit. Bits are numbered starting at one (the least significant +bit). +.SH RETURN VALUE +.LP +The \fIffs\fP() function shall return the index of the first bit set. +If \fIi\fP is 0, then \fIffs\fP() shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fgetc.3p b/man3p/fgetc.3p new file mode 100644 index 000000000..f38cbee42 --- /dev/null +++ b/man3p/fgetc.3p @@ -0,0 +1,120 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FGETC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fgetc +.SH NAME +fgetc \- get a byte from a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fgetc(FILE *\fP\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If the end-of-file indicator for the input stream pointed to by \fIstream\fP +is not set and a next byte is present, the +\fIfgetc\fP() function shall obtain the next byte as an \fBunsigned +char\fP converted to an \fBint\fP, from the input stream +pointed to by \fIstream\fP, and advance the associated file position +indicator for the stream (if defined). Since \fIfgetc\fP() +operates on bytes, reading a character consisting of multiple bytes +(or "a multi-byte character") may require multiple calls to +\fIfgetc\fP(). +.LP +The +\fIfgetc\fP() function may mark the \fIst_atime\fP field of the file +associated with \fIstream\fP for update. The +\fIst_atime\fP field shall be marked for update by the first successful +execution of \fIfgetc\fP(), \fIfgets\fP(), \fIfgetwc\fP(), \fIfgetws\fP(), +\fIfread\fP(), \fIfscanf\fP(), \fIgetc\fP(), \fIgetchar\fP(), \fIgets\fP(), +or \fIscanf\fP() using \fIstream\fP that returns data not supplied +by a prior call to \fIungetc\fP() or \fIungetwc\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, \fIfgetc\fP() shall return the next byte +from the input stream pointed to by \fIstream\fP. If the +end-of-file indicator for the stream is set, or if the stream is at +end-of-file, the end-of-file indicator for the stream shall be +set and \fIfgetc\fP() shall return EOF. If a read error occurs, the +error indicator for the stream shall be set, \fIfgetc\fP() +shall return EOF, \ and shall set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIfgetc\fP() function shall fail if data needs to be read and: +.TP 7 +.B EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying \fIstream\fP +and the process would be delayed in the \fIfgetc\fP() +operation. +.TP 7 +.B EBADF +The file descriptor underlying \fIstream\fP is not a valid file descriptor +open for reading. +.TP 7 +.B EINTR +The read operation was terminated due to the receipt of a signal, +and no data was transferred. +.TP 7 +.B EIO +A +physical I/O error has occurred, or the process is in a background +process group attempting to read from its controlling terminal, +and either the process is ignoring or blocking the SIGTTIN signal +or the process group is orphaned. This error may also be +generated for implementation-defined reasons. +.TP 7 +.B EOVERFLOW +The file is a regular file and an attempt was made to read at or beyond +the offset maximum associated with the corresponding +stream. +.sp +.LP +The \fIfgetc\fP() function may fail if: +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.TP 7 +.B ENXIO +A +request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +If the integer value returned by \fIfgetc\fP() is stored into a variable +of type \fBchar\fP and then compared against the +integer constant EOF, the comparison may never succeed, because sign-extension +of a variable of type \fBchar\fP on widening to +integer is implementation-defined. +.LP +The \fIferror\fP() or \fIfeof\fP() functions must +be used to distinguish between an error condition and an end-of-file +condition. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeof\fP() , \fIferror\fP() , \fIfopen\fP() , \fIgetchar\fP() , +\fIgetc\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fgetpos.3p b/man3p/fgetpos.3p new file mode 100644 index 000000000..03cea2679 --- /dev/null +++ b/man3p/fgetpos.3p @@ -0,0 +1,75 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FGETPOS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fgetpos +.SH NAME +fgetpos \- get current file position information +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fgetpos(FILE *restrict\fP \fIstream\fP\fB, fpos_t *restrict\fP +\fIpos\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfgetpos\fP() function shall store the current values of the +parse state (if any) and file position indicator for the +stream pointed to by \fIstream\fP in the object pointed to by \fIpos\fP. +The value stored contains unspecified information usable +by \fIfsetpos\fP() for repositioning the stream to its position at +the time of the call to +\fIfgetpos\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, \fIfgetpos\fP() shall return 0; otherwise, +it shall return a non-zero value and set \fIerrno\fP to +indicate the error. +.SH ERRORS +.LP +The \fIfgetpos\fP() function shall fail if: +.TP 7 +.B EOVERFLOW +The current value of the file position cannot be represented correctly +in an object of type \fBfpos_t\fP. +.sp +.LP +The \fIfgetpos\fP() function may fail if: +.TP 7 +.B EBADF +The file descriptor underlying \fIstream\fP is not valid. +.TP 7 +.B ESPIPE +The file descriptor underlying \fIstream\fP is associated with a pipe, +FIFO, or socket. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfopen\fP() , \fIftell\fP() , \fIrewind\fP() , +\fIungetc\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fgets.3p b/man3p/fgets.3p new file mode 100644 index 000000000..62e5b1eb1 --- /dev/null +++ b/man3p/fgets.3p @@ -0,0 +1,87 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FGETS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fgets +.SH NAME +fgets \- get a string from a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *fgets(char *restrict\fP \fIs\fP\fB, int\fP \fIn\fP\fB, FILE +*restrict\fP \fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfgets\fP() function shall read bytes from \fIstream\fP into +the array pointed to by \fIs\fP, until \fIn\fP-1 bytes +are read, or a is read and transferred to \fIs\fP, or an +end-of-file condition is encountered. The string is then +terminated with a null byte. +.LP +The +\fIfgets\fP() function may mark the \fIst_atime\fP field of the file +associated with \fIstream\fP for update. The +\fIst_atime\fP field shall be marked for update by the first successful +execution of \fIfgetc\fP(), \fIfgets\fP(), \fIfgetwc\fP(), \fIfgetws\fP(), +\fIfread\fP(), \fIfscanf\fP(), \fIgetc\fP(), \fIgetchar\fP(), \fIgets\fP(), +or \fIscanf\fP() using \fIstream\fP that returns data not supplied +by a prior call to \fIungetc\fP() or \fIungetwc\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, \fIfgets\fP() shall return \fIs\fP. If +the stream is at end-of-file, the end-of-file indicator for +the stream shall be set and \fIfgets\fP() shall return a null pointer. +If a read error occurs, the error indicator for the stream +shall be set, \fIfgets\fP() shall return a null pointer, \ and shall +set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +Refer to \fIfgetc\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Reading Input +.LP +The following example uses \fIfgets\fP() to read each line of input. +{LINE_MAX}, which defines the maximum size of the input +line, is defined in the \fI\fP header. +.sp +.RS +.nf + +\fB#include +\&... +char line[LINE_MAX]; +\&... +while (fgets(line, LINE_MAX, fp) != NULL) { +\&... +} +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfopen\fP() , \fIfread\fP() , \fIgets\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fgetwc.3p b/man3p/fgetwc.3p new file mode 100644 index 000000000..8f5eb742b --- /dev/null +++ b/man3p/fgetwc.3p @@ -0,0 +1,122 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FGETWC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fgetwc +.SH NAME +fgetwc \- get a wide-character code from a stream +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +wint_t fgetwc(FILE *\fP\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfgetwc\fP() function shall obtain the next character (if present) +from the input stream pointed to by \fIstream\fP, +convert that to the corresponding wide-character code, and advance +the associated file position indicator for the stream (if +defined). +.LP +If an error occurs, the resulting value of the file position indicator +for the stream is unspecified. +.LP +The +\fIfgetwc\fP() function may mark the \fIst_atime\fP field of the file +associated with \fIstream\fP for update. The +\fIst_atime\fP field shall be marked for update by the first successful +execution of \fIfgetc\fP(), \fIfgets\fP(), \fIfgetwc\fP(), \fIfgetws\fP(), +\fIfread\fP(), \fIfscanf\fP(), \fIgetc\fP(), \fIgetchar\fP(), \fIgets\fP(), +or \fIscanf\fP() using \fIstream\fP that returns data not supplied +by a prior call to \fIungetc\fP() or \fIungetwc\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, the \fIfgetwc\fP() function shall return +the wide-character code of the character read from the +input stream pointed to by \fIstream\fP converted to a type \fBwint_t\fP. +If the stream is at end-of-file, the end-of-file +indicator for the stream shall be set and \fIfgetwc\fP() shall return +WEOF. If a read error occurs, the error indicator for the +stream shall be set, \fIfgetwc\fP() shall return WEOF, \ and shall +set \fIerrno\fP to indicate the error. If an encoding error occurs, +the error indicator for the stream shall be +set, \fIfgetwc\fP() shall return WEOF, and shall set \fIerrno\fP to +indicate the error. +.SH ERRORS +.LP +The \fIfgetwc\fP() function shall fail if data needs to be read and: +.TP 7 +.B EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying \fIstream\fP +and the process would be delayed in the \fIfgetwc\fP() +operation. +.TP 7 +.B EBADF +The file descriptor underlying \fIstream\fP is not a valid file descriptor +open for reading. +.TP 7 +.B EILSEQ +The data obtained from the input stream does not form a valid character. +.TP 7 +.B EINTR +The read operation was terminated due to the receipt of a signal, +and no data was transferred. +.TP 7 +.B EIO +A +physical I/O error has occurred, or the process is in a background +process group attempting to read from its controlling terminal, +and either the process is ignoring or blocking the SIGTTIN signal +or the process group is orphaned. This error may also be +generated for implementation-defined reasons. +.TP 7 +.B EOVERFLOW +The file is a regular file and an attempt was made to read at or beyond +the offset maximum associated with the corresponding +stream. +.sp +.LP +The \fIfgetwc\fP() function may fail if: +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.TP 7 +.B ENXIO +A +request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIferror\fP() or \fIfeof\fP() functions must +be used to distinguish between an error condition and an end-of-file +condition. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeof\fP() , \fIferror\fP() , \fIfopen\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fgetws.3p b/man3p/fgetws.3p new file mode 100644 index 000000000..1254f87a1 --- /dev/null +++ b/man3p/fgetws.3p @@ -0,0 +1,77 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FGETWS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fgetws +.SH NAME +fgetws \- get a wide-character string from a stream +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +wchar_t *fgetws(wchar_t *restrict\fP \fIws\fP\fB, int\fP \fIn\fP\fB, +.br +\ \ \ \ \ \ FILE *restrict\fP \fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfgetws\fP() function shall read characters from the \fIstream\fP, +convert these to the corresponding wide-character +codes, place them in the \fBwchar_t\fP array pointed to by \fIws\fP, +until \fIn\fP-1 characters are read, or a +is read, converted, and transferred to \fIws\fP, or an end-of-file +condition is encountered. The wide-character string, \fIws\fP, +shall then be terminated with a null wide-character code. +.LP +If an error occurs, the resulting value of the file position indicator +for the stream is unspecified. +.LP +The +\fIfgetws\fP() function may mark the \fIst_atime\fP field of the file +associated with \fIstream\fP for update. The +\fIst_atime\fP field shall be marked for update by the first successful +execution of \fIfgetc\fP(), \fIfgets\fP(), \fIfgetwc\fP(), \fIfgetws\fP(), +\fIfread\fP(), \fIfscanf\fP(), \fIgetc\fP(), \fIgetchar\fP(), \fIgets\fP(), +or \fIscanf\fP() using \fIstream\fP that returns data not supplied +by a prior call to \fIungetc\fP() or \fIungetwc\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, \fIfgetws\fP() shall return \fIws\fP. +If the stream is at end-of-file, the end-of-file indicator +for the stream shall be set and \fIfgetws\fP() shall return a null +pointer. If a read error occurs, the error indicator for the +stream shall be set, \fIfgetws\fP() shall return a null pointer, +\ and shall set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +Refer to \fIfgetwc\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfopen\fP() , \fIfread\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fileno.3p b/man3p/fileno.3p new file mode 100644 index 000000000..688ae2bc8 --- /dev/null +++ b/man3p/fileno.3p @@ -0,0 +1,67 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FILENO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fileno +.SH NAME +fileno \- map a stream pointer to a file descriptor +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fileno(FILE *\fP\fIstream\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIfileno\fP() function shall return the integer file descriptor +associated with the stream pointed to by +\fIstream\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIfileno\fP() shall return the integer +value of the file descriptor associated with \fIstream\fP. +Otherwise, the value -1 shall be returned and \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +The \fIfileno\fP() function may fail if: +.TP 7 +.B EBADF +The \fIstream\fP argument is not a valid stream. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Without some specification of which file descriptors are associated +with these streams, it is impossible for an application to +set up the streams for another application it starts with \fIfork\fP() +and \fIexec\fP. In particular, it would not be possible to write a +portable version of the \fIsh\fP command interpreter (although there +may be other constraints that would prevent that +portability). +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIInteraction of File Descriptors and Standard I/O Streams\fP , \fIfdopen\fP() +, \fIfopen\fP() , \fIstdin\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/flockfile.3p b/man3p/flockfile.3p new file mode 100644 index 000000000..1388e0cc3 --- /dev/null +++ b/man3p/flockfile.3p @@ -0,0 +1,124 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FLOCKFILE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" flockfile +.SH NAME +flockfile, ftrylockfile, funlockfile \- stdio locking functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void flockfile(FILE *\fP\fIfile\fP\fB); +.br +int ftrylockfile(FILE *\fP\fIfile\fP\fB); +.br +void funlockfile(FILE *\fP\fIfile\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +These functions shall provide for explicit application-level locking +of stdio ( \fBFILE *\fP) objects. These functions can be +used by a thread to delineate a sequence of I/O statements that are +executed as a unit. +.LP +The \fIflockfile\fP() function shall acquire for a thread ownership +of a ( \fBFILE *\fP) object. +.LP +The \fIftrylockfile\fP() function shall acquire for a thread ownership +of a ( \fBFILE *\fP) object if the object is available; +\fIftrylockfile\fP() is a non-blocking version of \fIflockfile\fP(). +.LP +The \fIfunlockfile\fP() function shall relinquish the ownership granted +to the thread. The behavior is undefined if a thread +other than the current owner calls the \fIfunlockfile\fP() function. +.LP +The functions shall behave as if there is a lock count associated +with each ( \fBFILE *\fP) object. This count is implicitly +initialized to zero when the ( \fBFILE *\fP) object is created. The +( \fBFILE *\fP) object is unlocked when the count is zero. +When the count is positive, a single thread owns the ( \fBFILE *\fP) +object. When the \fIflockfile\fP() function is called, if +the count is zero or if the count is positive and the caller owns +the ( \fBFILE *\fP) object, the count shall be incremented. +Otherwise, the calling thread shall be suspended, waiting for the +count to return to zero. Each call to \fIfunlockfile\fP() shall +decrement the count. This allows matching calls to \fIflockfile\fP() +(or successful calls to \fIftrylockfile\fP()) and +\fIfunlockfile\fP() to be nested. +.LP +All functions that reference ( \fBFILE *\fP) objects shall behave +as if they use \fIflockfile\fP() and \fIfunlockfile\fP() +internally to obtain ownership of these ( \fBFILE *\fP) objects. +.SH RETURN VALUE +.LP +None for \fIflockfile\fP() and \fIfunlockfile\fP(). +.LP +The \fIftrylockfile\fP() function shall return zero for success and +non-zero to indicate that the lock cannot be acquired. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications using these functions may be subject to priority inversion, +as discussed in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 3.285, Priority Inversion. +.SH RATIONALE +.LP +The \fIflockfile\fP() and \fIfunlockfile\fP() functions provide an +orthogonal mutual-exclusion lock for each \fBFILE\fP. The +\fIftrylockfile\fP() function provides a non-blocking attempt to acquire +a file lock, analogous to \fIpthread_mutex_trylock\fP(). +.LP +These locks behave as if they are the same as those used internally +by \fIstdio\fP for thread-safety. This both provides +thread-safety of these functions without requiring a second level +of internal locking and allows functions in \fIstdio\fP to be +implemented in terms of other \fIstdio\fP functions. +.LP +Application writers and implementors should be aware that there are +potential deadlock problems on \fBFILE\fP objects. For +example, the line-buffered flushing semantics of \fIstdio\fP (requested +via {_IOLBF}) require that certain input operations +sometimes cause the buffered contents of implementation-defined line-buffered +output streams to be flushed. If two threads each +hold the lock on the other's \fBFILE\fP, deadlock ensues. This type +of deadlock can be avoided by acquiring \fBFILE\fP locks in a +consistent order. In particular, the line-buffered output stream deadlock +can typically be avoided by acquiring locks on input +streams before locks on output streams if a thread would be acquiring +both. +.LP +In summary, threads sharing \fIstdio\fP streams with other threads +can use \fIflockfile\fP() and \fIfunlockfile\fP() to cause +sequences of I/O performed by a single thread to be kept bundled. +The only case where the use of \fIflockfile\fP() and +\fIfunlockfile\fP() is required is to provide a scope protecting uses +of the +\fI*_unlocked\fP() functions/macros. This moves the cost/performance +tradeoff to the optimal +point. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetc_unlocked\fP() , \fIputc_unlocked\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/floor.3p b/man3p/floor.3p new file mode 100644 index 000000000..0d8c64afa --- /dev/null +++ b/man3p/floor.3p @@ -0,0 +1,97 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FLOOR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" floor +.SH NAME +floor, floorf, floorl \- floor function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double floor(double\fP \fIx\fP\fB); +.br +float floorf(float\fP \fIx\fP\fB); +.br +long double floorl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the largest integral value not greater +than \fIx\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the largest +integral value not greater than \fIx\fP, expressed as a +\fBdouble\fP, \fBfloat\fP, or \fBlong double\fP, as appropriate for +the return type of the function. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0 or \(+-Inf, \fIx\fP shall be returned. +.LP +If the correct value would cause overflow, a range error shall occur +and \fIfloor\fP(), \fIfloorf\fP(), and \fIfloorl\fP() shall +return the value of the macro -HUGE_VAL, -HUGE_VALF, and -HUGE_VALL, +respectively. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Range\ Error +The result would cause an overflow. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The integral value returned by these functions might not be expressible +as an \fBint\fP or \fBlong\fP. The return value should +be tested before assigning it to an integer type to avoid the undefined +results of an integer overflow. +.LP +The \fIfloor\fP() function can only overflow when the floating-point +representation has DBL_MANT_DIG > DBL_MAX_EXP. +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIceil\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/floorf.3p b/man3p/floorf.3p new file mode 100644 index 000000000..ea5aa817a --- /dev/null +++ b/man3p/floorf.3p @@ -0,0 +1 @@ +.so man3p/floor.3p diff --git a/man3p/floorl.3p b/man3p/floorl.3p new file mode 100644 index 000000000..ea5aa817a --- /dev/null +++ b/man3p/floorl.3p @@ -0,0 +1 @@ +.so man3p/floor.3p diff --git a/man3p/fma.3p b/man3p/fma.3p new file mode 100644 index 000000000..2c1dd300d --- /dev/null +++ b/man3p/fma.3p @@ -0,0 +1,136 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FMA" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fma +.SH NAME +fma, fmaf, fmal \- floating-point multiply-add +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double fma(double\fP \fIx\fP\fB, double\fP \fIy\fP\fB, double\fP \fIz\fP\fB); +.br +float fmaf(float\fP \fIx\fP\fB, float\fP \fIy\fP\fB, float\fP \fIz\fP\fB); +.br +long double fmal(long double\fP \fIx\fP\fB, long double\fP \fIy\fP\fB, +long double\fP \fIz\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute (\fIx\fP\ *\ \fIy\fP)\ +\ \fIz\fP, rounded +as one ternary operation: they shall +compute the value (as if) to infinite precision and round once to +the result format, according to the rounding mode characterized +by the value of FLT_ROUNDS. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return (\fIx\fP\ *\ \fIy\fP)\ + +\fIz\fP, rounded as one ternary +operation. +.LP +If +\fIx\fP or \fIy\fP are NaN, a NaN shall be returned. +.LP +If \fIx\fP multiplied by \fIy\fP is an exact infinity and \fIz\fP +is also an infinity but with the opposite sign, a domain +error shall occur, and either a NaN (if supported), or an implementation-defined +value shall be returned. +.LP +If one of \fIx\fP and \fIy\fP is infinite, the other is zero, and +\fIz\fP is not a NaN, a domain error shall occur, and +either a NaN (if supported), or an implementation-defined value shall +be returned. +.LP +If one of \fIx\fP and \fIy\fP is infinite, the other is zero, and +\fIz\fP is a NaN, a NaN shall be returned and a domain +error may occur. +.LP +If \fIx\fP* \fIy\fP is not 0*Inf nor Inf*0 and \fIz\fP is a NaN, a +NaN shall be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The value of \fIx\fP* \fIy\fP+ \fIz\fP is invalid, or the value \fIx\fP* +\fIy\fP is invalid and \fIz\fP is not a NaN. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be raised. +.TP 7 +Range\ Error +The result overflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be raised. +.sp +.LP +These functions may fail if: +.TP 7 +Domain\ Error +The value \fIx\fP* \fIy\fP is invalid and \fIz\fP is a NaN. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be raised. +.TP 7 +Range\ Error +The result underflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +In many cases, clever use of floating (\fIfused\fP) multiply-add leads +to much improved code; but its unexpected use by the +compiler can undermine carefully written code. The FP_CONTRACT macro +can be used to disallow use of floating multiply-add; and the +\fIfma\fP() function guarantees its use where desired. Many current +machines provide hardware floating multiply-add instructions; +software implementation can be used for others. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of +Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fmaf.3p b/man3p/fmaf.3p new file mode 100644 index 000000000..b52cbea47 --- /dev/null +++ b/man3p/fmaf.3p @@ -0,0 +1 @@ +.so man3p/fma.3p diff --git a/man3p/fmal.3p b/man3p/fmal.3p new file mode 100644 index 000000000..b52cbea47 --- /dev/null +++ b/man3p/fmal.3p @@ -0,0 +1 @@ +.so man3p/fma.3p diff --git a/man3p/fmax.3p b/man3p/fmax.3p new file mode 100644 index 000000000..9ef0e83d7 --- /dev/null +++ b/man3p/fmax.3p @@ -0,0 +1,64 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FMAX" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fmax +.SH NAME +fmax, fmaxf, fmaxl \- determine maximum numeric value of two floating-point +numbers +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double fmax(double\fP \fIx\fP\fB, double\fP \fIy\fP\fB); +.br +float fmaxf(float\fP \fIx\fP\fB, float\fP \fIy\fP\fB); +.br +long double fmaxl(long double\fP \fIx\fP\fB, long double\fP \fIy\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall determine the maximum numeric value of their +arguments. NaN arguments shall be treated as missing data: if +one argument is a NaN and the other numeric, then these functions +shall choose the numeric value. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the maximum +numeric value of their arguments. +.LP +If just one argument is a NaN, the other argument shall be returned. +.LP +If +\fIx\fP and \fIy\fP are NaN, a NaN shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfdim\fP() , \fIfmin\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fmaxf.3p b/man3p/fmaxf.3p new file mode 100644 index 000000000..9f3413d91 --- /dev/null +++ b/man3p/fmaxf.3p @@ -0,0 +1 @@ +.so man3p/fmax.3p diff --git a/man3p/fmaxl.3p b/man3p/fmaxl.3p new file mode 100644 index 000000000..9f3413d91 --- /dev/null +++ b/man3p/fmaxl.3p @@ -0,0 +1 @@ +.so man3p/fmax.3p diff --git a/man3p/fmin.3p b/man3p/fmin.3p new file mode 100644 index 000000000..31f98cef7 --- /dev/null +++ b/man3p/fmin.3p @@ -0,0 +1,64 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FMIN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fmin +.SH NAME +fmin, fminf, fminl \- determine minimum numeric value of two floating-point +numbers +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double fmin(double\fP \fIx\fP\fB, double\fP \fIy\fP\fB); +.br +float fminf(float\fP \fIx\fP\fB, float\fP \fIy\fP\fB); +.br +long double fminl(long double\fP \fIx\fP\fB, long double\fP \fIy\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall determine the minimum numeric value of their +arguments. NaN arguments shall be treated as missing data: if +one argument is a NaN and the other numeric, then these functions +shall choose the numeric value. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the minimum +numeric value of their arguments. +.LP +If just one argument is a NaN, the other argument shall be returned. +.LP +If +\fIx\fP and \fIy\fP are NaN, a NaN shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfdim\fP() , \fIfmax\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fminf.3p b/man3p/fminf.3p new file mode 100644 index 000000000..8a3d367d8 --- /dev/null +++ b/man3p/fminf.3p @@ -0,0 +1 @@ +.so man3p/fmin.3p diff --git a/man3p/fminl.3p b/man3p/fminl.3p new file mode 100644 index 000000000..8a3d367d8 --- /dev/null +++ b/man3p/fminl.3p @@ -0,0 +1 @@ +.so man3p/fmin.3p diff --git a/man3p/fmod.3p b/man3p/fmod.3p new file mode 100644 index 000000000..6f9c878a9 --- /dev/null +++ b/man3p/fmod.3p @@ -0,0 +1,114 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FMOD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fmod +.SH NAME +fmod, fmodf, fmodl \- floating-point remainder value function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double fmod(double\fP \fIx\fP\fB, double\fP \fIy\fP\fB); +.br +float fmodf(float\fP \fIx\fP\fB, float\fP \fIy\fP\fB); +.br +long double fmodl(long double\fP \fIx\fP\fB, long double\fP \fIy\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall return the floating-point remainder of the division +of \fIx\fP by \fIy\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +These functions shall return the value \fIx\fP- \fIi\fP* \fIy\fP, +for some integer \fIi\fP such that, if \fIy\fP is +non-zero, the result has the same sign as \fIx\fP and magnitude less +than the magnitude of \fIy\fP. +.LP +If the correct value would cause underflow, and is not representable, +a range error may occur, and \ either 0.0 (if +supported), or \ an implementation-defined value shall be +returned. +.LP +If +\fIx\fP or \fIy\fP is NaN, a NaN shall be returned. +.LP +If \fIy\fP is zero, a domain error shall occur, and either a NaN (if +supported), or an implementation-defined value shall be +returned. +.LP +If \fIx\fP is infinite, a domain error shall occur, and either a NaN +(if supported), or an implementation-defined value shall +be returned. +.LP +If \fIx\fP is \(+-0 and \fIy\fP is not zero, \(+-0 shall be returned. +.LP +If \fIx\fP is not infinite and \fIy\fP is \(+-Inf, \fIx\fP shall be +returned. +.LP +If the correct value would cause underflow, and is representable, +a range error may occur and the correct value shall be +returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The \fIx\fP argument is infinite or \fIy\fP is zero. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be raised. +.sp +.LP +These functions may fail if: +.TP 7 +Range\ Error +The result underflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fmodf.3p b/man3p/fmodf.3p new file mode 100644 index 000000000..212b52c56 --- /dev/null +++ b/man3p/fmodf.3p @@ -0,0 +1 @@ +.so man3p/fmod.3p diff --git a/man3p/fmodl.3p b/man3p/fmodl.3p new file mode 100644 index 000000000..212b52c56 --- /dev/null +++ b/man3p/fmodl.3p @@ -0,0 +1 @@ +.so man3p/fmod.3p diff --git a/man3p/fmtmsg.3p b/man3p/fmtmsg.3p new file mode 100644 index 000000000..33a6363b9 --- /dev/null +++ b/man3p/fmtmsg.3p @@ -0,0 +1,251 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FMTMSG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fmtmsg +.SH NAME +fmtmsg \- display a message in the specified format on standard error +and/or a system console +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fmtmsg(long\fP \fIclassification\fP\fB, const char *\fP\fIlabel\fP\fB, +int\fP \fIseverity\fP\fB, +.br +\ \ \ \ \ \ const char *\fP\fItext\fP\fB, const char *\fP\fIaction\fP\fB, +const char +*\fP\fItag\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIfmtmsg\fP() function shall display messages in a specified +format instead of the traditional \fIprintf\fP() function. +.LP +Based on a message's classification component, \fIfmtmsg\fP() shall +write a formatted message either to standard error, to the +console, or to both. +.LP +A formatted message consists of up to five components as defined below. +The component \fIclassification\fP is not part of a +message displayed to the user, but defines the source of the message +and directs the display of the formatted message. +.TP 7 +\fIclassification\fP +Contains the sum of identifying values constructed from the constants +defined below. Any one identifier from a subclass may be +used in combination with a single identifier from a different subclass. +Two or more identifiers from the same subclass should not +be used together, with the exception of identifiers from the display +subclass. (Both display subclass identifiers may be used so +that messages can be displayed to both standard error and the system +console.) +.TP 7 +\fBMajor Classifications\fP +.RS +.sp +Identifies the source of the condition. Identifiers are: MM_HARD (hardware), +MM_SOFT (software), and MM_FIRM (firmware). +.RE +.TP 7 +\fBMessage Source Subclassifications\fP +.RS +.sp +Identifies the type of software in which the problem is detected. +Identifiers are: MM_APPL (application), MM_UTIL (utility), and +MM_OPSYS (operating system). +.RE +.TP 7 +\fBDisplay Subclassifications\fP +.RS +.sp +Indicates where the message is to be displayed. Identifiers are: MM_PRINT +to display the message on the standard error stream, +MM_CONSOLE to display the message on the system console. One or both +identifiers may be used. +.RE +.TP 7 +\fBStatus Subclassifications\fP +.RS +.sp +Indicates whether the application can recover from the condition. +Identifiers are: MM_RECOVER (recoverable) and MM_NRECOV +(non-recoverable). +.RE +.sp +.LP +An additional identifier, MM_NULLMC, indicates that no classification +component is supplied for the message. +.TP 7 +\fIlabel\fP +Identifies the source of the message. The format is two fields separated +by a colon. The first field is up to 10 bytes, the +second is up to 14 bytes. +.TP 7 +\fIseverity\fP +Indicates the seriousness of the condition. Identifiers for the levels +of \fIseverity\fP are: +.TP 7 +MM_HALT +.RS +Indicates that the application has encountered a severe fault and +is halting. Produces the string \fB"HALT"\fP . +.RE +.TP 7 +MM_ERROR +.RS +Indicates that the application has detected a fault. Produces the +string \fB"ERROR"\fP . +.RE +.TP 7 +MM_WARNING +.RS +Indicates a condition that is out of the ordinary, that might be a +problem, and should be watched. Produces the string +\fB"WARNING"\fP . +.RE +.TP 7 +MM_INFO +.RS +Provides information about a condition that is not in error. Produces +the string \fB"INFO"\fP . +.RE +.TP 7 +MM_NOSEV +.RS +Indicates that no severity level is supplied for the message. +.RE +.sp +.TP 7 +\fItext\fP +Describes the error condition that produced the message. The character +string is not limited to a specific size. If the +character string is empty, then the text produced is unspecified. +.TP 7 +\fIaction\fP +Describes the first step to be taken in the error-recovery process. +The \fIfmtmsg\fP() function precedes the action string +with the prefix: \fB"TO FIX:"\fP . The \fIaction\fP string is not +limited to a specific size. +.TP 7 +\fItag\fP +An identifier that references on-line documentation for the message. +Suggested usage is that \fItag\fP includes the +\fIlabel\fP and a unique identifying number. A sample \fItag\fP is +\fB"XSI:cat:146"\fP . +.sp +.LP +The \fIMSGVERB\fP environment variable (for message verbosity) shall +determine for \fIfmtmsg\fP() which message components it +is to select when writing messages to standard error. The value of +\fIMSGVERB\fP shall be a colon-separated list of optional +keywords. Valid keywords are: \fIlabel\fP, \fIseverity\fP, \fItext\fP, +\fIaction\fP, and \fItag\fP. If \fIMSGVERB\fP contains +a keyword for a component and the component's value is not the component's +null value, \fIfmtmsg\fP() shall include that component +in the message when writing the message to standard error. If \fIMSGVERB\fP +does not include a keyword for a message component, +that component shall not be included in the display of the message. +The keywords may appear in any order. If \fIMSGVERB\fP is not +defined, if its value is the null string, if its value is not of the +correct format, or if it contains keywords other than the +valid ones listed above, \fIfmtmsg\fP() shall select all components. +.LP +\fIMSGVERB\fP shall determine which components are selected for display +to standard error. All message components shall be +included in console messages. +.SH RETURN VALUE +.LP +The \fIfmtmsg\fP() function shall return one of the following values: +.TP 7 +MM_OK +The function succeeded. +.TP 7 +MM_NOTOK +The function failed completely. +.TP 7 +MM_NOMSG +The function was unable to generate a message on standard error, but +otherwise succeeded. +.TP 7 +MM_NOCON +The function was unable to generate a console message, but otherwise +succeeded. +.sp +.SH ERRORS +.LP +None. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.IP " 1." 4 +The following example of \fIfmtmsg\fP(): +.sp +.RS +.nf + +\fBfmtmsg(MM_PRINT, "XSI:cat", MM_ERROR, "illegal option", +"refer to cat in user's reference manual", "XSI:cat:001") +\fP +.fi +.RE +.LP +produces a complete message in the specified message format: +.sp +.RS +.nf + +\fBXSI:cat: ERROR: illegal option +TO FIX: refer to cat in user's reference manual XSI:cat:001 +\fP +.fi +.RE +.LP +.IP " 2." 4 +When the environment variable \fIMSGVERB\fP is set as follows: +.sp +.RS +.nf + +\fBMSGVERB=severity:text:action +\fP +.fi +.RE +.LP +and Example 1 is used, \fIfmtmsg\fP() produces: +.sp +.RS +.nf + +\fBERROR: illegal option +TO FIX: refer to cat in user's reference manual +\fP +.fi +.RE +.LP +.SH APPLICATION USAGE +.LP +One or more message components may be systematically omitted from +messages generated by an application by using the null value +of the argument for that component. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIprintf\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fnmatch.3p b/man3p/fnmatch.3p new file mode 100644 index 000000000..c2bad3b2e --- /dev/null +++ b/man3p/fnmatch.3p @@ -0,0 +1,122 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FNMATCH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fnmatch +.SH NAME +fnmatch \- match a filename or a pathname +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fnmatch(const char *\fP\fIpattern\fP\fB, const char *\fP\fIstring\fP\fB, +int\fP \fIflags\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfnmatch\fP() function shall match patterns as described in +the Shell and Utilities volume of +IEEE\ Std\ 1003.1-2001, Section 2.13.1, Patterns Matching a Single +Character, and Section 2.13.2, Patterns Matching Multiple Characters. +It checks the string specified by the \fIstring\fP +argument to see if it matches the pattern specified by the \fIpattern\fP +argument. +.LP +The \fIflags\fP argument shall modify the interpretation of \fIpattern\fP +and \fIstring\fP. It is the bitwise-inclusive OR of +zero or more of the flags defined in \fI\fP. If the FNM_PATHNAME +flag is +set in \fIflags\fP, then a slash character ( \fB'/'\fP ) in \fIstring\fP +shall be explicitly matched by a slash in +\fIpattern\fP; it shall not be matched by either the asterisk or question-mark +special characters, nor by a bracket expression. If +the FNM_PATHNAME flag is not set, the slash character shall be treated +as an ordinary character. +.LP +If FNM_NOESCAPE is not set in \fIflags\fP, a backslash character ( +\fB'\\'\fP ) in \fIpattern\fP followed by any other +character shall match that second character in \fIstring\fP. In particular, +\fB"\\\\"\fP shall match a backslash in +\fIstring\fP. If FNM_NOESCAPE is set, a backslash character shall +be treated as an ordinary character. +.LP +If FNM_PERIOD is set in \fIflags\fP, then a leading period ( \fB'.'\fP +) in \fIstring\fP shall match a period in +\fIpattern\fP; as described by rule 2 in the Shell and Utilities volume +of IEEE\ Std\ 1003.1-2001, Section 2.13.3, Patterns Used for Filename +Expansion where the location of +"leading" is indicated by the value of FNM_PATHNAME: +.IP " *" 3 +If FNM_PATHNAME is set, a period is "leading" if it is the first character +in \fIstring\fP or if it immediately follows a +slash. +.LP +.IP " *" 3 +If FNM_PATHNAME is not set, a period is "leading" only if it is the +first character of \fIstring\fP. +.LP +.LP +If FNM_PERIOD is not set, then no special restrictions are placed +on matching a period. +.SH RETURN VALUE +.LP +If \fIstring\fP matches the pattern specified by \fIpattern\fP, then +\fIfnmatch\fP() shall return 0. If there is no match, +\fIfnmatch\fP() shall return FNM_NOMATCH, which is defined in \fI\fP. +If an error occurs, \fIfnmatch\fP() shall return another non-zero +value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIfnmatch\fP() function has two major uses. It could be used +by an application or utility that needs to read a directory +and apply a pattern against each entry. The \fIfind\fP utility is +an example of this. It can +also be used by the \fIpax\fP utility to process its \fIpattern\fP +operands, or by +applications that need to match strings in a similar manner. +.LP +The name \fIfnmatch\fP() is intended to imply \fIfilename\fP match, +rather than \fIpathname\fP match. The default action of +this function is to match filenames, rather than pathnames, since +it gives no special significance to the slash character. With the +FNM_PATHNAME flag, \fIfnmatch\fP() does match pathnames, but without +tilde expansion, parameter expansion, or special treatment +for a period at the beginning of a filename. +.SH RATIONALE +.LP +This function replaced the REG_FILENAME flag of \fIregcomp\fP() in +early proposals of +this volume of IEEE\ Std\ 1003.1-2001. It provides virtually the same +functionality as the \fIregcomp\fP() and \fIregexec\fP() functions +using the +REG_FILENAME and REG_FSLASH flags (the REG_FSLASH flag was proposed +for \fIregcomp\fP(), +and would have had the opposite effect from FNM_PATHNAME), but with +a simpler function and less system overhead. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIglob\fP() , \fIwordexp\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, the Shell and Utilities +volume +of IEEE\ Std\ 1003.1-2001 +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fopen.3p b/man3p/fopen.3p new file mode 100644 index 000000000..18292c29e --- /dev/null +++ b/man3p/fopen.3p @@ -0,0 +1,236 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FOPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fopen +.SH NAME +fopen \- open a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +FILE *fopen(const char *restrict\fP \fIfilename\fP\fB, const char +*restrict\fP \fImode\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfopen\fP() function shall open the file whose pathname is the +string pointed to by \fIfilename\fP, and associates a +stream with it. +.LP +The \fImode\fP argument points to a string. If the string is one of +the following, the file shall be opened in the indicated +mode. Otherwise, the behavior is undefined. +.TP 7 +\fIr\fP\ or\ \fIrb\fP +Open file for reading. +.TP 7 +\fIw\fP\ or\ \fIwb\fP +Truncate to zero length or create file for writing. +.TP 7 +\fIa\fP\ or\ \fIab\fP +Append; open or create file for writing at end-of-file. +.TP 7 +\fIr+\fP\ or\ \fIrb+\fP\ or\ \fIr+b\fP +Open file for update (reading and writing). +.TP 7 +\fIw+\fP\ or\ \fIwb+\fP\ or\ \fIw+b\fP +Truncate to zero length or create file for update. +.TP 7 +\fIa+\fP\ or\ \fIab+\fP\ or\ \fIa+b\fP +Append; open or create file for update, writing at end-of-file. +.sp +.LP +The +character \fB'b'\fP shall have no effect, but is allowed for ISO\ C +standard conformance. Opening a file with read mode (\fIr\fP as the +first character in the \fImode\fP argument) shall +fail if the file does not exist or cannot be read. +.LP +Opening a file with append mode (\fIa\fP as the first character in +the \fImode\fP argument) shall cause all subsequent writes +to the file to be forced to the then current end-of-file, regardless +of intervening calls to \fIfseek\fP(). +.LP +When a file is opened with update mode ( \fB'+'\fP as the second or +third character in the \fImode\fP argument), both input +and output may be performed on the associated stream. However, the +application shall ensure that output is not directly followed by +input without an intervening call to \fIfflush\fP() or to a file positioning +function ( \fIfseek\fP(), \fIfsetpos\fP(), or \fIrewind\fP()), and +input is not directly followed by output without an intervening call +to a file +positioning function, unless the input operation encounters end-of-file. +.LP +When opened, a stream is fully buffered if and only if it can be determined +not to refer to an interactive device. The error and +end-of-file indicators for the stream shall be cleared. +.LP +If +\fImode\fP is \fIw\fP, \fIwb\fP, \fIa\fP, \fIab\fP, \fIw\fP+, \fIwb\fP+, +\fIw\fP+\fIb\fP, \fIa\fP+, \fIab\fP+, or +\fIa\fP+\fIb\fP, and the file did not previously exist, upon successful +completion, the \fIfopen\fP() function shall mark for +update the \fIst_atime\fP, \fIst_ctime\fP, and \fIst_mtime\fP fields +of the file and the \fIst_ctime\fP and \fIst_mtime\fP +fields of the parent directory. +.LP +If \fImode\fP is \fIw\fP, \fIwb\fP, \fIw\fP+, \fIwb\fP+, or \fIw\fP+\fIb\fP, +and the file did previously exist, upon +successful completion, \fIfopen\fP() shall mark for update the \fIst_ctime\fP +and \fIst_mtime\fP fields of the file. The +\fIfopen\fP() function shall allocate a file descriptor as \fIopen\fP() +does. +.LP +After a successful call to the \fIfopen\fP() function, the orientation +of the stream shall be cleared, \ the encoding +rule shall be cleared, and the associated \fBmbstate_t\fP object +shall be set to describe an initial conversion state. +.LP +The +largest value that can be represented correctly in an object of type +\fBoff_t\fP shall be established as the offset maximum in the +open file description. +.SH RETURN VALUE +.LP +Upon successful completion, \fIfopen\fP() shall return a pointer to +the object controlling the stream. Otherwise, a null +pointer shall be returned, \ and \fIerrno\fP shall be set to indicate +the error. +.SH ERRORS +.LP +The \fIfopen\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied on a component of the path prefix, or +the file exists and the permissions specified by \fImode\fP are +denied, or the file does not exist and write permission is denied +for the parent directory of the file to be created. +.TP 7 +.B EINTR +A +signal was caught during \fIfopen\fP(). +.TP 7 +.B EISDIR +The named file is a directory and \fImode\fP requires write access. +.TP 7 +.B ELOOP +A +loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENAMETOOLONG +.sp +The length of the \fIfilename\fP argument exceeds {PATH_MAX} or a +pathname component is longer than {NAME_MAX}. +.TP 7 +.B ENFILE +The maximum allowable number of files is currently open in the system. +.TP 7 +.B ENOENT +A +component of \fIfilename\fP does not name an existing file or \fIfilename\fP +is an empty string. +.TP 7 +.B ENOSPC +The directory or file system that would contain the new file cannot +be expanded, the file does not exist, and the file was to be +created. +.TP 7 +.B ENOTDIR +A +component of the path prefix is not a directory. +.TP 7 +.B ENXIO +The named file is a character special or block special file, and the +device associated with this special file does not exist. +.TP 7 +.B EOVERFLOW +The named file is a regular file and the size of the file cannot be +represented correctly in an object of type \fBoff_t\fP. +.TP 7 +.B EROFS +The named file resides on a read-only file system and \fImode\fP requires +write access. +.sp +.LP +The \fIfopen\fP() function may fail if: +.TP 7 +.B EINVAL +The value of the \fImode\fP argument is not valid. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B EMFILE +{FOPEN_MAX} streams are currently open in the calling process. +.TP 7 +.B EMFILE +{STREAM_MAX} streams are currently open in the calling process. +.TP 7 +.B ENAMETOOLONG +.sp +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.TP 7 +.B ETXTBSY +The file is a pure procedure (shared text) file that is being executed +and \fImode\fP requires write access. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Opening a File +.LP +The following example tries to open the file named \fBfile\fP for +reading. The \fIfopen\fP() function returns a file pointer +that is used in subsequent \fIfgets\fP() and \fIfclose\fP() calls. +If the program cannot open the file, it just ignores it. +.sp +.RS +.nf + +\fB#include +\&... +FILE *fp; +\&... +void rgrep(const char *file) +{ +\&... + if ((fp = fopen(file, "r")) == NULL) + return; +\&... +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfclose\fP() , \fIfdopen\fP() , \fIfreopen\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fork.3p b/man3p/fork.3p new file mode 100644 index 000000000..08ebd4dfa --- /dev/null +++ b/man3p/fork.3p @@ -0,0 +1,358 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FORK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fork +.SH NAME +fork \- create a new process +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +pid_t fork(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfork\fP() function shall create a new process. The new process +(child process) shall be an exact copy of the calling +process (parent process) except as detailed below: +.IP " *" 3 +The child process shall have a unique process ID. +.LP +.IP " *" 3 +The child process ID also shall not match any active process group +ID. +.LP +.IP " *" 3 +The child process shall have a different parent process ID, which +shall be the process ID of the calling process. +.LP +.IP " *" 3 +The child process shall have its own copy of the parent's file descriptors. +Each of the child's file descriptors shall refer to +the same open file description with the corresponding file descriptor +of the parent. +.LP +.IP " *" 3 +The child process shall have its own copy of the parent's open directory +streams. Each open directory stream in the child +process may share directory stream positioning with the corresponding +directory stream of the parent. +.LP +.IP " *" 3 +The child process shall have its own copy of the parent's message +catalog descriptors. +.LP +.IP " *" 3 +The child process' values of \fItms_utime\fP, \fItms_stime\fP, \fItms_cutime\fP, +and \fItms_cstime\fP shall be set to 0. +.LP +.IP " *" 3 +The time left until an alarm clock signal shall be reset to zero, +and the alarm, if any, shall be canceled; see \fIalarm\fP() . +.LP +.IP " *" 3 +All \fIsemadj\fP values shall be cleared. +.LP +.IP " *" 3 +File locks set by the parent process shall not be inherited by the +child process. +.LP +.IP " *" 3 +The set of signals pending for the child process shall be initialized +to the empty set. +.LP +.IP " *" 3 +Interval timers shall be reset in the child process. +.LP +.IP " *" 3 +Any semaphores that are open in the parent process shall also be open +in the child process. +.LP +.IP " *" 3 +The +child process shall not inherit any address space memory locks established +by the parent process via calls to \fImlockall\fP() or \fImlock\fP(). +.LP +.IP " *" 3 +Memory mappings created in the parent shall be retained in the child +process. MAP_PRIVATE mappings inherited from the parent shall +also be MAP_PRIVATE mappings in the child, and any modifications to +the data in these mappings made by the parent prior to calling +\fIfork\fP() shall be visible to the child. Any modifications to the +data in MAP_PRIVATE mappings made by the parent after +\fIfork\fP() returns shall be visible only to the parent. Modifications +to the data in MAP_PRIVATE mappings made by the child +shall be visible only to the child. +.LP +.IP " *" 3 +For +the SCHED_FIFO and SCHED_RR scheduling policies, the child process +shall inherit the policy and priority settings of the parent +process during a \fIfork\fP() function. For other scheduling policies, +the policy and priority settings on \fIfork\fP() are +implementation-defined. +.LP +.IP " *" 3 +Per-process timers created by the parent shall not be inherited by +the child process. +.LP +.IP " *" 3 +The child process shall have its own copy of the message queue descriptors +of the parent. Each of the message descriptors of the +child shall refer to the same open message queue description as the +corresponding message descriptor of the parent. +.LP +.IP " *" 3 +No asynchronous input or asynchronous output operations shall be inherited +by the child process. +.LP +.IP " *" 3 +A process shall be created with a single thread. If a multi-threaded +process calls \fIfork\fP(), the new process shall contain +a replica of the calling thread and its entire address space, possibly +including the states of mutexes and other resources. +Consequently, to avoid errors, the child process may only execute +async-signal-safe operations until such time as one of the \fIexec\fP +functions is called. \ Fork handlers may be established by means +of the \fIpthread_atfork\fP() function in order to maintain application +invariants across +\fIfork\fP() calls. +.LP +When the application calls \fIfork\fP() from a signal handler and +any of the fork handlers registered by \fIpthread_atfork\fP() calls +a function that is not asynch-signal-safe, the behavior is +undefined. +.LP +.IP " *" 3 +If the Trace option and the Trace Inherit option are both supported: +.LP +If the calling process was being traced in a trace stream that had +its inheritance policy set to POSIX_TRACE_INHERITED, the +child process shall be traced into that trace stream, and the child +process shall inherit the parent's mapping of trace event names +to trace event type identifiers. If the trace stream in which the +calling process was being traced had its inheritance policy set +to POSIX_TRACE_CLOSE_FOR_CHILD, the child process shall not be traced +into that trace stream. The inheritance policy is set by a +call to the \fIposix_trace_attr_setinherited\fP() function. +.LP +.IP " *" 3 +If the Trace option is supported, but the Trace Inherit option is +not supported: +.LP +The child process shall not be traced into any of the trace streams +of its parent process. +.LP +.IP " *" 3 +If the Trace option is supported, the child process of a trace controller +process shall not control the trace streams controlled by +its parent process. +.LP +.IP " *" 3 +The initial value of the CPU-time clock of the child process shall +be set to zero. +.LP +.IP " *" 3 +The initial value of the CPU-time clock of the single thread of the +child process shall be set to zero. +.LP +.LP +All other process characteristics defined by IEEE\ Std\ 1003.1-2001 +shall be the same in the parent and child processes. +The inheritance of process characteristics not defined by IEEE\ Std\ 1003.1-2001 +is unspecified by +IEEE\ Std\ 1003.1-2001. +.LP +After \fIfork\fP(), both the parent and the child processes shall +be capable of executing independently before either one +terminates. +.SH RETURN VALUE +.LP +Upon successful completion, \fIfork\fP() shall return 0 to the child +process and shall return the process ID of the child +process to the parent process. Both processes shall continue to execute +from the \fIfork\fP() function. Otherwise, -1 shall be +returned to the parent process, no child process shall be created, +and \fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +The \fIfork\fP() function shall fail if: +.TP 7 +.B EAGAIN +The system lacked the necessary resources to create another process, +or the system-imposed limit on the total number of +processes under execution system-wide or by a single user {CHILD_MAX} +would be exceeded. +.sp +.LP +The \fIfork\fP() function may fail if: +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Many historical implementations have timing windows where a signal +sent to a process group (for example, an interactive SIGINT) +just prior to or during execution of \fIfork\fP() is delivered to +the parent following the \fIfork\fP() but not to the child +because the \fIfork\fP() code clears the child's set of pending signals. +This volume of IEEE\ Std\ 1003.1-2001 does not +require, or even permit, this behavior. However, it is pragmatic to +expect that problems of this nature may continue to exist in +implementations that appear to conform to this volume of IEEE\ Std\ 1003.1-2001 +and pass available verification suites. +This behavior is only a consequence of the implementation failing +to make the interval between signal generation and delivery +totally invisible. From the application's perspective, a \fIfork\fP() +call should appear atomic. A signal that is generated prior +to the \fIfork\fP() should be delivered prior to the \fIfork\fP(). +A signal sent to the process group after the \fIfork\fP() +should be delivered to both parent and child. The implementation may +actually initialize internal data structures corresponding to +the child's set of pending signals to include signals sent to the +process group during the \fIfork\fP(). Since the \fIfork\fP() +call can be considered as atomic from the application's perspective, +the set would be initialized as empty and such signals would +have arrived after the \fIfork\fP(); see also \fI\fP. +.LP +One approach that has been suggested to address the problem of signal +inheritance across \fIfork\fP() is to add an [EINTR] +error, which would be returned when a signal is detected during the +call. While this is preferable to losing signals, it was not +considered an optimal solution. Although it is not recommended for +this purpose, such an error would be an allowable extension for +an implementation. +.LP +The [ENOMEM] error value is reserved for those implementations that +detect and distinguish such a condition. This condition +occurs when an implementation detects that there is not enough memory +to create the process. This is intended to be returned when +[EAGAIN] is inappropriate because there can never be enough memory +(either primary or secondary storage) to perform the operation. +Since \fIfork\fP() duplicates an existing process, this must be a +condition where there is sufficient memory for one such process, +but not for two. Many historical implementations actually return [ENOMEM] +due to temporary lack of memory, a case that is not +generally distinct from [EAGAIN] from the perspective of a conforming +application. +.LP +Part of the reason for including the optional error [ENOMEM] is because +the SVID specifies it and it should be reserved for the +error condition specified there. The condition is not applicable on +many implementations. +.LP +IEEE\ Std\ 1003.1-1988 neglected to require concurrent execution of +the parent and child of \fIfork\fP(). A system that +single-threads processes was clearly not intended and is considered +an unacceptable "toy implementation" of this volume of +IEEE\ Std\ 1003.1-2001. The only objection anticipated to the phrase +"executing independently" is testability, but this +assertion should be testable. Such tests require that both the parent +and child can block on a detectable action of the other, such +as a write to a pipe or a signal. An interactive exchange of such +actions should be possible for the system to conform to the +intent of this volume of IEEE\ Std\ 1003.1-2001. +.LP +The [EAGAIN] error exists to warn applications that such a condition +might occur. Whether it occurs or not is not in any +practical sense under the control of the application because the condition +is usually a consequence of the user's use of the +system, not of the application's code. Thus, no application can or +should rely upon its occurrence under any circumstances, nor +should the exact semantics of what concept of "user" is used be of +concern to the application writer. Validation writers should +be cognizant of this limitation. +.LP +There are two reasons why POSIX programmers call \fIfork\fP(). One +reason is to create a new thread of control within the same +program (which was originally only possible in POSIX by creating a +new process); the other is to create a new process running a +different program. In the latter case, the call to \fIfork\fP() is +soon followed by a call to one of the \fIexec\fP functions. +.LP +The general problem with making \fIfork\fP() work in a multi-threaded +world is what to do with all of the threads. There are +two alternatives. One is to copy all of the threads into the new process. +This causes the programmer or implementation to deal with +threads that are suspended on system calls or that might be about +to execute system calls that should not be executed in the new +process. The other alternative is to copy only the thread that calls +\fIfork\fP(). This creates the difficulty that the state of +process-local resources is usually held in process memory. If a thread +that is not calling \fIfork\fP() holds a resource, that +resource is never released in the child process because the thread +whose job it is to release the resource does not exist in the +child process. +.LP +When a programmer is writing a multi-threaded program, the first described +use of \fIfork\fP(), creating new threads in the +same program, is provided by the \fIpthread_create\fP() function. +The \fIfork\fP() +function is thus used only to run new programs, and the effects of +calling functions that require certain resources between the +call to \fIfork\fP() and the call to an \fIexec\fP function are undefined. +.LP +The addition of the \fIforkall\fP() function to the standard was considered +and rejected. The \fIforkall\fP() function lets +all the threads in the parent be duplicated in the child. This essentially +duplicates the state of the parent in the child. This +allows threads in the child to continue processing and allows locks +and the state to be preserved without explicit \fIpthread_atfork\fP() +code. The calling process has to ensure that the threads processing +state that is shared between the parent and child (that is, file descriptors +or MAP_SHARED memory) behaves properly after +\fIforkall\fP(). For example, if a thread is reading a file descriptor +in the parent when \fIforkall\fP() is called, then two +threads (one in the parent and one in the child) are reading the file +descriptor after the \fIforkall\fP(). If this is not desired +behavior, the parent process has to synchronize with such threads +before calling \fIforkall\fP(). +.LP +While the \fIfork\fP() function is async-signal-safe, there is no +way for an implementation to determine whether the fork +handlers established by \fIpthread_atfork\fP() are async-signal-safe. +The fork +handlers may attempt to execute portions of the implementation that +are not async-signal-safe, such as those that are protected by +mutexes, leading to a deadlock condition. It is therefore undefined +for the fork handlers to execute functions that are not +async-signal-safe when \fIfork\fP() is called from a signal handler. +.LP +When \fIforkall\fP() is called, threads, other than the calling thread, +that are in functions that can return with an [EINTR] +error may have those functions return [EINTR] if the implementation +cannot ensure that the function behaves correctly in the parent +and child. In particular, \fIpthread_cond_wait\fP() and \fIpthread_cond_timedwait\fP() +need to return in order to ensure that the condition +has not changed. These functions can be awakened by a spurious condition +wakeup rather than returning [EINTR]. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIalarm\fP() , \fIexec\fP() , \fIfcntl\fP() , \fIposix_trace_attr_getinherited\fP() +, \fIposix_trace_trid_eventid_open\fP() , \fIpthread_atfork\fP() , +\fIsemop\fP() , \fIsignal\fP() , \fItimes\fP() , the Base Definitions +volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fpathconf.3p b/man3p/fpathconf.3p new file mode 100644 index 000000000..7b08350aa --- /dev/null +++ b/man3p/fpathconf.3p @@ -0,0 +1 @@ +.so man3p/pathconf.3p diff --git a/man3p/fpclassify.3p b/man3p/fpclassify.3p new file mode 100644 index 000000000..77f1863a9 --- /dev/null +++ b/man3p/fpclassify.3p @@ -0,0 +1,57 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FPCLASSIFY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fpclassify +.SH NAME +fpclassify \- classify real floating type +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fpclassify(real-floating\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfpclassify\fP() macro shall classify its argument value as +NaN, infinite, normal, subnormal, zero, or into another +implementation-defined category. First, an argument represented in +a format wider than its semantic type is converted to its +semantic type. Then classification is based on the type of the argument. +.SH RETURN VALUE +.LP +The \fIfpclassify\fP() macro shall return the value of the number +classification macro appropriate to the value of its +argument. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisfinite\fP() , \fIisinf\fP() , \fIisnan\fP() , \fIisnormal\fP() +, \fIsignbit\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fprintf.3p b/man3p/fprintf.3p new file mode 100644 index 000000000..b1ca7350d --- /dev/null +++ b/man3p/fprintf.3p @@ -0,0 +1 @@ +.so man3p/printf.3p diff --git a/man3p/fputc.3p b/man3p/fputc.3p new file mode 100644 index 000000000..87fe5c16f --- /dev/null +++ b/man3p/fputc.3p @@ -0,0 +1,126 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FPUTC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fputc +.SH NAME +fputc \- put a byte on a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fputc(int\fP \fIc\fP\fB, FILE *\fP\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfputc\fP() function shall write the byte specified by \fIc\fP +(converted to an \fBunsigned char\fP) to the output +stream pointed to by \fIstream\fP, at the position indicated by the +associated file-position indicator for the stream (if +defined), and shall advance the indicator appropriately. If the file +cannot support positioning requests, or if the stream was +opened with append mode, the byte shall be appended to the output +stream. +.LP +The +\fIst_ctime\fP and \fIst_mtime\fP fields of the file shall be marked +for update between the successful execution of +\fIfputc\fP() and the next successful completion of a call to \fIfflush\fP() +or \fIfclose\fP() on the same stream or a call to \fIexit\fP() +or \fIabort\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, \fIfputc\fP() shall return the value it +has written. Otherwise, it shall return EOF, the error +indicator for the stream shall be set, \ and \fIerrno\fP shall be +set to indicate the error. +.SH ERRORS +.LP +The \fIfputc\fP() function shall fail if either the \fIstream\fP is +unbuffered or the \fIstream\fP's buffer needs to be +flushed, and: +.TP 7 +.B EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying \fIstream\fP +and the process would be delayed in the write +operation. +.TP 7 +.B EBADF +The file descriptor underlying \fIstream\fP is not a valid file descriptor +open for writing. +.TP 7 +.B EFBIG +An +attempt was made to write to a file that exceeds the maximum file +size. +.TP 7 +.B EFBIG +An attempt was made to write to a file that exceeds the process' file +size limit. +.TP 7 +.B EFBIG +The file is a regular file and an attempt was made to write at or +beyond the offset maximum. +.TP 7 +.B EINTR +The write operation was terminated due to the receipt of a signal, +and no data was transferred. +.TP 7 +.B EIO +A +physical I/O error has occurred, or the process is a member of a background +process group attempting to write to its controlling +terminal, TOSTOP is set, the process is neither ignoring nor blocking +SIGTTOU, and the process group of the process is orphaned. +This error may also be returned under implementation-defined conditions. +.TP 7 +.B ENOSPC +There was no free space remaining on the device containing the file. +.TP 7 +.B EPIPE +An +attempt is made to write to a pipe or FIFO that is not open for reading +by any process. A SIGPIPE signal shall also be sent to the +thread. +.sp +.LP +The \fIfputc\fP() function may fail if: +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.TP 7 +.B ENXIO +A +request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIferror\fP() , \fIfopen\fP() , \fIgetrlimit\fP() , \fIputc\fP() +, \fIputs\fP() , \fIsetbuf\fP() , \fIulimit\fP() , the Base Definitions +volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fputs.3p b/man3p/fputs.3p new file mode 100644 index 000000000..e289cb8eb --- /dev/null +++ b/man3p/fputs.3p @@ -0,0 +1,86 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FPUTS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fputs +.SH NAME +fputs \- put a string on a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fputs(const char *restrict\fP \fIs\fP\fB, FILE *restrict\fP \fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfputs\fP() function shall write the null-terminated string +pointed to by \fIs\fP to the stream pointed to by +\fIstream\fP. The terminating null byte shall not be written. +.LP +The +\fIst_ctime\fP and \fIst_mtime\fP fields of the file shall be marked +for update between the successful execution of +\fIfputs\fP() and the next successful completion of a call to \fIfflush\fP() +or \fIfclose\fP() on the same stream or a call to \fIexit\fP() +or \fIabort\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, \fIfputs\fP() shall return a non-negative +number. Otherwise, it shall return EOF, set an error +indicator for the stream, \ and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +Refer to \fIfputc\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Printing to Standard Output +.LP +The following example gets the current time, converts it to a string +using \fIlocaltime\fP() and \fIasctime\fP(), and prints it to +standard output using \fIfputs\fP(). It then prints the number of +minutes to an event for which it is waiting. +.sp +.RS +.nf + +\fB#include +#include +\&... +time_t now; +int minutes_to_event; +\&... +time(&now); +printf("The time is "); +fputs(asctime(localtime(&now)), stdout); +printf("There are still %d minutes to the event.\\n", + minutes_to_event); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIputs\fP() function appends a while \fIfputs\fP() +does not. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfopen\fP() , \fIputc\fP() , \fIputs\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fputwc.3p b/man3p/fputwc.3p new file mode 100644 index 000000000..0626e9db8 --- /dev/null +++ b/man3p/fputwc.3p @@ -0,0 +1,128 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FPUTWC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fputwc +.SH NAME +fputwc \- put a wide-character code on a stream +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +wint_t fputwc(wchar_t\fP \fIwc\fP\fB, FILE *\fP\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfputwc\fP() function shall write the character corresponding +to the wide-character code \fIwc\fP to the output stream +pointed to by \fIstream\fP, at the position indicated by the associated +file-position indicator for the stream (if defined), and +advances the indicator appropriately. If the file cannot support positioning +requests, or if the stream was opened with append +mode, the character is appended to the output stream. If an error +occurs while writing the character, the shift state of the output +file is left in an undefined state. +.LP +The +\fIst_ctime\fP and \fIst_mtime\fP fields of the file shall be marked +for update between the successful execution of +\fIfputwc\fP() and the next successful completion of a call to \fIfflush\fP() +or \fIfclose\fP() on the same stream or a call to \fIexit\fP() +or \fIabort\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, \fIfputwc\fP() shall return \fIwc\fP. +Otherwise, it shall return WEOF, the error indicator for the +stream shall be set, \ and \fIerrno\fP shall be set to indicate +the error. +.SH ERRORS +.LP +The \fIfputwc\fP() function shall fail if either the stream is unbuffered +or data in the \fIstream\fP's buffer needs to be +written, and: +.TP 7 +.B EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying \fIstream\fP +and the process would be delayed in the write +operation. +.TP 7 +.B EBADF +The file descriptor underlying \fIstream\fP is not a valid file descriptor +open for writing. +.TP 7 +.B EFBIG +An +attempt was made to write to a file that exceeds the maximum file +size or the process' file size limit. +.TP 7 +.B EFBIG +The file is a regular file and an attempt was made to write at or +beyond the offset maximum associated with the corresponding +stream. +.TP 7 +.B EILSEQ +The wide-character code \fIwc\fP does not correspond to a valid character. +.TP 7 +.B EINTR +The write operation was terminated due to the receipt of a signal, +and no data was transferred. +.TP 7 +.B EIO +A +physical I/O error has occurred, or the process is a member of a background +process group attempting to write to its controlling +terminal, TOSTOP is set, the process is neither ignoring nor blocking +SIGTTOU, and the process group of the process is orphaned. +This error may also be returned under implementation-defined conditions. +.TP 7 +.B ENOSPC +There was no free space remaining on the device containing the file. +.TP 7 +.B EPIPE +An +attempt is made to write to a pipe or FIFO that is not open for reading +by any process. A SIGPIPE signal shall also be sent to the +thread. +.sp +.LP +The \fIfputwc\fP() function may fail if: +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.TP 7 +.B ENXIO +A +request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIferror\fP() , \fIfopen\fP() , \fIsetbuf\fP() +, \fIulimit\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fputws.3p b/man3p/fputws.3p new file mode 100644 index 000000000..c79e87915 --- /dev/null +++ b/man3p/fputws.3p @@ -0,0 +1,67 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FPUTWS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fputws +.SH NAME +fputws \- put a wide-character string on a stream +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int fputws(const wchar_t *restrict\fP \fIws\fP\fB, FILE *restrict\fP +\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfputws\fP() function shall write a character string corresponding +to the (null-terminated) wide-character string pointed +to by \fIws\fP to the stream pointed to by \fIstream\fP. No character +corresponding to the terminating null wide-character code +shall be written. +.LP +The +\fIst_ctime\fP and \fIst_mtime\fP fields of the file shall be marked +for update between the successful execution of +\fIfputws\fP() and the next successful completion of a call to \fIfflush\fP() +or \fIfclose\fP() on the same stream or a call to \fIexit\fP() +or \fIabort\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, \fIfputws\fP() shall return a non-negative +number. Otherwise, it shall return -1, set an error +indicator for the stream, \ and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +Refer to \fIfputwc\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIfputws\fP() function does not append a . +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfopen\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fread.3p b/man3p/fread.3p new file mode 100644 index 000000000..4fd20b579 --- /dev/null +++ b/man3p/fread.3p @@ -0,0 +1,104 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FREAD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fread +.SH NAME +fread \- binary input +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t fread(void *restrict\fP \fIptr\fP\fB, size_t\fP \fIsize\fP\fB, +size_t\fP \fInitems\fP\fB, +.br +\ \ \ \ \ \ FILE *restrict\fP \fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfread\fP() function shall read into the array pointed to by +\fIptr\fP up to \fInitems\fP elements whose size is +specified by \fIsize\fP in bytes, from the stream pointed to by \fIstream\fP. +For each object, \fIsize\fP calls shall be made to +the \fIfgetc\fP() function and the results stored, in the order read, +in an array of +\fBunsigned char\fP exactly overlaying the object. The file position +indicator for the stream (if defined) shall be advanced by +the number of bytes successfully read. If an error occurs, the resulting +value of the file position indicator for the stream is +unspecified. If a partial element is read, its value is unspecified. +.LP +The +\fIfread\fP() function may mark the \fIst_atime\fP field of the file +associated with \fIstream\fP for update. The +\fIst_atime\fP field shall be marked for update by the first successful +execution of \fIfgetc\fP(), \fIfgets\fP(), \fIfgetwc\fP(), \fIfgetws\fP(), +\fIfread\fP(), \fIfscanf\fP(), \fIgetc\fP(), \fIgetchar\fP(), \fIgets\fP(), +or \fIscanf\fP() using \fIstream\fP that returns data not supplied +by a prior call to \fIungetc\fP() or \fIungetwc\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, \fIfread\fP() shall return the number +of elements successfully read which is less than +\fInitems\fP only if a read error or end-of-file is encountered. If +\fIsize\fP or \fInitems\fP is 0, \fIfread\fP() shall return +0 and the contents of the array and the state of the stream remain +unchanged. Otherwise, if a read error occurs, the error +indicator for the stream shall be set, \ and \fIerrno\fP shall be +set to indicate the error. +.SH ERRORS +.LP +Refer to \fIfgetc\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Reading from a Stream +.LP +The following example reads a single element from the \fIfp\fP stream +into the array pointed to by \fIbuf\fP. +.sp +.RS +.nf + +\fB#include +\&... +size_t bytes_read; +char buf[100]; +FILE *fp; +\&... +bytes_read = fread(buf, sizeof(buf), 1, fp); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIferror\fP() or \fIfeof\fP() functions must +be used to distinguish between an error condition and an end-of-file +condition. +.LP +Because of possible differences in element length and byte ordering, +files written using \fIfwrite\fP() are application-dependent, and +possibly cannot be read using \fIfread\fP() by a +different application or by the same application on a different processor. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeof\fP() , \fIferror\fP() , \fIfgetc\fP() , \fIfopen\fP() , \fIgetc\fP() +, \fIgets\fP() , \fIscanf\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/free.3p b/man3p/free.3p new file mode 100644 index 000000000..cbd5e8506 --- /dev/null +++ b/man3p/free.3p @@ -0,0 +1,61 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FREE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" free +.SH NAME +free \- free allocated memory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void free(void *\fP\fIptr\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfree\fP() function shall cause the space pointed to by \fIptr\fP +to be deallocated; that is, made available for further +allocation. If \fIptr\fP is a null pointer, no action shall occur. +Otherwise, if the argument does not match a pointer earlier +returned by the \fIcalloc\fP(), \fImalloc\fP(), +\fIposix_memalign\fP(), \fIrealloc\fP(), or \fIstrdup\fP() function, +or if the space has been deallocated by a call to \fIfree\fP() or +\fIrealloc\fP(), the behavior is undefined. +.LP +Any use of a pointer that refers to freed space results in undefined +behavior. +.SH RETURN VALUE +.LP +The \fIfree\fP() function shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +There is now no requirement for the implementation to support the +inclusion of \fI\fP. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcalloc\fP() , \fImalloc\fP() , \fIrealloc\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/freeaddrinfo.3p b/man3p/freeaddrinfo.3p new file mode 100644 index 000000000..055f9ec48 --- /dev/null +++ b/man3p/freeaddrinfo.3p @@ -0,0 +1 @@ +.so man3p/getaddrinfo.3p diff --git a/man3p/freopen.3p b/man3p/freopen.3p new file mode 100644 index 000000000..a8c22606c --- /dev/null +++ b/man3p/freopen.3p @@ -0,0 +1,184 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FREOPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" freopen +.SH NAME +freopen \- open a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +FILE *freopen(const char *restrict\fP \fIfilename\fP\fB, const char +*restrict\fP \fImode\fP\fB, +.br +\ \ \ \ \ \ FILE *restrict\fP \fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfreopen\fP() function shall first attempt to flush the stream +and close any file descriptor associated with +\fIstream\fP. Failure to flush or close the file descriptor successfully +shall be ignored. The error and end-of-file indicators +for the stream shall be cleared. +.LP +The \fIfreopen\fP() function shall open the file whose pathname is +the string pointed to by \fIfilename\fP and associate the +stream pointed to by \fIstream\fP with it. The \fImode\fP argument +shall be used just as in \fIfopen\fP(). +.LP +The original stream shall be closed regardless of whether the subsequent +open succeeds. +.LP +If \fIfilename\fP is a null pointer, the \fIfreopen\fP() function +shall attempt to change the mode of the stream to that +specified by \fImode\fP, as if the name of the file currently associated +with the stream had been used. It is +implementation-defined which changes of mode are permitted (if any), +and under what circumstances. +.LP +After a successful call to the \fIfreopen\fP() function, the orientation +of the stream shall be cleared, \ the encoding +rule shall be cleared, and the associated \fBmbstate_t\fP object +shall be set to describe an initial conversion state. +.LP +The +largest value that can be represented correctly in an object of type +\fBoff_t\fP shall be established as the offset maximum in the +open file description. +.SH RETURN VALUE +.LP +Upon successful completion, \fIfreopen\fP() shall return the value +of \fIstream\fP. Otherwise, a null pointer shall be +returned, \ and \fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +The \fIfreopen\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied on a component of the path prefix, or +the file exists and the permissions specified by \fImode\fP are +denied, or the file does not exist and write permission is denied +for the parent directory of the file to be created. +.TP 7 +.B EINTR +A +signal was caught during \fIfreopen\fP(). +.TP 7 +.B EISDIR +The named file is a directory and \fImode\fP requires write access. +.TP 7 +.B ELOOP +A +loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENAMETOOLONG +.sp +The length of the \fIfilename\fP argument exceeds {PATH_MAX} or a +pathname component is longer than {NAME_MAX}. +.TP 7 +.B ENFILE +The maximum allowable number of files is currently open in the system. +.TP 7 +.B ENOENT +A +component of \fIfilename\fP does not name an existing file or \fIfilename\fP +is an empty string. +.TP 7 +.B ENOSPC +The directory or file system that would contain the new file cannot +be expanded, the file does not exist, and it was to be created. +.TP 7 +.B ENOTDIR +A +component of the path prefix is not a directory. +.TP 7 +.B ENXIO +The named file is a character special or block special file, and the +device associated with this special file does not exist. +.TP 7 +.B EOVERFLOW +The named file is a regular file and the size of the file cannot be +represented correctly in an object of type \fBoff_t\fP. +.TP 7 +.B EROFS +The named file resides on a read-only file system and \fImode\fP requires +write access. +.sp +.LP +The \fIfreopen\fP() function may fail if: +.TP 7 +.B EINVAL +The value of the \fImode\fP argument is not valid. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +.sp +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.TP 7 +.B ENXIO +A +request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.TP 7 +.B ETXTBSY +The file is a pure procedure (shared text) file that is being executed +and \fImode\fP requires write access. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Directing Standard Output to a File +.LP +The following example logs all standard output to the \fB/tmp/logfile\fP +file. +.sp +.RS +.nf + +\fB#include +\&... +FILE *fp; +\&... +fp = freopen ("/tmp/logfile", "a+", stdout); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIfreopen\fP() function is typically used to attach the preopened +\fIstreams\fP associated with \fIstdin\fP, +\fIstdout\fP, and \fIstderr\fP to other files. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfclose\fP() , \fIfopen\fP() , \fIfdopen\fP() +, \fImbsinit\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/frexp.3p b/man3p/frexp.3p new file mode 100644 index 000000000..3a57686c5 --- /dev/null +++ b/man3p/frexp.3p @@ -0,0 +1,71 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FREXP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" frexp +.SH NAME +frexp, frexpf, frexpl \- extract mantissa and exponent from a double +precision number +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double frexp(double\fP \fInum\fP\fB, int *\fP\fIexp\fP\fB); +.br +float frexpf(float\fP \fInum\fP\fB, int *\fP\fIexp\fP\fB); +.br +long double frexpl(long double\fP \fInum\fP\fB, int *\fP\fIexp\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall break a floating-point number \fInum\fP into +a normalized fraction and an integral power of 2. The +integer exponent shall be stored in the \fBint\fP object pointed to +by \fIexp\fP. +.SH RETURN VALUE +.LP +For finite arguments, these functions shall return the value \fIx\fP, +such that \fIx\fP has a magnitude in the interval +[0.5,1) or 0, and \fInum\fP equals \fIx\fP times 2 raised to the power +*\fIexp\fP. +.LP +If +\fInum\fP is NaN, a NaN shall be returned, and the value of *\fIexp\fP +is unspecified. +.LP +If \fInum\fP is \(+-0, \(+-0 shall be returned, and the value of *\fIexp\fP +shall be 0. +.LP +If \fInum\fP is \(+-Inf, \fInum\fP shall be returned, and the value +of *\fIexp\fP is unspecified. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisnan\fP() , \fIldexp\fP() , \fImodf\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/frexpf.3p b/man3p/frexpf.3p new file mode 100644 index 000000000..6d976f325 --- /dev/null +++ b/man3p/frexpf.3p @@ -0,0 +1 @@ +.so man3p/frexp.3p diff --git a/man3p/frexpl.3p b/man3p/frexpl.3p new file mode 100644 index 000000000..6d976f325 --- /dev/null +++ b/man3p/frexpl.3p @@ -0,0 +1 @@ +.so man3p/frexp.3p diff --git a/man3p/fscanf.3p b/man3p/fscanf.3p new file mode 100644 index 000000000..0a084c9c9 --- /dev/null +++ b/man3p/fscanf.3p @@ -0,0 +1 @@ +.so man3p/scanf.3p diff --git a/man3p/fseek.3p b/man3p/fseek.3p new file mode 100644 index 000000000..efbdae84b --- /dev/null +++ b/man3p/fseek.3p @@ -0,0 +1,186 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FSEEK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fseek +.SH NAME +fseek, fseeko \- reposition a file-position indicator in a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fseek(FILE *\fP\fIstream\fP\fB, long\fP \fIoffset\fP\fB, int\fP +\fIwhence\fP\fB); +.br +\fP +.LP +\fBint fseeko(FILE *\fP\fIstream\fP\fB, off_t\fP \fIoffset\fP\fB, +int\fP \fIwhence\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIfseek\fP() function shall set the file-position indicator for +the stream pointed to by \fIstream\fP. If a read or write +error occurs, the error indicator for the stream shall be set and +\fIfseek\fP() fails. +.LP +The new position, measured in bytes from the beginning of the file, +shall be obtained by adding \fIoffset\fP to the position +specified by \fIwhence\fP. The specified point is the beginning of +the file for SEEK_SET, the current value of the file-position +indicator for SEEK_CUR, or end-of-file for SEEK_END. +.LP +If the stream is to be used with wide-character input/output functions, +the application shall ensure that \fIoffset\fP is +either 0 or a value returned by an earlier call to \fIftell\fP() on +the same stream and +\fIwhence\fP is SEEK_SET. +.LP +A successful call to \fIfseek\fP() shall clear the end-of-file indicator +for the stream and undo any effects of \fIungetc\fP() and \fIungetwc\fP() +on the same stream. +After an \fIfseek\fP() call, the next operation on an update stream +may be either input or output. +.LP +If +the most recent operation, other than \fIftell\fP(), on a given stream +is \fIfflush\fP(), the file offset in the underlying open file description +shall be adjusted to +reflect the location specified by \fIfseek\fP(). +.LP +The \fIfseek\fP() function shall allow the file-position indicator +to be set beyond the end of existing data in the file. If +data is later written at this point, subsequent reads of data in the +gap shall return bytes with the value 0 until data is actually +written into the gap. +.LP +The behavior of \fIfseek\fP() on devices which are incapable of seeking +is implementation-defined. The value of the file offset +associated with such a device is undefined. +.LP +If the stream is writable and buffered data had not been written to +the underlying file, \fIfseek\fP() shall cause the +unwritten data to be written to the file and shall mark the \fIst_ctime\fP +and \fIst_mtime\fP fields of the file for update. +.LP +In a locale with state-dependent encoding, whether \fIfseek\fP() restores +the stream's shift state is +implementation-defined. +.LP +The \fIfseeko\fP() function shall be equivalent to the \fIfseek\fP() +function except that the \fIoffset\fP argument is of +type \fBoff_t\fP. +.SH RETURN VALUE +.LP +The \fIfseek\fP() \ and \fIfseeko\fP() functions +shall return 0 if they succeed. +.LP +Otherwise, they shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fIfseek\fP() \ and \fIfseeko\fP() +\ functions shall fail if, \ either the \fIstream\fP is unbuffered +or the \fIstream\fP's buffer needed to be flushed, and +the call to \fIfseek\fP() or \fIfseeko\fP() causes an underlying \fIlseek\fP() +or \fIwrite\fP() to be invoked, and: +.TP 7 +.B EAGAIN +The O_NONBLOCK flag is set for the file descriptor and the process +would be delayed in the write operation. +.TP 7 +.B EBADF +The file descriptor underlying the stream file is not open for writing +or the stream's buffer needed to be flushed and the file is +not open. +.TP 7 +.B EFBIG +An +attempt was made to write a file that exceeds the maximum file size. +.TP 7 +.B EFBIG +An attempt was made to write a file that exceeds the process' file +size limit. +.TP 7 +.B EFBIG +The file is a regular file and an attempt was made to write at or +beyond the offset maximum associated with the corresponding +stream. +.TP 7 +.B EINTR +The write operation was terminated due to the receipt of a signal, +and no data was transferred. +.TP 7 +.B EINVAL +The \fIwhence\fP argument is invalid. The resulting file-position +indicator would be set to a negative value. +.TP 7 +.B EIO +A +physical I/O error has occurred, or the process is a member of a background +process group attempting to perform a \fIwrite\fP() to its controlling +terminal, TOSTOP is set, the process is neither ignoring nor +blocking SIGTTOU, and the process group of the process is orphaned. +This error may also be returned under implementation-defined +conditions. +.TP 7 +.B ENOSPC +There was no free space remaining on the device containing the file. +.TP 7 +.B ENXIO +A +request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.TP 7 +.B EOVERFLOW +For \fIfseek\fP(), the resulting file offset would be a value which +cannot be represented correctly in an object of type +\fBlong\fP. +.TP 7 +.B EOVERFLOW +For \fIfseeko\fP(), the resulting file offset would be a value which +cannot be represented correctly in an object of type +\fBoff_t\fP. +.TP 7 +.B EPIPE +An +attempt was made to write to a pipe or FIFO that is not open for reading +by any process; a SIGPIPE signal shall also be sent to the +thread. +.TP 7 +.B ESPIPE +The file descriptor underlying \fIstream\fP is associated with a pipe +or FIFO. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfopen\fP() , \fIfsetpos\fP() , \fIftell\fP() +, \fIgetrlimit\fP() , \fIlseek\fP() , \fIrewind\fP() , \fIulimit\fP() +, \fIungetc\fP() , \fIwrite\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fseeko.3p b/man3p/fseeko.3p new file mode 100644 index 000000000..294e7ce92 --- /dev/null +++ b/man3p/fseeko.3p @@ -0,0 +1 @@ +.so man3p/fseek.3p diff --git a/man3p/fsetpos.3p b/man3p/fsetpos.3p new file mode 100644 index 000000000..2852a99b3 --- /dev/null +++ b/man3p/fsetpos.3p @@ -0,0 +1,127 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FSETPOS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fsetpos +.SH NAME +fsetpos \- set current file position +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fsetpos(FILE *\fP\fIstream\fP\fB, const fpos_t *\fP\fIpos\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfsetpos\fP() function shall set the file position and state +indicators for the stream pointed to by \fIstream\fP +according to the value of the object pointed to by \fIpos\fP, which +the application shall ensure is a value obtained from an +earlier call to \fIfgetpos\fP() on the same stream. If a read or write +error occurs, the +error indicator for the stream shall be set and \fIfsetpos\fP() fails. +.LP +A successful call to the \fIfsetpos\fP() function shall clear the +end-of-file indicator for the stream and undo any effects of +\fIungetc\fP() on the same stream. After an \fIfsetpos\fP() call, +the next operation on an +update stream may be either input or output. +.LP +The +behavior of \fIfsetpos\fP() on devices which are incapable of seeking +is implementation-defined. The value of the file offset +associated with such a device is undefined. +.SH RETURN VALUE +.LP +The \fIfsetpos\fP() function shall return 0 if it succeeds; otherwise, +it shall return a non-zero value and set \fIerrno\fP to +indicate the error. +.SH ERRORS +.LP +The \fIfsetpos\fP() function shall fail if, \ either the \fIstream\fP +is unbuffered or the \fIstream\fP's +buffer needed to be flushed, and the call to \fIfsetpos\fP() causes +an underlying \fIlseek\fP() or \fIwrite\fP() to be invoked, and: +.TP 7 +.B EAGAIN +The O_NONBLOCK flag is set for the file descriptor and the process +would be delayed in the write operation. +.TP 7 +.B EBADF +The file descriptor underlying the stream file is not open for writing +or the stream's buffer needed to be flushed and the file is +not open. +.TP 7 +.B EFBIG +An +attempt was made to write a file that exceeds the maximum file size. +.TP 7 +.B EFBIG +An attempt was made to write a file that exceeds the process' file +size limit. +.TP 7 +.B EFBIG +The file is a regular file and an attempt was made to write at or +beyond the offset maximum associated with the corresponding +stream. +.TP 7 +.B EINTR +The write operation was terminated due to the receipt of a signal, +and no data was transferred. +.TP 7 +.B EIO +A +physical I/O error has occurred, or the process is a member of a background +process group attempting to perform a \fIwrite\fP() to its controlling +terminal, TOSTOP is set, the process is neither ignoring nor +blocking SIGTTOU, and the process group of the process is orphaned. +This error may also be returned under implementation-defined +conditions. +.TP 7 +.B ENOSPC +There was no free space remaining on the device containing the file. +.TP 7 +.B ENXIO +A +request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.TP 7 +.B EPIPE +The file descriptor underlying \fIstream\fP is associated with a pipe +or FIFO. +.TP 7 +.B EPIPE +An +attempt was made to write to a pipe or FIFO that is not open for reading +by any process; a SIGPIPE signal shall also be sent to the +thread. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfopen\fP() , \fIftell\fP() , \fIlseek\fP() , \fIrewind\fP() , \fIungetc\fP() +, \fIwrite\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fstat.3p b/man3p/fstat.3p new file mode 100644 index 000000000..779019d9d --- /dev/null +++ b/man3p/fstat.3p @@ -0,0 +1,130 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FSTAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fstat +.SH NAME +fstat \- get file status +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fstat(int\fP \fIfildes\fP\fB, struct stat *\fP\fIbuf\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfstat\fP() function shall obtain information about an open +file associated with the file descriptor \fIfildes\fP, and +shall write it to the area pointed to by \fIbuf\fP. +.LP +If \fIfildes\fP references a shared memory object, the implementation +shall update in the \fBstat\fP structure pointed to by the +\fIbuf\fP argument only the \fIst_uid\fP, \fIst_gid\fP, \fIst_size\fP, +and \fIst_mode\fP fields, and only the S_IRUSR, +S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file permission bits +need be valid. The implementation may update other fields and +flags. +.LP +If \fIfildes\fP references a typed memory object, the implementation +shall update in the \fBstat\fP structure pointed to by the +\fIbuf\fP argument only the \fIst_uid\fP, \fIst_gid\fP, \fIst_size\fP, +and \fIst_mode\fP fields, and only the S_IRUSR, +S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file permission bits +need be valid. The implementation may update other fields and +flags. +.LP +The \fIbuf\fP argument is a pointer to a \fBstat\fP structure, as +defined in \fI\fP, into which information is placed concerning +the file. +.LP +The structure members \fIst_mode\fP, \fIst_ino\fP, \fIst_dev\fP, \fIst_uid\fP, +\fIst_gid\fP, \fIst_atime\fP, +\fIst_ctime\fP, and \fIst_mtime\fP shall have meaningful values for +all other file types defined in this volume of +IEEE\ Std\ 1003.1-2001. The value of the member \fIst_nlink\fP shall +be set to the number of links to the file. +.LP +An implementation that provides additional or alternative file access +control mechanisms may, under implementation-defined +conditions, cause \fIfstat\fP() to fail. +.LP +The \fIfstat\fP() function shall update any time-related fields as +described in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.7, File Times Update, before writing +into the \fBstat\fP structure. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIfstat\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B EIO +An I/O error occurred while reading from the file system. +.TP 7 +.B EOVERFLOW +The file size in bytes or the number of blocks allocated to the file +or the file serial number cannot be represented correctly +in the structure pointed to by \fIbuf\fP. +.sp +.LP +The \fIfstat\fP() function may fail if: +.TP 7 +.B EOVERFLOW +One of the values is too large to store into the structure pointed +to by the \fIbuf\fP argument. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Obtaining File Status Information +.LP +The following example shows how to obtain file status information +for a file named \fB/home/cnd/mod1\fP. The structure variable +\fIbuffer\fP is defined for the \fBstat\fP structure. The \fB/home/cnd/mod1\fP +file is opened with read/write privileges and is +passed to the open file descriptor \fIfildes\fP. +.sp +.RS +.nf + +\fB#include +#include +#include +.sp + +struct stat buffer; +int status; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +status = fstat(fildes, &buffer); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIlstat\fP() , \fIstat\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fstatvfs.3p b/man3p/fstatvfs.3p new file mode 100644 index 000000000..d32458e04 --- /dev/null +++ b/man3p/fstatvfs.3p @@ -0,0 +1 @@ +.so man3p/statvfs.3p diff --git a/man3p/fsync.3p b/man3p/fsync.3p new file mode 100644 index 000000000..f0890f12a --- /dev/null +++ b/man3p/fsync.3p @@ -0,0 +1,121 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FSYNC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fsync +.SH NAME +fsync \- synchronize changes to a file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fsync(int\fP \fIfildes\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIfsync\fP() function shall request that all data for the open +file descriptor named by \fIfildes\fP is to be transferred +to the storage device associated with the file described by \fIfildes\fP +in an implementation-defined manner. The \fIfsync\fP() +function shall not return until the system has completed that action +or until an error is detected. +.LP +If _POSIX_SYNCHRONIZED_IO is defined, the \fIfsync\fP() function shall +force all currently queued I/O operations associated with +the file indicated by file descriptor \fIfildes\fP to the synchronized +I/O completion state. All I/O operations shall be completed +as defined for synchronized I/O file integrity completion. +.SH RETURN VALUE +.LP +Upon successful completion, \fIfsync\fP() shall return 0. Otherwise, +-1 shall be returned and \fIerrno\fP set to indicate the +error. If the \fIfsync\fP() function fails, outstanding I/O operations +are not guaranteed to have been completed. +.SH ERRORS +.LP +The \fIfsync\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid descriptor. +.TP 7 +.B EINTR +The \fIfsync\fP() function was interrupted by a signal. +.TP 7 +.B EINVAL +The \fIfildes\fP argument does not refer to a file on which this operation +is possible. +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to the file system. +.sp +.LP +In the event that any of the queued I/O operations fail, \fIfsync\fP() +shall return the error conditions defined for \fIread\fP() and \fIwrite\fP(). +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIfsync\fP() function should be used by programs which require +modifications to a file to be completed before continuing; +for example, a program which contains a simple transaction facility +might use it to ensure that all modifications to a file or +files caused by a transaction are recorded. +.SH RATIONALE +.LP +The \fIfsync\fP() function is intended to force a physical write of +data from the buffer cache, and to assure that after a +system crash or other failure that all data up to the time of the +\fIfsync\fP() call is recorded on the disk. Since the concepts +of "buffer cache", "system crash", "physical write", and "non-volatile +storage" are not defined here, the wording has to be +more abstract. +.LP +If _POSIX_SYNCHRONIZED_IO is not defined, the wording relies heavily +on the conformance document to tell the user what can be +expected from the system. It is explicitly intended that a null implementation +is permitted. This could be valid in the case where +the system cannot assure non-volatile storage under any circumstances +or when the system is highly fault-tolerant and the +functionality is not required. In the middle ground between these +extremes, \fIfsync\fP() might or might not actually cause data +to be written where it is safe from a power failure. The conformance +document should identify at least that one configuration +exists (and how to obtain that configuration) where this can be assured +for at least some files that the user can select to use for +critical data. It is not intended that an exhaustive list is required, +but rather sufficient information is provided so that if +critical data needs to be saved, the user can determine how the system +is to be configured to allow the data to be written to +non-volatile storage. +.LP +It is reasonable to assert that the key aspects of \fIfsync\fP() are +unreasonable to test in a test suite. That does not make +the function any less valuable, just more difficult to test. A formal +conformance test should probably force a system crash (power +shutdown) during the test for this condition, but it needs to be done +in such a way that automated testing does not require this to +be done except when a formal record of the results is being made. +It would also not be unreasonable to omit testing for +\fIfsync\fP(), allowing it to be treated as a quality-of-implementation +issue. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsync\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ftell.3p b/man3p/ftell.3p new file mode 100644 index 000000000..eda7027ff --- /dev/null +++ b/man3p/ftell.3p @@ -0,0 +1,92 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FTELL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ftell +.SH NAME +ftell, ftello \- return a file offset in a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +long ftell(FILE *\fP\fIstream\fP\fB); +.br +\fP +.LP +\fBoff_t ftello(FILE *\fP\fIstream\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIftell\fP() function shall obtain the current value of the file-position +indicator for the stream pointed to by +\fIstream\fP. +.LP +The +\fIftello\fP() function shall be equivalent to \fIftell\fP(), except +that the return value is of type \fBoff_t\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIftell\fP() \ and \fIftello\fP() +\ shall return the current value of the file-position indicator for +the stream measured in bytes +from the beginning of the file. +.LP +Otherwise, \fIftell\fP() \ and \fIftello\fP() shall return +-1, cast to \fBlong\fP and \fBoff_t\fP respectively, and set \fIerrno\fP +to indicate the error. +.SH ERRORS +.LP +The \fIftell\fP() \ and \fIftello\fP() functions +shall fail if: +.TP 7 +.B EBADF +The file descriptor underlying \fIstream\fP is not an open file descriptor. +.TP 7 +.B EOVERFLOW +For \fIftell\fP(), the current file offset cannot be represented correctly +in an object of type \fBlong\fP. +.TP 7 +.B EOVERFLOW +For \fIftello\fP(), the current file offset cannot be represented +correctly in an object of type \fBoff_t\fP. +.TP 7 +.B ESPIPE +The file descriptor underlying \fIstream\fP is associated with a pipe +or FIFO. +.sp +.LP +The \fIftell\fP() function may fail if: +.TP 7 +.B ESPIPE +The file descriptor underlying \fIstream\fP is associated with a socket. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfgetpos\fP() , \fIfopen\fP() , \fIfseek\fP() +, \fIlseek\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ftello.3p b/man3p/ftello.3p new file mode 100644 index 000000000..680d18df2 --- /dev/null +++ b/man3p/ftello.3p @@ -0,0 +1 @@ +.so man3p/ftell.3p diff --git a/man3p/ftime.3p b/man3p/ftime.3p new file mode 100644 index 000000000..b54dcfe4a --- /dev/null +++ b/man3p/ftime.3p @@ -0,0 +1,84 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ftime +.SH NAME +ftime \- get date and time (\fBLEGACY\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int ftime(struct timeb *\fP\fItp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIftime\fP() function shall set the \fItime\fP and \fImillitm\fP +members of the \fBtimeb\fP structure pointed to by +\fItp\fP to contain the seconds and milliseconds portions, respectively, +of the current time in seconds since the Epoch. The +contents of the \fItimezone\fP and \fIdstflag\fP members of \fItp\fP +after a call to \fIftime\fP() are unspecified. +.LP +The system clock need not have millisecond granularity. Depending +on any granularity (particularly a granularity of one) renders +code non-portable. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIftime\fP() function shall return +0; otherwise, -1 shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Getting the Current Time and Date +.LP +The following example shows how to get the current system time values +using the \fIftime\fP() function. The \fBtimeb\fP +structure pointed to by \fItp\fP is filled with the current system +time values for \fItime\fP and \fImillitm\fP. +.sp +.RS +.nf + +\fB#include +.sp + +struct timeb tp; +int status; +\&... +status = ftime(&tp); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +For applications portability, the \fItime\fP() function should be +used to determine the +current time instead of \fIftime\fP(). Realtime applications should +use \fIclock_gettime\fP() to determine the current time instead of +\fIftime\fP(). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +This function may be withdrawn in a future version. +.SH SEE ALSO +.LP +\fIclock_getres\fP() , \fIctime\fP() , \fIgettimeofday\fP() , \fItime\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ftok.3p b/man3p/ftok.3p new file mode 100644 index 000000000..f30c04991 --- /dev/null +++ b/man3p/ftok.3p @@ -0,0 +1,140 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FTOK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ftok +.SH NAME +ftok \- generate an IPC key +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +key_t ftok(const char *\fP\fIpath\fP\fB, int\fP \fIid\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIftok\fP() function shall return a key based on \fIpath\fP and +\fIid\fP that is usable in subsequent calls to \fImsgget\fP(), \fIsemget\fP(), +and \fIshmget\fP(). The application shall ensure that the \fIpath\fP +argument is the pathname of an +existing file that the process is able to \fIstat\fP(). +.LP +The \fIftok\fP() function shall return the same key value for all +paths that name the same file, when called with the same +\fIid\fP value, and return different key values when called with different +\fIid\fP values or with paths that name different +files existing on the same file system at the same time. It is unspecified +whether \fIftok\fP() shall return the same key value +when called again after the file named by \fIpath\fP is removed and +recreated with the same name. +.LP +Only the low-order 8-bits of \fIid\fP are significant. The behavior +of \fIftok\fP() is unspecified if these bits are 0. +.SH RETURN VALUE +.LP +Upon successful completion, \fIftok\fP() shall return a key. Otherwise, +\fIftok\fP() shall return (\fBkey_t\fP)-1 and set +\fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIftok\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied for a component of the path prefix. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.sp +.LP +The \fIftok\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Getting an IPC Key +.LP +The following example gets a unique key that can be used by the IPC +functions \fIsemget\fP(), \fImsgget\fP(), and \fIshmget\fP(). The +key returned by \fIftok\fP() for this example is based on the ID value +\fIS\fP and the pathname \fB/tmp\fP. +.sp +.RS +.nf + +\fB#include +\&... +key_t key; +char *path = "/tmp"; +int id = 'S'; +.sp + +key = ftok(path, id); +\fP +.fi +.RE +.SS Saving an IPC Key +.LP +The following example gets a unique key based on the pathname \fB/tmp\fP +and the ID value \fIa\fP. It also assigns the value +of the resulting key to the \fIsemkey\fP variable so that it will +be available to a later call to \fIsemget\fP(), \fImsgget\fP(), or +\fIshmget\fP(). +.sp +.RS +.nf + +\fB#include +\&... +key_t semkey; +.sp + +if ((semkey = ftok("/tmp", 'a')) == (key_t) -1) { + perror("IPC error: ftok"); exit(1); +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +For maximum portability, \fIid\fP should be a single-byte character. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImsgget\fP() , \fIsemget\fP() , \fIshmget\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ftruncate.3p b/man3p/ftruncate.3p new file mode 100644 index 000000000..4f5644da1 --- /dev/null +++ b/man3p/ftruncate.3p @@ -0,0 +1,130 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FTRUNCATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ftruncate +.SH NAME +ftruncate \- truncate a file to a specified length +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int ftruncate(int\fP \fIfildes\fP\fB, off_t\fP \fIlength\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If \fIfildes\fP is not a valid file descriptor open for writing, the +\fIftruncate\fP() function shall fail. +.LP +If \fIfildes\fP refers to a regular file, the \fIftruncate\fP() function +shall cause the size of the file to be truncated to +\fIlength\fP. If the size of the file previously exceeded \fIlength\fP, +the extra data shall no longer be available to reads on +the file. If the file previously was smaller than this size, \fIftruncate\fP() +shall either increase the size of the file or fail. +\ XSI-conformant systems shall increase the size of the file. +If the file size is increased, the extended area shall appear as if +it were zero-filled. The value of the seek pointer shall not be +modified by a call to \fIftruncate\fP(). +.LP +Upon successful completion, if \fIfildes\fP refers to a regular file, +the \fIftruncate\fP() function shall mark for update the +\fIst_ctime\fP and \fIst_mtime\fP fields of the file and the S_ISUID +and S_ISGID bits of the file mode may be cleared. If the +\fIftruncate\fP() function is unsuccessful, the file is unaffected. +.LP +If the request would cause the file size to exceed the soft file size +limit for the process, the request shall fail and the +implementation shall generate the SIGXFSZ signal for the thread. +.LP +If \fIfildes\fP refers to a directory, \fIftruncate\fP() shall fail. +.LP +If \fIfildes\fP refers to any other file type, except a shared memory +object, the result is unspecified. +.LP +If \fIfildes\fP refers to a shared memory object, \fIftruncate\fP() +shall set the size of the shared memory object to +\fIlength\fP. +.LP +If the effect of \fIftruncate\fP() is to decrease the size of a shared +memory object or memory mapped file and whole pages beyond +the new end were previously mapped, then the whole pages beyond the +new end shall be discarded. +.LP +If the Memory Protection option is supported, references to discarded +pages shall result in the generation of a SIGBUS signal; +otherwise, the result of such references is undefined. +.LP +If the effect of \fIftruncate\fP() is to increase the size of a shared +memory object, it is unspecified whether the contents of +any mapped pages between the old end-of-file and the new are flushed +to the underlying object. +.SH RETURN VALUE +.LP +Upon successful completion, \fIftruncate\fP() shall return 0; otherwise, +-1 shall be returned and \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +The \fIftruncate\fP() function shall fail if: +.TP 7 +.B EINTR +A signal was caught during execution. +.TP 7 +.B EINVAL +The \fIlength\fP argument was less than 0. +.TP 7 +.B EFBIG \fRor\fP EINVAL +.sp +The \fIlength\fP argument was greater than the maximum file size. +.TP 7 +.B EFBIG +The file is a regular file and \fIlength\fP is greater than the offset +maximum established in the open file description associated +with \fIfildes\fP. +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to a file system. +.TP 7 +.B EBADF \fRor\fP EINVAL +.sp +The \fIfildes\fP argument is not a file descriptor open for writing. +.TP 7 +.B EINVAL +The \fIfildes\fP argument references a file that was opened without +write permission. +.TP 7 +.B EROFS +The named file resides on a read-only file system. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIftruncate\fP() function is part of IEEE\ Std\ 1003.1-2001 as +it was deemed to be more useful than \fItruncate\fP(). The \fItruncate\fP() +function is +provided as an XSI extension. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIopen\fP() , \fItruncate\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ftrylockfile.3p b/man3p/ftrylockfile.3p new file mode 100644 index 000000000..cdaeb6410 --- /dev/null +++ b/man3p/ftrylockfile.3p @@ -0,0 +1 @@ +.so man3p/flockfile.3p diff --git a/man3p/ftw.3p b/man3p/ftw.3p new file mode 100644 index 000000000..c9dee6f63 --- /dev/null +++ b/man3p/ftw.3p @@ -0,0 +1,194 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FTW" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ftw +.SH NAME +ftw \- traverse (walk) a file tree +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int ftw(const char *\fP\fIpath\fP\fB, int (*\fP\fIfn\fP\fB)(const +char *, +.br +\ \ \ \ \ \ const struct stat *\fP\fIptr\fP\fB, int\fP \fIflag\fP\fB), +int\fP +\fIndirs\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIftw\fP() function shall recursively descend the directory hierarchy +rooted in \fIpath\fP. For each object in the +hierarchy, \fIftw\fP() shall call the function pointed to by \fIfn\fP, +passing it a pointer to a null-terminated character string +containing the name of the object, a pointer to a \fBstat\fP structure +containing information about the object, and an integer. +Possible values of the integer, defined in the \fI\fP header, +are: +.TP 7 +FTW_D +For a directory. +.TP 7 +FTW_DNR +For a directory that cannot be read. +.TP 7 +FTW_F +For a file. +.TP 7 +FTW_SL +For a symbolic link (but see also FTW_NS below). +.TP 7 +FTW_NS +For an object other than a symbolic link on which \fIstat\fP() could +not successfully be +executed. If the object is a symbolic link and \fIstat\fP() failed, +it is unspecified whether +\fIftw\fP() passes FTW_SL or FTW_NS to the user-supplied function. +.sp +.LP +If the integer is FTW_DNR, descendants of that directory shall not +be processed. If the integer is FTW_NS, the \fBstat\fP +structure contains undefined values. An example of an object that +would cause FTW_NS to be passed to the function pointed to by +\fIfn\fP would be a file in a directory with read but without execute +(search) permission. +.LP +The \fIftw\fP() function shall visit a directory before visiting any +of its descendants. +.LP +The \fIftw\fP() function shall use at most one file descriptor for +each level in the tree. +.LP +The argument \fIndirs\fP should be in the range [1, {OPEN_MAX}]. +.LP +The tree traversal shall continue until either the tree is exhausted, +an invocation of \fIfn\fP returns a non-zero value, or +some error, other than [EACCES], is detected within \fIftw\fP(). +.LP +The \fIndirs\fP argument shall specify the maximum number of directory +streams or file descriptors or both available for use by +\fIftw\fP() while traversing the tree. When \fIftw\fP() returns it +shall close any directory streams and file descriptors it uses +not counting any opened by the application-supplied \fIfn\fP function. +.LP +The results are unspecified if the application-supplied \fIfn\fP function +does not preserve the current working directory. +.LP +The \fIftw\fP() function need not be reentrant. A function that is +not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +If the tree is exhausted, \fIftw\fP() shall return 0. If the function +pointed to by \fIfn\fP returns a non-zero value, +\fIftw\fP() shall stop its tree traversal and return whatever value +was returned by the function pointed to by \fIfn\fP. If +\fIftw\fP() detects an error, it shall return -1 and set \fIerrno\fP +to indicate the error. +.LP +If \fIftw\fP() encounters an error other than [EACCES] (see FTW_DNR +and FTW_NS above), it shall return -1 and set \fIerrno\fP +to indicate the error. The external variable \fIerrno\fP may contain +any error value that is possible when a directory is opened +or when one of the \fIstat\fP functions is executed on a directory +or file. +.SH ERRORS +.LP +The \fIftw\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied for any component of \fIpath\fP or read +permission is denied for \fIpath\fP. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of \fIpath\fP is not a directory. +.TP 7 +.B EOVERFLOW +A field in the \fBstat\fP structure cannot be represented correctly +in the current programming environment for one or more +files found in the file hierarchy. +.sp +.LP +The \fIftw\fP() function may fail if: +.TP 7 +.B EINVAL +The value of the \fIndirs\fP argument is invalid. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.sp +.LP +In addition, if the function pointed to by \fIfn\fP encounters system +errors, \fIerrno\fP may be set accordingly. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Walking a Directory Structure +.LP +The following example walks the current directory structure, calling +the \fIfn\fP function for every directory entry, using at +most 10 file descriptors: +.sp +.RS +.nf + +\fB#include +\&... +if (ftw(".", fn, 10) != 0) { + perror("ftw"); exit(2); +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIftw\fP() function may allocate dynamic storage during its operation. +If \fIftw\fP() is forcibly terminated, such as by +\fIlongjmp\fP() or \fIsiglongjmp\fP() being +executed by the function pointed to by \fIfn\fP or an interrupt routine, +\fIftw\fP() does not have a chance to free that storage, +so it remains permanently allocated. A safe way to handle interrupts +is to store the fact that an interrupt has occurred, and +arrange to have the function pointed to by \fIfn\fP return a non-zero +value at its next invocation. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIlongjmp\fP() , \fIlstat\fP() , \fImalloc\fP() , \fInftw\fP() , +\fIopendir\fP() , \fIsiglongjmp\fP() , \fIstat\fP() , the Base Definitions +volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/funlockfile.3p b/man3p/funlockfile.3p new file mode 100644 index 000000000..cdaeb6410 --- /dev/null +++ b/man3p/funlockfile.3p @@ -0,0 +1 @@ +.so man3p/flockfile.3p diff --git a/man3p/fwide.3p b/man3p/fwide.3p new file mode 100644 index 000000000..17d67dac9 --- /dev/null +++ b/man3p/fwide.3p @@ -0,0 +1,73 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FWIDE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fwide +.SH NAME +fwide \- set stream orientation +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int fwide(FILE *\fP\fIstream\fP\fB, int\fP \fImode\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfwide\fP() function shall determine the orientation of the +stream pointed to by \fIstream\fP. If \fImode\fP is greater +than zero, the function first attempts to make the stream wide-oriented. +If \fImode\fP is less than zero, the function first +attempts to make the stream byte-oriented. Otherwise, \fImode\fP is +zero and the function does not alter the orientation of the +stream. +.LP +If the orientation of the stream has already been determined, \fIfwide\fP() +shall not change it. +.LP +Since no return value is reserved to indicate an error, an application +wishing to check for error situations should set +\fIerrno\fP to 0, then call \fIfwide\fP(), then check \fIerrno\fP, +and if it is non-zero, assume an error has occurred. +.SH RETURN VALUE +.LP +The \fIfwide\fP() function shall return a value greater than zero +if, after the call, the stream has wide-orientation, a value +less than zero if the stream has byte-orientation, or zero if the +stream has no orientation. +.SH ERRORS +.LP +The \fIfwide\fP() function may fail if: +.TP 7 +.B EBADF +The \fIstream\fP argument is not a valid stream. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +A call to \fIfwide\fP() with \fImode\fP set to zero can be used to +determine the current orientation of a stream. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fwprintf.3p b/man3p/fwprintf.3p new file mode 100644 index 000000000..229818897 --- /dev/null +++ b/man3p/fwprintf.3p @@ -0,0 +1 @@ +.so man3p/wprintf.3p diff --git a/man3p/fwrite.3p b/man3p/fwrite.3p new file mode 100644 index 000000000..af01f6b68 --- /dev/null +++ b/man3p/fwrite.3p @@ -0,0 +1,80 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FWRITE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fwrite +.SH NAME +fwrite \- binary output +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t fwrite(const void *restrict\fP \fIptr\fP\fB, size_t\fP \fIsize\fP\fB, +size_t\fP \fInitems\fP\fB, +.br +\ \ \ \ \ \ FILE *restrict\fP \fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfwrite\fP() function shall write, from the array pointed to +by \fIptr\fP, up to \fInitems\fP elements whose size is +specified by \fIsize\fP, to the stream pointed to by \fIstream\fP. +For each object, \fIsize\fP calls shall be made to the \fIfputc\fP() +function, taking the values (in order) from an array of \fBunsigned +char\fP +exactly overlaying the object. The file-position indicator for the +stream (if defined) shall be advanced by the number of bytes +successfully written. If an error occurs, the resulting value of the +file-position indicator for the stream is unspecified. +.LP +The +\fIst_ctime\fP and \fIst_mtime\fP fields of the file shall be marked +for update between the successful execution of +\fIfwrite\fP() and the next successful completion of a call to \fIfflush\fP() +or \fIfclose\fP() on the same stream, or a call to \fIexit\fP() +or \fIabort\fP(). +.SH RETURN VALUE +.LP +The \fIfwrite\fP() function shall return the number of elements successfully +written, which may be less than \fInitems\fP if a +write error is encountered. If \fIsize\fP or \fInitems\fP is 0, \fIfwrite\fP() +shall return 0 and the state of the stream +remains unchanged. Otherwise, if a write error occurs, the error indicator +for the stream shall be set, \ and +\fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +Refer to \fIfputc\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Because of possible differences in element length and byte ordering, +files written using \fIfwrite\fP() are +application-dependent, and possibly cannot be read using \fIfread\fP() +by a different +application or by the same application on a different processor. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIferror\fP() , \fIfopen\fP() , \fIprintf\fP() +, \fIputc\fP() , \fIputs\fP() , \fIwrite\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/fwscanf.3p b/man3p/fwscanf.3p new file mode 100644 index 000000000..672fbc26f --- /dev/null +++ b/man3p/fwscanf.3p @@ -0,0 +1 @@ +.so man3p/wscanf.3p diff --git a/man3p/gai_strerror.3p b/man3p/gai_strerror.3p new file mode 100644 index 000000000..d497828f1 --- /dev/null +++ b/man3p/gai_strerror.3p @@ -0,0 +1,77 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GAI_STRERROR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" gai_strerror +.SH NAME +gai_strerror \- address and name information error description +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +const char *gai_strerror(int\fP \fIecode\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgai_strerror\fP() function shall return a text string describing +an error value for the \fIgetaddrinfo\fP() and \fIgetnameinfo\fP() +functions listed in the \fI\fP header. +.LP +When the \fIecode\fP argument is one of the following values listed +in the \fI\fP header: +.sp +.RS +.nf + +[EAI_AGAIN] +[EAI_BADFLAGS] +[EAI_FAIL] +[EAI_FAMILY] +[EAI_MEMORY] +[EAI_NONAME] +[EAI_OVERFLOW] +[EAI_SERVICE] +[EAI_SOCKTYPE] +[EAI_SYSTEM] +.fi +.RE +.LP +the function return value shall point to a string describing the error. +If the argument is not one of those values, the function +shall return a pointer to a string whose contents indicate an unknown +error. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgai_strerror\fP() shall return a pointer +to an implementation-defined string. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetaddrinfo\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/gcvt.3p b/man3p/gcvt.3p new file mode 100644 index 000000000..ad49771fb --- /dev/null +++ b/man3p/gcvt.3p @@ -0,0 +1 @@ +.so man3p/ecvt.3p diff --git a/man3p/getaddrinfo.3p b/man3p/getaddrinfo.3p new file mode 100644 index 000000000..246af22ec --- /dev/null +++ b/man3p/getaddrinfo.3p @@ -0,0 +1,312 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FREEADDRINFO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" freeaddrinfo +.SH NAME +freeaddrinfo, getaddrinfo \- get address information +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +void freeaddrinfo(struct addrinfo *\fP\fIai\fP\fB); +.br +int getaddrinfo(const char *restrict\fP \fInodename\fP\fB, +.br +\ \ \ \ \ \ const char *restrict\fP \fIservname\fP\fB, +.br +\ \ \ \ \ \ const struct addrinfo *restrict\fP \fIhints\fP\fB, +.br +\ \ \ \ \ \ struct addrinfo **restrict\fP \fIres\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfreeaddrinfo\fP() function shall free one or more \fBaddrinfo\fP +structures returned by \fIgetaddrinfo\fP(), along +with any additional storage associated with those structures. If the +\fIai_next\fP field of the structure is not null, the entire +list of structures shall be freed. The \fIfreeaddrinfo\fP() function +shall support the freeing of arbitrary sublists of an +\fBaddrinfo\fP list originally returned by \fIgetaddrinfo\fP(). +.LP +The \fIgetaddrinfo\fP() function shall translate the name of a service +location (for example, a host name) and/or a service +name and shall return a set of socket addresses and associated information +to be used in creating a socket with which to address +the specified service. +.TP 7 +\fBNote:\fP +In many cases it is implemented by the Domain Name System, as documented +in RFC\ 1034, RFC\ 1035, and +RFC\ 1886. +.sp +.LP +The \fIfreeaddrinfo\fP() and \fIgetaddrinfo\fP() functions shall be +thread-safe. +.LP +The \fInodename\fP and \fIservname\fP arguments are either null pointers +or pointers to null-terminated strings. One or both +of these two arguments shall be supplied by the application as a non-null +pointer. +.LP +The format of a valid name depends on the address family or families. +If a specific family is not given and the name could be +interpreted as valid within multiple supported families, the implementation +shall attempt to resolve the name in all supported +families and, in absence of errors, one or more results shall be returned. +.LP +If the \fInodename\fP argument is not null, it can be a descriptive +name or can be an address string. If the specified address +family is AF_INET, \ AF_INET6, or AF_UNSPEC, valid +descriptive names include host names. If the specified address family +is AF_INET or AF_UNSPEC, address strings using Internet +standard dot notation as specified in \fIinet_addr\fP() are valid. +.LP +If the specified address family is AF_INET6 or AF_UNSPEC, standard +IPv6 text forms described in \fIinet_ntop\fP() are valid. +.LP +If \fInodename\fP is not null, the requested service location is named +by \fInodename\fP; otherwise, the requested service +location is local to the caller. +.LP +If \fIservname\fP is null, the call shall return network-level addresses +for the specified \fInodename.\fP If \fIservname\fP +is not null, it is a null-terminated character string identifying +the requested service. This can be either a descriptive name or a +numeric representation suitable for use with the address family or +families. If the specified address family is AF_INET, +\ AF_INET6, or AF_UNSPEC, the service can be specified as a +string specifying a decimal port number. +.LP +If the \fIhints\fP argument is not null, it refers to a structure +containing input values that may direct the operation by +providing options and by limiting the returned information to a specific +socket type, address family, and/or protocol. In this +\fIhints\fP structure every member other than \fIai_flags\fP, \fIai_family\fP, +\fIai_socktype\fP, and \fIai_protocol\fP shall +be set to zero or a null pointer. A value of AF_UNSPEC for \fIai_family\fP +means that the caller shall accept any address family. +A value of zero for \fIai_socktype\fP means that the caller shall +accept any socket type. A value of zero for \fIai_protocol\fP +means that the caller shall accept any protocol. If \fIhints\fP is +a null pointer, the behavior shall be as if it referred to a +structure containing the value zero for the \fIai_flags\fP, \fIai_socktype\fP, +and \fIai_protocol\fP fields, and AF_UNSPEC for +the \fIai_family\fP field. +.LP +The \fIai_flags\fP field to which the \fIhints\fP parameter points +shall be set to zero or be the bitwise-inclusive OR of one +or more of the values AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, +AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG. +.LP +If the AI_PASSIVE flag is specified, the returned address information +shall be suitable for use in binding a socket for +accepting incoming connections for the specified service. In this +case, if the \fInodename\fP argument is null, then the IP +address portion of the socket address structure shall be set to INADDR_ANY +for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 +address. If the AI_PASSIVE flag is not specified, the returned address +information shall be suitable for a call to \fIconnect\fP() (for a +connection-mode protocol) or for a call to \fIconnect\fP(), \fIsendto\fP(), +or \fIsendmsg\fP() (for a connectionless protocol). In this case, +if the \fInodename\fP argument is +null, then the IP address portion of the socket address structure +shall be set to the loopback address. The AI_PASSIVE flag shall +be ignored if the \fInodename\fP argument is not null. +.LP +If the AI_CANONNAME flag is specified and the \fInodename\fP argument +is not null, the function shall attempt to determine the +canonical name corresponding to \fInodename\fP (for example, if \fInodename\fP +is an alias or shorthand notation for a complete +name). +.TP 7 +\fBNote:\fP +Since different implementations use different conceptual models, the +terms ``canonical name'' and ``alias'' cannot be precisely +defined for the general case. However, Domain Name System implementations +are expected to interpret them as they are used in +RFC\ 1034. +.LP +A numeric host address string is not a ``name'', and thus does not +have a ``canonical name'' form; no address to host name +translation is performed. See below for handling of the case where +a canonical name cannot be obtained. +.sp +.LP +If the AI_NUMERICHOST flag is specified, then a non-null \fInodename\fP +string supplied shall be a numeric host address string. +Otherwise, an [EAI_NONAME] error is returned. This flag shall prevent +any type of name resolution service (for example, the DNS) +from being invoked. +.LP +If the AI_NUMERICSERV flag is specified, then a non-null \fIservname\fP +string supplied shall be a numeric port string. +Otherwise, an [EAI_NONAME] error shall be returned. This flag shall +prevent any type of name resolution service (for example, NIS+) +from being invoked. +.LP +If the AI_V4MAPPED flag is specified along with an \fIai_family\fP +of AF_INET6, then \fIgetaddrinfo\fP() shall return IPv4-mapped +IPv6 addresses on finding no matching IPv6 addresses ( \fIai_addrlen\fP +shall be 16). The AI_V4MAPPED flag shall be ignored unless +\fIai_family\fP equals AF_INET6. If the AI_ALL flag is used with the +AI_V4MAPPED flag, then \fIgetaddrinfo\fP() shall return all +matching IPv6 and IPv4 addresses. The AI_ALL flag without the AI_V4MAPPED +flag is ignored. +.LP +If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be returned +only if an IPv4 address is configured on the local +system, \ and IPv6 addresses shall be returned only if an IPv6 address +is configured on the local system. +.LP +The \fIai_socktype\fP field to which argument \fIhints\fP points specifies +the socket type for the service, as defined in \fIsocket\fP() . If +a specific socket type is not given (for example, a value of zero) +and the service name +could be interpreted as valid with multiple supported socket types, +the implementation shall attempt to resolve the service name +for all supported socket types and, in the absence of errors, all +possible results shall be returned. A non-zero socket type value +shall limit the returned information to values with the specified +socket type. +.LP +If the \fIai_family\fP field to which \fIhints\fP points has the value +AF_UNSPEC, addresses shall be returned for use with any +address family that can be used with the specified \fInodename\fP +and/or \fIservname\fP. Otherwise, addresses shall be returned +for use only with the specified address family. If \fIai_family\fP +is not AF_UNSPEC and \fIai_protocol\fP is not zero, then +addresses are returned for use only with the specified address family +and protocol; the value of \fIai_protocol\fP shall be +interpreted as in a call to the \fIsocket\fP() function with the corresponding +values of +\fIai_family\fP and \fIai_protocol\fP. +.SH RETURN VALUE +.LP +A zero return value for \fIgetaddrinfo\fP() indicates successful completion; +a non-zero return value indicates failure. The +possible values for the failures are listed in the ERRORS section. +.LP +Upon successful return of \fIgetaddrinfo\fP(), the location to which +\fIres\fP points shall refer to a linked list of +\fBaddrinfo\fP structures, each of which shall specify a socket address +and information for use in creating a socket with which to +use that socket address. The list shall include at least one \fBaddrinfo\fP +structure. The \fIai_next\fP field of each structure +contains a pointer to the next structure on the list, or a null pointer +if it is the last structure on the list. Each structure on +the list shall include values for use with a call to the \fIsocket\fP() +function, and a +socket address for use with the \fIconnect\fP() function or, if the +AI_PASSIVE flag was +specified, for use with the \fIbind\fP() function. The fields \fIai_family\fP, +\fIai_socktype\fP, and \fIai_protocol\fP shall be usable as the arguments +to the \fIsocket\fP() function to create a socket suitable for use +with the returned address. The fields +\fIai_addr\fP and \fIai_addrlen\fP are usable as the arguments to +the \fIconnect\fP() or +\fIbind\fP() functions with such a socket, according to the AI_PASSIVE +flag. +.LP +If \fInodename\fP is not null, and if requested by the AI_CANONNAME +flag, the \fIai_canonname\fP field of the first returned +\fBaddrinfo\fP structure shall point to a null-terminated string containing +the canonical name corresponding to the input +\fInodename\fP; if the canonical name is not available, then \fIai_canonname\fP +shall refer to the \fInodename\fP argument or a +string with the same contents. The contents of the \fIai_flags\fP +field of the returned structures are undefined. +.LP +All fields in socket address structures returned by \fIgetaddrinfo\fP() +that are not filled in through an explicit argument +(for example, \fIsin6_flowinfo\fP) shall be set to zero. +.TP 7 +\fBNote:\fP +This makes it easier to compare socket address structures. +.sp +.SH ERRORS +.LP +The \fIgetaddrinfo\fP() function shall fail and return the corresponding +value if: +.TP 7 +.B EAI_AGAIN +The name could not be resolved at this time. Future attempts may succeed. +.TP 7 +.B EAI_BADFLAGS +.sp +The \fIflags\fP parameter had an invalid value. +.TP 7 +.B EAI_FAIL +A non-recoverable error occurred when attempting to resolve the name. +.TP 7 +.B EAI_FAMILY +The address family was not recognized. +.TP 7 +.B EAI_MEMORY +There was a memory allocation failure when trying to allocate storage +for the return value. +.TP 7 +.B EAI_NONAME +The name does not resolve for the supplied parameters. +.LP +Neither \fInodename\fP nor \fIservname\fP were supplied. At least +one of these shall be supplied. +.TP 7 +.B EAI_SERVICE +The service passed was not recognized for the specified socket type. +.TP 7 +.B EAI_SOCKTYPE +.sp +The intended socket type was not recognized. +.TP 7 +.B EAI_SYSTEM +A system error occurred; the error code can be found in \fIerrno\fP. +.TP 7 +.B EAI_OVERFLOW +.sp +An argument buffer overflowed. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +If the caller handles only TCP and not UDP, for example, then the +\fIai_protocol\fP member of the \fIhints\fP structure should +be set to IPPROTO_TCP when \fIgetaddrinfo\fP() is called. +.LP +If the caller handles only IPv4 and not IPv6, then the \fIai_family\fP +member of the \fIhints\fP structure should be set to +AF_INET when \fIgetaddrinfo\fP() is called. +.LP +The term ``canonical name'' is misleading; it is taken from the Domain +Name System (RFC\ 2181). It should be noted that the +canonical name is a result of alias processing, and not necessarily +a unique attribute of a host, address, or set of addresses. See +RFC\ 2181 for more discussion of this in the Domain Name System context. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIconnect\fP() , \fIgai_strerror\fP() , \fIgethostbyaddr\fP() , \fIgetnameinfo\fP() +, \fIgetservbyname\fP() , \fIsocket\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getc.3p b/man3p/getc.3p new file mode 100644 index 000000000..c745c4548 --- /dev/null +++ b/man3p/getc.3p @@ -0,0 +1,64 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getc +.SH NAME +getc \- get a byte from a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int getc(FILE *\fP\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetc\fP() function shall be equivalent to \fIfgetc\fP() , except +that if it is implemented as +a macro it may evaluate \fIstream\fP more than once, so the argument +should never be an expression with side effects. +.SH RETURN VALUE +.LP +Refer to \fIfgetc\fP() . +.SH ERRORS +.LP +Refer to \fIfgetc\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +If the integer value returned by \fIgetc\fP() is stored into a variable +of type \fBchar\fP and then compared against the +integer constant EOF, the comparison may never succeed, because sign-extension +of a variable of type \fBchar\fP on widening to +integer is implementation-defined. +.LP +Since it may be implemented as a macro, \fIgetc\fP() may treat incorrectly +a \fIstream\fP argument with side effects. In +particular, \fIgetc\fP(*\fIf\fP++) does not necessarily work as expected. +Therefore, use of this function should be preceded by +\fB"#undef getc"\fP in such situations; \fIfgetc\fP() could also be +used. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfgetc\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getc_unlocked.3p b/man3p/getc_unlocked.3p new file mode 100644 index 000000000..c7026cfff --- /dev/null +++ b/man3p/getc_unlocked.3p @@ -0,0 +1 @@ +.so man3p/getchar_unlocked.3p diff --git a/man3p/getchar.3p b/man3p/getchar.3p new file mode 100644 index 000000000..4cd133967 --- /dev/null +++ b/man3p/getchar.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETCHAR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getchar +.SH NAME +getchar \- get a byte from a stdin stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int getchar(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetchar\fP() function shall be equivalent to \fIgetc\fP(\fIstdin\fP). +.SH RETURN VALUE +.LP +Refer to \fIfgetc\fP() . +.SH ERRORS +.LP +Refer to \fIfgetc\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +If the integer value returned by \fIgetchar\fP() is stored into a +variable of type \fBchar\fP and then compared against the +integer constant EOF, the comparison may never succeed, because sign-extension +of a variable of type \fBchar\fP on widening to +integer is implementation-defined. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetc\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getchar_unlocked.3p b/man3p/getchar_unlocked.3p new file mode 100644 index 000000000..20bf63d70 --- /dev/null +++ b/man3p/getchar_unlocked.3p @@ -0,0 +1,157 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETC_UNLOCKED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getc_unlocked +.SH NAME +getc_unlocked, getchar_unlocked, putc_unlocked, putchar_unlocked \- +stdio with explicit client locking +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int getc_unlocked(FILE *\fP\fIstream\fP\fB); +.br +int getchar_unlocked(void); +.br +int putc_unlocked(int\fP \fIc\fP\fB, FILE *\fP\fIstream\fP\fB); +.br +int putchar_unlocked(int\fP \fIc\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +Versions of the functions \fIgetc\fP(), \fIgetchar\fP(), \fIputc\fP(), +and \fIputchar\fP() respectively named \fIgetc_unlocked\fP(), \fIgetchar_unlocked\fP(), +\fIputc_unlocked\fP(), and \fIputchar_unlocked\fP() shall be provided +which are functionally equivalent to the original versions, +with the exception that they are not required to be implemented in +a thread-safe manner. They may only safely be used within a +scope protected by \fIflockfile\fP() (or \fIftrylockfile\fP()) and +\fIfunlockfile\fP(). +These functions may safely be used in a multi-threaded program if +and only if they are called while the invoking thread owns the ( +\fBFILE *\fP) object, as is the case after a successful call to the +\fIflockfile\fP() +or \fIftrylockfile\fP() functions. +.SH RETURN VALUE +.LP +See \fIgetc\fP() , \fIgetchar\fP() , \fIputc\fP() +, and \fIputchar\fP() . +.SH ERRORS +.LP +See \fIgetc\fP() , \fIgetchar\fP() , \fIputc\fP() +, and \fIputchar\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Since they may be implemented as macros, \fIgetc_unlocked\fP() and +\fIputc_unlocked\fP() may treat incorrectly a \fIstream\fP +argument with side effects. In particular, \fIgetc_unlocked\fP(*f++) +and \fIputc_unlocked\fP(*f++) do not necessarily work as +expected. Therefore, use of these functions in such situations should +be preceded by the following statement as appropriate: +.sp +.RS +.nf + +\fB#undef getc_unlocked +#undef putc_unlocked +\fP +.fi +.RE +.SH RATIONALE +.LP +Some I/O functions are typically implemented as macros for performance +reasons (for example, \fIputc\fP() and \fIgetc\fP()). For safety, +they need to be +synchronized, but it is often too expensive to synchronize on every +character. Nevertheless, it was felt that the safety concerns +were more important; consequently, the \fIgetc\fP(), \fIgetchar\fP(), +\fIputc\fP(), and \fIputchar\fP() functions are required to be thread-safe. +However, unlocked versions are also +provided with names that clearly indicate the unsafe nature of their +operation but can be used to exploit their higher performance. +These unlocked versions can be safely used only within explicitly +locked program regions, using exported locking primitives. In +particular, a sequence such as: +.sp +.RS +.nf + +\fBflockfile(fileptr); +putc_unlocked('1', fileptr); +putc_unlocked('\\n', fileptr); +fprintf(fileptr, "Line 2\\n"); +funlockfile(fileptr); +\fP +.fi +.RE +.LP +is permissible, and results in the text sequence: +.sp +.RS +.nf + +\fB1 +Line 2 +\fP +.fi +.RE +.LP +being printed without being interspersed with output from other threads. +.LP +It would be wrong to have the standard names such as \fIgetc\fP(), +\fIputc\fP(), and so on, map to the "faster, but unsafe" rather than +the "slower, but safe'' +versions. In either case, you would still want to inspect all uses +of \fIgetc\fP(), \fIputc\fP(), and so on, by hand when converting +existing code. Choosing the safe bindings as the +default, at least, results in correct code and maintains the "atomicity +at the function" invariant. To do otherwise would +introduce gratuitous synchronization errors into converted code. Other +routines that modify the \fIstdio\fP ( \fBFILE *\fP) +structures or buffers are also safely synchronized. +.LP +Note that there is no need for functions of the form \fIgetc_locked\fP(), +\fIputc_locked\fP(), and so on, since this is the +functionality of \fIgetc\fP(), \fIputc\fP(), \fIet +al\fP. It would be inappropriate to use a feature test macro to switch +a macro definition of \fIgetc\fP() between \fIgetc_locked\fP() and +\fIgetc_unlocked\fP(), since the ISO\ C standard +requires an actual function to exist, a function whose behavior could +not be changed by the feature test macro. Also, providing +both the \fIxxx_locked\fP() and \fIxxx_unlocked\fP() forms leads to +the confusion of whether the suffix describes the behavior of +the function or the circumstances under which it should be used. +.LP +Three additional routines, \fIflockfile\fP(), \fIftrylockfile\fP(), +and \fIfunlockfile\fP() +(which may be macros), are provided to allow the user to delineate +a sequence of I/O statements that are executed +synchronously. +.LP +The \fIungetc\fP() function is infrequently called relative to the +other +functions/macros so no unlocked variation is needed. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetc\fP() , \fIgetchar\fP() , \fIputc\fP() , \fIputchar\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getcontext.3p b/man3p/getcontext.3p new file mode 100644 index 000000000..250a0d165 --- /dev/null +++ b/man3p/getcontext.3p @@ -0,0 +1,101 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETCONTEXT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getcontext +.SH NAME +getcontext, setcontext \- get and set current user context +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int getcontext(ucontext_t *\fP\fIucp\fP\fB); +.br +int setcontext(const ucontext_t *\fP\fIucp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetcontext\fP() function shall initialize the structure pointed +to by \fIucp\fP to the current user context of the +calling thread. The \fBucontext_t\fP type that \fIucp\fP points to +defines the user context and includes the contents of the +calling thread's machine registers, the signal mask, and the current +execution stack. +.LP +The \fIsetcontext\fP() function shall restore the user context pointed +to by \fIucp\fP. A successful call to +\fIsetcontext\fP() shall not return; program execution resumes at +the point specified by the \fIucp\fP argument passed to +\fIsetcontext\fP(). The \fIucp\fP argument should be created either +by a prior call to \fIgetcontext\fP() or \fImakecontext\fP(), or by +being passed as an argument to a signal handler. If the \fIucp\fP +argument was created with \fIgetcontext\fP(), program execution continues +as if the corresponding call of \fIgetcontext\fP() had +just returned. If the \fIucp\fP argument was created with \fImakecontext\fP(), +program execution continues with the function passed to \fImakecontext\fP(). +When that +function returns, the thread shall continue as if after a call to +\fIsetcontext\fP() with the \fIucp\fP argument that was input +to \fImakecontext\fP(). If the \fIuc_link\fP member of the \fBucontext_t\fP +structure pointed to by the \fIucp\fP argument is equal to 0, then +this context is the main context, and the thread shall exit +when this context returns. The effects of passing a \fIucp\fP argument +obtained from any other source are unspecified. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsetcontext\fP() shall not return and +\fIgetcontext\fP() shall return 0; otherwise, a value of +-1 shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +Refer to \fImakecontext\fP() . +.SH APPLICATION USAGE +.LP +When a signal handler is executed, the current user context is saved +and a new context is created. If the thread leaves the +signal handler via \fIlongjmp\fP(), then it is unspecified whether +the context at the time +of the corresponding \fIsetjmp\fP() call is restored and thus whether +future calls to +\fIgetcontext\fP() provide an accurate representation of the current +context, since the context restored by \fIlongjmp\fP() does not necessarily +contain all the information that \fIsetcontext\fP() +requires. Signal handlers should use \fIsiglongjmp\fP() or \fIsetcontext\fP() +instead. +.LP +Conforming applications should not modify or access the \fIuc_mcontext\fP +member of \fBucontext_t\fP. A conforming application +cannot assume that context includes any process-wide static data, +possibly including \fIerrno\fP. Users manipulating contexts +should take care to handle these explicitly when required. +.LP +Use of contexts to create alternate stacks is not defined by this +volume of IEEE\ Std\ 1003.1-2001. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIbsd_signal\fP() , \fImakecontext\fP() , \fIsetcontext\fP() , \fIsetjmp\fP() +, \fIsigaction\fP() , \fIsigaltstack\fP() , \fIsiglongjmp\fP() , \fIsigprocmask\fP() +, \fIsigsetjmp\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getcwd.3p b/man3p/getcwd.3p new file mode 100644 index 000000000..88cf2e07c --- /dev/null +++ b/man3p/getcwd.3p @@ -0,0 +1,145 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETCWD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getcwd +.SH NAME +getcwd \- get the pathname of the current working directory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *getcwd(char *\fP\fIbuf\fP\fB, size_t\fP \fIsize\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetcwd\fP() function shall place an absolute pathname of the +current working directory in the array pointed to by +\fIbuf\fP, and return \fIbuf\fP. The pathname copied to the array +shall contain no components that are symbolic links. The +\fIsize\fP argument is the size in bytes of the character array pointed +to by the \fIbuf\fP argument. If \fIbuf\fP is a null +pointer, the behavior of \fIgetcwd\fP() is unspecified. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetcwd\fP() shall return the \fIbuf\fP +argument. Otherwise, \fIgetcwd\fP() shall return a null +pointer and set \fIerrno\fP to indicate the error. The contents of +the array pointed to by \fIbuf\fP are then undefined. +.SH ERRORS +.LP +The \fIgetcwd\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fIsize\fP argument is 0. +.TP 7 +.B ERANGE +The \fIsize\fP argument is greater than 0, but is smaller than the +length of the pathname +1. +.sp +.LP +The \fIgetcwd\fP() function may fail if: +.TP 7 +.B EACCES +Read or search permission was denied for a component of the pathname. +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Determining the Absolute Pathname of the Current Working Directory +.LP +The following example returns a pointer to an array that holds the +absolute pathname of the current working directory. The +pointer is returned in the \fIptr\fP variable, which points to the +\fIbuf\fP array where the pathname is stored. +.sp +.RS +.nf + +\fB#include +#include +\&... +long size; +char *buf; +char *ptr; +.sp + +size = pathconf(".", _PC_PATH_MAX); +.sp + +if ((buf = (char *)malloc((size_t)size)) != NULL) + ptr = getcwd(buf, (size_t)size); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Since the maximum pathname length is arbitrary unless {PATH_MAX} is +defined, an application generally cannot supply a \fIbuf\fP +with \fIsize\fP {{PATH_MAX}+1}. +.LP +Having \fIgetcwd\fP() take no arguments and instead use the \fImalloc\fP() +function to +produce space for the returned argument was considered. The advantage +is that \fIgetcwd\fP() knows how big the working directory +pathname is and can allocate an appropriate amount of space. But the +programmer would have to use the \fIfree\fP() function to free the +resulting object, or each use of \fIgetcwd\fP() would further +reduce the available memory. Also, \fImalloc\fP() and \fIfree\fP() +are used nowhere else in this volume of IEEE\ Std\ 1003.1-2001. Finally, +\fIgetcwd\fP() is taken from the SVID where it has the two arguments +used in this volume of IEEE\ Std\ 1003.1-2001. +.LP +The older function \fIgetwd\fP() was rejected for use in this context +because it had only +a buffer argument and no \fIsize\fP argument, and thus had no way +to prevent overwriting the buffer, except to depend on the +programmer to provide a large enough buffer. +.LP +On some implementations, if \fIbuf\fP is a null pointer, \fIgetcwd\fP() +may obtain \fIsize\fP bytes of memory using \fImalloc\fP(). In this +case, the pointer returned by \fIgetcwd\fP() may be used as the argument +in a subsequent call to \fIfree\fP(). Invoking \fIgetcwd\fP() with +\fIbuf\fP as a null +pointer is not recommended in conforming applications. +.LP +If a program is operating in a directory where some (grand)parent +directory does not permit reading, \fIgetcwd\fP() may fail, +as in most implementations it must read the directory to determine +the name of the file. This can occur if search, but not read, +permission is granted in an intermediate directory, or if the program +is placed in that directory by some more privileged process +(for example, login). Including the [EACCES] error condition makes +the reporting of the error consistent and warns the application +writer that \fIgetcwd\fP() can fail for reasons beyond the control +of the application writer or user. Some implementations can +avoid this occurrence (for example, by implementing \fIgetcwd\fP() +using \fIpwd\fP, where \fIpwd\fP is a set-user-root process), thus +the error was made optional. Since this volume of +IEEE\ Std\ 1003.1-2001 permits the addition of other errors, this +would be a common addition and yet one that applications +could not be expected to deal with without this addition. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImalloc\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getdate.3p b/man3p/getdate.3p new file mode 100644 index 000000000..b1155ce8c --- /dev/null +++ b/man3p/getdate.3p @@ -0,0 +1,350 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETDATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getdate +.SH NAME +getdate \- convert user format date and time +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +struct tm *getdate(const char *\fP\fIstring\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetdate\fP() function shall convert a string representation +of a date or time into a broken-down time. +.LP +The external variable or macro \fIgetdate_err\fP is used by \fIgetdate\fP() +to return error values. +.LP +Templates are used to parse and interpret the input string. The templates +are contained in a text file identified by the +environment variable \fIDATEMSK .\fP The \fIDATEMSK\fP variable should +be set to indicate the full pathname of the file that +contains the templates. The first line in the template that matches +the input specification is used for interpretation and +conversion into the internal time format. +.LP +The following conversion specifications shall be supported: +.TP 7 +\fB%%\fP +Equivalent to \fB%\fP . +.TP 7 +\fB%a\fP +Abbreviated weekday name. +.TP 7 +\fB%A\fP +Full weekday name. +.TP 7 +\fB%b\fP +Abbreviated month name. +.TP 7 +\fB%B\fP +Full month name. +.TP 7 +\fB%c\fP +Locale's appropriate date and time representation. +.TP 7 +\fB%C\fP +Century number [00,99]; leading zeros are permitted but not required. +.TP 7 +\fB%d\fP +Day of month [01,31]; the leading 0 is optional. +.TP 7 +\fB%D\fP +Date as \fB%m\fP / \fB%d\fP / \fB%y\fP . +.TP 7 +\fB%e\fP +Equivalent to \fB%d\fP . +.TP 7 +\fB%h\fP +Abbreviated month name. +.TP 7 +\fB%H\fP +Hour [00,23]. +.TP 7 +\fB%I\fP +Hour [01,12]. +.TP 7 +\fB%m\fP +Month number [01,12]. +.TP 7 +\fB%M\fP +Minute [00,59]. +.TP 7 +\fB%n\fP +Equivalent to . +.TP 7 +\fB%p\fP +Locale's equivalent of either AM or PM. +.TP 7 +\fB%r\fP +The locale's appropriate representation of time in AM and PM notation. +In the POSIX locale, this shall be equivalent to +\fB%I\fP : \fB%M\fP : \fB%S\fP \fB%p\fP . +.TP 7 +\fB%R\fP +Time as \fB%H\fP : \fB%M\fP . +.TP 7 +\fB%S\fP +Seconds [00,60]. The range goes to 60 (rather than stopping at 59) +to allow positive leap seconds to be expressed. Since leap +seconds cannot be predicted by any algorithm, leap second data must +come from some external source. +.TP 7 +\fB%t\fP +Equivalent to . +.TP 7 +\fB%T\fP +Time as \fB%H\fP : \fB%M\fP : \fB%S\fP . +.TP 7 +\fB%w\fP +Weekday number (Sunday = [0,6]). +.TP 7 +\fB%x\fP +Locale's appropriate date representation. +.TP 7 +\fB%X\fP +Locale's appropriate time representation. +.TP 7 +\fB%y\fP +Year within century. When a century is not otherwise specified, values +in the range [69,99] shall refer to years 1969 to 1999 +inclusive, and values in the range [00,68] shall refer to years 2000 +to 2068 inclusive. +.TP 7 +\fBNote:\fP +.RS +It is expected that in a future version of IEEE\ Std\ 1003.1-2001 +the default century inferred from a 2-digit year will +change. (This would apply to all commands accepting a 2-digit year +as input.) +.RE +.sp +.TP 7 +\fB%Y\fP +Year as \fB"ccyy"\fP (for example, 2001). +.TP 7 +\fB%Z\fP +Timezone name or no characters if no timezone exists. If the timezone +supplied by \fB%Z\fP is not the timezone that +\fIgetdate\fP() expects, an invalid input specification error shall +result. The \fIgetdate\fP() function calculates an expected +timezone based on information supplied to the function (such as the +hour, day, and month). +.sp +.LP +The match between the template and input specification performed by +\fIgetdate\fP() shall be case-insensitive. +.LP +The month and weekday names can consist of any combination of upper +and lowercase letters. The process can request that the +input date or time specification be in a specific language by setting +the \fILC_TIME\fP category (see \fIsetlocale\fP() ). +.LP +Leading zeros are not necessary for the descriptors that allow leading +zeros. However, at most two digits are allowed for those +descriptors, including leading zeros. Extra whitespace in either the +template file or in \fIstring\fP shall be ignored. +.LP +The results are undefined if the conversion specifications \fB%c\fP +, \fB%x\fP , and \fB%X\fP include unsupported +conversion specifications. +.LP +The following rules apply for converting the input specification into +the internal format: +.IP " *" 3 +If \fB%Z\fP is being scanned, then \fIgetdate\fP() shall initialize +the broken-down time to be the current time in the +scanned timezone. Otherwise, it shall initialize the broken-down time +based on the current local time as if \fIlocaltime\fP() had been called. +.LP +.IP " *" 3 +If only the weekday is given, the day chosen shall be the day, starting +with today and moving into the future, which first +matches the named day. +.LP +.IP " *" 3 +If only the month (and no year) is given, the month chosen shall be +the month, starting with the current month and moving into +the future, which first matches the named month. The first day of +the month shall be assumed if no day is given. +.LP +.IP " *" 3 +If no hour, minute, and second are given, the current hour, minute, +and second shall be assumed. +.LP +.IP " *" 3 +If no date is given, the hour chosen shall be the hour, starting with +the current hour and moving into the future, which first +matches the named hour. +.LP +.LP +If a conversion specification in the DATEMSK file does not correspond +to one of the conversion specifications above, the +behavior is unspecified. +.LP +The \fIgetdate\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetdate\fP() shall return a pointer +to a \fBstruct tm\fP. Otherwise, it shall return a null +pointer and set \fIgetdate_err\fP to indicate the error. +.SH ERRORS +.LP +The \fIgetdate\fP() function shall fail in the following cases, setting +\fIgetdate_err\fP to the value shown in the list +below. Any changes to \fIerrno\fP are unspecified. +.IP " 1." 4 +The \fIDATEMSK\fP environment variable is null or undefined. +.LP +.IP " 2." 4 +The template file cannot be opened for reading. +.LP +.IP " 3." 4 +Failed to get file status information. +.LP +.IP " 4." 4 +The template file is not a regular file. +.LP +.IP " 5." 4 +An I/O error is encountered while reading the template file. +.LP +.IP " 6." 4 +Memory allocation failed (not enough memory available). +.LP +.IP " 7." 4 +There is no line in the template that matches the input. +.LP +.IP " 8." 4 +Invalid input specification. For example, February 31; or a time is +specified that cannot be represented in a \fBtime_t\fP +(representing the time in seconds since the Epoch). +.LP +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.IP " 1." 4 +The following example shows the possible contents of a template: +.sp +.RS +.nf + +\fB%m +%A %B %d, %Y, %H:%M:%S +%A +%B +%m/%d/%y %I %p +%d,%m,%Y %H:%M +at %A the %dst of %B in %Y +run job at %I %p,%B %dnd +%A den %d. %B %Y %H.%M Uhr +\fP +.fi +.RE +.LP +.IP " 2." 4 +The following are examples of valid input specifications for the template +in Example 1: +.sp +.RS +.nf + +\fBgetdate("10/1/87 4 PM"); +getdate("Friday"); +getdate("Friday September 18, 1987, 10:30:30"); +getdate("24,9,1986 10:30"); +getdate("at monday the 1st of december in 1986"); +getdate("run job at 3 PM, december 2nd"); +\fP +.fi +.RE +.LP +If the \fILC_TIME\fP category is set to a German locale that includes +\fIfreitag\fP as a weekday name and \fIoktober\fP as a +month name, the following would be valid: +.sp +.RS +.nf + +\fBgetdate("freitag den 10. oktober 1986 10.30 Uhr"); +\fP +.fi +.RE +.LP +.IP " 3." 4 +The following example shows how local date and time specification +can be defined in the template: +.TS C +center; l l. +\fBInvocation\fP \fBLine in Template\fP +getdate("11/27/86") %m/%d/%y +getdate("27.11.86") %d.%m.%y +getdate("86-11-27") %y-%m-%d +getdate("Friday 12:00:00") %A %H:%M:%S +.TE +.LP +.IP " 4." 4 +The following examples help to illustrate the above rules assuming +that the current date is Mon Sep 22 12:19:47 EDT 1986 and the +\fILC_TIME\fP category is set to the default C locale: +.TS C +center; l2 l2 l. +\fBInput\fP \fBLine in Template\fP \fBDate\fP +Mon %a Mon Sep 22 12:19:47 EDT 1986 +Sun %a Sun Sep 28 12:19:47 EDT 1986 +Fri %a Fri Sep 26 12:19:47 EDT 1986 +September %B Mon Sep 1 12:19:47 EDT 1986 +January %B Thu Jan 1 12:19:47 EST 1987 +December %B Mon Dec 1 12:19:47 EST 1986 +Sep Mon %b %a Mon Sep 1 12:19:47 EDT 1986 +Jan Fri %b %a Fri Jan 2 12:19:47 EST 1987 +Dec Mon %b %a Mon Dec 1 12:19:47 EST 1986 +Jan Wed 1989 %b %a %Y Wed Jan 4 12:19:47 EST 1989 +Fri 9 %a %H Fri Sep 26 09:00:00 EDT 1986 +Feb 10:30 %b %H:%S Sun Feb 1 10:00:30 EST 1987 +10:30 %H:%M Tue Sep 23 10:30:00 EDT 1986 +13:30 %H:%M Mon Sep 22 13:30:00 EDT 1986 +.TE +.LP +.SH APPLICATION USAGE +.LP +Although historical versions of \fIgetdate\fP() did not require that +\fI\fP declare the external variable \fIgetdate_err\fP, this +volume of +IEEE\ Std\ 1003.1-2001 does require it. The standard developers encourage +applications to remove declarations of +\fIgetdate_err\fP and instead incorporate the declaration by including +\fI\fP. +.LP +Applications should use \fB%Y\fP (4-digit years) in preference to +\fB%y\fP (2-digit years). +.SH RATIONALE +.LP +In standard locales, the conversion specifications \fB%c\fP , \fB%x\fP +, and \fB%X\fP do not include unsupported +conversion specifiers and so the text regarding results being undefined +is not a problem in that case. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIctime\fP() , \fIlocaltime\fP() , \fIsetlocale\fP() , \fIstrftime\fP() +, \fItimes\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getdate_err.3p b/man3p/getdate_err.3p new file mode 100644 index 000000000..99baff98d --- /dev/null +++ b/man3p/getdate_err.3p @@ -0,0 +1 @@ +.so man3p/getdate.3p diff --git a/man3p/getegid.3p b/man3p/getegid.3p new file mode 100644 index 000000000..3256d9b4c --- /dev/null +++ b/man3p/getegid.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETEGID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getegid +.SH NAME +getegid \- get the effective group ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +gid_t getegid(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetegid\fP() function shall return the effective group ID of +the calling process. +.SH RETURN VALUE +.LP +The \fIgetegid\fP() function shall always be successful and no return +value is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgeteuid\fP() , \fIgetgid\fP() , \fIgetuid\fP() , \fIsetegid\fP() +, \fIseteuid\fP() , \fIsetgid\fP() , \fIsetregid\fP() , \fIsetreuid\fP() +, \fIsetuid\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getenv.3p b/man3p/getenv.3p new file mode 100644 index 000000000..ddccb22a5 --- /dev/null +++ b/man3p/getenv.3p @@ -0,0 +1,157 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETENV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getenv +.SH NAME +getenv \- get value of an environment variable +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *getenv(const char *\fP\fIname\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetenv\fP() function shall search the environment of the calling +process (see the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables) for the +environment +variable \fIname\fP if it exists and return a pointer to the value +of the environment variable. If the specified environment +variable cannot be found, a null pointer shall be returned. The application +shall ensure that it does not modify the string pointed +to by the \fIgetenv\fP() function. +.LP +The string pointed to may be overwritten by a subsequent call to \fIgetenv\fP(), +\fIsetenv\fP(), or \fIunsetenv\fP(), but shall not be overwritten +by a call to any other function in this volume +of IEEE\ Std\ 1003.1-2001. +.LP +If +the application modifies \fIenviron\fP or the pointers to which it +points, the behavior of \fIgetenv\fP() is undefined. +.LP +The \fIgetenv\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetenv\fP() shall return a pointer +to a string containing the \fIvalue\fP for the specified +\fIname\fP. If the specified \fIname\fP cannot be found in the environment +of the calling process, a null pointer shall be +returned. +.LP +The return value from \fIgetenv\fP() may point to static data which +may be overwritten by subsequent calls to \fIgetenv\fP(), +\fIsetenv\fP(), or \fIunsetenv\fP(). +.LP +On XSI-conformant systems, the return value from \fIgetenv\fP() may +point to static data which may also be overwritten by +subsequent calls to \fIputenv\fP(). +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Getting the Value of an Environment Variable +.LP +The following example gets the value of the \fIHOME\fP environment +variable. +.sp +.RS +.nf + +\fB#include +\&... +const char *name = "HOME"; +char *value; +.sp + +value = getenv(name); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIclearenv\fP() function was considered but rejected. The \fIputenv\fP() +function +has now been included for alignment with the Single UNIX Specification. +.LP +The \fIgetenv\fP() function is inherently not reentrant because it +returns a value pointing to static data. +.LP +Conforming applications are required not to modify \fIenviron\fP directly, +but to use only the functions described here to +manipulate the process environment as an abstract object. Thus, the +implementation of the environment access functions has complete +control over the data structure used to represent the environment +(subject to the requirement that \fIenviron\fP be maintained as +a list of strings with embedded equal signs for applications that +wish to scan the environment). This constraint allows the +implementation to properly manage the memory it allocates, either +by using allocated storage for all variables (copying them on the +first invocation of \fIsetenv\fP() or \fIunsetenv\fP()), or keeping +track of which strings are currently in allocated space and which +are not, via a separate table or some other means. This enables the +implementation to free any allocated space used by strings (and +perhaps the pointers to them) stored in \fIenviron\fP when \fIunsetenv\fP() +is called. A +C runtime start-up procedure (that which invokes \fImain\fP() and +perhaps initializes \fIenviron\fP) can also initialize a flag +indicating that none of the environment has yet been copied to allocated +storage, or that the separate table has not yet been +initialized. +.LP +In fact, for higher performance of \fIgetenv\fP(), the implementation +could also maintain a separate copy of the environment in +a data structure that could be searched much more quickly (such as +an indexed hash table, or a binary tree), and update both it and +the linear list at \fIenviron\fP when \fIsetenv\fP() or \fIunsetenv\fP() +is invoked. +.LP +Performance of \fIgetenv\fP() can be important for applications which +have large numbers of environment variables. Typically, +applications like this use the environment as a resource database +of user-configurable parameters. The fact that these variables +are in the user's shell environment usually means that any other program +that uses environment variables (such as \fIls\fP, which attempts +to use \fICOLUMNS ),\fP or really almost any utility ( \fILANG ,\fP +\fILC_ALL ,\fP and so on) is similarly slowed down by the linear search +through the variables. +.LP +An implementation that maintains separate data structures, or even +one that manages the memory it consumes, is not currently +required as it was thought it would reduce consensus among implementors +who do not want to change their historical +implementations. +.LP +The POSIX Threads Extension states that multi-threaded applications +must not modify \fIenviron\fP directly, and that +IEEE\ Std\ 1003.1-2001 is providing functions which such applications +can use in the future to manipulate the environment +in a thread-safe manner. Thus, moving away from application use of +\fIenviron\fP is desirable from that standpoint as well. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIputenv\fP() , \fIsetenv\fP() , \fIunsetenv\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/geteuid.3p b/man3p/geteuid.3p new file mode 100644 index 000000000..1c7d9b376 --- /dev/null +++ b/man3p/geteuid.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETEUID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" geteuid +.SH NAME +geteuid \- get the effective user ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +uid_t geteuid(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgeteuid\fP() function shall return the effective user ID of +the calling process. +.SH RETURN VALUE +.LP +The \fIgeteuid\fP() function shall always be successful and no return +value is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetegid\fP() , \fIgetgid\fP() , \fIgetuid\fP() , \fIsetegid\fP() +, \fIseteuid\fP() , \fIsetgid\fP() , \fIsetregid\fP() , \fIsetreuid\fP() +, \fIsetuid\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getgid.3p b/man3p/getgid.3p new file mode 100644 index 000000000..cd54e8d5c --- /dev/null +++ b/man3p/getgid.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETGID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getgid +.SH NAME +getgid \- get the real group ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +gid_t getgid(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetgid\fP() function shall return the real group ID of the +calling process. +.SH RETURN VALUE +.LP +The \fIgetgid\fP() function shall always be successful and no return +value is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetegid\fP() , \fIgeteuid\fP() , \fIgetuid\fP() , \fIsetegid\fP() +, \fIseteuid\fP() , \fIsetgid\fP() , \fIsetregid\fP() , \fIsetreuid\fP() +, \fIsetuid\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getgrent.3p b/man3p/getgrent.3p new file mode 100644 index 000000000..cda5f86e2 --- /dev/null +++ b/man3p/getgrent.3p @@ -0,0 +1,106 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ENDGRENT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" endgrent +.SH NAME +endgrent, getgrent, setgrent \- group database entry functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void endgrent(void); +.br +struct group *getgrent(void); +.br +void setgrent(void); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetgrent\fP() function shall return a pointer to a structure +containing the broken-out fields of an entry in the group +database. When first called, \fIgetgrent\fP() shall return a pointer +to a \fBgroup\fP structure containing the first entry in the +group database. Thereafter, it shall return a pointer to a \fBgroup\fP +structure containing the next group structure in the group +database, so successive calls may be used to search the entire database. +.LP +An implementation that provides extended security controls may impose +further implementation-defined restrictions on accessing +the group database. In particular, the system may deny the existence +of some or all of the group database entries associated with +groups other than those groups associated with the caller and may +omit users other than the caller from the list of members of +groups in database entries that are returned. +.LP +The \fIsetgrent\fP() function shall rewind the group database to allow +repeated searches. +.LP +The \fIendgrent\fP() function may be called to close the group database +when processing is complete. +.LP +These functions need not be reentrant. A function that is not required +to be reentrant is not required to be thread-safe. +.SH RETURN VALUE +.LP +When first called, \fIgetgrent\fP() shall return a pointer to the +first group structure in the group database. Upon subsequent +calls it shall return the next group structure in the group database. +The \fIgetgrent\fP() function shall return a null pointer on +end-of-file or an error and \fIerrno\fP may be set to indicate the +error. +.LP +The return value may point to a static area which is overwritten by +a subsequent call to \fIgetgrgid\fP(), \fIgetgrnam\fP(), or +\fIgetgrent\fP(). +.SH ERRORS +.LP +The \fIgetgrent\fP() function may fail if: +.TP 7 +.B EINTR +A signal was caught during the operation. +.TP 7 +.B EIO +An I/O error has occurred. +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENFILE +The maximum allowable number of files is currently open in the system. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +These functions are provided due to their historical usage. Applications +should avoid dependencies on fields in the group +database, whether the database is a single file, or where in the file +system name space the database resides. Applications should +use \fIgetgrnam\fP() and \fIgetgrgid\fP() +whenever possible because it avoids these dependencies. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetgrgid\fP() , \fIgetgrnam\fP() , \fIgetlogin\fP() , \fIgetpwent\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getgrgid.3p b/man3p/getgrgid.3p new file mode 100644 index 000000000..093ac6c07 --- /dev/null +++ b/man3p/getgrgid.3p @@ -0,0 +1,142 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETGRGID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getgrgid +.SH NAME +getgrgid, getgrgid_r \- get group database entry for a group ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +struct group *getgrgid(gid_t\fP \fIgid\fP\fB); +.br +\fP +.LP +\fBint getgrgid_r(gid_t\fP \fIgid\fP\fB, struct group *\fP\fIgrp\fP\fB, +char +*\fP\fIbuffer\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIbufsize\fP\fB, struct group **\fP\fIresult\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetgrgid\fP() function shall search the group database for +an entry with a matching \fIgid\fP. +.LP +The \fIgetgrgid\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.LP +The \fIgetgrgid_r\fP() function shall update the \fBgroup\fP structure +pointed to by \fIgrp\fP and store a pointer to that +structure at the location pointed to by \fIresult\fP. The structure +shall contain an entry from the group database with a matching +\fIgid\fP. Storage referenced by the group structure is allocated +from the memory provided with the \fIbuffer\fP parameter, which +is \fIbufsize\fP bytes in size. The maximum size needed for this buffer +can be determined with the {_SC_GETGR_R_SIZE_MAX} \fIsysconf\fP() +parameter. A NULL pointer shall be returned at the location pointed +to by +\fIresult\fP on error or if the requested entry is not found. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetgrgid\fP() shall return a pointer +to a \fBstruct group\fP with the structure defined in \fI\fP +with a matching entry if one is found. The \fIgetgrgid\fP() function +shall +return a null pointer if either the requested entry was not found, +or an error occurred. On error, \fIerrno\fP shall be set to +indicate the error. +.LP +The return value may point to a static area which is overwritten by +a subsequent call to \fIgetgrent\fP(), \fIgetgrgid\fP(), or \fIgetgrnam\fP(). +.LP +If successful, the \fIgetgrgid_r\fP() function shall return zero; +otherwise, an error number shall be returned to indicate the +error. +.SH ERRORS +.LP +The \fIgetgrgid\fP() and \fIgetgrgid_r\fP() functions may fail if: +.TP 7 +.B EIO +An I/O error has occurred. +.TP 7 +.B EINTR +A signal was caught during \fIgetgrgid\fP(). +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENFILE +The maximum allowable number of files is currently open in the system. +.sp +.LP +The \fIgetgrgid_r\fP() function may fail if: +.TP 7 +.B ERANGE +Insufficient storage was supplied via \fIbuffer\fP and \fIbufsize\fP +to contain the data to be referenced by the resulting +\fBgroup\fP structure. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Finding an Entry in the Group Database +.LP +The following example uses \fIgetgrgid\fP() to search the group database +for a group ID that was previously stored in a +\fBstat\fP structure, then prints out the group name if it is found. +If the group is not found, the program prints the numeric +value of the group for the entry. +.sp +.RS +.nf + +\fB#include +#include +#include +\&... +struct stat statbuf; +struct group *grp; +\&... +if ((grp = getgrgid(statbuf.st_gid)) != NULL) + printf(" %-8.8s", grp->gr_name); +else + printf(" %-8d", statbuf.st_gid); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +Applications wishing to check for error situations should set \fIerrno\fP +to 0 before calling \fIgetgrgid\fP(). If +\fIerrno\fP is set on return, an error occurred. +.LP +The \fIgetgrgid_r\fP() function is thread-safe and shall return values +in a user-supplied buffer instead of possibly using a +static data area that may be overwritten by each call. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIendgrent\fP() , \fIgetgrnam\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getgrgid_r.3p b/man3p/getgrgid_r.3p new file mode 100644 index 000000000..b0bb4aed1 --- /dev/null +++ b/man3p/getgrgid_r.3p @@ -0,0 +1 @@ +.so man3p/getgrgid.3p diff --git a/man3p/getgrnam.3p b/man3p/getgrnam.3p new file mode 100644 index 000000000..905c453c9 --- /dev/null +++ b/man3p/getgrnam.3p @@ -0,0 +1,119 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETGRNAM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getgrnam +.SH NAME +getgrnam, getgrnam_r \- search group database for a name +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +struct group *getgrnam(const char *\fP\fIname\fP\fB); +.br +\fP +.LP +\fBint getgrnam_r(const char *\fP\fIname\fP\fB, struct group *\fP\fIgrp\fP\fB, +char +*\fP\fIbuffer\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIbufsize\fP\fB, struct group **\fP\fIresult\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetgrnam\fP() function shall search the group database for +an entry with a matching \fIname\fP. +.LP +The \fIgetgrnam\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.LP +The \fIgetgrnam_r\fP() function shall update the \fBgroup\fP structure +pointed to by \fIgrp\fP and store a pointer to that +structure at the location pointed to by \fIresult\fP. The structure +shall contain an entry from the group database with a matching +\fIgid\fP or \fIname\fP. Storage referenced by the \fBgroup\fP structure +is allocated from the memory provided with the +\fIbuffer\fP parameter, which is \fIbufsize\fP bytes in size. The +maximum size needed for this buffer can be determined with the +{_SC_GETGR_R_SIZE_MAX} \fIsysconf\fP() parameter. A NULL pointer is +returned at the +location pointed to by \fIresult\fP on error or if the requested entry +is not found. +.SH RETURN VALUE +.LP +The \fIgetgrnam\fP() function shall return a pointer to a \fBstruct +group\fP with the structure defined in \fI\fP with a matching +entry if one is found. The \fIgetgrnam\fP() function shall +return a null pointer if either the requested entry was not found, +or an error occurred. On error, \fIerrno\fP shall be set to +indicate the error. +.LP +The return value may point to a static area which is overwritten by +a subsequent call to \fIgetgrent\fP(), \fIgetgrgid\fP(), or +\fIgetgrnam\fP(). +.LP +If successful, the \fIgetgrnam_r\fP() function shall return zero; +otherwise, an error number shall be returned to indicate the +error. +.SH ERRORS +.LP +The \fIgetgrnam\fP() and \fIgetgrnam_r\fP() functions may fail if: +.TP 7 +.B EIO +An I/O error has occurred. +.TP 7 +.B EINTR +A signal was caught during \fIgetgrnam\fP(). +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENFILE +The maximum allowable number of files is currently open in the system. +.sp +.LP +The \fIgetgrnam_r\fP() function may fail if: +.TP 7 +.B ERANGE +Insufficient storage was supplied via \fIbuffer\fP and \fIbufsize\fP +to contain the data to be referenced by the resulting +\fBgroup\fP structure. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications wishing to check for error situations should set \fIerrno\fP +to 0 before calling \fIgetgrnam\fP(). If +\fIerrno\fP is set on return, an error occurred. +.LP +The \fIgetgrnam_r\fP() function is thread-safe and shall return values +in a user-supplied buffer instead of possibly using a +static data area that may be overwritten by each call. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIendgrent\fP() , \fIgetgrgid\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getgrnam_r.3p b/man3p/getgrnam_r.3p new file mode 100644 index 000000000..2103de3d1 --- /dev/null +++ b/man3p/getgrnam_r.3p @@ -0,0 +1 @@ +.so man3p/getgrnam.3p diff --git a/man3p/getgroups.3p b/man3p/getgroups.3p new file mode 100644 index 000000000..3bd7d6180 --- /dev/null +++ b/man3p/getgroups.3p @@ -0,0 +1,116 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETGROUPS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getgroups +.SH NAME +getgroups \- get supplementary group IDs +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int getgroups(int\fP \fIgidsetsize\fP\fB, gid_t\fP \fIgrouplist\fP\fB[]); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetgroups\fP() function shall fill in the array \fIgrouplist\fP +with the current supplementary group IDs of the calling +process. It is implementation-defined whether \fIgetgroups\fP() also +returns the effective group ID in the \fIgrouplist\fP +array. +.LP +The \fIgidsetsize\fP argument specifies the number of elements in +the array \fIgrouplist\fP. The actual number of group IDs +stored in the array shall be returned. The values of array entries +with indices greater than or equal to the value returned are +undefined. +.LP +If \fIgidsetsize\fP is 0, \fIgetgroups\fP() shall return the number +of group IDs that it would otherwise return without +modifying the array pointed to by \fIgrouplist\fP. +.LP +If the effective group ID of the process is returned with the supplementary +group IDs, the value returned shall always be +greater than or equal to one and less than or equal to the value of +{NGROUPS_MAX}+1. +.SH RETURN VALUE +.LP +Upon successful completion, the number of supplementary group IDs +shall be returned. A return value of -1 indicates failure and +\fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +The \fIgetgroups\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fIgidsetsize\fP argument is non-zero and less than the number +of group IDs that would have been returned. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Getting the Supplementary Group IDs of the Calling Process +.LP +The following example places the current supplementary group IDs of +the calling process into the \fIgroup\fP array. +.sp +.RS +.nf + +\fB#include +#include +\&... +gid_t *group; +int nogroups; +long ngroups_max; +.sp + +ngroups_max = sysconf(_SC_NGROUPS_MAX) + 1; +group = (gid_t *)malloc(ngroups_max *sizeof(gid_t)); +.sp + +ngroups = getgroups(ngroups_max, group); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The related function \fIsetgroups\fP() is a privileged operation and +therefore is not covered by this volume of +IEEE\ Std\ 1003.1-2001. +.LP +As implied by the definition of supplementary groups, the effective +group ID may appear in the array returned by +\fIgetgroups\fP() or it may be returned only by \fIgetegid\fP(). Duplication +may exist, +but the application needs to call \fIgetegid\fP() to be sure of getting +all of the +information. Various implementation variations and administrative +sequences cause the set of groups appearing in the result of +\fIgetgroups\fP() to vary in order and as to whether the effective +group ID is included, even when the set of groups is the same +(in the mathematical sense of "set"). (The history of a process and +its parents could affect the details of the result.) +.LP +Application writers should note that {NGROUPS_MAX} is not necessarily +a constant on all implementations. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetegid\fP() , \fIsetgid\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/gethostbyaddr.3p b/man3p/gethostbyaddr.3p new file mode 100644 index 000000000..40a1dddc2 --- /dev/null +++ b/man3p/gethostbyaddr.3p @@ -0,0 +1 @@ +.so man3p/gethostbyname.3p diff --git a/man3p/gethostbyname.3p b/man3p/gethostbyname.3p new file mode 100644 index 000000000..8c5daaad8 --- /dev/null +++ b/man3p/gethostbyname.3p @@ -0,0 +1,144 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETHOSTBYADDR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" gethostbyaddr +.SH NAME +gethostbyaddr, gethostbyname \- network host database functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +\fP +.LP +\fBstruct hostent *gethostbyaddr(const void *\fP\fIaddr\fP\fB, socklen_t\fP +\fIlen\fP\fB, +.br +\ \ \ \ \ \ int\fP \fItype\fP\fB); +.br +struct hostent *gethostbyname(const char *\fP\fIname\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +These functions shall retrieve information about hosts. This information +is considered to be stored in a database that can be +accessed sequentially or randomly. Implementation of this database +is unspecified. +.TP 7 +\fBNote:\fP +In many cases it is implemented by the Domain Name System, as documented +in RFC\ 1034, RFC\ 1035, and +RFC\ 1886. +.sp +.LP +Entries shall be returned in \fBhostent\fP structures. +.LP +The \fIgethostbyaddr\fP() function shall return an entry containing +addresses of address family \fItype\fP for the host with +address \fIaddr\fP. The \fIlen\fP argument contains the length of +the address pointed to by \fIaddr\fP. The +\fIgethostbyaddr\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.LP +The \fIgethostbyname\fP() function shall return an entry containing +addresses of address family AF_INET for the host with name +\fIname\fP. The \fIgethostbyname\fP() function need not be reentrant. +A function that is not required to be reentrant is not +required to be thread-safe. +.LP +The \fIaddr\fP argument of \fIgethostbyaddr\fP() shall be an \fBin_addr\fP +structure when \fItype\fP is AF_INET. It contains +a binary format (that is, not null-terminated) address in network +byte order. The \fIgethostbyaddr\fP() function is not guaranteed +to return addresses of address families other than AF_INET, even when +such addresses exist in the database. +.LP +If \fIgethostbyaddr\fP() returns successfully, then the \fIh_addrtype\fP +field in the result shall be the same as the +\fItype\fP argument that was passed to the function, and the \fIh_addr_list\fP +field shall list a single address that is a copy +of the \fIaddr\fP argument that was passed to the function. +.LP +The \fIname\fP argument of \fIgethostbyname\fP() shall be a node name; +the behavior of \fIgethostbyname\fP() when passed a +numeric address string is unspecified. For IPv4, a numeric address +string shall be in the dotted-decimal notation described in \fIinet_addr\fP() +\&. +.LP +If \fIname\fP is not a numeric address string and is an alias for +a valid host name, then \fIgethostbyname\fP() shall return +information about the host name to which the alias refers, and \fIname\fP +shall be included in the list of aliases returned. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return a pointer +to a \fBhostent\fP structure if the requested entry was +found, and a null pointer if the end of the database was reached or +the requested entry was not found. +.LP +Upon unsuccessful completion, \fIgethostbyaddr\fP() and \fIgethostbyname\fP() +shall set \fIh_errno\fP to indicate the +error. +.SH ERRORS +.LP +These functions shall fail in the following cases. The \fIgethostbyaddr\fP() +and \fIgethostbyname\fP() functions shall set +\fIh_errno\fP to the value shown in the list below. Any changes to +\fIerrno\fP are unspecified. +.TP 7 +.B HOST_NOT_FOUND +.sp +No such host is known. +.TP 7 +.B NO_DATA +The server recognized the request and the name, but no address is +available. Another type of request to the name server for the +domain might return an answer. +.TP 7 +.B NO_RECOVERY +.sp +An unexpected server failure occurred which cannot be recovered. +.TP 7 +.B TRY_AGAIN +A temporary and possibly transient error occurred, such as a failure +of a server to respond. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIgethostbyaddr\fP() and \fIgethostbyname\fP() functions may +return pointers to static data, which may be overwritten by +subsequent calls to any of these functions. +.LP +The \fIgetaddrinfo\fP() and \fIgetnameinfo\fP() functions are preferred +over the \fIgethostbyaddr\fP() and +\fIgethostbyname\fP() functions. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +The \fIgethostbyaddr\fP() and \fIgethostbyname\fP() functions may +be withdrawn in a future version. +.SH SEE ALSO +.LP +\fIendhostent\fP() , \fIendservent\fP() , \fIgai_strerror\fP() , \fIgetaddrinfo\fP() +, \fIh_errno\fP() , \fIinet_addr\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/gethostent.3p b/man3p/gethostent.3p new file mode 100644 index 000000000..b82393655 --- /dev/null +++ b/man3p/gethostent.3p @@ -0,0 +1,90 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ENDHOSTENT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" endhostent +.SH NAME +endhostent, gethostent, sethostent \- network host database functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void endhostent(void); +.br +struct hostent *gethostent(void); +.br +void sethostent(int\fP \fIstayopen\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall retrieve information about hosts. This information +is considered to be stored in a database that can be +accessed sequentially or randomly. The implementation of this database +is unspecified. +.TP 7 +\fBNote:\fP +In many cases this database is implemented by the Domain Name System, +as documented in RFC\ 1034, RFC\ 1035, and +RFC\ 1886. +.sp +.LP +The \fIsethostent\fP() function shall open a connection to the database +and set the next entry for retrieval to the first entry +in the database. If the \fIstayopen\fP argument is non-zero, the connection +shall not be closed by a call to \fIgethostent\fP(), +\fIgethostbyname\fP(), or \fIgethostbyaddr\fP(), and the implementation +may maintain an open file descriptor. +.LP +The \fIgethostent\fP() function shall read the next entry in the database, +opening and closing a connection to the database as +necessary. +.LP +Entries shall be returned in \fBhostent\fP structures. Refer to \fIgethostbyaddr\fP() +for a +definition of the \fBhostent\fP structure. +.LP +The \fIendhostent\fP() function shall close the connection to the +database, releasing any open file descriptor. +.LP +These functions need not be reentrant. A function that is not required +to be reentrant is not required to be thread-safe. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIgethostent\fP() function shall +return a pointer to a \fBhostent\fP structure if the +requested entry was found, and a null pointer if the end of the database +was reached or the requested entry was not found. +.SH ERRORS +.LP +No errors are defined for \fIendhostent\fP(), \fIgethostent\fP(), +and \fIsethostent\fP(). +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIgethostent\fP() function may return pointers to static data, +which may be overwritten by subsequent calls to any of +these functions. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIendservent\fP() , \fIgethostbyaddr\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/gethostid.3p b/man3p/gethostid.3p new file mode 100644 index 000000000..d94d3a485 --- /dev/null +++ b/man3p/gethostid.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETHOSTID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" gethostid +.SH NAME +gethostid \- get an identifier for the current host +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +long gethostid(void); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgethostid\fP() function shall retrieve a 32-bit identifier +for the current host. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgethostid\fP() shall return an identifier +for the current host. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +This volume of IEEE\ Std\ 1003.1-2001 does not define the domain in +which the return value is unique. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIrandom\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/gethostname.3p b/man3p/gethostname.3p new file mode 100644 index 000000000..12999abfc --- /dev/null +++ b/man3p/gethostname.3p @@ -0,0 +1,59 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETHOSTNAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" gethostname +.SH NAME +gethostname \- get name of current host +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int gethostname(char *\fP\fIname\fP\fB, size_t\fP \fInamelen\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgethostname\fP() function shall return the standard host name +for the current machine. The \fInamelen\fP argument shall +specify the size of the array pointed to by the \fIname\fP argument. +The returned name shall be null-terminated, except that if +\fInamelen\fP is an insufficient length to hold the host name, then +the returned name shall be truncated and it is unspecified +whether the returned name is null-terminated. +.LP +Host names are limited to {HOST_NAME_MAX} bytes. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned; otherwise, -1 shall +be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgethostid\fP() , \fIuname\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getitimer.3p b/man3p/getitimer.3p new file mode 100644 index 000000000..d1446f32a --- /dev/null +++ b/man3p/getitimer.3p @@ -0,0 +1,117 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETITIMER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getitimer +.SH NAME +getitimer, setitimer \- get and set value of interval timer +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int getitimer(int\fP \fIwhich\fP\fB, struct itimerval *\fP\fIvalue\fP\fB); +.br +int setitimer(int\fP \fIwhich\fP\fB, const struct itimerval *restrict\fP +\fIvalue\fP\fB, +.br +\ \ \ \ \ \ struct itimerval *restrict\fP \fIovalue\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetitimer\fP() function shall store the current value of the +timer specified by \fIwhich\fP into the structure pointed +to by \fIvalue\fP. The \fIsetitimer\fP() function shall set the timer +specified by \fIwhich\fP to the value specified in the +structure pointed to by \fIvalue\fP, and if \fIovalue\fP is not a +null pointer, store the previous value of the timer in the +structure pointed to by \fIovalue\fP. +.LP +A timer value is defined by the \fBitimerval\fP structure, specified +in \fI\fP. If \fIit_value\fP is non-zero, it shall indicate +the time to the next +timer expiration. If \fIit_interval\fP is non-zero, it shall specify +a value to be used in reloading \fIit_value\fP when the +timer expires. Setting \fIit_value\fP to 0 shall disable a timer, +regardless of the value of \fIit_interval\fP. Setting +\fIit_interval\fP to 0 shall disable a timer after its next expiration +(assuming \fIit_value\fP is non-zero). +.LP +Implementations may place limitations on the granularity of timer +values. For each interval timer, if the requested timer value +requires a finer granularity than the implementation supports, the +actual timer value shall be rounded up to the next supported +value. +.LP +An XSI-conforming implementation provides each process with at least +three interval timers, which are indicated by the +\fIwhich\fP argument: +.TP 7 +ITIMER_REAL +Decrements in real time. A SIGALRM signal is delivered when this timer +expires. +.TP 7 +ITIMER_VIRTUAL +Decrements in process virtual time. It runs only when the process +is executing. A SIGVTALRM signal is delivered when it +expires. +.TP 7 +ITIMER_PROF +Decrements both in process virtual time and when the system is running +on behalf of the process. It is designed to be used by +interpreters in statistically profiling the execution of interpreted +programs. Each time the ITIMER_PROF timer expires, the SIGPROF +signal is delivered. +.sp +.LP +The interaction between \fIsetitimer\fP() and any of \fIalarm\fP(), +\fIsleep\fP(), or \fIusleep\fP() is unspecified. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetitimer\fP() or \fIsetitimer\fP() +shall return 0; otherwise, -1 shall be returned and +\fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIsetitimer\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fIvalue\fP argument is not in canonical form. (In canonical form, +the number of microseconds is a non-negative integer +less than 1000000 and the number of seconds is a non-negative integer.) +.sp +.LP +The \fIgetitimer\fP() and \fIsetitimer\fP() functions may fail if: +.TP 7 +.B EINVAL +The \fIwhich\fP argument is not recognized. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIalarm\fP() , \fIsleep\fP() , \fItimer_getoverrun\fP() , \fIualarm\fP() +, \fIusleep\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getlogin.3p b/man3p/getlogin.3p new file mode 100644 index 000000000..66c7e9202 --- /dev/null +++ b/man3p/getlogin.3p @@ -0,0 +1,172 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETLOGIN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getlogin +.SH NAME +getlogin, getlogin_r \- get login name +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *getlogin(void); +.br +\fP +.LP +\fBint getlogin_r(char *\fP\fIname\fP\fB, size_t\fP \fInamesize\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetlogin\fP() function shall return a pointer to a string containing +the user name associated by the login activity with +the controlling terminal of the current process. If \fIgetlogin\fP() +returns a non-null pointer, then that pointer points to the +name that the user logged in under, even if there are several login +names with the same user ID. +.LP +The \fIgetlogin\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.LP +The \fIgetlogin_r\fP() function shall put the name associated by the +login activity with the controlling terminal of the current +process in the character array pointed to by \fIname\fP. The array +is \fInamesize\fP characters long and should have space for +the name and the terminating null character. The maximum size of the +login name is {LOGIN_NAME_MAX}. +.LP +If \fIgetlogin_r\fP() is successful, \fIname\fP points to the name +the user used at login, even if there are several login +names with the same user ID. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetlogin\fP() shall return a pointer +to the login name or a null pointer if the user's login +name cannot be found. Otherwise, it shall return a null pointer and +set \fIerrno\fP to indicate the error. +.LP +The return value from \fIgetlogin\fP() may point to static data whose +content is overwritten by each call. +.LP +If successful, the \fIgetlogin_r\fP() function shall return zero; +otherwise, an error number shall be returned to indicate the +error. +.SH ERRORS +.LP +The \fIgetlogin\fP() and \fIgetlogin_r\fP() functions may fail if: +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENFILE +The maximum allowable number of files is currently open in the system. +.TP 7 +.B ENXIO +The calling process has no controlling terminal. +.sp +.LP +The \fIgetlogin_r\fP() function may fail if: +.TP 7 +.B ERANGE +The value of \fInamesize\fP is smaller than the length of the string +to be returned including the terminating null character. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Getting the User Login Name +.LP +The following example calls the \fIgetlogin\fP() function to obtain +the name of the user associated with the calling process, +and passes this information to the \fIgetpwnam\fP() function to get +the associated user +database information. +.sp +.RS +.nf + +\fB#include +#include +#include +#include +\&... +char *lgn; +struct passwd *pw; +\&... +if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) { + fprintf(stderr, "Get of user information failed.\\n"); exit(1); + } +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +Three names associated with the current process can be determined: +\fIgetpwuid\fP( \fIgeteuid\fP()) shall return the name associated +with the effective user ID of the process; +\fIgetlogin\fP() shall return the name associated with the current +login activity; and \fIgetpwuid\fP( \fIgetuid\fP()) shall return the +name associated with the real user ID of the process. +.LP +The \fIgetlogin_r\fP() function is thread-safe and returns values +in a user-supplied buffer instead of possibly using a static +data area that may be overwritten by each call. +.SH RATIONALE +.LP +The \fIgetlogin\fP() function returns a pointer to the user's login +name. The same user ID may be shared by several login +names. If it is desired to get the user database entry that is used +during login, the result of \fIgetlogin\fP() should be used to +provide the argument to the \fIgetpwnam\fP() function. (This might +be used to determine +the user's login shell, particularly where a single user has multiple +login shells with distinct login names, but the same user +ID.) +.LP +The information provided by the \fIcuserid\fP() function, which was +originally defined in the POSIX.1-1988 standard and +subsequently removed, can be obtained by the following: +.sp +.RS +.nf + +\fBgetpwuid(geteuid()) +\fP +.fi +.RE +.LP +while the information provided by historical implementations of \fIcuserid\fP() +can be obtained by: +.sp +.RS +.nf + +\fBgetpwuid(getuid()) +\fP +.fi +.RE +.LP +The thread-safe version of this function places the user name in a +user-supplied buffer and returns a non-zero value if it +fails. The non-thread-safe version may return the name in a static +data area that may be overwritten by each call. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetpwnam\fP() , \fIgetpwuid\fP() , \fIgeteuid\fP() , \fIgetuid\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getlogin_r.3p b/man3p/getlogin_r.3p new file mode 100644 index 000000000..ebb17b87c --- /dev/null +++ b/man3p/getlogin_r.3p @@ -0,0 +1 @@ +.so man3p/getlogin.3p diff --git a/man3p/getmsg.3p b/man3p/getmsg.3p new file mode 100644 index 000000000..683a99429 --- /dev/null +++ b/man3p/getmsg.3p @@ -0,0 +1,278 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETMSG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getmsg +.SH NAME +getmsg, getpmsg \- receive next message from a STREAMS file (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int getmsg(int\fP \fIfildes\fP\fB, struct strbuf *restrict\fP \fIctlptr\fP\fB, +.br +\ \ \ \ \ \ struct strbuf *restrict\fP \fIdataptr\fP\fB, int *restrict\fP +\fIflagsp\fP\fB); +.br +int getpmsg(int\fP \fIfildes\fP\fB, struct strbuf *restrict\fP \fIctlptr\fP\fB, +.br +\ \ \ \ \ \ struct strbuf *restrict\fP \fIdataptr\fP\fB, int *restrict\fP +\fIbandp\fP\fB, +.br +\ \ \ \ \ \ int *restrict\fP \fIflagsp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetmsg\fP() function shall retrieve the contents of a message +located at the head of the STREAM head read queue +associated with a STREAMS file and place the contents into one or +more buffers. The message contains either a data part, a control +part, or both. The data and control parts of the message shall be +placed into separate buffers, as described below. The semantics +of each part are defined by the originator of the message. +.LP +The \fIgetpmsg\fP() function shall be equivalent to \fIgetmsg\fP(), +except that it provides finer control over the priority of +the messages received. Except where noted, all requirements on \fIgetmsg\fP() +also pertain to \fIgetpmsg\fP(). +.LP +The \fIfildes\fP argument specifies a file descriptor referencing +a STREAMS-based file. +.LP +The \fIctlptr\fP and \fIdataptr\fP arguments each point to a \fBstrbuf\fP +structure, in which the \fIbuf\fP member points to +a buffer in which the data or control information is to be placed, +and the \fImaxlen\fP member indicates the maximum number of +bytes this buffer can hold. On return, the \fIlen\fP member shall +contain the number of bytes of data or control information +actually received. The \fIlen\fP member shall be set to 0 if there +is a zero-length control or data part and \fIlen\fP shall be +set to -1 if no data or control information is present in the message. +.LP +When \fIgetmsg\fP() is called, \fIflagsp\fP should point to an integer +that indicates the type of message the process is able +to receive. This is described further below. +.LP +The \fIctlptr\fP argument is used to hold the control part of the +message, and \fIdataptr\fP is used to hold the data part of +the message. If \fIctlptr\fP (or \fIdataptr\fP) is a null pointer +or the \fImaxlen\fP member is -1, the control (or data) part +of the message shall not be processed and shall be left on the STREAM +head read queue, and if the \fIctlptr\fP (or \fIdataptr\fP) +is not a null pointer, \fIlen\fP shall be set to -1. If the \fImaxlen\fP +member is set to 0 and there is a zero-length control +(or data) part, that zero-length part shall be removed from the read +queue and \fIlen\fP shall be set to 0. If the \fImaxlen\fP +member is set to 0 and there are more than 0 bytes of control (or +data) information, that information shall be left on the read +queue and \fIlen\fP shall be set to 0. If the \fImaxlen\fP member +in \fIctlptr\fP (or \fIdataptr\fP) is less than the control +(or data) part of the message, \fImaxlen\fP bytes shall be retrieved. +In this case, the remainder of the message shall be left on +the STREAM head read queue and a non-zero return value shall be provided. +.LP +By default, \fIgetmsg\fP() shall process the first available message +on the STREAM head read queue. However, a process may +choose to retrieve only high-priority messages by setting the integer +pointed to by \fIflagsp\fP to RS_HIPRI. In this case, +\fIgetmsg\fP() shall only process the next message if it is a high-priority +message. When the integer pointed to by \fIflagsp\fP +is 0, any available message shall be retrieved. In this case, on return, +the integer pointed to by \fIflagsp\fP shall be set to +RS_HIPRI if a high-priority message was retrieved, or 0 otherwise. +.LP +For \fIgetpmsg\fP(), the flags are different. The \fIflagsp\fP argument +points to a bitmask with the following +mutually-exclusive flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY. +Like \fIgetmsg\fP(), \fIgetpmsg\fP() shall process the first +available message on the STREAM head read queue. A process may choose +to retrieve only high-priority messages by setting the +integer pointed to by \fIflagsp\fP to MSG_HIPRI and the integer pointed +to by \fIbandp\fP to 0. In this case, \fIgetpmsg\fP() +shall only process the next message if it is a high-priority message. +In a similar manner, a process may choose to retrieve a +message from a particular priority band by setting the integer pointed +to by \fIflagsp\fP to MSG_BAND and the integer pointed to +by \fIbandp\fP to the priority band of interest. In this case, \fIgetpmsg\fP() +shall only process the next message if it is in a +priority band equal to, or greater than, the integer pointed to by +\fIbandp\fP, or if it is a high-priority message. If a process +wants to get the first message off the queue, the integer pointed +to by \fIflagsp\fP should be set to MSG_ANY and the integer +pointed to by \fIbandp\fP should be set to 0. On return, if the message +retrieved was a high-priority message, the integer pointed +to by \fIflagsp\fP shall be set to MSG_HIPRI and the integer pointed +to by \fIbandp\fP shall be set to 0. Otherwise, the integer +pointed to by \fIflagsp\fP shall be set to MSG_BAND and the integer +pointed to by \fIbandp\fP shall be set to the priority band +of the message. +.LP +If O_NONBLOCK is not set, \fIgetmsg\fP() and \fIgetpmsg\fP() shall +block until a message of the type specified by +\fIflagsp\fP is available at the front of the STREAM head read queue. +If O_NONBLOCK is set and a message of the specified type is +not present at the front of the read queue, \fIgetmsg\fP() and \fIgetpmsg\fP() +shall fail and set \fIerrno\fP to [EAGAIN]. +.LP +If a hangup occurs on the STREAM from which messages are retrieved, +\fIgetmsg\fP() and \fIgetpmsg\fP() shall continue to +operate normally, as described above, until the STREAM head read queue +is empty. Thereafter, they shall return 0 in the \fIlen\fP +members of \fIctlptr\fP and \fIdataptr\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetmsg\fP() and \fIgetpmsg\fP() shall +return a non-negative value. A value of 0 indicates that +a full message was read successfully. A return value of MORECTL indicates +that more control information is waiting for retrieval. A +return value of MOREDATA indicates that more data is waiting for retrieval. +A return value of the bitwise-logical OR of MORECTL and +MOREDATA indicates that both types of information remain. Subsequent +\fIgetmsg\fP() and \fIgetpmsg\fP() calls shall retrieve the +remainder of the message. However, if a message of higher priority +has come in on the STREAM head read queue, the next call to +\fIgetmsg\fP() or \fIgetpmsg\fP() shall retrieve that higher-priority +message before retrieving the remainder of the previous +message. +.LP +If the high priority control part of the message is consumed, the +message shall be placed back on the queue as a normal message +of band 0. Subsequent \fIgetmsg\fP() and \fIgetpmsg\fP() calls shall +retrieve the remainder of the message. If, however, a +priority message arrives or already exists on the STREAM head, the +subsequent call to \fIgetmsg\fP() or \fIgetpmsg\fP() shall +retrieve the higher-priority message before retrieving the remainder +of the message that was put back. +.LP +Upon failure, \fIgetmsg\fP() and \fIgetpmsg\fP() shall return -1 and +set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIgetmsg\fP() and \fIgetpmsg\fP() functions shall fail if: +.TP 7 +.B EAGAIN +The O_NONBLOCK flag is set and no messages are available. +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor open for +reading. +.TP 7 +.B EBADMSG +The queued message to be read is not valid for \fIgetmsg\fP() or \fIgetpmsg\fP() +or a pending file descriptor is at the +STREAM head. +.TP 7 +.B EINTR +A signal was caught during \fIgetmsg\fP() or \fIgetpmsg\fP(). +.TP 7 +.B EINVAL +An illegal value was specified by \fIflagsp\fP, or the STREAM or multiplexer +referenced by \fIfildes\fP is linked (directly +or indirectly) downstream from a multiplexer. +.TP 7 +.B ENOSTR +A STREAM is not associated with \fIfildes\fP. +.sp +.LP +In addition, \fIgetmsg\fP() and \fIgetpmsg\fP() shall fail if the +STREAM head had processed an asynchronous error before the +call. In this case, the value of \fIerrno\fP does not reflect the +result of \fIgetmsg\fP() or \fIgetpmsg\fP() but reflects the +prior error. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Getting Any Message +.LP +In the following example, the value of \fIfd\fP is assumed to refer +to an open STREAMS file. The call to \fIgetmsg\fP() +retrieves any available message on the associated STREAM-head read +queue, returning control and data information to the buffers +pointed to by \fIctrlbuf\fP and \fIdatabuf\fP, respectively. +.sp +.RS +.nf + +\fB#include +\&... +int fd; +char ctrlbuf[128]; +char databuf[512]; +struct strbuf ctrl; +struct strbuf data; +int flags = 0; +int ret; +.sp + +ctrl.buf = ctrlbuf; +ctrl.maxlen = sizeof(ctrlbuf); +.sp + +data.buf = databuf; +data.maxlen = sizeof(databuf); +.sp + +ret = getmsg (fd, &ctrl, &data, &flags); +\fP +.fi +.RE +.SS Getting the First Message off the Queue +.LP +In the following example, the call to \fIgetpmsg\fP() retrieves the +first available message on the associated STREAM-head read +queue. +.sp +.RS +.nf + +\fB#include +\&... +.sp + +int fd; +char ctrlbuf[128]; +char databuf[512]; +struct strbuf ctrl; +struct strbuf data; +int band = 0; +int flags = MSG_ANY; +int ret; +.sp + +ctrl.buf = ctrlbuf; +ctrl.maxlen = sizeof(ctrlbuf); +.sp + +data.buf = databuf; +data.maxlen = sizeof(databuf); +.sp + +ret = getpmsg (fd, &ctrl, &data, &band, &flags); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISTREAMS\fP , \fIpoll\fP() , \fIputmsg\fP() , \fIread\fP() , \fIwrite\fP() +, the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getnameinfo.3p b/man3p/getnameinfo.3p new file mode 100644 index 000000000..bfc5c6575 --- /dev/null +++ b/man3p/getnameinfo.3p @@ -0,0 +1,193 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETNAMEINFO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getnameinfo +.SH NAME +getnameinfo \- get name information +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int getnameinfo(const struct sockaddr *restrict\fP \fIsa\fP\fB, socklen_t\fP +\fIsalen\fP\fB, +.br +\ \ \ \ \ \ char *restrict\fP \fInode\fP\fB, socklen_t\fP \fInodelen\fP\fB, +char *restrict\fP +\fIservice\fP\fB, +.br +\ \ \ \ \ \ socklen_t\fP \fIservicelen\fP\fB, int\fP \fIflags\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetnameinfo\fP() function shall translate a socket address +to a node name and service location, all of which are defined +as in \fIgetaddrinfo\fP() . +.LP +The \fIsa\fP argument points to a socket address structure to be translated. +.LP +If the socket address structure contains an IPv4-mapped IPv6 address +or an IPv4-compatible IPv6 address, the implementation shall +extract the embedded IPv4 address and lookup the node name for that +IPv4 address. +.TP 7 +\fBNote:\fP +The IPv6 unspecified address ( \fB"::"\fP ) and the IPv6 loopback +address ( \fB"::1"\fP ) are not IPv4-compatible +addresses. If the address is the IPv6 unspecified address ( \fB"::"\fP +), a lookup is not performed, and the [EAI_NONAME] error +is returned. +.sp +.LP +If the \fInode\fP argument is non-NULL and the \fInodelen\fP argument +is non-zero, then the \fInode\fP argument points to a +buffer able to contain up to \fInodelen\fP characters that receives +the node name as a null-terminated string. If the \fInode\fP +argument is NULL or the \fInodelen\fP argument is zero, the node name +shall not be returned. If the node's name cannot be located, +the numeric form of the address contained in the socket address structure +pointed to by the \fIsa\fP argument is returned instead +of its name. +.LP +If the \fIservice\fP argument is non-NULL and the \fIservicelen\fP +argument is non-zero, then the \fIservice\fP argument +points to a buffer able to contain up to \fIservicelen\fP bytes that +receives the service name as a null-terminated string. If the +\fIservice\fP argument is NULL or the \fIservicelen\fP argument is +zero, the service name shall not be returned. If the service's +name cannot be located, the numeric form of the service address (for +example, its port number) shall be returned instead of its +name. +.LP +The \fIflags\fP argument is a flag that changes the default actions +of the function. By default the fully-qualified domain name +(FQDN) for the host shall be returned, but: +.IP " *" 3 +If the flag bit NI_NOFQDN is set, only the node name portion of the +FQDN shall be returned for local hosts. +.LP +.IP " *" 3 +If the flag bit NI_NUMERICHOST is set, the numeric form of the address +contained in the socket address structure pointed to by +the \fIsa\fP argument shall be returned instead of its name, under +all circumstances. +.LP +.IP " *" 3 +If the flag bit NI_NAMEREQD is set, an error shall be returned if +the host's name cannot be located. +.LP +.IP " *" 3 +If the flag bit NI_NUMERICSERV is set, the numeric form of the service +address shall be returned (for example, its port number) +instead of its name, under all circumstances. +.LP +.IP " *" 3 +If the flag bit NI_NUMERICSCOPE is set, the numeric form of the scope +identifier shall be returned (for example, interface +index) instead of its name. This flag shall be ignored if the \fIsa\fP +argument is not an IPv6 address. +.LP +.IP " *" 3 +If the flag bit NI_DGRAM is set, this indicates that the service is +a datagram service (SOCK_DGRAM). The default behavior shall +assume that the service is a stream service (SOCK_STREAM). +.LP +.TP 7 +\fBNotes:\fP +.RS +.IP " 1." 4 +The two NI_NUMERICxxx flags are required to support the \fB-n\fP flag +that many commands provide. +.LP +.IP " 2." 4 +The NI_DGRAM flag is required for the few AF_INET and AF_INET6 port +numbers (for example, [512,514]) that represent different +services for UDP and TCP. +.LP +.RE +.sp +.LP +The \fIgetnameinfo\fP() function shall be thread-safe. +.SH RETURN VALUE +.LP +A zero return value for \fIgetnameinfo\fP() indicates successful completion; +a non-zero return value indicates failure. The +possible values for the failures are listed in the ERRORS section. +.LP +Upon successful completion, \fIgetnameinfo\fP() shall return the \fInode\fP +and \fIservice\fP names, if requested, in the +buffers provided. The returned names are always null-terminated strings. +.SH ERRORS +.LP +The \fIgetnameinfo\fP() function shall fail and return the corresponding +value if: +.TP 7 +.B EAI_AGAIN +The name could not be resolved at this time. Future attempts may succeed. +.TP 7 +.B EAI_BADFLAGS +.sp +The \fIflags\fP had an invalid value. +.TP 7 +.B EAI_FAIL +A non-recoverable error occurred. +.TP 7 +.B EAI_FAMILY +The address family was not recognized or the address length was invalid +for the specified family. +.TP 7 +.B EAI_MEMORY +There was a memory allocation failure. +.TP 7 +.B EAI_NONAME +The name does not resolve for the supplied parameters. +.LP +NI_NAMEREQD is set and the host's name cannot be located, or both +\fInodename\fP and \fIservname\fP were null. +.TP 7 +.B EAI_OVERFLOW +.sp +An argument buffer overflowed. The buffer pointed to by the \fInode\fP +argument or the \fIservice\fP argument was too small. +.TP 7 +.B EAI_SYSTEM +A system error occurred. The error code can be found in \fIerrno\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +If the returned values are to be used as part of any further name +resolution (for example, passed to \fIgetaddrinfo\fP()), applications +should provide buffers large enough to store any result +possible on the system. +.LP +Given the IPv4-mapped IPv6 address \fB"::ffff:1.2.3.4"\fP , the implementation +performs a lookup as if the socket address +structure contains the IPv4 address \fB"1.2.3.4"\fP . +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgai_strerror\fP() , \fIgetaddrinfo\fP() , \fIgetservbyname\fP() +, \fIinet_ntop\fP() , \fIsocket\fP() , the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getnetbyaddr.3p b/man3p/getnetbyaddr.3p new file mode 100644 index 000000000..17b642ad2 --- /dev/null +++ b/man3p/getnetbyaddr.3p @@ -0,0 +1 @@ +.so man3p/getnetent.3p diff --git a/man3p/getnetbyname.3p b/man3p/getnetbyname.3p new file mode 100644 index 000000000..17b642ad2 --- /dev/null +++ b/man3p/getnetbyname.3p @@ -0,0 +1 @@ +.so man3p/getnetent.3p diff --git a/man3p/getnetent.3p b/man3p/getnetent.3p new file mode 100644 index 000000000..e3a63f9c9 --- /dev/null +++ b/man3p/getnetent.3p @@ -0,0 +1,104 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ENDNETENT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" endnetent +.SH NAME +endnetent, getnetbyaddr, getnetbyname, getnetent, setnetent \- network +database functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void endnetent(void); +.br +struct netent *getnetbyaddr(uint32_t\fP \fInet\fP\fB, int\fP \fItype\fP\fB); +.br +struct netent *getnetbyname(const char *\fP\fIname\fP\fB); +.br +struct netent *getnetent(void); +.br +void setnetent(int\fP \fIstayopen\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall retrieve information about networks. This information +is considered to be stored in a database that can be +accessed sequentially or randomly. The implementation of this database +is unspecified. +.LP +The \fIsetnetent\fP() function shall open and rewind the database. +If the \fIstayopen\fP argument is non-zero, the connection +to the \fInet\fP database shall not be closed after each call to \fIgetnetent\fP() +(either directly, or indirectly through one of +the other \fIgetnet*\fP() functions), and the implementation may maintain +an open file +descriptor to the database. +.LP +The \fIgetnetent\fP() function shall read the next entry of the database, +opening and closing a connection to the database as +necessary. +.LP +The \fIgetnetbyaddr\fP() function shall search the database from the +beginning, and find the first entry for which the address +family specified by \fItype\fP matches the \fIn_addrtype\fP member +and the network number \fInet\fP matches the \fIn_net\fP +member, opening and closing a connection to the database as necessary. +The \fInet\fP argument shall be the network number in host +byte order. +.LP +The \fIgetnetbyname\fP() function shall search the database from the +beginning and find the first entry for which the network +name specified by \fIname\fP matches the \fIn_name\fP member, opening +and closing a connection to the database as necessary. +.LP +The \fIgetnetbyaddr\fP(), \fIgetnetbyname\fP(), and \fIgetnetent\fP() +functions shall each return a pointer to a +\fBnetent\fP structure, the members of which shall contain the fields +of an entry in the network database. +.LP +The \fIendnetent\fP() function shall close the database, releasing +any open file descriptor. +.LP +These functions need not be reentrant. A function that is not required +to be reentrant is not required to be thread-safe. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetnetbyaddr\fP(), \fIgetnetbyname\fP(), +and \fIgetnetent\fP() shall return a pointer to a +\fBnetent\fP structure if the requested entry was found, and a null +pointer if the end of the database was reached or the +requested entry was not found. Otherwise, a null pointer shall be +returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIgetnetbyaddr\fP(), \fIgetnetbyname\fP(), and \fIgetnetent\fP() +functions may return pointers to static data, which may +be overwritten by subsequent calls to any of these functions. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getopt.3p b/man3p/getopt.3p new file mode 100644 index 000000000..af847634d --- /dev/null +++ b/man3p/getopt.3p @@ -0,0 +1,321 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETOPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getopt +.SH NAME +getopt, optarg, opterr, optind, optopt \- command option parsing +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int getopt(int\fP \fIargc\fP\fB, char * const\fP \fIargv\fP\fB[], +const char *\fP\fIoptstring\fP\fB); +.br +extern char *optarg; +.br +extern int optind, opterr, optopt; +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetopt\fP() function is a command-line parser that shall follow +Utility Syntax Guidelines 3, 4, 5, 6, 7, 9, and 10 in +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 12.2, +Utility Syntax Guidelines. +.LP +The parameters \fIargc\fP and \fIargv\fP are the argument count and +argument array as passed to \fImain\fP() (see \fIexec\fP() ). The +argument \fIoptstring\fP is a string of recognized +option characters; if a character is followed by a colon, the option +takes an argument. All option characters allowed by Utility +Syntax Guideline 3 are allowed in \fIoptstring\fP. The implementation +may accept other characters as an extension. +.LP +The variable \fIoptind\fP is the index of the next element of the +\fIargv\fP[] vector to be processed. It shall be initialized +to 1 by the system, and \fIgetopt\fP() shall update it when it finishes +with each element of \fIargv\fP[]. When an element of +\fIargv\fP[] contains multiple option characters, it is unspecified +how \fIgetopt\fP() determines which options have already been +processed. +.LP +The \fIgetopt\fP() function shall return the next option character +(if one is found) from \fIargv\fP that matches a character +in \fIoptstring\fP, if there is one that matches. If the option takes +an argument, \fIgetopt\fP() shall set the variable +\fIoptarg\fP to point to the option-argument as follows: +.IP " 1." 4 +If the option was the last character in the string pointed to by an +element of \fIargv\fP, then \fIoptarg\fP shall contain the +next element of \fIargv\fP, and \fIoptind\fP shall be incremented +by 2. If the resulting value of \fIoptind\fP is greater than +\fIargc\fP, this indicates a missing option-argument, and \fIgetopt\fP() +shall return an error indication. +.LP +.IP " 2." 4 +Otherwise, \fIoptarg\fP shall point to the string following the option +character in that element of \fIargv\fP, and +\fIoptind\fP shall be incremented by 1. +.LP +.LP +If, when \fIgetopt\fP() is called: +.sp +.RS +.nf + +\fIargv\fP\fB[optind]\fP is a null pointer\fB*\fP +\fIargv\fP\fB[optind]\fP is not the character \fB- \fP +\fIargv\fP\fB[optind]\fP points to the string \fB"-"\fP +.fi +.RE +.LP +\fIgetopt\fP() shall return -1 without changing \fIoptind\fP. If: +.sp +.RS +.nf + +\fIargv\fP\fB[optind] \fP points to the string \fB"--" +\fP +.fi +.RE +.LP +\fIgetopt\fP() shall return -1 after incrementing \fIoptind\fP. +.LP +If \fIgetopt\fP() encounters an option character that is not contained +in \fIoptstring\fP, it shall return the question-mark ( +\fB'?'\fP ) character. If it detects a missing option-argument, it +shall return the colon character ( \fB':'\fP ) if the +first character of \fIoptstring\fP was a colon, or a question-mark +character ( \fB'?'\fP ) otherwise. In either case, +\fIgetopt\fP() shall set the variable \fIoptopt\fP to the option character +that caused the error. If the application has not set +the variable \fIopterr\fP to 0 and the first character of \fIoptstring\fP +is not a colon, \fIgetopt\fP() shall also print a +diagnostic message to \fIstderr\fP in the format specified for the +\fIgetopts\fP +utility. +.LP +The \fIgetopt\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +The \fIgetopt\fP() function shall return the next option character +specified on the command line. +.LP +A colon ( \fB':'\fP ) shall be returned if \fIgetopt\fP() detects +a missing argument and the first character of +\fIoptstring\fP was a colon ( \fB':'\fP ). +.LP +A question mark ( \fB'?'\fP ) shall be returned if \fIgetopt\fP() +encounters an option character not in \fIoptstring\fP or +detects a missing argument and the first character of \fIoptstring\fP +was not a colon ( \fB':'\fP ). +.LP +Otherwise, \fIgetopt\fP() shall return -1 when all command line options +are parsed. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Parsing Command Line Options +.LP +The following code fragment shows how you might process the arguments +for a utility that can take the mutually-exclusive options +\fIa\fP and \fIb\fP and the options \fIf\fP and \fIo\fP, both of which +require arguments: +.sp +.RS +.nf + +\fB#include +.sp + +int +main(int argc, char *argv[ ]) +{ + int c; + int bflg, aflg, errflg; + char *ifile; + char *ofile; + extern char *optarg; + extern int optind, optopt; + . . . + while ((c = getopt(argc, argv, ":abf:o:")) != -1) { + switch(c) { + case 'a': + if (bflg) + errflg++; + else + aflg++; + break; + case 'b': + if (aflg) + errflg++; + else { + bflg++; + bproc(); + } + break; + case 'f': + ifile = optarg; + break; + case 'o': + ofile = optarg; + break; + case ':': /* -f or -o without operand */ + fprintf(stderr, + "Option -%c requires an operand\\n", optopt); + errflg++; + break; + case '?': + fprintf(stderr, + "Unrecognized option: -%c\\n", optopt); + errflg++; + } + } + if (errflg) { + fprintf(stderr, "usage: . . . "); + exit(2); + } + for ( ; optind < argc; optind++) { + if (access(argv[optind], R_OK)) { + . . . +} +\fP +.fi +.RE +.LP +This code accepts any of the following as equivalent: +.sp +.RS +.nf + +\fBcmd -ao arg path path +cmd -a -o arg path path +cmd -o arg -a path path +cmd -a -o arg -- path path +cmd -a -oarg path path +cmd -aoarg path path +\fP +.fi +.RE +.SS Checking Options and Arguments +.LP +The following example parses a set of command line options and prints +messages to standard output for each option and argument +that it encounters. +.sp +.RS +.nf + +\fB#include +#include +\&... +int c; +char *filename; +extern char *optarg; +extern int optind, optopt, opterr; +\&... +while ((c = getopt(argc, argv, ":abf:")) != -1) { + switch(c) { + case 'a': + printf("a is set\\n"); + break; + case 'b': + printf("b is set\\n"); + break; + case 'f': + filename = optarg; + printf("filename is %s\\n", filename); + break; + case ':': + printf("-%c without filename\\n", optopt); + break; + case '?': + printf("unknown arg %c\\n", optopt); + break; + } +} +\fP +.fi +.RE +.SS Selecting Options from the Command Line +.LP +The following example selects the type of database routines the user +wants to use based on the \fIOptions\fP argument. +.sp +.RS +.nf + +\fB#include +#include +\&... +char *Options = "hdbtl"; +\&... +int dbtype, i; +char c; +char *st; +\&... +dbtype = 0; +while ((c = getopt(argc, argv, Options)) != -1) { + if ((st = strchr(Options, c)) != NULL) { + dbtype = st - Options; + break; + } +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIgetopt\fP() function is only required to support option characters +included in Utility Syntax Guideline 3. Many +historical implementations of \fIgetopt\fP() support other characters +as options. This is an allowed extension, but applications +that use extensions are not maximally portable. Note that support +for multi-byte option characters is only possible when such +characters can be represented as type \fBint\fP. +.SH RATIONALE +.LP +The \fIoptopt\fP variable represents historical practice and allows +the application to obtain the identity of the invalid +option. +.LP +The description has been written to make it clear that \fIgetopt\fP(), +like the \fIgetopts\fP utility, deals with option-arguments whether +separated from the option by +s or not. Note that the requirements on \fIgetopt\fP() and +\fIgetopts\fP are +more stringent than the Utility Syntax Guidelines. +.LP +The \fIgetopt\fP() function shall return -1, rather than EOF, so that +\fI\fP is not required. +.LP +The special significance of a colon as the first character of \fIoptstring\fP +makes \fIgetopt\fP() consistent with the \fIgetopts\fP utility. It +allows an application to make a distinction between a missing +argument and an incorrect option letter without having to examine +the option letter. It is true that a missing argument can only be +detected in one case, but that is a case that has to be considered. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, the Shell and Utilities +volume of +IEEE\ Std\ 1003.1-2001 +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getpeername.3p b/man3p/getpeername.3p new file mode 100644 index 000000000..df69c9814 --- /dev/null +++ b/man3p/getpeername.3p @@ -0,0 +1,90 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETPEERNAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getpeername +.SH NAME +getpeername \- get the name of the peer socket +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int getpeername(int\fP \fIsocket\fP\fB, struct sockaddr *restrict\fP +\fIaddress\fP\fB, +.br +\ \ \ \ \ \ socklen_t *restrict\fP \fIaddress_len\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetpeername\fP() function shall retrieve the peer address of +the specified socket, store this address in the +\fBsockaddr\fP structure pointed to by the \fIaddress\fP argument, +and store the length of this address in the object pointed to +by the \fIaddress_len\fP argument. +.LP +If the actual length of the address is greater than the length of +the supplied \fBsockaddr\fP structure, the stored address +shall be truncated. +.LP +If the protocol permits connections by unbound clients, and the peer +is not bound, then the value stored in the object pointed +to by \fIaddress\fP is unspecified. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIgetpeername\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid file descriptor. +.TP 7 +.B EINVAL +The socket has been shut down. +.TP 7 +.B ENOTCONN +The socket is not connected or otherwise has not had the peer pre-specified. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.TP 7 +.B EOPNOTSUPP +The operation is not supported for the socket protocol. +.sp +.LP +The \fIgetpeername\fP() function may fail if: +.TP 7 +.B ENOBUFS +Insufficient resources were available in the system to complete the +call. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIaccept\fP() , \fIbind\fP() , \fIgetsockname\fP() , \fIsocket\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getpgid.3p b/man3p/getpgid.3p new file mode 100644 index 000000000..0bd100830 --- /dev/null +++ b/man3p/getpgid.3p @@ -0,0 +1,73 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETPGID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getpgid +.SH NAME +getpgid \- get the process group ID for a process +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +pid_t getpgid(pid_t\fP \fIpid\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetpgid\fP() function shall return the process group ID of +the process whose process ID is equal to \fIpid\fP. If +\fIpid\fP is equal to 0, \fIgetpgid\fP() shall return the process +group ID of the calling process. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetpgid\fP() shall return a process +group ID. Otherwise, it shall return (\fBpid_t\fP)-1 and +set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIgetpgid\fP() function shall fail if: +.TP 7 +.B EPERM +The process whose process ID is equal to \fIpid\fP is not in the same +session as the calling process, and the implementation +does not allow access to the process group ID of that process from +the calling process. +.TP 7 +.B ESRCH +There is no process with a process ID equal to \fIpid\fP. +.sp +.LP +The \fIgetpgid\fP() function may fail if: +.TP 7 +.B EINVAL +The value of the \fIpid\fP argument is invalid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIfork\fP() , \fIgetpgrp\fP() , \fIgetpid\fP() , \fIgetsid\fP() +, \fIsetpgid\fP() , \fIsetsid\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getpgrp.3p b/man3p/getpgrp.3p new file mode 100644 index 000000000..19d47085d --- /dev/null +++ b/man3p/getpgrp.3p @@ -0,0 +1,59 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETPGRP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getpgrp +.SH NAME +getpgrp \- get the process group ID of the calling process +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +pid_t getpgrp(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetpgrp\fP() function shall return the process group ID of +the calling process. +.SH RETURN VALUE +.LP +The \fIgetpgrp\fP() function shall always be successful and no return +value is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +4.3 BSD provides a \fIgetpgrp\fP() function that returns the process +group ID for a specified process. Although this function +supports job control, all known job control shells always specify +the calling process with this function. Thus, the simpler System +V \fIgetpgrp\fP() suffices, and the added complexity of the 4.3 BSD +\fIgetpgrp\fP() is provided by the XSI extension \fIgetpgid\fP(). +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIfork\fP() , \fIgetpgid\fP() , \fIgetpid\fP() , \fIgetppid\fP() +, \fIkill\fP() , \fIsetpgid\fP() , \fIsetsid\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getpid.3p b/man3p/getpid.3p new file mode 100644 index 000000000..e3cd4d3c7 --- /dev/null +++ b/man3p/getpid.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETPID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getpid +.SH NAME +getpid \- get the process ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +pid_t getpid(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetpid\fP() function shall return the process ID of the calling +process. +.SH RETURN VALUE +.LP +The \fIgetpid\fP() function shall always be successful and no return +value is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIfork\fP() , \fIgetpgrp\fP() , \fIgetppid\fP() , +\fIkill\fP() , \fIsetpgid\fP() , \fIsetsid\fP() , the Base Definitions +volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getpmsg.3p b/man3p/getpmsg.3p new file mode 100644 index 000000000..84ede0bb5 --- /dev/null +++ b/man3p/getpmsg.3p @@ -0,0 +1 @@ +.so man3p/getmsg.3p diff --git a/man3p/getppid.3p b/man3p/getppid.3p new file mode 100644 index 000000000..75dee9aad --- /dev/null +++ b/man3p/getppid.3p @@ -0,0 +1,55 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETPPID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getppid +.SH NAME +getppid \- get the parent process ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +pid_t getppid(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetppid\fP() function shall return the parent process ID of +the calling process. +.SH RETURN VALUE +.LP +The \fIgetppid\fP() function shall always be successful and no return +value is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIfork\fP() , \fIgetpgid\fP() , \fIgetpgrp\fP() , +\fIgetpid\fP() , \fIkill\fP() , \fIsetpgid\fP() , \fIsetsid\fP() , +the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getpriority.3p b/man3p/getpriority.3p new file mode 100644 index 000000000..8c4fb6101 --- /dev/null +++ b/man3p/getpriority.3p @@ -0,0 +1,175 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETPRIORITY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getpriority +.SH NAME +getpriority, setpriority \- get and set the nice value +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int getpriority(int\fP \fIwhich\fP\fB, id_t\fP \fIwho\fP\fB); +.br +int setpriority(int\fP \fIwhich\fP\fB, id_t\fP \fIwho\fP\fB, int\fP +\fIvalue\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetpriority\fP() function shall obtain the nice value of a +process, process group, or user. The \fIsetpriority\fP() +function shall set the nice value of a process, process group, or +user to \fIvalue\fP+ {NZERO}. +.LP +Target processes are specified by the values of the \fIwhich\fP and +\fIwho\fP arguments. The \fIwhich\fP argument may be one +of the following values: PRIO_PROCESS, PRIO_PGRP, or PRIO_USER, indicating +that the \fIwho\fP argument is to be interpreted as a +process ID, a process group ID, or an effective user ID, respectively. +A 0 value for the \fIwho\fP argument specifies the current +process, process group, or user. +.LP +The nice value set with \fIsetpriority\fP() shall be applied to the +process. If the process is multi-threaded, the nice value +shall affect all system scope threads in the process. +.LP +If more than one process is specified, \fIgetpriority\fP() shall return +value {NZERO} less than the lowest nice value +pertaining to any of the specified processes, and \fIsetpriority\fP() +shall set the nice values of all of the specified processes +to \fIvalue\fP+ {NZERO}. +.LP +The default nice value is {NZERO}; lower nice values shall cause more +favorable scheduling. While the range of valid nice values +is [0,{NZERO}*2-1], implementations may enforce more restrictive limits. +If \fIvalue\fP+ {NZERO} is less than the system's lowest +supported nice value, \fIsetpriority\fP() shall set the nice value +to the lowest supported value; if \fIvalue\fP+ {NZERO} is +greater than the system's highest supported nice value, \fIsetpriority\fP() +shall set the nice value to the highest supported +value. +.LP +Only a process with appropriate privileges can lower its nice value. +.LP +Any processes or threads using SCHED_FIFO or SCHED_RR shall be unaffected +by a call to \fIsetpriority\fP(). This is not considered +an error. A process which subsequently reverts to SCHED_OTHER need +not have its priority affected by such a \fIsetpriority\fP() +call. +.LP +The effect of changing the nice value may vary depending on the process-scheduling +algorithm in effect. +.LP +Since \fIgetpriority\fP() can return the value -1 on successful completion, +it is necessary to set \fIerrno\fP to 0 prior to a +call to \fIgetpriority\fP(). If \fIgetpriority\fP() returns the value +-1, then \fIerrno\fP can be checked to see if an error +occurred or if the value is a legitimate nice value. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetpriority\fP() shall return an integer +in the range -{NZERO} to {NZERO}-1. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.LP +Upon successful completion, \fIsetpriority\fP() shall return 0; otherwise, +-1 shall be returned and \fIerrno\fP set to +indicate the error. +.SH ERRORS +.LP +The \fIgetpriority\fP() and \fIsetpriority\fP() functions shall fail +if: +.TP 7 +.B ESRCH +No process could be located using the \fIwhich\fP and \fIwho\fP argument +values specified. +.TP 7 +.B EINVAL +The value of the \fIwhich\fP argument was not recognized, or the value +of the \fIwho\fP argument is not a valid process ID, +process group ID, or user ID. +.sp +.LP +In addition, \fIsetpriority\fP() may fail if: +.TP 7 +.B EPERM +A process was located, but neither the real nor effective user ID +of the executing process match the effective user ID of the +process whose nice value is being changed. +.TP 7 +.B EACCES +A request was made to change the nice value to a lower numeric value +and the current process does not have appropriate +privileges. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Using getpriority() +.LP +The following example returns the current scheduling priority for +the process ID returned by the call to \fIgetpid\fP(). +.sp +.RS +.nf + +\fB#include +\&... +int which = PRIO_PROCESS; +id_t pid; +int ret; +.sp + +pid = getpid(); +ret = getpriority(which, pid); +\fP +.fi +.RE +.SS Using setpriority() +.LP +The following example sets the priority for the current process ID +to -20. +.sp +.RS +.nf + +\fB#include +\&... +int which = PRIO_PROCESS; +id_t pid; +int priority = -20; +int ret; +.sp + +pid = getpid(); +ret = setpriority(which, pid, priority); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIgetpriority\fP() and \fIsetpriority\fP() functions work with +an offset nice value (nice value -{NZERO}). The nice value +is in the range [0,2*{NZERO} -1], while the return value for \fIgetpriority\fP() +and the third parameter for \fIsetpriority\fP() +are in the range [-{NZERO},{NZERO} -1]. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fInice\fP() , \fIsched_get_priority_max\fP() , \fIsched_setscheduler\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getprotobyname.3p b/man3p/getprotobyname.3p new file mode 100644 index 000000000..82a414026 --- /dev/null +++ b/man3p/getprotobyname.3p @@ -0,0 +1 @@ +.so man3p/getprotoent.3p diff --git a/man3p/getprotobynumber.3p b/man3p/getprotobynumber.3p new file mode 100644 index 000000000..82a414026 --- /dev/null +++ b/man3p/getprotobynumber.3p @@ -0,0 +1 @@ +.so man3p/getprotoent.3p diff --git a/man3p/getprotoent.3p b/man3p/getprotoent.3p new file mode 100644 index 000000000..9b2d8bf02 --- /dev/null +++ b/man3p/getprotoent.3p @@ -0,0 +1,104 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ENDPROTOENT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" endprotoent +.SH NAME +endprotoent, getprotobyname, getprotobynumber, getprotoent, setprotoent +\- network protocol database +functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void endprotoent(void); +.br +struct protoent *getprotobyname(const char *\fP\fIname\fP\fB); +.br +struct protoent *getprotobynumber(int\fP \fIproto\fP\fB); +.br +struct protoent *getprotoent(void); +.br +void setprotoent(int\fP \fIstayopen\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall retrieve information about protocols. This information +is considered to be stored in a database that can +be accessed sequentially or randomly. The implementation of this database +is unspecified. +.LP +The \fIsetprotoent\fP() function shall open a connection to the database, +and set the next entry to the first entry. If the +\fIstayopen\fP argument is non-zero, the connection to the network +protocol database shall not be closed after each call to +\fIgetprotoent\fP() (either directly, or indirectly through one of +the other \fIgetproto*\fP() functions), and the implementation may +maintain an open file descriptor for +the database. +.LP +The \fIgetprotobyname\fP() function shall search the database from +the beginning and find the first entry for which the +protocol name specified by \fIname\fP matches the \fIp_name\fP member, +opening and closing a connection to the database as +necessary. +.LP +The \fIgetprotobynumber\fP() function shall search the database from +the beginning and find the first entry for which the +protocol number specified by \fIproto\fP matches the \fIp_proto\fP +member, opening and closing a connection to the database as +necessary. +.LP +The \fIgetprotoent\fP() function shall read the next entry of the +database, opening and closing a connection to the database as +necessary. +.LP +The \fIgetprotobyname\fP(), \fIgetprotobynumber\fP(), and \fIgetprotoent\fP() +functions shall each return a pointer to a +\fBprotoent\fP structure, the members of which shall contain the fields +of an entry in the network protocol database. +.LP +The \fIendprotoent\fP() function shall close the connection to the +database, releasing any open file descriptor. +.LP +These functions need not be reentrant. A function that is not required +to be reentrant is not required to be thread-safe. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetprotobyname\fP(), \fIgetprotobynumber\fP(), +and \fIgetprotoent\fP() return a pointer to a +\fBprotoent\fP structure if the requested entry was found, and a null +pointer if the end of the database was reached or the +requested entry was not found. Otherwise, a null pointer is returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIgetprotobyname\fP(), \fIgetprotobynumber\fP(), and \fIgetprotoent\fP() +functions may return pointers to static data, +which may be overwritten by subsequent calls to any of these functions. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getpwent.3p b/man3p/getpwent.3p new file mode 100644 index 000000000..cf3e4cb27 --- /dev/null +++ b/man3p/getpwent.3p @@ -0,0 +1,131 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ENDPWENT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" endpwent +.SH NAME +endpwent, getpwent, setpwent \- user database functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void endpwent(void); +.br +struct passwd *getpwent(void); +.br +void setpwent(void); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +These functions shall retrieve information about users. +.LP +The \fIgetpwent\fP() function shall return a pointer to a structure +containing the broken-out fields of an entry in the user +database. Each entry in the user database contains a \fBpasswd\fP +structure. When first called, \fIgetpwent\fP() shall return a +pointer to a \fBpasswd\fP structure containing the first entry in +the user database. Thereafter, it shall return a pointer to a +\fBpasswd\fP structure containing the next entry in the user database. +Successive calls can be used to search the entire user +database. +.LP +If an end-of-file or an error is encountered on reading, \fIgetpwent\fP() +shall return a null pointer. +.LP +An implementation that provides extended security controls may impose +further implementation-defined restrictions on accessing +the user database. In particular, the system may deny the existence +of some or all of the user database entries associated with +users other than the caller. +.LP +The \fIsetpwent\fP() function effectively rewinds the user database +to allow repeated searches. +.LP +The \fIendpwent\fP() function may be called to close the user database +when processing is complete. +.LP +These functions need not be reentrant. A function that is not required +to be reentrant is not required to be thread-safe. +.SH RETURN VALUE +.LP +The \fIgetpwent\fP() function shall return a null pointer on end-of-file +or error. +.SH ERRORS +.LP +The \fIgetpwent\fP(), \fIsetpwent\fP(), and \fIendpwent\fP() functions +may fail if: +.TP 7 +.B EIO +An I/O error has occurred. +.sp +.LP +In addition, \fIgetpwent\fP() and \fIsetpwent\fP() may fail if: +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENFILE +The maximum allowable number of files is currently open in the system. +.sp +.LP +The return value may point to a static area which is overwritten by +a subsequent call to \fIgetpwuid\fP(), \fIgetpwnam\fP(), or +\fIgetpwent\fP(). +.br +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Searching the User Database +.LP +The following example uses the \fIgetpwent\fP() function to get successive +entries in the user database, returning a pointer to +a \fBpasswd\fP structure that contains information about each user. +The call to \fIendpwent\fP() closes the user database and +cleans up. +.sp +.RS +.nf + +\fB#include +\&... +struct passwd *p; +\&... +while ((p = getpwent ()) != NULL) { +\&... +} +.sp + +endpwent(); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +These functions are provided due to their historical usage. Applications +should avoid dependencies on fields in the password +database, whether the database is a single file, or where in the file +system name space the database resides. Applications should +use \fIgetpwuid\fP() whenever possible because it avoids these dependencies. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIendgrent\fP() , \fIgetlogin\fP() , \fIgetpwnam\fP() , \fIgetpwuid\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getpwnam.3p b/man3p/getpwnam.3p new file mode 100644 index 000000000..4cf45d84d --- /dev/null +++ b/man3p/getpwnam.3p @@ -0,0 +1,148 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETPWNAM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getpwnam +.SH NAME +getpwnam, getpwnam_r \- search user database for a name +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +struct passwd *getpwnam(const char *\fP\fIname\fP\fB); +.br +\fP +.LP +\fBint getpwnam_r(const char *\fP\fIname\fP\fB, struct passwd *\fP\fIpwd\fP\fB, +char +*\fP\fIbuffer\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIbufsize\fP\fB, struct passwd **\fP\fIresult\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetpwnam\fP() function shall search the user database for an +entry with a matching \fIname\fP. +.LP +The \fIgetpwnam\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.LP +Applications wishing to check for error situations should set \fIerrno\fP +to 0 before calling \fIgetpwnam\fP(). If +\fIgetpwnam\fP() returns a null pointer and \fIerrno\fP is non-zero, +an error occurred. +.LP +The \fIgetpwnam_r\fP() function shall update the \fBpasswd\fP structure +pointed to by \fIpwd\fP and store a pointer to that +structure at the location pointed to by \fIresult\fP. The structure +shall contain an entry from the user database with a matching +\fIname\fP. Storage referenced by the structure is allocated from +the memory provided with the \fIbuffer\fP parameter, which is +\fIbufsize\fP bytes in size. The maximum size needed for this buffer +can be determined with the {_SC_GETPW_R_SIZE_MAX} \fIsysconf\fP() +parameter. A NULL pointer shall be returned at the location pointed +to by +\fIresult\fP on error or if the requested entry is not found. +.SH RETURN VALUE +.LP +The \fIgetpwnam\fP() function shall return a pointer to a \fBstruct +passwd\fP with the structure as defined in \fI\fP with a matching +entry if found. A null pointer shall be returned if the requested +entry is not found, or an error occurs. On error, \fIerrno\fP shall +be set to indicate the error. +.LP +The return value may point to a static area which is overwritten by +a subsequent call to \fIgetpwent\fP(), \fIgetpwnam\fP(), or \fIgetpwuid\fP(). +.LP +If successful, the \fIgetpwnam_r\fP() function shall return zero; +otherwise, an error number shall be returned to indicate the +error. +.SH ERRORS +.LP +The \fIgetpwnam\fP() and \fIgetpwnam_r\fP() functions may fail if: +.TP 7 +.B EIO +An I/O error has occurred. +.TP 7 +.B EINTR +A signal was caught during \fIgetpwnam\fP(). +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENFILE +The maximum allowable number of files is currently open in the system. +.sp +.LP +The \fIgetpwnam_r\fP() function may fail if: +.TP 7 +.B ERANGE +Insufficient storage was supplied via \fIbuffer\fP and \fIbufsize\fP +to contain the data to be referenced by the resulting +\fBpasswd\fP structure. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Getting an Entry for the Login Name +.LP +The following example uses the \fIgetlogin\fP() function to return +the name of the +user who logged in; this information is passed to the \fIgetpwnam\fP() +function to get the user database entry for that user. +.sp +.RS +.nf + +\fB#include +#include +#include +#include +#include +\&... +char *lgn; +struct passwd *pw; +\&... +if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) { + fprintf(stderr, "Get of user information failed.\\n"); exit(1); +} +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +Three names associated with the current process can be determined: +\fIgetpwuid\fP( \fIgeteuid\fP()) returns the name associated with +the effective user ID of the process; \fIgetlogin\fP() returns the +name associated with the current login activity; and +\fIgetpwuid\fP( \fIgetuid\fP()) returns the name associated with the +real user ID of the +process. +.LP +The \fIgetpwnam_r\fP() function is thread-safe and returns values +in a user-supplied buffer instead of possibly using a static +data area that may be overwritten by each call. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetpwuid\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getpwnam_r.3p b/man3p/getpwnam_r.3p new file mode 100644 index 000000000..9ee0665d6 --- /dev/null +++ b/man3p/getpwnam_r.3p @@ -0,0 +1 @@ +.so man3p/getpwnam.3p diff --git a/man3p/getpwuid.3p b/man3p/getpwuid.3p new file mode 100644 index 000000000..9fef587df --- /dev/null +++ b/man3p/getpwuid.3p @@ -0,0 +1,191 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETPWUID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getpwuid +.SH NAME +getpwuid, getpwuid_r \- search user database for a user ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +struct passwd *getpwuid(uid_t\fP \fIuid\fP\fB); +.br +\fP +.LP +\fBint getpwuid_r(uid_t\fP \fIuid\fP\fB, struct passwd *\fP\fIpwd\fP\fB, +char +*\fP\fIbuffer\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIbufsize\fP\fB, struct passwd **\fP\fIresult\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetpwuid\fP() function shall search the user database for an +entry with a matching \fIuid\fP. +.LP +The \fIgetpwuid\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.LP +Applications wishing to check for error situations should set \fIerrno\fP +to 0 before calling \fIgetpwuid\fP(). If +\fIgetpwuid\fP() returns a null pointer and \fIerrno\fP is set to +non-zero, an error occurred. +.LP +The \fIgetpwuid_r\fP() function shall update the \fBpasswd\fP structure +pointed to by \fIpwd\fP and store a pointer to that +structure at the location pointed to by \fIresult\fP. The structure +shall contain an entry from the user database with a matching +\fIuid\fP. Storage referenced by the structure is allocated from the +memory provided with the \fIbuffer\fP parameter, which is +\fIbufsize\fP bytes in size. The maximum size needed for this buffer +can be determined with the {_SC_GETPW_R_SIZE_MAX} \fIsysconf\fP() +parameter. A NULL pointer shall be returned at the location pointed +to by +\fIresult\fP on error or if the requested entry is not found. +.SH RETURN VALUE +.LP +The \fIgetpwuid\fP() function shall return a pointer to a \fBstruct +passwd\fP with the structure as defined in \fI\fP with a matching +entry if found. A null pointer shall be returned if the requested +entry is not found, or an error occurs. On error, \fIerrno\fP shall +be set to indicate the error. +.LP +The return value may point to a static area which is overwritten by +a subsequent call to \fIgetpwent\fP(), \fIgetpwnam\fP(), or +\fIgetpwuid\fP(). +.LP +If successful, the \fIgetpwuid_r\fP() function shall return zero; +otherwise, an error number shall be returned to indicate the +error. +.SH ERRORS +.LP +The \fIgetpwuid\fP() and \fIgetpwuid_r\fP() functions may fail if: +.TP 7 +.B EIO +An I/O error has occurred. +.TP 7 +.B EINTR +A signal was caught during \fIgetpwuid\fP(). +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENFILE +The maximum allowable number of files is currently open in the system. +.sp +.LP +The \fIgetpwuid_r\fP() function may fail if: +.TP 7 +.B ERANGE +Insufficient storage was supplied via \fIbuffer\fP and \fIbufsize\fP +to contain the data to be referenced by the resulting +\fBpasswd\fP structure. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Getting an Entry for the Root User +.LP +The following example gets the user database entry for the user with +user ID 0 (root). +.sp +.RS +.nf + +\fB#include +#include +\&... +uid_t id = 0; +struct passwd *pwd; +.sp + +pwd = getpwuid(id); +\fP +.fi +.RE +.SS Finding the Name for the Effective User ID +.LP +The following example defines \fIpws\fP as a pointer to a structure +of type \fBpasswd\fP, which is used to store the structure +pointer returned by the call to the \fIgetpwuid\fP() function. The +\fIgeteuid\fP() +function shall return the effective user ID of the calling process; +this is used as the search criteria for the \fIgetpwuid\fP() +function. The call to \fIgetpwuid\fP() shall return a pointer to the +structure containing that user ID value. +.sp +.RS +.nf + +\fB#include +#include +#include +\&... +struct passwd *pws; +pws = getpwuid(geteuid()); +\fP +.fi +.RE +.SS Finding an Entry in the User Database +.LP +The following example uses \fIgetpwuid\fP() to search the user database +for a user ID that was previously stored in a +\fBstat\fP structure, then prints out the user name if it is found. +If the user is not found, the program prints the numeric value +of the user ID for the entry. +.sp +.RS +.nf + +\fB#include +#include +#include +\&... +struct stat statbuf; +struct passwd *pwd; +\&... +if ((pwd = getpwuid(statbuf.st_uid)) != NULL) + printf(" %-8.8s", pwd->pw_name); +else + printf(" %-8d", statbuf.st_uid); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +Three names associated with the current process can be determined: +\fIgetpwuid\fP( \fIgeteuid\fP()) returns the name associated with +the effective user ID of the process; \fIgetlogin\fP() returns the +name associated with the current login activity; and +\fIgetpwuid\fP( \fIgetuid\fP()) returns the name associated with the +real user ID of the +process. +.LP +The \fIgetpwuid_r\fP() function is thread-safe and returns values +in a user-supplied buffer instead of possibly using a static +data area that may be overwritten by each call. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetpwnam\fP() , \fIgeteuid\fP() , \fIgetuid\fP() , \fIgetlogin\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getpwuid_r.3p b/man3p/getpwuid_r.3p new file mode 100644 index 000000000..90e8a661a --- /dev/null +++ b/man3p/getpwuid_r.3p @@ -0,0 +1 @@ +.so man3p/getpwuid.3p diff --git a/man3p/getrlimit.3p b/man3p/getrlimit.3p new file mode 100644 index 000000000..f9dbba006 --- /dev/null +++ b/man3p/getrlimit.3p @@ -0,0 +1,189 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETRLIMIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getrlimit +.SH NAME +getrlimit, setrlimit \- control maximum resource consumption +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int getrlimit(int\fP \fIresource\fP\fB, struct rlimit *\fP\fIrlp\fP\fB); +.br +int setrlimit(int\fP \fIresource\fP\fB, const struct rlimit *\fP\fIrlp\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetrlimit\fP() function shall get, and the \fIsetrlimit\fP() +function shall set, limits on the consumption of a variety +of resources. +.LP +Each call to either \fIgetrlimit\fP() or \fIsetrlimit\fP() identifies +a specific resource to be operated upon as well as a +resource limit. A resource limit is represented by an \fBrlimit\fP +structure. The \fIrlim_cur\fP member specifies the current or +soft limit and the \fIrlim_max\fP member specifies the maximum or +hard limit. Soft limits may be changed by a process to any value +that is less than or equal to the hard limit. A process may (irreversibly) +lower its hard limit to any value that is greater than +or equal to the soft limit. Only a process with appropriate privileges +can raise a hard limit. Both hard and soft limits can be +changed in a single call to \fIsetrlimit\fP() subject to the constraints +described above. +.LP +The value RLIM_INFINITY, defined in \fI\fP, shall +be +considered to be larger than any other limit value. If a call to \fIgetrlimit\fP() +returns RLIM_INFINITY for a resource, it means +the implementation shall not enforce limits on that resource. Specifying +RLIM_INFINITY as any resource limit value on a successful +call to \fIsetrlimit\fP() shall inhibit enforcement of that resource +limit. +.LP +The following resources are defined: +.TP 7 +RLIMIT_CORE +This is the maximum size of a \fBcore\fP file, in bytes, that may +be created by a process. A limit of 0 shall prevent the +creation of a \fBcore\fP file. If this limit is exceeded, the writing +of a \fBcore\fP file shall terminate at this size. +.TP 7 +RLIMIT_CPU +This is the maximum amount of CPU time, in seconds, used by a process. +If this limit is exceeded, SIGXCPU shall be generated +for the process. If the process is catching or ignoring SIGXCPU, or +all threads belonging to that process are blocking SIGXCPU, the +behavior is unspecified. +.TP 7 +RLIMIT_DATA +This is the maximum size of a process' data segment, in bytes. If +this limit is exceeded, the \fImalloc\fP() function shall fail with +\fIerrno\fP set to [ENOMEM]. +.TP 7 +RLIMIT_FSIZE +This is the maximum size of a file, in bytes, that may be created +by a process. If a write or truncate operation would cause +this limit to be exceeded, SIGXFSZ shall be generated for the thread. +If the thread is blocking, or the process is catching or +ignoring SIGXFSZ, continued attempts to increase the size of a file +from end-of-file to beyond the limit shall fail with +\fIerrno\fP set to [EFBIG]. +.TP 7 +RLIMIT_NOFILE +This is a number one greater than the maximum value that the system +may assign to a newly-created descriptor. If this limit is +exceeded, functions that allocate a file descriptor shall fail with +\fIerrno\fP set to [EMFILE]. This limit constrains the number +of file descriptors that a process may allocate. +.TP 7 +RLIMIT_STACK +This is the maximum size of a process' stack, in bytes. The implementation +does not automatically grow the stack beyond this +limit. If this limit is exceeded, SIGSEGV shall be generated for the +thread. If the thread is blocking SIGSEGV, or the process is +ignoring or catching SIGSEGV and has not made arrangements to use +an alternate stack, the disposition of SIGSEGV shall be set to +SIG_DFL before it is generated. +.TP 7 +RLIMIT_AS +This is the maximum size of a process' total available memory, in +bytes. If this limit is exceeded, the \fImalloc\fP() and \fImmap\fP() +functions shall fail with +\fIerrno\fP set to [ENOMEM]. In addition, the automatic stack growth +fails with the effects outlined above. +.sp +.LP +When using the \fIgetrlimit\fP() function, if a resource limit can +be represented correctly in an object of type \fBrlim_t\fP, +then its representation is returned; otherwise, if the value of the +resource limit is equal to that of the corresponding saved hard +limit, the value returned shall be RLIM_SAVED_MAX; otherwise, the +value returned shall be RLIM_SAVED_CUR. +.LP +When using the \fIsetrlimit\fP() function, if the requested new limit +is RLIM_INFINITY, the new limit shall be "no limit''; +otherwise, if the requested new limit is RLIM_SAVED_MAX, the new limit +shall be the corresponding saved hard limit; otherwise, if +the requested new limit is RLIM_SAVED_CUR, the new limit shall be +the corresponding saved soft limit; otherwise, the new limit +shall be the requested value. In addition, if the corresponding saved +limit can be represented correctly in an object of type +\fBrlim_t\fP then it shall be overwritten with the new limit. +.LP +The result of setting a limit to RLIM_SAVED_MAX or RLIM_SAVED_CUR +is unspecified unless a previous call to \fIgetrlimit\fP() +returned that value as the soft or hard limit for the corresponding +resource limit. +.LP +The determination of whether a limit can be correctly represented +in an object of type \fBrlim_t\fP is implementation-defined. +For example, some implementations permit a limit whose value is greater +than RLIM_INFINITY and others do not. +.LP +The \fIexec\fP family of functions shall cause resource limits to +be saved. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetrlimit\fP() and \fIsetrlimit\fP() +shall return 0. Otherwise, these functions shall return -1 +and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIgetrlimit\fP() and \fIsetrlimit\fP() functions shall fail if: +.TP 7 +.B EINVAL +An invalid \fIresource\fP was specified; or in a \fIsetrlimit\fP() +call, the new \fIrlim_cur\fP exceeds the new +\fIrlim_max\fP. +.TP 7 +.B EPERM +The limit specified to \fIsetrlimit\fP() would have raised the maximum +limit value, and the calling process does not have +appropriate privileges. +.sp +.LP +The \fIsetrlimit\fP() function may fail if: +.TP 7 +.B EINVAL +The limit specified cannot be lowered because current usage is already +higher than the limit. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +If a process attempts to set the hard limit or soft limit for RLIMIT_NOFILE +to less than the value of {_POSIX_OPEN_MAX} from \fI\fP, +unexpected behavior may occur. +.LP +If a process attempts to set the hard limit or soft limit for RLIMIT_NOFILE +to less than the highest currently open file +descriptor +1, unexpected behavior may occur. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIfork\fP() , \fImalloc\fP() , \fIopen\fP() , \fIsigaltstack\fP() +, +\fIsysconf\fP() , \fIulimit\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getrusage.3p b/man3p/getrusage.3p new file mode 100644 index 000000000..1cfe2fa29 --- /dev/null +++ b/man3p/getrusage.3p @@ -0,0 +1,90 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETRUSAGE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getrusage +.SH NAME +getrusage \- get information about resource utilization +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int getrusage(int\fP \fIwho\fP\fB, struct rusage *\fP\fIr_usage\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetrusage\fP() function shall provide measures of the resources +used by the current process or its terminated and +waited-for child processes. If the value of the \fIwho\fP argument +is RUSAGE_SELF, information shall be returned about resources +used by the current process. If the value of the \fIwho\fP argument +is RUSAGE_CHILDREN, information shall be returned about +resources used by the terminated and waited-for children of the current +process. If the child is never waited for (for example, if +the parent has SA_NOCLDWAIT set or sets SIGCHLD to SIG_IGN), the resource +information for the child process is discarded and not +included in the resource information provided by \fIgetrusage\fP(). +.LP +The \fIr_usage\fP argument is a pointer to an object of type \fBstruct +rusage\fP in which the returned information is +stored. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetrusage\fP() shall return 0; otherwise, +-1 shall be returned and \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +The \fIgetrusage\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of the \fIwho\fP argument is not valid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Using getrusage() +.LP +The following example returns information about the resources used +by the current process. +.sp +.RS +.nf + +\fB#include +\&... +int who = RUSAGE_SELF; +struct rusage usage; +int ret; +.sp + +ret = getrusage(who, &usage); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexit\fP() , \fIsigaction\fP() , \fItime\fP() +, \fItimes\fP() , \fIwait\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/gets.3p b/man3p/gets.3p new file mode 100644 index 000000000..386eb7b91 --- /dev/null +++ b/man3p/gets.3p @@ -0,0 +1,78 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" gets +.SH NAME +gets \- get a string from a stdin stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *gets(char *\fP\fIs\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgets\fP() function shall read bytes from the standard input +stream, \fIstdin\fP, into the array pointed to by \fIs\fP, +until a is read or an end-of-file condition is encountered. +Any shall be discarded and a null byte +shall be placed immediately after the last byte read into the array. +.LP +The +\fIgets\fP() function may mark the \fIst_atime\fP field of the file +associated with \fIstream\fP for update. The \fIst_atime\fP +field shall be marked for update by the first successful execution +of \fIfgetc\fP(), \fIfgets\fP(), \fIfread\fP(), \fIgetc\fP(), \fIgetchar\fP(), +\fIgets\fP(), \fIfscanf\fP(), or \fIscanf\fP() using \fIstream\fP +that +returns data not supplied by a prior call to \fIungetc\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, \fIgets\fP() shall return \fIs\fP. If +the stream is at end-of-file, the end-of-file indicator for +the stream shall be set and \fIgets\fP() shall return a null pointer. +If a read error occurs, the error indicator for the stream +shall be set, \fIgets\fP() shall return a null pointer, \ and set +\fIerrno\fP to indicate the error. +.SH ERRORS +.LP +Refer to \fIfgetc\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Reading a line that overflows the array pointed to by \fIs\fP results +in undefined behavior. The use of \fIfgets\fP() is recommended. +.LP +Since the user cannot specify the length of the buffer passed to \fIgets\fP(), +use of this function is discouraged. The length +of the string read is unlimited. It is possible to overflow this buffer +in such a way as to cause applications to fail, or possible +system security violations. +.LP +It is recommended that the \fIfgets\fP() function should be used to +read input lines. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeof\fP() , \fIferror\fP() , \fIfgets\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getservbyname.3p b/man3p/getservbyname.3p new file mode 100644 index 000000000..dc6b5d8e9 --- /dev/null +++ b/man3p/getservbyname.3p @@ -0,0 +1 @@ +.so man3p/getservent.3p diff --git a/man3p/getservbyport.3p b/man3p/getservbyport.3p new file mode 100644 index 000000000..dc6b5d8e9 --- /dev/null +++ b/man3p/getservbyport.3p @@ -0,0 +1 @@ +.so man3p/getservent.3p diff --git a/man3p/getservent.3p b/man3p/getservent.3p new file mode 100644 index 000000000..9395f71d5 --- /dev/null +++ b/man3p/getservent.3p @@ -0,0 +1,114 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ENDSERVENT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" endservent +.SH NAME +endservent, getservbyname, getservbyport, getservent, setservent \- +network services database functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void endservent(void); +.br +struct servent *getservbyname(const char *\fP\fIname\fP\fB, const +char *\fP\fIproto\fP\fB); +.br +struct servent *getservbyport(int\fP \fIport\fP\fB, const char *\fP\fIproto\fP\fB); +.br +struct servent *getservent(void); +.br +void setservent(int\fP \fIstayopen\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall retrieve information about network services. +This information is considered to be stored in a database +that can be accessed sequentially or randomly. The implementation +of this database is unspecified. +.LP +The \fIsetservent\fP() function shall open a connection to the database, +and set the next entry to the first entry. If the +\fIstayopen\fP argument is non-zero, the \fInet\fP database shall +not be closed after each call to the \fIgetservent\fP() +function (either directly, or indirectly through one of the other +\fIgetserv*\fP() +functions), and the implementation may maintain an open file descriptor +for the database. +.LP +The \fIgetservent\fP() function shall read the next entry of the database, +opening and closing a connection to the database as +necessary. +.LP +The \fIgetservbyname\fP() function shall search the database from +the beginning and find the first entry for which the service +name specified by \fIname\fP matches the \fIs_name\fP member and the +protocol name specified by \fIproto\fP matches the +\fIs_proto\fP member, opening and closing a connection to the database +as necessary. If \fIproto\fP is a null pointer, any value +of the \fIs_proto\fP member shall be matched. +.LP +The \fIgetservbyport\fP() function shall search the database from +the beginning and find the first entry for which the port +specified by \fIport\fP matches the \fIs_port\fP member and the protocol +name specified by \fIproto\fP matches the +\fIs_proto\fP member, opening and closing a connection to the database +as necessary. If \fIproto\fP is a null pointer, any value +of the \fIs_proto\fP member shall be matched. The \fIport\fP argument +shall be in network byte order. +.LP +The \fIgetservbyname\fP(), \fIgetservbyport\fP(), and \fIgetservent\fP() +functions shall each return a pointer to a +\fBservent\fP structure, the members of which shall contain the fields +of an entry in the network services database. +.LP +The \fIendservent\fP() function shall close the database, releasing +any open file descriptor. +.LP +These functions need not be reentrant. A function that is not required +to be reentrant is not required to be thread-safe. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetservbyname\fP(), \fIgetservbyport\fP(), +and \fIgetservent\fP() return a pointer to a +\fBservent\fP structure if the requested entry was found, and a null +pointer if the end of the database was reached or the +requested entry was not found. Otherwise, a null pointer is returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIport\fP argument of \fIgetservbyport\fP() need not be compatible +with the port values of all address families. +.LP +The \fIgetservbyname\fP(), \fIgetservbyport\fP(), and \fIgetservent\fP() +functions may return pointers to static data, which +may be overwritten by subsequent calls to any of these functions. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIendhostent\fP() , \fIendprotoent\fP() , \fIhtonl\fP() , \fIinet_addr\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getsid.3p b/man3p/getsid.3p new file mode 100644 index 000000000..f0ecd7448 --- /dev/null +++ b/man3p/getsid.3p @@ -0,0 +1,68 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETSID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getsid +.SH NAME +getsid \- get the process group ID of a session leader +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +pid_t getsid(pid_t\fP \fIpid\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetsid\fP() function shall obtain the process group ID of the +process that is the session leader of the process +specified by \fIpid\fP. If \fIpid\fP is (\fBpid_t\fP)0, it specifies +the calling process. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetsid\fP() shall return the process +group ID of the session leader of the specified process. +Otherwise, it shall return (\fBpid_t\fP)-1 and set \fIerrno\fP to +indicate the error. +.SH ERRORS +.LP +The \fIgetsid\fP() function shall fail if: +.TP 7 +.B EPERM +The process specified by \fIpid\fP is not in the same session as the +calling process, and the implementation does not allow +access to the process group ID of the session leader of that process +from the calling process. +.TP 7 +.B ESRCH +There is no process with a process ID equal to \fIpid\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIfork\fP() , \fIgetpid\fP() , \fIgetpgid\fP() , \fIsetpgid\fP() +, \fIsetsid\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getsockname.3p b/man3p/getsockname.3p new file mode 100644 index 000000000..8c3fb0f6b --- /dev/null +++ b/man3p/getsockname.3p @@ -0,0 +1,90 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETSOCKNAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getsockname +.SH NAME +getsockname \- get the socket name +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int getsockname(int\fP \fIsocket\fP\fB, struct sockaddr *restrict\fP +\fIaddress\fP\fB, +.br +\ \ \ \ \ \ socklen_t *restrict\fP \fIaddress_len\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetsockname\fP() function shall retrieve the locally-bound +name of the specified socket, store this address in the +\fBsockaddr\fP structure pointed to by the \fIaddress\fP argument, +and store the length of this address in the object pointed to +by the \fIaddress_len\fP argument. +.LP +If the actual length of the address is greater than the length of +the supplied \fBsockaddr\fP structure, the stored address +shall be truncated. +.LP +If the socket has not been bound to a local name, the value stored +in the object pointed to by \fIaddress\fP is +unspecified. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned, the \fIaddress\fP +argument shall point to the address of the socket, and the +\fIaddress_len\fP argument shall point to the length of the address. +Otherwise, -1 shall be returned and \fIerrno\fP set to +indicate the error. +.SH ERRORS +.LP +The \fIgetsockname\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid file descriptor. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.TP 7 +.B EOPNOTSUPP +The operation is not supported for this socket's protocol. +.sp +.LP +The \fIgetsockname\fP() function may fail if: +.TP 7 +.B EINVAL +The socket has been shut down. +.TP 7 +.B ENOBUFS +Insufficient resources were available in the system to complete the +function. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIaccept\fP() , \fIbind\fP() , \fIgetpeername\fP() , \fIsocket\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getsockopt.3p b/man3p/getsockopt.3p new file mode 100644 index 000000000..c9e9f8bc1 --- /dev/null +++ b/man3p/getsockopt.3p @@ -0,0 +1,227 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETSOCKOPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getsockopt +.SH NAME +getsockopt \- get the socket options +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int getsockopt(int\fP \fIsocket\fP\fB, int\fP \fIlevel\fP\fB, int\fP +\fIoption_name,\fP\fB +.br +\ \ \ \ \ \ void *restrict\fP \fIoption_value\fP\fB, socklen_t *restrict\fP +\fIoption_len\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetsockopt\fP() function manipulates options associated with +a socket. +.LP +The \fIgetsockopt\fP() function shall retrieve the value for the option +specified by the \fIoption_name\fP argument for the +socket specified by the \fIsocket\fP argument. If the size of the +option value is greater than \fIoption_len\fP, the value stored +in the object pointed to by the \fIoption_value\fP argument shall +be silently truncated. Otherwise, the object pointed to by the +\fIoption_len\fP argument shall be modified to indicate the actual +length of the value. +.LP +The \fIlevel\fP argument specifies the protocol level at which the +option resides. To retrieve options at the socket level, +specify the \fIlevel\fP argument as SOL_SOCKET. To retrieve options +at other levels, supply the appropriate level identifier for +the protocol controlling the option. For example, to indicate that +an option is interpreted by the TCP (Transmission Control +Protocol), set \fIlevel\fP to IPPROTO_TCP as defined in the \fI\fP +header. +.LP +The socket in use may require the process to have appropriate privileges +to use the \fIgetsockopt\fP() function. +.LP +The \fIoption_name\fP argument specifies a single option to be retrieved. +It can be one of the following values defined in \fI\fP: +.TP 7 +SO_DEBUG +Reports whether debugging information is being recorded. This option +shall store an \fBint\fP value. This is a Boolean +option. +.TP 7 +SO_ACCEPTCONN +Reports whether socket listening is enabled. This option shall store +an \fBint\fP value. This is a Boolean option. +.TP 7 +SO_BROADCAST +Reports whether transmission of broadcast messages is supported, if +this is supported by the protocol. This option shall store +an \fBint\fP value. This is a Boolean option. +.TP 7 +SO_REUSEADDR +Reports whether the rules used in validating addresses supplied to +\fIbind\fP() should +allow reuse of local addresses, if this is supported by the protocol. +This option shall store an \fBint\fP value. This is a +Boolean option. +.TP 7 +SO_KEEPALIVE +Reports whether connections are kept active with periodic transmission +of messages, if this is supported by the protocol. +.LP +If the connected socket fails to respond to these messages, the connection +shall be broken and threads writing to that socket +shall be notified with a SIGPIPE signal. This option shall store an +\fBint\fP value. This is a Boolean option. +.TP 7 +SO_LINGER +Reports whether the socket lingers on \fIclose\fP() if data is present. +If SO_LINGER is +set, the system blocks the process during \fIclose\fP() until it can +transmit the data or +until the end of the interval indicated by the \fIl_linger\fP member, +whichever comes first. If SO_LINGER is not specified, and \fIclose\fP() +is issued, the system handles the call in a way that allows the process +to +continue as quickly as possible. This option shall store a \fBlinger\fP +structure. +.TP 7 +SO_OOBINLINE +Reports whether the socket leaves received out-of-band data (data +marked urgent) inline. This option shall store an \fBint\fP +value. This is a Boolean option. +.TP 7 +SO_SNDBUF +Reports send buffer size information. This option shall store an \fBint\fP +value. +.TP 7 +SO_RCVBUF +Reports receive buffer size information. This option shall store an +\fBint\fP value. +.TP 7 +SO_ERROR +Reports information about error status and clears it. This option +shall store an \fBint\fP value. +.TP 7 +SO_TYPE +Reports the socket type. This option shall store an \fBint\fP value. +Socket types are described in \fISocket Types\fP . +.TP 7 +SO_DONTROUTE +Reports whether outgoing messages bypass the standard routing facilities. +The destination shall be on a directly-connected +network, and messages are directed to the appropriate network interface +according to the destination address. The effect, if any, +of this option depends on what protocol is in use. This option shall +store an \fBint\fP value. This is a Boolean option. +.TP 7 +SO_RCVLOWAT +Reports the minimum number of bytes to process for socket input operations. +The default value for SO_RCVLOWAT is 1. If +SO_RCVLOWAT is set to a larger value, blocking receive calls normally +wait until they have received the smaller of the low water +mark value or the requested amount. (They may return less than the +low water mark if an error occurs, a signal is caught, or the +type of data next in the receive queue is different from that returned; +for example, out-of-band data.) This option shall store an +\fBint\fP value. Note that not all implementations allow this option +to be retrieved. +.TP 7 +SO_RCVTIMEO +Reports the timeout value for input operations. This option shall +store a \fBtimeval\fP structure with the number of seconds +and microseconds specifying the limit on how long to wait for an input +operation to complete. If a receive operation has blocked +for this much time without receiving additional data, it shall return +with a partial count or \fIerrno\fP set to [EAGAIN] or +[EWOULDBLOCK] if no data was received. The default for this option +is zero, which indicates that a receive operation shall not time +out. Note that not all implementations allow this option to be retrieved. +.TP 7 +SO_SNDLOWAT +Reports the minimum number of bytes to process for socket output operations. +Non-blocking output operations shall process no +data if flow control does not allow the smaller of the send low water +mark value or the entire request to be processed. This option +shall store an \fBint\fP value. Note that not all implementations +allow this option to be retrieved. +.TP 7 +SO_SNDTIMEO +Reports the timeout value specifying the amount of time that an output +function blocks because flow control prevents data from +being sent. If a send operation has blocked for this time, it shall +return with a partial count or with \fIerrno\fP set to +[EAGAIN] or [EWOULDBLOCK] if no data was sent. The default for this +option is zero, which indicates that a send operation shall not +time out. The option shall store a \fBtimeval\fP structure. Note that +not all implementations allow this option to be +retrieved. +.sp +.LP +For Boolean options, a zero value indicates that the option is disabled +and a non-zero value indicates that the option is +enabled. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetsockopt\fP() shall return 0; otherwise, +-1 shall be returned and \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +The \fIgetsockopt\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid file descriptor. +.TP 7 +.B EINVAL +The specified option is invalid at the specified socket level. +.TP 7 +.B ENOPROTOOPT +.sp +The option is not supported by the protocol. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.sp +.LP +The \fIgetsockopt\fP() function may fail if: +.TP 7 +.B EACCES +The calling process does not have the appropriate privileges. +.TP 7 +.B EINVAL +The socket has been shut down. +.TP 7 +.B ENOBUFS +Insufficient resources are available in the system to complete the +function. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIbind\fP() , \fIclose\fP() , \fIendprotoent\fP() , \fIsetsockopt\fP() +, \fIsocket\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getsubopt.3p b/man3p/getsubopt.3p new file mode 100644 index 000000000..0b3b8dbbf --- /dev/null +++ b/man3p/getsubopt.3p @@ -0,0 +1,215 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETSUBOPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getsubopt +.SH NAME +getsubopt \- parse suboption arguments from a string +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int getsubopt(char **\fP\fIoptionp\fP\fB, char * const *\fP\fIkeylistp\fP\fB, +char **\fP\fIvaluep\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetsubopt\fP() function shall parse suboption arguments in +a flag argument. Such options often result from the use of \fIgetopt\fP(). +.LP +The \fIgetsubopt\fP() argument \fIoptionp\fP is a pointer to a pointer +to the option argument string. The suboption arguments +shall be separated by commas and each may consist of either a single +token, or a token-value pair separated by an equal sign. +.LP +The \fIkeylistp\fP argument shall be a pointer to a vector of strings. +The end of the vector is identified by a null pointer. +Each entry in the vector is one of the possible tokens that might +be found in *\fIoptionp\fP. Since commas delimit suboption +arguments in \fIoptionp\fP, they should not appear in any of the strings +pointed to by \fIkeylistp\fP. Similarly, because an +equal sign separates a token from its value, the application should +not include an equal sign in any of the strings pointed to by +\fIkeylistp\fP. +.LP +The \fIvaluep\fP argument is the address of a value string pointer. +.LP +If a comma appears in \fIoptionp\fP, it shall be interpreted as a +suboption separator. After commas have been processed, if +there are one or more equal signs in a suboption string, the first +equal sign in any suboption string shall be interpreted as a +separator between a token and a value. Subsequent equal signs in a +suboption string shall be interpreted as part of the value. +.LP +If the string at *\fIoptionp\fP contains only one suboption argument +(equivalently, no commas), \fIgetsubopt\fP() shall update +*\fIoptionp\fP to point to the null character at the end of the string. +Otherwise, it shall isolate the suboption argument by +replacing the comma separator with a null character, and shall update +*\fIoptionp\fP to point to the start of the next suboption +argument. If the suboption argument has an associated value (equivalently, +contains an equal sign), \fIgetsubopt\fP() shall update +*\fIvaluep\fP to point to the value's first character. Otherwise, +it shall set *\fIvaluep\fP to a null pointer. The calling +application may use this information to determine whether the presence +or absence of a value for the suboption is an error. +.LP +Additionally, when \fIgetsubopt\fP() fails to match the suboption +argument with a token in the \fIkeylistp\fP array, the +calling application should decide if this is an error, or if the unrecognized +option should be processed in another way. +.SH RETURN VALUE +.LP +The \fIgetsubopt\fP() function shall return the index of the matched +token string, or -1 if no token strings were matched. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.sp +.RS +.nf + +\fB#include +#include +.sp + +int do_all; +const char *type; +int read_size; +int write_size; +int read_only; +.sp + +enum +{ + RO_OPTION = 0, + RW_OPTION, + READ_SIZE_OPTION, + WRITE_SIZE_OPTION +}; +.sp + +const char *mount_opts[] = +{ + [RO_OPTION] = "ro", + [RW_OPTION] = "rw", + [READ_SIZE_OPTION] = "rsize", + [WRITE_SIZE_OPTION] = "wsize", + NULL +}; +.sp + +int +main(int argc, char *argv[]) +{ + char *subopts, *value; + int opt; +.sp + + while ((opt = getopt(argc, argv, "at:o:")) != -1) + switch(opt) + { + case 'a': + do_all = 1; + break; + case 't': + type = optarg; + break; + case 'o': + subopts = optarg; + while (*subopts != '\\0') + switch(getsubopt(&subopts, mount_opts, &value)) + { + case RO_OPTION: + read_only = 1; + break; + case RW_OPTION: + read_only = 0; + break; + case READ_SIZE_OPTION: + if (value == NULL) + abort(); + read_size = atoi(value); + break; + case WRITE_SIZE_OPTION: + if (value == NULL) + abort(); + write_size = atoi(value); + break; + default: + /* Unknown suboption. */ + printf("Unknown suboption `%s'\\n", value); + break; + } + break; + default: + abort(); + } +.sp + + /* Do the real work. */ +.sp + + return 0; +} +\fP +.fi +.RE +.SS Parsing Suboptions +.LP +The following example uses the \fIgetsubopt\fP() function to parse +a \fIvalue\fP argument in the \fIoptarg\fP external +variable returned by a call to \fIgetopt\fP(). +.sp +.RS +.nf + +\fB#include +\&... +char *tokens[] = {"HOME", "PATH", "LOGNAME", (char *) NULL }; +char *value; +int opt, index; +.sp + +while ((opt = getopt(argc, argv, "e:")) != -1) { + switch(opt) { + case 'e' : + while ((index = getsubopt(&optarg, tokens, &value)) != -1) { + switch(index) { +\&... + } + break; +\&... + } +} +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetopt\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/gettimeofday.3p b/man3p/gettimeofday.3p new file mode 100644 index 000000000..11187d948 --- /dev/null +++ b/man3p/gettimeofday.3p @@ -0,0 +1,58 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETTIMEOFDAY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" gettimeofday +.SH NAME +gettimeofday \- get the date and time +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int gettimeofday(struct timeval *restrict\fP \fItp\fP\fB, void *restrict\fP +\fItzp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgettimeofday\fP() function shall obtain the current time, expressed +as seconds and microseconds since the Epoch, and +store it in the \fBtimeval\fP structure pointed to by \fItp\fP. The +resolution of the system clock is unspecified. +.LP +If \fItzp\fP is not a null pointer, the behavior is unspecified. +.SH RETURN VALUE +.LP +The \fIgettimeofday\fP() function shall return 0 and no value shall +be reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIctime\fP() , \fIftime\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getuid.3p b/man3p/getuid.3p new file mode 100644 index 000000000..efe2d7881 --- /dev/null +++ b/man3p/getuid.3p @@ -0,0 +1,69 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETUID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getuid +.SH NAME +getuid \- get a real user ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +uid_t getuid(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetuid\fP() function shall return the real user ID of the calling +process. +.SH RETURN VALUE +.LP +The \fIgetuid\fP() function shall always be successful and no return +value is reserved to indicate the error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Setting the Effective User ID to the Real User ID +.LP +The following example sets the effective user ID and the real user +ID of the current process to the real user ID of the +caller. +.sp +.RS +.nf + +\fB#include +#include +\&... +setreuid(getuid(), getuid()); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetegid\fP() , \fIgeteuid\fP() , \fIgetgid\fP() , \fIsetegid\fP() +, \fIseteuid\fP() , \fIsetgid\fP() , \fIsetregid\fP() , \fIsetreuid\fP() +, \fIsetuid\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getutxent.3p b/man3p/getutxent.3p new file mode 100644 index 000000000..f7769c373 --- /dev/null +++ b/man3p/getutxent.3p @@ -0,0 +1 @@ +.so man3p/getutxid.3p diff --git a/man3p/getutxid.3p b/man3p/getutxid.3p new file mode 100644 index 000000000..1b0d8feb5 --- /dev/null +++ b/man3p/getutxid.3p @@ -0,0 +1,199 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ENDUTXENT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" endutxent +.SH NAME +endutxent, getutxent, getutxid, getutxline, pututxline, setutxent +\- user accounting database functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void endutxent(void); +.br +struct utmpx *getutxent(void); +.br +struct utmpx *getutxid(const struct utmpx *\fP\fIid\fP\fB); +.br +struct utmpx *getutxline(const struct utmpx *\fP\fIline\fP\fB); +.br +struct utmpx *pututxline(const struct utmpx *\fP\fIutmpx\fP\fB); +.br +void setutxent(void); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +These functions shall provide access to the user accounting database. +.LP +The \fIgetutxent\fP() function shall read the next entry from the +user accounting database. If the database is not already +open, it shall open it. If it reaches the end of the database, it +shall fail. +.LP +The \fIgetutxid\fP() function shall search forward from the current +point in the database. If the \fIut_type\fP value of the +\fButmpx\fP structure pointed to by \fIid\fP is BOOT_TIME, OLD_TIME, +or NEW_TIME, then it shall stop when it finds an entry with +a matching \fIut_type\fP value. If the \fIut_type\fP value is INIT_PROCESS, +LOGIN_PROCESS, USER_PROCESS, or DEAD_PROCESS, then it +shall stop when it finds an entry whose type is one of these four +and whose \fIut_id\fP member matches the \fIut_id\fP member of +the \fButmpx\fP structure pointed to by \fIid\fP. If the end of the +database is reached without a match, \fIgetutxid\fP() shall +fail. +.LP +The \fIgetutxline\fP() function shall search forward from the current +point in the database until it finds an entry of the type +LOGIN_PROCESS or USER_PROCESS which also has a \fIut_line\fP value +matching that in the \fButmpx\fP structure pointed to by +\fIline\fP. If the end of the database is reached without a match, +\fIgetutxline\fP() shall fail. +.LP +The \fIgetutxid\fP() or \fIgetutxline\fP() function may cache data. +For this reason, to use \fIgetutxline\fP() to search for +multiple occurrences, the application shall zero out the static data +after each success, or \fIgetutxline\fP() may return a +pointer to the same \fButmpx\fP structure. +.LP +There is one exception to the rule about clearing the structure before +further reads are done. The implicit read done by +\fIpututxline\fP() (if it finds that it is not already at the correct +place in the user accounting database) shall not modify the +static structure returned by \fIgetutxent\fP(), \fIgetutxid\fP(), +or \fIgetutxline\fP(), if the application has modified this +structure and passed the pointer back to \fIpututxline\fP(). +.LP +For all entries that match a request, the \fIut_type\fP member indicates +the type of the entry. Other members of the entry +shall contain meaningful data based on the value of the \fIut_type\fP +member as follows: +.TS C +center; l lw(40). +\fBut_type Member\fP T{ +.na +\fBOther Members with Meaningful Data\fP +.ad +T} +EMPTY T{ +.na +No others +.ad +T} +BOOT_TIME T{ +.na +\fIut_tv\fP +.ad +T} +OLD_TIME T{ +.na +\fIut_tv\fP +.ad +T} +NEW_TIME T{ +.na +\fIut_tv\fP +.ad +T} +USER_PROCESS T{ +.na +\fIut_id\fP, \fIut_user\fP (login name of the user), \fIut_line\fP, \fIut_pid\fP, \fIut_tv\fP +.ad +T} +INIT_PROCESS T{ +.na +\fIut_id\fP, \fIut_pid\fP, \fIut_tv\fP +.ad +T} +LOGIN_PROCESS T{ +.na +\fIut_id\fP, \fIut_user\fP (implementation-defined name of the login process), \fIut_pid\fP, \fIut_tv\fP +.ad +T} +DEAD_PROCESS T{ +.na +\fIut_id\fP, \fIut_pid\fP, \fIut_tv\fP +.ad +T} +.TE +.LP +An implementation that provides extended security controls may impose +implementation-defined restrictions on accessing the user +accounting database. In particular, the system may deny the existence +of some or all of the user accounting database entries +associated with users other than the caller. +.LP +If the process has appropriate privileges, the \fIpututxline\fP() +function shall write out the structure into the user +accounting database. It shall use \fIgetutxid\fP() to search for a +record that satisfies the request. If this search succeeds, +then the entry shall be replaced. Otherwise, a new entry shall be +made at the end of the user accounting database. +.LP +The \fIendutxent\fP() function shall close the user accounting database. +.LP +The \fIsetutxent\fP() function shall reset the input to the beginning +of the database. This should be done before each search +for a new entry if it is desired that the entire database be examined. +.LP +These functions need not be reentrant. A function that is not required +to be reentrant is not required to be thread-safe. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgetutxent\fP(), \fIgetutxid\fP(), and +\fIgetutxline\fP() shall return a pointer to a +\fButmpx\fP structure containing a copy of the requested entry in +the user accounting database. Otherwise, a null pointer shall be +returned. +.LP +The return value may point to a static area which is overwritten by +a subsequent call to \fIgetutxid\fP() or +\fIgetutxline\fP(). +.LP +Upon successful completion, \fIpututxline\fP() shall return a pointer +to a \fButmpx\fP structure containing a copy of the +entry added to the user accounting database. Otherwise, a null pointer +shall be returned. +.LP +The \fIendutxent\fP() and \fIsetutxent\fP() functions shall not return +a value. +.SH ERRORS +.LP +No errors are defined for the \fIendutxent\fP(), \fIgetutxent\fP(), +\fIgetutxid\fP(), \fIgetutxline\fP(), and +\fIsetutxent\fP() functions. +.LP +The \fIpututxline\fP() function may fail if: +.TP 7 +.B EPERM +The process does not have appropriate privileges. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The sizes of the arrays in the structure can be found using the \fIsizeof\fP +operator. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getutxline.3p b/man3p/getutxline.3p new file mode 100644 index 000000000..f7769c373 --- /dev/null +++ b/man3p/getutxline.3p @@ -0,0 +1 @@ +.so man3p/getutxid.3p diff --git a/man3p/getwc.3p b/man3p/getwc.3p new file mode 100644 index 000000000..e21714b1b --- /dev/null +++ b/man3p/getwc.3p @@ -0,0 +1,60 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETWC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getwc +.SH NAME +getwc \- get a wide character from a stream +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +wint_t getwc(FILE *\fP\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetwc\fP() function shall be equivalent to \fIfgetwc\fP(), +except that if it is +implemented as a macro it may evaluate \fIstream\fP more than once, +so the argument should never be an expression with side +effects. +.SH RETURN VALUE +.LP +Refer to \fIfgetwc\fP() . +.SH ERRORS +.LP +Refer to \fIfgetwc\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Since it may be implemented as a macro, \fIgetwc\fP() may treat incorrectly +a \fIstream\fP argument with side effects. In +particular, \fIgetwc\fP(*\fIf\fP++) does not necessarily work as expected. +Therefore, use of this function is not recommended; \fIfgetwc\fP() +should be used instead. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfgetwc\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getwchar.3p b/man3p/getwchar.3p new file mode 100644 index 000000000..06f41fa79 --- /dev/null +++ b/man3p/getwchar.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETWCHAR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getwchar +.SH NAME +getwchar \- get a wide character from a stdin stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wint_t getwchar(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetwchar\fP() function shall be equivalent to \fIgetwc\fP(\fIstdin\fP). +.SH RETURN VALUE +.LP +Refer to \fIfgetwc\fP() . +.SH ERRORS +.LP +Refer to \fIfgetwc\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +If the \fBwint_t\fP value returned by \fIgetwchar\fP() is stored into +a variable of type \fBwchar_t\fP and then compared +against the \fBwint_t\fP macro WEOF, the result may be incorrect. +Only the \fBwint_t\fP type is guaranteed to be able to +represent any wide character and WEOF. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfgetwc\fP() , \fIgetwc\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/getwd.3p b/man3p/getwd.3p new file mode 100644 index 000000000..b5847d128 --- /dev/null +++ b/man3p/getwd.3p @@ -0,0 +1,74 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETWD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getwd +.SH NAME +getwd \- get the current working directory pathname (\fBLEGACY\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *getwd(char *\fP\fIpath_name\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetwd\fP() function shall determine an absolute pathname of +the current working directory of the calling process, and +copy a string containing that pathname into the array pointed to by +the \fIpath_name\fP argument. +.LP +If the length of the pathname of the current working directory is +greater than ({PATH_MAX}+1) including the null byte, +\fIgetwd\fP() shall fail and return a null pointer. +.SH RETURN VALUE +.LP +Upon successful completion, a pointer to the string containing the +absolute pathname of the current working directory shall be +returned. Otherwise, \fIgetwd\fP() shall return a null pointer and +the contents of the array pointed to by \fIpath_name\fP are +undefined. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +For applications portability, the \fIgetcwd\fP() function should be +used to determine +the current working directory instead of \fIgetwd\fP(). +.SH RATIONALE +.LP +Since the user cannot specify the length of the buffer passed to \fIgetwd\fP(), +use of this function is discouraged. The length +of a pathname described in {PATH_MAX} is file system-dependent and +may vary from one mount point to another, or might even be +unlimited. It is possible to overflow this buffer in such a way as +to cause applications to fail, or possible system security +violations. +.LP +It is recommended that the \fIgetcwd\fP() function should be used +to determine the +current working directory. +.SH FUTURE DIRECTIONS +.LP +This function may be withdrawn in a future version. +.SH SEE ALSO +.LP +\fIgetcwd\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/glob.3p b/man3p/glob.3p new file mode 100644 index 000000000..6ff132ca0 --- /dev/null +++ b/man3p/glob.3p @@ -0,0 +1,354 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GLOB" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" glob +.SH NAME +glob, globfree \- generate pathnames matching a pattern +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int glob(const char *restrict\fP \fIpattern\fP\fB, int\fP \fIflags\fP\fB, +.br +\ \ \ \ \ \ int(*\fP\fIerrfunc\fP\fB)(const char *\fP\fIepath\fP\fB, +int\fP +\fIeerrno\fP\fB), +.br +\ \ \ \ \ \ glob_t *restrict\fP \fIpglob\fP\fB); +.br +void globfree(glob_t *\fP\fIpglob\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIglob\fP() function is a pathname generator that shall implement +the rules defined in the Shell and Utilities volume of +IEEE\ Std\ 1003.1-2001, Section 2.13, Pattern Matching Notation, with +optional support for rule 3 in the Shell and Utilities volume of IEEE\ Std\ 1003.1-2001, +Section 2.13.3, Patterns Used for Filename Expansion. +.LP +The structure type \fBglob_t\fP is defined in \fI\fP and includes +at least +the following members: +.TS C +center; l1 l1 l. +\fBMember Type\fP \fBMember Name\fP \fBDescription\fP +\fBsize_t\fP \fIgl_pathc\fP Count of paths matched by \fIpattern\fP. +\fBchar **\fP \fIgl_pathv\fP Pointer to a list of matched pathnames. +\fBsize_t\fP \fIgl_offs\fP Slots to reserve at the beginning of \fIgl_pathv\fP. +.TE +.LP +The argument \fIpattern\fP is a pointer to a pathname pattern to be +expanded. The \fIglob\fP() function shall match all +accessible pathnames against this pattern and develop a list of all +pathnames that match. In order to have access to a pathname, +\fIglob\fP() requires search permission on every component of a path +except the last, and read permission on each directory of any +filename component of \fIpattern\fP that contains any of the following +special characters: \fB'*'\fP , \fB'?'\fP , and +\fB'['\fP . +.LP +The \fIglob\fP() function shall store the number of matched pathnames +into \fIpglob\fP->\fIgl_pathc\fP and a pointer to a +list of pointers to pathnames into \fIpglob\fP->\fIgl_pathv\fP. The +pathnames shall be in sort order as defined by the current +setting of the \fILC_COLLATE\fP category; see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 7.3.2, LC_COLLATE. The first +pointer after the last pathname shall be a null +pointer. If the pattern does not match any pathnames, the returned +number of matched paths is set to 0, and the contents of +\fIpglob\fP->\fIgl_pathv\fP are implementation-defined. +.LP +It is the caller's responsibility to create the structure pointed +to by \fIpglob\fP. The \fIglob\fP() function shall allocate +other space as needed, including the memory pointed to by \fIgl_pathv\fP. +The \fIglobfree\fP() function shall free any space +associated with \fIpglob\fP from a previous call to \fIglob\fP(). +.LP +The \fIflags\fP argument is used to control the behavior of \fIglob\fP(). +The value of \fIflags\fP is a bitwise-inclusive OR +of zero or more of the following constants, which are defined in \fI\fP: +.TP 7 +GLOB_APPEND +Append pathnames generated to the ones from a previous call to \fIglob\fP(). +.TP 7 +GLOB_DOOFFS +Make use of \fIpglob\fP->\fIgl_offs\fP. If this flag is set, \fIpglob\fP->\fIgl_offs\fP +is used to specify how many +null pointers to add to the beginning of \fIpglob\fP->\fIgl_pathv\fP. +In other words, \fIpglob\fP->\fIgl_pathv\fP shall +point to \fIpglob\fP->\fIgl_offs\fP null pointers, followed by \fIpglob\fP->\fIgl_pathc\fP +pathname pointers, followed by +a null pointer. +.TP 7 +GLOB_ERR +Cause \fIglob\fP() to return when it encounters a directory that it +cannot open or read. Ordinarily, \fIglob\fP() continues +to find matches. +.TP 7 +GLOB_MARK +Each pathname that is a directory that matches \fIpattern\fP shall +have a slash appended. +.TP 7 +GLOB_NOCHECK +Supports rule 3 in the Shell and Utilities volume of IEEE\ Std\ 1003.1-2001, +Section 2.13.3, Patterns Used for Filename Expansion. If \fIpattern\fP +does not +match any pathname, then \fIglob\fP() shall return a list consisting +of only \fIpattern\fP, and the number of matched pathnames +is 1. +.TP 7 +GLOB_NOESCAPE +Disable backslash escaping. +.TP 7 +GLOB_NOSORT +Ordinarily, \fIglob\fP() sorts the matching pathnames according to +the current setting of the \fILC_COLLATE\fP category; see +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 7.3.2, +LC_COLLATE. When this flag is used, the order of pathnames returned +is unspecified. +.sp +.LP +The GLOB_APPEND flag can be used to append a new set of pathnames +to those found in a previous call to \fIglob\fP(). The +following rules apply to applications when two or more calls to \fIglob\fP() +are made with the same value of \fIpglob\fP and +without intervening calls to \fIglobfree\fP(): +.IP " 1." 4 +The first such call shall not set GLOB_APPEND. All subsequent calls +shall set it. +.LP +.IP " 2." 4 +All the calls shall set GLOB_DOOFFS, or all shall not set it. +.LP +.IP " 3." 4 +After the second call, \fIpglob\fP->\fIgl_pathv\fP points to a list +containing the following: +.RS +.IP " a." 4 +Zero or more null pointers, as specified by GLOB_DOOFFS and \fIpglob\fP->\fIgl_offs\fP. +.LP +.IP " b." 4 +Pointers to the pathnames that were in the \fIpglob\fP->\fIgl_pathv\fP +list before the call, in the same order as +before. +.LP +.IP " c." 4 +Pointers to the new pathnames generated by the second call, in the +specified order. +.LP +.RE +.LP +.IP " 4." 4 +The count returned in \fIpglob\fP->\fIgl_pathc\fP shall be the total +number of pathnames from the two calls. +.LP +.IP " 5." 4 +The application can change any of the fields after a call to \fIglob\fP(). +If it does, the application shall reset them to the +original value before a subsequent call, using the same \fIpglob\fP +value, to \fIglobfree\fP() or \fIglob\fP() with the +GLOB_APPEND flag. +.LP +.LP +If, during the search, a directory is encountered that cannot be opened +or read and \fIerrfunc\fP is not a null pointer, +\fIglob\fP() calls (\fI*errfunc\fP()) with two arguments: +.IP " 1." 4 +The \fIepath\fP argument is a pointer to the path that failed. +.LP +.IP " 2." 4 +The \fIeerrno\fP argument is the value of \fIerrno\fP from the failure, +as set by \fIopendir\fP(), \fIreaddir\fP(), or \fIstat\fP(). (Other +values may be used to report other errors not explicitly documented +for those +functions.) +.LP +.LP +If (\fI*errfunc\fP()) is called and returns non-zero, or if the GLOB_ERR +flag is set in \fIflags\fP, \fIglob\fP() shall stop +the scan and return GLOB_ABORTED after setting \fIgl_pathc\fP and +\fIgl_pathv\fP in \fIpglob\fP to reflect the paths already +scanned. If GLOB_ERR is not set and either \fIerrfunc\fP is a null +pointer or (\fI*errfunc\fP()) returns 0, the error shall be +ignored. +.LP +The \fIglob\fP() function shall not fail because of large files. +.SH RETURN VALUE +.LP +Upon successful completion, \fIglob\fP() shall return 0. The argument +\fIpglob\fP->\fIgl_pathc\fP shall return the number +of matched pathnames and the argument \fIpglob\fP->\fIgl_pathv\fP +shall contain a pointer to a null-terminated list of matched +and sorted pathnames. However, if \fIpglob\fP->\fIgl_pathc\fP is 0, +the content of \fIpglob\fP->\fIgl_pathv\fP is +undefined. +.LP +The \fIglobfree\fP() function shall not return a value. +.LP +If \fIglob\fP() terminates due to an error, it shall return one of +the non-zero constants defined in \fI\fP. The arguments \fIpglob\fP->\fIgl_pathc\fP +and +\fIpglob\fP->\fIgl_pathv\fP are still set as defined above. +.SH ERRORS +.LP +The \fIglob\fP() function shall fail and return the corresponding +value if: +.TP 7 +GLOB_ABORTED +The scan was stopped because GLOB_ERR was set or (\fI*errfunc\fP()) +returned non-zero. +.TP 7 +GLOB_NOMATCH +The pattern does not match any existing pathname, and GLOB_NOCHECK +was not set in flags. +.TP 7 +GLOB_NOSPACE +An attempt to allocate memory failed. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +One use of the GLOB_DOOFFS flag is by applications that build an argument +list for use with \fIexecv\fP(), \fIexecve\fP(), or \fIexecvp\fP(). +Suppose, for example, that an application wants to do the equivalent +of: +.sp +.RS +.nf + +\fBls -l *.c +\fP +.fi +.RE +.LP +but for some reason: +.sp +.RS +.nf + +\fBsystem("ls -l *.c") +\fP +.fi +.RE +.LP +is not acceptable. The application could obtain approximately the +same result using the sequence: +.sp +.RS +.nf + +\fBglobbuf.gl_offs = 2; +glob("*.c", GLOB_DOOFFS, NULL, &globbuf); +globbuf.gl_pathv[0] = "ls"; +globbuf.gl_pathv[1] = "-l"; +execvp("ls", &globbuf.gl_pathv[0]); +\fP +.fi +.RE +.LP +Using the same example: +.sp +.RS +.nf + +\fBls -l *.c *.h +\fP +.fi +.RE +.LP +could be approximately simulated using GLOB_APPEND as follows: +.sp +.RS +.nf + +\fBglobbuf.gl_offs = 2; +glob("*.c", GLOB_DOOFFS, NULL, &globbuf); +glob("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +This function is not provided for the purpose of enabling utilities +to perform pathname expansion on their arguments, as this +operation is performed by the shell, and utilities are explicitly +not expected to redo this. Instead, it is provided for +applications that need to do pathname expansion on strings obtained +from other sources, such as a pattern typed by a user or read +from a file. +.LP +If a utility needs to see if a pathname matches a given pattern, it +can use \fIfnmatch\fP(). +.LP +Note that \fIgl_pathc\fP and \fIgl_pathv\fP have meaning even if \fIglob\fP() +fails. This allows \fIglob\fP() to report +partial results in the event of an error. However, if \fIgl_pathc\fP +is 0, \fIgl_pathv\fP is unspecified even if \fIglob\fP() +did not return an error. +.LP +The GLOB_NOCHECK option could be used when an application wants to +expand a pathname if wildcards are specified, but wants to +treat the pattern as just a string otherwise. The \fIsh\fP utility +might use this for +option-arguments, for example. +.LP +The new pathnames generated by a subsequent call with GLOB_APPEND +are not sorted together with the previous pathnames. This +mirrors the way that the shell handles pathname expansion when multiple +expansions are done on a command line. +.LP +Applications that need tilde and parameter expansion should use \fIwordexp\fP(). +.SH RATIONALE +.LP +It was claimed that the GLOB_DOOFFS flag is unnecessary because it +could be simulated using: +.sp +.RS +.nf + +\fBnew = (char **)malloc((n + pglob->gl_pathc + 1) + * sizeof(char *)); +(void) memcpy(new+n, pglob->gl_pathv, + pglob->gl_pathc * sizeof(char *)); +(void) memset(new, 0, n * sizeof(char *)); +free(pglob->gl_pathv); +pglob->gl_pathv = new; +\fP +.fi +.RE +.LP +However, this assumes that the memory pointed to by \fIgl_pathv\fP +is a block that was separately created using \fImalloc\fP(). This +is not necessarily the case. An application should make no assumptions +about +how the memory referenced by fields in \fIpglob\fP was allocated. +It might have been obtained from \fImalloc\fP() in a large chunk and +then carved up within \fIglob\fP(), or it might have been +created using a different memory allocator. It is not the intent of +the standard developers to specify or imply how the memory used +by \fIglob\fP() is managed. +.LP +The GLOB_APPEND flag would be used when an application wants to expand +several different patterns into a single list. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIfnmatch\fP() , \fIopendir\fP() , \fIreaddir\fP() +, \fIstat\fP() , \fIwordexp\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, the Shell and Utilities volume +of IEEE\ Std\ 1003.1-2001 +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/globfree.3p b/man3p/globfree.3p new file mode 100644 index 000000000..7978c329c --- /dev/null +++ b/man3p/globfree.3p @@ -0,0 +1 @@ +.so man3p/glob.3p diff --git a/man3p/gmtime.3p b/man3p/gmtime.3p new file mode 100644 index 000000000..c61a16a65 --- /dev/null +++ b/man3p/gmtime.3p @@ -0,0 +1,114 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GMTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" gmtime +.SH NAME +gmtime, gmtime_r \- convert a time value to a broken-down UTC time +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +struct tm *gmtime(const time_t *\fP\fItimer\fP\fB); +.br +\fP +.LP +\fBstruct tm *gmtime_r(const time_t *restrict\fP \fItimer\fP\fB, +.br +\ \ \ \ \ \ struct tm *restrict\fP \fIresult\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +For \fIgmtime\fP(): The functionality described on this reference +page is aligned with the ISO\ C standard. Any +conflict between the requirements described here and the ISO\ C standard +is unintentional. This volume of +IEEE\ Std\ 1003.1-2001 defers to the ISO\ C standard. +.LP +The \fIgmtime\fP() function shall convert the time in seconds since +the Epoch pointed to by \fItimer\fP into a broken-down +time, expressed as Coordinated Universal Time (UTC). +.LP +The +relationship between a time in seconds since the Epoch used as an +argument to \fIgmtime\fP() and the \fBtm\fP structure (defined +in the \fI\fP header) is that the result shall be as specified +in the +expression given in the definition of seconds since the Epoch (see +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 4.14, Seconds Since the Epoch), where the names in the structure +and in +the expression correspond. +.LP +The same relationship shall apply for \fIgmtime_r\fP(). +.LP +The +\fIgmtime\fP() function need not be reentrant. A function that is +not required to be reentrant is not required to be +thread-safe. +.LP +The \fIasctime\fP(), \fIctime\fP(), +\fIgmtime\fP(), and \fIlocaltime\fP() functions shall return values +in one of two +static objects: a broken-down time structure and an array of type +\fBchar\fP. Execution of any of the functions may overwrite the +information returned in either of these objects by any of the other +functions. +.LP +The \fIgmtime_r\fP() function shall convert the time in seconds since +the Epoch pointed to by \fItimer\fP into a broken-down time +expressed as Coordinated Universal Time (UTC). The broken-down time +is stored in the structure referred to by \fIresult\fP. The +\fIgmtime_r\fP() function shall also return the address of the same +structure. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIgmtime\fP() function shall return +a pointer to a \fBstruct tm\fP. If an error is detected, +\fIgmtime\fP() shall return a null pointer \ and set \fIerrno\fP +to indicate the error. +.LP +Upon successful completion, \fIgmtime_r\fP() shall return the address +of the structure pointed to by the argument \fIresult\fP. +If an error is detected, \fIgmtime_r\fP() shall return a null pointer. +.SH ERRORS +.LP +The \fIgmtime\fP() function shall fail if: +.TP 7 +.B EOVERFLOW +The result cannot be represented. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIgmtime_r\fP() function is thread-safe and returns values in +a user-supplied buffer instead of possibly using a static +data area that may be overwritten by each call. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIasctime\fP() , \fIclock\fP() , \fIctime\fP() +, \fIdifftime\fP() , \fIlocaltime\fP() , \fImktime\fP() , \fIstrftime\fP() +, \fIstrptime\fP() , +\fItime\fP() , \fIutime\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/gmtime_r.3p b/man3p/gmtime_r.3p new file mode 100644 index 000000000..e3268573f --- /dev/null +++ b/man3p/gmtime_r.3p @@ -0,0 +1 @@ +.so man3p/gmtime.3p diff --git a/man3p/grantpt.3p b/man3p/grantpt.3p new file mode 100644 index 000000000..5c1a7455c --- /dev/null +++ b/man3p/grantpt.3p @@ -0,0 +1,75 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GRANTPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" grantpt +.SH NAME +grantpt \- grant access to the slave pseudo-terminal device +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int grantpt(int\fP \fIfildes\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgrantpt\fP() function shall change the mode and ownership of +the slave pseudo-terminal device associated with its master +pseudo-terminal counterpart. The \fIfildes\fP argument is a file descriptor +that refers to a master pseudo-terminal device. The +user ID of the slave shall be set to the real UID of the calling process +and the group ID shall be set to an unspecified group ID. +The permission mode of the slave pseudo-terminal shall be set to readable +and writable by the owner, and writable by the group. +.LP +The behavior of the \fIgrantpt\fP() function is unspecified if the +application has installed a signal handler to catch SIGCHLD +signals. +.SH RETURN VALUE +.LP +Upon successful completion, \fIgrantpt\fP() shall return 0; otherwise, +it shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fIgrantpt\fP() function may fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid open file descriptor. +.TP 7 +.B EINVAL +The \fIfildes\fP argument is not associated with a master pseudo-terminal +device. +.TP 7 +.B EACCES +The corresponding slave pseudo-terminal device could not be accessed. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIopen\fP() , \fIptsname\fP() , \fIunlockpt\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/h_errno.3p b/man3p/h_errno.3p new file mode 100644 index 000000000..2800fdc22 --- /dev/null +++ b/man3p/h_errno.3p @@ -0,0 +1,57 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "H_ERRNO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" h_errno +.SH NAME +h_errno \- error return value for network database operations +.SH SYNOPSIS +.LP +\fB#include \fP +.SH DESCRIPTION +.LP +This method of returning errors is used only in connection with obsolescent +functions. +.LP +The \fI\fP header provides a declaration of \fIh_errno\fP +as a +modifiable lvalue of type \fBint\fP. +.LP +It is unspecified whether \fIh_errno\fP is a macro or an identifier +declared with external linkage. If a macro definition is +suppressed in order to access an actual object, or a program defines +an identifier with the name \fIh_errno\fP, the behavior is +undefined. +.SH RETURN VALUE +.LP +None. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications should obtain the definition of \fIh_errno\fP by the +inclusion of the \fI\fP header. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +\fIh_errno\fP may be withdrawn in a future version. +.SH SEE ALSO +.LP +\fIendhostent\fP() , \fIerrno\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/hcreate.3p b/man3p/hcreate.3p new file mode 100644 index 000000000..ef65c3198 --- /dev/null +++ b/man3p/hcreate.3p @@ -0,0 +1,175 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "HCREATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" hcreate +.SH NAME +hcreate, hdestroy, hsearch \- manage hash search table +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int hcreate(size_t\fP \fInel\fP\fB); +.br +void hdestroy(void); +.br +ENTRY *hsearch(ENTRY\fP \fIitem\fP\fB, ACTION\fP \fIaction\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIhcreate\fP(), \fIhdestroy\fP(), and \fIhsearch\fP() functions +shall manage hash search tables. +.LP +The \fIhcreate\fP() function shall allocate sufficient space for the +table, and the application shall ensure it is called +before \fIhsearch\fP() is used. The \fInel\fP argument is an estimate +of the maximum number of entries that the table shall +contain. This number may be adjusted upward by the algorithm in order +to obtain certain mathematically favorable circumstances. +.LP +The \fIhdestroy\fP() function shall dispose of the search table, and +may be followed by another call to \fIhcreate\fP(). After +the call to \fIhdestroy\fP(), the data can no longer be considered +accessible. +.LP +The \fIhsearch\fP() function is a hash-table search routine. It shall +return a pointer into a hash table indicating the +location at which an entry can be found. The \fIitem\fP argument is +a structure of type \fBENTRY\fP (defined in the \fI\fP header) +containing two pointers: \fIitem.key\fP points to the comparison +key (a \fBchar *\fP), and \fIitem.data\fP (a \fBvoid *\fP) points +to any other data to be associated with that key. The +comparison function used by \fIhsearch\fP() is \fIstrcmp\fP(). The +\fIaction\fP argument +is a member of an enumeration type \fBACTION\fP indicating the disposition +of the entry if it cannot be found in the table. ENTER +indicates that the item should be inserted in the table at an appropriate +point. FIND indicates that no entry should be made. +Unsuccessful resolution is indicated by the return of a null pointer. +.LP +These functions need not be reentrant. A function that is not required +to be reentrant is not required to be thread-safe. +.SH RETURN VALUE +.LP +The \fIhcreate\fP() function shall return 0 if it cannot allocate +sufficient space for the table; otherwise, it shall return +non-zero. +.LP +The \fIhdestroy\fP() function shall not return a value. +.LP +The \fIhsearch\fP() function shall return a null pointer if either +the action is FIND and the item could not be found or the +action is ENTER and the table is full. +.SH ERRORS +.LP +The \fIhcreate\fP() and \fIhsearch\fP() functions may fail if: +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The following example reads in strings followed by two numbers and +stores them in a hash table, discarding duplicates. It then +reads in strings and finds the matching entry in the hash table and +prints it out. +.sp +.RS +.nf + +\fB#include +#include +#include +.sp + +struct info { /* This is the info stored in the table */ + int age, room; /* other than the key. */ +}; +.sp + +#define NUM_EMPL 5000 /* # of elements in search table. */ + +.sp + +int main(void) +{ + char string_space[NUM_EMPL*20]; /* Space to store strings. */ + struct info info_space[NUM_EMPL]; /* Space to store employee info. */ + char *str_ptr = string_space; /* Next space in string_space. */ + struct info *info_ptr = info_space; + /* Next space in info_space. */ + ENTRY item; + ENTRY *found_item; /* Name to look for in table. */ + char name_to_find[30]; +.sp + + int i = 0; +.sp + + /* Create table; no error checking is performed. */ + (void) hcreate(NUM_EMPL); + while (scanf("%s%d%d", str_ptr, &info_ptr->age, + &info_ptr->room) != EOF && i++ < NUM_EMPL) { +.sp + + /* Put information in structure, and structure in item. */ + item.key = str_ptr; + item.data = info_ptr; + str_ptr += strlen(str_ptr) + 1; + info_ptr++; +.sp + + /* Put item into table. */ + (void) hsearch(item, ENTER); + } +.sp + + /* Access table. */ + item.key = name_to_find; + while (scanf("%s", item.key) != EOF) { + if ((found_item = hsearch(item, FIND)) != NULL) { +.sp + + /* If item is in the table. */ + (void)printf("found %s, age = %d, room = %d\\n", + found_item->key, + ((struct info *)found_item->data)->age, + ((struct info *)found_item->data)->room); + } else + (void)printf("no such employee %s\\n", name_to_find); + } + return 0; +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIhcreate\fP() and \fIhsearch\fP() functions may use \fImalloc\fP() +to allocate +space. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIbsearch\fP() , \fIlsearch\fP() , \fImalloc\fP() , \fIstrcmp\fP() +, \fItsearch\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/hdestroy.3p b/man3p/hdestroy.3p new file mode 100644 index 000000000..febf98552 --- /dev/null +++ b/man3p/hdestroy.3p @@ -0,0 +1 @@ +.so man3p/hcreate.3p diff --git a/man3p/hsearch.3p b/man3p/hsearch.3p new file mode 100644 index 000000000..febf98552 --- /dev/null +++ b/man3p/hsearch.3p @@ -0,0 +1 @@ +.so man3p/hcreate.3p diff --git a/man3p/htonl.3p b/man3p/htonl.3p new file mode 100644 index 000000000..d3309c110 --- /dev/null +++ b/man3p/htonl.3p @@ -0,0 +1,67 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "HTONL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" htonl +.SH NAME +htonl, htons, ntohl, ntohs \- convert values between host and network +byte order +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +uint32_t htonl(uint32_t\fP \fIhostlong\fP\fB); +.br +uint16_t htons(uint16_t\fP \fIhostshort\fP\fB); +.br +uint32_t ntohl(uint32_t\fP \fInetlong\fP\fB); +.br +uint16_t ntohs(uint16_t\fP \fInetshort\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall convert 16-bit and 32-bit quantities between +network byte order and host byte order. +.LP +On some implementations, these functions are defined as macros. +.LP +The \fBuint32_t\fP and \fBuint16_t\fP types are defined in \fI\fP. +.SH RETURN VALUE +.LP +The \fIhtonl\fP() and \fIhtons\fP() functions shall return the argument +value converted from host to network byte order. +.LP +The \fIntohl\fP() and \fIntohs\fP() functions shall return the argument +value converted from network to host byte order. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +These functions are most often used in conjunction with IPv4 addresses +and ports as returned by \fIgethostent\fP() and \fIgetservent\fP(). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIendhostent\fP() , \fIendservent\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/htons.3p b/man3p/htons.3p new file mode 100644 index 000000000..6bb3f2de9 --- /dev/null +++ b/man3p/htons.3p @@ -0,0 +1 @@ +.so man3p/htonl.3p diff --git a/man3p/hypot.3p b/man3p/hypot.3p new file mode 100644 index 000000000..03ab0efe7 --- /dev/null +++ b/man3p/hypot.3p @@ -0,0 +1,117 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "HYPOT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" hypot +.SH NAME +hypot, hypotf, hypotl \- Euclidean distance function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double hypot(double\fP \fIx\fP\fB, double\fP \fIy\fP\fB); +.br +float hypotf(float\fP \fIx\fP\fB, float\fP \fIy\fP\fB); +.br +long double hypotl(long double\fP \fIx\fP\fB, long double\fP \fIy\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the value of the square root of \fIx\fP**2+ +\fIy\fP**2 without undue overflow or underflow. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the length +of the hypotenuse of a right-angled triangle with sides of +length \fIx\fP and \fIy\fP. +.LP +If the correct value would cause overflow, a range error shall occur +and \fIhypot\fP(), \fIhypotf\fP(), and \fIhypotl\fP() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.LP +If +\fIx\fP or \fIy\fP is \(+-Inf, +Inf shall be returned (even if one +of \fIx\fP or \fIy\fP is NaN). +.LP +If \fIx\fP or \fIy\fP is NaN, and the other is not \(+-Inf, a NaN +shall be returned. +.LP +If both arguments are subnormal and the correct result is subnormal, +a range error may occur and the correct result is returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Range\ Error +The result overflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be +raised. +.sp +.LP +These functions may fail if: +.TP 7 +Range\ Error +The result underflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +\fIhypot\fP(\fIx\fP,\fIy\fP), \fIhypot\fP(\fIy\fP,\fIx\fP), and \fIhypot\fP(\fIx\fP, +-\fIy\fP) are equivalent. +.LP +\fIhypot\fP(\fIx\fP, \(+-0) is equivalent to \fIfabs\fP(\fIx\fP). +.LP +Underflow only happens when both \fIx\fP and \fIy\fP are subnormal +and the (inexact) result is also subnormal. +.LP +These functions take precautions against overflow during intermediate +steps of the computation. +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() , \fIsqrt\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/hypotf.3p b/man3p/hypotf.3p new file mode 100644 index 000000000..c650fa0a8 --- /dev/null +++ b/man3p/hypotf.3p @@ -0,0 +1 @@ +.so man3p/hypot.3p diff --git a/man3p/hypotl.3p b/man3p/hypotl.3p new file mode 100644 index 000000000..c650fa0a8 --- /dev/null +++ b/man3p/hypotl.3p @@ -0,0 +1 @@ +.so man3p/hypot.3p diff --git a/man3p/iconv.3p b/man3p/iconv.3p new file mode 100644 index 000000000..67ccf3912 --- /dev/null +++ b/man3p/iconv.3p @@ -0,0 +1,167 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ICONV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iconv +.SH NAME +iconv \- codeset conversion function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t iconv(iconv_t\fP \fIcd\fP\fB, char **restrict\fP \fIinbuf\fP\fB, +.br +\ \ \ \ \ \ size_t *restrict\fP \fIinbytesleft\fP\fB, char **restrict\fP +\fIoutbuf\fP\fB, +.br +\ \ \ \ \ \ size_t *restrict\fP \fIoutbytesleft\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIiconv\fP() function shall convert the sequence of characters +from one codeset, in the array specified by \fIinbuf\fP, +into a sequence of corresponding characters in another codeset, in +the array specified by \fIoutbuf\fP. The codesets are those +specified in the \fIiconv_open\fP() call that returned the conversion +descriptor, +\fIcd\fP. The \fIinbuf\fP argument points to a variable that points +to the first character in the input buffer and +\fIinbytesleft\fP indicates the number of bytes to the end of the +buffer to be converted. The \fIoutbuf\fP argument points to a +variable that points to the first available byte in the output buffer +and \fIoutbytesleft\fP indicates the number of the available +bytes to the end of the buffer. +.LP +For state-dependent encodings, the conversion descriptor \fIcd\fP +is placed into its initial shift state by a call for which +\fIinbuf\fP is a null pointer, or for which \fIinbuf\fP points to +a null pointer. When \fIiconv\fP() is called in this way, and +if \fIoutbuf\fP is not a null pointer or a pointer to a null pointer, +and \fIoutbytesleft\fP points to a positive value, +\fIiconv\fP() shall place, into the output buffer, the byte sequence +to change the output buffer to its initial shift state. If +the output buffer is not large enough to hold the entire reset sequence, +\fIiconv\fP() shall fail and set \fIerrno\fP to [E2BIG]. +Subsequent calls with \fIinbuf\fP as other than a null pointer or +a pointer to a null pointer cause the conversion to take place +from the current state of the conversion descriptor. +.LP +If a sequence of input bytes does not form a valid character in the +specified codeset, conversion shall stop after the previous +successfully converted character. If the input buffer ends with an +incomplete character or shift sequence, conversion shall stop +after the previous successfully converted bytes. If the output buffer +is not large enough to hold the entire converted input, +conversion shall stop just prior to the input bytes that would cause +the output buffer to overflow. The variable pointed to by +\fIinbuf\fP shall be updated to point to the byte following the last +byte successfully used in the conversion. The value pointed +to by \fIinbytesleft\fP shall be decremented to reflect the number +of bytes still not converted in the input buffer. The variable +pointed to by \fIoutbuf\fP shall be updated to point to the byte following +the last byte of converted output data. The value +pointed to by \fIoutbytesleft\fP shall be decremented to reflect the +number of bytes still available in the output buffer. For +state-dependent encodings, the conversion descriptor shall be updated +to reflect the shift state in effect at the end of the last +successfully converted byte sequence. +.LP +If \fIiconv\fP() encounters a character in the input buffer that is +valid, but for which an identical character does not exist +in the target codeset, \fIiconv\fP() shall perform an implementation-defined +conversion on this character. +.SH RETURN VALUE +.LP +The \fIiconv\fP() function shall update the variables pointed to by +the arguments to reflect the extent of the conversion and +return the number of non-identical conversions performed. If the entire +string in the input buffer is converted, the value pointed +to by \fIinbytesleft\fP shall be 0. If the input conversion is stopped +due to any conditions mentioned above, the value pointed to +by \fIinbytesleft\fP shall be non-zero and \fIerrno\fP shall be set +to indicate the condition. If an error occurs, \fIiconv\fP() +shall return (\fBsize_t\fP)-1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fIiconv\fP() function shall fail if: +.TP 7 +.B EILSEQ +Input conversion stopped due to an input byte that does not belong +to the input codeset. +.TP 7 +.B E2BIG +Input conversion stopped due to lack of space in the output buffer. +.TP 7 +.B EINVAL +Input conversion stopped due to an incomplete character or shift sequence +at the end of the input buffer. +.sp +.LP +The \fIiconv\fP() function may fail if: +.TP 7 +.B EBADF +The \fIcd\fP argument is not a valid open conversion descriptor. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIinbuf\fP argument indirectly points to the memory area which +contains the conversion input data. The \fIoutbuf\fP +argument indirectly points to the memory area which is to contain +the result of the conversion. The objects indirectly pointed to +by \fIinbuf\fP and \fIoutbuf\fP are not restricted to containing data +that is directly representable in the ISO\ C standard +language \fBchar\fP data type. The type of \fIinbuf\fP and \fIoutbuf\fP, +\fBchar **\fP, does not imply that the objects pointed +to are interpreted as null-terminated C strings or arrays of characters. +Any interpretation of a byte sequence that represents a +character in a given character set encoding scheme is done internally +within the codeset converters. For example, the area pointed +to indirectly by \fIinbuf\fP and/or \fIoutbuf\fP can contain all zero +octets that are not interpreted as string terminators but +as coded character data according to the respective codeset encoding +scheme. The type of the data ( \fBchar\fP, \fBshort\fP, +\fBlong\fP, and so on) read or stored in the objects is not specified, +but may be inferred for both the input and output data by +the converters determined by the \fIfromcode\fP and \fItocode\fP arguments +of \fIiconv_open\fP(). +.LP +Regardless of the data type inferred by the converter, the size of +the remaining space in both input and output objects (the +\fIintbytesleft\fP and \fIoutbytesleft\fP arguments) is always measured +in bytes. +.LP +For implementations that support the conversion of state-dependent +encodings, the conversion descriptor must be able to +accurately reflect the shift-state in effect at the end of the last +successful conversion. It is not required that the conversion +descriptor itself be updated, which would require it to be a pointer +type. Thus, implementations are free to implement the +descriptor as a handle (other than a pointer type) by which the conversion +information can be accessed and updated. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiconv_open\fP() , \fIiconv_close\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/iconv_close.3p b/man3p/iconv_close.3p new file mode 100644 index 000000000..21d8c3054 --- /dev/null +++ b/man3p/iconv_close.3p @@ -0,0 +1,61 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ICONV_CLOSE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iconv_close +.SH NAME +iconv_close \- codeset conversion deallocation function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int iconv_close(iconv_t\fP \fIcd\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIiconv_close\fP() function shall deallocate the conversion descriptor +\fIcd\fP and all other associated resources +allocated by \fIiconv_open\fP(). +.LP +If a file descriptor is used to implement the type \fBiconv_t\fP, +that file descriptor shall be closed. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned; otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIiconv_close\fP() function may fail if: +.TP 7 +.B EBADF +The conversion descriptor is invalid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiconv\fP() , \fIiconv_open\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/iconv_open.3p b/man3p/iconv_open.3p new file mode 100644 index 000000000..17347d0f4 --- /dev/null +++ b/man3p/iconv_open.3p @@ -0,0 +1,95 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ICONV_OPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iconv_open +.SH NAME +iconv_open \- codeset conversion allocation function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +iconv_t iconv_open(const char *\fP\fItocode\fP\fB, const char *\fP\fIfromcode\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIiconv_open\fP() function shall return a conversion descriptor +that describes a conversion from the codeset specified by +the string pointed to by the \fIfromcode\fP argument to the codeset +specified by the string pointed to by the \fItocode\fP +argument. For state-dependent encodings, the conversion descriptor +shall be in a codeset-dependent initial shift state, ready for +immediate use with \fIiconv\fP(). +.LP +Settings of \fIfromcode\fP and \fItocode\fP and their permitted combinations +are implementation-defined. +.LP +A conversion descriptor shall remain valid until it is closed by \fIiconv_close\fP() +or an implicit close. +.LP +If a file descriptor is used to implement conversion descriptors, +the FD_CLOEXEC flag shall be set; see \fI\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIiconv_open\fP() shall return a conversion +descriptor for use on subsequent calls to \fIiconv\fP(). Otherwise, +\fIiconv_open\fP() shall return (\fBiconv_t\fP)-1 and set \fIerrno\fP +to indicate the error. +.SH ERRORS +.LP +The \fIiconv_open\fP() function may fail if: +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENFILE +Too many files are currently open in the system. +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.TP 7 +.B EINVAL +The conversion specified by \fIfromcode\fP and \fItocode\fP is not +supported by the implementation. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Some implementations of \fIiconv_open\fP() use \fImalloc\fP() to allocate +space for +internal buffer areas. The \fIiconv_open\fP() function may fail if +there is insufficient storage space to accommodate these +buffers. +.LP +Conforming applications must assume that conversion descriptors are +not valid after a call to one of the \fIexec\fP functions. +.LP +Application developers should consult the system documentation to +determine the supported codesets and their naming schemes. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiconv\fP() , \fIiconv_close\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/if_freenameindex.3p b/man3p/if_freenameindex.3p new file mode 100644 index 000000000..efa21434f --- /dev/null +++ b/man3p/if_freenameindex.3p @@ -0,0 +1,55 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "IF_FREENAMEINDEX" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" if_freenameindex +.SH NAME +if_freenameindex \- free memory allocated by if_nameindex +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void if_freenameindex(struct if_nameindex *\fP\fIptr\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIif_freenameindex\fP() function shall free the memory allocated +by \fIif_nameindex\fP(). The \fIptr\fP argument shall be a pointer +that was returned by \fIif_nameindex\fP(). After \fIif_freenameindex\fP() +has been called, the application +shall not use the array of which \fIptr\fP is the address. +.SH RETURN VALUE +.LP +None. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetsockopt\fP() , \fIif_indextoname\fP() , \fIif_nameindex\fP() +, \fIif_nametoindex\fP() , \fIsetsockopt\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/if_indextoname.3p b/man3p/if_indextoname.3p new file mode 100644 index 000000000..0ed299b2c --- /dev/null +++ b/man3p/if_indextoname.3p @@ -0,0 +1,65 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "IF_INDEXTONAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" if_indextoname +.SH NAME +if_indextoname \- map a network interface index to its corresponding +name +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *if_indextoname(unsigned\fP \fIifindex\fP\fB, char *\fP\fIifname\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIif_indextoname\fP() function shall map an interface index to +its corresponding name. +.LP +When this function is called, \fIifname\fP shall point to a buffer +of at least {IF_NAMESIZE} bytes. The function shall place in +this buffer the name of the interface with index \fIifindex\fP. +.SH RETURN VALUE +.LP +If \fIifindex\fP is an interface index, then the function shall return +the value supplied in \fIifname\fP, which points to a +buffer now containing the interface name. Otherwise, the function +shall return a NULL pointer and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fIif_indextoname\fP() function shall fail if: +.TP 7 +.B ENXIO +The interface does not exist. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetsockopt\fP() , \fIif_freenameindex\fP() , \fIif_nameindex\fP() +, \fIif_nametoindex\fP() , \fIsetsockopt\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/if_nameindex.3p b/man3p/if_nameindex.3p new file mode 100644 index 000000000..f6b1f771e --- /dev/null +++ b/man3p/if_nameindex.3p @@ -0,0 +1,65 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "IF_NAMEINDEX" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" if_nameindex +.SH NAME +if_nameindex \- return all network interface names and indexes +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +struct if_nameindex *\fP\fIif_nameindex\fP\fB(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fIif_nameindex\fP() function shall return an array of \fIif_nameindex\fP +structures, one structure per interface. The end +of the array is indicated by a structure with an \fIif_index\fP field +of zero and an \fIif_name\fP field of NULL. +.LP +Applications should call \fIif_freenameindex\fP() to release the memory +that +may be dynamically allocated by this function, after they have finished +using it. +.SH RETURN VALUE +.LP +An array of structures identifying local interfaces. A NULL pointer +is returned upon an error, with \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +The \fIif_nameindex\fP() function may fail if: +.TP 7 +.B ENOBUFS +Insufficient resources are available to complete the function. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetsockopt\fP() , \fIif_freenameindex\fP() , \fIif_indextoname\fP() +, \fIif_nametoindex\fP() , \fIsetsockopt\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/if_nametoindex.3p b/man3p/if_nametoindex.3p new file mode 100644 index 000000000..9f4f03f9e --- /dev/null +++ b/man3p/if_nametoindex.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "IF_NAMETOINDEX" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" if_nametoindex +.SH NAME +if_nametoindex \- map a network interface name to its corresponding +index +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +unsigned if_nametoindex(const char *\fP\fIifname\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIif_nametoindex\fP() function shall return the interface index +corresponding to name \fIifname\fP. +.SH RETURN VALUE +.LP +The corresponding index if \fIifname\fP is the name of an interface; +otherwise, zero. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetsockopt\fP() , \fIif_freenameindex\fP() , \fIif_indextoname\fP() +, \fIif_nameindex\fP() , \fIsetsockopt\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ilogb.3p b/man3p/ilogb.3p new file mode 100644 index 000000000..6c5f8fa99 --- /dev/null +++ b/man3p/ilogb.3p @@ -0,0 +1,110 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ILOGB" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ilogb +.SH NAME +ilogb, ilogbf, ilogbl \- return an unbiased exponent +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int ilogb(double\fP \fIx\fP\fB); +.br +int ilogbf(float\fP \fIx\fP\fB); +.br +int ilogbl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall return the exponent part of their argument \fIx\fP. +Formally, the return value is the integral part of +log_r|x| as a signed integral value, for non-zero \fIx\fP, where \fIr\fP +is the radix of the machine's floating-point +arithmetic, which is the value of FLT_RADIX defined in \fI\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the exponent +part of \fIx\fP as a signed integer value. They are +equivalent to calling the corresponding \fIlogb\fP() function and +casting the returned value +to type \fBint\fP. +.LP +If \fIx\fP is 0, \ a domain error shall occur, and +the value FP_ILOGB0 shall be returned. +.LP +If \fIx\fP is \(+-Inf, \ a domain error shall occur, and +the value {INT_MAX} shall be returned. +.LP +If \fIx\fP is a NaN, \ a domain error shall occur, and +the value FP_ILOGBNAN shall be returned. +.LP +If the correct value is greater than {INT_MAX}, {INT_MAX} shall be +returned and a domain error shall occur. +.LP +If the correct value is less than {INT_MIN}, {INT_MIN} shall be returned +and a domain error shall occur. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The \fIx\fP argument is zero, NaN, or \(+-Inf, or the correct value +is not representable as an integer. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +The errors come from taking the expected floating-point value and +converting it to \fBint\fP, which is an invalid operation in +IEEE\ Std\ 754-1985 (since overflow, infinity, and NaN are not representable +in a type \fBint\fP), so should be a domain +error. +.LP +There are no known implementations that overflow. For overflow to +happen, {INT_MAX} must be less than +LDBL_MAX_EXP*\fIlog2\fP(FLT_RADIX) or {INT_MIN} must be greater than +LDBL_MIN_EXP*\fIlog2\fP(FLT_RADIX) if subnormals are not +supported, or {INT_MIN} must be greater than (LDBL_MIN_EXP-LDBL_MANT_DIG)*\fIlog2\fP(FLT_RADIX) +if subnormals are supported. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIlogb\fP() , \fIscalb\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ilogbf.3p b/man3p/ilogbf.3p new file mode 100644 index 000000000..6e8bd3a3c --- /dev/null +++ b/man3p/ilogbf.3p @@ -0,0 +1 @@ +.so man3p/ilogb.3p diff --git a/man3p/ilogbl.3p b/man3p/ilogbl.3p new file mode 100644 index 000000000..6e8bd3a3c --- /dev/null +++ b/man3p/ilogbl.3p @@ -0,0 +1 @@ +.so man3p/ilogb.3p diff --git a/man3p/imaxabs.3p b/man3p/imaxabs.3p new file mode 100644 index 000000000..6a8b80f52 --- /dev/null +++ b/man3p/imaxabs.3p @@ -0,0 +1,53 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "IMAXABS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" imaxabs +.SH NAME +imaxabs \- return absolute value +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +intmax_t imaxabs(intmax_t\fP \fIj\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIimaxabs\fP() function shall compute the absolute value of an +integer \fIj\fP. If the result cannot be represented, the +behavior is undefined. +.SH RETURN VALUE +.LP +The \fIimaxabs\fP() function shall return the absolute value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The absolute value of the most negative number cannot be represented +in two's complement. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIimaxdiv\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/imaxdiv.3p b/man3p/imaxdiv.3p new file mode 100644 index 000000000..b3c722e7d --- /dev/null +++ b/man3p/imaxdiv.3p @@ -0,0 +1,59 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "IMAXDIV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" imaxdiv +.SH NAME +imaxdiv \- return quotient and remainder +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +imaxdiv_t imaxdiv(intmax_t\fP \fInumer\fP\fB, intmax_t\fP \fIdenom\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIimaxdiv\fP() function shall compute \fInumer\fP\ /\ \fIdenom\fP +and \fInumer\fP\ %\ \fIdenom\fP in a +single operation. +.SH RETURN VALUE +.LP +The \fIimaxdiv\fP() function shall return a structure of type \fBimaxdiv_t\fP, +comprising both the quotient and the remainder. +The structure shall contain (in either order) the members \fIquot\fP +(the quotient) and \fIrem\fP (the remainder), each of which +has type \fBintmax_t\fP. +.LP +If either part of the result cannot be represented, the behavior is +undefined. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIimaxabs\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/index.3p b/man3p/index.3p new file mode 100644 index 000000000..306513df7 --- /dev/null +++ b/man3p/index.3p @@ -0,0 +1,62 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "INDEX" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" index +.SH NAME +index \- character string operations (\fBLEGACY\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *index(const char *\fP\fIs\fP\fB, int\fP \fIc\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIindex\fP() function shall be equivalent to \fIstrchr\fP(). +.SH RETURN VALUE +.LP +See \fIstrchr\fP() . +.SH ERRORS +.LP +See \fIstrchr\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIstrchr\fP() function is preferred over this function. +.LP +For maximum portability, it is recommended to replace the function +call to \fIindex\fP() as follows: +.sp +.RS +.nf + +\fB#define index(a,b) strchr((a),(b)) +\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +This function may be withdrawn in a future version. +.SH SEE ALSO +.LP +\fIstrchr\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/inet_addr.3p b/man3p/inet_addr.3p new file mode 100644 index 000000000..f7b0abf46 --- /dev/null +++ b/man3p/inet_addr.3p @@ -0,0 +1,105 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "INET_ADDR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" inet_addr +.SH NAME +inet_addr, inet_ntoa \- IPv4 address manipulation +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +in_addr_t inet_addr(const char *\fP\fIcp\fP\fB); +.br +char *inet_ntoa(struct in_addr\fP \fIin\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIinet_addr\fP() function shall convert the string pointed to +by \fIcp\fP, in the standard IPv4 dotted decimal notation, +to an integer value suitable for use as an Internet address. +.LP +The \fIinet_ntoa\fP() function shall convert the Internet host address +specified by \fIin\fP to a string in the Internet +standard dot notation. +.LP +The \fIinet_ntoa\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.LP +All Internet addresses shall be returned in network order (bytes ordered +from left to right). +.LP +Values specified using IPv4 dotted decimal notation take one of the +following forms: +.TP 7 +\fBa.b.c.d\fP +When four parts are specified, each shall be interpreted as a byte +of data and assigned, from left to right, to the four bytes +of an Internet address. +.TP 7 +\fBa.b.c\fP +When a three-part address is specified, the last part shall be interpreted +as a 16-bit quantity and placed in the rightmost two +bytes of the network address. This makes the three-part address format +convenient for specifying Class B network addresses as +\fB"128.net.host"\fP . +.TP 7 +\fBa.b\fP +When a two-part address is supplied, the last part shall be interpreted +as a 24-bit quantity and placed in the rightmost three +bytes of the network address. This makes the two-part address format +convenient for specifying Class A network addresses as +\fB"net.host"\fP . +.TP 7 +\fBa\fP +When only one part is given, the value shall be stored directly in +the network address without any byte rearrangement. +.sp +.LP +All numbers supplied as parts in IPv4 dotted decimal notation may +be decimal, octal, or hexadecimal, as specified in the +ISO\ C standard (that is, a leading 0x or 0X implies hexadecimal; +otherwise, a leading \fB'0'\fP implies octal; otherwise, +the number is interpreted as decimal). +.SH RETURN VALUE +.LP +Upon successful completion, \fIinet_addr\fP() shall return the Internet +address. Otherwise, it shall return ( +\fBin_addr_t\fP)(-1). +.LP +The \fIinet_ntoa\fP() function shall return a pointer to the network +address in Internet standard dot notation. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The return value of \fIinet_ntoa\fP() may point to static data that +may be overwritten by subsequent calls to +\fIinet_ntoa\fP(). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIendhostent\fP() , \fIendnetent\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/inet_ntoa.3p b/man3p/inet_ntoa.3p new file mode 100644 index 000000000..8d332a5c6 --- /dev/null +++ b/man3p/inet_ntoa.3p @@ -0,0 +1 @@ +.so man3p/inet_addr.3p diff --git a/man3p/inet_ntop.3p b/man3p/inet_ntop.3p new file mode 100644 index 000000000..4c955a376 --- /dev/null +++ b/man3p/inet_ntop.3p @@ -0,0 +1,143 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "INET_NTOP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" inet_ntop +.SH NAME +inet_ntop, inet_pton \- convert IPv4 and IPv6 addresses between binary +and text form +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +const char *inet_ntop(int\fP \fIaf\fP\fB, const void *restrict\fP +\fIsrc\fP\fB, +.br +\ \ \ \ \ \ char *restrict\fP \fIdst\fP\fB, socklen_t\fP \fIsize\fP\fB); +.br +int inet_pton(int\fP \fIaf\fP\fB, const char *restrict\fP \fIsrc\fP\fB, +void *restrict\fP \fIdst\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIinet_ntop\fP() function shall convert a numeric address into +a text string suitable for presentation. The \fIaf\fP +argument shall specify the family of the address. This can be AF_INET +\ or AF_INET6. The \fIsrc\fP argument points to a buffer holding +an IPv4 address if the \fIaf\fP argument is AF_INET, +\ or an IPv6 address if the \fIaf\fP argument is AF_INET6; the +address must be in network byte order. The \fIdst\fP argument points +to a buffer where the function stores the resulting text +string; it shall not be NULL. The \fIsize\fP argument specifies the +size of this buffer, which shall be large enough to hold the +text string (INET_ADDRSTRLEN characters for IPv4, \ INET6_ADDRSTRLEN +characters for IPv6). +.LP +The \fIinet_pton\fP() function shall convert an address in its standard +text presentation form into its numeric binary form. +The \fIaf\fP argument shall specify the family of the address. The +AF_INET \ and AF_INET6 +address families shall be supported. The \fIsrc\fP argument points +to the string being passed in. The \fIdst\fP argument points to a +buffer into which the function stores the numeric address; this +shall be large enough to hold the numeric address (32 bits for AF_INET, +\ 128 bits for AF_INET6). +.LP +If the \fIaf\fP argument of \fIinet_pton\fP() is AF_INET, the \fIsrc\fP +string shall be in the standard IPv4 dotted-decimal +form: +.sp +.RS +.nf + +\fBddd.ddd.ddd.ddd +\fP +.fi +.RE +.LP +where \fB"ddd"\fP is a one to three digit decimal number between 0 +and 255 (see \fIinet_addr\fP() ). The \fIinet_pton\fP() function does +not accept other formats (such as the octal +numbers, hexadecimal numbers, and fewer than four numbers that \fIinet_addr\fP() +accepts). +.LP +If the \fIaf\fP argument of \fIinet_pton\fP() is AF_INET6, the \fIsrc\fP +string shall be in one of the following standard IPv6 +text forms: +.IP " 1." 4 +The preferred form is \fB"x:x:x:x:x:x:x:x"\fP , where the \fB'x'\fP +s are the hexadecimal values of the eight 16-bit +pieces of the address. Leading zeros in individual fields can be omitted, +but there shall be at least one numeral in every +field. +.LP +.IP " 2." 4 +A string of contiguous zero fields in the preferred form can be shown +as \fB"::"\fP . The \fB"::"\fP can only appear once +in an address. Unspecified addresses ( \fB"0:0:0:0:0:0:0:0"\fP ) may +be represented simply as \fB"::"\fP . +.LP +.IP " 3." 4 +A third form that is sometimes more convenient when dealing with a +mixed environment of IPv4 and IPv6 nodes is +\fB"x:x:x:x:x:x:d.d.d.d"\fP , where the \fB'x'\fP s are the hexadecimal +values of the six high-order 16-bit pieces of the +address, and the \fB'd'\fP s are the decimal values of the four low-order +8-bit pieces of the address (standard IPv4 +representation). +.LP +.TP 7 +\fBNote:\fP +A more extensive description of the standard representations of IPv6 +addresses can be found in RFC\ 2373. +.sp +.SH RETURN VALUE +.LP +The \fIinet_ntop\fP() function shall return a pointer to the buffer +containing the text string if the conversion succeeds, and +NULL otherwise, and set \fIerrno\fP to indicate the error. +.LP +The \fIinet_pton\fP() function shall return 1 if the conversion succeeds, +with the address pointed to by \fIdst\fP in network +byte order. It shall return 0 if the input is not a valid IPv4 dotted-decimal +string \ or a valid +IPv6 address string, or -1 with \fIerrno\fP set to [EAFNOSUPPORT] +if the \fIaf\fP argument is unknown. +.SH ERRORS +.LP +The \fIinet_ntop\fP() and \fIinet_pton\fP() functions shall fail if: +.TP 7 +.B EAFNOSUPPORT +.sp +The \fIaf\fP argument is invalid. +.TP 7 +.B ENOSPC +The size of the \fIinet_ntop\fP() result buffer is inadequate. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/inet_pton.3p b/man3p/inet_pton.3p new file mode 100644 index 000000000..23370aea2 --- /dev/null +++ b/man3p/inet_pton.3p @@ -0,0 +1 @@ +.so man3p/inet_ntop.3p diff --git a/man3p/initstate.3p b/man3p/initstate.3p new file mode 100644 index 000000000..0f22b822b --- /dev/null +++ b/man3p/initstate.3p @@ -0,0 +1 @@ +.so man3p/random.3p diff --git a/man3p/insque.3p b/man3p/insque.3p new file mode 100644 index 000000000..1cf606c2e --- /dev/null +++ b/man3p/insque.3p @@ -0,0 +1,184 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "INSQUE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" insque +.SH NAME +insque, remque \- insert or remove an element in a queue +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void insque(void *\fP\fIelement\fP\fB, void *\fP\fIpred\fP\fB); +.br +void remque(void *\fP\fIelement\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIinsque\fP() and \fIremque\fP() functions shall manipulate queues +built from doubly-linked lists. The queue can be +either circular or linear. An application using \fIinsque\fP() or +\fIremque\fP() shall ensure it defines a structure in which the +first two members of the structure are pointers to the same type of +structure, and any further members are application-specific. +The first member of the structure is a forward pointer to the next +entry in the queue. The second member is a backward pointer to +the previous entry in the queue. If the queue is linear, the queue +is terminated with null pointers. The names of the structure and +of the pointer members are not subject to any special restriction. +.LP +The \fIinsque\fP() function shall insert the element pointed to by +\fIelement\fP into a queue immediately after the element +pointed to by \fIpred\fP. +.LP +The \fIremque\fP() function shall remove the element pointed to by +\fIelement\fP from a queue. +.LP +If the queue is to be used as a linear list, invoking \fIinsque\fP(&\fIelement\fP, +NULL), where \fIelement\fP is the +initial element of the queue, shall initialize the forward and backward +pointers of \fIelement\fP to null pointers. +.LP +If the queue is to be used as a circular list, the application shall +ensure it initializes the forward pointer and the backward +pointer of the initial element of the queue to the element's own address. +.SH RETURN VALUE +.LP +The \fIinsque\fP() and \fIremque\fP() functions do not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Creating a Linear Linked List +.LP +The following example creates a linear linked list. +.sp +.RS +.nf + +\fB#include +\&... +struct myque element1; +struct myque element2; +.sp + +char *data1 = "DATA1"; +char *data2 = "DATA2"; +\&... +element1.data = data1; +element2.data = data2; +.sp + +insque (&element1, NULL); +insque (&element2, &element1); +\fP +.fi +.RE +.SS Creating a Circular Linked List +.LP +The following example creates a circular linked list. +.sp +.RS +.nf + +\fB#include +\&... +struct myque element1; +struct myque element2; +.sp + +char *data1 = "DATA1"; +char *data2 = "DATA2"; +\&... +element1.data = data1; +element2.data = data2; +.sp + +element1.fwd = &element1; +element1.bck = &element1; +.sp + +insque (&element2, &element1); +\fP +.fi +.RE +.SS Removing an Element +.LP +The following example removes the element pointed to by \fIelement1\fP. +.sp +.RS +.nf + +\fB#include +\&... +struct myque element1; +\&... +remque (&element1); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The historical implementations of these functions described the arguments +as being of type \fBstruct qelem *\fP rather than as +being of type \fBvoid *\fP as defined here. In those implementations, +\fBstruct qelem\fP was commonly defined in \fI\fP as: +.sp +.RS +.nf + +\fBstruct qelem { + struct qelem *q_forw; + struct qelem *q_back; +}; +\fP +.fi +.RE +.LP +Applications using these functions, however, were never able to use +this structure directly since it provided no room for the +actual data contained in the elements. Most applications defined structures +that contained the two pointers as the initial elements +and also provided space for, or pointers to, the object's data. Applications +that used these functions to update more than one type +of table also had the problem of specifying two or more different +structures with the same name, if they literally used \fBstruct +qelem\fP as specified. +.LP +As described here, the implementations were actually expecting a structure +type where the first two members were forward and +backward pointers to structures. With C compilers that didn't provide +function prototypes, applications used structures as +specified in the DESCRIPTION above and the compiler did what the application +expected. +.LP +If this method had been carried forward with an ISO\ C standard compiler +and the historical function prototype, most +applications would have to be modified to cast pointers to the structures +actually used to be pointers to \fBstruct qelem\fP to +avoid compilation warnings. By specifying \fBvoid *\fP as the argument +type, applications do not need to change (unless they +specifically referenced \fBstruct qelem\fP and depended on it being +defined in \fI\fP). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ioctl.3p b/man3p/ioctl.3p new file mode 100644 index 000000000..783112893 --- /dev/null +++ b/man3p/ioctl.3p @@ -0,0 +1,1058 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "IOCTL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ioctl +.SH NAME +ioctl \- control a STREAMS device (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int ioctl(int\fP \fIfildes\fP\fB, int\fP \fIrequest\fP\fB, ... /* +arg */); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIioctl\fP() function shall perform a variety of control functions +on STREAMS devices. For non-STREAMS devices, the +functions performed by this call are unspecified. The \fIrequest\fP +argument and an optional third argument (with varying type) +shall be passed to and interpreted by the appropriate part of the +STREAM associated with \fIfildes\fP. +.LP +The \fIfildes\fP argument is an open file descriptor that refers to +a device. +.LP +The \fIrequest\fP argument selects the control function to be performed +and shall depend on the STREAMS device being +addressed. +.LP +The \fIarg\fP argument represents additional information that is needed +by this specific STREAMS device to perform the +requested function. The type of \fIarg\fP depends upon the particular +control request, but it shall be either an integer or a +pointer to a device-specific data structure. +.LP +The \fIioctl\fP() commands applicable to STREAMS, their arguments, +and error conditions that apply to each individual command +are described below. +.LP +The following \fIioctl\fP() commands, with error values indicated, +are applicable to all STREAMS files: +.TP 7 +I_PUSH +Pushes the module whose name is pointed to by \fIarg\fP onto the top +of the current STREAM, just below the STREAM head. It +then calls the \fIopen\fP() function of the newly-pushed module. +.LP +The \fIioctl\fP() function with the I_PUSH command shall fail if: +.TP 7 +.B EINVAL +.RS +Invalid module name. +.RE +.TP 7 +.B ENXIO +.RS +Open function of new module failed. +.RE +.TP 7 +.B ENXIO +.RS +Hangup received on \fIfildes\fP. +.RE +.sp +.TP 7 +I_POP +Removes the module just below the STREAM head of the STREAM pointed +to by \fIfildes\fP. The \fIarg\fP argument should be 0 in +an I_POP request. +.LP +The \fIioctl\fP() function with the I_POP command shall fail if: +.TP 7 +.B EINVAL +.RS +No module present in the STREAM. +.RE +.TP 7 +.B ENXIO +.RS +Hangup received on \fIfildes\fP. +.RE +.sp +.TP 7 +I_LOOK +Retrieves the name of the module just below the STREAM head of the +STREAM pointed to by \fIfildes\fP, and places it in a +character string pointed to by \fIarg\fP. The buffer pointed to by +\fIarg\fP should be at least FMNAMESZ+1 bytes long, where +FMNAMESZ is defined in \fI\fP. +.LP +The \fIioctl\fP() function with the I_LOOK command shall fail if: +.TP 7 +.B EINVAL +.RS +No module present in the STREAM. +.RE +.sp +.TP 7 +I_FLUSH +Flushes read and/or write queues, depending on the value of \fIarg\fP. +Valid \fIarg\fP values are: +.TP 7 +FLUSHR +.RS +Flush all read queues. +.RE +.TP 7 +FLUSHW +.RS +Flush all write queues. +.RE +.TP 7 +FLUSHRW +.RS +Flush all read and all write queues. +.RE +.sp +.LP +The \fIioctl\fP() function with the I_FLUSH command shall fail if: +.TP 7 +.B EINVAL +.RS +Invalid \fIarg\fP value. +.RE +.TP 7 +.B EAGAIN \fRor\fP ENOSR +.RS +.sp +Unable to allocate buffers for flush message. +.RE +.TP 7 +.B ENXIO +.RS +Hangup received on \fIfildes\fP. +.RE +.sp +.TP 7 +I_FLUSHBAND +Flushes a particular band of messages. The \fIarg\fP argument points +to a \fBbandinfo\fP structure. The \fIbi_flag\fP member +may be one of FLUSHR, FLUSHW, or FLUSHRW as described above. The \fIbi_pri\fP +member determines the priority band to be +flushed. +.TP 7 +I_SETSIG +Requests that the STREAMS implementation send the SIGPOLL signal to +the calling process when a particular event has occurred on +the STREAM associated with \fIfildes\fP. I_SETSIG supports an asynchronous +processing capability in STREAMS. The value of +\fIarg\fP is a bitmask that specifies the events for which the process +should be signaled. It is the bitwise-inclusive OR of any +combination of the following constants: +.TP 7 +S_RDNORM +.RS +A normal (priority band set to 0) message has arrived at the head +of a STREAM head read queue. A signal shall be generated even +if the message is of zero length. +.RE +.TP 7 +S_RDBAND +.RS +A message with a non-zero priority band has arrived at the head of +a STREAM head read queue. A signal shall be generated even +if the message is of zero length. +.RE +.TP 7 +S_INPUT +.RS +A message, other than a high-priority message, has arrived at the +head of a STREAM head read queue. A signal shall be generated +even if the message is of zero length. +.RE +.TP 7 +S_HIPRI +.RS +A high-priority message is present on a STREAM head read queue. A +signal shall be generated even if the message is of zero +length. +.RE +.TP 7 +S_OUTPUT +.RS +The write queue for normal data (priority band 0) just below the STREAM +head is no longer full. This notifies the process that +there is room on the queue for sending (or writing) normal data downstream. +.RE +.TP 7 +S_WRNORM +.RS +Equivalent to S_OUTPUT. +.RE +.TP 7 +S_WRBAND +.RS +The write queue for a non-zero priority band just below the STREAM +head is no longer full. This notifies the process that there +is room on the queue for sending (or writing) priority data downstream. +.RE +.TP 7 +S_MSG +.RS +A STREAMS signal message that contains the SIGPOLL signal has reached +the front of the STREAM head read queue. +.RE +.TP 7 +S_ERROR +.RS +Notification of an error condition has reached the STREAM head. +.RE +.TP 7 +S_HANGUP +.RS +Notification of a hangup has reached the STREAM head. +.RE +.TP 7 +S_BANDURG +.RS +When used in conjunction with S_RDBAND, SIGURG is generated instead +of SIGPOLL when a priority message reaches the front of the +STREAM head read queue. +.RE +.sp +.LP +If \fIarg\fP is 0, the calling process shall be unregistered and shall +not receive further SIGPOLL signals for the stream +associated with \fIfildes\fP. +.LP +Processes that wish to receive SIGPOLL signals shall ensure that they +explicitly register to receive them using I_SETSIG. If +several processes register to receive this signal for the same event +on the same STREAM, each process shall be signaled when the +event occurs. +.LP +The \fIioctl\fP() function with the I_SETSIG command shall fail if: +.TP 7 +.B EINVAL +.RS +The value of \fIarg\fP is invalid. +.RE +.TP 7 +.B EINVAL +.RS +The value of \fIarg\fP is 0 and the calling process is not registered +to receive the SIGPOLL signal. +.RE +.TP 7 +.B EAGAIN +.RS +There were insufficient resources to store the signal request. +.RE +.sp +.TP 7 +I_GETSIG +Returns the events for which the calling process is currently registered +to be sent a SIGPOLL signal. The events are returned +as a bitmask in an \fBint\fP pointed to by \fIarg\fP, where the events +are those specified in the description of I_SETSIG above. +.LP +The \fIioctl\fP() function with the I_GETSIG command shall fail if: +.TP 7 +.B EINVAL +.RS +Process is not registered to receive the SIGPOLL signal. +.RE +.sp +.TP 7 +I_FIND +Compares the names of all modules currently present in the STREAM +to the name pointed to by \fIarg\fP, and returns 1 if the +named module is present in the STREAM, or returns 0 if the named module +is not present. +.LP +The \fIioctl\fP() function with the I_FIND command shall fail if: +.TP 7 +.B EINVAL +.RS +\fIarg\fP does not contain a valid module name. +.RE +.sp +.TP 7 +I_PEEK +Retrieves the information in the first message on the STREAM head +read queue without taking the message off the queue. It is +analogous to \fIgetmsg\fP() except that this command does not remove +the message from the +queue. The \fIarg\fP argument points to a \fBstrpeek\fP structure. +.LP +The application shall ensure that the \fImaxlen\fP member in the \fBctlbuf\fP +and \fBdatabuf strbuf\fP structures is set to +the number of bytes of control information and/or data information, +respectively, to retrieve. The \fIflags\fP member may be +marked RS_HIPRI or 0, as described by \fIgetmsg\fP(). If the process +sets \fIflags\fP to +RS_HIPRI, for example, I_PEEK shall only look for a high-priority +message on the STREAM head read queue. +.LP +I_PEEK returns 1 if a message was retrieved, and returns 0 if no message +was found on the STREAM head read queue, or if the +RS_HIPRI flag was set in \fIflags\fP and a high-priority message was +not present on the STREAM head read queue. It does not wait +for a message to arrive. On return, \fBctlbuf\fP specifies information +in the control buffer, \fBdatabuf\fP specifies information +in the data buffer, and \fIflags\fP contains the value RS_HIPRI or +0. +.TP 7 +I_SRDOPT +Sets the read mode using the value of the argument \fIarg\fP. Read +modes are described in \fIread\fP() . Valid \fIarg\fP flags are: +.TP 7 +RNORM +.RS +Byte-stream mode, the default. +.RE +.TP 7 +RMSGD +.RS +Message-discard mode. +.RE +.TP 7 +RMSGN +.RS +Message-nondiscard mode. +.RE +.sp +.LP +The bitwise-inclusive OR of RMSGD and RMSGN shall return [EINVAL]. +The bitwise-inclusive OR of RNORM and either RMSGD or RMSGN +shall result in the other flag overriding RNORM which is the default. +.LP +In addition, treatment of control messages by the STREAM head may +be changed by setting any of the following flags in +\fIarg\fP: +.TP 7 +RPROTNORM +.RS +Fail \fIread\fP() with [EBADMSG] if a message containing a control +part is at the front +of the STREAM head read queue. +.RE +.TP 7 +RPROTDAT +.RS +Deliver the control part of a message as data when a process issues +a \fIread\fP(). +.RE +.TP 7 +RPROTDIS +.RS +Discard the control part of a message, delivering any data portion, +when a process issues a \fIread\fP(). +.RE +.sp +.LP +The \fIioctl\fP() function with the I_SRDOPT command shall fail if: +.TP 7 +.B EINVAL +.RS +The \fIarg\fP argument is not valid. +.RE +.sp +.TP 7 +I_GRDOPT +Returns the current read mode setting, as described above, in an \fBint\fP +pointed to by the argument \fIarg\fP. Read modes +are described in \fIread\fP() . +.TP 7 +I_NREAD +Counts the number of data bytes in the data part of the first message +on the STREAM head read queue and places this value in +the \fBint\fP pointed to by \fIarg\fP. The return value for the command +shall be the number of messages on the STREAM head read +queue. For example, if 0 is returned in \fIarg\fP, but the \fIioctl\fP() +return value is greater than 0, this indicates that a +zero-length message is next on the queue. +.TP 7 +I_FDINSERT +Creates a message from specified buffer(s), adds information about +another STREAM, and sends the message downstream. The +message contains a control part and an optional data part. The data +and control parts to be sent are distinguished by placement in +separate buffers, as described below. The \fIarg\fP argument points +to a \fBstrfdinsert\fP structure. +.LP +The application shall ensure that the \fIlen\fP member in the \fBctlbuf +strbuf\fP structure is set to the size of a +\fBt_uscalar_t\fP plus the number of bytes of control information +to be sent with the message. The \fIfildes\fP member specifies +the file descriptor of the other STREAM, and the \fIoffset\fP member, +which must be suitably aligned for use as a +\fBt_uscalar_t\fP, specifies the offset from the start of the control +buffer where I_FDINSERT shall store a \fBt_uscalar_t\fP +whose interpretation is specific to the STREAM end. The application +shall ensure that the \fIlen\fP member in the \fBdatabuf +strbuf\fP structure is set to the number of bytes of data information +to be sent with the message, or to 0 if no data part is to +be sent. +.LP +The \fIflags\fP member specifies the type of message to be created. +A normal message is created if \fIflags\fP is set to 0, +and a high-priority message is created if \fIflags\fP is set to RS_HIPRI. +For non-priority messages, I_FDINSERT shall block if the +STREAM write queue is full due to internal flow control conditions. +For priority messages, I_FDINSERT does not block on this +condition. For non-priority messages, I_FDINSERT does not block when +the write queue is full and O_NONBLOCK is set. Instead, it +fails and sets \fIerrno\fP to [EAGAIN]. +.LP +I_FDINSERT also blocks, unless prevented by lack of internal resources, +waiting for the availability of message blocks in the +STREAM, regardless of priority or whether O_NONBLOCK has been specified. +No partial message is sent. +.LP +The \fIioctl\fP() function with the I_FDINSERT command shall fail +if: +.TP 7 +.B EAGAIN +.RS +A non-priority message is specified, the O_NONBLOCK flag is set, and +the STREAM write queue is full due to internal flow +control conditions. +.RE +.TP 7 +.B EAGAIN \fRor\fP ENOSR +.RS +.sp +Buffers cannot be allocated for the message that is to be created. +.RE +.TP 7 +.B EINVAL +.RS +One of the following: +.RS +.IP " *" 3 +The \fIfildes\fP member of the \fBstrfdinsert\fP structure is not +a valid, open STREAM file descriptor. +.LP +.IP " *" 3 +The size of a \fBt_uscalar_t\fP plus \fIoffset\fP is greater than +the \fIlen\fP member for the buffer specified through +\fBctlbuf\fP. +.LP +.IP " *" 3 +The \fIoffset\fP member does not specify a properly-aligned location +in the data buffer. +.LP +.IP " *" 3 +An undefined value is stored in \fIflags\fP. +.LP +.RE +.RE +.TP 7 +.B ENXIO +.RS +Hangup received on the STREAM identified by either the \fIfildes\fP +argument or the \fIfildes\fP member of the +\fBstrfdinsert\fP structure. +.RE +.TP 7 +.B ERANGE +.RS +The \fIlen\fP member for the buffer specified through \fBdatabuf\fP +does not fall within the range specified by the maximum +and minimum packet sizes of the topmost STREAM module; or the \fIlen\fP +member for the buffer specified through \fBdatabuf\fP is +larger than the maximum configured size of the data part of a message; +or the \fIlen\fP member for the buffer specified through +\fBctlbuf\fP is larger than the maximum configured size of the control +part of a message. +.RE +.sp +.TP 7 +I_STR +Constructs an internal STREAMS \fIioctl\fP() message from the data +pointed to by \fIarg\fP, and sends that message +downstream. +.LP +This mechanism is provided to send \fIioctl\fP() requests to downstream +modules and drivers. It allows information to be sent +with \fIioctl\fP(), and returns to the process any information sent +upstream by the downstream recipient. I_STR shall block until +the system responds with either a positive or negative acknowledgement +message, or until the request times out after some period of +time. If the request times out, it shall fail with \fIerrno\fP set +to [ETIME]. +.LP +At most, one I_STR can be active on a STREAM. Further I_STR calls +shall block until the active I_STR completes at the STREAM +head. The default timeout interval for these requests is 15 seconds. +The O_NONBLOCK flag has no effect on this call. +.LP +To send requests downstream, the application shall ensure that \fIarg\fP +points to a \fBstrioctl\fP structure. +.LP +The \fIic_cmd\fP member is the internal \fIioctl\fP() command intended +for a downstream module or driver and \fIic_timout\fP +is the number of seconds (-1=infinite, 0=use implementation-defined +timeout interval, >0=as specified) an I_STR request shall +wait for acknowledgement before timing out. \fIic_len\fP is the number +of bytes in the data argument, and \fIic_dp\fP is a +pointer to the data argument. The \fIic_len\fP member has two uses: +on input, it contains the length of the data argument passed +in, and on return from the command, it contains the number of bytes +being returned to the process (the buffer pointed to by +\fIic_dp\fP should be large enough to contain the maximum amount of +data that any module or the driver in the STREAM can +return). +.LP +The STREAM head shall convert the information pointed to by the \fBstrioctl\fP +structure to an internal \fIioctl\fP() command +message and send it downstream. +.LP +The \fIioctl\fP() function with the I_STR command shall fail if: +.TP 7 +.B EAGAIN \fRor\fP ENOSR +.RS +.sp +Unable to allocate buffers for the \fIioctl\fP() message. +.RE +.TP 7 +.B EINVAL +.RS +The \fIic_len\fP member is less than 0 or larger than the maximum +configured size of the data part of a message, or +\fIic_timout\fP is less than -1. +.RE +.TP 7 +.B ENXIO +.RS +Hangup received on \fIfildes\fP. +.RE +.TP 7 +.B ETIME +.RS +A downstream \fIioctl\fP() timed out before acknowledgement was received. +.RE +.sp +.LP +An I_STR can also fail while waiting for an acknowledgement if a message +indicating an error or a hangup is received at the +STREAM head. In addition, an error code can be returned in the positive +or negative acknowledgement message, in the event the +\fIioctl\fP() command sent downstream fails. For these cases, I_STR +shall fail with \fIerrno\fP set to the value in the +message. +.TP 7 +I_SWROPT +Sets the write mode using the value of the argument \fIarg\fP. Valid +bit settings for \fIarg\fP are: +.TP 7 +SNDZERO +.RS +Send a zero-length message downstream when a \fIwrite\fP() of 0 bytes +occurs. To not +send a zero-length message when a \fIwrite\fP() of 0 bytes occurs, +the application shall +ensure that this bit is not set in \fIarg\fP (for example, \fIarg\fP +would be set to 0). +.RE +.sp +.LP +The \fIioctl\fP() function with the I_SWROPT command shall fail if: +.TP 7 +.B EINVAL +.RS +\fIarg\fP is not the above value. +.RE +.sp +.TP 7 +I_GWROPT +Returns the current write mode setting, as described above, in the +\fBint\fP that is pointed to by the argument +\fIarg\fP. +.TP 7 +I_SENDFD +Creates a new reference to the open file description associated with +the file descriptor \fIarg\fP, and writes a message on +the STREAMS-based pipe \fIfildes\fP containing this reference, together +with the user ID and group ID of the calling process. +.LP +The \fIioctl\fP() function with the I_SENDFD command shall fail if: +.TP 7 +.B EAGAIN +.RS +The sending STREAM is unable to allocate a message block to contain +the file pointer; or the read queue of the receiving STREAM +head is full and cannot accept the message sent by I_SENDFD. +.RE +.TP 7 +.B EBADF +.RS +The \fIarg\fP argument is not a valid, open file descriptor. +.RE +.TP 7 +.B EINVAL +.RS +The \fIfildes\fP argument is not connected to a STREAM pipe. +.RE +.TP 7 +.B ENXIO +.RS +Hangup received on \fIfildes\fP. +.RE +.sp +.TP 7 +I_RECVFD +Retrieves the reference to an open file description from a message +written to a STREAMS-based pipe using the I_SENDFD command, +and allocates a new file descriptor in the calling process that refers +to this open file description. The \fIarg\fP argument is a +pointer to a \fBstrrecvfd\fP data structure as defined in \fI\fP. +.LP +The \fIfd\fP member is a file descriptor. The \fIuid\fP and \fIgid\fP +members are the effective user ID and effective group +ID, respectively, of the sending process. +.LP +If O_NONBLOCK is not set, I_RECVFD shall block until a message is +present at the STREAM head. If O_NONBLOCK is set, I_RECVFD +shall fail with \fIerrno\fP set to [EAGAIN] if no message is present +at the STREAM head. +.LP +If the message at the STREAM head is a message sent by an I_SENDFD, +a new file descriptor shall be allocated for the open file +descriptor referenced in the message. The new file descriptor is placed +in the \fIfd\fP member of the \fBstrrecvfd\fP structure +pointed to by \fIarg\fP. +.LP +The \fIioctl\fP() function with the I_RECVFD command shall fail if: +.TP 7 +.B EAGAIN +.RS +A message is not present at the STREAM head read queue and the O_NONBLOCK +flag is set. +.RE +.TP 7 +.B EBADMSG +.RS +The message at the STREAM head read queue is not a message containing +a passed file descriptor. +.RE +.TP 7 +.B EMFILE +.RS +The process has the maximum number of file descriptors currently open +that it is allowed. +.RE +.TP 7 +.B ENXIO +.RS +Hangup received on \fIfildes\fP. +.RE +.sp +.TP 7 +I_LIST +Allows the process to list all the module names on the STREAM, up +to and including the topmost driver name. If \fIarg\fP is a +null pointer, the return value shall be the number of modules, including +the driver, that are on the STREAM pointed to by +\fIfildes\fP. This lets the process allocate enough space for the +module names. Otherwise, it should point to a \fBstr_list\fP +structure. +.LP +The \fIsl_nmods\fP member indicates the number of entries the process +has allocated in the array. Upon return, the +\fIsl_modlist\fP member of the \fBstr_list\fP structure shall contain +the list of module names, and the number of entries that +have been filled into the \fIsl_modlist\fP array is found in the \fIsl_nmods\fP +member (the number includes the number of modules +including the driver). The return value from \fIioctl\fP() shall be +0. The entries are filled in starting at the top of the STREAM +and continuing downstream until either the end of the STREAM is reached, +or the number of requested modules ( \fIsl_nmods\fP) is +satisfied. +.LP +The \fIioctl\fP() function with the I_LIST command shall fail if: +.TP 7 +.B EINVAL +.RS +The \fIsl_nmods\fP member is less than 1. +.RE +.TP 7 +.B EAGAIN \fRor\fP ENOSR +.RS +.sp +Unable to allocate buffers. +.RE +.sp +.TP 7 +I_ATMARK +Allows the process to see if the message at the head of the STREAM +head read queue is marked by some module downstream. The +\fIarg\fP argument determines how the checking is done when there +may be multiple marked messages on the STREAM head read queue. +It may take on the following values: +.TP 7 +ANYMARK +.RS +Check if the message is marked. +.RE +.TP 7 +LASTMARK +.RS +Check if the message is the last one marked on the queue. +.RE +.sp +.LP +The bitwise-inclusive OR of the flags ANYMARK and LASTMARK is permitted. +.LP +The return value shall be 1 if the mark condition is satisfied; otherwise, +the value shall be 0. +.LP +The \fIioctl\fP() function with the I_ATMARK command shall fail if: +.TP 7 +.B EINVAL +.RS +Invalid \fIarg\fP value. +.RE +.sp +.TP 7 +I_CKBAND +Checks if the message of a given priority band exists on the STREAM +head read queue. This shall return 1 if a message of the +given priority exists, 0 if no such message exists, or -1 on error. +\fIarg\fP should be of type \fBint\fP. +.LP +The \fIioctl\fP() function with the I_CKBAND command shall fail if: +.TP 7 +.B EINVAL +.RS +Invalid \fIarg\fP value. +.RE +.sp +.TP 7 +I_GETBAND +Returns the priority band of the first message on the STREAM head +read queue in the integer referenced by \fIarg\fP. +.LP +The \fIioctl\fP() function with the I_GETBAND command shall fail if: +.TP 7 +.B ENODATA +.RS +No message on the STREAM head read queue. +.RE +.sp +.TP 7 +I_CANPUT +Checks if a certain band is writable. \fIarg\fP is set to the priority +band in question. The return value shall be 0 if the +band is flow-controlled, 1 if the band is writable, or -1 on error. +.LP +The \fIioctl\fP() function with the I_CANPUT command shall fail if: +.TP 7 +.B EINVAL +.RS +Invalid \fIarg\fP value. +.RE +.sp +.TP 7 +I_SETCLTIME +This request allows the process to set the time the STREAM head shall +delay when a STREAM is closing and there is data on the +write queues. Before closing each module or driver, if there is data +on its write queue, the STREAM head shall delay for the +specified amount of time to allow the data to drain. If, after the +delay, data is still present, it shall be flushed. The +\fIarg\fP argument is a pointer to an integer specifying the number +of milliseconds to delay, rounded up to the nearest valid +value. If I_SETCLTIME is not performed on a STREAM, an implementation-defined +default timeout interval is used. +.LP +The \fIioctl\fP() function with the I_SETCLTIME command shall fail +if: +.TP 7 +.B EINVAL +.RS +Invalid \fIarg\fP value. +.RE +.sp +.TP 7 +I_GETCLTIME +Returns the close time delay in the integer pointed to by \fIarg\fP. +.sp +.SS Multiplexed STREAMS Configurations +.LP +The following commands are used for connecting and disconnecting multiplexed +STREAMS configurations. These commands use an +implementation-defined default timeout interval. +.TP 7 +I_LINK +Connects two STREAMs, where \fIfildes\fP is the file descriptor of +the STREAM connected to the multiplexing driver, and +\fIarg\fP is the file descriptor of the STREAM connected to another +driver. The STREAM designated by \fIarg\fP is connected below +the multiplexing driver. I_LINK requires the multiplexing driver to +send an acknowledgement message to the STREAM head regarding +the connection. This call shall return a multiplexer ID number (an +identifier used to disconnect the multiplexer; see I_UNLINK) on +success, and -1 on failure. +.LP +The \fIioctl\fP() function with the I_LINK command shall fail if: +.TP 7 +.B ENXIO +.RS +Hangup received on \fIfildes\fP. +.RE +.TP 7 +.B ETIME +.RS +Timeout before acknowledgement message was received at STREAM head. +.RE +.TP 7 +.B EAGAIN \fRor\fP ENOSR +.RS +.sp +Unable to allocate STREAMS storage to perform the I_LINK. +.RE +.TP 7 +.B EBADF +.RS +The \fIarg\fP argument is not a valid, open file descriptor. +.RE +.TP 7 +.B EINVAL +.RS +The \fIfildes\fP argument does not support multiplexing; or \fIarg\fP +is not a STREAM or is already connected downstream from +a multiplexer; or the specified I_LINK operation would connect the +STREAM head in more than one place in the multiplexed +STREAM. +.RE +.sp +.LP +An I_LINK can also fail while waiting for the multiplexing driver +to acknowledge the request, if a message indicating an error +or a hangup is received at the STREAM head of \fIfildes\fP. In addition, +an error code can be returned in the positive or negative +acknowledgement message. For these cases, I_LINK fails with \fIerrno\fP +set to the value in the message. +.TP 7 +I_UNLINK +Disconnects the two STREAMs specified by \fIfildes\fP and \fIarg\fP. +\fIfildes\fP is the file descriptor of the STREAM +connected to the multiplexing driver. The \fIarg\fP argument is the +multiplexer ID number that was returned by the I_LINK +\fIioctl\fP() command when a STREAM was connected downstream from +the multiplexing driver. If \fIarg\fP is MUXID_ALL, then all +STREAMs that were connected to \fIfildes\fP shall be disconnected. +As in I_LINK, this command requires acknowledgement. +.LP +The \fIioctl\fP() function with the I_UNLINK command shall fail if: +.TP 7 +.B ENXIO +.RS +Hangup received on \fIfildes\fP. +.RE +.TP 7 +.B ETIME +.RS +Timeout before acknowledgement message was received at STREAM head. +.RE +.TP 7 +.B EAGAIN \fRor\fP ENOSR +.RS +.sp +Unable to allocate buffers for the acknowledgement message. +.RE +.TP 7 +.B EINVAL +.RS +Invalid multiplexer ID number. +.RE +.sp +.LP +An I_UNLINK can also fail while waiting for the multiplexing driver +to acknowledge the request if a message indicating an error +or a hangup is received at the STREAM head of \fIfildes\fP. In addition, +an error code can be returned in the positive or negative +acknowledgement message. For these cases, I_UNLINK shall fail with +\fIerrno\fP set to the value in the message. +.TP 7 +I_PLINK +Creates a \fIpersistent connection\fP between two STREAMs, where \fIfildes\fP +is the file descriptor of the STREAM connected +to the multiplexing driver, and \fIarg\fP is the file descriptor of +the STREAM connected to another driver. This call shall create +a persistent connection which can exist even if the file descriptor +\fIfildes\fP associated with the upper STREAM to the +multiplexing driver is closed. The STREAM designated by \fIarg\fP +gets connected via a persistent connection below the +multiplexing driver. I_PLINK requires the multiplexing driver to send +an acknowledgement message to the STREAM head. This call +shall return a multiplexer ID number (an identifier that may be used +to disconnect the multiplexer; see I_PUNLINK) on success, and +-1 on failure. +.LP +The \fIioctl\fP() function with the I_PLINK command shall fail if: +.TP 7 +.B ENXIO +.RS +Hangup received on \fIfildes\fP. +.RE +.TP 7 +.B ETIME +.RS +Timeout before acknowledgement message was received at STREAM head. +.RE +.TP 7 +.B EAGAIN \fRor\fP ENOSR +.RS +.sp +Unable to allocate STREAMS storage to perform the I_PLINK. +.RE +.TP 7 +.B EBADF +.RS +The \fIarg\fP argument is not a valid, open file descriptor. +.RE +.TP 7 +.B EINVAL +.RS +The \fIfildes\fP argument does not support multiplexing; or \fIarg\fP +is not a STREAM or is already connected downstream from +a multiplexer; or the specified I_PLINK operation would connect the +STREAM head in more than one place in the multiplexed +STREAM. +.RE +.sp +.LP +An I_PLINK can also fail while waiting for the multiplexing driver +to acknowledge the request, if a message indicating an error +or a hangup is received at the STREAM head of \fIfildes\fP. In addition, +an error code can be returned in the positive or negative +acknowledgement message. For these cases, I_PLINK shall fail with +\fIerrno\fP set to the value in the message. +.TP 7 +I_PUNLINK +Disconnects the two STREAMs specified by \fIfildes\fP and \fIarg\fP +from a persistent connection. The \fIfildes\fP argument +is the file descriptor of the STREAM connected to the multiplexing +driver. The \fIarg\fP argument is the multiplexer ID number +that was returned by the I_PLINK \fIioctl\fP() command when a STREAM +was connected downstream from the multiplexing driver. If +\fIarg\fP is MUXID_ALL, then all STREAMs which are persistent connections +to \fIfildes\fP shall be disconnected. As in I_PLINK, +this command requires the multiplexing driver to acknowledge the request. +.LP +The \fIioctl\fP() function with the I_PUNLINK command shall fail if: +.TP 7 +.B ENXIO +.RS +Hangup received on \fIfildes\fP. +.RE +.TP 7 +.B ETIME +.RS +Timeout before acknowledgement message was received at STREAM head. +.RE +.TP 7 +.B EAGAIN \fRor\fP ENOSR +.RS +.sp +Unable to allocate buffers for the acknowledgement message. +.RE +.TP 7 +.B EINVAL +.RS +Invalid multiplexer ID number. +.RE +.sp +.LP +An I_PUNLINK can also fail while waiting for the multiplexing driver +to acknowledge the request if a message indicating an error +or a hangup is received at the STREAM head of \fIfildes\fP. In addition, +an error code can be returned in the positive or negative +acknowledgement message. For these cases, I_PUNLINK shall fail with +\fIerrno\fP set to the value in the message. +.sp +.SH RETURN VALUE +.LP +Upon successful completion, \fIioctl\fP() shall return a value other +than -1 that depends upon the STREAMS device control +function. Otherwise, it shall return -1 and set \fIerrno\fP to indicate +the error. +.SH ERRORS +.LP +Under the following general conditions, \fIioctl\fP() shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid open file descriptor. +.TP 7 +.B EINTR +A signal was caught during the \fIioctl\fP() operation. +.TP 7 +.B EINVAL +The STREAM or multiplexer referenced by \fIfildes\fP is linked (directly +or indirectly) downstream from a multiplexer. +.sp +.LP +If an underlying device driver detects an error, then \fIioctl\fP() +shall fail if: +.TP 7 +.B EINVAL +The \fIrequest\fP or \fIarg\fP argument is not valid for this device. +.TP 7 +.B EIO +Some physical I/O error has occurred. +.TP 7 +.B ENOTTY +The \fIfildes\fP argument is not associated with a STREAMS device +that accepts control functions. +.TP 7 +.B ENXIO +The \fIrequest\fP and \fIarg\fP arguments are valid for this device +driver, but the service requested cannot be performed on +this particular sub-device. +.TP 7 +.B ENODEV +The \fIfildes\fP argument refers to a valid STREAMS device, but the +corresponding device driver does not support the +\fIioctl\fP() function. +.sp +.LP +If a STREAM is connected downstream from a multiplexer, any \fIioctl\fP() +command except I_UNLINK and I_PUNLINK shall set +\fIerrno\fP to [EINVAL]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The implementation-defined timeout interval for STREAMS has historically +been 15 seconds. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISTREAMS\fP , \fIclose\fP() , \fIfcntl\fP() , \fIgetmsg\fP() , \fIopen\fP() +, \fIpipe\fP() , \fIpoll\fP() , \fIputmsg\fP() , \fIread\fP() , \fIsigaction\fP() +, \fIwrite\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isalnum.3p b/man3p/isalnum.3p new file mode 100644 index 000000000..bc1d71be8 --- /dev/null +++ b/man3p/isalnum.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISALNUM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isalnum +.SH NAME +isalnum \- test for an alphanumeric character +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isalnum(int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisalnum\fP() function shall test whether \fIc\fP is a character +of class \fBalpha\fP or \fBdigit\fP in the program's +current locale; see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, +Locale. +.LP +The \fIc\fP argument is an \fBint\fP, the value of which the application +shall ensure is representable as an \fBunsigned +char\fP or equal to the value of the macro EOF. If the argument has +any other value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIisalnum\fP() function shall return non-zero if \fIc\fP is an +alphanumeric character; otherwise, it shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for character classification. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisalpha\fP() , \fIiscntrl\fP() , \fIisdigit\fP() , \fIisgraph\fP() +, \fIislower\fP() , +\fIisprint\fP() , \fIispunct\fP() , \fIisspace\fP() , \fIisupper\fP() +, \fIisxdigit\fP() , +\fIsetlocale\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, Locale, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isalpha.3p b/man3p/isalpha.3p new file mode 100644 index 000000000..de43a5bc5 --- /dev/null +++ b/man3p/isalpha.3p @@ -0,0 +1,65 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISALPHA" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isalpha +.SH NAME +isalpha \- test for an alphabetic character +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isalpha(int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisalpha\fP() function shall test whether \fIc\fP is a character +of class \fBalpha\fP in the program's current locale; +see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter +7, Locale. +.LP +The \fIc\fP argument is an \fBint\fP, the value of which the application +shall ensure is representable as an \fBunsigned +char\fP or equal to the value of the macro EOF. If the argument has +any other value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIisalpha\fP() function shall return non-zero if \fIc\fP is an +alphabetic character; otherwise, it shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for character classification. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisalnum\fP() , \fIiscntrl\fP() , \fIisdigit\fP() , \fIisgraph\fP() +, \fIislower\fP() , +\fIisprint\fP() , \fIispunct\fP() , \fIisspace\fP() , \fIisupper\fP() +, \fIisxdigit\fP() , +\fIsetlocale\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, Locale, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isascii.3p b/man3p/isascii.3p new file mode 100644 index 000000000..d509e514a --- /dev/null +++ b/man3p/isascii.3p @@ -0,0 +1,55 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISASCII" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isascii +.SH NAME +isascii \- test for a 7-bit US-ASCII character +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isascii(int\fP \fIc\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIisascii\fP() function shall test whether \fIc\fP is a 7-bit +US-ASCII character code. +.LP +The \fIisascii\fP() function is defined on all integer values. +.SH RETURN VALUE +.LP +The \fIisascii\fP() function shall return non-zero if \fIc\fP is a +7-bit US-ASCII character code between 0 and octal 0177 +inclusive; otherwise, it shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isastream.3p b/man3p/isastream.3p new file mode 100644 index 000000000..0a714d929 --- /dev/null +++ b/man3p/isastream.3p @@ -0,0 +1,59 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISASTREAM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isastream +.SH NAME +isastream \- test a file descriptor (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isastream(int\fP \fIfildes\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIisastream\fP() function shall test whether \fIfildes\fP, an +open file descriptor, is associated with a STREAMS-based +file. +.SH RETURN VALUE +.LP +Upon successful completion, \fIisastream\fP() shall return 1 if \fIfildes\fP +refers to a STREAMS-based file and 0 if not. +Otherwise, \fIisastream\fP() shall return -1 and set \fIerrno\fP to +indicate the error. +.SH ERRORS +.LP +The \fIisastream\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid open file descriptor. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isatty.3p b/man3p/isatty.3p new file mode 100644 index 000000000..f86bd7310 --- /dev/null +++ b/man3p/isatty.3p @@ -0,0 +1,63 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISATTY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isatty +.SH NAME +isatty \- test for a terminal device +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isatty(int\fP \fIfildes\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisatty\fP() function shall test whether \fIfildes\fP, an open +file descriptor, is associated with a terminal +device. +.SH RETURN VALUE +.LP +The \fIisatty\fP() function shall return 1 if \fIfildes\fP is associated +with a terminal; otherwise, it shall return 0 and may +set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIisatty\fP() function may fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid open file descriptor. +.TP 7 +.B ENOTTY +The \fIfildes\fP argument is not associated with a terminal. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIisatty\fP() function does not necessarily indicate that a human +being is available for interaction via \fIfildes\fP. It +is quite possible that non-terminal devices are connected to the communications +line. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isblank.3p b/man3p/isblank.3p new file mode 100644 index 000000000..4fb6993ad --- /dev/null +++ b/man3p/isblank.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISBLANK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isblank +.SH NAME +isblank \- test for a blank character +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isblank(int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisblank\fP() function shall test whether \fIc\fP is a character +of class \fBblank\fP in the program's current locale; +see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter +7, Locale. +.LP +The \fIc\fP argument is a type \fBint\fP, the value of which the application +shall ensure is a character representable as an +\fBunsigned char\fP or equal to the value of the macro EOF. If the +argument has any other value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIisblank\fP() function shall return non-zero if \fIc\fP is a +; otherwise, it shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for character classification. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisalnum\fP() , \fIisalpha\fP() , \fIiscntrl\fP() , \fIisdigit\fP() +, \fIisgraph\fP() , +\fIislower\fP() , \fIisprint\fP() , \fIispunct\fP() , \fIisspace\fP() +, \fIisupper\fP() , +\fIisxdigit\fP() , \fIsetlocale\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/iscntrl.3p b/man3p/iscntrl.3p new file mode 100644 index 000000000..e392b3869 --- /dev/null +++ b/man3p/iscntrl.3p @@ -0,0 +1,65 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISCNTRL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iscntrl +.SH NAME +iscntrl \- test for a control character +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int iscntrl(int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIiscntrl\fP() function shall test whether \fIc\fP is a character +of class \fBcntrl\fP in the program's current locale; +see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter +7, Locale. +.LP +The \fIc\fP argument is a type \fBint\fP, the value of which the application +shall ensure is a character representable as an +\fBunsigned char\fP or equal to the value of the macro EOF. If the +argument has any other value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIiscntrl\fP() function shall return non-zero if \fIc\fP is a +control character; otherwise, it shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for character classification. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisalnum\fP() , \fIisalpha\fP() , \fIisdigit\fP() , \fIisgraph\fP() +, \fIislower\fP() , +\fIisprint\fP() , \fIispunct\fP() , \fIisspace\fP() , \fIisupper\fP() +, \fIisxdigit\fP() , +\fIsetlocale\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, Locale, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isdigit.3p b/man3p/isdigit.3p new file mode 100644 index 000000000..224209fb1 --- /dev/null +++ b/man3p/isdigit.3p @@ -0,0 +1,65 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISDIGIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isdigit +.SH NAME +isdigit \- test for a decimal digit +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isdigit(int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisdigit\fP() function shall test whether \fIc\fP is a character +of class \fBdigit\fP in the program's current locale; +see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter +7, Locale. +.LP +The \fIc\fP argument is an \fBint\fP, the value of which the application +shall ensure is a character representable as an +\fBunsigned char\fP or equal to the value of the macro EOF. If the +argument has any other value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIisdigit\fP() function shall return non-zero if \fIc\fP is a +decimal digit; otherwise, it shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for character classification. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisalnum\fP() , \fIisalpha\fP() , \fIiscntrl\fP() , \fIisgraph\fP() +, \fIislower\fP() , +\fIisprint\fP() , \fIispunct\fP() , \fIisspace\fP() , \fIisupper\fP() +, \fIisxdigit\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 7, +Locale, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isfinite.3p b/man3p/isfinite.3p new file mode 100644 index 000000000..ea70d1f48 --- /dev/null +++ b/man3p/isfinite.3p @@ -0,0 +1,56 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISFINITE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isfinite +.SH NAME +isfinite \- test for finite value +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isfinite(real-floating\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisfinite\fP() macro shall determine whether its argument has +a finite value (zero, subnormal, or normal, and not +infinite or NaN). First, an argument represented in a format wider +than its semantic type is converted to its semantic type. Then +determination is based on the type of the argument. +.SH RETURN VALUE +.LP +The \fIisfinite\fP() macro shall return a non-zero value if and only +if its argument has a finite value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfpclassify\fP() , \fIisinf\fP() , \fIisnan\fP() , \fIisnormal\fP() +, \fIsignbit\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001 \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isgraph.3p b/man3p/isgraph.3p new file mode 100644 index 000000000..6c5418db0 --- /dev/null +++ b/man3p/isgraph.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISGRAPH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isgraph +.SH NAME +isgraph \- test for a visible character +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isgraph(int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisgraph\fP() function shall test whether \fIc\fP is a character +of class \fBgraph\fP in the program's current locale; +see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter +7, Locale. +.LP +The \fIc\fP argument is an \fBint\fP, the value of which the application +shall ensure is a character representable as an +\fBunsigned char\fP or equal to the value of the macro EOF. If the +argument has any other value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIisgraph\fP() function shall return non-zero if \fIc\fP is a +character with a visible representation; otherwise, it +shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for character classification. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisalnum\fP() , \fIisalpha\fP() , \fIiscntrl\fP() , \fIisdigit\fP() +, \fIislower\fP() , +\fIisprint\fP() , \fIispunct\fP() , \fIisspace\fP() , \fIisupper\fP() +, \fIisxdigit\fP() , +\fIsetlocale\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, Locale, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isgreater.3p b/man3p/isgreater.3p new file mode 100644 index 000000000..f00b7faad --- /dev/null +++ b/man3p/isgreater.3p @@ -0,0 +1,71 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISGREATER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isgreater +.SH NAME +isgreater \- test if x greater than y +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isgreater(real-floating\fP \fIx\fP\fB, real-floating\fP \fIy\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisgreater\fP() macro shall determine whether its first argument +is greater than its second argument. The value of +\fIisgreater\fP( \fIx\fP, \fIy\fP) shall be equal to (\fIx\fP)\ >\ (\fIy\fP); +however, unlike +(\fIx\fP)\ >\ (\fIy\fP), \fIisgreater\fP( \fIx\fP, \fIy\fP) shall +not raise the invalid floating-point exception +when \fIx\fP and \fIy\fP are unordered. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIisgreater\fP() macro shall return +the value of (\fIx\fP)\ >\ (\fIy\fP). +.LP +If \fIx\fP or \fIy\fP is NaN, 0 shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair +of numeric values, exactly one of the relationships (less, greater, +and equal) is true. Relational operators may raise the invalid +floating-point exception when argument values are NaNs. For a NaN +and a numeric value, or for two NaNs, just the unordered +relationship is true. This macro is a quiet (non-floating-point exception +raising) version of a relational operator. It facilitates +writing efficient code that accounts for NaNs without suffering the +invalid floating-point exception. In the SYNOPSIS section, +\fBreal-floating\fP indicates that the argument shall be an expression +of \fBreal-floating\fP type. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisgreaterequal\fP() , \fIisless\fP() , \fIislessequal\fP() , \fIislessgreater\fP() +, \fIisunordered\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001 +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isgreaterequal.3p b/man3p/isgreaterequal.3p new file mode 100644 index 000000000..32bc21396 --- /dev/null +++ b/man3p/isgreaterequal.3p @@ -0,0 +1,72 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISGREATEREQUAL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isgreaterequal +.SH NAME +isgreaterequal \- test if x is greater than or equal to y +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isgreaterequal(real-floating\fP \fIx\fP\fB, real-floating\fP \fIy\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisgreaterequal\fP() macro shall determine whether its first +argument is greater than or equal to its second argument. +The value of \fIisgreaterequal\fP( \fIx\fP, \fIy\fP) shall be equal +to (\fIx\fP)\ >=\ (\fIy\fP); however, unlike +(\fIx\fP)\ >=\ (\fIy\fP), \fIisgreaterequal\fP( \fIx\fP, \fIy\fP) +shall not raise the invalid floating-point +exception when \fIx\fP and \fIy\fP are unordered. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIisgreaterequal\fP() macro shall +return the value of +(\fIx\fP)\ >=\ (\fIy\fP). +.LP +If \fIx\fP or \fIy\fP is NaN, 0 shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair +of numeric values, exactly one of the relationships (less, greater, +and equal) is true. Relational operators may raise the invalid +floating-point exception when argument values are NaNs. For a NaN +and a numeric value, or for two NaNs, just the unordered +relationship is true. This macro is a quiet (non-floating-point exception +raising) version of a relational operator. It facilitates +writing efficient code that accounts for NaNs without suffering the +invalid floating-point exception. In the SYNOPSIS section, +\fBreal-floating\fP indicates that the argument shall be an expression +of \fBreal-floating\fP type. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisgreater\fP() , \fIisless\fP() , \fIislessequal\fP() , \fIislessgreater\fP() +, \fIisunordered\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001 +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isinf.3p b/man3p/isinf.3p new file mode 100644 index 000000000..70c90b150 --- /dev/null +++ b/man3p/isinf.3p @@ -0,0 +1,56 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISINF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isinf +.SH NAME +isinf \- test for infinity +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isinf(real-floating\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisinf\fP() macro shall determine whether its argument value +is an infinity (positive or negative). First, an argument +represented in a format wider than its semantic type is converted +to its semantic type. Then determination is based on the type of +the argument. +.SH RETURN VALUE +.LP +The \fIisinf\fP() macro shall return a non-zero value if and only +if its argument has an infinite value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfpclassify\fP() , \fIisfinite\fP() , \fIisnan\fP() , \fIisnormal\fP() +, \fIsignbit\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001 \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isless.3p b/man3p/isless.3p new file mode 100644 index 000000000..1f423c321 --- /dev/null +++ b/man3p/isless.3p @@ -0,0 +1,71 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISLESS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isless +.SH NAME +isless \- test if x is less than y +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isless(real-floating\fP \fIx\fP\fB, real-floating\fP \fIy\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisless\fP() macro shall determine whether its first argument +is less than its second argument. The value of +\fIisless\fP( \fIx\fP, \fIy\fP) shall be equal to (\fIx\fP)\ <\ (\fIy\fP); +however, unlike +(\fIx\fP)\ <\ (\fIy\fP), \fIisless\fP( \fIx\fP, \fIy\fP) shall not +raise the invalid floating-point exception when +\fIx\fP and \fIy\fP are unordered. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIisless\fP() macro shall return +the value of (\fIx\fP)\ <\ (\fIy\fP). +.LP +If \fIx\fP or \fIy\fP is NaN, 0 shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair +of numeric values, exactly one of the relationships (less, greater, +and equal) is true. Relational operators may raise the invalid +floating-point exception when argument values are NaNs. For a NaN +and a numeric value, or for two NaNs, just the unordered +relationship is true. This macro is a quiet (non-floating-point exception +raising) version of a relational operator. It facilitates +writing efficient code that accounts for NaNs without suffering the +invalid floating-point exception. In the SYNOPSIS section, +\fBreal-floating\fP indicates that the argument shall be an expression +of \fBreal-floating\fP type. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisgreater\fP() , \fIisgreaterequal\fP() , \fIislessequal\fP() , +\fIislessgreater\fP() , \fIisunordered\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/islessequal.3p b/man3p/islessequal.3p new file mode 100644 index 000000000..66525ba0b --- /dev/null +++ b/man3p/islessequal.3p @@ -0,0 +1,71 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISLESSEQUAL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" islessequal +.SH NAME +islessequal \- test if x is less than or equal to y +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int islessequal(real-floating\fP \fIx\fP\fB, real-floating\fP \fIy\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIislessequal\fP() macro shall determine whether its first argument +is less than or equal to its second argument. The +value of \fIislessequal\fP( \fIx\fP, \fIy\fP) shall be equal to (\fIx\fP)\ <=\ (\fIy\fP); +however, unlike +(\fIx\fP)\ <=\ (\fIy\fP), \fIislessequal\fP( \fIx\fP, \fIy\fP) shall +not raise the invalid floating-point exception +when \fIx\fP and \fIy\fP are unordered. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIislessequal\fP() macro shall return +the value of (\fIx\fP)\ <=\ (\fIy\fP). +.LP +If \fIx\fP or \fIy\fP is NaN, 0 shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair +of numeric values, exactly one of the relationships (less, greater, +and equal) is true. Relational operators may raise the invalid +floating-point exception when argument values are NaNs. For a NaN +and a numeric value, or for two NaNs, just the unordered +relationship is true. This macro is a quiet (non-floating-point exception +raising) version of a relational operator. It facilitates +writing efficient code that accounts for NaNs without suffering the +invalid floating-point exception. In the SYNOPSIS section, +\fBreal-floating\fP indicates that the argument shall be an expression +of \fBreal-floating\fP type. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisgreater\fP() , \fIisgreaterequal\fP() , \fIisless\fP() , \fIislessgreater\fP() +, \fIisunordered\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001 +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/islessgreater.3p b/man3p/islessgreater.3p new file mode 100644 index 000000000..97510a558 --- /dev/null +++ b/man3p/islessgreater.3p @@ -0,0 +1,73 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISLESSGREATER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" islessgreater +.SH NAME +islessgreater \- test if x is less than or greater than y +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int islessgreater(real-floating\fP \fIx\fP\fB, real-floating\fP \fIy\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIislessgreater\fP() macro shall determine whether its first +argument is less than or greater than its second argument. +The \fIislessgreater\fP( \fIx\fP, \fIy\fP) macro is similar to +(\fIx\fP)\ <\ (\fIy\fP)\ ||\ (\fIx\fP)\ >\ (\fIy\fP); however, \fIislessgreater\fP( +\fIx\fP, +\fIy\fP) shall not raise the invalid floating-point exception when +\fIx\fP and \fIy\fP are unordered (nor shall it evaluate +\fIx\fP and \fIy\fP twice). +.SH RETURN VALUE +.LP +Upon successful completion, the \fIislessgreater\fP() macro shall +return the value of +(\fIx\fP)\ <\ (\fIy\fP)\ ||\ (\fIx\fP)\ >\ (\fIy\fP). +.LP +If \fIx\fP or \fIy\fP is NaN, 0 shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair +of numeric values, exactly one of the relationships (less, greater, +and equal) is true. Relational operators may raise the invalid +floating-point exception when argument values are NaNs. For a NaN +and a numeric value, or for two NaNs, just the unordered +relationship is true. This macro is a quiet (non-floating-point exception +raising) version of a relational operator. It facilitates +writing efficient code that accounts for NaNs without suffering the +invalid floating-point exception. In the SYNOPSIS section, +\fBreal-floating\fP indicates that the argument shall be an expression +of \fBreal-floating\fP type. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisgreater\fP() , \fIisgreaterequal\fP() , \fIisless\fP() , \fIislessequal\fP() +, \fIisunordered\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001 +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/islower.3p b/man3p/islower.3p new file mode 100644 index 000000000..282a72b30 --- /dev/null +++ b/man3p/islower.3p @@ -0,0 +1,93 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISLOWER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" islower +.SH NAME +islower \- test for a lowercase letter +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int islower(int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIislower\fP() function shall test whether \fIc\fP is a character +of class \fBlower\fP in the program's current locale; +see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter +7, Locale. +.LP +The \fIc\fP argument is an \fBint\fP, the value of which the application +shall ensure is a character representable as an +\fBunsigned char\fP or equal to the value of the macro EOF. If the +argument has any other value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIislower\fP() function shall return non-zero if \fIc\fP is a +lowercase letter; otherwise, it shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Testing for a Lowercase Letter +.LP +The following example tests whether the value is a lowercase letter, +based on the locale of the user, then uses it as part of a +key value. +.sp +.RS +.nf + +\fB#include +#include +#include +\&... +char *keystr; +int elementlen, len; +char c; +\&... +setlocale(LC_ALL, ""); +\&... +len = 0; +while (len < elementlen) { + c = (char) (rand() % 256); +\&... + if (islower(c)) + keystr[len++] = c; + } +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for character classification. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisalnum\fP() , \fIisalpha\fP() , \fIiscntrl\fP() , \fIisdigit\fP() +, \fIisgraph\fP() , +\fIisprint\fP() , \fIispunct\fP() , \fIisspace\fP() , \fIisupper\fP() +, \fIisxdigit\fP() , +\fIsetlocale\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, Locale, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isnan.3p b/man3p/isnan.3p new file mode 100644 index 000000000..7dbb17855 --- /dev/null +++ b/man3p/isnan.3p @@ -0,0 +1,55 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISNAN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isnan +.SH NAME +isnan \- test for a NaN +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isnan(real-floating\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisnan\fP() macro shall determine whether its argument value +is a NaN. First, an argument represented in a format wider +than its semantic type is converted to its semantic type. Then determination +is based on the type of the argument. +.SH RETURN VALUE +.LP +The \fIisnan\fP() macro shall return a non-zero value if and only +if its argument has a NaN value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfpclassify\fP() , \fIisfinite\fP() , \fIisinf\fP() , \fIisnormal\fP() +, \fIsignbit\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isnormal.3p b/man3p/isnormal.3p new file mode 100644 index 000000000..ff08b4484 --- /dev/null +++ b/man3p/isnormal.3p @@ -0,0 +1,56 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISNORMAL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isnormal +.SH NAME +isnormal \- test for a normal value +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isnormal(real-floating\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisnormal\fP() macro shall determine whether its argument value +is normal (neither zero, subnormal, infinite, nor NaN). +First, an argument represented in a format wider than its semantic +type is converted to its semantic type. Then determination is +based on the type of the argument. +.SH RETURN VALUE +.LP +The \fIisnormal\fP() macro shall return a non-zero value if and only +if its argument has a normal value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfpclassify\fP() , \fIisfinite\fP() , \fIisinf\fP() , \fIisnan\fP() +, \fIsignbit\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isprint.3p b/man3p/isprint.3p new file mode 100644 index 000000000..eb8f8d20b --- /dev/null +++ b/man3p/isprint.3p @@ -0,0 +1,65 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISPRINT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isprint +.SH NAME +isprint \- test for a printable character +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isprint(int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisprint\fP() function shall test whether \fIc\fP is a character +of class \fBprint\fP in the program's current locale; +see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter +7, Locale. +.LP +The \fIc\fP argument is an \fBint\fP, the value of which the application +shall ensure is a character representable as an +\fBunsigned char\fP or equal to the value of the macro EOF. If the +argument has any other value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIisprint\fP() function shall return non-zero if \fIc\fP is a +printable character; otherwise, it shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for character classification. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisalnum\fP() , \fIisalpha\fP() , \fIiscntrl\fP() , \fIisdigit\fP() +, \fIisgraph\fP() , +\fIislower\fP() , \fIispunct\fP() , \fIisspace\fP() , \fIisupper\fP() +, \fIisxdigit\fP() , +\fIsetlocale\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, Locale, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ispunct.3p b/man3p/ispunct.3p new file mode 100644 index 000000000..6bc2364a9 --- /dev/null +++ b/man3p/ispunct.3p @@ -0,0 +1,65 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISPUNCT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ispunct +.SH NAME +ispunct \- test for a punctuation character +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int ispunct(int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIispunct\fP() function shall test whether \fIc\fP is a character +of class \fBpunct\fP in the program's current locale; +see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter +7, Locale. +.LP +The \fIc\fP argument is an \fBint\fP, the value of which the application +shall ensure is a character representable as an +\fBunsigned char\fP or equal to the value of the macro EOF. If the +argument has any other value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIispunct\fP() function shall return non-zero if \fIc\fP is a +punctuation character; otherwise, it shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for character classification. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisalnum\fP() , \fIisalpha\fP() , \fIiscntrl\fP() , \fIisdigit\fP() +, \fIisgraph\fP() , +\fIislower\fP() , \fIisprint\fP() , \fIisspace\fP() , \fIisupper\fP() +, \fIisxdigit\fP() , +\fIsetlocale\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, Locale, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isspace.3p b/man3p/isspace.3p new file mode 100644 index 000000000..1414f4d30 --- /dev/null +++ b/man3p/isspace.3p @@ -0,0 +1,65 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISSPACE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isspace +.SH NAME +isspace \- test for a white-space character +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isspace(int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisspace\fP() function shall test whether \fIc\fP is a character +of class \fBspace\fP in the program's current locale; +see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter +7, Locale. +.LP +The \fIc\fP argument is an \fBint\fP, the value of which the application +shall ensure is a character representable as an +\fBunsigned char\fP or equal to the value of the macro EOF. If the +argument has any other value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIisspace\fP() function shall return non-zero if \fIc\fP is a +white-space character; otherwise, it shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for character classification. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisalnum\fP() , \fIisalpha\fP() , \fIiscntrl\fP() , \fIisdigit\fP() +, \fIisgraph\fP() , +\fIislower\fP() , \fIisprint\fP() , \fIispunct\fP() , \fIisupper\fP() +, \fIisxdigit\fP() , +\fIsetlocale\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, Locale, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isunordered.3p b/man3p/isunordered.3p new file mode 100644 index 000000000..89ad65f16 --- /dev/null +++ b/man3p/isunordered.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISUNORDERED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isunordered +.SH NAME +isunordered \- test if arguments are unordered +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isunordered(real-floating\fP \fIx\fP\fB, real-floating\fP \fIy\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisunordered\fP() macro shall determine whether its arguments +are unordered. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIisunordered\fP() macro shall return +1 if its arguments are unordered, and 0 otherwise. +.LP +If \fIx\fP or \fIy\fP is NaN, 0 shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair +of numeric values, exactly one of the relationships (less, greater, +and equal) is true. Relational operators may raise the invalid +floating-point exception when argument values are NaNs. For a NaN +and a numeric value, or for two NaNs, just the unordered +relationship is true. This macro is a quiet (non-floating-point exception +raising) version of a relational operator. It facilitates +writing efficient code that accounts for NaNs without suffering the +invalid floating-point exception. In the SYNOPSIS section, +\fBreal-floating\fP indicates that the argument shall be an expression +of \fBreal-floating\fP type. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisgreater\fP() , \fIisgreaterequal\fP() , \fIisless\fP() , \fIislessequal\fP() +, \fIislessgreater\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isupper.3p b/man3p/isupper.3p new file mode 100644 index 000000000..b2fa81ab4 --- /dev/null +++ b/man3p/isupper.3p @@ -0,0 +1,65 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISUPPER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isupper +.SH NAME +isupper \- test for an uppercase letter +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isupper(int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisupper\fP() function shall test whether \fIc\fP is a character +of class \fBupper\fP in the program's current locale; +see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter +7, Locale. +.LP +The \fIc\fP argument is an \fBint\fP, the value of which the application +shall ensure is a character representable as an +\fBunsigned char\fP or equal to the value of the macro EOF. If the +argument has any other value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIisupper\fP() function shall return non-zero if \fIc\fP is an +uppercase letter; otherwise, it shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for character classification. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisalnum\fP() , \fIisalpha\fP() , \fIiscntrl\fP() , \fIisdigit\fP() +, \fIisgraph\fP() , +\fIislower\fP() , \fIisprint\fP() , \fIispunct\fP() , \fIisspace\fP() +, \fIisxdigit\fP() , +\fIsetlocale\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, Locale, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/iswalnum.3p b/man3p/iswalnum.3p new file mode 100644 index 000000000..553c9a802 --- /dev/null +++ b/man3p/iswalnum.3p @@ -0,0 +1,67 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISWALNUM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iswalnum +.SH NAME +iswalnum \- test for an alphanumeric wide-character code +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int iswalnum(wint_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIiswalnum\fP() function shall test whether \fIwc\fP is a wide-character +code representing a character of class +\fBalpha\fP or \fBdigit\fP in the program's current locale; see the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale. +.LP +The \fIwc\fP argument is a \fBwint_t\fP, the value of which the application +shall ensure is a wide-character code +corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other +value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIiswalnum\fP() function shall return non-zero if \fIwc\fP is +an alphanumeric wide-character code; otherwise, it shall +return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for classification of wide-character codes. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswalpha\fP() , \fIiswcntrl\fP() , \fIiswctype\fP() , \fIiswdigit\fP() +, \fIiswgraph\fP() , \fIiswlower\fP() , \fIiswprint\fP() , \fIiswpunct\fP() +, \fIiswspace\fP() , \fIiswupper\fP() , \fIiswxdigit\fP() , \fIsetlocale\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI\fP, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/iswalpha.3p b/man3p/iswalpha.3p new file mode 100644 index 000000000..8be9f5a4f --- /dev/null +++ b/man3p/iswalpha.3p @@ -0,0 +1,67 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISWALPHA" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iswalpha +.SH NAME +iswalpha \- test for an alphabetic wide-character code +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int iswalpha(wint_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIiswalpha\fP() function shall test whether \fIwc\fP is a wide-character +code representing a character of class +\fBalpha\fP in the program's current locale; see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale. +.LP +The \fIwc\fP argument is a \fBwint_t\fP, the value of which the application +shall ensure is a wide-character code +corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other +value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIiswalpha\fP() function shall return non-zero if \fIwc\fP is +an alphabetic wide-character code; otherwise, it shall +return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for classification of wide-character codes. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswalnum\fP() , \fIiswcntrl\fP() , \fIiswctype\fP() , \fIiswdigit\fP() +, \fIiswgraph\fP() , \fIiswlower\fP() , \fIiswprint\fP() , \fIiswpunct\fP() +, \fIiswspace\fP() , \fIiswupper\fP() , \fIiswxdigit\fP() , \fIsetlocale\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI\fP, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/iswblank.3p b/man3p/iswblank.3p new file mode 100644 index 000000000..5c6ed98d9 --- /dev/null +++ b/man3p/iswblank.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISWBLANK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iswblank +.SH NAME +iswblank \- test for a blank wide-character code +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int iswblank(wint_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIiswblank\fP() function shall test whether \fIwc\fP is a wide-character +code representing a character of class +\fBblank\fP in the program's current locale; see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale. +.LP +The \fIwc\fP argument is a \fBwint_t\fP, the value of which the application +shall ensure is a wide-character code +corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other +value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIiswblank\fP() function shall return non-zero if \fIwc\fP is +a blank wide-character code; otherwise, it shall return +0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for classification of wide-character codes. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswalnum\fP() , \fIiswalpha\fP() , \fIiswcntrl\fP() , \fIiswctype\fP() +, \fIiswdigit\fP() , \fIiswgraph\fP() , \fIiswlower\fP() , \fIiswprint\fP() +, \fIiswpunct\fP() , \fIiswspace\fP() , \fIiswupper\fP() , \fIiswxdigit\fP() +, \fIsetlocale\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, Locale, \fI\fP, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/iswcntrl.3p b/man3p/iswcntrl.3p new file mode 100644 index 000000000..9d78dc6a2 --- /dev/null +++ b/man3p/iswcntrl.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISWCNTRL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iswcntrl +.SH NAME +iswcntrl \- test for a control wide-character code +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int iswcntrl(wint_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIiswcntrl\fP() function shall test whether \fIwc\fP is a wide-character +code representing a character of class +\fBcntrl\fP in the program's current locale; see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale. +.LP +The \fIwc\fP argument is a \fBwint_t\fP, the value of which the application +shall ensure is a wide-character code +corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other +value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIiswcntrl\fP() function shall return non-zero if \fIwc\fP is +a control wide-character code; otherwise, it shall return +0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for classification of wide-character codes. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswalnum\fP() , \fIiswalpha\fP() , \fIiswctype\fP() , \fIiswdigit\fP() +, \fIiswgraph\fP() , \fIiswlower\fP() , \fIiswprint\fP() , \fIiswpunct\fP() +, \fIiswspace\fP() , \fIiswupper\fP() , \fIiswxdigit\fP() , \fIsetlocale\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/iswctype.3p b/man3p/iswctype.3p new file mode 100644 index 000000000..c991ecd06 --- /dev/null +++ b/man3p/iswctype.3p @@ -0,0 +1,105 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISWCTYPE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iswctype +.SH NAME +iswctype \- test character for a specified class +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int iswctype(wint_t\fP \fIwc\fP\fB, wctype_t\fP \fIcharclass\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIiswctype\fP() function shall determine whether the wide-character +code \fIwc\fP has the character class +\fIcharclass\fP, returning true or false. The \fIiswctype\fP() function +is defined on WEOF and wide-character codes corresponding +to the valid character encodings in the current locale. If the \fIwc\fP +argument is not in the domain of the function, the result +is undefined. If the value of \fIcharclass\fP is invalid (that is, +not obtained by a call to \fIwctype\fP() or \fIcharclass\fP is invalidated +by a subsequent call to \fIsetlocale\fP() that has affected category +\fILC_CTYPE )\fP the result is unspecified. +.SH RETURN VALUE +.LP +The \fIiswctype\fP() function shall return non-zero (true) if and +only if \fIwc\fP has the property described by +\fIcharclass\fP. \ If \fIcharclass\fP is 0, \fIiswctype\fP() shall +return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Testing for a Valid Character +.sp +.RS +.nf + +\fB#include +\&... +int yes_or_no; +wint_t wc; +wctype_t valid_class; +\&... +if ((valid_class=wctype("vowel")) == (wctype_t)0) + /* Invalid character class. */ +yes_or_no=iswctype(wc,valid_class); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The twelve strings \fB"alnum"\fP , \fB"alpha"\fP , \fB"blank"\fP , +\fB"cntrl"\fP , \fB"digit"\fP , +\fB"graph"\fP , \fB"lower"\fP , \fB"print"\fP , \fB"punct"\fP , \fB"space"\fP +, \fB"upper"\fP , and +\fB"xdigit"\fP are reserved for the standard character classes. In +the table below, the functions in the left column are +equivalent to the functions in the right column. +.sp +.RS +.nf + +\fBiswalnum(\fP\fIwc\fP\fB) iswctype(\fP\fIwc\fP\fB, wctype("alnum")) +iswalpha(\fP\fIwc\fP\fB) iswctype(\fP\fIwc\fP\fB, wctype("alpha")) +iswblank(\fP\fIwc\fP\fB) iswctype(\fP\fIwc\fP\fB, wctype("blank")) +iswcntrl(\fP\fIwc\fP\fB) iswctype(\fP\fIwc\fP\fB, wctype("cntrl")) +iswdigit(\fP\fIwc\fP\fB) iswctype(\fP\fIwc\fP\fB, wctype("digit")) +iswgraph(\fP\fIwc\fP\fB) iswctype(\fP\fIwc\fP\fB, wctype("graph")) +iswlower(\fP\fIwc\fP\fB) iswctype(\fP\fIwc\fP\fB, wctype("lower")) +iswprint(\fP\fIwc\fP\fB) iswctype(\fP\fIwc\fP\fB, wctype("print")) +iswpunct(\fP\fIwc\fP\fB) iswctype(\fP\fIwc\fP\fB, wctype("punct")) +iswspace(\fP\fIwc\fP\fB) iswctype(\fP\fIwc\fP\fB, wctype("space")) +iswupper(\fP\fIwc\fP\fB) iswctype(\fP\fIwc\fP\fB, wctype("upper")) +iswxdigit(\fP\fIwc\fP\fB) iswctype(\fP\fIwc\fP\fB, wctype("xdigit")) +\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswalnum\fP() , \fIiswalpha\fP() , \fIiswcntrl\fP() , \fIiswdigit\fP() +, \fIiswgraph\fP() , \fIiswlower\fP() , \fIiswprint\fP() , \fIiswpunct\fP() +, \fIiswspace\fP() , \fIiswupper\fP() , \fIiswxdigit\fP() , \fIsetlocale\fP() +, \fIwctype\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/iswdigit.3p b/man3p/iswdigit.3p new file mode 100644 index 000000000..a3db07ce2 --- /dev/null +++ b/man3p/iswdigit.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISWDIGIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iswdigit +.SH NAME +iswdigit \- test for a decimal digit wide-character code +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int iswdigit(wint_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIiswdigit\fP() function shall test whether \fIwc\fP is a wide-character +code representing a character of class +\fBdigit\fP in the program's current locale; see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale. +.LP +The \fIwc\fP argument is a \fBwint_t\fP, the value of which the application +shall ensure is a wide-character code +corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other +value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIiswdigit\fP() function shall return non-zero if \fIwc\fP is +a decimal digit wide-character code; otherwise, it shall +return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for classification of wide-character codes. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswalnum\fP() , \fIiswalpha\fP() , \fIiswcntrl\fP() , \fIiswctype\fP() +, \fIiswgraph\fP() , \fIiswlower\fP() , \fIiswprint\fP() , \fIiswpunct\fP() +, \fIiswspace\fP() , \fIiswupper\fP() , \fIiswxdigit\fP() , \fIsetlocale\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/iswgraph.3p b/man3p/iswgraph.3p new file mode 100644 index 000000000..9bc0b6279 --- /dev/null +++ b/man3p/iswgraph.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISWGRAPH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iswgraph +.SH NAME +iswgraph \- test for a visible wide-character code +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int iswgraph(wint_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIiswgraph\fP() function shall test whether \fIwc\fP is a wide-character +code representing a character of class +\fBgraph\fP in the program's current locale; see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale. +.LP +The \fIwc\fP argument is a \fBwint_t\fP, the value of which the application +shall ensure is a wide-character code +corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other +value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIiswgraph\fP() function shall return non-zero if \fIwc\fP is +a wide-character code with a visible representation; +otherwise, it shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for classification of wide-character codes. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswalnum\fP() , \fIiswalpha\fP() , \fIiswcntrl\fP() , \fIiswctype\fP() +, \fIiswdigit\fP() , \fIiswlower\fP() , \fIiswprint\fP() , \fIiswpunct\fP() +, \fIiswspace\fP() , \fIiswupper\fP() , \fIiswxdigit\fP() , \fIsetlocale\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/iswlower.3p b/man3p/iswlower.3p new file mode 100644 index 000000000..3dd0c7364 --- /dev/null +++ b/man3p/iswlower.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISWLOWER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iswlower +.SH NAME +iswlower \- test for a lowercase letter wide-character code +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int iswlower(wint_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIiswlower\fP() function shall test whether \fIwc\fP is a wide-character +code representing a character of class +\fBlower\fP in the program's current locale; see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale. +.LP +The \fIwc\fP argument is a \fBwint_t\fP, the value of which the application +shall ensure is a wide-character code +corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other +value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIiswlower\fP() function shall return non-zero if \fIwc\fP is +a lowercase letter wide-character code; otherwise, it shall +return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for classification of wide-character codes. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswalnum\fP() , \fIiswalpha\fP() , \fIiswcntrl\fP() , \fIiswctype\fP() +, \fIiswdigit\fP() , \fIiswgraph\fP() , \fIiswprint\fP() , \fIiswpunct\fP() +, \fIiswspace\fP() , \fIiswupper\fP() , \fIiswxdigit\fP() , \fIsetlocale\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/iswprint.3p b/man3p/iswprint.3p new file mode 100644 index 000000000..29f1a4936 --- /dev/null +++ b/man3p/iswprint.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISWPRINT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iswprint +.SH NAME +iswprint \- test for a printable wide-character code +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int iswprint(wint_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIiswprint\fP() function shall test whether \fIwc\fP is a wide-character +code representing a character of class +\fBprint\fP in the program's current locale; see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale. +.LP +The \fIwc\fP argument is a \fBwint_t\fP, the value of which the application +shall ensure is a wide-character code +corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other +value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIiswprint\fP() function shall return non-zero if \fIwc\fP is +a printable wide-character code; otherwise, it shall return +0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for classification of wide-character codes. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswalnum\fP() , \fIiswalpha\fP() , \fIiswcntrl\fP() , \fIiswctype\fP() +, \fIiswdigit\fP() , \fIiswgraph\fP() , \fIiswlower\fP() , \fIiswpunct\fP() +, \fIiswspace\fP() , \fIiswupper\fP() , \fIiswxdigit\fP() , \fIsetlocale\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/iswpunct.3p b/man3p/iswpunct.3p new file mode 100644 index 000000000..e9fbddc06 --- /dev/null +++ b/man3p/iswpunct.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISWPUNCT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iswpunct +.SH NAME +iswpunct \- test for a punctuation wide-character code +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int iswpunct(wint_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIiswpunct\fP() function shall test whether \fIwc\fP is a wide-character +code representing a character of class +\fBpunct\fP in the program's current locale; see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale. +.LP +The \fIwc\fP argument is a \fBwint_t\fP, the value of which the application +shall ensure is a wide-character code +corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other +value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIiswpunct\fP() function shall return non-zero if \fIwc\fP is +a punctuation wide-character code; otherwise, it shall +return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for classification of wide-character codes. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswalnum\fP() , \fIiswalpha\fP() , \fIiswcntrl\fP() , \fIiswctype\fP() +, \fIiswdigit\fP() , \fIiswgraph\fP() , \fIiswlower\fP() , \fIiswprint\fP() +, \fIiswspace\fP() , \fIiswupper\fP() , \fIiswxdigit\fP() , \fIsetlocale\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/iswspace.3p b/man3p/iswspace.3p new file mode 100644 index 000000000..2f7e77aa2 --- /dev/null +++ b/man3p/iswspace.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISWSPACE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iswspace +.SH NAME +iswspace \- test for a white-space wide-character code +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int iswspace(wint_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIiswspace\fP() function shall test whether \fIwc\fP is a wide-character +code representing a character of class +\fBspace\fP in the program's current locale; see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale. +.LP +The \fIwc\fP argument is a \fBwint_t\fP, the value of which the application +shall ensure is a wide-character code +corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other +value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIiswspace\fP() function shall return non-zero if \fIwc\fP is +a white-space wide-character code; otherwise, it shall +return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for classification of wide-character codes. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswalnum\fP() , \fIiswalpha\fP() , \fIiswcntrl\fP() , \fIiswctype\fP() +, \fIiswdigit\fP() , \fIiswgraph\fP() , \fIiswlower\fP() , \fIiswprint\fP() +, \fIiswpunct\fP() , \fIiswupper\fP() , \fIiswxdigit\fP() , \fIsetlocale\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/iswupper.3p b/man3p/iswupper.3p new file mode 100644 index 000000000..30022b3ef --- /dev/null +++ b/man3p/iswupper.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISWUPPER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iswupper +.SH NAME +iswupper \- test for an uppercase letter wide-character code +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int iswupper(wint_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIiswupper\fP() function shall test whether \fIwc\fP is a wide-character +code representing a character of class +\fBupper\fP in the program's current locale; see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale. +.LP +The \fIwc\fP argument is a \fBwint_t\fP, the value of which the application +shall ensure is a wide-character code +corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other +value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIiswupper\fP() function shall return non-zero if \fIwc\fP is +an uppercase letter wide-character code; otherwise, it +shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for classification of wide-character codes. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswalnum\fP() , \fIiswalpha\fP() , \fIiswcntrl\fP() , \fIiswctype\fP() +, \fIiswdigit\fP() , \fIiswgraph\fP() , \fIiswlower\fP() , \fIiswprint\fP() +, \fIiswpunct\fP() , \fIiswspace\fP() , \fIiswxdigit\fP() , \fIsetlocale\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/iswxdigit.3p b/man3p/iswxdigit.3p new file mode 100644 index 000000000..1e9a791cb --- /dev/null +++ b/man3p/iswxdigit.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISWXDIGIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" iswxdigit +.SH NAME +iswxdigit \- test for a hexadecimal digit wide-character code +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int iswxdigit(wint_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIiswxdigit\fP() function shall test whether \fIwc\fP is a wide-character +code representing a character of class +\fBxdigit\fP in the program's current locale; see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale. +.LP +The \fIwc\fP argument is a \fBwint_t\fP, the value of which the application +shall ensure is a wide-character code +corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other +value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIiswxdigit\fP() function shall return non-zero if \fIwc\fP is +a hexadecimal digit wide-character code; otherwise, it +shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for classification of wide-character codes. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswalnum\fP() , \fIiswalpha\fP() , \fIiswcntrl\fP() , \fIiswctype\fP() +, \fIiswdigit\fP() , \fIiswgraph\fP() , \fIiswlower\fP() , \fIiswprint\fP() +, \fIiswpunct\fP() , \fIiswspace\fP() , \fIiswupper\fP() , \fIsetlocale\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/isxdigit.3p b/man3p/isxdigit.3p new file mode 100644 index 000000000..1354e527b --- /dev/null +++ b/man3p/isxdigit.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ISXDIGIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" isxdigit +.SH NAME +isxdigit \- test for a hexadecimal digit +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int isxdigit(int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIisxdigit\fP() function shall test whether \fIc\fP is a character +of class \fBxdigit\fP in the program's current +locale; see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, +Locale. +.LP +The \fIc\fP argument is an \fBint\fP, the value of which the application +shall ensure is a character representable as an +\fBunsigned char\fP or equal to the value of the macro EOF. If the +argument has any other value, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIisxdigit\fP() function shall return non-zero if \fIc\fP is +a hexadecimal digit; otherwise, it shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +To ensure applications portability, especially across natural languages, +only this function and those listed in the SEE ALSO +section should be used for character classification. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisalnum\fP() , \fIisalpha\fP() , \fIiscntrl\fP() , \fIisdigit\fP() +, \fIisgraph\fP() , +\fIislower\fP() , \fIisprint\fP() , \fIispunct\fP() , \fIisspace\fP() +, \fIisupper\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 7, +Locale, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/j0.3p b/man3p/j0.3p new file mode 100644 index 000000000..19b3cd144 --- /dev/null +++ b/man3p/j0.3p @@ -0,0 +1,88 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "J0" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" j0 +.SH NAME +j0, j1, jn \- Bessel functions of the first kind +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double j0(double\fP \fIx\fP\fB); +.br +double j1(double\fP \fIx\fP\fB); +.br +double jn(int\fP \fIn\fP\fB, double\fP \fIx\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIj0\fP(), \fIj1\fP(), and \fIjn\fP() functions shall compute +Bessel functions of \fIx\fP of the first kind of orders +0, 1, and \fIn\fP, respectively. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the relevant +Bessel value of \fIx\fP of the first kind. +.LP +If the \fIx\fP argument is too large in magnitude, or the correct +result would cause underflow, 0 shall be returned and a range +error may occur. +.LP +If \fIx\fP is NaN, a NaN shall be returned. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +Range\ Error +The value of \fIx\fP was too large in magnitude, or an underflow occurred. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +No other errors shall occur. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() , \fIy0\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/j1.3p b/man3p/j1.3p new file mode 100644 index 000000000..dec50d029 --- /dev/null +++ b/man3p/j1.3p @@ -0,0 +1 @@ +.so man3p/j0.3p diff --git a/man3p/jn.3p b/man3p/jn.3p new file mode 100644 index 000000000..dec50d029 --- /dev/null +++ b/man3p/jn.3p @@ -0,0 +1 @@ +.so man3p/j0.3p diff --git a/man3p/jrand48.3p b/man3p/jrand48.3p new file mode 100644 index 000000000..a71d5ed19 --- /dev/null +++ b/man3p/jrand48.3p @@ -0,0 +1 @@ +.so man3p/drand48.3p diff --git a/man3p/kill.3p b/man3p/kill.3p new file mode 100644 index 000000000..d96e28648 --- /dev/null +++ b/man3p/kill.3p @@ -0,0 +1,206 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "KILL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" kill +.SH NAME +kill \- send a signal to a process or a group of processes +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int kill(pid_t\fP \fIpid\fP\fB, int\fP \fIsig\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIkill\fP() function shall send a signal to a process or a group +of processes specified by \fIpid\fP. The signal to be +sent is specified by \fIsig\fP and is either one from the list given +in \fI\fP or 0. If \fIsig\fP is 0 (the null signal), error +checking is performed but +no signal is actually sent. The null signal can be used to check the +validity of \fIpid\fP. +.LP +For a process to have permission to send a signal to a process designated +by \fIpid\fP, unless the sending process has +appropriate privileges, the real or effective user ID of the sending +process shall match the real or saved set-user-ID of the +receiving process. +.LP +If \fIpid\fP is greater than 0, \fIsig\fP shall be sent to the process +whose process ID is equal to \fIpid\fP. +.LP +If \fIpid\fP is 0, \fIsig\fP shall be sent to all processes (excluding +an unspecified set of system processes) whose process +group ID is equal to the process group ID of the sender, and for which +the process has permission to send a signal. +.LP +If \fIpid\fP is -1, \fIsig\fP shall be sent to all processes (excluding +an unspecified set of system processes) for which the +process has permission to send that signal. +.LP +If \fIpid\fP is negative, but not -1, \fIsig\fP shall be sent to all +processes (excluding an unspecified set of system +processes) whose process group ID is equal to the absolute value of +\fIpid\fP, and for which the process has permission to send a +signal. +.LP +If the value of \fIpid\fP causes \fIsig\fP to be generated for the +sending process, and if \fIsig\fP is not blocked for the +calling thread and if no other thread has \fIsig\fP unblocked or is +waiting in a \fIsigwait\fP() function for \fIsig\fP, either \fIsig\fP +or at least one pending unblocked +signal shall be delivered to the sending thread before \fIkill\fP() +returns. +.LP +The user ID tests described above shall not be applied when sending +SIGCONT to a process that is a member of the same session as +the sending process. +.LP +An implementation that provides extended security controls may impose +further implementation-defined restrictions on the sending +of signals, including the null signal. In particular, the system may +deny the existence of some or all of the processes specified +by \fIpid\fP. +.LP +The \fIkill\fP() function is successful if the process has permission +to send \fIsig\fP to any of the processes specified by +\fIpid\fP. If \fIkill\fP() fails, no signal shall be sent. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIkill\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of the \fIsig\fP argument is an invalid or unsupported signal +number. +.TP 7 +.B EPERM +The process does not have permission to send the signal to any receiving +process. +.TP 7 +.B ESRCH +No process or process group can be found corresponding to that specified +by \fIpid\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The semantics for permission checking for \fIkill\fP() differed between +System V and most other implementations, such as +Version 7 or 4.3 BSD. The semantics chosen for this volume of IEEE\ Std\ 1003.1-2001 +agree with System V. Specifically, a +set-user-ID process cannot protect itself against signals (or at least +not against SIGKILL) unless it changes its real user ID. +This choice allows the user who starts an application to send it signals +even if it changes its effective user ID. The other +semantics give more power to an application that wants to protect +itself from the user who ran it. +.LP +Some implementations provide semantic extensions to the \fIkill\fP() +function when the absolute value of \fIpid\fP is greater +than some maximum, or otherwise special, value. Negative values are +a flag to \fIkill\fP(). Since most implementations return +[ESRCH] in this case, this behavior is not included in this volume +of IEEE\ Std\ 1003.1-2001, although a conforming +implementation could provide such an extension. +.LP +The implementation-defined processes to which a signal cannot be sent +may include the scheduler or \fIinit\fP. +.LP +There was initially strong sentiment to specify that, if \fIpid\fP +specifies that a signal be sent to the calling process and +that signal is not blocked, that signal would be delivered before +\fIkill\fP() returns. This would permit a process to call +\fIkill\fP() and be guaranteed that the call never return. However, +historical implementations that provide only the \fIsignal\fP() function +make only the weaker guarantee in this volume of +IEEE\ Std\ 1003.1-2001, because they only deliver one signal each +time a process enters the kernel. Modifications to such +implementations to support the \fIsigaction\fP() function generally +require entry to the +kernel following return from a signal-catching function, in order +to restore the signal mask. Such modifications have the effect of +satisfying the stronger requirement, at least when \fIsigaction\fP() +is used, but not +necessarily when \fIsignal\fP() is used. The developers of this volume +of +IEEE\ Std\ 1003.1-2001 considered making the stronger requirement +except when \fIsignal\fP() is used, but felt this would be unnecessarily +complex. Implementors are encouraged +to meet the stronger requirement whenever possible. In practice, the +weaker requirement is the same, except in the rare case when +two signals arrive during a very short window. This reasoning also +applies to a similar requirement for \fIsigprocmask\fP(). +.LP +In 4.2 BSD, the SIGCONT signal can be sent to any descendant process +regardless of user-ID security checks. This allows a job +control shell to continue a job even if processes in the job have +altered their user IDs (as in the \fIsu\fP command). In keeping +with the addition of the concept of sessions, similar functionality +is provided by allowing the SIGCONT signal to be sent to any +process in the same session regardless of user ID security checks. +This is less restrictive than BSD in the sense that ancestor +processes (in the same session) can now be the recipient. It is more +restrictive than BSD in the sense that descendant processes +that form new sessions are now subject to the user ID checks. A similar +relaxation of security is not necessary for the other job +control signals since those signals are typically sent by the terminal +driver in recognition of special characters being typed; the +terminal driver bypasses all security checks. +.LP +In secure implementations, a process may be restricted from sending +a signal to a process having a different security label. In +order to prevent the existence or nonexistence of a process from being +used as a covert channel, such processes should appear +nonexistent to the sender; that is, [ESRCH] should be returned, rather +than [EPERM], if \fIpid\fP refers only to such +processes. +.LP +Existing implementations vary on the result of a \fIkill\fP() with +\fIpid\fP indicating an inactive process (a terminated +process that has not been waited for by its parent). Some indicate +success on such a call (subject to permission checking), while +others give an error of [ESRCH]. Since the definition of process lifetime +in this volume of IEEE\ Std\ 1003.1-2001 covers +inactive processes, the [ESRCH] error as described is inappropriate +in this case. In particular, this means that an application +cannot have a parent process check for termination of a particular +child with \fIkill\fP(). (Usually this is done with the null +signal; this can be done reliably with \fIwaitpid\fP().) +.LP +There is some belief that the name \fIkill\fP() is misleading, since +the function is not always intended to cause process +termination. However, the name is common to all historical implementations, +and any change would be in conflict with the goal of +minimal changes to existing application code. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetpid\fP() , \fIraise\fP() , \fIsetsid\fP() +, \fIsigaction\fP() , \fIsigqueue\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/killpg.3p b/man3p/killpg.3p new file mode 100644 index 000000000..eeaac54f3 --- /dev/null +++ b/man3p/killpg.3p @@ -0,0 +1,59 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "KILLPG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" killpg +.SH NAME +killpg \- send a signal to a process group +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int killpg(pid_t\fP \fIpgrp\fP\fB, int\fP \fIsig\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIkillpg\fP() function shall send the signal specified by \fIsig\fP +to the process group specified by \fIpgrp\fP. +.LP +If \fIpgrp\fP is greater than 1, \fIkillpg\fP(\fIpgrp\fP,\ \fIsig\fP) +shall be equivalent to +\fIkill\fP(-\fIpgrp\fP,\ \fIsig\fP). If \fIpgrp\fP is less than or +equal to 1, the behavior of \fIkillpg\fP() is +undefined. +.SH RETURN VALUE +.LP +Refer to \fIkill\fP() . +.SH ERRORS +.LP +Refer to \fIkill\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetpgid\fP() , \fIgetpid\fP() , \fIkill\fP() +, \fIraise\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/l64a.3p b/man3p/l64a.3p new file mode 100644 index 000000000..282d4e0b6 --- /dev/null +++ b/man3p/l64a.3p @@ -0,0 +1 @@ +.so man3p/a64l.3p diff --git a/man3p/labs.3p b/man3p/labs.3p new file mode 100644 index 000000000..4b2ef7ceb --- /dev/null +++ b/man3p/labs.3p @@ -0,0 +1,58 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LABS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" labs +.SH NAME +labs, llabs \- return a long integer absolute value +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +long labs(long\fP \fIi\fP\fB); +.br +long long llabs(long long\fP \fIi\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIlabs\fP() function shall compute the absolute value of the +\fBlong\fP integer operand \fIi\fP. The \fIllabs\fP() +function shall compute the absolute value of the \fBlong long\fP integer +operand \fIi\fP. If the result cannot be represented, +the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIlabs\fP() function shall return the absolute value of the \fBlong\fP +integer operand. The \fIlabs\fP() function shall +return the absolute value of the \fBlong long\fP integer operand. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIabs\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/lchown.3p b/man3p/lchown.3p new file mode 100644 index 000000000..c336e4367 --- /dev/null +++ b/man3p/lchown.3p @@ -0,0 +1,140 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LCHOWN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" lchown +.SH NAME +lchown \- change the owner and group of a symbolic link +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int lchown(const char *\fP\fIpath\fP\fB, uid_t\fP \fIowner\fP\fB, +gid_t\fP \fIgroup\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIlchown\fP() function shall be equivalent to \fIchown\fP(), +except in the case +where the named file is a symbolic link. In this case, \fIlchown\fP() +shall change the ownership of the symbolic link file itself, +while \fIchown\fP() changes the ownership of the file or directory +to which the symbolic +link refers. +.SH RETURN VALUE +.LP +Upon successful completion, \fIlchown\fP() shall return 0. Otherwise, +it shall return -1 and set \fIerrno\fP to indicate an +error. +.SH ERRORS +.LP +The \fIlchown\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied on a component of the path prefix of \fIpath\fP. +.TP 7 +.B EINVAL +The owner or group ID is not a value supported by the implementation. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of a pathname exceeds {PATH_MAX} or a pathname component +is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix of \fIpath\fP is not a directory. +.TP 7 +.B EOPNOTSUPP +The \fIpath\fP argument names a symbolic link and the implementation +does not support setting the owner or group of a symbolic +link. +.TP 7 +.B EPERM +The effective user ID does not match the owner of the file and the +process does not have appropriate privileges. +.TP 7 +.B EROFS +The file resides on a read-only file system. +.sp +.LP +The \fIlchown\fP() function may fail if: +.TP 7 +.B EIO +An I/O error occurred while reading or writing to the file system. +.TP 7 +.B EINTR +A signal was caught during execution of the function. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Changing the Current Owner of a File +.LP +The following example shows how to change the ownership of the symbolic +link named \fB/modules/pass1\fP to the user ID +associated with "jones" and the group ID associated with "cnd". +.LP +The numeric value for the user ID is obtained by using the \fIgetpwnam\fP() +function. +The numeric value for the group ID is obtained by using the \fIgetgrnam\fP() +function. +.sp +.RS +.nf + +\fB#include +#include +#include +#include +.sp + +struct passwd *pwd; +struct group *grp; +char *path = "/modules/pass1"; +\&... +pwd = getpwnam("jones"); +grp = getgrnam("cnd"); +lchown(path, pwd->pw_uid, grp->gr_gid); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +On implementations which support symbolic links as directory entries +rather than files, \fIlchown\fP() may fail. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchown\fP() , \fIsymlink\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/lcong48.3p b/man3p/lcong48.3p new file mode 100644 index 000000000..a71d5ed19 --- /dev/null +++ b/man3p/lcong48.3p @@ -0,0 +1 @@ +.so man3p/drand48.3p diff --git a/man3p/ldexp.3p b/man3p/ldexp.3p new file mode 100644 index 000000000..43e0a856a --- /dev/null +++ b/man3p/ldexp.3p @@ -0,0 +1,110 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LDEXP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ldexp +.SH NAME +ldexp, ldexpf, ldexpl \- load exponent of a floating-point number +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double ldexp(double\fP \fIx\fP\fB, int\fP \fIexp\fP\fB); +.br +float ldexpf(float\fP \fIx\fP\fB, int\fP \fIexp\fP\fB); +.br +long double ldexpl(long double\fP \fIx\fP\fB, int\fP \fIexp\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the quantity \fIx\fP\ *\ 2**\fIexp\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return \fIx\fP multiplied +by 2, raised to the power \fIexp\fP. +.LP +If these functions would cause overflow, a range error shall occur +and \fIldexp\fP(), \fIldexpf\fP(), and \fIldexpl\fP() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL (according +to the sign of \fIx\fP), respectively. +.LP +If the correct value would cause underflow, and is not representable, +a range error may occur, and \ either 0.0 (if +supported), or \ an implementation-defined value shall be +returned. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0 or \(+-Inf, \fIx\fP shall be returned. +.LP +If \fIexp\fP is 0, \fIx\fP shall be returned. +.LP +If the correct value would cause underflow, and is representable, +a range error may occur and the correct value shall be +returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Range\ Error +The result overflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be +raised. +.sp +.LP +These functions may fail if: +.TP 7 +Range\ Error +The result underflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIfrexp\fP() , \fIisnan\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ldexpf.3p b/man3p/ldexpf.3p new file mode 100644 index 000000000..0596e2cdb --- /dev/null +++ b/man3p/ldexpf.3p @@ -0,0 +1 @@ +.so man3p/ldexp.3p diff --git a/man3p/ldexpl.3p b/man3p/ldexpl.3p new file mode 100644 index 000000000..0596e2cdb --- /dev/null +++ b/man3p/ldexpl.3p @@ -0,0 +1 @@ +.so man3p/ldexp.3p diff --git a/man3p/ldiv.3p b/man3p/ldiv.3p new file mode 100644 index 000000000..128da2806 --- /dev/null +++ b/man3p/ldiv.3p @@ -0,0 +1,84 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LDIV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ldiv +.SH NAME +ldiv, lldiv \- compute quotient and remainder of a long division +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +ldiv_t ldiv(long\fP \fInumer\fP\fB, long\fP \fIdenom\fP\fB); +.br +lldiv_t lldiv(long long\fP \fInumer\fP\fB, long long\fP \fIdenom\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the quotient and remainder of the division +of the numerator \fInumer\fP by the denominator +\fIdenom\fP. If the division is inexact, the resulting quotient is +the \fBlong\fP integer (for the \fIldiv\fP() function) or +\fBlong long\fP integer (for the \fIlldiv\fP() function) of lesser +magnitude that is the nearest to the algebraic quotient. If +the result cannot be represented, the behavior is undefined; otherwise, +\fIquot\fP\ *\ \fIdenom\fP+\fIrem\fP shall equal +\fInumer\fP. +.SH RETURN VALUE +.LP +The \fIldiv\fP() function shall return a structure of type \fBldiv_t\fP, +comprising both the quotient and the remainder. The +structure shall include the following members, in any order: +.sp +.RS +.nf + +\fBlong quot; /* Quotient */ +long rem; /* Remainder */ +\fP +.fi +.RE +.LP +The \fIlldiv\fP() function shall return a structure of type \fBlldiv_t\fP, +comprising both the quotient and the remainder. The +structure shall include the following members, in any order: +.sp +.RS +.nf + +\fBlong long quot; /* Quotient */ +long long rem; /* Remainder */ +\fP +.fi +.RE +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIdiv\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/lfind.3p b/man3p/lfind.3p new file mode 100644 index 000000000..0ee9f847a --- /dev/null +++ b/man3p/lfind.3p @@ -0,0 +1 @@ +.so man3p/lsearch.3p diff --git a/man3p/lgamma.3p b/man3p/lgamma.3p new file mode 100644 index 000000000..8d4a9e8fa --- /dev/null +++ b/man3p/lgamma.3p @@ -0,0 +1,118 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LGAMMA" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" lgamma +.SH NAME +lgamma, lgammaf, lgammal \- log gamma function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double lgamma(double\fP \fIx\fP\fB); +.br +float lgammaf(float\fP \fIx\fP\fB); +.br +long double lgammal(long double\fP \fIx\fP\fB); +.br +\fP +.LP +\fBextern int signgam; \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute +.sp +.sp +The argument \fIx\fP need not be a non-positive integer (Gamma(x) +is defined over the reals, +except the non-positive integers). +.LP +The sign of Gamma(x) is returned in the external integer \fIsigngam\fP. +.LP +These functions need not be reentrant. A function that is not required +to be reentrant is not required to be thread-safe. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the logarithmic +gamma of \fIx\fP. +.LP +If \fIx\fP is a non-positive integer, a pole error shall occur and +\fIlgamma\fP(), \fIlgammaf\fP(), and \fIlgammal\fP() +shall return +HUGE_VAL, +HUGE_VALF, and +HUGE_VALL, respectively. +.LP +If the correct value would cause overflow, a range error shall occur +and \fIlgamma\fP(), \fIlgammaf\fP(), and \fIlgammal\fP() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL (having +the same sign as the correct value), +respectively. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is 1 or 2, +0 shall be returned. +.LP +If \fIx\fP is \(+-Inf, +Inf shall be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Pole\ Error +The \fIx\fP argument is a negative integer or zero. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the divide-by-zero floating-point exception shall be +raised. +.TP 7 +Range\ Error +The result overflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexp\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/lgammaf.3p b/man3p/lgammaf.3p new file mode 100644 index 000000000..b17905e64 --- /dev/null +++ b/man3p/lgammaf.3p @@ -0,0 +1 @@ +.so man3p/lgamma.3p diff --git a/man3p/lgammal.3p b/man3p/lgammal.3p new file mode 100644 index 000000000..b17905e64 --- /dev/null +++ b/man3p/lgammal.3p @@ -0,0 +1 @@ +.so man3p/lgamma.3p diff --git a/man3p/link.3p b/man3p/link.3p new file mode 100644 index 000000000..d9eb87ac1 --- /dev/null +++ b/man3p/link.3p @@ -0,0 +1,202 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LINK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" link +.SH NAME +link \- link to a file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int link(const char *\fP\fIpath1\fP\fB, const char *\fP\fIpath2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIlink\fP() function shall create a new link (directory entry) +for the existing file, \fIpath1\fP. +.LP +The \fIpath1\fP argument points to a pathname naming an existing file. +The \fIpath2\fP argument points to a pathname naming +the new directory entry to be created. The \fIlink\fP() function shall +atomically create a new link for the existing file and the +link count of the file shall be incremented by one. +.LP +If \fIpath1\fP names a directory, \fIlink\fP() shall fail unless the +process has appropriate privileges and the implementation +supports using \fIlink\fP() on directories. +.LP +Upon successful completion, \fIlink\fP() shall mark for update the +\fIst_ctime\fP field of the file. Also, the \fIst_ctime\fP +and \fIst_mtime\fP fields of the directory that contains the new entry +shall be marked for update. +.LP +If \fIlink\fP() fails, no link shall be created and the link count +of the file shall remain unchanged. +.LP +The implementation may require that the calling process has permission +to access the existing file. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIlink\fP() function shall fail if: +.TP 7 +.B EACCES +A component of either path prefix denies search permission, or the +requested link requires writing in a directory that denies +write permission, or the calling process does not have permission +to access the existing file and this is required by the +implementation. +.TP 7 +.B EEXIST +The \fIpath2\fP argument resolves to an existing file or refers to +a symbolic link. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath1\fP or \fIpath2\fP argument. +.TP 7 +.B EMLINK +The number of links to the file named by \fIpath1\fP would exceed +{LINK_MAX}. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath1\fP or \fIpath2\fP argument exceeds {PATH_MAX} +or a pathname component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of either path prefix does not exist; the file named by +\fIpath1\fP does not exist; or \fIpath1\fP or +\fIpath2\fP points to an empty string. +.TP 7 +.B ENOSPC +The directory to contain the link cannot be extended. +.TP 7 +.B ENOTDIR +A component of either path prefix is not a directory. +.TP 7 +.B EPERM +The file named by \fIpath1\fP is a directory and either the calling +process does not have appropriate privileges or the +implementation prohibits using \fIlink\fP() on directories. +.TP 7 +.B EROFS +The requested link requires writing in a directory on a read-only +file system. +.TP 7 +.B EXDEV +The link named by \fIpath2\fP and the file named by \fIpath1\fP are +on different file systems and the implementation does not +support links between file systems. +.TP 7 +.B EXDEV +\fIpath1\fP refers to a named STREAM. +.sp +.LP +The \fIlink\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath1\fP or \fIpath2\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath1\fP +or \fIpath2\fP argument, the length of the +substituted pathname string exceeded {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Creating a Link to a File +.LP +The following example shows how to create a link to a file named \fB/home/cnd/mod1\fP +by creating a new directory entry named +\fB/modules/pass1\fP. +.sp +.RS +.nf + +\fB#include +.sp + +char *path1 = "/home/cnd/mod1"; +char *path2 = "/modules/pass1"; +int status; +\&... +status = link (path1, path2); +\fP +.fi +.RE +.SS Creating a Link to a File Within a Program +.LP +In the following program example, the \fIlink\fP() function links +the \fB/etc/passwd\fP file (defined as \fBPASSWDFILE\fP) to +a file named \fB/etc/opasswd\fP (defined as \fBSAVEFILE\fP), which +is used to save the current password file. Then, after +removing the current password file (defined as \fBPASSWDFILE\fP), +the new password file is saved as the current password file +using the \fIlink\fP() function again. +.sp +.RS +.nf + +\fB#include +.sp + +#define LOCKFILE "/etc/ptmp" +#define PASSWDFILE "/etc/passwd" +#define SAVEFILE "/etc/opasswd" +\&... +/* Save current password file */ +link (PASSWDFILE, SAVEFILE); +.sp + +/* Remove current password file. */ +unlink (PASSWDFILE); +.sp + +/* Save new password file as current password file. */ +link (LOCKFILE,PASSWDFILE); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +Some implementations do allow links between file systems. +.SH RATIONALE +.LP +Linking to a directory is restricted to the superuser in most historical +implementations because this capability may produce +loops in the file hierarchy or otherwise corrupt the file system. +This volume of IEEE\ Std\ 1003.1-2001 continues that +philosophy by prohibiting \fIlink\fP() and \fIunlink\fP() from doing +this. Other functions +could do it if the implementor designed such an extension. +.LP +Some historical implementations allow linking of files on different +file systems. Wording was added to explicitly allow this +optional behavior. +.LP +The exception for cross-file system links is intended to apply only +to links that are programmatically indistinguishable from +"hard" links. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsymlink\fP() , \fIunlink\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/lio_listio.3p b/man3p/lio_listio.3p new file mode 100644 index 000000000..26a9b96b7 --- /dev/null +++ b/man3p/lio_listio.3p @@ -0,0 +1,225 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LIO_LISTIO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" lio_listio +.SH NAME +lio_listio \- list directed I/O (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int lio_listio(int\fP \fImode\fP\fB, struct aiocb *restrict const\fP +\fIlist\fP\fB[restrict], +.br +\ \ \ \ \ \ int\fP \fInent\fP\fB, struct sigevent *restrict\fP \fIsig\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIlio_listio\fP() function shall initiate a list of I/O requests +with a single function call. +.LP +The \fImode\fP argument takes one of the values LIO_WAIT or LIO_NOWAIT +declared in \fI\fP and determines whether the function returns +when the I/O operations have been +completed, or as soon as the operations have been queued. If the \fImode\fP +argument is LIO_WAIT, the function shall wait until +all I/O is complete and the \fIsig\fP argument shall be ignored. +.LP +If the \fImode\fP argument is LIO_NOWAIT, the function shall return +immediately, and asynchronous notification shall occur, +according to the \fIsig\fP argument, when all the I/O operations complete. +If \fIsig\fP is NULL, then no asynchronous +notification shall occur. If \fIsig\fP is not NULL, asynchronous notification +occurs as specified in \fISignal Generation and Delivery\fP when all +the requests in \fIlist\fP have +completed. +.LP +The I/O requests enumerated by \fIlist\fP are submitted in an unspecified +order. +.LP +The \fIlist\fP argument is an array of pointers to \fBaiocb\fP structures. +The array contains \fInent\fP elements. The array +may contain NULL elements, which shall be ignored. +.LP +The \fIaio_lio_opcode\fP field of each \fBaiocb\fP structure specifies +the operation to be performed. The supported operations +are LIO_READ, LIO_WRITE, and LIO_NOP; these symbols are defined in +\fI\fP. The +LIO_NOP operation causes the list entry to be ignored. If the \fIaio_lio_opcode\fP +element is equal to LIO_READ, then an I/O +operation is submitted as if by a call to \fIaio_read\fP() with the +\fIaiocbp\fP equal +to the address of the \fBaiocb\fP structure. If the \fIaio_lio_opcode\fP +element is equal to LIO_WRITE, then an I/O operation is +submitted as if by a call to \fIaio_write\fP() with the \fIaiocbp\fP +equal to the +address of the \fBaiocb\fP structure. +.LP +The \fIaio_fildes\fP member specifies the file descriptor on which +the operation is to be performed. +.LP +The \fIaio_buf\fP member specifies the address of the buffer to or +from which the data is transferred. +.LP +The \fIaio_nbytes\fP member specifies the number of bytes of data +to be transferred. +.LP +The members of the \fBaiocb\fP structure further describe the I/O +operation to be performed, in a manner identical to that of +the corresponding \fBaiocb\fP structure when used by the \fIaio_read\fP() +and \fIaio_write\fP() functions. +.LP +The \fInent\fP argument specifies how many elements are members of +the list; that is, the length of the array. +.LP +The behavior of this function is altered according to the definitions +of synchronized I/O data integrity completion and +synchronized I/O file integrity completion if synchronized I/O is +enabled on the file associated with \fIaio_fildes\fP. +.LP +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +\fIaiocbp\fP->\fIaio_fildes\fP. +.SH RETURN VALUE +.LP +If the \fImode\fP argument has the value LIO_NOWAIT, the \fIlio_listio\fP() +function shall return the value zero if the I/O +operations are successfully queued; otherwise, the function shall +return the value -1 and set \fIerrno\fP to indicate the +error. +.LP +If the \fImode\fP argument has the value LIO_WAIT, the \fIlio_listio\fP() +function shall return the value zero when all the +indicated I/O has completed successfully. Otherwise, \fIlio_listio\fP() +shall return a value of -1 and set \fIerrno\fP to +indicate the error. +.LP +In either case, the return value only indicates the success or failure +of the \fIlio_listio\fP() call itself, not the status of +the individual I/O requests. In some cases one or more of the I/O +requests contained in the list may fail. Failure of an individual +request does not prevent completion of any other individual request. +To determine the outcome of each I/O request, the application +shall examine the error status associated with each \fBaiocb\fP control +block. The error statuses so returned are identical to +those returned as the result of an \fIaio_read\fP() or \fIaio_write\fP() +function. +.SH ERRORS +.LP +The \fIlio_listio\fP() function shall fail if: +.TP 7 +.B EAGAIN +The resources necessary to queue all the I/O requests were not available. +The application may check the error status for each +\fBaiocb\fP to determine the individual request(s) that failed. +.TP 7 +.B EAGAIN +The number of entries indicated by \fInent\fP would cause the system-wide +limit {AIO_MAX} to be exceeded. +.TP 7 +.B EINVAL +The \fImode\fP argument is not a proper value, or the value of \fInent\fP +was greater than {AIO_LISTIO_MAX}. +.TP 7 +.B EINTR +A signal was delivered while waiting for all I/O requests to complete +during an LIO_WAIT operation. Note that, since each I/O +operation invoked by \fIlio_listio\fP() may possibly provoke a signal +when it completes, this error return may be caused by the +completion of one (or more) of the very I/O operations being awaited. +Outstanding I/O requests are not canceled, and the +application shall examine each list element to determine whether the +request was initiated, canceled, or completed. +.TP 7 +.B EIO +One or more of the individual I/O operations failed. The application +may check the error status for each \fBaiocb\fP structure +to determine the individual request(s) that failed. +.sp +.LP +In addition to the errors returned by the \fIlio_listio\fP() function, +if the \fIlio_listio\fP() function succeeds or fails +with errors of [EAGAIN], [EINTR], or [EIO], then some of the I/O specified +by the list may have been initiated. If the +\fIlio_listio\fP() function fails with an error code other than [EAGAIN], +[EINTR], or [EIO], no operations from the list shall +have been initiated. The I/O operation indicated by each list element +can encounter errors specific to the individual read or write +function being performed. In this event, the error status for each +\fBaiocb\fP control block contains the associated error code. +The error codes that can be set are the same as would be set by a +\fIread\fP() or \fIwrite\fP() function, with the following additional +error codes possible: +.TP 7 +.B EAGAIN +The requested I/O operation was not queued due to resource limitations. +.TP 7 +.B ECANCELED +The requested I/O was canceled before the I/O completed due to an +explicit \fIaio_cancel\fP() request. +.TP 7 +.B EFBIG +The \fIaiocbp\fP->\fIaio_lio_opcode\fP is LIO_WRITE, the file is a +regular file, \fIaiocbp\fP->\fIaio_nbytes\fP is +greater than 0, and the \fIaiocbp\fP->\fIaio_offset\fP is greater +than or equal to the offset maximum in the open file +description associated with \fIaiocbp\fP->\fIaio_fildes\fP. +.TP 7 +.B EINPROGRESS +The requested I/O is in progress. +.TP 7 +.B EOVERFLOW +The \fIaiocbp\fP->\fIaio_lio_opcode\fP is LIO_READ, the file is a +regular file, \fIaiocbp\fP->\fIaio_nbytes\fP is +greater than 0, and the \fIaiocbp\fP->\fIaio_offset\fP is before the +end-of-file and is greater than or equal to the offset +maximum in the open file description associated with \fIaiocbp\fP->\fIaio_fildes\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Although it may appear that there are inconsistencies in the specified +circumstances for error codes, the [EIO] error condition +applies when any circumstance relating to an individual operation +makes that operation fail. This might be due to a badly +formulated request (for example, the \fIaio_lio_opcode\fP field is +invalid, and \fIaio_error\fP() returns [EINVAL]) or might arise from +application behavior (for example, the +file descriptor is closed before the operation is initiated, and \fIaio_error\fP() +returns [EBADF]). +.LP +The limitation on the set of error codes returned when operations +from the list shall have been initiated enables applications +to know when operations have been started and whether \fIaio_error\fP() +is valid for a +specific operation. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIaio_read\fP() , \fIaio_write\fP() , \fIaio_error\fP() , \fIaio_return\fP() +, \fIaio_cancel\fP() , \fIclose\fP() , \fIexec\fP() , \fIexit\fP() +, \fIfork\fP() , \fIlseek\fP() , \fIread\fP() , the Base Definitions +volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/listen.3p b/man3p/listen.3p new file mode 100644 index 000000000..4318f52d9 --- /dev/null +++ b/man3p/listen.3p @@ -0,0 +1,115 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LISTEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" listen +.SH NAME +listen \- listen for socket connections and limit the queue of incoming +connections +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int listen(int\fP \fIsocket\fP\fB, int\fP \fIbacklog\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIlisten\fP() function shall mark a connection-mode socket, specified +by the \fIsocket\fP argument, as accepting +connections. +.LP +The \fIbacklog\fP argument provides a hint to the implementation which +the implementation shall use to limit the number of +outstanding connections in the socket's listen queue. Implementations +may impose a limit on \fIbacklog\fP and silently reduce the +specified value. Normally, a larger \fIbacklog\fP argument value shall +result in a larger or equal length of the listen queue. +Implementations shall support values of \fIbacklog\fP up to SOMAXCONN, +defined in \fI\fP. +.LP +The implementation may include incomplete connections in its listen +queue. The limits on the number of incomplete connections +and completed connections queued may be different. +.LP +The implementation may have an upper limit on the length of the listen +queue-either global or per accepting socket. If +\fIbacklog\fP exceeds this limit, the length of the listen queue is +set to the limit. +.LP +If \fIlisten\fP() is called with a \fIbacklog\fP argument value that +is less than 0, the function behaves as if it had been +called with a \fIbacklog\fP argument value of 0. +.LP +A \fIbacklog\fP argument of 0 may allow the socket to accept connections, +in which case the length of the listen queue may be +set to an implementation-defined minimum value. +.LP +The socket in use may require the process to have appropriate privileges +to use the \fIlisten\fP() function. +.SH RETURN VALUE +.LP +Upon successful completions, \fIlisten\fP() shall return 0; otherwise, +-1 shall be returned and \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +The \fIlisten\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid file descriptor. +.TP 7 +.B EDESTADDRREQ +.sp +The socket is not bound to a local address, and the protocol does +not support listening on an unbound socket. +.TP 7 +.B EINVAL +The \fIsocket\fP is already connected. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.TP 7 +.B EOPNOTSUPP +The socket protocol does not support \fIlisten\fP(). +.sp +.LP +The \fIlisten\fP() function may fail if: +.TP 7 +.B EACCES +The calling process does not have the appropriate privileges. +.TP 7 +.B EINVAL +The \fIsocket\fP has been shut down. +.TP 7 +.B ENOBUFS +Insufficient resources are available in the system to complete the +call. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIaccept\fP() , \fIconnect\fP() , \fIsocket\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/llabs.3p b/man3p/llabs.3p new file mode 100644 index 000000000..dfcca077e --- /dev/null +++ b/man3p/llabs.3p @@ -0,0 +1 @@ +.so man3p/labs.3p diff --git a/man3p/lldiv.3p b/man3p/lldiv.3p new file mode 100644 index 000000000..ee66ba288 --- /dev/null +++ b/man3p/lldiv.3p @@ -0,0 +1 @@ +.so man3p/ldiv.3p diff --git a/man3p/llrint.3p b/man3p/llrint.3p new file mode 100644 index 000000000..135966f5d --- /dev/null +++ b/man3p/llrint.3p @@ -0,0 +1,102 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LLRINT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" llrint +.SH NAME +llrint, llrintf, llrintl \- round to the nearest integer value using +current rounding direction +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +long long llrint(double\fP \fIx\fP\fB); +.br +long long llrintf(float\fP \fIx\fP\fB); +.br +long long llrintl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall round their argument to the nearest integer +value, rounding according to the current rounding +direction. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the rounded +integer value. +.LP +If +\fIx\fP is NaN, a domain error shall occur, and an unspecified value +is returned. +.LP +If \fIx\fP is +Inf, a domain error shall occur and an unspecified +value is returned. +.LP +If \fIx\fP is -Inf, a domain error shall occur and an unspecified +value is returned. +.LP +If the correct value is positive and too large to represent as a \fBlong +long\fP, a domain error shall occur and an unspecified +value is returned. +.LP +If the correct value is negative and too large to represent as a \fBlong +long\fP, a domain error shall occur and an unspecified +value is returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The \fIx\fP argument is NaN or \(+-Inf, or the correct value is not +representable as an integer. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +These functions provide floating-to-integer conversions. They round +according to the current rounding direction. If the rounded +value is outside the range of the return type, the numeric result +is unspecified and the invalid floating-point exception is +raised. When they raise no other floating-point exception and the +result differs from the argument, they raise the inexact +floating-point exception. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIlrint\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/llrintf.3p b/man3p/llrintf.3p new file mode 100644 index 000000000..8ae956fa5 --- /dev/null +++ b/man3p/llrintf.3p @@ -0,0 +1 @@ +.so man3p/llrint.3p diff --git a/man3p/llrintl.3p b/man3p/llrintl.3p new file mode 100644 index 000000000..8ae956fa5 --- /dev/null +++ b/man3p/llrintl.3p @@ -0,0 +1 @@ +.so man3p/llrint.3p diff --git a/man3p/llround.3p b/man3p/llround.3p new file mode 100644 index 000000000..b65ed8506 --- /dev/null +++ b/man3p/llround.3p @@ -0,0 +1,100 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LLROUND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" llround +.SH NAME +llround, llroundf, llroundl \- round to nearest integer value +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +long long llround(double\fP \fIx\fP\fB); +.br +long long llroundf(float\fP \fIx\fP\fB); +.br +long long llroundl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall round their argument to the nearest integer +value, rounding halfway cases away from zero, regardless of +the current rounding direction. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the rounded +integer value. +.LP +If +\fIx\fP is NaN, a domain error shall occur, and an unspecified value +is returned. +.LP +If \fIx\fP is +Inf, a domain error shall occur and an unspecified +value is returned. +.LP +If \fIx\fP is -Inf, a domain error shall occur and an unspecified +value is returned. +.LP +If the correct value is positive and too large to represent as a \fBlong +long\fP, a domain error shall occur and an unspecified +value is returned. +.LP +If the correct value is negative and too large to represent as a \fBlong +long\fP, a domain error shall occur and an unspecified +value is returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The \fIx\fP argument is NaN or \(+-Inf, or the correct value is not +representable as an integer. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +These functions differ from the \fIllrint\fP() functions in that the +default rounding +direction for the \fIllround\fP() functions round halfway cases away +from zero and need not raise the inexact floating-point +exception for non-integer arguments that round to within the range +of the return type. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIlround\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/llroundf.3p b/man3p/llroundf.3p new file mode 100644 index 000000000..75555acb9 --- /dev/null +++ b/man3p/llroundf.3p @@ -0,0 +1 @@ +.so man3p/llround.3p diff --git a/man3p/llroundl.3p b/man3p/llroundl.3p new file mode 100644 index 000000000..75555acb9 --- /dev/null +++ b/man3p/llroundl.3p @@ -0,0 +1 @@ +.so man3p/llround.3p diff --git a/man3p/localeconv.3p b/man3p/localeconv.3p new file mode 100644 index 000000000..c61937a1b --- /dev/null +++ b/man3p/localeconv.3p @@ -0,0 +1,317 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LOCALECONV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" localeconv +.SH NAME +localeconv \- return locale-specific information +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +struct lconv *localeconv(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fIlocaleconv\fP() function shall set the components of an object +with the type \fBstruct lconv\fP with the values +appropriate for the formatting of numeric quantities (monetary and +otherwise) according to the rules of the current locale. +.LP +The members of the structure with type \fBchar *\fP are pointers to +strings, any of which (except \fBdecimal_point\fP) can +point to \fB""\fP , to indicate that the value is not available in +the current locale or is of zero length. The members with +type \fBchar\fP are non-negative numbers, any of which can be {CHAR_MAX} +to indicate that the value is not available in the +current locale. +.LP +The members include the following: +.TP 7 +\fBchar\ *decimal_point\fP +.sp +The radix character used to format non-monetary quantities. +.TP 7 +\fBchar\ *thousands_sep\fP +.sp +The character used to separate groups of digits before the decimal-point +character in formatted non-monetary quantities. +.TP 7 +\fBchar\ *grouping\fP +.sp +A string whose elements taken as one-byte integer values indicate +the size of each group of digits in formatted non-monetary +quantities. +.TP 7 +\fBchar\ *int_curr_symbol\fP +.sp +The international currency symbol applicable to the current locale. +The first three characters contain the alphabetic international +currency symbol in accordance with those specified in the ISO\ 4217:1995 +standard. The fourth character (immediately preceding +the null byte) is the character used to separate the international +currency symbol from the monetary quantity. +.TP 7 +\fBchar\ *currency_symbol\fP +.sp +The local currency symbol applicable to the current locale. +.TP 7 +\fBchar\ *mon_decimal_point\fP +.sp +The radix character used to format monetary quantities. +.TP 7 +\fBchar\ *mon_thousands_sep\fP +.sp +The separator for groups of digits before the decimal-point in formatted +monetary quantities. +.TP 7 +\fBchar\ *mon_grouping\fP +.sp +A string whose elements taken as one-byte integer values indicate +the size of each group of digits in formatted monetary +quantities. +.TP 7 +\fBchar\ *positive_sign\fP +.sp +The string used to indicate a non-negative valued formatted monetary +quantity. +.TP 7 +\fBchar\ *negative_sign\fP +.sp +The string used to indicate a negative valued formatted monetary quantity. +.TP 7 +\fBchar\ int_frac_digits\fP +.sp +The number of fractional digits (those after the decimal-point) to +be displayed in an internationally formatted monetary +quantity. +.TP 7 +\fBchar\ frac_digits\fP +.sp +The number of fractional digits (those after the decimal-point) to +be displayed in a formatted monetary quantity. +.TP 7 +\fBchar\ p_cs_precedes\fP +.sp +Set to 1 if the \fBcurrency_symbol\fP precedes the value for a non-negative +formatted monetary quantity. Set to 0 if the symbol +succeeds the value. +.TP 7 +\fBchar\ p_sep_by_space\fP +.sp +Set to a value indicating the separation of the \fBcurrency_symbol\fP, +the sign string, and the value for a non-negative formatted +monetary quantity. +.TP 7 +\fBchar\ n_cs_precedes\fP +.sp +Set to 1 if the \fBcurrency_symbol\fP precedes the value for a negative +formatted monetary quantity. Set to 0 if the symbol +succeeds the value. +.TP 7 +\fBchar\ n_sep_by_space\fP +.sp +Set to a value indicating the separation of the \fBcurrency_symbol\fP, +the sign string, and the value for a negative formatted +monetary quantity. +.TP 7 +\fBchar\ p_sign_posn\fP +.sp +Set to a value indicating the positioning of the \fBpositive_sign\fP +for a non-negative formatted monetary quantity. +.TP 7 +\fBchar\ n_sign_posn\fP +.sp +Set to a value indicating the positioning of the \fBnegative_sign\fP +for a negative formatted monetary quantity. +.TP 7 +\fBchar\ int_p_cs_precedes\fP +.sp +Set to 1 or 0 if the \fBint_curr_symbol\fP respectively precedes or +succeeds the value for a non-negative internationally +formatted monetary quantity. +.TP 7 +\fBchar\ int_n_cs_precedes\fP +.sp +Set to 1 or 0 if the \fBint_curr_symbol\fP respectively precedes or +succeeds the value for a negative internationally formatted +monetary quantity. +.TP 7 +\fBchar\ int_p_sep_by_space\fP +.sp +Set to a value indicating the separation of the \fBint_curr_symbol\fP, +the sign string, and the value for a non-negative +internationally formatted monetary quantity. +.TP 7 +\fBchar\ int_n_sep_by_space\fP +.sp +Set to a value indicating the separation of the \fBint_curr_symbol\fP, +the sign string, and the value for a negative +internationally formatted monetary quantity. +.TP 7 +\fBchar\ int_p_sign_posn\fP +.sp +Set to a value indicating the positioning of the \fBpositive_sign\fP +for a non-negative internationally formatted monetary +quantity. +.TP 7 +\fBchar\ int_n_sign_posn\fP +.sp +Set to a value indicating the positioning of the \fBnegative_sign\fP +for a negative internationally formatted monetary +quantity. +.sp +.LP +The elements of \fBgrouping\fP and \fBmon_grouping\fP are interpreted +according to the following: +.TP 7 +{CHAR_MAX} +No further grouping is to be performed. +.TP 7 +0 +The previous element is to be repeatedly used for the remainder of +the digits. +.TP 7 +\fIother\fP +The integer value is the number of digits that comprise the current +group. The next element is examined to determine the size +of the next group of digits before the current group. +.sp +.LP +The values of \fBp_sep_by_space\fP, \fBn_sep_by_space\fP, \fBint_p_sep_by_space\fP, +and \fBint_n_sep_by_space\fP are +interpreted according to the following: +.TP 7 +0 +No space separates the currency symbol and value. +.TP 7 +1 +If the currency symbol and sign string are adjacent, a space separates +them from the value; otherwise, a space separates the +currency symbol from the value. +.TP 7 +2 +If the currency symbol and sign string are adjacent, a space separates +them; otherwise, a space separates the sign string from +the value. +.sp +.LP +For \fBint_p_sep_by_space\fP and \fBint_n_sep_by_space\fP, the fourth +character of \fBint_curr_symbol\fP is used instead of a +space. +.LP +The values of \fBp_sign_posn\fP, \fBn_sign_posn\fP, \fBint_p_sign_posn\fP, +and \fBint_n_sign_posn\fP are interpreted +according to the following: +.TP 7 +0 +Parentheses surround the quantity and \fBcurrency_symbol\fP or \fBint_curr_symbol\fP. +.TP 7 +1 +The sign string precedes the quantity and \fBcurrency_symbol\fP or +\fBint_curr_symbol\fP. +.TP 7 +2 +The sign string succeeds the quantity and \fBcurrency_symbol\fP or +\fBint_curr_symbol\fP. +.TP 7 +3 +The sign string immediately precedes the \fBcurrency_symbol\fP or +\fBint_curr_symbol\fP. +.TP 7 +4 +The sign string immediately succeeds the \fBcurrency_symbol\fP or +\fBint_curr_symbol\fP. +.sp +.LP +The implementation shall behave as if no function in this volume of +IEEE\ Std\ 1003.1-2001 calls +\fIlocaleconv\fP(). +.LP +The +\fIlocaleconv\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +The \fIlocaleconv\fP() function shall return a pointer to the filled-in +object. The application shall not modify the structure +pointed to by the return value which may be overwritten by a subsequent +call to \fIlocaleconv\fP(). In addition, calls to \fIsetlocale\fP() +with the categories \fILC_ALL ,\fP \fILC_MONETARY ,\fP or \fILC_NUMERIC\fP +may overwrite the contents of the structure. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The following table illustrates the rules which may be used by four +countries to format monetary quantities. +.TS C +center; l1 l1 l1 l. +\fBCountry\fP \fBPositive Format\fP \fBNegative Format\fP \fBInternational Format\fP +Italy L.1.230 -L.1.230 ITL.1.230 +Netherlands F 1.234,56 F -1.234,56 NLG 1.234,56 +Norway kr1.234,56 kr1.234,56- NOK 1.234,56 +Switzerland SFrs.1,234.56 SFrs.1,234.56C CHF 1,234.56 +.TE +.LP +For these four countries, the respective values for the monetary members +of the structure returned by \fIlocaleconv\fP() +are: +.TS C +center; l2 l2 l2 l2 l. +\fB\ \fP \fBItaly\fP \fBNetherlands\fP \fBNorway\fP \fBSwitzerland\fP +\fBint_curr_symbol\fP "ITL." "NLG " "NOK " "CHF " +\fBcurrency_symbol\fP "L." "F" "kr" "SFrs." +\fBmon_decimal_point\fP "" "," "," "." +\fBmon_thousands_sep\fP "." "." "." "," +\fBmon_grouping\fP "\\3" "\\3" "\\3" "\\3" +\fBpositive_sign\fP "" "" "" "" +\fBnegative_sign\fP "-" "-" "-" "C" +\fBint_frac_digits\fP 0 2 2 2 +\fBfrac_digits\fP 0 2 2 2 +\fBp_cs_precedes\fP 1 1 1 1 +\fBp_sep_by_space\fP 0 1 0 0 +\fBn_cs_precedes\fP 1 1 1 1 +\fBn_sep_by_space\fP 0 1 0 0 +\fBp_sign_posn\fP 1 1 1 1 +\fBn_sign_posn\fP 1 4 2 2 +\fBint_p_cs_precedes\fP 1 1 1 1 +\fBint_n_cs_precedes\fP 1 1 1 1 +\fBint_p_sep_by_space\fP 0 0 0 0 +\fBint_n_sep_by_space\fP 0 0 0 0 +\fBint_p_sign_posn\fP 1 1 1 1 +\fBint_n_sign_posn\fP 1 4 4 2 +.TE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisalpha\fP() , \fIisascii\fP() , \fInl_langinfo\fP() , \fIprintf\fP() +, \fIscanf\fP() , +\fIsetlocale\fP() , \fIstrcat\fP() , \fIstrchr\fP() , \fIstrcmp\fP() +, \fIstrcoll\fP() , \fIstrcpy\fP() , \fIstrftime\fP() , \fIstrlen\fP() +, \fIstrpbrk\fP() , \fIstrspn\fP() , \fIstrtok\fP() , \fIstrxfrm\fP() +, \fIstrtod\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/localtime.3p b/man3p/localtime.3p new file mode 100644 index 000000000..482228755 --- /dev/null +++ b/man3p/localtime.3p @@ -0,0 +1,200 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LOCALTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" localtime +.SH NAME +localtime, localtime_r \- convert a time value to a broken-down local +time +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +struct tm *localtime(const time_t *\fP\fItimer\fP\fB); +.br +\fP +.LP +\fBstruct tm *localtime_r(const time_t *restrict\fP \fItimer\fP\fB, +.br +\ \ \ \ \ \ struct tm *restrict\fP \fIresult\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +For \fIlocaltime\fP(): The functionality described on this reference +page is aligned with the ISO\ C standard. Any +conflict between the requirements described here and the ISO\ C standard +is unintentional. This volume of +IEEE\ Std\ 1003.1-2001 defers to the ISO\ C standard. +.LP +The \fIlocaltime\fP() function shall convert the time in seconds since +the Epoch pointed to by \fItimer\fP into a broken-down +time, expressed as a local time. The function corrects for the timezone +and any seasonal time adjustments. \ Local timezone +information is used as though \fIlocaltime\fP() calls \fItzset\fP(). +.LP +The relationship between a time in seconds since the Epoch used as +an argument to \fIlocaltime\fP() and the \fBtm\fP structure +(defined in the \fI\fP header) is that the result shall be +as specified in the +expression given in the definition of seconds since the Epoch (see +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 4.14, Seconds Since the Epoch) corrected for timezone and +any seasonal +time adjustments, where the names in the structure and in the expression +correspond. +.LP +The same relationship shall apply for \fIlocaltime_r\fP(). +.LP +The +\fIlocaltime\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.LP +The \fIasctime\fP(), \fIctime\fP(), \fIgmtime\fP(), and \fIlocaltime\fP() +functions shall return values in one of two static objects: +a broken-down time structure and an array of type \fBchar\fP. Execution +of any of the functions may overwrite the information +returned in either of these objects by any of the other functions. +.LP +The \fIlocaltime_r\fP() function shall convert the time in seconds +since the Epoch pointed to by \fItimer\fP into a broken-down +time stored in the structure to which \fIresult\fP points. The \fIlocaltime_r\fP() +function shall also return a pointer to that +same structure. +.LP +Unlike \fIlocaltime\fP(), the reentrant version is not required to +set \fItzname\fP. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIlocaltime\fP() function shall return +a pointer to the broken-down time structure. If an +error is detected, \fIlocaltime\fP() shall return a null pointer +\ and set \fIerrno\fP to indicate the error. +.LP +Upon successful completion, \fIlocaltime_r\fP() shall return a pointer +to the structure pointed to by the argument \fIresult\fP. +.SH ERRORS +.LP +The \fIlocaltime\fP() function shall fail if: +.TP 7 +.B EOVERFLOW +The result cannot be represented. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Getting the Local Date and Time +.LP +The following example uses the \fItime\fP() function to calculate +the time elapsed, in +seconds, since January 1, 1970 0:00 UTC (the Epoch), \fIlocaltime\fP() +to convert that value to a broken-down time, and \fIasctime\fP() to +convert the broken-down time values into a printable string. +.sp +.RS +.nf + +\fB#include +#include +.sp + +int main(void) +{ + time_t result; +.sp + + result = time(NULL); + printf("%s%ju secs since the Epoch\\n", + asctime(localtime(&result)), + (uintmax_t)result); + return(0); +} +\fP +.fi +.RE +.LP +This example writes the current time to \fIstdout\fP in a form like +this: +.sp +.RS +.nf + +\fBWed Jun 26 10:32:15 1996 +835810335 secs since the Epoch +\fP +.fi +.RE +.SS Getting the Modification Time for a File +.LP +The following example gets the modification time for a file. The \fIlocaltime\fP() +function converts the \fBtime_t\fP value of +the last modification date, obtained by a previous call to \fIstat\fP(), +into a \fBtm\fP +structure that contains the year, month, day, and so on. +.sp +.RS +.nf + +\fB#include +\&... +struct stat statbuf; +\&... +tm = localtime(&statbuf.st_mtime); +\&... +\fP +.fi +.RE +.SS Timing an Event +.LP +The following example gets the current time, converts it to a string +using \fIlocaltime\fP() and \fIasctime\fP(), and prints it to standard +output using \fIfputs\fP(). It then prints the number of minutes to +an event being timed. +.sp +.RS +.nf + +\fB#include +#include +\&... +time_t now; +int minutes_to_event; +\&... +time(&now); +printf("The time is "); +fputs(asctime(localtime(&now)), stdout); +printf("There are still %d minutes to the event.\\n", + minutes_to_event); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIlocaltime_r\fP() function is thread-safe and returns values +in a user-supplied buffer instead of possibly using a static +data area that may be overwritten by each call. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIasctime\fP() , \fIclock\fP() , \fIctime\fP() +, \fIdifftime\fP() , \fIgetdate\fP() , \fIgmtime\fP() , \fImktime\fP() +, \fIstrftime\fP() , \fIstrptime\fP() , \fItime\fP() , \fIutime\fP() +, the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/localtime_r.3p b/man3p/localtime_r.3p new file mode 100644 index 000000000..a8ccf45f4 --- /dev/null +++ b/man3p/localtime_r.3p @@ -0,0 +1 @@ +.so man3p/localtime.3p diff --git a/man3p/lockf.3p b/man3p/lockf.3p new file mode 100644 index 000000000..92d2a57c2 --- /dev/null +++ b/man3p/lockf.3p @@ -0,0 +1,224 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LOCKF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" lockf +.SH NAME +lockf \- record locking on files +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int lockf(int\fP \fIfildes\fP\fB, int\fP \fIfunction\fP\fB, off_t\fP +\fIsize\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIlockf\fP() function shall lock sections of a file with advisory-mode +locks. Calls to \fIlockf\fP() from other threads +which attempt to lock the locked file section shall either return +an error value or block until the section becomes unlocked. All +the locks for a process are removed when the process terminates. Record +locking with \fIlockf\fP() shall be supported for regular +files and may be supported for other files. +.LP +The \fIfildes\fP argument is an open file descriptor. To establish +a lock with this function, the file descriptor shall be +opened with write-only permission (O_WRONLY) or with read/write permission +(O_RDWR). +.LP +The \fIfunction\fP argument is a control value which specifies the +action to be taken. The permissible values for +\fIfunction\fP are defined in \fI\fP as follows: +.TS C +center; l2 l. +\fBFunction\fP \fBDescription\fP +F_ULOCK Unlock locked sections. +F_LOCK Lock a section for exclusive use. +F_TLOCK Test and lock a section for exclusive use. +F_TEST Test a section for locks by other processes. +.TE +.LP +F_TEST shall detect if a lock by another process is present on the +specified section. +.LP +F_LOCK and F_TLOCK shall both lock a section of a file if the section +is available. +.LP +F_ULOCK shall remove locks from a section of the file. +.LP +The \fIsize\fP argument is the number of contiguous bytes to be locked +or unlocked. The section to be locked or unlocked starts +at the current offset in the file and extends forward for a positive +size or backward for a negative size (the preceding bytes up +to but not including the current offset). If \fIsize\fP is 0, the +section from the current offset through the largest possible +file offset shall be locked (that is, from the current offset through +the present or any future end-of-file). An area need not be +allocated to the file to be locked because locks may exist past the +end-of-file. +.LP +The sections locked with F_LOCK or F_TLOCK may, in whole or in part, +contain or be contained by a previously locked section for +the same process. When this occurs, or if adjacent locked sections +would occur, the sections shall be combined into a single locked +section. If the request would cause the number of locks to exceed +a system-imposed limit, the request shall fail. +.LP +F_LOCK and F_TLOCK requests differ only by the action taken if the +section is not available. F_LOCK shall block the calling +thread until the section is available. F_TLOCK shall cause the function +to fail if the section is already locked by another +process. +.LP +File locks shall be released on first close by the locking process +of any file descriptor for the file. +.LP +F_ULOCK requests may release (wholly or in part) one or more locked +sections controlled by the process. Locked sections shall be +unlocked starting at the current file offset through \fIsize\fP bytes +or to the end-of-file if \fIsize\fP is (\fBoff_t\fP)0. +When all of a locked section is not released (that is, when the beginning +or end of the area to be unlocked falls within a locked +section), the remaining portions of that section shall remain locked +by the process. Releasing the center portion of a locked +section shall cause the remaining locked beginning and end portions +to become two separate locked sections. If the request would +cause the number of locks in the system to exceed a system-imposed +limit, the request shall fail. +.LP +A potential for deadlock occurs if the threads of a process controlling +a locked section are blocked by accessing another +process' locked section. If the system detects that deadlock would +occur, \fIlockf\fP() shall fail with an [EDEADLK] error. +.LP +The interaction between \fIfcntl\fP() and \fIlockf\fP() locks is unspecified. +.LP +Blocking on a section shall be interrupted by any signal. +.LP +An F_ULOCK request in which \fIsize\fP is non-zero and the offset +of the last byte of the requested section is the maximum +value for an object of type \fBoff_t\fP, when the process has an existing +lock in which \fIsize\fP is 0 and which includes the +last byte of the requested section, shall be treated as a request +to unlock from the start of the requested section with a size +equal to 0. Otherwise, an F_ULOCK request shall attempt to unlock +only the requested section. +.LP +Attempting to lock a section of a file that is associated with a buffered +stream produces unspecified results. +.SH RETURN VALUE +.LP +Upon successful completion, \fIlockf\fP() shall return 0. Otherwise, +it shall return -1, set \fIerrno\fP to indicate an error, +and existing locks shall not be changed. +.SH ERRORS +.LP +The \fIlockf\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid open file descriptor; or +\fIfunction\fP is F_LOCK or F_TLOCK and \fIfildes\fP is +not a valid file descriptor open for writing. +.TP 7 +.B EACCES \fRor\fP EAGAIN +.sp +The \fIfunction\fP argument is F_TLOCK or F_TEST and the section is +already locked by another process. +.TP 7 +.B EDEADLK +The \fIfunction\fP argument is F_LOCK and a deadlock is detected. +.TP 7 +.B EINTR +A signal was caught during execution of the function. +.TP 7 +.B EINVAL +The \fIfunction\fP argument is not one of F_LOCK, F_TLOCK, F_TEST, +or F_ULOCK; or \fIsize\fP plus the current file offset is +less than 0. +.TP 7 +.B EOVERFLOW +The offset of the first, or if \fIsize\fP is not 0 then the last, +byte in the requested section cannot be represented +correctly in an object of type \fBoff_t\fP. +.sp +.LP +The \fIlockf\fP() function may fail if: +.TP 7 +.B EAGAIN +The \fIfunction\fP argument is F_LOCK or F_TLOCK and the file is mapped +with \fImmap\fP(). +.TP 7 +.B EDEADLK \fRor\fP ENOLCK +.sp +The \fIfunction\fP argument is F_LOCK, F_TLOCK, or F_ULOCK, and the +request would cause the number of locks to exceed a +system-imposed limit. +.TP 7 +.B EOPNOTSUPP \fRor\fP EINVAL +.sp +The implementation does not support the locking of files of the type +indicated by the \fIfildes\fP argument. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Locking a Portion of a File +.LP +In the following example, a file named \fB/home/cnd/mod1\fP is being +modified. Other processes that use locking are prevented +from changing it during this process. Only the first 10000 bytes are +locked, and the lock call fails if another process has any +part of this area locked already. +.sp +.RS +.nf + +\fB#include +#include +.sp + +int fildes; +int status; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +status = lockf(fildes, F_TLOCK, (off_t)10000); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +Record-locking should not be used in combination with the \fIfopen\fP(), +\fIfread\fP(), \fIfwrite\fP(), and other \fIstdio\fP +functions. Instead, the more primitive, non-buffered functions (such +as \fIopen\fP()) should +be used. Unexpected results may occur in processes that do buffering +in the user address space. The process may later read/write +data which is/was locked. The \fIstdio\fP functions are the most common +source of unexpected buffering. +.LP +The \fIalarm\fP() function may be used to provide a timeout facility +in applications +requiring it. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIalarm\fP() , \fIchmod\fP() , \fIclose\fP() , \fIcreat\fP() , \fIfcntl\fP() +, \fIfopen\fP() , \fImmap\fP() , \fIopen\fP() , \fIread\fP() , \fIwrite\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/log.3p b/man3p/log.3p new file mode 100644 index 000000000..8bc98ebd8 --- /dev/null +++ b/man3p/log.3p @@ -0,0 +1,103 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LOG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" log +.SH NAME +log, logf, logl \- natural logarithm function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double log(double\fP \fIx\fP\fB); +.br +float logf(float\fP \fIx\fP\fB); +.br +long double logl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the natural logarithm of their argument +\fIx\fP, +log_\fIe\fP(\fIx\fP). +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the natural +logarithm of \fIx\fP. +.LP +If \fIx\fP is \(+-0, a pole error shall occur and \fIlog\fP(), \fIlogf\fP(), +and \fIlogl\fP() shall return -HUGE_VAL, +-HUGE_VALF, and -HUGE_VALL, respectively. +.LP +For finite values of \fIx\fP that are less than 0, \ or if \fIx\fP +is -Inf, a domain error shall occur, and \ either a NaN (if supported), +or \ an implementation-defined value shall be returned. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is 1, +0 shall be returned. +.LP +If \fIx\fP is +Inf, \fIx\fP shall be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The finite value of \fIx\fP is negative, \ or \fIx\fP is -Inf. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be +raised. +.TP 7 +Pole\ Error +The value of \fIx\fP is zero. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the divide-by-zero floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexp\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() +, \fIlog10\fP() , +\fIlog1p\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 4.18, Treatment of Error Conditions for Mathematical Functions, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/log10.3p b/man3p/log10.3p new file mode 100644 index 000000000..fb9be1891 --- /dev/null +++ b/man3p/log10.3p @@ -0,0 +1,101 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LOG10" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" log10 +.SH NAME +log10, log10f, log10l \- base 10 logarithm function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double log10(double\fP \fIx\fP\fB); +.br +float log10f(float\fP \fIx\fP\fB); +.br +long double log10l(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the base 10 logarithm of their argument +\fIx\fP, log_10(\fIx\fP). +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the base +10 logarithm of \fIx\fP. +.LP +If \fIx\fP is \(+-0, a pole error shall occur and \fIlog10\fP(), \fIlog10f\fP(), +and \fIlog10l\fP() shall return +-HUGE_VAL, -HUGE_VALF, and -HUGE_VALL, respectively. +.LP +For finite values of \fIx\fP that are less than 0, \ or if \fIx\fP +is -Inf, a domain error shall occur, and \ either a NaN (if supported), +or \ an implementation-defined value shall be returned. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is 1, +0 shall be returned. +.LP +If \fIx\fP is +Inf, +Inf shall be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The finite value of \fIx\fP is negative, \ or \fIx\fP is -Inf. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be +raised. +.TP 7 +Pole\ Error +The value of \fIx\fP is zero. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the divide-by-zero floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() , \fIlog\fP() +, \fIpow\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error +Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/log10f.3p b/man3p/log10f.3p new file mode 100644 index 000000000..815b492fa --- /dev/null +++ b/man3p/log10f.3p @@ -0,0 +1 @@ +.so man3p/log10.3p diff --git a/man3p/log10l.3p b/man3p/log10l.3p new file mode 100644 index 000000000..815b492fa --- /dev/null +++ b/man3p/log10l.3p @@ -0,0 +1 @@ +.so man3p/log10.3p diff --git a/man3p/log1p.3p b/man3p/log1p.3p new file mode 100644 index 000000000..d497440ff --- /dev/null +++ b/man3p/log1p.3p @@ -0,0 +1,112 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LOG1P" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" log1p +.SH NAME +log1p, log1pf, log1pl \- compute a natural logarithm +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double log1p(double\fP \fIx\fP\fB); +.br +float log1pf(float\fP \fIx\fP\fB); +.br +long double log1pl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute log_e(1.0 + \fIx\fP). +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the natural +logarithm of 1.0 + \fIx\fP. +.LP +If \fIx\fP is -1, a pole error shall occur and \fIlog1p\fP(), \fIlog1pf\fP(), +and \fIlog1pl\fP() shall return -HUGE_VAL, +-HUGE_VALF, and -HUGE_VALL, respectively. +.LP +For finite values of \fIx\fP that are less than -1, \ or if \fIx\fP +is -Inf, a domain error shall occur, and \ either a NaN (if supported), +or \ an implementation-defined value shall be returned. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, or +Inf, \fIx\fP shall be returned. +.LP +If \fIx\fP is subnormal, a range error may occur and \fIx\fP should +be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The finite value of \fIx\fP is less than -1, \ or \fIx\fP is -Inf. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be +raised. +.TP 7 +Pole\ Error +The value of \fIx\fP is -1. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the divide-by-zero floating-point exception shall be +raised. +.sp +.LP +These functions may fail if: +.TP 7 +Range\ Error +The value of \fIx\fP is subnormal. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIlog\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/log1pf.3p b/man3p/log1pf.3p new file mode 100644 index 000000000..94f881c10 --- /dev/null +++ b/man3p/log1pf.3p @@ -0,0 +1 @@ +.so man3p/log1p.3p diff --git a/man3p/log1pl.3p b/man3p/log1pl.3p new file mode 100644 index 000000000..94f881c10 --- /dev/null +++ b/man3p/log1pl.3p @@ -0,0 +1 @@ +.so man3p/log1p.3p diff --git a/man3p/log2.3p b/man3p/log2.3p new file mode 100644 index 000000000..d3a62adec --- /dev/null +++ b/man3p/log2.3p @@ -0,0 +1,100 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LOG2" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" log2 +.SH NAME +log2, log2f, log2l \- compute base 2 logarithm functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double log2(double\fP \fIx\fP\fB); +.br +float log2f(float\fP \fIx\fP\fB); +.br +long double log2l(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the base 2 logarithm of their argument +\fIx\fP, log_2(\fIx\fP). +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the base +2 logarithm of \fIx\fP. +.LP +If \fIx\fP is \(+-0, a pole error shall occur and \fIlog2\fP(), \fIlog2f\fP(), +and \fIlog2l\fP() shall return -HUGE_VAL, +-HUGE_VALF, and -HUGE_VALL, respectively. +.LP +For finite values of \fIx\fP that are less than 0, \ or if \fIx\fP +is -Inf, a domain error shall occur, and \ either a NaN (if supported), +or \ an implementation-defined value shall be returned. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is 1, +0 shall be returned. +.LP +If \fIx\fP is +Inf, \fIx\fP shall be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The finite value of \fIx\fP is less than zero, \ or \fIx\fP is -Inf. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be +raised. +.TP 7 +Pole\ Error +The value of \fIx\fP is zero. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the divide-by-zero floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIlog\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/log2f.3p b/man3p/log2f.3p new file mode 100644 index 000000000..2399a106a --- /dev/null +++ b/man3p/log2f.3p @@ -0,0 +1 @@ +.so man3p/log2.3p diff --git a/man3p/log2l.3p b/man3p/log2l.3p new file mode 100644 index 000000000..2399a106a --- /dev/null +++ b/man3p/log2l.3p @@ -0,0 +1 @@ +.so man3p/log2.3p diff --git a/man3p/logb.3p b/man3p/logb.3p new file mode 100644 index 000000000..905cee5cb --- /dev/null +++ b/man3p/logb.3p @@ -0,0 +1,102 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LOGB" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" logb +.SH NAME +logb, logbf, logbl \- radix-independent exponent +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double logb(double\fP \fIx\fP\fB); +.br +float logbf(float\fP \fIx\fP\fB); +.br +long double logbl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the exponent of \fIx\fP, which is the +integral part of log\fI_r\fP +|\fIx\fP|, as a signed floating-point value, for non-zero \fIx\fP, +where \fIr\fP is the radix of the machine's floating-point +arithmetic, which is the value of FLT_RADIX defined in the \fI\fP +header. +.LP +If \fIx\fP is subnormal it is treated as though it were normalized; +thus for finite positive \fIx\fP: +.sp +.RS +.nf + +\fB1 <=\fP \fIx\fP \fB* FLT_RADIX**-logb(x) < FLT_RADIX +\fP +.fi +.RE +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the exponent +of \fIx\fP. +.LP +If \fIx\fP is \(+-0, a pole error shall occur and \fIlogb\fP(), \fIlogbf\fP(), +and \fIlogbl\fP() shall return -HUGE_VAL, +-HUGE_VALF, and -HUGE_VALL, respectively. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-Inf, +Inf shall be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Pole\ Error +The value of \fIx\fP is \(+-0. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the divide-by-zero floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIilogb\fP() , \fIscalb\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/logbf.3p b/man3p/logbf.3p new file mode 100644 index 000000000..fcb44d7f3 --- /dev/null +++ b/man3p/logbf.3p @@ -0,0 +1 @@ +.so man3p/logb.3p diff --git a/man3p/logbl.3p b/man3p/logbl.3p new file mode 100644 index 000000000..fcb44d7f3 --- /dev/null +++ b/man3p/logbl.3p @@ -0,0 +1 @@ +.so man3p/logb.3p diff --git a/man3p/logf.3p b/man3p/logf.3p new file mode 100644 index 000000000..3a026a7e6 --- /dev/null +++ b/man3p/logf.3p @@ -0,0 +1 @@ +.so man3p/log.3p diff --git a/man3p/logl.3p b/man3p/logl.3p new file mode 100644 index 000000000..3a026a7e6 --- /dev/null +++ b/man3p/logl.3p @@ -0,0 +1 @@ +.so man3p/log.3p diff --git a/man3p/longjmp.3p b/man3p/longjmp.3p new file mode 100644 index 000000000..355780f91 --- /dev/null +++ b/man3p/longjmp.3p @@ -0,0 +1,100 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LONGJMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" longjmp +.SH NAME +longjmp \- non-local goto +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void longjmp(jmp_buf\fP \fIenv\fP\fB, int\fP \fIval\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIlongjmp\fP() function shall restore the environment saved by +the most recent invocation of \fIsetjmp\fP() in the same thread, with +the corresponding \fBjmp_buf\fP argument. If there is no +such invocation, or if the function containing the invocation of \fIsetjmp\fP() +has +terminated execution in the interim, or if the invocation of \fIsetjmp\fP() +was within the +scope of an identifier with variably modified type and execution has +left that scope in the interim, the behavior is undefined. +\ It is unspecified whether \fIlongjmp\fP() restores the signal mask, +leaves the signal mask unchanged, or restores it to its +value at the time \fIsetjmp\fP() was called. +.LP +All accessible objects have values, and all other components of the +abstract machine have state (for example, floating-point +status flags and open files), as of the time \fIlongjmp\fP() was called, +except that the values of objects of automatic storage +duration are unspecified if they meet all the following conditions: +.IP " *" 3 +They are local to the function containing the corresponding \fIsetjmp\fP() +invocation. +.LP +.IP " *" 3 +They do not have volatile-qualified type. +.LP +.IP " *" 3 +They are changed between the \fIsetjmp\fP() invocation and \fIlongjmp\fP() +call. +.LP +.LP +As +it bypasses the usual function call and return mechanisms, \fIlongjmp\fP() +shall execute correctly in contexts of interrupts, +signals, and any of their associated functions. However, if \fIlongjmp\fP() +is invoked from a nested signal handler (that is, from +a function invoked as a result of a signal raised during the handling +of another signal), the behavior is undefined. +.LP +The effect of a call to \fIlongjmp\fP() where initialization of the +\fBjmp_buf\fP structure was not performed in the calling +thread is undefined. +.SH RETURN VALUE +.LP +After \fIlongjmp\fP() is completed, program execution continues as +if the corresponding invocation of \fIsetjmp\fP() had just returned +the value specified by \fIval\fP. The \fIlongjmp\fP() function +shall not cause \fIsetjmp\fP() to return 0; if \fIval\fP is 0, \fIsetjmp\fP() +shall return 1. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications whose behavior depends on the value of the signal mask +should not use \fIlongjmp\fP() and \fIsetjmp\fP(), since their effect +on the signal mask is unspecified, but should instead use the \fIsiglongjmp\fP() +and \fIsigsetjmp\fP() +functions (which can save and restore the signal mask under application +control). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsetjmp\fP() , \fIsigaction\fP() , \fIsiglongjmp\fP() , \fIsigsetjmp\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/lrand48.3p b/man3p/lrand48.3p new file mode 100644 index 000000000..a71d5ed19 --- /dev/null +++ b/man3p/lrand48.3p @@ -0,0 +1 @@ +.so man3p/drand48.3p diff --git a/man3p/lrint.3p b/man3p/lrint.3p new file mode 100644 index 000000000..80fcfb2ed --- /dev/null +++ b/man3p/lrint.3p @@ -0,0 +1,102 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LRINT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" lrint +.SH NAME +lrint, lrintf, lrintl \- round to nearest integer value using current +rounding direction +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +long lrint(double\fP \fIx\fP\fB); +.br +long lrintf(float\fP \fIx\fP\fB); +.br +long lrintl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall round their argument to the nearest integer +value, rounding according to the current rounding +direction. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the rounded +integer value. +.LP +If +\fIx\fP is NaN, a domain error shall occur and an unspecified value +is returned. +.LP +If \fIx\fP is +Inf, a domain error shall occur and an unspecified +value is returned. +.LP +If \fIx\fP is -Inf, a domain error shall occur and an unspecified +value is returned. +.LP +If the correct value is positive and too large to represent as a \fBlong\fP, +a domain error shall occur and an unspecified +value is returned. +.LP +If the correct value is negative and too large to represent as a \fBlong\fP, +a domain error shall occur and an unspecified +value is returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The \fIx\fP argument is NaN or \(+-Inf, or the correct value is not +representable as an integer. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +These functions provide floating-to-integer conversions. They round +according to the current rounding direction. If the rounded +value is outside the range of the return type, the numeric result +is unspecified and the invalid floating-point exception is +raised. When they raise no other floating-point exception and the +result differs from the argument, they raise the inexact +floating-point exception. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIllrint\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/lrintf.3p b/man3p/lrintf.3p new file mode 100644 index 000000000..523041a48 --- /dev/null +++ b/man3p/lrintf.3p @@ -0,0 +1 @@ +.so man3p/lrint.3p diff --git a/man3p/lrintl.3p b/man3p/lrintl.3p new file mode 100644 index 000000000..523041a48 --- /dev/null +++ b/man3p/lrintl.3p @@ -0,0 +1 @@ +.so man3p/lrint.3p diff --git a/man3p/lround.3p b/man3p/lround.3p new file mode 100644 index 000000000..e2faadcf5 --- /dev/null +++ b/man3p/lround.3p @@ -0,0 +1,100 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LROUND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" lround +.SH NAME +lround, lroundf, lroundl \- round to nearest integer value +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +long lround(double\fP \fIx\fP\fB); +.br +long lroundf(float\fP \fIx\fP\fB); +.br +long lroundl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall round their argument to the nearest integer +value, rounding halfway cases away from zero, regardless of +the current rounding direction. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the rounded +integer value. +.LP +If +\fIx\fP is NaN, a domain error shall occur and an unspecified value +is returned. +.LP +If \fIx\fP is +Inf, a domain error shall occur and an unspecified +value is returned. +.LP +If \fIx\fP is -Inf, a domain error shall occur and an unspecified +value is returned. +.LP +If the correct value is positive and too large to represent as a \fBlong\fP, +a domain error shall occur and an unspecified +value is returned. +.LP +If the correct value is negative and too large to represent as a \fBlong\fP, +a domain error shall occur and an unspecified +value is returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The \fIx\fP argument is NaN or \(+-Inf, or the correct value is not +representable as an integer. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +These functions differ from the \fIlrint\fP() functions in the default +rounding +direction, with the \fIlround\fP() functions rounding halfway cases +away from zero and needing not to raise the inexact +floating-point exception for non-integer arguments that round to within +the range of the return type. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIllround\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/lroundf.3p b/man3p/lroundf.3p new file mode 100644 index 000000000..69c83b3b9 --- /dev/null +++ b/man3p/lroundf.3p @@ -0,0 +1 @@ +.so man3p/lround.3p diff --git a/man3p/lroundl.3p b/man3p/lroundl.3p new file mode 100644 index 000000000..69c83b3b9 --- /dev/null +++ b/man3p/lroundl.3p @@ -0,0 +1 @@ +.so man3p/lround.3p diff --git a/man3p/lsearch.3p b/man3p/lsearch.3p new file mode 100644 index 000000000..223edd09b --- /dev/null +++ b/man3p/lsearch.3p @@ -0,0 +1,141 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LSEARCH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" lsearch +.SH NAME +lsearch, lfind \- linear search and update +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void *lsearch(const void *\fP\fIkey\fP\fB, void *\fP\fIbase\fP\fB, +size_t *\fP\fInelp\fP\fB, size_t\fP +\fIwidth\fP\fB, +.br +\ \ \ \ \ \ int (*\fP\fIcompar\fP\fB)(const void *, const void *)); +.br +void *lfind(const void *\fP\fIkey\fP\fB, const void *\fP\fIbase\fP\fB, +size_t *\fP\fInelp\fP\fB, +.br +\ \ \ \ \ \ size_t width, int (*\fP\fIcompar\fP\fB)(const void *, +const void *)); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIlsearch\fP() function shall linearly search the table and return +a pointer into the table for the matching entry. If the +entry does not occur, it shall be added at the end of the table. The +\fIkey\fP argument points to the entry to be sought in the +table. The \fIbase\fP argument points to the first element in the +table. The \fIwidth\fP argument is the size of an element in +bytes. The \fInelp\fP argument points to an integer containing the +current number of elements in the table. The integer to which +\fInelp\fP points shall be incremented if the entry is added to the +table. The \fIcompar\fP argument points to a comparison +function which the application shall supply (for example, \fIstrcmp\fP()). +It is called +with two arguments that point to the elements being compared. The +application shall ensure that the function returns 0 if the +elements are equal, and non-zero otherwise. +.LP +The \fIlfind\fP() function shall be equivalent to \fIlsearch\fP(), +except that if the entry is not found, it is not added to +the table. Instead, a null pointer is returned. +.SH RETURN VALUE +.LP +If the searched for entry is found, both \fIlsearch\fP() and \fIlfind\fP() +shall return a pointer to it. Otherwise, +\fIlfind\fP() shall return a null pointer and \fIlsearch\fP() shall +return a pointer to the newly added element. +.LP +Both functions shall return a null pointer in case of error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Storing Strings in a Table +.LP +This fragment reads in less than or equal to TABSIZE strings of length +less than or equal to ELSIZE and stores them in a table, +eliminating duplicates. +.sp +.RS +.nf + +\fB#include +#include +#include +.sp + +#define TABSIZE 50 +#define ELSIZE 120 +.sp + +\&... + char line[ELSIZE], tab[TABSIZE][ELSIZE]; + size_t nel = 0; + ... + while (fgets(line, ELSIZE, stdin) != NULL && nel < TABSIZE) + (void) lsearch(line, tab, &nel, + ELSIZE, (int (*)(const void *, const void *)) strcmp); + ... +\fP +.fi +.RE +.SS Finding a Matching Entry +.LP +The following example finds any line that reads \fB"This is a test."\fP +\&. +.sp +.RS +.nf + +\fB#include +#include +\&... +char line[ELSIZE], tab[TABSIZE][ELSIZE]; +size_t nel = 0; +char *findline; +void *entry; +.sp + +findline = "This is a test.\\n"; +.sp + +entry = lfind(findline, tab, &nel, ELSIZE, ( + int (*)(const void *, const void *)) strcmp); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The comparison function need not compare every byte, so arbitrary +data may be contained in the elements in addition to the +values being compared. +.LP +Undefined results can occur if there is not enough room in the table +to add a new item. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIhcreate\fP() , \fItsearch\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/lseek.3p b/man3p/lseek.3p new file mode 100644 index 000000000..87e3805f1 --- /dev/null +++ b/man3p/lseek.3p @@ -0,0 +1,133 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LSEEK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" lseek +.SH NAME +lseek \- move the read/write file offset +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +off_t lseek(int\fP \fIfildes\fP\fB, off_t\fP \fIoffset\fP\fB, int\fP +\fIwhence\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIlseek\fP() function shall set the file offset for the open +file description associated with the file descriptor +\fIfildes,\fP as follows: +.IP " *" 3 +If \fIwhence\fP is SEEK_SET, the file offset shall be set to \fIoffset\fP +bytes. +.LP +.IP " *" 3 +If \fIwhence\fP is SEEK_CUR, the file offset shall be set to its current +location plus \fIoffset\fP. +.LP +.IP " *" 3 +If \fIwhence\fP is SEEK_END, the file offset shall be set to the size +of the file plus \fIoffset\fP. +.LP +.LP +The symbolic constants SEEK_SET, SEEK_CUR, and SEEK_END are defined +in \fI\fP. +.LP +The behavior of \fIlseek\fP() on devices which are incapable of seeking +is implementation-defined. The value of the file offset +associated with such a device is undefined. +.LP +The \fIlseek\fP() function shall allow the file offset to be set beyond +the end of the existing data in the file. If data is +later written at this point, subsequent reads of data in the gap shall +return bytes with the value 0 until data is actually written +into the gap. +.LP +The \fIlseek\fP() function shall not, by itself, extend the size of +a file. +.LP +If \fIfildes\fP refers to a shared memory object, the result of the +\fIlseek\fP() function is unspecified. +.LP +If \fIfildes\fP refers to a typed memory object, the result of the +\fIlseek\fP() function is unspecified. +.SH RETURN VALUE +.LP +Upon successful completion, the resulting offset, as measured in bytes +from the beginning of the file, shall be returned. +Otherwise, (\fBoff_t\fP)-1 shall be returned, \fIerrno\fP shall be +set to indicate the error, and the file offset shall remain +unchanged. +.SH ERRORS +.LP +The \fIlseek\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not an open file descriptor. +.TP 7 +.B EINVAL +The \fIwhence\fP argument is not a proper value, or the resulting +file offset would be negative for a regular file, block +special file, or directory. +.TP 7 +.B EOVERFLOW +The resulting file offset would be a value which cannot be represented +correctly in an object of type \fBoff_t\fP. +.TP 7 +.B ESPIPE +The \fIfildes\fP argument is associated with a pipe, FIFO, or socket. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The ISO\ C standard includes the functions \fIfgetpos\fP() and \fIfsetpos\fP(), +which work on very large files by use of a special positioning type. +.LP +Although \fIlseek\fP() may position the file offset beyond the end +of the file, this function does not itself extend the size +of the file. While the only function in IEEE\ Std\ 1003.1-2001 that +may directly extend the size of the file is \fIwrite\fP(), \fItruncate\fP(), +and \fIftruncate\fP(), several functions originally derived from the +ISO\ C standard, such as \fIfwrite\fP(), \fIfprintf\fP(), and so on, +may do so +(by causing calls on \fIwrite\fP()). +.LP +An invalid file offset that would cause [EINVAL] to be returned may +be both implementation-defined and device-dependent (for +example, memory may have few invalid values). A negative file offset +may be valid for some devices in some implementations. +.LP +The POSIX.1-1990 standard did not specifically prohibit \fIlseek\fP() +from returning a negative offset. Therefore, an +application was required to clear \fIerrno\fP prior to the call and +check \fIerrno\fP upon return to determine whether a return +value of ( \fBoff_t\fP)-1 is a negative offset or an indication of +an error condition. The standard developers did not wish to +require this action on the part of a conforming application, and chose +to require that \fIerrno\fP be set to [EINVAL] when the +resulting file offset would be negative for a regular file, block +special file, or directory. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIopen\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/lstat.3p b/man3p/lstat.3p new file mode 100644 index 000000000..dbe1d0bb1 --- /dev/null +++ b/man3p/lstat.3p @@ -0,0 +1,137 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LSTAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" lstat +.SH NAME +lstat \- get symbolic link status +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int lstat(const char *restrict\fP \fIpath\fP\fB, struct stat *restrict\fP +\fIbuf\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIlstat\fP() function shall be equivalent to \fIstat\fP(), except +when \fIpath\fP +refers to a symbolic link. In that case \fIlstat\fP() shall return +information about the link, while \fIstat\fP() shall return information +about the file the link references. +.LP +For symbolic links, the \fIst_mode\fP member shall contain meaningful +information when used with the file type macros, and the +\fIst_size\fP member shall contain the length of the pathname contained +in the symbolic link. File mode bits and the contents of +the remaining members of the \fBstat\fP structure are unspecified. +The value returned in the \fIst_size\fP member is the length +of the contents of the symbolic link, and does not count any trailing +null. +.SH RETURN VALUE +.LP +Upon successful completion, \fIlstat\fP() shall return 0. Otherwise, +it shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fIlstat\fP() function shall fail if: +.TP 7 +.B EACCES +A component of the path prefix denies search permission. +.TP 7 +.B EIO +An error occurred while reading from the file system. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of a pathname exceeds {PATH_MAX} or a pathname component +is longer than {NAME_MAX}. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B EOVERFLOW +The file size in bytes or the number of blocks allocated to the file +or the file serial number cannot be represented correctly +in the structure pointed to by \fIbuf\fP. +.sp +.LP +The \fIlstat\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.TP 7 +.B EOVERFLOW +One of the members is too large to store into the structure pointed +to by the \fIbuf\fP argument. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Obtaining Symbolic Link Status Information +.LP +The following example shows how to obtain status information for a +symbolic link named \fB/modules/pass1\fP. The structure +variable \fIbuffer\fP is defined for the \fBstat\fP structure. If +the \fIpath\fP argument specified the filename for the file +pointed to by the symbolic link ( \fB/home/cnd/mod1\fP), the results +of calling the function would be the same as those returned +by a call to the \fIstat\fP() function. +.sp +.RS +.nf + +\fB#include +.sp + +struct stat buffer; +int status; +\&... +status = lstat("/modules/pass1", &buffer); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIlstat\fP() function is not required to update the time-related +fields if the named file is not a symbolic link. While +the \fIst_uid\fP, \fIst_gid\fP, \fIst_atime\fP, \fIst_mtime\fP, and +\fIst_ctime\fP members of the \fBstat\fP structure may +apply to a symbolic link, they are not required to do so. No functions +in IEEE\ Std\ 1003.1-2001 are required to maintain +any of these time fields. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfstat\fP() , \fIreadlink\fP() , \fIstat\fP() +, \fIsymlink\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/makecontext.3p b/man3p/makecontext.3p new file mode 100644 index 000000000..f7cd844d6 --- /dev/null +++ b/man3p/makecontext.3p @@ -0,0 +1,142 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MAKECONTEXT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" makecontext +.SH NAME +makecontext, swapcontext \- manipulate user contexts +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void makecontext(ucontext_t *\fP\fIucp\fP\fB, void (*\fP\fIfunc\fP\fB)(void), +.br +\ \ \ \ \ \ int\fP \fIargc\fP\fB, ...); +.br +int swapcontext(ucontext_t *restrict\fP \fIoucp\fP\fB, +.br +\ \ \ \ \ \ const ucontext_t *restrict\fP \fIucp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImakecontext\fP() function shall modify the context specified +by \fIucp\fP, which has been initialized using \fIgetcontext\fP(). +When this context is resumed using \fIswapcontext\fP() or \fIsetcontext\fP(), +program execution shall continue by calling \fIfunc\fP, passing it +the +arguments that follow \fIargc\fP in the \fImakecontext\fP() call. +.LP +Before a call is made to \fImakecontext\fP(), the application shall +ensure that the context being modified has a stack +allocated for it. The application shall ensure that the value of \fIargc\fP +matches the number of arguments of type \fBint\fP +passed to \fIfunc\fP; otherwise, the behavior is undefined. +.LP +The \fIuc_link\fP member is used to determine the context that shall +be resumed when the context being modified by +\fImakecontext\fP() returns. The application shall ensure that the +\fIuc_link\fP member is initialized prior to the call to +\fImakecontext\fP(). +.LP +The \fIswapcontext\fP() function shall save the current context in +the context structure pointed to by \fIoucp\fP and shall +set the context to the context structure pointed to by \fIucp\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIswapcontext\fP() shall return 0. Otherwise, +-1 shall be returned and \fIerrno\fP set to +indicate the error. +.SH ERRORS +.LP +The \fIswapcontext\fP() function shall fail if: +.TP 7 +.B ENOMEM +The \fIucp\fP argument does not have enough stack left to complete +the operation. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The following example illustrates the use of \fImakecontext\fP(): +.sp +.RS +.nf + +\fB#include +#include +.sp + +static ucontext_t ctx[3]; +.sp + +static void +f1 (void) +{ + puts("start f1"); + swapcontext(&ctx[1], &ctx[2]); + puts("finish f1"); +} +.sp + +static void +f2 (void) +{ + puts("start f2"); + swapcontext(&ctx[2], &ctx[1]); + puts("finish f2"); +} +.sp + +int +main (void) +{ + char st1[8192]; + char st2[8192]; +.sp + + getcontext(&ctx[1]); + ctx[1].uc_stack.ss_sp = st1; + ctx[1].uc_stack.ss_size = sizeof st1; + ctx[1].uc_link = &ctx[0]; + makecontext(&ctx[1], f1, 0); +.sp + + getcontext(&ctx[2]); + ctx[2].uc_stack.ss_sp = st2; + ctx[2].uc_stack.ss_size = sizeof st2; + ctx[2].uc_link = &ctx[1]; + makecontext(&ctx[2], f2, 0); +.sp + + swapcontext(&ctx[0], &ctx[2]); + return 0; +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexit\fP() , \fIgetcontext\fP() , \fIsigaction\fP() , \fIsigprocmask\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/malloc.3p b/man3p/malloc.3p new file mode 100644 index 000000000..78b8c838c --- /dev/null +++ b/man3p/malloc.3p @@ -0,0 +1,74 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MALLOC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" malloc +.SH NAME +malloc \- a memory allocator +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void *malloc(size_t\fP \fIsize\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fImalloc\fP() function shall allocate unused space for an object +whose size in bytes is specified by \fIsize\fP and whose +value is unspecified. +.LP +The order and contiguity of storage allocated by successive calls +to \fImalloc\fP() is unspecified. The pointer returned if the +allocation succeeds shall be suitably aligned so that it may be assigned +to a pointer to any type of object and then used to access +such an object in the space allocated (until the space is explicitly +freed or reallocated). Each such allocation shall yield a +pointer to an object disjoint from any other object. The pointer returned +points to the start (lowest byte address) of the +allocated space. If the space cannot be allocated, a null pointer +shall be returned. If the size of the space requested is 0, the +behavior is implementation-defined: the value returned shall be either +a null pointer or a unique pointer. +.SH RETURN VALUE +.LP +Upon successful completion with \fIsize\fP not equal to 0, \fImalloc\fP() +shall return a pointer to the allocated space. If +\fIsize\fP is 0, either a null pointer or a unique pointer that can +be successfully passed to \fIfree\fP() shall be returned. Otherwise, +it shall return a null pointer \ and set +\fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fImalloc\fP() function shall fail if: +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcalloc\fP() , \fIfree\fP() , \fIrealloc\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mblen.3p b/man3p/mblen.3p new file mode 100644 index 000000000..6f84afb44 --- /dev/null +++ b/man3p/mblen.3p @@ -0,0 +1,94 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MBLEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mblen +.SH NAME +mblen \- get number of bytes in a character +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int mblen(const char *\fP\fIs\fP\fB, size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If \fIs\fP is not a null pointer, \fImblen\fP() shall determine the +number of bytes constituting the character pointed to by +\fIs\fP. Except that the shift state of \fImbtowc\fP() is not affected, +it shall be +equivalent to: +.sp +.RS +.nf + +\fBmbtowc((wchar_t *)0,\fP \fIs\fP\fB,\fP \fIn\fP\fB); +\fP +.fi +.RE +.LP +The implementation shall behave as if no function defined in this +volume of IEEE\ Std\ 1003.1-2001 calls +\fImblen\fP(). +.LP +The behavior of this function is affected by the \fILC_CTYPE\fP category +of the current locale. For a state-dependent encoding, +this function shall be placed into its initial state by a call for +which its character pointer argument, \fIs\fP, is a null +pointer. Subsequent calls with \fIs\fP as other than a null pointer +shall cause the internal state of the function to be altered +as necessary. A call with \fIs\fP as a null pointer shall cause this +function to return a non-zero value if encodings have state +dependency, and 0 otherwise. If the implementation employs special +bytes to change the shift state, these bytes shall not produce +separate wide-character codes, but shall be grouped with an adjacent +character. Changing the \fILC_CTYPE\fP category causes the +shift state of this function to be unspecified. +.SH RETURN VALUE +.LP +If \fIs\fP is a null pointer, \fImblen\fP() shall return a non-zero +or 0 value, if character encodings, respectively, do or do +not have state-dependent encodings. If \fIs\fP is not a null pointer, +\fImblen\fP() shall either return 0 (if \fIs\fP points to +the null byte), or return the number of bytes that constitute the +character (if the next \fIn\fP or fewer bytes form a valid +character), or return -1 (if they do not form a valid character) +\ and may set \fIerrno\fP to indicate the error. In no case shall +the value returned be greater than \fIn\fP or the value of +the {MB_CUR_MAX} macro. +.SH ERRORS +.LP +The \fImblen\fP() function may fail if: +.TP 7 +.B EILSEQ +Invalid character sequence is detected. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImbtowc\fP() , \fImbstowcs\fP() , \fIwctomb\fP() , \fIwcstombs\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mbrlen.3p b/man3p/mbrlen.3p new file mode 100644 index 000000000..c2228d456 --- /dev/null +++ b/man3p/mbrlen.3p @@ -0,0 +1,107 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MBRLEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mbrlen +.SH NAME +mbrlen \- get number of bytes in a character (restartable) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t mbrlen(const char *restrict\fP \fIs\fP\fB, size_t\fP \fIn\fP\fB, +.br +\ \ \ \ \ \ mbstate_t *restrict\fP \fIps\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If \fIs\fP is not a null pointer, \fImbrlen\fP() shall determine the +number of bytes constituting the character pointed to by +\fIs\fP. It shall be equivalent to: +.sp +.RS +.nf + +\fBmbstate_t internal; +mbrtowc(NULL, s, n, ps != NULL ? ps : &internal); +\fP +.fi +.RE +.LP +If \fIps\fP is a null pointer, the \fImbrlen\fP() function shall use +its own internal \fBmbstate_t\fP object, which is +initialized at program start-up to the initial conversion state. Otherwise, +the \fBmbstate_t\fP object pointed to by \fIps\fP +shall be used to completely describe the current conversion state +of the associated character sequence. The implementation shall +behave as if no function defined in this volume of IEEE\ Std\ 1003.1-2001 +calls \fImbrlen\fP(). +.LP +The behavior of this function is affected by the \fILC_CTYPE\fP category +of the current locale. +.SH RETURN VALUE +.LP +The \fImbrlen\fP() function shall return the first of the following +that applies: +.TP 7 +0 +If the next \fIn\fP or fewer bytes complete the character that corresponds +to the null wide character. +.TP 7 +\fIpositive\fP +If the next \fIn\fP or fewer bytes complete a valid character; the +value returned shall be the number of bytes that complete +the character. +.TP 7 +(\fBsize_t\fP)-2 +If the next \fIn\fP bytes contribute to an incomplete but potentially +valid character, and all \fIn\fP bytes have been +processed. When \fIn\fP has at least the value of the {MB_CUR_MAX} +macro, this case can only occur if \fIs\fP points at a +sequence of redundant shift sequences (for implementations with state-dependent +encodings). +.TP 7 +(\fBsize_t\fP)-1 +If an encoding error occurs, in which case the next \fIn\fP or fewer +bytes do not contribute to a complete and valid +character. In this case, [EILSEQ] shall be stored in \fIerrno\fP and +the conversion state is undefined. +.sp +.SH ERRORS +.LP +The \fImbrlen\fP() function may fail if: +.TP 7 +.B EINVAL +\fIps\fP points to an object that contains an invalid conversion state. +.TP 7 +.B EILSEQ +Invalid character sequence is detected. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImbsinit\fP() , \fImbrtowc\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mbrtowc.3p b/man3p/mbrtowc.3p new file mode 100644 index 000000000..1faaee756 --- /dev/null +++ b/man3p/mbrtowc.3p @@ -0,0 +1,122 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MBRTOWC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mbrtowc +.SH NAME +mbrtowc \- convert a character to a wide-character code (restartable) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t mbrtowc(wchar_t *restrict\fP \fIpwc\fP\fB, const char *restrict\fP +\fIs\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIn\fP\fB, mbstate_t *restrict\fP \fIps\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If \fIs\fP is a null pointer, the \fImbrtowc\fP() function shall be +equivalent to the call: +.sp +.RS +.nf + +\fBmbrtowc(NULL, "", 1, ps) +\fP +.fi +.RE +.LP +In this case, the values of the arguments \fIpwc\fP and \fIn\fP are +ignored. +.LP +If \fIs\fP is not a null pointer, the \fImbrtowc\fP() function shall +inspect at most \fIn\fP bytes beginning at the byte +pointed to by \fIs\fP to determine the number of bytes needed to complete +the next character (including any shift sequences). If +the function determines that the next character is completed, it shall +determine the value of the corresponding wide character and +then, if \fIpwc\fP is not a null pointer, shall store that value in +the object pointed to by \fIpwc\fP. If the corresponding wide +character is the null wide character, the resulting state described +shall be the initial conversion state. +.LP +If \fIps\fP is a null pointer, the \fImbrtowc\fP() function shall +use its own internal \fBmbstate_t\fP object, which shall be +initialized at program start-up to the initial conversion state. Otherwise, +the \fBmbstate_t\fP object pointed to by \fIps\fP +shall be used to completely describe the current conversion state +of the associated character sequence. The implementation shall +behave as if no function defined in this volume of IEEE\ Std\ 1003.1-2001 +calls \fImbrtowc\fP(). +.LP +The behavior of this function is affected by the \fILC_CTYPE\fP category +of the current locale. +.SH RETURN VALUE +.LP +The \fImbrtowc\fP() function shall return the first of the following +that applies: +.TP 7 +0 +If the next \fIn\fP or fewer bytes complete the character that corresponds +to the null wide character (which is the value +stored). +.TP 7 +between 1 and \fIn\fP inclusive +.sp +If the next \fIn\fP or fewer bytes complete a valid character (which +is the value stored); the value returned shall be the number +of bytes that complete the character. +.TP 7 +(\fBsize_t\fP)-2 +If the next \fIn\fP bytes contribute to an incomplete but potentially +valid character, and all \fIn\fP bytes have been +processed (no value is stored). When \fIn\fP has at least the value +of the {MB_CUR_MAX} macro, this case can only occur if +\fIs\fP points at a sequence of redundant shift sequences (for implementations +with state-dependent encodings). +.TP 7 +(\fBsize_t\fP)-1 +If an encoding error occurs, in which case the next \fIn\fP or fewer +bytes do not contribute to a complete and valid character +(no value is stored). In this case, [EILSEQ] shall be stored in \fIerrno\fP +and the conversion state is undefined. +.sp +.SH ERRORS +.LP +The \fImbrtowc\fP() function may fail if: +.TP 7 +.B EINVAL +\fIps\fP points to an object that contains an invalid conversion state. +.TP 7 +.B EILSEQ +Invalid character sequence is detected. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImbsinit\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mbsinit.3p b/man3p/mbsinit.3p new file mode 100644 index 000000000..3623dd1b5 --- /dev/null +++ b/man3p/mbsinit.3p @@ -0,0 +1,73 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MBSINIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mbsinit +.SH NAME +mbsinit \- determine conversion object status +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int mbsinit(const mbstate_t *\fP\fIps\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If \fIps\fP is not a null pointer, the \fImbsinit\fP() function shall +determine whether the object pointed to by \fIps\fP +describes an initial conversion state. +.SH RETURN VALUE +.LP +The \fImbsinit\fP() function shall return non-zero if \fIps\fP is +a null pointer, or if the pointed-to object describes an +initial conversion state; otherwise, it shall return zero. +.LP +If an \fBmbstate_t\fP object is altered by any of the functions described +as "restartable", and is then used with a different +character sequence, or in the other conversion direction, or with +a different \fILC_CTYPE\fP category setting than on earlier +function calls, the behavior is undefined. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fBmbstate_t\fP object is used to describe the current conversion +state from a particular character sequence to a +wide-character sequence (or \fIvice versa\fP) under the rules of a +particular setting of the \fILC_CTYPE\fP category of the +current locale. +.LP +The initial conversion state corresponds, for a conversion in either +direction, to the beginning of a new character sequence in +the initial shift state. A zero valued \fBmbstate_t\fP object is at +least one way to describe an initial conversion state. A zero +valued \fBmbstate_t\fP object can be used to initiate conversion involving +any character sequence, in any \fILC_CTYPE\fP category +setting. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImbrlen\fP() , \fImbrtowc\fP() , \fIwcrtomb\fP() , \fImbsrtowcs\fP() +, \fIwcsrtombs\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mbsrtowcs.3p b/man3p/mbsrtowcs.3p new file mode 100644 index 000000000..c4e0fe071 --- /dev/null +++ b/man3p/mbsrtowcs.3p @@ -0,0 +1,105 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MBSRTOWCS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mbsrtowcs +.SH NAME +mbsrtowcs \- convert a character string to a wide-character string +(restartable) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t mbsrtowcs(wchar_t *restrict\fP \fIdst\fP\fB, const char **restrict\fP +\fIsrc\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIlen\fP\fB, mbstate_t *restrict\fP \fIps\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fImbsrtowcs\fP() function shall convert a sequence of characters, +beginning in the conversion state described by the +object pointed to by \fIps\fP, from the array indirectly pointed to +by \fIsrc\fP into a sequence of corresponding wide +characters. If \fIdst\fP is not a null pointer, the converted characters +shall be stored into the array pointed to by \fIdst\fP. +Conversion continues up to and including a terminating null character, +which shall also be stored. Conversion shall stop early in +either of the following cases: +.IP " *" 3 +A sequence of bytes is encountered that does not form a valid character. +.LP +.IP " *" 3 +\fIlen\fP codes have been stored into the array pointed to by \fIdst\fP +(and \fIdst\fP is not a null pointer). +.LP +.LP +Each conversion shall take place as if by a call to the \fImbrtowc\fP() +function. +.LP +If \fIdst\fP is not a null pointer, the pointer object pointed to +by \fIsrc\fP shall be assigned either a null pointer (if +conversion stopped due to reaching a terminating null character) or +the address just past the last character converted (if any). If +conversion stopped due to reaching a terminating null character, and +if \fIdst\fP is not a null pointer, the resulting state +described shall be the initial conversion state. +.LP +If \fIps\fP is a null pointer, the \fImbsrtowcs\fP() function shall +use its own internal \fBmbstate_t\fP object, which is +initialized at program start-up to the initial conversion state. Otherwise, +the \fBmbstate_t\fP object pointed to by \fIps\fP +shall be used to completely describe the current conversion state +of the associated character sequence. The implementation behaves +as if no function defined in this volume of IEEE\ Std\ 1003.1-2001 +calls \fImbsrtowcs\fP(). +.LP +The behavior of this function shall be affected by the \fILC_CTYPE\fP +category of the current locale. +.SH RETURN VALUE +.LP +If the input conversion encounters a sequence of bytes that do not +form a valid character, an encoding error occurs. In this +case, the \fImbsrtowcs\fP() function stores the value of the macro +[EILSEQ] in \fIerrno\fP and shall return (\fBsize_t\fP)-1; +the conversion state is undefined. Otherwise, it shall return the +number of characters successfully converted, not including the +terminating null (if any). +.SH ERRORS +.LP +The \fImbsrtowcs\fP() function may fail if: +.TP 7 +.B EINVAL +\fIps\fP points to an object that contains an invalid conversion state. +.TP 7 +.B EILSEQ +Invalid character sequence is detected. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImbsinit\fP() , \fImbrtowc\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mbstowcs.3p b/man3p/mbstowcs.3p new file mode 100644 index 000000000..75a40dcda --- /dev/null +++ b/man3p/mbstowcs.3p @@ -0,0 +1,84 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MBSTOWCS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mbstowcs +.SH NAME +mbstowcs \- convert a character string to a wide-character string +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t mbstowcs(wchar_t *restrict\fP \fIpwcs\fP\fB, const char *restrict\fP +\fIs\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fImbstowcs\fP() function shall convert a sequence of characters +that begins in the initial shift state from the array +pointed to by \fIs\fP into a sequence of corresponding wide-character +codes and shall store not more than \fIn\fP wide-character +codes into the array pointed to by \fIpwcs\fP. No characters that +follow a null byte (which is converted into a wide-character +code with value 0) shall be examined or converted. Each character +shall be converted as if by a call to \fImbtowc\fP(), except that +the shift state of \fImbtowc\fP() is not affected. +.LP +No more than \fIn\fP elements shall be modified in the array pointed +to by \fIpwcs\fP. If copying takes place between objects +that overlap, the behavior is undefined. +.LP +The behavior of this function shall be affected by the \fILC_CTYPE\fP +category of the current locale. \ If +\fIpwcs\fP is a null pointer, \fImbstowcs\fP() shall return the length +required to convert the entire array regardless of the +value of \fIn\fP, but no values are stored. +.SH RETURN VALUE +.LP +If an invalid character is encountered, \fImbstowcs\fP() shall return +(\fBsize_t\fP)-1 \ and may set +\fIerrno\fP to indicate the error. +.LP +Otherwise, \fImbstowcs\fP() shall return the number of the array elements +modified \ (or required +if \fIpwcs\fP is null), not including a terminating 0 code, if +any. The array shall not be zero-terminated if the value returned +is \fIn\fP. +.SH ERRORS +.LP +The \fImbstowcs\fP() function may fail if: +.TP 7 +.B EILSEQ +Invalid byte sequence is detected. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImblen\fP() , \fImbtowc\fP() , \fIwctomb\fP() +, \fIwcstombs\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mbtowc.3p b/man3p/mbtowc.3p new file mode 100644 index 000000000..e32de36ec --- /dev/null +++ b/man3p/mbtowc.3p @@ -0,0 +1,92 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MBTOWC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mbtowc +.SH NAME +mbtowc \- convert a character to a wide-character code +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int mbtowc(wchar_t *restrict\fP \fIpwc\fP\fB, const char *restrict\fP +\fIs\fP\fB, size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If \fIs\fP is not a null pointer, \fImbtowc\fP() shall determine the +number of bytes that constitute the character pointed to +by \fIs\fP. It shall then determine the wide-character code for the +value of type \fBwchar_t\fP that corresponds to that +character. (The value of the wide-character code corresponding to +the null byte is 0.) If the character is valid and \fIpwc\fP is +not a null pointer, \fImbtowc\fP() shall store the wide-character +code in the object pointed to by \fIpwc\fP. +.LP +The behavior of this function is affected by the \fILC_CTYPE\fP category +of the current locale. For a state-dependent encoding, +this function is placed into its initial state by a call for which +its character pointer argument, \fIs\fP, is a null pointer. +Subsequent calls with \fIs\fP as other than a null pointer shall cause +the internal state of the function to be altered as +necessary. A call with \fIs\fP as a null pointer shall cause this +function to return a non-zero value if encodings have state +dependency, and 0 otherwise. If the implementation employs special +bytes to change the shift state, these bytes shall not produce +separate wide-character codes, but shall be grouped with an adjacent +character. Changing the \fILC_CTYPE\fP category causes the +shift state of this function to be unspecified. At most \fIn\fP bytes +of the array pointed to by \fIs\fP shall be examined. +.LP +The implementation shall behave as if no function defined in this +volume of IEEE\ Std\ 1003.1-2001 calls +\fImbtowc\fP(). +.SH RETURN VALUE +.LP +If \fIs\fP is a null pointer, \fImbtowc\fP() shall return a non-zero +or 0 value, if character encodings, respectively, do or +do not have state-dependent encodings. If \fIs\fP is not a null pointer, +\fImbtowc\fP() shall either return 0 (if \fIs\fP points +to the null byte), or return the number of bytes that constitute the +converted character (if the next \fIn\fP or fewer bytes form +a valid character), or return -1 \ and may set \fIerrno\fP to indicate +the error (if they do not form a valid character). +.LP +In no case shall the value returned be greater than \fIn\fP or the +value of the {MB_CUR_MAX} macro. +.SH ERRORS +.LP +The \fImbtowc\fP() function may fail if: +.TP 7 +.B EILSEQ +Invalid character sequence is detected. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImblen\fP() , \fImbstowcs\fP() , \fIwctomb\fP() , \fIwcstombs\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/memccpy.3p b/man3p/memccpy.3p new file mode 100644 index 000000000..b28e79d60 --- /dev/null +++ b/man3p/memccpy.3p @@ -0,0 +1,61 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MEMCCPY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" memccpy +.SH NAME +memccpy \- copy bytes in memory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void *memccpy(void *restrict\fP \fIs1\fP\fB, const void *restrict\fP +\fIs2\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIc\fP\fB, size_t\fP \fIn\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImemccpy\fP() function shall copy bytes from memory area \fIs2\fP +into \fIs1\fP, stopping after the first occurrence of +byte \fIc\fP (converted to an \fBunsigned char\fP) is copied, or after +\fIn\fP bytes are copied, whichever comes first. If +copying takes place between objects that overlap, the behavior is +undefined. +.SH RETURN VALUE +.LP +The \fImemccpy\fP() function shall return a pointer to the byte after +the copy of \fIc\fP in \fIs1\fP, or a null pointer if +\fIc\fP was not found in the first \fIn\fP bytes of \fIs2\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fImemccpy\fP() function does not check for the overflow of the +receiving memory area. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/memchr.3p b/man3p/memchr.3p new file mode 100644 index 000000000..541c0f6ae --- /dev/null +++ b/man3p/memchr.3p @@ -0,0 +1,55 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MEMCHR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" memchr +.SH NAME +memchr \- find byte in memory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void *memchr(const void *\fP\fIs\fP\fB, int\fP \fIc\fP\fB, size_t\fP +\fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fImemchr\fP() function shall locate the first occurrence of \fIc\fP +(converted to an \fBunsigned char\fP) in the initial +\fIn\fP bytes (each interpreted as \fBunsigned char\fP) of the object +pointed to by \fIs\fP. +.SH RETURN VALUE +.LP +The \fImemchr\fP() function shall return a pointer to the located +byte, or a null pointer if the byte does not occur in the +object. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/memcmp.3p b/man3p/memcmp.3p new file mode 100644 index 000000000..8e0e0c8aa --- /dev/null +++ b/man3p/memcmp.3p @@ -0,0 +1,61 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MEMCMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" memcmp +.SH NAME +memcmp \- compare bytes in memory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int memcmp(const void *\fP\fIs1\fP\fB, const void *\fP\fIs2\fP\fB, +size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fImemcmp\fP() function shall compare the first \fIn\fP bytes +(each interpreted as \fBunsigned char\fP) of the object +pointed to by \fIs1\fP to the first \fIn\fP bytes of the object pointed +to by \fIs2\fP. +.LP +The sign of a non-zero return value shall be determined by the sign +of the difference between the values of the first pair of +bytes (both interpreted as type \fBunsigned char\fP) that differ in +the objects being compared. +.SH RETURN VALUE +.LP +The \fImemcmp\fP() function shall return an integer greater than, +equal to, or less than 0, if the object pointed to by +\fIs1\fP is greater than, equal to, or less than the object pointed +to by \fIs2\fP, respectively. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/memcpy.3p b/man3p/memcpy.3p new file mode 100644 index 000000000..4b537cdc0 --- /dev/null +++ b/man3p/memcpy.3p @@ -0,0 +1,55 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MEMCPY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" memcpy +.SH NAME +memcpy \- copy bytes in memory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void *memcpy(void *restrict\fP \fIs1\fP\fB, const void *restrict\fP +\fIs2\fP\fB, size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fImemcpy\fP() function shall copy \fIn\fP bytes from the object +pointed to by \fIs2\fP into the object pointed to by +\fIs1\fP. If copying takes place between objects that overlap, the +behavior is undefined. +.SH RETURN VALUE +.LP +The \fImemcpy\fP() function shall return \fIs1\fP; no return value +is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fImemcpy\fP() function does not check for the overflow of the +receiving memory area. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/memmove.3p b/man3p/memmove.3p new file mode 100644 index 000000000..3fd9a3e2a --- /dev/null +++ b/man3p/memmove.3p @@ -0,0 +1,57 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MEMMOVE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" memmove +.SH NAME +memmove \- copy bytes in memory with overlapping areas +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void *memmove(void *\fP\fIs1\fP\fB, const void *\fP\fIs2\fP\fB, size_t\fP +\fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fImemmove\fP() function shall copy \fIn\fP bytes from the object +pointed to by \fIs2\fP into the object pointed to by +\fIs1\fP. Copying takes place as if the \fIn\fP bytes from the object +pointed to by \fIs2\fP are first copied into a temporary +array of \fIn\fP bytes that does not overlap the objects pointed to +by \fIs1\fP and \fIs2\fP, and then the \fIn\fP bytes from +the temporary array are copied into the object pointed to by \fIs1\fP. +.SH RETURN VALUE +.LP +The \fImemmove\fP() function shall return \fIs1\fP; no return value +is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/memset.3p b/man3p/memset.3p new file mode 100644 index 000000000..226539783 --- /dev/null +++ b/man3p/memset.3p @@ -0,0 +1,52 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MEMSET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" memset +.SH NAME +memset \- set bytes in memory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void *memset(void *\fP\fIs\fP\fB, int\fP \fIc\fP\fB, size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fImemset\fP() function shall copy \fIc\fP (converted to an \fBunsigned +char\fP) into each of the first \fIn\fP bytes of +the object pointed to by \fIs\fP. +.SH RETURN VALUE +.LP +The \fImemset\fP() function shall return \fIs\fP; no return value +is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mkdir.3p b/man3p/mkdir.3p new file mode 100644 index 000000000..cd7e6b47d --- /dev/null +++ b/man3p/mkdir.3p @@ -0,0 +1,161 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MKDIR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mkdir +.SH NAME +mkdir \- make a directory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int mkdir(const char *\fP\fIpath\fP\fB, mode_t\fP \fImode\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fImkdir\fP() function shall create a new directory with name +\fIpath\fP. The file permission bits of the new directory +shall be initialized from \fImode\fP. These file permission bits of +the \fImode\fP argument shall be modified by the process' +file creation mask. +.LP +When bits in \fImode\fP other than the file permission bits are set, +the meaning of these additional bits is +implementation-defined. +.LP +The directory's user ID shall be set to the process' effective user +ID. The directory's group ID shall be set to the group ID of +the parent directory or to the effective group ID of the process. +Implementations shall provide a way to initialize the directory's +group ID to the group ID of the parent directory. Implementations +may, but need not, provide an implementation-defined way to +initialize the directory's group ID to the effective group ID of the +calling process. +.LP +The newly created directory shall be an empty directory. +.LP +If \fIpath\fP names a symbolic link, \fImkdir\fP() shall fail and +set \fIerrno\fP to [EEXIST]. +.LP +Upon successful completion, \fImkdir\fP() shall mark for update the +\fIst_atime\fP, \fIst_ctime\fP, and \fIst_mtime\fP +fields of the directory. Also, the \fIst_ctime\fP and \fIst_mtime\fP +fields of the directory that contains the new entry shall be +marked for update. +.SH RETURN VALUE +.LP +Upon successful completion, \fImkdir\fP() shall return 0. Otherwise, +-1 shall be returned, no directory shall be created, and +\fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +The \fImkdir\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied on a component of the path prefix, or +write permission is denied on the parent directory of the +directory to be created. +.TP 7 +.B EEXIST +The named file exists. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B EMLINK +The link count of the parent directory would exceed {LINK_MAX}. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of the path prefix specified by \fIpath\fP does not name +an existing directory or \fIpath\fP is an empty +string. +.TP 7 +.B ENOSPC +The file system does not contain enough space to hold the contents +of the new directory or to extend the parent directory of +the new directory. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.TP 7 +.B EROFS +The parent directory resides on a read-only file system. +.sp +.LP +The \fImkdir\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Creating a Directory +.LP +The following example shows how to create a directory named \fB/home/cnd/mod1\fP, +with read/write/search permissions for owner +and group, and with read/search permissions for others. +.sp +.RS +.nf + +\fB#include +#include +.sp + +int status; +\&... +status = mkdir("/home/cnd/mod1", S_IRWXU | S_IRWXG | S_IROTH | S_IXOTH); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fImkdir\fP() function originated in 4.2 BSD and was added to +System V in Release 3.0. +.LP +4.3 BSD detects [ENAMETOOLONG]. +.LP +The POSIX.1-1990 standard required that the group ID of a newly created +directory be set to the group ID of its parent directory +or to the effective group ID of the creating process. FIPS 151-2 required +that implementations provide a way to have the group ID +be set to the group ID of the containing directory, but did not prohibit +implementations also supporting a way to set the group ID +to the effective group ID of the creating process. Conforming applications +should not assume which group ID will be used. If it +matters, an application can use \fIchown\fP() to set the group ID +after the directory is +created, or determine under what conditions the implementation will +set the desired group ID. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIumask\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mkfifo.3p b/man3p/mkfifo.3p new file mode 100644 index 000000000..2b5c79eb4 --- /dev/null +++ b/man3p/mkfifo.3p @@ -0,0 +1,160 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MKFIFO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mkfifo +.SH NAME +mkfifo \- make a FIFO special file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int mkfifo(const char *\fP\fIpath\fP\fB, mode_t\fP \fImode\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fImkfifo\fP() function shall create a new FIFO special file named +by the pathname pointed to by \fIpath\fP. The file +permission bits of the new FIFO shall be initialized from \fImode\fP. +The file permission bits of the \fImode\fP argument shall +be modified by the process' file creation mask. +.LP +When bits in \fImode\fP other than the file permission bits are set, +the effect is implementation-defined. +.LP +If \fIpath\fP names a symbolic link, \fImkfifo\fP() shall fail and +set \fIerrno\fP to [EEXIST]. +.LP +The FIFO's user ID shall be set to the process' effective user ID. +The FIFO's group ID shall be set to the group ID of the +parent directory or to the effective group ID of the process. Implementations +shall provide a way to initialize the FIFO's group ID +to the group ID of the parent directory. Implementations may, but +need not, provide an implementation-defined way to initialize the +FIFO's group ID to the effective group ID of the calling process. +.LP +Upon successful completion, \fImkfifo\fP() shall mark for update the +\fIst_atime\fP, \fIst_ctime\fP, and \fIst_mtime\fP +fields of the file. Also, the \fIst_ctime\fP and \fIst_mtime\fP fields +of the directory that contains the new entry shall be +marked for update. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned, no FIFO shall be created, and \fIerrno\fP +shall be set to indicate the error. +.SH ERRORS +.LP +The \fImkfifo\fP() function shall fail if: +.TP 7 +.B EACCES +A component of the path prefix denies search permission, or write +permission is denied on the parent directory of the FIFO to +be created. +.TP 7 +.B EEXIST +The named file already exists. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of the path prefix specified by \fIpath\fP does not name +an existing directory or \fIpath\fP is an empty +string. +.TP 7 +.B ENOSPC +The directory that would contain the new file cannot be extended or +the file system is out of file-allocation resources. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.TP 7 +.B EROFS +The named file resides on a read-only file system. +.sp +.LP +The \fImkfifo\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Creating a FIFO File +.LP +The following example shows how to create a FIFO file named \fB/home/cnd/mod_done\fP, +with read/write permissions for owner, +and with read permissions for group and others. +.sp +.RS +.nf + +\fB#include +#include +.sp + +int status; +\&... +status = mkfifo("/home/cnd/mod_done", S_IWUSR | S_IRUSR | + S_IRGRP | S_IROTH); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The syntax of this function is intended to maintain compatibility +with historical implementations of \fImknod\fP(). The latter function +was included in the 1984 /usr/group standard but only for use in +creating FIFO special files. The \fImknod\fP() function was originally +excluded from the +POSIX.1-1988 standard as implementation-defined and replaced by \fImkdir\fP() +and +\fImkfifo\fP(). The \fImknod\fP() function is now included for alignment +with the Single +UNIX Specification. +.LP +The POSIX.1-1990 standard required that the group ID of a newly created +FIFO be set to the group ID of its parent directory or +to the effective group ID of the creating process. FIPS 151-2 required +that implementations provide a way to have the group ID be +set to the group ID of the containing directory, but did not prohibit +implementations also supporting a way to set the group ID to +the effective group ID of the creating process. Conforming applications +should not assume which group ID will be used. If it +matters, an application can use \fIchown\fP() to set the group ID +after the FIFO is created, +or determine under what conditions the implementation will set the +desired group ID. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIumask\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mknod.3p b/man3p/mknod.3p new file mode 100644 index 000000000..ac58c9518 --- /dev/null +++ b/man3p/mknod.3p @@ -0,0 +1,207 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MKNOD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mknod +.SH NAME +mknod \- make a directory, a special file, or a regular file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int mknod(const char *\fP\fIpath\fP\fB, mode_t\fP \fImode\fP\fB, dev_t\fP +\fIdev\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImknod\fP() function shall create a new file named by the pathname +to which the argument \fIpath\fP points. +.LP +The file type for \fIpath\fP is OR'ed into the \fImode\fP argument, +and the application shall select one of the following +symbolic constants: +.TS C +center; l l. +\fBName\fP \fBDescription\fP +S_IFIFO FIFO-special +S_IFCHR Character-special (non-portable) +S_IFDIR Directory (non-portable) +S_IFBLK Block-special (non-portable) +S_IFREG Regular (non-portable) +.TE +.LP +The only portable use of \fImknod\fP() is to create a FIFO-special +file. If \fImode\fP is not S_IFIFO or \fIdev\fP is not 0, +the behavior of \fImknod\fP() is unspecified. +.LP +The permissions for the new file are OR'ed into the \fImode\fP argument, +and may be selected from any combination of the +following symbolic constants: +.TS C +center; l2 l. +\fBName\fP \fBDescription\fP +S_ISUID Set user ID on execution. +S_ISGID Set group ID on execution. +S_IRWXU Read, write, or execute (search) by owner. +S_IRUSR Read by owner. +S_IWUSR Write by owner. +S_IXUSR Execute (search) by owner. +S_IRWXG Read, write, or execute (search) by group. +S_IRGRP Read by group. +S_IWGRP Write by group. +S_IXGRP Execute (search) by group. +S_IRWXO Read, write, or execute (search) by others. +S_IROTH Read by others. +S_IWOTH Write by others. +S_IXOTH Execute (search) by others. +S_ISVTX On directories, restricted deletion flag. +.TE +.LP +The user ID of the file shall be initialized to the effective user +ID of the process. The group ID of the file shall be +initialized to either the effective group ID of the process or the +group ID of the parent directory. Implementations shall provide +a way to initialize the file's group ID to the group ID of the parent +directory. Implementations may, but need not, provide an +implementation-defined way to initialize the file's group ID to the +effective group ID of the calling process. The owner, group, +and other permission bits of \fImode\fP shall be modified by the file +mode creation mask of the process. The \fImknod\fP() +function shall clear each bit whose corresponding bit in the file +mode creation mask of the process is set. +.LP +If \fIpath\fP names a symbolic link, \fImknod\fP() shall fail and +set \fIerrno\fP to [EEXIST]. +.LP +Upon successful completion, \fImknod\fP() shall mark for update the +\fIst_atime\fP, \fIst_ctime\fP, and \fIst_mtime\fP +fields of the file. Also, the \fIst_ctime\fP and \fIst_mtime\fP fields +of the directory that contains the new entry shall be +marked for update. +.LP +Only a process with appropriate privileges may invoke \fImknod\fP() +for file types other than FIFO-special. +.SH RETURN VALUE +.LP +Upon successful completion, \fImknod\fP() shall return 0. Otherwise, +it shall return -1, the new file shall not be created, and +\fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +The \fImknod\fP() function shall fail if: +.TP 7 +.B EACCES +A component of the path prefix denies search permission, or write +permission is denied on the parent directory. +.TP 7 +.B EEXIST +The named file exists. +.TP 7 +.B EINVAL +An invalid argument exists. +.TP 7 +.B EIO +An I/O error occurred while accessing the file system. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of a pathname exceeds {PATH_MAX} or a pathname component +is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of the path prefix specified by \fIpath\fP does not name +an existing directory or \fIpath\fP is an empty +string. +.TP 7 +.B ENOSPC +The directory that would contain the new file cannot be extended or +the file system is out of file allocation resources. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.TP 7 +.B EPERM +The invoking process does not have appropriate privileges and the +file type is not FIFO-special. +.TP 7 +.B EROFS +The directory in which the file is to be created is located on a read-only +file system. +.sp +.LP +The \fImknod\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Creating a FIFO Special File +.LP +The following example shows how to create a FIFO special file named +\fB/home/cnd/mod_done\fP, with read/write permissions for +owner, and with read permissions for group and others. +.sp +.RS +.nf + +\fB#include +#include +.sp + +dev_t dev; +int status; +\&... +status = mknod("/home/cnd/mod_done", S_IFIFO | S_IWUSR | + S_IRUSR | S_IRGRP | S_IROTH, dev); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fImkfifo\fP() function is preferred over this function for making +FIFO special +files. +.SH RATIONALE +.LP +The POSIX.1-1990 standard required that the group ID of a newly created +file be set to the group ID of its parent directory or +to the effective group ID of the creating process. FIPS 151-2 required +that implementations provide a way to have the group ID be +set to the group ID of the containing directory, but did not prohibit +implementations also supporting a way to set the group ID to +the effective group ID of the creating process. Conforming applications +should not assume which group ID will be used. If it +matters, an application can use \fIchown\fP() to set the group ID +after the file is created, +or determine under what conditions the implementation will set the +desired group ID. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchmod\fP() , \fIcreat\fP() , \fIexec\fP() , \fImkdir\fP() , \fImkfifo\fP() +, +\fIopen\fP() , \fIstat\fP() , \fIumask\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mkstemp.3p b/man3p/mkstemp.3p new file mode 100644 index 000000000..ee9b6cbb9 --- /dev/null +++ b/man3p/mkstemp.3p @@ -0,0 +1,86 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MKSTEMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mkstemp +.SH NAME +mkstemp \- make a unique filename +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int mkstemp(char *\fP\fItemplate\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImkstemp\fP() function shall replace the contents of the string +pointed to by \fItemplate\fP by a unique filename, and +return a file descriptor for the file open for reading and writing. +The function thus prevents any possible race condition between +testing whether the file exists and opening it for use. The string +in \fItemplate\fP should look like a filename with six trailing +\fB'X'\fP s; \fImkstemp\fP() replaces each \fB'X'\fP with a character +from the portable filename character set. The +characters are chosen such that the resulting name does not duplicate +the name of an existing file at the time of a call to +\fImkstemp\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, \fImkstemp\fP() shall return an open file +descriptor. Otherwise, -1 shall be returned if no +suitable file could be created. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Generating a Filename +.LP +The following example creates a file with a 10-character name beginning +with the characters \fB"file"\fP and opens the file +for reading and writing. The value returned as the value of \fIfd\fP +is a file descriptor that identifies the file. +.sp +.RS +.nf + +\fB#include +\&... +char template[] = "/tmp/fileXXXXXX"; +int fd; +.sp + +fd = mkstemp(template); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +It is possible to run out of letters. +.LP +The \fImkstemp\fP() function need not check to determine whether the +filename part of \fItemplate\fP exceeds the maximum +allowable filename length. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetpid\fP() , \fIopen\fP() , \fItmpfile\fP() +, \fItmpnam\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mktemp.3p b/man3p/mktemp.3p new file mode 100644 index 000000000..f5ec7564e --- /dev/null +++ b/man3p/mktemp.3p @@ -0,0 +1,80 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MKTEMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mktemp +.SH NAME +mktemp \- make a unique filename (\fBLEGACY\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *mktemp(char *\fP\fItemplate\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImktemp\fP() function shall replace the contents of the string +pointed to by \fItemplate\fP by a unique filename and +return \fItemplate\fP. The application shall initialize \fItemplate\fP +to be a filename with six trailing \fB'X'\fP s; +\fImktemp\fP() shall replace each \fB'X'\fP with a single byte character +from the portable filename character set. +.SH RETURN VALUE +.LP +The \fImktemp\fP() function shall return the pointer \fItemplate\fP. +If a unique name cannot be created, \fItemplate\fP shall +point to a null string. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Generating a Filename +.LP +The following example replaces the contents of the \fB"template"\fP +string with a 10-character filename beginning with the +characters \fB"file"\fP and returns a pointer to the \fB"template"\fP +string that contains the new filename. +.sp +.RS +.nf + +\fB#include +\&... +char *template = "/tmp/fileXXXXXX"; +char *ptr; +.sp + +ptr = mktemp(template); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +Between the time a pathname is created and the file opened, it is +possible for some other process to create a file with the same +name. The \fImkstemp\fP() function avoids this problem and is preferred +over this +function. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +This function may be withdrawn in a future version. +.SH SEE ALSO +.LP +\fImkstemp\fP() , \fItmpfile\fP() , \fItmpnam\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mktime.3p b/man3p/mktime.3p new file mode 100644 index 000000000..5b8647c86 --- /dev/null +++ b/man3p/mktime.3p @@ -0,0 +1,123 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MKTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mktime +.SH NAME +mktime \- convert broken-down time into time since the Epoch +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +time_t mktime(struct tm *\fP\fItimeptr\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fImktime\fP() function shall convert the broken-down time, expressed +as local time, in the structure pointed to by +\fItimeptr\fP, into a time since the Epoch value with the same encoding +as that of the values returned by \fItime\fP(). The original values +of the \fItm_wday\fP and \fItm_yday\fP components of the +structure are ignored, and the original values of the other components +are not restricted to the ranges described in \fI\fP. +.LP +A +positive or 0 value for \fItm_isdst\fP shall cause \fImktime\fP() +to presume initially that Daylight Savings Time, respectively, +is or is not in effect for the specified time. A negative value for +\fItm_isdst\fP shall cause \fImktime\fP() to attempt to +determine whether Daylight Savings Time is in effect for the specified +time. +.LP +Local timezone information shall be set as though \fImktime\fP() called +\fItzset\fP(). +.LP +The relationship between the \fBtm\fP structure (defined in the \fI\fP +header) and the time in seconds since the Epoch is that the result +shall be as specified in the expression given in the definition +of seconds since the Epoch (see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 4.14, Seconds Since the Epoch) corrected for timezone and +any seasonal time +adjustments, where the names in the structure and in the expression +correspond. +.LP +Upon successful completion, the values of the \fItm_wday\fP and \fItm_yday\fP +components of the structure shall be set +appropriately, and the other components are set to represent the specified +time since the Epoch, but with their values forced to +the ranges indicated in the \fI\fP entry; the final value +of \fItm_mday\fP +shall not be set until \fItm_mon\fP and \fItm_year\fP are determined. +.SH RETURN VALUE +.LP +The \fImktime\fP() function shall return the specified time since +the Epoch encoded as a value of type \fBtime_t\fP. If the +time since the Epoch cannot be represented, the function shall return +the value (\fBtime_t\fP)-1. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +What day of the week is July 4, 2001? +.sp +.RS +.nf + +\fB#include +#include +.sp + +struct tm time_str; +.sp + +char daybuf[20]; +.sp + +int main(void) +{ + time_str.tm_year = 2001 - 1900; + time_str.tm_mon = 7 - 1; + time_str.tm_mday = 4; + time_str.tm_hour = 0; + time_str.tm_min = 0; + time_str.tm_sec = 1; + time_str.tm_isdst = -1; + if (mktime(&time_str) == -1) + (void)puts("-unknown-"); + else { + (void)strftime(daybuf, sizeof(daybuf), "%A", &time_str); + (void)puts(daybuf); + } + return 0; +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIasctime\fP() , \fIclock\fP() , \fIctime\fP() +, \fIdifftime\fP() , \fIgmtime\fP() , \fIlocaltime\fP() , \fIstrftime\fP() +, \fIstrptime\fP() , \fItime\fP() , \fIutime\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mlock.3p b/man3p/mlock.3p new file mode 100644 index 000000000..54d72d227 --- /dev/null +++ b/man3p/mlock.3p @@ -0,0 +1,122 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MLOCK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mlock +.SH NAME +mlock, munlock \- lock or unlock a range of process address space (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int mlock(const void *\fP\fIaddr\fP\fB, size_t\fP \fIlen\fP\fB); +.br +int munlock(const void *\fP\fIaddr\fP\fB, size_t\fP \fIlen\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImlock\fP() function shall cause those whole pages containing +any part of the address space of the process starting at +address \fIaddr\fP and continuing for \fIlen\fP bytes to be memory-resident +until unlocked or until the process exits or \fIexec\fPs another process +image. The implementation may require that \fIaddr\fP be a multiple +of +{PAGESIZE}. +.LP +The \fImunlock\fP() function shall unlock those whole pages containing +any part of the address space of the process starting at +address \fIaddr\fP and continuing for \fIlen\fP bytes, regardless +of how many times \fImlock\fP() has been called by the process +for any of the pages in the specified range. The implementation may +require that \fIaddr\fP be a multiple of {PAGESIZE}. +.LP +If any of the pages in the range specified to a call to \fImunlock\fP() +are also mapped into the address spaces of other +processes, any locks established on those pages by another process +are unaffected by the call of this process to \fImunlock\fP(). +If any of the pages in the range specified by a call to \fImunlock\fP() +are also mapped into other portions of the address space +of the calling process outside the range specified, any locks established +on those pages via the other mappings are also unaffected +by this call. +.LP +Upon successful return from \fImlock\fP(), pages in the specified +range shall be locked and memory-resident. Upon successful +return from \fImunlock\fP(), pages in the specified range shall be +unlocked with respect to the address space of the process. +Memory residency of unlocked pages is unspecified. +.LP +The appropriate privilege is required to lock process memory with +\fImlock\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, the \fImlock\fP() and \fImunlock\fP() +functions shall return a value of zero. Otherwise, no change +is made to any locks in the address space of the process, and the +function shall return a value of -1 and set \fIerrno\fP to +indicate the error. +.SH ERRORS +.LP +The \fImlock\fP() and \fImunlock\fP() functions shall fail if: +.TP 7 +.B ENOMEM +Some or all of the address range specified by the \fIaddr\fP and \fIlen\fP +arguments does not correspond to valid mapped +pages in the address space of the process. +.sp +.LP +The \fImlock\fP() function shall fail if: +.TP 7 +.B EAGAIN +Some or all of the memory identified by the operation could not be +locked when the call was made. +.sp +.LP +The \fImlock\fP() and \fImunlock\fP() functions may fail if: +.TP 7 +.B EINVAL +The \fIaddr\fP argument is not a multiple of {PAGESIZE}. +.sp +.LP +The \fImlock\fP() function may fail if: +.TP 7 +.B ENOMEM +Locking the pages mapped by the specified range would exceed an implementation-defined +limit on the amount of memory that the +process may lock. +.TP 7 +.B EPERM +The calling process does not have the appropriate privilege to perform +the requested operation. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIexit\fP() , \fIfork\fP() , \fImlockall\fP() , \fImunmap\fP() +, the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mlockall.3p b/man3p/mlockall.3p new file mode 100644 index 000000000..a0672cb36 --- /dev/null +++ b/man3p/mlockall.3p @@ -0,0 +1,133 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MLOCKALL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mlockall +.SH NAME +mlockall, munlockall \- lock/unlock the address space of a process +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int mlockall(int\fP \fIflags\fP\fB); +.br +int munlockall(void); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImlockall\fP() function shall cause all of the pages mapped +by the address space of a process to be memory-resident until +unlocked or until the process exits or \fIexec\fPs another process +image. The \fIflags\fP +argument determines whether the pages to be locked are those currently +mapped by the address space of the process, those that are +mapped in the future, or both. The \fIflags\fP argument is constructed +from the bitwise-inclusive OR of one or more of the +following symbolic constants, defined in \fI\fP: +.TP 7 +MCL_CURRENT +Lock all of the pages currently mapped into the address space of the +process. +.TP 7 +MCL_FUTURE +Lock all of the pages that become mapped into the address space of +the process in the future, when those mappings are +established. +.sp +.LP +If MCL_FUTURE is specified, and the automatic locking of future mappings +eventually causes the amount of locked memory to exceed +the amount of available physical memory or any other implementation-defined +limit, the behavior is implementation-defined. The +manner in which the implementation informs the application of these +situations is also implementation-defined. +.LP +The \fImunlockall\fP() function shall unlock all currently mapped +pages of the address space of the process. Any pages that +become mapped into the address space of the process after a call to +\fImunlockall\fP() shall not be locked, unless there is an +intervening call to \fImlockall\fP() specifying MCL_FUTURE or a subsequent +call to \fImlockall\fP() specifying MCL_CURRENT. If +pages mapped into the address space of the process are also mapped +into the address spaces of other processes and are locked by +those processes, the locks established by the other processes shall +be unaffected by a call by this process to +\fImunlockall\fP(). +.LP +Upon successful return from the \fImlockall\fP() function that specifies +MCL_CURRENT, all currently mapped pages of the +process' address space shall be memory-resident and locked. Upon return +from the \fImunlockall\fP() function, all currently mapped +pages of the process' address space shall be unlocked with respect +to the process' address space. The memory residency of unlocked +pages is unspecified. +.LP +The appropriate privilege is required to lock process memory with +\fImlockall\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, the \fImlockall\fP() function shall return +a value of zero. Otherwise, no additional memory shall +be locked, and the function shall return a value of -1 and set \fIerrno\fP +to indicate the error. The effect of failure of +\fImlockall\fP() on previously existing locks in the address space +is unspecified. +.LP +If it is supported by the implementation, the \fImunlockall\fP() function +shall always return a value of zero. Otherwise, the +function shall return a value of -1 and set \fIerrno\fP to indicate +the error. +.SH ERRORS +.LP +The \fImlockall\fP() function shall fail if: +.TP 7 +.B EAGAIN +Some or all of the memory identified by the operation could not be +locked when the call was made. +.TP 7 +.B EINVAL +The \fIflags\fP argument is zero, or includes unimplemented flags. +.sp +.LP +The \fImlockall\fP() function may fail if: +.TP 7 +.B ENOMEM +Locking all of the pages currently mapped into the address space of +the process would exceed an implementation-defined limit on +the amount of memory that the process may lock. +.TP 7 +.B EPERM +The calling process does not have the appropriate privilege to perform +the requested operation. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIexit\fP() , \fIfork\fP() , \fImlock\fP() , \fImunmap\fP() +, the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mmap.3p b/man3p/mmap.3p new file mode 100644 index 000000000..2a60ea937 --- /dev/null +++ b/man3p/mmap.3p @@ -0,0 +1,510 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MMAP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mmap +.SH NAME +mmap \- map pages of memory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void *mmap(void *\fP\fIaddr\fP\fB, size_t\fP \fIlen\fP\fB, int\fP +\fIprot\fP\fB, int\fP \fIflags\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIfildes\fP\fB, off_t\fP \fIoff\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImmap\fP() function shall establish a mapping between a process' +address space and a file, shared memory object, or +\ typed memory object. The format of the call is as +follows: +.sp +.RS +.nf + +\fIpa\fP\fB=\fP\fImmap\fP\fB(\fP\fIaddr\fP\fB,\fP \fIlen\fP\fB,\fP \fIprot\fP\fB,\fP \fIflags\fP\fB,\fP \fIfildes\fP\fB,\fP \fIoff\fP\fB); +\fP +.fi +.RE +.LP +The \fImmap\fP() function shall establish a mapping between the address +space of the process at an address \fIpa\fP for +\fIlen\fP bytes to the memory object represented by the file descriptor +\fIfildes\fP at offset \fIoff\fP for \fIlen\fP bytes. +The value of \fIpa\fP is an implementation-defined function of the +parameter \fIaddr\fP and the values of \fIflags\fP, further +described below. A successful \fImmap\fP() call shall return \fIpa\fP +as its result. The address range starting at \fIpa\fP and +continuing for \fIlen\fP bytes shall be legitimate for the possible +(not necessarily current) address space of the process. The +range of bytes starting at \fIoff\fP and continuing for \fIlen\fP +bytes shall be legitimate for the possible (not necessarily +current) offsets in the file, shared memory object, or \ typed memory +object \ represented by \fIfildes\fP. +.LP +If \fIfildes\fP represents a typed memory object opened with either +the POSIX_TYPED_MEM_ALLOCATE flag or the +POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, the memory object to be mapped +shall be that portion of the typed memory object allocated by +the implementation as specified below. In this case, if \fIoff\fP +is non-zero, the behavior of \fImmap\fP() is undefined. If +\fIfildes\fP refers to a valid typed memory object that is not accessible +from the calling process, \fImmap\fP() shall fail. +.LP +The mapping established by \fImmap\fP() shall replace any previous +mappings for those whole pages containing any part of the +address space of the process starting at \fIpa\fP and continuing for +\fIlen\fP bytes. +.LP +If the size of the mapped file changes after the call to \fImmap\fP() +as a result of some other operation on the mapped file, +the effect of references to portions of the mapped region that correspond +to added or removed portions of the file is +unspecified. +.LP +The \fImmap\fP() function shall be supported for regular files, shared +memory objects, and \ typed memory +objects. Support for any other type of file is unspecified. +.LP +The parameter \fIprot\fP determines whether read, write, execute, +or some combination of accesses are permitted to the data +being mapped. The \fIprot\fP shall be either PROT_NONE or the bitwise-inclusive +OR of one or more of the other flags in the +following table, defined in the \fI\fP header. +.TS C +center; l l. +\fBSymbolic Constant\fP \fBDescription\fP +PROT_READ Data can be read. +PROT_WRITE Data can be written. +PROT_EXEC Data can be executed. +PROT_NONE Data cannot be accessed. +.TE +.LP +If an implementation cannot support the combination of access types +specified by \fIprot\fP, the call to \fImmap\fP() shall +fail. +.LP +An implementation may permit accesses other than those specified by +\fIprot\fP; \ however, if +the Memory Protection option is supported, the implementation shall +not permit a write to succeed where PROT_WRITE has not been set +or shall not permit any access where PROT_NONE alone has been set. +The implementation shall support at least the following values +of \fIprot\fP: PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise-inclusive +OR of PROT_READ and PROT_WRITE. If the Memory Protection option is +not supported, the result of any access +that conflicts with the specified protection is undefined. The file +descriptor \fIfildes\fP shall have been opened with read +permission, regardless of the protection options specified. If PROT_WRITE +is specified, the application shall ensure that it has +opened the file descriptor \fIfildes\fP with write permission unless +MAP_PRIVATE is specified in the \fIflags\fP parameter as +described below. +.LP +The parameter \fIflags\fP provides other information about the handling +of the mapped data. The value of \fIflags\fP is the +bitwise-inclusive OR of these options, defined in \fI\fP: +.TS C +center; l l. +\fBSymbolic Constant\fP \fBDescription\fP +MAP_SHARED Changes are shared. +MAP_PRIVATE Changes are private. +MAP_FIXED Interpret \fIaddr\fP exactly. +.TE +.LP +Implementations that do not support the Memory Mapped Files option +are not required to support MAP_PRIVATE. +.LP +It is implementation-defined whether MAP_FIXED shall be supported. +\ MAP_FIXED shall be supported on XSI-conformant systems. +.LP +MAP_SHARED and MAP_PRIVATE describe the disposition of write references +to the memory object. If MAP_SHARED is specified, write +references shall change the underlying object. If MAP_PRIVATE is specified, +modifications to the mapped data by the calling process +shall be visible only to the calling process and shall not change +the underlying object. It is unspecified whether modifications to +the underlying object done after the MAP_PRIVATE mapping is established +are visible through the MAP_PRIVATE mapping. Either +MAP_SHARED or MAP_PRIVATE can be specified, but not both. The mapping +type is retained across \fIfork\fP(). +.LP +When \fIfildes\fP represents a typed memory object opened with either +the POSIX_TYPED_MEM_ALLOCATE flag or the +POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, \fImmap\fP() shall, if there +are enough resources available, map \fIlen\fP bytes allocated +from the corresponding typed memory object which were not previously +allocated to any process in any processor that may access that +typed memory object. If there are not enough resources available, +the function shall fail. If \fIfildes\fP represents a typed +memory object opened with the POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, +these allocated bytes shall be contiguous within the typed +memory object. If \fIfildes\fP represents a typed memory object opened +with the POSIX_TYPED_MEM_ALLOCATE flag, these allocated +bytes may be composed of non-contiguous fragments within the typed +memory object. If \fIfildes\fP represents a typed memory object +opened with neither the POSIX_TYPED_MEM_ALLOCATE_CONTIG flag nor the +POSIX_TYPED_MEM_ALLOCATE flag, \fIlen\fP bytes starting at +offset \fIoff\fP within the typed memory object are mapped, exactly +as when mapping a file or shared memory object. In this case, +if two processes map an area of typed memory using the same \fIoff\fP +and \fIlen\fP values and using file descriptors that refer +to the same memory pool (either from the same port or from a different +port), both processes shall map the same region of storage. +.LP +When MAP_FIXED is set in the \fIflags\fP argument, the implementation +is informed that the value of \fIpa\fP shall be +\fIaddr\fP, exactly. If MAP_FIXED is set, \fImmap\fP() may return +MAP_FAILED and set \fIerrno\fP to [EINVAL]. If a MAP_FIXED +request is successful, the mapping established by \fImmap\fP() replaces +any previous mappings for the process' pages in the range +[\fIpa\fP,\fIpa\fP+\fIlen\fP). +.LP +When MAP_FIXED is not set, the implementation uses \fIaddr\fP in an +implementation-defined manner to arrive at \fIpa\fP. The +\fIpa\fP so chosen shall be an area of the address space that the +implementation deems suitable for a mapping of \fIlen\fP bytes +to the file. All implementations interpret an \fIaddr\fP value of +0 as granting the implementation complete freedom in selecting +\fIpa\fP, subject to constraints described below. A non-zero value +of \fIaddr\fP is taken to be a suggestion of a process address +near which the mapping should be placed. When the implementation selects +a value for \fIpa\fP, it never places a mapping at +address 0, nor does it replace any extant mapping. +.LP +The \fIoff\fP argument is constrained to be aligned and sized according +to the value returned by \fIsysconf\fP() when passed _SC_PAGESIZE +or _SC_PAGE_SIZE. When MAP_FIXED is specified, the +application shall ensure that the argument \fIaddr\fP also meets these +constraints. The implementation performs mapping operations +over whole pages. Thus, while the argument \fIlen\fP need not meet +a size or alignment constraint, the implementation shall +include, in any mapping operation, any partial page specified by the +range [\fIpa\fP,\fIpa\fP+\fIlen\fP). +.LP +The system shall always zero-fill any partial page at the end of an +object. Further, the system shall never write out any +modified portions of the last page of an object which are beyond its +end. \ References +within the address range starting at \fIpa\fP and continuing for \fIlen\fP +bytes to whole pages following the end of an object +shall result in delivery of a SIGBUS signal. +.LP +An implementation may generate SIGBUS signals when a reference would +cause an error in the mapped object, such as out-of-space +condition. +.LP +The \fImmap\fP() function shall add an extra reference to the file +associated with the file descriptor \fIfildes\fP which is +not removed by a subsequent \fIclose\fP() on that file descriptor. +This reference shall be +removed when there are no more mappings to the file. +.LP +The \fIst_atime\fP field of the mapped file may be marked for update +at any time between the \fImmap\fP() call and the +corresponding \fImunmap\fP() call. The initial read or write reference +to a mapped region +shall cause the file's \fIst_atime\fP field to be marked for update +if it has not already been marked for update. +.LP +The \fIst_ctime\fP and \fIst_mtime\fP fields of a file that is mapped +with MAP_SHARED and PROT_WRITE shall be marked for +update at some point in the interval between a write reference to +the mapped region and the next call to \fImsync\fP() with MS_ASYNC +or MS_SYNC for that portion of the file by any process. If there is +no +such call and if the underlying file is modified as a result of a +write reference, then these fields shall be marked for update at +some time after the write reference. +.LP +There may be implementation-defined limits on the number of memory +regions that can be mapped (per process or per system). +.LP +If such a limit is imposed, whether the number of memory regions that +can be mapped by a process is decreased by the use of \fIshmat\fP() +is implementation-defined. +.LP +If \fImmap\fP() fails for reasons other than [EBADF], [EINVAL], or +[ENOTSUP], some of the mappings in the address range +starting at \fIaddr\fP and continuing for \fIlen\fP bytes may have +been unmapped. +.SH RETURN VALUE +.LP +Upon successful completion, the \fImmap\fP() function shall return +the address at which the mapping was placed ( \fIpa\fP); +otherwise, it shall return a value of MAP_FAILED and set \fIerrno\fP +to indicate the error. The symbol MAP_FAILED is defined in +the \fI\fP header. No successful return from \fImmap\fP() +shall +return the value MAP_FAILED. +.SH ERRORS +.LP +The \fImmap\fP() function shall fail if: +.TP 7 +.B EACCES +The \fIfildes\fP argument is not open for read, regardless of the +protection specified, or \fIfildes\fP is not open for write +and PROT_WRITE was specified for a MAP_SHARED type mapping. +.TP 7 +.B EAGAIN +The mapping could not be locked in memory, if required by \fImlockall\fP(), +due to a lack +of resources. +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid open file descriptor. +.TP 7 +.B EINVAL +The \fIaddr\fP argument (if MAP_FIXED was specified) or \fIoff\fP +is not a multiple of the page size as returned by \fIsysconf\fP(), +or is considered invalid by the implementation. +.TP 7 +.B EINVAL +The value of \fIflags\fP is invalid (neither MAP_PRIVATE nor MAP_SHARED +is set). +.TP 7 +.B EMFILE +The number of mapped regions would exceed an implementation-defined +limit (per process or per system). +.TP 7 +.B ENODEV +The \fIfildes\fP argument refers to a file whose type is not supported +by \fImmap\fP(). +.TP 7 +.B ENOMEM +MAP_FIXED was specified, and the range [\fIaddr\fP,\fIaddr\fP+\fIlen\fP) +exceeds that allowed for the address space of a +process; or, if MAP_FIXED was not specified and there is insufficient +room in the address space to effect the mapping. +.TP 7 +.B ENOMEM +The mapping could not be locked in memory, if required by \fImlockall\fP(), +because it +would require more space than the system is able to supply. +.TP 7 +.B ENOMEM +Not enough unallocated memory resources remain in the typed memory +object designated by \fIfildes\fP to allocate \fIlen\fP bytes. +.TP 7 +.B ENOTSUP +MAP_FIXED or MAP_PRIVATE was specified in the \fIflags\fP argument +and the implementation does not support this functionality. +.LP +The implementation does not support the combination of accesses requested +in the \fIprot\fP argument. +.TP 7 +.B ENXIO +Addresses in the range [\fIoff\fP,\fIoff\fP+\fIlen\fP) are invalid +for the object specified by \fIfildes\fP. +.TP 7 +.B ENXIO +MAP_FIXED was specified in \fIflags\fP and the combination of \fIaddr\fP, +\fIlen\fP, and \fIoff\fP is invalid for the +object specified by \fIfildes\fP. +.TP 7 +.B ENXIO +The \fIfildes\fP argument refers to a typed memory object that is +not accessible from the calling process. +.TP 7 +.B EOVERFLOW +The file is a regular file and the value of \fIoff\fP plus \fIlen\fP +exceeds the offset maximum established in the open file +description associated with \fIfildes\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Use of \fImmap\fP() may reduce the amount of memory available to other +memory allocation functions. +.LP +Use of MAP_FIXED may result in unspecified behavior in further use +of \fImalloc\fP() and +\fIshmat\fP(). The use of MAP_FIXED is discouraged, as it may prevent +an implementation from +making the most effective use of resources. +.LP +The application must ensure correct synchronization when using \fImmap\fP() +in conjunction with any other file access method, +such as \fIread\fP() and \fIwrite\fP(), standard +input/output, and \fIshmat\fP(). +.LP +The \fImmap\fP() function allows access to resources via address space +manipulations, instead of \fIread\fP()/ \fIwrite\fP(). Once a file +is mapped, all a +process has to do to access it is use the data at the address to which +the file was mapped. So, using pseudo-code to illustrate the +way in which an existing program might be changed to use \fImmap\fP(), +the following: +.sp +.RS +.nf + +\fBfildes = open(...) +lseek(fildes, some_offset) +read(fildes, buf, len) +/* Use data in buf. */ +\fP +.fi +.RE +.LP +becomes: +.sp +.RS +.nf + +\fBfildes = open(...) +address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset) +/* Use data at address. */ +\fP +.fi +.RE +.SH RATIONALE +.LP +After considering several other alternatives, it was decided to adopt +the \fImmap\fP() definition found in SVR4 for mapping +memory objects into process address spaces. The SVR4 definition is +minimal, in that it describes only what has been built, and what +appears to be necessary for a general and portable mapping facility. +.LP +Note that while \fImmap\fP() was first designed for mapping files, +it is actually a general-purpose mapping facility. It can be +used to map any appropriate object, such as memory, files, devices, +and so on, into the address space of a process. +.LP +When a mapping is established, it is possible that the implementation +may need to map more than is requested into the address +space of the process because of hardware requirements. An application, +however, cannot count on this behavior. Implementations that +do not use a paged architecture may simply allocate a common memory +region and return the address of it; such implementations +probably do not allocate any more than is necessary. References past +the end of the requested area are unspecified. +.LP +If an application requests a mapping that would overlay existing mappings +in the process, it might be desirable that an +implementation detect this and inform the application. However, the +default, portable (not MAP_FIXED) operation does not overlay +existing mappings. On the other hand, if the program specifies a fixed +address mapping (which requires some implementation +knowledge to determine a suitable address, if the function is supported +at all), then the program is presumed to be successfully +managing its own address space and should be trusted when it asks +to map over existing data structures. Furthermore, it is also +desirable to make as few system calls as possible, and it might be +considered onerous to require an \fImunmap\fP() before an \fImmap\fP() +to the same address range. This volume of +IEEE\ Std\ 1003.1-2001 specifies that the new mappings replace any +existing mappings, following existing practice in this +regard. +.LP +It is not expected, when the Memory Protection option is supported, +that all hardware implementations are able to support all +combinations of permissions at all addresses. When this option is +supported, implementations are required to disallow write access +to mappings without write permission and to disallow access to mappings +without any access permission. Other than these +restrictions, implementations may allow access types other than those +requested by the application. For example, if the application +requests only PROT_WRITE, the implementation may also allow read access. +A call to \fImmap\fP() fails if the implementation cannot +support allowing all the access requested by the application. For +example, some implementations cannot support a request for both +write access and execute access simultaneously. All implementations +supporting the Memory Protection option must support requests +for no access, read access, write access, and both read and write +access. Strictly conforming code must only rely on the required +checks. These restrictions allow for portability across a wide range +of hardware. +.LP +The MAP_FIXED address treatment is likely to fail for non-page-aligned +values and for certain architecture-dependent address +ranges. Conforming implementations cannot count on being able to choose +address values for MAP_FIXED without utilizing +non-portable, implementation-defined knowledge. Nonetheless, MAP_FIXED +is provided as a standard interface conforming to existing +practice for utilizing such knowledge when it is available. +.LP +Similarly, in order to allow implementations that do not support virtual +addresses, support for directly specifying any mapping +addresses via MAP_FIXED is not required and thus a conforming application +may not count on it. +.LP +The MAP_PRIVATE function can be implemented efficiently when memory +protection hardware is available. When such hardware is not +available, implementations can implement such "mappings" by simply +making a real copy of the relevant data into process private +memory, though this tends to behave similarly to \fIread\fP(). +.LP +The function has been defined to allow for many different models of +using shared memory. However, all uses are not equally +portable across all machine architectures. In particular, the \fImmap\fP() +function allows the system as well as the application +to specify the address at which to map a specific region of a memory +object. The most portable way to use the function is always to +let the system choose the address, specifying NULL as the value for +the argument \fIaddr\fP and not to specify MAP_FIXED. +.LP +If it is intended that a particular region of a memory object be mapped +at the same address in a group of processes (on machines +where this is even possible), then MAP_FIXED can be used to pass in +the desired mapping address. The system can still be used to +choose the desired address if the first such mapping is made without +specifying MAP_FIXED, and then the resulting mapping address +can be passed to subsequent processes for them to pass in via MAP_FIXED. +The availability of a specific address range cannot be +guaranteed, in general. +.LP +The \fImmap\fP() function can be used to map a region of memory that +is larger than the current size of the object. Memory +access within the mapping but beyond the current end of the underlying +objects may result in SIGBUS signals being sent to the +process. The reason for this is that the size of the object can be +manipulated by other processes and can change at any moment. The +implementation should tell the application that a memory reference +is outside the object where this can be detected; otherwise, +written data may be lost and read data may not reflect actual data +in the object. +.LP +Note that references beyond the end of the object do not extend the +object as the new end cannot be determined precisely by most +virtual memory hardware. Instead, the size can be directly manipulated +by \fIftruncate\fP(). +.LP +Process memory locking does apply to shared memory regions, and the +MEMLOCK_FUTURE argument to \fImlockall\fP() can be relied upon to +cause new shared memory regions to be automatically +locked. +.LP +Existing implementations of \fImmap\fP() return the value -1 when +unsuccessful. Since the casting of this value to type \fBvoid +*\fP cannot be guaranteed by the ISO\ C standard to be distinct from +a successful value, this volume of +IEEE\ Std\ 1003.1-2001 defines the symbol MAP_FAILED, which a conforming +implementation does not return as the result of a +successful call. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIfcntl\fP() , \fIfork\fP() , \fIlockf\fP() , \fImsync\fP() +, \fImunmap\fP() , \fImprotect\fP() , \fIposix_typed_mem_open\fP() +, \fIshmat\fP() , \fIsysconf\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/modf.3p b/man3p/modf.3p new file mode 100644 index 000000000..161e1c104 --- /dev/null +++ b/man3p/modf.3p @@ -0,0 +1,79 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MODF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" modf +.SH NAME +modf, modff, modfl \- decompose a floating-point number +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double modf(double\fP \fIx\fP\fB, double *\fP\fIiptr\fP\fB); +.br +float modff(float\fP \fIvalue\fP\fB, float *\fP\fIiptr\fP\fB); +.br +long double modfl(long double\fP \fIvalue\fP\fB, long double *\fP\fIiptr\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall break the argument \fIx\fP into integral and +fractional parts, each of which has the same sign as the +argument. It stores the integral part as a \fBdouble\fP (for the \fImodf\fP() +function), a \fBfloat\fP (for the \fImodff\fP() +function), or a \fBlong double\fP (for the \fImodfl\fP() function), +in the object pointed to by \fIiptr\fP. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the signed +fractional part of \fIx\fP. +.LP +If +\fIx\fP is NaN, a NaN shall be returned, and *\fIiptr\fP shall be +set to a NaN. +.LP +If \fIx\fP is \(+-Inf, \(+-0 shall be returned, and *\fIiptr\fP shall +be set to \(+-Inf. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fImodf\fP() function computes the function result and *\fIiptr\fP +such that: +.sp +.RS +.nf + +\fBa = modf(x, iptr) ; +x == a+*iptr ; +\fP +.fi +.RE +.LP +allowing for the usual floating-point inaccuracies. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfrexp\fP() , \fIisnan\fP() , \fIldexp\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/modff.3p b/man3p/modff.3p new file mode 100644 index 000000000..e3e887951 --- /dev/null +++ b/man3p/modff.3p @@ -0,0 +1 @@ +.so man3p/modf.3p diff --git a/man3p/modfl.3p b/man3p/modfl.3p new file mode 100644 index 000000000..e3e887951 --- /dev/null +++ b/man3p/modfl.3p @@ -0,0 +1 @@ +.so man3p/modf.3p diff --git a/man3p/mprotect.3p b/man3p/mprotect.3p new file mode 100644 index 000000000..06560e52c --- /dev/null +++ b/man3p/mprotect.3p @@ -0,0 +1,118 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MPROTECT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mprotect +.SH NAME +mprotect \- set protection of memory mapping +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int mprotect(void *\fP\fIaddr\fP\fB, size_t\fP \fIlen\fP\fB, int\fP +\fIprot\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImprotect\fP() function shall change the access protections +to be that specified by \fIprot\fP for those whole pages +containing any part of the address space of the process starting at +address \fIaddr\fP and continuing for \fIlen\fP bytes. The +parameter \fIprot\fP determines whether read, write, execute, or some +combination of accesses are permitted to the data being +mapped. The \fIprot\fP argument should be either PROT_NONE or the +bitwise-inclusive OR of one or more of PROT_READ, PROT_WRITE, +and PROT_EXEC. +.LP +If an implementation cannot support the combination of access types +specified by \fIprot\fP, the call to \fImprotect\fP() +shall fail. +.LP +An implementation may permit accesses other than those specified by +\fIprot\fP; however, no implementation shall permit a write +to succeed where PROT_WRITE has not been set or shall permit any access +where PROT_NONE alone has been set. Implementations shall +support at least the following values of \fIprot\fP: PROT_NONE, PROT_READ, +PROT_WRITE, and the bitwise-inclusive OR of PROT_READ +and PROT_WRITE. If PROT_WRITE is specified, the application shall +ensure that it has opened the mapped objects in the specified +address range with write permission, unless MAP_PRIVATE was specified +in the original mapping, regardless of whether the file +descriptors used to map the objects have since been closed. +.LP +The implementation shall require that \fIaddr\fP be a multiple of +the page size as returned by \fIsysconf\fP(). +.LP +The behavior of this function is unspecified if the mapping was not +established by a call to \fImmap\fP(). +.LP +When \fImprotect\fP() fails for reasons other than [EINVAL], the protections +on some of the pages in the range +[\fIaddr\fP,\fIaddr\fP+\fIlen\fP) may have been changed. +.SH RETURN VALUE +.LP +Upon successful completion, \fImprotect\fP() shall return 0; otherwise, +it shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fImprotect\fP() function shall fail if: +.TP 7 +.B EACCES +The \fIprot\fP argument specifies a protection that violates the access +permission the process has to the underlying memory +object. +.TP 7 +.B EAGAIN +The \fIprot\fP argument specifies PROT_WRITE over a MAP_PRIVATE mapping +and there are insufficient memory resources to reserve +for locking the private page. +.TP 7 +.B EINVAL +The \fIaddr\fP argument is not a multiple of the page size as returned +by \fIsysconf\fP(). +.TP 7 +.B ENOMEM +Addresses in the range [\fIaddr\fP,\fIaddr\fP+\fIlen\fP) are invalid +for the address space of a process, or specify one or +more pages which are not mapped. +.TP 7 +.B ENOMEM +The \fIprot\fP argument specifies PROT_WRITE on a MAP_PRIVATE mapping, +and it would require more space than the system is able +to supply for locking the private pages, if required. +.TP 7 +.B ENOTSUP +The implementation does not support the combination of accesses requested +in the \fIprot\fP argument. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The [EINVAL] error above is marked EX because it is defined as an +optional error in the POSIX Realtime Extension. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImmap\fP() , \fIsysconf\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mq_close.3p b/man3p/mq_close.3p new file mode 100644 index 000000000..d08df440c --- /dev/null +++ b/man3p/mq_close.3p @@ -0,0 +1,68 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MQ_CLOSE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mq_close +.SH NAME +mq_close \- close a message queue (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int mq_close(mqd_t\fP \fImqdes\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImq_close\fP() function shall remove the association between +the message queue descriptor, \fImqdes\fP, and its message +queue. The results of using this message queue descriptor after successful +return from this \fImq_close\fP(), and until the return +of this message queue descriptor from a subsequent \fImq_open\fP(), +are undefined. +.LP +If the process has successfully attached a notification request to +the message queue via this \fImqdes\fP, this attachment +shall be removed, and the message queue is available for another process +to attach for notification. +.SH RETURN VALUE +.LP +Upon successful completion, the \fImq_close\fP() function shall return +a value of zero; otherwise, the function shall return a +value of -1 and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fImq_close\fP() function shall fail if: +.TP 7 +.B EBADF +The \fImqdes\fP argument is not a valid message queue descriptor. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImq_open\fP() , \fImq_unlink\fP() , \fImsgctl\fP() , \fImsgget\fP() +, \fImsgrcv\fP() , \fImsgsnd\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mq_getattr.3p b/man3p/mq_getattr.3p new file mode 100644 index 000000000..c6e561ebb --- /dev/null +++ b/man3p/mq_getattr.3p @@ -0,0 +1,84 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MQ_GETATTR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mq_getattr +.SH NAME +mq_getattr \- get message queue attributes (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int mq_getattr(mqd_t\fP \fImqdes\fP\fB, struct mq_attr *\fP\fImqstat\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImq_getattr\fP() function shall obtain status information and +attributes of the message queue and the open message queue +description associated with the message queue descriptor. +.LP +The \fImqdes\fP argument specifies a message queue descriptor. +.LP +The results shall be returned in the \fBmq_attr\fP structure referenced +by the \fImqstat\fP argument. +.LP +Upon return, the following members shall have the values associated +with the open message queue description as set when the +message queue was opened and as modified by subsequent \fImq_setattr\fP() +calls: +\fImq_flags\fP. +.LP +The following attributes of the message queue shall be returned as +set at message queue creation: \fImq_maxmsg\fP, +\fImq_msgsize\fP. +.LP +Upon return, the following members within the \fBmq_attr\fP structure +referenced by the \fImqstat\fP argument shall be set to +the current state of the message queue: +.TP 7 +\fImq_curmsgs\fP +The number of messages currently on the queue. +.sp +.SH RETURN VALUE +.LP +Upon successful completion, the \fImq_getattr\fP() function shall +return zero. Otherwise, the function shall return -1 and set +\fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fImq_getattr\fP() function shall fail if: +.TP 7 +.B EBADF +The \fImqdes\fP argument is not a valid message queue descriptor. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImq_open\fP() , \fImq_send\fP() , \fImq_setattr\fP() , \fImq_timedsend\fP() +, \fImsgctl\fP() , \fImsgget\fP() , \fImsgrcv\fP() , \fImsgsnd\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mq_notify.3p b/man3p/mq_notify.3p new file mode 100644 index 000000000..797057926 --- /dev/null +++ b/man3p/mq_notify.3p @@ -0,0 +1,88 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MQ_NOTIFY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mq_notify +.SH NAME +mq_notify \- notify process that a message is available (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int mq_notify(mqd_t\fP \fImqdes\fP\fB, const struct sigevent *\fP\fInotification\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +If the argument \fInotification\fP is not NULL, this function shall +register the calling process to be notified of message +arrival at an empty message queue associated with the specified message +queue descriptor, \fImqdes\fP. The notification specified +by the \fInotification\fP argument shall be sent to the process when +the message queue transitions from empty to non-empty. At any +time, only one process may be registered for notification by a message +queue. If the calling process or any other process has +already registered for notification of message arrival at the specified +message queue, subsequent attempts to register for that +message queue shall fail. +.LP +If \fInotification\fP is NULL and the process is currently registered +for notification by the specified message queue, the +existing registration shall be removed. +.LP +When the notification is sent to the registered process, its registration +shall be removed. The message queue shall then be +available for registration. +.LP +If a process has registered for notification of message arrival at +a message queue and some thread is blocked in \fImq_receive\fP() waiting +to receive a message when a message arrives at the queue, the +arriving message shall satisfy the appropriate \fImq_receive\fP(). +The resulting +behavior is as if the message queue remains empty, and no notification +shall be sent. +.SH RETURN VALUE +.LP +Upon successful completion, the \fImq_notify\fP() function shall return +a value of zero; otherwise, the function shall return a +value of -1 and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fImq_notify\fP() function shall fail if: +.TP 7 +.B EBADF +The \fImqdes\fP argument is not a valid message queue descriptor. +.TP 7 +.B EBUSY +A process is already registered for notification by the message queue. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImq_open\fP() , \fImq_send\fP() , \fImq_timedsend\fP() , \fImsgctl\fP() +, \fImsgget\fP() , \fImsgrcv\fP() , \fImsgsnd\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mq_open.3p b/man3p/mq_open.3p new file mode 100644 index 000000000..433911e3f --- /dev/null +++ b/man3p/mq_open.3p @@ -0,0 +1,195 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MQ_OPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mq_open +.SH NAME +mq_open \- open a message queue (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +mqd_t mq_open(const char *\fP\fIname\fP\fB, int\fP \fIoflag\fP\fB, +\&...); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImq_open\fP() function shall establish the connection between +a process and a message queue with a message queue +descriptor. It shall create an open message queue description that +refers to the message queue, and a message queue descriptor that +refers to that open message queue description. The message queue descriptor +is used by other functions to refer to that message +queue. The \fIname\fP argument points to a string naming a message +queue. It is unspecified whether the name appears in the file +system and is visible to other functions that take pathnames as arguments. +The \fIname\fP argument shall conform to the +construction rules for a pathname. If \fIname\fP begins with the slash +character, then processes calling \fImq_open\fP() with the +same value of \fIname\fP shall refer to the same message queue object, +as long as that name has not been removed. If \fIname\fP +does not begin with the slash character, the effect is implementation-defined. +The interpretation of slash characters other than +the leading slash character in \fIname\fP is implementation-defined. +If the \fIname\fP argument is not the name of an existing +message queue and creation is not requested, \fImq_open\fP() shall +fail and return an error. +.LP +A message queue descriptor may be implemented using a file descriptor, +in which case applications can open up to at least +{OPEN_MAX} file and message queues. +.LP +The \fIoflag\fP argument requests the desired receive and/or send +access to the message queue. The requested access permission +to receive messages or send messages shall be granted if the calling +process would be granted read or write access, respectively, +to an equivalently protected file. +.LP +The value of \fIoflag\fP is the bitwise-inclusive OR of values from +the following list. Applications shall specify exactly one +of the first three values (access modes) below in the value of \fIoflag\fP: +.TP 7 +O_RDONLY +Open the message queue for receiving messages. The process can use +the returned message queue descriptor with \fImq_receive\fP(), but +not \fImq_send\fP(). A message +queue may be open multiple times in the same or different processes +for receiving messages. +.TP 7 +O_WRONLY +Open the queue for sending messages. The process can use the returned +message queue descriptor with \fImq_send\fP() but not \fImq_receive\fP(). +A message +queue may be open multiple times in the same or different processes +for sending messages. +.TP 7 +O_RDWR +Open the queue for both receiving and sending messages. The process +can use any of the functions allowed for O_RDONLY and +O_WRONLY. A message queue may be open multiple times in the same or +different processes for sending messages. +.sp +.LP +Any combination of the remaining flags may be specified in the value +of \fIoflag\fP: +.TP 7 +O_CREAT +Create a message queue. It requires two additional arguments: \fImode\fP, +which shall be of type \fBmode_t\fP, and +\fIattr\fP, which shall be a pointer to an \fBmq_attr\fP structure. +If the pathname \fIname\fP has already been used to create a +message queue that still exists, then this flag shall have no effect, +except as noted under O_EXCL. Otherwise, a message queue +shall be created without any messages in it. The user ID of the message +queue shall be set to the effective user ID of the process, +and the group ID of the message queue shall be set to the effective +group ID of the process. The file permission bits shall be set +to the value of \fImode\fP. When bits in \fImode\fP other than file +permission bits are set, the effect is +implementation-defined. If \fIattr\fP is NULL, the message queue shall +be created with implementation-defined default message +queue attributes. If \fIattr\fP is non-NULL and the calling process +has the appropriate privilege on \fIname\fP, the message +queue \fImq_maxmsg\fP and \fImq_msgsize\fP attributes shall be set +to the values of the corresponding members in the +\fBmq_attr\fP structure referred to by \fIattr\fP. If \fIattr\fP is +non-NULL, but the calling process does not have the +appropriate privilege on \fIname\fP, the \fImq_open\fP() function +shall fail and return an error without creating the message +queue. +.TP 7 +O_EXCL +If O_EXCL and O_CREAT are set, \fImq_open\fP() shall fail if the message +queue \fIname\fP exists. The check for the existence +of the message queue and the creation of the message queue if it does +not exist shall be atomic with respect to other threads +executing \fImq_open\fP() naming the same \fIname\fP with O_EXCL and +O_CREAT set. If O_EXCL is set and O_CREAT is not set, the +result is undefined. +.TP 7 +O_NONBLOCK +Determines whether an \fImq_send\fP() or \fImq_receive\fP() waits +for resources or messages that are not currently available, or fails +with \fIerrno\fP set to [EAGAIN]; see \fImq_send\fP() and \fImq_receive\fP() +for details. +.sp +.LP +The \fImq_open\fP() function does not add or remove messages from +the queue. +.SH RETURN VALUE +.LP +Upon successful completion, the function shall return a message queue +descriptor; otherwise, the function shall return +(\fBmqd_t\fP)-1 and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fImq_open\fP() function shall fail if: +.TP 7 +.B EACCES +The message queue exists and the permissions specified by \fIoflag\fP +are denied, or the message queue does not exist and +permission to create the message queue is denied. +.TP 7 +.B EEXIST +O_CREAT and O_EXCL are set and the named message queue already exists. +.TP 7 +.B EINTR +The \fImq_open\fP() function was interrupted by a signal. +.TP 7 +.B EINVAL +The \fImq_open\fP() function is not supported for the given name. +.TP 7 +.B EINVAL +O_CREAT was specified in \fIoflag\fP, the value of \fIattr\fP is not +NULL, and either \fImq_maxmsg\fP or \fImq_msgsize\fP +was less than or equal to zero. +.TP 7 +.B EMFILE +Too many message queue descriptors or file descriptors are currently +in use by this process. +.TP 7 +.B ENAMETOOLONG +The length of the \fIname\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENFILE +Too many message queues are currently open in the system. +.TP 7 +.B ENOENT +O_CREAT is not set and the named message queue does not exist. +.TP 7 +.B ENOSPC +There is insufficient space for the creation of the new message queue. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImq_close\fP() , \fImq_getattr\fP() , \fImq_receive\fP() , \fImq_send\fP() +, \fImq_setattr\fP() , \fImq_timedreceive\fP() , \fImq_timedsend\fP() +, \fImq_unlink\fP() , \fImsgctl\fP() , \fImsgget\fP() , \fImsgrcv\fP() +, \fImsgsnd\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mq_receive.3p b/man3p/mq_receive.3p new file mode 100644 index 000000000..d60f88ae8 --- /dev/null +++ b/man3p/mq_receive.3p @@ -0,0 +1,176 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MQ_RECEIVE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mq_receive +.SH NAME +mq_receive, mq_timedreceive \- receive a message from a message queue +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +ssize_t mq_receive(mqd_t\fP \fImqdes\fP\fB, char *\fP\fImsg_ptr\fP\fB, +size_t\fP \fImsg_len\fP\fB, +.br +\ \ \ \ \ \ unsigned *\fP\fImsg_prio\fP\fB); \fP +\fB +.br +.sp +\fP +.LP +\fB +.br +#include +.br +#include +.br +ssize_t mq_timedreceive(mqd_t\fP \fImqdes\fP\fB, char *restrict\fP +\fImsg_ptr\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fImsg_len\fP\fB, unsigned *restrict\fP \fImsg_prio\fP\fB, +.br +\ \ \ \ \ \ const struct timespec *restrict\fP \fIabs_timeout\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImq_receive\fP() function shall receive the oldest of the highest +priority message(s) from the message queue specified by +\fImqdes\fP. If the size of the buffer in bytes, specified by the +\fImsg_len\fP argument, is less than the \fImq_msgsize\fP +attribute of the message queue, the function shall fail and return +an error. Otherwise, the selected message shall be removed from +the queue and copied to the buffer pointed to by the \fImsg_ptr\fP +argument. +.LP +If the value of \fImsg_len\fP is greater than {SSIZE_MAX}, the result +is implementation-defined. +.LP +If the argument \fImsg_prio\fP is not NULL, the priority of the selected +message shall be stored in the location referenced by +\fImsg_prio\fP. +.LP +If the specified message queue is empty and O_NONBLOCK is not set +in the message queue description associated with \fImqdes\fP, +\fImq_receive\fP() shall block until a message is enqueued on the +message queue or until \fImq_receive\fP() is interrupted by a +signal. If more than one thread is waiting to receive a message when +a message arrives at an empty queue and the Priority +Scheduling option is supported, then the thread of highest priority +that has been waiting the longest shall be selected to receive +the message. Otherwise, it is unspecified which waiting thread receives +the message. If the specified message queue is empty and +O_NONBLOCK is set in the message queue description associated with +\fImqdes\fP, no message shall be removed from the queue, and +\fImq_receive\fP() shall return an error. +.LP +The \fImq_timedreceive\fP() function shall receive the oldest of the +highest priority messages from the message queue specified by +\fImqdes\fP as described for the \fImq_receive\fP() function. However, +if O_NONBLOCK was not specified when the message queue was +opened via the \fImq_open\fP() function, and no message exists on +the queue to satisfy the +receive, the wait for such a message shall be terminated when the +specified timeout expires. If O_NONBLOCK is set, this function is +equivalent to \fImq_receive\fP(). +.LP +The timeout expires when the absolute time specified by \fIabs_timeout\fP +passes, as measured by the clock on which timeouts +are based (that is, when the value of that clock equals or exceeds +\fIabs_timeout\fP), or if the absolute time specified by +\fIabs_timeout\fP has already been passed at the time of the call. +.LP +If the Timers option is supported, the timeout shall be based on the +CLOCK_REALTIME clock; if the Timers option is not +supported, the timeout shall be based on the system clock as returned +by the \fItime\fP() +function. +.LP +The resolution of the timeout shall be the resolution of the clock +on which it is based. The \fItimespec\fP argument is defined in +the \fI\fP header. +.LP +Under no circumstance shall the operation fail with a timeout if a +message can be removed from the message queue immediately. +The validity of the \fIabs_timeout\fP parameter need not be checked +if a message can be removed from the message queue +immediately. +.SH RETURN VALUE +.LP +Upon successful completion, the \fImq_receive\fP() \ and \fImq_timedreceive\fP() +functions shall return the length of the selected message in bytes +and the message shall be removed from +the queue. Otherwise, no message shall be removed from the queue, +the functions shall return a value of -1, and set \fIerrno\fP to +indicate the error. +.SH ERRORS +.LP +The \fImq_receive\fP() \ and \fImq_timedreceive\fP() +functions shall fail if: +.TP 7 +.B EAGAIN +O_NONBLOCK was set in the message description associated with \fImqdes\fP, +and the specified message queue is empty. +.TP 7 +.B EBADF +The \fImqdes\fP argument is not a valid message queue descriptor open +for reading. +.TP 7 +.B EMSGSIZE +The specified message buffer size, \fImsg_len\fP, is less than the +message size attribute of the message queue. +.TP 7 +.B EINTR +The \fImq_receive\fP() \ or \fImq_timedreceive\fP() +operation was interrupted by a signal. +.TP 7 +.B EINVAL +The process or thread would have blocked, and the \fIabs_timeout\fP +parameter specified a nanoseconds field value less than zero +or greater than or equal to 1000 million. +.TP 7 +.B ETIMEDOUT +The O_NONBLOCK flag was not set when the message queue was opened, +but no message arrived on the queue before the specified timeout +expired. +.sp +.LP +The \fImq_receive\fP() \ and \fImq_timedreceive\fP() +functions may fail if: +.TP 7 +.B EBADMSG +The implementation has detected a data corruption problem with the +message. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImq_open\fP() , \fImq_send\fP() , \fImq_timedsend\fP() , \fImsgctl\fP() +, \fImsgget\fP() , \fImsgrcv\fP() , \fImsgsnd\fP() , \fItime\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mq_send.3p b/man3p/mq_send.3p new file mode 100644 index 000000000..b8d1fba40 --- /dev/null +++ b/man3p/mq_send.3p @@ -0,0 +1,166 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MQ_SEND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mq_send +.SH NAME +mq_send, mq_timedsend \- send a message to a message queue (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int mq_send(mqd_t\fP \fImqdes\fP\fB, const char *\fP\fImsg_ptr\fP\fB, +size_t\fP \fImsg_len\fP\fB, +.br +\ \ \ \ \ \ unsigned\fP \fImsg_prio\fP\fB); \fP +\fB +.br +.sp +\fP +.LP +\fB +.br +#include +.br +#include +.br +int mq_timedsend(mqd_t\fP \fImqdes\fP\fB, const char *\fP\fImsg_ptr\fP\fB, +size_t\fP \fImsg_len\fP\fB, +.br +\ \ \ \ \ \ unsigned\fP \fImsg_prio\fP\fB, const struct timespec +*\fP\fIabs_timeout\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImq_send\fP() function shall add the message pointed to by the +argument \fImsg_ptr\fP to the message queue specified by +\fImqdes\fP. The \fImsg_len\fP argument specifies the length of the +message, in bytes, pointed to by \fImsg_ptr\fP. The value of +\fImsg_len\fP shall be less than or equal to the \fImq_msgsize\fP +attribute of the message queue, or \fImq_send\fP() shall +fail. +.LP +If the specified message queue is not full, \fImq_send\fP() shall +behave as if the message is inserted into the message queue +at the position indicated by the \fImsg_prio\fP argument. A message +with a larger numeric value of \fImsg_prio\fP shall be +inserted before messages with lower values of \fImsg_prio\fP. A message +shall be inserted after other messages in the queue, if +any, with equal \fImsg_prio\fP. The value of \fImsg_prio\fP shall +be less than {MQ_PRIO_MAX}. +.LP +If the specified message queue is full and O_NONBLOCK is not set in +the message queue description associated with \fImqdes\fP, +\fImq_send\fP() shall block until space becomes available to enqueue +the message, or until \fImq_send\fP() is interrupted by a +signal. If more than one thread is waiting to send when space becomes +available in the message queue and the Priority Scheduling +option is supported, then the thread of the highest priority that +has been waiting the longest shall be unblocked to send its +message. Otherwise, it is unspecified which waiting thread is unblocked. +If the specified message queue is full and O_NONBLOCK is +set in the message queue description associated with \fImqdes\fP, +the message shall not be queued and \fImq_send\fP() shall +return an error. +.LP +The \fImq_timedsend\fP() function shall add a message to the message +queue specified by \fImqdes\fP in the manner defined for the +\fImq_send\fP() function. However, if the specified message queue +is full and O_NONBLOCK is not set in the message queue +description associated with \fImqdes\fP, the wait for sufficient room +in the queue shall be terminated when the specified timeout +expires. If O_NONBLOCK is set in the message queue description, this +function shall be equivalent to \fImq_send\fP(). +.LP +The timeout shall expire when the absolute time specified by \fIabs_timeout\fP +passes, as measured by the clock on which +timeouts are based (that is, when the value of that clock equals or +exceeds \fIabs_timeout\fP), or if the absolute time specified +by \fIabs_timeout\fP has already been passed at the time of the call. +.LP +If the Timers option is supported, the timeout shall be based on the +CLOCK_REALTIME clock; if the Timers option is not +supported, the timeout shall be based on the system clock as returned +by the \fItime\fP() +function. +.LP +The resolution of the timeout shall be the resolution of the clock +on which it is based. The \fItimespec\fP argument is defined in +the \fI\fP header. +.LP +Under no circumstance shall the operation fail with a timeout if there +is sufficient room in the queue to add the message +immediately. The validity of the \fIabs_timeout\fP parameter need +not be checked when there is sufficient room in the queue. +.SH RETURN VALUE +.LP +Upon successful completion, the \fImq_send\fP() \ and \fImq_timedsend\fP() +functions shall return a value of zero. Otherwise, no message shall +be enqueued, the functions shall +return -1, and \fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +The \fImq_send\fP() \ and \fImq_timedsend\fP() +functions shall fail if: +.TP 7 +.B EAGAIN +The O_NONBLOCK flag is set in the message queue description associated +with \fImqdes\fP, and the specified message queue is +full. +.TP 7 +.B EBADF +The \fImqdes\fP argument is not a valid message queue descriptor open +for writing. +.TP 7 +.B EINTR +A signal interrupted the call to \fImq_send\fP() \ or \fImq_timedsend\fP(). +.TP 7 +.B EINVAL +The value of \fImsg_prio\fP was outside the valid range. +.TP 7 +.B EINVAL +The process or thread would have blocked, and the \fIabs_timeout\fP +parameter specified a nanoseconds field value less than zero +or greater than or equal to 1000 million. +.TP 7 +.B EMSGSIZE +The specified message length, \fImsg_len\fP, exceeds the message size +attribute of the message queue. +.TP 7 +.B ETIMEDOUT +The O_NONBLOCK flag was not set when the message queue was opened, +but the timeout expired before the message could be added to the +queue. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The value of the symbol {MQ_PRIO_MAX} limits the number of priority +levels supported by the application. Message priorities +range from 0 to {MQ_PRIO_MAX}-1. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImq_open\fP() , \fImq_receive\fP() , \fImq_setattr\fP() , \fImq_timedreceive\fP() +, \fItime\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mq_setattr.3p b/man3p/mq_setattr.3p new file mode 100644 index 000000000..78e436471 --- /dev/null +++ b/man3p/mq_setattr.3p @@ -0,0 +1,86 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MQ_SETATTR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mq_setattr +.SH NAME +mq_setattr \- set message queue attributes (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int mq_setattr(mqd_t\fP \fImqdes\fP\fB, const struct mq_attr *restrict\fP +\fImqstat\fP\fB, +.br +\ \ \ \ \ \ struct mq_attr *restrict\fP \fIomqstat\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImq_setattr\fP() function shall set attributes associated with +the open message queue description referenced by the +message queue descriptor specified by \fImqdes\fP. +.LP +The message queue attributes corresponding to the following members +defined in the \fBmq_attr\fP structure shall be set to the +specified values upon successful completion of \fImq_setattr\fP(): +.TP 7 +\fImq_flags\fP +The value of this member is the bitwise-logical OR of zero or more +of O_NONBLOCK and any implementation-defined flags. +.sp +.LP +The values of the \fImq_maxmsg\fP, \fImq_msgsize\fP, and \fImq_curmsgs\fP +members of the \fBmq_attr\fP structure shall be +ignored by \fImq_setattr\fP(). +.LP +If \fIomqstat\fP is non-NULL, the \fImq_setattr\fP() function shall +store, in the location referenced by \fIomqstat\fP, the +previous message queue attributes and the current queue status. These +values shall be the same as would be returned by a call to \fImq_getattr\fP() +at that point. +.SH RETURN VALUE +.LP +Upon successful completion, the function shall return a value of zero +and the attributes of the message queue shall have been +changed as specified. +.LP +Otherwise, the message queue attributes shall be unchanged, and the +function shall return a value of -1 and set \fIerrno\fP to +indicate the error. +.SH ERRORS +.LP +The \fImq_setattr\fP() function shall fail if: +.TP 7 +.B EBADF +The \fImqdes\fP argument is not a valid message queue descriptor. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImq_open\fP() , \fImq_send\fP() , \fImq_timedsend\fP() , \fImsgctl\fP() +, \fImsgget\fP() , \fImsgrcv\fP() , \fImsgsnd\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mq_timedreceive.3p b/man3p/mq_timedreceive.3p new file mode 100644 index 000000000..ac3648623 --- /dev/null +++ b/man3p/mq_timedreceive.3p @@ -0,0 +1 @@ +.so man3p/mq_receive.3p diff --git a/man3p/mq_timedsend.3p b/man3p/mq_timedsend.3p new file mode 100644 index 000000000..d0bfb7039 --- /dev/null +++ b/man3p/mq_timedsend.3p @@ -0,0 +1 @@ +.so man3p/mq_send.3p diff --git a/man3p/mq_unlink.3p b/man3p/mq_unlink.3p new file mode 100644 index 000000000..34193f163 --- /dev/null +++ b/man3p/mq_unlink.3p @@ -0,0 +1,79 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MQ_UNLINK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mq_unlink +.SH NAME +mq_unlink \- remove a message queue (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int mq_unlink(const char *\fP\fIname\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImq_unlink\fP() function shall remove the message queue named +by the pathname \fIname\fP. After a successful call to +\fImq_unlink\fP() with \fIname\fP, a call to \fImq_open\fP() with +\fIname\fP shall fail +if the flag O_CREAT is not set in \fIflags\fP. If one or more processes +have the message queue open when \fImq_unlink\fP() is +called, destruction of the message queue shall be postponed until +all references to the message queue have been closed. +.LP +Calls to \fImq_open\fP() to recreate the message queue may fail until +the message queue +is actually removed. However, the \fImq_unlink\fP() call need not +block until all references have been closed; it may return +immediately. +.SH RETURN VALUE +.LP +Upon successful completion, the function shall return a value of zero. +Otherwise, the named message queue shall be unchanged by +this function call, and the function shall return a value of -1 and +set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fImq_unlink\fP() function shall fail if: +.TP 7 +.B EACCES +Permission is denied to unlink the named message queue. +.TP 7 +.B ENAMETOOLONG +The length of the \fIname\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +The named message queue does not exist. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImq_close\fP() , \fImq_open\fP() , \fImsgctl\fP() , \fImsgget\fP() +, \fImsgrcv\fP() , \fImsgsnd\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/mrand48.3p b/man3p/mrand48.3p new file mode 100644 index 000000000..a71d5ed19 --- /dev/null +++ b/man3p/mrand48.3p @@ -0,0 +1 @@ +.so man3p/drand48.3p diff --git a/man3p/msgctl.3p b/man3p/msgctl.3p new file mode 100644 index 000000000..a98c122a6 --- /dev/null +++ b/man3p/msgctl.3p @@ -0,0 +1,130 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MSGCTL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" msgctl +.SH NAME +msgctl \- XSI message control operations +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int msgctl(int\fP \fImsqid\fP\fB, int\fP \fIcmd\fP\fB, struct msqid_ds +*\fP\fIbuf\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImsgctl\fP() function operates on XSI message queues (see the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 3.224, Message Queue). It is unspecified whether this function +interoperates with the realtime interprocess communication facilities +defined in \fIRealtime\fP . +.LP +The \fImsgctl\fP() function shall provide message control operations +as specified by \fIcmd\fP. The following values for +\fIcmd\fP, and the message control operations they specify, are: +.TP 7 +IPC_STAT +Place the current value of each member of the \fBmsqid_ds\fP data +structure associated with \fImsqid\fP into the structure +pointed to by \fIbuf\fP. The contents of this structure are defined +in \fI\fP. +.TP 7 +IPC_SET +Set the value of the following members of the \fBmsqid_ds\fP data +structure associated with \fImsqid\fP to the corresponding +value found in the structure pointed to by \fIbuf\fP: +.sp +.RS +.nf + +\fBmsg_perm.uid +msg_perm.gid +msg_perm.mode +msg_qbytes +\fP +.fi +.RE +.LP +IPC_SET can only be executed by a process with appropriate privileges +or that has an effective user ID equal to the value of +\fBmsg_perm.cuid\fP or \fBmsg_perm.uid\fP in the \fBmsqid_ds\fP data +structure associated with \fImsqid\fP. Only a process with +appropriate privileges can raise the value of \fBmsg_qbytes\fP. +.TP 7 +IPC_RMID +Remove the message queue identifier specified by \fImsqid\fP from +the system and destroy the message queue and \fBmsqid_ds\fP +data structure associated with it. IPC_RMD can only be executed by +a process with appropriate privileges or one that has an +effective user ID equal to the value of \fBmsg_perm.cuid\fP or \fBmsg_perm.uid\fP +in the \fBmsqid_ds\fP data structure +associated with \fImsqid\fP. +.sp +.SH RETURN VALUE +.LP +Upon successful completion, \fImsgctl\fP() shall return 0; otherwise, +it shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fImsgctl\fP() function shall fail if: +.TP 7 +.B EACCES +The argument \fIcmd\fP is IPC_STAT and the calling process does not +have read permission; see \fIXSI Interprocess Communication\fP . +.TP 7 +.B EINVAL +The value of \fImsqid\fP is not a valid message queue identifier; +or the value of \fIcmd\fP is not a valid command. +.TP 7 +.B EPERM +The argument \fIcmd\fP is IPC_RMID or IPC_SET and the effective user +ID of the calling process is not equal to that of a +process with appropriate privileges and it is not equal to the value +of \fBmsg_perm.cuid\fP or \fBmsg_perm.uid\fP in the data +structure associated with \fImsqid\fP. +.TP 7 +.B EPERM +The argument \fIcmd\fP is IPC_SET, an attempt is being made to increase +to the value of \fBmsg_qbytes\fP, and the effective +user ID of the calling process does not have appropriate privileges. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication (IPC). Application developers who +need to use IPC should design their applications so that modules using +the IPC routines described in \fIXSI Interprocess Communication\fP +can be easily modified to use the alternative +interfaces. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIXSI Interprocess Communication\fP , \fIRealtime\fP , \fImq_close\fP() +, \fImq_getattr\fP() , \fImq_notify\fP() , \fImq_open\fP() , \fImq_receive\fP() +, \fImq_send\fP() , \fImq_setattr\fP() , \fImq_unlink\fP() , \fImsgget\fP() +, \fImsgrcv\fP() , +\fImsgsnd\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/msgget.3p b/man3p/msgget.3p new file mode 100644 index 000000000..d4078421c --- /dev/null +++ b/man3p/msgget.3p @@ -0,0 +1,125 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MSGGET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" msgget +.SH NAME +msgget \- get the XSI message queue identifier +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int msgget(key_t\fP \fIkey\fP\fB, int\fP \fImsgflg\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImsgget\fP() function operates on XSI message queues (see the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 3.224, Message Queue). It is unspecified whether this function +interoperates with the realtime interprocess communication facilities +defined in \fIRealtime\fP . +.LP +The \fImsgget\fP() function shall return the message queue identifier +associated with the argument \fIkey\fP. +.LP +A message queue identifier, associated message queue, and data structure +(see \fI\fP), shall be created for the argument \fIkey\fP +if one of the following is +true: +.IP " *" 3 +The argument \fIkey\fP is equal to IPC_PRIVATE. +.LP +.IP " *" 3 +The argument \fIkey\fP does not already have a message queue identifier +associated with it, and (\fImsgflg\fP & IPC_CREAT) +is non-zero. +.LP +.LP +Upon creation, the data structure associated with the new message +queue identifier shall be initialized as follows: +.IP " *" 3 +\fBmsg_perm.cuid\fP, \fBmsg_perm.uid\fP, \fBmsg_perm.cgid\fP, and +\fBmsg_perm.gid\fP shall be set equal to the effective +user ID and effective group ID, respectively, of the calling process. +.LP +.IP " *" 3 +The low-order 9 bits of \fBmsg_perm.mode\fP shall be set equal to +the low-order 9 bits of \fImsgflg\fP. +.LP +.IP " *" 3 +\fBmsg_qnum\fP, \fBmsg_lspid\fP, \fBmsg_lrpid\fP, \fBmsg_stime\fP, +and \fBmsg_rtime\fP shall be set equal to 0. +.LP +.IP " *" 3 +\fBmsg_ctime\fP shall be set equal to the current time. +.LP +.IP " *" 3 +\fBmsg_qbytes\fP shall be set equal to the system limit. +.LP +.SH RETURN VALUE +.LP +Upon successful completion, \fImsgget\fP() shall return a non-negative +integer, namely a message queue identifier. Otherwise, +it shall return -1 and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fImsgget\fP() function shall fail if: +.TP 7 +.B EACCES +A message queue identifier exists for the argument \fIkey\fP, but +operation permission as specified by the low-order 9 bits of +\fImsgflg\fP would not be granted; see \fIXSI Interprocess Communication\fP +\&. +.TP 7 +.B EEXIST +A message queue identifier exists for the argument \fIkey\fP but ((\fImsgflg\fP +& IPC_CREAT) && (\fImsgflg\fP +& IPC_EXCL)) is non-zero. +.TP 7 +.B ENOENT +A message queue identifier does not exist for the argument \fIkey\fP +and (\fImsgflg\fP & IPC_CREAT) is 0. +.TP 7 +.B ENOSPC +A message queue identifier is to be created but the system-imposed +limit on the maximum number of allowed message queue +identifiers system-wide would be exceeded. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication (IPC). Application developers who +need to use IPC should design their applications so that modules using +the IPC routines described in \fIXSI Interprocess Communication\fP +can be easily modified to use the alternative +interfaces. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIXSI Interprocess Communication\fP , \fIRealtime\fP , \fImq_close\fP() +, \fImq_getattr\fP() , \fImq_notify\fP() , \fImq_open\fP() , \fImq_receive\fP() +, \fImq_send\fP() , \fImq_setattr\fP() , \fImq_unlink\fP() , \fImsgctl\fP() +, \fImsgrcv\fP() , +\fImsgsnd\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/msgrcv.3p b/man3p/msgrcv.3p new file mode 100644 index 000000000..7104a8f75 --- /dev/null +++ b/man3p/msgrcv.3p @@ -0,0 +1,214 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MSGRCV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" msgrcv +.SH NAME +msgrcv \- XSI message receive operation +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +ssize_t msgrcv(int\fP \fImsqid\fP\fB, void *\fP\fImsgp\fP\fB, size_t\fP +\fImsgsz\fP\fB, long\fP +\fImsgtyp\fP\fB, +.br +\ \ \ \ \ \ int\fP \fImsgflg\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImsgrcv\fP() function operates on XSI message queues (see the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 3.224, Message Queue). It is unspecified whether this function +interoperates with the realtime interprocess communication facilities +defined in \fIRealtime\fP . +.LP +The \fImsgrcv\fP() function shall read a message from the queue associated +with the message queue identifier specified by +\fImsqid\fP and place it in the user-defined buffer pointed to by +\fImsgp\fP. +.LP +The application shall ensure that the argument \fImsgp\fP points to +a user-defined buffer that contains first a field of type +\fBlong\fP specifying the type of the message, and then a data portion +that holds the data bytes of the message. The structure +below is an example of what this user-defined buffer might look like: +.sp +.RS +.nf + +\fBstruct mymsg { + long mtype; /* Message type. */ + char mtext[1]; /* Message text. */ +} +\fP +.fi +.RE +.LP +The structure member \fImtype\fP is the received message's type as +specified by the sending process. +.LP +The structure member \fImtext\fP is the text of the message. +.LP +The argument \fImsgsz\fP specifies the size in bytes of \fImtext\fP. +The received message shall be truncated to \fImsgsz\fP +bytes if it is larger than \fImsgsz\fP and (\fImsgflg\fP & MSG_NOERROR) +is non-zero. The truncated part of the message shall +be lost and no indication of the truncation shall be given to the +calling process. +.LP +If the value of \fImsgsz\fP is greater than {SSIZE_MAX}, the result +is implementation-defined. +.LP +The argument \fImsgtyp\fP specifies the type of message requested +as follows: +.IP " *" 3 +If \fImsgtyp\fP is 0, the first message on the queue shall be received. +.LP +.IP " *" 3 +If \fImsgtyp\fP is greater than 0, the first message of type \fImsgtyp\fP +shall be received. +.LP +.IP " *" 3 +If \fImsgtyp\fP is less than 0, the first message of the lowest type +that is less than or equal to the absolute value of +\fImsgtyp\fP shall be received. +.LP +.LP +The argument \fImsgflg\fP specifies the action to be taken if a message +of the desired type is not on the queue. These are as +follows: +.IP " *" 3 +If (\fImsgflg\fP & IPC_NOWAIT) is non-zero, the calling thread shall +return immediately with a return value of -1 and +\fIerrno\fP set to [ENOMSG]. +.LP +.IP " *" 3 +If (\fImsgflg\fP & IPC_NOWAIT) is 0, the calling thread shall suspend +execution until one of the following occurs: +.RS +.IP " *" 3 +A message of the desired type is placed on the queue. +.LP +.IP " *" 3 +The message queue identifier \fImsqid\fP is removed from the system; +when this occurs, \fIerrno\fP shall be set equal to +[EIDRM] and -1 shall be returned. +.LP +.IP " *" 3 +The calling thread receives a signal that is to be caught; in this +case a message is not received and the calling thread resumes +execution in the manner prescribed in \fIsigaction\fP() . +.LP +.RE +.LP +.LP +Upon successful completion, the following actions are taken with respect +to the data structure associated with \fImsqid\fP: +.IP " *" 3 +\fBmsg_qnum\fP shall be decremented by 1. +.LP +.IP " *" 3 +\fBmsg_lrpid\fP shall be set equal to the process ID of the calling +process. +.LP +.IP " *" 3 +\fBmsg_rtime\fP shall be set equal to the current time. +.LP +.SH RETURN VALUE +.LP +Upon successful completion, \fImsgrcv\fP() shall return a value equal +to the number of bytes actually placed into the buffer +\fImtext\fP. Otherwise, no message shall be received, \fImsgrcv\fP() +shall return (\fBssize_t\fP)-1, and \fIerrno\fP shall be +set to indicate the error. +.SH ERRORS +.LP +The \fImsgrcv\fP() function shall fail if: +.TP 7 +.B E2BIG +The value of \fImtext\fP is greater than \fImsgsz\fP and (\fImsgflg\fP +& MSG_NOERROR) is 0. +.TP 7 +.B EACCES +Operation permission is denied to the calling process; see \fIXSI +Interprocess +Communication\fP . +.TP 7 +.B EIDRM +The message queue identifier \fImsqid\fP is removed from the system. +.TP 7 +.B EINTR +The \fImsgrcv\fP() function was interrupted by a signal. +.TP 7 +.B EINVAL +\fImsqid\fP is not a valid message queue identifier. +.TP 7 +.B ENOMSG +The queue does not contain a message of the desired type and (\fImsgflg\fP +& IPC_NOWAIT) is non-zero. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Receiving a Message +.LP +The following example receives the first message on the queue (based +on the value of the \fImsgtyp\fP argument, 0). The queue +is identified by the \fImsqid\fP argument (assuming that the value +has previously been set). This call specifies that an error +should be reported if no message is available, but not if the message +is too large. The message size is calculated directly using +the \fIsizeof\fP operator. +.sp +.RS +.nf + +\fB#include +\&... +int result; +int msqid; +struct message { + long type; + char text[20]; +} msg; +long msgtyp = 0; +\&... +result = msgrcv(msqid, (void *) &msg, sizeof(msg.text), + msgtyp, MSG_NOERROR | IPC_NOWAIT); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication (IPC). Application developers who +need to use IPC should design their applications so that modules using +the IPC routines described in \fIXSI Interprocess Communication\fP +can be easily modified to use the alternative +interfaces. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIXSI Interprocess Communication\fP , \fIRealtime\fP , \fImq_close\fP() +, \fImq_getattr\fP() , \fImq_notify\fP() , \fImq_open\fP() , \fImq_receive\fP() +, \fImq_send\fP() , \fImq_setattr\fP() , \fImq_unlink\fP() , \fImsgctl\fP() +, \fImsgget\fP() , +\fImsgsnd\fP() , \fIsigaction\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/msgsnd.3p b/man3p/msgsnd.3p new file mode 100644 index 000000000..2bfb538ea --- /dev/null +++ b/man3p/msgsnd.3p @@ -0,0 +1,196 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MSGSND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" msgsnd +.SH NAME +msgsnd \- XSI message send operation +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int msgsnd(int\fP \fImsqid\fP\fB, const void *\fP\fImsgp\fP\fB, size_t\fP +\fImsgsz\fP\fB, int\fP \fImsgflg\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImsgsnd\fP() function operates on XSI message queues (see the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 3.224, Message Queue). It is unspecified whether this function +interoperates with the realtime interprocess communication facilities +defined in \fIRealtime\fP . +.LP +The \fImsgsnd\fP() function shall send a message to the queue associated +with the message queue identifier specified by +\fImsqid\fP. +.LP +The application shall ensure that the argument \fImsgp\fP points to +a user-defined buffer that contains first a field of type +\fBlong\fP specifying the type of the message, and then a data portion +that holds the data bytes of the message. The structure +below is an example of what this user-defined buffer might look like: +.sp +.RS +.nf + +\fBstruct mymsg { + long mtype; /* Message type. */ + char mtext[1]; /* Message text. */ +} +\fP +.fi +.RE +.LP +The structure member \fImtype\fP is a non-zero positive type \fBlong\fP +that can be used by the receiving process for message +selection. +.LP +The structure member \fImtext\fP is any text of length \fImsgsz\fP +bytes. The argument \fImsgsz\fP can range from 0 to a +system-imposed maximum. +.LP +The argument \fImsgflg\fP specifies the action to be taken if one +or more of the following is true: +.IP " *" 3 +The number of bytes already on the queue is equal to \fBmsg_qbytes\fP; +see \fI\fP. +.LP +.IP " *" 3 +The total number of messages on all queues system-wide is equal to +the system-imposed limit. +.LP +.LP +These actions are as follows: +.IP " *" 3 +If (\fImsgflg\fP & IPC_NOWAIT) is non-zero, the message shall not +be sent and the calling thread shall return +immediately. +.LP +.IP " *" 3 +If (\fImsgflg\fP & IPC_NOWAIT) is 0, the calling thread shall suspend +execution until one of the following occurs: +.RS +.IP " *" 3 +The condition responsible for the suspension no longer exists, in +which case the message is sent. +.LP +.IP " *" 3 +The message queue identifier \fImsqid\fP is removed from the system; +when this occurs, \fIerrno\fP shall be set equal to +[EIDRM] and -1 shall be returned. +.LP +.IP " *" 3 +The calling thread receives a signal that is to be caught; in this +case the message is not sent and the calling thread resumes +execution in the manner prescribed in \fIsigaction\fP() . +.LP +.RE +.LP +.LP +Upon successful completion, the following actions are taken with respect +to the data structure associated with \fImsqid\fP; see +\fI\fP: +.IP " *" 3 +\fBmsg_qnum\fP shall be incremented by 1. +.LP +.IP " *" 3 +\fBmsg_lspid\fP shall be set equal to the process ID of the calling +process. +.LP +.IP " *" 3 +\fBmsg_stime\fP shall be set equal to the current time. +.LP +.SH RETURN VALUE +.LP +Upon successful completion, \fImsgsnd\fP() shall return 0; otherwise, +no message shall be sent, \fImsgsnd\fP() shall return +-1, and \fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +The \fImsgsnd\fP() function shall fail if: +.TP 7 +.B EACCES +Operation permission is denied to the calling process; see \fIXSI +Interprocess +Communication\fP . +.TP 7 +.B EAGAIN +The message cannot be sent for one of the reasons cited above and +(\fImsgflg\fP & IPC_NOWAIT) is non-zero. +.TP 7 +.B EIDRM +The message queue identifier \fImsqid\fP is removed from the system. +.TP 7 +.B EINTR +The \fImsgsnd\fP() function was interrupted by a signal. +.TP 7 +.B EINVAL +The value of \fImsqid\fP is not a valid message queue identifier, +or the value of \fImtype\fP is less than 1; or the value of +\fImsgsz\fP is less than 0 or greater than the system-imposed limit. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Sending a Message +.LP +The following example sends a message to the queue identified by the +\fImsqid\fP argument (assuming that value has previously +been set). This call specifies that an error should be reported if +no message is available. The message size is calculated directly +using the \fIsizeof\fP operator. +.sp +.RS +.nf + +\fB#include +\&... +int result; +int msqid; +struct message { + long type; + char text[20]; +} msg; +.sp + +msg.type = 1; +strcpy(msg.text, "This is message 1"); +\&... +result = msgsnd(msqid, (void *) &msg, sizeof(msg.text), IPC_NOWAIT); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication (IPC). Application developers who +need to use IPC should design their applications so that modules using +the IPC routines described in \fIXSI Interprocess Communication\fP +can be easily modified to use the alternative +interfaces. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIXSI Interprocess Communication\fP , \fIRealtime\fP , \fImq_close\fP() +, \fImq_getattr\fP() , \fImq_notify\fP() , \fImq_open\fP() , \fImq_receive\fP() +, \fImq_send\fP() , \fImq_setattr\fP() , \fImq_unlink\fP() , \fImsgctl\fP() +, \fImsgget\fP() , +\fImsgrcv\fP() , \fIsigaction\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/msync.3p b/man3p/msync.3p new file mode 100644 index 000000000..34a2f122a --- /dev/null +++ b/man3p/msync.3p @@ -0,0 +1,139 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MSYNC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" msync +.SH NAME +msync \- synchronize memory with physical storage +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int msync(void *\fP\fIaddr\fP\fB, size_t\fP \fIlen\fP\fB, int\fP \fIflags\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImsync\fP() function shall write all modified data to permanent +storage locations, if any, in those whole pages +containing any part of the address space of the process starting at +address \fIaddr\fP and continuing for \fIlen\fP bytes. If no +such storage exists, \fImsync\fP() need not have any effect. If requested, +the \fImsync\fP() function shall then invalidate +cached copies of data. +.LP +The implementation shall require that \fIaddr\fP be a multiple of +the page size as returned by \fIsysconf\fP(). +.LP +For mappings to files, the \fImsync\fP() function shall ensure that +all write operations are completed as defined for +synchronized I/O data integrity completion. It is unspecified whether +the implementation also writes out other file attributes. +When the \fImsync\fP() function is called on MAP_PRIVATE mappings, +any modified data shall not be written to the underlying object +and shall not cause such data to be made visible to other processes. +It is unspecified whether data in MAP_PRIVATE mappings has any +permanent storage locations. \ The effect of \fImsync\fP() on a +shared memory object or a typed memory object is unspecified. +The behavior of this function is unspecified if the mapping was not +established by a call to \fImmap\fP(). +.LP +The \fIflags\fP argument is constructed from the bitwise-inclusive +OR of one or more of the following flags defined in the \fI\fP +header: +.TS C +center; l2 l. +\fBSymbolic Constant\fP \fBDescription\fP +MS_ASYNC Perform asynchronous writes. +MS_SYNC Perform synchronous writes. +MS_INVALIDATE Invalidate cached data. +.TE +.LP +When MS_ASYNC is specified, \fImsync\fP() shall return immediately +once all the write operations are initiated or queued for +servicing; when MS_SYNC is specified, \fImsync\fP() shall not return +until all write operations are completed as defined for +synchronized I/O data integrity completion. Either MS_ASYNC or MS_SYNC +is specified, but not both. +.LP +When MS_INVALIDATE is specified, \fImsync\fP() shall invalidate all +cached copies of mapped data that are inconsistent with the +permanent storage locations such that subsequent references shall +obtain data that was consistent with the permanent storage +locations sometime between the call to \fImsync\fP() and the first +subsequent memory reference to the data. +.LP +If \fImsync\fP() causes any write to a file, the file's \fIst_ctime\fP +and \fIst_mtime\fP fields shall be marked for +update. +.SH RETURN VALUE +.LP +Upon successful completion, \fImsync\fP() shall return 0; otherwise, +it shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fImsync\fP() function shall fail if: +.TP 7 +.B EBUSY +Some or all of the addresses in the range starting at \fIaddr\fP and +continuing for \fIlen\fP bytes are locked, and +MS_INVALIDATE is specified. +.TP 7 +.B EINVAL +The value of \fIflags\fP is invalid. +.TP 7 +.B EINVAL +The value of \fIaddr\fP is not a multiple of the page size {PAGESIZE}. +.TP 7 +.B ENOMEM +The addresses in the range starting at \fIaddr\fP and continuing for +\fIlen\fP bytes are outside the range allowed for the +address space of a process or specify one or more pages that are not +mapped. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fImsync\fP() function is only supported if the Memory Mapped +Files option and the Synchronized Input and Output option are +supported, and thus need not be available on all implementations. +.LP +The \fImsync\fP() function should be used by programs that require +a memory object to be in a known state; for example, in +building transaction facilities. +.LP +Normal system activity can cause pages to be written to disk. Therefore, +there are no guarantees that \fImsync\fP() is the only +control over when pages are or are not written to disk. +.SH RATIONALE +.LP +The \fImsync\fP() function writes out data in a mapped region to the +permanent storage for the underlying object. The call to +\fImsync\fP() ensures data integrity of the file. +.LP +After the data is written out, any cached data may be invalidated +if the MS_INVALIDATE flag was specified. This is useful on +systems that do not support read/write consistency. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImmap\fP() , \fIsysconf\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/munlock.3p b/man3p/munlock.3p new file mode 100644 index 000000000..17606082d --- /dev/null +++ b/man3p/munlock.3p @@ -0,0 +1 @@ +.so man3p/mlock.3p diff --git a/man3p/munlockall.3p b/man3p/munlockall.3p new file mode 100644 index 000000000..01891215a --- /dev/null +++ b/man3p/munlockall.3p @@ -0,0 +1 @@ +.so man3p/mlockall.3p diff --git a/man3p/munmap.3p b/man3p/munmap.3p new file mode 100644 index 000000000..d8a1d905c --- /dev/null +++ b/man3p/munmap.3p @@ -0,0 +1,108 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MUNMAP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" munmap +.SH NAME +munmap \- unmap pages of memory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int munmap(void *\fP\fIaddr\fP\fB, size_t\fP \fIlen\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImunmap\fP() function shall remove any mappings for those entire +pages containing any part of the address space of the +process starting at \fIaddr\fP and continuing for \fIlen\fP bytes. +Further references to these pages shall result in the +generation of a SIGSEGV signal to the process. If there are no mappings +in the specified address range, then \fImunmap\fP() has no +effect. +.LP +The implementation shall require that \fIaddr\fP be a multiple of +the page size {PAGESIZE}. +.LP +If a mapping to be removed was private, any modifications made in +this address range shall be discarded. +.LP +Any memory locks (see \fImlock\fP() and \fImlockall\fP() ) associated +with +this address range shall be removed, as if by an appropriate call +to \fImunlock\fP(). +.LP +If a mapping removed from a typed memory object causes the corresponding +address range of the memory pool to be inaccessible by any +process in the system except through allocatable mappings (that is, +mappings of typed memory objects opened with the +POSIX_TYPED_MEM_MAP_ALLOCATABLE flag), then that range of the memory +pool shall become deallocated and may become available to +satisfy future typed memory allocation requests. +.LP +A mapping removed from a typed memory object opened with the POSIX_TYPED_MEM_MAP_ALLOCATABLE +flag shall not affect in any way +the availability of that typed memory for allocation. +.LP +The behavior of this function is unspecified if the mapping was not +established by a call to \fImmap\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, \fImunmap\fP() shall return 0; otherwise, +it shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fImunmap\fP() function shall fail if: +.TP 7 +.B EINVAL +Addresses in the range [\fIaddr\fP,\fIaddr\fP+\fIlen\fP) are outside +the valid range for the address space of a +process. +.TP 7 +.B EINVAL +The \fIlen\fP argument is 0. +.TP 7 +.B EINVAL +The \fIaddr\fP argument is not a multiple of the page size as returned +by \fIsysconf\fP(). +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fImunmap\fP() function is only supported if the Memory Mapped +Files option or the Shared Memory Objects option is +supported. +.SH RATIONALE +.LP +The \fImunmap\fP() function corresponds to SVR4, just as the \fImmap\fP() +function +does. +.LP +It is possible that an application has applied process memory locking +to a region that contains shared memory. If this has +occurred, the \fImunmap\fP() call ignores those locks and, if necessary, +causes those locks to be removed. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImlock\fP() , \fImlockall\fP() , \fImmap\fP() +, \fIposix_typed_mem_open\fP() , \fIsysconf\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/nan.3p b/man3p/nan.3p new file mode 100644 index 000000000..f2ce7bf00 --- /dev/null +++ b/man3p/nan.3p @@ -0,0 +1,92 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "NAN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" nan +.SH NAME +nan, nanf, nanl \- return quiet NaN +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double nan(const char *\fP\fItagp\fP\fB); +.br +float nanf(const char *\fP\fItagp\fP\fB); +.br +long double nanl(const char *\fP\fItagp\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The function call \fInan\fP("\fIn-char-sequence\fP") shall be equivalent +to: +.sp +.RS +.nf + +\fBstrtod("NAN(\fP\fIn-char-sequence\fP\fB)", (char **) NULL); +\fP +.fi +.RE +.LP +The function call \fInan\fP("") shall be equivalent to: +.sp +.RS +.nf + +\fBstrtod("NAN()", (char **) NULL) +\fP +.fi +.RE +.LP +If \fItagp\fP does not point to an \fIn\fP- \fBchar\fP sequence or +an empty string, the function call shall be equivalent +to: +.sp +.RS +.nf + +\fBstrtod("NAN", (char **) NULL) +\fP +.fi +.RE +.LP +Function calls to \fInanf\fP() and \fInanl\fP() are equivalent to +the corresponding function calls to \fIstrtof\fP() and \fIstrtold\fP(). +.SH RETURN VALUE +.LP +These functions shall return a quiet NaN, if available, with content +indicated through \fItagp\fP. +.LP +If the implementation does not support quiet NaNs, these functions +shall return zero. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrtod\fP() , \fIstrtold\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/nanf.3p b/man3p/nanf.3p new file mode 100644 index 000000000..5f97c4cea --- /dev/null +++ b/man3p/nanf.3p @@ -0,0 +1 @@ +.so man3p/nan.3p diff --git a/man3p/nanl.3p b/man3p/nanl.3p new file mode 100644 index 000000000..5f97c4cea --- /dev/null +++ b/man3p/nanl.3p @@ -0,0 +1 @@ +.so man3p/nan.3p diff --git a/man3p/nanosleep.3p b/man3p/nanosleep.3p new file mode 100644 index 000000000..d2fb63aae --- /dev/null +++ b/man3p/nanosleep.3p @@ -0,0 +1,108 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "NANOSLEEP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" nanosleep +.SH NAME +nanosleep \- high resolution sleep (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int nanosleep(const struct timespec *\fP\fIrqtp\fP\fB, struct timespec +*\fP\fIrmtp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fInanosleep\fP() function shall cause the current thread to be +suspended from execution until either the time interval +specified by the \fIrqtp\fP argument has elapsed or a signal is delivered +to the calling thread, and its action is to invoke a +signal-catching function or to terminate the process. The suspension +time may be longer than requested because the argument value +is rounded up to an integer multiple of the sleep resolution or because +of the scheduling of other activity by the system. But, +except for the case of being interrupted by a signal, the suspension +time shall not be less than the time specified by \fIrqtp\fP, +as measured by the system clock CLOCK_REALTIME. +.LP +The use of the \fInanosleep\fP() function has no effect on the action +or blockage of any signal. +.SH RETURN VALUE +.LP +If the \fInanosleep\fP() function returns because the requested time +has elapsed, its return value shall be zero. +.LP +If the \fInanosleep\fP() function returns because it has been interrupted +by a signal, it shall return a value of -1 and set +\fIerrno\fP to indicate the interruption. If the \fIrmtp\fP argument +is non-NULL, the \fBtimespec\fP structure referenced by it +is updated to contain the amount of time remaining in the interval +(the requested time minus the time actually slept). If the +\fIrmtp\fP argument is NULL, the remaining time is not returned. +.LP +If \fInanosleep\fP() fails, it shall return a value of -1 and set +\fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fInanosleep\fP() function shall fail if: +.TP 7 +.B EINTR +The \fInanosleep\fP() function was interrupted by a signal. +.TP 7 +.B EINVAL +The \fIrqtp\fP argument specified a nanosecond value less than zero +or greater than or equal to 1000 million. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +It is common to suspend execution of a process for an interval in +order to poll the status of a non-interrupting function. A +large number of actual needs can be met with a simple extension to +\fIsleep\fP() that +provides finer resolution. +.LP +In the POSIX.1-1990 standard and SVR4, it is possible to implement +such a routine, but the frequency of wakeup is limited by the +resolution of the \fIalarm\fP() and \fIsleep\fP() +functions. In 4.3 BSD, it is possible to write such a routine using +no static storage and reserving no system facilities. Although +it is possible to write a function with similar functionality to \fIsleep\fP() +using the +remainder of the \fItimer_*\fP() functions, such a function requires +the use of signals +and the reservation of some signal number. This volume of IEEE\ Std\ 1003.1-2001 +requires that \fInanosleep\fP() be +non-intrusive of the signals function. +.LP +The \fInanosleep\fP() function shall return a value of 0 on success +and -1 on failure or if interrupted. This latter case is +different from \fIsleep\fP(). This was done because the remaining +time is returned via an +argument structure pointer, \fIrmtp\fP, instead of as the return value. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsleep\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/nearbyint.3p b/man3p/nearbyint.3p new file mode 100644 index 000000000..f8ec14191 --- /dev/null +++ b/man3p/nearbyint.3p @@ -0,0 +1,90 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "NEARBYINT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" nearbyint +.SH NAME +nearbyint, nearbyintf, nearbyintl \- floating-point rounding functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double nearbyint(double\fP \fIx\fP\fB); +.br +float nearbyintf(float\fP \fIx\fP\fB); +.br +long double nearbyintl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall round their argument to an integer value in +floating-point format, using the current rounding direction +and without raising the inexact floating-point exception. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the rounded +integer value. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, \(+-0 shall be returned. +.LP +If \fIx\fP is \(+-Inf, \fIx\fP shall be returned. +.LP +If the correct value would cause overflow, a range error shall occur +and \fInearbyint\fP(), \fInearbyintf\fP(), and +\fInearbyintl\fP() shall return the value of the macro \(+-HUGE_VAL, +\(+-HUGE_VALF, and \(+-HUGE_VALL (with the same +sign as \fIx\fP), respectively. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Range\ Error +The result would cause an overflow. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of +Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/nearbyintf.3p b/man3p/nearbyintf.3p new file mode 100644 index 000000000..a6ae113ce --- /dev/null +++ b/man3p/nearbyintf.3p @@ -0,0 +1 @@ +.so man3p/nearbyint.3p diff --git a/man3p/nearbyintl.3p b/man3p/nearbyintl.3p new file mode 100644 index 000000000..a6ae113ce --- /dev/null +++ b/man3p/nearbyintl.3p @@ -0,0 +1 @@ +.so man3p/nearbyint.3p diff --git a/man3p/nextafter.3p b/man3p/nextafter.3p new file mode 100644 index 000000000..881b28dd1 --- /dev/null +++ b/man3p/nextafter.3p @@ -0,0 +1,123 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "NEXTAFTER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" nextafter +.SH NAME +nextafter, nextafterf, nextafterl, nexttoward, nexttowardf, nexttowardl +\- next representable floating-point +number +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double nextafter(double\fP \fIx\fP\fB, double\fP \fIy\fP\fB); +.br +float nextafterf(float\fP \fIx\fP\fB, float\fP \fIy\fP\fB); +.br +long double nextafterl(long double\fP \fIx\fP\fB, long double\fP \fIy\fP\fB); +.br +double nexttoward(double\fP \fIx\fP\fB, long double\fP \fIy\fP\fB); +.br +float nexttowardf(float\fP \fIx\fP\fB, long double\fP \fIy\fP\fB); +.br +long double nexttowardl(long double\fP \fIx\fP\fB, long double\fP +\fIy\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fInextafter\fP(), \fInextafterf\fP(), and \fInextafterl\fP() +functions shall compute the next representable +floating-point value following \fIx\fP in the direction of \fIy\fP. +Thus, if \fIy\fP is less than \fIx\fP, \fInextafter\fP() +shall return the largest representable floating-point number less +than \fIx\fP. The \fInextafter\fP(), \fInextafterf\fP(), and +\fInextafterl\fP() functions shall return \fIy\fP if \fIx\fP equals +\fIy\fP. +.LP +The \fInexttoward\fP(), \fInexttowardf\fP(), and \fInexttowardl\fP() +functions shall be equivalent to the corresponding +\fInextafter\fP() functions, except that the second parameter shall +have type \fBlong double\fP and the functions shall return +\fIy\fP converted to the type of the function if \fIx\fP equals \fIy\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the next +representable floating-point value following \fIx\fP in the +direction of \fIy\fP. +.LP +If \fIx\fP== \fIy\fP, \fIy\fP (of the type \fIx\fP) shall be returned. +.LP +If \fIx\fP is finite and the correct function value would overflow, +a range error shall occur and \(+-HUGE_VAL, +\(+-HUGE_VALF, and \(+-HUGE_VALL (with the same sign as \fIx\fP) shall +be returned as appropriate for the return type of +the function. +.LP +If +\fIx\fP or \fIy\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP!= \fIy\fP and the correct function value is subnormal, +zero, or underflows, a range error shall occur, and either +the correct function value (if representable) or 0.0 shall be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Range\ Error +The correct value overflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be +raised. +.TP 7 +Range\ Error +The correct value is subnormal or underflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of +Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/nextafterf.3p b/man3p/nextafterf.3p new file mode 100644 index 000000000..2c0c1d72b --- /dev/null +++ b/man3p/nextafterf.3p @@ -0,0 +1 @@ +.so man3p/nextafter.3p diff --git a/man3p/nextafterl.3p b/man3p/nextafterl.3p new file mode 100644 index 000000000..2c0c1d72b --- /dev/null +++ b/man3p/nextafterl.3p @@ -0,0 +1 @@ +.so man3p/nextafter.3p diff --git a/man3p/nexttoward.3p b/man3p/nexttoward.3p new file mode 100644 index 000000000..2c0c1d72b --- /dev/null +++ b/man3p/nexttoward.3p @@ -0,0 +1 @@ +.so man3p/nextafter.3p diff --git a/man3p/nexttowardf.3p b/man3p/nexttowardf.3p new file mode 100644 index 000000000..2c0c1d72b --- /dev/null +++ b/man3p/nexttowardf.3p @@ -0,0 +1 @@ +.so man3p/nextafter.3p diff --git a/man3p/nexttowardl.3p b/man3p/nexttowardl.3p new file mode 100644 index 000000000..2c0c1d72b --- /dev/null +++ b/man3p/nexttowardl.3p @@ -0,0 +1 @@ +.so man3p/nextafter.3p diff --git a/man3p/nftw.3p b/man3p/nftw.3p new file mode 100644 index 000000000..6277a8824 --- /dev/null +++ b/man3p/nftw.3p @@ -0,0 +1,253 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "NFTW" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" nftw +.SH NAME +nftw \- walk a file tree +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int nftw(const char *\fP\fIpath\fP\fB, int (*\fP\fIfn\fP\fB)(const +char *, +.br +\ \ \ \ \ \ const struct stat *, int, struct FTW *), int\fP \fIdepth\fP\fB, +int\fP +\fIflags\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fInftw\fP() function shall recursively descend the directory +hierarchy rooted in \fIpath\fP. The \fInftw\fP() function +has a similar effect to \fIftw\fP() except that it takes an additional +argument \fIflags\fP, +which is a bitwise-inclusive OR of zero or more of the following flags: +.TP 7 +FTW_CHDIR +If set, \fInftw\fP() shall change the current working directory to +each directory as it reports files in that directory. If +clear, \fInftw\fP() shall not change the current working directory. +.TP 7 +FTW_DEPTH +If set, \fInftw\fP() shall report all files in a directory before +reporting the directory itself. If clear, \fInftw\fP() +shall report any directory before reporting the files in that directory. +.TP 7 +FTW_MOUNT +If set, \fInftw\fP() shall only report files in the same file system +as \fIpath\fP. If clear, \fInftw\fP() shall report all +files encountered during the walk. +.TP 7 +FTW_PHYS +If set, \fInftw\fP() shall perform a physical walk and shall not follow +symbolic links. +.sp +.LP +If FTW_PHYS is clear and FTW_DEPTH is set, \fInftw\fP() shall follow +links instead of reporting them, but shall not report any +directory that would be a descendant of itself. If FTW_PHYS is clear +and FTW_DEPTH is clear, \fInftw\fP() shall follow links +instead of reporting them, but shall not report the contents of any +directory that would be a descendant of itself. +.LP +At each file it encounters, \fInftw\fP() shall call the user-supplied +function \fIfn\fP with four arguments: +.IP " *" 3 +The first argument is the pathname of the object. +.LP +.IP " *" 3 +The second argument is a pointer to the \fBstat\fP buffer containing +information on the object. +.LP +.IP " *" 3 +The third argument is an integer giving additional information. Its +value is one of the following: +.TP 7 +FTW_F +.RS +The object is a file. +.RE +.TP 7 +FTW_D +.RS +The object is a directory. +.RE +.TP 7 +FTW_DP +.RS +The object is a directory and subdirectories have been visited. (This +condition shall only occur if the FTW_DEPTH flag is +included in \fIflags\fP.) +.RE +.TP 7 +FTW_SL +.RS +The object is a symbolic link. (This condition shall only occur if +the FTW_PHYS flag is included in \fIflags\fP.) +.RE +.TP 7 +FTW_SLN +.RS +The object is a symbolic link that does not name an existing file. +(This condition shall only occur if the FTW_PHYS flag is not +included in \fIflags\fP.) +.RE +.TP 7 +FTW_DNR +.RS +The object is a directory that cannot be read. The \fIfn\fP function +shall not be called for any of its descendants. +.RE +.TP 7 +FTW_NS +.RS +The \fIstat\fP() function failed on the object because of lack of +appropriate permission. +The \fBstat\fP buffer passed to \fIfn\fP is undefined. Failure of +\fIstat\fP() for any +other reason is considered an error and \fInftw\fP() shall return +-1. +.RE +.sp +.LP +.IP " *" 3 +The fourth argument is a pointer to an \fBFTW\fP structure. The value +of \fBbase\fP is the offset of the object's filename in +the pathname passed as the first argument to \fIfn\fP. The value of +\fBlevel\fP indicates depth relative to the root of the walk, +where the root level is 0. +.LP +.LP +The results are unspecified if the application-supplied \fIfn\fP function +does not preserve the current working directory. +.LP +The argument \fIdepth\fP sets the maximum number of file descriptors +that shall be used by \fInftw\fP() while traversing the +file tree. At most one file descriptor shall be used for each directory +level. +.LP +The \fInftw\fP() function need not be reentrant. A function that is +not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +The \fInftw\fP() function shall continue until the first of the following +conditions occurs: +.IP " *" 3 +An invocation of \fIfn\fP shall return a non-zero value, in which +case \fInftw\fP() shall return that value. +.LP +.IP " *" 3 +The \fInftw\fP() function detects an error other than [EACCES] (see +FTW_DNR and FTW_NS above), in which case \fInftw\fP() +shall return -1 and set \fIerrno\fP to indicate the error. +.LP +.IP " *" 3 +The tree is exhausted, in which case \fInftw\fP() shall return 0. +.LP +.SH ERRORS +.LP +The \fInftw\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied for any component of \fIpath\fP or read +permission is denied for \fIpath\fP, or \fIfn\fP returns +-1 and does not reset \fIerrno\fP. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of \fIpath\fP is not a directory. +.TP 7 +.B EOVERFLOW +A field in the \fBstat\fP structure cannot be represented correctly +in the current programming environment for one or more +files found in the file hierarchy. +.sp +.LP +The \fInftw\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.TP 7 +.B ENFILE +Too many files are currently open in the system. +.sp +.LP +In addition, \fIerrno\fP may be set if the function pointed to by +\fIfn\fP causes \fIerrno\fP to be set. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The following example walks the \fB/tmp\fP directory and its subdirectories, +calling the \fInftw\fP() function for every +directory entry, to a maximum of 5 levels deep. +.sp +.RS +.nf + +\fB#include +\&... +int nftwfunc(const char *, const struct stat *, int, struct FTW *); +.sp + +int nftwfunc(const char *filename, const struct stat *statptr, + int fileflags, struct FTW *pfwt) +{ + return 0; +} +\&... +char *startpath = "/tmp"; +int depth = 5; +int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT; +int ret; +.sp + +ret = nftw(startpath, nftwfunc, depth, flags); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIlstat\fP() , \fIopendir\fP() , \fIreaddir\fP() , \fIstat\fP() , +the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/nice.3p b/man3p/nice.3p new file mode 100644 index 000000000..ff8bac615 --- /dev/null +++ b/man3p/nice.3p @@ -0,0 +1,97 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "NICE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" nice +.SH NAME +nice \- change the nice value of a process +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int nice(int\fP \fIincr\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fInice\fP() function shall add the value of \fIincr\fP to the +nice value of the calling process. A process' nice value is +a non-negative number for which a more positive value shall result +in less favorable scheduling. +.LP +A maximum nice value of 2*{NZERO}-1 and a minimum nice value of 0 +shall be imposed by the system. Requests for values above or +below these limits shall result in the nice value being set to the +corresponding limit. Only a process with appropriate privileges +can lower the nice value. +.LP +Calling the \fInice\fP() function has no effect on the priority of +processes or threads with policy SCHED_FIFO or SCHED_RR. The +effect on processes or threads with other scheduling policies is implementation-defined. +.LP +The nice value set with \fInice\fP() shall be applied to the process. +If the process is multi-threaded, the nice value shall +affect all system scope threads in the process. +.LP +As -1 is a permissible return value in a successful situation, an +application wishing to check for error situations should set +\fIerrno\fP to 0, then call \fInice\fP(), and if it returns -1, check +to see whether \fIerrno\fP is non-zero. +.SH RETURN VALUE +.LP +Upon successful completion, \fInice\fP() shall return the new nice +value -{NZERO}. Otherwise, -1 shall be returned, the +process' nice value shall not be changed, and \fIerrno\fP shall be +set to indicate the error. +.SH ERRORS +.LP +The \fInice\fP() function shall fail if: +.TP 7 +.B EPERM +The \fIincr\fP argument is negative and the calling process does not +have appropriate privileges. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Changing the Nice Value +.LP +The following example adds the value of the \fIincr\fP argument, -20, +to the nice value of the calling process. +.sp +.RS +.nf + +\fB#include +\&... +int incr = -20; +int ret; +.sp + +ret = nice(incr); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetpriority\fP() , \fIsetpriority\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/nl_langinfo.3p b/man3p/nl_langinfo.3p new file mode 100644 index 000000000..483617109 --- /dev/null +++ b/man3p/nl_langinfo.3p @@ -0,0 +1,102 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "NL_LANGINFO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" nl_langinfo +.SH NAME +nl_langinfo \- language information +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *nl_langinfo(nl_item\fP \fIitem\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fInl_langinfo\fP() function shall return a pointer to a string +containing information relevant to the particular language +or cultural area defined in the program's locale (see \fI\fP). +The +manifest constant names and values of \fIitem\fP are defined in \fI\fP. +For example: +.sp +.RS +.nf + +\fBnl_langinfo(ABDAY_1) +\fP +.fi +.RE +.LP +would return a pointer to the string \fB"Dom"\fP if the identified +language was Portuguese, and \fB"Sun"\fP if the +identified language was English. +.LP +Calls to \fIsetlocale\fP() with a category corresponding to the category +of +\fIitem\fP (see \fI\fP), or to the category \fILC_ALL +,\fP may +overwrite the array pointed to by the return value. +.LP +The \fInl_langinfo\fP() function need not be reentrant. A function +that is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +In a locale where \fIlanginfo\fP data is not defined, \fInl_langinfo\fP() +shall return a pointer to the corresponding string +in the POSIX locale. In all locales, \fInl_langinfo\fP() shall return +a pointer to an empty string if \fIitem\fP contains an +invalid setting. +.LP +This pointer may point to static data that may be overwritten on the +next call. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Getting Date and Time Formatting Information +.LP +The following example returns a pointer to a string containing date +and time formatting information, as defined in the +\fILC_TIME\fP category of the current locale. +.sp +.RS +.nf + +\fB#include +#include +\&... +strftime(datestring, sizeof(datestring), nl_langinfo(D_T_FMT), tm); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The array pointed to by the return value should not be modified by +the program, but may be modified by further calls to +\fInl_langinfo\fP(). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsetlocale\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, Locale, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/nrand48.3p b/man3p/nrand48.3p new file mode 100644 index 000000000..a71d5ed19 --- /dev/null +++ b/man3p/nrand48.3p @@ -0,0 +1 @@ +.so man3p/drand48.3p diff --git a/man3p/ntohl.3p b/man3p/ntohl.3p new file mode 100644 index 000000000..6bb3f2de9 --- /dev/null +++ b/man3p/ntohl.3p @@ -0,0 +1 @@ +.so man3p/htonl.3p diff --git a/man3p/ntohs.3p b/man3p/ntohs.3p new file mode 100644 index 000000000..6bb3f2de9 --- /dev/null +++ b/man3p/ntohs.3p @@ -0,0 +1 @@ +.so man3p/htonl.3p diff --git a/man3p/open.3p b/man3p/open.3p new file mode 100644 index 000000000..3ba1e40f8 --- /dev/null +++ b/man3p/open.3p @@ -0,0 +1,494 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "OPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" open +.SH NAME +open \- open a file +.SH SYNOPSIS +.LP +\fB#include \fP +\fB +.br +#include +.br +.sp +int open(const char *\fP\fIpath\fP\fB, int\fP \fIoflag\fP\fB, ... +); +.br +\fP +.SH DESCRIPTION +.LP +The \fIopen\fP() function shall establish the connection between a +file and a file descriptor. It shall create an open file +description that refers to a file and a file descriptor that refers +to that open file description. The file descriptor is used by +other I/O functions to refer to that file. The \fIpath\fP argument +points to a pathname naming the file. +.LP +The \fIopen\fP() function shall return a file descriptor for the named +file that is the lowest file descriptor not currently +open for that process. The open file description is new, and therefore +the file descriptor shall not share it with any other +process in the system. The FD_CLOEXEC file descriptor flag associated +with the new file descriptor shall be cleared. +.LP +The file offset used to mark the current position within the file +shall be set to the beginning of the file. +.LP +The file status flags and file access modes of the open file description +shall be set according to the value of +\fIoflag\fP. +.LP +Values for \fIoflag\fP are constructed by a bitwise-inclusive OR of +flags from the following list, defined in \fI\fP. Applications +shall specify exactly one of the first three values (file +access modes) below in the value of \fIoflag\fP: +.TP 7 +O_RDONLY +Open for reading only. +.TP 7 +O_WRONLY +Open for writing only. +.TP 7 +O_RDWR +Open for reading and writing. The result is undefined if this flag +is applied to a FIFO. +.sp +.LP +Any combination of the following may be used: +.TP 7 +O_APPEND +If set, the file offset shall be set to the end of the file prior +to each write. +.TP 7 +O_CREAT +If the file exists, this flag has no effect except as noted under +O_EXCL below. Otherwise, the file shall be created; the user +ID of the file shall be set to the effective user ID of the process; +the group ID of the file shall be set to the group ID of the +file's parent directory or to the effective group ID of the process; +and the access permission bits (see \fI\fP) of the file +mode shall be set to the value of the third argument taken +as type \fBmode_t\fP modified as follows: a bitwise AND is performed +on the file-mode bits and the corresponding bits in the +complement of the process' file mode creation mask. Thus, all bits +in the file mode whose corresponding bit in the file mode +creation mask is set are cleared. When bits other than the file permission +bits are set, the effect is unspecified. The third +argument does not affect whether the file is open for reading, writing, +or for both. Implementations shall provide a way to +initialize the file's group ID to the group ID of the parent directory. +Implementations may, but need not, provide an +implementation-defined way to initialize the file's group ID to the +effective group ID of the calling process. +.TP 7 +O_DSYNC +Write I/O operations on the file descriptor shall complete as defined +by synchronized I/O data integrity completion. +.TP 7 +O_EXCL +If O_CREAT and O_EXCL are set, \fIopen\fP() shall fail if the file +exists. The check for the existence of the file and the +creation of the file if it does not exist shall be atomic with respect +to other threads executing \fIopen\fP() naming the same +filename in the same directory with O_EXCL and O_CREAT set. If O_EXCL +and O_CREAT are set, and \fIpath\fP names a symbolic link, +\fIopen\fP() shall fail and set \fIerrno\fP to [EEXIST], regardless +of the contents of the symbolic link. If O_EXCL is set and +O_CREAT is not set, the result is undefined. +.TP 7 +O_NOCTTY +If set and \fIpath\fP identifies a terminal device, \fIopen\fP() shall +not cause the terminal device to become the +controlling terminal for the process. +.TP 7 +O_NONBLOCK +When opening a FIFO with O_RDONLY or O_WRONLY set: +.RS +.IP " *" 3 +If O_NONBLOCK is set, an \fIopen\fP() for reading-only shall return +without delay. An \fIopen\fP() for writing-only shall +return an error if no process currently has the file open for reading. +.LP +.IP " *" 3 +If O_NONBLOCK is clear, an \fIopen\fP() for reading-only shall block +the calling thread until a thread opens the file for +writing. An \fIopen\fP() for writing-only shall block the calling +thread until a thread opens the file for reading. +.LP +.RE +.LP +When opening a block special or character special file that supports +non-blocking opens: +.RS +.IP " *" 3 +If O_NONBLOCK is set, the \fIopen\fP() function shall return without +blocking for the device to be ready or available. +Subsequent behavior of the device is device-specific. +.LP +.IP " *" 3 +If O_NONBLOCK is clear, the \fIopen\fP() function shall block the +calling thread until the device is ready or available before +returning. +.LP +.RE +.LP +Otherwise, the behavior of O_NONBLOCK is unspecified. +.TP 7 +O_RSYNC +Read I/O operations on the file descriptor shall complete at the same +level of integrity as specified by the O_DSYNC and O_SYNC +flags. If both O_DSYNC and O_RSYNC are set in \fIoflag\fP, all I/O +operations on the file descriptor shall complete as defined by +synchronized I/O data integrity completion. If both O_SYNC and O_RSYNC +are set in flags, all I/O operations on the file descriptor +shall complete as defined by synchronized I/O file integrity completion. +.TP 7 +O_SYNC +Write I/O operations on the file descriptor shall complete as defined +by synchronized I/O file integrity completion. +.TP 7 +O_TRUNC +If the file exists and is a regular file, and the file is successfully +opened O_RDWR or O_WRONLY, its length shall be truncated +to 0, and the mode and owner shall be unchanged. It shall have no +effect on FIFO special files or terminal device files. Its effect +on other file types is implementation-defined. The result of using +O_TRUNC with O_RDONLY is undefined. +.sp +.LP +If O_CREAT is set and the file did not previously exist, upon successful +completion, \fIopen\fP() shall mark for update the +\fIst_atime,\fP \fIst_ctime\fP, and \fIst_mtime\fP fields of the file +and the \fIst_ctime\fP and \fIst_mtime\fP fields of the +parent directory. +.LP +If O_TRUNC is set and the file did previously exist, upon successful +completion, \fIopen\fP() shall mark for update the +\fIst_ctime\fP and \fIst_mtime\fP fields of the file. +.LP +If both the O_SYNC and O_DSYNC flags are set, the effect is as if +only the O_SYNC flag was set. +.LP +If \fIpath\fP refers to a STREAMS file, \fIoflag\fP may be constructed +from O_NONBLOCK OR'ed with either O_RDONLY, O_WRONLY, or +O_RDWR. Other flag values are not applicable to STREAMS devices and +shall have no effect on them. The value O_NONBLOCK affects the +operation of STREAMS drivers and certain functions applied to file +descriptors associated with STREAMS files. For STREAMS drivers, +the implementation of O_NONBLOCK is device-specific. +.LP +If \fIpath\fP names the master side of a pseudo-terminal device, then +it is unspecified whether \fIopen\fP() locks the slave side +so that it cannot be opened. Conforming applications shall call \fIunlockpt\fP() +before +opening the slave side. +.LP +The largest value that can be represented correctly in an object of +type \fBoff_t\fP shall be established as the offset maximum +in the open file description. +.SH RETURN VALUE +.LP +Upon successful completion, the function shall open the file and return +a non-negative integer representing the lowest numbered +unused file descriptor. Otherwise, -1 shall be returned and \fIerrno\fP +set to indicate the error. No files shall be created or +modified if the function returns -1. +.SH ERRORS +.LP +The \fIopen\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied on a component of the path prefix, or +the file exists and the permissions specified by \fIoflag\fP +are denied, or the file does not exist and write permission is denied +for the parent directory of the file to be created, or +O_TRUNC is specified and write permission is denied. +.TP 7 +.B EEXIST +O_CREAT and O_EXCL are set, and the named file exists. +.TP 7 +.B EINTR +A signal was caught during \fIopen\fP(). +.TP 7 +.B EINVAL +The implementation does not support synchronized I/O for this file. +.TP 7 +.B EIO +The \fIpath\fP argument names a STREAMS file and a hangup or error +occurred during the \fIopen\fP(). +.TP 7 +.B EISDIR +The named file is a directory and \fIoflag\fP includes O_WRONLY or +O_RDWR. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENFILE +The maximum allowable number of files is currently open in the system. +.TP 7 +.B ENOENT +O_CREAT is not set and the named file does not exist; or O_CREAT is +set and either the path prefix does not exist or the +\fIpath\fP argument points to an empty string. +.TP 7 +.B ENOSR +The \fIpath\fP argument names a STREAMS-based file and the system +is unable to allocate a STREAM. +.TP 7 +.B ENOSPC +The directory or file system that would contain the new file cannot +be expanded, the file does not exist, and O_CREAT is +specified. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.TP 7 +.B ENXIO +O_NONBLOCK is set, the named file is a FIFO, O_WRONLY is set, and +no process has the file open for reading. +.TP 7 +.B ENXIO +The named file is a character special or block special file, and the +device associated with this special file does not +exist. +.TP 7 +.B EOVERFLOW +The named file is a regular file and the size of the file cannot be +represented correctly in an object of type +\fBoff_t\fP. +.TP 7 +.B EROFS +The named file resides on a read-only file system and either O_WRONLY, +O_RDWR, O_CREAT (if the file does not exist), or O_TRUNC +is set in the \fIoflag\fP argument. +.sp +.LP +The \fIopen\fP() function may fail if: +.TP 7 +.B EAGAIN +The \fIpath\fP argument names the slave side of a pseudo-terminal +device that is locked. +.TP 7 +.B EINVAL +The value of the \fIoflag\fP argument is not valid. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.TP 7 +.B ENOMEM +The \fIpath\fP argument names a STREAMS file and the system is unable +to allocate resources. +.TP 7 +.B ETXTBSY +The file is a pure procedure (shared text) file that is being executed +and \fIoflag\fP is O_WRONLY or O_RDWR. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Opening a File for Writing by the Owner +.LP +The following example opens the file \fB/tmp/file\fP, either by creating +it (if it does not already exist), or by truncating +its length to 0 (if it does exist). In the former case, if the call +creates a new file, the access permission bits in the file mode +of the file are set to permit reading and writing by the owner, and +to permit reading only by group members and others. +.LP +If the call to \fIopen\fP() is successful, the file is opened for +writing. +.sp +.RS +.nf + +\fB#include +\&... +int fd; +mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH; +char *filename = "/tmp/file"; +\&... +fd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, mode); +\&... +\fP +.fi +.RE +.SS Opening a File Using an Existence Check +.LP +The following example uses the \fIopen\fP() function to try to create +the \fBLOCKFILE\fP file and open it for writing. Since +the \fIopen\fP() function specifies the O_EXCL flag, the call fails +if the file already exists. In that case, the program assumes +that someone else is updating the password file and exits. +.sp +.RS +.nf + +\fB#include +#include +#include +.sp + +#define LOCKFILE "/etc/ptmp" +\&... +int pfd; /* Integer for file descriptor returned by open() call. */ +\&... +if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL, + S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1) +{ + fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\\n"); + exit(1); +} +\&... +\fP +.fi +.RE +.SS Opening a File for Writing +.LP +The following example opens a file for writing, creating the file +if it does not already exist. If the file does exist, the +system truncates the file to zero bytes. +.sp +.RS +.nf + +\fB#include +#include +#include +.sp + +#define LOCKFILE "/etc/ptmp" +\&... +int pfd; +char filename[PATH_MAX+1]; +\&... +if ((pfd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, + S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1) +{ + perror("Cannot open output file\\n"); exit(1); +} +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Except as specified in this volume of IEEE\ Std\ 1003.1-2001, the +flags allowed in \fIoflag\fP are not +mutually-exclusive and any number of them may be used simultaneously. +.LP +Some implementations permit opening FIFOs with O_RDWR. Since FIFOs +could be implemented in other ways, and since two file +descriptors can be used to the same effect, this possibility is left +as undefined. +.LP +See \fIgetgroups\fP() about the group of a newly created file. +.LP +The use of \fIopen\fP() to create a regular file is preferable to +the use of \fIcreat\fP(), because the latter is redundant and included +only for historical reasons. +.LP +The use of the O_TRUNC flag on FIFOs and directories (pipes cannot +be \fIopen\fP()-ed) must be permissible without unexpected +side effects (for example, \fIcreat\fP() on a FIFO must not remove +data). Since terminal +special files might have type-ahead data stored in the buffer, O_TRUNC +should not affect their content, particularly if a program +that normally opens a regular file should open the current controlling +terminal instead. Other file types, particularly +implementation-defined ones, are left implementation-defined. +.LP +IEEE\ Std\ 1003.1-2001 permits [EACCES] to be returned for conditions +other than those explicitly listed. +.LP +The O_NOCTTY flag was added to allow applications to avoid unintentionally +acquiring a controlling terminal as a side effect of +opening a terminal file. This volume of IEEE\ Std\ 1003.1-2001 does +not specify how a controlling terminal is acquired, but +it allows an implementation to provide this on \fIopen\fP() if the +O_NOCTTY flag is not set and other conditions specified in the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General +Terminal Interface are met. The O_NOCTTY flag is an effective no-op +if the file being opened is not a terminal device. +.LP +In historical implementations the value of O_RDONLY is zero. Because +of that, it is not possible to detect the presence of +O_RDONLY and another option. Future implementations should encode +O_RDONLY and O_WRONLY as bit flags so that: +.sp +.RS +.nf + +\fBO_RDONLY | O_WRONLY == O_RDWR +\fP +.fi +.RE +.LP +In general, the \fIopen\fP() function follows the symbolic link if +\fIpath\fP names a symbolic link. However, the +\fIopen\fP() function, when called with O_CREAT and O_EXCL, is required +to fail with [EEXIST] if \fIpath\fP names an existing +symbolic link, even if the symbolic link refers to a nonexistent file. +This behavior is required so that privileged applications +can create a new file in a known location without the possibility +that a symbolic link might cause the file to be created in a +different location. +.LP +For example, a privileged application that must create a file with +a predictable name in a user-writable directory, such as the +user's home directory, could be compromised if the user creates a +symbolic link with that name that refers to a nonexistent file in +a system directory. If the user can influence the contents of a file, +the user could compromise the system by creating a new system +configuration or spool file that would then be interpreted by the +system. The test for a symbolic link which refers to a +nonexisting file must be atomic with the creation of a new file. +.LP +The POSIX.1-1990 standard required that the group ID of a newly created +file be set to the group ID of its parent directory or +to the effective group ID of the creating process. FIPS 151-2 required +that implementations provide a way to have the group ID be +set to the group ID of the containing directory, but did not prohibit +implementations also supporting a way to set the group ID to +the effective group ID of the creating process. Conforming applications +should not assume which group ID will be used. If it +matters, an application can use \fIchown\fP() to set the group ID +after the file is created, +or determine under what conditions the implementation will set the +desired group ID. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchmod\fP() , \fIclose\fP() , \fIcreat\fP() , \fIdup\fP() , \fIfcntl\fP() +, \fIlseek\fP() , \fIread\fP() , \fIumask\fP() , \fIunlockpt\fP() +, \fIwrite\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/opendir.3p b/man3p/opendir.3p new file mode 100644 index 000000000..b7db3047e --- /dev/null +++ b/man3p/opendir.3p @@ -0,0 +1,157 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "OPENDIR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" opendir +.SH NAME +opendir \- open a directory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +DIR *opendir(const char *\fP\fIdirname\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIopendir\fP() function shall open a directory stream corresponding +to the directory named by the \fIdirname\fP argument. +The directory stream is positioned at the first entry. If the type +\fBDIR\fP is implemented using a file descriptor, applications +shall only be able to open up to a total of {OPEN_MAX} files and directories. +.SH RETURN VALUE +.LP +Upon successful completion, \fIopendir\fP() shall return a pointer +to an object of type \fBDIR\fP. Otherwise, a null pointer +shall be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIopendir\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied for the component of the path prefix of +\fIdirname\fP or read permission is denied for +\fIdirname\fP. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIdirname\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIdirname\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIdirname\fP does not name an existing directory or +\fIdirname\fP is an empty string. +.TP 7 +.B ENOTDIR +A component of \fIdirname\fP is not a directory. +.sp +.LP +The \fIopendir\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIdirname\fP argument. +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIdirname\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.TP 7 +.B ENFILE +Too many files are currently open in the system. +.sp +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Open a Directory Stream +.LP +The following program fragment demonstrates how the \fIopendir\fP() +function is used. +.sp +.RS +.nf + +\fB#include +#include +#include +\&... + DIR *dir; + struct dirent *dp; +\&... + if ((dir = opendir (".")) == NULL) { + perror ("Cannot open ."); + exit (1); + } +.sp + + while ((dp = readdir (dir)) != NULL) { +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIopendir\fP() function should be used in conjunction with \fIreaddir\fP(), +\fIclosedir\fP(), and \fIrewinddir\fP() to +examine the contents of the directory (see the EXAMPLES section in +\fIreaddir\fP() ). This method is +recommended for portability. +.SH RATIONALE +.LP +Based on historical implementations, the rules about file descriptors +apply to directory streams as well. However, this volume +of IEEE\ Std\ 1003.1-2001 does not mandate that the directory stream +be implemented using file descriptors. The description +of \fIclosedir\fP() clarifies that if a file descriptor is used for +the directory stream, +it is mandatory that \fIclosedir\fP() deallocate the file descriptor. +When a file +descriptor is used to implement the directory stream, it behaves as +if the FD_CLOEXEC had been set for the file descriptor. +.LP +The directory entries for dot and dot-dot are optional. This volume +of IEEE\ Std\ 1003.1-2001 does not provide a way to +test \fIa priori\fP for their existence because an application that +is portable must be written to look for (and usually ignore) +those entries. Writing code that presumes that they are the first +two entries does not always work, as many implementations permit +them to be other than the first two entries, with a "normal" entry +preceding them. There is negligible value in providing a way +to determine what the implementation does because the code to deal +with dot and dot-dot must be written in any case and because +such a flag would add to the list of those flags (which has proven +in itself to be objectionable) and might be abused. +.LP +Since the structure and buffer allocation, if any, for directory operations +are defined by the implementation, this volume of +IEEE\ Std\ 1003.1-2001 imposes no portability requirements for erroneous +program constructs, erroneous data, or the use of +unspecified values such as the use or referencing of a \fIdirp\fP +value or a \fBdirent\fP structure value after a directory +stream has been closed or after a \fIfork\fP() or one of the \fIexec\fP +function calls. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclosedir\fP() , \fIlstat\fP() , \fIreaddir\fP() , \fIrewinddir\fP() +, \fIsymlink\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/openlog.3p b/man3p/openlog.3p new file mode 100644 index 000000000..904d7e950 --- /dev/null +++ b/man3p/openlog.3p @@ -0,0 +1 @@ +.so man3p/syslog.3p diff --git a/man3p/optarg.3p b/man3p/optarg.3p new file mode 100644 index 000000000..ca30d067b --- /dev/null +++ b/man3p/optarg.3p @@ -0,0 +1 @@ +.so man3p/getopt.3p diff --git a/man3p/opterr.3p b/man3p/opterr.3p new file mode 100644 index 000000000..ca30d067b --- /dev/null +++ b/man3p/opterr.3p @@ -0,0 +1 @@ +.so man3p/getopt.3p diff --git a/man3p/optind.3p b/man3p/optind.3p new file mode 100644 index 000000000..ca30d067b --- /dev/null +++ b/man3p/optind.3p @@ -0,0 +1 @@ +.so man3p/getopt.3p diff --git a/man3p/optopt.3p b/man3p/optopt.3p new file mode 100644 index 000000000..ca30d067b --- /dev/null +++ b/man3p/optopt.3p @@ -0,0 +1 @@ +.so man3p/getopt.3p diff --git a/man3p/pathconf.3p b/man3p/pathconf.3p new file mode 100644 index 000000000..cfb5be873 --- /dev/null +++ b/man3p/pathconf.3p @@ -0,0 +1,282 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FPATHCONF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fpathconf +.SH NAME +fpathconf, pathconf \- get configurable pathname variables +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +long fpathconf(int\fP \fIfildes\fP\fB, int\fP \fIname\fP\fB); +.br +long pathconf(const char *\fP\fIpath\fP\fB, int\fP \fIname\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfpathconf\fP() and \fIpathconf\fP() functions shall determine +the current value of a configurable limit or option +(\fIvariable\fP) that is associated with a file or directory. +.LP +For \fIpathconf\fP(), the \fIpath\fP argument points to the pathname +of a file or directory. +.LP +For \fIfpathconf\fP(), the \fIfildes\fP argument is an open file descriptor. +.LP +The \fIname\fP argument represents the variable to be queried relative +to that file or directory. Implementations shall support +all of the variables listed in the following table and may support +others. The variables in the following table come from \fI\fP +or \fI\fP and the +symbolic constants, defined in \fI\fP, are the corresponding +values used +for \fIname\fP. +.TS C +center; l2 l2 l. +\fBVariable\fP \fBValue of \fIname\fP\fP \fBRequirements\fP +{FILESIZEBITS} _PC_FILESIZEBITS 3,4 +{LINK_MAX} _PC_LINK_MAX 1 +{MAX_CANON} _PC_MAX_CANON 2 +{MAX_INPUT} _PC_MAX_INPUT 2 +{NAME_MAX} _PC_NAME_MAX 3,4 +{PATH_MAX} _PC_PATH_MAX 4,5 +{PIPE_BUF} _PC_PIPE_BUF 6 +{POSIX_ALLOC_SIZE_MIN} _PC_ALLOC_SIZE_MIN \ +{POSIX_REC_INCR_XFER_SIZE} _PC_REC_INCR_XFER_SIZE \ +{POSIX_REC_MAX_XFER_SIZE} _PC_REC_MAX_XFER_SIZE \ +{POSIX_REC_MIN_XFER_SIZE} _PC_REC_MIN_XFER_SIZE \ +{POSIX_REC_XFER_ALIGN} _PC_REC_XFER_ALIGN \ +{SYMLINK_MAX} _PC_SYMLINK_MAX 4,9 +_POSIX_CHOWN_RESTRICTED _PC_CHOWN_RESTRICTED 7 +_POSIX_NO_TRUNC _PC_NO_TRUNC 3,4 +_POSIX_VDISABLE _PC_VDISABLE 2 +_POSIX_ASYNC_IO _PC_ASYNC_IO 8 +_POSIX_PRIO_IO _PC_PRIO_IO 8 +_POSIX_SYNC_IO _PC_SYNC_IO 8 +.TE +.SS Requirements +.IP " 1." 4 +If \fIpath\fP or \fIfildes\fP refers to a directory, the value returned +shall apply to the directory itself. +.LP +.IP " 2." 4 +If \fIpath\fP or \fIfildes\fP does not refer to a terminal file, it +is unspecified whether an implementation supports an +association of the variable name with the specified file. +.LP +.IP " 3." 4 +If \fIpath\fP or \fIfildes\fP refers to a directory, the value returned +shall apply to filenames within the directory. +.LP +.IP " 4." 4 +If \fIpath\fP or \fIfildes\fP does not refer to a directory, it is +unspecified whether an implementation supports an +association of the variable name with the specified file. +.LP +.IP " 5." 4 +If \fIpath\fP or \fIfildes\fP refers to a directory, the value returned +shall be the maximum length of a relative pathname +when the specified directory is the working directory. +.LP +.IP " 6." 4 +If \fIpath\fP refers to a FIFO, or \fIfildes\fP refers to a pipe or +FIFO, the value returned shall apply to the referenced +object. If \fIpath\fP or \fIfildes\fP refers to a directory, the value +returned shall apply to any FIFO that exists or can be +created within the directory. If \fIpath\fP or \fIfildes\fP refers +to any other type of file, it is unspecified whether an +implementation supports an association of the variable name with the +specified file. +.LP +.IP " 7." 4 +If \fIpath\fP or \fIfildes\fP refers to a directory, the value returned +shall apply to any files, other than directories, that +exist or can be created within the directory. +.LP +.IP " 8." 4 +If \fIpath\fP or \fIfildes\fP refers to a directory, it is unspecified +whether an implementation supports an association of +the variable name with the specified file. +.LP +.IP " 9." 4 +If \fIpath\fP or \fIfildes\fP refers to a directory, the value returned +shall be the maximum length of the string that a +symbolic link in that directory can contain. +.LP +.SH RETURN VALUE +.LP +If \fIname\fP is an invalid value, both \fIpathconf\fP() and \fIfpathconf\fP() +shall return -1 and set \fIerrno\fP to +indicate the error. +.LP +If the variable corresponding to \fIname\fP has no limit for the \fIpath\fP +or file descriptor, both \fIpathconf\fP() and +\fIfpathconf\fP() shall return -1 without changing \fIerrno\fP. If +the implementation needs to use \fIpath\fP to determine the +value of \fIname\fP and the implementation does not support the association +of \fIname\fP with the file specified by \fIpath\fP, +or if the process did not have appropriate privileges to query the +file specified by \fIpath\fP, or \fIpath\fP does not exist, +\fIpathconf\fP() shall return -1 and set \fIerrno\fP to indicate the +error. +.LP +If the implementation needs to use \fIfildes\fP to determine the value +of \fIname\fP and the implementation does not support +the association of \fIname\fP with the file specified by \fIfildes\fP, +or if \fIfildes\fP is an invalid file descriptor, +\fIfpathconf\fP() shall return -1 and set \fIerrno\fP to indicate +the error. +.LP +Otherwise, \fIpathconf\fP() or \fIfpathconf\fP() shall return the +current variable value for the file or directory without +changing \fIerrno\fP. The value returned shall not be more restrictive +than the corresponding value available to the application +when it was compiled with the implementation's \fI\fP or +\fI\fP. +.SH ERRORS +.LP +The \fIpathconf\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of \fIname\fP is not valid. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.sp +.LP +The \fIpathconf\fP() function may fail if: +.TP 7 +.B EACCES +Search permission is denied for a component of the path prefix. +.TP 7 +.B EINVAL +The implementation does not support an association of the variable +\fIname\fP with the specified file. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.sp +.LP +The \fIfpathconf\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of \fIname\fP is not valid. +.sp +.LP +The \fIfpathconf\fP() function may fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B EINVAL +The implementation does not support an association of the variable +\fIname\fP with the specified file. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIpathconf\fP() function was proposed immediately after the \fIsysconf\fP() +function when it was realized that some configurable values may differ +across file system, directory, or device boundaries. +.LP +For example, {NAME_MAX} frequently changes between System V and BSD-based +file systems; System V uses a maximum of 14, BSD 255. +On an implementation that provides both types of file systems, an +application would be forced to limit all pathname components to +14 bytes, as this would be the value specified in \fI\fP +on such a +system. +.LP +Therefore, various useful values can be queried on any pathname or +file descriptor, assuming that the appropriate permissions +are in place. +.LP +The value returned for the variable {PATH_MAX} indicates the longest +relative pathname that could be given if the specified +directory is the process' current working directory. A process may +not always be able to generate a name that long and use it if a +subdirectory in the pathname crosses into a more restrictive file +system. +.LP +The value returned for the variable _POSIX_CHOWN_RESTRICTED also applies +to directories that do not have file systems mounted on +them. The value may change when crossing a mount point, so applications +that need to know should check for each directory. (An even +easier check is to try the \fIchown\fP() function and look for an +error in case it +happens.) +.LP +Unlike the values returned by \fIsysconf\fP(), the pathname-oriented +variables are +potentially more volatile and are not guaranteed to remain constant +throughout the process' lifetime. For example, in between two +calls to \fIpathconf\fP(), the file system in question may have been +unmounted and remounted with different characteristics. +.LP +Also note that most of the errors are optional. If one of the variables +always has the same value on an implementation, the +implementation need not look at \fIpath\fP or \fIfildes\fP to return +that value and is, therefore, not required to detect any of +the errors except the meaning of [EINVAL] that indicates that the +value of \fIname\fP is not valid for that variable. +.LP +If the value of any of the limits is unspecified (logically infinite), +they will not be defined in \fI\fP and the \fIpathconf\fP() +and \fIfpathconf\fP() functions return -1 +without changing \fIerrno\fP. This can be distinguished from the case +of giving an unrecognized \fIname\fP argument because +\fIerrno\fP is set to [EINVAL] in this case. +.LP +Since -1 is a valid return value for the \fIpathconf\fP() and \fIfpathconf\fP() +functions, applications should set +\fIerrno\fP to zero before calling them and check \fIerrno\fP only +if the return value is -1. +.LP +For the case of {SYMLINK_MAX}, since both \fIpathconf\fP() and \fIopen\fP() +follow +symbolic links, there is no way that \fIpath\fP or \fIfildes\fP could +refer to a symbolic link. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIconfstr\fP() , \fIsysconf\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP, the Shell +and Utilities volume of IEEE\ Std\ 1003.1-2001 +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pause.3p b/man3p/pause.3p new file mode 100644 index 000000000..42423181d --- /dev/null +++ b/man3p/pause.3p @@ -0,0 +1,72 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PAUSE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pause +.SH NAME +pause \- suspend the thread until a signal is received +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pause(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fIpause\fP() function shall suspend the calling thread until +delivery of a signal whose action is either to execute a +signal-catching function or to terminate the process. +.LP +If the action is to terminate the process, \fIpause\fP() shall not +return. +.LP +If the action is to execute a signal-catching function, \fIpause\fP() +shall return after the signal-catching function +returns. +.SH RETURN VALUE +.LP +Since \fIpause\fP() suspends thread execution indefinitely unless +interrupted by a signal, there is no successful completion +return value. A value of -1 shall be returned and \fIerrno\fP set +to indicate the error. +.SH ERRORS +.LP +The \fIpause\fP() function shall fail if: +.TP 7 +.B EINTR +A signal is caught by the calling process and control is returned +from the signal-catching function. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Many common uses of \fIpause\fP() have timing windows. The scenario +involves checking a condition related to a signal and, if +the signal has not occurred, calling \fIpause\fP(). When the signal +occurs between the check and the call to \fIpause\fP(), the +process often blocks indefinitely. The \fIsigprocmask\fP() and \fIsigsuspend\fP() +functions can be used to avoid this type of problem. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsigsuspend\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pclose.3p b/man3p/pclose.3p new file mode 100644 index 000000000..dc4c3cd1d --- /dev/null +++ b/man3p/pclose.3p @@ -0,0 +1,168 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PCLOSE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pclose +.SH NAME +pclose \- close a pipe stream to or from a process +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pclose(FILE *\fP\fIstream\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpclose\fP() function shall close a stream that was opened by +\fIpopen\fP(), wait +for the command to terminate, and return the termination status of +the process that was running the command language interpreter. +However, if a call caused the termination status to be unavailable +to \fIpclose\fP(), then \fIpclose\fP() shall return -1 with +\fIerrno\fP set to [ECHILD] to report this situation. This can happen +if the application calls one of the following functions: +.IP " *" 3 +\fIwait\fP() +.LP +.IP " *" 3 +\fIwaitpid\fP() with a \fIpid\fP argument less than or equal to 0 +or equal to the +process ID of the command line interpreter +.LP +.IP " *" 3 +Any other function not defined in this volume of IEEE\ Std\ 1003.1-2001 +that could do one of the above +.LP +.LP +In any case, \fIpclose\fP() shall not return before the child process +created by \fIpopen\fP() has terminated. +.LP +If the command language interpreter cannot be executed, the child +termination status returned by \fIpclose\fP() shall be as if +the command language interpreter terminated using \fIexit\fP(127) +or \fI_exit\fP(127). +.LP +The \fIpclose\fP() function shall not affect the termination status +of any child of the calling process other than the one +created by \fIpopen\fP() for the associated stream. +.LP +If the argument \fIstream\fP to \fIpclose\fP() is not a pointer to +a stream created by \fIpopen\fP(), the result of \fIpclose\fP() is +undefined. +.SH RETURN VALUE +.LP +Upon successful return, \fIpclose\fP() shall return the termination +status of the command language interpreter. Otherwise, +\fIpclose\fP() shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fIpclose\fP() function shall fail if: +.TP 7 +.B ECHILD +The status of the child process could not be obtained, as described +above. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +There is a requirement that \fIpclose\fP() not return before the child +process terminates. This is intended to disallow +implementations that return [EINTR] if a signal is received while +waiting. If \fIpclose\fP() returned before the child terminated, +there would be no way for the application to discover which child +used to be associated with the stream, and it could not do the +cleanup itself. +.LP +If the stream pointed to by \fIstream\fP was not created by \fIpopen\fP(), +historical +implementations of \fIpclose\fP() return -1 without setting \fIerrno\fP. +To avoid requiring \fIpclose\fP() to set \fIerrno\fP +in this case, IEEE\ Std\ 1003.1-2001 makes the behavior unspecified. +An application should not use \fIpclose\fP() to close +any stream that was not created by \fIpopen\fP(). +.LP +Some historical implementations of \fIpclose\fP() either block or +ignore the signals SIGINT, SIGQUIT, and SIGHUP while waiting +for the child process to terminate. Since this behavior is not described +for the \fIpclose\fP() function in +IEEE\ Std\ 1003.1-2001, such implementations are not conforming. Also, +some historical implementations return [EINTR] if a +signal is received, even though the child process has not terminated. +Such implementations are also considered non-conforming. +.LP +Consider, for example, an application that uses: +.sp +.RS +.nf + +\fBpopen("command", "r") +\fP +.fi +.RE +.LP +to start \fIcommand\fP, which is part of the same application. The +parent writes a prompt to its standard output (presumably +the terminal) and then reads from the \fIpopen\fP()ed stream. The +child reads the response +from the user, does some transformation on the response (pathname +expansion, perhaps) and writes the result to its standard output. +The parent process reads the result from the pipe, does something +with it, and prints another prompt. The cycle repeats. Assuming +that both processes do appropriate buffer flushing, this would be +expected to work. +.LP +To conform to IEEE\ Std\ 1003.1-2001, \fIpclose\fP() must use \fIwaitpid\fP(), +or some similar function, instead of \fIwait\fP(). +.LP +The code sample below illustrates how the \fIpclose\fP() function +might be implemented on a system conforming to +IEEE\ Std\ 1003.1-2001. +.sp +.RS +.nf + +\fBint pclose(FILE *stream) +{ + int stat; + pid_t pid; +.sp + + pid = + (void) fclose(stream); + while (waitpid(pid, &stat, 0) == -1) { + if (errno != EINTR){ + stat = -1; + break; + } + } + return(stat); +} +\fP +.fi +.RE +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfork\fP() , \fIpopen\fP() , \fIwaitpid\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/perror.3p b/man3p/perror.3p new file mode 100644 index 000000000..2ec27af61 --- /dev/null +++ b/man3p/perror.3p @@ -0,0 +1,93 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PERROR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" perror +.SH NAME +perror \- write error messages to standard error +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void perror(const char *\fP\fIs\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIperror\fP() function shall map the error number accessed through +the symbol \fIerrno\fP to a language-dependent error +message, which shall be written to the standard error stream as follows: +.IP " *" 3 +First (if \fIs\fP is not a null pointer and the character pointed +to by \fIs\fP is not the null byte), the string pointed to +by \fIs\fP followed by a colon and a . +.LP +.IP " *" 3 +Then an error message string followed by a . +.LP +.LP +The contents of the error message strings shall be the same as those +returned by \fIstrerror\fP() with argument \fIerrno\fP. +.LP +The +\fIperror\fP() function shall mark the file associated with the standard +error stream as having been written (\fIst_ctime\fP, +\fIst_mtime\fP marked for update) at some time between its successful +completion and \fIexit\fP(), \fIabort\fP(), or the completion of \fIfflush\fP() +or \fIfclose\fP() on \fIstderr\fP. +.LP +The \fIperror\fP() function shall not change the orientation of the +standard error stream. +.SH RETURN VALUE +.LP +The \fIperror\fP() function shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Printing an Error Message for a Function +.LP +The following example replaces \fIbufptr\fP with a buffer that is +the necessary size. If an error occurs, the \fIperror\fP() +function prints a message and the program exits. +.sp +.RS +.nf + +\fB#include +#include +\&... +char *bufptr; +size_t szbuf; +\&... +if ((bufptr = malloc(szbuf)) == NULL) { + perror("malloc"); exit(2); +} +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrerror\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pipe.3p b/man3p/pipe.3p new file mode 100644 index 000000000..6c6f889f2 --- /dev/null +++ b/man3p/pipe.3p @@ -0,0 +1,85 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PIPE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pipe +.SH NAME +pipe \- create an interprocess channel +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pipe(int\fP \fIfildes\fP\fB[2]); +.br +\fP +.SH DESCRIPTION +.LP +The \fIpipe\fP() function shall create a pipe and place two file descriptors, +one each into the arguments \fIfildes\fP[0] and +\fIfildes\fP[1], that refer to the open file descriptions for the +read and write ends of the pipe. Their integer values shall be +the two lowest available at the time of the \fIpipe\fP() call. The +O_NONBLOCK and FD_CLOEXEC flags shall be clear on both file +descriptors. (The \fIfcntl\fP() function can be used to set both these +flags.) +.LP +Data can be written to the file descriptor \fIfildes\fP[1] and read +from the file descriptor \fIfildes\fP[0]. A read on the +file descriptor \fIfildes\fP[0] shall access data written to the file +descriptor \fIfildes\fP[1] on a first-in-first-out basis. +It is unspecified whether \fIfildes\fP[0] is also open for writing +and whether \fIfildes\fP[1] is also open for reading. +.LP +A process has the pipe open for reading (correspondingly writing) +if it has a file descriptor open that refers to the read end, +\fIfildes\fP[0] (write end, \fIfildes\fP[1]). +.LP +Upon successful completion, \fIpipe\fP() shall mark for update the +\fIst_atime\fP, \fIst_ctime\fP, and \fIst_mtime\fP fields +of the pipe. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned; otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIpipe\fP() function shall fail if: +.TP 7 +.B EMFILE +More than {OPEN_MAX} minus two file descriptors are already in use +by this process. +.TP 7 +.B ENFILE +The number of simultaneously open files in the system would exceed +a system-imposed limit. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The wording carefully avoids using the verb "to open" in order to +avoid any implication of use of \fIopen\fP(); see also \fIwrite\fP() +\&. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfcntl\fP() , \fIread\fP() , \fIwrite\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/poll.3p b/man3p/poll.3p new file mode 100644 index 000000000..73995e5d3 --- /dev/null +++ b/man3p/poll.3p @@ -0,0 +1,286 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POLL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" poll +.SH NAME +poll \- input/output multiplexing +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int poll(struct pollfd\fP \fIfds\fP\fB[], nfds_t\fP \fInfds\fP\fB, +int\fP \fItimeout\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpoll\fP() function provides applications with a mechanism for +multiplexing input/output over a set of file descriptors. +For each member of the array pointed to by \fIfds\fP, \fIpoll\fP() +shall examine the given file descriptor for the event(s) +specified in \fIevents\fP. The number of \fBpollfd\fP structures in +the \fIfds\fP array is specified by \fInfds\fP. The +\fIpoll\fP() function shall identify those file descriptors on which +an application can read or write data, or on which certain +events have occurred. +.LP +The \fIfds\fP argument specifies the file descriptors to be examined +and the events of interest for each file descriptor. It is +a pointer to an array with one member for each open file descriptor +of interest. The array's members are \fBpollfd\fP structures +within which \fIfd\fP specifies an open file descriptor and \fIevents\fP +and \fIrevents\fP are bitmasks constructed by OR'ing a +combination of the following event flags: +.TP 7 +POLLIN +Data other than high-priority data may be read without blocking. +.LP +For STREAMS, this flag is set in \fIrevents\fP even if the message +is of zero length. This flag shall be equivalent to POLLRDNORM +| POLLRDBAND. +.TP 7 +POLLRDNORM +Normal data may be read without blocking. +.LP +For STREAMS, data on priority band 0 may be read without blocking. +This flag is set in \fIrevents\fP even if the message is of +zero length. +.TP 7 +POLLRDBAND +Priority data may be read without blocking. +.LP +For STREAMS, data on priority bands greater than 0 may be read without +blocking. This flag is set in \fIrevents\fP even if the +message is of zero length. +.TP 7 +POLLPRI +High-priority data may be read without blocking. +.LP +For STREAMS, this flag is set in \fIrevents\fP even if the message +is of zero length. +.TP 7 +POLLOUT +Normal data may be written without blocking. +.LP +For STREAMS, data on priority band 0 may be written without blocking. +.TP 7 +POLLWRNORM +Equivalent to POLLOUT. +.TP 7 +POLLWRBAND +Priority data may be written. +.LP +For STREAMS, data on priority bands greater than 0 may be written +without blocking. If any priority band has been written to on +this STREAM, this event only examines bands that have been written +to at least once. +.TP 7 +POLLERR +An error has occurred on the device or stream. This flag is only valid +in the \fIrevents\fP bitmask; it shall be ignored in +the \fIevents\fP member. +.TP 7 +POLLHUP +The device has been disconnected. This event and POLLOUT are mutually-exclusive; +a stream can never be writable if a hangup has +occurred. However, this event and POLLIN, POLLRDNORM, POLLRDBAND, +or POLLPRI are not mutually-exclusive. This flag is only valid in +the \fIrevents\fP bitmask; it shall be ignored in the \fIevents\fP +member. +.TP 7 +POLLNVAL +The specified \fIfd\fP value is invalid. This flag is only valid in +the \fIrevents\fP member; it shall ignored in the +\fIevents\fP member. +.sp +.LP +The significance and semantics of normal, priority, and high-priority +data are file and device-specific. +.LP +If the value of \fIfd\fP is less than 0, \fIevents\fP shall be ignored, +and \fIrevents\fP shall be set to 0 in that entry on +return from \fIpoll\fP(). +.LP +In each \fBpollfd\fP structure, \fIpoll\fP() shall clear the \fIrevents\fP +member, except that where the application +requested a report on a condition by setting one of the bits of \fIevents\fP +listed above, \fIpoll\fP() shall set the +corresponding bit in \fIrevents\fP if the requested condition is true. +In addition, \fIpoll\fP() shall set the POLLHUP, POLLERR, +and POLLNVAL flag in \fIrevents\fP if the condition is true, even +if the application did not set the corresponding bit in +\fIevents\fP. +.LP +If none of the defined events have occurred on any selected file descriptor, +\fIpoll\fP() shall wait at least \fItimeout\fP +milliseconds for an event to occur on any of the selected file descriptors. +If the value of \fItimeout\fP is 0, \fIpoll\fP() +shall return immediately. If the value of \fItimeout\fP is -1, \fIpoll\fP() +shall block until a requested event occurs or until +the call is interrupted. +.LP +Implementations may place limitations on the granularity of timeout +intervals. If the requested timeout interval requires a +finer granularity than the implementation supports, the actual timeout +interval shall be rounded up to the next supported +value. +.LP +The \fIpoll\fP() function shall not be affected by the O_NONBLOCK +flag. +.LP +The \fIpoll\fP() function shall support regular files, terminal and +pseudo-terminal devices, FIFOs, pipes, sockets and +\ STREAMS-based files. The behavior of \fIpoll\fP() on +elements of \fIfds\fP that refer to other types of file is unspecified. +.LP +Regular files shall always poll TRUE for reading and writing. +.LP +A file descriptor for a socket that is listening for connections shall +indicate that it is ready for reading, once connections +are available. A file descriptor for a socket that is connecting asynchronously +shall indicate that it is ready for writing, once a +connection has been established. +.SH RETURN VALUE +.LP +Upon successful completion, \fIpoll\fP() shall return a non-negative +value. A positive value indicates the total number of file +descriptors that have been selected (that is, file descriptors for +which the \fIrevents\fP member is non-zero). A value of 0 +indicates that the call timed out and no file descriptors have been +selected. Upon failure, \fIpoll\fP() shall return -1 and set +\fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIpoll\fP() function shall fail if: +.TP 7 +.B EAGAIN +The allocation of internal data structures failed but a subsequent +request may succeed. +.TP 7 +.B EINTR +A signal was caught during \fIpoll\fP(). +.TP 7 +.B EINVAL +The \fInfds\fP argument is greater than {OPEN_MAX}, \ or one of +the \fIfd\fP members refers to a STREAM or multiplexer +that is linked (directly or indirectly) downstream from a multiplexer. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Checking for Events on a Stream +.LP +The following example opens a pair of STREAMS devices and then waits +for either one to become writable. This example proceeds as +follows: +.IP " 1." 4 +Sets the \fItimeout\fP parameter to 500 milliseconds. +.LP +.IP " 2." 4 +Opens the STREAMS devices \fB/dev/dev0\fP and \fB/dev/dev1\fP, and +then polls them, specifying POLLOUT and POLLWRBAND as the +events of interest. +.LP +The STREAMS device names \fB/dev/dev0\fP and \fB/dev/dev1\fP are only +examples of how STREAMS devices can be named; STREAMS +naming conventions may vary among systems conforming to the IEEE\ Std\ 1003.1-2001. +.LP +.IP " 3." 4 +Uses the \fIret\fP variable to determine whether an event has occurred +on either of the two STREAMS. The \fIpoll\fP() function +is given 500 milliseconds to wait for an event to occur (if it has +not occurred prior to the \fIpoll\fP() call). +.LP +.IP " 4." 4 +Checks the returned value of \fIret\fP. If a positive value is returned, +one of the following can be done: +.RS +.IP " a." 4 +Priority data can be written to the open STREAM on priority bands +greater than 0, because the POLLWRBAND event occurred on the +open STREAM ( \fIfds\fP[0] or \fIfds\fP[1]). +.LP +.IP " b." 4 +Data can be written to the open STREAM on priority-band 0, because +the POLLOUT event occurred on the open STREAM ( \fIfds\fP[0] +or \fIfds\fP[1]). +.LP +.RE +.LP +.IP " 5." 4 +If the returned value is not a positive value, permission to write +data to the open STREAM (on any priority band) is denied. +.LP +.IP " 6." 4 +If the POLLHUP event occurs on the open STREAM ( \fIfds\fP[0] or \fIfds\fP[1]), +the device on the open STREAM has +disconnected. +.LP +.sp +.RS +.nf + +\fB#include +#include +\&... +struct pollfd fds[2]; +int timeout_msecs = 500; +int ret; + int i; +.sp + +/* Open STREAMS device. */ +fds[0].fd = open("/dev/dev0", ...); +fds[1].fd = open("/dev/dev1", ...); + fds[0].events = POLLOUT | POLLWRBAND; + fds[1].events = POLLOUT | POLLWRBAND; +.sp + +ret = poll(fds, 2, timeout_msecs); +.sp + +if (ret > 0) { + /* An event on one of the fds has occurred. */ + for (i=0; i<2; i++) { + if (fds[i].revents & POLLWRBAND) { + /* Priority data may be written on device number i. */ +\&... + } + if (fds[i].revents & POLLOUT) { + /* Data may be written on device number i. */ +\&... + } + if (fds[i].revents & POLLHUP) { + /* A hangup has occurred on device number i. */ +\&... + } + } +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISTREAMS\fP , \fIgetmsg\fP() , \fIputmsg\fP() , \fIread\fP() , \fIselect\fP() +, \fIwrite\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/popen.3p b/man3p/popen.3p new file mode 100644 index 000000000..984e0c839 --- /dev/null +++ b/man3p/popen.3p @@ -0,0 +1,169 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" popen +.SH NAME +popen \- initiate pipe streams to or from a process +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +FILE *popen(const char *\fP\fIcommand\fP\fB, const char *\fP\fImode\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpopen\fP() function shall execute the command specified by +the string \fIcommand\fP. It shall create a pipe between the +calling program and the executed command, and shall return a pointer +to a stream that can be used to either read from or write to +the pipe. +.LP +The environment of the executed command shall be as if a child process +were created within the \fIpopen\fP() call using the \fIfork\fP() +function, and the child invoked the \fIsh\fP +utility using the call: +.sp +.RS +.nf + +\fBexecl(\fP\fIshell path\fP\fB, "sh", "-c",\fP \fIcommand\fP\fB, (char *)0); +\fP +.fi +.RE +.LP +where \fIshell path\fP is an unspecified pathname for the \fIsh\fP +utility. +.LP +The \fIpopen\fP() function shall ensure that any streams from previous +\fIpopen\fP() calls that remain open in the parent +process are closed in the new child process. +.LP +The \fImode\fP argument to \fIpopen\fP() is a string that specifies +I/O mode: +.IP " 1." 4 +If \fImode\fP is \fIr\fP, when the child process is started, its file +descriptor STDOUT_FILENO shall be the writable end of +the pipe, and the file descriptor \fIfileno\fP(\fIstream\fP) in the +calling process, where \fIstream\fP is the stream pointer +returned by \fIpopen\fP(), shall be the readable end of the pipe. +.LP +.IP " 2." 4 +If \fImode\fP is \fIw\fP, when the child process is started its file +descriptor STDIN_FILENO shall be the readable end of the +pipe, and the file descriptor \fIfileno\fP(\fIstream\fP) in the calling +process, where \fIstream\fP is the stream pointer +returned by \fIpopen\fP(), shall be the writable end of the pipe. +.LP +.IP " 3." 4 +If \fImode\fP is any other value, the result is undefined. +.LP +.LP +After \fIpopen\fP(), both the parent and the child process shall be +capable of executing independently before either +terminates. +.LP +Pipe streams are byte-oriented. +.SH RETURN VALUE +.LP +Upon successful completion, \fIpopen\fP() shall return a pointer to +an open stream that can be used to read or write to the +pipe. Otherwise, it shall return a null pointer and may set \fIerrno\fP +to indicate the error. +.SH ERRORS +.LP +The \fIpopen\fP() function may fail if: +.TP 7 +.B EMFILE +{FOPEN_MAX} or {STREAM_MAX} streams are currently open in the calling +process. +.TP 7 +.B EINVAL +The \fImode\fP argument is invalid. +.sp +.LP +The \fIpopen\fP() function may also set \fIerrno\fP values as described +by \fIfork\fP() or \fIpipe\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Since open files are shared, a mode \fIr\fP command can be used as +an input filter and a mode \fIw\fP command as an output +filter. +.LP +Buffered reading before opening an input filter may leave the standard +input of that filter mispositioned. Similar problems with +an output filter may be prevented by careful buffer flushing; for +example, with \fIfflush\fP() . +.LP +A stream opened by \fIpopen\fP() should be closed by \fIpclose\fP(). +.LP +The behavior of \fIpopen\fP() is specified for values of \fImode\fP +of \fIr\fP and \fIw\fP. Other modes such as \fIrb\fP +and \fIwb\fP might be supported by specific implementations, but these +would not be portable features. Note that historical +implementations of \fIpopen\fP() only check to see if the first character +of \fImode\fP is \fIr\fP. Thus, a \fImode\fP of +\fIrobert the robot\fP would be treated as \fImode\fP \fIr\fP, and +a \fImode\fP of \fIanything else\fP would be treated as +\fImode\fP \fIw\fP. +.LP +If the application calls \fIwaitpid\fP() or \fIwaitid\fP() with a +\fIpid\fP argument greater than 0, and it still has a stream that +was called +with \fIpopen\fP() open, it must ensure that \fIpid\fP does not refer +to the process started by \fIpopen\fP(). +.LP +To determine whether or not the environment specified in the Shell +and Utilities volume of IEEE\ Std\ 1003.1-2001 is +present, use the function call: +.sp +.RS +.nf + +\fBsysconf(_SC_2_VERSION) +\fP +.fi +.RE +.LP +(See \fIsysconf\fP() ). +.SH RATIONALE +.LP +The \fIpopen\fP() function should not be used by programs that have +set user (or group) ID privileges. The \fIfork\fP() and \fIexec\fP +family of functions (except \fIexeclp\fP() and \fIexecvp\fP()), should +be used +instead. This prevents any unforeseen manipulation of the environment +of the user that could cause execution of commands not +anticipated by the calling program. +.LP +If the original and \fIpopen\fP()ed processes both intend to read +or write or read and write a common file, and either will be +using FILE-type C functions ( \fIfread\fP(), \fIfwrite\fP(), and so +on), the rules for sharing file handles must be observed (see \fIInteraction +of File Descriptors and Standard I/O Streams\fP ). +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpclose\fP() , \fIpipe\fP() , \fIsysconf\fP() +, \fIsystem\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, the Shell and Utilities volume of IEEE\ Std\ 1003.1-2001, +\fIsh\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_fadvise.3p b/man3p/posix_fadvise.3p new file mode 100644 index 000000000..26b6f7ce4 --- /dev/null +++ b/man3p/posix_fadvise.3p @@ -0,0 +1,114 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_FADVISE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_fadvise +.SH NAME +posix_fadvise \- file advisory information (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_fadvise(int\fP \fIfd\fP\fB, off_t\fP \fIoffset\fP\fB, size_t\fP +\fIlen\fP\fB, int\fP \fIadvice\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_fadvise\fP() function shall advise the implementation +on the expected behavior of the application with respect to +the data in the file associated with the open file descriptor, \fIfd\fP, +starting at \fIoffset\fP and continuing for \fIlen\fP +bytes. The specified range need not currently exist in the file. If +\fIlen\fP is zero, all data following \fIoffset\fP is +specified. The implementation may use this information to optimize +handling of the specified data. The \fIposix_fadvise\fP() +function shall have no effect on the semantics of other operations +on the specified data, although it may affect the performance of +other operations. +.LP +The advice to be applied to the data is specified by the \fIadvice\fP +parameter and may be one of the following values: +.TP 7 +POSIX_FADV_NORMAL +.sp +Specifies that the application has no advice to give on its behavior +with respect to the specified data. It is the default +characteristic if no advice is given for an open file. +.TP 7 +POSIX_FADV_SEQUENTIAL +.sp +Specifies that the application expects to access the specified data +sequentially from lower offsets to higher offsets. +.TP 7 +POSIX_FADV_RANDOM +.sp +Specifies that the application expects to access the specified data +in a random order. +.TP 7 +POSIX_FADV_WILLNEED +.sp +Specifies that the application expects to access the specified data +in the near future. +.TP 7 +POSIX_FADV_DONTNEED +.sp +Specifies that the application expects that it will not access the +specified data in the near future. +.TP 7 +POSIX_FADV_NOREUSE +.sp +Specifies that the application expects to access the specified data +once and then not reuse it thereafter. +.sp +.LP +These values are defined in \fI\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIposix_fadvise\fP() shall return zero; +otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +.LP +The \fIposix_fadvise\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfd\fP argument is not a valid file descriptor. +.TP 7 +.B EINVAL +The value of \fIadvice\fP is invalid. +.TP 7 +.B ESPIPE +The \fIfd\fP argument is associated with a pipe or FIFO. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIposix_fadvise\fP() function is part of the Advisory Information +option and need not be provided on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_madvise\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_fallocate.3p b/man3p/posix_fallocate.3p new file mode 100644 index 000000000..4f36a50a2 --- /dev/null +++ b/man3p/posix_fallocate.3p @@ -0,0 +1,109 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_FALLOCATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_fallocate +.SH NAME +posix_fallocate \- file space control (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_fallocate(int\fP \fIfd\fP\fB, off_t\fP \fIoffset\fP\fB, +size_t\fP \fIlen\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_fallocate\fP() function shall ensure that any required +storage for regular file data starting at \fIoffset\fP and +continuing for \fIlen\fP bytes is allocated on the file system storage +media. If \fIposix_fallocate\fP() returns successfully, +subsequent writes to the specified file data shall not fail due to +the lack of free space on the file system storage media. +.LP +If the \fIoffset\fP+ \fIlen\fP is beyond the current file size, then +\fIposix_fallocate\fP() shall adjust the file size to +\fIoffset\fP+ \fIlen\fP. Otherwise, the file size shall not be changed. +.LP +It is implementation-defined whether a previous \fIposix_fadvise\fP() +call +influences allocation strategy. +.LP +Space allocated via \fIposix_fallocate\fP() shall be freed by a successful +call to \fIcreat\fP() or \fIopen\fP() that truncates the size of the +file. Space allocated via \fIposix_fallocate\fP() may be freed by +a successful call to \fIftruncate\fP() that reduces the file size +to a size smaller than \fIoffset\fP+ +\fIlen\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIposix_fallocate\fP() shall return zero; +otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +.LP +The \fIposix_fallocate\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfd\fP argument is not a valid file descriptor. +.TP 7 +.B EBADF +The \fIfd\fP argument references a file that was opened without write +permission. +.TP 7 +.B EFBIG +The value of \fIoffset\fP+ \fIlen\fP is greater than the maximum file +size. +.TP 7 +.B EINTR +A signal was caught during execution. +.TP 7 +.B EINVAL +The \fIlen\fP argument was zero or the \fIoffset\fP argument was less +than zero. +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to a file system. +.TP 7 +.B ENODEV +The \fIfd\fP argument does not refer to a regular file. +.TP 7 +.B ENOSPC +There is insufficient free space remaining on the file system storage +media. +.TP 7 +.B ESPIPE +The \fIfd\fP argument is associated with a pipe or FIFO. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIposix_fallocate\fP() function is part of the Advisory Information +option and need not be provided on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcreat\fP() , \fIftruncate\fP() , \fIopen\fP() , \fIunlink\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_madvise.3p b/man3p/posix_madvise.3p new file mode 100644 index 000000000..739bd851a --- /dev/null +++ b/man3p/posix_madvise.3p @@ -0,0 +1,125 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_MADVISE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_madvise +.SH NAME +posix_madvise \- memory advisory information and alignment control +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_madvise(void *\fP\fIaddr\fP\fB, size_t\fP \fIlen\fP\fB, +int\fP \fIadvice\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_madvise\fP() function need only be supported if either +the Memory Mapped Files or the Shared Memory Objects options +are supported. +.LP +The \fIposix_madvise\fP() function shall advise the implementation +on the expected behavior of the application with respect to +the data in the memory starting at address \fIaddr\fP, and continuing +for \fIlen\fP bytes. The implementation may use this +information to optimize handling of the specified data. The \fIposix_madvise\fP() +function shall have no effect on the semantics +of access to memory in the specified range, although it may affect +the performance of access. +.LP +The implementation may require that \fIaddr\fP be a multiple of the +page size, which is the value returned by \fIsysconf\fP() when the +name value _SC_PAGESIZE is used. +.LP +The advice to be applied to the memory range is specified by the \fIadvice\fP +parameter and may be one of the following +values: +.TP 7 +POSIX_MADV_NORMAL +.sp +Specifies that the application has no advice to give on its behavior +with respect to the specified range. It is the default +characteristic if no advice is given for a range of memory. +.TP 7 +POSIX_MADV_SEQUENTIAL +.sp +Specifies that the application expects to access the specified range +sequentially from lower addresses to higher addresses. +.TP 7 +POSIX_MADV_RANDOM +.sp +Specifies that the application expects to access the specified range +in a random order. +.TP 7 +POSIX_MADV_WILLNEED +.sp +Specifies that the application expects to access the specified range +in the near future. +.TP 7 +POSIX_MADV_DONTNEED +.sp +Specifies that the application expects that it will not access the +specified range in the near future. +.sp +.LP +These values are defined in the \fI\fP header. +.SH RETURN VALUE +.LP +Upon successful completion, \fIposix_madvise\fP() shall return zero; +otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +.LP +The \fIposix_madvise\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of \fIadvice\fP is invalid. +.TP 7 +.B ENOMEM +Addresses in the range starting at \fIaddr\fP and continuing for \fIlen\fP +bytes are partly or completely outside the range +allowed for the address space of the calling process. +.sp +.LP +The \fIposix_madvise\fP() function may fail if: +.TP 7 +.B EINVAL +The value of \fIaddr\fP is not a multiple of the value returned by +\fIsysconf\fP() +when the name value _SC_PAGESIZE is used. +.TP 7 +.B EINVAL +The value of \fIlen\fP is zero. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIposix_madvise\fP() function is part of the Advisory Information +option and need not be provided on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImmap\fP() , \fIposix_fadvise\fP() , \fIsysconf\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_mem_offset.3p b/man3p/posix_mem_offset.3p new file mode 100644 index 000000000..8e340de1f --- /dev/null +++ b/man3p/posix_mem_offset.3p @@ -0,0 +1,97 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_MEM_OFFSET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_mem_offset +.SH NAME +posix_mem_offset \- find offset and length of a mapped typed memory +block (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_mem_offset(const void *restrict\fP \fIaddr\fP\fB, size_t\fP +\fIlen\fP\fB, +.br +\ \ \ \ \ \ off_t *restrict\fP \fIoff\fP\fB, size_t *restrict\fP +\fIcontig_len\fP\fB, +.br +\ \ \ \ \ \ int *restrict\fP \fIfildes\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_mem_offset\fP() function shall return in the variable +pointed to by \fIoff\fP a value that identifies the offset +(or location), within a memory object, of the memory block currently +mapped at \fIaddr\fP. The function shall return in the +variable pointed to by \fIfildes\fP, the descriptor used (via \fImmap\fP()) +to establish the +mapping which contains \fIaddr\fP. If that descriptor was closed since +the mapping was established, the returned value of +\fIfildes\fP shall be -1. The \fIlen\fP argument specifies the length +of the block of the memory object the user wishes the +offset for; upon return, the value pointed to by \fIcontig_len\fP +shall equal either \fIlen\fP, or the length of the largest +contiguous block of the memory object that is currently mapped to +the calling process starting at \fIaddr\fP, whichever is +smaller. +.LP +If the memory object mapped at \fIaddr\fP is a typed memory object, +then if the \fIoff\fP and \fIcontig_len\fP values +obtained by calling \fIposix_mem_offset\fP() are used in a call to +\fImmap\fP() with a file +descriptor that refers to the same memory pool as \fIfildes\fP (either +through the same port or through a different port), and +that was opened with neither the POSIX_TYPED_MEM_ALLOCATE nor the +POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, the typed memory area that +is mapped shall be exactly the same area that was mapped at \fIaddr\fP +in the address space of the process that called +\fIposix_mem_offset\fP(). +.LP +If the memory object specified by \fIfildes\fP is not a typed memory +object, then the behavior of this function is +implementation-defined. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIposix_mem_offset\fP() function +shall return zero; otherwise, the corresponding error status +value shall be returned. +.SH ERRORS +.LP +The \fIposix_mem_offset\fP() function shall fail if: +.TP 7 +.B EACCES +The process has not mapped a memory object supported by this function +at the given address \fIaddr\fP. +.sp +.LP +This function shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImmap\fP() , \fIposix_typed_mem_open\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_memalign.3p b/man3p/posix_memalign.3p new file mode 100644 index 000000000..ee79199db --- /dev/null +++ b/man3p/posix_memalign.3p @@ -0,0 +1,75 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_MEMALIGN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_memalign +.SH NAME +posix_memalign \- aligned memory allocation (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_memalign(void **\fP\fImemptr\fP\fB, size_t\fP \fIalignment\fP\fB, +size_t\fP \fIsize\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_memalign\fP() function shall allocate \fIsize\fP bytes +aligned on a boundary specified by \fIalignment\fP, and +shall return a pointer to the allocated memory in \fImemptr\fP. The +value of \fIalignment\fP shall be a multiple of +\fIsizeof\fP( \fBvoid *\fP), that is also a power of two. Upon successful +completion, the value pointed to by \fImemptr\fP shall +be a multiple of \fIalignment\fP. +.LP +The +\fIfree\fP() function shall deallocate memory that has previously +been allocated by +\fIposix_memalign\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, \fIposix_memalign\fP() shall return zero; +otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +.LP +The \fIposix_memalign\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of the alignment parameter is not a power of two multiple +of \fIsizeof\fP( \fBvoid *\fP). +.TP 7 +.B ENOMEM +There is insufficient memory available with the requested alignment. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIposix_memalign\fP() function is part of the Advisory Information +option and need not be provided on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfree\fP() , \fImalloc\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_openpt.3p b/man3p/posix_openpt.3p new file mode 100644 index 000000000..46888f86b --- /dev/null +++ b/man3p/posix_openpt.3p @@ -0,0 +1,151 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_OPENPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_openpt +.SH NAME +posix_openpt \- open a pseudo-terminal device +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int posix_openpt(int\fP \fIoflag\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_openpt\fP() function shall establish a connection between +a master device for a pseudo-terminal and a file +descriptor. The file descriptor is used by other I/O functions that +refer to that pseudo-terminal. +.LP +The file status flags and file access modes of the open file description +shall be set according to the value of +\fIoflag\fP. +.LP +Values for \fIoflag\fP are constructed by a bitwise-inclusive OR of +flags from the following list, defined in \fI\fP: +.TP 7 +O_RDWR +Open for reading and writing. +.TP 7 +O_NOCTTY +If set \fIposix_openpt\fP() shall not cause the terminal device to +become the controlling terminal for the process. +.sp +.LP +The behavior of other values for the \fIoflag\fP argument is unspecified. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIposix_openpt\fP() function shall +open a master pseudo-terminal device and return a +non-negative integer representing the lowest numbered unused file +descriptor. Otherwise, -1 shall be returned and \fIerrno\fP set +to indicate the error. +.SH ERRORS +.LP +The \fIposix_openpt\fP() function shall fail if: +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENFILE +The maximum allowable number of files is currently open in the system. +.sp +.LP +The \fIposix_openpt\fP() function may fail if: +.TP 7 +.B EINVAL +The value of \fIoflag\fP is not valid. +.TP 7 +.B EAGAIN +Out of pseudo-terminal resources. +.TP 7 +.B ENOSR +Out of STREAMS resources. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Opening a Pseudo-Terminal and Returning the Name of the Slave +Device and a File Descriptor +.sp +.RS +.nf + +\fB#include +#include +.sp + +int masterfd, slavefd; +char *slavedevice; +.sp + +masterfd = posix_openpt(O_RDWR|O_NOCTTY); +.sp + +if (masterfd == -1 + || grantpt (masterfd) == -1 + || unlockpt (masterfd) == -1 + || (slavedevice = ptsname (masterfd)) == NULL) + return -1; +.sp + +printf("slave device is: %s\\n", slavedevice); +.sp + +slavefd = open(slave, O_RDWR|O_NOCTTY); +if (slavefd < 0) + return -1; +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +This function is a method for portably obtaining a file descriptor +of a master terminal device for a pseudo-terminal. The \fIgrantpt\fP() +and \fIptsname\fP() functions can be +used to manipulate mode and ownership permissions, and to obtain the +name of the slave device, respectively. +.SH RATIONALE +.LP +The standard developers considered the matter of adding a special +device for cloning master pseudo-terminals: the +\fB/dev/ptmx\fP device. However, consensus could not be reached, and +it was felt that adding a new function would permit other +implementations. The \fIposix_openpt\fP() function is designed to +complement the \fIgrantpt\fP(), \fIptsname\fP(), and \fIunlockpt\fP() +functions. +.LP +On implementations supporting the \fB/dev/ptmx\fP clone device, opening +the master device of a pseudo-terminal is simply: +.sp +.RS +.nf + +\fBmfdp = open("/dev/ptmx", oflag ); +if (mfdp < 0) + return -1; +\fP +.fi +.RE +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgrantpt\fP() , \fIopen\fP() , \fIptsname\fP() , \fIunlockpt\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_spawn.3p b/man3p/posix_spawn.3p new file mode 100644 index 000000000..738501a62 --- /dev/null +++ b/man3p/posix_spawn.3p @@ -0,0 +1,631 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_SPAWN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_spawn +.SH NAME +posix_spawn, posix_spawnp \- spawn a process (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_spawn(pid_t *restrict\fP \fIpid\fP\fB, const char *restrict\fP +\fIpath\fP\fB, +.br +\ \ \ \ \ \ const posix_spawn_file_actions_t *\fP\fIfile_actions\fP\fB, +.br +\ \ \ \ \ \ const posix_spawnattr_t *restrict\fP \fIattrp\fP\fB, +.br +\ \ \ \ \ \ char *const\fP \fIargv\fP\fB[restrict], char *const\fP +\fIenvp\fP\fB[restrict]); +.br +int posix_spawnp(pid_t *restrict\fP \fIpid\fP\fB, const char *restrict\fP +\fIfile\fP\fB, +.br +\ \ \ \ \ \ const posix_spawn_file_actions_t *\fP\fIfile_actions\fP\fB, +.br +\ \ \ \ \ \ const posix_spawnattr_t *restrict\fP \fIattrp\fP\fB, +.br +\ \ \ \ \ \ char *const\fP \fIargv\fP\fB[restrict], char * const\fP +\fIenvp\fP\fB[restrict]); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_spawn\fP() and \fIposix_spawnp\fP() functions shall create +a new process (child process) from the specified +process image. The new process image shall be constructed from a regular +executable file called the new process image file. +.LP +When a C program is executed as the result of this call, it shall +be entered as a C-language function call as follows: +.sp +.RS +.nf + +\fBint main(int\fP \fIargc\fP\fB, char *\fP\fIargv\fP\fB[]); +\fP +.fi +.RE +.LP +where \fIargc\fP is the argument count and \fIargv\fP is an array +of character pointers to the arguments themselves. In +addition, the following variable: +.sp +.RS +.nf + +\fBextern char **environ; +\fP +.fi +.RE +.LP +shall be initialized as a pointer to an array of character pointers +to the environment strings. +.LP +The argument \fIargv\fP is an array of character pointers to null-terminated +strings. The last member of this array shall be a +null pointer and is not counted in \fIargc\fP. These strings constitute +the argument list available to the new process image. The +value in \fIargv\fP[0] should point to a filename that is associated +with the process image being started by the +\fIposix_spawn\fP() or \fIposix_spawnp\fP() function. +.LP +The argument \fIenvp\fP is an array of character pointers to null-terminated +strings. These strings constitute the environment +for the new process image. The environment array is terminated by +a null pointer. +.LP +The number of bytes available for the child process' combined argument +and environment lists is {ARG_MAX}. The implementation +shall specify in the system documentation (see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 2, Conformance) whether +any list overhead, such as length words, null terminators, +pointers, or alignment bytes, is included in this total. +.LP +The \fIpath\fP argument to \fIposix_spawn\fP() is a pathname that +identifies the new process image file to execute. +.LP +The \fIfile\fP parameter to \fIposix_spawnp\fP() shall be used to +construct a pathname that identifies the new process image +file. If the \fIfile\fP parameter contains a slash character, the +\fIfile\fP parameter shall be used as the pathname for the new +process image file. Otherwise, the path prefix for this file shall +be obtained by a search of the directories passed as the +environment variable \fIPATH\fP (see the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables). If this +environment variable is not defined, the results of +the search are implementation-defined. +.LP +If \fIfile_actions\fP is a null pointer, then file descriptors open +in the calling process shall remain open in the child +process, except for those whose close-on- \fIexec\fP flag FD_CLOEXEC +is set (see \fIfcntl\fP() ). For those file descriptors that remain +open, all attributes of the corresponding open file +descriptions, including file locks (see \fIfcntl\fP() ), shall remain +unchanged. +.LP +If \fIfile_actions\fP is not NULL, then the file descriptors open +in the child process shall be those open in the calling +process as modified by the spawn file actions object pointed to by +\fIfile_actions\fP and the FD_CLOEXEC flag of each remaining +open file descriptor after the spawn file actions have been processed. +The effective order of processing the spawn file actions +shall be: +.IP " 1." 4 +The set of open file descriptors for the child process shall initially +be the same set as is open for the calling process. All +attributes of the corresponding open file descriptions, including +file locks (see \fIfcntl\fP() ), shall +remain unchanged. +.LP +.IP " 2." 4 +The signal mask, signal default actions, and the effective user and +group IDs for the child process shall be changed as +specified in the attributes object referenced by \fIattrp\fP. +.LP +.IP " 3." 4 +The file actions specified by the spawn file actions object shall +be performed in the order in which they were added to the +spawn file actions object. +.LP +.IP " 4." 4 +Any file descriptor that has its FD_CLOEXEC flag set (see \fIfcntl\fP() +) shall be closed. +.LP +.LP +The \fBposix_spawnattr_t\fP spawn attributes object type is defined +in \fI\fP. It shall contain at least the attributes defined +below. +.LP +If the POSIX_SPAWN_SETPGROUP flag is set in the \fIspawn-flags\fP +attribute of the object referenced by \fIattrp\fP, and the +\fIspawn-pgroup\fP attribute of the same object is non-zero, then +the child's process group shall be as specified in the +\fIspawn-pgroup\fP attribute of the object referenced by \fIattrp\fP. +.LP +As a special case, if the POSIX_SPAWN_SETPGROUP flag is set in the +\fIspawn-flags\fP attribute of the object referenced by +\fIattrp\fP, and the \fIspawn-pgroup\fP attribute of the same object +is set to zero, then the child shall be in a new process +group with a process group ID equal to its process ID. +.LP +If the POSIX_SPAWN_SETPGROUP flag is not set in the \fIspawn-flags\fP +attribute of the object referenced by \fIattrp\fP, the +new child process shall inherit the parent's process group. +.LP +If +the POSIX_SPAWN_SETSCHEDPARAM flag is set in the \fIspawn-flags\fP +attribute of the object referenced by \fIattrp\fP, but +POSIX_SPAWN_SETSCHEDULER is not set, the new process image shall initially +have the scheduling policy of the calling process with +the scheduling parameters specified in the \fIspawn-schedparam\fP +attribute of the object referenced by \fIattrp\fP. +.LP +If the POSIX_SPAWN_SETSCHEDULER flag is set in the \fIspawn-flags\fP +attribute of the object referenced by \fIattrp\fP +(regardless of the setting of the POSIX_SPAWN_SETSCHEDPARAM flag), +the new process image shall initially have the scheduling policy +specified in the \fIspawn-schedpolicy\fP attribute of the object referenced +by \fIattrp\fP and the scheduling parameters +specified in the \fIspawn-schedparam\fP attribute of the same object. +.LP +The POSIX_SPAWN_RESETIDS flag in the \fIspawn-flags\fP attribute of +the object referenced by \fIattrp\fP governs the effective +user ID of the child process. If this flag is not set, the child process +shall inherit the parent process' effective user ID. If +this flag is set, the child process' effective user ID shall be reset +to the parent's real user ID. In either case, if the +set-user-ID mode bit of the new process image file is set, the effective +user ID of the child process shall become that file's +owner ID before the new process image begins execution. +.LP +The POSIX_SPAWN_RESETIDS flag in the \fIspawn-flags\fP attribute of +the object referenced by \fIattrp\fP also governs the +effective group ID of the child process. If this flag is not set, +the child process shall inherit the parent process' effective +group ID. If this flag is set, the child process' effective group +ID shall be reset to the parent's real group ID. In either case, +if the set-group-ID mode bit of the new process image file is set, +the effective group ID of the child process shall become that +file's group ID before the new process image begins execution. +.LP +If the POSIX_SPAWN_SETSIGMASK flag is set in the \fIspawn-flags\fP +attribute of the object referenced by \fIattrp\fP, the +child process shall initially have the signal mask specified in the +\fIspawn-sigmask\fP attribute of the object referenced by +\fIattrp\fP. +.LP +If the POSIX_SPAWN_SETSIGDEF flag is set in the \fIspawn-flags\fP +attribute of the object referenced by \fIattrp\fP, the +signals specified in the \fIspawn-sigdefault\fP attribute of the same +object shall be set to their default actions in the child +process. Signals set to the default action in the parent process shall +be set to the default action in the child process. +.LP +Signals set to be caught by the calling process shall be set to the +default action in the child process. +.LP +Except for SIGCHLD, signals set to be ignored by the calling process +image shall be set to be ignored by the child process, +unless otherwise specified by the POSIX_SPAWN_SETSIGDEF flag being +set in the \fIspawn-flags\fP attribute of the object referenced +by \fIattrp\fP and the signals being indicated in the \fIspawn-sigdefault\fP +attribute of the object referenced by +\fIattrp\fP. +.LP +If the SIGCHLD signal is set to be ignored by the calling process, +it is unspecified whether the SIGCHLD signal is set to be +ignored or to the default action in the child process, unless otherwise +specified by the POSIX_SPAWN_SETSIGDEF flag being set in +the \fIspawn_flags\fP attribute of the object referenced by \fIattrp\fP +and the SIGCHLD signal being indicated in the +\fIspawn_sigdefault\fP attribute of the object referenced by \fIattrp\fP. +.LP +If the value of the \fIattrp\fP pointer is NULL, then the default +values are used. +.LP +All process attributes, other than those influenced by the attributes +set in the object referenced by \fIattrp\fP as specified +above or by the file descriptor manipulations specified in \fIfile_actions\fP, +shall appear in the new process image as though \fIfork\fP() had been +called to create a child process and then a member of the \fIexec\fP +family of functions had been called by the child process to execute +the new process +image. +.LP +It is implementation-defined whether the fork handlers are run when +\fIposix_spawn\fP() or \fIposix_spawnp\fP() is called. +.SH RETURN VALUE +.LP +Upon successful completion, \fIposix_spawn\fP() and \fIposix_spawnp\fP() +shall return the process ID of the child process to +the parent process, in the variable pointed to by a non-NULL \fIpid\fP +argument, and shall return zero as the function return +value. Otherwise, no child process shall be created, the value stored +into the variable pointed to by a non-NULL \fIpid\fP is +unspecified, and an error number shall be returned as the function +return value to indicate the error. If the \fIpid\fP argument +is a null pointer, the process ID of the child is not returned to +the caller. +.SH ERRORS +.LP +The \fIposix_spawn\fP() and \fIposix_spawnp\fP() functions may fail +if: +.TP 7 +.B EINVAL +The value specified by \fIfile_actions\fP or \fIattrp\fP is invalid. +.sp +.LP +If this error occurs after the calling process successfully returns +from the \fIposix_spawn\fP() or \fIposix_spawnp\fP() +function, the child process may exit with exit status 127. +.LP +If \fIposix_spawn\fP() or \fIposix_spawnp\fP() fail for any of the +reasons that would cause \fIfork\fP() or one of the \fIexec\fP family +of functions to +fail, an error value shall be returned as described by \fIfork\fP() +and \fIexec\fP, respectively (or, if the error occurs after the calling +process successfully returns, the +child process shall exit with exit status 127). +.LP +If POSIX_SPAWN_SETPGROUP is set in the \fIspawn-flags\fP attribute +of the object referenced by \fIattrp\fP, and +\fIposix_spawn\fP() or \fIposix_spawnp\fP() fails while changing the +child's process group, an error value shall be returned as +described by \fIsetpgid\fP() (or, if the error occurs after the calling +process +successfully returns, the child process shall exit with exit status +127). +.LP +If +POSIX_SPAWN_SETSCHEDPARAM is set and POSIX_SPAWN_SETSCHEDULER is not +set in the \fIspawn-flags\fP attribute of the object +referenced by \fIattrp\fP, then if \fIposix_spawn\fP() or \fIposix_spawnp\fP() +fails for any of the reasons that would cause \fIsched_setparam\fP() +to fail, an error value shall be returned as described by \fIsched_setparam\fP() +(or, if the error occurs after the calling process successfully +returns, the child process shall exit with exit status 127). +.LP +If POSIX_SPAWN_SETSCHEDULER is set in the \fIspawn-flags\fP attribute +of the object referenced by \fIattrp\fP, and if +\fIposix_spawn\fP() or \fIposix_spawnp\fP() fails for any of the reasons +that would cause \fIsched_setscheduler\fP() to fail, an error value +shall be returned as described by \fIsched_setscheduler\fP() (or, +if the error occurs after the calling process +successfully returns, the child process shall exit with exit status +127). +.LP +If the \fIfile_actions\fP argument is not NULL, and specifies any +\fIclose\fP, \fIdup2\fP, or \fIopen\fP actions to be +performed, and if \fIposix_spawn\fP() or \fIposix_spawnp\fP() fails +for any of the reasons that would cause \fIclose\fP(), \fIdup2\fP(), +or \fIopen\fP() to fail, an error value shall be returned as described +by \fIclose\fP(), \fIdup2\fP(), and \fIopen\fP(), respectively (or, +if the error occurs after the calling process successfully returns, +the child process shall exit with exit status 127). An open file action +may, by itself, result in any of the errors described by \fIclose\fP() +or \fIdup2\fP(), in addition to those +described by \fIopen\fP(). +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +These functions are part of the Spawn option and need not be provided +on all implementations. +.SH RATIONALE +.LP +The \fIposix_spawn\fP() function and its close relation \fIposix_spawnp\fP() +have been introduced to overcome the following +perceived difficulties with \fIfork\fP(): the \fIfork\fP() function +is difficult or impossible to implement without swapping or dynamic +address +translation. +.IP " *" 3 +Swapping is generally too slow for a realtime environment. +.LP +.IP " *" 3 +Dynamic address translation is not available everywhere that POSIX +might be useful. +.LP +.IP " *" 3 +Processes are too useful to simply option out of POSIX whenever it +must run without address translation or other MMU +services. +.LP +.LP +Thus, POSIX needs process creation and file execution primitives that +can be efficiently implemented without address translation +or other MMU services. +.LP +The \fIposix_spawn\fP() function is implementable as a library routine, +but both \fIposix_spawn\fP() and \fIposix_spawnp\fP() +are designed as kernel operations. Also, although they may be an efficient +replacement for many \fIfork\fP()/ \fIexec\fP pairs, their goal is +to provide useful +process creation primitives for systems that have difficulty with +\fIfork\fP(), not to +provide drop-in replacements for \fIfork\fP()/ \fIexec\fP. +.LP +This view of the role of \fIposix_spawn\fP() and \fIposix_spawnp\fP() +influenced the design of their API. It does not attempt +to provide the full functionality of \fIfork\fP()/ \fIexec\fP in which +arbitrary user-specified operations of any sort are permitted between +the creation +of the child process and the execution of the new process image; any +attempt to reach that level would need to provide a +programming language as parameters. Instead, \fIposix_spawn\fP() and +\fIposix_spawnp\fP() are process creation primitives like +the \fIStart_Process\fP and \fIStart_Process_Search\fP Ada language +bindings package \fIPOSIX_Process_Primitives\fP and also +like those in many operating systems that are not UNIX systems, but +with some POSIX-specific additions. +.LP +To achieve its coverage goals, \fIposix_spawn\fP() and \fIposix_spawnp\fP() +have control of six types of inheritance: file +descriptors, process group ID, user and group ID, signal mask, scheduling, +and whether each signal ignored in the parent will +remain ignored in the child, or be reset to its default action in +the child. +.LP +Control of file descriptors is required to allow an independently +written child process image to access data streams opened by +and even generated or read by the parent process without being specifically +coded to know which parent files and file descriptors +are to be used. Control of the process group ID is required to control +how the child process' job control relates to that of the +parent. +.LP +Control of the signal mask and signal defaulting is sufficient to +support the implementation of \fIsystem\fP(). Although support for +\fIsystem\fP() is not +explicitly one of the goals for \fIposix_spawn\fP() and \fIposix_spawnp\fP(), +it is covered under the "at least 50%" coverage +goal. +.LP +The intention is that the normal file descriptor inheritance across +\fIfork\fP(), the +subsequent effect of the specified spawn file actions, and the normal +file descriptor inheritance across one of the \fIexec\fP family of +functions should fully specify open file inheritance. The implementation +need make +no decisions regarding the set of open file descriptors when the child +process image begins execution, those decisions having +already been made by the caller and expressed as the set of open file +descriptors and their FD_CLOEXEC flags at the time of the +call and the spawn file actions object specified in the call. We have +been assured that in cases where the POSIX +\fIStart_Process\fP Ada primitives have been implemented in a library, +this method of controlling file descriptor inheritance may +be implemented very easily. +.LP +We can identify several problems with \fIposix_spawn\fP() and \fIposix_spawnp\fP(), +but there does not appear to be a solution +that introduces fewer problems. Environment modification for child +process attributes not specifiable via the \fIattrp\fP or +\fIfile_actions\fP arguments must be done in the parent process, and +since the parent generally wants to save its context, it is +more costly than similar functionality with \fIfork\fP()/ \fIexec\fP. +It is also complicated to modify the environment of a multi-threaded +process temporarily, +since all threads must agree when it is safe for the environment to +be changed. However, this cost is only borne by those +invocations of \fIposix_spawn\fP() and \fIposix_spawnp\fP() that use +the additional functionality. Since extensive modifications +are not the usual case, and are particularly unlikely in time-critical +code, keeping much of the environment control out of +\fIposix_spawn\fP() and \fIposix_spawnp\fP() is appropriate design. +.LP +The \fIposix_spawn\fP() and \fIposix_spawnp\fP() functions do not +have all the power of \fIfork\fP()/ \fIexec\fP. This is to be expected. +The \fIfork\fP() function is a wonderfully powerful operation. We +do not expect to duplicate its +functionality in a simple, fast function with no special hardware +requirements. It is worth noting that \fIposix_spawn\fP() and +\fIposix_spawnp\fP() are very similar to the process creation operations +on many operating systems that are not UNIX systems. +.SS Requirements +.LP +The requirements for \fIposix_spawn\fP() and \fIposix_spawnp\fP() +are: +.IP " *" 3 +They must be implementable without an MMU or unusual hardware. +.LP +.IP " *" 3 +They must be compatible with existing POSIX standards. +.LP +.LP +Additional goals are: +.IP " *" 3 +They should be efficiently implementable. +.LP +.IP " *" 3 +They should be able to replace at least 50% of typical executions +of \fIfork\fP(). +.LP +.IP " *" 3 +A system with \fIposix_spawn\fP() and \fIposix_spawnp\fP() and without +\fIfork\fP() +should be useful, at least for realtime applications. +.LP +.IP " *" 3 +A system with \fIfork\fP() and the \fIexec\fP family +should be able to implement \fIposix_spawn\fP() and \fIposix_spawnp\fP() +as library routines. +.LP +.SS Two-Syntax +.LP +POSIX \fIexec\fP has several calling sequences with approximately +the same functionality. +These appear to be required for compatibility with existing practice. +Since the existing practice for the \fIposix_spawn*\fP() functions +is otherwise substantially unlike POSIX, we feel that +simplicity outweighs compatibility. There are, therefore, only two +names for the \fIposix_spawn*\fP() functions. +.LP +The parameter list does not differ between \fIposix_spawn\fP() and +\fIposix_spawnp\fP(); \fIposix_spawnp\fP() interprets the +second parameter more elaborately than \fIposix_spawn\fP(). +.SS Compatibility with POSIX.5 (Ada) +.LP +The \fIStart_Process\fP and \fIStart_Process_Search\fP procedures +from the \fIPOSIX_Process_Primitives\fP package from the +Ada language binding to POSIX.1 encapsulate \fIfork\fP() and \fIexec\fP +functionality in a manner similar to that of \fIposix_spawn\fP() and +\fIposix_spawnp\fP(). +Originally, in keeping with our simplicity goal, the standard developers +had limited the capabilities of \fIposix_spawn\fP() and +\fIposix_spawnp\fP() to a subset of the capabilities of \fIStart_Process\fP +and \fIStart_Process_Search\fP; certain non-default +capabilities were not supported. However, based on suggestions by +the ballot group to improve file descriptor mapping or drop it, +and on the advice of an Ada Language Bindings working group member, +the standard developers decided that \fIposix_spawn\fP() and +\fIposix_spawnp\fP() should be sufficiently powerful to implement +\fIStart_Process\fP and \fIStart_Process_Search\fP. The +rationale is that if the Ada language binding to such a primitive +had already been approved as an IEEE standard, there can be +little justification for not approving the functionally-equivalent +parts of a C binding. The only three capabilities provided by +\fIposix_spawn\fP() and \fIposix_spawnp\fP() that are not provided +by \fIStart_Process\fP and \fIStart_Process_Search\fP are +optionally specifying the child's process group ID, the set of signals +to be reset to default signal handling in the child process, +and the child's scheduling policy and parameters. +.LP +For the Ada language binding for \fIStart_Process\fP to be implemented +with \fIposix_spawn\fP(), that binding would need to +explicitly pass an empty signal mask and the parent's environment +to \fIposix_spawn\fP() whenever the caller of +\fIStart_Process\fP allowed these arguments to default, since \fIposix_spawn\fP() +does not provide such defaults. The ability of +\fIStart_Process\fP to mask user-specified signals during its execution +is functionally unique to the Ada language binding and +must be dealt with in the binding separately from the call to \fIposix_spawn\fP(). +.SS Process Group +.LP +The process group inheritance field can be used to join the child +process with an existing process group. By assigning a value +of zero to the \fIspawn-pgroup\fP attribute of the object referenced +by \fIattrp\fP, the \fIsetpgid\fP() mechanism will place the child +process in a new process group. +.SS Threads +.LP +Without the \fIposix_spawn\fP() and \fIposix_spawnp\fP() functions, +systems without address translation can still use threads +to give an abstraction of concurrency. In many cases, thread creation +suffices, but it is not always a good substitute. The +\fIposix_spawn\fP() and \fIposix_spawnp\fP() functions are considerably +"heavier" than thread creation. Processes have several +important attributes that threads do not. Even without address translation, +a process may have base-and-bound memory protection. +Each process has a process environment including security attributes +and file capabilities, and powerful scheduling attributes. +Processes abstract the behavior of non-uniform-memory-architecture +multi-processors better than threads, and they are more +convenient to use for activities that are not closely linked. +.LP +The \fIposix_spawn\fP() and \fIposix_spawnp\fP() functions may not +bring support for multiple processes to every +configuration. Process creation is not the only piece of operating +system support required to support multiple processes. The total +cost of support for multiple processes may be quite high in some circumstances. +Existing practice shows that support for multiple +processes is uncommon and threads are common among "tiny kernels". +There should, therefore, probably continue to be AEPs for +operating systems with only one process. +.SS Asynchronous Error Notification +.LP +A library implementation of \fIposix_spawn\fP() or \fIposix_spawnp\fP() +may not be able to detect all possible errors before +it forks the child process. IEEE\ Std\ 1003.1-2001 provides for an +error indication returned from a child process which +could not successfully complete the spawn operation via a special +exit status which may be detected using the status value returned +by \fIwait\fP() and \fIwaitpid\fP(). +.LP +The \fIstat_val\fP interface and the macros used to interpret it are +not well suited to the purpose of returning API errors, +but they are the only path available to a library implementation. +Thus, an implementation may cause the child process to exit with +exit status 127 for any error detected during the spawn process after +the \fIposix_spawn\fP() or \fIposix_spawnp\fP() function +has successfully returned. +.LP +The standard developers had proposed using two additional macros to +interpret \fIstat_val\fP. The first, WIFSPAWNFAIL, would +have detected a status that indicated that the child exited because +of an error detected during the \fIposix_spawn\fP() or +\fIposix_spawnp\fP() operations rather than during actual execution +of the child process image; the second, WSPAWNERRNO, would +have extracted the error value if WIFSPAWNFAIL indicated a failure. +Unfortunately, the ballot group strongly opposed this because +it would make a library implementation of \fIposix_spawn\fP() or \fIposix_spawnp\fP() +dependent on kernel modifications to \fIwaitpid\fP() to be able to +embed special information in \fIstat_val\fP to indicate a +spawn failure. +.LP +The 8 bits of child process exit status that are guaranteed by IEEE\ Std\ 1003.1-2001 +to be accessible to the waiting +parent process are insufficient to disambiguate a spawn error from +any other kind of error that may be returned by an arbitrary +process image. No other bits of the exit status are required to be +visible in \fIstat_val\fP, so these macros could not be +strictly implemented at the library level. Reserving an exit status +of 127 for such spawn errors is consistent with the use of this +value by \fIsystem\fP() and \fIpopen\fP() to signal +failures in these operations that occur after the function has returned +but before a shell is able to execute. The exit status of +127 does not uniquely identify this class of error, nor does it provide +any detailed information on the nature of the failure. Note +that a kernel implementation of \fIposix_spawn\fP() or \fIposix_spawnp\fP() +is permitted (and encouraged) to return any possible +error as the function value, thus providing more detailed failure +information to the parent process. +.LP +Thus, no special macros are available to isolate asynchronous \fIposix_spawn\fP() +or \fIposix_spawnp\fP() errors. Instead, +errors detected by the \fIposix_spawn\fP() or \fIposix_spawnp\fP() +operations in the context of the child process before the new +process image executes are reported by setting the child's exit status +to 127. The calling process may use the WIFEXITED and +WEXITSTATUS macros on the \fIstat_val\fP stored by the \fIwait\fP() +or \fIwaitpid\fP() functions to detect spawn failures to the extent +that other status values with +which the child process image may exit (before the parent can conclusively +determine that the child process image has begun +execution) are distinct from exit status 127. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIalarm\fP() , \fIchmod\fP() , \fIclose\fP() , \fIdup\fP() , \fIexec\fP() +, \fIexit\fP() , \fIfcntl\fP() , \fIfork\fP() , \fIkill\fP() , \fIopen\fP() +, \fIposix_spawn_file_actions_addclose\fP() , \fIposix_spawn_file_actions_adddup2\fP() +, \fIposix_spawn_file_actions_addopen\fP() , \fIposix_spawn_file_actions_destroy\fP() +, , \fIposix_spawnattr_destroy\fP() , \fIposix_spawnattr_init\fP() +, \fIposix_spawnattr_getsigdefault\fP() , \fIposix_spawnattr_getflags\fP() +, \fIposix_spawnattr_getpgroup\fP() , \fIposix_spawnattr_getschedparam\fP() +, \fIposix_spawnattr_getschedpolicy\fP() , \fIposix_spawnattr_getsigmask\fP() +, \fIposix_spawnattr_setsigdefault\fP() , \fIposix_spawnattr_setflags\fP() +, \fIposix_spawnattr_setpgroup\fP() , \fIposix_spawnattr_setschedparam\fP() +, \fIposix_spawnattr_setschedpolicy\fP() , \fIposix_spawnattr_setsigmask\fP() +, \fIsched_setparam\fP() , \fIsched_setscheduler\fP() , \fIsetpgid\fP() +, \fIsetuid\fP() , \fIstat\fP() , \fItimes\fP() , \fIwait\fP() , the +Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_spawn_file_actions_addclose.3p b/man3p/posix_spawn_file_actions_addclose.3p new file mode 100644 index 000000000..68e164b0a --- /dev/null +++ b/man3p/posix_spawn_file_actions_addclose.3p @@ -0,0 +1 @@ +.so man3p/posix_spawn_file_actions_addopen.3p diff --git a/man3p/posix_spawn_file_actions_adddup2.3p b/man3p/posix_spawn_file_actions_adddup2.3p new file mode 100644 index 000000000..5286b1df1 --- /dev/null +++ b/man3p/posix_spawn_file_actions_adddup2.3p @@ -0,0 +1,93 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_SPAWN_FILE_ACTIONS_ADDDUP2" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_spawn_file_actions_adddup2 +.SH NAME +posix_spawn_file_actions_adddup2 \- add dup2 action to spawn file actions +object (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_spawn_file_actions_adddup2(posix_spawn_file_actions_t * +.br +\ \ \ \ \ \ \fP \fIfile_actions\fP\fB, int\fP \fIfildes\fP\fB, int\fP +\fInewfildes\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_spawn_file_actions_adddup2\fP() function shall add a +\fIdup2\fP() action to +the object referenced by \fIfile_actions\fP that shall cause the file +descriptor \fIfildes\fP to be duplicated as +\fInewfildes\fP (as if \fIdup2\fP( \fIfildes\fP, \fInewfildes\fP) +had been called) when a new process is spawned using this +file actions object. +.LP +A spawn file actions object is as defined in \fIposix_spawn_file_actions_addclose\fP() +\&. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIposix_spawn_file_actions_adddup2\fP() +function shall return zero; otherwise, an error number +shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIposix_spawn_file_actions_adddup2\fP() function shall fail if: +.TP 7 +.B EBADF +The value specified by \fIfildes\fP or \fInewfildes\fP is negative +or greater than or equal to {OPEN_MAX}. +.TP 7 +.B ENOMEM +Insufficient memory exists to add to the spawn file actions object. +.sp +.LP +The \fIposix_spawn_file_actions_adddup2\fP() function may fail if: +.TP 7 +.B EINVAL +The value specified by \fIfile_actions\fP is invalid. +.sp +.LP +It shall not be considered an error for the \fIfildes\fP argument +passed to the \fIposix_spawn_file_actions_adddup2\fP() +function to specify a file descriptor for which the specified operation +could not be performed at the time of the call. Any such +error will be detected when the associated file actions object is +later used during a \fIposix_spawn\fP() or \fIposix_spawnp\fP() +operation. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIposix_spawn_file_actions_adddup2\fP() function is part of the +Spawn option and need not be provided on all +implementations. +.SH RATIONALE +.LP +Refer to the RATIONALE in \fIposix_spawn_file_actions_addclose\fP() +\&. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIdup\fP() , \fIposix_spawn\fP() , \fIposix_spawn_file_actions_addclose\fP() +, \fIposix_spawn_file_actions_destroy\fP() , \fIposix_spawnp\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_spawn_file_actions_addopen.3p b/man3p/posix_spawn_file_actions_addopen.3p new file mode 100644 index 000000000..b377b5399 --- /dev/null +++ b/man3p/posix_spawn_file_actions_addopen.3p @@ -0,0 +1,218 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_spawn_file_actions_addclose +.SH NAME +posix_spawn_file_actions_addclose, posix_spawn_file_actions_addopen +\- add close or open action to spawn file actions +object (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t * +.br +\ \ \ \ \ \ \fP \fIfile_actions\fP\fB, int\fP \fIfildes\fP\fB); +.br +int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t * +.br +\ \ \ \ \ \ restrict\fP \fIfile_actions\fP\fB, int\fP \fIfildes\fP\fB, +.br +\ \ \ \ \ \ const char *restrict\fP \fIpath\fP\fB, int\fP \fIoflag\fP\fB, +mode_t\fP +\fImode\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +These functions shall add or delete a close or open action to a spawn +file actions object. +.LP +A spawn file actions object is of type \fBposix_spawn_file_actions_t\fP +(defined in \fI\fP) and is used to specify a series of actions +to be performed by a \fIposix_spawn\fP() or \fIposix_spawnp\fP() +operation in order to arrive at the set of open file descriptors for +the child process given the set of open file descriptors of +the parent. IEEE\ Std\ 1003.1-2001 does not define comparison or assignment +operators for the type +\fBposix_spawn_file_actions_t\fP. +.LP +A spawn file actions object, when passed to \fIposix_spawn\fP() or +\fIposix_spawnp\fP(), shall specify how the set of open file descriptors +in the calling +process is transformed into a set of potentially open file descriptors +for the spawned process. This transformation shall be as if +the specified sequence of actions was performed exactly once, in the +context of the spawned process (prior to execution of the new +process image), in the order in which the actions were added to the +object; additionally, when the new process image is executed, +any file descriptor (from this new set) which has its FD_CLOEXEC flag +set shall be closed (see \fIposix_spawn\fP() ). +.LP +The \fIposix_spawn_file_actions_addclose\fP() function shall add a +\fIclose\fP action to the object referenced by +\fIfile_actions\fP that shall cause the file descriptor \fIfildes\fP +to be closed (as if \fIclose\fP( \fIfildes\fP) had been +called) when a new process is spawned using this file actions object. +.LP +The \fIposix_spawn_file_actions_addopen\fP() function shall add an +\fIopen\fP action to the object referenced by +\fIfile_actions\fP that shall cause the file named by \fIpath\fP to +be opened (as if \fIopen\fP( \fIpath\fP, \fIoflag\fP, +\fImode\fP) had been called, and the returned file descriptor, if +not \fIfildes\fP, had been changed to \fIfildes\fP) when a new +process is spawned using this file actions object. If \fIfildes\fP +was already an open file descriptor, it shall be closed before +the new file is opened. +.LP +The string described by \fIpath\fP shall be copied by the \fIposix_spawn_file_actions_addopen\fP() +function. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return zero; otherwise, +an error number shall be returned to indicate the +error. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +.B EBADF +The value specified by \fIfildes\fP is negative or greater than or +equal to {OPEN_MAX}. +.sp +.LP +These functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIfile_actions\fP is invalid. +.TP 7 +.B ENOMEM +Insufficient memory exists to add to the spawn file actions object. +.sp +.LP +It shall not be considered an error for the \fIfildes\fP argument +passed to these functions to specify a file descriptor for +which the specified operation could not be performed at the time of +the call. Any such error will be detected when the associated +file actions object is later used during a \fIposix_spawn\fP() or +\fIposix_spawnp\fP() operation. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +These functions are part of the Spawn option and need not be provided +on all implementations. +.SH RATIONALE +.LP +A spawn file actions object may be initialized to contain an ordered +sequence of \fIclose\fP(), \fIdup2\fP(), and \fIopen\fP() operations +to be used by \fIposix_spawn\fP() or \fIposix_spawnp\fP() to +arrive at the set of open file descriptors inherited by the spawned +process from the set of open file descriptors in the parent at +the time of the \fIposix_spawn\fP() or \fIposix_spawnp\fP() call. +It had been suggested that the \fIclose\fP() and \fIdup2\fP() operations +alone are sufficient +to rearrange file descriptors, and that files which need to be opened +for use by the spawned process can be handled either by +having the calling process open them before the \fIposix_spawn\fP() +or \fIposix_spawnp\fP() call (and close them after), or by passing +filenames to the spawned +process (in \fIargv\fP) so that it may open them itself. The standard +developers recommend that applications use one of these two +methods when practical, since detailed error status on a failed open +operation is always available to the application this way. +However, the standard developers feel that allowing a spawn file actions +object to specify open operations is still appropriate +because: +.IP " 1." 4 +It is consistent with equivalent POSIX.5 (Ada) functionality. +.LP +.IP " 2." 4 +It supports the I/O redirection paradigm commonly employed by POSIX +programs designed to be invoked from a shell. When such a +program is the child process, it may not be designed to open files +on its own. +.LP +.IP " 3." 4 +It allows file opens that might otherwise fail or violate file ownership/access +rights if executed by the parent process. +.LP +.LP +Regarding 2. above, note that the spawn open file action provides +to \fIposix_spawn\fP() and \fIposix_spawnp\fP() the +same capability that the shell redirection operators provide to \fIsystem\fP(), +only +without the intervening execution of a shell; for example: +.sp +.RS +.nf + +\fBsystem ("myprog \fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_spawn_file_actions_destroy.3p b/man3p/posix_spawn_file_actions_destroy.3p new file mode 100644 index 000000000..17a7bd71a --- /dev/null +++ b/man3p/posix_spawn_file_actions_destroy.3p @@ -0,0 +1 @@ +.so man3p/posix_spawn_file_actions_init.3p diff --git a/man3p/posix_spawn_file_actions_init.3p b/man3p/posix_spawn_file_actions_init.3p new file mode 100644 index 000000000..94e10ac7d --- /dev/null +++ b/man3p/posix_spawn_file_actions_init.3p @@ -0,0 +1,91 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_SPAWN_FILE_ACTIONS_DESTROY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_spawn_file_actions_destroy +.SH NAME +posix_spawn_file_actions_destroy, posix_spawn_file_actions_init \- +destroy and initialize spawn file actions object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_spawn_file_actions_destroy(posix_spawn_file_actions_t * +.br +\ \ \ \ \ \ \fP \fIfile_actions\fP\fB); +.br +int posix_spawn_file_actions_init(posix_spawn_file_actions_t * +.br +\ \ \ \ \ \ \fP \fIfile_actions\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_spawn_file_actions_destroy\fP() function shall destroy +the object referenced by \fIfile_actions\fP; the object +becomes, in effect, uninitialized. An implementation may cause \fIposix_spawn_file_actions_destroy\fP() +to set the object +referenced by \fIfile_actions\fP to an invalid value. A destroyed +spawn file actions object can be reinitialized using +\fIposix_spawn_file_actions_init\fP(); the results of otherwise referencing +the object after it has been destroyed are +undefined. +.LP +The \fIposix_spawn_file_actions_init\fP() function shall initialize +the object referenced by \fIfile_actions\fP to contain no +file actions for \fIposix_spawn\fP() or \fIposix_spawnp\fP() to perform. +.LP +A spawn file actions object is as defined in \fIposix_spawn_file_actions_addclose\fP() +\&. +.LP +The effect of initializing an already initialized spawn file actions +object is undefined. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return zero; otherwise, +an error number shall be returned to indicate the +error. +.SH ERRORS +.LP +The \fIposix_spawn_file_actions_init\fP() function shall fail if: +.TP 7 +.B ENOMEM +Insufficient memory exists to initialize the spawn file actions object. +.sp +.LP +The \fIposix_spawn_file_actions_destroy\fP() function may fail if: +.TP 7 +.B EINVAL +The value specified by \fIfile_actions\fP is invalid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +These functions are part of the Spawn option and need not be provided +on all implementations. +.SH RATIONALE +.LP +Refer to the RATIONALE in \fIposix_spawn_file_actions_addclose\fP() +\&. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_spawn\fP() , \fIposix_spawnp\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_spawnattr_destroy.3p b/man3p/posix_spawnattr_destroy.3p new file mode 100644 index 000000000..8e7f069ba --- /dev/null +++ b/man3p/posix_spawnattr_destroy.3p @@ -0,0 +1 @@ +.so man3p/posix_spawnattr_init.3p diff --git a/man3p/posix_spawnattr_getflags.3p b/man3p/posix_spawnattr_getflags.3p new file mode 100644 index 000000000..3275cfee1 --- /dev/null +++ b/man3p/posix_spawnattr_getflags.3p @@ -0,0 +1,116 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_SPAWNATTR_GETFLAGS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_spawnattr_getflags +.SH NAME +posix_spawnattr_getflags, posix_spawnattr_setflags \- get and set the +spawn\-flags attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_spawnattr_getflags(const posix_spawnattr_t *restrict\fP +\fIattr\fP\fB, +.br +\ \ \ \ \ \ short *restrict\fP \fIflags\fP\fB); +.br +int posix_spawnattr_setflags(posix_spawnattr_t *\fP\fIattr\fP\fB, +short\fP \fIflags\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_spawnattr_getflags\fP() function shall obtain the value +of the \fIspawn-flags\fP attribute from the attributes +object referenced by \fIattr\fP. +.LP +The \fIposix_spawnattr_setflags\fP() function shall set the \fIspawn-flags\fP +attribute in an initialized attributes object +referenced by \fIattr\fP. +.LP +The \fIspawn-flags\fP attribute is used to indicate which process +attributes are to be changed in the new process image when +invoking \fIposix_spawn\fP() or \fIposix_spawnp\fP(). It is the bitwise-inclusive +OR of zero or more of the following +flags: +.LP +.sp +POSIX_SPAWN_RESETIDS +.br +POSIX_SPAWN_SETPGROUP +.br +POSIX_SPAWN_SETSIGDEF +.br +POSIX_SPAWN_SETSIGMASK +.br +.sp +POSIX_SPAWN_SETSCHEDPARAM +.br +POSIX_SPAWN_SETSCHEDULER +.br +.sp +.LP +These flags are defined in \fI\fP. The default value of this +attribute +shall be as if no flags were set. +.SH RETURN VALUE +.LP +Upon successful completion, \fIposix_spawnattr_getflags\fP() shall +return zero and store the value of the \fIspawn-flags\fP +attribute of \fIattr\fP into the object referenced by the \fIflags\fP +parameter; otherwise, an error number shall be returned to +indicate the error. +.LP +Upon successful completion, \fIposix_spawnattr_setflags\fP() shall +return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +The \fIposix_spawnattr_setflags\fP() function may fail if: +.TP 7 +.B EINVAL +The value of the attribute being set is not valid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +These functions are part of the Spawn option and need not be provided +on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_spawn\fP() , \fIposix_spawnattr_destroy\fP() , \fIposix_spawnattr_init\fP() +, \fIposix_spawnattr_getsigdefault\fP() , \fIposix_spawnattr_getpgroup\fP() +, \fIposix_spawnattr_getschedparam\fP() , \fIposix_spawnattr_getschedpolicy\fP() +, \fIposix_spawnattr_getsigmask\fP() , \fIposix_spawnattr_setsigdefault\fP() +, \fIposix_spawnattr_setpgroup\fP() , \fIposix_spawnattr_setschedparam\fP() +, \fIposix_spawnattr_setschedpolicy\fP() , \fIposix_spawnattr_setsigmask\fP() +, \fIposix_spawnp\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_spawnattr_getpgroup.3p b/man3p/posix_spawnattr_getpgroup.3p new file mode 100644 index 000000000..8c599a4f8 --- /dev/null +++ b/man3p/posix_spawnattr_getpgroup.3p @@ -0,0 +1,95 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_SPAWNATTR_GETPGROUP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_spawnattr_getpgroup +.SH NAME +posix_spawnattr_getpgroup, posix_spawnattr_setpgroup \- get and set +the spawn\-pgroup attribute of a spawn attributes +object (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_spawnattr_getpgroup(const posix_spawnattr_t *restrict\fP +\fIattr\fP\fB, +.br +\ \ \ \ \ \ pid_t *restrict\fP \fIpgroup\fP\fB); +.br +int posix_spawnattr_setpgroup(posix_spawnattr_t *\fP\fIattr\fP\fB, +pid_t\fP \fIpgroup\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_spawnattr_getpgroup\fP() function shall obtain the value +of the \fIspawn-pgroup\fP attribute from the attributes +object referenced by \fIattr\fP. +.LP +The \fIposix_spawnattr_setpgroup\fP() function shall set the \fIspawn-pgroup\fP +attribute in an initialized attributes object +referenced by \fIattr\fP. +.LP +The \fIspawn-pgroup\fP attribute represents the process group to be +joined by the new process image in a spawn operation (if +POSIX_SPAWN_SETPGROUP is set in the \fIspawn-flags\fP attribute). +The default value of this attribute shall be zero. +.SH RETURN VALUE +.LP +Upon successful completion, \fIposix_spawnattr_getpgroup\fP() shall +return zero and store the value of the \fIspawn-pgroup\fP +attribute of \fIattr\fP into the object referenced by the \fIpgroup\fP +parameter; otherwise, an error number shall be returned to +indicate the error. +.LP +Upon successful completion, \fIposix_spawnattr_setpgroup\fP() shall +return zero; otherwise, an error number shall be returned +to indicate the error. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +The \fIposix_spawnattr_setpgroup\fP() function may fail if: +.TP 7 +.B EINVAL +The value of the attribute being set is not valid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +These functions are part of the Spawn option and need not be provided +on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_spawn\fP() , \fIposix_spawnattr_destroy\fP() , \fIposix_spawnattr_init\fP() +, \fIposix_spawnattr_getsigdefault\fP() , \fIposix_spawnattr_getflags\fP() +, \fIposix_spawnattr_getschedparam\fP() , \fIposix_spawnattr_getschedpolicy\fP() +, \fIposix_spawnattr_getsigmask\fP() , \fIposix_spawnattr_setsigdefault\fP() +, \fIposix_spawnattr_setflags\fP() , \fIposix_spawnattr_setschedparam\fP() +, \fIposix_spawnattr_setschedpolicy\fP() , \fIposix_spawnattr_setsigmask\fP() +, \fIposix_spawnp\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_spawnattr_getschedparam.3p b/man3p/posix_spawnattr_getschedparam.3p new file mode 100644 index 000000000..87df6e2b1 --- /dev/null +++ b/man3p/posix_spawnattr_getschedparam.3p @@ -0,0 +1,101 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_SPAWNATTR_GETSCHEDPARAM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_spawnattr_getschedparam +.SH NAME +posix_spawnattr_getschedparam, posix_spawnattr_setschedparam \- get +and set the spawn\-schedparam attribute of a spawn +attributes object (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int posix_spawnattr_getschedparam(const posix_spawnattr_t * +.br +\ \ \ \ \ \ restrict\fP \fIattr\fP\fB, struct sched_param *restrict\fP +\fIschedparam\fP\fB); +.br +int posix_spawnattr_setschedparam(posix_spawnattr_t *restrict\fP \fIattr\fP\fB, +.br +\ \ \ \ \ \ const struct sched_param *restrict\fP \fIschedparam\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_spawnattr_getschedparam\fP() function shall obtain the +value of the \fIspawn-schedparam\fP attribute from the +attributes object referenced by \fIattr\fP. +.LP +The \fIposix_spawnattr_setschedparam\fP() function shall set the \fIspawn-schedparam\fP +attribute in an initialized attributes +object referenced by \fIattr\fP. +.LP +The \fIspawn-schedparam\fP attribute represents the scheduling parameters +to be assigned to the new process image in a spawn +operation (if POSIX_SPAWN_SETSCHEDULER or POSIX_SPAWN_SETSCHEDPARAM +is set in the \fIspawn-flags\fP attribute). The default value +of this attribute is unspecified. +.SH RETURN VALUE +.LP +Upon successful completion, \fIposix_spawnattr_getschedparam\fP() +shall return zero and store the value of the +\fIspawn-schedparam\fP attribute of \fIattr\fP into the object referenced +by the \fIschedparam\fP parameter; otherwise, an error +number shall be returned to indicate the error. +.LP +Upon successful completion, \fIposix_spawnattr_setschedparam\fP() +shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +The \fIposix_spawnattr_setschedparam\fP() function may fail if: +.TP 7 +.B EINVAL +The value of the attribute being set is not valid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +These functions are part of the Spawn and Process Scheduling options +and need not be provided on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_spawn\fP() , \fIposix_spawnattr_destroy\fP() , \fIposix_spawnattr_init\fP() +, \fIposix_spawnattr_getsigdefault\fP() , \fIposix_spawnattr_getflags\fP() +, \fIposix_spawnattr_getpgroup\fP() , \fIposix_spawnattr_getschedpolicy\fP() +, \fIposix_spawnattr_getsigmask\fP() , \fIposix_spawnattr_setsigdefault\fP() +, \fIposix_spawnattr_setflags\fP() , \fIposix_spawnattr_setpgroup\fP() +, \fIposix_spawnattr_setschedpolicy\fP() , \fIposix_spawnattr_setsigmask\fP() +, \fIposix_spawnp\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_spawnattr_getschedpolicy.3p b/man3p/posix_spawnattr_getschedpolicy.3p new file mode 100644 index 000000000..80a617206 --- /dev/null +++ b/man3p/posix_spawnattr_getschedpolicy.3p @@ -0,0 +1,99 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_SPAWNATTR_GETSCHEDPOLICY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_spawnattr_getschedpolicy +.SH NAME +posix_spawnattr_getschedpolicy, posix_spawnattr_setschedpolicy \- get +and set the spawn\-schedpolicy attribute of a spawn +attributes object (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int posix_spawnattr_getschedpolicy(const posix_spawnattr_t * +.br +\ \ \ \ \ \ restrict\fP \fIattr\fP\fB, int *restrict\fP \fIschedpolicy\fP\fB); +.br +int posix_spawnattr_setschedpolicy(posix_spawnattr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIschedpolicy\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_spawnattr_getschedpolicy\fP() function shall obtain the +value of the \fIspawn-schedpolicy\fP attribute from the +attributes object referenced by \fIattr\fP. +.LP +The \fIposix_spawnattr_setschedpolicy\fP() function shall set the +\fIspawn-schedpolicy\fP attribute in an initialized +attributes object referenced by \fIattr\fP. +.LP +The \fIspawn-schedpolicy\fP attribute represents the scheduling policy +to be assigned to the new process image in a spawn +operation (if POSIX_SPAWN_SETSCHEDULER is set in the \fIspawn-flags\fP +attribute). The default value of this attribute is +unspecified. +.SH RETURN VALUE +.LP +Upon successful completion, \fIposix_spawnattr_getschedpolicy\fP() +shall return zero and store the value of the +\fIspawn-schedpolicy\fP attribute of \fIattr\fP into the object referenced +by the \fIschedpolicy\fP parameter; otherwise, an +error number shall be returned to indicate the error. +.LP +Upon successful completion, \fIposix_spawnattr_setschedpolicy\fP() +shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +The \fIposix_spawnattr_setschedpolicy\fP() function may fail if: +.TP 7 +.B EINVAL +The value of the attribute being set is not valid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +These functions are part of the Spawn and Process Scheduling options +and need not be provided on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_spawn\fP() , \fIposix_spawnattr_destroy\fP() , \fIposix_spawnattr_init\fP() +, \fIposix_spawnattr_getsigdefault\fP() , \fIposix_spawnattr_getflags\fP() +, \fIposix_spawnattr_getpgroup\fP() , \fIposix_spawnattr_getschedparam\fP() +, \fIposix_spawnattr_getsigmask\fP() , \fIposix_spawnattr_setsigdefault\fP() +, \fIposix_spawnattr_setflags\fP() , \fIposix_spawnattr_setpgroup\fP() +, \fIposix_spawnattr_setschedparam\fP() , \fIposix_spawnattr_setsigmask\fP() +, \fIposix_spawnp\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_spawnattr_getsigdefault.3p b/man3p/posix_spawnattr_getsigdefault.3p new file mode 100644 index 000000000..4a25d3b4d --- /dev/null +++ b/man3p/posix_spawnattr_getsigdefault.3p @@ -0,0 +1,99 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_SPAWNATTR_GETSIGDEFAULT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_spawnattr_getsigdefault +.SH NAME +posix_spawnattr_getsigdefault, posix_spawnattr_setsigdefault \- get +and set the spawn\-sigdefault attribute of a spawn +attributes object (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int posix_spawnattr_getsigdefault(const posix_spawnattr_t * +.br +\ \ \ \ \ \ restrict\fP \fIattr\fP\fB, sigset_t *restrict\fP \fIsigdefault\fP\fB); +.br +int posix_spawnattr_setsigdefault(posix_spawnattr_t *restrict\fP \fIattr\fP\fB, +.br +\ \ \ \ \ \ const sigset_t *restrict\fP \fIsigdefault\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_spawnattr_getsigdefault\fP() function shall obtain the +value of the \fIspawn-sigdefault\fP attribute from the +attributes object referenced by \fIattr\fP. +.LP +The \fIposix_spawnattr_setsigdefault\fP() function shall set the \fIspawn-sigdefault\fP +attribute in an initialized attributes +object referenced by \fIattr\fP. +.LP +The \fIspawn-sigdefault\fP attribute represents the set of signals +to be forced to default signal handling in the new process +image (if POSIX_SPAWN_SETSIGDEF is set in the \fIspawn-flags\fP attribute) +by a spawn operation. The default value of this +attribute shall be an empty signal set. +.SH RETURN VALUE +.LP +Upon successful completion, \fIposix_spawnattr_getsigdefault\fP() +shall return zero and store the value of the +\fIspawn-sigdefault\fP attribute of \fIattr\fP into the object referenced +by the \fIsigdefault\fP parameter; otherwise, an error +number shall be returned to indicate the error. +.LP +Upon successful completion, \fIposix_spawnattr_setsigdefault\fP() +shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +The \fIposix_spawnattr_setsigdefault\fP() function may fail if: +.TP 7 +.B EINVAL +The value of the attribute being set is not valid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +These functions are part of the Spawn option and need not be provided +on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_spawn\fP() , \fIposix_spawnattr_destroy\fP() , \fIposix_spawnattr_init\fP() +, \fIposix_spawnattr_getflags\fP() , \fIposix_spawnattr_getpgroup\fP() +, \fIposix_spawnattr_getschedparam\fP() , \fIposix_spawnattr_getschedpolicy\fP() +, \fIposix_spawnattr_getsigmask\fP() , \fIposix_spawnattr_setflags\fP() +, \fIposix_spawnattr_setpgroup\fP() , \fIposix_spawnattr_setschedparam\fP() +, \fIposix_spawnattr_setschedpolicy\fP() , \fIposix_spawnattr_setsigmask\fP() +, \fIposix_spawnp\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_spawnattr_getsigmask.3p b/man3p/posix_spawnattr_getsigmask.3p new file mode 100644 index 000000000..ce81f6d97 --- /dev/null +++ b/man3p/posix_spawnattr_getsigmask.3p @@ -0,0 +1,98 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_SPAWNATTR_GETSIGMASK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_spawnattr_getsigmask +.SH NAME +posix_spawnattr_getsigmask, posix_spawnattr_setsigmask \- get and set +the spawn\-sigmask attribute of a spawn attributes +object (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int posix_spawnattr_getsigmask(const posix_spawnattr_t *restrict\fP +\fIattr\fP\fB, +.br +\ \ \ \ \ \ sigset_t *restrict\fP \fIsigmask\fP\fB); +.br +int posix_spawnattr_setsigmask(posix_spawnattr_t *restrict\fP \fIattr\fP\fB, +.br +\ \ \ \ \ \ const sigset_t *restrict\fP \fIsigmask\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_spawnattr_getsigmask\fP() function shall obtain the value +of the \fIspawn-sigmask\fP attribute from the +attributes object referenced by \fIattr\fP. +.LP +The \fIposix_spawnattr_setsigmask\fP() function shall set the \fIspawn-sigmask\fP +attribute in an initialized attributes +object referenced by \fIattr\fP. +.LP +The \fIspawn-sigmask\fP attribute represents the signal mask in effect +in the new process image of a spawn operation (if +POSIX_SPAWN_SETSIGMASK is set in the \fIspawn-flags\fP attribute). +The default value of this attribute is unspecified. +.SH RETURN VALUE +.LP +Upon successful completion, \fIposix_spawnattr_getsigmask\fP() shall +return zero and store the value of the +\fIspawn-sigmask\fP attribute of \fIattr\fP into the object referenced +by the \fIsigmask\fP parameter; otherwise, an error +number shall be returned to indicate the error. +.LP +Upon successful completion, \fIposix_spawnattr_setsigmask\fP() shall +return zero; otherwise, an error number shall be returned +to indicate the error. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +The \fIposix_spawnattr_setsigmask\fP() function may fail if: +.TP 7 +.B EINVAL +The value of the attribute being set is not valid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +These functions are part of the Spawn option and need not be provided +on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_spawn\fP() , \fIposix_spawnattr_destroy\fP() , \fIposix_spawnattr_init\fP() +, \fIposix_spawnattr_getsigdefault\fP() , \fIposix_spawnattr_getflags\fP() +, \fIposix_spawnattr_getpgroup\fP() , \fIposix_spawnattr_getschedparam\fP() +, \fIposix_spawnattr_getschedpolicy\fP() , \fIposix_spawnattr_setsigdefault\fP() +, \fIposix_spawnattr_setflags\fP() , \fIposix_spawnattr_setpgroup\fP() +, \fIposix_spawnattr_setschedparam\fP() , \fIposix_spawnattr_setschedpolicy\fP() +, \fIposix_spawnp\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_spawnattr_init.3p b/man3p/posix_spawnattr_init.3p new file mode 100644 index 000000000..b62ef67d2 --- /dev/null +++ b/man3p/posix_spawnattr_init.3p @@ -0,0 +1,122 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_SPAWNATTR_DESTROY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_spawnattr_destroy +.SH NAME +posix_spawnattr_destroy, posix_spawnattr_init \- destroy and initialize +spawn attributes object (\fBADVANCED +REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_spawnattr_destroy(posix_spawnattr_t *\fP\fIattr\fP\fB); +.br +int posix_spawnattr_init(posix_spawnattr_t *\fP\fIattr\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_spawnattr_destroy\fP() function shall destroy a spawn +attributes object. A destroyed \fIattr\fP attributes object +can be reinitialized using \fIposix_spawnattr_init\fP(); the results +of otherwise referencing the object after it has been +destroyed are undefined. An implementation may cause \fIposix_spawnattr_destroy\fP() +to set the object referenced by \fIattr\fP +to an invalid value. +.LP +The \fIposix_spawnattr_init\fP() function shall initialize a spawn +attributes object \fIattr\fP with the default value for all +of the individual attributes used by the implementation. Results are +undefined if \fIposix_spawnattr_init\fP() is called +specifying an already initialized \fIattr\fP attributes object. +.LP +A spawn attributes object is of type \fBposix_spawnattr_t\fP (defined +in \fI\fP) and is used to specify the inheritance of process +attributes across a spawn +operation. IEEE\ Std\ 1003.1-2001 does not define comparison or assignment +operators for the type +\fBposix_spawnattr_t\fP. +.LP +Each implementation shall document the individual attributes it uses +and their default values unless these values are defined by +IEEE\ Std\ 1003.1-2001. Attributes not defined by IEEE\ Std\ 1003.1-2001, +their default values, and the names of +the associated functions to get and set those attribute values are +implementation-defined. +.LP +The resulting spawn attributes object (possibly modified by setting +individual attribute values), is used to modify the behavior +of \fIposix_spawn\fP() or \fIposix_spawnp\fP(). After a spawn attributes +object has been used to spawn a process by a +call to a \fIposix_spawn\fP() or \fIposix_spawnp\fP(), any function +affecting the attributes object (including destruction) +shall not affect any process that has been spawned in this way. +.SH RETURN VALUE +.LP +Upon successful completion, \fIposix_spawnattr_destroy\fP() and \fIposix_spawnattr_init\fP() +shall return zero; otherwise, an +error number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIposix_spawnattr_init\fP() function shall fail if: +.TP 7 +.B ENOMEM +Insufficient memory exists to initialize the spawn attributes object. +.sp +.LP +The \fIposix_spawnattr_destroy\fP() function may fail if: +.TP 7 +.B EINVAL +The value specified by attr is invalid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +These functions are part of the Spawn option and need not be provided +on all implementations. +.SH RATIONALE +.LP +The original spawn interface proposed in IEEE\ Std\ 1003.1-2001 defined +the attributes that specify the inheritance of +process attributes across a spawn operation as a structure. In order +to be able to separate optional individual attributes under +their appropriate options (that is, the \fIspawn-schedparam\fP and +\fIspawn-schedpolicy\fP attributes depending upon the Process +Scheduling option), and also for extensibility and consistency with +the newer POSIX interfaces, the attributes interface has been +changed to an opaque data type. This interface now consists of the +type \fBposix_spawnattr_t\fP, representing a spawn attributes +object, together with associated functions to initialize or destroy +the attributes object, and to set or get each individual +attribute. Although the new object-oriented interface is more verbose +than the original structure, it is simple to use, more +extensible, and easy to implement. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_spawn\fP() , \fIposix_spawnattr_getsigdefault\fP() , \fIposix_spawnattr_getflags\fP() +, \fIposix_spawnattr_getpgroup\fP() , \fIposix_spawnattr_getschedparam\fP() +, \fIposix_spawnattr_getschedpolicy\fP() , \fIposix_spawnattr_getsigmask\fP() +, \fIposix_spawnattr_setsigdefault\fP() , \fIposix_spawnattr_setflags\fP() +, \fIposix_spawnattr_setpgroup\fP() , \fIposix_spawnattr_setsigmask\fP() +, \fIposix_spawnattr_setschedpolicy\fP() , \fIposix_spawnattr_setschedparam\fP() +, \fIposix_spawnp\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_spawnattr_setflags.3p b/man3p/posix_spawnattr_setflags.3p new file mode 100644 index 000000000..782ea522c --- /dev/null +++ b/man3p/posix_spawnattr_setflags.3p @@ -0,0 +1 @@ +.so man3p/posix_spawnattr_getflags.3p diff --git a/man3p/posix_spawnattr_setpgroup.3p b/man3p/posix_spawnattr_setpgroup.3p new file mode 100644 index 000000000..921fe126f --- /dev/null +++ b/man3p/posix_spawnattr_setpgroup.3p @@ -0,0 +1 @@ +.so man3p/posix_spawnattr_getpgroup.3p diff --git a/man3p/posix_spawnattr_setschedparam.3p b/man3p/posix_spawnattr_setschedparam.3p new file mode 100644 index 000000000..f55abc055 --- /dev/null +++ b/man3p/posix_spawnattr_setschedparam.3p @@ -0,0 +1 @@ +.so man3p/posix_spawnattr_getschedparam.3p diff --git a/man3p/posix_spawnattr_setschedpolicy.3p b/man3p/posix_spawnattr_setschedpolicy.3p new file mode 100644 index 000000000..05d8768f0 --- /dev/null +++ b/man3p/posix_spawnattr_setschedpolicy.3p @@ -0,0 +1 @@ +.so man3p/posix_spawnattr_getschedpolicy.3p diff --git a/man3p/posix_spawnattr_setsigdefault.3p b/man3p/posix_spawnattr_setsigdefault.3p new file mode 100644 index 000000000..b779038c8 --- /dev/null +++ b/man3p/posix_spawnattr_setsigdefault.3p @@ -0,0 +1 @@ +.so man3p/posix_spawnattr_getsigdefault.3p diff --git a/man3p/posix_spawnattr_setsigmask.3p b/man3p/posix_spawnattr_setsigmask.3p new file mode 100644 index 000000000..1bb1865d3 --- /dev/null +++ b/man3p/posix_spawnattr_setsigmask.3p @@ -0,0 +1 @@ +.so man3p/posix_spawnattr_getsigmask.3p diff --git a/man3p/posix_spawnp.3p b/man3p/posix_spawnp.3p new file mode 100644 index 000000000..2ad975dcd --- /dev/null +++ b/man3p/posix_spawnp.3p @@ -0,0 +1 @@ +.so man3p/posix_spawn.3p diff --git a/man3p/posix_trace_attr_destroy.3p b/man3p/posix_trace_attr_destroy.3p new file mode 100644 index 000000000..e94a3c05e --- /dev/null +++ b/man3p/posix_trace_attr_destroy.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_init.3p diff --git a/man3p/posix_trace_attr_getclockres.3p b/man3p/posix_trace_attr_getclockres.3p new file mode 100644 index 000000000..b26bc73ec --- /dev/null +++ b/man3p/posix_trace_attr_getclockres.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_getname.3p diff --git a/man3p/posix_trace_attr_getcreatetime.3p b/man3p/posix_trace_attr_getcreatetime.3p new file mode 100644 index 000000000..b26bc73ec --- /dev/null +++ b/man3p/posix_trace_attr_getcreatetime.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_getname.3p diff --git a/man3p/posix_trace_attr_getgenversion.3p b/man3p/posix_trace_attr_getgenversion.3p new file mode 100644 index 000000000..b26bc73ec --- /dev/null +++ b/man3p/posix_trace_attr_getgenversion.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_getname.3p diff --git a/man3p/posix_trace_attr_getinherited.3p b/man3p/posix_trace_attr_getinherited.3p new file mode 100644 index 000000000..d2d17f056 --- /dev/null +++ b/man3p/posix_trace_attr_getinherited.3p @@ -0,0 +1,228 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TRACE_ATTR_GETINHERITED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_trace_attr_getinherited +.SH NAME +posix_trace_attr_getinherited, posix_trace_attr_getlogfullpolicy, +posix_trace_attr_getstreamfullpolicy, +posix_trace_attr_setinherited, posix_trace_attr_setlogfullpolicy, +posix_trace_attr_setstreamfullpolicy \- retrieve and set the +behavior of a trace stream (\fBTRACING\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +\fP +.LP +\fBint posix_trace_attr_getinherited(const trace_attr_t *restrict\fP +\fIattr\fP\fB, +.br +\ \ \ \ \ \ int *restrict\fP \fIinheritancepolicy\fP\fB); +.br +\fP +.LP +\fBint posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict\fP +\fIattr\fP\fB, +.br +\ \ \ \ \ \ int *restrict\fP \fIlogpolicy\fP\fB); +.br +\fP +.LP +\fBint posix_trace_attr_getstreamfullpolicy(const trace_attr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ int *\fP\fIstreampolicy\fP\fB); +.br +\fP +.LP +\fBint posix_trace_attr_setinherited(trace_attr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIinheritancepolicy\fP\fB); +.br +\fP +.LP +\fBint posix_trace_attr_setlogfullpolicy(trace_attr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIlogpolicy\fP\fB); +.br +\fP +.LP +\fBint posix_trace_attr_setstreamfullpolicy(trace_attr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIstreampolicy\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_trace_attr_getinherited\fP() and \fIposix_trace_attr_setinherited\fP() +functions, respectively, shall get and set +the inheritance policy stored in the \fIinheritance\fP attribute for +traced processes across the \fIfork\fP() and \fIspawn\fP() operations. +The \fIinheritance\fP attribute of the attributes object +pointed to by the \fIattr\fP argument shall be set to one of the following +values defined by manifest constants in the \fI\fP header: +.TP 7 +POSIX_TRACE_CLOSE_FOR_CHILD +.sp +After a \fIfork\fP() or \fIspawn\fP() operation, the child shall not +be traced, and tracing +of the parent shall continue. +.TP 7 +POSIX_TRACE_INHERITED +.sp +After a \fIfork\fP() or \fIspawn\fP() operation, if the parent is +being traced, its child +shall be concurrently traced using the same trace stream. +.sp +.LP +The default value for the \fIinheritance\fP attribute is POSIX_TRACE_CLOSE_FOR_CHILD. +.LP +The \fIposix_trace_attr_getlogfullpolicy\fP() and \fIposix_trace_attr_setlogfullpolicy\fP() +functions, respectively, shall get +and set the trace log full policy stored in the \fIlog-full-policy\fP +attribute of the attributes object pointed to by the +\fIattr\fP argument. +.LP +The \fIlog-full-policy\fP attribute shall be set to one of the following +values defined by manifest constants in the \fI\fP header: +.TP 7 +POSIX_TRACE_LOOP +.sp +The trace log shall loop until the associated trace stream is stopped. +This policy means that when the trace log gets full, the +file system shall reuse the resources allocated to the oldest trace +events that were recorded. In this way, the trace log will +always contain the most recent trace events flushed. +.TP 7 +POSIX_TRACE_UNTIL_FULL +.sp +The trace stream shall be flushed to the trace log until the trace +log is full. This condition can be deduced from the +\fIposix_log_full_status\fP member status (see the \fBposix_trace_status_info\fP +structure defined in \fI\fP). The last recorded trace event +shall be the POSIX_TRACE_STOP trace +event. +.TP 7 +POSIX_TRACE_APPEND +.sp +The associated trace stream shall be flushed to the trace log without +log size limitation. If the application specifies +POSIX_TRACE_APPEND, the implementation shall ignore the \fIlog-max-size\fP +attribute. +.sp +.LP +The default value for the \fIlog-full-policy\fP attribute is POSIX_TRACE_LOOP. +.LP +The \fIposix_trace_attr_getstreamfullpolicy\fP() and \fIposix_trace_attr_setstreamfullpolicy\fP() +functions, respectively, +shall get and set the trace stream full policy stored in the \fIstream-full-policy\fP +attribute of the attributes object pointed +to by the \fIattr\fP argument. +.LP +The \fIstream-full-policy\fP attribute shall be set to one of the +following values defined by manifest constants in the \fI\fP +header: +.TP 7 +POSIX_TRACE_LOOP +.sp +The trace stream shall loop until explicitly stopped by the \fIposix_trace_stop\fP() +function. This policy means that when the trace stream is full, +the trace system shall reuse the resources allocated to the oldest +trace events recorded. In this way, the trace stream will always +contain the most recent trace events recorded. +.TP 7 +POSIX_TRACE_UNTIL_FULL +.sp +The trace stream will run until the trace stream resources are exhausted. +Then the trace stream will stop. This condition can be +deduced from \fIposix_stream_status\fP and \fIposix_stream_full_status\fP +(see the \fBposix_trace_status_info\fP structure +defined in \fI\fP). When this trace stream is read, a POSIX_TRACE_STOP +trace +event shall be reported after reporting the last recorded trace event. +The trace system shall reuse the resources allocated to any +trace events already reported-see the \fIposix_trace_getnext_event\fP(), +\fIposix_trace_trygetnext_event\fP(), and \fIposix_trace_timedgetnext_event\fP() +functions-or already flushed for an +active trace stream with log if the Trace Log option is supported; +see the \fIposix_trace_flush\fP() function. The trace system shall +restart the trace stream when +it is empty and may restart it sooner. A POSIX_TRACE_START trace event +shall be reported before reporting the next recorded trace +event. +.TP 7 +POSIX_TRACE_FLUSH +.sp +If the Trace Log option is supported, this policy is identical to +the POSIX_TRACE_UNTIL_FULL trace stream full policy except that +the trace stream shall be flushed regularly as if \fIposix_trace_flush\fP() +had +been explicitly called. Defining this policy for an active trace stream +without log shall be invalid. +.sp +.LP +The default value for the \fIstream-full-policy\fP attribute shall +be POSIX_TRACE_LOOP for an active trace stream without +log. +.LP +If the Trace Log option is supported, the default value for the \fIstream-full-policy\fP +attribute shall be POSIX_TRACE_FLUSH for +an active trace stream with log. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error +number. +.LP +If successful, the \fIposix_trace_attr_getinherited\fP() function +shall store the \fIinheritance\fP attribute value in the object +pointed to by \fIinheritancepolicy\fP. Otherwise, the content of this +object is undefined. +.LP +If successful, the \fIposix_trace_attr_getlogfullpolicy\fP() function +shall store the \fIlog-full-policy\fP attribute value in +the object pointed to by \fIlogpolicy\fP. Otherwise, the content of +this object is undefined. +.LP +If successful, the \fIposix_trace_attr_getstreamfullpolicy\fP() function +shall store the \fIstream-full-policy\fP attribute +value in the object pointed to by \fIstreampolicy\fP. Otherwise, the +content of this object is undefined. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +.B EINVAL +The value specified by at least one of the arguments is invalid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfork\fP() , \fIposix_trace_attr_init\fP() , \fIposix_trace_create\fP() +, \fIposix_trace_flush\fP() , \fIposix_trace_get_attr\fP() , \fIposix_trace_getnext_event\fP() +, \fIposix_trace_start\fP() , \fIposix_trace_timedgetnext_event\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_trace_attr_getlogfullpolicy.3p b/man3p/posix_trace_attr_getlogfullpolicy.3p new file mode 100644 index 000000000..9d412639a --- /dev/null +++ b/man3p/posix_trace_attr_getlogfullpolicy.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_getinherited.3p diff --git a/man3p/posix_trace_attr_getlogsize.3p b/man3p/posix_trace_attr_getlogsize.3p new file mode 100644 index 000000000..812629b3d --- /dev/null +++ b/man3p/posix_trace_attr_getlogsize.3p @@ -0,0 +1,207 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TRACE_ATTR_GETLOGSIZE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_trace_attr_getlogsize +.SH NAME +posix_trace_attr_getlogsize, posix_trace_attr_getmaxdatasize, posix_trace_attr_getmaxsystemeventsize, +posix_trace_attr_getmaxusereventsize, posix_trace_attr_getstreamsize, +posix_trace_attr_setlogsize, posix_trace_attr_setmaxdatasize, +posix_trace_attr_setstreamsize \- retrieve and set trace stream size +attributes (\fBTRACING\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +\fP +.LP +\fBint posix_trace_attr_getlogsize(const trace_attr_t *restrict\fP +\fIattr\fP\fB, +.br +\ \ \ \ \ \ size_t *restrict\fP \fIlogsize\fP\fB); +.br +\fP +.LP +\fBint posix_trace_attr_getmaxdatasize(const trace_attr_t *restrict\fP +\fIattr\fP\fB, +.br +\ \ \ \ \ \ size_t *restrict\fP \fImaxdatasize\fP\fB); +.br +int posix_trace_attr_getmaxsystemeventsize( +.br +\ \ \ \ \ \ const trace_attr_t *restrict\fP \fIattr\fP\fB, +.br +\ \ \ \ \ \ size_t *restrict\fP \fIeventsize\fP\fB); +.br +int posix_trace_attr_getmaxusereventsize( +.br +\ \ \ \ \ \ const trace_attr_t *restrict\fP \fIattr\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIdata_len\fP\fB, size_t *restrict\fP \fIeventsize\fP\fB); +.br +int posix_trace_attr_getstreamsize(const trace_attr_t *restrict\fP +\fIattr\fP\fB, +.br +\ \ \ \ \ \ size_t *restrict\fP \fIstreamsize\fP\fB); +.br +\fP +.LP +\fBint posix_trace_attr_setlogsize(trace_attr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIlogsize\fP\fB); +.br +\fP +.LP +\fBint posix_trace_attr_setmaxdatasize(trace_attr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fImaxdatasize\fP\fB); +.br +int posix_trace_attr_setstreamsize(trace_attr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIstreamsize\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_trace_attr_getlogsize\fP() function shall copy the log +size, in bytes, from the \fIlog-max-size\fP attribute of the +attributes object pointed to by the \fIattr\fP argument into the variable +pointed to by the \fIlogsize\fP argument. This log size +is the maximum total of bytes that shall be allocated for system and +user trace events in the trace log. The default value for the +\fIlog-max-size\fP attribute is implementation-defined. +.LP +The \fIposix_trace_attr_setlogsize\fP() function shall set the maximum +allowed size, in bytes, in the \fIlog-max-size\fP +attribute of the attributes object pointed to by the \fIattr\fP argument, +using the size value supplied by the \fIlogsize\fP +argument. +.LP +The trace log size shall be used if the \fIlog-full-policy\fP attribute +is set to POSIX_TRACE_LOOP or POSIX_TRACE_UNTIL_FULL. +If the \fIlog-full-policy\fP attribute is set to POSIX_TRACE_APPEND, +the implementation shall ignore the \fIlog-max-size\fP +attribute. +.LP +The \fIposix_trace_attr_getmaxdatasize\fP() function shall copy the +maximum user trace event data size, in bytes, from the +\fImax-data-size\fP attribute of the attributes object pointed to +by the \fIattr\fP argument into the variable pointed to by the +\fImaxdatasize\fP argument. The default value for the \fImax-data-size\fP +attribute is implementation-defined. +.LP +The \fIposix_trace_attr_getmaxsystemeventsize\fP() function shall +calculate the maximum memory size, in bytes, required to +store a single system trace event. This value is calculated for the +trace stream attributes object pointed to by the \fIattr\fP +argument and is returned in the variable pointed to by the \fIeventsize\fP +argument. +.LP +The values returned as the maximum memory sizes of the user and system +trace events shall be such that if the sum of the maximum +memory sizes of a set of the trace events that may be recorded in +a trace stream is less than or equal to the +\fIstream-min-size\fP attribute of that trace stream, the system provides +the necessary resources for recording all those trace +events, without loss. +.LP +The \fIposix_trace_attr_getmaxusereventsize\fP() function shall calculate +the maximum memory size, in bytes, required to store +a single user trace event generated by a call to \fIposix_trace_event\fP() +with +a \fIdata_len\fP parameter equal to the \fIdata_len\fP value specified +in this call. This value is calculated for the trace +stream attributes object pointed to by the \fIattr\fP argument and +is returned in the variable pointed to by the \fIeventsize\fP +argument. +.LP +The \fIposix_trace_attr_getstreamsize\fP() function shall copy the +stream size, in bytes, from the \fIstream-min-size\fP +attribute of the attributes object pointed to by the \fIattr\fP argument +into the variable pointed to by the \fIstreamsize\fP +argument. +.LP +This stream size is the current total memory size reserved for system +and user trace events in the trace stream. The default +value for the \fIstream-min-size\fP attribute is implementation-defined. +The stream size refers to memory used to store trace +event records. Other stream data (for example, trace attribute values) +shall not be included in this size. +.LP +The \fIposix_trace_attr_setmaxdatasize\fP() function shall set the +maximum allowed size, in bytes, in the \fImax-data-size\fP +attribute of the attributes object pointed to by the \fIattr\fP argument, +using the size value supplied by the \fImaxdatasize\fP +argument. This maximum size is the maximum allowed size for the user +data argument which may be passed to \fIposix_trace_event\fP(). The +implementation shall be allowed to truncate data passed +to \fItrace_user_event\fP which is longer than \fImaxdatasize\fP. +.LP +The \fIposix_trace_attr_setstreamsize\fP() function shall set the +minimum allowed size, in bytes, in the \fIstream-min-size\fP +attribute of the attributes object pointed to by the \fIattr\fP argument, +using the size value supplied by the \fIstreamsize\fP +argument. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error +number. +.LP +The \fIposix_trace_attr_getlogsize\fP() function stores the maximum +trace log allowed size in the object pointed to by +\fIlogsize\fP, if successful. +.LP +The \fIposix_trace_attr_getmaxdatasize\fP() function stores the maximum +trace event record memory size in the object pointed to +by \fImaxdatasize\fP, if successful. +.LP +The \fIposix_trace_attr_getmaxsystemeventsize\fP() function stores +the maximum memory size to store a single system trace event +in the object pointed to by \fIeventsize\fP, if successful. +.LP +The \fIposix_trace_attr_getmaxusereventsize\fP() function stores the +maximum memory size to store a single user trace event in +the object pointed to by \fIeventsize\fP, if successful. +.LP +The \fIposix_trace_attr_getstreamsize\fP() function stores the maximum +trace stream allowed size in the object pointed to by +\fIstreamsize\fP, if successful. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +.B EINVAL +The value specified by one of the arguments is invalid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_trace_attr_init\fP() , \fIposix_trace_create\fP() , \fIposix_trace_event\fP() +, \fIposix_trace_get_attr\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_trace_attr_getmaxdatasize.3p b/man3p/posix_trace_attr_getmaxdatasize.3p new file mode 100644 index 000000000..bac62e2a9 --- /dev/null +++ b/man3p/posix_trace_attr_getmaxdatasize.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_getlogsize.3p diff --git a/man3p/posix_trace_attr_getmaxsystemeventsize.3p b/man3p/posix_trace_attr_getmaxsystemeventsize.3p new file mode 100644 index 000000000..bac62e2a9 --- /dev/null +++ b/man3p/posix_trace_attr_getmaxsystemeventsize.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_getlogsize.3p diff --git a/man3p/posix_trace_attr_getmaxusereventsize.3p b/man3p/posix_trace_attr_getmaxusereventsize.3p new file mode 100644 index 000000000..bac62e2a9 --- /dev/null +++ b/man3p/posix_trace_attr_getmaxusereventsize.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_getlogsize.3p diff --git a/man3p/posix_trace_attr_getname.3p b/man3p/posix_trace_attr_getname.3p new file mode 100644 index 000000000..aa0586b98 --- /dev/null +++ b/man3p/posix_trace_attr_getname.3p @@ -0,0 +1,141 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TRACE_ATTR_GETCLOCKRES" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_trace_attr_getclockres +.SH NAME +posix_trace_attr_getclockres, posix_trace_attr_getcreatetime, posix_trace_attr_getgenversion, +posix_trace_attr_getname, +posix_trace_attr_setname \- retrieve and set information about a trace +stream (\fBTRACING\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int posix_trace_attr_getclockres(const trace_attr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ struct timespec *\fP\fIresolution\fP\fB); +.br +int posix_trace_attr_getcreatetime(const trace_attr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ struct timespec *\fP\fIcreatetime\fP\fB); +.br +.sp +.sp +#include +.br +int posix_trace_attr_getgenversion(const trace_attr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ char *\fP\fIgenversion\fP\fB); +.br +int posix_trace_attr_getname(const trace_attr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ char *\fP\fItracename\fP\fB); +.br +int posix_trace_attr_setname(trace_attr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ const char *\fP\fItracename\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_trace_attr_getclockres\fP() function shall copy the clock +resolution of the clock used to generate timestamps from +the \fIclock-resolution\fP attribute of the attributes object pointed +to by the \fIattr\fP argument into the structure pointed to +by the \fIresolution\fP argument. +.LP +The \fIposix_trace_attr_getcreatetime\fP() function shall copy the +trace stream creation time from the \fIcreation-time\fP +attribute of the attributes object pointed to by the \fIattr\fP argument +into the structure pointed to by the \fIcreatetime\fP +argument. The \fIcreation-time\fP attribute shall represent the time +of creation of the trace stream. +.LP +The \fIposix_trace_attr_getgenversion\fP() function shall copy the +string containing version information from the +\fIgeneration-version\fP attribute of the attributes object pointed +to by the \fIattr\fP argument into the string pointed to by +the \fIgenversion\fP argument. The \fIgenversion\fP argument shall +be the address of a character array which can store at least +{TRACE_NAME_MAX} characters. +.LP +The \fIposix_trace_attr_getname\fP() function shall copy the string +containing the trace name from the \fItrace-name\fP +attribute of the attributes object pointed to by the \fIattr\fP argument +into the string pointed to by the \fItracename\fP +argument. The \fItracename\fP argument shall be the address of a character +array which can store at least {TRACE_NAME_MAX} +characters. +.LP +The \fIposix_trace_attr_setname\fP() function shall set the name in +the \fItrace-name\fP attribute of the attributes object +pointed to by the \fIattr\fP argument, using the trace name string +supplied by the \fItracename\fP argument. If the supplied +string contains more than {TRACE_NAME_MAX} characters, the name copied +into the \fItrace-name\fP attribute may be truncated to one +less than the length of {TRACE_NAME_MAX} characters. The default value +is a null string. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error +number. +.LP +If successful, the \fIposix_trace_attr_getclockres\fP() function stores +the \fIclock-resolution\fP attribute value in the +object pointed to by \fIresolution\fP. Otherwise, the content of this +object is unspecified. +.LP +If successful, the \fIposix_trace_attr_getcreatetime\fP() function +stores the trace stream creation time in the object pointed +to by \fIcreatetime\fP. Otherwise, the content of this object is unspecified. +.LP +If successful, the \fIposix_trace_attr_getgenversion\fP() function +stores the trace version information in the string pointed +to by \fIgenversion\fP. Otherwise, the content of this string is unspecified. +.LP +If successful, the \fIposix_trace_attr_getname\fP() function stores +the trace name in the string pointed to by +\fItracename\fP. Otherwise, the content of this string is unspecified. +.SH ERRORS +.LP +The \fIposix_trace_attr_getclockres\fP(), \fIposix_trace_attr_getcreatetime\fP(), +\fIposix_trace_attr_getgenversion\fP(), and +\fIposix_trace_attr_getname\fP() functions may fail if: +.TP 7 +.B EINVAL +The value specified by one of the arguments is invalid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_trace_attr_init\fP() , \fIposix_trace_create\fP() , \fIposix_trace_get_attr\fP() +, +\fIuname\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_trace_attr_getstreamfullpolicy.3p b/man3p/posix_trace_attr_getstreamfullpolicy.3p new file mode 100644 index 000000000..9d412639a --- /dev/null +++ b/man3p/posix_trace_attr_getstreamfullpolicy.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_getinherited.3p diff --git a/man3p/posix_trace_attr_getstreamsize.3p b/man3p/posix_trace_attr_getstreamsize.3p new file mode 100644 index 000000000..bac62e2a9 --- /dev/null +++ b/man3p/posix_trace_attr_getstreamsize.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_getlogsize.3p diff --git a/man3p/posix_trace_attr_init.3p b/man3p/posix_trace_attr_init.3p new file mode 100644 index 000000000..851a5e3bb --- /dev/null +++ b/man3p/posix_trace_attr_init.3p @@ -0,0 +1,99 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TRACE_ATTR_DESTROY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_trace_attr_destroy +.SH NAME +posix_trace_attr_destroy, posix_trace_attr_init \- destroy and initialize +the trace stream attributes object +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_trace_attr_destroy(trace_attr_t *\fP\fIattr\fP\fB); +.br +int posix_trace_attr_init(trace_attr_t *\fP\fIattr\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_trace_attr_destroy\fP() function shall destroy an initialized +trace attributes object. A destroyed \fIattr\fP +attributes object can be reinitialized using \fIposix_trace_attr_init\fP(); +the results of otherwise referencing the object after +it has been destroyed are undefined. +.LP +The \fIposix_trace_attr_init\fP() function shall initialize a trace +attributes object \fIattr\fP with the default value for +all of the individual attributes used by a given implementation. The +read-only \fIgeneration-version\fP and +\fIclock-resolution\fP attributes of the newly initialized trace attributes +object shall be set to their appropriate values (see +\fITrace Stream Attributes\fP ). +.LP +Results are undefined if \fIposix_trace_attr_init\fP() is called specifying +an already initialized \fIattr\fP attributes +object. +.LP +Implementations may add extensions to the trace attributes object +structure as permitted in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 2, Conformance. +.LP +The resulting attributes object (possibly modified by setting individual +attributes values), when used by \fIposix_trace_create\fP(), defines +the attributes of the trace stream created. A +single attributes object can be used in multiple calls to \fIposix_trace_create\fP(). +After one or more trace streams have been created using an +attributes object, any function affecting that attributes object, +including destruction, shall not affect any trace stream +previously created. An initialized attributes object also serves to +receive the attributes of an existing trace stream or trace log +when calling the \fIposix_trace_get_attr\fP() function. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error +number. +.SH ERRORS +.LP +The \fIposix_trace_attr_destroy\fP() function may fail if: +.TP 7 +.B EINVAL +The value of \fIattr\fP is invalid. +.sp +.LP +The \fIposix_trace_attr_init\fP() function shall fail if: +.TP 7 +.B ENOMEM +Insufficient memory exists to initialize the trace attributes object. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_trace_create\fP() , \fIposix_trace_get_attr\fP() , \fIuname\fP() +, the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_trace_attr_setinherited.3p b/man3p/posix_trace_attr_setinherited.3p new file mode 100644 index 000000000..9d412639a --- /dev/null +++ b/man3p/posix_trace_attr_setinherited.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_getinherited.3p diff --git a/man3p/posix_trace_attr_setlogfullpolicy.3p b/man3p/posix_trace_attr_setlogfullpolicy.3p new file mode 100644 index 000000000..9d412639a --- /dev/null +++ b/man3p/posix_trace_attr_setlogfullpolicy.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_getinherited.3p diff --git a/man3p/posix_trace_attr_setlogsize.3p b/man3p/posix_trace_attr_setlogsize.3p new file mode 100644 index 000000000..bac62e2a9 --- /dev/null +++ b/man3p/posix_trace_attr_setlogsize.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_getlogsize.3p diff --git a/man3p/posix_trace_attr_setmaxdatasize.3p b/man3p/posix_trace_attr_setmaxdatasize.3p new file mode 100644 index 000000000..bac62e2a9 --- /dev/null +++ b/man3p/posix_trace_attr_setmaxdatasize.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_getlogsize.3p diff --git a/man3p/posix_trace_attr_setname.3p b/man3p/posix_trace_attr_setname.3p new file mode 100644 index 000000000..b26bc73ec --- /dev/null +++ b/man3p/posix_trace_attr_setname.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_getname.3p diff --git a/man3p/posix_trace_attr_setstreamfullpolicy.3p b/man3p/posix_trace_attr_setstreamfullpolicy.3p new file mode 100644 index 000000000..9d412639a --- /dev/null +++ b/man3p/posix_trace_attr_setstreamfullpolicy.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_getinherited.3p diff --git a/man3p/posix_trace_attr_setstreamsize.3p b/man3p/posix_trace_attr_setstreamsize.3p new file mode 100644 index 000000000..bac62e2a9 --- /dev/null +++ b/man3p/posix_trace_attr_setstreamsize.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_attr_getlogsize.3p diff --git a/man3p/posix_trace_clear.3p b/man3p/posix_trace_clear.3p new file mode 100644 index 000000000..d3d29d661 --- /dev/null +++ b/man3p/posix_trace_clear.3p @@ -0,0 +1,98 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TRACE_CLEAR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_trace_clear +.SH NAME +posix_trace_clear \- clear trace stream and trace log (\fBTRACING\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int posix_trace_clear(trace_id_t\fP \fItrid\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_trace_clear\fP() function shall reinitialize the trace +stream identified by the argument \fItrid\fP as if it were +returning from the \fIposix_trace_create\fP() function, except that +the same +allocated resources shall be reused, the mapping of trace event type +identifiers to trace event names shall be unchanged, and the +trace stream status shall remain unchanged (that is, if it was running, +it remains running and if it was suspended, it remains +suspended). +.LP +All trace events in the trace stream recorded before the call to \fIposix_trace_clear\fP() +shall be lost. The +\fIposix_stream_full_status\fP status shall be set to POSIX_TRACE_NOT_FULL. +There is no guarantee that all trace events that +occurred during the \fIposix_trace_clear\fP() call are recorded; the +behavior with respect to trace points that may occur during +this call is unspecified. +.LP +If the Trace Log option is supported and the trace stream has been +created with a log, the \fIposix_trace_clear\fP() function +shall reinitialize the trace stream with the same behavior as if the +trace stream was created without the log, plus it shall +reinitialize the trace log associated with the trace stream identified +by the argument \fItrid\fP as if it were returning from the +\fIposix_trace_create_withlog\fP() function, except that the same +allocated resources, for the trace log, may be reused and the associated +trace stream status remains unchanged. The first trace +event recorded in the trace log after the call to \fIposix_trace_clear\fP() +shall be the same as the first trace event recorded in +the active trace stream after the call to \fIposix_trace_clear\fP(). +The \fIposix_log_full_status\fP status shall be set to +POSIX_TRACE_NOT_FULL. There is no guarantee that all trace events +that occurred during the \fIposix_trace_clear\fP() call are +recorded in the trace log; the behavior with respect to trace points +that may occur during this call is unspecified. If the log +full policy is POSIX_TRACE_APPEND, the effect of a call to this function +is unspecified for the trace log associated with the trace +stream identified by the \fItrid\fP argument. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIposix_trace_clear\fP() function +shall return a value of zero. Otherwise, it shall return the +corresponding error number. +.SH ERRORS +.LP +The \fIposix_trace_clear\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of the \fItrid\fP argument does not correspond to an active +trace stream. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_trace_attr_init\fP() , \fIposix_trace_create\fP() , \fIposix_trace_flush\fP() +, \fIposix_trace_get_attr\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_trace_close.3p b/man3p/posix_trace_close.3p new file mode 100644 index 000000000..a42c3abb4 --- /dev/null +++ b/man3p/posix_trace_close.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_open.3p diff --git a/man3p/posix_trace_create.3p b/man3p/posix_trace_create.3p new file mode 100644 index 000000000..4454247b3 --- /dev/null +++ b/man3p/posix_trace_create.3p @@ -0,0 +1,381 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TRACE_CREATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_trace_create +.SH NAME +posix_trace_create, posix_trace_create_withlog, posix_trace_flush, +posix_trace_shutdown \- trace stream initialization, +flush, and shutdown from a process (\fBTRACING\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int posix_trace_create(pid_t\fP \fIpid\fP\fB, +.br +\ \ \ \ \ \ const trace_attr_t *restrict\fP \fIattr\fP\fB, +.br +\ \ \ \ \ \ trace_id_t *restrict\fP \fItrid\fP\fB); +.br +\fP +.LP +\fBint posix_trace_create_withlog(pid_t\fP \fIpid\fP\fB, +.br +\ \ \ \ \ \ const trace_attr_t *restrict\fP \fIattr\fP\fB, int\fP +\fIfile_desc\fP\fB, +.br +\ \ \ \ \ \ trace_id_t *restrict\fP \fItrid\fP\fB); +.br +int posix_trace_flush(trace_id_t\fP \fItrid\fP\fB); +.br +\fP +.LP +\fBint posix_trace_shutdown(trace_id_t\fP \fItrid\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_trace_create\fP() function shall create an active trace +stream. It allocates all the resources needed by the trace +stream being created for tracing the process specified by \fIpid\fP +in accordance with the \fIattr\fP argument. The \fIattr\fP +argument represents the initial attributes of the trace stream and +shall have been initialized by the function \fIposix_trace_attr_init\fP() +prior to the \fIposix_trace_create\fP() call. If the +argument \fIattr\fP is NULL, the default attributes shall be used. +The \fIattr\fP attributes object shall be manipulated through +a set of functions described in the \fIposix_trace_attr\fP family +of functions. If the attributes of the object pointed to by +\fIattr\fP are modified later, the attributes of the trace stream +shall not be affected. The \fIcreation-time\fP attribute of the +newly created trace stream shall be set to the value of the system +clock, if the Timers option is not supported, or to the value of +the CLOCK_REALTIME clock, if the Timers option is supported. +.LP +The \fIpid\fP argument represents the target process to be traced. +If the process executing this function does not have +appropriate privileges to trace the process identified by \fIpid\fP, +an error shall be returned. If the \fIpid\fP argument is +zero, the calling process shall be traced. +.LP +The \fIposix_trace_create\fP() function shall store the trace stream +identifier of the new trace stream in the object pointed +to by the \fItrid\fP argument. This trace stream identifier shall +be used in subsequent calls to control tracing. The \fItrid\fP +argument may only be used by the following functions: +.TS C +center; lw(39) lw(39). +T{ +.br +\fIposix_trace_clear\fP() +.br +\fIposix_trace_eventid_equal\fP() +.br +\fIposix_trace_eventid_get_name\fP() +.br +\fIposix_trace_eventtypelist_getnext_id\fP() +.br +\fIposix_trace_eventtypelist_rewind\fP() +.br +\fIposix_trace_get_attr\fP() +.br +\fIposix_trace_get_status\fP() +.br +\ +T} T{ +.br +\fIposix_trace_getnext_event\fP() +.br +\fIposix_trace_shutdown\fP() +.br +\fIposix_trace_start\fP() +.br +\fIposix_trace_stop\fP() +.br +\fIposix_trace_timedgetnext_event\fP() +.br +\fIposix_trace_trid_eventid_open\fP() +.br +\fIposix_trace_trygetnext_event\fP() +.br +\ +T} +.TE +.LP +If the Trace Event Filter option is supported, the following additional +functions may use the \fItrid\fP argument: +.TS C +center; l2 l. +\fIposix_trace_get_filter\fP() \ \fIposix_trace_set_filter\fP() \ +.TE +.LP +In particular, notice that the operations normally used by a trace +analyzer process, such as \fIposix_trace_rewind\fP() or \fIposix_trace_close\fP(), +cannot be invoked using the trace stream identifier returned +by the \fIposix_trace_create\fP() function. +.LP +A trace stream shall be created in a suspended state. \ If the Trace +Event Filter option is supported, its trace event +type filter shall be empty. +.LP +The \fIposix_trace_create\fP() function may be called multiple times +from the same or different processes, with the system-wide +limit indicated by the runtime invariant value {TRACE_SYS_MAX}, which +has the minimum value {_POSIX_TRACE_SYS_MAX}. +.LP +The trace stream identifier returned by the \fIposix_trace_create\fP() +function in the argument pointed to by \fItrid\fP is +valid only in the process that made the function call. If it is used +from another process, that is a child process, in functions +defined in IEEE\ Std\ 1003.1-2001, these functions shall return with +the error [EINVAL]. +.LP +The \fIposix_trace_create_withlog\fP() function shall be equivalent +to \fIposix_trace_create\fP(), except that it associates a +trace log with this stream. The \fIfile_desc\fP argument shall be +the file descriptor designating the trace log destination. The +function shall fail if this file descriptor refers to a file with +a file type that is not compatible with the log policy associated +with the trace log. The list of the appropriate file types that are +compatible with each log policy is implementation-defined. +.LP +The \fIposix_trace_create_withlog\fP() function shall return in the +parameter pointed to by \fItrid\fP the trace stream +identifier, which uniquely identifies the newly created trace stream, +and shall be used in subsequent calls to control tracing. The +\fItrid\fP argument may only be used by the following functions: +.TS C +center; lw(39) lw(39). +T{ +.br +\fIposix_trace_clear\fP() +.br +\fIposix_trace_eventid_equal\fP() +.br +\fIposix_trace_eventid_get_name\fP() +.br +\fIposix_trace_eventtypelist_getnext_id\fP() +.br +\fIposix_trace_eventtypelist_rewind\fP() +.br +\fIposix_trace_flush\fP() +.br +\fIposix_trace_get_attr\fP() +.br +\fIposix_trace_get_status\fP() +.br +\ +T} T{ +.br +\fIposix_trace_getnext_event\fP() +.br +\fIposix_trace_shutdown\fP() +.br +\fIposix_trace_start\fP() +.br +\fIposix_trace_stop\fP() +.br +\fIposix_trace_timedgetnext_event\fP() +.br +\fIposix_trace_trid_eventid_open\fP() +.br +\fIposix_trace_trygetnext_event\fP() +.br +\ +T} +.TE +.LP +If the Trace Event Filter option is supported, the following additional +functions may use the \fItrid\fP argument: +.TS C +center; l2 l. +\fIposix_trace_get_filter\fP() \ \fIposix_trace_set_filter\fP() \ +.TE +.LP +In particular, notice that the operations normally used by a trace +analyzer process, such as \fIposix_trace_rewind\fP() or \fIposix_trace_close\fP(), +cannot be invoked using the trace stream identifier returned +by the \fIposix_trace_create_withlog\fP() function. +.LP +The \fIposix_trace_flush\fP() function shall initiate a flush operation +which copies the contents of the trace stream +identified by the argument \fItrid\fP into the trace log associated +with the trace stream at the creation time. If no trace log +has been associated with the trace stream pointed to by \fItrid\fP, +this function shall return an error. The termination of the +flush operation can be polled by the \fIposix_trace_get_status\fP() +function. During the flush operation, it shall be possible to trace +new trace events up to the point when the trace stream becomes +full. After flushing is completed, the space used by the flushed trace +events shall be available for tracing new trace events. +.LP +If flushing the trace stream causes the resulting trace log to become +full, the trace log full policy shall be applied. If the +trace \fIlog-full-policy\fP attribute is set, the following occurs: +.TP 7 +POSIX_TRACE_UNTIL_FULL +.sp +The trace events that have not yet been flushed shall be discarded. +.TP 7 +POSIX_TRACE_LOOP +.sp +The trace events that have not yet been flushed shall be written to +the beginning of the trace log, overwriting previous trace +events stored there. +.TP 7 +POSIX_TRACE_APPEND +.sp +The trace events that have not yet been flushed shall be appended +to the trace log. +.sp +.LP +The \fIposix_trace_shutdown\fP() function shall stop the tracing of +trace events in the trace stream identified by \fItrid\fP, +as if \fIposix_trace_stop\fP() had been invoked. The +\fIposix_trace_shutdown\fP() function shall free all the resources +associated with the trace stream. +.LP +The \fIposix_trace_shutdown\fP() function shall not return until all +the resources associated with the trace stream have been +freed. When the \fIposix_trace_shutdown\fP() function returns, the +\fItrid\fP argument becomes an invalid trace stream +identifier. A call to this function shall unconditionally deallocate +the resources regardless of whether all trace events have been +retrieved by the analyzer process. Any thread blocked on one of the +\fItrace_getnext_event\fP() functions (which specified this +\fItrid\fP) before this call is unblocked with the error [EINVAL]. +.LP +If the process exits, invokes a member of the \fIexec\fP family of +functions, or is +terminated, the trace streams that the process had created and that +have not yet been shut down, shall be automatically shut down +as if an explicit call were made to the \fIposix_trace_shutdown\fP() +function. +.LP +For an active trace stream with log, when the \fIposix_trace_shutdown\fP() +function is called, all trace events that have not yet +been flushed to the trace log shall be flushed, as in the \fIposix_trace_flush\fP() +function, and the trace log shall be +closed. +.LP +When a trace log is closed, all the information that may be retrieved +later from the trace log through the trace interface shall +have been written to the trace log. This information includes the +trace attributes, the list of trace event types (with the mapping +between trace event names and trace event type identifiers), and the +trace status. +.LP +In addition, unspecified information shall be written to the trace +log to allow detection of a valid trace log during the \fIposix_trace_open\fP() +operation. +.LP +The \fIposix_trace_shutdown\fP() function shall not return until all +trace events have been flushed. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error +number. +.LP +The \fIposix_trace_create\fP() and \fIposix_trace_create_withlog\fP() +\ functions store the trace stream identifier value in the object +pointed to by \fItrid\fP, if +successful. +.SH ERRORS +.LP +The \fIposix_trace_create\fP() and \fIposix_trace_create_withlog\fP() +\ functions shall fail if: +.TP 7 +.B EAGAIN +No more trace streams can be started now. {TRACE_SYS_MAX} has been +exceeded. +.TP 7 +.B EINTR +The operation was interrupted by a signal. No trace stream was created. +.TP 7 +.B EINVAL +One or more of the trace parameters specified by the \fIattr\fP parameter +is invalid. +.TP 7 +.B ENOMEM +The implementation does not currently have sufficient memory to create +the trace stream with the specified parameters. +.TP 7 +.B EPERM +The caller does not have appropriate privilege to trace the process +specified by \fIpid\fP. +.TP 7 +.B ESRCH +The \fIpid\fP argument does not refer to an existing process. +.sp +.LP +The \fIposix_trace_create_withlog\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfile_desc\fP argument is not a valid file descriptor open for +writing. +.TP 7 +.B EINVAL +The \fIfile_desc\fP argument refers to a file with a file type that +does not support the log policy associated with the trace +log. +.TP 7 +.B ENOSPC +No space left on device. The device corresponding to the argument +\fIfile_desc\fP does not contain the space required to +create this trace log. +.sp +.LP +The \fIposix_trace_flush\fP() \ and +\fIposix_trace_shutdown\fP() functions shall fail if: +.TP 7 +.B EINVAL +The value of the \fItrid\fP argument does not correspond to an active +trace stream with log. +.TP 7 +.B EFBIG +The trace log file has attempted to exceed an implementation-defined +maximum file size. +.TP 7 +.B ENOSPC +No space left on device. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclock_getres\fP() , \fIexec\fP() , \fIposix_trace_attr_init\fP() +, \fIposix_trace_clear\fP() , \fIposix_trace_close\fP() , \fIposix_trace_eventid_equal\fP() +, \fIposix_trace_eventtypelist_getnext_id\fP() , \fIposix_trace_flush\fP() +, \fIposix_trace_get_attr\fP() , +\fIposix_trace_get_filter\fP() , \fIposix_trace_get_status\fP() , +\fIposix_trace_getnext_event\fP() , \fIposix_trace_open\fP() , \fIposix_trace_set_filter\fP() +, +\fIposix_trace_shutdown\fP() , \fIposix_trace_start\fP() , \fIposix_trace_timedgetnext_event\fP() +, \fIposix_trace_trid_eventid_open\fP() , \fIposix_trace_start\fP() +, \fItime\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_trace_create_withlog.3p b/man3p/posix_trace_create_withlog.3p new file mode 100644 index 000000000..fe471c7bd --- /dev/null +++ b/man3p/posix_trace_create_withlog.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_create.3p diff --git a/man3p/posix_trace_event.3p b/man3p/posix_trace_event.3p new file mode 100644 index 000000000..f495da08a --- /dev/null +++ b/man3p/posix_trace_event.3p @@ -0,0 +1,138 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TRACE_EVENT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_trace_event +.SH NAME +posix_trace_event, posix_trace_eventid_open \- trace functions for +instrumenting application code +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +void posix_trace_event(trace_event_id_t\fP \fIevent_id\fP\fB, +.br +\ \ \ \ \ \ const void *restrict\fP\fIdata_ptr\fP\fB, size_t\fP \fIdata_len\fP\fB); +.br +int posix_trace_eventid_open(const char *restrict\fP \fIevent_name\fP\fB, +.br +\ \ \ \ \ \ trace_event_id_t *restrict\fP \fIevent_id\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_trace_event\fP() function shall record the \fIevent_id\fP +and the user data pointed to by \fIdata_ptr\fP in the +trace stream into which the calling process is being traced and in +which \fIevent_id\fP is not filtered out. If the total size of +the user trace event data represented by \fIdata_len\fP is not greater +than the declared maximum size for user trace event data, +then the \fItruncation-status\fP attribute of the trace event recorded +is POSIX_TRACE_NOT_TRUNCATED. Otherwise, the user trace +event data is truncated to this declared maximum size and the \fItruncation-status\fP +attribute of the trace event recorded is +POSIX_TRACE_TRUNCATED_RECORD. +.LP +If there is no trace stream created for the process or if the created +trace stream is not running, or if the trace event +specified by \fIevent_id\fP is filtered out in the trace stream, the +\fIposix_trace_event\fP() function shall have no effect. +.LP +The \fIposix_trace_eventid_open\fP() function shall associate a user +trace event name with a trace event type identifier for +the calling process. The trace event name is the string pointed to +by the argument \fIevent_name\fP. It shall have a maximum of +{TRACE_EVENT_NAME_MAX} characters (which has the minimum value {_POSIX_TRACE_EVENT_NAME_MAX}). +The number of user trace event type +identifiers that can be defined for any given process is limited by +the maximum value {TRACE_USER_EVENT_MAX}, which has the minimum +value {POSIX_TRACE_USER_EVENT_MAX}. +.LP +If the Trace Inherit option is not supported, the \fIposix_trace_eventid_open\fP() +function shall associate the user trace +event name pointed to by the \fIevent_name\fP argument with a trace +event type identifier that is unique for the traced process, +and is returned in the variable pointed to by the \fIevent_id\fP argument. +If the user trace event name has already been mapped +for the traced process, then the previously assigned trace event type +identifier shall be returned. If the per-process user trace +event name limit represented by {TRACE_USER_EVENT_MAX} has been reached, +the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (see \fITrace Option: +User Trace Event\fP ) user trace event shall be returned. +.LP +If the Trace Inherit option is supported, the \fIposix_trace_eventid_open\fP() +function shall associate the user trace event name +pointed to by the \fIevent_name\fP argument with a trace event type +identifier that is unique for all the processes being traced +in this same trace stream, and is returned in the variable pointed +to by the \fIevent_id\fP argument. If the user trace event name +has already been mapped for the traced processes, then the previously +assigned trace event type identifier shall be returned. If +the per-process user trace event name limit represented by {TRACE_USER_EVENT_MAX} +has been reached, the pre-defined +POSIX_TRACE_UNNAMED_USEREVENT ( \fITrace Option: User Trace Event\fP +) user trace event +shall be returned. +.TP 7 +\fBNote:\fP +The above procedure, together with the fact that multiple processes +can only be traced into the same trace stream by +inheritance, ensure that all the processes that are traced into a +trace stream have the same mapping of trace event names to trace +event type identifiers. +.sp +.LP +If there is no trace stream created, the \fIposix_trace_eventid_open\fP() +function shall store this information for future +trace streams created for this process. +.SH RETURN VALUE +.LP +No return value is defined for the \fIposix_trace_event\fP() function. +.LP +Upon successful completion, the \fIposix_trace_eventid_open\fP() function +shall return a value of zero. Otherwise, it shall +return the corresponding error number. The \fIposix_trace_eventid_open\fP() +function stores the trace event type identifier value +in the object pointed to by \fIevent_id\fP, if successful. +.SH ERRORS +.LP +The \fIposix_trace_eventid_open\fP() function shall fail if: +.TP 7 +.B ENAMETOOLONG +The size of the name pointed to by the \fIevent_name\fP argument was +longer than the implementation-defined value +{TRACE_EVENT_NAME_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fITrace Option: User Trace Event\fP , \fIposix_trace_start\fP() , +\fIposix_trace_trid_eventid_open\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_trace_eventid_equal.3p b/man3p/posix_trace_eventid_equal.3p new file mode 100644 index 000000000..9e4d8630a --- /dev/null +++ b/man3p/posix_trace_eventid_equal.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_eventid_get_name.3p diff --git a/man3p/posix_trace_eventid_get_name.3p b/man3p/posix_trace_eventid_get_name.3p new file mode 100644 index 000000000..d5ea933c3 --- /dev/null +++ b/man3p/posix_trace_eventid_get_name.3p @@ -0,0 +1,166 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TRACE_EVENTID_EQUAL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_trace_eventid_equal +.SH NAME +posix_trace_eventid_equal, posix_trace_eventid_get_name, posix_trace_trid_eventid_open +\- manipulate the trace event +type identifier (\fBTRACING\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_trace_eventid_equal(trace_id_t\fP \fItrid\fP\fB, trace_event_id_t\fP +\fIevent1\fP\fB, +.br +\ \ \ \ \ \ trace_event_id_t\fP \fIevent2\fP\fB); +.br +int posix_trace_eventid_get_name(trace_id_t\fP \fItrid\fP\fB, +.br +\ \ \ \ \ \ trace_event_id_t\fP \fIevent\fP\fB, char *\fP\fIevent_name\fP\fB); +.br +\fP +.LP +\fBint posix_trace_trid_eventid_open(trace_id_t\fP \fItrid\fP\fB, +.br +\ \ \ \ \ \ const char *restrict\fP \fIevent_name\fP\fB, +.br +\ \ \ \ \ \ trace_event_id_t *restrict\fP \fIevent\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_trace_eventid_equal\fP() function shall compare the trace +event type identifiers \fIevent1\fP and \fIevent2\fP +from the same trace stream or the same trace log identified by the +\fItrid\fP argument. If the trace event type identifiers +\fIevent1\fP and \fIevent2\fP are from different trace streams, the +return value shall be unspecified. +.LP +The \fIposix_trace_eventid_get_name\fP() function shall return, in +the argument pointed to by \fIevent_name\fP, the trace +event name associated with the trace event type identifier identified +by the argument \fIevent\fP, for the trace stream or for the +trace log identified by the \fItrid\fP argument. The name of the trace +event shall have a maximum of {TRACE_EVENT_NAME_MAX} +characters (which has the minimum value {_POSIX_TRACE_EVENT_NAME_MAX}). +Successive calls to this function with the same trace event +type identifier and the same trace stream identifier shall return +the same event name. +.LP +The \fIposix_trace_trid_eventid_open\fP() function shall associate +a user trace event name with a trace event type identifier for +a given trace stream. The trace stream is identified by the \fItrid\fP +argument, and it shall be an active trace stream. The trace +event name is the string pointed to by the argument \fIevent_name\fP. +It shall have a maximum of {TRACE_EVENT_NAME_MAX} characters +(which has the minimum value {_POSIX_TRACE_EVENT_NAME_MAX}). The number +of user trace event type identifiers that can be defined +for any given process is limited by the maximum value {TRACE_USER_EVENT_MAX}, +which has the minimum value +{_POSIX_TRACE_USER_EVENT_MAX}. +.LP +If the Trace Inherit option is not supported, the \fIposix_trace_trid_eventid_open\fP() +function shall associate the user trace +event name pointed to by the \fIevent_name\fP argument with a trace +event type identifier that is unique for the process being +traced in the trace stream identified by the \fItrid\fP argument, +and is returned in the variable pointed to by the \fIevent\fP +argument. If the user trace event name has already been mapped for +the traced process, then the previously assigned trace event +type identifier shall be returned. If the per-process user trace event +name limit represented by {TRACE_USER_EVENT_MAX} has been +reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (see \fITrace +Option: User Trace +Event\fP ) user trace event shall be returned. +.LP +If the Trace Inherit option is supported, the \fIposix_trace_trid_eventid_open\fP() +function shall associate the user +trace event name pointed to by the \fIevent_name\fP argument with +a trace event type identifier that is unique for all the +processes being traced in the trace stream identified by the \fItrid\fP +argument, and is returned in the variable pointed to by +the \fIevent\fP argument. If the user trace event name has already +been mapped for the traced processes, then the previously +assigned trace event type identifier shall be returned. If the per-process +user trace event name limit represented by +{TRACE_USER_EVENT_MAX} has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT +(see \fITrace Option: User Trace Event\fP ) user trace event shall +be returned. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIposix_trace_eventid_get_name\fP() +and +\fIposix_trace_trid_eventid_open\fP() functions shall return a +value of zero. Otherwise, they shall return the corresponding error +number. +.LP +The \fIposix_trace_eventid_equal\fP() function shall return a non-zero +value if \fIevent1\fP and \fIevent2\fP are equal; +otherwise, a value of zero shall be returned. No errors are defined. +If either \fIevent1\fP or \fIevent2\fP are not valid trace +event type identifiers for the trace stream specified by \fItrid\fP +or if the \fItrid\fP is invalid, the behavior shall be +unspecified. +.LP +The \fIposix_trace_eventid_get_name\fP() function stores the trace +event name value in the object pointed to by +\fIevent_name\fP, if successful. +.LP +The \fIposix_trace_trid_eventid_open\fP() function stores the trace +event type identifier value in the object pointed to by +\fIevent\fP, if successful. +.SH ERRORS +.LP +The \fIposix_trace_eventid_get_name\fP() and \fIposix_trace_trid_eventid_open\fP() +functions shall fail if: +.TP 7 +.B EINVAL +The \fItrid\fP argument was not a valid trace stream identifier. +.sp +.LP +The \fIposix_trace_trid_eventid_open\fP() function shall fail if: +.TP 7 +.B ENAMETOOLONG +.sp +The size of the name pointed to by the \fIevent_name\fP argument was +longer than the implementation-defined value +{TRACE_EVENT_NAME_MAX}. +.sp +.LP +The \fIposix_trace_eventid_get_name\fP() function shall fail if: +.TP 7 +.B EINVAL +The trace event type identifier \fIevent\fP was not associated with +any name. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fITrace Option: User Trace Event\fP , \fIposix_trace_event\fP() , +\fIposix_trace_getnext_event\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_trace_eventid_open.3p b/man3p/posix_trace_eventid_open.3p new file mode 100644 index 000000000..d0d78a3a2 --- /dev/null +++ b/man3p/posix_trace_eventid_open.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_event.3p diff --git a/man3p/posix_trace_eventset_add.3p b/man3p/posix_trace_eventset_add.3p new file mode 100644 index 000000000..6ff04029d --- /dev/null +++ b/man3p/posix_trace_eventset_add.3p @@ -0,0 +1,132 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TRACE_EVENTSET_ADD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_trace_eventset_add +.SH NAME +posix_trace_eventset_add, posix_trace_eventset_del, posix_trace_eventset_empty, +posix_trace_eventset_fill, +posix_trace_eventset_ismember \- manipulate trace event type sets (\fBTRACING\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_trace_eventset_add(trace_event_id_t\fP \fIevent_id\fP\fB, +.br +\ \ \ \ \ \ trace_event_set_t *\fP\fIset\fP\fB); +.br +int posix_trace_eventset_del(trace_event_id_t\fP \fIevent_id\fP\fB, +.br +\ \ \ \ \ \ trace_event_set_t *\fP\fIset\fP\fB); +.br +int posix_trace_eventset_empty(trace_event_set_t *\fP\fIset\fP\fB); +.br +int posix_trace_eventset_fill(trace_event_set_t *\fP\fIset\fP\fB, +int\fP \fIwhat\fP\fB); +.br +int posix_trace_eventset_ismember(trace_event_id_t\fP \fIevent_id\fP\fB, +.br +\ \ \ \ \ \ const trace_event_set_t *restrict\fP \fIset\fP\fB, int +*restrict\fP +\fIismember\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +These primitives manipulate sets of trace event types. They operate +on data objects addressable by the application, not on the +current trace event filter of any trace stream. +.LP +The \fIposix_trace_eventset_add\fP() and \fIposix_trace_eventset_del\fP() +functions, respectively, shall add or delete the +individual trace event type specified by the value of the argument +\fIevent_id\fP to or from the trace event type set pointed to +by the argument \fIset\fP. Adding a trace event type already in the +set or deleting a trace event type not in the set shall not be +considered an error. +.LP +The \fIposix_trace_eventset_empty\fP() function shall initialize the +trace event type set pointed to by the \fIset\fP argument +such that all trace event types defined, both system and user, shall +be excluded from the set. +.LP +The \fIposix_trace_eventset_fill\fP() function shall initialize the +trace event type set pointed to by the argument \fIset\fP, +such that the set of trace event types defined by the argument \fIwhat\fP +shall be included in the set. The value of the argument +\fIwhat\fP shall consist of one of the following values, as defined +in the \fI\fP header: +.TP 7 +POSIX_TRACE_WOPID_EVENTS +.sp +All the process-independent implementation-defined system trace event +types are included in the set. +.TP 7 +POSIX_TRACE_SYSTEM_EVENTS +.sp +All the implementation-defined system trace event types are included +in the set, as are those defined in +IEEE\ Std\ 1003.1-2001. +.TP 7 +POSIX_TRACE_ALL_EVENTS +.sp +All trace event types defined, both system and user, are included +in the set. +.sp +.LP +Applications shall call either \fIposix_trace_eventset_empty\fP() +or \fIposix_trace_eventset_fill\fP() at least once for each +object of type \fBtrace_event_set_t\fP prior to any other use of that +object. If such an object is not initialized in this way, +but is nonetheless supplied as an argument to any of the \fIposix_trace_eventset_add\fP(), +\fIposix_trace_eventset_del\fP(), or +\fIposix_trace_eventset_ismember\fP() functions, the results are undefined. +.LP +The \fIposix_trace_eventset_ismember\fP() function shall test whether +the trace event type specified by the value of the +argument \fIevent_id\fP is a member of the set pointed to by the argument +\fIset\fP. The value returned in the object pointed to +by \fIismember\fP argument is zero if the trace event type identifier +is not a member of the set and a value different from zero +if it is a member of the set. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error +number. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +.B EINVAL +The value of one of the arguments is invalid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_trace_set_filter\fP() , \fIposix_trace_trid_eventid_open\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_trace_eventset_del.3p b/man3p/posix_trace_eventset_del.3p new file mode 100644 index 000000000..795224b18 --- /dev/null +++ b/man3p/posix_trace_eventset_del.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_eventset_add.3p diff --git a/man3p/posix_trace_eventset_empty.3p b/man3p/posix_trace_eventset_empty.3p new file mode 100644 index 000000000..795224b18 --- /dev/null +++ b/man3p/posix_trace_eventset_empty.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_eventset_add.3p diff --git a/man3p/posix_trace_eventset_fill.3p b/man3p/posix_trace_eventset_fill.3p new file mode 100644 index 000000000..795224b18 --- /dev/null +++ b/man3p/posix_trace_eventset_fill.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_eventset_add.3p diff --git a/man3p/posix_trace_eventset_ismember.3p b/man3p/posix_trace_eventset_ismember.3p new file mode 100644 index 000000000..795224b18 --- /dev/null +++ b/man3p/posix_trace_eventset_ismember.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_eventset_add.3p diff --git a/man3p/posix_trace_eventtypelist_getnext_id.3p b/man3p/posix_trace_eventtypelist_getnext_id.3p new file mode 100644 index 000000000..ff685eec4 --- /dev/null +++ b/man3p/posix_trace_eventtypelist_getnext_id.3p @@ -0,0 +1,87 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TRACE_EVENTTYPELIST_GETNEXT_ID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_trace_eventtypelist_getnext_id +.SH NAME +posix_trace_eventtypelist_getnext_id, posix_trace_eventtypelist_rewind +\- iterate over a mapping of trace event types +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_trace_eventtypelist_getnext_id(trace_id_t\fP \fItrid\fP\fB, +.br +\ \ \ \ \ \ trace_event_id_t *restrict\fP \fIevent\fP\fB, int *restrict\fP +\fIunavailable\fP\fB); +.br +int posix_trace_eventtypelist_rewind(trace_id_t\fP \fItrid\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The first time \fIposix_trace_eventtypelist_getnext_id\fP() is called, +the function shall return in the variable pointed to by +\fIevent\fP the first trace event type identifier of the list of trace +events of the trace stream identified by the \fItrid\fP +argument. Successive calls to \fIposix_trace_eventtypelist_getnext_id\fP() +return in the variable pointed to by \fIevent\fP the +next trace event type identifier in that same list. Each time a trace +event type identifier is successfully written into the +variable pointed to by the \fIevent\fP argument, the variable pointed +to by the \fIunavailable\fP argument shall be set to zero. +When no more trace event type identifiers are available, and so none +is returned, the variable pointed to by the \fIunavailable\fP +argument shall be set to a value different from zero. +.LP +The \fIposix_trace_eventtypelist_rewind\fP() function shall reset +the next trace event type identifier to be read to the first +trace event type identifier from the list of trace events used in +the trace stream identified by \fItrid\fP. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error +number. +.LP +The \fIposix_trace_eventtypelist_getnext_id\fP() function stores the +trace event type identifier value in the object pointed to +by \fIevent\fP, if successful. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +.B EINVAL +The \fItrid\fP argument was not a valid trace stream identifier. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_trace_event\fP() , \fIposix_trace_getnext_event\fP() , \fIposix_trace_trid_eventid_open\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_trace_eventtypelist_rewind.3p b/man3p/posix_trace_eventtypelist_rewind.3p new file mode 100644 index 000000000..d3114be01 --- /dev/null +++ b/man3p/posix_trace_eventtypelist_rewind.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_eventtypelist_getnext_id.3p diff --git a/man3p/posix_trace_flush.3p b/man3p/posix_trace_flush.3p new file mode 100644 index 000000000..fe471c7bd --- /dev/null +++ b/man3p/posix_trace_flush.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_create.3p diff --git a/man3p/posix_trace_get_attr.3p b/man3p/posix_trace_get_attr.3p new file mode 100644 index 000000000..51dc2d81f --- /dev/null +++ b/man3p/posix_trace_get_attr.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_get_status.3p diff --git a/man3p/posix_trace_get_filter.3p b/man3p/posix_trace_get_filter.3p new file mode 100644 index 000000000..eff099edc --- /dev/null +++ b/man3p/posix_trace_get_filter.3p @@ -0,0 +1,121 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TRACE_GET_FILTER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_trace_get_filter +.SH NAME +posix_trace_get_filter, posix_trace_set_filter \- retrieve and set +the filter of an initialized trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_trace_get_filter(trace_id_t\fP \fItrid\fP\fB, trace_event_set_t +*\fP\fIset\fP\fB); +.br +int posix_trace_set_filter(trace_id_t\fP \fItrid\fP\fB, +.br +\ \ \ \ \ \ const trace_event_set_t *\fP\fIset\fP\fB, int\fP \fIhow\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_trace_get_filter\fP() function shall retrieve, into the +argument pointed to by \fIset\fP, the actual trace event +filter from the trace stream specified by \fItrid\fP. +.LP +The \fIposix_trace_set_filter\fP() function shall change the set of +filtered trace event types after a trace stream identified +by the \fItrid\fP argument is created. This function may be called +prior to starting the trace stream, or while the trace stream +is active. By default, if no call is made to \fIposix_trace_set_filter\fP(), +all trace events shall be recorded (that is, none of +the trace event types are filtered out). +.LP +If this function is called while the trace is in progress, a special +system trace event, POSIX_TRACE_FILTER, shall be recorded +in the trace indicating both the old and the new sets of filtered +trace event types (see \fITrace and Trace Event Filter Options: System +Trace Events\fP and \fITrace, Trace Log, and Trace Event Filter Options: +System Trace Events\fP ). +.LP +If the \fIposix_trace_set_filter\fP() function is interrupted by a +signal, an error shall be returned and the filter shall not +be changed. In this case, the state of the trace stream shall not +be changed. +.LP +The value of the argument \fIhow\fP indicates the manner in which +the set is to be changed and shall have one of the following +values, as defined in the \fI\fP header: +.TP 7 +POSIX_TRACE_SET_EVENTSET +.sp +The resulting set of trace event types to be filtered shall be the +trace event type set pointed to by the argument \fIset\fP. +.TP 7 +POSIX_TRACE_ADD_EVENTSET +.sp +The resulting set of trace event types to be filtered shall be the +union of the current set and the trace event type set pointed to +by the argument \fIset\fP. +.TP 7 +POSIX_TRACE_SUB_EVENTSET +.sp +The resulting set of trace event types to be filtered shall be all +trace event types in the current set that are not in the set +pointed to by the argument \fIset\fP; that is, remove each element +of the specified set from the current filter. +.sp +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error +number. +.LP +The \fIposix_trace_get_filter\fP() function stores the set of filtered +trace event types in \fIset\fP, if successful. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +.B EINVAL +The value of the \fItrid\fP argument does not correspond to an active +trace stream or the value of the argument pointed to by +\fIset\fP is invalid. +.TP 7 +.B EINTR +The operation was interrupted by a signal. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fITrace and Trace Event Filter Options: System Trace Events\fP , +\fITrace, Trace Log, and Trace Event Filter Options: System Trace +Events\fP , \fIposix_trace_eventset_add\fP() , the Base Definitions +volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_trace_get_status.3p b/man3p/posix_trace_get_status.3p new file mode 100644 index 000000000..93bad5ea5 --- /dev/null +++ b/man3p/posix_trace_get_status.3p @@ -0,0 +1,111 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TRACE_GET_ATTR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_trace_get_attr +.SH NAME +posix_trace_get_attr, posix_trace_get_status \- retrieve the trace +attributes or trace status +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_trace_get_attr(trace_id_t\fP \fItrid\fP\fB, trace_attr_t +*\fP\fIattr\fP\fB); +.br +int posix_trace_get_status(trace_id_t\fP \fItrid\fP\fB, +.br +\ \ \ \ \ \ struct posix_trace_status_info *\fP\fIstatusinfo\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_trace_get_attr\fP() function shall copy the attributes +of the active trace stream identified by \fItrid\fP into +the object pointed to by the \fIattr\fP argument. If the Trace Log +option is supported, \fItrid\fP may represent a +pre-recorded trace log. +.LP +The \fIposix_trace_get_status\fP() function shall return, in the structure +pointed to by the \fIstatusinfo\fP argument, the +current trace status for the trace stream identified by the \fItrid\fP +argument. These status values returned in the structure +pointed to by \fIstatusinfo\fP shall have been appropriately read +to ensure that the returned values are consistent. \ If the +Trace Log option is supported and the \fItrid\fP argument refers to +a pre-recorded trace stream, the status shall be the status of +the completed trace stream. +.LP +Each time the \fIposix_trace_get_status\fP() function is used, the +overrun status of the trace stream shall be reset to +POSIX_TRACE_NO_OVERRUN immediately after the call completes. \ If +the Trace Log option is supported, the +\fIposix_trace_get_status\fP() function shall behave the same as when +the option is not supported except for the following +differences: +.IP " *" 3 +If the \fItrid\fP argument refers to a trace stream with log, each +time the \fIposix_trace_get_status\fP() function is used, +the log overrun status of the trace stream shall be reset to POSIX_TRACE_NO_OVERRUN +and the \fIflush_error\fP status shall be +reset to zero immediately after the call completes. +.LP +.IP " *" 3 +If the \fItrid\fP argument refers to a pre-recorded trace stream, +the status returned shall be the status of the completed +trace stream and the status values of the trace stream shall not be +reset. +.LP +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error +number. +.LP +The \fIposix_trace_get_attr\fP() function stores the trace attributes +in the object pointed to by \fIattr\fP, if +successful. +.LP +The \fIposix_trace_get_status\fP() function stores the trace status +in the object pointed to by \fIstatusinfo\fP, if +successful. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +.B EINVAL +The trace stream argument \fItrid\fP does not correspond to a valid +active trace stream or a valid trace log. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_trace_attr_destroy\fP() , \fIposix_trace_attr_init\fP() , +\fIposix_trace_create\fP() +, \fIposix_trace_open\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_trace_getnext_event.3p b/man3p/posix_trace_getnext_event.3p new file mode 100644 index 000000000..59d9b7e80 --- /dev/null +++ b/man3p/posix_trace_getnext_event.3p @@ -0,0 +1,222 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TRACE_GETNEXT_EVENT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_trace_getnext_event +.SH NAME +posix_trace_getnext_event, posix_trace_timedgetnext_event, posix_trace_trygetnext_event +\- retrieve a trace event +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int posix_trace_getnext_event(trace_id_t\fP \fItrid\fP\fB, +.br +\ \ \ \ \ \ struct posix_trace_event_info *restrict\fP \fIevent\fP\fB, +.br +\ \ \ \ \ \ void *restrict\fP \fIdata\fP\fB, size_t\fP \fInum_bytes\fP\fB, +.br +\ \ \ \ \ \ size_t *restrict\fP \fIdata_len\fP\fB, int *restrict\fP +\fIunavailable\fP\fB); +.br +\fP +.LP +\fBint posix_trace_timedgetnext_event(trace_id_t\fP \fItrid\fP\fB, +.br +\ \ \ \ \ \ struct posix_trace_event_info *restrict\fP \fIevent\fP\fB, +.br +\ \ \ \ \ \ void *restrict\fP \fIdata\fP\fB, size_t\fP \fInum_bytes\fP\fB, +.br +\ \ \ \ \ \ size_t *restrict\fP \fIdata_len\fP\fB, int *restrict\fP +\fIunavailable\fP\fB, +.br +\ \ \ \ \ \ const struct timespec *restrict\fP \fIabs_timeout\fP\fB); +.br +\fP +.LP +\fBint posix_trace_trygetnext_event(trace_id_t\fP \fItrid\fP\fB, +.br +\ \ \ \ \ \ struct posix_trace_event_info *restrict\fP \fIevent\fP\fB, +.br +\ \ \ \ \ \ void *restrict\fP \fIdata\fP\fB, size_t\fP \fInum_bytes\fP\fB, +.br +\ \ \ \ \ \ size_t *restrict\fP \fIdata_len\fP\fB, int *restrict\fP +\fIunavailable\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_trace_getnext_event\fP() function shall report a recorded +trace event either from an active trace stream without +log +\ or a pre-recorded trace stream identified by the \fItrid\fP argument. +The \fIposix_trace_trygetnext_event\fP() function shall report a recorded +trace event from an active trace stream +without log identified by the \fItrid\fP argument. +.LP +The trace event information associated with the recorded trace event +shall be copied by the function into the structure pointed +to by the argument \fIevent\fP and the data associated with the trace +event shall be copied into the buffer pointed to by the +\fIdata\fP argument. +.LP +The \fIposix_trace_getnext_event\fP() function shall block if the +\fItrid\fP argument identifies an active trace stream and +there is currently no trace event ready to be retrieved. When returning, +if a recorded trace event was reported, the variable +pointed to by the \fIunavailable\fP argument shall be set to zero. +Otherwise, the variable pointed to by the \fIunavailable\fP +argument shall be set to a value different from zero. +.LP +\ The \fIposix_trace_timedgetnext_event\fP() function shall attempt +to get another trace event from an active trace stream +without log, as in the \fIposix_trace_getnext_event\fP() function. +However, if no trace event is available from the trace stream, +the implied wait shall be terminated when the timeout specified by +the argument \fIabs_timeout\fP expires, and the function shall +return the error [ETIMEDOUT]. +.LP +The timeout shall expire when the absolute time specified by \fIabs_timeout\fP +passes, as measured by the clock upon which +timeouts are based (that is, when the value of that clock equals or +exceeds \fIabs_timeout\fP), or if the absolute time specified +by \fIabs_timeout\fP has already passed at the time of the call. +.LP +\ If the Timers option is supported, the timeout shall be based on +the CLOCK_REALTIME clock; if the Timers option +is not supported, the timeout shall be based on the system clock as +returned by the \fItime\fP() function. The resolution of the timeout +shall be the resolution of the clock on which it +is based. The \fBtimespec\fP data type is defined in the \fI\fP +header. +.LP +Under no circumstance shall the function fail with a timeout if a +trace event is immediately available from the trace stream. The +validity of the \fIabs_timeout\fP argument need not be checked if +a trace event is immediately available from the trace +stream. +.LP +The behavior of this function for a pre-recorded trace stream is unspecified. +.LP +The \fIposix_trace_trygetnext_event\fP() function shall not block. +\ This function shall return an error if the \fItrid\fP +argument identifies a pre-recorded trace stream. If a recorded +trace event was reported, the variable pointed to by the \fIunavailable\fP +argument shall be set to zero. Otherwise, if no trace +event was reported, the variable pointed to by the \fIunavailable\fP +argument shall be set to a value different from zero. +.LP +The argument \fInum_bytes\fP shall be the size of the buffer pointed +to by the \fIdata\fP argument. The argument +\fIdata_len\fP reports to the application the length in bytes of the +data record just transferred. If \fInum_bytes\fP is greater +than or equal to the size of the data associated with the trace event +pointed to by the \fIevent\fP argument, all the recorded +data shall be transferred. In this case, the \fItruncation-status\fP +member of the trace event structure shall be either +POSIX_TRACE_NOT_TRUNCATED, if the trace event data was recorded without +truncation while tracing, or POSIX_TRACE_TRUNCATED_RECORD, +if the trace event data was truncated when it was recorded. If the +\fInum_bytes\fP argument is less than the length of recorded +trace event data, the data transferred shall be truncated to a length +of \fInum_bytes\fP, the value stored in the variable pointed +to by \fIdata_len\fP shall be equal to \fInum_bytes\fP, and the \fItruncation-status\fP +member of the \fIevent\fP structure +argument shall be set to POSIX_TRACE_TRUNCATED_READ (see the \fBposix_trace_event_info\fP +structure defined in \fI\fP). +.LP +The report of a trace event shall be sequential starting from the +oldest recorded trace event. Trace events shall be reported in +the order in which they were generated, up to an implementation-defined +time resolution that causes the ordering of trace events +occurring very close to each other to be unknown. Once reported, a +trace event cannot be reported again from an active trace +stream. Once a trace event is reported from an active trace stream +without log, the trace stream shall make the resources +associated with that trace event available to record future generated +trace events. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error +number. +.LP +If successful, these functions store: +.IP " *" 3 +The recorded trace event in the object pointed to by \fIevent\fP +.LP +.IP " *" 3 +The trace event information associated with the recorded trace event +in the object pointed to by \fIdata\fP +.LP +.IP " *" 3 +The length of this trace event information in the object pointed to +by \fIdata_len\fP +.LP +.IP " *" 3 +The value of zero in the object pointed to by \fIunavailable\fP +.LP +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +.B EINVAL +The trace stream identifier argument \fItrid\fP is invalid. +.sp +.LP +The \fIposix_trace_getnext_event\fP() and \fIposix_trace_timedgetnext_event\fP() +functions shall fail if: +.TP 7 +.B EINTR +The operation was interrupted by a signal, and so the call had no +effect. +.sp +.LP +The \fIposix_trace_trygetnext_event\fP() function shall fail if: +.TP 7 +.B EINVAL +The trace stream identifier argument \fItrid\fP does not correspond +to an active trace stream. +.sp +.LP +The \fIposix_trace_timedgetnext_event\fP() function shall fail if: +.TP 7 +.B EINVAL +There is no trace event immediately available from the trace stream, +and the \fItimeout\fP argument is invalid. +.TP 7 +.B ETIMEDOUT +No trace event was available from the trace stream before the specified +timeout \fItimeout\fP expired. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_trace_create\fP() , \fIposix_trace_open\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_trace_open.3p b/man3p/posix_trace_open.3p new file mode 100644 index 000000000..11b08d9a0 --- /dev/null +++ b/man3p/posix_trace_open.3p @@ -0,0 +1,139 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TRACE_CLOSE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_trace_close +.SH NAME +posix_trace_close, posix_trace_open, posix_trace_rewind \- trace log +management (\fBTRACING\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_trace_close(trace_id_t\fP \fItrid\fP\fB); +.br +int posix_trace_open(int\fP \fIfile_desc\fP\fB, trace_id_t *\fP\fItrid\fP\fB); +.br +int posix_trace_rewind(trace_id_t\fP \fItrid\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_trace_close\fP() function shall deallocate the trace +log identifier indicated by \fItrid\fP, and all of its +associated resources. If there is no valid trace log pointed to by +the \fItrid\fP, this function shall fail. +.LP +The \fIposix_trace_open\fP() function shall allocate the necessary +resources and establish the connection between a trace log +identified by the \fIfile_desc\fP argument and a trace stream identifier +identified by the object pointed to by the \fItrid\fP +argument. The \fIfile_desc\fP argument should be a valid open file +descriptor that corresponds to a trace log. The +\fIfile_desc\fP argument shall be open for reading. The current trace +event timestamp, which specifies the timestamp of the trace +event that will be read by the next call to \fIposix_trace_getnext_event\fP(), +shall be set to the timestamp of the oldest +trace event recorded in the trace log identified by \fItrid\fP. +.LP +The \fIposix_trace_open\fP() function shall return a trace stream +identifier in the variable pointed to by the \fItrid\fP +argument, that may only be used by the following functions: +.TS C +center; lw(39) lw(39). +T{ +.br +\fIposix_trace_close\fP() +.br +\fIposix_trace_eventid_equal\fP() +.br +\fIposix_trace_eventid_get_name\fP() +.br +\fIposix_trace_eventtypelist_getnext_id\fP() +.br +\fIposix_trace_eventtypelist_rewind\fP() +.br +\ +T} T{ +.br +\fIposix_trace_get_attr\fP() +.br +\fIposix_trace_get_status\fP() +.br +\fIposix_trace_getnext_event\fP() +.br +\fIposix_trace_rewind\fP() +.br +\ +T} +.TE +.LP +In particular, notice that the operations normally used by a trace +controller process, such as \fIposix_trace_start\fP(), \fIposix_trace_stop\fP(), +or \fIposix_trace_shutdown\fP(), cannot be invoked using the trace +stream identifier +returned by the \fIposix_trace_open\fP() function. +.LP +The \fIposix_trace_rewind\fP() function shall reset the current trace +event timestamp, which specifies the timestamp of the +trace event that will be read by the next call to \fIposix_trace_getnext_event\fP(), +to the timestamp of the oldest trace event +recorded in the trace log identified by \fItrid\fP. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error +number. +.LP +If successful, the \fIposix_trace_open\fP() function stores the trace +stream identifier value in the object pointed to by +\fItrid\fP. +.SH ERRORS +.LP +The \fIposix_trace_open\fP() function shall fail if: +.TP 7 +.B EINTR +The operation was interrupted by a signal and thus no trace log was +opened. +.TP 7 +.B EINVAL +The object pointed to by \fIfile_desc\fP does not correspond to a +valid trace log. +.sp +.LP +The \fIposix_trace_close\fP() and \fIposix_trace_rewind\fP() functions +may fail if: +.TP 7 +.B EINVAL +The object pointed to by \fItrid\fP does not correspond to a valid +trace log. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_trace_get_attr\fP() , \fIposix_trace_get_filter\fP() , \fIposix_trace_getnext_event\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_trace_rewind.3p b/man3p/posix_trace_rewind.3p new file mode 100644 index 000000000..a42c3abb4 --- /dev/null +++ b/man3p/posix_trace_rewind.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_open.3p diff --git a/man3p/posix_trace_set_filter.3p b/man3p/posix_trace_set_filter.3p new file mode 100644 index 000000000..0d2f0fd2f --- /dev/null +++ b/man3p/posix_trace_set_filter.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_get_filter.3p diff --git a/man3p/posix_trace_shutdown.3p b/man3p/posix_trace_shutdown.3p new file mode 100644 index 000000000..fe471c7bd --- /dev/null +++ b/man3p/posix_trace_shutdown.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_create.3p diff --git a/man3p/posix_trace_start.3p b/man3p/posix_trace_start.3p new file mode 100644 index 000000000..6046a3b4f --- /dev/null +++ b/man3p/posix_trace_start.3p @@ -0,0 +1,87 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TRACE_START" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_trace_start +.SH NAME +posix_trace_start, posix_trace_stop \- trace start and stop (\fBTRACING\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_trace_start(trace_id_t\fP \fItrid\fP\fB); +.br +int posix_trace_stop (trace_id_t\fP \fItrid\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_trace_start\fP() and \fIposix_trace_stop\fP() functions, +respectively, shall start and stop the trace stream +identified by the argument \fItrid\fP. +.LP +The effect of calling the \fIposix_trace_start\fP() function shall +be recorded in the trace stream as the POSIX_TRACE_START +system trace event and the status of the trace stream shall become +POSIX_TRACE_RUNNING. If the trace stream is in progress when +this function is called, the POSIX_TRACE_START system trace event +shall not be recorded and the trace stream shall continue to run. +If the trace stream is full, the POSIX_TRACE_START system trace event +shall not be recorded and the status of the trace stream +shall not be changed. +.LP +The effect of calling the \fIposix_trace_stop\fP() function shall +be recorded in the trace stream as the POSIX_TRACE_STOP +system trace event and the status of the trace stream shall become +POSIX_TRACE_SUSPENDED. If the trace stream is suspended when +this function is called, the POSIX_TRACE_STOP system trace event shall +not be recorded and the trace stream shall remain suspended. +If the trace stream is full, the POSIX_TRACE_STOP system trace event +shall not be recorded and the status of the trace stream shall +not be changed. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error +number. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +.B EINVAL +The value of the argument \fItrid\fP does not correspond to an active +trace stream and thus no trace stream was started or +stopped. +.TP 7 +.B EINTR +The operation was interrupted by a signal and thus the trace stream +was not necessarily started or stopped. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIposix_trace_create\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_trace_stop.3p b/man3p/posix_trace_stop.3p new file mode 100644 index 000000000..2a3dc92b0 --- /dev/null +++ b/man3p/posix_trace_stop.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_start.3p diff --git a/man3p/posix_trace_timedgetnext_event.3p b/man3p/posix_trace_timedgetnext_event.3p new file mode 100644 index 000000000..8daa88408 --- /dev/null +++ b/man3p/posix_trace_timedgetnext_event.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_getnext_event.3p diff --git a/man3p/posix_trace_trid_eventid_open.3p b/man3p/posix_trace_trid_eventid_open.3p new file mode 100644 index 000000000..9e4d8630a --- /dev/null +++ b/man3p/posix_trace_trid_eventid_open.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_eventid_get_name.3p diff --git a/man3p/posix_trace_trygetnext_event.3p b/man3p/posix_trace_trygetnext_event.3p new file mode 100644 index 000000000..8daa88408 --- /dev/null +++ b/man3p/posix_trace_trygetnext_event.3p @@ -0,0 +1 @@ +.so man3p/posix_trace_getnext_event.3p diff --git a/man3p/posix_typed_mem_get_info.3p b/man3p/posix_typed_mem_get_info.3p new file mode 100644 index 000000000..d9a7ff0c3 --- /dev/null +++ b/man3p/posix_typed_mem_get_info.3p @@ -0,0 +1,109 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TYPED_MEM_GET_INFO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_typed_mem_get_info +.SH NAME +posix_typed_mem_get_info \- query typed memory information (\fBADVANCED +REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_typed_mem_get_info(int\fP \fIfildes\fP\fB, +.br +\ \ \ \ \ \ struct posix_typed_mem_info *\fP\fIinfo\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_typed_mem_get_info\fP() function shall return, in the +\fIposix_tmi_length\fP field of the +\fBposix_typed_mem_info\fP structure pointed to by \fIinfo\fP, the +maximum length which may be successfully allocated by the +typed memory object designated by \fIfildes\fP. This maximum length +shall take into account the flag POSIX_TYPED_MEM_ALLOCATE or +POSIX_TYPED_MEM_ALLOCATE_CONTIG specified when the typed memory object +represented by \fIfildes\fP was opened. The maximum length +is dynamic; therefore, the value returned is valid only while the +current mapping of the corresponding typed memory pool remains +unchanged. +.LP +If \fIfildes\fP represents a typed memory object opened with neither +the POSIX_TYPED_MEM_ALLOCATE flag nor the +POSIX_TYPED_MEM_ALLOCATE_CONTIG flag specified, the returned value +of \fIinfo\fP->\fIposix_tmi_length\fP is unspecified. +.LP +The \fIposix_typed_mem_get_info\fP() function may return additional +implementation-defined information in other fields of the +\fBposix_typed_mem_info\fP structure pointed to by \fIinfo\fP. +.LP +If the memory object specified by \fIfildes\fP is not a typed memory +object, then the behavior of this function is +undefined. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIposix_typed_mem_get_info\fP() function +shall return zero; otherwise, the corresponding error +status value shall be returned. +.SH ERRORS +.LP +The \fIposix_typed_mem_get_info\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid open file descriptor. +.TP 7 +.B ENODEV +The \fIfildes\fP argument is not connected to a memory object supported +by this function. +.sp +.LP +This function shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +An application that needs to allocate a block of typed memory with +length dependent upon the amount of memory currently +available must either query the typed memory object to obtain the +amount available, or repeatedly invoke \fImmap\fP() attempting to +guess an appropriate length. While the latter method is existing practice +with \fImalloc\fP(), it is awkward and imprecise. The \fIposix_typed_mem_get_info\fP() +function allows an application to immediately determine available +memory. This is particularly important for typed memory objects +that may in some cases be scarce resources. Note that when a typed +memory pool is a shared resource, some form of mutual-exclusion +or synchronization may be required while typed memory is being queried +and allocated to prevent race conditions. +.LP +The existing \fIfstat\fP() function is not suitable for this purpose. +We realize that +implementations may wish to provide other attributes of typed memory +objects (for example, alignment requirements, page size, and +so on). The \fIfstat\fP() function returns a structure which is not +extensible and, +furthermore, contains substantial information that is inappropriate +for typed memory objects. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfstat\fP() , \fImmap\fP() , \fIposix_typed_mem_open\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/posix_typed_mem_open.3p b/man3p/posix_typed_mem_open.3p new file mode 100644 index 000000000..170c57106 --- /dev/null +++ b/man3p/posix_typed_mem_open.3p @@ -0,0 +1,185 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TYPED_MEM_OPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_typed_mem_open +.SH NAME +posix_typed_mem_open \- open a typed memory object (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int posix_typed_mem_open(const char *\fP\fIname\fP\fB, int\fP \fIoflag\fP\fB, +int\fP \fItflag\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_typed_mem_open\fP() function shall establish a connection +between the typed memory object specified by the string +pointed to by \fIname\fP and a file descriptor. It shall create an +open file description that refers to the typed memory object +and a file descriptor that refers to that open file description. The +file descriptor is used by other functions to refer to that +typed memory object. It is unspecified whether the name appears in +the file system and is visible to other functions that take +pathnames as arguments. The \fIname\fP argument shall conform to the +construction rules for a pathname. If \fIname\fP begins with +the slash character, then processes calling \fIposix_typed_mem_open\fP() +with the same value of \fIname\fP shall refer to the +same typed memory object. If \fIname\fP does not begin with the slash +character, the effect is implementation-defined. The +interpretation of slash characters other than the leading slash character +in \fIname\fP is implementation-defined. +.LP +Each typed memory object supported in a system shall be identified +by a name which specifies not only its associated typed +memory pool, but also the path or port by which it is accessed. That +is, the same typed memory pool accessed via several different +ports shall have several different corresponding names. The binding +between names and typed memory objects is established in an +implementation-defined manner. Unlike shared memory objects, there +is no way within IEEE\ Std\ 1003.1-2001 for a program to +create a typed memory object. +.LP +The value of \fItflag\fP shall determine how the typed memory object +behaves when subsequently mapped by calls to \fImmap\fP(). At most, +one of the following flags defined in \fI\fP may be specified: +.TP 7 +POSIX_TYPED_MEM_ALLOCATE +Allocate on \fImmap\fP(). +.TP 7 +POSIX_TYPED_MEM_ALLOCATE_CONTIG +Allocate contiguously on \fImmap\fP(). +.TP 7 +POSIX_TYPED_MEM_MAP_ALLOCATABLE +Map on \fImmap\fP(), without affecting allocatability. +.sp +.LP +If \fItflag\fP has the flag POSIX_TYPED_MEM_ALLOCATE specified, any +subsequent call to \fImmap\fP() using the returned file descriptor +shall result in allocation and mapping of typed +memory from the specified typed memory pool. The allocated memory +may be a contiguous previously unallocated area of the typed +memory pool or several non-contiguous previously unallocated areas +(mapped to a contiguous portion of the process address space). +If \fItflag\fP has the flag POSIX_TYPED_MEM_ALLOCATE_CONTIG specified, +any subsequent call to \fImmap\fP() using the returned file descriptor +shall result in allocation and mapping of a single +contiguous previously unallocated area of the typed memory pool (also +mapped to a contiguous portion of the process address space). +If \fItflag\fP has none of the flags POSIX_TYPED_MEM_ALLOCATE or POSIX_TYPED_MEM_ALLOCATE_CONTIG +specified, any subsequent call to +\fImmap\fP() using the returned file descriptor shall map an application-chosen +area from the +specified typed memory pool such that this mapped area becomes unavailable +for allocation until unmapped by all processes. If +\fItflag\fP has the flag POSIX_TYPED_MEM_MAP_ALLOCATABLE specified, +any subsequent call to \fImmap\fP() using the returned file descriptor +shall map an application-chosen area from the +specified typed memory pool without an effect on the availability +of that area for allocation; that is, mapping such an object +leaves each byte of the mapped area unallocated if it was unallocated +prior to the mapping or allocated if it was allocated prior +to the mapping. The appropriate privilege to specify the POSIX_TYPED_MEM_MAP_ALLOCATABLE +flag is implementation-defined. +.LP +If successful, \fIposix_typed_mem_open\fP() shall return a file descriptor +for the typed memory object that is the lowest +numbered file descriptor not currently open for that process. The +open file description is new, and therefore the file descriptor +shall not share it with any other processes. It is unspecified whether +the file offset is set. The FD_CLOEXEC file descriptor flag +associated with the new file descriptor shall be cleared. +.LP +The behavior of \fImsync\fP(), \fIftruncate\fP(), and all file operations +other than \fImmap\fP(), \fIposix_mem_offset\fP(), \fIposix_typed_mem_get_info\fP(), +\fIfstat\fP(), \fIdup\fP(), \fIdup2\fP(), and \fIclose\fP(), is unspecified +when passed a +file descriptor connected to a typed memory object by this function. +.LP +The file status flags of the open file description shall be set according +to the value of \fIoflag\fP. Applications shall +specify exactly one of the three access mode values described below +and defined in the \fI\fP header, as the value of \fIoflag\fP. +.TP 7 +O_RDONLY +Open for read access only. +.TP 7 +O_WRONLY +Open for write access only. +.TP 7 +O_RDWR +Open for read or write access. +.sp +.SH RETURN VALUE +.LP +Upon successful completion, the \fIposix_typed_mem_open\fP() function +shall return a non-negative integer representing the +lowest numbered unused file descriptor. Otherwise, it shall return +-1 and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIposix_typed_mem_open\fP() function shall fail if: +.TP 7 +.B EACCES +The typed memory object exists and the permissions specified by \fIoflag\fP +are denied. +.TP 7 +.B EINTR +The \fIposix_typed_mem_open\fP() operation was interrupted by a signal. +.TP 7 +.B EINVAL +The flags specified in \fItflag\fP are invalid (more than one of POSIX_TYPED_MEM_ALLOCATE, +POSIX_TYPED_MEM_ALLOCATE_CONTIG, or +POSIX_TYPED_MEM_MAP_ALLOCATABLE is specified). +.TP 7 +.B EMFILE +Too many file descriptors are currently in use by this process. +.TP 7 +.B ENAMETOOLONG +The length of the \fIname\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENFILE +Too many file descriptors are currently open in the system. +.TP 7 +.B ENOENT +The named typed memory object does not exist. +.TP 7 +.B EPERM +The caller lacks the appropriate privilege to specify the flag POSIX_TYPED_MEM_MAP_ALLOCATABLE +in argument \fItflag\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclose\fP() , \fIdup\fP() , \fIexec\fP() , \fIfcntl\fP() , \fIfstat\fP() +, +\fIftruncate\fP() , \fImmap\fP() , \fImsync\fP() , +\fIposix_mem_offset\fP() , \fIposix_typed_mem_get_info\fP() , \fIumask\fP() +, the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pow.3p b/man3p/pow.3p new file mode 100644 index 000000000..eb33031c7 --- /dev/null +++ b/man3p/pow.3p @@ -0,0 +1,181 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POW" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pow +.SH NAME +pow, powf, powl \- power function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double pow(double\fP \fIx\fP\fB, double\fP \fIy\fP\fB); +.br +float powf(float\fP \fIx\fP\fB, float\fP \fIy\fP\fB); +.br +long double powl(long double\fP \fIx\fP\fB, long double\fP \fIy\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the value of \fIx\fP raised to the power +\fIy\fP, \fIx**y\fP. If +\fIx\fP is negative, the application shall ensure that \fIy\fP is +an integer value. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the value +of \fIx\fP raised to the power \fIy\fP. +.LP +For finite values of \fIx\fP < 0, and finite non-integer values of +\fIy\fP, a domain error shall occur and \ either a NaN +(if representable), or an implementation-defined value shall be +returned. +.LP +If the correct value would cause overflow, a range error shall occur +and \fIpow\fP(), \fIpowf\fP(), and \fIpowl\fP() shall +return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL, respectively, +with the same sign as the correct value of the +function. +.LP +If the correct value would cause underflow, and is not representable, +a range error may occur, and \ either 0.0 (if +supported), or \ an implementation-defined value shall be +returned. +.LP +If +\fIx\fP or \fIy\fP is a NaN, a NaN shall be returned (unless specified +elsewhere in this description). +.LP +For any value of \fIy\fP (including NaN), if \fIx\fP is +1, 1.0 shall +be returned. +.LP +For any value of \fIx\fP (including NaN), if \fIy\fP is \(+-0, 1.0 +shall be returned. +.LP +For any odd integer value of \fIy\fP > 0, if \fIx\fP is \(+-0, \(+-0 +shall be returned. +.LP +For \fIy\fP > 0 and not an odd integer, if \fIx\fP is \(+-0, +0 shall +be returned. +.LP +If \fIx\fP is -1, and \fIy\fP is \(+-Inf, 1.0 shall be returned. +.LP +For |\fIx\fP| < 1, if \fIy\fP is -Inf, +Inf shall be returned. +.LP +For |\fIx\fP| > 1, if \fIy\fP is -Inf, +0 shall be returned. +.LP +For |\fIx\fP| < 1, if \fIy\fP is +Inf, +0 shall be returned. +.LP +For |\fIx\fP| > 1, if \fIy\fP is +Inf, +Inf shall be returned. +.LP +For \fIy\fP an odd integer < 0, if \fIx\fP is -Inf, -0 shall be returned. +.LP +For \fIy\fP < 0 and not an odd integer, if \fIx\fP is -Inf, +0 shall +be returned. +.LP +For \fIy\fP an odd integer > 0, if \fIx\fP is -Inf, -Inf shall be +returned. +.LP +For \fIy\fP > 0 and not an odd integer, if \fIx\fP is -Inf, +Inf shall +be returned. +.LP +For \fIy\fP < 0, if \fIx\fP is +Inf, +0 shall be returned. +.LP +For \fIy\fP > 0, if \fIx\fP is +Inf, +Inf shall be returned. +.LP +For \fIy\fP an odd integer < 0, if \fIx\fP is \(+-0, a pole error +shall occur and \(+-HUGE_VAL, \(+-HUGE_VALF, +and \(+-HUGE_VALL shall be returned for \fIpow\fP(), \fIpowf\fP(), +and \fIpowl\fP(), respectively. +.LP +For \fIy\fP < 0 and not an odd integer, if \fIx\fP is \(+-0, a pole +error shall occur and HUGE_VAL, HUGE_VALF, and +HUGE_VALL shall be returned for \fIpow\fP(), \fIpowf\fP(), and \fIpowl\fP(), +respectively. +.LP +If the correct value would cause underflow, and is representable, +a range error may occur and the correct value shall be +returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The value of \fIx\fP is negative and \fIy\fP is a finite non-integer. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be +raised. +.TP 7 +Pole\ Error +The value of \fIx\fP is zero and \fIy\fP is negative. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the divide-by-zero floating-point exception shall be +raised. +.TP 7 +Range\ Error +The result overflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be +raised. +.sp +.LP +These functions may fail if: +.TP 7 +Range\ Error +The result underflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexp\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/powf.3p b/man3p/powf.3p new file mode 100644 index 000000000..37209b025 --- /dev/null +++ b/man3p/powf.3p @@ -0,0 +1 @@ +.so man3p/pow.3p diff --git a/man3p/powl.3p b/man3p/powl.3p new file mode 100644 index 000000000..37209b025 --- /dev/null +++ b/man3p/powl.3p @@ -0,0 +1 @@ +.so man3p/pow.3p diff --git a/man3p/pread.3p b/man3p/pread.3p new file mode 100644 index 000000000..01503bd95 --- /dev/null +++ b/man3p/pread.3p @@ -0,0 +1 @@ +.so man3p/read.3p diff --git a/man3p/printf.3p b/man3p/printf.3p new file mode 100644 index 000000000..c608d8747 --- /dev/null +++ b/man3p/printf.3p @@ -0,0 +1,975 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FPRINTF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fprintf +.SH NAME +fprintf, printf, snprintf, sprintf \- print formatted output +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fprintf(FILE *restrict\fP \fIstream\fP\fB, const char *restrict\fP +\fIformat\fP\fB, ...); +.br +int printf(const char *restrict\fP \fIformat\fP\fB, ...); +.br +int snprintf(char *restrict\fP \fIs\fP\fB, size_t\fP \fIn\fP\fB, +.br +\ \ \ \ \ \ const char *restrict\fP \fIformat\fP\fB, ...); +.br +int sprintf(char *restrict\fP \fIs\fP\fB, const char *restrict\fP +\fIformat\fP\fB, ...); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfprintf\fP() function shall place output on the named output +\fIstream\fP. The \fIprintf\fP() function shall place +output on the standard output stream \fIstdout\fP. The \fIsprintf\fP() +function shall place output followed by the null byte, +\fB'\\0'\fP , in consecutive bytes starting at *\fIs\fP; it is the +user's responsibility to ensure that enough space is +available. +.LP +The \fIsnprintf\fP() function shall be equivalent to \fIsprintf\fP(), +with the addition of the \fIn\fP argument which states +the size of the buffer referred to by \fIs\fP. If \fIn\fP is zero, +nothing shall be written and \fIs\fP may be a null pointer. +Otherwise, output bytes beyond the \fIn\fP-1st shall be discarded +instead of being written to the array, and a null byte is +written at the end of the bytes actually written into the array. +.LP +If copying takes place between objects that overlap as a result of +a call to \fIsprintf\fP() or \fIsnprintf\fP(), the results +are undefined. +.LP +Each of these functions converts, formats, and prints its arguments +under control of the \fIformat\fP. The \fIformat\fP is a +character string, beginning and ending in its initial shift state, +if any. The \fIformat\fP is composed of zero or more +directives: \fIordinary characters\fP, which are simply copied to +the output stream, and \fIconversion specifications\fP, each of +which shall result in the fetching of zero or more arguments. The +results are undefined if there are insufficient arguments for the +\fIformat\fP. If the \fIformat\fP is exhausted while arguments remain, +the excess arguments shall be evaluated but are otherwise +ignored. +.LP +Conversions can be applied to the \fIn\fPth argument after the \fIformat\fP +in the argument list, rather than to the next unused +argument. In this case, the conversion specifier character \fB%\fP +(see below) is replaced by the sequence +\fB"%\fP\fIn\fP\fB$"\fP, where \fIn\fP is a decimal integer in the +range [1,{NL_ARGMAX}], giving the position of the +argument in the argument list. This feature provides for the definition +of format strings that select arguments in an order +appropriate to specific languages (see the EXAMPLES section). +.LP +The \fIformat\fP can contain either numbered argument conversion specifications +(that is, \fB"%\fP\fIn\fP\fB$"\fP and +\fB"*\fP\fIm\fP\fB$"\fP), or unnumbered argument conversion specifications +(that is, \fB%\fP and \fB*\fP ), but not +both. The only exception to this is that \fB%%\fP can be mixed with +the \fB"%\fP\fIn\fP\fB$"\fP form. The results of +mixing numbered and unnumbered argument specifications in a \fIformat\fP +string are undefined. When numbered argument +specifications are used, specifying the \fIN\fPth argument requires +that all the leading arguments, from the first to the +(\fIN-1\fP)th, are specified in the format string. +.LP +In format strings containing the \fB"%\fP\fIn\fP\fB$"\fP form of conversion +specification, numbered arguments in the +argument list can be referenced from the format string as many times +as required. +.LP +In format strings containing the \fB%\fP form of conversion specification, +each conversion specification uses the first +unused argument in the argument list. +.LP +All +forms of the \fIfprintf\fP() functions allow for the insertion of +a language-dependent radix character in the output string. The +radix character is defined in the program's locale (category \fILC_NUMERIC +).\fP In the POSIX locale, or in a locale where the +radix character is not defined, the radix character shall default +to a period ( \fB'.'\fP ). +.LP +Each conversion specification is introduced by the \fB'%'\fP character +\ or by the +character sequence \fB"%\fP\fIn\fP\fB$"\fP, after which the +following appear in sequence: +.IP " *" 3 +Zero or more \fIflags\fP (in any order), which modify the meaning +of the conversion specification. +.LP +.IP " *" 3 +An optional minimum \fIfield width\fP. If the converted value has +fewer bytes than the field width, it shall be padded with +spaces by default on the left; it shall be padded on the right if +the left-adjustment flag ( \fB'-'\fP ), described below, is +given to the field width. The field width takes the form of an asterisk +( \fB'*'\fP ), described below, or a decimal +integer. +.LP +.IP " *" 3 +An optional \fIprecision\fP that gives the minimum number of digits +to appear for the \fBd\fP , \fBi\fP , \fBo\fP , +\fBu\fP , \fBx\fP , and \fBX\fP conversion specifiers; the number +of digits to appear after the radix character for the +\fBa\fP , \fBA\fP , \fBe\fP , \fBE\fP , \fBf\fP , and \fBF\fP conversion +specifiers; the maximum number of +significant digits for the \fBg\fP and \fBG\fP conversion specifiers; +or the maximum number of bytes to be printed from a +string in the \fBs\fP \ and \fBS\fP \ conversion +specifiers. The precision takes the form of a period ( \fB'.'\fP ) +followed either by an asterisk ( \fB'*'\fP ), described +below, or an optional decimal digit string, where a null digit string +is treated as zero. If a precision appears with any other +conversion specifier, the behavior is undefined. +.LP +.IP " *" 3 +An optional length modifier that specifies the size of the argument. +.LP +.IP " *" 3 +A \fIconversion specifier\fP character that indicates the type of +conversion to be applied. +.LP +.LP +A field width, or precision, or both, may be indicated by an asterisk +( \fB'*'\fP ). In this case an argument of type +\fBint\fP supplies the field width or precision. Applications shall +ensure that arguments specifying field width, or precision, or +both appear in that order before the argument, if any, to be converted. +A negative field width is taken as a \fB'-'\fP flag +followed by a positive field width. A negative precision is taken +as if the precision were omitted. \ In format +strings containing the \fB"%\fP\fIn\fP\fB$"\fP form of a conversion +specification, a field width or precision may be +indicated by the sequence \fB"*\fP\fIm\fP\fB$"\fP, where \fIm\fP is +a decimal integer in the range [1,{NL_ARGMAX}] giving +the position in the argument list (after the \fIformat\fP argument) +of an integer argument containing the field width or +precision, for example: +.sp +.RS +.nf + +\fBprintf("%1$d:%2$.*3$d:%4$.*3$d\\n", hour, min, precision, sec); +\fP +.fi +.RE +.LP +The flag characters and their meanings are: +.TP 7 +\fB'\fP +The integer portion of the result of a decimal conversion ( \fB%i\fP +, \fB%d\fP , \fB%u\fP , \fB%f\fP , \fB%F\fP , +\fB%g\fP , or \fB%G\fP ) shall be formatted with thousands' grouping +characters. For other conversions the behavior is +undefined. The non-monetary grouping character is used. +.TP 7 +\fB-\fP +The result of the conversion shall be left-justified within the field. +The conversion is right-justified if this flag is not +specified. +.TP 7 +\fB+\fP +The result of a signed conversion shall always begin with a sign ( +\fB'+'\fP or \fB'-'\fP ). The conversion shall begin +with a sign only when a negative value is converted if this flag is +not specified. +.TP 7 + +If the first character of a signed conversion is not a sign or if +a signed conversion results in no characters, a +shall be prefixed to the result. This means that if the and +\fB'+'\fP flags both appear, the flag +shall be ignored. +.TP 7 +\fB#\fP +Specifies that the value is to be converted to an alternative form. +For \fBo\fP conversion, it increases the precision (if +necessary) to force the first digit of the result to be zero. For +\fBx\fP or \fBX\fP conversion specifiers, a non-zero result +shall have 0x (or 0X) prefixed to it. For \fBa\fP , \fBA\fP , \fBe\fP +, \fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP +, and \fBG\fP conversion specifiers, the result shall always contain +a radix character, even if no digits follow the radix +character. Without this flag, a radix character appears in the result +of these conversions only if a digit follows it. For +\fBg\fP and \fBG\fP conversion specifiers, trailing zeros shall \fInot\fP +be removed from the result as they normally are. +For other conversion specifiers, the behavior is undefined. +.TP 7 +\fB0\fP +For \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , \fBx\fP , \fBX\fP , \fBa\fP +, \fBA\fP , \fBe\fP , +\fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP , and \fBG\fP conversion specifiers, +leading zeros (following any indication +of sign or base) are used to pad to the field width; no space padding +is performed. If the \fB'0'\fP and \fB'-'\fP flags both +appear, the \fB'0'\fP flag is ignored. For \fBd\fP , \fBi\fP , \fBo\fP +, \fBu\fP , \fBx\fP , and \fBX\fP +conversion specifiers, if a precision is specified, the \fB'0'\fP +flag is ignored. \ If the +\fB'0'\fP and \fB'"\fP flags both appear, the grouping characters +are inserted before zero padding. For other conversions, +the behavior is undefined. +.sp +.LP +The length modifiers and their meanings are: +.TP 7 +\fBhh\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , or \fBX\fP conversion specifier +applies to a \fBsigned char\fP or \fBunsigned char\fP argument (the +argument will have been promoted according to the integer +promotions, but its value shall be converted to \fBsigned char\fP +or \fBunsigned char\fP before printing); or that a following +\fBn\fP conversion specifier applies to a pointer to a \fBsigned char\fP +argument. +.TP 7 +\fBh\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , or \fBX\fP conversion specifier +applies to a \fBshort\fP or \fBunsigned short\fP argument (the argument +will have been promoted according to the integer +promotions, but its value shall be converted to \fBshort\fP or \fBunsigned +short\fP before printing); or that a following +\fBn\fP conversion specifier applies to a pointer to a \fBshort\fP +argument. +.TP 7 +\fBl\fP\ (ell) +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , or \fBX\fP conversion specifier +applies to a \fBlong\fP or \fBunsigned long\fP argument; that a following +\fBn\fP conversion specifier applies to a pointer to +a \fBlong\fP argument; that a following \fBc\fP conversion specifier +applies to a \fBwint_t\fP argument; that a following +\fBs\fP conversion specifier applies to a pointer to a \fBwchar_t\fP +argument; or has no effect on a following \fBa\fP , +\fBA\fP , \fBe\fP , \fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP , or \fBG\fP +conversion specifier. +.TP 7 +\fBll\fP\ (ell-ell) +.sp +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , or \fBX\fP conversion specifier +applies to a \fBlong long\fP or \fBunsigned long long\fP argument; +or that a following \fBn\fP conversion specifier applies to +a pointer to a \fBlong long\fP argument. +.TP 7 +\fBj\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , or \fBX\fP conversion specifier +applies to an \fBintmax_t\fP or \fBuintmax_t\fP argument; or that +a following \fBn\fP conversion specifier applies to a +pointer to an \fBintmax_t\fP argument. +.TP 7 +\fBz\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , or \fBX\fP conversion specifier +applies to a \fBsize_t\fP or the corresponding signed integer type +argument; or that a following \fBn\fP conversion specifier +applies to a pointer to a signed integer type corresponding to a \fBsize_t\fP +argument. +.TP 7 +\fBt\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , or \fBX\fP conversion specifier +applies to a \fBptrdiff_t\fP or the corresponding \fBunsigned\fP type +argument; or that a following \fBn\fP conversion +specifier applies to a pointer to a \fBptrdiff_t\fP argument. +.TP 7 +\fBL\fP +Specifies that a following \fBa\fP , \fBA\fP , \fBe\fP , \fBE\fP , +\fBf\fP , \fBF\fP , \fBg\fP , or +\fBG\fP conversion specifier applies to a \fBlong double\fP argument. +.sp +.LP +If a length modifier appears with any conversion specifier other than +as specified above, the behavior is undefined. +.LP +The conversion specifiers and their meanings are: +.TP 7 +\fBd\fP,\ \fBi\fP +The \fBint\fP argument shall be converted to a signed decimal in the +style \fB"[-]\fP\fIdddd\fP\fB"\fP. The precision +specifies the minimum number of digits to appear; if the value being +converted can be represented in fewer digits, it shall be +expanded with leading zeros. The default precision is 1. The result +of converting zero with an explicit precision of zero shall be +no characters. +.TP 7 +\fBo\fP +The \fBunsigned\fP argument shall be converted to unsigned octal format +in the style \fB"\fP\fIdddd\fP\fB"\fP. The +precision specifies the minimum number of digits to appear; if the +value being converted can be represented in fewer digits, it +shall be expanded with leading zeros. The default precision is 1. +The result of converting zero with an explicit precision of zero +shall be no characters. +.TP 7 +\fBu\fP +The \fBunsigned\fP argument shall be converted to unsigned decimal +format in the style \fB"\fP\fIdddd\fP\fB"\fP. The +precision specifies the minimum number of digits to appear; if the +value being converted can be represented in fewer digits, it +shall be expanded with leading zeros. The default precision is 1. +The result of converting zero with an explicit precision of zero +shall be no characters. +.TP 7 +\fBx\fP +The \fBunsigned\fP argument shall be converted to unsigned hexadecimal +format in the style \fB"\fP\fIdddd\fP\fB"\fP; +the letters \fB"abcdef"\fP are used. The precision specifies the minimum +number of digits to appear; if the value being +converted can be represented in fewer digits, it shall be expanded +with leading zeros. The default precision is 1. The result of +converting zero with an explicit precision of zero shall be no characters. +.TP 7 +\fBX\fP +Equivalent to the \fBx\fP conversion specifier, except that letters +\fB"ABCDEF"\fP are used instead of \fB"abcdef"\fP +\&. +.TP 7 +\fBf\fP,\ \fBF\fP +The \fBdouble\fP argument shall be converted to decimal notation in +the style +\fB"[-]\fP\fIddd\fP\fB.\fP\fIddd\fP\fB"\fP, where the number of digits +after the radix character is equal to the +precision specification. If the precision is missing, it shall be +taken as 6; if the precision is explicitly zero and no +\fB'#'\fP flag is present, no radix character shall appear. If a radix +character appears, at least one digit appears before it. +The low-order digit shall be rounded in an implementation-defined +manner. +.LP +A \fBdouble\fP argument representing an infinity shall be converted +in one of the styles \fB"[-]inf"\fP or +\fB"[-]infinity"\fP ; which style is implementation-defined. A \fBdouble\fP +argument representing a NaN shall be converted in +one of the styles \fB"[-]nan(\fP\fIn-char-sequence\fP\fB)"\fP or \fB"[-]nan"\fP +; which style, and the meaning of any +\fIn-char-sequence\fP, is implementation-defined. The \fBF\fP conversion +specifier produces \fB"INF"\fP , +\fB"INFINITY"\fP , or \fB"NAN"\fP instead of \fB"inf"\fP , \fB"infinity"\fP +, or \fB"nan"\fP , respectively. +.TP 7 +\fBe\fP,\ \fBE\fP +The \fBdouble\fP argument shall be converted in the style +\fB"[-]\fP\fId\fP\fB.\fP\fIddd\fP\fBe\(+-\fP\fIdd\fP\fB"\fP, where +there is one digit before the radix character +(which is non-zero if the argument is non-zero) and the number of +digits after it is equal to the precision; if the precision is +missing, it shall be taken as 6; if the precision is zero and no \fB'#'\fP +flag is present, no radix character shall appear. The +low-order digit shall be rounded in an implementation-defined manner. +The \fBE\fP conversion specifier shall produce a number +with \fB'E'\fP instead of \fB'e'\fP introducing the exponent. The +exponent shall always contain at least two digits. If the +value is zero, the exponent shall be zero. +.LP +A \fBdouble\fP argument representing an infinity or NaN shall be converted +in the style of an \fBf\fP or \fBF\fP +conversion specifier. +.TP 7 +\fBg\fP,\ \fBG\fP +The \fBdouble\fP argument shall be converted in the style \fBf\fP +or \fBe\fP (or in the style \fBF\fP or \fBE\fP +in the case of a \fBG\fP conversion specifier), with the precision +specifying the number of significant digits. If an explicit +precision is zero, it shall be taken as 1. The style used depends +on the value converted; style \fBe\fP (or \fBE\fP ) shall +be used only if the exponent resulting from such a conversion is less +than -4 or greater than or equal to the precision. Trailing +zeros shall be removed from the fractional portion of the result; +a radix character shall appear only if it is followed by a digit +or a \fB'#'\fP flag is present. +.LP +A \fBdouble\fP argument representing an infinity or NaN shall be converted +in the style of an \fBf\fP or \fBF\fP +conversion specifier. +.TP 7 +\fBa\fP,\ \fBA\fP +A \fBdouble\fP argument representing a floating-point number shall +be converted in the style +\fB"[-]0x\fP\fIh\fP\fB.\fP\fIhhhh\fP\fBp\(+-\fP\fId\fP\fB"\fP, where +there is one hexadecimal digit (which shall +be non-zero if the argument is a normalized floating-point number +and is otherwise unspecified) before the decimal-point character +and the number of hexadecimal digits after it is equal to the precision; +if the precision is missing and FLT_RADIX is a power of 2, +then the precision shall be sufficient for an exact representation +of the value; if the precision is missing and FLT_RADIX is not a +power of 2, then the precision shall be sufficient to distinguish +values of type \fBdouble\fP, except that trailing zeros may be +omitted; if the precision is zero and the \fB'#'\fP flag is not specified, +no decimal-point character shall appear. The letters +\fB"abcdef"\fP shall be used for \fBa\fP conversion and the letters +\fB"ABCDEF"\fP for \fBA\fP conversion. The +\fBA\fP conversion specifier produces a number with \fB'X'\fP and +\fB'P'\fP instead of \fB'x'\fP and \fB'p'\fP . The +exponent shall always contain at least one digit, and only as many +more digits as necessary to represent the decimal exponent of 2. +If the value is zero, the exponent shall be zero. +.LP +A \fBdouble\fP argument representing an infinity or NaN shall be converted +in the style of an \fBf\fP or \fBF\fP +conversion specifier. +.TP 7 +\fBc\fP +The \fBint\fP argument shall be converted to an \fBunsigned char\fP, +and the resulting byte shall be written. +.LP +If an \fBl\fP (ell) qualifier is present, the \fBwint_t\fP argument +shall be converted as if by an \fBls\fP conversion +specification with no precision and an argument that points to a two-element +array of type \fBwchar_t\fP, the first element of +which contains the \fBwint_t\fP argument to the \fBls\fP conversion +specification and the second element contains a null wide +character. +.TP 7 +\fBs\fP +The argument shall be a pointer to an array of \fBchar\fP. Bytes from +the array shall be written up to (but not including) any +terminating null byte. If the precision is specified, no more than +that many bytes shall be written. If the precision is not +specified or is greater than the size of the array, the application +shall ensure that the array contains a null byte. +.LP +If an \fBl\fP (ell) qualifier is present, the argument shall be a +pointer to an array of type \fBwchar_t\fP. Wide characters +from the array shall be converted to characters (each as if by a call +to the \fIwcrtomb\fP() function, with the conversion state described +by an \fBmbstate_t\fP object +initialized to zero before the first wide character is converted) +up to and including a terminating null wide character. The +resulting characters shall be written up to (but not including) the +terminating null character (byte). If no precision is +specified, the application shall ensure that the array contains a +null wide character. If a precision is specified, no more than +that many characters (bytes) shall be written (including shift sequences, +if any), and the array shall contain a null wide +character if, to equal the character sequence length given by the +precision, the function would need to access a wide character one +past the end of the array. In no case shall a partial character be +written. +.TP 7 +\fBp\fP +The argument shall be a pointer to \fBvoid\fP. The value of the pointer +is converted to a sequence of printable characters, in +an implementation-defined manner. +.TP 7 +\fBn\fP +The argument shall be a pointer to an integer into which is written +the number of bytes written to the output so far by this +call to one of the \fIfprintf\fP() functions. No argument is converted. +.TP 7 +\fBC\fP +Equivalent to \fBlc\fP . +.TP 7 +\fBS\fP +Equivalent to \fBls\fP . +.TP 7 +\fB%\fP +Print a \fB'%'\fP character; no argument is converted. The complete +conversion specification shall be \fB%%\fP . +.sp +.LP +If a conversion specification does not match one of the above forms, +the behavior is undefined. If any argument is not the +correct type for the corresponding conversion specification, the behavior +is undefined. +.LP +In no case shall 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 shall be expanded to contain the conversion +result. Characters generated by \fIfprintf\fP() and +\fIprintf\fP() are printed as if \fIfputc\fP() had been called. +.LP +For the \fBa\fP and \fBA\fP conversion specifiers, if FLT_RADIX is +a power of 2, the value shall be correctly rounded to a +hexadecimal floating number with the given precision. +.LP +For \fBa\fP and \fBA\fP conversions, if FLT_RADIX is not a power of +2 and the result is not exactly representable in the +given precision, the result should be one of the two adjacent numbers +in hexadecimal floating style with the given precision, with +the extra stipulation that the error should have a correct sign for +the current rounding direction. +.LP +For the \fBe\fP , \fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP , and \fBG\fP +conversion specifiers, if the number of +significant decimal digits is at most DECIMAL_DIG, then the result +should be correctly rounded. If the number of significant +decimal digits is more than DECIMAL_DIG but the source value is exactly +representable with DECIMAL_DIG digits, then the result +should be an exact representation with trailing zeros. Otherwise, +the source value is bounded by two adjacent decimal strings +\fIL\fP < \fIU\fP, both having DECIMAL_DIG significant digits; the +value of the resultant decimal string \fID\fP should +satisfy \fIL\fP <= \fID\fP <= \fIU\fP, with the extra stipulation +that the error should have a correct sign for the +current rounding direction. +.LP +The +\fIst_ctime\fP and \fIst_mtime\fP fields of the file shall be marked +for update between the call to a successful execution of +\fIfprintf\fP() or \fIprintf\fP() and the next successful completion +of a call to \fIfflush\fP() or \fIfclose\fP() on the same stream or +a +call to \fIexit\fP() or \fIabort\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, the \fIfprintf\fP() and \fIprintf\fP() +functions shall return the number of bytes transmitted. +.LP +Upon successful completion, the \fIsprintf\fP() function shall return +the number of bytes written to \fIs\fP, excluding the +terminating null byte. +.LP +Upon successful completion, the \fIsnprintf\fP() function shall return +the number of bytes that would be written to \fIs\fP +had \fIn\fP been sufficiently large excluding the terminating null +byte. +.LP +If an output error was encountered, these functions shall return a +negative value. +.LP +If the value of \fIn\fP is zero on a call to \fIsnprintf\fP(), nothing +shall be written, the number of bytes that would have +been written had \fIn\fP been sufficiently large excluding the terminating +null shall be returned, and \fIs\fP may be a null +pointer. +.SH ERRORS +.LP +For the conditions under which \fIfprintf\fP() and \fIprintf\fP() +fail and may fail, refer to \fIfputc\fP() or \fIfputwc\fP() . +.LP +In addition, all forms of \fIfprintf\fP() may fail if: +.TP 7 +.B EILSEQ +A wide-character code that does not correspond to a valid character +has been detected. +.TP 7 +.B EINVAL +There are insufficient arguments. +.sp +.LP +The \fIprintf\fP() and \fIfprintf\fP() functions may fail if: +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.sp +.LP +The \fIsnprintf\fP() function shall fail if: +.TP 7 +.B EOVERFLOW +The value of \fIn\fP is greater than {INT_MAX} or the number of bytes +needed to hold the output excluding the terminating null is +greater than {INT_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Printing Language-Independent Date and Time +.LP +The following statement can be used to print date and time using a +language-independent format: +.sp +.RS +.nf + +\fBprintf(format, weekday, month, day, hour, min); +\fP +.fi +.RE +.LP +For American usage, \fIformat\fP could be a pointer to the following +string: +.sp +.RS +.nf + +\fB"%s, %s %d, %d:%.2d\\n" +\fP +.fi +.RE +.LP +This example would produce the following message: +.sp +.RS +.nf + +\fBSunday, July 3, 10:02 +\fP +.fi +.RE +.LP +For German usage, \fIformat\fP could be a pointer to the following +string: +.sp +.RS +.nf + +\fB"%1$s, %3$d. %2$s, %4$d:%5$.2d\\n" +\fP +.fi +.RE +.LP +This definition of \fIformat\fP would produce the following message: +.sp +.RS +.nf + +\fBSonntag, 3. Juli, 10:02 +\fP +.fi +.RE +.SS Printing File Information +.LP +The following example prints information about the type, permissions, +and number of links of a specific file in a directory. +.LP +The first two calls to \fIprintf\fP() use data decoded from a previous +\fIstat\fP() call. +The user-defined \fIstrperm\fP() function shall return a string similar +to the one at the beginning of the output for the +following command: +.sp +.RS +.nf + +\fBls -l +\fP +.fi +.RE +.LP +The next call to \fIprintf\fP() outputs the owner's name if it is +found using \fIgetpwuid\fP(); the \fIgetpwuid\fP() function shall +return a \fBpasswd\fP structure from which the name of the user is +extracted. If the user name is not found, the program instead +prints out the numeric value of the user ID. +.LP +The next call prints out the group name if it is found using \fIgetgrgid\fP(); +\fIgetgrgid\fP() is very similar to \fIgetpwuid\fP() except that it +shall return group information based on the group number. Once +again, if the group is not found, the program prints the numeric value +of the group for the entry. +.LP +The final call to \fIprintf\fP() prints the size of the file. +.sp +.RS +.nf + +\fB#include +#include +#include +#include +.sp + +char *strperm (mode_t); +\&... +struct stat statbuf; +struct passwd *pwd; +struct group *grp; +\&... +printf("%10.10s", strperm (statbuf.st_mode)); +printf("%4d", statbuf.st_nlink); +.sp + +if ((pwd = getpwuid(statbuf.st_uid)) != NULL) + printf(" %-8.8s", pwd->pw_name); +else + printf(" %-8ld", (long) statbuf.st_uid); +.sp + +if ((grp = getgrgid(statbuf.st_gid)) != NULL) + printf(" %-8.8s", grp->gr_name); +else + printf(" %-8ld", (long) statbuf.st_gid); +.sp + +printf("%9jd", (intmax_t) statbuf.st_size); +\&... +\fP +.fi +.RE +.SS Printing a Localized Date String +.LP +The following example gets a localized date string. The \fInl_langinfo\fP() +function shall return the localized date string, which specifies the +order and layout of the date. The \fIstrftime\fP() function takes +this information and, using the \fBtm\fP structure for values, +places the date and time information into \fIdatestring\fP. The \fIprintf\fP() +function then outputs \fIdatestring\fP and the +name of the entry. +.sp +.RS +.nf + +\fB#include +#include +#include +\&... +struct dirent *dp; +struct tm *tm; +char datestring[256]; +\&... +strftime(datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm); +.sp + +printf(" %s %s\\n", datestring, dp->d_name); +\&... +\fP +.fi +.RE +.SS Printing Error Information +.LP +The following example uses \fIfprintf\fP() to write error information +to standard error. +.LP +In the first group of calls, the program tries to open the password +lock file named \fBLOCKFILE\fP. If the file already exists, +this is an error, as indicated by the O_EXCL flag on the \fIopen\fP() +function. If the call +fails, the program assumes that someone else is updating the password +file, and the program exits. +.LP +The next group of calls saves a new password file as the current password +file by creating a link between \fBLOCKFILE\fP and +the new password file \fBPASSWDFILE\fP. +.sp +.RS +.nf + +\fB#include +#include +#include +#include +#include +#include +#include +#include +.sp + +#define LOCKFILE "/etc/ptmp" +#define PASSWDFILE "/etc/passwd" +\&... +int pfd; +\&... +if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL, + S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1) +{ + fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\\n"); + exit(1); +} +\&... +if (link(LOCKFILE,PASSWDFILE) == -1) { + fprintf(stderr, "Link error: %s\\n", strerror(errno)); + exit(1); +} +\&... +\fP +.fi +.RE +.SS Printing Usage Information +.LP +The following example checks to make sure the program has the necessary +arguments, and uses \fIfprintf\fP() to print usage +information if the expected number of arguments is not present. +.sp +.RS +.nf + +\fB#include +#include +\&... +char *Options = "hdbtl"; +\&... +if (argc < 2) { + fprintf(stderr, "Usage: %s -%s +\&... +long i; +char *keystr; +int elementlen, len; +\&... +while (len < elementlen) { +\&... + printf("%s Element%0*ld\\n", keystr, elementlen, i); +\&... +} +\fP +.fi +.RE +.SS Creating a Filename +.LP +The following example creates a filename using information from a +previous \fIgetpwnam\fP() function that returned the HOME directory +of the user. +.sp +.RS +.nf + +\fB#include +#include +#include +\&... +char filename[PATH_MAX+1]; +struct passwd *pw; +\&... +sprintf(filename, "%s/%d.out", pw->pw_dir, getpid()); +\&... +\fP +.fi +.RE +.SS Reporting an Event +.LP +The following example loops until an event has timed out. The \fIpause\fP() +function +waits forever unless it receives a signal. The \fIfprintf\fP() statement +should never occur due to the possible return values of +\fIpause\fP(). +.sp +.RS +.nf + +\fB#include +#include +#include +#include +\&... +while (!event_complete) { +\&... + if (pause() != -1 || errno != EINTR) + fprintf(stderr, "pause: unknown error: %s\\n", strerror(errno)); +} +\&... +\fP +.fi +.RE +.SS Printing Monetary Information +.LP +The following example uses \fIstrfmon\fP() to convert a number and +store it as a +formatted monetary string named \fIconvbuf\fP. If the first number +is printed, the program prints the format and the description; +otherwise, it just prints the number. +.sp +.RS +.nf + +\fB#include +#include +\&... +struct tblfmt { + char *format; + char *description; +}; +.sp + +struct tblfmt table[] = { + { "%n", "default formatting" }, + { "%11n", "right align within an 11 character field" }, + { "%#5n", "aligned columns for values up to 99999" }, + { "%=*#5n", "specify a fill character" }, + { "%=0#5n", "fill characters do not use grouping" }, + { "%^#5n", "disable the grouping separator" }, + { "%^#5.0n", "round off to whole units" }, + { "%^#5.4n", "increase the precision" }, + { "%(#5n", "use an alternative pos/neg style" }, + { "%!(#5n", "disable the currency symbol" }, +}; +\&... +float input[3]; +int i, j; +char convbuf[100]; +\&... +strfmon(convbuf, sizeof(convbuf), table[i].format, input[j]); +.sp + +if (j == 0) { + printf("%s %s %s\\n", table[i].format, + convbuf, table[i].description); +} +else { + printf(" %s\\n", convbuf); +} +\&... +\fP +.fi +.RE +.SS Printing Wide Characters +.LP +The following example prints a series of wide characters. Suppose +that \fB"L`@`"\fP expands to three bytes: +.sp +.RS +.nf + +\fBwchar_t wz [3] = L"@@"; // Zero-terminated +wchar_t wn [3] = L"@@@"; // Unterminated +.sp + +fprintf (stdout,"%ls", wz); // Outputs 6 bytes +fprintf (stdout,"%ls", wn); // Undefined because wn has no terminator +fprintf (stdout,"%4ls", wz); // Outputs 3 bytes +fprintf (stdout,"%4ls", wn); // Outputs 3 bytes; no terminator needed +fprintf (stdout,"%9ls", wz); // Outputs 6 bytes +fprintf (stdout,"%9ls", wn); // Outputs 9 bytes; no terminator needed +fprintf (stdout,"%10ls", wz); // Outputs 6 bytes +fprintf (stdout,"%10ls", wn); // Undefined because wn has no terminator +\fP +.fi +.RE +.LP +In the last line of the example, after processing three characters, +nine bytes have been output. The fourth character must then +be examined to determine whether it converts to one byte or more. +If it converts to more than one byte, the output is only nine +bytes. Since there is no fourth character in the array, the behavior +is undefined. +.SH APPLICATION USAGE +.LP +If the application calling \fIfprintf\fP() has any objects of type +\fBwint_t\fP or \fBwchar_t\fP, it must also include the \fI\fP +header to have these objects defined. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfputc\fP() , \fIfscanf\fP() , \fIsetlocale\fP() , \fIstrfmon\fP() +, \fIwcrtomb\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 7, +Locale, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pselect.3p b/man3p/pselect.3p new file mode 100644 index 000000000..24347e495 --- /dev/null +++ b/man3p/pselect.3p @@ -0,0 +1 @@ +.so man3p/select.3p diff --git a/man3p/pthread_atfork.3p b/man3p/pthread_atfork.3p new file mode 100644 index 000000000..e272e5fb4 --- /dev/null +++ b/man3p/pthread_atfork.3p @@ -0,0 +1,153 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_ATFORK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_atfork +.SH NAME +pthread_atfork \- register fork handlers +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_atfork(void (*\fP\fIprepare\fP\fB)(void), void (*\fP\fIparent\fP\fB)(void), +.br +\ \ \ \ \ \ void (*\fP\fIchild\fP\fB)(void)); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_atfork\fP() function shall declare fork handlers to +be called before and after \fIfork\fP(), in the context of the thread +that called \fIfork\fP(). The \fIprepare\fP fork handler shall be +called before \fIfork\fP() processing commences. The \fIparent\fP +fork handle shall be called after \fIfork\fP() processing completes +in the parent process. The \fIchild\fP fork handler shall be +called after \fIfork\fP() processing completes in the child process. +If no handling is +desired at one or more of these three points, the corresponding fork +handler address(es) may be set to NULL. +.LP +The order of calls to \fIpthread_atfork\fP() is significant. The \fIparent\fP +and \fIchild\fP fork handlers shall be called +in the order in which they were established by calls to \fIpthread_atfork\fP(). +The \fIprepare\fP fork handlers shall be called +in the opposite order. +.SH RETURN VALUE +.LP +Upon successful completion, \fIpthread_atfork\fP() shall return a +value of zero; otherwise, an error number shall be returned +to indicate the error. +.SH ERRORS +.LP +The \fIpthread_atfork\fP() function shall fail if: +.TP 7 +.B ENOMEM +Insufficient table space exists to record the fork handler addresses. +.sp +.LP +The \fIpthread_atfork\fP() function shall not return an error code +of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +There are at least two serious problems with the semantics of \fIfork\fP() +in a +multi-threaded program. One problem has to do with state (for example, +memory) covered by mutexes. Consider the case where one +thread has a mutex locked and the state covered by that mutex is inconsistent +while another thread calls \fIfork\fP(). In the child, the mutex is +in the locked state (locked by a nonexistent thread and thus +can never be unlocked). Having the child simply reinitialize the mutex +is unsatisfactory since this approach does not resolve the +question about how to correct or otherwise deal with the inconsistent +state in the child. +.LP +It is suggested that programs that use \fIfork\fP() call an \fIexec\fP +function very soon afterwards in the child process, thus resetting +all states. In the +meantime, only a short list of async-signal-safe library routines +are promised to be available. +.LP +Unfortunately, this solution does not address the needs of multi-threaded +libraries. Application programs may not be aware that +a multi-threaded library is in use, and they feel free to call any +number of library routines between the \fIfork\fP() and \fIexec\fP +calls, just as they always have. +Indeed, they may be extant single-threaded programs and cannot, therefore, +be expected to obey new restrictions imposed by the +threads library. +.LP +On the other hand, the multi-threaded library needs a way to protect +its internal state during \fIfork\fP() in case it is re-entered later +in the child process. The problem arises especially in +multi-threaded I/O libraries, which are almost sure to be invoked +between the \fIfork\fP() +and \fIexec\fP calls to effect I/O redirection. The solution may require +locking mutex +variables during \fIfork\fP(), or it may entail simply resetting the +state in the child after +the \fIfork\fP() processing completes. +.LP +The \fIpthread_atfork\fP() function provides multi-threaded libraries +with a means to protect themselves from innocent +application programs that call \fIfork\fP(), and it provides multi-threaded +application +programs with a standard mechanism for protecting themselves from +\fIfork\fP() calls in a +library routine or the application itself. +.LP +The expected usage is that the \fIprepare\fP handler acquires all +mutex locks and the other two fork handlers release them. +.LP +For example, an application can supply a \fIprepare\fP routine that +acquires the necessary mutexes the library maintains and +supply \fIchild\fP and \fIparent\fP routines that release those mutexes, +thus ensuring that the child gets a consistent snapshot +of the state of the library (and that no mutexes are left stranded). +Alternatively, some libraries might be able to supply just a +\fIchild\fP routine that reinitializes the mutexes in the library +and all associated states to some known value (for example, what +it was when the image was originally executed). +.LP +When \fIfork\fP() is called, only the calling thread is duplicated +in the child process. +Synchronization variables remain in the same state in the child as +they were in the parent at the time \fIfork\fP() was called. Thus, +for example, mutex locks may be held by threads that no longer exist +in the child process, and any associated states may be inconsistent. +The parent process may avoid this by explicit code that +acquires and releases locks critical to the child via \fIpthread_atfork\fP(). +In addition, any critical threads need to be +recreated and reinitialized to the proper state in the child (also +via \fIpthread_atfork\fP()). +.LP +A higher-level package may acquire locks on its own data structures +before invoking lower-level packages. Under this scenario, +the order specified for fork handler calls allows a simple rule of +initialization for avoiding package deadlock: a package +initializes all packages on which it depends before it calls the \fIpthread_atfork\fP() +function for itself. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIatexit\fP() , \fIfork\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_attr_destroy.3p b/man3p/pthread_attr_destroy.3p new file mode 100644 index 000000000..c453440f6 --- /dev/null +++ b/man3p/pthread_attr_destroy.3p @@ -0,0 +1 @@ +.so man3p/pthread_attr_init.3p diff --git a/man3p/pthread_attr_getdetachstate.3p b/man3p/pthread_attr_getdetachstate.3p new file mode 100644 index 000000000..6a5cc155a --- /dev/null +++ b/man3p/pthread_attr_getdetachstate.3p @@ -0,0 +1,92 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_ATTR_GETDETACHSTATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_attr_getdetachstate +.SH NAME +pthread_attr_getdetachstate, pthread_attr_setdetachstate \- get and +set the detachstate attribute +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_attr_getdetachstate(const pthread_attr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ int *\fP\fIdetachstate\fP\fB); +.br +int pthread_attr_setdetachstate(pthread_attr_t *\fP\fIattr\fP\fB, +int\fP \fIdetachstate\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIdetachstate\fP attribute controls whether the thread is created +in a detached state. If the thread is created detached, +then use of the ID of the newly created thread by the \fIpthread_detach\fP() +or \fIpthread_join\fP() function is an error. +.LP +The \fIpthread_attr_getdetachstate\fP() and \fIpthread_attr_setdetachstate\fP() +functions, respectively, shall get and set the +\fIdetachstate\fP attribute in the \fIattr\fP object. +.LP +For \fIpthread_attr_getdetachstate\fP(), \fIdetachstate\fP shall be +set to either PTHREAD_CREATE_DETACHED or +PTHREAD_CREATE_JOINABLE. +.LP +For \fIpthread_attr_setdetachstate\fP(), the application shall set +\fIdetachstate\fP to either PTHREAD_CREATE_DETACHED or +PTHREAD_CREATE_JOINABLE. +.LP +A value of PTHREAD_CREATE_DETACHED shall cause all threads created +with \fIattr\fP to be in the detached state, whereas using a +value of PTHREAD_CREATE_JOINABLE shall cause all threads created with +\fIattr\fP to be in the joinable state. The default value of +the \fIdetachstate\fP attribute shall be PTHREAD_CREATE_JOINABLE. +.SH RETURN VALUE +.LP +Upon successful completion, \fIpthread_attr_getdetachstate\fP() and +\fIpthread_attr_setdetachstate\fP() shall return a value +of 0; otherwise, an error number shall be returned to indicate the +error. +.LP +The \fIpthread_attr_getdetachstate\fP() function stores the value +of the \fIdetachstate\fP attribute in \fIdetachstate\fP if +successful. +.SH ERRORS +.LP +The \fIpthread_attr_setdetachstate\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of \fIdetachstate\fP was not valid +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_attr_destroy\fP() , \fIpthread_attr_getstackaddr\fP() , +\fIpthread_attr_getstacksize\fP() , \fIpthread_create\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_attr_getguardsize.3p b/man3p/pthread_attr_getguardsize.3p new file mode 100644 index 000000000..8d9b9440c --- /dev/null +++ b/man3p/pthread_attr_getguardsize.3p @@ -0,0 +1,122 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_ATTR_GETGUARDSIZE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_attr_getguardsize +.SH NAME +pthread_attr_getguardsize, pthread_attr_setguardsize \- get and set +the thread guardsize attribute +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_attr_getguardsize(const pthread_attr_t *restrict\fP \fIattr\fP\fB, +.br +\ \ \ \ \ \ size_t *restrict\fP \fIguardsize\fP\fB); +.br +int pthread_attr_setguardsize(pthread_attr_t\fP \fI*attr\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIguardsize\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_attr_getguardsize\fP() function shall get the \fIguardsize\fP +attribute in the \fIattr\fP object. This +attribute shall be returned in the \fIguardsize\fP parameter. +.LP +The \fIpthread_attr_setguardsize\fP() function shall set the \fIguardsize\fP +attribute in the \fIattr\fP object. The new +value of this attribute shall be obtained from the \fIguardsize\fP +parameter. If \fIguardsize\fP is zero, a guard area shall not +be provided for threads created with \fIattr\fP. If \fIguardsize\fP +is greater than zero, a guard area of at least size +\fIguardsize\fP bytes shall be provided for each thread created with +\fIattr\fP. +.LP +The \fIguardsize\fP attribute controls the size of the guard area +for the created thread's stack. The \fIguardsize\fP +attribute provides protection against overflow of the stack pointer. +If a thread's stack is created with guard protection, the +implementation allocates extra memory at the overflow end of the stack +as a buffer against stack overflow of the stack pointer. If +an application overflows into this buffer an error shall result (possibly +in a SIGSEGV signal being delivered to the thread). +.LP +A conforming implementation may round up the value contained in \fIguardsize\fP +to a multiple of the configurable system +variable {PAGESIZE} (see \fI\fP). If an implementation +rounds up the +value of \fIguardsize\fP to a multiple of {PAGESIZE}, a call to \fIpthread_attr_getguardsize\fP() +specifying \fIattr\fP shall +store in the \fIguardsize\fP parameter the guard size specified by +the previous \fIpthread_attr_setguardsize\fP() function +call. +.LP +The default value of the \fIguardsize\fP attribute is {PAGESIZE} bytes. +The actual value of {PAGESIZE} is +implementation-defined. +.LP +If the \fIstackaddr\fP or \fIstack\fP attribute has been set (that +is, the caller is allocating and managing its own thread +stacks), the \fIguardsize\fP attribute shall be ignored and no protection +shall be provided by the implementation. It is the +responsibility of the application to manage stack overflow along with +stack allocation and management in this case. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_attr_getguardsize\fP() and \fIpthread_attr_setguardsize\fP() +functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_attr_getguardsize\fP() and \fIpthread_attr_setguardsize\fP() +functions shall fail if: +.TP 7 +.B EINVAL +The attribute \fIattr\fP is invalid. +.TP 7 +.B EINVAL +The parameter \fIguardsize\fP is invalid. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIguardsize\fP attribute is provided to the application for two +reasons: +.IP " 1." 4 +Overflow protection can potentially result in wasted system resources. +An application that creates a large number of threads, +and which knows its threads never overflow their stack, can save system +resources by turning off guard areas. +.LP +.IP " 2." 4 +When threads allocate large data structures on the stack, large guard +areas may be needed to detect stack overflow. +.LP +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_attr_getinheritsched.3p b/man3p/pthread_attr_getinheritsched.3p new file mode 100644 index 000000000..116ec37e7 --- /dev/null +++ b/man3p/pthread_attr_getinheritsched.3p @@ -0,0 +1,103 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_ATTR_GETINHERITSCHED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_attr_getinheritsched +.SH NAME +pthread_attr_getinheritsched, pthread_attr_setinheritsched \- get and +set the inheritsched attribute (\fBREALTIME +THREADS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_attr_getinheritsched(const pthread_attr_t *restrict\fP +\fIattr\fP\fB, +.br +\ \ \ \ \ \ int *restrict\fP \fIinheritsched\fP\fB); +.br +int pthread_attr_setinheritsched(pthread_attr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIinheritsched\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_attr_getinheritsched\fP(), and \fIpthread_attr_setinheritsched\fP() +functions, respectively, shall get and set +the \fIinheritsched\fP attribute in the \fIattr\fP argument. +.LP +When the attributes objects are used by \fIpthread_create\fP(), the +\fIinheritsched\fP attribute determines how the other scheduling attributes +of the created thread shall be set. +.TP 7 +PTHREAD_INHERIT_SCHED +.sp +Specifies that the thread scheduling attributes shall be inherited +from the creating thread, and the scheduling attributes in this +\fIattr\fP argument shall be ignored. +.TP 7 +PTHREAD_EXPLICIT_SCHED +.sp +Specifies that the thread scheduling attributes shall be set to the +corresponding values from this attributes object. +.sp +.LP +The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED are defined +in the \fI\fP header. +.LP +The following thread scheduling attributes defined by IEEE\ Std\ 1003.1-2001 +are affected by the \fIinheritsched\fP +attribute: scheduling policy ( \fIschedpolicy\fP), scheduling parameters +( \fIschedparam\fP), and scheduling contention scope ( +\fIcontentionscope\fP). +.SH RETURN VALUE +.LP +If successful, the \fIpthread_attr_getinheritsched\fP() and \fIpthread_attr_setinheritsched\fP() +functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_attr_setinheritsched\fP() function may fail if: +.TP 7 +.B EINVAL +The value of \fIinheritsched\fP is not valid. +.TP 7 +.B ENOTSUP +An attempt was made to set the attribute to an unsupported value. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +After these attributes have been set, a thread can be created with +the specified attributes using \fIpthread_create\fP(). Using these +routines does not affect the current running +thread. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_attr_destroy\fP() , \fIpthread_attr_getscope\fP() , \fIpthread_attr_getschedpolicy\fP() +, \fIpthread_attr_getschedparam\fP() , \fIpthread_create\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_attr_getschedparam.3p b/man3p/pthread_attr_getschedparam.3p new file mode 100644 index 000000000..6775066c9 --- /dev/null +++ b/man3p/pthread_attr_getschedparam.3p @@ -0,0 +1,92 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_ATTR_GETSCHEDPARAM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_attr_getschedparam +.SH NAME +pthread_attr_getschedparam, pthread_attr_setschedparam \- get and set +the schedparam attribute +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_attr_getschedparam(const pthread_attr_t *restrict\fP \fIattr\fP\fB, +.br +\ \ \ \ \ \ struct sched_param *restrict\fP \fIparam\fP\fB); +.br +int pthread_attr_setschedparam(pthread_attr_t *restrict\fP \fIattr\fP\fB, +.br +\ \ \ \ \ \ const struct sched_param *restrict\fP \fIparam\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_attr_getschedparam\fP(), and \fIpthread_attr_setschedparam\fP() +functions, respectively, shall get and set the +scheduling parameter attributes in the \fIattr\fP argument. The contents +of the \fIparam\fP structure are defined in the \fI\fP header. +For the SCHED_FIFO and SCHED_RR policies, the only required member +of +\fIparam\fP is \fIsched_priority\fP. +.LP +For the SCHED_SPORADIC policy, the required members of the \fIparam\fP +structure are \fIsched_priority\fP, +\fIsched_ss_low_priority\fP, \fIsched_ss_repl_period\fP, \fIsched_ss_init_budget\fP, +and \fIsched_ss_max_repl\fP. The specified +\fIsched_ss_repl_period\fP must be greater than or equal to the specified +\fIsched_ss_init_budget\fP for the function to succeed; +if it is not, then the function shall fail. The value of \fIsched_ss_max_repl\fP +shall be within the inclusive range [1, +{SS_REPL_MAX}] for the function to succeed; if not, the function shall +fail. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_attr_getschedparam\fP() and \fIpthread_attr_setschedparam\fP() +functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_attr_setschedparam\fP() function may fail if: +.TP 7 +.B EINVAL +The value of \fIparam\fP is not valid. +.TP 7 +.B ENOTSUP +An attempt was made to set the attribute to an unsupported value. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +After these attributes have been set, a thread can be created with +the specified attributes using \fIpthread_create\fP(). Using these +routines does not affect the current running +thread. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_attr_destroy\fP() , \fIpthread_attr_getscope\fP() , \fIpthread_attr_getinheritsched\fP() +, \fIpthread_attr_getschedpolicy\fP() , \fIpthread_create\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_attr_getschedpolicy.3p b/man3p/pthread_attr_getschedpolicy.3p new file mode 100644 index 000000000..7f8878276 --- /dev/null +++ b/man3p/pthread_attr_getschedpolicy.3p @@ -0,0 +1,83 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_ATTR_GETSCHEDPOLICY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_attr_getschedpolicy +.SH NAME +pthread_attr_getschedpolicy, pthread_attr_setschedpolicy \- get and +set the schedpolicy attribute (\fBREALTIME +THREADS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_attr_getschedpolicy(const pthread_attr_t *restrict\fP +\fIattr\fP\fB, +.br +\ \ \ \ \ \ int *restrict\fP \fIpolicy\fP\fB); +.br +int pthread_attr_setschedpolicy(pthread_attr_t *\fP\fIattr\fP\fB, +int\fP \fIpolicy\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_attr_getschedpolicy\fP() and \fIpthread_attr_setschedpolicy\fP() +functions, respectively, shall get and set the +\fIschedpolicy\fP attribute in the \fIattr\fP argument. +.LP +The supported values of \fIpolicy\fP shall include SCHED_FIFO, SCHED_RR, +and SCHED_OTHER, which are defined in the \fI\fP header. +When threads executing with the scheduling policy SCHED_FIFO, +SCHED_RR, \ or SCHED_SPORADIC are waiting on a mutex, they +shall acquire the mutex in priority order when the mutex is unlocked. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_attr_getschedpolicy\fP() and \fIpthread_attr_setschedpolicy\fP() +functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_attr_setschedpolicy\fP() function may fail if: +.TP 7 +.B EINVAL +The value of \fIpolicy\fP is not valid. +.TP 7 +.B ENOTSUP +An attempt was made to set the attribute to an unsupported value. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +After these attributes have been set, a thread can be created with +the specified attributes using \fIpthread_create\fP(). Using these +routines does not affect the current running +thread. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_attr_destroy\fP() , \fIpthread_attr_getscope\fP() , \fIpthread_attr_getinheritsched\fP() +, \fIpthread_attr_getschedparam\fP() , \fIpthread_create\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_attr_getscope.3p b/man3p/pthread_attr_getscope.3p new file mode 100644 index 000000000..22be4816f --- /dev/null +++ b/man3p/pthread_attr_getscope.3p @@ -0,0 +1,82 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_ATTR_GETSCOPE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_attr_getscope +.SH NAME +pthread_attr_getscope, pthread_attr_setscope \- get and set the contentionscope +attribute (\fBREALTIME +THREADS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_attr_getscope(const pthread_attr_t *restrict\fP \fIattr\fP\fB, +.br +\ \ \ \ \ \ int *restrict\fP \fIcontentionscope\fP\fB); +.br +int pthread_attr_setscope(pthread_attr_t *\fP\fIattr\fP\fB, int\fP +\fIcontentionscope\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_attr_getscope\fP() and \fIpthread_attr_setscope\fP() +functions, respectively, shall get and set the +\fIcontentionscope\fP attribute in the \fIattr\fP object. +.LP +The \fIcontentionscope\fP attribute may have the values PTHREAD_SCOPE_SYSTEM, +signifying system scheduling contention scope, or +PTHREAD_SCOPE_PROCESS, signifying process scheduling contention scope. +The symbols PTHREAD_SCOPE_SYSTEM and PTHREAD_SCOPE_PROCESS +are defined in the \fI\fP header. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_attr_getscope\fP() and \fIpthread_attr_setscope\fP() +functions shall return zero; otherwise, an +error number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_attr_setscope\fP() function may fail if: +.TP 7 +.B EINVAL +The value of \fIcontentionscope\fP is not valid. +.TP 7 +.B ENOTSUP +An attempt was made to set the attribute to an unsupported value. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +After these attributes have been set, a thread can be created with +the specified attributes using \fIpthread_create\fP(). Using these +routines does not affect the current running +thread. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_attr_destroy\fP() , \fIpthread_attr_getinheritsched\fP() +, \fIpthread_attr_getschedpolicy\fP() , \fIpthread_attr_getschedparam\fP() +, \fIpthread_create\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_attr_getstack.3p b/man3p/pthread_attr_getstack.3p new file mode 100644 index 000000000..b81e63fef --- /dev/null +++ b/man3p/pthread_attr_getstack.3p @@ -0,0 +1,113 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_ATTR_GETSTACK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_attr_getstack +.SH NAME +pthread_attr_getstack, pthread_attr_setstack \- get and set stack attributes +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +\fBint pthread_attr_getstack(const pthread_attr_t *restrict\fP \fIattr\fP\fB, +.br +\ \ \ \ \ \ void **restrict\fP \fIstackaddr\fP\fB, size_t *restrict\fP +\fIstacksize\fP\fB); +.br +int pthread_attr_setstack(pthread_attr_t *\fP\fIattr\fP\fB, void *\fP\fIstackaddr\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIstacksize\fP\fB); \fP +.sp +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_attr_getstack\fP() and \fIpthread_attr_setstack\fP() +functions, respectively, shall get and set the thread +creation stack attributes \fIstackaddr\fP and \fIstacksize\fP in the +\fIattr\fP object. +.LP +The stack attributes specify the area of storage to be used for the +created thread's stack. The base (lowest addressable byte) +of the storage shall be \fIstackaddr\fP, and the size of the storage +shall be \fIstacksize\fP bytes. The \fIstacksize\fP shall +be at least {PTHREAD_STACK_MIN}. The \fIstackaddr\fP shall be aligned +appropriately to be used as a stack; for example, +\fIpthread_attr_setstack\fP() may fail with [EINVAL] if ( \fIstackaddr\fP +& 0x7) is not 0. All pages within the stack +described by \fIstackaddr\fP and \fIstacksize\fP shall be both readable +and writable by the thread. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return a value of +0; otherwise, an error number shall be returned to indicate +the error. +.LP +The \fIpthread_attr_getstack\fP() function shall store the stack attribute +values in \fIstackaddr\fP and \fIstacksize\fP if +successful. +.SH ERRORS +.LP +The \fIpthread_attr_setstack\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of \fIstacksize\fP is less than {PTHREAD_STACK_MIN} or exceeds +an implementation-defined limit. +.sp +.LP +The \fIpthread_attr_setstack\fP() function may fail if: +.TP 7 +.B EINVAL +The value of \fIstackaddr\fP does not have proper alignment to be +used as a stack, or if ( \fIstackaddr\fP + +\fIstacksize\fP) lacks proper alignment. +.TP 7 +.B EACCES +The stack page(s) described by \fIstackaddr\fP and \fIstacksize\fP +are not both readable and writable by the thread. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +These functions are appropriate for use by applications in an environment +where the stack for a thread must be placed in some +particular region of memory. +.LP +While it might seem that an application could detect stack overflow +by providing a protected page outside the specified stack +region, this cannot be done portably. Implementations are free to +place the thread's initial stack pointer anywhere within the +specified region to accommodate the machine's stack pointer behavior +and allocation requirements. Furthermore, on some +architectures, such as the IA-64, "overflow" might mean that two separate +stack pointers allocated within the region will overlap +somewhere in the middle of the region. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_attr_init\fP() , \fIpthread_attr_setdetachstate\fP() , +\fIpthread_attr_setstacksize\fP() , \fIpthread_create\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_attr_getstackaddr.3p b/man3p/pthread_attr_getstackaddr.3p new file mode 100644 index 000000000..e3d52680d --- /dev/null +++ b/man3p/pthread_attr_getstackaddr.3p @@ -0,0 +1,93 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_ATTR_GETSTACKADDR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_attr_getstackaddr +.SH NAME +pthread_attr_getstackaddr, pthread_attr_setstackaddr \- get and set +the stackaddr attribute +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +\fP +.LP +\fBint pthread_attr_getstackaddr(const pthread_attr_t *restrict\fP +\fIattr\fP\fB, +.br +\ \ \ \ \ \ void **restrict\fP \fIstackaddr\fP\fB); +.br +int pthread_attr_setstackaddr(pthread_attr_t *\fP\fIattr\fP\fB, void +*\fP\fIstackaddr\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_attr_getstackaddr\fP() and \fIpthread_attr_setstackaddr\fP() +functions, respectively, shall get and set the +thread creation \fIstackaddr\fP attribute in the \fIattr\fP object. +.LP +The \fIstackaddr\fP attribute specifies the location of storage to +be used for the created thread's stack. The size of the +storage shall be at least {PTHREAD_STACK_MIN}. +.SH RETURN VALUE +.LP +Upon successful completion, \fIpthread_attr_getstackaddr\fP() and +\fIpthread_attr_setstackaddr\fP() shall return a value of 0; +otherwise, an error number shall be returned to indicate the error. +.LP +The \fIpthread_attr_getstackaddr\fP() function stores the \fIstackaddr\fP +attribute value in \fIstackaddr\fP if +successful. +.SH ERRORS +.LP +No errors are defined. +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The specification of the \fIstackaddr\fP attribute presents several +ambiguities that make portable use of these interfaces +impossible. The description of the single address parameter as a "stack" +does not specify a particular relationship between the +address and the "stack" implied by that address. For example, the +address may be taken as the low memory address of a buffer +intended for use as a stack, or it may be taken as the address to +be used as the initial stack pointer register value for the new +thread. These two are not the same except for a machine on which the +stack grows "up" from low memory to high, and on which a +"push" operation first stores the value in memory and then increments +the stack pointer register. Further, on a machine where the +stack grows "down" from high memory to low, interpretation of the +address as the "low memory" address requires a determination +of the intended size of the stack. IEEE\ Std\ 1003.1-2001 has introduced +the new interfaces \fIpthread_attr_setstack\fP() and \fIpthread_attr_getstack\fP() +to resolve these ambiguities. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_attr_destroy\fP() , \fIpthread_attr_getdetachstate\fP() +, \fIpthread_attr_getstack\fP() , \fIpthread_attr_getstacksize\fP() +, \fIpthread_attr_setstack\fP() , \fIpthread_create\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_attr_getstacksize.3p b/man3p/pthread_attr_getstacksize.3p new file mode 100644 index 000000000..4d57af7dd --- /dev/null +++ b/man3p/pthread_attr_getstacksize.3p @@ -0,0 +1,77 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_ATTR_GETSTACKSIZE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_attr_getstacksize +.SH NAME +pthread_attr_getstacksize, pthread_attr_setstacksize \- get and set +the stacksize attribute +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_attr_getstacksize(const pthread_attr_t *restrict\fP \fIattr\fP\fB, +.br +\ \ \ \ \ \ size_t *restrict\fP \fIstacksize\fP\fB); +.br +int pthread_attr_setstacksize(pthread_attr_t *\fP\fIattr\fP\fB, size_t\fP +\fIstacksize\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_attr_getstacksize\fP() and \fIpthread_attr_setstacksize\fP() +functions, respectively, shall get and set the +thread creation \fIstacksize\fP attribute in the \fIattr\fP object. +.LP +The \fIstacksize\fP attribute shall define the minimum stack size +(in bytes) allocated for the created threads stack. +.SH RETURN VALUE +.LP +Upon successful completion, \fIpthread_attr_getstacksize\fP() and +\fIpthread_attr_setstacksize\fP() shall return a value of 0; +otherwise, an error number shall be returned to indicate the error. +.LP +The \fIpthread_attr_getstacksize\fP() function stores the \fIstacksize\fP +attribute value in \fIstacksize\fP if +successful. +.SH ERRORS +.LP +The \fIpthread_attr_setstacksize\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of \fIstacksize\fP is less than {PTHREAD_STACK_MIN} or exceeds +a system-imposed limit. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_attr_destroy\fP() , \fIpthread_attr_getstackaddr\fP() , +\fIpthread_attr_getdetachstate\fP() , \fIpthread_create\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_attr_init.3p b/man3p/pthread_attr_init.3p new file mode 100644 index 000000000..5d850fa02 --- /dev/null +++ b/man3p/pthread_attr_init.3p @@ -0,0 +1,185 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_ATTR_DESTROY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_attr_destroy +.SH NAME +pthread_attr_destroy, pthread_attr_init \- destroy and initialize the +thread attributes object +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_attr_destroy(pthread_attr_t *\fP\fIattr\fP\fB); +.br +int pthread_attr_init(pthread_attr_t *\fP\fIattr\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_attr_destroy\fP() function shall destroy a thread attributes +object. An implementation may cause +\fIpthread_attr_destroy\fP() to set \fIattr\fP to an implementation-defined +invalid value. A destroyed \fIattr\fP attributes +object can be reinitialized using \fIpthread_attr_init\fP(); the results +of otherwise referencing the object after it has been +destroyed are undefined. +.LP +The \fIpthread_attr_init\fP() function shall initialize a thread attributes +object \fIattr\fP with the default value for all +of the individual attributes used by a given implementation. +.LP +The resulting attributes object (possibly modified by setting individual +attribute values) when used by \fIpthread_create\fP() defines the +attributes of the thread created. A single attributes +object can be used in multiple simultaneous calls to \fIpthread_create\fP(). +Results are undefined if \fIpthread_attr_init\fP() is called specifying +an already initialized \fIattr\fP attributes object. +.SH RETURN VALUE +.LP +Upon successful completion, \fIpthread_attr_destroy\fP() and \fIpthread_attr_init\fP() +shall return a value of 0; otherwise, +an error number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_attr_init\fP() function shall fail if: +.TP 7 +.B ENOMEM +Insufficient memory exists to initialize the thread attributes object. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Attributes objects are provided for threads, mutexes, and condition +variables as a mechanism to support probable future +standardization in these areas without requiring that the function +itself be changed. +.LP +Attributes objects provide clean isolation of the configurable aspects +of threads. For example, "stack size" is an important +attribute of a thread, but it cannot be expressed portably. When porting +a threaded program, stack sizes often need to be adjusted. +The use of attributes objects can help by allowing the changes to +be isolated in a single place, rather than being spread across +every instance of thread creation. +.LP +Attributes objects can be used to set up "classes' of threads with +similar attributes; for example, "threads with large stacks +and high priority" or "threads with minimal stacks". These classes +can be defined in a single place and then referenced wherever +threads need to be created. Changes to "class" decisions become straightforward, +and detailed analysis of each \fIpthread_create\fP() call is not required. +.LP +The attributes objects are defined as opaque types as an aid to extensibility. +If these objects had been specified as +structures, adding new attributes would force recompilation of all +multi-threaded programs when the attributes objects are +extended; this might not be possible if different program components +were supplied by different vendors. +.LP +Additionally, opaque attributes objects present opportunities for +improving performance. Argument validity can be checked once +when attributes are set, rather than each time a thread is created. +Implementations often need to cache kernel objects that are +expensive to create. Opaque attributes objects provide an efficient +mechanism to detect when cached objects become invalid due to +attribute changes. +.LP +Since assignment is not necessarily defined on a given opaque type, +implementation-defined default values cannot be defined in a +portable way. The solution to this problem is to allow attributes +objects to be initialized dynamically by attributes object +initialization functions, so that default values can be supplied automatically +by the implementation. +.LP +The following proposal was provided as a suggested alternative to +the supplied attributes: +.IP " 1." 4 +Maintain the style of passing a parameter formed by the bitwise-inclusive +OR of flags to the initialization routines ( \fIpthread_create\fP(), +\fIpthread_mutex_init\fP(), \fIpthread_cond_init\fP()). The parameter +containing the flags should be an opaque type +for extensibility. If no flags are set in the parameter, then the +objects are created with default characteristics. An +implementation may specify implementation-defined flag values and +associated behavior. +.LP +.IP " 2." 4 +If further specialization of mutexes and condition variables is necessary, +implementations may specify additional procedures +that operate on the \fBpthread_mutex_t\fP and \fBpthread_cond_t\fP +objects (instead of on attributes objects). +.LP +.LP +The difficulties with this solution are: +.IP " 1." 4 +A bitmask is not opaque if bits have to be set into bitvector attributes +objects using explicitly-coded bitwise-inclusive OR +operations. If the set of options exceeds an \fBint\fP, application +programmers need to know the location of each bit. If bits are +set or read by encapsulation (that is, get and set functions), then +the bitmask is merely an implementation of attributes objects +as currently defined and should not be exposed to the programmer. +.LP +.IP " 2." 4 +Many attributes are not Boolean or very small integral values. For +example, scheduling policy may be placed in 3-bit or 4-bit, +but priority requires 5-bit or more, thereby taking up at least 8 +bits out of a possible 16 bits on machines with 16-bit integers. +Because of this, the bitmask can only reasonably control whether particular +attributes are set or not, and it cannot serve as the +repository of the value itself. The value needs to be specified as +a function parameter (which is non-extensible), or by setting a +structure field (which is non-opaque), or by get and set functions +(making the bitmask a redundant addition to the attributes +objects). +.LP +.LP +Stack size is defined as an optional attribute because the very notion +of a stack is inherently machine-dependent. Some +implementations may not be able to change the size of the stack, for +example, and others may not need to because stack pages may be +discontiguous and can be allocated and released on demand. +.LP +The attribute mechanism has been designed in large measure for extensibility. +Future extensions to the attribute mechanism or to +any attributes object defined in this volume of IEEE\ Std\ 1003.1-2001 +has to be done with care so as not to affect +binary-compatibility. +.LP +Attributes objects, even if allocated by means of dynamic allocation +functions such as \fImalloc\fP(), may have their size fixed at compile +time. This means, for example, a \fIpthread_create\fP() in an implementation +with extensions to \fBpthread_attr_t\fP cannot +look beyond the area that the binary application assumes is valid. +This suggests that implementations should maintain a size field +in the attributes object, as well as possibly version information, +if extensions in different directions (possibly by different +vendors) are to be accommodated. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_attr_getstackaddr\fP() , \fIpthread_attr_getstacksize\fP() +, \fIpthread_attr_getdetachstate\fP() , \fIpthread_create\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_attr_setdetachstate.3p b/man3p/pthread_attr_setdetachstate.3p new file mode 100644 index 000000000..99aa09f3e --- /dev/null +++ b/man3p/pthread_attr_setdetachstate.3p @@ -0,0 +1 @@ +.so man3p/pthread_attr_getdetachstate.3p diff --git a/man3p/pthread_attr_setguardsize.3p b/man3p/pthread_attr_setguardsize.3p new file mode 100644 index 000000000..e7cd07f41 --- /dev/null +++ b/man3p/pthread_attr_setguardsize.3p @@ -0,0 +1 @@ +.so man3p/pthread_attr_getguardsize.3p diff --git a/man3p/pthread_attr_setinheritsched.3p b/man3p/pthread_attr_setinheritsched.3p new file mode 100644 index 000000000..11f6f9a04 --- /dev/null +++ b/man3p/pthread_attr_setinheritsched.3p @@ -0,0 +1 @@ +.so man3p/pthread_attr_getinheritsched.3p diff --git a/man3p/pthread_attr_setschedparam.3p b/man3p/pthread_attr_setschedparam.3p new file mode 100644 index 000000000..698e3386f --- /dev/null +++ b/man3p/pthread_attr_setschedparam.3p @@ -0,0 +1 @@ +.so man3p/pthread_attr_getschedparam.3p diff --git a/man3p/pthread_attr_setschedpolicy.3p b/man3p/pthread_attr_setschedpolicy.3p new file mode 100644 index 000000000..2f8d6a9c2 --- /dev/null +++ b/man3p/pthread_attr_setschedpolicy.3p @@ -0,0 +1 @@ +.so man3p/pthread_attr_getschedpolicy.3p diff --git a/man3p/pthread_attr_setscope.3p b/man3p/pthread_attr_setscope.3p new file mode 100644 index 000000000..32c8a3b84 --- /dev/null +++ b/man3p/pthread_attr_setscope.3p @@ -0,0 +1 @@ +.so man3p/pthread_attr_getscope.3p diff --git a/man3p/pthread_attr_setstack.3p b/man3p/pthread_attr_setstack.3p new file mode 100644 index 000000000..49621fb7a --- /dev/null +++ b/man3p/pthread_attr_setstack.3p @@ -0,0 +1 @@ +.so man3p/pthread_attr_getstack.3p diff --git a/man3p/pthread_attr_setstackaddr.3p b/man3p/pthread_attr_setstackaddr.3p new file mode 100644 index 000000000..859c233be --- /dev/null +++ b/man3p/pthread_attr_setstackaddr.3p @@ -0,0 +1 @@ +.so man3p/pthread_attr_getstackaddr.3p diff --git a/man3p/pthread_attr_setstacksize.3p b/man3p/pthread_attr_setstacksize.3p new file mode 100644 index 000000000..fb5936ace --- /dev/null +++ b/man3p/pthread_attr_setstacksize.3p @@ -0,0 +1 @@ +.so man3p/pthread_attr_getstacksize.3p diff --git a/man3p/pthread_barrier_destroy.3p b/man3p/pthread_barrier_destroy.3p new file mode 100644 index 000000000..fece59af8 --- /dev/null +++ b/man3p/pthread_barrier_destroy.3p @@ -0,0 +1 @@ +.so man3p/pthread_barrier_init.3p diff --git a/man3p/pthread_barrier_init.3p b/man3p/pthread_barrier_init.3p new file mode 100644 index 000000000..631052ba4 --- /dev/null +++ b/man3p/pthread_barrier_init.3p @@ -0,0 +1,132 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_BARRIER_DESTROY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_barrier_destroy +.SH NAME +pthread_barrier_destroy, pthread_barrier_init \- destroy and initialize +a barrier object (\fBADVANCED REALTIME +THREADS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_barrier_destroy(pthread_barrier_t *\fP\fIbarrier\fP\fB); +.br +int pthread_barrier_init(pthread_barrier_t *restrict\fP \fIbarrier\fP\fB, +.br +\ \ \ \ \ \ const pthread_barrierattr_t *restrict\fP \fIattr\fP\fB, +unsigned\fP \fIcount\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_barrier_destroy\fP() function shall destroy the barrier +referenced by \fIbarrier\fP and release any resources +used by the barrier. The effect of subsequent use of the barrier is +undefined until the barrier is reinitialized by another call to +\fIpthread_barrier_init\fP(). An implementation may use this function +to set \fIbarrier\fP to an invalid value. The results are +undefined if \fIpthread_barrier_destroy\fP() is called when any thread +is blocked on the barrier, or if this function is called +with an uninitialized barrier. +.LP +The \fIpthread_barrier_init\fP() function shall allocate any resources +required to use the barrier referenced by \fIbarrier\fP +and shall initialize the barrier with attributes referenced by \fIattr\fP. +If \fIattr\fP is NULL, the default barrier attributes +shall be used; the effect is the same as passing the address of a +default barrier attributes object. The results are undefined if +\fIpthread_barrier_init\fP() is called when any thread is blocked +on the barrier (that is, has not returned from the \fIpthread_barrier_wait\fP() +call). The results are undefined if a barrier is used +without first being initialized. The results are undefined if \fIpthread_barrier_init\fP() +is called specifying an already +initialized barrier. +.LP +The \fIcount\fP argument specifies the number of threads that must +call \fIpthread_barrier_wait\fP() before any of them successfully +return from the call. +The value specified by \fIcount\fP must be greater than zero. +.LP +If the \fIpthread_barrier_init\fP() function fails, the barrier shall +not be initialized and the contents of \fIbarrier\fP are +undefined. +.LP +Only the object referenced by \fIbarrier\fP may be used for performing +synchronization. The result of referring to copies of +that object in calls to \fIpthread_barrier_destroy\fP() or \fIpthread_barrier_wait\fP() +is undefined. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return zero; otherwise, +an error number shall be returned to indicate the +error. +.SH ERRORS +.LP +The \fIpthread_barrier_destroy\fP() function may fail if: +.TP 7 +.B EBUSY +The implementation has detected an attempt to destroy a barrier while +it is in use (for example, while being used in a \fIpthread_barrier_wait\fP() +call) by another thread. +.TP 7 +.B EINVAL +The value specified by \fIbarrier\fP is invalid. +.sp +.LP +The \fIpthread_barrier_init\fP() function shall fail if: +.TP 7 +.B EAGAIN +The system lacks the necessary resources to initialize another barrier. +.TP 7 +.B EINVAL +The value specified by \fIcount\fP is equal to zero. +.TP 7 +.B ENOMEM +Insufficient memory exists to initialize the barrier. +.sp +.LP +The \fIpthread_barrier_init\fP() function may fail if: +.TP 7 +.B EBUSY +The implementation has detected an attempt to reinitialize a barrier +while it is in use (for example, while being used in a \fIpthread_barrier_wait\fP() +call) by another thread. +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIpthread_barrier_destroy\fP() and \fIpthread_barrier_init\fP() +functions are part of the Barriers option and need not be +provided on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_barrier_wait\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_barrier_wait.3p b/man3p/pthread_barrier_wait.3p new file mode 100644 index 000000000..402168812 --- /dev/null +++ b/man3p/pthread_barrier_wait.3p @@ -0,0 +1,104 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_BARRIER_WAIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_barrier_wait +.SH NAME +pthread_barrier_wait \- synchronize at a barrier (\fBADVANCED REALTIME +THREADS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_barrier_wait(pthread_barrier_t *\fP\fIbarrier\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_barrier_wait\fP() function shall synchronize participating +threads at the barrier referenced by \fIbarrier\fP. +The calling thread shall block until the required number of threads +have called \fIpthread_barrier_wait\fP() specifying the +barrier. +.LP +When the required number of threads have called \fIpthread_barrier_wait\fP() +specifying the barrier, the constant +PTHREAD_BARRIER_SERIAL_THREAD shall be returned to one unspecified +thread and zero shall be returned to each of the remaining +threads. At this point, the barrier shall be reset to the state it +had as a result of the most recent \fIpthread_barrier_init\fP() function +that referenced it. +.LP +The constant PTHREAD_BARRIER_SERIAL_THREAD is defined in \fI\fP +and +its value shall be distinct from any other value returned by \fIpthread_barrier_wait\fP(). +.LP +The results are undefined if this function is called with an uninitialized +barrier. +.LP +If a signal is delivered to a thread blocked on a barrier, upon return +from the signal handler the thread shall resume waiting +at the barrier if the barrier wait has not completed (that is, if +the required number of threads have not arrived at the barrier +during the execution of the signal handler); otherwise, the thread +shall continue as normal from the completed barrier wait. Until +the thread in the signal handler returns from it, it is unspecified +whether other threads may proceed past the barrier once they +have all reached it. +.LP +A thread that has blocked on a barrier shall not prevent any unblocked +thread that is eligible to use the same processing +resources from eventually making forward progress in its execution. +Eligibility for processing resources shall be determined by the +scheduling policy. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIpthread_barrier_wait\fP() function +shall return PTHREAD_BARRIER_SERIAL_THREAD for a single +(arbitrary) thread synchronized at the barrier and zero for each of +the other threads. Otherwise, an error number shall be returned +to indicate the error. +.SH ERRORS +.LP +The \fIpthread_barrier_wait\fP() function may fail if: +.TP 7 +.B EINVAL +The value specified by \fIbarrier\fP does not refer to an initialized +barrier object. +.sp +.LP +This function shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications using this function may be subject to priority inversion, +as discussed in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 3.285, Priority Inversion. +.LP +The \fIpthread_barrier_wait\fP() function is part of the Barriers +option and need not be provided on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_barrier_destroy\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_barrierattr_destroy.3p b/man3p/pthread_barrierattr_destroy.3p new file mode 100644 index 000000000..3ac035285 --- /dev/null +++ b/man3p/pthread_barrierattr_destroy.3p @@ -0,0 +1 @@ +.so man3p/pthread_barrierattr_init.3p diff --git a/man3p/pthread_barrierattr_getpshared.3p b/man3p/pthread_barrierattr_getpshared.3p new file mode 100644 index 000000000..965a6c10a --- /dev/null +++ b/man3p/pthread_barrierattr_getpshared.3p @@ -0,0 +1,107 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_BARRIERATTR_GETPSHARED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_barrierattr_getpshared +.SH NAME +pthread_barrierattr_getpshared, pthread_barrierattr_setpshared \- get +and set the process\-shared attribute of the +barrier attributes object (\fBADVANCED REALTIME THREADS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +\fP +.LP +\fBint pthread_barrierattr_getpshared(const pthread_barrierattr_t +* +.br +\ \ \ \ \ \ restrict\fP \fIattr\fP\fB, int *restrict\fP \fIpshared\fP\fB); +.br +int pthread_barrierattr_setpshared(pthread_barrierattr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIpshared\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_barrierattr_getpshared\fP() function shall obtain the +value of the \fIprocess-shared\fP attribute from the +attributes object referenced by \fIattr\fP. The \fIpthread_barrierattr_setpshared\fP() +function shall set the +\fIprocess-shared\fP attribute in an initialized attributes object +referenced by \fIattr\fP. +.LP +The \fIprocess-shared\fP attribute is set to PTHREAD_PROCESS_SHARED +to permit a barrier to be operated upon by any thread that +has access to the memory where the barrier is allocated. If the \fIprocess-shared\fP +attribute is PTHREAD_PROCESS_PRIVATE, the +barrier shall only be operated upon by threads created within the +same process as the thread that initialized the barrier; if +threads of different processes attempt to operate on such a barrier, +the behavior is undefined. The default value of the attribute +shall be PTHREAD_PROCESS_PRIVATE. Both constants PTHREAD_PROCESS_SHARED +and PTHREAD_PROCESS_PRIVATE are defined in \fI\fP. +.LP +Additional attributes, their default values, and the names of the +associated functions to get and set those attribute values are +implementation-defined. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_barrierattr_getpshared\fP() function +shall return zero and store the value of the +\fIprocess-shared\fP attribute of \fIattr\fP into the object referenced +by the \fIpshared\fP parameter. Otherwise, an error +number shall be returned to indicate the error. +.LP +If successful, the \fIpthread_barrierattr_setpshared\fP() function +shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +The \fIpthread_barrierattr_setpshared\fP() function may fail if: +.TP 7 +.B EINVAL +The new value specified for the \fIprocess-shared\fP attribute is +not one of the legal values PTHREAD_PROCESS_SHARED or +PTHREAD_PROCESS_PRIVATE. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIpthread_barrierattr_getpshared\fP() and \fIpthread_barrierattr_setpshared\fP() +functions are part of the Barriers +option and need not be provided on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_barrier_destroy\fP() , \fIpthread_barrierattr_destroy\fP() +, \fIpthread_barrierattr_init\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_barrierattr_init.3p b/man3p/pthread_barrierattr_init.3p new file mode 100644 index 000000000..f4c75791e --- /dev/null +++ b/man3p/pthread_barrierattr_init.3p @@ -0,0 +1,92 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_BARRIERATTR_DESTROY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_barrierattr_destroy +.SH NAME +pthread_barrierattr_destroy, pthread_barrierattr_init \- destroy and +initialize the barrier attributes object +(\fBADVANCED REALTIME THREADS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_barrierattr_destroy(pthread_barrierattr_t *\fP\fIattr\fP\fB); +.br +int pthread_barrierattr_init(pthread_barrierattr_t *\fP\fIattr\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_barrierattr_destroy\fP() function shall destroy a barrier +attributes object. A destroyed \fIattr\fP attributes +object can be reinitialized using \fIpthread_barrierattr_init\fP(); +the results of otherwise referencing the object after it has +been destroyed are undefined. An implementation may cause \fIpthread_barrierattr_destroy\fP() +to set the object referenced by +\fIattr\fP to an invalid value. +.LP +The \fIpthread_barrierattr_init\fP() function shall initialize a barrier +attributes object \fIattr\fP with the default value +for all of the attributes defined by the implementation. +.LP +Results are undefined if \fIpthread_barrierattr_init\fP() is called +specifying an already initialized \fIattr\fP attributes +object. +.LP +After a barrier attributes object has been used to initialize one +or more barriers, any function affecting the attributes object +(including destruction) shall not affect any previously initialized +barrier. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_barrierattr_destroy\fP() and \fIpthread_barrierattr_init\fP() +functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_barrierattr_destroy\fP() function may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +The \fIpthread_barrierattr_init\fP() function shall fail if: +.TP 7 +.B ENOMEM +Insufficient memory exists to initialize the barrier attributes object. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIpthread_barrierattr_destroy\fP() and \fIpthread_barrierattr_init\fP() +functions are part of the Barriers option and +need not be provided on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_barrierattr_getpshared\fP() , \fIpthread_barrierattr_setpshared\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP. +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_barrierattr_setpshared.3p b/man3p/pthread_barrierattr_setpshared.3p new file mode 100644 index 000000000..2cbb2b928 --- /dev/null +++ b/man3p/pthread_barrierattr_setpshared.3p @@ -0,0 +1 @@ +.so man3p/pthread_barrierattr_getpshared.3p diff --git a/man3p/pthread_cancel.3p b/man3p/pthread_cancel.3p new file mode 100644 index 000000000..6f4ca8484 --- /dev/null +++ b/man3p/pthread_cancel.3p @@ -0,0 +1,103 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_CANCEL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_cancel +.SH NAME +pthread_cancel \- cancel execution of a thread +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_cancel(pthread_t\fP \fIthread\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_cancel\fP() function shall request that \fIthread\fP +be canceled. The target thread's cancelability state and +type determines when the cancellation takes effect. When the cancellation +is acted on, the cancellation cleanup handlers for +\fIthread\fP shall be called. When the last cancellation cleanup handler +returns, the thread-specific data destructor functions +shall be called for \fIthread\fP. When the last destructor function +returns, \fIthread\fP shall be terminated. +.LP +The cancellation processing in the target thread shall run asynchronously +with respect to the calling thread returning from +\fIpthread_cancel\fP(). +.SH RETURN VALUE +.LP +If successful, the \fIpthread_cancel\fP() function shall return zero; +otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +.LP +The \fIpthread_cancel\fP() function may fail if: +.TP 7 +.B ESRCH +No thread could be found corresponding to that specified by the given +thread ID. +.sp +.LP +The \fIpthread_cancel\fP() function shall not return an error code +of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Two alternative functions were considered for sending the cancellation +notification to a thread. One would be to define a new +SIGCANCEL signal that had the cancellation semantics when delivered; +the other was to define the new \fIpthread_cancel\fP() +function, which would trigger the cancellation semantics. +.LP +The advantage of a new signal was that so much of the delivery criteria +were identical to that used when trying to deliver a +signal that making cancellation notification a signal was seen as +consistent. Indeed, many implementations implement cancellation +using a special signal. On the other hand, there would be no signal +functions that could be used with this signal except \fIpthread_kill\fP(), +and the behavior of the delivered cancellation signal would be unlike +any previously existing defined signal. +.LP +The benefits of a special function include the recognition that this +signal would be defined because of the similar delivery +criteria and that this is the only common behavior between a cancellation +request and a signal. In addition, the cancellation +delivery mechanism does not have to be implemented as a signal. There +are also strong, if not stronger, parallels with language +exception mechanisms than with signals that are potentially obscured +if the delivery mechanism is visibly closer to signals. +.LP +In the end, it was considered that as there were so many exceptions +to the use of the new signal with existing signals functions +it would be misleading. A special function has resolved this problem. +This function was carefully defined so that an implementation +wishing to provide the cancellation functions on top of signals could +do so. The special function also means that implementations +are not obliged to implement cancellation with signals. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_exit\fP() , \fIpthread_cond_timedwait\fP() , \fIpthread_join\fP() +, \fIpthread_setcancelstate\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_cleanup_pop.3p b/man3p/pthread_cleanup_pop.3p new file mode 100644 index 000000000..fc21cf4a3 --- /dev/null +++ b/man3p/pthread_cleanup_pop.3p @@ -0,0 +1 @@ +.so man3p/pthread_cleanup_push.3p diff --git a/man3p/pthread_cleanup_push.3p b/man3p/pthread_cleanup_push.3p new file mode 100644 index 000000000..e8bdcb6bf --- /dev/null +++ b/man3p/pthread_cleanup_push.3p @@ -0,0 +1,295 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_CLEANUP_POP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_cleanup_pop +.SH NAME +pthread_cleanup_pop, pthread_cleanup_push \- establish cancellation +handlers +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void pthread_cleanup_pop(int\fP \fIexecute\fP\fB); +.br +void pthread_cleanup_push(void (*\fP\fIroutine\fP\fB)(void*), void +*\fP\fIarg\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_cleanup_pop\fP() function shall remove the routine +at the top of the calling thread's cancellation cleanup stack +and optionally invoke it (if \fIexecute\fP is non-zero). +.LP +The \fIpthread_cleanup_push\fP() function shall push the specified +cancellation cleanup handler \fIroutine\fP onto the calling +thread's cancellation cleanup stack. The cancellation cleanup handler +shall be popped from the cancellation cleanup stack and +invoked with the argument \fIarg\fP when: +.IP " *" 3 +The thread exits (that is, calls \fIpthread_exit\fP()). +.LP +.IP " *" 3 +The thread acts upon a cancellation request. +.LP +.IP " *" 3 +The thread calls \fIpthread_cleanup_pop\fP() with a non-zero \fIexecute\fP +argument. +.LP +.LP +These functions may be implemented as macros. The application shall +ensure that they appear as statements, and in pairs within +the same lexical scope (that is, the \fIpthread_cleanup_push\fP() +macro may be thought to expand to a token list whose first token +is \fB'{'\fP with \fIpthread_cleanup_pop\fP() expanding to a token +list whose last token is the corresponding \fB'}'\fP +). +.LP +The effect of calling \fIlongjmp\fP() or \fIsiglongjmp\fP() is undefined +if there have been any calls to \fIpthread_cleanup_push\fP() +or \fIpthread_cleanup_pop\fP() made without the matching call since +the jump buffer was filled. The effect of calling \fIlongjmp\fP() +or \fIsiglongjmp\fP() from inside a +cancellation cleanup handler is also undefined unless the jump buffer +was also filled in the cancellation cleanup handler. +.SH RETURN VALUE +.LP +The \fIpthread_cleanup_push\fP() and \fIpthread_cleanup_pop\fP() functions +shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The following is an example using thread primitives to implement a +cancelable, writers-priority read-write lock: +.sp +.RS +.nf + +\fBtypedef struct { + pthread_mutex_t lock; + pthread_cond_t rcond, + wcond; + int lock_count; /* < 0 .. Held by writer. */ + /* > 0 .. Held by lock_count readers. */ + /* = 0 .. Held by nobody. */ + int waiting_writers; /* Count of waiting writers. */ +} rwlock; +.sp + +void +waiting_reader_cleanup(void *arg) +{ + rwlock *l; +.sp + + l = (rwlock *) arg; + pthread_mutex_unlock(&l->lock); +} +.sp + +void +lock_for_read(rwlock *l) +{ + pthread_mutex_lock(&l->lock); + pthread_cleanup_push(waiting_reader_cleanup, l); + while ((l->lock_count < 0) && (l->waiting_writers != 0)) + pthread_cond_wait(&l->rcond, &l->lock); + l->lock_count++; + /* + * Note the pthread_cleanup_pop executes + * waiting_reader_cleanup. + */ + pthread_cleanup_pop(1); +} +.sp + +void +release_read_lock(rwlock *l) +{ + pthread_mutex_lock(&l->lock); + if (--l->lock_count == 0) + pthread_cond_signal(&l->wcond); + pthread_mutex_unlock(l); +} +.sp + +void +waiting_writer_cleanup(void *arg) +{ + rwlock *l; +.sp + + l = (rwlock *) arg; + if ((--l->waiting_writers == 0) && (l->lock_count >= 0)) { + /* + * This only happens if we have been canceled. + */ + pthread_cond_broadcast(&l->wcond); +} + pthread_mutex_unlock(&l->lock); +} +.sp + +void +lock_for_write(rwlock *l) +{ + pthread_mutex_lock(&l->lock); + l->waiting_writers++; + pthread_cleanup_push(waiting_writer_cleanup, l); + while (l->lock_count != 0) + pthread_cond_wait(&l->wcond, &l->lock); + l->lock_count = -1; + /* + * Note the pthread_cleanup_pop executes + * waiting_writer_cleanup. + */ + pthread_cleanup_pop(1); +} +.sp + +void +release_write_lock(rwlock *l) +{ + pthread_mutex_lock(&l->lock); + l->lock_count = 0; + if (l->waiting_writers == 0) + pthread_cond_broadcast(&l->rcond) + else + pthread_cond_signal(&l->wcond); + pthread_mutex_unlock(&l->lock); +} +.sp + +/* + * This function is called to initialize the read/write lock. + */ +void +initialize_rwlock(rwlock *l) +{ + pthread_mutex_init(&l->lock, pthread_mutexattr_default); + pthread_cond_init(&l->wcond, pthread_condattr_default); + pthread_cond_init(&l->rcond, pthread_condattr_default); + l->lock_count = 0; + l->waiting_writers = 0; +} +.sp + +reader_thread() +{ + lock_for_read(&lock); + pthread_cleanup_push(release_read_lock, &lock); + /* + * Thread has read lock. + */ + pthread_cleanup_pop(1); +} +.sp + +writer_thread() +{ + lock_for_write(&lock); + pthread_cleanup_push(release_write_lock, &lock); + /* + * Thread has write lock. + */ +pthread_cleanup_pop(1); +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The two routines that push and pop cancellation cleanup handlers, +\fIpthread_cleanup_push\fP() and +\fIpthread_cleanup_pop\fP(), can be thought of as left and right parentheses. +They always need to be matched. +.SH RATIONALE +.LP +The restriction that the two routines that push and pop cancellation +cleanup handlers, \fIpthread_cleanup_push\fP() and +\fIpthread_cleanup_pop\fP(), have to appear in the same lexical scope +allows for efficient macro or compiler implementations and +efficient storage management. A sample implementation of these routines +as macros might look like this: +.sp +.RS +.nf + +\fB#define pthread_cleanup_push(rtn,arg) { \\ + struct _pthread_handler_rec __cleanup_handler, **__head; \\ + __cleanup_handler.rtn = rtn; \\ + __cleanup_handler.arg = arg; \\ + (void) pthread_getspecific(_pthread_handler_key, &__head); \\ + __cleanup_handler.next = *__head; \\ + *__head = &__cleanup_handler; +.sp + +#define pthread_cleanup_pop(ex) \\ + *__head = __cleanup_handler.next; \\ + if (ex) (*__cleanup_handler.rtn)(__cleanup_handler.arg); \\ +} +\fP +.fi +.RE +.LP +A more ambitious implementation of these routines might do even better +by allowing the compiler to note that the cancellation +cleanup handler is a constant and can be expanded inline. +.LP +This volume of IEEE\ Std\ 1003.1-2001 currently leaves unspecified +the effect of calling \fIlongjmp\fP() from a signal handler executing +in a POSIX System Interfaces function. If an +implementation wants to allow this and give the programmer reasonable +behavior, the \fIlongjmp\fP() function has to call all cancellation +cleanup handlers that have been pushed but +not popped since the time \fIsetjmp\fP() was called. +.LP +Consider a multi-threaded function called by a thread that uses signals. +If a signal were delivered to a signal handler during +the operation of \fIqsort\fP() and that handler were to call \fIlongjmp\fP() +(which, in turn, did \fInot\fP call the cancellation cleanup handlers) +the helper +threads created by the \fIqsort\fP() function would not be canceled. +Instead, they would +continue to execute and write into the argument array even though +the array might have been popped off the stack. +.LP +Note that the specified cleanup handling mechanism is especially tied +to the C language and, while the requirement for a uniform +mechanism for expressing cleanup is language-independent, the mechanism +used in other languages may be quite different. In +addition, this mechanism is really only necessary due to the lack +of a real exception mechanism in the C language, which would be +the ideal solution. +.LP +There is no notion of a cancellation cleanup-safe function. If an +application has no cancellation points in its signal handlers, +blocks any signal whose handler may have cancellation points while +calling async-unsafe functions, or disables cancellation while +calling async-unsafe functions, all functions may be safely called +from cancellation cleanup routines. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_cancel\fP() , \fIpthread_setcancelstate\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_cond_broadcast.3p b/man3p/pthread_cond_broadcast.3p new file mode 100644 index 000000000..47aee2574 --- /dev/null +++ b/man3p/pthread_cond_broadcast.3p @@ -0,0 +1 @@ +.so man3p/pthread_cond_signal.3p diff --git a/man3p/pthread_cond_destroy.3p b/man3p/pthread_cond_destroy.3p new file mode 100644 index 000000000..2a3b2efde --- /dev/null +++ b/man3p/pthread_cond_destroy.3p @@ -0,0 +1 @@ +.so man3p/pthread_cond_init.3p diff --git a/man3p/pthread_cond_init.3p b/man3p/pthread_cond_init.3p new file mode 100644 index 000000000..b5d48718d --- /dev/null +++ b/man3p/pthread_cond_init.3p @@ -0,0 +1,193 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_COND_DESTROY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_cond_destroy +.SH NAME +pthread_cond_destroy, pthread_cond_init \- destroy and initialize condition +variables +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_cond_destroy(pthread_cond_t *\fP\fIcond\fP\fB); +.br +int pthread_cond_init(pthread_cond_t *restrict\fP \fIcond\fP\fB, +.br +\ \ \ \ \ \ const pthread_condattr_t *restrict\fP \fIattr\fP\fB); +.br +pthread_cond_t\fP \fIcond\fP \fB= PTHREAD_COND_INITIALIZER; \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_cond_destroy\fP() function shall destroy the given +condition variable specified by \fIcond\fP; the object +becomes, in effect, uninitialized. An implementation may cause \fIpthread_cond_destroy\fP() +to set the object referenced by +\fIcond\fP to an invalid value. A destroyed condition variable object +can be reinitialized using \fIpthread_cond_init\fP(); the +results of otherwise referencing the object after it has been destroyed +are undefined. +.LP +It shall be safe to destroy an initialized condition variable upon +which no threads are currently blocked. Attempting to destroy +a condition variable upon which other threads are currently blocked +results in undefined behavior. +.LP +The \fIpthread_cond_init\fP() function shall initialize the condition +variable referenced by \fIcond\fP with attributes +referenced by \fIattr\fP. If \fIattr\fP is NULL, the default condition +variable attributes shall be used; the effect is the same +as passing the address of a default condition variable attributes +object. Upon successful initialization, the state of the +condition variable shall become initialized. +.LP +Only \fIcond\fP itself may be used for performing synchronization. +The result of referring to copies of \fIcond\fP in calls to +\fIpthread_cond_wait\fP(), \fIpthread_cond_timedwait\fP(), \fIpthread_cond_signal\fP(), +\fIpthread_cond_broadcast\fP(), and \fIpthread_cond_destroy\fP() is +undefined. +.LP +Attempting to initialize an already initialized condition variable +results in undefined behavior. +.LP +In cases where default condition variable attributes are appropriate, +the macro PTHREAD_COND_INITIALIZER can be used to +initialize condition variables that are statically allocated. The +effect shall be equivalent to dynamic initialization by a call to +\fIpthread_cond_init\fP() with parameter \fIattr\fP specified as NULL, +except that no error checks are performed. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_cond_destroy\fP() and \fIpthread_cond_init\fP() +functions shall return zero; otherwise, an error +number shall be returned to indicate the error. +.LP +The [EBUSY] and [EINVAL] error checks, if implemented, shall act as +if they were performed immediately at the beginning of +processing for the function and caused an error return prior to modifying +the state of the condition variable specified by +\fIcond\fP. +.SH ERRORS +.LP +The \fIpthread_cond_destroy\fP() function may fail if: +.TP 7 +.B EBUSY +The implementation has detected an attempt to destroy the object referenced +by \fIcond\fP while it is referenced (for example, +while being used in a \fIpthread_cond_wait\fP() or \fIpthread_cond_timedwait\fP()) +by another thread. +.TP 7 +.B EINVAL +The value specified by \fIcond\fP is invalid. +.sp +.LP +The \fIpthread_cond_init\fP() function shall fail if: +.TP 7 +.B EAGAIN +The system lacked the necessary resources (other than memory) to initialize +another condition variable. +.TP 7 +.B ENOMEM +Insufficient memory exists to initialize the condition variable. +.sp +.LP +The \fIpthread_cond_init\fP() function may fail if: +.TP 7 +.B EBUSY +The implementation has detected an attempt to reinitialize the object +referenced by \fIcond\fP, a previously initialized, but +not yet destroyed, condition variable. +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +A condition variable can be destroyed immediately after all the threads +that are blocked on it are awakened. For example, +consider the following code: +.sp +.RS +.nf + +\fBstruct list { + pthread_mutex_t lm; + ... +} +.sp + +struct elt { + key k; + int busy; + pthread_cond_t notbusy; + ... +} +.sp + +/* Find a list element and reserve it. */ +struct elt * +list_find(struct list *lp, key k) +{ + struct elt *ep; +.sp + + pthread_mutex_lock(&lp->lm); + while ((ep = find_elt(l, k) != NULL) && ep->busy) + pthread_cond_wait(&ep->notbusy, &lp->lm); + if (ep != NULL) + ep->busy = 1; + pthread_mutex_unlock(&lp->lm); + return(ep); +} +.sp + +delete_elt(struct list *lp, struct elt *ep) +{ + pthread_mutex_lock(&lp->lm); + assert(ep->busy); + ... remove ep from list ... + ep->busy = 0; /* Paranoid. */ +(A) pthread_cond_broadcast(&ep->notbusy); + pthread_mutex_unlock(&lp->lm); +(B) pthread_cond_destroy(&rp->notbusy); + free(ep); +} +\fP +.fi +.RE +.LP +In this example, the condition variable and its list element may be +freed (line B) immediately after all threads waiting for it +are awakened (line A), since the mutex and the code ensure that no +other thread can touch the element to be deleted. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +See \fIpthread_mutex_init\fP() ; a similar rationale applies to condition +variables. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_cond_broadcast\fP() , \fIpthread_cond_signal\fP() , \fIpthread_cond_timedwait\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_cond_signal.3p b/man3p/pthread_cond_signal.3p new file mode 100644 index 000000000..7b0a96a41 --- /dev/null +++ b/man3p/pthread_cond_signal.3p @@ -0,0 +1,182 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_COND_BROADCAST" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_cond_broadcast +.SH NAME +pthread_cond_broadcast, pthread_cond_signal \- broadcast or signal +a condition +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_cond_broadcast(pthread_cond_t *\fP\fIcond\fP\fB); +.br +int pthread_cond_signal(pthread_cond_t *\fP\fIcond\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +These functions shall unblock threads blocked on a condition variable. +.LP +The \fIpthread_cond_broadcast\fP() function shall unblock all threads +currently blocked on the specified condition variable +\fIcond\fP. +.LP +The \fIpthread_cond_signal\fP() function shall unblock at least one +of the threads that are blocked on the specified condition +variable \fIcond\fP (if any threads are blocked on \fIcond\fP). +.LP +If more than one thread is blocked on a condition variable, the scheduling +policy shall determine the order in which threads are +unblocked. When each thread unblocked as a result of a \fIpthread_cond_broadcast\fP() +or \fIpthread_cond_signal\fP() returns from +its call to \fIpthread_cond_wait\fP() or \fIpthread_cond_timedwait\fP(), +the thread shall own the mutex with which it called +\fIpthread_cond_wait\fP() or \fIpthread_cond_timedwait\fP(). The thread(s) +that are unblocked shall contend for +the mutex according to the scheduling policy (if applicable), and +as if each had called \fIpthread_mutex_lock\fP(). +.LP +The \fIpthread_cond_broadcast\fP() or \fIpthread_cond_signal\fP() +functions may be called by a thread whether or not it +currently owns the mutex that threads calling \fIpthread_cond_wait\fP() +or \fIpthread_cond_timedwait\fP() have associated with the condition +variable +during their waits; however, if predictable scheduling behavior is +required, then that mutex shall be locked by the thread calling +\fIpthread_cond_broadcast\fP() or \fIpthread_cond_signal\fP(). +.LP +The \fIpthread_cond_broadcast\fP() and \fIpthread_cond_signal\fP() +functions shall have no effect if there are no threads +currently blocked on \fIcond\fP. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_cond_broadcast\fP() and \fIpthread_cond_signal\fP() +functions shall return zero; otherwise, an +error number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_cond_broadcast\fP() and \fIpthread_cond_signal\fP() +function may fail if: +.TP 7 +.B EINVAL +The value \fIcond\fP does not refer to an initialized condition variable. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIpthread_cond_broadcast\fP() function is used whenever the shared-variable +state has been changed in a way that more than +one thread can proceed with its task. Consider a single producer/multiple +consumer problem, where the producer can insert multiple +items on a list that is accessed one item at a time by the consumers. +By calling the \fIpthread_cond_broadcast\fP() function, the +producer would notify all consumers that might be waiting, and thereby +the application would receive more throughput on a +multi-processor. In addition, \fIpthread_cond_broadcast\fP() makes +it easier to implement a read-write lock. The +\fIpthread_cond_broadcast\fP() function is needed in order to wake +up all waiting readers when a writer releases its lock. +Finally, the two-phase commit algorithm can use this broadcast function +to notify all clients of an impending transaction +commit. +.LP +It is not safe to use the \fIpthread_cond_signal\fP() function in +a signal handler that is invoked asynchronously. Even if it +were safe, there would still be a race between the test of the Boolean +\fIpthread_cond_wait\fP() that could not be efficiently eliminated. +.LP +Mutexes and condition variables are thus not suitable for releasing +a waiting thread by signaling from code running in a signal +handler. +.SH RATIONALE +.SS Multiple Awakenings by Condition Signal +.LP +On a multi-processor, it may be impossible for an implementation of +\fIpthread_cond_signal\fP() to avoid the unblocking of more +than one thread blocked on a condition variable. For example, consider +the following partial implementation of \fIpthread_cond_wait\fP() +and \fIpthread_cond_signal\fP(), executed by two threads in +the order given. One thread is trying to wait on the condition variable, +another is concurrently executing +\fIpthread_cond_signal\fP(), while a third thread is already waiting. +.sp +.RS +.nf + +\fBpthread_cond_wait(mutex, cond): + value = cond->value; /* 1 */ + pthread_mutex_unlock(mutex); /* 2 */ + pthread_mutex_lock(cond->mutex); /* 10 */ + if (value == cond->value) { /* 11 */ + me->next_cond = cond->waiter; + cond->waiter = me; + pthread_mutex_unlock(cond->mutex); + unable_to_run(me); + } else + pthread_mutex_unlock(cond->mutex); /* 12 */ + pthread_mutex_lock(mutex); /* 13 */ +.sp + +pthread_cond_signal(cond): + pthread_mutex_lock(cond->mutex); /* 3 */ + cond->value++; /* 4 */ + if (cond->waiter) { /* 5 */ + sleeper = cond->waiter; /* 6 */ + cond->waiter = sleeper->next_cond; /* 7 */ + able_to_run(sleeper); /* 8 */ + } + pthread_mutex_unlock(cond->mutex); /* 9 */ +\fP +.fi +.RE +.LP +The effect is that more than one thread can return from its call to +\fIpthread_cond_wait\fP() or \fIpthread_cond_timedwait\fP() as a result +of one call to +\fIpthread_cond_signal\fP(). This effect is called "spurious wakeup". +Note that the situation is self-correcting in that the +number of threads that are so awakened is finite; for example, the +next thread to call \fIpthread_cond_wait\fP() after the sequence of +events above blocks. +.LP +While this problem could be resolved, the loss of efficiency for a +fringe condition that occurs only rarely is unacceptable, +especially given that one has to check the predicate associated with +a condition variable anyway. Correcting this problem would +unnecessarily reduce the degree of concurrency in this basic building +block for all higher-level synchronization operations. +.LP +An added benefit of allowing spurious wakeups is that applications +are forced to code a predicate-testing-loop around the +condition wait. This also makes the application tolerate superfluous +condition broadcasts or signals on the same condition variable +that may be coded in some other part of the application. The resulting +applications are thus more robust. Therefore, +IEEE\ Std\ 1003.1-2001 explicitly documents that spurious wakeups +may occur. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_cond_destroy\fP() , \fIpthread_cond_timedwait\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_cond_timedwait.3p b/man3p/pthread_cond_timedwait.3p new file mode 100644 index 000000000..801322d98 --- /dev/null +++ b/man3p/pthread_cond_timedwait.3p @@ -0,0 +1 @@ +.so man3p/pthread_cond_wait.3p diff --git a/man3p/pthread_cond_wait.3p b/man3p/pthread_cond_wait.3p new file mode 100644 index 000000000..a1bee1a85 --- /dev/null +++ b/man3p/pthread_cond_wait.3p @@ -0,0 +1,335 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_COND_TIMEDWAIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_cond_timedwait +.SH NAME +pthread_cond_timedwait, pthread_cond_wait \- wait on a condition +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_cond_timedwait(pthread_cond_t *restrict\fP \fIcond\fP\fB, +.br +\ \ \ \ \ \ pthread_mutex_t *restrict\fP \fImutex\fP\fB, +.br +\ \ \ \ \ \ const struct timespec *restrict\fP \fIabstime\fP\fB); +.br +int pthread_cond_wait(pthread_cond_t *restrict\fP \fIcond\fP\fB, +.br +\ \ \ \ \ \ pthread_mutex_t *restrict\fP \fImutex\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_cond_timedwait\fP() and \fIpthread_cond_wait\fP() functions +shall block on a condition variable. They shall be +called with \fImutex\fP locked by the calling thread or undefined +behavior results. +.LP +These functions atomically release \fImutex\fP and cause the calling +thread to block on the condition variable \fIcond\fP; +atomically here means "atomically with respect to access by another +thread to the mutex and then the condition variable". That +is, if another thread is able to acquire the mutex after the about-to-block +thread has released it, then a subsequent call to \fIpthread_cond_broadcast\fP() +or \fIpthread_cond_signal\fP() in that thread shall behave as if it +were issued after the +about-to-block thread has blocked. +.LP +Upon successful return, the mutex shall have been locked and shall +be owned by the calling thread. +.LP +When using condition variables there is always a Boolean predicate +involving shared variables associated with each condition +wait that is true if the thread should proceed. Spurious wakeups from +the \fIpthread_cond_timedwait\fP() or +\fIpthread_cond_wait\fP() functions may occur. Since the return from +\fIpthread_cond_timedwait\fP() or \fIpthread_cond_wait\fP() +does not imply anything about the value of this predicate, the predicate +should be re-evaluated upon such return. +.LP +The effect of using more than one mutex for concurrent \fIpthread_cond_timedwait\fP() +or \fIpthread_cond_wait\fP() operations +on the same condition variable is undefined; that is, a condition +variable becomes bound to a unique mutex when a thread waits on +the condition variable, and this (dynamic) binding shall end when +the wait returns. +.LP +A condition wait (whether timed or not) is a cancellation point. When +the cancelability enable state of a thread is set to +PTHREAD_CANCEL_DEFERRED, a side effect of acting upon a cancellation +request while in a condition wait is that the mutex is (in +effect) re-acquired before calling the first cancellation cleanup +handler. The effect is as if the thread were unblocked, allowed +to execute up to the point of returning from the call to \fIpthread_cond_timedwait\fP() +or \fIpthread_cond_wait\fP(), but at that +point notices the cancellation request and instead of returning to +the caller of \fIpthread_cond_timedwait\fP() or +\fIpthread_cond_wait\fP(), starts the thread cancellation activities, +which includes calling cancellation cleanup handlers. +.LP +A thread that has been unblocked because it has been canceled while +blocked in a call to \fIpthread_cond_timedwait\fP() or +\fIpthread_cond_wait\fP() shall not consume any condition signal that +may be directed concurrently at the condition variable if +there are other threads blocked on the condition variable. +.LP +The \fIpthread_cond_timedwait\fP() function shall be equivalent to +\fIpthread_cond_wait\fP(), except that an error is returned +if the absolute time specified by \fIabstime\fP passes (that is, system +time equals or exceeds \fIabstime\fP) before the +condition \fIcond\fP is signaled or broadcasted, or if the absolute +time specified by \fIabstime\fP has already been passed at +the time of the call. +.LP +If +the Clock Selection option is supported, the condition variable shall +have a clock attribute which specifies the clock that shall +be used to measure the time specified by the \fIabstime\fP argument. +When such timeouts occur, \fIpthread_cond_timedwait\fP() shall nonetheless +release and re-acquire the mutex referenced by +\fImutex\fP. The \fIpthread_cond_timedwait\fP() function is also a +cancellation point. +.LP +If a signal is delivered to a thread waiting for a condition variable, +upon return from the signal handler the thread resumes +waiting for the condition variable as if it was not interrupted, or +it shall return zero due to spurious wakeup. +.SH RETURN VALUE +.LP +Except in the case of [ETIMEDOUT], all these error checks shall act +as if they were performed immediately at the beginning of +processing for the function and shall cause an error return, in effect, +prior to modifying the state of the mutex specified by +\fImutex\fP or the condition variable specified by \fIcond\fP. +.LP +Upon successful completion, a value of zero shall be returned; otherwise, +an error number shall be returned to indicate the +error. +.SH ERRORS +.LP +The \fIpthread_cond_timedwait\fP() function shall fail if: +.TP 7 +.B ETIMEDOUT +The time specified by \fIabstime\fP to \fIpthread_cond_timedwait\fP() +has passed. +.sp +.LP +The \fIpthread_cond_timedwait\fP() and \fIpthread_cond_wait\fP() functions +may fail if: +.TP 7 +.B EINVAL +The value specified by \fIcond\fP, \fImutex\fP, or \fIabstime\fP is +invalid. +.TP 7 +.B EINVAL +Different mutexes were supplied for concurrent \fIpthread_cond_timedwait\fP() +or \fIpthread_cond_wait\fP() operations on the +same condition variable. +.TP 7 +.B EPERM +The mutex was not owned by the current thread at the time of the call. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.SS Condition Wait Semantics +.LP +It is important to note that when \fIpthread_cond_wait\fP() and \fIpthread_cond_timedwait\fP() +return without error, the +associated predicate may still be false. Similarly, when \fIpthread_cond_timedwait\fP() +returns with the timeout error, the +associated predicate may be true due to an unavoidable race between +the expiration of the timeout and the predicate state +change. +.LP +Some implementations, particularly on a multi-processor, may sometimes +cause multiple threads to wake up when the condition +variable is signaled simultaneously on different processors. +.LP +In general, whenever a condition wait returns, the thread has to re-evaluate +the predicate associated with the condition wait to +determine whether it can safely proceed, should wait again, or should +declare a timeout. A return from the wait does not imply that +the associated predicate is either true or false. +.LP +It is thus recommended that a condition wait be enclosed in the equivalent +of a "while loop" that checks the predicate. +.SS Timed Wait Semantics +.LP +An absolute time measure was chosen for specifying the timeout parameter +for two reasons. First, a relative time measure can be +easily implemented on top of a function that specifies absolute time, +but there is a race condition associated with specifying an +absolute timeout on top of a function that specifies relative timeouts. +For example, assume that \fIclock_gettime\fP() returns the current +time and \fIcond_relative_timed_wait\fP() uses +relative timeouts: +.sp +.RS +.nf + +\fBclock_gettime(CLOCK_REALTIME, &now) +reltime = sleep_til_this_absolute_time -now; +cond_relative_timed_wait(c, m, &reltime); +\fP +.fi +.RE +.LP +If the thread is preempted between the first statement and the last +statement, the thread blocks for too long. Blocking, +however, is irrelevant if an absolute timeout is used. An absolute +timeout also need not be recomputed if it is used multiple times +in a loop, such as that enclosing a condition wait. +.LP +For cases when the system clock is advanced discontinuously by an +operator, it is expected that implementations process any +timed wait expiring at an intervening time as if that time had actually +occurred. +.SS Cancellation and Condition Wait +.LP +A condition wait, whether timed or not, is a cancellation point. That +is, the functions \fIpthread_cond_wait\fP() or +\fIpthread_cond_timedwait\fP() are points where a pending (or concurrent) +cancellation request is noticed. The reason for this is +that an indefinite wait is possible at these points-whatever event +is being waited for, even if the program is totally correct, +might never occur; for example, some input data being awaited might +never be sent. By making condition wait a cancellation point, +the thread can be canceled and perform its cancellation cleanup handler +even though it may be stuck in some indefinite wait. +.LP +A side effect of acting on a cancellation request while a thread is +blocked on a condition variable is to re-acquire the mutex +before calling any of the cancellation cleanup handlers. This is done +in order to ensure that the cancellation cleanup handler is +executed in the same state as the critical code that lies both before +and after the call to the condition wait function. This rule +is also required when interfacing to POSIX threads from languages, +such as Ada or C++, which may choose to map cancellation onto a +language exception; this rule ensures that each exception handler +guarding a critical section can always safely depend upon the +fact that the associated mutex has already been locked regardless +of exactly where within the critical section the exception was +raised. Without this rule, there would not be a uniform rule that +exception handlers could follow regarding the lock, and so coding +would become very cumbersome. +.LP +Therefore, since \fIsome\fP statement has to be made regarding the +state of the lock when a cancellation is delivered during a +wait, a definition has been chosen that makes application coding most +convenient and error free. +.LP +When acting on a cancellation request while a thread is blocked on +a condition variable, the implementation is required to +ensure that the thread does not consume any condition signals directed +at that condition variable if there are any other threads +waiting on that condition variable. This rule is specified in order +to avoid deadlock conditions that could occur if these two +independent requests (one acting on a thread and the other acting +on the condition variable) were not processed independently. +.SS Performance of Mutexes and Condition Variables +.LP +Mutexes are expected to be locked only for a few instructions. This +practice is almost automatically enforced by the desire of +programmers to avoid long serial regions of execution (which would +reduce total effective parallelism). +.LP +When using mutexes and condition variables, one tries to ensure that +the usual case is to lock the mutex, access shared data, +and unlock the mutex. Waiting on a condition variable should be a +relatively rare situation. For example, when implementing a +read-write lock, code that acquires a read-lock typically needs only +to increment the count of readers (under mutual-exclusion) and +return. The calling thread would actually wait on the condition variable +only when there is already an active writer. So the +efficiency of a synchronization operation is bounded by the cost of +mutex lock/unlock and not by condition wait. Note that in the +usual case there is no context switch. +.LP +This is not to say that the efficiency of condition waiting is unimportant. +Since there needs to be at least one context switch +per Ada rendezvous, the efficiency of waiting on a condition variable +is important. The cost of waiting on a condition variable +should be little more than the minimal cost for a context switch plus +the time to unlock and lock the mutex. +.SS Features of Mutexes and Condition Variables +.LP +It had been suggested that the mutex acquisition and release be decoupled +from condition wait. This was rejected because it is +the combined nature of the operation that, in fact, facilitates realtime +implementations. Those implementations can atomically move +a high-priority thread between the condition variable and the mutex +in a manner that is transparent to the caller. This can prevent +extra context switches and provide more deterministic acquisition +of a mutex when the waiting thread is signaled. Thus, fairness +and priority issues can be dealt with directly by the scheduling discipline. +Furthermore, the current condition wait operation +matches existing practice. +.SS Scheduling Behavior of Mutexes and Condition Variables +.LP +Synchronization primitives that attempt to interfere with scheduling +policy by specifying an ordering rule are considered +undesirable. Threads waiting on mutexes and condition variables are +selected to proceed in an order dependent upon the scheduling +policy rather than in some fixed order (for example, FIFO or priority). +Thus, the scheduling policy determines which thread(s) are +awakened and allowed to proceed. +.SS Timed Condition Wait +.LP +The \fIpthread_cond_timedwait\fP() function allows an application +to give up waiting for a particular condition after a given +amount of time. An example of its use follows: +.sp +.RS +.nf + +\fB(void) pthread_mutex_lock(&t.mn); + t.waiters++; + clock_gettime(CLOCK_REALTIME, &ts); + ts.tv_sec += 5; + rc = 0; + while (! mypredicate(&t) && rc == 0) + rc = pthread_cond_timedwait(&t.cond, &t.mn, &ts); + t.waiters--; + if (rc == 0) setmystate(&t); +(void) pthread_mutex_unlock(&t.mn); +\fP +.fi +.RE +.LP +By making the timeout parameter absolute, it does not need to be recomputed +each time the program checks its blocking predicate. +If the timeout was relative, it would have to be recomputed before +each call. This would be especially difficult since such code +would need to take into account the possibility of extra wakeups that +result from extra broadcasts or signals on the condition +variable that occur before either the predicate is true or the timeout +is due. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_cond_signal\fP() , \fIpthread_cond_broadcast\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_condattr_destroy.3p b/man3p/pthread_condattr_destroy.3p new file mode 100644 index 000000000..8da0a9c23 --- /dev/null +++ b/man3p/pthread_condattr_destroy.3p @@ -0,0 +1 @@ +.so man3p/pthread_condattr_init.3p diff --git a/man3p/pthread_condattr_getclock.3p b/man3p/pthread_condattr_getclock.3p new file mode 100644 index 000000000..198c4f2f9 --- /dev/null +++ b/man3p/pthread_condattr_getclock.3p @@ -0,0 +1,95 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_CONDATTR_GETCLOCK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_condattr_getclock +.SH NAME +pthread_condattr_getclock, pthread_condattr_setclock \- get and set +the clock selection condition variable attribute +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_condattr_getclock(const pthread_condattr_t *restrict\fP +\fIattr\fP\fB, +.br +\ \ \ \ \ \ clockid_t *restrict\fP \fIclock_id\fP\fB); +.br +int pthread_condattr_setclock(pthread_condattr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ clockid_t\fP \fIclock_id\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_condattr_getclock\fP() function shall obtain the value +of the \fIclock\fP attribute from the attributes object +referenced by \fIattr\fP. The \fIpthread_condattr_setclock\fP() function +shall set the \fIclock\fP attribute in an initialized +attributes object referenced by \fIattr\fP. If \fIpthread_condattr_setclock\fP() +is called with a \fIclock_id\fP argument that +refers to a CPU-time clock, the call shall fail. +.LP +The \fIclock\fP attribute is the clock ID of the clock that shall +be used to measure the timeout service of \fIpthread_cond_timedwait\fP(). +The default value of the \fIclock\fP attribute +shall refer to the system clock. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_condattr_getclock\fP() function shall +return zero and store the value of the clock attribute of +\fIattr\fP into the object referenced by the \fIclock_id\fP argument. +Otherwise, an error number shall be returned to indicate +the error. +.LP +If successful, the \fIpthread_condattr_setclock\fP() function shall +return zero; otherwise, an error number shall be returned +to indicate the error. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +The \fIpthread_condattr_setclock\fP() function may fail if: +.TP 7 +.B EINVAL +The value specified by \fIclock_id\fP does not refer to a known clock, +or is a CPU-time clock. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_cond_destroy\fP() , \fIpthread_cond_timedwait\fP() , \fIpthread_condattr_destroy\fP() +, \fIpthread_condattr_getpshared\fP() ,1 \fIpthread_condattr_init\fP() +, \fIpthread_condattr_setpshared\fP() ,1 \fIpthread_create\fP() , +\fIpthread_mutex_init\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_condattr_getpshared.3p b/man3p/pthread_condattr_getpshared.3p new file mode 100644 index 000000000..c48492237 --- /dev/null +++ b/man3p/pthread_condattr_getpshared.3p @@ -0,0 +1,99 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_CONDATTR_GETPSHARED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_condattr_getpshared +.SH NAME +pthread_condattr_getpshared, pthread_condattr_setpshared \- get and +set the process\-shared condition variable +attributes +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_condattr_getpshared(const pthread_condattr_t *restrict\fP +\fIattr\fP\fB, +.br +\ \ \ \ \ \ int *restrict\fP \fIpshared\fP\fB); +.br +int pthread_condattr_setpshared(pthread_condattr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIpshared\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_condattr_getpshared\fP() function shall obtain the +value of the \fIprocess-shared\fP attribute from the +attributes object referenced by \fIattr\fP. The \fIpthread_condattr_setpshared\fP() +function shall set the \fIprocess-shared\fP +attribute in an initialized attributes object referenced by \fIattr\fP. +.LP +The \fIprocess-shared\fP attribute is set to PTHREAD_PROCESS_SHARED +to permit a condition variable to be operated upon by any +thread that has access to the memory where the condition variable +is allocated, even if the condition variable is allocated in +memory that is shared by multiple processes. If the \fIprocess-shared\fP +attribute is PTHREAD_PROCESS_PRIVATE, the condition +variable shall only be operated upon by threads created within the +same process as the thread that initialized the condition +variable; if threads of differing processes attempt to operate on +such a condition variable, the behavior is undefined. The default +value of the attribute is PTHREAD_PROCESS_PRIVATE. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_condattr_setpshared\fP() function shall +return zero; otherwise, an error number shall be returned +to indicate the error. +.LP +If successful, the \fIpthread_condattr_getpshared\fP() function shall +return zero and store the value of the +\fIprocess-shared\fP attribute of \fIattr\fP into the object referenced +by the \fIpshared\fP parameter. Otherwise, an error +number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_condattr_getpshared\fP() and \fIpthread_condattr_setpshared\fP() +functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +The \fIpthread_condattr_setpshared\fP() function may fail if: +.TP 7 +.B EINVAL +The new value specified for the attribute is outside the range of +legal values for that attribute. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_create\fP() , \fIpthread_cond_destroy\fP() , \fIpthread_condattr_destroy\fP() +, \fIpthread_mutex_destroy\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_condattr_init.3p b/man3p/pthread_condattr_init.3p new file mode 100644 index 000000000..960b3ff68 --- /dev/null +++ b/man3p/pthread_condattr_init.3p @@ -0,0 +1,103 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_CONDATTR_DESTROY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_condattr_destroy +.SH NAME +pthread_condattr_destroy, pthread_condattr_init \- destroy and initialize +the condition variable attributes +object +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_condattr_destroy(pthread_condattr_t *\fP\fIattr\fP\fB); +.br +int pthread_condattr_init(pthread_condattr_t *\fP\fIattr\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_condattr_destroy\fP() function shall destroy a condition +variable attributes object; the object becomes, in +effect, uninitialized. An implementation may cause \fIpthread_condattr_destroy\fP() +to set the object referenced by \fIattr\fP to +an invalid value. A destroyed \fIattr\fP attributes object can be +reinitialized using \fIpthread_condattr_init\fP(); the results +of otherwise referencing the object after it has been destroyed are +undefined. +.LP +The \fIpthread_condattr_init\fP() function shall initialize a condition +variable attributes object \fIattr\fP with the default +value for all of the attributes defined by the implementation. +.LP +Results are undefined if \fIpthread_condattr_init\fP() is called specifying +an already initialized \fIattr\fP attributes +object. +.LP +After a condition variable attributes object has been used to initialize +one or more condition variables, any function affecting +the attributes object (including destruction) shall not affect any +previously initialized condition variables. +.LP +This volume of IEEE\ Std\ 1003.1-2001 requires two attributes, the +\fIclock\fP attribute and the \fIprocess-shared\fP +attribute. +.LP +Additional attributes, their default values, and the names of the +associated functions to get and set those attribute values are +implementation-defined. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_condattr_destroy\fP() and \fIpthread_condattr_init\fP() +functions shall return zero; otherwise, +an error number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_condattr_destroy\fP() function may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +The \fIpthread_condattr_init\fP() function shall fail if: +.TP 7 +.B ENOMEM +Insufficient memory exists to initialize the condition variable attributes +object. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +See \fIpthread_attr_init\fP() and \fIpthread_mutex_init\fP() . +.LP +A \fIprocess-shared\fP attribute has been defined for condition variables +for the same reason it has been defined for +mutexes. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_attr_destroy\fP() , \fIpthread_cond_destroy\fP() , \fIpthread_condattr_getpshared\fP() +, \fIpthread_create\fP() , \fIpthread_mutex_destroy\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_condattr_setclock.3p b/man3p/pthread_condattr_setclock.3p new file mode 100644 index 000000000..518089a4b --- /dev/null +++ b/man3p/pthread_condattr_setclock.3p @@ -0,0 +1 @@ +.so man3p/pthread_condattr_getclock.3p diff --git a/man3p/pthread_condattr_setpshared.3p b/man3p/pthread_condattr_setpshared.3p new file mode 100644 index 000000000..2bd028ca1 --- /dev/null +++ b/man3p/pthread_condattr_setpshared.3p @@ -0,0 +1 @@ +.so man3p/pthread_condattr_getpshared.3p diff --git a/man3p/pthread_create.3p b/man3p/pthread_create.3p new file mode 100644 index 000000000..4e4c1ef6e --- /dev/null +++ b/man3p/pthread_create.3p @@ -0,0 +1,191 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_CREATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_create +.SH NAME +pthread_create \- thread creation +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_create(pthread_t *restrict\fP \fIthread\fP\fB, +.br +\ \ \ \ \ \ const pthread_attr_t *restrict\fP \fIattr\fP\fB, +.br +\ \ \ \ \ \ void *(*\fP\fIstart_routine\fP\fB)(void*), void *restrict\fP +\fIarg\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_create\fP() function shall create a new thread, with +attributes specified by \fIattr\fP, within a process. If +\fIattr\fP is NULL, the default attributes shall be used. If the attributes +specified by \fIattr\fP are modified later, the +thread's attributes shall not be affected. Upon successful completion, +\fIpthread_create\fP() shall store the ID of the created +thread in the location referenced by \fIthread\fP. +.LP +The thread is created executing \fIstart_routine\fP with \fIarg\fP +as its sole argument. If the \fIstart_routine\fP returns, +the effect shall be as if there was an implicit call to \fIpthread_exit\fP() +using +the return value of \fIstart_routine\fP as the exit status. Note that +the thread in which \fImain\fP() was originally invoked +differs from this. When it returns from \fImain\fP(), the effect shall +be as if there was an implicit call to \fIexit\fP() using the return +value of \fImain\fP() as the exit status. +.LP +The signal state of the new thread shall be initialized as follows: +.IP " *" 3 +The signal mask shall be inherited from the creating thread. +.LP +.IP " *" 3 +The set of signals pending for the new thread shall be empty. +.LP +.LP +The alternate stack shall not be inherited. +.LP +The floating-point environment shall be inherited from the creating +thread. +.LP +If \fIpthread_create\fP() fails, no new thread is created and the +contents of the location referenced by \fIthread\fP are +undefined. +.LP +If _POSIX_THREAD_CPUTIME is defined, the new thread shall have a CPU-time +clock accessible, and the initial value of this clock +shall be set to zero. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_create\fP() function shall return zero; +otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +.LP +The \fIpthread_create\fP() function shall fail if: +.TP 7 +.B EAGAIN +The system lacked the necessary resources to create another thread, +or the system-imposed limit on the total number of threads +in a process {PTHREAD_THREADS_MAX} would be exceeded. +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.TP 7 +.B EPERM +The caller does not have appropriate permission to set the required +scheduling parameters or scheduling policy. +.sp +.LP +The \fIpthread_create\fP() function shall not return an error code +of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +A suggested alternative to \fIpthread_create\fP() would be to define +two separate operations: create and start. Some +applications would find such behavior more natural. Ada, in particular, +separates the "creation" of a task from its +"activation". +.LP +Splitting the operation was rejected by the standard developers for +many reasons: +.IP " *" 3 +The number of calls required to start a thread would increase from +one to two and thus place an additional burden on +applications that do not require the additional synchronization. The +second call, however, could be avoided by the additional +complication of a start-up state attribute. +.LP +.IP " *" 3 +An extra state would be introduced: "created but not started". This +would require the standard to specify the behavior of the +thread operations when the target has not yet started executing. +.LP +.IP " *" 3 +For those applications that require such behavior, it is possible +to simulate the two separate steps with the facilities that +are currently provided. The \fIstart_routine\fP() can synchronize +by waiting on a condition variable that is signaled by the start +operation. +.LP +.LP +An Ada implementor can choose to create the thread at either of two +points in the Ada program: when the task object is created, +or when the task is activated (generally at a "begin"). If the first +approach is adopted, the \fIstart_routine\fP() needs to +wait on a condition variable to receive the order to begin "activation". +The second approach requires no such condition variable +or extra synchronization. In either approach, a separate Ada task +control block would need to be created when the task object is +created to hold rendezvous queues, and so on. +.LP +An extension of the preceding model would be to allow the state of +the thread to be modified between the create and start. This +would allow the thread attributes object to be eliminated. This has +been rejected because: +.IP " *" 3 +All state in the thread attributes object has to be able to be set +for the thread. This would require the definition of +functions to modify thread attributes. There would be no reduction +in the number of function calls required to set up the thread. +In fact, for an application that creates all threads using identical +attributes, the number of function calls required to set up +the threads would be dramatically increased. Use of a thread attributes +object permits the application to make one set of attribute +setting function calls. Otherwise, the set of attribute setting function +calls needs to be made for each thread creation. +.LP +.IP " *" 3 +Depending on the implementation architecture, functions to set thread +state would require kernel calls, or for other +implementation reasons would not be able to be implemented as macros, +thereby increasing the cost of thread creation. +.LP +.IP " *" 3 +The ability for applications to segregate threads by class would be +lost. +.LP +.LP +Another suggested alternative uses a model similar to that for process +creation, such as "thread fork". The fork semantics +would provide more flexibility and the "create" function can be implemented +simply by doing a thread fork followed immediately by +a call to the desired "start routine" for the thread. This alternative +has these problems: +.IP " *" 3 +For many implementations, the entire stack of the calling thread would +need to be duplicated, since in many architectures there +is no way to determine the size of the calling frame. +.LP +.IP " *" 3 +Efficiency is reduced since at least some part of the stack has to +be copied, even though in most cases the thread never needs +the copied context, since it merely calls the desired start routine. +.LP +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfork\fP() , \fIpthread_exit\fP() , \fIpthread_join\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_detach.3p b/man3p/pthread_detach.3p new file mode 100644 index 000000000..337fd1468 --- /dev/null +++ b/man3p/pthread_detach.3p @@ -0,0 +1,95 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_DETACH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_detach +.SH NAME +pthread_detach \- detach a thread +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_detach(pthread_t\fP \fIthread\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_detach\fP() function shall indicate to the implementation +that storage for the thread \fIthread\fP can be +reclaimed when that thread terminates. If \fIthread\fP has not terminated, +\fIpthread_detach\fP() shall not cause it to +terminate. The effect of multiple \fIpthread_detach\fP() calls on +the same target thread is unspecified. +.SH RETURN VALUE +.LP +If the call succeeds, \fIpthread_detach\fP() shall return 0; otherwise, +an error number shall be returned to indicate the +error. +.SH ERRORS +.LP +The \fIpthread_detach\fP() function shall fail if: +.TP 7 +.B EINVAL +The implementation has detected that the value specified by \fIthread\fP +does not refer to a joinable thread. +.TP 7 +.B ESRCH +No thread could be found corresponding to that specified by the given +thread ID. +.sp +.LP +The \fIpthread_detach\fP() function shall not return an error code +of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIpthread_join\fP() or \fIpthread_detach\fP() functions should +eventually be +called for every thread that is created so that storage associated +with the thread may be reclaimed. +.LP +It has been suggested that a "detach" function is not necessary; the +\fIdetachstate\fP thread creation attribute is +sufficient, since a thread need never be dynamically detached. However, +need arises in at least two cases: +.IP " 1." 4 +In a cancellation handler for a \fIpthread_join\fP() it is nearly +essential to +have a \fIpthread_detach\fP() function in order to detach the thread +on which \fIpthread_join\fP() was waiting. Without it, it would be +necessary to have the handler do +another \fIpthread_join\fP() to attempt to detach the thread, which +would both delay +the cancellation processing for an unbounded period and introduce +a new call to \fIpthread_join\fP(), which might itself need a cancellation +handler. A dynamic detach is +nearly essential in this case. +.LP +.IP " 2." 4 +In order to detach the "initial thread" (as may be desirable in processes +that set up server threads). +.LP +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_join\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_equal.3p b/man3p/pthread_equal.3p new file mode 100644 index 000000000..078c0a195 --- /dev/null +++ b/man3p/pthread_equal.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_EQUAL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_equal +.SH NAME +pthread_equal \- compare thread IDs +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_equal(pthread_t\fP \fIt1\fP\fB, pthread_t\fP \fIt2\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +This function shall compare the thread IDs \fIt1\fP and \fIt2\fP. +.SH RETURN VALUE +.LP +The \fIpthread_equal\fP() function shall return a non-zero value if +\fIt1\fP and \fIt2\fP are equal; otherwise, zero shall be +returned. +.LP +If either \fIt1\fP or \fIt2\fP are not valid thread IDs, the behavior +is undefined. +.SH ERRORS +.LP +No errors are defined. +.LP +The \fIpthread_equal\fP() function shall not return an error code +of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Implementations may choose to define a thread ID as a structure. This +allows additional flexibility and robustness over using an +\fBint\fP. For example, a thread ID could include a sequence number +that allows detection of "dangling IDs" (copies of a thread +ID that has been detached). Since the C language does not support +comparison on structure types, the \fIpthread_equal\fP() +function is provided to compare thread IDs. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_create\fP() , \fIpthread_self\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_exit.3p b/man3p/pthread_exit.3p new file mode 100644 index 000000000..a392d9894 --- /dev/null +++ b/man3p/pthread_exit.3p @@ -0,0 +1,104 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_EXIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_exit +.SH NAME +pthread_exit \- thread termination +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void pthread_exit(void *\fP\fIvalue_ptr\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_exit\fP() function shall terminate the calling thread +and make the value \fIvalue_ptr\fP available to any +successful join with the terminating thread. Any cancellation cleanup +handlers that have been pushed and not yet popped shall be +popped in the reverse order that they were pushed and then executed. +After all cancellation cleanup handlers have been executed, if +the thread has any thread-specific data, appropriate destructor functions +shall be called in an unspecified order. Thread +termination does not release any application visible process resources, +including, but not limited to, mutexes and file +descriptors, nor does it perform any process-level cleanup actions, +including, but not limited to, calling any \fIatexit\fP() routines +that may exist. +.LP +An implicit call to \fIpthread_exit\fP() is made when a thread other +than the thread in which \fImain\fP() was first invoked +returns from the start routine that was used to create it. The function's +return value shall serve as the thread's exit status. +.LP +The behavior of \fIpthread_exit\fP() is undefined if called from a +cancellation cleanup handler or destructor function that was +invoked as a result of either an implicit or explicit call to \fIpthread_exit\fP(). +.LP +After a thread has terminated, the result of access to local (auto) +variables of the thread is undefined. Thus, references to +local variables of the exiting thread should not be used for the \fIpthread_exit\fP() +\fIvalue_ptr\fP parameter value. +.LP +The process shall exit with an exit status of 0 after the last thread +has been terminated. The behavior shall be as if the +implementation called \fIexit\fP() with a zero argument at thread +termination time. +.SH RETURN VALUE +.LP +The \fIpthread_exit\fP() function cannot return to its caller. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The normal mechanism by which a thread terminates is to return from +the routine that was specified in the \fIpthread_create\fP() call +that started it. The \fIpthread_exit\fP() function provides +the capability for a thread to terminate without requiring a return +from the start routine of that thread, thereby providing a +function analogous to \fIexit\fP(). +.LP +Regardless of the method of thread termination, any cancellation cleanup +handlers that have been pushed and not yet popped are +executed, and the destructors for any existing thread-specific data +are executed. This volume of IEEE\ Std\ 1003.1-2001 +requires that cancellation cleanup handlers be popped and called in +order. After all cancellation cleanup handlers have been +executed, thread-specific data destructors are called, in an unspecified +order, for each item of thread-specific data that exists +in the thread. This ordering is necessary because cancellation cleanup +handlers may rely on thread-specific data. +.LP +As the meaning of the status is determined by the application (except +when the thread has been canceled, in which case it is +PTHREAD_CANCELED), the implementation has no idea what an illegal +status value is, which is why no address error checking is +done. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexit\fP() , \fIpthread_create\fP() , \fIpthread_join\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_getconcurrency.3p b/man3p/pthread_getconcurrency.3p new file mode 100644 index 000000000..7928ea538 --- /dev/null +++ b/man3p/pthread_getconcurrency.3p @@ -0,0 +1,110 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_GETCONCURRENCY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_getconcurrency +.SH NAME +pthread_getconcurrency, pthread_setconcurrency \- get and set the level +of concurrency +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_getconcurrency(void); +.br +int pthread_setconcurrency(int\fP \fInew_level\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +Unbound threads in a process may or may not be required to be simultaneously +active. By default, the threads implementation +ensures that a sufficient number of threads are active so that the +process can continue to make progress. While this conserves +system resources, it may not produce the most effective level of concurrency. +.LP +The \fIpthread_setconcurrency\fP() function allows an application +to inform the threads implementation of its desired +concurrency level, \fInew_level\fP. The actual level of concurrency +provided by the implementation as a result of this function +call is unspecified. +.LP +If \fInew_level\fP is zero, it causes the implementation to maintain +the concurrency level at its discretion as if +\fIpthread_setconcurrency\fP() had never been called. +.LP +The \fIpthread_getconcurrency\fP() function shall return the value +set by a previous call to the +\fIpthread_setconcurrency\fP() function. If the \fIpthread_setconcurrency\fP() +function was not previously called, this function +shall return zero to indicate that the implementation is maintaining +the concurrency level. +.LP +A call to \fIpthread_setconcurrency\fP() shall inform the implementation +of its desired concurrency level. The implementation +shall use this as a hint, not a requirement. +.LP +If an implementation does not support multiplexing of user threads +on top of several kernel-scheduled entities, the +\fIpthread_setconcurrency\fP() and \fIpthread_getconcurrency\fP() +functions are provided for source code compatibility but they +shall have no effect when called. To maintain the function semantics, +the \fInew_level\fP parameter is saved when +\fIpthread_setconcurrency\fP() is called so that a subsequent call +to \fIpthread_getconcurrency\fP() shall return the same +value. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_setconcurrency\fP() function shall return +zero; otherwise, an error number shall be returned to +indicate the error. +.LP +The \fIpthread_getconcurrency\fP() function shall always return the +concurrency level set by a previous call to +\fIpthread_setconcurrency\fP(). If the \fIpthread_setconcurrency\fP() +function has never been called, +\fIpthread_getconcurrency\fP() shall return zero. +.SH ERRORS +.LP +The \fIpthread_setconcurrency\fP() function shall fail if: +.TP 7 +.B EINVAL +The value specified by \fInew_level\fP is negative. +.TP 7 +.B EAGAIN +The value specific by \fInew_level\fP would cause a system resource +to be exceeded. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Use of these functions changes the state of the underlying concurrency +upon which the application depends. Library developers +are advised to not use the \fIpthread_getconcurrency\fP() and \fIpthread_setconcurrency\fP() +functions since their use may +conflict with an applications use of these functions. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_getcpuclockid.3p b/man3p/pthread_getcpuclockid.3p new file mode 100644 index 000000000..916d78e51 --- /dev/null +++ b/man3p/pthread_getcpuclockid.3p @@ -0,0 +1,68 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_GETCPUCLOCKID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_getcpuclockid +.SH NAME +pthread_getcpuclockid \- access a thread CPU-time clock (\fBADVANCED +REALTIME THREADS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int pthread_getcpuclockid(pthread_t\fP \fIthread_id\fP\fB, clockid_t +*\fP\fIclock_id\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_getcpuclockid\fP() function shall return in \fIclock_id\fP +the clock ID of the CPU-time clock of the thread +specified by \fIthread_id\fP, if the thread specified by \fIthread_id\fP +exists. +.SH RETURN VALUE +.LP +Upon successful completion, \fIpthread_getcpuclockid\fP() shall return +zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +.LP +The \fIpthread_getcpuclockid\fP() function may fail if: +.TP 7 +.B ESRCH +The value specified by \fIthread_id\fP does not refer to an existing +thread. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIpthread_getcpuclockid\fP() function is part of the Thread CPU-Time +Clocks option and need not be provided on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclock_getcpuclockid\fP() , \fIclock_getres\fP() , \fItimer_create\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_getschedparam.3p b/man3p/pthread_getschedparam.3p new file mode 100644 index 000000000..5cb2812ec --- /dev/null +++ b/man3p/pthread_getschedparam.3p @@ -0,0 +1,147 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_GETSCHEDPARAM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_getschedparam +.SH NAME +pthread_getschedparam, pthread_setschedparam \- dynamic thread scheduling +parameters access (\fBREALTIME +THREADS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_getschedparam(pthread_t\fP \fIthread\fP\fB, int *restrict\fP +\fIpolicy\fP\fB, +.br +\ \ \ \ \ \ struct sched_param *restrict\fP \fIparam\fP\fB); +.br +int pthread_setschedparam(pthread_t\fP \fIthread\fP\fB, int\fP \fIpolicy\fP\fB, +.br +\ \ \ \ \ \ const struct sched_param *\fP\fIparam\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_getschedparam\fP() and \fIpthread_setschedparam\fP() +functions shall, respectively, get and set the scheduling +policy and parameters of individual threads within a multi-threaded +process to be retrieved and set. For SCHED_FIFO and SCHED_RR, +the only required member of the \fBsched_param\fP structure is the +priority \fIsched_priority\fP. For SCHED_OTHER, the affected +scheduling parameters are implementation-defined. +.LP +The \fIpthread_getschedparam\fP() function shall retrieve the scheduling +policy and scheduling parameters for the thread whose +thread ID is given by \fIthread\fP and shall store those values in +\fIpolicy\fP and \fIparam\fP, respectively. The priority +value returned from \fIpthread_getschedparam\fP() shall be the value +specified by the most recent \fIpthread_setschedparam\fP(), +\fIpthread_setschedprio\fP(), or \fIpthread_create\fP() call affecting +the target thread. It shall not reflect any temporary +adjustments to its priority as a result of any priority inheritance +or ceiling functions. The \fIpthread_setschedparam\fP() +function shall set the scheduling policy and associated scheduling +parameters for the thread whose thread ID is given by +\fIthread\fP to the policy and associated parameters provided in \fIpolicy\fP +and \fIparam\fP, respectively. +.LP +The \fIpolicy\fP parameter may have the value SCHED_OTHER, SCHED_FIFO, +or SCHED_RR. The scheduling parameters for the +SCHED_OTHER policy are implementation-defined. The SCHED_FIFO and +SCHED_RR policies shall have a single scheduling parameter, +\fIpriority\fP. +.LP +If _POSIX_THREAD_SPORADIC_SERVER is defined, then the \fIpolicy\fP +argument may have the value SCHED_SPORADIC, with the exception +for the \fIpthread_setschedparam\fP() function that if the scheduling +policy was not SCHED_SPORADIC at the time of the call, it is +implementation-defined whether the function is supported; in other +words, the implementation need not allow the application to +dynamically change the scheduling policy to SCHED_SPORADIC. The sporadic +server scheduling policy has the associated parameters +\fIsched_ss_low_priority\fP, \fIsched_ss_repl_period\fP, \fIsched_ss_init_budget\fP, +\fIsched_priority\fP, and +\fIsched_ss_max_repl\fP. The specified \fIsched_ss_repl_period\fP +shall be greater than or equal to the specified +\fIsched_ss_init_budget\fP for the function to succeed; if it is not, +then the function shall fail. The value of +\fIsched_ss_max_repl\fP shall be within the inclusive range [1, {SS_REPL_MAX}] +for the function to succeed; if not, the function +shall fail. +.LP +If the \fIpthread_setschedparam\fP() function fails, the scheduling +parameters shall not be changed for the target thread. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_getschedparam\fP() and \fIpthread_setschedparam\fP() +functions shall return zero; otherwise, an +error number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_getschedparam\fP() function may fail if: +.TP 7 +.B ESRCH +The value specified by \fIthread\fP does not refer to an existing +thread. +.sp +.LP +The \fIpthread_setschedparam\fP() function may fail if: +.TP 7 +.B EINVAL +The value specified by \fIpolicy\fP or one of the scheduling parameters +associated with the scheduling policy \fIpolicy\fP is +invalid. +.TP 7 +.B ENOTSUP +An attempt was made to set the policy or scheduling parameters to +an unsupported value. +.TP 7 +.B ENOTSUP +An attempt was made to dynamically change the scheduling policy to +SCHED_SPORADIC, and the implementation does not support this +change. +.TP 7 +.B EPERM +The caller does not have the appropriate permission to set either +the scheduling parameters or the scheduling policy of the +specified thread. +.TP 7 +.B EPERM +The implementation does not allow the application to modify one of +the parameters to the value specified. +.TP 7 +.B ESRCH +The value specified by \fIthread\fP does not refer to a existing thread. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_setschedprio\fP() , \fIsched_getparam\fP() , \fIsched_getscheduler\fP() +, the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_getspecific.3p b/man3p/pthread_getspecific.3p new file mode 100644 index 000000000..d0408a15e --- /dev/null +++ b/man3p/pthread_getspecific.3p @@ -0,0 +1,109 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_GETSPECIFIC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_getspecific +.SH NAME +pthread_getspecific, pthread_setspecific \- thread-specific data management +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void *pthread_getspecific(pthread_key_t\fP \fIkey\fP\fB); +.br +int pthread_setspecific(pthread_key_t\fP \fIkey\fP\fB, const void +*\fP\fIvalue\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_getspecific\fP() function shall return the value currently +bound to the specified \fIkey\fP on behalf of the +calling thread. +.LP +The \fIpthread_setspecific\fP() function shall associate a thread-specific +\fIvalue\fP with a \fIkey\fP obtained via a +previous call to \fIpthread_key_create\fP(). Different threads may +bind +different values to the same key. These values are typically pointers +to blocks of dynamically allocated memory that have been +reserved for use by the calling thread. +.LP +The effect of calling \fIpthread_getspecific\fP() or \fIpthread_setspecific\fP() +with a \fIkey\fP value not obtained from \fIpthread_key_create\fP() +or after \fIkey\fP has been deleted with \fIpthread_key_delete\fP() +is undefined. +.LP +Both \fIpthread_getspecific\fP() and \fIpthread_setspecific\fP() may +be called from a thread-specific data destructor +function. A call to \fIpthread_getspecific\fP() for the thread-specific +data key being destroyed shall return the value NULL, +unless the value is changed (after the destructor starts) by a call +to \fIpthread_setspecific\fP(). Calling +\fIpthread_setspecific\fP() from a thread-specific data destructor +routine may result either in lost storage (after at least +PTHREAD_DESTRUCTOR_ITERATIONS attempts at destruction) or in an infinite +loop. +.LP +Both functions may be implemented as macros. +.SH RETURN VALUE +.LP +The \fIpthread_getspecific\fP() function shall return the thread-specific +data value associated with the given \fIkey\fP. If +no thread-specific data value is associated with \fIkey\fP, then the +value NULL shall be returned. +.LP +If successful, the \fIpthread_setspecific\fP() function shall return +zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +.LP +No errors are returned from \fIpthread_getspecific\fP(). +.LP +The \fIpthread_setspecific\fP() function shall fail if: +.TP 7 +.B ENOMEM +Insufficient memory exists to associate the value with the key. +.sp +.LP +The \fIpthread_setspecific\fP() function may fail if: +.TP 7 +.B EINVAL +The key value is invalid. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Performance and ease-of-use of \fIpthread_getspecific\fP() are critical +for functions that rely on maintaining state in +thread-specific data. Since no errors are required to be detected +by it, and since the only error that could be detected is the use +of an invalid key, the function to \fIpthread_getspecific\fP() has +been designed to favor speed and simplicity over error +reporting. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_key_create\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_join.3p b/man3p/pthread_join.3p new file mode 100644 index 000000000..a34e46147 --- /dev/null +++ b/man3p/pthread_join.3p @@ -0,0 +1,179 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_JOIN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_join +.SH NAME +pthread_join \- wait for thread termination +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_join(pthread_t\fP \fIthread\fP\fB, void **\fP\fIvalue_ptr\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_join\fP() function shall suspend execution of the calling +thread until the target \fIthread\fP terminates, +unless the target \fIthread\fP has already terminated. On return from +a successful \fIpthread_join\fP() call with a non-NULL +\fIvalue_ptr\fP argument, the value passed to \fIpthread_exit\fP() +by the +terminating thread shall be made available in the location referenced +by \fIvalue_ptr\fP. When a \fIpthread_join\fP() returns +successfully, the target thread has been terminated. The results of +multiple simultaneous calls to \fIpthread_join\fP() specifying +the same target thread are undefined. If the thread calling \fIpthread_join\fP() +is canceled, then the target thread shall not be +detached. +.LP +It is unspecified whether a thread that has exited but remains unjoined +counts against {PTHREAD_THREADS_MAX}. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_join\fP() function shall return zero; +otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +.LP +The \fIpthread_join\fP() function shall fail if: +.TP 7 +.B EINVAL +The implementation has detected that the value specified by \fIthread\fP +does not refer to a joinable thread. +.TP 7 +.B ESRCH +No thread could be found corresponding to that specified by the given +thread ID. +.sp +.LP +The \fIpthread_join\fP() function may fail if: +.TP 7 +.B EDEADLK +A deadlock was detected or the value of \fIthread\fP specifies the +calling thread. +.sp +.LP +The \fIpthread_join\fP() function shall not return an error code of +[EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +An example of thread creation and deletion follows: +.sp +.RS +.nf + +\fBtypedef struct { + int *ar; + long n; +} subarray; +.sp + +void * +incer(void *arg) +{ + long i; +.sp + + for (i = 0; i < ((subarray *)arg)->n; i++) + ((subarray *)arg)->ar[i]++; +} +.sp + +int main(void) +{ + int ar[1000000]; + pthread_t th1, th2; + subarray sb1, sb2; +.sp + + sb1.ar = &ar[0]; + sb1.n = 500000; + (void) pthread_create(&th1, NULL, incer, &sb1); +.sp + + sb2.ar = &ar[500000]; + sb2.n = 500000; + (void) pthread_create(&th2, NULL, incer, &sb2); +.sp + + (void) pthread_join(th1, NULL); + (void) pthread_join(th2, NULL); + return 0; +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIpthread_join\fP() function is a convenience that has proven +useful in multi-threaded applications. It is true that a +programmer could simulate this function if it were not provided by +passing extra state as part of the argument to the +\fIstart_routine\fP(). The terminating thread would set a flag to +indicate termination and broadcast a condition that is part of +that state; a joining thread would wait on that condition variable. +While such a technique would allow a thread to wait on more +complex conditions (for example, waiting for multiple threads to terminate), +waiting on individual thread termination is considered +widely useful. Also, including the \fIpthread_join\fP() function in +no way precludes a programmer from coding such complex waits. +Thus, while not a primitive, including \fIpthread_join\fP() in this +volume of IEEE\ Std\ 1003.1-2001 was considered +valuable. +.LP +The \fIpthread_join\fP() function provides a simple mechanism allowing +an application to wait for a thread to terminate. After +the thread terminates, the application may then choose to clean up +resources that were used by the thread. For instance, after +\fIpthread_join\fP() returns, any application-provided stack storage +could be reclaimed. +.LP +The \fIpthread_join\fP() or \fIpthread_detach\fP() function should +eventually +be called for every thread that is created with the \fIdetachstate\fP +attribute set to PTHREAD_CREATE_JOINABLE so that storage +associated with the thread may be reclaimed. +.LP +The interaction between \fIpthread_join\fP() and cancellation is well-defined +for the following reasons: +.IP " *" 3 +The \fIpthread_join\fP() function, like all other non-async-cancel-safe +functions, can only be called with deferred +cancelability type. +.LP +.IP " *" 3 +Cancellation cannot occur in the disabled cancelability state. +.LP +.LP +Thus, only the default cancelability state need be considered. As +specified, either the \fIpthread_join\fP() call is canceled, +or it succeeds, but not both. The difference is obvious to the application, +since either a cancellation handler is run or +\fIpthread_join\fP() returns. There are no race conditions since \fIpthread_join\fP() +was called in the deferred cancelability +state. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_create\fP() , \fIwait\fP() , the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_key_create.3p b/man3p/pthread_key_create.3p new file mode 100644 index 000000000..3da43c967 --- /dev/null +++ b/man3p/pthread_key_create.3p @@ -0,0 +1,233 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_KEY_CREATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_key_create +.SH NAME +pthread_key_create \- thread-specific data key creation +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_key_create(pthread_key_t *\fP\fIkey\fP\fB, void (*\fP\fIdestructor\fP\fB)(void*)); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_key_create\fP() function shall create a thread-specific +data key visible to all threads in the process. Key +values provided by \fIpthread_key_create\fP() are opaque objects used +to locate thread-specific data. Although the same key value +may be used by different threads, the values bound to the key by \fIpthread_setspecific\fP() +are maintained on a per-thread basis and persist for the +life of the calling thread. +.LP +Upon key creation, the value NULL shall be associated with the new +key in all active threads. Upon thread creation, the value +NULL shall be associated with all defined keys in the new thread. +.LP +An optional destructor function may be associated with each key value. +At thread exit, if a key value has a non-NULL destructor +pointer, and the thread has a non-NULL value associated with that +key, the value of the key is set to NULL, and then the function +pointed to is called with the previously associated value as its sole +argument. The order of destructor calls is unspecified if +more than one destructor exists for a thread when it exits. +.LP +If, after all the destructors have been called for all non-NULL values +with associated destructors, there are still some +non-NULL values with associated destructors, then the process is repeated. +If, after at least {PTHREAD_DESTRUCTOR_ITERATIONS} +iterations of destructor calls for outstanding non-NULL values, there +are still some non-NULL values with associated destructors, +implementations may stop calling destructors, or they may continue +calling destructors until no non-NULL values with associated +destructors exist, even though this might result in an infinite loop. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_key_create\fP() function shall store +the newly created key value at *\fIkey\fP and shall return +zero. Otherwise, an error number shall be returned to indicate the +error. +.SH ERRORS +.LP +The \fIpthread_key_create\fP() function shall fail if: +.TP 7 +.B EAGAIN +The system lacked the necessary resources to create another thread-specific +data key, or the system-imposed limit on the total +number of keys per process {PTHREAD_KEYS_MAX} has been exceeded. +.TP 7 +.B ENOMEM +Insufficient memory exists to create the key. +.sp +.LP +The \fIpthread_key_create\fP() function shall not return an error +code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The following example demonstrates a function that initializes a thread-specific +data key when it is first called, and +associates a thread-specific object with each calling thread, initializing +this object when necessary. +.sp +.RS +.nf + +\fBstatic pthread_key_t key; +static pthread_once_t key_once = PTHREAD_ONCE_INIT; +.sp + +static void +make_key() +{ + (void) pthread_key_create(&key, NULL); +} +.sp + +func() +{ + void *ptr; +.sp + + (void) pthread_once(&key_once, make_key); + if ((ptr = pthread_getspecific(key)) == NULL) { + ptr = malloc(OBJECT_SIZE); + ... + (void) pthread_setspecific(key, ptr); + } + ... +} +\fP +.fi +.RE +.LP +Note that the key has to be initialized before \fIpthread_getspecific\fP() +or \fIpthread_setspecific\fP() can be used. The \fIpthread_key_create\fP() +call could either be explicitly made in a module initialization routine, +or it can be done implicitly by the first call to a module +as in this example. Any attempt to use the key before it is initialized +is a programming error, making the code below +incorrect. +.sp +.RS +.nf + +\fBstatic pthread_key_t key; +.sp + +func() +{ + void *ptr; +.sp + + /* KEY NOT INITIALIZED!!! THIS WON'T WORK!!! */ + if ((ptr = pthread_getspecific(key)) == NULL && + pthread_setspecific(key, NULL) != 0) { + pthread_key_create(&key, NULL); + ... + } +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.br +.SH RATIONALE +.LP +.SS Destructor Functions +.LP +Normally, the value bound to a key on behalf of a particular thread +is a pointer to storage allocated dynamically on behalf of +the calling thread. The destructor functions specified with \fIpthread_key_create\fP() +are intended to be used to free this +storage when the thread exits. Thread cancellation cleanup handlers +cannot be used for this purpose because thread-specific data +may persist outside the lexical scope in which the cancellation cleanup +handlers operate. +.LP +If the value associated with a key needs to be updated during the +lifetime of the thread, it may be necessary to release the +storage associated with the old value before the new value is bound. +Although the \fIpthread_setspecific\fP() function could do this automatically, +this feature is not +needed often enough to justify the added complexity. Instead, the +programmer is responsible for freeing the stale storage: +.sp +.RS +.nf + +\fBpthread_getspecific(key, &old); +new = allocate(); +destructor(old); +pthread_setspecific(key, new); +\fP +.fi +.RE +.TP 7 +\fBNote:\fP +The above example could leak storage if run with asynchronous cancellation +enabled. No such problems occur in the default +cancellation state if no cancellation points occur between the get +and set. +.sp +.LP +There is no notion of a destructor-safe function. If an application +does not call \fIpthread_exit\fP() from a signal handler, or if it +blocks any signal whose handler may call +\fIpthread_exit\fP() while calling async-unsafe functions, all functions +may be +safely called from destructors. +.SS Non-Idempotent Data Key Creation +.LP +There were requests to make \fIpthread_key_create\fP() idempotent +with respect to a given \fIkey\fP address parameter. This +would allow applications to call \fIpthread_key_create\fP() multiple +times for a given \fIkey\fP address and be guaranteed that +only one key would be created. Doing so would require the key value +to be previously initialized (possibly at compile time) to a +known null value and would require that implicit mutual-exclusion +be performed based on the address and contents of the \fIkey\fP +parameter in order to guarantee that exactly one key would be created. +.LP +Unfortunately, the implicit mutual-exclusion would not be limited +to only \fIpthread_key_create\fP(). On many implementations, +implicit mutual-exclusion would also have to be performed by \fIpthread_getspecific\fP() +and \fIpthread_setspecific\fP() in order to guard against using incompletely +stored or +not-yet-visible key values. This could significantly increase the +cost of important operations, particularly \fIpthread_getspecific\fP(). +.LP +Thus, this proposal was rejected. The \fIpthread_key_create\fP() function +performs no implicit synchronization. It is the +responsibility of the programmer to ensure that it is called exactly +once per key before use of the key. Several straightforward +mechanisms can already be used to accomplish this, including calling +explicit module initialization functions, using mutexes, and +using \fIpthread_once\fP(). This places no significant burden on the +programmer, +introduces no possibly confusing \fIad hoc\fP implicit synchronization +mechanism, and potentially allows commonly used +thread-specific data operations to be more efficient. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_getspecific\fP() , \fIpthread_key_delete\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_key_delete.3p b/man3p/pthread_key_delete.3p new file mode 100644 index 000000000..3a07dab8a --- /dev/null +++ b/man3p/pthread_key_delete.3p @@ -0,0 +1,117 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_KEY_DELETE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_key_delete +.SH NAME +pthread_key_delete \- thread-specific data key deletion +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_key_delete(pthread_key_t\fP \fIkey\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_key_delete\fP() function shall delete a thread-specific +data key previously returned by \fIpthread_key_create\fP(). The thread-specific +data values associated with \fIkey\fP +need not be NULL at the time \fIpthread_key_delete\fP() is called. +It is the responsibility of the application to free any +application storage or perform any cleanup actions for data structures +related to the deleted key or associated thread-specific +data in any threads; this cleanup can be done either before or after +\fIpthread_key_delete\fP() is called. Any attempt to use +\fIkey\fP following the call to \fIpthread_key_delete\fP() results +in undefined behavior. +.LP +The \fIpthread_key_delete\fP() function shall be callable from within +destructor functions. No destructor functions shall be +invoked by \fIpthread_key_delete\fP(). Any destructor function that +may have been associated with \fIkey\fP shall no longer be +called upon thread exit. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_key_delete\fP() function shall return +zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +.LP +The \fIpthread_key_delete\fP() function may fail if: +.TP 7 +.B EINVAL +The \fIkey\fP value is invalid. +.sp +.LP +The \fIpthread_key_delete\fP() function shall not return an error +code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +A thread-specific data key deletion function has been included in +order to allow the resources associated with an unused +thread-specific data key to be freed. Unused thread-specific data +keys can arise, among other scenarios, when a dynamically loaded +module that allocated a key is unloaded. +.LP +Conforming applications are responsible for performing any cleanup +actions needed for data structures associated with the key to +be deleted, including data referenced by thread-specific data values. +No such cleanup is done by \fIpthread_key_delete\fP(). In +particular, destructor functions are not called. There are several +reasons for this division of responsibility: +.IP " 1." 4 +The associated destructor functions used to free thread-specific data +at thread exit time are only guaranteed to work correctly +when called in the thread that allocated the thread-specific data. +(Destructors themselves may utilize thread-specific data.) Thus, +they cannot be used to free thread-specific data in other threads +at key deletion time. Attempting to have them called by other +threads at key deletion time would require other threads to be asynchronously +interrupted. But since interrupted threads could be +in an arbitrary state, including holding locks necessary for the destructor +to run, this approach would fail. In general, there is +no safe mechanism whereby an implementation could free thread-specific +data at key deletion time. +.LP +.IP " 2." 4 +Even if there were a means of safely freeing thread-specific data +associated with keys to be deleted, doing so would require +that implementations be able to enumerate the threads with non-NULL +data and potentially keep them from creating more +thread-specific data while the key deletion is occurring. This special +case could cause extra synchronization in the normal case, +which would otherwise be unnecessary. +.LP +.LP +For an application to know that it is safe to delete a key, it has +to know that all the threads that might potentially ever use +the key do not attempt to use it again. For example, it could know +this if all the client threads have called a cleanup procedure +declaring that they are through with the module that is being shut +down, perhaps by setting a reference count to zero. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_key_create\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_kill.3p b/man3p/pthread_kill.3p new file mode 100644 index 000000000..aee080c28 --- /dev/null +++ b/man3p/pthread_kill.3p @@ -0,0 +1,78 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_KILL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_kill +.SH NAME +pthread_kill \- send a signal to a thread +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_kill(pthread_t\fP \fIthread\fP\fB, int\fP \fIsig\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_kill\fP() function shall request that a signal be delivered +to the specified thread. +.LP +As in \fIkill\fP(), if \fIsig\fP is zero, error checking shall be +performed but no signal +shall actually be sent. +.SH RETURN VALUE +.LP +Upon successful completion, the function shall return a value of zero. +Otherwise, the function shall return an error number. If +the \fIpthread_kill\fP() function fails, no signal shall be sent. +.SH ERRORS +.LP +The \fIpthread_kill\fP() function shall fail if: +.TP 7 +.B ESRCH +No thread could be found corresponding to that specified by the given +thread ID. +.TP 7 +.B EINVAL +The value of the \fIsig\fP argument is an invalid or unsupported signal +number. +.sp +.LP +The \fIpthread_kill\fP() function shall not return an error code of +[EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIpthread_kill\fP() function provides a mechanism for asynchronously +directing a signal at a thread in the calling +process. This could be used, for example, by one thread to affect +broadcast delivery of a signal to a set of threads. +.LP +Note that \fIpthread_kill\fP() only causes the signal to be handled +in the context of the given thread; the signal action +(termination or stopping) affects the process as a whole. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIkill\fP() , \fIpthread_self\fP() , \fIraise\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_mutex_destroy.3p b/man3p/pthread_mutex_destroy.3p new file mode 100644 index 000000000..c6ceacfc1 --- /dev/null +++ b/man3p/pthread_mutex_destroy.3p @@ -0,0 +1 @@ +.so man3p/pthread_mutex_init.3p diff --git a/man3p/pthread_mutex_getprioceiling.3p b/man3p/pthread_mutex_getprioceiling.3p new file mode 100644 index 000000000..3baa67115 --- /dev/null +++ b/man3p/pthread_mutex_getprioceiling.3p @@ -0,0 +1,90 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_MUTEX_GETPRIOCEILING" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_mutex_getprioceiling +.SH NAME +pthread_mutex_getprioceiling, pthread_mutex_setprioceiling \- get and +set the priority ceiling of a mutex (\fBREALTIME +THREADS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_mutex_getprioceiling(const pthread_mutex_t *restrict\fP +\fImutex\fP\fB, +.br +\ \ \ \ \ \ int *restrict\fP \fIprioceiling\fP\fB); +.br +int pthread_mutex_setprioceiling(pthread_mutex_t *restrict\fP \fImutex\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIprioceiling\fP\fB, int *restrict\fP \fIold_ceiling\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_mutex_getprioceiling\fP() function shall return the +current priority ceiling of the mutex. +.LP +The \fIpthread_mutex_setprioceiling\fP() function shall either lock +the mutex if it is unlocked, or block until it can +successfully lock the mutex, then it shall change the mutex's priority +ceiling and release the mutex. When the change is +successful, the previous value of the priority ceiling shall be returned +in \fIold_ceiling\fP. The process of locking the mutex +need not adhere to the priority protect protocol. +.LP +If the \fIpthread_mutex_setprioceiling\fP() function fails, the mutex +priority ceiling shall not be changed. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_mutex_getprioceiling\fP() and \fIpthread_mutex_setprioceiling\fP() +functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_mutex_getprioceiling\fP() and \fIpthread_mutex_setprioceiling\fP() +functions may fail if: +.TP 7 +.B EINVAL +The priority requested by \fIprioceiling\fP is out of range. +.TP 7 +.B EINVAL +The value specified by \fImutex\fP does not refer to a currently existing +mutex. +.TP 7 +.B EPERM +The caller does not have the privilege to perform the operation. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_mutex_destroy\fP() , \fIpthread_mutex_lock\fP() , \fIpthread_mutex_timedlock\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_mutex_init.3p b/man3p/pthread_mutex_init.3p new file mode 100644 index 000000000..f538d727b --- /dev/null +++ b/man3p/pthread_mutex_init.3p @@ -0,0 +1,363 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_MUTEX_DESTROY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_mutex_destroy +.SH NAME +pthread_mutex_destroy, pthread_mutex_init \- destroy and initialize +a mutex +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_mutex_destroy(pthread_mutex_t *\fP\fImutex\fP\fB); +.br +int pthread_mutex_init(pthread_mutex_t *restrict\fP \fImutex\fP\fB, +.br +\ \ \ \ \ \ const pthread_mutexattr_t *restrict\fP \fIattr\fP\fB); +.br +pthread_mutex_t\fP \fImutex\fP \fB= PTHREAD_MUTEX_INITIALIZER; \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_mutex_destroy\fP() function shall destroy the mutex +object referenced by \fImutex\fP; the mutex object becomes, +in effect, uninitialized. An implementation may cause \fIpthread_mutex_destroy\fP() +to set the object referenced by \fImutex\fP +to an invalid value. A destroyed mutex object can be reinitialized +using \fIpthread_mutex_init\fP(); the results of otherwise +referencing the object after it has been destroyed are undefined. +.LP +It shall be safe to destroy an initialized mutex that is unlocked. +Attempting to destroy a locked mutex results in undefined +behavior. +.LP +The \fIpthread_mutex_init\fP() function shall initialize the mutex +referenced by \fImutex\fP with attributes specified by +\fIattr\fP. If \fIattr\fP is NULL, the default mutex attributes are +used; the effect shall be the same as passing the address of +a default mutex attributes object. Upon successful initialization, +the state of the mutex becomes initialized and unlocked. +.LP +Only \fImutex\fP itself may be used for performing synchronization. +The result of referring to copies of \fImutex\fP in calls +to \fIpthread_mutex_lock\fP(), \fIpthread_mutex_trylock\fP(), \fIpthread_mutex_unlock\fP(), +and \fIpthread_mutex_destroy\fP() is undefined. +.LP +Attempting to initialize an already initialized mutex results in undefined +behavior. +.LP +In cases where default mutex attributes are appropriate, the macro +PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexes +that are statically allocated. The effect shall be equivalent to dynamic +initialization by a call to \fIpthread_mutex_init\fP() +with parameter \fIattr\fP specified as NULL, except that no error +checks are performed. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_mutex_destroy\fP() and \fIpthread_mutex_init\fP() +functions shall return zero; otherwise, an +error number shall be returned to indicate the error. +.LP +The [EBUSY] and [EINVAL] error checks, if implemented, act as if they +were performed immediately at the beginning of processing +for the function and shall cause an error return prior to modifying +the state of the mutex specified by \fImutex\fP. +.SH ERRORS +.LP +The \fIpthread_mutex_destroy\fP() function may fail if: +.TP 7 +.B EBUSY +The implementation has detected an attempt to destroy the object referenced +by \fImutex\fP while it is locked or referenced +(for example, while being used in a \fIpthread_cond_timedwait\fP() +or \fIpthread_cond_wait\fP()) by another thread. +.TP 7 +.B EINVAL +The value specified by \fImutex\fP is invalid. +.sp +.LP +The \fIpthread_mutex_init\fP() function shall fail if: +.TP 7 +.B EAGAIN +The system lacked the necessary resources (other than memory) to initialize +another mutex. +.TP 7 +.B ENOMEM +Insufficient memory exists to initialize the mutex. +.TP 7 +.B EPERM +The caller does not have the privilege to perform the operation. +.sp +.LP +The \fIpthread_mutex_init\fP() function may fail if: +.TP 7 +.B EBUSY +The implementation has detected an attempt to reinitialize the object +referenced by \fImutex\fP, a previously initialized, but +not yet destroyed, mutex. +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.SS Alternate Implementations Possible +.LP +This volume of IEEE\ Std\ 1003.1-2001 supports several alternative +implementations of mutexes. An implementation may +store the lock directly in the object of type \fBpthread_mutex_t\fP. +Alternatively, an implementation may store the lock in the +heap and merely store a pointer, handle, or unique ID in the mutex +object. Either implementation has advantages or may be required +on certain hardware configurations. So that portable code can be written +that is invariant to this choice, this volume of +IEEE\ Std\ 1003.1-2001 does not define assignment or equality for +this type, and it uses the term "initialize" to +reinforce the (more restrictive) notion that the lock may actually +reside in the mutex object itself. +.LP +Note that this precludes an over-specification of the type of the +mutex or condition variable and motivates the opaqueness of +the type. +.LP +An implementation is permitted, but not required, to have \fIpthread_mutex_destroy\fP() +store an illegal value into the mutex. +This may help detect erroneous programs that try to lock (or otherwise +reference) a mutex that has already been destroyed. +.SS Tradeoff Between Error Checks and Performance Supported +.LP +Many of the error checks were made optional in order to let implementations +trade off performance \fIversus\fP degree of error +checking according to the needs of their specific applications and +execution environment. As a general rule, errors or conditions +caused by the system (such as insufficient memory) always need to +be reported, but errors due to an erroneously coded application +(such as failing to provide adequate synchronization to prevent a +mutex from being deleted while in use) are made optional. +.LP +A wide range of implementations is thus made possible. For example, +an implementation intended for application debugging may +implement all of the error checks, but an implementation running a +single, provably correct application under very tight +performance constraints in an embedded computer might implement minimal +checks. An implementation might even be provided in two +versions, similar to the options that compilers provide: a full-checking, +but slower version; and a limited-checking, but faster +version. To forbid this optionality would be a disservice to users. +.LP +By carefully limiting the use of "undefined behavior" only to things +that an erroneous (badly coded) application might do, and +by defining that resource-not-available errors are mandatory, this +volume of IEEE\ Std\ 1003.1-2001 ensures that a +fully-conforming application is portable across the full range of +implementations, while not forcing all implementations to add +overhead to check for numerous things that a correct program never +does. +.SS Why No Limits are Defined +.LP +Defining symbols for the maximum number of mutexes and condition variables +was considered but rejected because the number of +these objects may change dynamically. Furthermore, many implementations +place these objects into application memory; thus, there is +no explicit maximum. +.SS Static Initializers for Mutexes and Condition Variables +.LP +Providing for static initialization of statically allocated synchronization +objects allows modules with private static +synchronization variables to avoid runtime initialization tests and +overhead. Furthermore, it simplifies the coding of +self-initializing modules. Such modules are common in C libraries, +where for various reasons the design calls for +self-initialization instead of requiring an explicit module initialization +function to be called. An example use of static +initialization follows. +.LP +Without static initialization, a self-initializing routine \fIfoo\fP() +might look as follows: +.sp +.RS +.nf + +\fBstatic pthread_once_t foo_once = PTHREAD_ONCE_INIT; +static pthread_mutex_t foo_mutex; +.sp + +void foo_init() +{ + pthread_mutex_init(&foo_mutex, NULL); +} +.sp + +void foo() +{ + pthread_once(&foo_once, foo_init); + pthread_mutex_lock(&foo_mutex); + /* Do work. */ + pthread_mutex_unlock(&foo_mutex); +} +\fP +.fi +.RE +.LP +With static initialization, the same routine could be coded as follows: +.sp +.RS +.nf + +\fBstatic pthread_mutex_t foo_mutex = PTHREAD_MUTEX_INITIALIZER; +.sp + +void foo() +{ + pthread_mutex_lock(&foo_mutex); + /* Do work. */ + pthread_mutex_unlock(&foo_mutex); +} +\fP +.fi +.RE +.LP +Note that the static initialization both eliminates the need for the +initialization test inside \fIpthread_once\fP() and the fetch of &\fIfoo_mutex\fP +to learn the address to be passed +to \fIpthread_mutex_lock\fP() or \fIpthread_mutex_unlock\fP(). +.LP +Thus, the C code written to initialize static objects is simpler on +all systems and is also faster on a large class of systems; +those where the (entire) synchronization object can be stored in application +memory. +.LP +Yet the locking performance question is likely to be raised for machines +that require mutexes to be allocated out of special +memory. Such machines actually have to have mutexes and possibly condition +variables contain pointers to the actual hardware locks. +For static initialization to work on such machines, \fIpthread_mutex_lock\fP() +also has to test whether or not the pointer to the actual lock has +been allocated. If it has not, \fIpthread_mutex_lock\fP() has to initialize +it before use. The reservation of such +resources can be made when the program is loaded, and hence return +codes have not been added to mutex locking and condition +variable waiting to indicate failure to complete initialization. +.LP +This runtime test in \fIpthread_mutex_lock\fP() would at first seem +to be +extra work; an extra test is required to see whether the pointer has +been initialized. On most machines this would actually be +implemented as a fetch of the pointer, testing the pointer against +zero, and then using the pointer if it has already been +initialized. While the test might seem to add extra work, the extra +effort of testing a register is usually negligible since no +extra memory references are actually done. As more and more machines +provide caches, the real expenses are memory references, not +instructions executed. +.LP +Alternatively, depending on the machine architecture, there are often +ways to eliminate \fIall\fP overhead in the most +important case: on the lock operations that occur \fIafter\fP the +lock has been initialized. This can be done by shifting more +overhead to the less frequent operation: initialization. Since out-of-line +mutex allocation also means that an address has to be +dereferenced to find the actual lock, one technique that is widely +applicable is to have static initialization store a bogus value +for that address; in particular, an address that causes a machine +fault to occur. When such a fault occurs upon the first attempt +to lock such a mutex, validity checks can be done, and then the correct +address for the actual lock can be filled in. Subsequent +lock operations incur no extra overhead since they do not "fault". +This is merely one technique that can be used to support +static initialization, while not adversely affecting the performance +of lock acquisition. No doubt there are other techniques that +are highly machine-dependent. +.LP +The locking overhead for machines doing out-of-line mutex allocation +is thus similar for modules being implicitly initialized, +where it is improved for those doing mutex allocation entirely inline. +The inline case is thus made much faster, and the +out-of-line case is not significantly worse. +.LP +Besides the issue of locking performance for such machines, a concern +is raised that it is possible that threads would serialize +contending for initialization locks when attempting to finish initializing +statically allocated mutexes. (Such finishing would +typically involve taking an internal lock, allocating a structure, +storing a pointer to the structure in the mutex, and releasing +the internal lock.) First, many implementations would reduce such +serialization by hashing on the mutex address. Second, such +serialization can only occur a bounded number of times. In particular, +it can happen at most as many times as there are statically +allocated synchronization objects. Dynamically allocated objects would +still be initialized via \fIpthread_mutex_init\fP() or \fIpthread_cond_init\fP(). +.LP +Finally, if none of the above optimization techniques for out-of-line +allocation yields sufficient performance for an +application on some implementation, the application can avoid static +initialization altogether by explicitly initializing all +synchronization objects with the corresponding \fIpthread_*_init\fP() +functions, +which are supported by all implementations. An implementation can +also document the tradeoffs and advise which initialization +technique is more efficient for that particular implementation. +.SS Destroying Mutexes +.LP +A mutex can be destroyed immediately after it is unlocked. For example, +consider the following code: +.sp +.RS +.nf + +\fBstruct obj { +pthread_mutex_t om; + int refcnt; + ... +}; +.sp + +obj_done(struct obj *op) +{ + pthread_mutex_lock(&op->om); + if (--op->refcnt == 0) { + pthread_mutex_unlock(&op->om); +(A) pthread_mutex_destroy(&op->om); +(B) free(op); + } else +(C) pthread_mutex_unlock(&op->om); +} +\fP +.fi +.RE +.LP +In this case \fIobj\fP is reference counted and \fIobj_done\fP() is +called whenever a reference to the object is dropped. +Implementations are required to allow an object to be destroyed and +freed and potentially unmapped (for example, lines A and B) +immediately after the object is unlocked (line C). +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_mutex_getprioceiling\fP() , \fIpthread_mutex_lock\fP() +, \fIpthread_mutex_timedlock\fP() , \fIpthread_mutexattr_getpshared\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_mutex_lock.3p b/man3p/pthread_mutex_lock.3p new file mode 100644 index 000000000..d05a8907c --- /dev/null +++ b/man3p/pthread_mutex_lock.3p @@ -0,0 +1,189 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_MUTEX_LOCK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_mutex_lock +.SH NAME +pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock \- +lock and unlock a mutex +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_mutex_lock(pthread_mutex_t *\fP\fImutex\fP\fB); +.br +int pthread_mutex_trylock(pthread_mutex_t *\fP\fImutex\fP\fB); +.br +int pthread_mutex_unlock(pthread_mutex_t *\fP\fImutex\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The mutex object referenced by \fImutex\fP shall be locked by calling +\fIpthread_mutex_lock\fP(). If the mutex is already +locked, the calling thread shall block until the mutex becomes available. +This operation shall return with the mutex object +referenced by \fImutex\fP in the locked state with the calling thread +as its owner. +.LP +If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection shall +not be provided. Attempting to relock the mutex causes +deadlock. If a thread attempts to unlock a mutex that it has not locked +or a mutex which is unlocked, undefined behavior +results. +.LP +If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking +shall be provided. If a thread attempts to relock a mutex +that it has already locked, an error shall be returned. If a thread +attempts to unlock a mutex that it has not locked or a mutex +which is unlocked, an error shall be returned. +.LP +If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex shall +maintain the concept of a lock count. When a thread +successfully acquires a mutex for the first time, the lock count shall +be set to one. Every time a thread relocks this mutex, the +lock count shall be incremented by one. Each time the thread unlocks +the mutex, the lock count shall be decremented by one. When +the lock count reaches zero, the mutex shall become available for +other threads to acquire. If a thread attempts to unlock a mutex +that it has not locked or a mutex which is unlocked, an error shall +be returned. +.LP +If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively +lock the mutex results in undefined behavior. Attempting +to unlock the mutex if it was not locked by the calling thread results +in undefined behavior. Attempting to unlock the mutex if it +is not locked results in undefined behavior. +.LP +The \fIpthread_mutex_trylock\fP() function shall be equivalent to +\fIpthread_mutex_lock\fP(), except that if the mutex object +referenced by \fImutex\fP is currently locked (by any thread, including +the current thread), the call shall return immediately. If +the mutex type is PTHREAD_MUTEX_RECURSIVE and the mutex is currently +owned by the calling thread, the mutex lock count shall be +incremented by one and the \fIpthread_mutex_trylock\fP() function +shall immediately return success. +.LP +The \fIpthread_mutex_unlock\fP() function shall release the mutex +object referenced by \fImutex\fP. \ The manner +in which a mutex is released is dependent upon the mutex's type attribute. +If there are threads blocked on the mutex object referenced by \fImutex\fP +when \fIpthread_mutex_unlock\fP() is +called, resulting in the mutex becoming available, the scheduling +policy shall determine which thread shall acquire the mutex. +.LP +(In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex shall become +available when the count reaches zero and the calling +thread no longer has any locks on this mutex.) +.LP +If a signal is delivered to a thread waiting for a mutex, upon return +from the signal handler the thread shall resume waiting +for the mutex as if it was not interrupted. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_mutex_lock\fP() and \fIpthread_mutex_unlock\fP() +functions shall return zero; otherwise, an +error number shall be returned to indicate the error. +.LP +The \fIpthread_mutex_trylock\fP() function shall return zero if a +lock on the mutex object referenced by \fImutex\fP is +acquired. Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_mutex_lock\fP() and \fIpthread_mutex_trylock\fP() functions +shall fail if: +.TP 7 +.B EINVAL +The \fImutex\fP was created with the protocol attribute having the +value PTHREAD_PRIO_PROTECT and the calling thread's +priority is higher than the mutex's current priority ceiling. +.sp +.LP +The \fIpthread_mutex_trylock\fP() function shall fail if: +.TP 7 +.B EBUSY +The \fImutex\fP could not be acquired because it was already locked. +.sp +.LP +The \fIpthread_mutex_lock\fP(), \fIpthread_mutex_trylock\fP(), and +\fIpthread_mutex_unlock\fP() functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fImutex\fP does not refer to an initialized +mutex object. +.TP 7 +.B EAGAIN +The mutex could not be acquired because the maximum number of recursive +locks for \fImutex\fP has been exceeded. +.sp +.LP +The \fIpthread_mutex_lock\fP() function may fail if: +.TP 7 +.B EDEADLK +The current thread already owns the mutex. +.sp +.LP +The \fIpthread_mutex_unlock\fP() function may fail if: +.TP 7 +.B EPERM +The current thread does not own the mutex. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Mutex objects are intended to serve as a low-level primitive from +which other thread synchronization functions can be built. As +such, the implementation of mutexes should be as efficient as possible, +and this has ramifications on the features available at the +interface. +.LP +The mutex functions and the particular default settings of the mutex +attributes have been motivated by the desire to not +preclude fast, inlined implementations of mutex locking and unlocking. +.LP +For example, deadlocking on a double-lock is explicitly allowed behavior +in order to avoid requiring more overhead in the basic +mechanism than is absolutely necessary. (More "friendly" mutexes that +detect deadlock or that allow multiple locking by the same +thread are easily constructed by the user via the other mechanisms +provided. For example, \fIpthread_self\fP() can be used to record +mutex ownership.) Implementations might also +choose to provide such extended features as options via special mutex +attributes. +.LP +Since most attributes only need to be checked when a thread is going +to be blocked, the use of attributes does not slow the +(common) mutex-locking case. +.LP +Likewise, while being able to extract the thread ID of the owner of +a mutex might be desirable, it would require storing the +current thread ID when each mutex is locked, and this could incur +unacceptable levels of overhead. Similar arguments apply to a +\fImutex_tryunlock\fP operation. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_mutex_destroy\fP() , \fIpthread_mutex_timedlock\fP() , +the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_mutex_setprioceiling.3p b/man3p/pthread_mutex_setprioceiling.3p new file mode 100644 index 000000000..ea30e6787 --- /dev/null +++ b/man3p/pthread_mutex_setprioceiling.3p @@ -0,0 +1 @@ +.so man3p/pthread_mutex_getprioceiling.3p diff --git a/man3p/pthread_mutex_timedlock.3p b/man3p/pthread_mutex_timedlock.3p new file mode 100644 index 000000000..efd024c1d --- /dev/null +++ b/man3p/pthread_mutex_timedlock.3p @@ -0,0 +1,124 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_MUTEX_TIMEDLOCK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_mutex_timedlock +.SH NAME +pthread_mutex_timedlock \- lock a mutex (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int pthread_mutex_timedlock(pthread_mutex_t *restrict\fP \fImutex\fP\fB, +.br +\ \ \ \ \ \ const struct timespec *restrict\fP \fIabs_timeout\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_mutex_timedlock\fP() function shall lock the mutex +object referenced by \fImutex\fP. If the mutex is already +locked, the calling thread shall block until the mutex becomes available +as in the \fIpthread_mutex_lock\fP() function. If the mutex cannot +be locked without waiting for +another thread to unlock the mutex, this wait shall be terminated +when the specified timeout expires. +.LP +The timeout shall expire when the absolute time specified by \fIabs_timeout\fP +passes, as measured by the clock on which +timeouts are based (that is, when the value of that clock equals or +exceeds \fIabs_timeout\fP), or if the absolute time specified +by \fIabs_timeout\fP has already been passed at the time of the call. +.LP +If the Timers option is supported, the timeout shall be based on the +CLOCK_REALTIME clock; if the Timers option is not supported, +the timeout shall be based on the system clock as returned by the +\fItime\fP() function. +.LP +The resolution of the timeout shall be the resolution of the clock +on which it is based. The \fBtimespec\fP data type is +defined in the \fI\fP header. +.LP +Under no circumstance shall the function fail with a timeout if the +mutex can be locked immediately. The validity of the +\fIabs_timeout\fP parameter need not be checked if the mutex can be +locked immediately. +.LP +As a consequence of the priority inheritance rules (for mutexes initialized +with the PRIO_INHERIT protocol), if a timed mutex +wait is terminated because its timeout expires, the priority of the +owner of the mutex shall be adjusted as necessary to reflect +the fact that this thread is no longer among the threads waiting for +the mutex. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_mutex_timedlock\fP() function shall +return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +.LP +The \fIpthread_mutex_timedlock\fP() function shall fail if: +.TP 7 +.B EINVAL +The mutex was created with the protocol attribute having the value +PTHREAD_PRIO_PROTECT and the calling thread's priority is +higher than the mutex' current priority ceiling. +.TP 7 +.B EINVAL +The process or thread would have blocked, and the \fIabs_timeout\fP +parameter specified a nanoseconds field value less than +zero or greater than or equal to 1000 million. +.TP 7 +.B ETIMEDOUT +The mutex could not be locked before the specified timeout expired. +.sp +.LP +The \fIpthread_mutex_timedlock\fP() function may fail if: +.TP 7 +.B EINVAL +The value specified by \fImutex\fP does not refer to an initialized +mutex object. +.TP 7 +.B EAGAIN +The mutex could not be acquired because the maximum number of recursive +locks for \fImutex\fP has been exceeded. +.TP 7 +.B EDEADLK +The current thread already owns the mutex. +.sp +.LP +This function shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIpthread_mutex_timedlock\fP() function is part of the Threads +and Timeouts options and need not be provided on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_mutex_destroy\fP() , \fIpthread_mutex_lock\fP() , \fIpthread_mutex_trylock\fP() +, \fItime\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_mutex_trylock.3p b/man3p/pthread_mutex_trylock.3p new file mode 100644 index 000000000..342eaefb0 --- /dev/null +++ b/man3p/pthread_mutex_trylock.3p @@ -0,0 +1 @@ +.so man3p/pthread_mutex_lock.3p diff --git a/man3p/pthread_mutex_unlock.3p b/man3p/pthread_mutex_unlock.3p new file mode 100644 index 000000000..342eaefb0 --- /dev/null +++ b/man3p/pthread_mutex_unlock.3p @@ -0,0 +1 @@ +.so man3p/pthread_mutex_lock.3p diff --git a/man3p/pthread_mutexattr_destroy.3p b/man3p/pthread_mutexattr_destroy.3p new file mode 100644 index 000000000..5ec6502a4 --- /dev/null +++ b/man3p/pthread_mutexattr_destroy.3p @@ -0,0 +1 @@ +.so man3p/pthread_mutexattr_init.3p diff --git a/man3p/pthread_mutexattr_getprioceiling.3p b/man3p/pthread_mutexattr_getprioceiling.3p new file mode 100644 index 000000000..a71c361d4 --- /dev/null +++ b/man3p/pthread_mutexattr_getprioceiling.3p @@ -0,0 +1,90 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_MUTEXATTR_GETPRIOCEILING" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_mutexattr_getprioceiling +.SH NAME +pthread_mutexattr_getprioceiling, pthread_mutexattr_setprioceiling +\- get and set the prioceiling attribute of the mutex +attributes object (\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t * +.br +\ \ \ \ \ \ restrict\fP \fIattr\fP\fB, int *restrict\fP \fIprioceiling\fP\fB); +.br +int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIprioceiling\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_mutexattr_getprioceiling\fP() and \fIpthread_mutexattr_setprioceiling\fP() +functions, respectively, shall get +and set the priority ceiling attribute of a mutex attributes object +pointed to by \fIattr\fP which was previously created by the +function \fIpthread_mutexattr_init\fP(). +.LP +The \fIprioceiling\fP attribute contains the priority ceiling of initialized +mutexes. The values of \fIprioceiling\fP are +within the maximum range of priorities defined by SCHED_FIFO. +.LP +The \fIprioceiling\fP attribute defines the priority ceiling of initialized +mutexes, which is the minimum priority level at +which the critical section guarded by the mutex is executed. In order +to avoid priority inversion, the priority ceiling of the +mutex shall be set to a priority higher than or equal to the highest +priority of all the threads that may lock that mutex. The +values of \fIprioceiling\fP are within the maximum range of priorities +defined under the SCHED_FIFO scheduling policy. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIpthread_mutexattr_getprioceiling\fP() +and \fIpthread_mutexattr_setprioceiling\fP() +functions shall return zero; otherwise, an error number shall be returned +to indicate the error. +.SH ERRORS +.LP +The \fIpthread_mutexattr_getprioceiling\fP() and \fIpthread_mutexattr_setprioceiling\fP() +functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP or \fIprioceiling\fP is invalid. +.TP 7 +.B EPERM +The caller does not have the privilege to perform the operation. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_cond_destroy\fP() , \fIpthread_create\fP() , \fIpthread_mutex_destroy\fP() +, the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_mutexattr_getprotocol.3p b/man3p/pthread_mutexattr_getprotocol.3p new file mode 100644 index 000000000..c4bf67251 --- /dev/null +++ b/man3p/pthread_mutexattr_getprotocol.3p @@ -0,0 +1,147 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_MUTEXATTR_GETPROTOCOL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_mutexattr_getprotocol +.SH NAME +pthread_mutexattr_getprotocol, pthread_mutexattr_setprotocol \- get +and set the protocol attribute of the mutex +attributes object (\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +\fBint pthread_mutexattr_getprotocol(const pthread_mutexattr_t * +.br +\ \ \ \ \ \ restrict\fP \fIattr\fP\fB, int *restrict\fP \fIprotocol\fP\fB); +.br +int pthread_mutexattr_setprotocol(pthread_mutexattr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIprotocol\fP\fB); \fP +.sp +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_mutexattr_getprotocol\fP() and \fIpthread_mutexattr_setprotocol\fP() +functions, respectively, shall get and set +the protocol attribute of a mutex attributes object pointed to by +\fIattr\fP which was previously created by the function \fIpthread_mutexattr_init\fP(). +.LP +The \fIprotocol\fP attribute defines the protocol to be followed in +utilizing mutexes. The value of \fIprotocol\fP may be one +of: +.LP +.sp +PTHREAD_PRIO_NONE +.br +.sp +PTHREAD_PRIO_INHERIT +.br +.sp +.sp +PTHREAD_PRIO_PROTECT +.br +.sp +.LP +which are defined in the \fI\fP header. +.LP +When a thread owns a mutex with the PTHREAD_PRIO_NONE \fIprotocol\fP +attribute, its priority and scheduling shall not be +affected by its mutex ownership. +.LP +When a thread is blocking higher priority threads because of owning +one or more mutexes with the PTHREAD_PRIO_INHERIT +\fIprotocol\fP attribute, it shall execute at the higher of its priority +or the priority of the highest priority thread waiting on +any of the mutexes owned by this thread and initialized with this +protocol. +.LP +When a thread owns one or more mutexes initialized with the PTHREAD_PRIO_PROTECT +protocol, it shall execute at the higher of its +priority or the highest of the priority ceilings of all the mutexes +owned by this thread and initialized with this attribute, +regardless of whether other threads are blocked on any of these mutexes +or not. +.LP +While a thread is holding a mutex which has been initialized with +the PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT protocol +attributes, it shall not be subject to being moved to the tail of +the scheduling queue at its priority in the event that its +original priority is changed, such as by a call to \fIsched_setparam\fP(). +Likewise, when a thread unlocks a mutex that has been initialized +with the PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT protocol +attributes, it shall not be subject to being moved to the tail of +the scheduling queue at its priority in the event that its +original priority is changed. +.LP +If a thread simultaneously owns several mutexes initialized with different +protocols, it shall execute at the highest of the +priorities that it would have obtained by each of these protocols. +.LP +When a thread makes a call to \fIpthread_mutex_lock\fP(), the mutex +was +initialized with the protocol attribute having the value PTHREAD_PRIO_INHERIT, +when the calling thread is blocked because the mutex +is owned by another thread, that owner thread shall inherit the priority +level of the calling thread as long as it continues to own +the mutex. The implementation shall update its execution priority +to the maximum of its assigned priority and all its inherited +priorities. Furthermore, if this owner thread itself becomes blocked +on another mutex, the same priority inheritance effect shall +be propagated to this other owner thread, in a recursive manner. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIpthread_mutexattr_getprotocol\fP() +and \fIpthread_mutexattr_setprotocol\fP() functions +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +.LP +The \fIpthread_mutexattr_setprotocol\fP() function shall fail if: +.TP 7 +.B ENOTSUP +The value specified by \fIprotocol\fP is an unsupported value. +.sp +.LP +The \fIpthread_mutexattr_getprotocol\fP() and \fIpthread_mutexattr_setprotocol\fP() +functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP or \fIprotocol\fP is invalid. +.TP 7 +.B EPERM +The caller does not have the privilege to perform the operation. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_cond_destroy\fP() , \fIpthread_create\fP() , \fIpthread_mutex_destroy\fP() +, the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_mutexattr_getpshared.3p b/man3p/pthread_mutexattr_getpshared.3p new file mode 100644 index 000000000..d17b751bb --- /dev/null +++ b/man3p/pthread_mutexattr_getpshared.3p @@ -0,0 +1,97 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_MUTEXATTR_GETPSHARED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_mutexattr_getpshared +.SH NAME +pthread_mutexattr_getpshared, pthread_mutexattr_setpshared \- get and +set the process\-shared attribute +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_mutexattr_getpshared(const pthread_mutexattr_t * +.br +\ \ \ \ \ \ restrict\fP \fIattr\fP\fB, int *restrict\fP \fIpshared\fP\fB); +.br +int pthread_mutexattr_setpshared(pthread_mutexattr_t *\fP\fIattr\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIpshared\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_mutexattr_getpshared\fP() function shall obtain the +value of the \fIprocess-shared\fP attribute from the +attributes object referenced by \fIattr\fP. The \fIpthread_mutexattr_setpshared\fP() +function shall set the \fIprocess-shared\fP +attribute in an initialized attributes object referenced by \fIattr\fP. +.LP +The \fIprocess-shared\fP attribute is set to PTHREAD_PROCESS_SHARED +to permit a mutex to be operated upon by any thread that +has access to the memory where the mutex is allocated, even if the +mutex is allocated in memory that is shared by multiple +processes. If the \fIprocess-shared\fP attribute is PTHREAD_PROCESS_PRIVATE, +the mutex shall only be operated upon by threads +created within the same process as the thread that initialized the +mutex; if threads of differing processes attempt to operate on +such a mutex, the behavior is undefined. The default value of the +attribute shall be PTHREAD_PROCESS_PRIVATE. +.SH RETURN VALUE +.LP +Upon successful completion, \fIpthread_mutexattr_setpshared\fP() shall +return zero; otherwise, an error number shall be +returned to indicate the error. +.LP +Upon successful completion, \fIpthread_mutexattr_getpshared\fP() shall +return zero and store the value of the +\fIprocess-shared\fP attribute of \fIattr\fP into the object referenced +by the \fIpshared\fP parameter. Otherwise, an error +number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_mutexattr_getpshared\fP() and \fIpthread_mutexattr_setpshared\fP() +functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +The \fIpthread_mutexattr_setpshared\fP() function may fail if: +.TP 7 +.B EINVAL +The new value specified for the attribute is outside the range of +legal values for that attribute. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_cond_destroy\fP() , \fIpthread_create\fP() , \fIpthread_mutex_destroy\fP() +, \fIpthread_mutexattr_destroy\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_mutexattr_gettype.3p b/man3p/pthread_mutexattr_gettype.3p new file mode 100644 index 000000000..14f12a178 --- /dev/null +++ b/man3p/pthread_mutexattr_gettype.3p @@ -0,0 +1,129 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_MUTEXATTR_GETTYPE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_mutexattr_gettype +.SH NAME +pthread_mutexattr_gettype, pthread_mutexattr_settype \- get and set +the mutex type attribute +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_mutexattr_gettype(const pthread_mutexattr_t *restrict\fP +\fIattr\fP\fB, +.br +\ \ \ \ \ \ int *restrict\fP \fItype\fP\fB); +.br +int pthread_mutexattr_settype(pthread_mutexattr_t\fP \fI*attr\fP\fB, +int\fP \fItype\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_mutexattr_gettype\fP() and \fIpthread_mutexattr_settype\fP() +functions, respectively, shall get and set the +mutex \fItype\fP attribute. This attribute is set in the \fItype\fP +parameter to these functions. The default value of the +\fItype\fP attribute is PTHREAD_MUTEX_DEFAULT. +.LP +The type of mutex is contained in the \fItype\fP attribute of the +mutex attributes. Valid mutex types include: +.TP 7 +PTHREAD_MUTEX_NORMAL +.sp +This type of mutex does not detect deadlock. A thread attempting to +relock this mutex without first unlocking it shall deadlock. +Attempting to unlock a mutex locked by a different thread results +in undefined behavior. Attempting to unlock an unlocked mutex +results in undefined behavior. +.TP 7 +PTHREAD_MUTEX_ERRORCHECK +.sp +This type of mutex provides error checking. A thread attempting to +relock this mutex without first unlocking it shall return with +an error. A thread attempting to unlock a mutex which another thread +has locked shall return with an error. A thread attempting to +unlock an unlocked mutex shall return with an error. +.TP 7 +PTHREAD_MUTEX_RECURSIVE +.sp +A thread attempting to relock this mutex without first unlocking it +shall succeed in locking the mutex. The relocking deadlock +which can occur with mutexes of type PTHREAD_MUTEX_NORMAL cannot occur +with this type of mutex. Multiple locks of this mutex shall +require the same number of unlocks to release the mutex before another +thread can acquire the mutex. A thread attempting to unlock +a mutex which another thread has locked shall return with an error. +A thread attempting to unlock an unlocked mutex shall return +with an error. +.TP 7 +PTHREAD_MUTEX_DEFAULT +.sp +Attempting to recursively lock a mutex of this type results in undefined +behavior. Attempting to unlock a mutex of this type which +was not locked by the calling thread results in undefined behavior. +Attempting to unlock a mutex of this type which is not locked +results in undefined behavior. An implementation may map this mutex +to one of the other mutex types. +.sp +.SH RETURN VALUE +.LP +Upon successful completion, the \fIpthread_mutexattr_gettype\fP() +function shall return zero and store the value of the +\fItype\fP attribute of \fIattr\fP into the object referenced by the +\fItype\fP parameter. Otherwise, an error shall be returned +to indicate the error. +.LP +If successful, the \fIpthread_mutexattr_settype\fP() function shall +return zero; otherwise, an error number shall be returned +to indicate the error. +.SH ERRORS +.LP +The \fIpthread_mutexattr_settype\fP() function shall fail if: +.TP 7 +.B EINVAL +The value \fItype\fP is invalid. +.sp +.LP +The \fIpthread_mutexattr_gettype\fP() and \fIpthread_mutexattr_settype\fP() +functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +It is advised that an application should not use a PTHREAD_MUTEX_RECURSIVE +mutex with condition variables because the implicit +unlock performed for a \fIpthread_cond_timedwait\fP() or \fIpthread_cond_wait\fP() +may not actually release the mutex (if it had been locked +multiple times). If this happens, no other thread can satisfy the +condition of the predicate. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_cond_timedwait\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_mutexattr_init.3p b/man3p/pthread_mutexattr_init.3p new file mode 100644 index 000000000..02a8b7aaa --- /dev/null +++ b/man3p/pthread_mutexattr_init.3p @@ -0,0 +1,341 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_MUTEXATTR_DESTROY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_mutexattr_destroy +.SH NAME +pthread_mutexattr_destroy, pthread_mutexattr_init \- destroy and initialize +the mutex attributes object +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_mutexattr_destroy(pthread_mutexattr_t *\fP\fIattr\fP\fB); +.br +int pthread_mutexattr_init(pthread_mutexattr_t *\fP\fIattr\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_mutexattr_destroy\fP() function shall destroy a mutex +attributes object; the object becomes, in effect, +uninitialized. An implementation may cause \fIpthread_mutexattr_destroy\fP() +to set the object referenced by \fIattr\fP to an +invalid value. A destroyed \fIattr\fP attributes object can be reinitialized +using \fIpthread_mutexattr_init\fP(); the results of +otherwise referencing the object after it has been destroyed are undefined. +.LP +The \fIpthread_mutexattr_init\fP() function shall initialize a mutex +attributes object \fIattr\fP with the default value for +all of the attributes defined by the implementation. +.LP +Results are undefined if \fIpthread_mutexattr_init\fP() is called +specifying an already initialized \fIattr\fP attributes +object. +.LP +After a mutex attributes object has been used to initialize one or +more mutexes, any function affecting the attributes object +(including destruction) shall not affect any previously initialized +mutexes. +.SH RETURN VALUE +.LP +Upon successful completion, \fIpthread_mutexattr_destroy\fP() and +\fIpthread_mutexattr_init\fP() shall return zero; otherwise, +an error number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_mutexattr_destroy\fP() function may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +The \fIpthread_mutexattr_init\fP() function shall fail if: +.TP 7 +.B ENOMEM +Insufficient memory exists to initialize the mutex attributes object. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +See \fIpthread_attr_init\fP() for a general explanation of attributes. +Attributes objects +allow implementations to experiment with useful extensions and permit +extension of this volume of IEEE\ Std\ 1003.1-2001 +without changing the existing functions. Thus, they provide for future +extensibility of this volume of +IEEE\ Std\ 1003.1-2001 and reduce the temptation to standardize prematurely +on semantics that are not yet widely +implemented or understood. +.LP +Examples of possible additional mutex attributes that have been discussed +are \fIspin_only\fP, \fIlimited_spin\fP, +\fIno_spin\fP, \fIrecursive\fP, and \fImetered\fP. (To explain what +the latter attributes might mean: recursive mutexes would +allow for multiple re-locking by the current owner; metered mutexes +would transparently keep records of queue length, wait time, +and so on.) Since there is not yet wide agreement on the usefulness +of these resulting from shared implementation and usage +experience, they are not yet specified in this volume of IEEE\ Std\ 1003.1-2001. +Mutex attributes objects, however, make it +possible to test out these concepts for possible standardization at +a later time. +.SS Mutex Attributes and Performance +.LP +Care has been taken to ensure that the default values of the mutex +attributes have been defined such that mutexes initialized +with the defaults have simple enough semantics so that the locking +and unlocking can be done with the equivalent of a test-and-set +instruction (plus possibly a few other basic instructions). +.LP +There is at least one implementation method that can be used to reduce +the cost of testing at lock-time if a mutex has +non-default attributes. One such method that an implementation can +employ (and this can be made fully transparent to fully +conforming POSIX applications) is to secretly pre-lock any mutexes +that are initialized to non-default attributes. Any later +attempt to lock such a mutex causes the implementation to branch to +the "slow path" as if the mutex were unavailable; then, on +the slow path, the implementation can do the "real work" to lock a +non-default mutex. The underlying unlock operation is more +complicated since the implementation never really wants to release +the pre-lock on this kind of mutex. This illustrates that, +depending on the hardware, there may be certain optimizations that +can be used so that whatever mutex attributes are considered +"most frequently used" can be processed most efficiently. +.SS Process Shared Memory and Synchronization +.LP +The existence of memory mapping functions in this volume of IEEE\ Std\ 1003.1-2001 +leads to the possibility that an +application may allocate the synchronization objects from this section +in memory that is accessed by multiple processes (and +therefore, by threads of multiple processes). +.LP +In order to permit such usage, while at the same time keeping the +usual case (that is, usage within a single process) efficient, +a \fIprocess-shared\fP option has been defined. +.LP +If an implementation supports the _POSIX_THREAD_PROCESS_SHARED option, +then the \fIprocess-shared\fP attribute can be used to +indicate that mutexes or condition variables may be accessed by threads +of multiple processes. +.LP +The default setting of PTHREAD_PROCESS_PRIVATE has been chosen for +the \fIprocess-shared\fP attribute so that the most +efficient forms of these synchronization objects are created by default. +.LP +Synchronization variables that are initialized with the PTHREAD_PROCESS_PRIVATE +\fIprocess-shared\fP attribute may only be +operated on by threads in the process that initialized them. Synchronization +variables that are initialized with the +PTHREAD_PROCESS_SHARED \fIprocess-shared\fP attribute may be operated +on by any thread in any process that has access to it. In +particular, these processes may exist beyond the lifetime of the initializing +process. For example, the following code implements a +simple counting semaphore in a mapped file that may be used by many +processes. +.sp +.RS +.nf + +\fB/* sem.h */ +struct semaphore { + pthread_mutex_t lock; + pthread_cond_t nonzero; + unsigned count; +}; +typedef struct semaphore semaphore_t; +.sp + +semaphore_t *semaphore_create(char *semaphore_name); +semaphore_t *semaphore_open(char *semaphore_name); +void semaphore_post(semaphore_t *semap); +void semaphore_wait(semaphore_t *semap); +void semaphore_close(semaphore_t *semap); +.sp + +/* sem.c */ +#include +#include +#include +#include +#include +#include "sem.h" +.sp + +semaphore_t * +semaphore_create(char *semaphore_name) +{ +int fd; + semaphore_t *semap; + pthread_mutexattr_t psharedm; + pthread_condattr_t psharedc; +.sp + + fd = open(semaphore_name, O_RDWR | O_CREAT | O_EXCL, 0666); + if (fd < 0) + return (NULL); + (void) ftruncate(fd, sizeof(semaphore_t)); + (void) pthread_mutexattr_init(&psharedm); + (void) pthread_mutexattr_setpshared(&psharedm, + PTHREAD_PROCESS_SHARED); + (void) pthread_condattr_init(&psharedc); + (void) pthread_condattr_setpshared(&psharedc, + PTHREAD_PROCESS_SHARED); + semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t), + PROT_READ | PROT_WRITE, MAP_SHARED, + fd, 0); + close (fd); + (void) pthread_mutex_init(&semap->lock, &psharedm); + (void) pthread_cond_init(&semap->nonzero, &psharedc); + semap->count = 0; + return (semap); +} +.sp + +semaphore_t * +semaphore_open(char *semaphore_name) +{ + int fd; + semaphore_t *semap; +.sp + + fd = open(semaphore_name, O_RDWR, 0666); + if (fd < 0) + return (NULL); + semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t), + PROT_READ | PROT_WRITE, MAP_SHARED, + fd, 0); + close (fd); + return (semap); +} +.sp + +void +semaphore_post(semaphore_t *semap) +{ + pthread_mutex_lock(&semap->lock); + if (semap->count == 0) + pthread_cond_signal(&semapx->nonzero); + semap->count++; + pthread_mutex_unlock(&semap->lock); +} +.sp + +void +semaphore_wait(semaphore_t *semap) +{ + pthread_mutex_lock(&semap->lock); + while (semap->count == 0) + pthread_cond_wait(&semap->nonzero, &semap->lock); + semap->count--; + pthread_mutex_unlock(&semap->lock); +} +.sp + +void +semaphore_close(semaphore_t *semap) +{ + munmap((void *) semap, sizeof(semaphore_t)); +} +\fP +.fi +.RE +.LP +The following code is for three separate processes that create, post, +and wait on a semaphore in the file \fB/tmp/semaphore\fP. +Once the file is created, the post and wait programs increment and +decrement the counting semaphore (waiting and waking as +required) even though they did not initialize the semaphore. +.sp +.RS +.nf + +\fB/* create.c */ +#include "pthread.h" +#include "sem.h" +.sp + +int +main() +{ + semaphore_t *semap; +.sp + + semap = semaphore_create("/tmp/semaphore"); + if (semap == NULL) + exit(1); + semaphore_close(semap); + return (0); +} +.sp + +/* post */ +#include "pthread.h" +#include "sem.h" +.sp + +int +main() +{ + semaphore_t *semap; +.sp + + semap = semaphore_open("/tmp/semaphore"); + if (semap == NULL) + exit(1); + semaphore_post(semap); + semaphore_close(semap); + return (0); +} +.sp + +/* wait */ +#include "pthread.h" +#include "sem.h" +.sp + +int +main() +{ + semaphore_t *semap; +.sp + + semap = semaphore_open("/tmp/semaphore"); + if (semap == NULL) + exit(1); + semaphore_wait(semap); + semaphore_close(semap); + return (0); +} +\fP +.fi +.RE +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_cond_destroy\fP() , \fIpthread_create\fP() , \fIpthread_mutex_destroy\fP() +, pthread_mutexattr_destroy , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_mutexattr_setprioceiling.3p b/man3p/pthread_mutexattr_setprioceiling.3p new file mode 100644 index 000000000..acb5a16f5 --- /dev/null +++ b/man3p/pthread_mutexattr_setprioceiling.3p @@ -0,0 +1 @@ +.so man3p/pthread_mutexattr_getprioceiling.3p diff --git a/man3p/pthread_mutexattr_setprotocol.3p b/man3p/pthread_mutexattr_setprotocol.3p new file mode 100644 index 000000000..120b0d2ca --- /dev/null +++ b/man3p/pthread_mutexattr_setprotocol.3p @@ -0,0 +1 @@ +.so man3p/pthread_mutexattr_getprotocol.3p diff --git a/man3p/pthread_mutexattr_setpshared.3p b/man3p/pthread_mutexattr_setpshared.3p new file mode 100644 index 000000000..49356aef6 --- /dev/null +++ b/man3p/pthread_mutexattr_setpshared.3p @@ -0,0 +1 @@ +.so man3p/pthread_mutexattr_getpshared.3p diff --git a/man3p/pthread_mutexattr_settype.3p b/man3p/pthread_mutexattr_settype.3p new file mode 100644 index 000000000..4e34ea478 --- /dev/null +++ b/man3p/pthread_mutexattr_settype.3p @@ -0,0 +1 @@ +.so man3p/pthread_mutexattr_gettype.3p diff --git a/man3p/pthread_once.3p b/man3p/pthread_once.3p new file mode 100644 index 000000000..4220b3167 --- /dev/null +++ b/man3p/pthread_once.3p @@ -0,0 +1,144 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_ONCE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_once +.SH NAME +pthread_once \- dynamic package initialization +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_once(pthread_once_t *\fP\fIonce_control\fP\fB, +.br +\ \ \ \ \ \ void (*\fP\fIinit_routine\fP\fB)(void)); +.br +pthread_once_t\fP \fIonce_control\fP \fB= PTHREAD_ONCE_INIT; \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The first call to \fIpthread_once\fP() by any thread in a process, +with a given \fIonce_control\fP, shall call the +\fIinit_routine\fP with no arguments. Subsequent calls of \fIpthread_once\fP() +with the same \fIonce_control\fP shall not call +the \fIinit_routine\fP. On return from \fIpthread_once\fP(), \fIinit_routine\fP +shall have completed. The \fIonce_control\fP +parameter shall determine whether the associated initialization routine +has been called. +.LP +The \fIpthread_once\fP() function is not a cancellation point. However, +if \fIinit_routine\fP is a cancellation point and is +canceled, the effect on \fIonce_control\fP shall be as if \fIpthread_once\fP() +was never called. +.LP +The constant PTHREAD_ONCE_INIT is defined in the \fI\fP +header. +.LP +The behavior of \fIpthread_once\fP() is undefined if \fIonce_control\fP +has automatic storage duration or is not initialized +by PTHREAD_ONCE_INIT. +.SH RETURN VALUE +.LP +Upon successful completion, \fIpthread_once\fP() shall return zero; +otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +.LP +The \fIpthread_once\fP() function may fail if: +.TP 7 +.B EINVAL +If either \fIonce_control\fP or \fIinit_routine\fP is invalid. +.sp +.LP +The \fIpthread_once\fP() function shall not return an error code of +[EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Some C libraries are designed for dynamic initialization. That is, +the global initialization for the library is performed when +the first procedure in the library is called. In a single-threaded +program, this is normally implemented using a static variable +whose value is checked on entry to a routine, as follows: +.sp +.RS +.nf + +\fBstatic int random_is_initialized = 0; +extern int initialize_random(); +.sp + +int random_function() +{ + if (random_is_initialized == 0) { + initialize_random(); + random_is_initialized = 1; + } + ... /* Operations performed after initialization. */ +} +\fP +.fi +.RE +.LP +To keep the same structure in a multi-threaded program, a new primitive +is needed. Otherwise, library initialization has to be +accomplished by an explicit call to a library-exported initialization +function prior to any use of the library. +.LP +For dynamic library initialization in a multi-threaded process, a +simple initialization flag is not sufficient; the flag needs +to be protected against modification by multiple threads simultaneously +calling into the library. Protecting the flag requires the +use of a mutex; however, mutexes have to be initialized before they +are used. Ensuring that the mutex is only initialized once +requires a recursive solution to this problem. +.LP +The use of \fIpthread_once\fP() not only supplies an implementation-guaranteed +means of dynamic initialization, it provides an +aid to the reliable construction of multi-threaded and realtime systems. +The preceding example then becomes: +.sp +.RS +.nf + +\fB#include +static pthread_once_t random_is_initialized = PTHREAD_ONCE_INIT; +extern int initialize_random(); +.sp + +int random_function() +{ + (void) pthread_once(&random_is_initialized, initialize_random); + ... /* Operations performed after initialization. */ +} +\fP +.fi +.RE +.LP +Note that a \fBpthread_once_t\fP cannot be an array because some compilers +do not accept the construct +\fB&\fP. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_rwlock_destroy.3p b/man3p/pthread_rwlock_destroy.3p new file mode 100644 index 000000000..3114e09a6 --- /dev/null +++ b/man3p/pthread_rwlock_destroy.3p @@ -0,0 +1 @@ +.so man3p/pthread_rwlock_init.3p diff --git a/man3p/pthread_rwlock_init.3p b/man3p/pthread_rwlock_init.3p new file mode 100644 index 000000000..f2fe880d3 --- /dev/null +++ b/man3p/pthread_rwlock_init.3p @@ -0,0 +1,137 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_RWLOCK_DESTROY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_rwlock_destroy +.SH NAME +pthread_rwlock_destroy, pthread_rwlock_init \- destroy and initialize +a read\-write lock object +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_rwlock_destroy(pthread_rwlock_t *\fP\fIrwlock\fP\fB); +.br +int pthread_rwlock_init(pthread_rwlock_t *restrict\fP \fIrwlock\fP\fB, +.br +\ \ \ \ \ \ const pthread_rwlockattr_t *restrict\fP \fIattr\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_rwlock_destroy\fP() function shall destroy the read-write +lock object referenced by \fIrwlock\fP and release +any resources used by the lock. The effect of subsequent use of the +lock is undefined until the lock is reinitialized by another +call to \fIpthread_rwlock_init\fP(). An implementation may cause \fIpthread_rwlock_destroy\fP() +to set the object referenced by +\fIrwlock\fP to an invalid value. Results are undefined if \fIpthread_rwlock_destroy\fP() +is called when any thread holds +\fIrwlock\fP. Attempting to destroy an uninitialized read-write lock +results in undefined behavior. +.LP +The \fIpthread_rwlock_init\fP() function shall allocate any resources +required to use the read-write lock referenced by +\fIrwlock\fP and initializes the lock to an unlocked state with attributes +referenced by \fIattr\fP. If \fIattr\fP is NULL, the +default read-write lock attributes shall be used; the effect is the +same as passing the address of a default read-write lock +attributes object. Once initialized, the lock can be used any number +of times without being reinitialized. Results are undefined if +\fIpthread_rwlock_init\fP() is called specifying an already initialized +read-write lock. Results are undefined if a read-write +lock is used without first being initialized. +.LP +If the \fIpthread_rwlock_init\fP() function fails, \fIrwlock\fP shall +not be initialized and the contents of \fIrwlock\fP are +undefined. +.LP +Only the object referenced by \fIrwlock\fP may be used for performing +synchronization. The result of referring to copies of +that object in calls to \fIpthread_rwlock_destroy\fP(), \fIpthread_rwlock_rdlock\fP(), +\fIpthread_rwlock_timedrdlock\fP(), \fIpthread_rwlock_timedwrlock\fP(), +\fIpthread_rwlock_tryrdlock\fP(), \fIpthread_rwlock_trywrlock\fP(), +\fIpthread_rwlock_unlock\fP(), or \fIpthread_rwlock_wrlock\fP() is +undefined. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_rwlock_destroy\fP() and \fIpthread_rwlock_init\fP() +functions shall return zero; otherwise, an +error number shall be returned to indicate the error. +.LP +The [EBUSY] and [EINVAL] error checks, if implemented, act as if they +were performed immediately at the beginning of processing +for the function and caused an error return prior to modifying the +state of the read-write lock specified by \fIrwlock\fP. +.SH ERRORS +.LP +The \fIpthread_rwlock_destroy\fP() function may fail if: +.TP 7 +.B EBUSY +The implementation has detected an attempt to destroy the object referenced +by \fIrwlock\fP while it is locked. +.TP 7 +.B EINVAL +The value specified by \fIrwlock\fP is invalid. +.sp +.LP +The \fIpthread_rwlock_init\fP() function shall fail if: +.TP 7 +.B EAGAIN +The system lacked the necessary resources (other than memory) to initialize +another read-write lock. +.TP 7 +.B ENOMEM +Insufficient memory exists to initialize the read-write lock. +.TP 7 +.B EPERM +The caller does not have the privilege to perform the operation. +.sp +.LP +The \fIpthread_rwlock_init\fP() function may fail if: +.TP 7 +.B EBUSY +The implementation has detected an attempt to reinitialize the object +referenced by \fIrwlock\fP, a previously initialized but +not yet destroyed read-write lock. +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications using these and related read-write lock functions may +be subject to priority inversion, as discussed in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 3.285, Priority +Inversion. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_rwlock_rdlock\fP() , \fIpthread_rwlock_timedrdlock\fP() +, \fIpthread_rwlock_timedwrlock\fP() , \fIpthread_rwlock_tryrdlock\fP() +, \fIpthread_rwlock_trywrlock\fP() , \fIpthread_rwlock_unlock\fP() +, \fIpthread_rwlock_wrlock\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_rwlock_rdlock.3p b/man3p/pthread_rwlock_rdlock.3p new file mode 100644 index 000000000..93c46c128 --- /dev/null +++ b/man3p/pthread_rwlock_rdlock.3p @@ -0,0 +1,145 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_RWLOCK_RDLOCK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_rwlock_rdlock +.SH NAME +pthread_rwlock_rdlock, pthread_rwlock_tryrdlock \- lock a read-write +lock object for reading +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_rwlock_rdlock(pthread_rwlock_t\fP \fI*rwlock\fP\fB); +.br +int pthread_rwlock_tryrdlock(pthread_rwlock_t\fP \fI*rwlock\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_rwlock_rdlock\fP() function shall apply a read lock +to the read-write lock referenced by \fIrwlock\fP. The +calling thread acquires the read lock if a writer does not hold the +lock and there are no writers blocked on the lock. +.LP +If the Thread Execution Scheduling option is supported, and the threads +involved in the lock are executing with the scheduling +policies SCHED_FIFO or SCHED_RR, the calling thread shall not acquire +the lock if a writer holds the lock or if writers of higher +or equal priority are blocked on the lock; otherwise, the calling +thread shall acquire the lock. +.LP +If the Threads Execution Scheduling option is supported, and the threads +involved in the lock are executing with the +SCHED_SPORADIC scheduling policy, the calling thread shall not acquire +the lock if a writer holds the lock or if writers of higher +or equal priority are blocked on the lock; otherwise, the calling +thread shall acquire the lock. +.LP +If the Thread Execution Scheduling option is not supported, it is +implementation-defined whether the calling thread acquires the +lock when a writer does not hold the lock and there are writers blocked +on the lock. If a writer holds the lock, the calling thread +shall not acquire the read lock. If the read lock is not acquired, +the calling thread shall block until it can acquire the lock. +The calling thread may deadlock if at the time the call is made it +holds a write lock. +.LP +A thread may hold multiple concurrent read locks on \fIrwlock\fP (that +is, successfully call the \fIpthread_rwlock_rdlock\fP() +function \fIn\fP times). If so, the application shall ensure that +the thread performs matching unlocks (that is, it calls the \fIpthread_rwlock_unlock\fP() +function \fIn\fP times). +.LP +The maximum number of simultaneous read locks that an implementation +guarantees can be applied to a read-write lock shall be +implementation-defined. The \fIpthread_rwlock_rdlock\fP() function +may fail if this maximum would be exceeded. +.LP +The \fIpthread_rwlock_tryrdlock\fP() function shall apply a read lock +as in the \fIpthread_rwlock_rdlock\fP() function, with +the exception that the function shall fail if the equivalent \fIpthread_rwlock_rdlock\fP() +call would have blocked the calling +thread. In no case shall the \fIpthread_rwlock_tryrdlock\fP() function +ever block; it always either acquires the lock or fails and +returns immediately. +.LP +Results are undefined if any of these functions are called with an +uninitialized read-write lock. +.LP +If a signal is delivered to a thread waiting for a read-write lock +for reading, upon return from the signal handler the thread +resumes waiting for the read-write lock for reading as if it was not +interrupted. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_rwlock_rdlock\fP() function shall return +zero; otherwise, an error number shall be returned to +indicate the error. +.LP +The \fIpthread_rwlock_tryrdlock\fP() function shall return zero if +the lock for reading on the read-write lock object +referenced by \fIrwlock\fP is acquired. Otherwise, an error number +shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_rwlock_tryrdlock\fP() function shall fail if: +.TP 7 +.B EBUSY +The read-write lock could not be acquired for reading because a writer +holds the lock or a writer with the appropriate priority +was blocked on it. +.sp +.LP +The \fIpthread_rwlock_rdlock\fP() and \fIpthread_rwlock_tryrdlock\fP() +functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIrwlock\fP does not refer to an initialized +read-write lock object. +.TP 7 +.B EAGAIN +The read lock could not be acquired because the maximum number of +read locks for \fIrwlock\fP has been exceeded. +.sp +.LP +The \fIpthread_rwlock_rdlock\fP() function may fail if: +.TP 7 +.B EDEADLK +The current thread already owns the read-write lock for writing. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications using these functions may be subject to priority inversion, +as discussed in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 3.285, Priority Inversion. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_rwlock_destroy\fP() , \fIpthread_rwlock_timedrdlock\fP() +, \fIpthread_rwlock_timedwrlock\fP() , \fIpthread_rwlock_trywrlock\fP() +, \fIpthread_rwlock_unlock\fP() , \fIpthread_rwlock_wrlock\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_rwlock_timedrdlock.3p b/man3p/pthread_rwlock_timedrdlock.3p new file mode 100644 index 000000000..1e8629335 --- /dev/null +++ b/man3p/pthread_rwlock_timedrdlock.3p @@ -0,0 +1,123 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_RWLOCK_TIMEDRDLOCK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_rwlock_timedrdlock +.SH NAME +pthread_rwlock_timedrdlock \- lock a read-write lock for reading +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int pthread_rwlock_timedrdlock(pthread_rwlock_t *restrict\fP \fIrwlock\fP\fB, +.br +\ \ \ \ \ \ const struct timespec *restrict\fP \fIabs_timeout\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_rwlock_timedrdlock\fP() function shall apply a read +lock to the read-write lock referenced by \fIrwlock\fP as +in the \fIpthread_rwlock_rdlock\fP() function. However, if the lock +cannot +be acquired without waiting for other threads to unlock the lock, +this wait shall be terminated when the specified timeout expires. +The timeout shall expire when the absolute time specified by \fIabs_timeout\fP +passes, as measured by the clock on which timeouts +are based (that is, when the value of that clock equals or exceeds +\fIabs_timeout\fP), or if the absolute time specified by +\fIabs_timeout\fP has already been passed at the time of the call. +.LP +If the Timers option is supported, the timeout shall be based on the +CLOCK_REALTIME clock. If the Timers option is not supported, the +timeout shall be based on the system clock as returned by the +\fItime\fP() function. The resolution of the timeout shall be the +resolution of the clock on +which it is based. The \fBtimespec\fP data type is defined in the +\fI\fP +header. Under no circumstances shall the function fail with a timeout +if the lock can be acquired immediately. The validity of the +\fIabs_timeout\fP parameter need not be checked if the lock can be +immediately acquired. +.LP +If a signal that causes a signal handler to be executed is delivered +to a thread blocked on a read-write lock via a call to +\fIpthread_rwlock_timedrdlock\fP(), upon return from the signal handler +the thread shall resume waiting for the lock as if it was +not interrupted. +.LP +The calling thread may deadlock if at the time the call is made it +holds a write lock on \fIrwlock\fP. The results are +undefined if this function is called with an uninitialized read-write +lock. +.SH RETURN VALUE +.LP +The \fIpthread_rwlock_timedrdlock\fP() function shall return zero +if the lock for reading on the read-write lock object +referenced by \fIrwlock\fP is acquired. Otherwise, an error number +shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_rwlock_timedrdlock\fP() function shall fail if: +.TP 7 +.B ETIMEDOUT +The lock could not be acquired before the specified timeout expired. +.sp +.LP +The \fIpthread_rwlock_timedrdlock\fP() function may fail if: +.TP 7 +.B EAGAIN +The read lock could not be acquired because the maximum number of +read locks for lock would be exceeded. +.TP 7 +.B EDEADLK +The calling thread already holds a write lock on \fIrwlock\fP. +.TP 7 +.B EINVAL +The value specified by \fIrwlock\fP does not refer to an initialized +read-write lock object, or the \fIabs_timeout\fP +nanosecond value is less than zero or greater than or equal to 1000 +million. +.sp +.LP +This function shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications using this function may be subject to priority inversion, +as discussed in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 3.285, Priority Inversion. +.LP +The \fIpthread_rwlock_timedrdlock\fP() function is part of the Threads +and Timeouts options and need not be provided on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_rwlock_destroy\fP() , \fIpthread_rwlock_rdlock\fP() , \fIpthread_rwlock_timedwrlock\fP() +, \fIpthread_rwlock_tryrdlock\fP() , \fIpthread_rwlock_trywrlock\fP() +, \fIpthread_rwlock_unlock\fP() , \fIpthread_rwlock_wrlock\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_rwlock_timedwrlock.3p b/man3p/pthread_rwlock_timedwrlock.3p new file mode 100644 index 000000000..c3d6c56b3 --- /dev/null +++ b/man3p/pthread_rwlock_timedwrlock.3p @@ -0,0 +1,117 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_RWLOCK_TIMEDWRLOCK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_rwlock_timedwrlock +.SH NAME +pthread_rwlock_timedwrlock \- lock a read-write lock for writing +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int pthread_rwlock_timedwrlock(pthread_rwlock_t *restrict\fP \fIrwlock\fP\fB, +.br +\ \ \ \ \ \ const struct timespec *restrict\fP \fIabs_timeout\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_rwlock_timedwrlock\fP() function shall apply a write +lock to the read-write lock referenced by \fIrwlock\fP as +in the \fIpthread_rwlock_wrlock\fP() function. However, if the lock +cannot +be acquired without waiting for other threads to unlock the lock, +this wait shall be terminated when the specified timeout expires. +The timeout shall expire when the absolute time specified by \fIabs_timeout\fP +passes, as measured by the clock on which timeouts +are based (that is, when the value of that clock equals or exceeds +\fIabs_timeout\fP), or if the absolute time specified by +\fIabs_timeout\fP has already been passed at the time of the call. +.LP +If the Timers option is supported, the timeout shall be based on the +CLOCK_REALTIME clock. If the Timers option is not supported, the +timeout shall be based on the system clock as returned by the +\fItime\fP() function. The resolution of the timeout shall be the +resolution of the clock on +which it is based. The \fBtimespec\fP data type is defined in the +\fI\fP +header. Under no circumstances shall the function fail with a timeout +if the lock can be acquired immediately. The validity of the +\fIabs_timeout\fP parameter need not be checked if the lock can be +immediately acquired. +.LP +If a signal that causes a signal handler to be executed is delivered +to a thread blocked on a read-write lock via a call to +\fIpthread_rwlock_timedwrlock\fP(), upon return from the signal handler +the thread shall resume waiting for the lock as if it was +not interrupted. +.LP +The calling thread may deadlock if at the time the call is made it +holds the read-write lock. The results are undefined if this +function is called with an uninitialized read-write lock. +.SH RETURN VALUE +.LP +The \fIpthread_rwlock_timedwrlock\fP() function shall return zero +if the lock for writing on the read-write lock object +referenced by \fIrwlock\fP is acquired. Otherwise, an error number +shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_rwlock_timedwrlock\fP() function shall fail if: +.TP 7 +.B ETIMEDOUT +The lock could not be acquired before the specified timeout expired. +.sp +.LP +The \fIpthread_rwlock_timedwrlock\fP() function may fail if: +.TP 7 +.B EDEADLK +The calling thread already holds the \fIrwlock\fP. +.TP 7 +.B EINVAL +The value specified by rwlock does not refer to an initialized read-write +lock object, or the \fIabs_timeout\fP nanosecond +value is less than zero or greater than or equal to 1000 million. +.sp +.LP +This function shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications using this function may be subject to priority inversion, +as discussed in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 3.285, Priority Inversion. +.LP +The \fIpthread_rwlock_timedwrlock\fP() function is part of the Threads +and Timeouts options and need not be provided on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_rwlock_destroy\fP() , \fIpthread_rwlock_rdlock\fP() , \fIpthread_rwlock_timedrdlock\fP() +, \fIpthread_rwlock_tryrdlock\fP() , \fIpthread_rwlock_trywrlock\fP() +, \fIpthread_rwlock_unlock\fP() , \fIpthread_rwlock_wrlock\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_rwlock_tryrdlock.3p b/man3p/pthread_rwlock_tryrdlock.3p new file mode 100644 index 000000000..d3c2a0c88 --- /dev/null +++ b/man3p/pthread_rwlock_tryrdlock.3p @@ -0,0 +1 @@ +.so man3p/pthread_rwlock_rdlock.3p diff --git a/man3p/pthread_rwlock_trywrlock.3p b/man3p/pthread_rwlock_trywrlock.3p new file mode 100644 index 000000000..4df624e03 --- /dev/null +++ b/man3p/pthread_rwlock_trywrlock.3p @@ -0,0 +1 @@ +.so man3p/pthread_rwlock_wrlock.3p diff --git a/man3p/pthread_rwlock_unlock.3p b/man3p/pthread_rwlock_unlock.3p new file mode 100644 index 000000000..55b327363 --- /dev/null +++ b/man3p/pthread_rwlock_unlock.3p @@ -0,0 +1,95 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_RWLOCK_UNLOCK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_rwlock_unlock +.SH NAME +pthread_rwlock_unlock \- unlock a read-write lock object +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_rwlock_unlock(pthread_rwlock_t\fP \fI*rwlock\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_rwlock_unlock\fP() function shall release a lock held +on the read-write lock object referenced by \fIrwlock\fP. +Results are undefined if the read-write lock \fIrwlock\fP is not held +by the calling thread. +.LP +If this function is called to release a read lock from the read-write +lock object and there are other read locks currently held +on this read-write lock object, the read-write lock object remains +in the read locked state. If this function releases the last +read lock for this read-write lock object, the read-write lock object +shall be put in the unlocked state with no owners. +.LP +If this function is called to release a write lock for this read-write +lock object, the read-write lock object shall be put in +the unlocked state. +.LP +If there are threads blocked on the lock when it becomes available, +the scheduling policy shall determine which thread(s) shall +acquire the lock. \ If the Thread Execution Scheduling option is +supported, when threads executing with the +scheduling policies SCHED_FIFO, SCHED_RR, or SCHED_SPORADIC are waiting +on the lock, they shall acquire the lock in priority order +when the lock becomes available. For equal priority threads, write +locks shall take precedence over read locks. If the Thread Execution +Scheduling option is not supported, it is +implementation-defined whether write locks take precedence over read +locks. +.LP +Results are undefined if any of these functions are called with an +uninitialized read-write lock. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_rwlock_unlock\fP() function shall return +zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +.LP +The \fIpthread_rwlock_unlock\fP() function may fail if: +.TP 7 +.B EINVAL +The value specified by \fIrwlock\fP does not refer to an initialized +read-write lock object. +.TP 7 +.B EPERM +The current thread does not hold a lock on the read-write lock. +.sp +.LP +The \fIpthread_rwlock_unlock\fP() function shall not return an error +code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_rwlock_destroy\fP() , \fIpthread_rwlock_rdlock\fP() , \fIpthread_rwlock_timedrdlock\fP() +, \fIpthread_rwlock_timedwrlock\fP() , \fIpthread_rwlock_tryrdlock\fP() +, \fIpthread_rwlock_trywrlock\fP() , \fIpthread_rwlock_wrlock\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_rwlock_wrlock.3p b/man3p/pthread_rwlock_wrlock.3p new file mode 100644 index 000000000..cab2a76ae --- /dev/null +++ b/man3p/pthread_rwlock_wrlock.3p @@ -0,0 +1,108 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_RWLOCK_TRYWRLOCK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_rwlock_trywrlock +.SH NAME +pthread_rwlock_trywrlock, pthread_rwlock_wrlock \- lock a read-write +lock object for writing +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_rwlock_trywrlock(pthread_rwlock_t\fP \fI*rwlock\fP\fB); +.br +int pthread_rwlock_wrlock(pthread_rwlock_t\fP \fI*rwlock\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_rwlock_trywrlock\fP() function shall apply a write +lock like the \fIpthread_rwlock_wrlock\fP() function, with +the exception that the function shall fail if any thread currently +holds \fIrwlock\fP (for reading or writing). +.LP +The \fIpthread_rwlock_wrlock\fP() function shall apply a write lock +to the read-write lock referenced by \fIrwlock\fP. The +calling thread acquires the write lock if no other thread (reader +or writer) holds the read-write lock \fIrwlock\fP. Otherwise, +the thread shall block until it can acquire the lock. The calling +thread may deadlock if at the time the call is made it holds the +read-write lock (whether a read or write lock). +.LP +Implementations may favor writers over readers to avoid writer starvation. +.LP +Results are undefined if any of these functions are called with an +uninitialized read-write lock. +.LP +If a signal is delivered to a thread waiting for a read-write lock +for writing, upon return from the signal handler the thread +resumes waiting for the read-write lock for writing as if it was not +interrupted. +.SH RETURN VALUE +.LP +The \fIpthread_rwlock_trywrlock\fP() function shall return zero if +the lock for writing on the read-write lock object +referenced by \fIrwlock\fP is acquired. Otherwise, an error number +shall be returned to indicate the error. +.LP +If successful, the \fIpthread_rwlock_wrlock\fP() function shall return +zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +.LP +The \fIpthread_rwlock_trywrlock\fP() function shall fail if: +.TP 7 +.B EBUSY +The read-write lock could not be acquired for writing because it was +already locked for reading or writing. +.sp +.LP +The \fIpthread_rwlock_trywrlock\fP() and \fIpthread_rwlock_wrlock\fP() +functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIrwlock\fP does not refer to an initialized +read-write lock object. +.sp +.LP +The \fIpthread_rwlock_wrlock\fP() function may fail if: +.TP 7 +.B EDEADLK +The current thread already owns the read-write lock for writing or +reading. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications using these functions may be subject to priority inversion, +as discussed in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 3.285, Priority Inversion. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_rwlock_destroy\fP() , \fIpthread_rwlock_rdlock\fP() , \fIpthread_rwlock_timedrdlock\fP() +, \fIpthread_rwlock_timedwrlock\fP() , \fIpthread_rwlock_tryrdlock\fP() +, \fIpthread_rwlock_unlock\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_rwlockattr_destroy.3p b/man3p/pthread_rwlockattr_destroy.3p new file mode 100644 index 000000000..650be889a --- /dev/null +++ b/man3p/pthread_rwlockattr_destroy.3p @@ -0,0 +1 @@ +.so man3p/pthread_rwlockattr_init.3p diff --git a/man3p/pthread_rwlockattr_getpshared.3p b/man3p/pthread_rwlockattr_getpshared.3p new file mode 100644 index 000000000..adc809e4b --- /dev/null +++ b/man3p/pthread_rwlockattr_getpshared.3p @@ -0,0 +1,103 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_RWLOCKATTR_GETPSHARED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_rwlockattr_getpshared +.SH NAME +pthread_rwlockattr_getpshared, pthread_rwlockattr_setpshared \- get +and set the process\-shared attribute of the +read\-write lock attributes object +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t * +.br +\ \ \ \ \ \ restrict\fP \fIattr\fP\fB, int *restrict\fP \fIpshared\fP\fB); +.br +int pthread_rwlockattr_setpshared(pthread_rwlockattr_t\fP \fI*attr\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIpshared\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_rwlockattr_getpshared\fP() function shall obtain the +value of the \fIprocess-shared\fP attribute from the +initialized attributes object referenced by \fIattr\fP. The \fIpthread_rwlockattr_setpshared\fP() +function shall set the +\fIprocess-shared\fP attribute in an initialized attributes object +referenced by \fIattr\fP. +.LP +The \fIprocess-shared\fP attribute shall be set to PTHREAD_PROCESS_SHARED +to permit a read-write lock to be operated upon by +any thread that has access to the memory where the read-write lock +is allocated, even if the read-write lock is allocated in memory +that is shared by multiple processes. If the \fIprocess-shared\fP +attribute is PTHREAD_PROCESS_PRIVATE, the read-write lock shall +only be operated upon by threads created within the same process as +the thread that initialized the read-write lock; if threads of +differing processes attempt to operate on such a read-write lock, +the behavior is undefined. The default value of the +\fIprocess-shared\fP attribute shall be PTHREAD_PROCESS_PRIVATE. +.LP +Additional attributes, their default values, and the names of the +associated functions to get and set those attribute values are +implementation-defined. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIpthread_rwlockattr_getpshared\fP() +function shall return zero and store the value of the +\fIprocess-shared\fP attribute of \fIattr\fP into the object referenced +by the \fIpshared\fP parameter. Otherwise, an error +number shall be returned to indicate the error. +.LP +If successful, the \fIpthread_rwlockattr_setpshared\fP() function +shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_rwlockattr_getpshared\fP() and \fIpthread_rwlockattr_setpshared\fP() +functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +The \fIpthread_rwlockattr_setpshared\fP() function may fail if: +.TP 7 +.B EINVAL +The new value specified for the attribute is outside the range of +legal values for that attribute. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_rwlock_destroy\fP() , \fIpthread_rwlockattr_destroy\fP() +, \fIpthread_rwlockattr_init\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_rwlockattr_init.3p b/man3p/pthread_rwlockattr_init.3p new file mode 100644 index 000000000..4e1356cd5 --- /dev/null +++ b/man3p/pthread_rwlockattr_init.3p @@ -0,0 +1,92 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_RWLOCKATTR_DESTROY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_rwlockattr_destroy +.SH NAME +pthread_rwlockattr_destroy, pthread_rwlockattr_init \- destroy and +initialize the read\-write lock attributes +object +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_rwlockattr_destroy(pthread_rwlockattr_t\fP \fI*attr\fP\fB); +.br +int pthread_rwlockattr_init(pthread_rwlockattr_t\fP \fI*attr\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_rwlockattr_destroy\fP() function shall destroy a read-write +lock attributes object. A destroyed \fIattr\fP +attributes object can be reinitialized using \fIpthread_rwlockattr_init\fP(); +the results of otherwise referencing the object +after it has been destroyed are undefined. An implementation may cause +\fIpthread_rwlockattr_destroy\fP() to set the object +referenced by \fIattr\fP to an invalid value. +.LP +The \fIpthread_rwlockattr_init\fP() function shall initialize a read-write +lock attributes object \fIattr\fP with the default +value for all of the attributes defined by the implementation. +.LP +Results are undefined if \fIpthread_rwlockattr_init\fP() is called +specifying an already initialized \fIattr\fP attributes +object. +.LP +After a read-write lock attributes object has been used to initialize +one or more read-write locks, any function affecting the +attributes object (including destruction) shall not affect any previously +initialized read-write locks. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_rwlockattr_destroy\fP() and \fIpthread_rwlockattr_init\fP() +functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_rwlockattr_destroy\fP() function may fail if: +.TP 7 +.B EINVAL +The value specified by \fIattr\fP is invalid. +.sp +.LP +The \fIpthread_rwlockattr_init\fP() function shall fail if: +.TP 7 +.B ENOMEM +Insufficient memory exists to initialize the read-write lock attributes +object. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_rwlock_destroy\fP() , \fIpthread_rwlockattr_getpshared\fP() +, \fIpthread_rwlockattr_setpshared\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_rwlockattr_setpshared.3p b/man3p/pthread_rwlockattr_setpshared.3p new file mode 100644 index 000000000..07d9aca28 --- /dev/null +++ b/man3p/pthread_rwlockattr_setpshared.3p @@ -0,0 +1 @@ +.so man3p/pthread_rwlockattr_getpshared.3p diff --git a/man3p/pthread_self.3p b/man3p/pthread_self.3p new file mode 100644 index 000000000..7b1b950af --- /dev/null +++ b/man3p/pthread_self.3p @@ -0,0 +1,58 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_SELF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_self +.SH NAME +pthread_self \- get the calling thread ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +pthread_t pthread_self(void); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_self\fP() function shall return the thread ID of the +calling thread. +.SH RETURN VALUE +.LP +Refer to the DESCRIPTION. +.SH ERRORS +.LP +No errors are defined. +.LP +The \fIpthread_self\fP() function shall not return an error code of +[EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIpthread_self\fP() function provides a capability similar to +the \fIgetpid\fP() +function for processes and the rationale is the same: the creation +call does not provide the thread ID to the created thread. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_create\fP() , \fIpthread_equal\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_setcancelstate.3p b/man3p/pthread_setcancelstate.3p new file mode 100644 index 000000000..5de2c51a6 --- /dev/null +++ b/man3p/pthread_setcancelstate.3p @@ -0,0 +1 @@ +.so man3p/pthread_testcancel.3p diff --git a/man3p/pthread_setcanceltype.3p b/man3p/pthread_setcanceltype.3p new file mode 100644 index 000000000..5de2c51a6 --- /dev/null +++ b/man3p/pthread_setcanceltype.3p @@ -0,0 +1 @@ +.so man3p/pthread_testcancel.3p diff --git a/man3p/pthread_setconcurrency.3p b/man3p/pthread_setconcurrency.3p new file mode 100644 index 000000000..a2b8dd9b9 --- /dev/null +++ b/man3p/pthread_setconcurrency.3p @@ -0,0 +1 @@ +.so man3p/pthread_getconcurrency.3p diff --git a/man3p/pthread_setschedparam.3p b/man3p/pthread_setschedparam.3p new file mode 100644 index 000000000..f8191728b --- /dev/null +++ b/man3p/pthread_setschedparam.3p @@ -0,0 +1 @@ +.so man3p/pthread_getschedparam.3p diff --git a/man3p/pthread_setschedprio.3p b/man3p/pthread_setschedprio.3p new file mode 100644 index 000000000..efd445d09 --- /dev/null +++ b/man3p/pthread_setschedprio.3p @@ -0,0 +1,102 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_SETSCHEDPRIO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_setschedprio +.SH NAME +pthread_setschedprio \- dynamic thread scheduling parameters access +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_setschedprio(pthread_t\fP \fIthread\fP\fB, int\fP \fIprio\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_setschedprio\fP() function shall set the scheduling +priority for the thread whose thread ID is given by +\fIthread\fP to the value given by \fIprio\fP. See \fIScheduling Policies\fP +for a description on how this function call affects the ordering of +the thread in the thread list for its new priority. +.LP +If the \fIpthread_setschedprio\fP() function fails, the scheduling +priority of the target thread shall not be changed. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_setschedprio\fP() function shall return +zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +.LP +The \fIpthread_setschedprio\fP() function may fail if: +.TP 7 +.B EINVAL +The value of \fIprio\fP is invalid for the scheduling policy of the +specified thread. +.TP 7 +.B ENOTSUP +An attempt was made to set the priority to an unsupported value. +.TP 7 +.B EPERM +The caller does not have the appropriate permission to set the scheduling +policy of the specified thread. +.TP 7 +.B EPERM +The implementation does not allow the application to modify the priority +to the value specified. +.TP 7 +.B ESRCH +The value specified by \fIthread\fP does not refer to an existing +thread. +.sp +.LP +The \fIpthread_setschedprio\fP() function shall not return an error +code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIpthread_setschedprio\fP() function provides a way for an application +to temporarily raise its priority and then lower it +again, without having the undesired side effect of yielding to other +threads of the same priority. This is necessary if the +application is to implement its own strategies for bounding priority +inversion, such as priority inheritance or priority ceilings. +This capability is especially important if the implementation does +not support the Thread Priority Protection or Thread Priority +Inheritance options, but even if those options are supported it is +needed if the application is to bound priority inheritance for +other resources, such as semaphores. +.LP +The standard developers considered that while it might be preferable +conceptually to solve this problem by modifying the +specification of \fIpthread_setschedparam\fP(), it was too late to +make such +a change, as there may be implementations that would need to be changed. +Therefore, this new function was introduced. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIScheduling Policies\fP , \fIpthread_getschedparam\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_setspecific.3p b/man3p/pthread_setspecific.3p new file mode 100644 index 000000000..aa3b23ba8 --- /dev/null +++ b/man3p/pthread_setspecific.3p @@ -0,0 +1 @@ +.so man3p/pthread_getspecific.3p diff --git a/man3p/pthread_sigmask.3p b/man3p/pthread_sigmask.3p new file mode 100644 index 000000000..e5415204d --- /dev/null +++ b/man3p/pthread_sigmask.3p @@ -0,0 +1 @@ +.so man3p/sigprocmask.3p diff --git a/man3p/pthread_spin_destroy.3p b/man3p/pthread_spin_destroy.3p new file mode 100644 index 000000000..92e56931a --- /dev/null +++ b/man3p/pthread_spin_destroy.3p @@ -0,0 +1 @@ +.so man3p/pthread_spin_init.3p diff --git a/man3p/pthread_spin_init.3p b/man3p/pthread_spin_init.3p new file mode 100644 index 000000000..bc976071f --- /dev/null +++ b/man3p/pthread_spin_init.3p @@ -0,0 +1,120 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_SPIN_DESTROY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_spin_destroy +.SH NAME +pthread_spin_destroy, pthread_spin_init \- destroy or initialize a +spin lock object (\fBADVANCED REALTIME +THREADS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_spin_destroy(pthread_spinlock_t *\fP\fIlock\fP\fB); +.br +int pthread_spin_init(pthread_spinlock_t *\fP\fIlock\fP\fB, int\fP +\fIpshared\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_spin_destroy\fP() function shall destroy the spin lock +referenced by \fIlock\fP and release any resources used +by the lock. The effect of subsequent use of the lock is undefined +until the lock is reinitialized by another call to +\fIpthread_spin_init\fP(). The results are undefined if \fIpthread_spin_destroy\fP() +is called when a thread holds the lock, or +if this function is called with an uninitialized thread spin lock. +.LP +The \fIpthread_spin_init\fP() function shall allocate any resources +required to use the spin lock referenced by \fIlock\fP and +initialize the lock to an unlocked state. +.LP +If the Thread Process-Shared Synchronization option is supported and +the value of \fIpshared\fP is PTHREAD_PROCESS_SHARED, the +implementation shall permit the spin lock to be operated upon by any +thread that has access to the memory where the spin lock is +allocated, even if it is allocated in memory that is shared by multiple +processes. +.LP +If the Thread Process-Shared Synchronization option is supported and +the value of \fIpshared\fP is PTHREAD_PROCESS_PRIVATE, +or if the option is not supported, the spin lock shall only be +operated upon by threads created within the same process as the thread +that initialized the spin lock. If threads of differing +processes attempt to operate on such a spin lock, the behavior is +undefined. +.LP +The results are undefined if \fIpthread_spin_init\fP() is called specifying +an already initialized spin lock. The results are +undefined if a spin lock is used without first being initialized. +.LP +If the \fIpthread_spin_init\fP() function fails, the lock is not initialized +and the contents of \fIlock\fP are undefined. +.LP +Only the object referenced by \fIlock\fP may be used for performing +synchronization. +.LP +The result of referring to copies of that object in calls to \fIpthread_spin_destroy\fP(), +\fIpthread_spin_lock\fP(), \fIpthread_spin_trylock\fP(), or \fIpthread_spin_unlock\fP() +is undefined. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return zero; otherwise, +an error number shall be returned to indicate the +error. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +.B EBUSY +The implementation has detected an attempt to initialize or destroy +a spin lock while it is in use (for example, while being +used in a \fIpthread_spin_lock\fP() call) by another thread. +.TP 7 +.B EINVAL +The value specified by \fIlock\fP is invalid. +.sp +.LP +The \fIpthread_spin_init\fP() function shall fail if: +.TP 7 +.B EAGAIN +The system lacks the necessary resources to initialize another spin +lock. +.TP 7 +.B ENOMEM +Insufficient memory exists to initialize the lock. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIpthread_spin_destroy\fP() and \fIpthread_spin_init\fP() functions +are part of the Spin Locks option and need not be +provided on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_spin_lock\fP() , \fIpthread_spin_unlock\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_spin_lock.3p b/man3p/pthread_spin_lock.3p new file mode 100644 index 000000000..889864598 --- /dev/null +++ b/man3p/pthread_spin_lock.3p @@ -0,0 +1,92 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_SPIN_LOCK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_spin_lock +.SH NAME +pthread_spin_lock, pthread_spin_trylock \- lock a spin lock object +(\fBADVANCED REALTIME THREADS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_spin_lock(pthread_spinlock_t *\fP\fIlock\fP\fB); +.br +int pthread_spin_trylock(pthread_spinlock_t *\fP\fIlock\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_spin_lock\fP() function shall lock the spin lock referenced +by \fIlock\fP. The calling thread shall acquire the +lock if it is not held by another thread. Otherwise, the thread shall +spin (that is, shall not return from the +\fIpthread_spin_lock\fP() call) until the lock becomes available. +The results are undefined if the calling thread holds the lock +at the time the call is made. The \fIpthread_spin_trylock\fP() function +shall lock the spin lock referenced by \fIlock\fP if it +is not held by any thread. Otherwise, the function shall fail. +.LP +The results are undefined if any of these functions is called with +an uninitialized spin lock. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return zero; otherwise, +an error number shall be returned to indicate the +error. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +.B EINVAL +The value specified by \fIlock\fP does not refer to an initialized +spin lock object. +.sp +.LP +The \fIpthread_spin_lock\fP() function may fail if: +.TP 7 +.B EDEADLK +The calling thread already holds the lock. +.sp +.LP +The \fIpthread_spin_trylock\fP() function shall fail if: +.TP 7 +.B EBUSY +A thread currently holds the lock. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications using this function may be subject to priority inversion, +as discussed in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 3.285, Priority Inversion. +.LP +The \fIpthread_spin_lock\fP() and \fIpthread_spin_trylock\fP() functions +are part of the Spin Locks option and need not be +provided on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_spin_destroy\fP() , \fIpthread_spin_unlock\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_spin_trylock.3p b/man3p/pthread_spin_trylock.3p new file mode 100644 index 000000000..ca0cd282c --- /dev/null +++ b/man3p/pthread_spin_trylock.3p @@ -0,0 +1 @@ +.so man3p/pthread_spin_lock.3p diff --git a/man3p/pthread_spin_unlock.3p b/man3p/pthread_spin_unlock.3p new file mode 100644 index 000000000..298d0c837 --- /dev/null +++ b/man3p/pthread_spin_unlock.3p @@ -0,0 +1,73 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_SPIN_UNLOCK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_spin_unlock +.SH NAME +pthread_spin_unlock \- unlock a spin lock object (\fBADVANCED REALTIME +THREADS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_spin_unlock(pthread_spinlock_t *\fP\fIlock\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_spin_unlock\fP() function shall release the spin lock +referenced by \fIlock\fP which was locked via the \fIpthread_spin_lock\fP() +or \fIpthread_spin_trylock\fP() functions. The results are undefined +if the lock is not +held by the calling thread. If there are threads spinning on the lock +when \fIpthread_spin_unlock\fP() is called, the lock becomes +available and an unspecified spinning thread shall acquire the lock. +.LP +The results are undefined if this function is called with an uninitialized +thread spin lock. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIpthread_spin_unlock\fP() function +shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_spin_unlock\fP() function may fail if: +.TP 7 +.B EINVAL +An invalid argument was specified. +.TP 7 +.B EPERM +The calling thread does not hold the lock. +.sp +.LP +This function shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIpthread_spin_unlock\fP() function is part of the Spin Locks +option and need not be provided on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_spin_destroy\fP() , \fIpthread_spin_lock\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pthread_testcancel.3p b/man3p/pthread_testcancel.3p new file mode 100644 index 000000000..3de4c826e --- /dev/null +++ b/man3p/pthread_testcancel.3p @@ -0,0 +1,120 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_SETCANCELSTATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_setcancelstate +.SH NAME +pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel +\- set cancelability state +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pthread_setcancelstate(int\fP \fIstate\fP\fB, int *\fP\fIoldstate\fP\fB); +.br +int pthread_setcanceltype(int\fP \fItype\fP\fB, int *\fP\fIoldtype\fP\fB); +.br +void pthread_testcancel(void); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_setcancelstate\fP() function shall atomically both +set the calling thread's cancelability state to the indicated +\fIstate\fP and return the previous cancelability state at the location +referenced by \fIoldstate\fP. Legal values for +\fIstate\fP are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE. +.LP +The \fIpthread_setcanceltype\fP() function shall atomically both set +the calling thread's cancelability type to the indicated +\fItype\fP and return the previous cancelability type at the location +referenced by \fIoldtype\fP. Legal values for \fItype\fP +are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS. +.LP +The cancelability state and type of any newly created threads, including +the thread in which \fImain\fP() was first invoked, +shall be PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED respectively. +.LP +The \fIpthread_testcancel\fP() function shall create a cancellation +point in the calling thread. The +\fIpthread_testcancel\fP() function shall have no effect if cancelability +is disabled. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_setcancelstate\fP() and \fIpthread_setcanceltype\fP() +functions shall return zero; otherwise, an +error number shall be returned to indicate the error. +.SH ERRORS +.LP +The \fIpthread_setcancelstate\fP() function may fail if: +.TP 7 +.B EINVAL +The specified state is not PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE. +.sp +.LP +The \fIpthread_setcanceltype\fP() function may fail if: +.TP 7 +.B EINVAL +The specified type is not PTHREAD_CANCEL_DEFERRED or PTHREAD_CANCEL_ASYNCHRONOUS. +.sp +.LP +These functions shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIpthread_setcancelstate\fP() and \fIpthread_setcanceltype\fP() +functions control the points at which a thread may be +asynchronously canceled. For cancellation control to be usable in +modular fashion, some rules need to be followed. +.LP +An object can be considered to be a generalization of a procedure. +It is a set of procedures and global variables written as a +unit and called by clients not known by the object. Objects may depend +on other objects. +.LP +First, cancelability should only be disabled on entry to an object, +never explicitly enabled. On exit from an object, the +cancelability state should always be restored to its value on entry +to the object. +.LP +This follows from a modularity argument: if the client of an object +(or the client of an object that uses that object) has +disabled cancelability, it is because the client does not want to +be concerned about cleaning up if the thread is canceled while +executing some sequence of actions. If an object is called in such +a state and it enables cancelability and a cancellation request +is pending for that thread, then the thread is canceled, contrary +to the wish of the client that disabled. +.LP +Second, the cancelability type may be explicitly set to either \fIdeferred\fP +or \fIasynchronous\fP upon entry to an object. +But as with the cancelability state, on exit from an object the cancelability +type should always be restored to its value on entry +to the object. +.LP +Finally, only functions that are cancel-safe may be called from a +thread that is asynchronously cancelable. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_cancel\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ptsname.3p b/man3p/ptsname.3p new file mode 100644 index 000000000..c6091f146 --- /dev/null +++ b/man3p/ptsname.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTSNAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ptsname +.SH NAME +ptsname \- get name of the slave pseudo-terminal device +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *ptsname(int\fP \fIfildes\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIptsname\fP() function shall return the name of the slave pseudo-terminal +device associated with a master pseudo-terminal +device. The \fIfildes\fP argument is a file descriptor that refers +to the master device. The \fIptsname\fP() function shall +return a pointer to a string containing the pathname of the corresponding +slave device. +.LP +The \fIptsname\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +Upon successful completion, \fIptsname\fP() shall return a pointer +to a string which is the name of the pseudo-terminal slave +device. Upon failure, \fIptsname\fP() shall return a null pointer. +This could occur if \fIfildes\fP is an invalid file descriptor +or if the slave device name does not exist in the file system. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The value returned may point to a static data area that is overwritten +by each call to \fIptsname\fP(). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgrantpt\fP() , \fIopen\fP() , \fIttyname\fP() , \fIunlockpt\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/putc.3p b/man3p/putc.3p new file mode 100644 index 000000000..a11e71dd9 --- /dev/null +++ b/man3p/putc.3p @@ -0,0 +1,58 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PUTC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" putc +.SH NAME +putc \- put a byte on a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int putc(int\fP \fIc\fP\fB, FILE *\fP\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIputc\fP() function shall be equivalent to \fIfputc\fP(), except +that if it is +implemented as a macro it may evaluate \fIstream\fP more than once, +so the argument should never be an expression with side +effects. +.SH RETURN VALUE +.LP +Refer to \fIfputc\fP() . +.SH ERRORS +.LP +Refer to \fIfputc\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Since it may be implemented as a macro, \fIputc\fP() may treat a \fIstream\fP +argument with side effects incorrectly. In +particular, \fIputc\fP(\fIc\fP,*\fIf\fP++) does not necessarily work +correctly. Therefore, use of this function is not +recommended in such situations; \fIfputc\fP() should be used instead. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfputc\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/putc_unlocked.3p b/man3p/putc_unlocked.3p new file mode 100644 index 000000000..c7026cfff --- /dev/null +++ b/man3p/putc_unlocked.3p @@ -0,0 +1 @@ +.so man3p/getchar_unlocked.3p diff --git a/man3p/putchar.3p b/man3p/putchar.3p new file mode 100644 index 000000000..983674436 --- /dev/null +++ b/man3p/putchar.3p @@ -0,0 +1,50 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PUTCHAR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" putchar +.SH NAME +putchar \- put a byte on a stdout stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int putchar(int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The function call \fIputchar\fP(\fIc\fP) shall be equivalent to \fIputc\fP(\fIc\fP,\fIstdout\fP). +.SH RETURN VALUE +.LP +Refer to \fIfputc\fP() . +.SH ERRORS +.LP +Refer to \fIfputc\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIputc\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/putchar_unlocked.3p b/man3p/putchar_unlocked.3p new file mode 100644 index 000000000..c7026cfff --- /dev/null +++ b/man3p/putchar_unlocked.3p @@ -0,0 +1 @@ +.so man3p/getchar_unlocked.3p diff --git a/man3p/putenv.3p b/man3p/putenv.3p new file mode 100644 index 000000000..4afe9fbc1 --- /dev/null +++ b/man3p/putenv.3p @@ -0,0 +1,101 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PUTENV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" putenv +.SH NAME +putenv \- change or add a value to an environment +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int putenv(char *\fP\fIstring\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIputenv\fP() function shall use the \fIstring\fP argument to +set environment variable values. The \fIstring\fP argument +should point to a string of the form " \fIname\fP= \fIvalue\fP ". +The \fIputenv\fP() function shall make the value of the +environment variable \fIname\fP equal to \fIvalue\fP by altering an +existing variable or creating a new one. In either case, the +string pointed to by \fIstring\fP shall become part of the environment, +so altering the string shall change the environment. The +space used by \fIstring\fP is no longer used once a new string which +defines \fIname\fP is passed to \fIputenv\fP(). +.LP +The \fIputenv\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +Upon successful completion, \fIputenv\fP() shall return 0; otherwise, +it shall return a non-zero value and set \fIerrno\fP to +indicate the error. +.SH ERRORS +.LP +The \fIputenv\fP() function may fail if: +.TP 7 +.B ENOMEM +Insufficient memory was available. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Changing the Value of an Environment Variable +.LP +The following example changes the value of the \fIHOME\fP environment +variable to the value \fB/usr/home\fP. +.sp +.RS +.nf + +\fB#include +\&... +static char *var = "HOME=/usr/home"; +int ret; +.sp + +ret = putenv(var); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIputenv\fP() function manipulates the environment pointed to +by \fIenviron\fP, and can be used in conjunction with \fIgetenv\fP(). +.LP +See \fIexec\fP() , for restrictions on changing the environment in +multi-threaded applications. +.LP +This routine may use \fImalloc\fP() to enlarge the environment. +.LP +A potential error is to call \fIputenv\fP() with an automatic variable +as the argument, then return from the calling function +while \fIstring\fP is still part of the environment. +.LP +The \fIsetenv\fP() function is preferred over this function. +.SH RATIONALE +.LP +The standard developers noted that \fIputenv\fP() is the only function +available to add to the environment without permitting +memory leaks. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIgetenv\fP() , \fImalloc\fP() , \fIsetenv\fP() , +the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/putmsg.3p b/man3p/putmsg.3p new file mode 100644 index 000000000..f069ab288 --- /dev/null +++ b/man3p/putmsg.3p @@ -0,0 +1,257 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PUTMSG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" putmsg +.SH NAME +putmsg, putpmsg \- send a message on a STREAM (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int putmsg(int\fP \fIfildes\fP\fB, const struct strbuf *\fP\fIctlptr\fP\fB, +.br +\ \ \ \ \ \ const struct strbuf *\fP\fIdataptr\fP\fB, int\fP \fIflags\fP\fB); +.br +int putpmsg(int\fP \fIfildes\fP\fB, const struct strbuf *\fP\fIctlptr\fP\fB, +.br +\ \ \ \ \ \ const struct strbuf *\fP\fIdataptr\fP\fB, int\fP \fIband\fP\fB, +int\fP +\fIflags\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIputmsg\fP() function shall create a message from a process +buffer(s) and send the message to a STREAMS file. The message +may contain either a data part, a control part, or both. The data +and control parts are distinguished by placement in separate +buffers, as described below. The semantics of each part are defined +by the STREAMS module that receives the message. +.LP +The \fIputpmsg\fP() function is equivalent to \fIputmsg\fP(), except +that the process can send messages in different priority +bands. Except where noted, all requirements on \fIputmsg\fP() also +pertain to \fIputpmsg\fP(). +.LP +The \fIfildes\fP argument specifies a file descriptor referencing +an open STREAM. The \fIctlptr\fP and \fIdataptr\fP +arguments each point to a \fBstrbuf\fP structure. +.LP +The \fIctlptr\fP argument points to the structure describing the control +part, if any, to be included in the message. The +\fIbuf\fP member in the \fBstrbuf\fP structure points to the buffer +where the control information resides, and the \fIlen\fP +member indicates the number of bytes to be sent. The \fImaxlen\fP +member is not used by \fIputmsg\fP(). In a similar manner, the +argument \fIdataptr\fP specifies the data, if any, to be included +in the message. The \fIflags\fP argument indicates what type of +message should be sent and is described further below. +.LP +To send the data part of a message, the application shall ensure that +\fIdataptr\fP is not a null pointer and the \fIlen\fP +member of \fIdataptr\fP is 0 or greater. To send the control part +of a message, the application shall ensure that the +corresponding values are set for \fIctlptr\fP. No data (control) part +shall be sent if either \fIdataptr\fP( \fIctlptr\fP) is a +null pointer or the \fIlen\fP member of \fIdataptr\fP( \fIctlptr\fP) +is set to -1. +.LP +For \fIputmsg\fP(), if a control part is specified and \fIflags\fP +is set to RS_HIPRI, a high priority message shall be sent. +If no control part is specified, and \fIflags\fP is set to RS_HIPRI, +\fIputmsg\fP() shall fail and set \fIerrno\fP to [EINVAL]. +If \fIflags\fP is set to 0, a normal message (priority band equal +to 0) shall be sent. If a control part and data part are not +specified and \fIflags\fP is set to 0, no message shall be sent and +0 shall be returned. +.LP +For \fIputpmsg\fP(), the flags are different. The \fIflags\fP argument +is a bitmask with the following mutually-exclusive +flags defined: MSG_HIPRI and MSG_BAND. If \fIflags\fP is set to 0, +\fIputpmsg\fP() shall fail and set \fIerrno\fP to [EINVAL]. +If a control part is specified and \fIflags\fP is set to MSG_HIPRI +and \fIband\fP is set to 0, a high-priority message shall be +sent. If \fIflags\fP is set to MSG_HIPRI and either no control part +is specified or \fIband\fP is set to a non-zero value, +\fIputpmsg\fP() shall fail and set \fIerrno\fP to [EINVAL]. If \fIflags\fP +is set to MSG_BAND, then a message shall be sent in +the priority band specified by \fIband\fP. If a control part and data +part are not specified and \fIflags\fP is set to MSG_BAND, +no message shall be sent and 0 shall be returned. +.LP +The \fIputmsg\fP() function shall block if the STREAM write queue +is full due to internal flow control conditions, with the +following exceptions: +.IP " *" 3 +For high-priority messages, \fIputmsg\fP() shall not block on this +condition and continues processing the message. +.LP +.IP " *" 3 +For other messages, \fIputmsg\fP() shall not block but shall fail +when the write queue is full and O_NONBLOCK is set. +.LP +.LP +The \fIputmsg\fP() function shall also block, unless prevented by +lack of internal resources, while waiting for the +availability of message blocks in the STREAM, regardless of priority +or whether O_NONBLOCK has been specified. No partial message +shall be sent. +.SH RETURN VALUE +.LP +Upon successful completion, \fIputmsg\fP() and \fIputpmsg\fP() shall +return 0; otherwise, they shall return -1 and set +\fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIputmsg\fP() and \fIputpmsg\fP() functions shall fail if: +.TP 7 +.B EAGAIN +A non-priority message was specified, the O_NONBLOCK flag is set, +and the STREAM write queue is full due to internal flow +control conditions; or buffers could not be allocated for the message +that was to be created. +.TP 7 +.B EBADF +\fIfildes\fP is not a valid file descriptor open for writing. +.TP 7 +.B EINTR +A signal was caught during \fIputmsg\fP(). +.TP 7 +.B EINVAL +An undefined value is specified in \fIflags\fP, or \fIflags\fP is +set to RS_HIPRI or MSG_HIPRI and no control part is +supplied, or the STREAM or multiplexer referenced by \fIfildes\fP +is linked (directly or indirectly) downstream from a +multiplexer, or \fIflags\fP is set to MSG_HIPRI and \fIband\fP is +non-zero (for \fIputpmsg\fP() only). +.TP 7 +.B ENOSR +Buffers could not be allocated for the message that was to be created +due to insufficient STREAMS memory resources. +.TP 7 +.B ENOSTR +A STREAM is not associated with \fIfildes\fP. +.TP 7 +.B ENXIO +A hangup condition was generated downstream for the specified STREAM. +.TP 7 +.B EPIPE \fRor\fP EIO +The \fIfildes\fP argument refers to a STREAMS-based pipe and the other +end of the pipe is closed. A SIGPIPE signal is +generated for the calling thread. +.TP 7 +.B ERANGE +The size of the data part of the message does not fall within the +range specified by the maximum and minimum packet sizes of +the topmost STREAM module. This value is also returned if the control +part of the message is larger than the maximum configured +size of the control part of a message, or if the data part of a message +is larger than the maximum configured size of the data part +of a message. +.sp +.LP +In addition, \fIputmsg\fP() and \fIputpmsg\fP() shall fail if the +STREAM head had processed an asynchronous error before the +call. In this case, the value of \fIerrno\fP does not reflect the +result of \fIputmsg\fP() or \fIputpmsg\fP(), but reflects the +prior error. +.br +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Sending a High-Priority Message +.LP +The value of \fIfd\fP is assumed to refer to an open STREAMS file. +This call to \fIputmsg\fP() does the following: +.IP " 1." 4 +Creates a high-priority message with a control part and a data part, +using the buffers pointed to by \fIctrlbuf\fP and +\fIdatabuf\fP, respectively. +.LP +.IP " 2." 4 +Sends the message to the STREAMS file identified by \fIfd\fP. +.LP +.sp +.RS +.nf + +\fB#include +#include +\&... +int fd; +char *ctrlbuf = "This is the control part"; +char *databuf = "This is the data part"; +struct strbuf ctrl; +struct strbuf data; +int ret; +.sp + +ctrl.buf = ctrlbuf; +ctrl.len = strlen(ctrlbuf); +.sp + +data.buf = databuf; +data.len = strlen(databuf); +.sp + +ret = putmsg(fd, &ctrl, &data, MSG_HIPRI); +\fP +.fi +.RE +.SS Using putpmsg() +.LP +This example has the same effect as the previous example. In this +example, however, the \fIputpmsg\fP() function creates and +sends the message to the STREAMS file. +.sp +.RS +.nf + +\fB#include +#include +\&... +int fd; +char *ctrlbuf = "This is the control part"; +char *databuf = "This is the data part"; +struct strbuf ctrl; +struct strbuf data; +int ret; +.sp + +ctrl.buf = ctrlbuf; +ctrl.len = strlen(ctrlbuf); +.sp + +data.buf = databuf; +data.len = strlen(databuf); +.sp + +ret = putpmsg(fd, &ctrl, &data, 0, MSG_HIPRI); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISTREAMS\fP , \fIgetmsg\fP() , \fIpoll\fP() , \fIread\fP() , \fIwrite\fP() +, the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/putpmsg.3p b/man3p/putpmsg.3p new file mode 100644 index 000000000..32d734e37 --- /dev/null +++ b/man3p/putpmsg.3p @@ -0,0 +1 @@ +.so man3p/putmsg.3p diff --git a/man3p/puts.3p b/man3p/puts.3p new file mode 100644 index 000000000..3cab68c02 --- /dev/null +++ b/man3p/puts.3p @@ -0,0 +1,86 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PUTS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" puts +.SH NAME +puts \- put a string on standard output +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int puts(const char *\fP\fIs\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIputs\fP() function shall write the string pointed to by \fIs\fP, +followed by a , to the standard output +stream \fIstdout\fP. The terminating null byte shall not be written. +.LP +The +\fIst_ctime\fP and \fIst_mtime\fP fields of the file shall be marked +for update between the successful execution of \fIputs\fP() +and the next successful completion of a call to \fIfflush\fP() or +\fIfclose\fP() on the same stream or a call to \fIexit\fP() +or \fIabort\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, \fIputs\fP() shall return a non-negative +number. Otherwise, it shall return EOF, shall set an error +indicator for the stream, \ and \fIerrno\fP shall be set to indicate +the error. +.SH ERRORS +.LP +Refer to \fIfputc\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Printing to Standard Output +.LP +The following example gets the current time, converts it to a string +using \fIlocaltime\fP() and \fIasctime\fP(), and prints it to +standard output using \fIputs\fP(). It then prints the number of minutes +to an event for which it is waiting. +.sp +.RS +.nf + +\fB#include +#include +\&... +time_t now; +int minutes_to_event; +\&... +time(&now); +printf("The time is "); +puts(asctime(localtime(&now))); +printf("There are %d minutes to the event.\\n", + minutes_to_event); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIputs\fP() function appends a , while \fIfputs\fP() +does not. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfopen\fP() , \fIfputs\fP() , \fIputc\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pututxline.3p b/man3p/pututxline.3p new file mode 100644 index 000000000..f7769c373 --- /dev/null +++ b/man3p/pututxline.3p @@ -0,0 +1 @@ +.so man3p/getutxid.3p diff --git a/man3p/putwc.3p b/man3p/putwc.3p new file mode 100644 index 000000000..d8c92ba14 --- /dev/null +++ b/man3p/putwc.3p @@ -0,0 +1,60 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PUTWC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" putwc +.SH NAME +putwc \- put a wide character on a stream +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +wint_t putwc(wchar_t\fP \fIwc\fP\fB, FILE *\fP\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIputwc\fP() function shall be equivalent to \fIfputwc\fP(), +except that if it is +implemented as a macro it may evaluate \fIstream\fP more than once, +so the argument should never be an expression with side +effects. +.SH RETURN VALUE +.LP +Refer to \fIfputwc\fP() . +.SH ERRORS +.LP +Refer to \fIfputwc\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Since it may be implemented as a macro, \fIputwc\fP() may treat a +\fIstream\fP argument with side effects incorrectly. In +particular, \fIputwc\fP(\fIwc\fP,*\fIf\fP++) need not work correctly. +Therefore, use of this function is not recommended; \fIfputwc\fP() +should be used instead. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfputwc\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/putwchar.3p b/man3p/putwchar.3p new file mode 100644 index 000000000..97e80a2d6 --- /dev/null +++ b/man3p/putwchar.3p @@ -0,0 +1,51 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PUTWCHAR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" putwchar +.SH NAME +putwchar \- put a wide character on a stdout stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wint_t putwchar(wchar_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The function call \fIputwchar\fP(\fIwc\fP) shall be equivalent to +\fIputwc\fP(\fIwc\fP,\fIstdout\fP). +.SH RETURN VALUE +.LP +Refer to \fIfputwc\fP() . +.SH ERRORS +.LP +Refer to \fIfputwc\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfputwc\fP() , \fIputwc\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/pwrite.3p b/man3p/pwrite.3p new file mode 100644 index 000000000..54c7c56a8 --- /dev/null +++ b/man3p/pwrite.3p @@ -0,0 +1 @@ +.so man3p/write.3p diff --git a/man3p/qsort.3p b/man3p/qsort.3p new file mode 100644 index 000000000..8b2e2ffa6 --- /dev/null +++ b/man3p/qsort.3p @@ -0,0 +1,94 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "QSORT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" qsort +.SH NAME +qsort \- sort a table of data +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void qsort(void *\fP\fIbase\fP\fB, size_t\fP \fInel\fP\fB, size_t\fP +\fIwidth\fP\fB, +.br +\ \ \ \ \ \ int (*\fP\fIcompar\fP\fB)(const void *, const void *)); +.br +\fP +.SH DESCRIPTION +.LP +The \fIqsort\fP() function shall sort an array of \fInel\fP objects, +the initial element of which is pointed to by +\fIbase\fP. The size of each object, in bytes, is specified by the +\fIwidth\fP argument. If the \fInel\fP argument has the value +zero, the comparison function pointed to by \fIcompar\fP shall not +be called and no rearrangement shall take place. +.LP +The application shall ensure that the comparison function pointed +to by \fIcompar\fP does not alter the contents of the array. +The implementation may reorder elements of the array between calls +to the comparison function, but shall not alter the contents of +any individual element. +.LP +When the same objects (consisting of width bytes, irrespective of +their current positions in the array) are passed more than +once to the comparison function, the results shall be consistent with +one another. That is, they shall define a total ordering on +the array. +.LP +The contents of the array shall be sorted in ascending order according +to a comparison function. The \fIcompar\fP argument is a +pointer to the comparison function, which is called with two arguments +that point to the elements being compared. The application +shall ensure that the function returns an integer less than, equal +to, or greater than 0, if the first argument is considered +respectively less than, equal to, or greater than the second. If two +members compare as equal, their order in the sorted array is +unspecified. +.SH RETURN VALUE +.LP +The \fIqsort\fP() function shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The comparison function need not compare every byte, so arbitrary +data may be contained in the elements in addition to the +values being compared. +.SH RATIONALE +.LP +The requirement that each argument (hereafter referred to as \fIp)\fP +to the comparison function is a pointer to elements of +the array implies that for every call, for each argument separately, +all of the following expressions are nonzero: +.sp +.RS +.nf + +\fB((char *)p - (char *)base) % width == 0 +(char *)p >= (char *)base +(char *)p < (char *)base + nel * width +\fP +.fi +.RE +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/raise.3p b/man3p/raise.3p new file mode 100644 index 000000000..86b69c3c0 --- /dev/null +++ b/man3p/raise.3p @@ -0,0 +1,81 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "RAISE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" raise +.SH NAME +raise \- send a signal to the executing process +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int raise(int\fP \fIsig\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIraise\fP() function shall send the signal \fIsig\fP to the +executing \ thread or +process. If a signal handler is called, the \fIraise\fP() function +shall not return until after the signal handler does. +.LP +If the implementation supports the Threads option, the effect of the +\fIraise\fP() function shall be equivalent to calling: +.sp +.RS +.nf + +\fBpthread_kill(pthread_self(), sig); +\fP +.fi +.RE +.LP +Otherwise, the effect of the \fIraise\fP() function shall be equivalent +to calling: +.sp +.RS +.nf + +\fBkill(getpid(), sig); +\fP +.fi +.RE +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, a non-zero +value shall be returned \ and +\fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +The \fIraise\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of the \fIsig\fP argument is an invalid signal number. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The term "thread" is an extension to the ISO\ C standard. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIkill\fP() , \fIsigaction\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/rand.3p b/man3p/rand.3p new file mode 100644 index 000000000..9c62699b1 --- /dev/null +++ b/man3p/rand.3p @@ -0,0 +1,181 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "RAND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" rand +.SH NAME +rand, rand_r, srand \- pseudo-random number generator +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int rand(void); +.br +\fP +.LP +\fBint rand_r(unsigned *\fP\fIseed\fP\fB); \fP +\fB +.br +void srand(unsigned\fP \fIseed\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIrand\fP() function shall compute a sequence of pseudo-random +integers in the range [0, {RAND_MAX}] \ with a +period of at least 2**32. +.LP +The +\fIrand\fP() function need not be reentrant. A function that is not +required to be reentrant is not required to be thread-safe. +.LP +The \fIrand_r\fP() function shall compute a sequence of pseudo-random +integers in the range [0, {RAND_MAX}]. (The value of the +{RAND_MAX} macro shall be at least 32767.) +.LP +If \fIrand_r\fP() is called with the same initial value for the object +pointed to by \fIseed\fP and that object is not +modified between successive returns and calls to \fIrand_r\fP(), the +same sequence shall be generated. +.LP +The \fIsrand\fP() function uses the argument as a seed for a new sequence +of pseudo-random numbers to be returned by subsequent +calls to \fIrand\fP(). If \fIsrand\fP() is then called with the same +seed value, the sequence of pseudo-random numbers shall be +repeated. If \fIrand\fP() is called before any calls to \fIsrand\fP() +are made, the same sequence shall be generated as when +\fIsrand\fP() is first called with a seed value of 1. +.LP +The implementation shall behave as if no function defined in this +volume of IEEE\ Std\ 1003.1-2001 calls \fIrand\fP() +or \fIsrand\fP(). +.SH RETURN VALUE +.LP +The \fIrand\fP() function shall return the next pseudo-random number +in the sequence. +.LP +The \fIrand_r\fP() function shall return a pseudo-random integer. +.LP +The \fIsrand\fP() function shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Generating a Pseudo-Random Number Sequence +.LP +The following example demonstrates how to generate a sequence of pseudo-random +numbers. +.sp +.RS +.nf + +\fB#include +#include +\&... + long count, i; + char *keystr; + int elementlen, len; + char c; +\&... +/* Initial random number generator. */ + srand(1); +.sp + + /* Create keys using only lowercase characters */ + len = 0; + for (i=0; i\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/rand_r.3p b/man3p/rand_r.3p new file mode 100644 index 000000000..4cebbbb2c --- /dev/null +++ b/man3p/rand_r.3p @@ -0,0 +1 @@ +.so man3p/rand.3p diff --git a/man3p/random.3p b/man3p/random.3p new file mode 100644 index 000000000..60fa767bd --- /dev/null +++ b/man3p/random.3p @@ -0,0 +1,137 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "INITSTATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" initstate +.SH NAME +initstate, random, setstate, srandom \- pseudo-random number functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *initstate(unsigned\fP \fIseed\fP\fB, char *\fP\fIstate\fP\fB, +size_t\fP \fIsize\fP\fB); +.br +long random(void); +.br +char *setstate(const char *\fP\fIstate\fP\fB); +.br +void srandom(unsigned\fP \fIseed\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIrandom\fP() function shall use a non-linear additive feedback +random-number generator employing a default state array +size of 31 \fBlong\fP integers to return successive pseudo-random +numbers in the range from 0 to 2**31-1. +The period of this random-number generator is approximately 16 x (2**31-1). +The size of the state array +determines the period of the random-number generator. Increasing the +state array size shall increase the period. +.LP +With 256 bytes of state information, the period of the random-number +generator shall be greater than +2**69. +.LP +Like \fIrand\fP(), \fIrandom\fP() shall produce by default a sequence +of numbers that can +be duplicated by calling \fIsrandom\fP() with 1 as the seed. +.LP +The \fIsrandom\fP() function shall initialize the current state array +using the value of \fIseed\fP. +.LP +The \fIinitstate\fP() and \fIsetstate\fP() functions handle restarting +and changing random-number generators. The +\fIinitstate\fP() function allows a state array, pointed to by the +\fIstate\fP argument, to be initialized for future use. The +\fIsize\fP argument, which specifies the size in bytes of the state +array, shall be used by \fIinitstate\fP() to decide what type +of random-number generator to use; the larger the state array, the +more random the numbers. Values for the amount of state +information are 8, 32, 64, 128, and 256 bytes. Other values greater +than 8 bytes are rounded down to the nearest one of these +values. If \fIinitstate\fP() is called with 8<=\fIsize\fP<32, then +\fIrandom\fP() shall use a simple linear congruential +random number generator. The \fIseed\fP argument specifies a starting +point for the random-number sequence and provides for +restarting at the same point. The \fIinitstate\fP() function shall +return a pointer to the previous state information array. +.LP +If \fIinitstate\fP() has not been called, then \fIrandom\fP() shall +behave as though \fIinitstate\fP() had been called with +\fIseed\fP=1 and \fIsize\fP=128. +.LP +Once a state has been initialized, \fIsetstate\fP() allows switching +between state arrays. The array defined by the +\fIstate\fP argument shall be used for further random-number generation +until \fIinitstate\fP() is called or \fIsetstate\fP() is +called again. The \fIsetstate\fP() function shall return a pointer +to the previous state array. +.SH RETURN VALUE +.LP +If \fIinitstate\fP() is called with \fIsize\fP less than 8, it shall +return NULL. +.LP +The \fIrandom\fP() function shall return the generated pseudo-random +number. +.LP +The \fIsrandom\fP() function shall not return a value. +.LP +Upon successful completion, \fIinitstate\fP() and \fIsetstate\fP() +shall return a pointer to the previous state array; +otherwise, a null pointer shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +After initialization, a state array can be restarted at a different +point in one of two ways: +.IP " 1." 4 +The \fIinitstate\fP() function can be used, with the desired seed, +state array, and size of the array. +.LP +.IP " 2." 4 +The \fIsetstate\fP() function, with the desired state, can be used, +followed by \fIsrandom\fP() with the desired seed. The +advantage of using both of these functions is that the size of the +state array does not have to be saved once it is +initialized. +.LP +.LP +Although some implementations of \fIrandom\fP() have written messages +to standard error, such implementations do not conform to +IEEE\ Std\ 1003.1-2001. +.LP +Issue 5 restored the historical behavior of this function. +.LP +Threaded applications should use \fIerand48\fP(), \fInrand48\fP(), +or \fIjrand48\fP() instead of +\fIrandom\fP() when an independent random number sequence in multiple +threads is required. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIdrand48\fP() , \fIrand\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/read.3p b/man3p/read.3p new file mode 100644 index 000000000..6322e0e3a --- /dev/null +++ b/man3p/read.3p @@ -0,0 +1,477 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "READ" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" read +.SH NAME +pread, read \- read from a file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +\fP +.LP +\fBssize_t pread(int\fP \fIfildes\fP\fB, void *\fP\fIbuf\fP\fB, size_t\fP +\fInbyte\fP\fB, +off_t\fP \fIoffset\fP\fB); \fP +\fB +.br +ssize_t read(int\fP \fIfildes\fP\fB, void *\fP\fIbuf\fP\fB, size_t\fP +\fInbyte\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIread\fP() function shall attempt to read \fInbyte\fP bytes +from the file associated with the open file descriptor, +\fIfildes\fP, into the buffer pointed to by \fIbuf\fP. The behavior +of multiple concurrent reads on the same pipe, FIFO, or +terminal device is unspecified. +.LP +Before any action described below is taken, and if \fInbyte\fP is +zero, the \fIread\fP() function may detect and return errors +as described below. In the absence of errors, or if error detection +is not performed, the \fIread\fP() function shall return zero +and have no other results. +.LP +On files that support seeking (for example, a regular file), the \fIread\fP() +shall start at a position in the file given by +the file offset associated with \fIfildes\fP. The file offset shall +be incremented by the number of bytes actually read. +.LP +Files that do not support seeking-for example, terminals-always read +from the current position. The value of a file offset +associated with such a file is undefined. +.LP +No data transfer shall occur past the current end-of-file. If the +starting position is at or after the end-of-file, 0 shall be +returned. If the file refers to a device special file, the result +of subsequent \fIread\fP() requests is +implementation-defined. +.LP +If the value of \fInbyte\fP is greater than {SSIZE_MAX}, the result +is implementation-defined. +.LP +When attempting to read from an empty pipe or FIFO: +.IP " *" 3 +If no process has the pipe open for writing, \fIread\fP() shall return +0 to indicate end-of-file. +.LP +.IP " *" 3 +If some process has the pipe open for writing and O_NONBLOCK is set, +\fIread\fP() shall return -1 and set \fIerrno\fP to +[EAGAIN]. +.LP +.IP " *" 3 +If some process has the pipe open for writing and O_NONBLOCK is clear, +\fIread\fP() shall block the calling thread until some +data is written or the pipe is closed by all processes that had the +pipe open for writing. +.LP +.LP +When attempting to read a file (other than a pipe or FIFO) that supports +non-blocking reads and has no data currently +available: +.IP " *" 3 +If O_NONBLOCK is set, \fIread\fP() shall return -1 and set \fIerrno\fP +to [EAGAIN]. +.LP +.IP " *" 3 +If O_NONBLOCK is clear, \fIread\fP() shall block the calling thread +until some data becomes available. +.LP +.IP " *" 3 +The use of the O_NONBLOCK flag has no effect if there is some data +available. +.LP +.LP +The \fIread\fP() function reads data previously written to a file. +If any portion of a regular file prior to the end-of-file +has not been written, \fIread\fP() shall return bytes with value 0. +For example, \fIlseek\fP() allows the file offset to be set beyond +the end of existing data in the file. If data +is later written at this point, subsequent reads in the gap between +the previous end of data and the newly written data shall +return bytes with value 0 until data is written into the gap. +.LP +Upon successful completion, where \fInbyte\fP is greater than 0, \fIread\fP() +shall mark for update the \fIst_atime\fP field +of the file, and shall return the number of bytes read. This number +shall never be greater than \fInbyte\fP. The value returned +may be less than \fInbyte\fP if the number of bytes left in the file +is less than \fInbyte\fP, if the \fIread\fP() request was +interrupted by a signal, or if the file is a pipe or FIFO or special +file and has fewer than \fInbyte\fP bytes immediately +available for reading. For example, a \fIread\fP() from a file associated +with a terminal may return one typed line of data. +.LP +If a \fIread\fP() is interrupted by a signal before it reads any data, +it shall return -1 with \fIerrno\fP set to [EINTR]. +.LP +If a \fIread\fP() is interrupted by a signal after it has successfully +read some data, it shall return the number of bytes +read. +.LP +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +\fIfildes\fP. +.LP +If \fIfildes\fP refers to a socket, \fIread\fP() shall be equivalent +to \fIrecv\fP() +with no flags set. +.LP +If the O_DSYNC and O_RSYNC bits have been set, read I/O operations +on the file descriptor shall complete as defined by synchronized +I/O data integrity completion. If the O_SYNC and O_RSYNC bits have +been set, read I/O operations on the file descriptor shall +complete as defined by synchronized I/O file integrity completion. +.LP +If \fIfildes\fP refers to a shared memory object, the result of the +\fIread\fP() function is unspecified. +.LP +If \fIfildes\fP refers to a typed memory object, the result of the +\fIread\fP() function is unspecified. +.LP +A +\fIread\fP() from a STREAMS file can read data in three different +modes: \fIbyte-stream\fP mode, \fImessage-nondiscard\fP mode, +and \fImessage-discard\fP mode. The default shall be byte-stream mode. +This can be changed using the I_SRDOPT \fIioctl\fP() request, and +can be tested with I_GRDOPT \fIioctl\fP(). In byte-stream mode, \fIread\fP() +shall retrieve data from the STREAM until as many +bytes as were requested are transferred, or until there is no more +data to be retrieved. Byte-stream mode ignores message +boundaries. +.LP +In STREAMS message-nondiscard mode, \fIread\fP() shall retrieve data +until as many bytes as were requested are transferred, or +until a message boundary is reached. If \fIread\fP() does not retrieve +all the data in a message, the remaining data shall be left +on the STREAM, and can be retrieved by the next \fIread\fP() call. +Message-discard mode also retrieves data until as many bytes as +were requested are transferred, or a message boundary is reached. +However, unread data remaining in a message after the +\fIread\fP() returns shall be discarded, and shall not be available +for a subsequent \fIread\fP(), \fIgetmsg\fP(), or \fIgetpmsg\fP() +call. +.LP +How \fIread\fP() handles zero-byte STREAMS messages is determined +by the current read mode setting. In byte-stream mode, +\fIread\fP() shall accept data until it has read \fInbyte\fP bytes, +or until there is no more data to read, or until a zero-byte +message block is encountered. The \fIread\fP() function shall then +return the number of bytes read, and place the zero-byte +message back on the STREAM to be retrieved by the next \fIread\fP(), +\fIgetmsg\fP(), or \fIgetpmsg\fP(). In message-nondiscard mode or +message-discard mode, a zero-byte message +shall return 0 and the message shall be removed from the STREAM. When +a zero-byte message is read as the first message on a STREAM, +the message shall be removed from the STREAM and 0 shall be returned, +regardless of the read mode. +.LP +A \fIread\fP() from a STREAMS file shall return the data in the message +at the front of the STREAM head read queue, regardless +of the priority band of the message. +.LP +By default, STREAMs are in control-normal mode, in which a \fIread\fP() +from a STREAMS file can only process messages that +contain a data part but do not contain a control part. The \fIread\fP() +shall fail if a message containing a control part is +encountered at the STREAM head. This default action can be changed +by placing the STREAM in either control-data mode or +control-discard mode with the I_SRDOPT \fIioctl\fP() command. In control-data +mode, +\fIread\fP() shall convert any control part to data and pass it to +the application before passing any data part originally present +in the same message. In control-discard mode, \fIread\fP() shall discard +message control parts but return to the process any data +part in the message. +.LP +In addition, \fIread\fP() shall fail if the STREAM head had processed +an asynchronous error before the call. In this case, the +value of \fIerrno\fP shall not reflect the result of \fIread\fP(), +but reflect the prior error. If a hangup occurs on the STREAM +being read, \fIread\fP() shall continue to operate normally until +the STREAM head read queue is empty. Thereafter, it shall return +0. +.LP +The \fIpread\fP() function shall be equivalent to \fIread\fP(), except +that it shall read from a given position in the file +without changing the file pointer. The first three arguments to \fIpread\fP() +are the same as \fIread\fP() with the addition of a +fourth argument \fIoffset\fP for the desired position inside the file. +An attempt to perform a \fIpread\fP() on a file that is +incapable of seeking shall result in an error. +.SH RETURN VALUE +.LP +Upon successful completion, \fIread\fP() \ and \fIpread\fP() shall +return a non-negative integer indicating the number of bytes actually +read. Otherwise, the +functions shall return -1 and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIread\fP() and \fIpread\fP() functions shall fail +if: +.TP 7 +.B EAGAIN +The O_NONBLOCK flag is set for the file descriptor and the process +would be delayed. +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor open for +reading. +.TP 7 +.B EBADMSG +The file is a STREAM file that is set to control-normal mode and the +message waiting to be read includes a control part. +.TP 7 +.B EINTR +The read operation was terminated due to the receipt of a signal, +and no data was transferred. +.TP 7 +.B EINVAL +The STREAM or multiplexer referenced by \fIfildes\fP is linked (directly +or indirectly) downstream from a multiplexer. +.TP 7 +.B EIO +The process is a member of a background process attempting to read +from its controlling terminal, the process is ignoring or +blocking the SIGTTIN signal, or the process group is orphaned. This +error may also be generated for implementation-defined +reasons. +.TP 7 +.B EISDIR +The \fIfildes\fP argument refers to a directory and the implementation +does not allow the directory to be read using \fIread\fP() +or \fIpread\fP(). The \fIreaddir\fP() function should be used instead. +.TP 7 +.B EOVERFLOW +The file is a regular file, \fInbyte\fP is greater than 0, the starting +position is before the end-of-file, and the starting +position is greater than or equal to the offset maximum established +in the open file description associated with +\fIfildes\fP. +.sp +.LP +The \fIread\fP() function shall fail if: +.TP 7 +.B EAGAIN \fRor\fP EWOULDBLOCK +.sp +The file descriptor is for a socket, is marked O_NONBLOCK, and no +data is waiting to be received. +.TP 7 +.B ECONNRESET +A read was attempted on a socket and the connection was forcibly closed +by its peer. +.TP 7 +.B ENOTCONN +A read was attempted on a socket that is not connected. +.TP 7 +.B ETIMEDOUT +A read was attempted on a socket and a transmission timeout occurred. +.sp +.LP +The \fIread\fP() and \fIpread\fP() functions may fail +if: +.TP 7 +.B EIO +A physical I/O error has occurred. +.TP 7 +.B ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP 7 +.B ENOMEM +Insufficient memory was available to fulfill the request. +.TP 7 +.B ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.sp +.LP +The \fIpread\fP() function shall fail, and the file pointer shall +remain unchanged, if: +.TP 7 +.B EINVAL +The \fIoffset\fP argument is invalid. The value is negative. +.TP 7 +.B EOVERFLOW +The file is a regular file and an attempt was made to read at or beyond +the offset maximum associated with the file. +.TP 7 +.B ENXIO +A request was outside the capabilities of the device. +.TP 7 +.B ESPIPE +\fIfildes\fP is associated with a pipe or FIFO. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Reading Data into a Buffer +.LP +The following example reads data from the file associated with the +file descriptor \fIfd\fP into the buffer pointed to by +\fIbuf\fP. +.sp +.RS +.nf + +\fB#include +#include +\&... +char buf[20]; +size_t nbytes; +ssize_t bytes_read; +int fd; +\&... +nbytes = sizeof(buf); +bytes_read = read(fd, buf, nbytes); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +This volume of IEEE\ Std\ 1003.1-2001 does not specify the value of +the file offset after an error is returned; there +are too many cases. For programming errors, such as [EBADF], the concept +is meaningless since no file is involved. For errors that +are detected immediately, such as [EAGAIN], clearly the pointer should +not change. After an interrupt or hardware error, however, +an updated value would be very useful and is the behavior of many +implementations. +.LP +Note that a \fIread\fP() of zero bytes does not modify \fIst_atime\fP. +A \fIread\fP() that requests more than zero bytes, but +returns zero, shall modify \fIst_atime\fP. +.LP +Implementations are allowed, but not required, to perform error checking +for \fIread\fP() requests of zero bytes. +.SS Input and Output +.LP +The use of I/O with large byte counts has always presented problems. +Ideas such as \fIlread\fP() and \fIlwrite\fP() (using and +returning \fBlong\fPs) were considered at one time. The current solution +is to use abstract types on the ISO\ C standard +function to \fIread\fP() and \fIwrite\fP(). The abstract types can +be declared so that +existing functions work, but can also be declared so that larger types +can be represented in future implementations. It is presumed +that whatever constraints limit the maximum range of \fBsize_t\fP +also limit portable I/O requests to the same range. This volume +of IEEE\ Std\ 1003.1-2001 also limits the range further by requiring +that the byte count be limited so that a signed return +value remains meaningful. Since the return type is also a (signed) +abstract type, the byte count can be defined by the +implementation to be larger than an \fBint\fP can hold. +.LP +The standard developers considered adding atomicity requirements to +a pipe or FIFO, but recognized that due to the nature of +pipes and FIFOs there could be no guarantee of atomicity of reads +of {PIPE_BUF} or any other size that would be an aid to +applications portability. +.LP +This volume of IEEE\ Std\ 1003.1-2001 requires that no action be taken +for \fIread\fP() or \fIwrite\fP() when \fInbyte\fP is zero. This is +not intended to take precedence over detection of +errors (such as invalid buffer pointers or file descriptors). This +is consistent with the rest of this volume of +IEEE\ Std\ 1003.1-2001, but the phrasing here could be misread to +require detection of the zero case before any other +errors. A value of zero is to be considered a correct value, for which +the semantics are a no-op. +.LP +I/O is intended to be atomic to ordinary files and pipes and FIFOs. +Atomic means that all the bytes from a single operation that +started out together end up together, without interleaving from other +I/O operations. It is a known attribute of terminals that +this is not honored, and terminals are explicitly (and implicitly +permanently) excepted, making the behavior unspecified. The +behavior for other device types is also left unspecified, but the +wording is intended to imply that future standards might choose +to specify atomicity (or not). +.LP +There were recommendations to add format parameters to \fIread\fP() +and \fIwrite\fP() in +order to handle networked transfers among heterogeneous file system +and base hardware types. Such a facility may be required for +support by the OSI presentation of layer services. However, it was +determined that this should correspond with similar C-language +facilities, and that is beyond the scope of this volume of IEEE\ Std\ 1003.1-2001. +The concept was suggested to the +developers of the ISO\ C standard for their consideration as a possible +area for future work. +.LP +In 4.3 BSD, a \fIread\fP() or \fIwrite\fP() that is interrupted by +a signal before +transferring any data does not by default return an [EINTR] error, +but is restarted. In 4.2 BSD, 4.3 BSD, and the Eighth Edition, +there is an additional function, \fIselect\fP(), whose purpose is +to pause until specified +activity (data to read, space to write, and so on) is detected on +specified file descriptors. It is common in applications written +for those systems for \fIselect\fP() to be used before \fIread\fP() +in situations (such as +keyboard input) where interruption of I/O due to a signal is desired. +.LP +The issue of which files or file types are interruptible is considered +an implementation design issue. This is often affected +primarily by hardware and reliability issues. +.LP +There are no references to actions taken following an "unrecoverable +error". It is considered beyond the scope of this volume +of IEEE\ Std\ 1003.1-2001 to describe what happens in the case of +hardware errors. +.LP +Previous versions of IEEE\ Std\ 1003.1-2001 allowed two very different +behaviors with regard to the handling of +interrupts. In order to minimize the resulting confusion, it was decided +that IEEE\ Std\ 1003.1-2001 should support only +one of these behaviors. Historical practice on AT&T-derived systems +was to have \fIread\fP() and \fIwrite\fP() return -1 and set \fIerrno\fP +to [EINTR] when interrupted after some, but not all, of +the data requested had been transferred. However, the U.S. Department +of Commerce FIPS 151-1 and FIPS 151-2 require the historical +BSD behavior, in which \fIread\fP() and \fIwrite\fP() return the number +of bytes actually +transferred before the interrupt. If -1 is returned when any data +is transferred, it is difficult to recover from the error on a +seekable device and impossible on a non-seekable device. Most new +implementations support this behavior. The behavior required by +IEEE\ Std\ 1003.1-2001 is to return the number of bytes transferred. +.LP +IEEE\ Std\ 1003.1-2001 does not specify when an implementation that +buffers \fIread\fP()ss actually moves the data into +the user-supplied buffer, so an implementation may chose to do this +at the latest possible moment. Therefore, an interrupt arriving +earlier may not cause \fIread\fP() to return a partial byte count, +but rather to return -1 and set \fIerrno\fP to [EINTR]. +.LP +Consideration was also given to combining the two previous options, +and setting \fIerrno\fP to [EINTR] while returning a short +count. However, not only is there no existing practice that implements +this, it is also contradictory to the idea that when +\fIerrno\fP is set, the function responsible shall return -1. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfcntl\fP() , \fIioctl\fP() , \fIlseek\fP() , \fIopen\fP() , \fIpipe\fP() +, \fIreadv\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General +Terminal +Interface, \fI\fP, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/readdir.3p b/man3p/readdir.3p new file mode 100644 index 000000000..585793685 --- /dev/null +++ b/man3p/readdir.3p @@ -0,0 +1,281 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "READDIR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" readdir +.SH NAME +readdir, readdir_r \- read a directory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +struct dirent *readdir(DIR *\fP\fIdirp\fP\fB); +.br +\fP +.LP +\fBint readdir_r(DIR *restrict\fP \fIdirp\fP\fB, struct dirent *restrict\fP +\fIentry\fP\fB, +.br +\ \ \ \ \ \ struct dirent **restrict\fP \fIresult\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The type \fBDIR\fP, which is defined in the \fI\fP header, +represents +a \fIdirectory stream\fP, which is an ordered sequence of all the +directory entries in a particular directory. Directory entries +represent files; files may be removed from a directory or added to +a directory asynchronously to the operation of +\fIreaddir\fP(). +.LP +The \fIreaddir\fP() function shall return a pointer to a structure +representing the directory entry at the current position in +the directory stream specified by the argument \fIdirp\fP, and position +the directory stream at the next entry. It shall return a +null pointer upon reaching the end of the directory stream. The structure +\fBdirent\fP defined in the \fI\fP header describes a directory +entry. +.LP +The \fIreaddir\fP() function shall not return directory entries containing +empty names. If entries for dot or dot-dot exist, +one entry shall be returned for dot and one entry shall be returned +for dot-dot; otherwise, they shall not be returned. +.LP +The pointer returned by \fIreaddir\fP() points to data which may be +overwritten by another call to \fIreaddir\fP() on the same +directory stream. This data is not overwritten by another call to +\fIreaddir\fP() on a different directory stream. +.LP +If a file is removed from or added to the directory after the most +recent call to \fIopendir\fP() or \fIrewinddir\fP(), whether a +subsequent call to \fIreaddir\fP() returns an entry for that file +is unspecified. +.LP +The \fIreaddir\fP() function may buffer several directory entries +per actual read operation; \fIreaddir\fP() shall mark for +update the \fIst_atime\fP field of the directory each time the directory +is actually read. +.LP +After a call to \fIfork\fP(), either the parent or child (but not +both) may continue +processing the directory stream using \fIreaddir\fP(), \fIrewinddir\fP(), +\ or \fIseekdir\fP(). If both the +parent and child processes use these functions, the result is undefined. +.LP +If the entry names a symbolic link, the value of the \fId_ino\fP member +is unspecified. +.LP +The \fIreaddir\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.LP +The \fIreaddir_r\fP() function shall initialize the \fBdirent\fP structure +referenced by \fIentry\fP to represent the directory +entry at the current position in the directory stream referred to +by \fIdirp\fP, store a pointer to this structure at the location +referenced by \fIresult\fP, and position the directory stream at the +next entry. +.LP +The storage pointed to by \fIentry\fP shall be large enough for a +\fBdirent\fP with an array of \fBchar\fP \fId_name\fP +members containing at least {NAME_MAX}+1 elements. +.LP +Upon successful return, the pointer returned at *\fIresult\fP shall +have the same value as the argument \fIentry\fP. Upon +reaching the end of the directory stream, this pointer shall have +the value NULL. +.LP +The \fIreaddir_r\fP() function shall not return directory entries +containing empty names. +.LP +If a file is removed from or added to the directory after the most +recent call to \fIopendir\fP() or \fIrewinddir\fP(), whether a +subsequent call to \fIreaddir_r\fP() returns an entry for that file +is unspecified. +.LP +The \fIreaddir_r\fP() function may buffer several directory entries +per actual read operation; the \fIreaddir_r\fP() function +shall mark for update the \fIst_atime\fP field of the directory each +time the directory is actually read. +.LP +Applications wishing to check for error situations should set \fIerrno\fP +to 0 before calling \fIreaddir\fP(). If \fIerrno\fP +is set to non-zero on return, an error occurred. +.SH RETURN VALUE +.LP +Upon successful completion, \fIreaddir\fP() shall return a pointer +to an object of type \fBstruct dirent\fP. When an error is +encountered, a null pointer shall be returned and \fIerrno\fP shall +be set to indicate the error. When the end of the directory is +encountered, a null pointer shall be returned and \fIerrno\fP is not +changed. +.LP +If successful, the \fIreaddir_r\fP() function shall return zero; otherwise, +an error number shall be returned to indicate the +error. +.SH ERRORS +.LP +The \fIreaddir\fP() function shall fail if: +.TP 7 +.B EOVERFLOW +One of the values in the structure to be returned cannot be represented +correctly. +.sp +.LP +The \fIreaddir\fP() function may fail if: +.TP 7 +.B EBADF +The \fIdirp\fP argument does not refer to an open directory stream. +.TP 7 +.B ENOENT +The current position of the directory stream is invalid. +.sp +.LP +The \fIreaddir_r\fP() function may fail if: +.TP 7 +.B EBADF +The \fIdirp\fP argument does not refer to an open directory stream. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The following sample program searches the current directory for each +of the arguments supplied on the command line. +.sp +.RS +.nf + +\fB#include +#include +#include +#include +.sp + +static void lookup(const char *arg) +{ + DIR *dirp; + struct dirent *dp; +.sp + + if ((dirp = opendir(".")) == NULL) { + perror("couldn't open '.'"); + return; + } +.sp + + do { + errno = 0; + if ((dp = readdir(dirp)) != NULL) { + if (strcmp(dp->d_name, arg) != 0) + continue; +.sp + + (void) printf("found %s\\n", arg); + (void) closedir(dirp); + return; +.sp + + } + } while (dp != NULL); +.sp + + if (errno != 0) + perror("error reading directory"); + else + (void) printf("failed to find %s\\n", arg); + (void) closedir(dirp); + return; +} +.sp + +int main(int argc, char *argv[]) +{ + int i; + for (i = 1; i < argc; i++) + lookup(arvg[i]); + return (0); +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIreaddir\fP() function should be used in conjunction with \fIopendir\fP(), +\fIclosedir\fP(), and \fIrewinddir\fP() to +examine the contents of the directory. +.LP +The \fIreaddir_r\fP() function is thread-safe and shall return values +in a user-supplied buffer instead of possibly using a +static data area that may be overwritten by each call. +.SH RATIONALE +.LP +The returned value of \fIreaddir\fP() merely \fIrepresents\fP a directory +entry. No equivalence should be inferred. +.LP +Historical implementations of \fIreaddir\fP() obtain multiple directory +entries on a single read operation, which permits +subsequent \fIreaddir\fP() operations to operate from the buffered +information. Any wording that required each successful +\fIreaddir\fP() operation to mark the directory \fIst_atime\fP field +for update would disallow such historical +performance-oriented implementations. +.LP +Since \fIreaddir\fP() returns NULL when it detects an error and when +the end of the directory is encountered, an application +that needs to tell the difference must set \fIerrno\fP to zero before +the call and check it if NULL is returned. Since the +function must not change \fIerrno\fP in the second case and must set +it to a non-zero value in the first case, a zero \fIerrno\fP +after a call returning NULL indicates end-of-directory; otherwise, +an error. +.LP +Routines to deal with this problem more directly were proposed: +.sp +.RS +.nf + +\fBint derror (\fP\fIdirp\fP\fB) +DIR *\fP\fIdirp\fP\fB; +.sp + +void clearderr (\fP\fIdirp\fP\fB) +DIR *\fP\fIdirp\fP\fB; +\fP +.fi +.RE +.LP +The first would indicate whether an error had occurred, and the second +would clear the error indication. The simpler method +involving \fIerrno\fP was adopted instead by requiring that \fIreaddir\fP() +not change \fIerrno\fP when end-of-directory is +encountered. +.LP +An error or signal indicating that a directory has changed while open +was considered but rejected. +.LP +The thread-safe version of the directory reading function returns +values in a user-supplied buffer instead of possibly using a +static data area that may be overwritten by each call. Either the +{NAME_MAX} compile-time constant or the corresponding \fIpathconf\fP() +option can be used to determine the maximum sizes of returned pathnames. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclosedir\fP() , \fIlstat\fP() , \fIopendir\fP() , \fIrewinddir\fP() +, \fIsymlink\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/readdir_r.3p b/man3p/readdir_r.3p new file mode 100644 index 000000000..35080df21 --- /dev/null +++ b/man3p/readdir_r.3p @@ -0,0 +1 @@ +.so man3p/readdir.3p diff --git a/man3p/readlink.3p b/man3p/readlink.3p new file mode 100644 index 000000000..2cec20c5e --- /dev/null +++ b/man3p/readlink.3p @@ -0,0 +1,138 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "READLINK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" readlink +.SH NAME +readlink \- read the contents of a symbolic link +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +ssize_t readlink(const char *restrict\fP \fIpath\fP\fB, char *restrict\fP +\fIbuf\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIbufsize\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIreadlink\fP() function shall place the contents of the symbolic +link referred to by \fIpath\fP in the buffer \fIbuf\fP +which has size \fIbufsize\fP. If the number of bytes in the symbolic +link is less than \fIbufsize\fP, the contents of the +remainder of \fIbuf\fP are unspecified. If the \fIbuf\fP argument +is not large enough to contain the link content, the first +\fIbufsize\fP bytes shall be placed in \fIbuf\fP. +.LP +If the value of \fIbufsize\fP is greater than {SSIZE_MAX}, the result +is implementation-defined. +.SH RETURN VALUE +.LP +Upon successful completion, \fIreadlink\fP() shall return the count +of bytes placed in the buffer. Otherwise, it shall return a +value of -1, leave the buffer unchanged, and set \fIerrno\fP to indicate +the error. +.SH ERRORS +.LP +The \fIreadlink\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied for a component of the path prefix of +\fIpath\fP. +.TP 7 +.B EINVAL +The \fIpath\fP argument names a file that is not a symbolic link. +.TP 7 +.B EIO +An I/O error occurred while reading from the file system. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.sp +.LP +The \fIreadlink\fP() function may fail if: +.TP 7 +.B EACCES +Read permission is denied for the directory. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Reading the Name of a Symbolic Link +.LP +The following example shows how to read the name of a symbolic link +named \fB/modules/pass1\fP. +.sp +.RS +.nf + +\fB#include +.sp + +char buf[1024]; +ssizet_t len; +\&... +if ((len = readlink("/modules/pass1", buf, sizeof(buf)-1)) != -1) + buf[len] = '\\0'; +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +Conforming applications should not assume that the returned contents +of the symbolic link are null-terminated. +.SH RATIONALE +.LP +Since IEEE\ Std\ 1003.1-2001 does not require any association of file +times with symbolic links, there is no requirement +that file times be updated by \fIreadlink\fP(). The type associated +with \fIbufsiz\fP is a \fBsize_t\fP in order to be +consistent with both the ISO\ C standard and the definition of \fIread\fP(). +The behavior +specified for \fIreadlink\fP() when \fIbufsiz\fP is zero represents +historical practice. For this case, the standard developers +considered a change whereby \fIreadlink\fP() would return the number +of non-null bytes contained in the symbolic link with the +buffer \fIbuf\fP remaining unchanged; however, since the \fBstat\fP +structure member \fIst_size\fP value can be used to +determine the size of buffer necessary to contain the contents of +the symbolic link as returned by \fIreadlink\fP(), this proposal +was rejected, and the historical practice retained. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIlstat\fP() , \fIstat\fP() , \fIsymlink\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/readv.3p b/man3p/readv.3p new file mode 100644 index 000000000..1830265f1 --- /dev/null +++ b/man3p/readv.3p @@ -0,0 +1,115 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "READV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" readv +.SH NAME +readv \- read a vector +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +ssize_t readv(int\fP \fIfildes\fP\fB, const struct iovec *\fP\fIiov\fP\fB, +int\fP \fIiovcnt\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIreadv\fP() function shall be equivalent to \fIread\fP(), except +as described +below. The \fIreadv\fP() function shall place the input data into +the \fIiovcnt\fP buffers specified by the members of the +\fIiov\fP array: \fIiov\fP[0], \fIiov\fP[1], ..., \fIiov\fP[ \fIiovcnt\fP-1]. +The \fIiovcnt\fP argument is valid if greater +than 0 and less than or equal to {IOV_MAX}. +.LP +Each \fIiovec\fP entry specifies the base address and length of an +area in memory where data should be placed. The +\fIreadv\fP() function shall always fill an area completely before +proceeding to the next. +.LP +Upon successful completion, \fIreadv\fP() shall mark for update the +\fIst_atime\fP field of the file. +.SH RETURN VALUE +.LP +Refer to \fIread\fP() . +.SH ERRORS +.LP +Refer to \fIread\fP() . +.LP +In addition, the \fIreadv\fP() function shall fail if: +.TP 7 +.B EINVAL +The sum of the \fIiov_len\fP values in the \fIiov\fP array overflowed +an \fBssize_t\fP. +.sp +.LP +The \fIreadv\fP() function may fail if: +.TP 7 +.B EINVAL +The \fIiovcnt\fP argument was less than or equal to 0, or greater +than {IOV_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Reading Data into an Array +.LP +The following example reads data from the file associated with the +file descriptor \fIfd\fP into the buffers specified by +members of the \fIiov\fP array. +.sp +.RS +.nf + +\fB#include +#include +#include +\&... +ssize_t bytes_read; +int fd; +char buf0[20]; +char buf1[30]; +char buf2[40]; +int iovcnt; +struct iovec iov[3]; +.sp + +iov[0].iov_base = buf0; +iov[0].iov_len = sizeof(buf0); +iov[1].iov_base = buf1; +iov[1].iov_len = sizeof(buf1); +iov[2].iov_base = buf2; +iov[2].iov_len = sizeof(buf2); +\&... +iovcnt = sizeof(iov) / sizeof(struct iovec); +.sp + +bytes_read = readv(fd, iov, iovcnt); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Refer to \fIread\fP() . +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIread\fP() , \fIwritev\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/realloc.3p b/man3p/realloc.3p new file mode 100644 index 000000000..58b6c0009 --- /dev/null +++ b/man3p/realloc.3p @@ -0,0 +1,88 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "REALLOC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" realloc +.SH NAME +realloc \- memory reallocator +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void *realloc(void *\fP\fIptr\fP\fB, size_t\fP \fIsize\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIrealloc\fP() function shall change the size of the memory object +pointed to by \fIptr\fP to the size specified by +\fIsize\fP. The contents of the object shall remain unchanged up to +the lesser of the new and old sizes. If the new size of the +memory object would require movement of the object, the space for +the previous instantiation of the object is freed. If the new +size is larger, the contents of the newly allocated portion of the +object are unspecified. If \fIsize\fP is 0 and \fIptr\fP is +not a null pointer, the object pointed to is freed. If the space cannot +be allocated, the object shall remain unchanged. +.LP +If \fIptr\fP is a null pointer, \fIrealloc\fP() shall be equivalent +to \fImalloc\fP() +for the specified size. +.LP +If \fIptr\fP does not match a pointer returned earlier by \fIcalloc\fP(), +\fImalloc\fP(), or \fIrealloc\fP() or if the space has previously +been deallocated by a call to \fIfree\fP() or \fIrealloc\fP(), the +behavior is undefined. +.LP +The order and contiguity of storage allocated by successive calls +to \fIrealloc\fP() is unspecified. The pointer returned if +the allocation succeeds shall be suitably aligned so that it may be +assigned to a pointer to any type of object and then used to +access such an object in the space allocated (until the space is explicitly +freed or reallocated). Each such allocation shall yield +a pointer to an object disjoint from any other object. The pointer +returned shall point to the start (lowest byte address) of the +allocated space. If the space cannot be allocated, a null pointer +shall be returned. +.SH RETURN VALUE +.LP +Upon successful completion with a size not equal to 0, \fIrealloc\fP() +shall return a pointer to the (possibly moved) allocated +space. If \fIsize\fP is 0, either a null pointer or a unique pointer +that can be successfully passed to \fIfree\fP() shall be returned. +If there is not enough available memory, \fIrealloc\fP() shall +return a null pointer \ and set \fIerrno\fP to [ENOMEM]. +.SH ERRORS +.LP +The \fIrealloc\fP() function shall fail if: +.TP 7 +.B ENOMEM +Insufficient memory is available. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcalloc\fP() , \fIfree\fP() , \fImalloc\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/realpath.3p b/man3p/realpath.3p new file mode 100644 index 000000000..a7d243bcc --- /dev/null +++ b/man3p/realpath.3p @@ -0,0 +1,126 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "REALPATH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" realpath +.SH NAME +realpath \- resolve a pathname +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *realpath(const char *restrict\fP \fIfile_name\fP\fB, +.br +\ \ \ \ \ \ char *restrict\fP \fIresolved_name\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIrealpath\fP() function shall derive, from the pathname pointed +to by \fIfile_name\fP, an absolute pathname that names +the same file, whose resolution does not involve \fB'.'\fP , \fB'..'\fP +, or symbolic links. The generated pathname shall be +stored as a null-terminated string, up to a maximum of {PATH_MAX} +bytes, in the buffer pointed to by \fIresolved_name\fP. +.LP +If \fIresolved_name\fP is a null pointer, the behavior of \fIrealpath\fP() +is implementation-defined. +.SH RETURN VALUE +.LP +Upon successful completion, \fIrealpath\fP() shall return a pointer +to the resolved name. Otherwise, \fIrealpath\fP() shall +return a null pointer and set \fIerrno\fP to indicate the error, and +the contents of the buffer pointed to by \fIresolved_name\fP +are undefined. +.SH ERRORS +.LP +The \fIrealpath\fP() function shall fail if: +.TP 7 +.B EACCES +Read or search permission was denied for a component of \fIfile_name\fP. +.TP 7 +.B EINVAL +The \fIfile_name\fP argument is a null pointer. +.TP 7 +.B EIO +An error occurred while reading from the file system. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIfile_name\fP argument exceeds {PATH_MAX} or a +pathname component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIfile_name\fP does not name an existing file or \fIfile_name\fP +points to an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.sp +.LP +The \fIrealpath\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Generating an Absolute Pathname +.LP +The following example generates an absolute pathname for the file +identified by the \fIsymlinkpath\fP argument. The generated +pathname is stored in the \fIactualpath\fP array. +.sp +.RS +.nf + +\fB#include +\&... +char *symlinkpath = "/tmp/symlink/file"; +char actualpath [PATH_MAX+1]; +char *ptr; +.sp + +ptr = realpath(symlinkpath, actualpath); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Since the maximum pathname length is arbitrary unless {PATH_MAX} is +defined, an application generally cannot supply a +\fIresolved_name\fP buffer with size {{PATH_MAX}+1}. +.SH FUTURE DIRECTIONS +.LP +In the future, passing a null pointer to \fIrealpath\fP() for the +\fIresolved_name\fP argument may be defined to have +\fIrealpath\fP() allocate space for the generated pathname. +.SH SEE ALSO +.LP +\fIgetcwd\fP() , \fIsysconf\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/recv.3p b/man3p/recv.3p new file mode 100644 index 000000000..89bc36d2b --- /dev/null +++ b/man3p/recv.3p @@ -0,0 +1,175 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "RECV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" recv +.SH NAME +recv \- receive a message from a connected socket +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +ssize_t recv(int\fP \fIsocket\fP\fB, void *\fP\fIbuffer\fP\fB, size_t\fP +\fIlength\fP\fB, int\fP +\fIflags\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIrecv\fP() function shall receive a message from a connection-mode +or connectionless-mode socket. It is normally used +with connected sockets because it does not permit the application +to retrieve the source address of received data. +.LP +The \fIrecv\fP() function takes the following arguments: +.TP 7 +\fIsocket\fP +Specifies the socket file descriptor. +.TP 7 +\fIbuffer\fP +Points to a buffer where the message should be stored. +.TP 7 +\fIlength\fP +Specifies the length in bytes of the buffer pointed to by the \fIbuffer\fP +argument. +.TP 7 +\fIflags\fP +Specifies the type of message reception. Values of this argument are +formed by logically OR'ing zero or more of the following +values: +.TP 7 +MSG_PEEK +.RS +Peeks at an incoming message. The data is treated as unread and the +next \fIrecv\fP() or similar function shall still return +this data. +.RE +.TP 7 +MSG_OOB +.RS +Requests out-of-band data. The significance and semantics of out-of-band +data are protocol-specific. +.RE +.TP 7 +MSG_WAITALL +.RS +On SOCK_STREAM sockets this requests that the function block until +the full amount of data can be returned. The function may +return the smaller amount of data if the socket is a message-based +socket, if a signal is caught, if the connection is terminated, +if MSG_PEEK was specified, or if an error is pending for the socket. +.RE +.sp +.sp +.LP +The \fIrecv\fP() function shall return the length of the message written +to the buffer pointed to by the \fIbuffer\fP +argument. For message-based sockets, such as SOCK_DGRAM and SOCK_SEQPACKET, +the entire message shall be read in a single operation. +If a message is too long to fit in the supplied buffer, and MSG_PEEK +is not set in the \fIflags\fP argument, the excess bytes +shall be discarded. For stream-based sockets, such as SOCK_STREAM, +message boundaries shall be ignored. In this case, data shall be +returned to the user as soon as it becomes available, and no data +shall be discarded. +.LP +If the MSG_WAITALL flag is not set, data shall be returned only up +to the end of the first message. +.LP +If no messages are available at the socket and O_NONBLOCK is not set +on the socket's file descriptor, \fIrecv\fP() shall block +until a message arrives. If no messages are available at the socket +and O_NONBLOCK is set on the socket's file descriptor, +\fIrecv\fP() shall fail and set \fIerrno\fP to [EAGAIN] or [EWOULDBLOCK]. +.SH RETURN VALUE +.LP +Upon successful completion, \fIrecv\fP() shall return the length of +the message in bytes. If no messages are available to be +received and the peer has performed an orderly shutdown, \fIrecv\fP() +shall return 0. Otherwise, -1 shall be returned and +\fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIrecv\fP() function shall fail if: +.TP 7 +.B EAGAIN \fRor\fP EWOULDBLOCK +.sp +The socket's file descriptor is marked O_NONBLOCK and no data is waiting +to be received; or MSG_OOB is set and no out-of-band data +is available and either the socket's file descriptor is marked O_NONBLOCK +or the socket does not support blocking to await +out-of-band data. +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid file descriptor. +.TP 7 +.B ECONNRESET +A connection was forcibly closed by a peer. +.TP 7 +.B EINTR +The \fIrecv\fP() function was interrupted by a signal that was caught, +before any data was available. +.TP 7 +.B EINVAL +The MSG_OOB flag is set and no out-of-band data is available. +.TP 7 +.B ENOTCONN +A receive is attempted on a connection-mode socket that is not connected. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.TP 7 +.B EOPNOTSUPP +The specified flags are not supported for this socket type or protocol. +.TP 7 +.B ETIMEDOUT +The connection timed out during connection establishment, or due to +a transmission timeout on active connection. +.sp +.LP +The \fIrecv\fP() function may fail if: +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to the file system. +.TP 7 +.B ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP 7 +.B ENOMEM +Insufficient memory was available to fulfill the request. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIrecv\fP() function is equivalent to \fIrecvfrom\fP() with a +zero +\fIaddress_len\fP argument, and to \fIread\fP() if no flags are used. +.LP +The \fIselect\fP() and \fIpoll\fP() functions can +be used to determine when data is available to be received. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpoll\fP() , \fIread\fP() , \fIrecvmsg\fP() , \fIrecvfrom\fP() , +\fIselect\fP() , \fIsend\fP() , \fIsendmsg\fP() , \fIsendto\fP() , +\fIshutdown\fP() , \fIsocket\fP() , \fIwrite\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/recvfrom.3p b/man3p/recvfrom.3p new file mode 100644 index 000000000..6b90f8355 --- /dev/null +++ b/man3p/recvfrom.3p @@ -0,0 +1,199 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "RECVFROM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" recvfrom +.SH NAME +recvfrom \- receive a message from a socket +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +ssize_t recvfrom(int\fP \fIsocket\fP\fB, void *restrict\fP \fIbuffer\fP\fB, +size_t\fP \fIlength\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIflags\fP\fB, struct sockaddr *restrict\fP \fIaddress\fP\fB, +.br +\ \ \ \ \ \ socklen_t *restrict\fP \fIaddress_len\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIrecvfrom\fP() function shall receive a message from a connection-mode +or connectionless-mode socket. It is normally used +with connectionless-mode sockets because it permits the application +to retrieve the source address of received data. +.LP +The \fIrecvfrom\fP() function takes the following arguments: +.TP 7 +\fIsocket\fP +Specifies the socket file descriptor. +.TP 7 +\fIbuffer\fP +Points to the buffer where the message should be stored. +.TP 7 +\fIlength\fP +Specifies the length in bytes of the buffer pointed to by the \fIbuffer\fP +argument. +.TP 7 +\fIflags\fP +Specifies the type of message reception. Values of this argument are +formed by logically OR'ing zero or more of the following +values: +.TP 7 +MSG_PEEK +.RS +Peeks at an incoming message. The data is treated as unread and the +next \fIrecvfrom\fP() or similar function shall still +return this data. +.RE +.TP 7 +MSG_OOB +.RS +Requests out-of-band data. The significance and semantics of out-of-band +data are protocol-specific. +.RE +.TP 7 +MSG_WAITALL +.RS +On SOCK_STREAM sockets this requests that the function block until +the full amount of data can be returned. The function may +return the smaller amount of data if the socket is a message-based +socket, if a signal is caught, if the connection is terminated, +if MSG_PEEK was specified, or if an error is pending for the socket. +.RE +.sp +.TP 7 +\fIaddress\fP +A null pointer, or points to a \fBsockaddr\fP structure in which the +sending address is to be stored. The length and format of +the address depend on the address family of the socket. +.TP 7 +\fIaddress_len\fP +Specifies the length of the \fBsockaddr\fP structure pointed to by +the \fIaddress\fP argument. +.sp +.LP +The \fIrecvfrom\fP() function shall return the length of the message +written to the buffer pointed to by the \fIbuffer\fP +argument. For message-based sockets, such as \ SOCK_RAW, SOCK_DGRAM, +and SOCK_SEQPACKET, the entire message shall be read in a single operation. +If a message is too long to fit +in the supplied buffer, and MSG_PEEK is not set in the \fIflags\fP +argument, the excess bytes shall be discarded. For stream-based +sockets, such as SOCK_STREAM, message boundaries shall be ignored. +In this case, data shall be returned to the user as soon as it +becomes available, and no data shall be discarded. +.LP +If the MSG_WAITALL flag is not set, data shall be returned only up +to the end of the first message. +.LP +Not all protocols provide the source address for messages. If the +\fIaddress\fP argument is not a null pointer and the protocol +provides the source address of messages, the source address of the +received message shall be stored in the \fBsockaddr\fP +structure pointed to by the \fIaddress\fP argument, and the length +of this address shall be stored in the object pointed to by the +\fIaddress_len\fP argument. +.LP +If the actual length of the address is greater than the length of +the supplied \fBsockaddr\fP structure, the stored address +shall be truncated. +.LP +If the \fIaddress\fP argument is not a null pointer and the protocol +does not provide the source address of messages, the value +stored in the object pointed to by \fIaddress\fP is unspecified. +.LP +If no messages are available at the socket and O_NONBLOCK is not set +on the socket's file descriptor, \fIrecvfrom\fP() shall +block until a message arrives. If no messages are available at the +socket and O_NONBLOCK is set on the socket's file descriptor, +\fIrecvfrom\fP() shall fail and set \fIerrno\fP to [EAGAIN] or [EWOULDBLOCK]. +.SH RETURN VALUE +.LP +Upon successful completion, \fIrecvfrom\fP() shall return the length +of the message in bytes. If no messages are available to +be received and the peer has performed an orderly shutdown, \fIrecvfrom\fP() +shall return 0. Otherwise, the function shall return +-1 and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIrecvfrom\fP() function shall fail if: +.TP 7 +.B EAGAIN \fRor\fP EWOULDBLOCK +.sp +The socket's file descriptor is marked O_NONBLOCK and no data is waiting +to be received; or MSG_OOB is set and no out-of-band data +is available and either the socket's file descriptor is marked O_NONBLOCK +or the socket does not support blocking to await +out-of-band data. +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid file descriptor. +.TP 7 +.B ECONNRESET +A connection was forcibly closed by a peer. +.TP 7 +.B EINTR +A signal interrupted \fIrecvfrom\fP() before any data was available. +.TP 7 +.B EINVAL +The MSG_OOB flag is set and no out-of-band data is available. +.TP 7 +.B ENOTCONN +A receive is attempted on a connection-mode socket that is not connected. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.TP 7 +.B EOPNOTSUPP +The specified flags are not supported for this socket type. +.TP 7 +.B ETIMEDOUT +The connection timed out during connection establishment, or due to +a transmission timeout on active connection. +.sp +.LP +The \fIrecvfrom\fP() function may fail if: +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to the file system. +.TP 7 +.B ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP 7 +.B ENOMEM +Insufficient memory was available to fulfill the request. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIselect\fP() and \fIpoll\fP() functions can +be used to determine when data is available to be received. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpoll\fP() , \fIread\fP() , \fIrecv\fP() , \fIrecvmsg\fP() , \fIselect\fP() +, \fIsend\fP() , \fIsendmsg\fP() , \fIsendto\fP() , \fIshutdown\fP() +, +\fIsocket\fP() , \fIwrite\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/recvmsg.3p b/man3p/recvmsg.3p new file mode 100644 index 000000000..6308319ec --- /dev/null +++ b/man3p/recvmsg.3p @@ -0,0 +1,212 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "RECVMSG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" recvmsg +.SH NAME +recvmsg \- receive a message from a socket +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +ssize_t recvmsg(int\fP \fIsocket\fP\fB, struct msghdr *\fP\fImessage\fP\fB, +int\fP \fIflags\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIrecvmsg\fP() function shall receive a message from a connection-mode +or connectionless-mode socket. It is normally used +with connectionless-mode sockets because it permits the application +to retrieve the source address of received data. +.LP +The \fIrecvmsg\fP() function takes the following arguments: +.TP 7 +\fIsocket\fP +Specifies the socket file descriptor. +.TP 7 +\fImessage\fP +Points to a \fBmsghdr\fP structure, containing both the buffer to +store the source address and the buffers for the incoming +message. The length and format of the address depend on the address +family of the socket. The \fImsg_flags\fP member is ignored on +input, but may contain meaningful values on output. +.TP 7 +\fIflags\fP +Specifies the type of message reception. Values of this argument are +formed by logically OR'ing zero or more of the following +values: +.TP 7 +MSG_OOB +.RS +Requests out-of-band data. The significance and semantics of out-of-band +data are protocol-specific. +.RE +.TP 7 +MSG_PEEK +.RS +Peeks at the incoming message. +.RE +.TP 7 +MSG_WAITALL +.RS +On SOCK_STREAM sockets this requests that the function block until +the full amount of data can be returned. The function may +return the smaller amount of data if the socket is a message-based +socket, if a signal is caught, if the connection is terminated, +if MSG_PEEK was specified, or if an error is pending for the socket. +.RE +.sp +.sp +.LP +The \fIrecvmsg\fP() function shall receive messages from unconnected +or connected sockets and shall return the length of the +message. +.LP +The \fIrecvmsg\fP() function shall return the total length of the +message. For message-based sockets, such as SOCK_DGRAM and +SOCK_SEQPACKET, the entire message shall be read in a single operation. +If a message is too long to fit in the supplied buffers, +and MSG_PEEK is not set in the \fIflags\fP argument, the excess bytes +shall be discarded, and MSG_TRUNC shall be set in the +\fImsg_flags\fP member of the \fBmsghdr\fP structure. For stream-based +sockets, such as SOCK_STREAM, message boundaries shall be +ignored. In this case, data shall be returned to the user as soon +as it becomes available, and no data shall be discarded. +.LP +If the MSG_WAITALL flag is not set, data shall be returned only up +to the end of the first message. +.LP +If no messages are available at the socket and O_NONBLOCK is not set +on the socket's file descriptor, \fIrecvmsg\fP() shall +block until a message arrives. If no messages are available at the +socket and O_NONBLOCK is set on the socket's file descriptor, +the \fIrecvmsg\fP() function shall fail and set \fIerrno\fP to [EAGAIN] +or [EWOULDBLOCK]. +.LP +In the \fBmsghdr\fP structure, the \fImsg_name\fP and \fImsg_namelen\fP +members specify the source address if the socket is +unconnected. If the socket is connected, the \fImsg_name\fP and \fImsg_namelen\fP +members shall be ignored. The \fImsg_name\fP +member may be a null pointer if no names are desired or required. +The \fImsg_iov\fP and \fImsg_iovlen\fP fields are used to +specify where the received data shall be stored. \fImsg_iov\fP points +to an array of \fBiovec\fP structures; \fImsg_iovlen\fP +shall be set to the dimension of this array. In each \fBiovec\fP structure, +the \fIiov_base\fP field specifies a storage area and +the \fIiov_len\fP field gives its size in bytes. Each storage area +indicated by \fImsg_iov\fP is filled with received data in +turn until all of the received data is stored or all of the areas +have been filled. +.LP +Upon successful completion, the \fImsg_flags\fP member of the message +header shall be the bitwise-inclusive OR of all of the +following flags that indicate conditions detected for the received +message: +.TP 7 +MSG_EOR +End-of-record was received (if supported by the protocol). +.TP 7 +MSG_OOB +Out-of-band data was received. +.TP 7 +MSG_TRUNC +Normal data was truncated. +.TP 7 +MSG_CTRUNC +Control data was truncated. +.sp +.SH RETURN VALUE +.LP +Upon successful completion, \fIrecvmsg\fP() shall return the length +of the message in bytes. If no messages are available to be +received and the peer has performed an orderly shutdown, \fIrecvmsg\fP() +shall return 0. Otherwise, -1 shall be returned and +\fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIrecvmsg\fP() function shall fail if: +.TP 7 +.B EAGAIN \fRor\fP EWOULDBLOCK +.sp +The socket's file descriptor is marked O_NONBLOCK and no data is waiting +to be received; or MSG_OOB is set and no out-of-band data +is available and either the socket's file descriptor is marked O_NONBLOCK +or the socket does not support blocking to await +out-of-band data. +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid open file descriptor. +.TP 7 +.B ECONNRESET +A connection was forcibly closed by a peer. +.TP 7 +.B EINTR +This function was interrupted by a signal before any data was available. +.TP 7 +.B EINVAL +The sum of the \fIiov_len\fP values overflows a \fBssize_t\fP, or +the MSG_OOB flag is set and no out-of-band data is +available. +.TP 7 +.B EMSGSIZE +The \fImsg_iovlen\fP member of the \fBmsghdr\fP structure pointed +to by \fImessage\fP is less than or equal to 0, or is +greater than {IOV_MAX}. +.TP 7 +.B ENOTCONN +A receive is attempted on a connection-mode socket that is not connected. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.TP 7 +.B EOPNOTSUPP +The specified flags are not supported for this socket type. +.TP 7 +.B ETIMEDOUT +The connection timed out during connection establishment, or due to +a transmission timeout on active connection. +.sp +.LP +The \fIrecvmsg\fP() function may fail if: +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to the file system. +.TP 7 +.B ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP 7 +.B ENOMEM +Insufficient memory was available to fulfill the request. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIselect\fP() and \fIpoll\fP() functions can +be used to determine when data is available to be received. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpoll\fP() , \fIrecv\fP() , \fIrecvfrom\fP() , +\fIselect\fP() , \fIsend\fP() , \fIsendmsg\fP() , +\fIsendto\fP() , \fIshutdown\fP() , \fIsocket\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/regcomp.3p b/man3p/regcomp.3p new file mode 100644 index 000000000..874fd47ed --- /dev/null +++ b/man3p/regcomp.3p @@ -0,0 +1,582 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "REGCOMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" regcomp +.SH NAME +regcomp, regerror, regexec, regfree \- regular expression matching +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int regcomp(regex_t *restrict\fP \fIpreg\fP\fB, const char *restrict\fP +\fIpattern\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIcflags\fP\fB); +.br +size_t regerror(int\fP \fIerrcode\fP\fB, const regex_t *restrict\fP +\fIpreg\fP\fB, +.br +\ \ \ \ \ \ char *restrict\fP \fIerrbuf\fP\fB, size_t\fP \fIerrbuf_size\fP\fB); +.br +int regexec(const regex_t *restrict\fP \fIpreg\fP\fB, const char *restrict\fP +\fIstring\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fInmatch\fP\fB, regmatch_t\fP \fIpmatch\fP\fB[restrict], +int\fP +\fIeflags\fP\fB); +.br +void regfree(regex_t *\fP\fIpreg\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions interpret \fIbasic\fP and \fIextended\fP regular expressions +as described in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 9, Regular Expressions. +.LP +The \fBregex_t\fP structure is defined in \fI\fP and contains +at least +the following member: +.TS C +center; l2 l2 l. +\fBMember Type\fP \fBMember Name\fP \fBDescription\fP +size_t re_nsub Number of parenthesized subexpressions. +.TE +.LP +The \fBregmatch_t\fP structure is defined in \fI\fP and contains +at +least the following members: +.TS C +center; l1 l1 lw(40). +\fBMember Type\fP \fBMember Name\fP T{ +.na +\fBDescription\fP +.ad +T} +\fBregoff_t\fP \fIrm_so\fP T{ +.na +Byte offset from start of \fIstring\fP to start of substring. +.ad +T} +\fBregoff_t\fP \fIrm_eo\fP T{ +.na +Byte offset from start of \fIstring\fP of the first character after the end of substring. +.ad +T} +.TE +.LP +The \fIregcomp\fP() function shall compile the regular expression +contained in the string pointed to by the \fIpattern\fP +argument and place the results in the structure pointed to by \fIpreg\fP. +The \fIcflags\fP argument is the bitwise-inclusive OR +of zero or more of the following flags, which are defined in the \fI\fP +header: +.TP 7 +REG_EXTENDED +Use Extended Regular Expressions. +.TP 7 +REG_ICASE +Ignore case in match. (See the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 9, Regular Expressions.) +.TP 7 +REG_NOSUB +Report only success/fail in \fIregexec\fP(). +.TP 7 +REG_NEWLINE +Change the handling of s, as described in the text. +.sp +.LP +The default regular expression type for \fIpattern\fP is a Basic Regular +Expression. The application can specify Extended +Regular Expressions using the REG_EXTENDED \fIcflags\fP flag. +.LP +If the REG_NOSUB flag was not set in \fIcflags\fP, then \fIregcomp\fP() +shall set \fIre_nsub\fP to the number of +parenthesized subexpressions (delimited by \fB"\\(\\)"\fP in basic +regular expressions or \fB"()"\fP in extended regular +expressions) found in \fIpattern\fP. +.LP +The \fIregexec\fP() function compares the null-terminated string specified +by \fIstring\fP with the compiled regular +expression \fIpreg\fP initialized by a previous call to \fIregcomp\fP(). +If it finds a match, \fIregexec\fP() shall return 0; +otherwise, it shall return non-zero indicating either no match or +an error. The \fIeflags\fP argument is the bitwise-inclusive OR +of zero or more of the following flags, which are defined in the \fI\fP +header: +.TP 7 +REG_NOTBOL +The first character of the string pointed to by \fIstring\fP is not +the beginning of the line. Therefore, the circumflex +character ( \fB'^'\fP ), when taken as a special character, shall +not match the beginning of \fIstring\fP. +.TP 7 +REG_NOTEOL +The last character of the string pointed to by \fIstring\fP is not +the end of the line. Therefore, the dollar sign ( +\fB'$'\fP ), when taken as a special character, shall not match the +end of \fIstring\fP. +.sp +.LP +If \fInmatch\fP is 0 or REG_NOSUB was set in the \fIcflags\fP argument +to \fIregcomp\fP(), then \fIregexec\fP() shall ignore +the \fIpmatch\fP argument. Otherwise, the application shall ensure +that the \fIpmatch\fP argument points to an array with at +least \fInmatch\fP elements, and \fIregexec\fP() shall fill in the +elements of that array with offsets of the substrings of +\fIstring\fP that correspond to the parenthesized subexpressions of +\fIpattern\fP: \fIpmatch\fP[ \fIi\fP]. \fIrm_so\fP shall +be the byte offset of the beginning and \fIpmatch\fP[ \fIi\fP]. \fIrm_eo\fP +shall be one greater than the byte offset of the end +of substring \fIi\fP. (Subexpression \fIi\fP begins at the \fIi\fPth +matched open parenthesis, counting from 1.) Offsets in +\fIpmatch\fP[0] identify the substring that corresponds to the entire +regular expression. Unused elements of \fIpmatch\fP up to +\fIpmatch\fP[ \fInmatch\fP-1] shall be filled with -1. If there are +more than \fInmatch\fP subexpressions in \fIpattern\fP ( +\fIpattern\fP itself counts as a subexpression), then \fIregexec\fP() +shall still do the match, but shall record only the first +\fInmatch\fP substrings. +.LP +When matching a basic or extended regular expression, any given parenthesized +subexpression of \fIpattern\fP might participate +in the match of several different substrings of \fIstring\fP, or it +might not match any substring even though the pattern as a +whole did match. The following rules shall be used to determine which +substrings to report in \fIpmatch\fP when matching regular +expressions: +.IP " 1." 4 +If subexpression \fIi\fP in a regular expression is not contained +within another subexpression, and it participated in the +match several times, then the byte offsets in \fIpmatch\fP[ \fIi\fP] +shall delimit the last such match. +.LP +.IP " 2." 4 +If subexpression \fIi\fP is not contained within another subexpression, +and it did not participate in an otherwise successful +match, the byte offsets in \fIpmatch\fP[ \fIi\fP] shall be -1. A subexpression +does not participate in the match when: +\fB'*'\fP or \fB"\\{\\}"\fP appears immediately after the subexpression +in a basic regular expression, or +\fB'*'\fP , \fB'?'\fP , or \fB"{}"\fP appears immediately after the +subexpression in an extended regular expression, and +the subexpression did not match (matched 0 times) +.LP +or: +\fB'|'\fP is used in an extended regular expression to select this +subexpression or another, and the other +subexpression matched. +.LP +.IP " 3." 4 +If subexpression \fIi\fP is contained within another subexpression +\fIj\fP, and \fIi\fP is not contained within any other +subexpression that is contained within \fIj\fP, and a match of subexpression +\fIj\fP is reported in \fIpmatch\fP[ \fIj\fP], +then the match or non-match of subexpression \fIi\fP reported in \fIpmatch\fP[ +\fIi\fP] shall be as described in 1. and 2. +above, but within the substring reported in \fIpmatch\fP[ \fIj\fP] +rather than the whole string. The offsets in \fIpmatch\fP[ +\fIi\fP] are still relative to the start of \fIstring\fP. +.LP +.IP " 4." 4 +If subexpression \fIi\fP is contained in subexpression \fIj\fP, and +the byte offsets in \fIpmatch\fP[ \fIj\fP] are -1, then +the pointers in \fIpmatch\fP[ \fIi\fP] shall also be -1. +.LP +.IP " 5." 4 +If subexpression \fIi\fP matched a zero-length string, then both byte +offsets in \fIpmatch\fP[ \fIi\fP] shall be the byte +offset of the character or null terminator immediately following the +zero-length string. +.LP +.LP +If, when \fIregexec\fP() is called, the locale is different from when +the regular expression was compiled, the result is +undefined. +.LP +If REG_NEWLINE is not set in \fIcflags\fP, then a in \fIpattern\fP +or \fIstring\fP shall be treated as an +ordinary character. If REG_NEWLINE is set, then shall be +treated as an ordinary character except as follows: +.IP " 1." 4 +A in \fIstring\fP shall not be matched by a period outside +a bracket expression or by any form of a +non-matching list (see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter +9, Regular Expressions). +.LP +.IP " 2." 4 +A circumflex ( \fB'^'\fP ) in \fIpattern\fP, when used to specify +expression anchoring (see the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 9.3.8, BRE Expression Anchoring), +shall match the zero-length string immediately after a in +\fIstring\fP, regardless of the setting of +REG_NOTBOL. +.LP +.IP " 3." 4 +A dollar sign ( \fB'$'\fP ) in \fIpattern\fP, when used to specify +expression anchoring, shall match the zero-length string +immediately before a in \fIstring\fP, regardless of the +setting of REG_NOTEOL. +.LP +.LP +The \fIregfree\fP() function frees any memory allocated by \fIregcomp\fP() +associated with \fIpreg\fP. +.LP +The following constants are defined as error return values: +.TP 7 +REG_NOMATCH +\fIregexec\fP() failed to match. +.TP 7 +REG_BADPAT +Invalid regular expression. +.TP 7 +REG_ECOLLATE +Invalid collating element referenced. +.TP 7 +REG_ECTYPE +Invalid character class type referenced. +.TP 7 +REG_EESCAPE +Trailing \fB'\\'\fP in pattern. +.TP 7 +REG_ESUBREG +Number in \fB"\\digit"\fP invalid or in error. +.TP 7 +REG_EBRACK +\fB"[]"\fP imbalance. +.TP 7 +REG_EPAREN +\fB"\\(\\)"\fP or \fB"()"\fP imbalance. +.TP 7 +REG_EBRACE +\fB"\\{\\}"\fP imbalance. +.TP 7 +REG_BADBR +Content of \fB"\\{\\}"\fP invalid: not a number, number too large, +more than two numbers, first larger than second. +.TP 7 +REG_ERANGE +Invalid endpoint in range expression. +.TP 7 +REG_ESPACE +Out of memory. +.TP 7 +REG_BADRPT +\fB'?'\fP , \fB'*'\fP , or \fB'+'\fP not preceded by valid regular +expression. +.sp +.LP +The \fIregerror\fP() function provides a mapping from error codes +returned by \fIregcomp\fP() and \fIregexec\fP() to +unspecified printable strings. It generates a string corresponding +to the value of the \fIerrcode\fP argument, which the +application shall ensure is the last non-zero value returned by \fIregcomp\fP() +or \fIregexec\fP() with the given value of +\fIpreg\fP. If \fIerrcode\fP is not such a value, the content of the +generated string is unspecified. +.LP +If \fIpreg\fP is a null pointer, but \fIerrcode\fP is a value returned +by a previous call to \fIregexec\fP() or +\fIregcomp\fP(), the \fIregerror\fP() still generates an error string +corresponding to the value of \fIerrcode\fP, but it might +not be as detailed under some implementations. +.LP +If the \fIerrbuf_size\fP argument is not 0, \fIregerror\fP() shall +place the generated string into the buffer of size +\fIerrbuf_size\fP bytes pointed to by \fIerrbuf\fP. If the string +(including the terminating null) cannot fit in the buffer, +\fIregerror\fP() shall truncate the string and null-terminate the +result. +.LP +If \fIerrbuf_size\fP is 0, \fIregerror\fP() shall ignore the \fIerrbuf\fP +argument, and return the size of the buffer needed +to hold the generated string. +.LP +If the \fIpreg\fP argument to \fIregexec\fP() or \fIregfree\fP() is +not a compiled regular expression returned by +\fIregcomp\fP(), the result is undefined. A \fIpreg\fP is no longer +treated as a compiled regular expression after it is given to +\fIregfree\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, the \fIregcomp\fP() function shall return +0. Otherwise, it shall return an integer value indicating +an error as described in \fI\fP, and the content of \fIpreg\fP +is +undefined. If a code is returned, the interpretation shall be as given +in \fI\fP. +.LP +If \fIregcomp\fP() detects an invalid RE, it may return REG_BADPAT, +or it may return one of the error codes that more precisely +describes the error. +.LP +Upon successful completion, the \fIregexec\fP() function shall return +0. Otherwise, it shall return REG_NOMATCH to indicate no +match. +.LP +Upon successful completion, the \fIregerror\fP() function shall return +the number of bytes needed to hold the entire generated +string, including the null termination. If the return value is greater +than \fIerrbuf_size\fP, the string returned in the buffer +pointed to by \fIerrbuf\fP has been truncated. +.LP +The \fIregfree\fP() function shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.sp +.RS +.nf + +\fB#include +.sp + +/* + * Match string against the extended regular expression in + * pattern, treating errors as no match. + * + * Return 1 for match, 0 for no match. + */ +.sp + +int +match(const char *string, char *pattern) +{ + int status; + regex_t re; +.sp + + if (regcomp(&re, pattern, REG_EXTENDED|REG_NOSUB) != 0) { + return(0); /* Report error. */ + } + status = regexec(&re, string, (size_t) 0, NULL, 0); + regfree(&re); + if (status != 0) { + return(0); /* Report error. */ + } + return(1); +} +\fP +.fi +.RE +.LP +The following demonstrates how the REG_NOTBOL flag could be used with +\fIregexec\fP() to find all substrings in a line that +match a pattern supplied by a user. (For simplicity of the example, +very little error checking is done.) +.sp +.RS +.nf + +\fB(void) regcomp (&re, pattern, 0); +/* This call to regexec() finds the first match on the line. */ +error = regexec (&re, &buffer[0], 1, &pm, 0); +while (error == 0) { /* While matches found. */ + /* Substring found between pm.rm_so and pm.rm_eo. */ + /* This call to regexec() finds the next match. */ + error = regexec (&re, buffer + pm.rm_eo, 1, &pm, REG_NOTBOL); +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +An application could use: +.sp +.RS +.nf + +\fBregerror(code,preg,(char *)NULL,(size_t)0) +\fP +.fi +.RE +.LP +to find out how big a buffer is needed for the generated string, \fImalloc\fP() +a buffer +to hold the string, and then call \fIregerror\fP() again to get the +string. Alternatively, it could allocate a fixed, static +buffer that is big enough to hold most strings, and then use \fImalloc\fP() +to allocate a +larger buffer if it finds that this is too small. +.LP +To match a pattern as described in the Shell and Utilities volume +of IEEE\ Std\ 1003.1-2001, Section 2.13, Pattern Matching Notation, +use the \fIfnmatch\fP() function. +.SH RATIONALE +.LP +The \fIregexec\fP() function must fill in all \fInmatch\fP elements +of \fIpmatch\fP, where \fInmatch\fP and \fIpmatch\fP +are supplied by the application, even if some elements of \fIpmatch\fP +do not correspond to subexpressions in \fIpattern\fP. The +application writer should note that there is probably no reason for +using a value of \fInmatch\fP that is larger than +\fIpreg\fP-> \fIre_nsub\fP+1. +.LP +The REG_NEWLINE flag supports a use of RE matching that is needed +in some applications like text editors. In such applications, +the user supplies an RE asking the application to find a line that +matches the given expression. An anchor in such an RE anchors at +the beginning or end of any line. Such an application can pass a sequence +of -separated lines to \fIregexec\fP() as +a single long string and specify REG_NEWLINE to \fIregcomp\fP() to +get the desired behavior. The application must ensure that +there are no explicit s in \fIpattern\fP if it wants to ensure +that any match occurs entirely within a single +line. +.LP +The REG_NEWLINE flag affects the behavior of \fIregexec\fP(), but +it is in the \fIcflags\fP parameter to \fIregcomp\fP() to +allow flexibility of implementation. Some implementations will want +to generate the same compiled RE in \fIregcomp\fP() regardless +of the setting of REG_NEWLINE and have \fIregexec\fP() handle anchors +differently based on the setting of the flag. Other +implementations will generate different compiled REs based on the +REG_NEWLINE. +.LP +The REG_ICASE flag supports the operations taken by the \fIgrep\fP +\fB-i\fP option and +the historical implementations of \fIex\fP and \fIvi\fP. +Including this flag will make it easier for application code to be +written that does the same thing as these utilities. +.LP +The substrings reported in \fIpmatch\fP[] are defined using offsets +from the start of the string rather than pointers. Since +this is a new interface, there should be no impact on historical implementations +or applications, and offsets should be just as +easy to use as pointers. The change to offsets was made to facilitate +future extensions in which the string to be searched is +presented to \fIregexec\fP() in blocks, allowing a string to be searched +that is not all in memory at once. +.LP +The type \fBregoff_t\fP is used for the elements of \fIpmatch\fP[] +to ensure that the application can represent either the +largest possible array in memory (important for an application conforming +to the Shell and Utilities volume of +IEEE\ Std\ 1003.1-2001) or the largest possible file (important for +an application using the extension where a file is +searched in chunks). +.LP +The standard developers rejected the inclusion of a \fIregsub\fP() +function that would be used to do substitutions for a +matched RE. While such a routine would be useful to some applications, +its utility would be much more limited than the matching +function described here. Both RE parsing and substitution are possible +to implement without support other than that required by the +ISO\ C standard, but matching is much more complex than substituting. +The only difficult part of substitution, given the +information supplied by \fIregexec\fP(), is finding the next character +in a string when there can be multi-byte characters. That +is a much larger issue, and one that needs a more general solution. +.LP +The \fIerrno\fP variable has not been used for error returns to avoid +filling the \fIerrno\fP name space for this feature. +.LP +The interface is defined so that the matched substrings \fIrm_sp\fP +and \fIrm_ep\fP are in a separate \fBregmatch_t\fP +structure instead of in \fBregex_t\fP. This allows a single compiled +RE to be used simultaneously in several contexts; in +\fImain\fP() and a signal handler, perhaps, or in multiple threads +of lightweight processes. (The \fIpreg\fP argument to +\fIregexec\fP() is declared with type \fBconst\fP, so the implementation +is not permitted to use the structure to store +intermediate results.) It also allows an application to request an +arbitrary number of substrings from an RE. The number of +subexpressions in the RE is reported in \fIre_nsub\fP in \fIpreg\fP. +With this change to \fIregexec\fP(), consideration was +given to dropping the REG_NOSUB flag since the user can now specify +this with a zero \fInmatch\fP argument to \fIregexec\fP(). +However, keeping REG_NOSUB allows an implementation to use a different +(perhaps more efficient) algorithm if it knows in +\fIregcomp\fP() that no subexpressions need be reported. The implementation +is only required to fill in \fIpmatch\fP if +\fInmatch\fP is not zero and if REG_NOSUB is not specified. Note that +the \fBsize_t\fP type, as defined in the ISO\ C +standard, is unsigned, so the description of \fIregexec\fP() does +not need to address negative values of \fInmatch\fP. +.LP +REG_NOTBOL was added to allow an application to do repeated searches +for the same pattern in a line. If the pattern contains a +circumflex character that should match the beginning of a line, then +the pattern should only match when matched against the +beginning of the line. Without the REG_NOTBOL flag, the application +could rewrite the expression for subsequent matches, but in the +general case this would require parsing the expression. The need for +REG_NOTEOL is not as clear; it was added for symmetry. +.LP +The addition of the \fIregerror\fP() function addresses the historical +need for conforming application programs to have access +to error information more than "Function failed to compile/match your +RE for unknown reasons". +.LP +This interface provides for two different methods of dealing with +error conditions. The specific error codes (REG_EBRACE, for +example), defined in \fI\fP, allow an application to recover +from an error +if it is so able. Many applications, especially those that use patterns +supplied by a user, will not try to deal with specific +error cases, but will just use \fIregerror\fP() to obtain a human-readable +error message to present to the user. +.LP +The \fIregerror\fP() function uses a scheme similar to \fIconfstr\fP() +to deal with +the problem of allocating memory to hold the generated string. The +scheme used by \fIstrerror\fP() in the ISO\ C standard was considered +unacceptable since it creates +difficulties for multi-threaded applications. +.LP +The \fIpreg\fP argument is provided to \fIregerror\fP() to allow an +implementation to generate a more descriptive message than +would be possible with \fIerrcode\fP alone. An implementation might, +for example, save the character offset of the offending +character of the pattern in a field of \fIpreg\fP, and then include +that in the generated message string. The implementation may +also ignore \fIpreg\fP. +.LP +A REG_FILENAME flag was considered, but omitted. This flag caused +\fIregexec\fP() to match patterns as described in the Shell +and Utilities volume of IEEE\ Std\ 1003.1-2001, Section 2.13, Pattern +Matching Notation instead of REs. This service is now provided by +the \fIfnmatch\fP() +function. +.LP +Notice that there is a difference in philosophy between the ISO\ POSIX-2:1993 +standard and IEEE\ Std\ 1003.1-2001 in +how to handle a "bad" regular expression. The ISO\ POSIX-2:1993 standard +says that many bad constructs "produce undefined +results", or that "the interpretation is undefined". IEEE\ Std\ 1003.1-2001, +however, says that the interpretation of +such REs is unspecified. The term "undefined" means that the action +by the application is an error, of similar severity to +passing a bad pointer to a function. +.LP +The \fIregcomp\fP() and \fIregexec\fP() functions are required to +accept any null-terminated string as the \fIpattern\fP +argument. If the meaning of the string is "undefined", the behavior +of the function is "unspecified". +IEEE\ Std\ 1003.1-2001 does not specify how the functions will interpret +the pattern; they might return error codes, or +they might do pattern matching in some completely unexpected way, +but they should not do something like abort the process. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfnmatch\fP() , \fIglob\fP() , Shell and Utilities volume of +IEEE\ Std\ 1003.1-2001, Section 2.13, Pattern Matching Notation, Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 9, Regular Expressions, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/regerror.3p b/man3p/regerror.3p new file mode 100644 index 000000000..bcf1d434b --- /dev/null +++ b/man3p/regerror.3p @@ -0,0 +1 @@ +.so man3p/regcomp.3p diff --git a/man3p/regexec.3p b/man3p/regexec.3p new file mode 100644 index 000000000..bcf1d434b --- /dev/null +++ b/man3p/regexec.3p @@ -0,0 +1 @@ +.so man3p/regcomp.3p diff --git a/man3p/regfree.3p b/man3p/regfree.3p new file mode 100644 index 000000000..bcf1d434b --- /dev/null +++ b/man3p/regfree.3p @@ -0,0 +1 @@ +.so man3p/regcomp.3p diff --git a/man3p/remainder.3p b/man3p/remainder.3p new file mode 100644 index 000000000..a333d5390 --- /dev/null +++ b/man3p/remainder.3p @@ -0,0 +1,84 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "REMAINDER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" remainder +.SH NAME +remainder, remainderf, remainderl \- remainder function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double remainder(double\fP \fIx\fP\fB, double\fP \fIy\fP\fB); +.br +float remainderf(float\fP \fIx\fP\fB, float\fP \fIy\fP\fB); +.br +long double remainderl(long double\fP \fIx\fP\fB, long double\fP \fIy\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall return the floating-point remainder \fIr\fP= +\fIx\fP- \fIny\fP when \fIy\fP is non-zero. The value +\fIn\fP is the integral value nearest the exact value \fIx\fP/ \fIy\fP. +When |\fIn\fP-\fIx\fP/\fIy\fP|=0.5, the value +\fIn\fP is chosen to be even. +.LP +The behavior of \fIremainder\fP() shall be independent of the rounding +mode. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the floating-point +remainder \fIr\fP= \fIx\fP- \fIny\fP when +\fIy\fP is non-zero. +.LP +If +\fIx\fP or \fIy\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is infinite or \fIy\fP is 0 and the other is non-NaN, a +domain error shall occur, and either a NaN (if supported), +or an implementation-defined value shall be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The \fIx\fP argument is \(+-Inf, or the \fIy\fP argument is \(+-0 +and the other argument is non-NaN. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIabs\fP() , \fIdiv\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() +, \fIldiv\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 4.18, Treatment of Error Conditions for Mathematical Functions, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/remainderf.3p b/man3p/remainderf.3p new file mode 100644 index 000000000..a91128c52 --- /dev/null +++ b/man3p/remainderf.3p @@ -0,0 +1 @@ +.so man3p/remainder.3p diff --git a/man3p/remainderl.3p b/man3p/remainderl.3p new file mode 100644 index 000000000..a91128c52 --- /dev/null +++ b/man3p/remainderl.3p @@ -0,0 +1 @@ +.so man3p/remainder.3p diff --git a/man3p/remove.3p b/man3p/remove.3p new file mode 100644 index 000000000..47d8ba260 --- /dev/null +++ b/man3p/remove.3p @@ -0,0 +1,74 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "REMOVE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" remove +.SH NAME +remove \- remove a file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int remove(const char *\fP\fIpath\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIremove\fP() function shall cause the file named by the pathname +pointed to by \fIpath\fP to be no longer accessible by +that name. A subsequent attempt to open that file using that name +shall fail, unless it is created anew. +.LP +If +\fIpath\fP does not name a directory, \fIremove\fP(\fIpath\fP) shall +be equivalent to \fIunlink\fP(\fIpath\fP). +.LP +If \fIpath\fP names a directory, \fIremove\fP(\fIpath\fP) shall be +equivalent to \fIrmdir\fP(\fIpath\fP). +.SH RETURN VALUE +.LP +Refer to \fIrmdir\fP() or \fIunlink\fP() . +.SH ERRORS +.LP +Refer to \fIrmdir\fP() or \fIunlink\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Removing Access to a File +.LP +The following example shows how to remove access to a file named \fB/home/cnd/old_mods\fP. +.sp +.RS +.nf + +\fB#include +.sp + +int status; +\&... +status = remove("/home/cnd/old_mods"); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIrmdir\fP() , \fIunlink\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/remque.3p b/man3p/remque.3p new file mode 100644 index 000000000..3057ae33f --- /dev/null +++ b/man3p/remque.3p @@ -0,0 +1 @@ +.so man3p/insque.3p diff --git a/man3p/remquo.3p b/man3p/remquo.3p new file mode 100644 index 000000000..2be23d4af --- /dev/null +++ b/man3p/remquo.3p @@ -0,0 +1,93 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "REMQUO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" remquo +.SH NAME +remquo, remquof, remquol \- remainder functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double remquo(double\fP \fIx\fP\fB, double\fP \fIy\fP\fB, int *\fP\fIquo\fP\fB); +.br +float remquof(float\fP \fIx\fP\fB, float\fP \fIy\fP\fB, int *\fP\fIquo\fP\fB); +.br +long double remquol(long double\fP \fIx\fP\fB, long double\fP \fIy\fP\fB, +int *\fP\fIquo\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIremquo\fP(), \fIremquof\fP(), and \fIremquol\fP() functions +shall compute the same remainder as the \fIremainder\fP(), \fIremainderf\fP(), +and \fIremainderl\fP() functions, respectively. In the object pointed +to by \fIquo\fP, they store +a value whose sign is the sign of \fIx\fP/ \fIy\fP and whose magnitude +is congruent modulo 2\fI**n\fP to +the magnitude of the integral quotient of \fIx\fP/ \fIy\fP, where +\fIn\fP is an implementation-defined integer greater than or +equal to 3. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +These functions shall return \fIx\fP REM \fIy\fP. +.LP +If +\fIx\fP or \fIy\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-Inf or \fIy\fP is zero and the other argument is +non-NaN, a domain error shall occur, and either a NaN +(if supported), or an implementation-defined value shall be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The \fIx\fP argument is \(+-Inf, or the \fIy\fP argument is \(+-0 +and the other argument is non-NaN. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +These functions are intended for implementing argument reductions +which can exploit a few low-order bits of the quotient. Note +that \fIx\fP may be so large in magnitude relative to \fIy\fP that +an exact representation of the quotient is not practical. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIremainder\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, +Treatment of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/remquof.3p b/man3p/remquof.3p new file mode 100644 index 000000000..54e1f6560 --- /dev/null +++ b/man3p/remquof.3p @@ -0,0 +1 @@ +.so man3p/remquo.3p diff --git a/man3p/remquol.3p b/man3p/remquol.3p new file mode 100644 index 000000000..54e1f6560 --- /dev/null +++ b/man3p/remquol.3p @@ -0,0 +1 @@ +.so man3p/remquo.3p diff --git a/man3p/rename.3p b/man3p/rename.3p new file mode 100644 index 000000000..ac1fb0076 --- /dev/null +++ b/man3p/rename.3p @@ -0,0 +1,262 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "RENAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" rename +.SH NAME +rename \- rename a file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int rename(const char *\fP\fIold\fP\fB, const char *\fP\fInew\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIrename\fP() function shall change the name of a file. The \fIold\fP +argument points to the pathname of the file to be +renamed. The \fInew\fP argument points to the new pathname of the +file. +.LP +If +either the \fIold\fP or \fInew\fP argument names a symbolic link, +\fIrename\fP() shall operate on the symbolic link itself, and +shall not resolve the last component of the argument. If the \fIold\fP +argument and the \fInew\fP argument resolve to the same +existing file, \fIrename\fP() shall return successfully and perform +no other action. +.LP +If the \fIold\fP argument points to the pathname of a file that is +not a directory, the \fInew\fP argument shall not point to +the pathname of a directory. If the link named by the \fInew\fP argument +exists, it shall be removed and \fIold\fP renamed to +\fInew\fP. In this case, a link named \fInew\fP shall remain visible +to other processes throughout the renaming operation and +refer either to the file referred to by \fInew\fP or \fIold\fP before +the operation began. Write access permission is required +for both the directory containing \fIold\fP and the directory containing +\fInew\fP. +.LP +If the \fIold\fP argument points to the pathname of a directory, the +\fInew\fP argument shall not point to the pathname of a +file that is not a directory. If the directory named by the \fInew\fP +argument exists, it shall be removed and \fIold\fP renamed +to \fInew\fP. In this case, a link named \fInew\fP shall exist throughout +the renaming operation and shall refer either to the +directory referred to by \fInew\fP or \fIold\fP before the operation +began. If \fInew\fP names an existing directory, it shall +be required to be an empty directory. +.LP +If the \fIold\fP argument points to a pathname of a symbolic link, +the symbolic link shall be renamed. If the \fInew\fP +argument points to a pathname of a symbolic link, the symbolic link +shall be removed. +.LP +The \fInew\fP pathname shall not contain a path prefix that names +\fIold\fP. Write access permission is required for the +directory containing \fIold\fP and the directory containing \fInew\fP. +If the \fIold\fP argument points to the pathname of a +directory, write access permission may be required for the directory +named by \fIold\fP, and, if it exists, the directory named by +\fInew\fP. +.LP +If the link named by the \fInew\fP argument exists and the file's +link count becomes 0 when it is removed and no process has +the file open, the space occupied by the file shall be freed and the +file shall no longer be accessible. If one or more processes +have the file open when the last link is removed, the link shall be +removed before \fIrename\fP() returns, but the removal of the +file contents shall be postponed until all references to the file +are closed. +.LP +Upon successful completion, \fIrename\fP() shall mark for update the +\fIst_ctime\fP and \fIst_mtime\fP fields of the parent +directory of each file. +.LP +If the \fIrename\fP() function fails for any reason other than [EIO], +any file named by \fInew\fP shall be unaffected. +.SH RETURN VALUE +.LP +Upon successful completion, \fIrename\fP() shall return 0; otherwise, +-1 shall be returned, \fIerrno\fP shall +be set to indicate the error, and neither the file named by +\fIold\fP nor the file named by \fInew\fP shall be changed or created. +.SH ERRORS +.LP +The \fIrename\fP() function shall fail if: +.TP 7 +.B EACCES +A +component of either path prefix denies search permission; or one of +the directories containing \fIold\fP or \fInew\fP denies +write permissions; or, write permission is required and is denied +for a directory pointed to by the \fIold\fP or \fInew\fP +arguments. +.TP 7 +.B EBUSY +The directory named by \fIold\fP or \fInew\fP is currently in use +by the system or another process, and the implementation +considers this an error. +.TP 7 +.B EEXIST \fRor\fP ENOTEMPTY +.sp +The link named by \fInew\fP is a directory that is not an empty directory. +.TP 7 +.B EINVAL +The \fInew\fP directory pathname contains a path prefix that names +the \fIold\fP directory. +.TP 7 +.B EIO +A +physical I/O error has occurred. +.TP 7 +.B EISDIR +The \fInew\fP argument points to a directory and the \fIold\fP argument +points to a file that is not a directory. +.TP 7 +.B ELOOP +A +loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B EMLINK +The file named by \fIold\fP is a directory, and the link count of +the parent directory of \fInew\fP would exceed {LINK_MAX}. +.TP 7 +.B ENAMETOOLONG +.sp +The length of the \fIold\fP or \fInew\fP argument exceeds {PATH_MAX} +or a pathname component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +The link named by \fIold\fP does not name an existing file, or either +\fIold\fP or \fInew\fP points to an empty string. +.TP 7 +.B ENOSPC +The directory that would contain \fInew\fP cannot be extended. +.TP 7 +.B ENOTDIR +A +component of either path prefix is not a directory; or the \fIold\fP +argument names a directory and \fInew\fP argument names a +non-directory file. +.TP 7 +.B EPERM \fRor\fP EACCES +.sp +The S_ISVTX flag is set on the directory containing the file referred +to by \fIold\fP and the caller is not the file owner, nor is +the caller the directory owner, nor does the caller have appropriate +privileges; or \fInew\fP refers to an existing file, the +S_ISVTX flag is set on the directory containing this file, and the +caller is not the file owner, nor is the caller the directory +owner, nor does the caller have appropriate privileges. +.TP 7 +.B EROFS +The requested operation requires writing in a directory on a read-only +file system. +.TP 7 +.B EXDEV +The links named by \fInew\fP and \fIold\fP are on different file systems +and the implementation does not support links between +file systems. +.sp +.LP +The \fIrename\fP() function may fail if: +.TP 7 +.B EBUSY +The file named by the \fIold\fP or \fInew\fP arguments is a named +STREAM. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +.sp +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.TP 7 +.B ETXTBSY +The file to be renamed is a pure procedure (shared text) file that +is being executed. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Renaming a File +.LP +The following example shows how to rename a file named \fB/home/cnd/mod1\fP +to \fB/home/cnd/mod2\fP. +.sp +.RS +.nf + +\fB#include +.sp + +int status; +\&... +status = rename("/home/cnd/mod1", "/home/cnd/mod2"); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +Some implementations mark for update the \fIst_ctime\fP field of renamed +files and some do not. Applications which make use of +the \fIst_ctime\fP field may behave differently with respect to renamed +files unless they are designed to allow for either +behavior. +.SH RATIONALE +.LP +This \fIrename\fP() function is equivalent for regular files to that +defined by the ISO\ C standard. Its inclusion here +expands that definition to include actions on directories and specifies +behavior when the \fInew\fP parameter names a file that +already exists. That specification requires that the action of the +function be atomic. +.LP +One of the reasons for introducing this function was to have a means +of renaming directories while permitting implementations to +prohibit the use of \fIlink\fP() and \fIunlink\fP() +with directories, thus constraining links to directories to those +made by \fImkdir\fP(). +.LP +The specification that if \fIold\fP and \fInew\fP refer to the same +file is intended to guarantee that: +.sp +.RS +.nf + +\fBrename("x", "x"); +\fP +.fi +.RE +.LP +does not remove the file. +.LP +Renaming dot or dot-dot is prohibited in order to prevent cyclical +file system paths. +.LP +See also the descriptions of [ENOTEMPTY] and [ENAMETOOLONG] in \fIrmdir\fP() +and [EBUSY] in \fIunlink\fP() . For a discussion of [EXDEV], see \fIlink\fP() +\&. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIlink\fP() , \fIrmdir\fP() , \fIsymlink\fP() , +\fIunlink\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/rewind.3p b/man3p/rewind.3p new file mode 100644 index 000000000..31e9c2587 --- /dev/null +++ b/man3p/rewind.3p @@ -0,0 +1,76 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "REWIND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" rewind +.SH NAME +rewind \- reset the file position indicator in a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void rewind(FILE *\fP\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The call: +.sp +.RS +.nf + +\fBrewind(stream) +\fP +.fi +.RE +.LP +shall be equivalent to: +.sp +.RS +.nf + +\fB(void) fseek(stream, 0L, SEEK_SET) +\fP +.fi +.RE +.LP +except that \fIrewind\fP() shall also clear the error indicator. +.LP +Since \fIrewind\fP() does not return a value, an application wishing +to detect errors should clear \fIerrno\fP, then call +\fIrewind\fP(), and if \fIerrno\fP is non-zero, assume an error has +occurred. +.SH RETURN VALUE +.LP +The \fIrewind\fP() function shall not return a value. +.SH ERRORS +.LP +Refer to \fIfseek\fP() with the exception of [EINVAL] which does not +apply. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfseek\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/rewinddir.3p b/man3p/rewinddir.3p new file mode 100644 index 000000000..c3150f656 --- /dev/null +++ b/man3p/rewinddir.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "REWINDDIR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" rewinddir +.SH NAME +rewinddir \- reset the position of a directory stream to the beginning +of a directory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void rewinddir(DIR *\fP\fIdirp\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIrewinddir\fP() function shall reset the position of the directory +stream to which \fIdirp\fP refers to the beginning of +the directory. It shall also cause the directory stream to refer to +the current state of the corresponding directory, as a call to +\fIopendir\fP() would have done. If \fIdirp\fP does not refer to a +directory stream, the +effect is undefined. +.LP +After a call to the \fIfork\fP() function, either the parent or child +(but not both) may +continue processing the directory stream using \fIreaddir\fP(), \fIrewinddir\fP(), +or +\fIseekdir\fP(). If both the +parent and child processes use these functions, the result is undefined. +.SH RETURN VALUE +.LP +The \fIrewinddir\fP() function shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIrewinddir\fP() function should be used in conjunction with +\fIopendir\fP(), \fIreaddir\fP(), and \fIclosedir\fP() to examine +the contents of the directory. This method is recommended for portability. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclosedir\fP() , \fIopendir\fP() , \fIreaddir\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/rindex.3p b/man3p/rindex.3p new file mode 100644 index 000000000..30f85bbec --- /dev/null +++ b/man3p/rindex.3p @@ -0,0 +1,63 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "RINDEX" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" rindex +.SH NAME +rindex \- character string operations (\fBLEGACY\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *rindex(const char *\fP\fIs\fP\fB, int\fP \fIc\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIrindex\fP() function shall be equivalent to \fIstrrchr\fP() +\&. +.SH RETURN VALUE +.LP +Refer to \fIstrrchr\fP() . +.SH ERRORS +.LP +Refer to \fIstrrchr\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIstrrchr\fP() function is preferred over this function. +.LP +For maximum portability, it is recommended to replace the function +call to \fIrindex\fP() as follows: +.sp +.RS +.nf + +\fB#define rindex(a,b) strrchr((a),(b)) +\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +This function may be withdrawn in a future version. +.SH SEE ALSO +.LP +\fIstrrchr\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/rint.3p b/man3p/rint.3p new file mode 100644 index 000000000..3c6da95da --- /dev/null +++ b/man3p/rint.3p @@ -0,0 +1,100 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "RINT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" rint +.SH NAME +rint, rintf, rintl \- round-to-nearest integral value +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double rint(double\fP \fIx\fP\fB); +.br +float rintf(float\fP \fIx\fP\fB); +.br +long double rintl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall return the integral value (represented as a +\fBdouble\fP) nearest \fIx\fP in the direction of the +current rounding mode. The current rounding mode is implementation-defined. +.LP +If the current rounding mode rounds toward negative infinity, then +\fIrint\fP() shall be equivalent to \fIfloor\fP() . If the current +rounding mode rounds toward positive infinity, then \fIrint\fP() shall +be +equivalent to \fIceil\fP() . +.LP +These functions differ from the \fInearbyint\fP(), \fInearbyintf\fP(), +and \fInearbyintl\fP() +functions only in that they may raise the inexact floating-point exception +if the result differs in value from the argument. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the integer +(represented as a double precision number) nearest \fIx\fP +in the direction of the current rounding mode. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0 or \(+-Inf, \fIx\fP shall be returned. +.LP +If the correct value would cause overflow, a range error shall occur +and \fIrint\fP(), \fIrintf\fP(), and \fIrintl\fP() shall +return the value of the macro \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL +(with the same sign as \fIx\fP), +respectively. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Range\ Error +The result would cause an overflow. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIabs\fP() , \fIceil\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() +, \fIfloor\fP() , \fIisnan\fP() , \fInearbyint\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/rintf.3p b/man3p/rintf.3p new file mode 100644 index 000000000..b42994e12 --- /dev/null +++ b/man3p/rintf.3p @@ -0,0 +1 @@ +.so man3p/rint.3p diff --git a/man3p/rintl.3p b/man3p/rintl.3p new file mode 100644 index 000000000..b42994e12 --- /dev/null +++ b/man3p/rintl.3p @@ -0,0 +1 @@ +.so man3p/rint.3p diff --git a/man3p/rmdir.3p b/man3p/rmdir.3p new file mode 100644 index 000000000..9c0c19726 --- /dev/null +++ b/man3p/rmdir.3p @@ -0,0 +1,187 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "RMDIR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" rmdir +.SH NAME +rmdir \- remove a directory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int rmdir(const char *\fP\fIpath\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIrmdir\fP() function shall remove a directory whose name is +given by \fIpath\fP. The directory shall be removed only if +it is an empty directory. +.LP +If the directory is the root directory or the current working directory +of any process, it is unspecified whether the function +succeeds, or whether it shall fail and set \fIerrno\fP to [EBUSY]. +.LP +If \fIpath\fP names a symbolic link, then \fIrmdir\fP() shall fail +and set \fIerrno\fP to [ENOTDIR]. +.LP +If the \fIpath\fP argument refers to a path whose final component +is either dot or dot-dot, \fIrmdir\fP() shall fail. +.LP +If the directory's link count becomes 0 and no process has the directory +open, the space occupied by the directory shall be +freed and the directory shall no longer be accessible. If one or more +processes have the directory open when the last link is +removed, the dot and dot-dot entries, if present, shall be removed +before \fIrmdir\fP() returns and no new entries may be created +in the directory, but the directory shall not be removed until all +references to the directory are closed. +.LP +If the directory is not an empty directory, \fIrmdir\fP() shall fail +and set \fIerrno\fP to [EEXIST] or [ENOTEMPTY]. +.LP +Upon successful completion, the \fIrmdir\fP() function shall mark +for update the \fIst_ctime\fP and \fIst_mtime\fP fields of +the parent directory. +.SH RETURN VALUE +.LP +Upon successful completion, the function \fIrmdir\fP() shall return +0. Otherwise, -1 shall be returned, and \fIerrno\fP set to +indicate the error. If -1 is returned, the named directory shall not +be changed. +.SH ERRORS +.LP +The \fIrmdir\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied on a component of the path prefix, or +write permission is denied on the parent directory of the +directory to be removed. +.TP 7 +.B EBUSY +The directory to be removed is currently in use by the system or some +process and the implementation considers this to be an +error. +.TP 7 +.B EEXIST \fRor\fP ENOTEMPTY +The \fIpath\fP argument names a directory that is not an empty directory, +or there are hard links to the directory other than dot +or a single entry in dot-dot. +.TP 7 +.B EINVAL +The \fIpath\fP argument contains a last component that is dot. +.TP 7 +.B EIO +A physical I/O error has occurred. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file, or the \fIpath\fP +argument names a nonexistent directory or points +to an empty string. +.TP 7 +.B ENOTDIR +A component of \fIpath\fP is not a directory. +.TP 7 +.B EPERM \fRor\fP EACCES +.sp +The S_ISVTX flag is set on the parent directory of the directory to +be removed and the caller is not the owner of the directory to +be removed, nor is the caller the owner of the parent directory, nor +does the caller have the appropriate privileges. +.TP 7 +.B EROFS +The directory entry to be removed resides on a read-only file system. +.sp +.LP +The \fIrmdir\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Removing a Directory +.LP +The following example shows how to remove a directory named \fB/home/cnd/mod1\fP. +.sp +.RS +.nf + +\fB#include +.sp + +int status; +\&... +status = rmdir("/home/cnd/mod1"); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIrmdir\fP() and \fIrename\fP() functions originated in 4.2 BSD, +and they used +[ENOTEMPTY] for the condition when the directory to be removed does +not exist or \fInew\fP already exists. When the 1984 +/usr/group standard was published, it contained [EEXIST] instead. +When these functions were adopted into System V, the 1984 +/usr/group standard was used as a reference. Therefore, several existing +applications and implementations support/use both forms, +and no agreement could be reached on either value. All implementations +are required to supply both [EEXIST] and [ENOTEMPTY] in \fI\fP +with distinct values, so that applications can use both values in +C-language \fBcase\fP statements. +.LP +The meaning of deleting \fIpathname\fP \fB/dot\fP is unclear, because +the name of the file (directory) in the parent directory +to be removed is not clear, particularly in the presence of multiple +links to a directory. +.LP +The POSIX.1-1990 standard was silent with regard to the behavior of +\fIrmdir\fP() when there are multiple hard links to the +directory being removed. The requirement to set \fIerrno\fP to [EEXIST] +or [ENOTEMPTY] clarifies the behavior in this case. +.LP +If the process' current working directory is being removed, that should +be an allowed error. +.LP +Virtually all existing implementations detect [ENOTEMPTY] or the case +of dot-dot. The text in \fIError Numbers\fP about returning any one +of the possible errors permits that behavior to +continue. The [ELOOP] error may be returned if more than {SYMLOOP_MAX} +symbolic links are encountered during resolution of the +\fIpath\fP argument. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIError Numbers\fP , \fImkdir\fP() , \fIremove\fP() , \fIunlink\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/round.3p b/man3p/round.3p new file mode 100644 index 000000000..1f6c6d48e --- /dev/null +++ b/man3p/round.3p @@ -0,0 +1,89 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ROUND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" round +.SH NAME +round, roundf, roundl \- round to the nearest integer value in a floating-point +format +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double round(double\fP \fIx\fP\fB); +.br +float roundf(float\fP \fIx\fP\fB); +.br +long double roundl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall round their argument to the nearest integer +value in floating-point format, rounding halfway cases away +from zero, regardless of the current rounding direction. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the rounded +integer value. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0 or \(+-Inf, \fIx\fP shall be returned. +.LP +If the correct value would cause overflow, a range error shall occur +and \fIround\fP(), \fIroundf\fP(), and \fIroundl\fP() shall +return the value of the macro \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL +(with the same sign as \fIx\fP), +respectively. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +Range\ Error +The result overflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of +Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/roundf.3p b/man3p/roundf.3p new file mode 100644 index 000000000..b4a56d38c --- /dev/null +++ b/man3p/roundf.3p @@ -0,0 +1 @@ +.so man3p/round.3p diff --git a/man3p/roundl.3p b/man3p/roundl.3p new file mode 100644 index 000000000..b4a56d38c --- /dev/null +++ b/man3p/roundl.3p @@ -0,0 +1 @@ +.so man3p/round.3p diff --git a/man3p/scalb.3p b/man3p/scalb.3p new file mode 100644 index 000000000..f6643ac53 --- /dev/null +++ b/man3p/scalb.3p @@ -0,0 +1,135 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SCALB" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" scalb +.SH NAME +scalb \- load exponent of a radix-independent floating-point number +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double scalb(double\fP \fIx\fP\fB, double\fP \fIn\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIscalb\fP() function shall compute \fIx\fP*\fIr**n\fP, where +\fIr\fP is the radix of the +machine's floating-point arithmetic. When \fIr\fP is 2, \fIscalb\fP() +shall be equivalent to \fIldexp\fP() . The value of \fIr\fP is FLT_RADIX +which is defined in \fI\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIscalb\fP() function shall return +\fIx\fP*\fIr**n\fP. +.LP +If \fIx\fP or \fIn\fP is NaN, a NaN shall be returned. +.LP +If \fIn\fP is zero, \fIx\fP shall be returned. +.LP +If \fIx\fP is \(+-Inf and \fIn\fP is not -Inf, \fIx\fP shall be returned. +.LP +If \fIx\fP is \(+-0 and \fIn\fP is not +Inf, \fIx\fP shall be returned. +.LP +If \fIx\fP is \(+-0 and \fIn\fP is +Inf, a domain error shall occur, +and either a NaN (if supported), or an +implementation-defined value shall be returned. +.LP +If \fIx\fP is \(+-Inf and \fIn\fP is -Inf, a domain error shall occur, +and either a NaN (if supported), or an +implementation-defined value shall be returned. +.LP +If the result would cause an overflow, a range error shall occur and +\(+-HUGE_VAL (according to the sign of \fIx\fP) shall +be returned. +.LP +If the correct value would cause underflow, and is representable, +a range error may occur and the correct value shall be +returned. +.LP +If the correct value would cause underflow, and is not representable, +a range error may occur, and 0.0 shall be returned. +.SH ERRORS +.LP +The \fIscalb\fP() function shall fail if: +.TP 7 +Domain\ Error +If \fIx\fP is zero and \fIn\fP is +Inf, or \fIx\fP is Inf and \fIn\fP +is -Inf. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be +raised. +.TP 7 +Range\ Error +The result would overflow. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be +raised. +.sp +.LP +The \fIscalb\fP() function may fail if: +.TP 7 +Range\ Error +The result underflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications should use either \fIscalbln\fP(), \fIscalblnf\fP(), +or \fIscalblnl\fP() in preference to +this function. +.LP +IEEE\ Std\ 1003.1-2001 only defines the behavior for the \fIscalb\fP() +function when the \fIn\fP argument is an +integer, a NaN, or Inf. The behavior of other values for the \fIn\fP +argument is unspecified. +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIilogb\fP() , \fIldexp\fP() +, \fIlogb\fP() , \fIscalbln\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for Mathematical Functions, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/scalbln.3p b/man3p/scalbln.3p new file mode 100644 index 000000000..51164a12b --- /dev/null +++ b/man3p/scalbln.3p @@ -0,0 +1 @@ +.so man3p/scalbn.3p diff --git a/man3p/scalblnf.3p b/man3p/scalblnf.3p new file mode 100644 index 000000000..51164a12b --- /dev/null +++ b/man3p/scalblnf.3p @@ -0,0 +1 @@ +.so man3p/scalbn.3p diff --git a/man3p/scalblnl.3p b/man3p/scalblnl.3p new file mode 100644 index 000000000..51164a12b --- /dev/null +++ b/man3p/scalblnl.3p @@ -0,0 +1 @@ +.so man3p/scalbn.3p diff --git a/man3p/scalbn.3p b/man3p/scalbn.3p new file mode 100644 index 000000000..34855bda5 --- /dev/null +++ b/man3p/scalbn.3p @@ -0,0 +1,126 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SCALBLN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" scalbln +.SH NAME +scalbln, scalblnf, scalblnl, scalbn, scalbnf, scalbnl \- compute exponent +using FLT_RADIX +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double scalbln(double\fP \fIx\fP\fB, long\fP \fIn\fP\fB); +.br +float scalblnf(float\fP \fIx\fP\fB, long\fP \fIn\fP\fB); +.br +long double scalblnl(long double\fP \fIx\fP\fB, long\fP \fIn\fP\fB); +.br +double scalbn(double\fP \fIx\fP\fB, int\fP \fIn\fP\fB); +.br +float scalbnf(float\fP \fIx\fP\fB, int\fP \fIn\fP\fB); +.br +long double scalbnl(long double\fP \fIx\fP\fB, int\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute \fIx\fP\ *\ FLT_RADIX\fI**n\fP efficiently, +not normally by +computing FLT_RADIX\fI**n\fP explicitly. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return \fIx\fP\ *\ FLT_RADIX\fI**n\fP. +.LP +If the result would cause overflow, a range error shall occur and +these functions shall return \(+-HUGE_VAL, +\(+-HUGE_VALF, and \(+-HUGE_VALL (according to the sign of \fIx\fP) +as appropriate for the return type of the +function. +.LP +If the correct value would cause underflow, and is not representable, +a range error may occur, and \ either 0.0 (if +supported), or \ an implementation-defined value shall be +returned. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0 or \(+-Inf, \fIx\fP shall be returned. +.LP +If \fIn\fP is 0, \fIx\fP shall be returned. +.LP +If the correct value would cause underflow, and is representable, +a range error may occur and the correct value shall be +returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Range\ Error +The result overflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be +raised. +.sp +.LP +These functions may fail if: +.TP 7 +Range\ Error +The result underflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +These functions are named so as to avoid conflicting with the historical +definition of the \fIscalb\fP() function from the Single UNIX Specification. +The difference is that the \fIscalb\fP() function has a second argument +of \fBdouble\fP instead of \fBint\fP. The \fIscalb\fP() function is +not part of the ISO\ C standard. The three functions whose second +type +is \fBlong\fP are provided because the factor required to scale from +the smallest positive floating-point value to the largest +finite one, on many implementations, is too large to represent in +the minimum-width \fBint\fP format. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIscalb\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/scalbnf.3p b/man3p/scalbnf.3p new file mode 100644 index 000000000..51164a12b --- /dev/null +++ b/man3p/scalbnf.3p @@ -0,0 +1 @@ +.so man3p/scalbn.3p diff --git a/man3p/scalbnl.3p b/man3p/scalbnl.3p new file mode 100644 index 000000000..51164a12b --- /dev/null +++ b/man3p/scalbnl.3p @@ -0,0 +1 @@ +.so man3p/scalbn.3p diff --git a/man3p/scanf.3p b/man3p/scanf.3p new file mode 100644 index 000000000..b47ea9530 --- /dev/null +++ b/man3p/scanf.3p @@ -0,0 +1,531 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FSCANF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fscanf +.SH NAME +fscanf, scanf, sscanf \- convert formatted input +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fscanf(FILE *restrict\fP \fIstream\fP\fB, const char *restrict\fP +\fIformat\fP\fB, ... ); +.br +int scanf(const char *restrict\fP \fIformat\fP\fB, ... ); +.br +int sscanf(const char *restrict\fP \fIs\fP\fB, const char *restrict\fP +\fIformat\fP\fB, ... ); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfscanf\fP() function shall read from the named input \fIstream\fP. +The \fIscanf\fP() function shall read from the +standard input stream \fIstdin\fP. The \fIsscanf\fP() function shall +read from the string \fIs\fP. Each function reads bytes, +interprets them according to a format, and stores the results in its +arguments. Each expects, as arguments, a control string +\fIformat\fP described below, and a set of \fIpointer\fP arguments +indicating where the converted input should be stored. The +result is undefined if there are insufficient arguments for the format. +If the format is exhausted while arguments remain, the +excess arguments shall be evaluated but otherwise ignored. +.LP +Conversions can be applied to the \fIn\fPth argument after the \fIformat\fP +in the argument list, rather than to the next unused +argument. In this case, the conversion specifier character \fB%\fP +(see below) is replaced by the sequence +\fB"%\fP\fIn\fP\fB$"\fP, where \fIn\fP is a decimal integer in the +range [1,{NL_ARGMAX}]. This feature provides for the +definition of format strings that select arguments in an order appropriate +to specific languages. In format strings containing the +\fB"%\fP\fIn\fP\fB$"\fP form of conversion specifications, it is unspecified +whether numbered arguments in the argument list +can be referenced from the format string more than once. +.LP +The \fIformat\fP can contain either form of a conversion specification-that +is, \fB%\fP or +\fB"%\fP\fIn\fP\fB$"\fP-but the two forms cannot be mixed within a +single \fIformat\fP string. The only exception to this +is that \fB%%\fP or \fB%*\fP can be mixed with the \fB"%\fP\fIn\fP\fB$"\fP +form. When numbered argument specifications +are used, specifying the \fIN\fPth argument requires that all the +leading arguments, from the first to the ( \fIN\fP-1)th, are +pointers. +.LP +The +\fIfscanf\fP() function in all its forms shall allow detection of +a language-dependent radix character in the input string. The +radix character is defined in the program's locale (category \fILC_NUMERIC +).\fP In the POSIX locale, or in a locale where the +radix character is not defined, the radix character shall default +to a period ( \fB'.'\fP ). +.LP +The format is a character string, beginning and ending in its initial +shift state, if any, composed of zero or more directives. +Each directive is composed of one of the following: one or more white-space +characters ( s, s, +s, s, or s); an ordinary character +(neither \fB'%'\fP nor a white-space +character); or a conversion specification. Each conversion specification +is introduced by the character \fB'%'\fP \ or the +character sequence \fB"%\fP\fIn\fP\fB$"\fP, \ after +which the following appear in sequence: +.IP " *" 3 +An optional assignment-suppressing character \fB'*'\fP . +.LP +.IP " *" 3 +An optional non-zero decimal integer that specifies the maximum field +width. +.LP +.IP " *" 3 +An option length modifier that specifies the size of the receiving +object. +.LP +.IP " *" 3 +A \fIconversion specifier\fP character that specifies the type of +conversion to be applied. The valid conversion specifiers are +described below. +.LP +.LP +The \fIfscanf\fP() functions shall execute each directive of the format +in turn. If a directive fails, as detailed below, the +function shall return. Failures are described as input failures (due +to the unavailability of input bytes) or matching failures +(due to inappropriate input). +.LP +A directive composed of one or more white-space characters shall be +executed by reading input until no more valid input can be +read, or up to the first byte which is not a white-space character, +which remains unread. +.LP +A directive that is an ordinary character shall be executed as follows: +the next byte shall be read from the input and compared +with the byte that comprises the directive; if the comparison shows +that they are not equivalent, the directive shall fail, and the +differing and subsequent bytes shall remain unread. Similarly, if +end-of-file, an encoding error, or a read error prevents a +character from being read, the directive shall fail. +.LP +A directive that is a conversion specification defines a set of matching +input sequences, as described below for each conversion +character. A conversion specification shall be executed in the following +steps. +.LP +Input white-space characters (as specified by \fIisspace\fP() ) shall +be skipped, unless the +conversion specification includes a \fB[\fP , \fBc\fP , \fBC\fP , +or \fBn\fP conversion specifier. +.LP +An item shall be read from the input, unless the conversion specification +includes an \fBn\fP conversion specifier. An input +item shall be defined as the longest sequence of input bytes (up to +any specified maximum field width, which may be measured in +characters or bytes dependent on the conversion specifier) which is +an initial subsequence of a matching sequence. The first byte, +if any, after the input item shall remain unread. If the length of +the input item is 0, the execution of the conversion +specification shall fail; this condition is a matching failure, unless +end-of-file, an encoding error, or a read error prevented +input from the stream, in which case it is an input failure. +.LP +Except in the case of a \fB%\fP conversion specifier, the input item +(or, in the case of a \fB%n\fP conversion +specification, the count of input bytes) shall be converted to a type +appropriate to the conversion character. If the input item is +not a matching sequence, the execution of the conversion specification +fails; this condition is a matching failure. Unless +assignment suppression was indicated by a \fB'*'\fP , the result of +the conversion shall be placed in the object pointed to by +the first argument following the \fIformat\fP argument that has not +already received a conversion result if the conversion +specification is introduced by \fB%\fP , \ or in the \fIn\fPth argument +if introduced by the character +sequence \fB"%\fP\fIn\fP\fB$"\fP. If this object does not +have an appropriate type, or if the result of the conversion cannot +be represented in the space provided, the behavior is +undefined. +.LP +The length modifiers and their meanings are: +.TP 7 +\fBhh\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBsigned +char\fP or \fBunsigned char\fP. +.TP 7 +\fBh\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBshort\fP +or \fBunsigned short\fP. +.TP 7 +\fBl\fP\ (ell) +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBlong\fP +or \fBunsigned long\fP; that a following \fBa\fP , +\fBA\fP , \fBe\fP , \fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP , or \fBG\fP +conversion specifier applies to an +argument with type pointer to \fBdouble\fP; or that a following \fBc\fP +, \fBs\fP , or \fB[\fP conversion specifier +applies to an argument with type pointer to \fBwchar_t\fP. +.TP 7 +\fBll\fP\ (ell-ell) +.sp +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP conversion +specifier applies to an argument with type pointer to \fBlong long\fP +or \fBunsigned long long\fP. +.TP 7 +\fBj\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBintmax_t\fP +or \fBuintmax_t\fP. +.TP 7 +\fBz\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBsize_t\fP +or the corresponding signed integer type. +.TP 7 +\fBt\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBptrdiff_t\fP +or the corresponding \fBunsigned\fP type. +.TP 7 +\fBL\fP +Specifies that a following \fBa\fP , \fBA\fP , \fBe\fP , \fBE\fP , +\fBf\fP , \fBF\fP , \fBg\fP , or +\fBG\fP conversion specifier applies to an argument with type pointer +to \fBlong double\fP. +.sp +.LP +If a length modifier appears with any conversion specifier other than +as specified above, the behavior is undefined. +.LP +The following conversion specifiers are valid: +.TP 7 +\fBd\fP +Matches an optionally signed decimal integer, whose format is the +same as expected for the subject sequence of \fIstrtol\fP() with the +value 10 for the \fIbase\fP argument. In the absence of a size modifier, +the application shall ensure that the corresponding argument is a +pointer to \fBint\fP. +.TP 7 +\fBi\fP +Matches an optionally signed integer, whose format is the same as +expected for the subject sequence of \fIstrtol\fP() with 0 for the +\fIbase\fP argument. In the absence of a size modifier, the +application shall ensure that the corresponding argument is a pointer +to \fBint\fP. +.TP 7 +\fBo\fP +Matches an optionally signed octal integer, whose format is the same +as expected for the subject sequence of \fIstrtoul\fP() with the value +8 for the \fIbase\fP argument. In the absence of a size modifier, +the application shall ensure that the corresponding argument is a +pointer to \fBunsigned\fP. +.TP 7 +\fBu\fP +Matches an optionally signed decimal integer, whose format is the +same as expected for the subject sequence of \fIstrtoul\fP() with +the value 10 for the \fIbase\fP argument. In the absence of a size +modifier, +the application shall ensure that the corresponding argument is a +pointer to \fBunsigned\fP. +.TP 7 +\fBx\fP +Matches an optionally signed hexadecimal integer, whose format is +the same as expected for the subject sequence of \fIstrtoul\fP() with +the value 16 for the \fIbase\fP argument. In the absence of a size +modifier, +the application shall ensure that the corresponding argument is a +pointer to \fBunsigned\fP. +.TP 7 +\fBa\fP,\ \fBe\fP,\ \fBf\fP,\ \fBg\fP +.sp +Matches an optionally signed floating-point number, infinity, or NaN, +whose format is the same as expected for the subject sequence +of \fIstrtod\fP(). In the absence of a size modifier, the application +shall ensure that the +corresponding argument is a pointer to \fBfloat\fP. +.LP +If the \fIfprintf\fP() family of functions generates character string +representations +for infinity and NaN (a symbolic entity encoded in floating-point +format) to support IEEE\ Std\ 754-1985, the +\fIfscanf\fP() family of functions shall recognize them as input. +.TP 7 +\fBs\fP +Matches a sequence of bytes that are not white-space characters. The +application shall ensure that the corresponding argument +is a pointer to the initial byte of an array of \fBchar\fP, \fBsigned +char\fP, or \fBunsigned char\fP large enough to accept the +sequence and a terminating null character code, which shall be added +automatically. +.LP +If an \fBl\fP (ell) qualifier is present, the input is a sequence +of characters that begins in the initial shift state. Each +character shall be converted to a wide character as if by a call to +the \fImbrtowc\fP() +function, with the conversion state described by an \fBmbstate_t\fP +object initialized to zero before the first character is +converted. The application shall ensure that the corresponding argument +is a pointer to an array of \fBwchar_t\fP large enough to +accept the sequence and the terminating null wide character, which +shall be added automatically. +.TP 7 +\fB[\fP +Matches a non-empty sequence of bytes from a set of expected bytes +(the \fIscanset\fP). The normal skip over white-space +characters shall be suppressed in this case. The application shall +ensure that the corresponding argument is a pointer to the +initial byte of an array of \fBchar\fP, \fBsigned char\fP, or \fBunsigned +char\fP large enough to accept the sequence and a +terminating null byte, which shall be added automatically. +.LP +If an \fBl\fP (ell) qualifier is present, the input is a sequence +of characters that begins in the initial shift state. Each +character in the sequence shall be converted to a wide character as +if by a call to the \fImbrtowc\fP() function, with the conversion +state described by an \fBmbstate_t\fP object +initialized to zero before the first character is converted. The application +shall ensure that the corresponding argument is a +pointer to an array of \fBwchar_t\fP large enough to accept the sequence +and the terminating null wide character, which shall be +added automatically. +.LP +The conversion specification includes all subsequent bytes in the +\fIformat\fP string up to and including the matching right +square bracket ( \fB']'\fP ). The bytes between the square brackets +(the \fIscanlist\fP) comprise the scanset, unless the byte +after the left square bracket is a circumflex ( \fB'^'\fP ), in which +case the scanset contains all bytes that do not appear in +the scanlist between the circumflex and the right square bracket. +If the conversion specification begins with \fB"[]"\fP or +\fB"[^]"\fP , the right square bracket is included in the scanlist +and the next right square bracket is the matching right +square bracket that ends the conversion specification; otherwise, +the first right square bracket is the one that ends the +conversion specification. If a \fB'-'\fP is in the scanlist and is +not the first character, nor the second where the first +character is a \fB'^'\fP , nor the last character, the behavior is +implementation-defined. +.TP 7 +\fBc\fP +Matches a sequence of bytes of the number specified by the field width +(1 if no field width is present in the conversion +specification). The application shall ensure that the corresponding +argument is a pointer to the initial byte of an array of +\fBchar\fP, \fBsigned char\fP, or \fBunsigned char\fP large enough +to accept the sequence. No null byte is added. The normal +skip over white-space characters shall be suppressed in this case. +.LP +If an \fBl\fP (ell) qualifier is present, the input shall be a sequence +of characters that begins in the initial shift state. +Each character in the sequence is converted to a wide character as +if by a call to the \fImbrtowc\fP() function, with the conversion +state described by an \fBmbstate_t\fP object +initialized to zero before the first character is converted. The application +shall ensure that the corresponding argument is a +pointer to an array of \fBwchar_t\fP large enough to accept the resulting +sequence of wide characters. No null wide character is +added. +.TP 7 +\fBp\fP +Matches an implementation-defined set of sequences, which shall be +the same as the set of sequences that is produced by the +\fB%p\fP conversion specification of the corresponding \fIfprintf\fP() +functions. The +application shall ensure that the corresponding argument is a pointer +to a pointer to \fBvoid\fP. The interpretation of the input +item is implementation-defined. If the input item is a value converted +earlier during the same program execution, the pointer that +results shall compare equal to that value; otherwise, the behavior +of the \fB%p\fP conversion specification is undefined. +.TP 7 +\fBn\fP +No input is consumed. The application shall ensure that the corresponding +argument is a pointer to the integer into which shall +be written the number of bytes read from the input so far by this +call to the \fIfscanf\fP() functions. Execution of a \fB%n\fP +conversion specification shall not increment the assignment count +returned at the completion of execution of the function. No +argument shall be converted, but one shall be consumed. If the conversion +specification includes an assignment-suppressing +character or a field width, the behavior is undefined. +.TP 7 +\fBC\fP +Equivalent to \fBlc\fP . +.TP 7 +\fBS\fP +Equivalent to \fBls\fP . +.TP 7 +\fB%\fP +Matches a single \fB'%'\fP character; no conversion or assignment +occurs. The complete conversion specification shall be +\fB%%\fP . +.sp +.LP +If a conversion specification is invalid, the behavior is undefined. +.LP +The conversion specifiers \fBA\fP , \fBE\fP , \fBF\fP , \fBG\fP , +and \fBX\fP are also valid and shall be +equivalent to \fBa\fP , \fBe\fP , \fBf\fP , \fBg\fP , and \fBx\fP +, respectively. +.LP +If end-of-file is encountered during input, conversion shall be terminated. +If end-of-file occurs before any bytes matching the +current conversion specification (except for \fB%n\fP ) have been +read (other than leading white-space characters, where +permitted), execution of the current conversion specification shall +terminate with an input failure. Otherwise, unless execution of +the current conversion specification is terminated with a matching +failure, execution of the following conversion specification (if +any) shall be terminated with an input failure. +.LP +Reaching the end of the string in \fIsscanf\fP() shall be equivalent +to encountering end-of-file for \fIfscanf\fP(). +.LP +If conversion terminates on a conflicting input, the offending input +is left unread in the input. Any trailing white space +(including s) shall be left unread unless matched by a conversion +specification. The success of literal matches and +suppressed assignments is only directly determinable via the \fB%n\fP +conversion specification. +.LP +The +\fIfscanf\fP() and \fIscanf\fP() functions may mark the \fIst_atime\fP +field of the file associated with \fIstream\fP for +update. The \fIst_atime\fP field shall be marked for update by the +first successful execution of \fIfgetc\fP(), \fIfgets\fP(), \fIfread\fP(), +\fIgetc\fP(), \fIgetchar\fP(), \fIgets\fP(), \fIfscanf\fP(), or +\fIfscanf\fP() using \fIstream\fP that returns data not supplied by +a prior call to \fIungetc\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the number +of successfully matched and assigned input items; this +number can be zero in the event of an early matching failure. If the +input ends before the first matching failure or conversion, +EOF shall be returned. If a read error occurs, the error indicator +for the stream is set, EOF shall be returned, \ and +\fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +For the conditions under which the \fIfscanf\fP() functions fail and +may fail, refer to \fIfgetc\fP() +or \fIfgetwc\fP() . +.LP +In addition, \fIfscanf\fP() may fail if: +.TP 7 +.B EILSEQ +Input byte sequence does not form a valid character. +.TP 7 +.B EINVAL +There are insufficient arguments. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The call: +.sp +.RS +.nf + +\fBint i, n; float x; char name[50]; +n = scanf("%d%f%s", &i, &x, name); +\fP +.fi +.RE +.LP +with the input line: +.sp +.RS +.nf + +\fB25 54.32E-1 Hamster +\fP +.fi +.RE +.LP +assigns to \fIn\fP the value 3, to \fIi\fP the value 25, to \fIx\fP +the value 5.432, and \fIname\fP contains the string +\fB"Hamster"\fP . +.LP +The call: +.sp +.RS +.nf + +\fBint i; float x; char name[50]; +(void) scanf("%2d%f%*d %[0123456789]", &i, &x, name); +\fP +.fi +.RE +.LP +with input: +.sp +.RS +.nf + +\fB56789 0123 56a72 +\fP +.fi +.RE +.LP +assigns 56 to \fIi\fP, 789.0 to \fIx\fP, skips 0123, and places the +string \fB"56\\0"\fP in \fIname\fP. The next call to \fIgetchar\fP() +shall return the character \fB'a'\fP . +.SS Reading Data into an Array +.LP +The following call uses \fIfscanf\fP() to read three floating-point +numbers from standard input into the \fIinput\fP +array. +.sp +.RS +.nf + +\fBfloat input[3]; fscanf (stdin, "%f %f %f", input, input+1, input+2); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +If the application calling \fIfscanf\fP() has any objects of type +\fBwint_t\fP or \fBwchar_t\fP, it must also include the \fI\fP +header to have these objects defined. +.SH RATIONALE +.LP +This function is aligned with the ISO/IEC\ 9899:1999 standard, and +in doing so a few "obvious" things were not included. +Specifically, the set of characters allowed in a scanset is limited +to single-byte characters. In other similar places, multi-byte +characters have been permitted, but for alignment with the ISO/IEC\ 9899:1999 +standard, it has not been done here. Applications +needing this could use the corresponding wide-character functions +to achieve the desired results. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetc\fP() , \fIprintf\fP() , \fIsetlocale\fP() , \fIstrtod\fP() +, \fIstrtol\fP() , +\fIstrtoul\fP() , \fIwcrtomb\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI\fP, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sched_get_priority_max.3p b/man3p/sched_get_priority_max.3p new file mode 100644 index 000000000..f16816fbf --- /dev/null +++ b/man3p/sched_get_priority_max.3p @@ -0,0 +1,71 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SCHED_GET_PRIORITY_MAX" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sched_get_priority_max +.SH NAME +sched_get_priority_max, sched_get_priority_min \- get priority limits +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sched_get_priority_max(int\fP \fIpolicy\fP\fB); +.br +int sched_get_priority_min(int\fP \fIpolicy\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsched_get_priority_max\fP() and \fIsched_get_priority_min\fP() +functions shall return the appropriate maximum or +minimum, respectively, for the scheduling policy specified by \fIpolicy\fP. +.LP +The value of \fIpolicy\fP shall be one of the scheduling policy values +defined in \fI\fP. +.SH RETURN VALUE +.LP +If successful, the \fIsched_get_priority_max\fP() and \fIsched_get_priority_min\fP() +functions shall return the appropriate +maximum or minimum values, respectively. If unsuccessful, they shall +return a value of -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fIsched_get_priority_max\fP() and \fIsched_get_priority_min\fP() +functions shall fail if: +.TP 7 +.B EINVAL +The value of the \fIpolicy\fP parameter does not represent a defined +scheduling policy. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsched_getparam\fP() , \fIsched_setparam\fP() , \fIsched_getscheduler\fP() +, \fIsched_rr_get_interval\fP() +, \fIsched_setscheduler\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sched_get_priority_min.3p b/man3p/sched_get_priority_min.3p new file mode 100644 index 000000000..5ad82b2d8 --- /dev/null +++ b/man3p/sched_get_priority_min.3p @@ -0,0 +1 @@ +.so man3p/sched_get_priority_max.3p diff --git a/man3p/sched_getparam.3p b/man3p/sched_getparam.3p new file mode 100644 index 000000000..9b03cfcf7 --- /dev/null +++ b/man3p/sched_getparam.3p @@ -0,0 +1,75 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SCHED_GETPARAM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sched_getparam +.SH NAME +sched_getparam \- get scheduling parameters (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sched_getparam(pid_t\fP \fIpid\fP\fB, struct sched_param *\fP\fIparam\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsched_getparam\fP() function shall return the scheduling parameters +of a process specified by \fIpid\fP in the +\fBsched_param\fP structure pointed to by \fIparam\fP. +.LP +If a process specified by \fIpid\fP exists, and if the calling process +has permission, the scheduling parameters for the +process whose process ID is equal to \fIpid\fP shall be returned. +.LP +If \fIpid\fP is zero, the scheduling parameters for the calling process +shall be returned. The behavior of the +\fIsched_getparam\fP() function is unspecified if the value of \fIpid\fP +is negative. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIsched_getparam\fP() function shall +return zero. If the call to \fIsched_getparam\fP() is +unsuccessful, the function shall return a value of -1 and set \fIerrno\fP +to indicate the error. +.SH ERRORS +.LP +The \fIsched_getparam\fP() function shall fail if: +.TP 7 +.B EPERM +The requesting process does not have permission to obtain the scheduling +parameters of the specified process. +.TP 7 +.B ESRCH +No process can be found corresponding to that specified by \fIpid\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsched_getscheduler\fP() , \fIsched_setparam\fP() , +\fIsched_setscheduler\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sched_getscheduler.3p b/man3p/sched_getscheduler.3p new file mode 100644 index 000000000..2d70e1600 --- /dev/null +++ b/man3p/sched_getscheduler.3p @@ -0,0 +1,75 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SCHED_GETSCHEDULER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sched_getscheduler +.SH NAME +sched_getscheduler \- get scheduling policy (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sched_getscheduler(pid_t\fP \fIpid\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsched_getscheduler\fP() function shall return the scheduling +policy of the process specified by \fIpid\fP. If the value +of \fIpid\fP is negative, the behavior of the \fIsched_getscheduler\fP() +function is unspecified. +.LP +The values that can be returned by \fIsched_getscheduler\fP() are +defined in the \fI\fP header. +.LP +If a process specified by \fIpid\fP exists, and if the calling process +has permission, the scheduling policy shall be returned +for the process whose process ID is equal to \fIpid\fP. +.LP +If \fIpid\fP is zero, the scheduling policy shall be returned for +the calling process. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIsched_getscheduler\fP() function +shall return the scheduling policy of the specified +process. If unsuccessful, the function shall return -1 and set \fIerrno\fP +to indicate the error. +.SH ERRORS +.LP +The \fIsched_getscheduler\fP() function shall fail if: +.TP 7 +.B EPERM +The requesting process does not have permission to determine the scheduling +policy of the specified process. +.TP 7 +.B ESRCH +No process can be found corresponding to that specified by \fIpid\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsched_getparam\fP() , \fIsched_setparam\fP() , \fIsched_setscheduler\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sched_rr_get_interval.3p b/man3p/sched_rr_get_interval.3p new file mode 100644 index 000000000..3b0b2aa9e --- /dev/null +++ b/man3p/sched_rr_get_interval.3p @@ -0,0 +1,64 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SCHED_RR_GET_INTERVAL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sched_rr_get_interval +.SH NAME +sched_rr_get_interval \- get execution time limits (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sched_rr_get_interval(pid_t\fP \fIpid\fP\fB, struct timespec *\fP\fIinterval\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsched_rr_get_interval\fP() function shall update the \fBtimespec\fP +structure referenced by the \fIinterval\fP +argument to contain the current execution time limit (that is, time +quantum) for the process specified by \fIpid\fP. If \fIpid\fP +is zero, the current execution time limit for the calling process +shall be returned. +.SH RETURN VALUE +.LP +If successful, the \fIsched_rr_get_interval\fP() function shall return +zero. Otherwise, it shall return a value of -1 and set +\fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIsched_rr_get_interval\fP() function shall fail if: +.TP 7 +.B ESRCH +No process can be found corresponding to that specified by \fIpid\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsched_getparam\fP() , \fIsched_get_priority_max\fP() , \fIsched_getscheduler\fP() +, \fIsched_setparam\fP() , \fIsched_setscheduler\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sched_setparam.3p b/man3p/sched_setparam.3p new file mode 100644 index 000000000..2dd5942a5 --- /dev/null +++ b/man3p/sched_setparam.3p @@ -0,0 +1,178 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SCHED_SETPARAM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sched_setparam +.SH NAME +sched_setparam \- set scheduling parameters (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sched_setparam(pid_t\fP \fIpid\fP\fB, const struct sched_param +*\fP\fIparam\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsched_setparam\fP() function shall set the scheduling parameters +of the process specified by \fIpid\fP to the values +specified by the \fBsched_param\fP structure pointed to by \fIparam\fP. +The value of the \fIsched_priority\fP member in the +\fBsched_param\fP structure shall be any integer within the inclusive +priority range for the current scheduling policy of the +process specified by \fIpid\fP. Higher numerical values for the priority +represent higher priorities. If the value of \fIpid\fP +is negative, the behavior of the \fIsched_setparam\fP() function is +unspecified. +.LP +If a process specified by \fIpid\fP exists, and if the calling process +has permission, the scheduling parameters shall be set +for the process whose process ID is equal to \fIpid\fP. +.LP +If \fIpid\fP is zero, the scheduling parameters shall be set for the +calling process. +.LP +The conditions under which one process has permission to change the +scheduling parameters of another process are +implementation-defined. +.LP +Implementations may require the requesting process to have the appropriate +privilege to set its own scheduling parameters or +those of another process. +.LP +The target process, whether it is running or not running, shall be +moved to the tail of the thread list for its priority. +.LP +If the priority of the process specified by the \fIpid\fP argument +is set higher than that of the lowest priority running +process and if the specified process is ready to run, the process +specified by the \fIpid\fP argument shall preempt a lowest +priority running process. Similarly, if the process calling \fIsched_setparam\fP() +sets its own priority lower than that of one or +more other non-empty process lists, then the process that is the head +of the highest priority list shall also preempt the calling +process. Thus, in either case, the originating process might not receive +notification of the completion of the requested priority +change until the higher priority process has executed. +.LP +If +the scheduling policy of the target process is SCHED_SPORADIC, the +value specified by the \fIsched_ss_low_priority\fP member of +the \fIparam\fP argument shall be any integer within the inclusive +priority range for the sporadic server policy. The +\fIsched_ss_repl_period\fP and \fIsched_ss_init_budget\fP members +of the \fIparam\fP argument shall represent the time +parameters to be used by the sporadic server scheduling policy for +the target process. The \fIsched_ss_max_repl\fP member of the +\fIparam\fP argument shall represent the maximum number of replenishments +that are allowed to be pending simultaneously for the +process scheduled under this scheduling policy. +.LP +The specified \fIsched_ss_repl_period\fP shall be greater than or +equal to the specified \fIsched_ss_init_budget\fP for the +function to succeed; if it is not, then the function shall fail. +.LP +The value of \fIsched_ss_max_repl\fP shall be within the inclusive +range [1, {SS_REPL_MAX}] for the function to succeed; if +not, the function shall fail. +.LP +If the scheduling policy of the target process is either SCHED_FIFO +or SCHED_RR, the \fIsched_ss_low_priority\fP, +\fIsched_ss_repl_period\fP, and \fIsched_ss_init_budget\fP members +of the \fIparam\fP argument shall have no effect on the +scheduling behavior. If the scheduling policy of this process is not +SCHED_FIFO, SCHED_RR, or SCHED_SPORADIC, the effects of these +members are implementation-defined; this case includes the SCHED_OTHER +policy. +.LP +If the current scheduling policy for the process specified by \fIpid\fP +is not SCHED_FIFO, SCHED_RR, \ or +SCHED_SPORADIC, \ the result is implementation-defined; this +case includes the SCHED_OTHER policy. +.LP +The effect of this function on individual threads is dependent on +the scheduling contention scope of the threads: +.IP " *" 3 +For threads with system scheduling contention scope, these functions +shall have no effect on their scheduling. +.LP +.IP " *" 3 +For threads with process scheduling contention scope, the threads' +scheduling parameters shall not be affected. However, the +scheduling of these threads with respect to threads in other processes +may be dependent on the scheduling parameters of their +process, which are governed using these functions. +.LP +.LP +If an implementation supports a two-level scheduling model in which +library threads are multiplexed on top of several +kernel-scheduled entities, then the underlying kernel-scheduled entities +for the system contention scope threads shall not be +affected by these functions. +.LP +The underlying kernel-scheduled entities for the process contention +scope threads shall have their scheduling parameters changed +to the value specified in \fIparam\fP. Kernel-scheduled entities for +use by process contention scope threads that are created +after this call completes shall inherit their scheduling policy and +associated scheduling parameters from the process. +.LP +This function is not atomic with respect to other threads in the process. +Threads may continue to execute while this function +call is in the process of changing the scheduling policy for the underlying +kernel-scheduled entities used by the process +contention scope threads. +.SH RETURN VALUE +.LP +If successful, the \fIsched_setparam\fP() function shall return zero. +.LP +If the call to \fIsched_setparam\fP() is unsuccessful, the priority +shall remain unchanged, and the function shall return a +value of -1 and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIsched_setparam\fP() function shall fail if: +.TP 7 +.B EINVAL +One or more of the requested scheduling parameters is outside the +range defined for the scheduling policy of the specified +\fIpid\fP. +.TP 7 +.B EPERM +The requesting process does not have permission to set the scheduling +parameters for the specified process, or does not have +the appropriate privilege to invoke \fIsched_setparam\fP(). +.TP 7 +.B ESRCH +No process can be found corresponding to that specified by \fIpid\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsched_getparam\fP() , \fIsched_getscheduler\fP() , +\fIsched_setscheduler\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sched_setscheduler.3p b/man3p/sched_setscheduler.3p new file mode 100644 index 000000000..46ccd9e59 --- /dev/null +++ b/man3p/sched_setscheduler.3p @@ -0,0 +1,170 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SCHED_SETSCHEDULER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sched_setscheduler +.SH NAME +sched_setscheduler \- set scheduling policy and parameters (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sched_setscheduler(pid_t\fP \fIpid\fP\fB, int\fP \fIpolicy\fP\fB, +.br +\ \ \ \ \ \ const struct sched_param *\fP\fIparam\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsched_setscheduler\fP() function shall set the scheduling policy +and scheduling parameters of the process specified by +\fIpid\fP to \fIpolicy\fP and the parameters specified in the \fBsched_param\fP +structure pointed to by \fIparam\fP, +respectively. The value of the \fIsched_priority\fP member in the +\fBsched_param\fP structure shall be any integer within the +inclusive priority range for the scheduling policy specified by \fIpolicy\fP. +If the value of \fIpid\fP is negative, the behavior +of the \fIsched_setscheduler\fP() function is unspecified. +.LP +The possible values for the \fIpolicy\fP parameter are defined in +the \fI\fP header. +.LP +If a process specified by \fIpid\fP exists, and if the calling process +has permission, the scheduling policy and scheduling +parameters shall be set for the process whose process ID is equal +to \fIpid\fP. +.LP +If \fIpid\fP is zero, the scheduling policy and scheduling parameters +shall be set for the calling process. +.LP +The conditions under which one process has the appropriate privilege +to change the scheduling parameters of another process are +implementation-defined. +.LP +Implementations may require that the requesting process have permission +to set its own scheduling parameters or those of another +process. Additionally, implementation-defined restrictions may apply +as to the appropriate privileges required to set a process' +own scheduling policy, or another process' scheduling policy, to a +particular value. +.LP +The \fIsched_setscheduler\fP() function shall be considered successful +if it succeeds in setting the scheduling policy and +scheduling parameters of the process specified by \fIpid\fP to the +values specified by \fIpolicy\fP and the structure pointed to +by \fIparam\fP, respectively. +.LP +If +the scheduling policy specified by \fIpolicy\fP is SCHED_SPORADIC, +the value specified by the \fIsched_ss_low_priority\fP member +of the \fIparam\fP argument shall be any integer within the inclusive +priority range for the sporadic server policy. The +\fIsched_ss_repl_period\fP and \fIsched_ss_init_budget\fP members +of the \fIparam\fP argument shall represent the time +parameters used by the sporadic server scheduling policy for the target +process. The \fIsched_ss_max_repl\fP member of the +\fIparam\fP argument shall represent the maximum number of replenishments +that are allowed to be pending simultaneously for the +process scheduled under this scheduling policy. +.LP +The specified \fIsched_ss_repl_period\fP shall be greater than or +equal to the specified \fIsched_ss_init_budget\fP for the +function to succeed; if it is not, then the function shall fail. +.LP +The value of \fIsched_ss_max_repl\fP shall be within the inclusive +range [1, {SS_REPL_MAX}] for the function to succeed; if +not, the function shall fail. +.LP +If the scheduling policy specified by \fIpolicy\fP is either SCHED_FIFO +or SCHED_RR, the \fIsched_ss_low_priority\fP, +\fIsched_ss_repl_period\fP, and \fIsched_ss_init_budget\fP members +of the \fIparam\fP argument shall have no effect on the +scheduling behavior. +.LP +The effect of this function on individual threads is dependent on +the scheduling contention scope of the threads: +.IP " *" 3 +For threads with system scheduling contention scope, these functions +shall have no effect on their scheduling. +.LP +.IP " *" 3 +For threads with process scheduling contention scope, the threads' +scheduling policy and associated parameters shall not be +affected. However, the scheduling of these threads with respect to +threads in other processes may be dependent on the scheduling +parameters of their process, which are governed using these functions. +.LP +.LP +If an implementation supports a two-level scheduling model in which +library threads are multiplexed on top of several +kernel-scheduled entities, then the underlying kernel-scheduled entities +for the system contention scope threads shall not be +affected by these functions. +.LP +The underlying kernel-scheduled entities for the process contention +scope threads shall have their scheduling policy and +associated scheduling parameters changed to the values specified in +\fIpolicy\fP and \fIparam\fP, respectively. Kernel-scheduled +entities for use by process contention scope threads that are created +after this call completes shall inherit their scheduling +policy and associated scheduling parameters from the process. +.LP +This function is not atomic with respect to other threads in the process. +Threads may continue to execute while this function +call is in the process of changing the scheduling policy and associated +scheduling parameters for the underlying kernel-scheduled +entities used by the process contention scope threads. +.SH RETURN VALUE +.LP +Upon successful completion, the function shall return the former scheduling +policy of the specified process. If the +\fIsched_setscheduler\fP() function fails to complete successfully, +the policy and scheduling parameters shall remain unchanged, +and the function shall return a value of -1 and set \fIerrno\fP to +indicate the error. +.SH ERRORS +.LP +The \fIsched_setscheduler\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of the \fIpolicy\fP parameter is invalid, or one or more +of the parameters contained in \fIparam\fP is outside the +valid range for the specified scheduling policy. +.TP 7 +.B EPERM +The requesting process does not have permission to set either or both +of the scheduling parameters or the scheduling policy of +the specified process. +.TP 7 +.B ESRCH +No process can be found corresponding to that specified by \fIpid\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsched_getparam\fP() , \fIsched_getscheduler\fP() , +\fIsched_setparam\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sched_yield.3p b/man3p/sched_yield.3p new file mode 100644 index 000000000..79f580a3c --- /dev/null +++ b/man3p/sched_yield.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SCHED_YIELD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sched_yield +.SH NAME +sched_yield \- yield the processor +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sched_yield(void); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsched_yield\fP() function shall force the running thread to +relinquish the processor until it again becomes the head of +its thread list. It takes no arguments. +.SH RETURN VALUE +.LP +The \fIsched_yield\fP() function shall return 0 if it completes successfully; +otherwise, it shall return a value of -1 and set +\fIerrno\fP to indicate the error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/seed48.3p b/man3p/seed48.3p new file mode 100644 index 000000000..a71d5ed19 --- /dev/null +++ b/man3p/seed48.3p @@ -0,0 +1 @@ +.so man3p/drand48.3p diff --git a/man3p/seekdir.3p b/man3p/seekdir.3p new file mode 100644 index 000000000..0b5f72737 --- /dev/null +++ b/man3p/seekdir.3p @@ -0,0 +1,83 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SEEKDIR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" seekdir +.SH NAME +seekdir \- set the position of a directory stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void seekdir(DIR *\fP\fIdirp\fP\fB, long\fP \fIloc\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIseekdir\fP() function shall set the position of the next \fIreaddir\fP() +operation on the directory stream specified by \fIdirp\fP to the position +specified by \fIloc\fP. The value of \fIloc\fP should +have been returned from an earlier call to \fItelldir\fP(). The new +position reverts to +the one associated with the directory stream when \fItelldir\fP() +was performed. +.LP +If the value of \fIloc\fP was not obtained from an earlier call to +\fItelldir\fP(), or +if a call to \fIrewinddir\fP() occurred between the call to \fItelldir\fP() +and the call to \fIseekdir\fP(), the results of subsequent calls to +\fIreaddir\fP() are unspecified. +.SH RETURN VALUE +.LP +The \fIseekdir\fP() function shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The original standard developers perceived that there were restrictions +on the use of the \fIseekdir\fP() and \fItelldir\fP() functions related +to implementation details, and for that reason these functions +need not be supported on all POSIX-conforming systems. They are required +on implementations supporting the XSI extension. +.LP +One of the perceived problems of implementation is that returning +to a given point in a directory is quite difficult to describe +formally, in spite of its intuitive appeal, when systems that use +B-trees, hashing functions, or other similar mechanisms to order +their directories are considered. The definition of \fIseekdir\fP() +and \fItelldir\fP() +does not specify whether, when using these interfaces, a given directory +entry will be seen at all, or more than once. +.LP +On systems not supporting these functions, their capability can sometimes +be accomplished by saving a filename found by \fIreaddir\fP() and +later using \fIrewinddir\fP() and a +loop on \fIreaddir\fP() to relocate the position from which the filename +was saved. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIopendir\fP() , \fIreaddir\fP() , \fItelldir\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/select.3p b/man3p/select.3p new file mode 100644 index 000000000..3df0205db --- /dev/null +++ b/man3p/select.3p @@ -0,0 +1,318 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PSELECT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pselect +.SH NAME +pselect, select \- synchronous I/O multiplexing +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int pselect(int\fP \fInfds\fP\fB, fd_set *restrict\fP \fIreadfds\fP\fB, +.br +\ \ \ \ \ \ fd_set *restrict\fP \fIwritefds\fP\fB, fd_set *restrict\fP +\fIerrorfds\fP\fB, +.br +\ \ \ \ \ \ const struct timespec *restrict\fP \fItimeout\fP\fB, +.br +\ \ \ \ \ \ const sigset_t *restrict\fP \fIsigmask\fP\fB); +.br +int select(int\fP \fInfds\fP\fB, fd_set *restrict\fP \fIreadfds\fP\fB, +.br +\ \ \ \ \ \ fd_set *restrict\fP \fIwritefds\fP\fB, fd_set *restrict\fP +\fIerrorfds\fP\fB, +.br +\ \ \ \ \ \ struct timeval *restrict\fP \fItimeout\fP\fB); +.br +void FD_CLR(int\fP \fIfd\fP\fB, fd_set *\fP\fIfdset\fP\fB); +.br +int FD_ISSET(int\fP \fIfd\fP\fB, fd_set *\fP\fIfdset\fP\fB); +.br +void FD_SET(int\fP \fIfd\fP\fB, fd_set *\fP\fIfdset\fP\fB); +.br +void FD_ZERO(fd_set *\fP\fIfdset\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIpselect\fP() function shall examine the file descriptor sets +whose addresses are passed in the \fIreadfds\fP, +\fIwritefds\fP, and \fIerrorfds\fP parameters to see whether some +of their descriptors are ready for reading, are ready for +writing, or have an exceptional condition pending, respectively. +.LP +The \fIselect\fP() function shall be equivalent to the \fIpselect\fP() +function, except as follows: +.IP " *" 3 +For the \fIselect\fP() function, the timeout period is given in seconds +and microseconds in an argument of type \fBstruct +timeval\fP, whereas for the \fIpselect\fP() function the timeout period +is given in seconds and nanoseconds in an argument of +type \fBstruct timespec\fP. +.LP +.IP " *" 3 +The \fIselect\fP() function has no \fIsigmask\fP argument; it shall +behave as \fIpselect\fP() does when \fIsigmask\fP is a +null pointer. +.LP +.IP " *" 3 +Upon successful completion, the \fIselect\fP() function may modify +the object pointed to by the \fItimeout\fP argument. +.LP +.LP +The \fIpselect\fP() and \fIselect\fP() functions shall support regular +files, terminal and pseudo-terminal devices, +\ STREAMS-based files, FIFOs, pipes, and sockets. The behavior +of \fIpselect\fP() and \fIselect\fP() on file descriptors that refer +to other types of file is unspecified. +.LP +The \fInfds\fP argument specifies the range of descriptors to be tested. +The first \fInfds\fP descriptors shall be checked in +each set; that is, the descriptors from zero through \fInfds\fP-1 +in the descriptor sets shall be examined. +.LP +If the \fIreadfds\fP argument is not a null pointer, it points to +an object of type \fBfd_set\fP that on input specifies the +file descriptors to be checked for being ready to read, and on output +indicates which file descriptors are ready to read. +.LP +If the \fIwritefds\fP argument is not a null pointer, it points to +an object of type \fBfd_set\fP that on input specifies the +file descriptors to be checked for being ready to write, and on output +indicates which file descriptors are ready to write. +.LP +If the \fIerrorfds\fP argument is not a null pointer, it points to +an object of type \fBfd_set\fP that on input specifies the +file descriptors to be checked for error conditions pending, and on +output indicates which file descriptors have error conditions +pending. +.LP +Upon successful completion, the \fIpselect\fP() or \fIselect\fP() +function shall modify the objects pointed to by the +\fIreadfds\fP, \fIwritefds\fP, and \fIerrorfds\fP arguments to indicate +which file descriptors are ready for reading, ready for +writing, or have an error condition pending, respectively, and shall +return the total number of ready descriptors in all the output +sets. For each file descriptor less than \fInfds\fP, the corresponding +bit shall be set on successful completion if it was set on +input and the associated condition is true for that file descriptor. +.LP +If none of the selected descriptors are ready for the requested operation, +the \fIpselect\fP() or \fIselect\fP() function +shall block until at least one of the requested operations becomes +ready, until the \fItimeout\fP occurs, or until interrupted by +a signal. The \fItimeout\fP parameter controls how long the \fIpselect\fP() +or \fIselect\fP() function shall take before timing +out. If the \fItimeout\fP parameter is not a null pointer, it specifies +a maximum interval to wait for the selection to complete. +If the specified time interval expires without any requested operation +becoming ready, the function shall return. If the +\fItimeout\fP parameter is a null pointer, then the call to \fIpselect\fP() +or \fIselect\fP() shall block indefinitely until at +least one descriptor meets the specified criteria. To effect a poll, +the \fItimeout\fP parameter should not be a null pointer, and +should point to a zero-valued \fBtimespec\fP structure. +.LP +The use of a timeout does not affect any pending timers set up by +\fIalarm\fP(), \fIualarm\fP(), or \fIsetitimer\fP(). +.LP +Implementations may place limitations on the maximum timeout interval +supported. All implementations shall support a maximum +timeout interval of at least 31 days. If the \fItimeout\fP argument +specifies a timeout interval greater than the +implementation-defined maximum value, the maximum value shall be used +as the actual timeout value. Implementations may also place +limitations on the granularity of timeout intervals. If the requested +timeout interval requires a finer granularity than the +implementation supports, the actual timeout interval shall be rounded +up to the next supported value. +.LP +If \fIsigmask\fP is not a null pointer, then the \fIpselect\fP() function +shall replace the signal mask of the process by the +set of signals pointed to by \fIsigmask\fP before examining the descriptors, +and shall restore the signal mask of the process +before returning. +.LP +A descriptor shall be considered ready for reading when a call to +an input function with O_NONBLOCK clear would not block, +whether or not the function would transfer data successfully. (The +function might return data, an end-of-file indication, or an +error other than one indicating that it is blocked, and in each of +these cases the descriptor shall be considered ready for +reading.) +.LP +A descriptor shall be considered ready for writing when a call to +an output function with O_NONBLOCK clear would not block, +whether or not the function would transfer data successfully. +.LP +If a socket has a pending error, it shall be considered to have an +exceptional condition pending. Otherwise, what constitutes an +exceptional condition is file type-specific. For a file descriptor +for use with a socket, it is protocol-specific except as noted +below. For other file types it is implementation-defined. If the operation +is meaningless for a particular file type, +\fIpselect\fP() or \fIselect\fP() shall indicate that the descriptor +is ready for read or write operations, and shall indicate +that the descriptor has no exceptional condition pending. +.LP +If a descriptor refers to a socket, the implied input function is +the \fIrecvmsg\fP() +function with parameters requesting normal and ancillary data, such +that the presence of either type shall cause the socket to be +marked as readable. The presence of out-of-band data shall be checked +if the socket option SO_OOBINLINE has been enabled, as +out-of-band data is enqueued with normal data. If the socket is currently +listening, then it shall be marked as readable if an +incoming connection request has been received, and a call to the \fIaccept\fP() +function +shall complete without blocking. +.LP +If a descriptor refers to a socket, the implied output function is +the \fIsendmsg\fP() +function supplying an amount of normal data equal to the current value +of the SO_SNDLOWAT option for the socket. If a non-blocking +call to the \fIconnect\fP() function has been made for a socket, and +the connection +attempt has either succeeded or failed leaving a pending error, the +socket shall be marked as writable. +.LP +A socket shall be considered to have an exceptional condition pending +if a receive operation with O_NONBLOCK clear for the open +file description and with the MSG_OOB flag set would return out-of-band +data without blocking. (It is protocol-specific whether the +MSG_OOB flag would be used to read out-of-band data.) A socket shall +also be considered to have an exceptional condition pending if +an out-of-band data mark is present in the receive queue. Other circumstances +under which a socket may be considered to have an +exceptional condition pending are protocol-specific and implementation-defined. +.LP +If the \fIreadfds\fP, \fIwritefds\fP, and \fIerrorfds\fP arguments +are all null pointers and the \fItimeout\fP argument is +not a null pointer, the \fIpselect\fP() or \fIselect\fP() function +shall block for the time specified, or until interrupted by a +signal. If the \fIreadfds\fP, \fIwritefds\fP, and \fIerrorfds\fP arguments +are all null pointers and the \fItimeout\fP argument +is a null pointer, the \fIpselect\fP() or \fIselect\fP() function +shall block until interrupted by a signal. +.LP +File descriptors associated with regular files shall always select +true for ready to read, ready to write, and error +conditions. +.LP +On failure, the objects pointed to by the \fIreadfds\fP, \fIwritefds\fP, +and \fIerrorfds\fP arguments shall not be modified. +If the timeout interval expires without the specified condition being +true for any of the specified file descriptors, the objects +pointed to by the \fIreadfds\fP, \fIwritefds\fP, and \fIerrorfds\fP +arguments shall have all bits set to 0. +.LP +File descriptor masks of type \fBfd_set\fP can be initialized and +tested with \fIFD_CLR\fP(), \fIFD_ISSET\fP(), +\fIFD_SET\fP(), and \fIFD_ZERO\fP(). It is unspecified whether each +of these is a macro or a function. If a macro definition is +suppressed in order to access an actual function, or a program defines +an external identifier with any of these names, the behavior +is undefined. +.LP +\fIFD_CLR\fP(\fIfd\fP, \fIfdsetp\fP) shall remove the file descriptor +\fIfd\fP from the set pointed to by \fIfdsetp\fP. If +\fIfd\fP is not a member of this set, there shall be no effect on +the set, nor will an error be returned. +.LP +\fIFD_ISSET\fP(\fIfd\fP, \fIfdsetp\fP) shall evaluate to non-zero +if the file descriptor \fIfd\fP is a member of the set +pointed to by \fIfdsetp\fP, and shall evaluate to zero otherwise. +.LP +\fIFD_SET\fP(\fIfd\fP, \fIfdsetp\fP) shall add the file descriptor +\fIfd\fP to the set pointed to by \fIfdsetp\fP. If the +file descriptor \fIfd\fP is already in this set, there shall be no +effect on the set, nor will an error be returned. +.LP +\fIFD_ZERO\fP(\fIfdsetp\fP) shall initialize the descriptor set pointed +to by \fIfdsetp\fP to the null set. No error is +returned if the set is not empty at the time \fIFD_ZERO\fP() is invoked. +.LP +The behavior of these macros is undefined if the \fIfd\fP argument +is less than 0 or greater than or equal to FD_SETSIZE, or if +\fIfd\fP is not a valid file descriptor, or if any of the arguments +are expressions with side effects. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIpselect\fP() and \fIselect\fP() +functions shall return the total number of bits set in the +bit masks. Otherwise, -1 shall be returned, and \fIerrno\fP shall +be set to indicate the error. +.LP +\fIFD_CLR\fP(), \fIFD_SET\fP(), and \fIFD_ZERO\fP() do not return +a value. \fIFD_ISSET\fP() shall return a non-zero value if +the bit for the file descriptor \fIfd\fP is set in the file descriptor +set pointed to by \fIfdset\fP, and 0 otherwise. +.SH ERRORS +.LP +Under the following conditions, \fIpselect\fP() and \fIselect\fP() +shall fail and set \fIerrno\fP to: +.TP 7 +.B EBADF +One or more of the file descriptor sets specified a file descriptor +that is not a valid open file descriptor. +.TP 7 +.B EINTR +The function was interrupted before any of the selected events occurred +and before the timeout interval expired. +.LP +If SA_RESTART has been set for the interrupting signal, it is implementation-defined +whether the function restarts or returns with +[EINTR]. +.TP 7 +.B EINVAL +An invalid timeout interval was specified. +.TP 7 +.B EINVAL +The \fInfds\fP argument is less than 0 or greater than FD_SETSIZE. +.TP 7 +.B EINVAL +One of the specified file descriptors refers to a STREAM or multiplexer +that is linked (directly or indirectly) downstream from a +multiplexer. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +In previous versions of the Single UNIX Specification, the \fIselect\fP() +function was defined in the \fI\fP header. This is now +changed to \fI\fP. The rationale for this change was +as follows: the introduction of +the \fIpselect\fP() function included the \fI\fP header +and the +\fI\fP header defines all the related definitions for +the +\fIpselect\fP() and \fIselect\fP() functions. Backwards-compatibility +to existing XSI implementations is handled by allowing \fI\fP +to include \fI\fP. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIaccept\fP() , \fIalarm\fP() , \fIconnect\fP() , \fIfcntl\fP() , +\fIpoll\fP() , \fIread\fP() , \fIrecvmsg\fP() , \fIsendmsg\fP() , +\fIsetitimer\fP() , \fIualarm\fP() , \fIwrite\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sem_close.3p b/man3p/sem_close.3p new file mode 100644 index 000000000..5c2d64437 --- /dev/null +++ b/man3p/sem_close.3p @@ -0,0 +1,77 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SEM_CLOSE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sem_close +.SH NAME +sem_close \- close a named semaphore (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sem_close(sem_t *\fP\fIsem\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsem_close\fP() function shall indicate that the calling process +is finished using the named semaphore indicated by +\fIsem\fP. The effects of calling \fIsem_close\fP() for an unnamed +semaphore (one created by \fIsem_init\fP()) are undefined. The \fIsem_close\fP() +function shall deallocate (that is, make +available for reuse by a subsequent \fIsem_open\fP() by this process) +any system +resources allocated by the system for use by this process for this +semaphore. The effect of subsequent use of the semaphore +indicated by \fIsem\fP by this process is undefined. If the semaphore +has not been removed with a successful call to \fIsem_unlink\fP(), +then \fIsem_close\fP() has no effect on the state of the semaphore. +If the +\fIsem_unlink\fP() function has been successfully invoked for \fIname\fP +after the +most recent call to \fIsem_open\fP() with O_CREAT for this semaphore, +then when all +processes that have opened the semaphore close it, the semaphore is +no longer accessible. +.SH RETURN VALUE +.LP +Upon successful completion, a value of zero shall be returned. Otherwise, +a value of -1 shall be returned and \fIerrno\fP set +to indicate the error. +.SH ERRORS +.LP +The \fIsem_close\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fIsem\fP argument is not a valid semaphore descriptor. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIsem_close\fP() function is part of the Semaphores option and +need not be available on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsemctl\fP() , \fIsemget\fP() , \fIsemop\fP() +, \fIsem_init\fP() , \fIsem_open\fP() , \fIsem_unlink\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sem_destroy.3p b/man3p/sem_destroy.3p new file mode 100644 index 000000000..f1f1f701e --- /dev/null +++ b/man3p/sem_destroy.3p @@ -0,0 +1,76 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SEM_DESTROY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sem_destroy +.SH NAME +sem_destroy \- destroy an unnamed semaphore (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sem_destroy(sem_t *\fP\fIsem\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsem_destroy\fP() function shall destroy the unnamed semaphore +indicated by \fIsem\fP. Only a semaphore that was created +using \fIsem_init\fP() may be destroyed using \fIsem_destroy\fP(); +the effect of calling +\fIsem_destroy\fP() with a named semaphore is undefined. The effect +of subsequent use of the semaphore \fIsem\fP is undefined +until \fIsem\fP is reinitialized by another call to \fIsem_init\fP(). +.LP +It is safe to destroy an initialized semaphore upon which no threads +are currently blocked. The effect of destroying a semaphore +upon which other threads are currently blocked is undefined. +.SH RETURN VALUE +.LP +Upon successful completion, a value of zero shall be returned. Otherwise, +a value of -1 shall be returned and \fIerrno\fP set +to indicate the error. +.SH ERRORS +.LP +The \fIsem_destroy\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fIsem\fP argument is not a valid semaphore. +.sp +.LP +The \fIsem_destroy\fP() function may fail if: +.TP 7 +.B EBUSY +There are currently processes blocked on the semaphore. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIsem_destroy\fP() function is part of the Semaphores option +and need not be available on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsemctl\fP() , \fIsemget\fP() , \fIsemop\fP() +, \fIsem_init\fP() , \fIsem_open\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sem_getvalue.3p b/man3p/sem_getvalue.3p new file mode 100644 index 000000000..12e74c625 --- /dev/null +++ b/man3p/sem_getvalue.3p @@ -0,0 +1,72 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SEM_GETVALUE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sem_getvalue +.SH NAME +sem_getvalue \- get the value of a semaphore (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sem_getvalue(sem_t *restrict\fP \fIsem\fP\fB, int *restrict\fP +\fIsval\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsem_getvalue\fP() function shall update the location referenced +by the \fIsval\fP argument to have the value of the +semaphore referenced by \fIsem\fP without affecting the state of the +semaphore. The updated value represents an actual semaphore +value that occurred at some unspecified time during the call, but +it need not be the actual value of the semaphore when it is +returned to the calling process. +.LP +If \fIsem\fP is locked, then the object to which \fIsval\fP points +shall either be set to zero or to a negative number whose +absolute value represents the number of processes waiting for the +semaphore at some unspecified time during the call. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIsem_getvalue\fP() function shall +return a value of zero. Otherwise, it shall return a value +of -1 and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIsem_getvalue\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fIsem\fP argument does not refer to a valid semaphore. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIsem_getvalue\fP() function is part of the Semaphores option +and need not be available on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsemctl\fP() , \fIsemget\fP() , \fIsemop\fP() +, \fIsem_post\fP() , \fIsem_timedwait\fP() , \fIsem_trywait\fP() , +\fIsem_wait\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sem_init.3p b/man3p/sem_init.3p new file mode 100644 index 000000000..bd8d63238 --- /dev/null +++ b/man3p/sem_init.3p @@ -0,0 +1,99 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SEM_INIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sem_init +.SH NAME +sem_init \- initialize an unnamed semaphore (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sem_init(sem_t *\fP\fIsem\fP\fB, int\fP \fIpshared\fP\fB, unsigned\fP +\fIvalue\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsem_init\fP() function shall initialize the unnamed semaphore +referred to by \fIsem\fP. The value of the initialized +semaphore shall be \fIvalue\fP. Following a successful call to \fIsem_init\fP(), +the semaphore may be used in subsequent calls to +\fIsem_wait\fP(), \fIsem_trywait\fP(), \fIsem_post\fP(), and \fIsem_destroy\fP(). +This +semaphore shall remain usable until the semaphore is destroyed. +.LP +If the \fIpshared\fP argument has a non-zero value, then the semaphore +is shared between processes; in this case, any process +that can access the semaphore \fIsem\fP can use \fIsem\fP for performing +\fIsem_wait\fP(), \fIsem_trywait\fP(), \fIsem_post\fP(), and \fIsem_destroy\fP() +operations. +.LP +Only \fIsem\fP itself may be used for performing synchronization. +The result of referring to copies of \fIsem\fP in calls to +\fIsem_wait\fP(), \fIsem_trywait\fP(), \fIsem_post\fP(), and \fIsem_destroy\fP() +is +undefined. +.LP +If the \fIpshared\fP argument is zero, then the semaphore is shared +between threads of the process; any thread in this process +can use \fIsem\fP for performing \fIsem_wait\fP(), \fIsem_trywait\fP(), +\fIsem_post\fP(), and \fIsem_destroy\fP() operations. The use of the +semaphore by threads other than those created +in the same process is undefined. +.LP +Attempting to initialize an already initialized semaphore results +in undefined behavior. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIsem_init\fP() function shall initialize +the semaphore in \fIsem\fP. Otherwise, it shall +return -1 and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIsem_init\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fIvalue\fP argument exceeds {SEM_VALUE_MAX}. +.TP 7 +.B ENOSPC +A resource required to initialize the semaphore has been exhausted, +or the limit on semaphores ( {SEM_NSEMS_MAX}) has been +reached. +.TP 7 +.B EPERM +The process lacks the appropriate privileges to initialize the semaphore. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIsem_init\fP() function is part of the Semaphores option and +need not be available on all implementations. +.SH RATIONALE +.LP +Although this volume of IEEE\ Std\ 1003.1-2001 fails to specify a +successful return value, it is likely that a later +version may require the implementation to return a value of zero if +the call to \fIsem_init\fP() is successful. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsem_destroy\fP() , \fIsem_post\fP() , \fIsem_timedwait\fP() , \fIsem_trywait\fP() +, \fIsem_wait\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sem_open.3p b/man3p/sem_open.3p new file mode 100644 index 000000000..d90d7a117 --- /dev/null +++ b/man3p/sem_open.3p @@ -0,0 +1,169 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SEM_OPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sem_open +.SH NAME +sem_open \- initialize and open a named semaphore (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +sem_t *sem_open(const char *\fP\fIname\fP\fB, int\fP \fIoflag\fP\fB, +\&...); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsem_open\fP() function shall establish a connection between +a named semaphore and a process. Following a call to +\fIsem_open\fP() with semaphore name \fIname\fP, the process may reference +the semaphore associated with \fIname\fP using the +address returned from the call. This semaphore may be used in subsequent +calls to \fIsem_wait\fP(), \fIsem_trywait\fP(), \fIsem_post\fP(), +and \fIsem_close\fP(). The semaphore +remains usable by this process until the semaphore is closed by a +successful call to \fIsem_close\fP(), \fI_exit\fP(), or one of the +\fIexec\fP functions. +.LP +The \fIoflag\fP argument controls whether the semaphore is created +or merely accessed by the call to \fIsem_open\fP(). The +following flag bits may be set in \fIoflag\fP: +.TP 7 +O_CREAT +This flag is used to create a semaphore if it does not already exist. +If O_CREAT is set and the semaphore already exists, then +O_CREAT has no effect, except as noted under O_EXCL. Otherwise, \fIsem_open\fP() +creates a named semaphore. The O_CREAT flag +requires a third and a fourth argument: \fImode\fP, which is of type +\fBmode_t\fP, and \fIvalue\fP, which is of type +\fBunsigned\fP. The semaphore is created with an initial value of +\fIvalue\fP. Valid initial values for semaphores are less than +or equal to {SEM_VALUE_MAX}. +.LP +The user ID of the semaphore is set to the effective user ID of the +process; the group ID of the semaphore is set to a system +default group ID or to the effective group ID of the process. The +permission bits of the semaphore are set to the value of the +\fImode\fP argument except those set in the file mode creation mask +of the process. When bits in \fImode\fP other than the file +permission bits are specified, the effect is unspecified. +.LP +After the semaphore named \fIname\fP has been created by \fIsem_open\fP() +with the O_CREAT flag, other processes can connect +to the semaphore by calling \fIsem_open\fP() with the same value of +\fIname\fP. +.TP 7 +O_EXCL +If O_EXCL and O_CREAT are set, \fIsem_open\fP() fails if the semaphore +\fIname\fP exists. The check for the existence of the +semaphore and the creation of the semaphore if it does not exist are +atomic with respect to other processes executing +\fIsem_open\fP() with O_EXCL and O_CREAT set. If O_EXCL is set and +O_CREAT is not set, the effect is undefined. +.LP +If flags other than O_CREAT and O_EXCL are specified in the \fIoflag\fP +parameter, the effect is unspecified. +.sp +.LP +The \fIname\fP argument points to a string naming a semaphore object. +It is unspecified whether the name appears in the file +system and is visible to functions that take pathnames as arguments. +The \fIname\fP argument conforms to the construction rules +for a pathname. If \fIname\fP begins with the slash character, then +processes calling \fIsem_open\fP() with the same value of +\fIname\fP shall refer to the same semaphore object, as long as that +name has not been removed. If \fIname\fP does not begin with +the slash character, the effect is implementation-defined. The interpretation +of slash characters other than the leading slash +character in \fIname\fP is implementation-defined. +.LP +If a process makes multiple successful calls to \fIsem_open\fP() with +the same value for \fIname\fP, the same semaphore +address shall be returned for each such successful call, provided +that there have been no calls to \fIsem_unlink\fP() for this semaphore. +.LP +References to copies of the semaphore produce undefined results. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIsem_open\fP() function shall return +the address of the semaphore. Otherwise, it shall return +a value of SEM_FAILED and set \fIerrno\fP to indicate the error. The +symbol SEM_FAILED is defined in the \fI\fP header. No +successful return from \fIsem_open\fP() shall return the +value SEM_FAILED. +.SH ERRORS +.LP +If any of the following conditions occur, the \fIsem_open\fP() function +shall return SEM_FAILED and set \fIerrno\fP to the +corresponding value: +.TP 7 +.B EACCES +The named semaphore exists and the permissions specified by \fIoflag\fP +are denied, or the named semaphore does not exist and +permission to create the named semaphore is denied. +.TP 7 +.B EEXIST +O_CREAT and O_EXCL are set and the named semaphore already exists. +.TP 7 +.B EINTR +The \fIsem_open\fP() operation was interrupted by a signal. +.TP 7 +.B EINVAL +The \fIsem_open\fP() operation is not supported for the given name, +or O_CREAT was specified in \fIoflag\fP and \fIvalue\fP +was greater than {SEM_VALUE_MAX}. +.TP 7 +.B EMFILE +Too many semaphore descriptors or file descriptors are currently in +use by this process. +.TP 7 +.B ENAMETOOLONG +The length of the \fIname\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENFILE +Too many semaphores are currently open in the system. +.TP 7 +.B ENOENT +O_CREAT is not set and the named semaphore does not exist. +.TP 7 +.B ENOSPC +There is insufficient space for the creation of the new named semaphore. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIsem_open\fP() function is part of the Semaphores option and +need not be available on all implementations. +.SH RATIONALE +.LP +Early drafts required an error return value of -1 with the type \fBsem_t +*\fP for the \fIsem_open\fP() function, which is not +guaranteed to be portable across implementations. The revised text +provides the symbolic error code SEM_FAILED to eliminate the +type conflict. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsemctl\fP() , \fIsemget\fP() , \fIsemop\fP() +, \fIsem_close\fP() , \fIsem_post\fP() , \fIsem_timedwait\fP() , \fIsem_trywait\fP() +, \fIsem_unlink\fP() , \fIsem_wait\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sem_post.3p b/man3p/sem_post.3p new file mode 100644 index 000000000..49e308c37 --- /dev/null +++ b/man3p/sem_post.3p @@ -0,0 +1,88 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SEM_POST" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sem_post +.SH NAME +sem_post \- unlock a semaphore (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sem_post(sem_t *\fP\fIsem\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsem_post\fP() function shall unlock the semaphore referenced +by \fIsem\fP by performing a semaphore unlock operation on +that semaphore. +.LP +If the semaphore value resulting from this operation is positive, +then no threads were blocked waiting for the semaphore to +become unlocked; the semaphore value is simply incremented. +.LP +If the value of the semaphore resulting from this operation is zero, +then one of the threads blocked waiting for the semaphore +shall be allowed to return successfully from its call to \fIsem_wait\fP(). +\ If the Process +Scheduling option is supported, the thread to be unblocked shall be +chosen in a manner appropriate to the scheduling policies and +parameters in effect for the blocked threads. In the case of the schedulers +SCHED_FIFO and SCHED_RR, the highest priority waiting +thread shall be unblocked, and if there is more than one highest priority +thread blocked waiting for the semaphore, then the +highest priority thread that has been waiting the longest shall be +unblocked. If the Process Scheduling option is not defined, the +choice of a thread to unblock is unspecified. +.LP +If +the Process Sporadic Server option is supported, and the scheduling +policy is SCHED_SPORADIC, the semantics are as per SCHED_FIFO +above. +.LP +The \fIsem_post\fP() function shall be reentrant with respect to signals +and may be invoked from a signal-catching +function. +.SH RETURN VALUE +.LP +If successful, the \fIsem_post\fP() function shall return zero; otherwise, +the function shall return -1 and set \fIerrno\fP to +indicate the error. +.SH ERRORS +.LP +The \fIsem_post\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fIsem\fP argument does not refer to a valid semaphore. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIsem_post\fP() function is part of the Semaphores option and +need not be available on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsemctl\fP() , \fIsemget\fP() , \fIsemop\fP() +, \fIsem_timedwait\fP() , \fIsem_trywait\fP() , \fIsem_wait\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sem_timedwait.3p b/man3p/sem_timedwait.3p new file mode 100644 index 000000000..b0e7f18d9 --- /dev/null +++ b/man3p/sem_timedwait.3p @@ -0,0 +1,114 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SEM_TIMEDWAIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sem_timedwait +.SH NAME +sem_timedwait \- lock a semaphore (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int sem_timedwait(sem_t *restrict\fP \fIsem\fP\fB, +.br +\ \ \ \ \ \ const struct timespec *restrict\fP \fIabs_timeout\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsem_timedwait\fP() function shall lock the semaphore referenced +by \fIsem\fP as in the \fIsem_wait\fP() function. However, if the +semaphore cannot be locked without waiting for another +process or thread to unlock the semaphore by performing a \fIsem_post\fP() +function, this +wait shall be terminated when the specified timeout expires. +.LP +The timeout shall expire when the absolute time specified by \fIabs_timeout\fP +passes, as measured by the clock on which +timeouts are based (that is, when the value of that clock equals or +exceeds \fIabs_timeout\fP), or if the absolute time specified +by \fIabs_timeout\fP has already been passed at the time of the call. +.LP +If the Timers option is supported, the timeout shall be based on the +CLOCK_REALTIME clock. If the Timers option is not supported, +the timeout shall be based on the system clock as returned by the +\fItime\fP() function. The +resolution of the timeout shall be the resolution of the clock on +which it is based. The \fBtimespec\fP data type is defined as a +structure in the \fI\fP header. +.LP +Under no circumstance shall the function fail with a timeout if the +semaphore can be locked immediately. The validity of the +\fIabs_timeout\fP need not be checked if the semaphore can be locked +immediately. +.SH RETURN VALUE +.LP +The \fIsem_timedwait\fP() function shall return zero if the calling +process successfully performed the semaphore lock operation +on the semaphore designated by \fIsem\fP. If the call was unsuccessful, +the state of the semaphore shall be unchanged, and the +function shall return a value of -1 and set \fIerrno\fP to indicate +the error. +.SH ERRORS +.LP +The \fIsem_timedwait\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fIsem\fP argument does not refer to a valid semaphore. +.TP 7 +.B EINVAL +The process or thread would have blocked, and the \fIabs_timeout\fP +parameter specified a nanoseconds field value less than +zero or greater than or equal to 1000 million. +.TP 7 +.B ETIMEDOUT +The semaphore could not be locked before the specified timeout expired. +.sp +.LP +The \fIsem_timedwait\fP() function may fail if: +.TP 7 +.B EDEADLK +A deadlock condition was detected. +.TP 7 +.B EINTR +A signal interrupted this function. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications using these functions may be subject to priority inversion, +as discussed in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 3.285, Priority Inversion. +.LP +The \fIsem_timedwait\fP() function is part of the Semaphores and Timeouts +options and need not be provided on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsem_post\fP() , \fIsem_trywait\fP() , \fIsem_wait\fP() , \fIsemctl\fP() +, \fIsemget\fP() , \fIsemop\fP() , \fItime\fP() , the Base Definitions +volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sem_trywait.3p b/man3p/sem_trywait.3p new file mode 100644 index 000000000..d7dd6ad30 --- /dev/null +++ b/man3p/sem_trywait.3p @@ -0,0 +1 @@ +.so man3p/sem_wait.3p diff --git a/man3p/sem_unlink.3p b/man3p/sem_unlink.3p new file mode 100644 index 000000000..08afc5d4c --- /dev/null +++ b/man3p/sem_unlink.3p @@ -0,0 +1,79 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SEM_UNLINK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sem_unlink +.SH NAME +sem_unlink \- remove a named semaphore (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sem_unlink(const char *\fP\fIname\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsem_unlink\fP() function shall remove the semaphore named by +the string \fIname\fP. If the semaphore named by +\fIname\fP is currently referenced by other processes, then \fIsem_unlink\fP() +shall have no effect on the state of the +semaphore. If one or more processes have the semaphore open when \fIsem_unlink\fP() +is called, destruction of the semaphore is +postponed until all references to the semaphore have been destroyed +by calls to \fIsem_close\fP(), \fI_exit\fP(), or \fIexec\fP. Calls +to \fIsem_open\fP() to recreate or reconnect +to the semaphore refer to a new semaphore after \fIsem_unlink\fP() +is called. The \fIsem_unlink\fP() call shall not block until +all references have been destroyed; it shall return immediately. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIsem_unlink\fP() function shall +return a value of 0. Otherwise, the semaphore shall not be +changed and the function shall return a value of -1 and set \fIerrno\fP +to indicate the error. +.SH ERRORS +.LP +The \fIsem_unlink\fP() function shall fail if: +.TP 7 +.B EACCES +Permission is denied to unlink the named semaphore. +.TP 7 +.B ENAMETOOLONG +The length of the \fIname\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +The named semaphore does not exist. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIsem_unlink\fP() function is part of the Semaphores option and +need not be available on all implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsemctl\fP() , \fIsemget\fP() , \fIsemop\fP() +, \fIsem_close\fP() , \fIsem_open\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sem_wait.3p b/man3p/sem_wait.3p new file mode 100644 index 000000000..9b4c6419f --- /dev/null +++ b/man3p/sem_wait.3p @@ -0,0 +1,101 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SEM_TRYWAIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sem_trywait +.SH NAME +sem_trywait, sem_wait \- lock a semaphore (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sem_trywait(sem_t *\fP\fIsem\fP\fB); +.br +int sem_wait(sem_t *\fP\fIsem\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsem_trywait\fP() function shall lock the semaphore referenced +by \fIsem\fP only if the semaphore is currently not +locked; that is, if the semaphore value is currently positive. Otherwise, +it shall not lock the semaphore. +.LP +The \fIsem_wait\fP() function shall lock the semaphore referenced +by \fIsem\fP by performing a semaphore lock operation on +that semaphore. If the semaphore value is currently zero, then the +calling thread shall not return from the call to +\fIsem_wait\fP() until it either locks the semaphore or the call is +interrupted by a signal. +.LP +Upon successful return, the state of the semaphore shall be locked +and shall remain locked until the \fIsem_post\fP() function is executed +and returns successfully. +.LP +The \fIsem_wait\fP() function is interruptible by the delivery of +a signal. +.SH RETURN VALUE +.LP +The \fIsem_trywait\fP() and \fIsem_wait\fP() functions shall return +zero if the calling process successfully performed the +semaphore lock operation on the semaphore designated by \fIsem\fP. +If the call was unsuccessful, the state of the semaphore shall +be unchanged, and the function shall return a value of -1 and set +\fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIsem_trywait\fP() and \fIsem_wait\fP() functions shall fail +if: +.TP 7 +.B EAGAIN +The semaphore was already locked, so it cannot be immediately locked +by the \fIsem_trywait\fP() operation ( +\fIsem_trywait\fP() only). +.TP 7 +.B EINVAL +The \fIsem\fP argument does not refer to a valid semaphore. +.sp +.LP +The \fIsem_trywait\fP() and \fIsem_wait\fP() functions may fail if: +.TP 7 +.B EDEADLK +A deadlock condition was detected. +.TP 7 +.B EINTR +A signal interrupted this function. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications using these functions may be subject to priority inversion, +as discussed in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 3.285, Priority Inversion. +.LP +The \fIsem_trywait\fP() and \fIsem_wait\fP() functions are part of +the Semaphores option and need not be provided on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsemctl\fP() , \fIsemget\fP() , \fIsemop\fP() +, \fIsem_post\fP() , \fIsem_timedwait\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/semctl.3p b/man3p/semctl.3p new file mode 100644 index 000000000..ea9baebe2 --- /dev/null +++ b/man3p/semctl.3p @@ -0,0 +1,227 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SEMCTL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" semctl +.SH NAME +semctl \- XSI semaphore control operations +.SH SYNOPSIS +.LP +\fB#include\ +.br +.sp +int semctl(int\fP \fIsemid\fP\fB, int\fP \fIsemnum\fP\fB, int\fP \fIcmd\fP\fB, +\&...); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsemctl\fP() function operates on XSI semaphores (see the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.15, Semaphore). +It is unspecified whether this function interoperates +with the realtime interprocess communication facilities defined in +\fIRealtime\fP . +.LP +The \fIsemctl\fP() function provides a variety of semaphore control +operations as specified by \fIcmd\fP. The fourth argument +is optional and depends upon the operation requested. If required, +it is of type \fBunion semun\fP, which the application shall +explicitly declare: +.sp +.RS +.nf + +\fBunion semun { + int val; + struct semid_ds *buf; + unsigned short *array; +} arg; +\fP +.fi +.RE +.LP +The following semaphore control operations as specified by \fIcmd\fP +are executed with respect to the semaphore specified by +\fIsemid\fP and \fIsemnum\fP. The level of permission required for +each operation is shown with each command; see \fIXSI Interprocess +Communication\fP . The symbolic names for the values of \fIcmd\fP +are +defined in the \fI\fP header: +.TP 7 +GETVAL +Return the value of \fIsemval\fP; see \fI\fP. Requires +read +permission. +.TP 7 +SETVAL +Set the value of \fIsemval\fP to \fIarg.val\fP, where \fIarg\fP is +the value of the fourth argument to \fIsemctl\fP(). When +this command is successfully executed, the \fIsemadj\fP value corresponding +to the specified semaphore in all processes is +cleared. Requires alter permission; see \fIXSI Interprocess Communication\fP +\&. +.TP 7 +GETPID +Return the value of \fIsempid\fP. Requires read permission. +.TP 7 +GETNCNT +Return the value of \fIsemncnt\fP. Requires read permission. +.TP 7 +GETZCNT +Return the value of \fIsemzcnt\fP. Requires read permission. +.sp +.LP +The following values of \fIcmd\fP operate on each \fIsemval\fP in +the set of semaphores: +.TP 7 +GETALL +Return the value of \fIsemval\fP for each semaphore in the semaphore +set and place into the array pointed to by +\fIarg.array\fP, where \fIarg\fP is the fourth argument to \fIsemctl\fP(). +Requires read permission. +.TP 7 +SETALL +Set the value of \fIsemval\fP for each semaphore in the semaphore +set according to the array pointed to by \fIarg.array\fP, +where \fIarg\fP is the fourth argument to \fIsemctl\fP(). When this +command is successfully executed, the \fIsemadj\fP values +corresponding to each specified semaphore in all processes are cleared. +Requires alter permission. +.sp +.LP +The following values of \fIcmd\fP are also available: +.TP 7 +IPC_STAT +Place the current value of each member of the \fBsemid_ds\fP data +structure associated with \fIsemid\fP into the structure +pointed to by \fIarg.buf\fP, where \fIarg\fP is the fourth argument +to \fIsemctl\fP(). The contents of this structure are +defined in \fI\fP. Requires read permission. +.TP 7 +IPC_SET +Set the value of the following members of the \fBsemid_ds\fP data +structure associated with \fIsemid\fP to the corresponding +value found in the structure pointed to by \fIarg.buf\fP, where \fIarg\fP +is the fourth argument to \fIsemctl\fP(): +.sp +.RS +.nf + +\fBsem_perm.uid +sem_perm.gid +sem_perm.mode +\fP +.fi +.RE +.LP +The mode bits specified in \fIIPC General Description\fP are copied +into the +corresponding bits of the \fIsem_perm.mode\fP associated with \fIsemid\fP. +The stored values of any other bits are +unspecified. +.LP +This command can only be executed by a process that has an effective +user ID equal to either that of a process with appropriate +privileges or to the value of \fIsem_perm.cuid\fP or \fIsem_perm.uid\fP +in the \fBsemid_ds\fP data structure associated with +\fIsemid\fP. +.TP 7 +IPC_RMID +Remove the semaphore identifier specified by \fIsemid\fP from the +system and destroy the set of semaphores and \fBsemid_ds\fP +data structure associated with it. This command can only be executed +by a process that has an effective user ID equal to either +that of a process with appropriate privileges or to the value of \fIsem_perm.cuid\fP +or \fIsem_perm.uid\fP in the \fBsemid_ds\fP +data structure associated with \fIsemid\fP. +.sp +.SH RETURN VALUE +.LP +If successful, the value returned by \fIsemctl\fP() depends on \fIcmd\fP +as follows: +.TP 7 +GETVAL +The value of \fIsemval\fP. +.TP 7 +GETPID +The value of \fIsempid\fP. +.TP 7 +GETNCNT +The value of \fIsemncnt\fP. +.TP 7 +GETZCNT +The value of \fIsemzcnt\fP. +.TP 7 +All others +0. +.sp +.LP +Otherwise, \fIsemctl\fP() shall return -1 and set \fIerrno\fP to indicate +the error. +.SH ERRORS +.LP +The \fIsemctl\fP() function shall fail if: +.TP 7 +.B EACCES +Operation permission is denied to the calling process; see \fIXSI +Interprocess +Communication\fP . +.TP 7 +.B EINVAL +The value of \fIsemid\fP is not a valid semaphore identifier, or the +value of \fIsemnum\fP is less than 0 or greater than or +equal to \fIsem_nsems\fP, or the value of \fIcmd\fP is not a valid +command. +.TP 7 +.B EPERM +The argument \fIcmd\fP is equal to IPC_RMID or IPC_SET and the effective +user ID of the calling process is not equal to that +of a process with appropriate privileges and it is not equal to the +value of \fIsem_perm.cuid\fP or \fIsem_perm.uid\fP in the +data structure associated with \fIsemid\fP. +.TP 7 +.B ERANGE +The argument \fIcmd\fP is equal to SETVAL or SETALL and the value +to which \fIsemval\fP is to be set is greater than the +system-imposed maximum. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The fourth parameter in the SYNOPSIS section is now specified as \fB"..."\fP +in order to avoid a clash with the ISO\ C +standard when referring to the union \fIsemun\fP (as defined in Issue +3) and for backwards-compatibility. +.LP +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to +use IPC should design their applications so that modules using the +IPC routines described in \fIXSI Interprocess Communication\fP can +be easily modified to use the alternative +interfaces. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIXSI Interprocess Communication\fP , \fIRealtime\fP , \fIsemget\fP() +, \fIsemop\fP() , \fIsem_close\fP() , \fIsem_destroy\fP() , \fIsem_getvalue\fP() +, \fIsem_init\fP() , \fIsem_open\fP() , \fIsem_post\fP() , \fIsem_unlink\fP() +, \fIsem_wait\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/semget.3p b/man3p/semget.3p new file mode 100644 index 000000000..cbbda746c --- /dev/null +++ b/man3p/semget.3p @@ -0,0 +1,212 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SEMGET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" semget +.SH NAME +semget \- get set of XSI semaphores +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int semget(key_t\fP \fIkey\fP\fB, int\fP \fInsems\fP\fB, int\fP \fIsemflg\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsemget\fP() function operates on XSI semaphores (see the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.15, Semaphore). +It is unspecified whether this function interoperates +with the realtime interprocess communication facilities defined in +\fIRealtime\fP . +.LP +The \fIsemget\fP() function shall return the semaphore identifier +associated with \fIkey\fP. +.LP +A semaphore identifier with its associated \fBsemid_ds\fP data structure +and its associated set of \fInsems\fP semaphores (see +\fI\fP) is created for \fIkey\fP if one of the following +is true: +.IP " *" 3 +The argument \fIkey\fP is equal to IPC_PRIVATE. +.LP +.IP " *" 3 +The argument \fIkey\fP does not already have a semaphore identifier +associated with it and (\fIsemflg\fP &IPC_CREAT) is +non-zero. +.LP +.LP +Upon creation, the \fBsemid_ds\fP data structure associated with the +new semaphore identifier is initialized as follows: +.IP " *" 3 +In the operation permissions structure \fIsem_perm.cuid\fP, \fIsem_perm.uid\fP, +\fIsem_perm.cgid\fP, and \fIsem_perm.gid\fP +shall be set equal to the effective user ID and effective group ID, +respectively, of the calling process. +.LP +.IP " *" 3 +The low-order 9 bits of \fIsem_perm.mode\fP shall be set equal to +the low-order 9 bits of \fIsemflg\fP. +.LP +.IP " *" 3 +The variable \fIsem_nsems\fP shall be set equal to the value of \fInsems\fP. +.LP +.IP " *" 3 +The variable \fIsem_otime\fP shall be set equal to 0 and \fIsem_ctime\fP +shall be set equal to the current time. +.LP +.IP " *" 3 +The data structure associated with each semaphore in the set shall +not be initialized. The \fIsemctl\fP() function with the command SETVAL +or SETALL can be used to initialize each +semaphore. +.LP +.SH RETURN VALUE +.LP +Upon successful completion, \fIsemget\fP() shall return a non-negative +integer, namely a semaphore identifier; otherwise, it +shall return -1 and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIsemget\fP() function shall fail if: +.TP 7 +.B EACCES +A semaphore identifier exists for \fIkey\fP, but operation permission +as specified by the low-order 9 bits of \fIsemflg\fP +would not be granted; see \fIXSI Interprocess Communication\fP . +.TP 7 +.B EEXIST +A semaphore identifier exists for the argument \fIkey\fP but ((\fIsemflg\fP +&IPC_CREAT) &&(\fIsemflg\fP +&IPC_EXCL)) is non-zero. +.TP 7 +.B EINVAL +The value of \fInsems\fP is either less than or equal to 0 or greater +than the system-imposed limit, or a semaphore identifier +exists for the argument \fIkey\fP, but the number of semaphores in +the set associated with it is less than \fInsems\fP and +\fInsems\fP is not equal to 0. +.TP 7 +.B ENOENT +A semaphore identifier does not exist for the argument \fIkey\fP and +(\fIsemflg\fP &IPC_CREAT) is equal to 0. +.TP 7 +.B ENOSPC +A semaphore identifier is to be created but the system-imposed limit +on the maximum number of allowed semaphores system-wide +would be exceeded. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Creating a Semaphore Identifier +.LP +The following example gets a unique semaphore key using the \fIftok\fP() +function, then +gets a semaphore ID associated with that key using the \fIsemget\fP() +function (the first call also tests to make sure the +semaphore exists). If the semaphore does not exist, the program creates +it, as shown by the second call to \fIsemget\fP(). In +creating the semaphore for the queuing process, the program attempts +to create one semaphore with read/write permission for all. It +also uses the IPC_EXCL flag, which forces \fIsemget\fP() to fail if +the semaphore already exists. +.LP +After creating the semaphore, the program uses a call to \fIsemop\fP() +to initialize it +to the values in the \fIsbuf\fP array. The number of processes that +can execute concurrently without queuing is initially set to +2. The final call to \fIsemget\fP() creates a semaphore identifier +that can be used later in the program. +.sp +.RS +.nf + +\fB#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +\&... +key_t semkey; +int semid, pfd, fv; +struct sembuf sbuf; +char *lgn; +char filename[PATH_MAX+1]; +struct stat outstat; +struct passwd *pw; +\&... +/* Get unique key for semaphore. */ +if ((semkey = ftok("/tmp", 'a')) == (key_t) -1) { + perror("IPC error: ftok"); exit(1); +} +.sp + +/* Get semaphore ID associated with this key. */ +if ((semid = semget(semkey, 0, 0)) == -1) { +.sp + + /* Semaphore does not exist - Create. */ + if ((semid = semget(semkey, 1, IPC_CREAT | IPC_EXCL | S_IRUSR | + S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH)) != -1) + { + /* Initialize the semaphore. */ + sbuf.sem_num = 0; + sbuf.sem_op = 2; /* This is the number of runs + without queuing. */ + sbuf.sem_flg = 0; + if (semop(semid, &sbuf, 1) == -1) { + perror("IPC error: semop"); exit(1); + } + } + else if (errno == EEXIST) { + if ((semid = semget(semkey, 0, 0)) == -1) { + perror("IPC error 1: semget"); exit(1); + } + } + else { + perror("IPC error 2: semget"); exit(1); + } +} +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to +use IPC should design their applications so that modules using the +IPC routines described in \fIXSI Interprocess Communication\fP can +be easily modified to use the alternative +interfaces. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIXSI Interprocess Communication\fP , \fIRealtime\fP , \fIsemctl\fP() +, \fIsemop\fP() , \fIsem_close\fP() , \fIsem_destroy\fP() , \fIsem_getvalue\fP() +, \fIsem_init\fP() , \fIsem_open\fP() , \fIsem_post\fP() , \fIsem_unlink\fP() +, \fIsem_wait\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/semop.3p b/man3p/semop.3p new file mode 100644 index 000000000..dafdffe52 --- /dev/null +++ b/man3p/semop.3p @@ -0,0 +1,348 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SEMOP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" semop +.SH NAME +semop \- XSI semaphore operations +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int semop(int\fP \fIsemid\fP\fB, struct sembuf *\fP\fIsops\fP\fB, +size_t\fP \fInsops\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsemop\fP() function operates on XSI semaphores (see the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.15, Semaphore). +It is unspecified whether this function interoperates +with the realtime interprocess communication facilities defined in +\fIRealtime\fP . +.LP +The \fIsemop\fP() function shall perform atomically a user-defined +array of semaphore operations on the set of semaphores +associated with the semaphore identifier specified by the argument +\fIsemid\fP. +.LP +The argument \fIsops\fP is a pointer to a user-defined array of semaphore +operation structures. The implementation shall not +modify elements of this array unless the application uses implementation-defined +extensions. +.LP +The argument \fInsops\fP is the number of such structures in the array. +.LP +Each structure, \fBsembuf\fP, includes the following members: +.TS C +center; l2 l2 l. +\fBMember Type\fP \fBMember Name\fP \fBDescription\fP +\fBshort\fP \fIsem_num\fP Semaphore number. +\fBshort\fP \fIsem_op\fP Semaphore operation. +\fBshort\fP \fIsem_flg\fP Operation flags. +.TE +.LP +Each semaphore operation specified by \fIsem_op\fP is performed on +the corresponding semaphore specified by \fIsemid\fP and +\fIsem_num\fP. +.LP +The variable \fIsem_op\fP specifies one of three semaphore operations: +.IP " 1." 4 +If \fIsem_op\fP is a negative integer and the calling process has +alter permission, one of the following shall occur: +.RS +.IP " *" 3 +If \fIsemval\fP(see \fI\fP) is greater than or equal to +the absolute +value of \fIsem_op\fP, the absolute value of \fIsem_op\fP is subtracted +from \fIsemval\fP. Also, if (\fIsem_flg\fP +&SEM_UNDO) is non-zero, the absolute value of \fIsem_op\fP shall be +added to the calling process' \fIsemadj\fP value for the +specified semaphore. +.LP +.IP " *" 3 +If \fIsemval\fP is less than the absolute value of \fIsem_op\fP and +(\fIsem_flg\fP &IPC_NOWAIT) is non-zero, +\fIsemop\fP() shall return immediately. +.LP +.IP " *" 3 +If \fIsemval\fP is less than the absolute value of \fIsem_op\fP and +(\fIsem_flg\fP &IPC_NOWAIT) is 0, \fIsemop\fP() +shall increment the \fIsemncnt\fP associated with the specified semaphore +and suspend execution of the calling thread until one of +the following conditions occurs: +.RS +.IP " *" 3 +The value of \fIsemval\fP becomes greater than or equal to the absolute +value of \fIsem_op\fP. When this occurs, the value of +\fIsemncnt\fP associated with the specified semaphore shall be decremented, +the absolute value of \fIsem_op\fP shall be +subtracted from \fIsemval\fP and, if (\fIsem_flg\fP &SEM_UNDO) is +non-zero, the absolute value of \fIsem_op\fP shall be +added to the calling process' \fIsemadj\fP value for the specified +semaphore. +.LP +.IP " *" 3 +The \fIsemid\fP for which the calling thread is awaiting action is +removed from the system. When this occurs, \fIerrno\fP +shall be set equal to [EIDRM] and -1 shall be returned. +.LP +.IP " *" 3 +The calling thread receives a signal that is to be caught. When this +occurs, the value of \fIsemncnt\fP associated with the +specified semaphore shall be decremented, and the calling thread shall +resume execution in the manner prescribed in \fIsigaction\fP() . +.LP +.RE +.LP +.RE +.LP +.IP " 2." 4 +If \fIsem_op\fP is a positive integer and the calling process has +alter permission, the value of \fIsem_op\fP shall be added +to \fIsemval\fP and, if (\fIsem_flg\fP &SEM_UNDO) is non-zero, the +value of \fIsem_op\fP shall be subtracted from the +calling process' \fIsemadj\fP value for the specified semaphore. +.LP +.IP " 3." 4 +If \fIsem_op\fP is 0 and the calling process has read permission, +one of the following shall occur: +.RS +.IP " *" 3 +If \fIsemval\fP is 0, \fIsemop\fP() shall return immediately. +.LP +.IP " *" 3 +If \fIsemval\fP is non-zero and (\fIsem_flg\fP &IPC_NOWAIT) is non-zero, +\fIsemop\fP() shall return immediately. +.LP +.IP " *" 3 +If \fIsemval\fP is non-zero and (\fIsem_flg\fP &IPC_NOWAIT) is 0, +\fIsemop\fP() shall increment the \fIsemzcnt\fP +associated with the specified semaphore and suspend execution of the +calling thread until one of the following occurs: +.RS +.IP " *" 3 +The value of \fIsemval\fP becomes 0, at which time the value of \fIsemzcnt\fP +associated with the specified semaphore shall be +decremented. +.LP +.IP " *" 3 +The \fIsemid\fP for which the calling thread is awaiting action is +removed from the system. When this occurs, \fIerrno\fP +shall be set equal to [EIDRM] and -1 shall be returned. +.LP +.IP " *" 3 +The calling thread receives a signal that is to be caught. When this +occurs, the value of \fIsemzcnt\fP associated with the +specified semaphore shall be decremented, and the calling thread shall +resume execution in the manner prescribed in \fIsigaction\fP() . +.LP +.RE +.LP +.RE +.LP +.LP +Upon successful completion, the value of \fIsempid\fP for each semaphore +specified in the array pointed to by \fIsops\fP shall +be set equal to the process ID of the calling process. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsemop\fP() shall return 0; otherwise, +it shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fIsemop\fP() function shall fail if: +.TP 7 +.B E2BIG +The value of \fInsops\fP is greater than the system-imposed maximum. +.TP 7 +.B EACCES +Operation permission is denied to the calling process; see \fIXSI +Interprocess +Communication\fP . +.TP 7 +.B EAGAIN +The operation would result in suspension of the calling process but +(\fIsem_flg\fP &IPC_NOWAIT) is non-zero. +.TP 7 +.B EFBIG +The value of \fIsem_num\fP is less than 0 or greater than or equal +to the number of semaphores in the set associated with +\fIsemid\fP. +.TP 7 +.B EIDRM +The semaphore identifier \fIsemid\fP is removed from the system. +.TP 7 +.B EINTR +The \fIsemop\fP() function was interrupted by a signal. +.TP 7 +.B EINVAL +The value of \fIsemid\fP is not a valid semaphore identifier, or the +number of individual semaphores for which the calling +process requests a SEM_UNDO would exceed the system-imposed limit. +.TP 7 +.B ENOSPC +The limit on the number of individual processes requesting a SEM_UNDO +would be exceeded. +.TP 7 +.B ERANGE +An operation would cause a \fIsemval\fP to overflow the system-imposed +limit, or an operation would cause a \fIsemadj\fP +value to overflow the system-imposed limit. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Setting Values in Semaphores +.LP +The following example sets the values of the two semaphores associated +with the \fIsemid\fP identifier to the values contained +in the \fIsb\fP array. +.sp +.RS +.nf + +\fB#include +\&... +int semid; +struct sembuf sb[2]; +int nsops = 2; +int result; +.sp + +/* Adjust value of semaphore in the semaphore array semid. */ +sb[0].sem_num = 0; +sb[0].sem_op = -1; +sb[0].sem_flg = SEM_UNDO | IPC_NOWAIT; +sb[1].sem_num = 1; +sb[1].sem_op = 1; +sb[1].sem_flg = 0; +.sp + +result = semop(semid, sb, nsops); +\fP +.fi +.RE +.SS Creating a Semaphore Identifier +.LP +The following example gets a unique semaphore key using the \fIftok\fP() +function, then +gets a semaphore ID associated with that key using the \fIsemget\fP() +function (the first +call also tests to make sure the semaphore exists). If the semaphore +does not exist, the program creates it, as shown by the second +call to \fIsemget\fP(). In creating the semaphore for the queuing +process, the program +attempts to create one semaphore with read/write permission for all. +It also uses the IPC_EXCL flag, which forces \fIsemget\fP() to fail +if the semaphore already exists. +.LP +After creating the semaphore, the program uses a call to \fIsemop\fP() +to initialize it to the values in the \fIsbuf\fP array. +The number of processes that can execute concurrently without queuing +is initially set to 2. The final call to \fIsemget\fP() creates a +semaphore identifier that can be used later in the program. +.LP +The final call to \fIsemop\fP() acquires the semaphore and waits until +it is free; the SEM_UNDO option releases the semaphore +when the process exits, waiting until there are less than two processes +running concurrently. +.sp +.RS +.nf + +\fB#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +\&... +key_t semkey; +int semid, pfd, fv; +struct sembuf sbuf; +char *lgn; +char filename[PATH_MAX+1]; +struct stat outstat; +struct passwd *pw; +\&... +/* Get unique key for semaphore. */ +if ((semkey = ftok("/tmp", 'a')) == (key_t) -1) { + perror("IPC error: ftok"); exit(1); +} +.sp + +/* Get semaphore ID associated with this key. */ +if ((semid = semget(semkey, 0, 0)) == -1) { +.sp + + /* Semaphore does not exist - Create. */ + if ((semid = semget(semkey, 1, IPC_CREAT | IPC_EXCL | S_IRUSR | + S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH)) != -1) + { + /* Initialize the semaphore. */ + sbuf.sem_num = 0; + sbuf.sem_op = 2; /* This is the number of runs without queuing. */ + sbuf.sem_flg = 0; + if (semop(semid, &sbuf, 1) == -1) { + perror("IPC error: semop"); exit(1); + } + } + else if (errno == EEXIST) { + if ((semid = semget(semkey, 0, 0)) == -1) { + perror("IPC error 1: semget"); exit(1); + } + } + else { + perror("IPC error 2: semget"); exit(1); + } +} +\&... +sbuf.sem_num = 0; +sbuf.sem_op = -1; +sbuf.sem_flg = SEM_UNDO; +if (semop(semid, &sbuf, 1) == -1) { + perror("IPC Error: semop"); exit(1); +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to +use IPC should design their applications so that modules using the +IPC routines described in \fIXSI Interprocess Communication\fP can +be easily modified to use the alternative +interfaces. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIXSI Interprocess Communication\fP , \fIRealtime\fP , \fIexec\fP() +, +\fIexit\fP() , \fIfork\fP() , \fIsemctl\fP() , \fIsemget\fP() , \fIsem_close\fP() +, \fIsem_destroy\fP() , \fIsem_getvalue\fP() , \fIsem_init\fP() , +\fIsem_open\fP() , \fIsem_post\fP() , \fIsem_unlink\fP() , \fIsem_wait\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/send.3p b/man3p/send.3p new file mode 100644 index 000000000..c3bf82710 --- /dev/null +++ b/man3p/send.3p @@ -0,0 +1,173 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SEND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" send +.SH NAME +send \- send a message on a socket +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +ssize_t send(int\fP \fIsocket\fP\fB, const void *\fP\fIbuffer\fP\fB, +size_t\fP \fIlength\fP\fB, int\fP +\fIflags\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsend\fP() function shall initiate transmission of a message +from the specified socket to its peer. The \fIsend\fP() +function shall send a message only when the socket is connected (including +when the peer of a connectionless socket has been set +via \fIconnect\fP()). +.LP +The \fIsend\fP() function takes the following arguments: +.TP 7 +\fIsocket\fP +Specifies the socket file descriptor. +.TP 7 +\fIbuffer\fP +Points to the buffer containing the message to send. +.TP 7 +\fIlength\fP +Specifies the length of the message in bytes. +.TP 7 +\fIflags\fP +Specifies the type of message transmission. Values of this argument +are formed by logically OR'ing zero or more of the +following flags: +.TP 7 +MSG_EOR +.RS +Terminates a record (if supported by the protocol). +.RE +.TP 7 +MSG_OOB +.RS +Sends out-of-band data on sockets that support out-of-band communications. +The significance and semantics of out-of-band data +are protocol-specific. +.RE +.sp +.sp +.LP +The length of the message to be sent is specified by the \fIlength\fP +argument. If the message is too long to pass through the +underlying protocol, \fIsend\fP() shall fail and no data shall be +transmitted. +.LP +Successful completion of a call to \fIsend\fP() does not guarantee +delivery of the message. A return value of -1 indicates only +locally-detected errors. +.LP +If space is not available at the sending socket to hold the message +to be transmitted, and the socket file descriptor does not +have O_NONBLOCK set, \fIsend\fP() shall block until space is available. +If space is not available at the sending socket to hold +the message to be transmitted, and the socket file descriptor does +have O_NONBLOCK set, \fIsend\fP() shall fail. The \fIselect\fP() and +\fIpoll\fP() functions can be used to +determine when it is possible to send more data. +.LP +The socket in use may require the process to have appropriate privileges +to use the \fIsend\fP() function. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsend\fP() shall return the number of +bytes sent. Otherwise, -1 shall be returned and +\fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIsend\fP() function shall fail if: +.TP 7 +.B EAGAIN \fRor\fP EWOULDBLOCK +.sp +The socket's file descriptor is marked O_NONBLOCK and the requested +operation would block. +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid file descriptor. +.TP 7 +.B ECONNRESET +A connection was forcibly closed by a peer. +.TP 7 +.B EDESTADDRREQ +.sp +The socket is not connection-mode and no peer address is set. +.TP 7 +.B EINTR +A signal interrupted \fIsend\fP() before any data was transmitted. +.TP 7 +.B EMSGSIZE +The message is too large to be sent all at once, as the socket requires. +.TP 7 +.B ENOTCONN +The socket is not connected or otherwise has not had the peer pre-specified. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.TP 7 +.B EOPNOTSUPP +The \fIsocket\fP argument is associated with a socket that does not +support one or more of the values set in +\fIflags\fP. +.TP 7 +.B EPIPE +The socket is shut down for writing, or the socket is connection-mode +and is no longer connected. In the latter case, and if +the socket is of type SOCK_STREAM, the SIGPIPE signal is generated +to the calling thread. +.sp +.LP +The \fIsend\fP() function may fail if: +.TP 7 +.B EACCES +The calling process does not have the appropriate privileges. +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to the file system. +.TP 7 +.B ENETDOWN +The local network interface used to reach the destination is down. +.TP 7 +.B ENETUNREACH +.sp +No route to the network is present. +.TP 7 +.B ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIsend\fP() function is equivalent to \fIsendto\fP() with a null +pointer +\fIdest_len\fP argument, and to \fIwrite\fP() if no flags are used. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIconnect\fP() , \fIgetsockopt\fP() , \fIpoll\fP() , \fIrecv\fP() +, \fIrecvfrom\fP() , \fIrecvmsg\fP() , \fIselect\fP() , \fIsendmsg\fP() +, \fIsendto\fP() , \fIsetsockopt\fP() , \fIshutdown\fP() , \fIsocket\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sendmsg.3p b/man3p/sendmsg.3p new file mode 100644 index 000000000..2595ef082 --- /dev/null +++ b/man3p/sendmsg.3p @@ -0,0 +1,231 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SENDMSG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sendmsg +.SH NAME +sendmsg \- send a message on a socket using a message structure +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +ssize_t sendmsg(int\fP \fIsocket\fP\fB, const struct msghdr *\fP\fImessage\fP\fB, +int\fP \fIflags\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsendmsg\fP() function shall send a message through a connection-mode +or connectionless-mode socket. If the socket is +connectionless-mode, the message shall be sent to the address specified +by \fBmsghdr\fP. If the socket is connection-mode, the +destination address in \fBmsghdr\fP shall be ignored. +.LP +The \fIsendmsg\fP() function takes the following arguments: +.TP 7 +\fIsocket\fP +Specifies the socket file descriptor. +.TP 7 +\fImessage\fP +Points to a \fBmsghdr\fP structure, containing both the destination +address and the buffers for the outgoing message. The +length and format of the address depend on the address family of the +socket. The \fImsg_flags\fP member is ignored. +.TP 7 +\fIflags\fP +Specifies the type of message transmission. The application may specify +0 or the following flag: +.TP 7 +MSG_EOR +.RS +Terminates a record (if supported by the protocol). +.RE +.TP 7 +MSG_OOB +.RS +Sends out-of-band data on sockets that support out-of-bound data. +The significance and semantics of out-of-band data are +protocol-specific. +.RE +.sp +.sp +.LP +The \fImsg_iov\fP and \fImsg_iovlen\fP fields of \fImessage\fP specify +zero or more buffers containing the data to be sent. +\fImsg_iov\fP points to an array of \fBiovec\fP structures; \fImsg_iovlen\fP +shall be set to the dimension of this array. In +each \fBiovec\fP structure, the \fIiov_base\fP field specifies a storage +area and the \fIiov_len\fP field gives its size in +bytes. Some of these sizes can be zero. The data from each storage +area indicated by \fImsg_iov\fP is sent in turn. +.LP +Successful completion of a call to \fIsendmsg\fP() does not guarantee +delivery of the message. A return value of -1 indicates +only locally-detected errors. +.LP +If space is not available at the sending socket to hold the message +to be transmitted and the socket file descriptor does not +have O_NONBLOCK set, the \fIsendmsg\fP() function shall block until +space is available. If space is not available at the sending +socket to hold the message to be transmitted and the socket file descriptor +does have O_NONBLOCK set, the \fIsendmsg\fP() function +shall fail. +.LP +If the socket protocol supports broadcast and the specified address +is a broadcast address for the socket protocol, +\fIsendmsg\fP() shall fail if the SO_BROADCAST option is not set for +the socket. +.LP +The socket in use may require the process to have appropriate privileges +to use the \fIsendmsg\fP() function. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsendmsg\fP() shall return the number +of bytes sent. Otherwise, -1 shall be returned and +\fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIsendmsg\fP() function shall fail if: +.TP 7 +.B EAGAIN \fRor\fP EWOULDBLOCK +The socket's file descriptor is marked O_NONBLOCK and the requested +operation would block. +.TP 7 +.B EAFNOSUPPORT +Addresses in the specified address family cannot be used with this +socket. +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid file descriptor. +.TP 7 +.B ECONNRESET +A connection was forcibly closed by a peer. +.TP 7 +.B EINTR +A signal interrupted \fIsendmsg\fP() before any data was transmitted. +.TP 7 +.B EINVAL +The sum of the \fIiov_len\fP values overflows an \fBssize_t\fP. +.TP 7 +.B EMSGSIZE +The message is too large to be sent all at once (as the socket requires), +or the \fImsg_iovlen\fP member of the \fBmsghdr\fP +structure pointed to by \fImessage\fP is less than or equal to 0 or +is greater than {IOV_MAX}. +.TP 7 +.B ENOTCONN +The socket is connection-mode but is not connected. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.TP 7 +.B EOPNOTSUPP +The \fIsocket\fP argument is associated with a socket that does not +support one or more of the values set in +\fIflags\fP. +.TP 7 +.B EPIPE +The socket is shut down for writing, or the socket is connection-mode +and is no longer connected. In the latter case, and if +the socket is of type SOCK_STREAM, the SIGPIPE signal is generated +to the calling thread. +.sp +.LP +If the address family of the socket is AF_UNIX, then \fIsendmsg\fP() +shall fail if: +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to the file system. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +pathname in the socket address. +.TP 7 +.B ENAMETOOLONG +A component of a pathname exceeded {NAME_MAX} characters, or an entire +pathname exceeded {PATH_MAX} characters. +.TP 7 +.B ENOENT +A component of the pathname does not name an existing file or the +path name is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix of the pathname in the socket address +is not a directory. +.sp +.LP +The \fIsendmsg\fP() function may fail if: +.TP 7 +.B EACCES +Search permission is denied for a component of the path prefix; or +write access to the named socket is denied. +.TP 7 +.B EDESTADDRREQ +The socket is not connection-mode and does not have its peer address +set, and no destination address was specified. +.TP 7 +.B EHOSTUNREACH +The destination host cannot be reached (probably because the host +is down or a remote router cannot reach it). +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to the file system. +.TP 7 +.B EISCONN +A destination address was specified and the socket is already connected. +.TP 7 +.B ENETDOWN +The local network interface used to reach the destination is down. +.TP 7 +.B ENETUNREACH +No route to the network is present. +.TP 7 +.B ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP 7 +.B ENOMEM +Insufficient memory was available to fulfill the request. +.sp +.LP +If the address family of the socket is AF_UNIX, then \fIsendmsg\fP() +may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the pathname in the socket address. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +Done. +.SH APPLICATION USAGE +.LP +The \fIselect\fP() and \fIpoll\fP() functions can +be used to determine when it is possible to send more data. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetsockopt\fP() , \fIpoll\fP() , \fIrecv\fP() , \fIrecvfrom\fP() +, \fIrecvmsg\fP() , \fIselect\fP() , \fIsend\fP() , \fIsendto\fP() +, \fIsetsockopt\fP() , \fIshutdown\fP() , \fIsocket\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sendto.3p b/man3p/sendto.3p new file mode 100644 index 000000000..795c8e64e --- /dev/null +++ b/man3p/sendto.3p @@ -0,0 +1,239 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SENDTO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sendto +.SH NAME +sendto \- send a message on a socket +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +ssize_t sendto(int\fP \fIsocket\fP\fB, const void *\fP\fImessage\fP\fB, +size_t\fP \fIlength\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIflags\fP\fB, const struct sockaddr *\fP\fIdest_addr\fP\fB, +.br +\ \ \ \ \ \ socklen_t\fP \fIdest_len\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsendto\fP() function shall send a message through a connection-mode +or connectionless-mode socket. If the socket is +connectionless-mode, the message shall be sent to the address specified +by \fIdest_addr\fP. If the socket is connection-mode, +\fIdest_addr\fP shall be ignored. +.LP +The \fIsendto\fP() function takes the following arguments: +.TP 7 +\fIsocket\fP +Specifies the socket file descriptor. +.TP 7 +\fImessage\fP +Points to a buffer containing the message to be sent. +.TP 7 +\fIlength\fP +Specifies the size of the message in bytes. +.TP 7 +\fIflags\fP +Specifies the type of message transmission. Values of this argument +are formed by logically OR'ing zero or more of the +following flags: +.TP 7 +MSG_EOR +.RS +Terminates a record (if supported by the protocol). +.RE +.TP 7 +MSG_OOB +.RS +Sends out-of-band data on sockets that support out-of-band data. The +significance and semantics of out-of-band data are +protocol-specific. +.RE +.sp +.TP 7 +\fIdest_addr\fP +Points to a \fBsockaddr\fP structure containing the destination address. +The length and format of the address depend on the +address family of the socket. +.TP 7 +\fIdest_len\fP +Specifies the length of the \fBsockaddr\fP structure pointed to by +the \fIdest_addr\fP argument. +.sp +.LP +If the socket protocol supports broadcast and the specified address +is a broadcast address for the socket protocol, +\fIsendto\fP() shall fail if the SO_BROADCAST option is not set for +the socket. +.LP +The \fIdest_addr\fP argument specifies the address of the target. +The \fIlength\fP argument specifies the length of the +message. +.LP +Successful completion of a call to \fIsendto\fP() does not guarantee +delivery of the message. A return value of -1 indicates +only locally-detected errors. +.LP +If space is not available at the sending socket to hold the message +to be transmitted and the socket file descriptor does not +have O_NONBLOCK set, \fIsendto\fP() shall block until space is available. +If space is not available at the sending socket to hold +the message to be transmitted and the socket file descriptor does +have O_NONBLOCK set, \fIsendto\fP() shall fail. +.LP +The socket in use may require the process to have appropriate privileges +to use the \fIsendto\fP() function. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsendto\fP() shall return the number +of bytes sent. Otherwise, -1 shall be returned and +\fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIsendto\fP() function shall fail if: +.TP 7 +.B EAFNOSUPPORT +Addresses in the specified address family cannot be used with this +socket. +.TP 7 +.B EAGAIN \fRor\fP EWOULDBLOCK +The socket's file descriptor is marked O_NONBLOCK and the requested +operation would block. +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid file descriptor. +.TP 7 +.B ECONNRESET +A connection was forcibly closed by a peer. +.TP 7 +.B EINTR +A signal interrupted \fIsendto\fP() before any data was transmitted. +.TP 7 +.B EMSGSIZE +The message is too large to be sent all at once, as the socket requires. +.TP 7 +.B ENOTCONN +The socket is connection-mode but is not connected. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.TP 7 +.B EOPNOTSUPP +The \fIsocket\fP argument is associated with a socket that does not +support one or more of the values set in +\fIflags\fP. +.TP 7 +.B EPIPE +The socket is shut down for writing, or the socket is connection-mode +and is no longer connected. In the latter case, and if +the socket is of type SOCK_STREAM, the SIGPIPE signal is generated +to the calling thread. +.sp +.LP +If the address family of the socket is AF_UNIX, then \fIsendto\fP() +shall fail if: +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to the file system. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +pathname in the socket address. +.TP 7 +.B ENAMETOOLONG +A component of a pathname exceeded {NAME_MAX} characters, or an entire +pathname exceeded {PATH_MAX} characters. +.TP 7 +.B ENOENT +A component of the pathname does not name an existing file or the +pathname is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix of the pathname in the socket address +is not a directory. +.sp +.LP +The \fIsendto\fP() function may fail if: +.TP 7 +.B EACCES +Search permission is denied for a component of the path prefix; or +write access to the named socket is denied. +.TP 7 +.B EDESTADDRREQ +The socket is not connection-mode and does not have its peer address +set, and no destination address was specified. +.TP 7 +.B EHOSTUNREACH +The destination host cannot be reached (probably because the host +is down or a remote router cannot reach it). +.TP 7 +.B EINVAL +The \fIdest_len\fP argument is not a valid length for the address +family. +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to the file system. +.TP 7 +.B EISCONN +A destination address was specified and the socket is already connected. +This error may or may not be returned for connection +mode sockets. +.TP 7 +.B ENETDOWN +The local network interface used to reach the destination is down. +.TP 7 +.B ENETUNREACH +No route to the network is present. +.TP 7 +.B ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP 7 +.B ENOMEM +Insufficient memory was available to fulfill the request. +.sp +.LP +If the address family of the socket is AF_UNIX, then \fIsendto\fP() +may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the pathname in the socket address. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIselect\fP() and \fIpoll\fP() functions can +be used to determine when it is possible to send more data. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetsockopt\fP() , \fIpoll\fP() , \fIrecv\fP() , \fIrecvfrom\fP() +, \fIrecvmsg\fP() , \fIselect\fP() , \fIsend\fP() , \fIsendmsg\fP() +, \fIsetsockopt\fP() , \fIshutdown\fP() , \fIsocket\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/setbuf.3p b/man3p/setbuf.3p new file mode 100644 index 000000000..00facf32e --- /dev/null +++ b/man3p/setbuf.3p @@ -0,0 +1,86 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETBUF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setbuf +.SH NAME +setbuf \- assign buffering to a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void setbuf(FILE *restrict\fP \fIstream\fP\fB, char *restrict\fP \fIbuf\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +Except that it returns no value, the function call: +.sp +.RS +.nf + +\fBsetbuf(stream, buf) +\fP +.fi +.RE +.LP +shall be equivalent to: +.sp +.RS +.nf + +\fBsetvbuf(stream, buf, _IOFBF, BUFSIZ) +\fP +.fi +.RE +.LP +if \fIbuf\fP is not a null pointer, or to: +.sp +.RS +.nf + +\fBsetvbuf(stream, buf, _IONBF, BUFSIZ) +\fP +.fi +.RE +.LP +if \fIbuf\fP is a null pointer. +.SH RETURN VALUE +.LP +The \fIsetbuf\fP() function shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +A common source of error is allocating buffer space as an "automatic" +variable in a code block, and then failing to close the +stream in the same block. +.LP +With \fIsetbuf\fP(), allocating a buffer of BUFSIZ bytes does not +necessarily imply that all of BUFSIZ bytes are used for the +buffer area. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfopen\fP() , \fIsetvbuf\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/setcontext.3p b/man3p/setcontext.3p new file mode 100644 index 000000000..e9a0e68f8 --- /dev/null +++ b/man3p/setcontext.3p @@ -0,0 +1 @@ +.so man3p/getcontext.3p diff --git a/man3p/setegid.3p b/man3p/setegid.3p new file mode 100644 index 000000000..328bb4999 --- /dev/null +++ b/man3p/setegid.3p @@ -0,0 +1,72 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETEGID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setegid +.SH NAME +setegid \- set the effective group ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int setegid(gid_t\fP \fIgid\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If \fIgid\fP is equal to the real group ID or the saved set-group-ID, +or if the process has appropriate privileges, +\fIsetegid\fP() shall set the effective group ID of the calling process +to \fIgid\fP; the real group ID, saved set-group-ID, and +any supplementary group IDs shall remain unchanged. +.LP +The \fIsetegid\fP() function shall not affect the supplementary group +list in any way. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned; otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIsetegid\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of the \fIgid\fP argument is invalid and is not supported +by the implementation. +.TP 7 +.B EPERM +The process does not have appropriate privileges and \fIgid\fP does +not match the real group ID or the saved +set-group-ID. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Refer to the RATIONALE section in \fIsetuid\fP() . +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIgetegid\fP() , \fIgeteuid\fP() , \fIgetgid\fP() +, \fIgetuid\fP() , +\fIseteuid\fP() , \fIsetgid\fP() , \fIsetregid\fP() , \fIsetreuid\fP() +, \fIsetuid\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/setenv.3p b/man3p/setenv.3p new file mode 100644 index 000000000..3b3e0c619 --- /dev/null +++ b/man3p/setenv.3p @@ -0,0 +1,120 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETENV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setenv +.SH NAME +setenv \- add or change environment variable +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int setenv(const char *\fP\fIenvname\fP\fB, const char *\fP\fIenvval\fP\fB, +int\fP \fIoverwrite\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsetenv\fP() function shall update or add a variable in the +environment of the calling process. The \fIenvname\fP +argument points to a string containing the name of an environment +variable to be added or altered. The environment variable shall +be set to the value to which \fIenvval\fP points. The function shall +fail if \fIenvname\fP points to a string which contains an +\fB'='\fP character. If the environment variable named by \fIenvname\fP +already exists and the value of \fIoverwrite\fP is +non-zero, the function shall return success and the environment shall +be updated. If the environment variable named by +\fIenvname\fP already exists and the value of \fIoverwrite\fP is zero, +the function shall return success and the environment +shall remain unchanged. +.LP +If the application modifies \fIenviron\fP or the pointers to which +it points, the behavior of \fIsetenv\fP() is undefined. The +\fIsetenv\fP() function shall update the list of pointers to which +\fIenviron\fP points. +.LP +The strings described by \fIenvname\fP and \fIenvval\fP are copied +by this function. +.LP +The \fIsetenv\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +Upon successful completion, zero shall be returned. Otherwise, -1 +shall be returned, \fIerrno\fP set to indicate the error, and +the environment shall be unchanged. +.SH ERRORS +.LP +The \fIsetenv\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fIname\fP argument is a null pointer, points to an empty string, +or points to a string containing an \fB'='\fP +character. +.TP 7 +.B ENOMEM +Insufficient memory was available to add a variable or its value to +the environment. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +See \fIexec\fP() , for restrictions on changing the environment in +multi-threaded applications. +.SH RATIONALE +.LP +Unanticipated results may occur if \fIsetenv\fP() changes the external +variable \fIenviron\fP. In particular, if the optional +\fIenvp\fP argument to \fImain\fP() is present, it is not changed, +and thus may point to an obsolete copy of the environment (as +may any other copy of \fIenviron\fP). However, other than the aforementioned +restriction, the developers of +IEEE\ Std\ 1003.1-2001 intended that the traditional method of walking +through the environment by way of the \fIenviron\fP +pointer must be supported. +.LP +It was decided that \fIsetenv\fP() should be required by this revision +because it addresses a piece of missing functionality, +and does not impose a significant burden on the implementor. +.LP +There was considerable debate as to whether the System V \fIputenv\fP() +function or the +BSD \fIsetenv\fP() function should be required as a mandatory function. +The \fIsetenv\fP() function was chosen because it +permitted the implementation of the \fIunsetenv\fP() function to delete +environmental +variables, without specifying an additional interface. The \fIputenv\fP() +function is +available as an XSI extension. +.LP +The standard developers considered requiring that \fIsetenv\fP() indicate +an error when a call to it would result in exceeding +{ARG_MAX}. The requirement was rejected since the condition might +be temporary, with the application eventually reducing the +environment size. The ultimate success or failure depends on the size +at the time of a call to \fIexec\fP, which returns an indication of +this error condition. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIgetenv\fP() , \fIunsetenv\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/seteuid.3p b/man3p/seteuid.3p new file mode 100644 index 000000000..0723ee197 --- /dev/null +++ b/man3p/seteuid.3p @@ -0,0 +1,72 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETEUID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" seteuid +.SH NAME +seteuid \- set effective user ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int seteuid(uid_t\fP \fIuid\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If \fIuid\fP is equal to the real user ID or the saved set-user-ID, +or if the process has appropriate privileges, +\fIseteuid\fP() shall set the effective user ID of the calling process +to \fIuid\fP; the real user ID and saved set-user-ID shall +remain unchanged. +.LP +The \fIseteuid\fP() function shall not affect the supplementary group +list in any way. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned; otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIseteuid\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of the \fIuid\fP argument is invalid and is not supported +by the implementation. +.TP 7 +.B EPERM +The process does not have appropriate privileges and \fIuid\fP does +not match the real group ID or the saved +set-group-ID. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Refer to the RATIONALE section in \fIsetuid\fP() . +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIgetegid\fP() , \fIgeteuid\fP() , \fIgetgid\fP() +, \fIgetuid\fP() , +\fIsetegid\fP() , \fIsetgid\fP() , \fIsetregid\fP() , \fIsetreuid\fP() +, \fIsetuid\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/setgid.3p b/man3p/setgid.3p new file mode 100644 index 000000000..a3b5667ec --- /dev/null +++ b/man3p/setgid.3p @@ -0,0 +1,78 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETGID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setgid +.SH NAME +setgid \- set-group-ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int setgid(gid_t\fP \fIgid\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If the process has appropriate privileges, \fIsetgid\fP() shall set +the real group ID, effective group ID, and the saved +set-group-ID of the calling process to \fIgid\fP. +.LP +If the process does not have appropriate privileges, but \fIgid\fP +is equal to the real group ID or the saved set-group-ID, +\fIsetgid\fP() shall set the effective group ID to \fIgid\fP; the +real group ID and saved set-group-ID shall remain +unchanged. +.LP +The \fIsetgid\fP() function shall not affect the supplementary group +list in any way. +.LP +Any supplementary group IDs of the calling process shall remain unchanged. +.SH RETURN VALUE +.LP +Upon successful completion, 0 is returned. Otherwise, -1 shall be +returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIsetgid\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of the \fIgid\fP argument is invalid and is not supported +by the implementation. +.TP 7 +.B EPERM +The process does not have appropriate privileges and \fIgid\fP does +not match the real group ID or the saved +set-group-ID. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Refer to the RATIONALE section in \fIsetuid\fP() . +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIgetegid\fP() , \fIgeteuid\fP() , \fIgetgid\fP() +, \fIgetuid\fP() , +\fIsetegid\fP() , \fIseteuid\fP() , \fIsetregid\fP() , \fIsetreuid\fP() +, \fIsetuid\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/setgrent.3p b/man3p/setgrent.3p new file mode 100644 index 000000000..8dc5addf7 --- /dev/null +++ b/man3p/setgrent.3p @@ -0,0 +1 @@ +.so man3p/getgrent.3p diff --git a/man3p/sethostent.3p b/man3p/sethostent.3p new file mode 100644 index 000000000..490b7646b --- /dev/null +++ b/man3p/sethostent.3p @@ -0,0 +1 @@ +.so man3p/gethostent.3p diff --git a/man3p/setitimer.3p b/man3p/setitimer.3p new file mode 100644 index 000000000..0fd2215b7 --- /dev/null +++ b/man3p/setitimer.3p @@ -0,0 +1 @@ +.so man3p/getitimer.3p diff --git a/man3p/setjmp.3p b/man3p/setjmp.3p new file mode 100644 index 000000000..e9fa50140 --- /dev/null +++ b/man3p/setjmp.3p @@ -0,0 +1,84 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETJMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setjmp +.SH NAME +setjmp \- set jump point for a non-local goto +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int setjmp(jmp_buf\fP \fIenv\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +A call to \fIsetjmp\fP() shall save the calling environment in its +\fIenv\fP argument for later use by \fIlongjmp\fP(). +.LP +It is unspecified whether \fIsetjmp\fP() is a macro or a function. +If a macro definition is suppressed in order to access an +actual function, or a program defines an external identifier with +the name \fIsetjmp\fP, the behavior is undefined. +.LP +An application shall ensure that an invocation of \fIsetjmp\fP() appears +in one of the following contexts only: +.IP " *" 3 +The entire controlling expression of a selection or iteration statement +.LP +.IP " *" 3 +One operand of a relational or equality operator with the other operand +an integral constant expression, with the resulting +expression being the entire controlling expression of a selection +or iteration statement +.LP +.IP " *" 3 +The operand of a unary \fB'!'\fP operator with the resulting expression +being the entire controlling expression of a +selection or iteration +.LP +.IP " *" 3 +The entire expression of an expression statement (possibly cast to +\fBvoid\fP) +.LP +.LP +If the invocation appears in any other context, the behavior is undefined. +.SH RETURN VALUE +.LP +If the return is from a direct invocation, \fIsetjmp\fP() shall return +0. If the return is from a call to \fIlongjmp\fP(), \fIsetjmp\fP() +shall return a non-zero value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +In general, \fIsigsetjmp\fP() is more useful in dealing with errors +and interrupts +encountered in a low-level subroutine of a program. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIlongjmp\fP() , \fIsigsetjmp\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/setkey.3p b/man3p/setkey.3p new file mode 100644 index 000000000..cb19e1898 --- /dev/null +++ b/man3p/setkey.3p @@ -0,0 +1,77 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETKEY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setkey +.SH NAME +setkey \- set encoding key (\fBCRYPT\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void setkey(const char *\fP\fIkey\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsetkey\fP() function provides access to an implementation-defined +encoding algorithm. The argument of \fIsetkey\fP() is +an array of length 64 bytes containing only the bytes with numerical +value of 0 and 1. If this string is divided into groups of 8, +the low-order bit in each group is ignored; this gives a 56-bit key +which is used by the algorithm. This is the key that shall be +used with the algorithm to encode a string \fIblock\fP passed to \fIencrypt\fP(). +.LP +The \fIsetkey\fP() function shall not change the setting of \fIerrno\fP +if successful. An application wishing to check for +error situations should set \fIerrno\fP to 0 before calling \fIsetkey\fP(). +If \fIerrno\fP is non-zero on return, an error has +occurred. +.LP +The \fIsetkey\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +No values are returned. +.SH ERRORS +.LP +The \fIsetkey\fP() function shall fail if: +.TP 7 +.B ENOSYS +The functionality is not supported on this implementation. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Decoding need not be implemented in all environments. This is related +to government restrictions in some countries on encryption +and decryption routines. Historical practice has been to ship a different +version of the encryption library without the decryption +feature in the routines supplied. Thus the exported version of \fIencrypt\fP() +does +encoding but not decoding. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcrypt\fP() , \fIencrypt\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/setlocale.3p b/man3p/setlocale.3p new file mode 100644 index 000000000..1bb80347c --- /dev/null +++ b/man3p/setlocale.3p @@ -0,0 +1,310 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETLOCALE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setlocale +.SH NAME +setlocale \- set program locale +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *setlocale(int\fP \fIcategory\fP\fB, const char *\fP\fIlocale\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsetlocale\fP() function selects the appropriate piece of the +program's locale, as specified by the \fIcategory\fP and +\fIlocale\fP arguments, and may be used to change or query the program's +entire locale or portions thereof. The value +\fILC_ALL\fP for \fIcategory\fP names the program's entire locale; +other values for \fIcategory\fP name only a part of the +program's locale: +.TP 7 +\fILC_COLLATE\fP +Affects the behavior of regular expressions and the collation functions. +.TP 7 +\fILC_CTYPE\fP +Affects the behavior of regular expressions, character classification, +character conversion functions, and wide-character +functions. +.TP 7 +\fILC_MESSAGES\fP +Affects what strings are expected by commands and utilities as affirmative +or negative responses. +.LP +It also affects what strings are given by commands and utilities as +affirmative or negative responses, and the content of messages. +.TP 7 +\fILC_MONETARY\fP +Affects the behavior of functions that handle monetary values. +.TP 7 +\fILC_NUMERIC\fP +Affects the behavior of functions that handle numeric values. +.TP 7 +\fILC_TIME\fP +Affects the behavior of the time conversion functions. +.sp +.LP +The \fIlocale\fP argument is a pointer to a character string containing +the required setting of \fIcategory\fP. The contents +of this string are implementation-defined. In addition, the following +preset values of \fIlocale\fP are defined for all settings +of \fIcategory\fP: +.TP 7 +"POSIX" +Specifies the minimal environment for C-language translation called +the POSIX locale. If \fIsetlocale\fP() is not invoked, the +POSIX locale is the default at entry to \fImain\fP(). +.TP 7 +"C" +Equivalent to \fB"POSIX"\fP . +.TP 7 +"" +Specifies an implementation-defined native environment. \ This corresponds +to the value of the associated environment +variables, \fILC_*\fP and \fILANG ;\fP see the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale and the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables. +.TP 7 +A\ null\ pointer +Used to direct \fIsetlocale\fP() to query the current internationalized +environment and return the name of the locale. +.sp +.LP +The locale state is common to all threads within a process. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsetlocale\fP() shall return the string +associated with the specified category for the new +locale. Otherwise, \fIsetlocale\fP() shall return a null pointer and +the program's locale is not changed. +.LP +A null pointer for \fIlocale\fP causes \fIsetlocale\fP() to return +a pointer to the string associated with the \fIcategory\fP +for the program's current locale. The program's locale shall not be +changed. +.LP +The string returned by \fIsetlocale\fP() is such that a subsequent +call with that string and its associated \fIcategory\fP +shall restore that part of the program's locale. The application shall +not modify the string returned which may be overwritten by a +subsequent call to \fIsetlocale\fP(). +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The following code illustrates how a program can initialize the international +environment for one language, while selectively +modifying the program's locale such that regular expressions and string +operations can be applied to text recorded in a different +language: +.sp +.RS +.nf + +\fBsetlocale(LC_ALL, "De"); +setlocale(LC_COLLATE, "Fr@dict"); +\fP +.fi +.RE +.LP +Internationalized programs must call \fIsetlocale\fP() to initiate +a specific language operation. This can be done by calling +\fIsetlocale\fP() as follows: +.sp +.RS +.nf + +\fBsetlocale(LC_ALL, ""); +\fP +.fi +.RE +.LP +Changing the setting of \fILC_MESSAGES\fP has no effect on catalogs +that have already been opened by calls to \fIcatopen\fP(). +.SH RATIONALE +.LP +The ISO\ C standard defines a collection of functions to support internationalization. +One of the most significant aspects +of these functions is a facility to set and query the \fIinternational +environment\fP. The international environment is a +repository of information that affects the behavior of certain functionality, +namely: +.IP " 1." 4 +Character handling +.LP +.IP " 2." 4 +Collating +.LP +.IP " 3." 4 +Date/time formatting +.LP +.IP " 4." 4 +Numeric editing +.LP +.IP " 5." 4 +Monetary formatting +.LP +.IP " 6." 4 +Messaging +.LP +.LP +The \fIsetlocale\fP() function provides the application developer +with the ability to set all or portions, called +\fIcategories\fP, of the international environment. These categories +correspond to the areas of functionality mentioned above. The +syntax for \fIsetlocale\fP() is as follows: +.sp +.RS +.nf + +\fBchar *setlocale(int\fP \fIcategory\fP\fB, const char *\fP\fIlocale\fP\fB); +\fP +.fi +.RE +.LP +where \fIcategory\fP is the name of one of following categories, namely: +.sp +.RS +.nf + +\fILC_COLLATE + +LC_CTYPE + +LC_MESSAGES + +LC_MONETARY + +LC_NUMERIC + +LC_TIME\fP + +.fi +.RE +.LP +In addition, a special value called \fILC_ALL\fP directs \fIsetlocale\fP() +to set all categories. +.LP +There are two primary uses of \fIsetlocale\fP(): +.IP " 1." 4 +Querying the international environment to find out what it is set +to +.LP +.IP " 2." 4 +Setting the international environment, or \fIlocale\fP, to a specific +value +.LP +.LP +The behavior of \fIsetlocale\fP() in these two areas is described +below. Since it is difficult to describe the behavior in +words, examples are used to illustrate the behavior of specific uses. +.LP +To query the international environment, \fIsetlocale\fP() is invoked +with a specific category and the NULL pointer as the +locale. The NULL pointer is a special directive to \fIsetlocale\fP() +that tells it to query rather than set the international +environment. The following syntax is used to query the name of the +international environment: +.sp +.RS +.nf + +\fBsetlocale({LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, \\ + LC_NUMERIC, LC_TIME},(char *) NULL); +\fP +.fi +.RE +.LP +The \fIsetlocale\fP() function shall return the string corresponding +to the current international environment. This value may +be used by a subsequent call to \fIsetlocale\fP() to reset the international +environment to this value. However, it should be +noted that the return value from \fIsetlocale\fP() may be a pointer +to a static area within the function and is not guaranteed to +remain unchanged (that is, it may be modified by a subsequent call +to \fIsetlocale\fP()). Therefore, if the purpose of calling +\fIsetlocale\fP() is to save the value of the current international +environment so it can be changed and reset later, the return +value should be copied to an array of \fBchar\fP in the calling program. +.LP +There are three ways to set the international environment with \fIsetlocale\fP(): +.TP 7 +\fIsetlocale\fP(\fIcategory\fP,\ \fIstring\fP) +.sp +This usage sets a specific \fIcategory\fP in the international environment +to a specific value corresponding to the value of the +\fIstring\fP. A specific example is provided below: +.sp +.RS +.nf + +\fBsetlocale(LC_ALL, "fr_FR.ISO-8859-1"); +\fP +.fi +.RE +.LP +In this example, all categories of the international environment are +set to the locale corresponding to the string +\fB"fr_FR.ISO-8859-1"\fP , or to the French language as spoken in +France using the ISO/IEC\ 8859-1:1998 standard +codeset. +.LP +If the string does not correspond to a valid locale, \fIsetlocale\fP() +shall return a NULL pointer and the international +environment is not changed. Otherwise, \fIsetlocale\fP() shall return +the name of the locale just set. +.TP 7 +\fIsetlocale\fP(\fIcategory\fP,\ "C") +.sp +The ISO\ C standard states that one locale must exist on all conforming +implementations. The name of the locale is C and +corresponds to a minimal international environment needed to support +the C programming language. +.TP 7 +\fIsetlocale\fP(\fIcategory\fP,\ "") +.sp +This sets a specific category to an implementation-defined default. +This corresponds to the value of the environment +variables. +.sp +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIisalnum\fP() , \fIisalpha\fP() , \fIisblank\fP() +, \fIiscntrl\fP() , \fIisdigit\fP() , \fIisgraph\fP() , +\fIislower\fP() , \fIisprint\fP() , \fIispunct\fP() , \fIisspace\fP() +, \fIisupper\fP() , +\fIiswalnum\fP() , \fIiswalpha\fP() , \fIiswblank\fP() , \fIiswcntrl\fP() +, \fIiswctype\fP() , \fIiswdigit\fP() , \fIiswgraph\fP() , \fIiswlower\fP() +, \fIiswprint\fP() , \fIiswpunct\fP() , \fIiswspace\fP() , \fIiswupper\fP() +, \fIiswxdigit\fP() , \fIisxdigit\fP() , \fIlocaleconv\fP() , \fImblen\fP() +, \fImbstowcs\fP() +, \fImbtowc\fP() , \fInl_langinfo\fP() , \fIprintf\fP() , \fIscanf\fP() +, setlocale , \fIstrcoll\fP() , \fIstrerror\fP() , \fIstrfmon\fP() +, +\fIstrtod\fP() , \fIstrxfrm\fP() , \fItolower\fP() , \fItoupper\fP() +, \fItowlower\fP() , +\fItowupper\fP() , \fIwcscoll\fP() , \fIwcstod\fP() , \fIwcstombs\fP() +, \fIwcsxfrm\fP() , +\fIwctomb\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/setlogmask.3p b/man3p/setlogmask.3p new file mode 100644 index 000000000..904d7e950 --- /dev/null +++ b/man3p/setlogmask.3p @@ -0,0 +1 @@ +.so man3p/syslog.3p diff --git a/man3p/setnetent.3p b/man3p/setnetent.3p new file mode 100644 index 000000000..17b642ad2 --- /dev/null +++ b/man3p/setnetent.3p @@ -0,0 +1 @@ +.so man3p/getnetent.3p diff --git a/man3p/setpgid.3p b/man3p/setpgid.3p new file mode 100644 index 000000000..ecdd01567 --- /dev/null +++ b/man3p/setpgid.3p @@ -0,0 +1,152 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETPGID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setpgid +.SH NAME +setpgid \- set process group ID for job control +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int setpgid(pid_t\fP \fIpid\fP\fB, pid_t\fP \fIpgid\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsetpgid\fP() function shall either join an existing process +group or create a new process group within the session of +the calling process. The process group ID of a session leader shall +not change. Upon successful completion, the process group ID of +the process with a process ID that matches \fIpid\fP shall be set +to \fIpgid\fP. As a special case, if \fIpid\fP is 0, the +process ID of the calling process shall be used. Also, if \fIpgid\fP +is 0, the process ID of the indicated process shall be +used. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsetpgid\fP() shall return 0; otherwise, +-1 shall be returned and \fIerrno\fP shall be set to +indicate the error. +.SH ERRORS +.LP +The \fIsetpgid\fP() function shall fail if: +.TP 7 +.B EACCES +The value of the \fIpid\fP argument matches the process ID of a child +process of the calling process and the child process has +successfully executed one of the \fIexec\fP functions. +.TP 7 +.B EINVAL +The value of the \fIpgid\fP argument is less than 0, or is not a value +supported by the implementation. +.TP 7 +.B EPERM +The process indicated by the \fIpid\fP argument is a session leader. +.TP 7 +.B EPERM +The value of the \fIpid\fP argument matches the process ID of a child +process of the calling process and the child process is +not in the same session as the calling process. +.TP 7 +.B EPERM +The value of the \fIpgid\fP argument is valid but does not match the +process ID of the process indicated by the \fIpid\fP +argument and there is no process with a process group ID that matches +the value of the \fIpgid\fP argument in the same session as +the calling process. +.TP 7 +.B ESRCH +The value of the \fIpid\fP argument does not match the process ID +of the calling process or of a child process of the calling +process. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIsetpgid\fP() function shall group processes together for the +purpose of signaling, placement in foreground or +background, and other job control actions. +.LP +The \fIsetpgid\fP() function is similar to the \fIsetpgrp\fP() function +of 4.2 BSD, +except that 4.2 BSD allowed the specified new process group to assume +any value. This presents certain security problems and is +more flexible than necessary to support job control. +.LP +To provide tighter security, \fIsetpgid\fP() only allows the calling +process to join a process group already in use inside its +session or create a new process group whose process group ID was equal +to its process ID. +.LP +When a job control shell spawns a new job, the processes in the job +must be placed into a new process group via +\fIsetpgid\fP(). There are two timing constraints involved in this +action: +.IP " 1." 4 +The new process must be placed in the new process group before the +appropriate program is launched via one of the \fIexec\fP functions. +.LP +.IP " 2." 4 +The new process must be placed in the new process group before the +shell can correctly send signals to the new process +group. +.LP +.LP +To address these constraints, the following actions are performed. +The new processes call \fIsetpgid\fP() to alter their own +process groups after \fIfork\fP() but before \fIexec\fP. This satisfies +the first constraint. Under 4.3 BSD, the second constraint is satisfied +by +the synchronization property of \fIvfork\fP(); that is, the shell +is suspended until the +child has completed the \fIexec\fP, thus ensuring that the child has +completed the +\fIsetpgid\fP(). A new version of \fIfork\fP() with this same synchronization +property was +considered, but it was decided instead to merely allow the parent +shell process to adjust the process group of its child processes +via \fIsetpgid\fP(). Both timing constraints are now satisfied by +having both the parent shell and the child attempt to adjust the +process group of the child process; it does not matter which succeeds +first. +.LP +Since it would be confusing to an application to have its process +group change after it began executing (that is, after \fIexec\fP), +and because the child process would already have adjusted its process +group before +this, the [EACCES] error was added to disallow this. +.LP +One non-obvious use of \fIsetpgid\fP() is to allow a job control shell +to return itself to its original process group (the one +in effect when the job control shell was executed). A job control +shell does this before returning control back to its parent when +it is terminating or suspending itself as a way of restoring its job +control "state" back to what its parent would expect. (Note +that the original process group of the job control shell typically +matches the process group of its parent, but this is not +necessarily always the case.) +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIgetpgrp\fP() , \fIsetsid\fP() , \fItcsetpgrp\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/setpgrp.3p b/man3p/setpgrp.3p new file mode 100644 index 000000000..3d818f1bd --- /dev/null +++ b/man3p/setpgrp.3p @@ -0,0 +1,58 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETPGRP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setpgrp +.SH NAME +setpgrp \- set the process group ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +pid_t setpgrp(void); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +If the calling process is not already a session leader, \fIsetpgrp\fP() +sets the process group ID of the calling process to the +process ID of the calling process. If \fIsetpgrp\fP() creates a new +session, then the new session has no controlling terminal. +.LP +The \fIsetpgrp\fP() function has no effect when the calling process +is a session leader. +.SH RETURN VALUE +.LP +Upon completion, \fIsetpgrp\fP() shall return the process group ID. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIfork\fP() , \fIgetpid\fP() , \fIgetsid\fP() , \fIkill\fP() +, \fIsetpgid\fP() , \fIsetsid\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/setpriority.3p b/man3p/setpriority.3p new file mode 100644 index 000000000..ad5e1f8f6 --- /dev/null +++ b/man3p/setpriority.3p @@ -0,0 +1 @@ +.so man3p/getpriority.3p diff --git a/man3p/setprotoent.3p b/man3p/setprotoent.3p new file mode 100644 index 000000000..82a414026 --- /dev/null +++ b/man3p/setprotoent.3p @@ -0,0 +1 @@ +.so man3p/getprotoent.3p diff --git a/man3p/setpwent.3p b/man3p/setpwent.3p new file mode 100644 index 000000000..235cf8b3e --- /dev/null +++ b/man3p/setpwent.3p @@ -0,0 +1 @@ +.so man3p/getpwent.3p diff --git a/man3p/setregid.3p b/man3p/setregid.3p new file mode 100644 index 000000000..216fcabb3 --- /dev/null +++ b/man3p/setregid.3p @@ -0,0 +1,86 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETREGID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setregid +.SH NAME +setregid \- set real and effective group IDs +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int setregid(gid_t\fP \fIrgid\fP\fB, gid_t\fP \fIegid\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsetregid\fP() function shall set the real and effective group +IDs of the calling process. +.LP +If \fIrgid\fP is -1, the real group ID shall not be changed; if \fIegid\fP +is -1, the effective group ID shall not be +changed. +.LP +The real and effective group IDs may be set to different values in +the same call. +.LP +Only a process with appropriate privileges can set the real group +ID and the effective group ID to any valid value. +.LP +A non-privileged process can set either the real group ID to the saved +set-group-ID from one of the \fIexec\fP family of functions, or the +effective group ID to the saved set-group-ID or the real group +ID. +.LP +Any supplementary group IDs of the calling process remain unchanged. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error, and +neither of the group IDs are changed. +.SH ERRORS +.LP +The \fIsetregid\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of the \fIrgid\fP or \fIegid\fP argument is invalid or out-of-range. +.TP 7 +.B EPERM +The process does not have appropriate privileges and a change other +than changing the real group ID to the saved set-group-ID, +or changing the effective group ID to the real group ID or the saved +set-group-ID, was requested. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +If a set-group-ID process sets its effective group ID to its real +group ID, it can still set its effective group ID back to the +saved set-group-ID. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIgetegid\fP() , \fIgeteuid\fP() , \fIgetgid\fP() +, \fIgetuid\fP() , +\fIsetegid\fP() , \fIseteuid\fP() , \fIsetgid\fP() , \fIsetreuid\fP() +, \fIsetuid\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/setreuid.3p b/man3p/setreuid.3p new file mode 100644 index 000000000..e40412061 --- /dev/null +++ b/man3p/setreuid.3p @@ -0,0 +1,93 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETREUID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setreuid +.SH NAME +setreuid \- set real and effective user IDs +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int setreuid(uid_t\fP \fIruid\fP\fB, uid_t\fP \fIeuid\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsetreuid\fP() function shall set the real and effective user +IDs of the current process to the values specified by the +\fIruid\fP and \fIeuid\fP arguments. If \fIruid\fP or \fIeuid\fP is +-1, the corresponding effective or real user ID of the +current process shall be left unchanged. +.LP +A process with appropriate privileges can set either ID to any value. +An unprivileged process can only set the effective user ID +if the \fIeuid\fP argument is equal to either the real, effective, +or saved user ID of the process. +.LP +It is unspecified whether a process without appropriate privileges +is permitted to change the real user ID to match the current +real, effective, or saved set-user-ID of the process. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIsetreuid\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of the \fIruid\fP or \fIeuid\fP argument is invalid or out-of-range. +.TP 7 +.B EPERM +The current process does not have appropriate privileges, and either +an attempt was made to change the effective user ID to a +value other than the real user ID or the saved set-user-ID or an attempt +was made to change the real user ID to a value not +permitted by the implementation. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Setting the Effective User ID to the Real User ID +.LP +The following example sets the effective user ID of the calling process +to the real user ID, so that files created later will be +owned by the current user. +.sp +.RS +.nf + +\fB#include +#include +\&... +setreuid(getuid(), getuid()); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetegid\fP() , \fIgeteuid\fP() , \fIgetgid\fP() , \fIgetuid\fP() +, \fIsetegid\fP() , \fIseteuid\fP() , \fIsetgid\fP() , \fIsetregid\fP() +, \fIsetuid\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/setrlimit.3p b/man3p/setrlimit.3p new file mode 100644 index 000000000..2b27bee28 --- /dev/null +++ b/man3p/setrlimit.3p @@ -0,0 +1 @@ +.so man3p/getrlimit.3p diff --git a/man3p/setservent.3p b/man3p/setservent.3p new file mode 100644 index 000000000..dc6b5d8e9 --- /dev/null +++ b/man3p/setservent.3p @@ -0,0 +1 @@ +.so man3p/getservent.3p diff --git a/man3p/setsid.3p b/man3p/setsid.3p new file mode 100644 index 000000000..314c77f6c --- /dev/null +++ b/man3p/setsid.3p @@ -0,0 +1,87 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETSID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setsid +.SH NAME +setsid \- create session and set process group ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +pid_t setsid(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsetsid\fP() function shall create a new session, if the calling +process is not a process group leader. Upon return the +calling process shall be the session leader of this new session, shall +be the process group leader of a new process group, and +shall have no controlling terminal. The process group ID of the calling +process shall be set equal to the process ID of the calling +process. The calling process shall be the only process in the new +process group and the only process in the new session. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsetsid\fP() shall return the value +of the new process group ID of the calling process. +Otherwise, it shall return (\fBpid_t\fP)-1 and set \fIerrno\fP to +indicate the error. +.SH ERRORS +.LP +The \fIsetsid\fP() function shall fail if: +.TP 7 +.B EPERM +The calling process is already a process group leader, or the process +group ID of a process other than the calling process +matches the process ID of the calling process. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIsetsid\fP() function is similar to the \fIsetpgrp\fP() function +of System V. +System V, without job control, groups processes into process groups +and creates new process groups via \fIsetpgrp\fP(); only one process +group may be part of a login session. +.LP +Job control allows multiple process groups within a login session. +In order to limit job control actions so that they can only +affect processes in the same login session, this volume of IEEE\ Std\ 1003.1-2001 +adds the concept of a session that is +created via \fIsetsid\fP(). The \fIsetsid\fP() function also creates +the initial process group contained in the session. +Additional process groups can be created via the \fIsetpgid\fP() function. +A System V +process group would correspond to a POSIX System Interfaces session +containing a single POSIX process group. Note that this +function requires that the calling process not be a process group +leader. The usual way to ensure this is true is to create a new +process with \fIfork\fP() and have it call \fIsetsid\fP(). The \fIfork\fP() +function guarantees that the process ID of the new process does not +match any existing +process group ID. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetsid\fP() , \fIsetpgid\fP() , \fIsetpgrp\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/setsockopt.3p b/man3p/setsockopt.3p new file mode 100644 index 000000000..a37d470a2 --- /dev/null +++ b/man3p/setsockopt.3p @@ -0,0 +1,225 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETSOCKOPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setsockopt +.SH NAME +setsockopt \- set the socket options +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int setsockopt(int\fP \fIsocket\fP\fB, int\fP \fIlevel\fP\fB, int\fP +\fIoption_name\fP\fB, +.br +\ \ \ \ \ \ const void *\fP\fIoption_value\fP\fB, socklen_t\fP \fIoption_len\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsetsockopt\fP() function shall set the option specified by +the \fIoption_name\fP argument, at the protocol level +specified by the \fIlevel\fP argument, to the value pointed to by +the \fIoption_value\fP argument for the socket associated with +the file descriptor specified by the \fIsocket\fP argument. +.LP +The \fIlevel\fP argument specifies the protocol level at which the +option resides. To set options at the socket level, specify +the \fIlevel\fP argument as SOL_SOCKET. To set options at other levels, +supply the appropriate \fIlevel\fP identifier for the +protocol controlling the option. For example, to indicate that an +option is interpreted by the TCP (Transport Control Protocol), +set \fIlevel\fP to IPPROTO_TCP as defined in the \fI\fP +header. +.LP +The \fIoption_name\fP argument specifies a single option to set. The +\fIoption_name\fP argument and any specified options are +passed uninterpreted to the appropriate protocol module for interpretations. +The \fI\fP header defines the socket-level options. +The options are as +follows: +.TP 7 +SO_DEBUG +Turns on recording of debugging information. This option enables or +disables debugging in the underlying protocol modules. This +option takes an \fBint\fP value. This is a Boolean option. +.TP 7 +SO_BROADCAST +Permits sending of broadcast messages, if this is supported by the +protocol. This option takes an \fBint\fP value. This is a +Boolean option. +.TP 7 +SO_REUSEADDR +Specifies that the rules used in validating addresses supplied to +\fIbind\fP() should +allow reuse of local addresses, if this is supported by the protocol. +This option takes an \fBint\fP value. This is a Boolean +option. +.TP 7 +SO_KEEPALIVE +Keeps connections active by enabling the periodic transmission of +messages, if this is supported by the protocol. This option +takes an \fBint\fP value. +.LP +If the connected socket fails to respond to these messages, the connection +is broken and threads writing to that socket are +notified with a SIGPIPE signal. This is a Boolean option. +.TP 7 +SO_LINGER +Lingers on a \fIclose\fP() if data is present. This option controls +the action taken +when unsent messages queue on a socket and \fIclose\fP() is performed. +If SO_LINGER is set, +the system shall block the process during \fIclose\fP() until it can +transmit the data or +until the time expires. If SO_LINGER is not specified, and \fIclose\fP() +is issued, the +system handles the call in a way that allows the process to continue +as quickly as possible. This option takes a \fBlinger\fP +structure, as defined in the \fI\fP header, to specify +the state +of the option and linger interval. +.TP 7 +SO_OOBINLINE +Leaves received out-of-band data (data marked urgent) inline. This +option takes an \fBint\fP value. This is a Boolean +option. +.TP 7 +SO_SNDBUF +Sets send buffer size. This option takes an \fBint\fP value. +.TP 7 +SO_RCVBUF +Sets receive buffer size. This option takes an \fBint\fP value. +.TP 7 +SO_DONTROUTE +Requests that outgoing messages bypass the standard routing facilities. +The destination shall be on a directly-connected +network, and messages are directed to the appropriate network interface +according to the destination address. The effect, if any, +of this option depends on what protocol is in use. This option takes +an \fBint\fP value. This is a Boolean option. +.TP 7 +SO_RCVLOWAT +Sets the minimum number of bytes to process for socket input operations. +The default value for SO_RCVLOWAT is 1. If SO_RCVLOWAT +is set to a larger value, blocking receive calls normally wait until +they have received the smaller of the low water mark value or +the requested amount. (They may return less than the low water mark +if an error occurs, a signal is caught, or the type of data +next in the receive queue is different from that returned; for example, +out-of-band data.) This option takes an \fBint\fP value. +Note that not all implementations allow this option to be set. +.TP 7 +SO_RCVTIMEO +Sets the timeout value that specifies the maximum amount of time an +input function waits until it completes. It accepts a +\fBtimeval\fP structure with the number of seconds and microseconds +specifying the limit on how long to wait for an input +operation to complete. If a receive operation has blocked for this +much time without receiving additional data, it shall return +with a partial count or \fIerrno\fP set to [EAGAIN] or [EWOULDBLOCK] +if no data is received. The default for this option is zero, +which indicates that a receive operation shall not time out. This +option takes a \fBtimeval\fP structure. Note that not all +implementations allow this option to be set. +.TP 7 +SO_SNDLOWAT +Sets the minimum number of bytes to process for socket output operations. +Non-blocking output operations shall process no data +if flow control does not allow the smaller of the send low water mark +value or the entire request to be processed. This option +takes an \fBint\fP value. Note that not all implementations allow +this option to be set. +.TP 7 +SO_SNDTIMEO +Sets the timeout value specifying the amount of time that an output +function blocks because flow control prevents data from +being sent. If a send operation has blocked for this time, it shall +return with a partial count or with \fIerrno\fP set to +[EAGAIN] or [EWOULDBLOCK] if no data is sent. The default for this +option is zero, which indicates that a send operation shall not +time out. This option stores a \fBtimeval\fP structure. Note that +not all implementations allow this option to be set. +.sp +.LP +For Boolean options, 0 indicates that the option is disabled and 1 +indicates that the option is enabled. +.LP +Options at other protocol levels vary in format and name. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsetsockopt\fP() shall return 0. Otherwise, +-1 shall be returned and \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +The \fIsetsockopt\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid file descriptor. +.TP 7 +.B EDOM +The send and receive timeout values are too big to fit into the timeout +fields in the socket structure. +.TP 7 +.B EINVAL +The specified option is invalid at the specified socket level or the +socket has been shut down. +.TP 7 +.B EISCONN +The socket is already connected, and a specified option cannot be +set while the socket is connected. +.TP 7 +.B ENOPROTOOPT +.sp +The option is not supported by the protocol. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.sp +.LP +The \fIsetsockopt\fP() function may fail if: +.TP 7 +.B ENOMEM +There was insufficient memory available for the operation to complete. +.TP 7 +.B ENOBUFS +Insufficient resources are available in the system to complete the +call. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIsetsockopt\fP() function provides an application program with +the means to control socket behavior. An application +program can use \fIsetsockopt\fP() to allocate buffer space, control +timeouts, or permit socket data broadcasts. The \fI\fP +header defines the socket-level options available to +\fIsetsockopt\fP(). +.LP +Options may exist at multiple protocol levels. The SO_ options are +always present at the uppermost socket level. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISockets\fP , \fIbind\fP() , \fIendprotoent\fP() , \fIgetsockopt\fP() +, \fIsocket\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/setstate.3p b/man3p/setstate.3p new file mode 100644 index 000000000..0f22b822b --- /dev/null +++ b/man3p/setstate.3p @@ -0,0 +1 @@ +.so man3p/random.3p diff --git a/man3p/setuid.3p b/man3p/setuid.3p new file mode 100644 index 000000000..bde62106c --- /dev/null +++ b/man3p/setuid.3p @@ -0,0 +1,199 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETUID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setuid +.SH NAME +setuid \- set user ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int setuid(uid_t\fP \fIuid\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If the process has appropriate privileges, \fIsetuid\fP() shall set +the real user ID, effective user ID, and the saved +set-user-ID of the calling process to \fIuid\fP. +.LP +If the process does not have appropriate privileges, but \fIuid\fP +is equal to the real user ID or the saved set-user-ID, +\fIsetuid\fP() shall set the effective user ID to \fIuid\fP; the real +user ID and saved set-user-ID shall remain unchanged. +.LP +The \fIsetuid\fP() function shall not affect the supplementary group +list in any way. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIsetuid\fP() function shall fail, return -1, and set \fIerrno\fP +to the corresponding value if one or more of the +following are true: +.TP 7 +.B EINVAL +The value of the \fIuid\fP argument is invalid and not supported by +the implementation. +.TP 7 +.B EPERM +The process does not have appropriate privileges and \fIuid\fP does +not match the real user ID or the saved set-user-ID. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The various behaviors of the \fIsetuid\fP() and \fIsetgid\fP() functions +when called by +non-privileged processes reflect the behavior of different historical +implementations. For portability, it is recommended that new +non-privileged applications use the \fIseteuid\fP() and \fIsetegid\fP() +functions instead. +.LP +The saved set-user-ID capability allows a program to regain the effective +user ID established at the last \fIexec\fP call. Similarly, the saved +set-group-ID capability allows a program to regain the effective +group ID established at the last \fIexec\fP call. These capabilities +are derived from System +V. Without them, a program might have to run as superuser in order +to perform the same functions, because superuser can write on +the user's files. This is a problem because such a program can write +on any user's files, and so must be carefully written to +emulate the permissions of the calling process properly. In System +V, these capabilities have traditionally been implemented only +via the \fIsetuid\fP() and \fIsetgid\fP() functions for non-privileged +processes. The fact +that the behavior of those functions was different for privileged +processes made them difficult to use. The POSIX.1-1990 standard +defined the \fIsetuid\fP() function to behave differently for privileged +and unprivileged users. When the caller had the +appropriate privilege, the function set the calling process' real +user ID, effective user ID, and saved set-user ID on +implementations that supported it. When the caller did not have the +appropriate privilege, the function set only the effective user +ID, subject to permission checks. The former use is generally needed +for utilities like \fIlogin\fP and \fIsu\fP, which are not +conforming applications and thus outside the scope of IEEE\ Std\ 1003.1-2001. +These utilities wish to change the user ID +irrevocably to a new value, generally that of an unprivileged user. +The latter use is needed for conforming applications that are +installed with the set-user-ID bit and need to perform operations +using the real user ID. +.LP +IEEE\ Std\ 1003.1-2001 augments the latter functionality with a mandatory +feature named _POSIX_SAVED_IDS. This feature +permits a set-user-ID application to switch its effective user ID +back and forth between the values of its \fIexec\fP-time real user +ID and effective user ID. Unfortunately, the POSIX.1-1990 standard +did not +permit a conforming application using this feature to work properly +when it happened to be executed with the +(implementation-defined) appropriate privilege. Furthermore, the application +did not even have a means to tell whether it had this +privilege. Since the saved set-user-ID feature is quite desirable +for applications, as evidenced by the fact that NIST required it +in FIPS 151-2, it has been mandated by IEEE\ Std\ 1003.1-2001. However, +there are implementors who have been reluctant to +support it given the limitation described above. +.LP +The 4.3BSD system handles the problem by supporting separate functions: +\fIsetuid\fP() (which always sets both the real and +effective user IDs, like \fIsetuid\fP() in IEEE\ Std\ 1003.1-2001 +for privileged users), and \fIseteuid\fP() (which always sets just +the effective user ID, like \fIsetuid\fP() in +IEEE\ Std\ 1003.1-2001 for non-privileged users). This separation +of functionality into distinct functions seems desirable. +4.3BSD does not support the saved set-user-ID feature. It supports +similar functionality of switching the effective user ID back +and forth via \fIsetreuid\fP(), which permits reversing the real and +effective user IDs. +This model seems less desirable than the saved set-user-ID because +the real user ID changes as a side effect. The current 4.4BSD +includes saved effective IDs and uses them for \fIseteuid\fP() and +\fIsetegid\fP() as described above. The \fIsetreuid\fP() +and \fIsetregid\fP() functions will be deprecated or removed. +.LP +The solution here is: +.IP " *" 3 +Require that all implementations support the functionality of the +saved set-user-ID, which is set by the \fIexec\fP functions and by +privileged calls to \fIsetuid\fP(). +.LP +.IP " *" 3 +Add the \fIseteuid\fP() and \fIsetegid\fP() +functions as portable alternatives to \fIsetuid\fP() and \fIsetgid\fP() +for non-privileged +and privileged processes. +.LP +.LP +Historical systems have provided two mechanisms for a set-user-ID +process to change its effective user ID to be the same as its +real user ID in such a way that it could return to the original effective +user ID: the use of the \fIsetuid\fP() function in the +presence of a saved set-user-ID, or the use of the BSD \fIsetreuid\fP() +function, which +was able to swap the real and effective user IDs. The changes included +in IEEE\ Std\ 1003.1-2001 provide a new mechanism +using \fIseteuid\fP() in conjunction with a saved set-user-ID. Thus, +all implementations +with the new \fIseteuid\fP() mechanism will have a saved set-user-ID +for each process, and +most of the behavior controlled by _POSIX_SAVED_IDS has been changed +to agree with the case where the option was defined. The \fIkill\fP() +function is an exception. Implementors of the new \fIseteuid\fP() +mechanism will generally be required to maintain compatibility with +the older +mechanisms previously supported by their systems. However, compatibility +with this use of \fIsetreuid\fP() and with the _POSIX_SAVED_IDS behavior +of \fIkill\fP() is unfortunately complicated. If an implementation +with a saved set-user-ID allows a +process to use \fIsetreuid\fP() to swap its real and effective user +IDs, but were to +leave the saved set-user-ID unmodified, the process would then have +an effective user ID equal to the original real user ID, and +both real and saved set-user-ID would be equal to the original effective +user ID. In that state, the real user would be unable to +kill the process, even though the effective user ID of the process +matches that of the real user, if the \fIkill\fP() behavior of _POSIX_SAVED_IDS +was used. This is obviously not acceptable. The alternative +choice, which is used in at least one implementation, is to change +the saved set-user-ID to the effective user ID during most calls +to \fIsetreuid\fP(). The standard developers considered that alternative +to be less +correct than the retention of the old behavior of \fIkill\fP() in +such systems. Current +conforming applications shall accommodate either behavior from \fIkill\fP(), +and there +appears to be no strong reason for \fIkill\fP() to check the saved +set-user-ID rather than +the effective user ID. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIgetegid\fP() , \fIgeteuid\fP() , \fIgetgid\fP() +, \fIgetuid\fP() , +\fIsetegid\fP() , \fIseteuid\fP() , \fIsetgid\fP() , \fIsetregid\fP() +, \fIsetreuid\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/setutxent.3p b/man3p/setutxent.3p new file mode 100644 index 000000000..f7769c373 --- /dev/null +++ b/man3p/setutxent.3p @@ -0,0 +1 @@ +.so man3p/getutxid.3p diff --git a/man3p/setvbuf.3p b/man3p/setvbuf.3p new file mode 100644 index 000000000..e5a14dd12 --- /dev/null +++ b/man3p/setvbuf.3p @@ -0,0 +1,91 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETVBUF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setvbuf +.SH NAME +setvbuf \- assign buffering to a stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int setvbuf(FILE *restrict\fP \fIstream\fP\fB, char *restrict\fP \fIbuf\fP\fB, +int\fP \fItype\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIsize\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsetvbuf\fP() function may be used after the stream pointed +to by \fIstream\fP is associated with an open file but +before any other operation (other than an unsuccessful call to \fIsetvbuf\fP()) +is performed on the stream. The argument +\fItype\fP determines how \fIstream\fP shall be buffered, as follows: +.IP " *" 3 +{_IOFBF} shall cause input/output to be fully buffered. +.LP +.IP " *" 3 +{_IOLBF} shall cause input/output to be line buffered. +.LP +.IP " *" 3 +{_IONBF} shall cause input/output to be unbuffered. +.LP +.LP +If \fIbuf\fP is not a null pointer, the array it points to may be +used instead of a buffer allocated by \fIsetvbuf\fP() and +the argument \fIsize\fP specifies the size of the array; otherwise, +\fIsize\fP may determine the size of a buffer allocated by +the \fIsetvbuf\fP() function. The contents of the array at any time +are unspecified. +.LP +For information about streams, see \fIStandard I/O Streams\fP . +.SH RETURN VALUE +.LP +Upon successful completion, \fIsetvbuf\fP() shall return 0. Otherwise, +it shall return a non-zero value if an invalid value is +given for \fItype\fP or if the request cannot be honored, \ and +may set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIsetvbuf\fP() function may fail if: +.TP 7 +.B EBADF +The file descriptor underlying \fIstream\fP is not valid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +A common source of error is allocating buffer space as an "automatic" +variable in a code block, and then failing to close the +stream in the same block. +.LP +With \fIsetvbuf\fP(), allocating a buffer of \fIsize\fP bytes does +not necessarily imply that all of \fIsize\fP bytes are +used for the buffer area. +.LP +Applications should note that many implementations only provide line +buffering on input from terminal devices. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIStandard I/O Streams\fP , \fIfopen\fP() , \fIsetbuf\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/shm_open.3p b/man3p/shm_open.3p new file mode 100644 index 000000000..29db09a70 --- /dev/null +++ b/man3p/shm_open.3p @@ -0,0 +1,262 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SHM_OPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" shm_open +.SH NAME +shm_open \- open a shared memory object (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int shm_open(const char *\fP\fIname\fP\fB, int\fP \fIoflag\fP\fB, +mode_t\fP \fImode\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIshm_open\fP() function shall establish a connection between +a shared memory object and a file descriptor. It shall +create an open file description that refers to the shared memory object +and a file descriptor that refers to that open file +description. The file descriptor is used by other functions to refer +to that shared memory object. The \fIname\fP argument points +to a string naming a shared memory object. It is unspecified whether +the name appears in the file system and is visible to other +functions that take pathnames as arguments. The \fIname\fP argument +conforms to the construction rules for a pathname. If +\fIname\fP begins with the slash character, then processes calling +\fIshm_open\fP() with the same value of \fIname\fP refer to +the same shared memory object, as long as that name has not been removed. +If \fIname\fP does not begin with the slash character, +the effect is implementation-defined. The interpretation of slash +characters other than the leading slash character in \fIname\fP +is implementation-defined. +.LP +If successful, \fIshm_open\fP() shall return a file descriptor for +the shared memory object that is the lowest numbered file +descriptor not currently open for that process. The open file description +is new, and therefore the file descriptor does not share +it with any other processes. It is unspecified whether the file offset +is set. The FD_CLOEXEC file descriptor flag associated with +the new file descriptor is set. +.LP +The file status flags and file access modes of the open file description +are according to the value of \fIoflag\fP. The +\fIoflag\fP argument is the bitwise-inclusive OR of the following +flags defined in the \fI\fP header. Applications specify +exactly one of the first two values (access +modes) below in the value of \fIoflag\fP: +.TP 7 +O_RDONLY +Open for read access only. +.TP 7 +O_RDWR +Open for read or write access. +.sp +.LP +Any combination of the remaining flags may be specified in the value +of \fIoflag\fP: +.TP 7 +O_CREAT +If the shared memory object exists, this flag has no effect, except +as noted under O_EXCL below. Otherwise, the shared memory +object is created; the user ID of the shared memory object shall be +set to the effective user ID of the process; the group ID of +the shared memory object is set to a system default group ID or to +the effective group ID of the process. The permission bits of +the shared memory object shall be set to the value of the \fImode\fP +argument except those set in the file mode creation mask of +the process. When bits in \fImode\fP other than the file permission +bits are set, the effect is unspecified. The \fImode\fP +argument does not affect whether the shared memory object is opened +for reading, for writing, or for both. The shared memory object +has a size of zero. +.TP 7 +O_EXCL +If O_EXCL and O_CREAT are set, \fIshm_open\fP() fails if the shared +memory object exists. The check for the existence of the +shared memory object and the creation of the object if it does not +exist is atomic with respect to other processes executing +\fIshm_open\fP() naming the same shared memory object with O_EXCL +and O_CREAT set. If O_EXCL is set and O_CREAT is not set, the +result is undefined. +.TP 7 +O_TRUNC +If the shared memory object exists, and it is successfully opened +O_RDWR, the object shall be truncated to zero length and the +mode and owner shall be unchanged by this function call. The result +of using O_TRUNC with O_RDONLY is undefined. +.sp +.LP +When a shared memory object is created, the state of the shared memory +object, including all data associated with the shared +memory object, persists until the shared memory object is unlinked +and all other references are gone. It is unspecified whether the +name and shared memory object state remain valid after a system reboot. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIshm_open\fP() function shall return +a non-negative integer representing the lowest numbered +unused file descriptor. Otherwise, it shall return -1 and set \fIerrno\fP +to indicate the error. +.SH ERRORS +.LP +The \fIshm_open\fP() function shall fail if: +.TP 7 +.B EACCES +The shared memory object exists and the permissions specified by \fIoflag\fP +are denied, or the shared memory object does not +exist and permission to create the shared memory object is denied, +or O_TRUNC is specified and write permission is denied. +.TP 7 +.B EEXIST +O_CREAT and O_EXCL are set and the named shared memory object already +exists. +.TP 7 +.B EINTR +The \fIshm_open\fP() operation was interrupted by a signal. +.TP 7 +.B EINVAL +The \fIshm_open\fP() operation is not supported for the given name. +.TP 7 +.B EMFILE +Too many file descriptors are currently in use by this process. +.TP 7 +.B ENAMETOOLONG +The length of the \fIname\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENFILE +Too many shared memory objects are currently open in the system. +.TP 7 +.B ENOENT +O_CREAT is not set and the named shared memory object does not exist. +.TP 7 +.B ENOSPC +There is insufficient space for the creation of the new shared memory +object. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +When the Memory Mapped Files option is supported, the normal \fIopen\fP() +call is used to +obtain a descriptor to a file to be mapped according to existing practice +with \fImmap\fP(). +When the Shared Memory Objects option is supported, the \fIshm_open\fP() +function shall obtain a descriptor to the shared memory +object to be mapped. +.LP +There is ample precedent for having a file descriptor represent several +types of objects. In the POSIX.1-1990 standard, a file +descriptor can represent a file, a pipe, a FIFO, a tty, or a directory. +Many implementations simply have an operations vector, +which is indexed by the file descriptor type and does very different +operations. Note that in some cases the file descriptor passed +to generic operations on file descriptors is returned by \fIopen\fP() +or \fIcreat\fP() and in some cases returned by alternate functions, +such as \fIpipe\fP(). The latter technique is used by \fIshm_open\fP(). +.LP +Note that such shared memory objects can actually be implemented as +mapped files. In both cases, the size can be set after the +open using \fIftruncate\fP(). The \fIshm_open\fP() function itself +does not create a +shared object of a specified size because this would duplicate an +extant function that set the size of an object referenced by a +file descriptor. +.LP +On implementations where memory objects are implemented using the +existing file system, the \fIshm_open\fP() function may be +implemented using a macro that invokes \fIopen\fP(), and the \fIshm_unlink\fP() +function may be implemented using a macro that invokes \fIunlink\fP(). +.LP +For implementations without a permanent file system, the definition +of the name of the memory objects is allowed not to survive +a system reboot. Note that this allows systems with a permanent file +system to implement memory objects as data structures internal +to the implementation as well. +.LP +On implementations that choose to implement memory objects using memory +directly, a \fIshm_open\fP() followed by an \fIftruncate\fP() and +\fIclose\fP() can be used to +preallocate a shared memory area and to set the size of that preallocation. +This may be necessary for systems without virtual +memory hardware support in order to ensure that the memory is contiguous. +.LP +The set of valid open flags to \fIshm_open\fP() was restricted to +O_RDONLY, O_RDWR, O_CREAT, and O_TRUNC because these could be +easily implemented on most memory mapping systems. This volume of +IEEE\ Std\ 1003.1-2001 is silent on the results if the +implementation cannot supply the requested file access because of +implementation-defined reasons, including hardware ones. +.LP +The error conditions [EACCES] and [ENOTSUP] are provided to inform +the application that the implementation cannot complete a +request. +.LP +[EACCES] indicates for implementation-defined reasons, probably hardware-related, +that the implementation cannot comply with a +requested mode because it conflicts with another requested mode. An +example might be that an application desires to open a memory +object two times, mapping different areas with different access modes. +If the implementation cannot map a single area into a +process space in two places, which would be required if different +access modes were required for the two areas, then the +implementation may inform the application at the time of the second +open. +.LP +[ENOTSUP] indicates for implementation-defined reasons, probably hardware-related, +that the implementation cannot comply with a +requested mode at all. An example would be that the hardware of the +implementation cannot support write-only shared memory +areas. +.LP +On all implementations, it may be desirable to restrict the location +of the memory objects to specific file systems for +performance (such as a RAM disk) or implementation-defined reasons +(shared memory supported directly only on certain file systems). +The \fIshm_open\fP() function may be used to enforce these restrictions. +There are a number of methods available to the +application to determine an appropriate name of the file or the location +of an appropriate directory. One way is from the +environment via \fIgetenv\fP(). Another would be from a configuration +file. +.LP +This volume of IEEE\ Std\ 1003.1-2001 specifies that memory objects +have initial contents of zero when created. This is +consistent with current behavior for both files and newly allocated +memory. For those implementations that use physical memory, it +would be possible that such implementations could simply use available +memory and give it to the process uninitialized. This, +however, is not consistent with standard behavior for the uninitialized +data area, the stack, and of course, files. Finally, it is +highly desirable to set the allocated memory to zero for security +reasons. Thus, initializing memory objects to zero is +required. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclose\fP() , \fIdup\fP() , \fIexec\fP() , \fIfcntl\fP() , \fImmap\fP() +, \fIshmat\fP() , \fIshmctl\fP() , \fIshmdt\fP() , \fIshm_unlink\fP() +, \fIumask\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/shm_unlink.3p b/man3p/shm_unlink.3p new file mode 100644 index 000000000..8032a15e0 --- /dev/null +++ b/man3p/shm_unlink.3p @@ -0,0 +1,86 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SHM_UNLINK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" shm_unlink +.SH NAME +shm_unlink \- remove a shared memory object (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int shm_unlink(const char *\fP\fIname\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIshm_unlink\fP() function shall remove the name of the shared +memory object named by the string pointed to by +\fIname\fP. +.LP +If one or more references to the shared memory object exist when the +object is unlinked, the name shall be removed before +\fIshm_unlink\fP() returns, but the removal of the memory object contents +shall be postponed until all open and map references to +the shared memory object have been removed. +.LP +Even if the object continues to exist after the last \fIshm_unlink\fP(), +reuse of the name shall subsequently cause \fIshm_open\fP() to behave +as if no shared memory object of this name exists (that is, \fIshm_open\fP() +will fail if O_CREAT is not set, or will create a new shared memory +object if +O_CREAT is set). +.SH RETURN VALUE +.LP +Upon successful completion, a value of zero shall be returned. Otherwise, +a value of -1 shall be returned and \fIerrno\fP set +to indicate the error. If -1 is returned, the named shared memory +object shall not be changed by this function call. +.SH ERRORS +.LP +The \fIshm_unlink\fP() function shall fail if: +.TP 7 +.B EACCES +Permission is denied to unlink the named shared memory object. +.TP 7 +.B ENAMETOOLONG +The length of the \fIname\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +The named shared memory object does not exist. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Names of memory objects that were allocated with \fIopen\fP() are +deleted with \fIunlink\fP() in the usual fashion. Names of memory +objects that were allocated with \fIshm_open\fP() are deleted with +\fIshm_unlink\fP(). Note that the actual memory object is not +destroyed until the last close and unmap on it have occurred if it +was already in use. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclose\fP() , \fImmap\fP() , \fImunmap\fP() , \fIshmat\fP() , \fIshmctl\fP() +, \fIshmdt\fP() , \fIshm_open\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/shmat.3p b/man3p/shmat.3p new file mode 100644 index 000000000..09da13902 --- /dev/null +++ b/man3p/shmat.3p @@ -0,0 +1,123 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SHMAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" shmat +.SH NAME +shmat \- XSI shared memory attach operation +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void *shmat(int\fP \fIshmid\fP\fB, const void *\fP\fIshmaddr\fP\fB, +int\fP \fIshmflg\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIshmat\fP() function operates on XSI shared memory (see the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 3.340, +Shared Memory Object). It is unspecified whether this function +interoperates with the realtime interprocess communication facilities +defined in \fIRealtime\fP . +.LP +The \fIshmat\fP() function attaches the shared memory segment associated +with the shared memory identifier specified by +\fIshmid\fP to the address space of the calling process. The segment +is attached at the address specified by one of the following +criteria: +.IP " *" 3 +If \fIshmaddr\fP is a null pointer, the segment is attached at the +first available address as selected by the system. +.LP +.IP " *" 3 +If \fIshmaddr\fP is not a null pointer and (\fIshmflg\fP &SHM_RND) +is non-zero, the segment is attached at the address +given by (\fIshmaddr\fP -((\fIuintptr_t\fP)\fIshmaddr\fP %SHMLBA)). +The character \fB'%'\fP is the C-language remainder +operator. +.LP +.IP " *" 3 +If \fIshmaddr\fP is not a null pointer and (\fIshmflg\fP &SHM_RND) +is 0, the segment is attached at the address given by +\fIshmaddr\fP. +.LP +.IP " *" 3 +The segment is attached for reading if (\fIshmflg\fP &SHM_RDONLY) +is non-zero and the calling process has read permission; +otherwise, if it is 0 and the calling process has read and write permission, +the segment is attached for reading and writing. +.LP +.SH RETURN VALUE +.LP +Upon successful completion, \fIshmat\fP() shall increment the value +of \fIshm_nattch\fP in the data structure associated with +the shared memory ID of the attached shared memory segment and return +the segment's start address. +.LP +Otherwise, the shared memory segment shall not be attached, \fIshmat\fP() +shall return -1, and \fIerrno\fP shall be set to +indicate the error. +.SH ERRORS +.LP +The \fIshmat\fP() function shall fail if: +.TP 7 +.B EACCES +Operation permission is denied to the calling process; see \fIXSI +Interprocess +Communication\fP . +.TP 7 +.B EINVAL +The value of \fIshmid\fP is not a valid shared memory identifier, +the \fIshmaddr\fP is not a null pointer, and the value of +(\fIshmaddr\fP -((\fIuintptr_t\fP)\fIshmaddr\fP %SHMLBA)) is an illegal +address for attaching shared memory; or the +\fIshmaddr\fP is not a null pointer, (\fIshmflg\fP &SHM_RND) is 0, +and the value of \fIshmaddr\fP is an illegal address for +attaching shared memory. +.TP 7 +.B EMFILE +The number of shared memory segments attached to the calling process +would exceed the system-imposed limit. +.TP 7 +.B ENOMEM +The available data space is not large enough to accommodate the shared +memory segment. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to +use IPC should design their applications so that modules using the +IPC routines described in \fIXSI Interprocess Communication\fP can +be easily modified to use the alternative +interfaces. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIXSI Interprocess Communication\fP , \fIRealtime\fP , \fIexec\fP() +, +\fIexit\fP() , \fIfork\fP() , \fIshmctl\fP() , \fIshmdt\fP() , \fIshmget\fP() +, \fIshm_open\fP() , +\fIshm_unlink\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/shmctl.3p b/man3p/shmctl.3p new file mode 100644 index 000000000..344ae2747 --- /dev/null +++ b/man3p/shmctl.3p @@ -0,0 +1,130 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SHMCTL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" shmctl +.SH NAME +shmctl \- XSI shared memory control operations +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int shmctl(int\fP \fIshmid\fP\fB, int\fP \fIcmd\fP\fB, struct shmid_ds +*\fP\fIbuf\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIshmctl\fP() function operates on XSI shared memory (see the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 3.340, Shared Memory Object). It is unspecified whether this +function +interoperates with the realtime interprocess communication facilities +defined in \fIRealtime\fP . +.LP +The \fIshmctl\fP() function provides a variety of shared memory control +operations as specified by \fIcmd\fP. The following +values for \fIcmd\fP are available: +.TP 7 +IPC_STAT +Place the current value of each member of the \fBshmid_ds\fP data +structure associated with \fIshmid\fP into the structure +pointed to by \fIbuf\fP. The contents of the structure are defined +in \fI\fP. +.TP 7 +IPC_SET +Set the value of the following members of the \fBshmid_ds\fP data +structure associated with \fIshmid\fP to the corresponding +value found in the structure pointed to by \fIbuf\fP: +.sp +.RS +.nf + +\fBshm_perm.uid +shm_perm.gid +shm_perm.mode \fP Low-order nine bits. +.fi +.RE +.LP +IPC_SET can only be executed by a process that has an effective user +ID equal to either that of a process with appropriate +privileges or to the value of \fIshm_perm.cuid\fP or \fIshm_perm.uid\fP +in the \fBshmid_ds\fP data structure associated with +\fIshmid\fP. +.TP 7 +IPC_RMID +Remove the shared memory identifier specified by \fIshmid\fP from +the system and destroy the shared memory segment and +\fBshmid_ds\fP data structure associated with it. IPC_RMID can only +be executed by a process that has an effective user ID equal +to either that of a process with appropriate privileges or to the +value of \fIshm_perm.cuid\fP or \fIshm_perm.uid\fP in the +\fBshmid_ds\fP data structure associated with \fIshmid\fP. +.sp +.SH RETURN VALUE +.LP +Upon successful completion, \fIshmctl\fP() shall return 0; otherwise, +it shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fIshmctl\fP() function shall fail if: +.TP 7 +.B EACCES +The argument \fIcmd\fP is equal to IPC_STAT and the calling process +does not have read permission; see \fIXSI Interprocess Communication\fP +\&. +.TP 7 +.B EINVAL +The value of \fIshmid\fP is not a valid shared memory identifier, +or the value of \fIcmd\fP is not a valid command. +.TP 7 +.B EPERM +The argument \fIcmd\fP is equal to IPC_RMID or IPC_SET and the effective +user ID of the calling process is not equal to that +of a process with appropriate privileges and it is not equal to the +value of \fIshm_perm.cuid\fP or \fIshm_perm.uid\fP in the +data structure associated with \fIshmid\fP. +.sp +.LP +The \fIshmctl\fP() function may fail if: +.TP 7 +.B EOVERFLOW +The \fIcmd\fP argument is IPC_STAT and the \fIgid\fP or \fIuid\fP +value is too large to be stored in the structure pointed +to by the \fIbuf\fP argument. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to +use IPC should design their applications so that modules using the +IPC routines described in \fIXSI Interprocess Communication\fP can +be easily modified to use the alternative +interfaces. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIXSI Interprocess Communication\fP , \fIRealtime\fP , \fIshmat\fP() +, \fIshmdt\fP() , \fIshmget\fP() , \fIshm_open\fP() , \fIshm_unlink\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/shmdt.3p b/man3p/shmdt.3p new file mode 100644 index 000000000..c2c3fa325 --- /dev/null +++ b/man3p/shmdt.3p @@ -0,0 +1,79 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SHMDT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" shmdt +.SH NAME +shmdt \- XSI shared memory detach operation +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int shmdt(const void *\fP\fIshmaddr\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIshmdt\fP() function operates on XSI shared memory (see the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 3.340, +Shared Memory Object). It is unspecified whether this function +interoperates with the realtime interprocess communication facilities +defined in \fIRealtime\fP . +.LP +The \fIshmdt\fP() function detaches the shared memory segment located +at the address specified by \fIshmaddr\fP from the +address space of the calling process. +.SH RETURN VALUE +.LP +Upon successful completion, \fIshmdt\fP() shall decrement the value +of \fIshm_nattch\fP in the data structure associated with +the shared memory ID of the attached shared memory segment and return +0. +.LP +Otherwise, the shared memory segment shall not be detached, \fIshmdt\fP() +shall return -1, and \fIerrno\fP shall be set to +indicate the error. +.SH ERRORS +.LP +The \fIshmdt\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of \fIshmaddr\fP is not the data segment start address of +a shared memory segment. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to +use IPC should design their applications so that modules using the +IPC routines described in \fIXSI Interprocess Communication\fP can +be easily modified to use the alternative +interfaces. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIXSI Interprocess Communication\fP , \fIRealtime\fP , \fIexec\fP() +, +\fIexit\fP() , \fIfork\fP() , \fIshmat\fP() , \fIshmctl\fP() , \fIshmget\fP() +, \fIshm_open\fP() , \fIshm_unlink\fP() , the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/shmget.3p b/man3p/shmget.3p new file mode 100644 index 000000000..9c3909710 --- /dev/null +++ b/man3p/shmget.3p @@ -0,0 +1,142 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SHMGET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" shmget +.SH NAME +shmget \- get an XSI shared memory segment +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int shmget(key_t\fP \fIkey\fP\fB, size_t\fP \fIsize\fP\fB, int\fP +\fIshmflg\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIshmget\fP() function operates on XSI shared memory (see the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 3.340, Shared Memory Object). It is unspecified whether this +function +interoperates with the realtime interprocess communication facilities +defined in \fIRealtime\fP . +.LP +The \fIshmget\fP() function shall return the shared memory identifier +associated with \fIkey\fP. +.LP +A shared memory identifier, associated data structure, and shared +memory segment of at least \fIsize\fP bytes (see \fI\fP) +are created for \fIkey\fP if one of the following is true: +.IP " *" 3 +The argument \fIkey\fP is equal to IPC_PRIVATE. +.LP +.IP " *" 3 +The argument \fIkey\fP does not already have a shared memory identifier +associated with it and (\fIshmflg\fP &IPC_CREAT) +is non-zero. +.LP +.LP +Upon creation, the data structure associated with the new shared memory +identifier shall be initialized as follows: +.IP " *" 3 +The values of \fIshm_perm.cuid\fP, \fIshm_perm.uid\fP, \fIshm_perm.cgid\fP, +and \fIshm_perm.gid\fP are set equal to the +effective user ID and effective group ID, respectively, of the calling +process. +.LP +.IP " *" 3 +The low-order nine bits of \fIshm_perm.mode\fP are set equal to the +low-order nine bits of \fIshmflg\fP. +.LP +.IP " *" 3 +The value of \fIshm_segsz\fP is set equal to the value of \fIsize\fP. +.LP +.IP " *" 3 +The values of \fIshm_lpid\fP, \fIshm_nattch\fP, \fIshm_atime\fP, and +\fIshm_dtime\fP are set equal to 0. +.LP +.IP " *" 3 +The value of \fIshm_ctime\fP is set equal to the current time. +.LP +.LP +When the shared memory segment is created, it shall be initialized +with all zero values. +.SH RETURN VALUE +.LP +Upon successful completion, \fIshmget\fP() shall return a non-negative +integer, namely a shared memory identifier; otherwise, +it shall return -1 and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIshmget\fP() function shall fail if: +.TP 7 +.B EACCES +A shared memory identifier exists for \fIkey\fP but operation permission +as specified by the low-order nine bits of +\fIshmflg\fP would not be granted; see \fIXSI Interprocess Communication\fP +\&. +.TP 7 +.B EEXIST +A shared memory identifier exists for the argument \fIkey\fP but (\fIshmflg\fP +&IPC_CREAT) &&(\fIshmflg\fP +&IPC_EXCL) is non-zero. +.TP 7 +.B EINVAL +A shared memory segment is to be created and the value of size is +less than the system-imposed minimum or greater than the +system-imposed maximum. +.TP 7 +.B EINVAL +No shared memory segment is to be created and a shared memory segment +exists for \fIkey\fP but the size of the segment +associated with it is less than \fIsize\fP and \fIsize\fP is not 0. +.TP 7 +.B ENOENT +A shared memory identifier does not exist for the argument \fIkey\fP +and (\fIshmflg\fP &IPC_CREAT) is 0. +.TP 7 +.B ENOMEM +A shared memory identifier and associated shared memory segment shall +be created, but the amount of available physical memory +is not sufficient to fill the request. +.TP 7 +.B ENOSPC +A shared memory identifier is to be created, but the system-imposed +limit on the maximum number of allowed shared memory +identifiers system-wide would be exceeded. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to +use IPC should design their applications so that modules using the +IPC routines described in \fIXSI Interprocess Communication\fP can +be easily modified to use the alternative +interfaces. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIXSI Interprocess Communication\fP , \fIRealtime\fP , \fIshmat\fP() +, \fIshmctl\fP() , \fIshmdt\fP() , \fIshm_open\fP() , \fIshm_unlink\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/shutdown.3p b/man3p/shutdown.3p new file mode 100644 index 000000000..0d7b51d6d --- /dev/null +++ b/man3p/shutdown.3p @@ -0,0 +1,105 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SHUTDOWN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" shutdown +.SH NAME +shutdown \- shut down socket send and receive operations +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int shutdown(int\fP \fIsocket\fP\fB, int\fP \fIhow\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIshutdown\fP() function shall cause all or part of a full-duplex +connection on the socket associated with the file +descriptor \fIsocket\fP to be shut down. +.LP +The \fIshutdown\fP() function takes the following arguments: +.TP 7 +\fIsocket\fP +Specifies the file descriptor of the socket. +.TP 7 +\fIhow\fP +Specifies the type of shutdown. The values are as follows: +.TP 7 +SHUT_RD +.RS +Disables further receive operations. +.RE +.TP 7 +SHUT_WR +.RS +Disables further send operations. +.RE +.TP 7 +SHUT_RDWR +.RS +Disables further send and receive operations. +.RE +.sp +.sp +.LP +The \fIshutdown\fP() function disables subsequent send and/or receive +operations on a socket, depending on the value of the +\fIhow\fP argument. +.SH RETURN VALUE +.LP +Upon successful completion, \fIshutdown\fP() shall return 0; otherwise, +-1 shall be returned and \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +The \fIshutdown\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIsocket\fP argument is not a valid file descriptor. +.TP 7 +.B EINVAL +The \fIhow\fP argument is invalid. +.TP 7 +.B ENOTCONN +The socket is not connected. +.TP 7 +.B ENOTSOCK +The \fIsocket\fP argument does not refer to a socket. +.sp +.LP +The \fIshutdown\fP() function may fail if: +.TP 7 +.B ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetsockopt\fP() , \fIread\fP() , \fIrecv\fP() , \fIrecvfrom\fP() +, \fIrecvmsg\fP() , \fIselect\fP() , \fIsend\fP() , \fIsendto\fP() +, \fIsetsockopt\fP() , \fIsocket\fP() , \fIwrite\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sigaction.3p b/man3p/sigaction.3p new file mode 100644 index 000000000..b203df648 --- /dev/null +++ b/man3p/sigaction.3p @@ -0,0 +1,506 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGACTION" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sigaction +.SH NAME +sigaction \- examine and change a signal action +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sigaction(int\fP \fIsig\fP\fB, const struct sigaction *restrict\fP +\fIact\fP\fB, +.br +\ \ \ \ \ \ struct sigaction *restrict\fP \fIoact\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsigaction\fP() function allows the calling process to examine +and/or specify the action to be associated with a specific +signal. The argument \fIsig\fP specifies the signal; acceptable values +are defined in \fI\fP. +.LP +The structure \fBsigaction\fP, used to describe an action to be taken, +is defined in the \fI\fP header to include at least the +following members: +.TS C +center; lw(15) l lw(30). +T{ +.na +\fBMember Type\fP +.ad +T} \fBMember Name\fP T{ +.na +\fBDescription\fP +.ad +T} +T{ +.na +\fBvoid(*) (int)\fP +.ad +T} \fIsa_handler\fP T{ +.na +Pointer to a signal-catching function or one of the macros SIG_IGN or SIG_DFL. +.ad +T} +T{ +.na +\fBsigset_t\fP +.ad +T} \fIsa_mask\fP T{ +.na +Additional set of signals to be blocked during execution of signal-catching function. +.ad +T} +T{ +.na +\fBint\fP +.ad +T} \fIsa_flags\fP T{ +.na +Special flags to affect behavior of signal. +.ad +T} +T{ +.na +\fBvoid(*) (int,\fP +.ad +T} \fI\ \fP T{ +.na +\ +.ad +T} +T{ +.na +\fB\ \ siginfo_t *, void *)\fP +.ad +T} \fIsa_sigaction\fP T{ +.na +Pointer to a signal-catching function. +.ad +T} +.TE +.LP +The storage occupied by \fIsa_handler\fP and \fIsa_sigaction\fP may +overlap, and a conforming application shall not use both +simultaneously. +.LP +If the argument \fIact\fP is not a null pointer, it points to a structure +specifying the action to be associated with the +specified signal. If the argument \fIoact\fP is not a null pointer, +the action previously associated with the signal is stored in +the location pointed to by the argument \fIoact\fP. If the argument +\fIact\fP is a null pointer, signal handling is unchanged; +thus, the call can be used to enquire about the current handling of +a given signal. The SIGKILL and SIGSTOP signals shall not be +added to the signal mask using this mechanism; this restriction shall +be enforced by the system without causing an error to be +indicated. +.LP +If the SA_SIGINFO flag (see below) is cleared in the \fIsa_flags\fP +field of the \fBsigaction\fP structure, the +\fIsa_handler\fP field identifies the action to be associated with +the specified signal. \ If the +SA_SIGINFO flag is set in the \fIsa_flags\fP field, and the implementation +supports the Realtime Signals Extension option or the +XSI Extension option, the \fIsa_sigaction\fP field specifies a signal-catching +function. If the SA_SIGINFO bit is cleared and the \fIsa_handler\fP +field specifies a signal-catching function, +or if the SA_SIGINFO bit is set, the \fIsa_mask\fP field identifies +a set of signals that shall be added to the signal mask of the +thread before the signal-catching function is invoked. If the \fIsa_handler\fP +field specifies a signal-catching function, the +\fIsa_mask\fP field identifies a set of signals that shall be added +to the process' signal mask before the signal-catching +function is invoked. +.LP +The \fIsa_flags\fP field can be used to modify the behavior of the +specified signal. +.LP +The following flags, defined in the \fI\fP header, can be +set in +\fIsa_flags\fP: +.TP 7 +SA_NOCLDSTOP +Do not generate SIGCHLD when children stop \ or stopped children +continue. +.LP +If \fIsig\fP is SIGCHLD and the SA_NOCLDSTOP flag is not set in \fIsa_flags\fP, +and the implementation supports the SIGCHLD +signal, then a SIGCHLD signal shall be generated for the calling process +whenever any of its child processes stop \ and a +SIGCHLD signal may be generated for the calling process whenever any +of its stopped child processes are continued. \ If \fIsig\fP is SIGCHLD +and the SA_NOCLDSTOP flag is set in +\fIsa_flags\fP, then the implementation shall not generate a SIGCHLD +signal in this way. +.TP 7 +SA_ONSTACK +If set and an alternate signal stack has been declared with \fIsigaltstack\fP(), +the +signal shall be delivered to the calling process on that stack. Otherwise, +the signal shall be delivered on the current stack. +.TP 7 +SA_RESETHAND +If set, the disposition of the signal shall be reset to SIG_DFL and +the SA_SIGINFO flag shall be cleared on entry to the signal +handler. +.TP 7 +\fBNote:\fP +.RS +SIGILL and SIGTRAP cannot be automatically reset when delivered; the +system silently enforces this restriction. +.RE +.sp +Otherwise, the disposition of the signal shall not be modified on +entry to the signal handler. +.LP +In addition, if this flag is set, \fIsigaction\fP() behaves as if +the SA_NODEFER flag were also set. +.TP 7 +SA_RESTART +This flag affects the behavior of interruptible functions; that is, +those specified to fail with \fIerrno\fP set to [EINTR]. If +set, and a function specified as interruptible is interrupted by this +signal, the function shall restart and shall not fail with +[EINTR] unless otherwise specified. If the flag is not set, interruptible +functions interrupted by this signal shall fail with +\fIerrno\fP set to [EINTR]. +.TP 7 +SA_SIGINFO +If cleared and the signal is caught, the signal-catching function +shall be entered as: +.sp +.RS +.nf + +\fBvoid func(int\fP \fIsigno\fP\fB); +\fP +.fi +.RE +.LP +where \fIsigno\fP is the only argument to the signal-catching function. +In this case, the application shall use the +\fIsa_handler\fP member to describe the signal-catching function and +the application shall not modify the \fIsa_sigaction\fP +member. +.LP +If SA_SIGINFO is set and the signal is caught, the signal-catching +function shall be entered as: +.sp +.RS +.nf + +\fBvoid func(int\fP \fIsigno\fP\fB, siginfo_t *\fP\fIinfo\fP\fB, void *\fP\fIcontext\fP\fB); +\fP +.fi +.RE +.LP +where two additional arguments are passed to the signal-catching function. +The second argument shall point to an object of type +\fBsiginfo_t\fP explaining the reason why the signal was generated; +the third argument can be cast to a pointer to an object of +type \fBucontext_t\fP to refer to the receiving process' context that +was interrupted when the signal was delivered. In this case, +the application shall use the \fIsa_sigaction\fP member to describe +the signal-catching function and the application shall not +modify the \fIsa_handler\fP member. +.LP +The \fIsi_signo\fP member contains the system-generated signal number. +.LP +The \fIsi_errno\fP member may contain implementation-defined additional +error information; if non-zero, it contains an error +number identifying the condition that caused the signal to be generated. +.LP +The \fIsi_code\fP member contains a code identifying the cause of +the signal. +.LP +If the value of \fIsi_code\fP is less than or equal to 0, then the +signal was generated by a process and \fIsi_pid\fP and +\fIsi_uid\fP, respectively, indicate the process ID and the real user +ID of the sender. The \fI\fP header description contains +information about the signal-specific contents of the elements of +the \fBsiginfo_t\fP type. +.TP 7 +SA_NOCLDWAIT +If set, and \fIsig\fP equals SIGCHLD, child processes of the calling +processes shall not be transformed into zombie processes when +they terminate. If the calling process subsequently waits for its +children, and the process has no unwaited-for children that were +transformed into zombie processes, it shall block until all of its +children terminate, and \fIwait\fP(), \fIwaitid\fP(), and \fIwaitpid\fP() +shall fail and set \fIerrno\fP to [ECHILD]. Otherwise, terminating +child +processes shall be transformed into zombie processes, unless SIGCHLD +is set to SIG_IGN. +.TP 7 +SA_NODEFER +If set and \fIsig\fP is caught, \fIsig\fP shall not be added to the +process' signal mask on entry to the signal handler unless it +is included in \fIsa_mask\fP. Otherwise, \fIsig\fP shall always be +added to the process' signal mask on entry to the signal +handler. +.sp +.LP +When a signal is caught by a signal-catching function installed by +\fIsigaction\fP(), a new signal mask is calculated and +installed for the duration of the signal-catching function (or until +a call to either \fIsigprocmask\fP() or \fIsigsuspend\fP() is +made). This mask is formed by taking the union of the current signal +mask and the value of the \fIsa_mask\fP for the signal being +delivered \ unless SA_NODEFER or SA_RESETHAND is set, and +then including the signal being delivered. If and when the user's +signal handler returns normally, the original signal mask is +restored. +.LP +Once an action is installed for a specific signal, it shall remain +installed until another action is explicitly requested (by +another call to \fIsigaction\fP()), \ until the SA_RESETHAND flag +causes resetting of the handler, \ or until one of the \fIexec\fP +functions is called. +.LP +If the previous action for \fIsig\fP had been established by \fIsignal\fP(), +the values +of the fields returned in the structure pointed to by \fIoact\fP are +unspecified, and in particular \fIoact\fP-> +\fIsa_handler\fP is not necessarily the same value passed to \fIsignal\fP(). +However, if a +pointer to the same structure or a copy thereof is passed to a subsequent +call to \fIsigaction\fP() via the \fIact\fP argument, +handling of the signal shall be as if the original call to \fIsignal\fP() +were +repeated. +.LP +If \fIsigaction\fP() fails, no new signal handler is installed. +.LP +It is unspecified whether an attempt to set the action for a signal +that cannot be caught or ignored to SIG_DFL is ignored or +causes an error to be returned with \fIerrno\fP set to [EINVAL]. +.LP +If SA_SIGINFO is not set in \fIsa_flags\fP, then the disposition of +subsequent occurrences of \fIsig\fP when it is already +pending is implementation-defined; the signal-catching function shall +be invoked with a single argument. \ If the +implementation supports the Realtime Signals Extension option, and +if SA_SIGINFO is set in \fIsa_flags\fP, then subsequent +occurrences of \fIsig\fP generated by \fIsigqueue\fP() or as a result +of any +signal-generating function that supports the specification of an application-defined +value (when \fIsig\fP is already pending) +shall be queued in FIFO order until delivered or accepted; the signal-catching +function shall be invoked with three arguments. The +application specified value is passed to the signal-catching function +as the \fIsi_value\fP member of the \fBsiginfo_t\fP +structure. +.LP +The result of the use of \fIsigaction\fP() and a \fIsigwait\fP() function +concurrently +within a process on the same signal is unspecified. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsigaction\fP() shall return 0; otherwise, +-1 shall be returned, \fIerrno\fP shall be set to +indicate the error, and no new signal-catching function shall be installed. +.SH ERRORS +.LP +The \fIsigaction\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fIsig\fP argument is not a valid signal number or an attempt +is made to catch a signal that cannot be caught or ignore a +signal that cannot be ignored. +.TP 7 +.B ENOTSUP +The SA_SIGINFO bit flag is set in the \fIsa_flags\fP field of the +\fBsigaction\fP structure, and the implementation does not +support either the Realtime Signals Extension option, or the XSI Extension +option. +.sp +.LP +The \fIsigaction\fP() function may fail if: +.TP 7 +.B EINVAL +An attempt was made to set the action to SIG_DFL for a signal that +cannot be caught or ignored (or both). +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIsigaction\fP() function supersedes the \fIsignal\fP() function, +and should be +used in preference. In particular, \fIsigaction\fP() and \fIsignal\fP() +should not be used +in the same process to control the same signal. The behavior of reentrant +functions, as defined in the DESCRIPTION, is as specified +by this volume of IEEE\ Std\ 1003.1-2001, regardless of invocation +from a signal-catching function. This is the only +intended meaning of the statement that reentrant functions may be +used in signal-catching functions without restrictions. +Applications must still consider all effects of such functions on +such things as data structures, files, and process state. In +particular, application writers need to consider the restrictions +on interactions when interrupting \fIsleep\fP() and interactions among +multiple handles for a file description. The fact that any +specific function is listed as reentrant does not necessarily mean +that invocation of that function from a signal-catching function +is recommended. +.LP +In order to prevent errors arising from interrupting non-reentrant +function calls, applications should protect calls to these +functions either by blocking the appropriate signals or through the +use of some programmatic semaphore (see \fIsemget\fP() , \fIsem_init\fP() +, \fIsem_open\fP() , +and so on). Note in particular that even the "safe" functions may +modify \fIerrno\fP; the signal-catching function, if not +executing as an independent thread, may want to save and restore its +value. Naturally, the same principles apply to the reentrancy +of application routines and asynchronous data access. Note that \fIlongjmp\fP() +and \fIsiglongjmp\fP() are not in the list of reentrant functions. +This is because the code +executing after \fIlongjmp\fP() and \fIsiglongjmp\fP() can call any +unsafe functions with the same danger as calling those unsafe +functions directly from the signal handler. Applications that use +\fIlongjmp\fP() and \fIsiglongjmp\fP() from within signal handlers +require rigorous protection in order to be +portable. Many of the other functions that are excluded from the list +are traditionally implemented using either \fImalloc\fP() or \fIfree\fP() +functions or the standard I/O +library, both of which traditionally use data structures in a non-reentrant +manner. Since any combination of different functions +using a common data structure can cause reentrancy problems, this +volume of IEEE\ Std\ 1003.1-2001 does not define the +behavior when any unsafe function is called in a signal handler that +interrupts an unsafe function. +.LP +If the signal occurs other than as the result of calling \fIabort\fP(), +\fIkill\fP(), or \fIraise\fP(), the behavior is undefined if +the signal handler calls any function in the standard library other +than one of the functions listed in the table above or refers +to any object with static storage duration other than by assigning +a value to a static storage duration variable of type +\fBvolatile sig_atomic_t\fP. Furthermore, if such a call fails, the +value of \fIerrno\fP is unspecified. +.LP +Usually, the signal is executed on the stack that was in effect before +the signal was delivered. An alternate stack may be +specified to receive a subset of the signals being caught. +.LP +When the signal handler returns, the receiving process resumes execution +at the point it was interrupted unless the signal +handler makes other arrangements. If \fIlongjmp\fP() or \fI_longjmp\fP() +is used to leave the signal handler, then the signal mask must be +explicitly +restored by the process. +.LP +This volume of IEEE\ Std\ 1003.1-2001 defines the third argument of +a signal handling function when SA_SIGINFO is set as +a \fBvoid *\fP instead of a \fBucontext_t *\fP, but without requiring +type checking. New applications should explicitly cast the +third argument of the signal handling function to \fBucontext_t *\fP. +.LP +The BSD optional four argument signal handling function is not supported +by this volume of IEEE\ Std\ 1003.1-2001. The +BSD declaration would be: +.sp +.RS +.nf + +\fBvoid handler(int\fP \fIsig\fP\fB, int\fP \fIcode\fP\fB, struct sigcontext *\fP\fIscp\fP\fB, + char *\fP\fIaddr\fP\fB); +\fP +.fi +.RE +.LP +where \fIsig\fP is the signal number, \fIcode\fP is additional information +on certain signals, \fIscp\fP is a pointer to the +\fBsigcontext\fP structure, and \fIaddr\fP is additional address information. +Much the same information is available in the +objects pointed to by the second argument of the signal handler specified +when SA_SIGINFO is set. +.SH RATIONALE +.LP +Although this volume of IEEE\ Std\ 1003.1-2001 requires that signals +that cannot be ignored shall not be added to the +signal mask when a signal-catching function is entered, there is no +explicit requirement that subsequent calls to +\fIsigaction\fP() reflect this in the information returned in the +\fIoact\fP argument. In other words, if SIGKILL is included in +the \fIsa_mask\fP field of \fIact\fP, it is unspecified whether or +not a subsequent call to \fIsigaction\fP() returns with +SIGKILL included in the \fIsa_mask\fP field of \fIoact\fP. +.LP +The SA_NOCLDSTOP flag, when supplied in the \fIact\fP-> \fIsa_flags\fP +parameter, allows overloading SIGCHLD with the +System V semantics that each SIGCLD signal indicates a single terminated +child. Most conforming applications that catch SIGCHLD are +expected to install signal-catching functions that repeatedly call +the \fIwaitpid\fP() +function with the WNOHANG flag set, acting on each child for which +status is returned, until \fIwaitpid\fP() returns zero. If stopped +children are not of interest, the use of the SA_NOCLDSTOP +flag can prevent the overhead from invoking the signal-catching routine +when they stop. +.LP +Some historical implementations also define other mechanisms for stopping +processes, such as the \fIptrace\fP() function. These +implementations usually do not generate a SIGCHLD signal when processes +stop due to this mechanism; however, that is beyond the +scope of this volume of IEEE\ Std\ 1003.1-2001. +.LP +This volume of IEEE\ Std\ 1003.1-2001 requires that calls to \fIsigaction\fP() +that supply a NULL \fIact\fP argument +succeed, even in the case of signals that cannot be caught or ignored +(that is, SIGKILL or SIGSTOP). The System V \fIsignal\fP() and BSD +\fIsigvec\fP() functions return [EINVAL] in these cases and, in this +respect, their behavior varies from \fIsigaction\fP(). +.LP +This volume of IEEE\ Std\ 1003.1-2001 requires that \fIsigaction\fP() +properly save and restore a signal action set up +by the ISO\ C standard \fIsignal\fP() function. However, there is +no guarantee that the +reverse is true, nor could there be given the greater amount of information +conveyed by the \fBsigaction\fP structure. Because of +this, applications should avoid using both functions for the same +signal in the same process. Since this cannot always be avoided +in case of general-purpose library routines, they should always be +implemented with \fIsigaction\fP(). +.LP +It was intended that the \fIsignal\fP() function should be implementable +as a library +routine using \fIsigaction\fP(). +.LP +The POSIX Realtime Extension extends the \fIsigaction\fP() function +as specified by the POSIX.1-1990 standard to allow the +application to request on a per-signal basis via an additional signal +action flag that the extra parameters, including the +application-defined signal value, if any, be passed to the signal-catching +function. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISignal Concepts\fP , \fIbsd_signal\fP() , \fIkill\fP() , \fI_longjmp\fP() +, \fIlongjmp\fP() , \fIraise\fP() , \fIsemget\fP() , \fIsem_init\fP() +, +\fIsem_open\fP() , \fIsigaddset\fP() , \fIsigaltstack\fP() , \fIsigdelset\fP() +, \fIsigemptyset\fP() , \fIsigfillset\fP() , \fIsigismember\fP() , +\fIsignal\fP() , \fIsigprocmask\fP() , \fIsigsuspend\fP() , \fIwait\fP() +, \fIwaitid\fP() , \fIwaitpid\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sigaddset.3p b/man3p/sigaddset.3p new file mode 100644 index 000000000..f4ee43bde --- /dev/null +++ b/man3p/sigaddset.3p @@ -0,0 +1,72 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGADDSET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sigaddset +.SH NAME +sigaddset \- add a signal to a signal set +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sigaddset(sigset_t *\fP\fIset\fP\fB, int\fP \fIsigno\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsigaddset\fP() function adds the individual signal specified +by the \fIsigno\fP to the signal set pointed to by +\fIset\fP. +.LP +Applications shall call either \fIsigemptyset\fP() or \fIsigfillset\fP() +at least once for each object of type \fBsigset_t\fP prior to any +other use +of that object. If such an object is not initialized in this way, +but is nonetheless supplied as an argument to any of \fIpthread_sigmask\fP(), +\fIsigaction\fP(), +\fIsigaddset\fP(), \fIsigdelset\fP(), \fIsigismember\fP(), \fIsigpending\fP(), +\fIsigprocmask\fP(), \fIsigsuspend\fP(), \fIsigtimedwait\fP(), \fIsigwait\fP(), +or \fIsigwaitinfo\fP(), the results are undefined. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsigaddset\fP() shall return 0; otherwise, +it shall return -1 and set \fIerrno\fP to indicate +the error. +.SH ERRORS +.LP +The \fIsigaddset\fP() function may fail if: +.TP 7 +.B EINVAL +The value of the \fIsigno\fP argument is an invalid or unsupported +signal number. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISignal Concepts\fP , \fIsigaction\fP() , \fIsigdelset\fP() , \fIsigemptyset\fP() +, \fIsigfillset\fP() , \fIsigismember\fP() , \fIsigpending\fP() , +\fIsigprocmask\fP() , \fIsigsuspend\fP() , the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sigaltstack.3p b/man3p/sigaltstack.3p new file mode 100644 index 000000000..34ac681ff --- /dev/null +++ b/man3p/sigaltstack.3p @@ -0,0 +1,144 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGALTSTACK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sigaltstack +.SH NAME +sigaltstack \- set and get signal alternate stack context +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sigaltstack(const stack_t *restrict\fP \fIss\fP\fB, stack_t *restrict\fP +\fIoss\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsigaltstack\fP() function allows a process to define and examine +the state of an alternate stack for signal handlers for +the current thread. Signals that have been explicitly declared to +execute on the alternate stack shall be delivered on the +alternate stack. +.LP +If \fIss\fP is not a null pointer, it points to a \fBstack_t\fP structure +that specifies the alternate signal stack that shall +take effect upon return from \fIsigaltstack\fP(). The \fIss_flags\fP +member specifies the new stack state. If it is set to +SS_DISABLE, the stack is disabled and \fIss_sp\fP and \fIss_size\fP +are ignored. Otherwise, the stack shall be enabled, and the +\fIss_sp\fP and \fIss_size\fP members specify the new address and +size of the stack. +.LP +The range of addresses starting at \fIss_sp\fP up to but not including +\fIss_sp\fP+ \fIss_size\fP is available to the +implementation for use as the stack. This function makes no assumptions +regarding which end is the stack base and in which +direction the stack grows as items are pushed. +.LP +If \fIoss\fP is not a null pointer, on successful completion it shall +point to a \fBstack_t\fP structure that specifies the +alternate signal stack that was in effect prior to the call to \fIsigaltstack\fP(). +The \fIss_sp\fP and \fIss_size\fP members +specify the address and size of that stack. The \fIss_flags\fP member +specifies the stack's state, and may contain one of the +following values: +.TP 7 +SS_ONSTACK +The process is currently executing on the alternate signal stack. +Attempts to modify the alternate signal stack while the +process is executing on it fail. This flag shall not be modified by +processes. +.TP 7 +SS_DISABLE +The alternate signal stack is currently disabled. +.sp +.LP +The value SIGSTKSZ is a system default specifying the number of bytes +that would be used to cover the usual case when manually +allocating an alternate stack area. The value MINSIGSTKSZ is defined +to be the minimum stack size for a signal handler. In +computing an alternate stack size, a program should add that amount +to its stack requirements to allow for the system +implementation overhead. The constants SS_ONSTACK, SS_DISABLE, SIGSTKSZ, +and MINSIGSTKSZ are defined in \fI\fP. +.LP +After a successful call to one of the \fIexec\fP functions, there +are no alternate signal +stacks in the new process image. +.LP +In some implementations, a signal (whether or not indicated to execute +on the alternate stack) shall always execute on the +alternate stack if it is delivered while another signal is being caught +using the alternate stack. +.LP +Use of this function by library threads that are not bound to kernel-scheduled +entities results in undefined behavior. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsigaltstack\fP() shall return 0; otherwise, +it shall return -1 and set \fIerrno\fP to indicate +the error. +.SH ERRORS +.LP +The \fIsigaltstack\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fIss\fP argument is not a null pointer, and the \fIss_flags\fP +member pointed to by \fIss\fP contains flags other than +SS_DISABLE. +.TP 7 +.B ENOMEM +The size of the alternate stack area is less than MINSIGSTKSZ. +.TP 7 +.B EPERM +An attempt was made to modify an active stack. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Allocating Memory for an Alternate Stack +.LP +The following example illustrates a method for allocating memory for +an alternate stack. +.sp +.RS +.nf + +\fB#include +\&... +if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL) + /* Error return. */ +sigstk.ss_size = SIGSTKSZ; +sigstk.ss_flags = 0; +if (sigaltstack(&sigstk,(stack_t *)0) < 0) + perror("sigaltstack"); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +On some implementations, stack space is automatically extended as +needed. On those implementations, automatic extension is +typically not available for an alternate stack. If the stack overflows, +the behavior is undefined. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISignal Concepts\fP , \fIsigaction\fP() , \fIsigsetjmp\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sigdelset.3p b/man3p/sigdelset.3p new file mode 100644 index 000000000..89b5148e7 --- /dev/null +++ b/man3p/sigdelset.3p @@ -0,0 +1,71 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGDELSET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sigdelset +.SH NAME +sigdelset \- delete a signal from a signal set +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sigdelset(sigset_t *\fP\fIset\fP\fB, int\fP \fIsigno\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsigdelset\fP() function deletes the individual signal specified +by \fIsigno\fP from the signal set pointed to by +\fIset\fP. +.LP +Applications should call either \fIsigemptyset\fP() or \fIsigfillset\fP() +at least once for each object of type \fBsigset_t\fP prior to any +other use +of that object. If such an object is not initialized in this way, +but is nonetheless supplied as an argument to any of \fIpthread_sigmask\fP(), +\fIsigaction\fP(), \fIsigaddset\fP(), \fIsigdelset\fP(), \fIsigismember\fP(), +\fIsigpending\fP(), \fIsigprocmask\fP(), \fIsigsuspend\fP(), \fIsigtimedwait\fP(), +\fIsigwait\fP(), or \fIsigwaitinfo\fP(), the results are undefined. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsigdelset\fP() shall return 0; otherwise, +it shall return -1 and set \fIerrno\fP to indicate +the error. +.SH ERRORS +.LP +The \fIsigdelset\fP() function may fail if: +.TP 7 +.B EINVAL +The \fIsigno\fP argument is not a valid signal number, or is an unsupported +signal number. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISignal Concepts\fP , \fIsigaction\fP() , \fIsigaddset\fP() , \fIsigemptyset\fP() +, \fIsigfillset\fP() , \fIsigismember\fP() , \fIsigpending\fP() , +\fIsigprocmask\fP() , \fIsigsuspend\fP() , the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sigemptyset.3p b/man3p/sigemptyset.3p new file mode 100644 index 000000000..97be194bc --- /dev/null +++ b/man3p/sigemptyset.3p @@ -0,0 +1,93 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGEMPTYSET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sigemptyset +.SH NAME +sigemptyset \- initialize and empty a signal set +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sigemptyset(sigset_t *\fP\fIset\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsigemptyset\fP() function initializes the signal set pointed +to by \fIset\fP, such that all signals defined in +IEEE\ Std\ 1003.1-2001 are excluded. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsigemptyset\fP() shall return 0; otherwise, +it shall return -1 and set \fIerrno\fP to indicate +the error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The implementation of the \fIsigemptyset\fP() (or \fIsigfillset\fP()) +function +could quite trivially clear (or set) all the bits in the signal set. +Alternatively, it would be reasonable to initialize part of +the structure, such as a version field, to permit binary-compatibility +between releases where the size of the set varies. For such +reasons, either \fIsigemptyset\fP() or \fIsigfillset\fP() must be +called prior to any +other use of the signal set, even if such use is read-only (for example, +as an argument to \fIsigpending\fP()). This function is not intended +for dynamic allocation. +.LP +The \fIsigfillset\fP() and \fIsigemptyset\fP() functions require that +the resulting +signal set include (or exclude) all the signals defined in this volume +of IEEE\ Std\ 1003.1-2001. Although it is outside +the scope of this volume of IEEE\ Std\ 1003.1-2001 to place this requirement +on signals that are implemented as extensions, +it is recommended that implementation-defined signals also be affected +by these functions. However, there may be a good reason for +a particular signal not to be affected. For example, blocking or ignoring +an implementation-defined signal may have undesirable +side effects, whereas the default action for that signal is harmless. +In such a case, it would be preferable for such a signal to +be excluded from the signal set returned by \fIsigfillset\fP(). +.LP +In early proposals there was no distinction between invalid and unsupported +signals (the names of optional signals that were not +supported by an implementation were not defined by that implementation). +The [EINVAL] error was thus specified as a required error +for invalid signals. With that distinction, it is not necessary to +require implementations of these functions to determine whether +an optional signal is actually supported, as that could have a significant +performance impact for little value. The error could +have been required for invalid signals and optional for unsupported +signals, but this seemed unnecessarily complex. Thus, the error +is optional in both cases. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISignal Concepts\fP , \fIsigaction\fP() , \fIsigaddset\fP() , \fIsigdelset\fP() +, \fIsigfillset\fP() , \fIsigismember\fP() , \fIsigpending\fP() , +\fIsigprocmask\fP() , \fIsigsuspend\fP() , the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sigfillset.3p b/man3p/sigfillset.3p new file mode 100644 index 000000000..8e103eacb --- /dev/null +++ b/man3p/sigfillset.3p @@ -0,0 +1,57 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGFILLSET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sigfillset +.SH NAME +sigfillset \- initialize and fill a signal set +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sigfillset(sigset_t *\fP\fIset\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsigfillset\fP() function shall initialize the signal set pointed +to by \fIset\fP, such that all signals defined in this +volume of IEEE\ Std\ 1003.1-2001 are included. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsigfillset\fP() shall return 0; otherwise, +it shall return -1 and set \fIerrno\fP to indicate +the error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Refer to \fIsigemptyset\fP() . +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISignal Concepts\fP , \fIsigaction\fP() , \fIsigaddset\fP() , \fIsigdelset\fP() +, \fIsigemptyset\fP() , \fIsigismember\fP() , \fIsigpending\fP() , +\fIsigprocmask\fP() , \fIsigsuspend\fP() , the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sighold.3p b/man3p/sighold.3p new file mode 100644 index 000000000..de0bfc345 --- /dev/null +++ b/man3p/sighold.3p @@ -0,0 +1 @@ +.so man3p/sigset.3p diff --git a/man3p/sigignore.3p b/man3p/sigignore.3p new file mode 100644 index 000000000..de0bfc345 --- /dev/null +++ b/man3p/sigignore.3p @@ -0,0 +1 @@ +.so man3p/sigset.3p diff --git a/man3p/siginterrupt.3p b/man3p/siginterrupt.3p new file mode 100644 index 000000000..e845ebe8c --- /dev/null +++ b/man3p/siginterrupt.3p @@ -0,0 +1,84 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGINTERRUPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" siginterrupt +.SH NAME +siginterrupt \- allow signals to interrupt functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int siginterrupt(int\fP \fIsig\fP\fB, int\fP \fIflag\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsiginterrupt\fP() function shall change the restart behavior +when a function is interrupted by the specified signal. The +function \fIsiginterrupt\fP(\fIsig\fP, \fIflag\fP) has an effect as +if implemented as: +.sp +.RS +.nf + +\fBint siginterrupt(int sig, int flag) { + int ret; + struct sigaction act; +.sp + + (void) sigaction(sig, NULL, &act); + if (flag) + act.sa_flags &= ~SA_RESTART; + else + act.sa_flags |= SA_RESTART; + ret = sigaction(sig, &act, NULL); + return ret; +} +\fP +.fi +.RE +.SH RETURN VALUE +.LP +Upon successful completion, \fIsiginterrupt\fP() shall return 0; otherwise, +-1 shall be returned and \fIerrno\fP set to +indicate the error. +.SH ERRORS +.LP +The \fIsiginterrupt\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fIsig\fP argument is not a valid signal number. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIsiginterrupt\fP() function supports programs written to historical +system interfaces. A conforming application, when +being written or rewritten, should use \fIsigaction\fP() with the +SA_RESTART flag +instead of \fIsiginterrupt\fP(). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISignal Concepts\fP , \fIsigaction\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sigismember.3p b/man3p/sigismember.3p new file mode 100644 index 000000000..f6ab9703d --- /dev/null +++ b/man3p/sigismember.3p @@ -0,0 +1,74 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGISMEMBER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sigismember +.SH NAME +sigismember \- test for a signal in a signal set +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sigismember(const sigset_t *\fP\fIset\fP\fB, int\fP \fIsigno\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsigismember\fP() function shall test whether the signal specified +by \fIsigno\fP is a member of the set pointed to by +\fIset\fP. +.LP +Applications should call either \fIsigemptyset\fP() or \fIsigfillset\fP() +at least once for each object of type \fBsigset_t\fP prior to any +other use +of that object. If such an object is not initialized in this way, +but is nonetheless supplied as an argument to any of \fIpthread_sigmask\fP(), +\fIsigaction\fP(), \fIsigaddset\fP(), \fIsigdelset\fP(), +\fIsigismember\fP(), \fIsigpending\fP(), \fIsigprocmask\fP(), \fIsigsuspend\fP(), +\fIsigtimedwait\fP(), \fIsigwait\fP(), or \fIsigwaitinfo\fP(), the +results are undefined. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsigismember\fP() shall return 1 if +the specified signal is a member of the specified set, or 0 +if it is not. Otherwise, it shall return -1 and set \fIerrno\fP to +indicate the error. +.SH ERRORS +.LP +The \fIsigismember\fP() function may fail if: +.TP 7 +.B EINVAL +The \fIsigno\fP argument is not a valid signal number, or is an unsupported +signal number. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISignal Concepts\fP , \fIsigaction\fP() , \fIsigaddset\fP() , \fIsigdelset\fP() +, \fIsigfillset\fP() , \fIsigemptyset\fP() , \fIsigpending\fP() , +\fIsigprocmask\fP() , \fIsigsuspend\fP() , the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/siglongjmp.3p b/man3p/siglongjmp.3p new file mode 100644 index 000000000..a28218b2a --- /dev/null +++ b/man3p/siglongjmp.3p @@ -0,0 +1,70 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGLONGJMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" siglongjmp +.SH NAME +siglongjmp \- non-local goto with signal handling +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void siglongjmp(sigjmp_buf\fP \fIenv\fP\fB, int\fP \fIval\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsiglongjmp\fP() function shall be equivalent to the \fIlongjmp\fP() +function, +except as follows: +.IP " *" 3 +References to \fIsetjmp\fP() shall be equivalent to \fIsigsetjmp\fP(). +.LP +.IP " *" 3 +The \fIsiglongjmp\fP() function shall restore the saved signal mask +if and only if the \fIenv\fP argument was initialized by a +call to \fIsigsetjmp\fP() with a non-zero \fIsavemask\fP argument. +.LP +.SH RETURN VALUE +.LP +After \fIsiglongjmp\fP() is completed, program execution shall continue +as if the corresponding invocation of \fIsigsetjmp\fP() had just returned +the value specified by \fIval\fP. The \fIsiglongjmp\fP() +function shall not cause \fIsigsetjmp\fP() to return 0; if \fIval\fP +is 0, \fIsigsetjmp\fP() shall return the value 1. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The distinction between \fIsetjmp\fP() or \fIlongjmp\fP() and \fIsigsetjmp\fP() +or +\fIsiglongjmp\fP() is only significant for programs which use \fIsigaction\fP(), +\fIsigprocmask\fP(), or \fIsigsuspend\fP(). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIlongjmp\fP() , \fIsetjmp\fP() , \fIsigprocmask\fP() , \fIsigsetjmp\fP() +, \fIsigsuspend\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/signal.3p b/man3p/signal.3p new file mode 100644 index 000000000..05d9f55cf --- /dev/null +++ b/man3p/signal.3p @@ -0,0 +1,151 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGNAL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" signal +.SH NAME +signal \- signal management +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void (*signal(int\fP \fIsig\fP\fB, void (*\fP\fIfunc\fP\fB)(int)))(int); +.br +\fP +.SH DESCRIPTION +.LP +Use +of this function is unspecified in a multi-threaded process. +.LP +The \fIsignal\fP() function chooses one of three ways in which receipt +of the signal number \fIsig\fP is to be subsequently +handled. If the value of \fIfunc\fP is SIG_DFL, default handling for +that signal shall occur. If the value of \fIfunc\fP is +SIG_IGN, the signal shall be ignored. Otherwise, the application shall +ensure that \fIfunc\fP points to a function to be called +when that signal occurs. An invocation of such a function because +of a signal, or (recursively) of any further functions called by +that invocation (other than functions in the standard library), is +called a "signal handler". +.LP +When a signal occurs, and \fIfunc\fP points to a function, it is implementation-defined +whether the equivalent of a: +.sp +.RS +.nf + +\fBsignal(\fP\fIsig\fP\fB, SIG_DFL); +\fP +.fi +.RE +.LP +is executed or the implementation prevents some implementation-defined +set of signals (at least including \fIsig\fP) from +occurring until the current signal handling has completed. (If the +value of \fIsig\fP is SIGILL, the implementation may +alternatively define that no action is taken.) Next the equivalent +of: +.sp +.RS +.nf + +\fB(*func)(sig); +\fP +.fi +.RE +.LP +is executed. If and when the function returns, if the value of \fIsig\fP +was SIGFPE, SIGILL, or SIGSEGV or any other +implementation-defined value corresponding to a computational exception, +the behavior is undefined. Otherwise, the program shall +resume execution at the point it was interrupted. If the signal occurs +as the result of calling the \fIabort\fP(), \fIraise\fP(), \fIkill\fP(), +\fIpthread_kill\fP(), or \fIsigqueue\fP() function, the +signal handler shall not call the \fIraise\fP() function. +.LP +If the signal occurs other than as the result of calling \fIabort\fP(), +\fIraise\fP(), \fIkill\fP(), \fIpthread_kill\fP(), or \fIsigqueue\fP(), +\ the behavior is undefined if the signal handler refers to any +object with static storage duration other than by assigning a value +to an object declared as volatile \fBsig_atomic_t\fP, or if +the signal handler calls any function in the standard library other +than one of the functions listed in \fISignal Concepts\fP . Furthermore, +if such a call fails, the value of \fIerrno\fP is +unspecified. +.LP +At program start-up, the equivalent of: +.sp +.RS +.nf + +\fBsignal(\fP\fIsig\fP\fB, SIG_IGN); +\fP +.fi +.RE +.LP +is executed for some signals, and the equivalent of: +.sp +.RS +.nf + +\fBsignal(\fP\fIsig\fP\fB, SIG_DFL); +\fP +.fi +.RE +.LP +is executed for all other signals \ (see \fIexec\fP). +.SH RETURN VALUE +.LP +If the request can be honored, \fIsignal\fP() shall return the value +of \fIfunc\fP for the most recent call to \fIsignal\fP() +for the specified signal \fIsig\fP. Otherwise, SIG_ERR shall be returned +and a positive value shall be stored in \fIerrno\fP. +.SH ERRORS +.LP +The \fIsignal\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fIsig\fP argument is not a valid signal number or an attempt +is made to catch a signal that cannot be caught or ignore a +signal that cannot be ignored. +.sp +.LP +The \fIsignal\fP() function may fail if: +.TP 7 +.B EINVAL +An +attempt was made to set the action to SIG_DFL for a signal that cannot +be caught or ignored (or both). +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIsigaction\fP() function provides a more comprehensive and reliable +mechanism +for controlling signals; new applications should use \fIsigaction\fP() +rather than +\fIsignal\fP(). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISignal Concepts\fP , \fIexec\fP() , \fIpause\fP() , \fIsigaction\fP() +, \fIsigsuspend\fP() , \fIwaitid\fP() , the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/signbit.3p b/man3p/signbit.3p new file mode 100644 index 000000000..0a1cea6e0 --- /dev/null +++ b/man3p/signbit.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGNBIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" signbit +.SH NAME +signbit \- test sign +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int signbit(real-floating\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsignbit\fP() macro shall determine whether the sign of its +argument value is negative. NaNs, zeros, and infinities have +a sign bit. +.SH RETURN VALUE +.LP +The \fIsignbit\fP() macro shall return a non-zero value if and only +if the sign of its argument value is negative. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfpclassify\fP() , \fIisfinite\fP() , \fIisinf\fP() , \fIisnan\fP() +, \fIisnormal\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/signgam.3p b/man3p/signgam.3p new file mode 100644 index 000000000..b17905e64 --- /dev/null +++ b/man3p/signgam.3p @@ -0,0 +1 @@ +.so man3p/lgamma.3p diff --git a/man3p/sigpause.3p b/man3p/sigpause.3p new file mode 100644 index 000000000..de0bfc345 --- /dev/null +++ b/man3p/sigpause.3p @@ -0,0 +1 @@ +.so man3p/sigset.3p diff --git a/man3p/sigpending.3p b/man3p/sigpending.3p new file mode 100644 index 000000000..fd9ab5a4e --- /dev/null +++ b/man3p/sigpending.3p @@ -0,0 +1,58 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGPENDING" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sigpending +.SH NAME +sigpending \- examine pending signals +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sigpending(sigset_t *\fP\fIset\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsigpending\fP() function shall store, in the location referenced +by the \fIset\fP argument, the set of signals that are +blocked from delivery to the calling thread and that are pending on +the process or the calling thread. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsigpending\fP() shall return 0; otherwise, +-1 shall be returned and \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsigaddset\fP() , \fIsigdelset\fP() , \fIsigemptyset\fP() , \fIsigfillset\fP() +, \fIsigismember\fP() , \fIsigprocmask\fP() , the Base Definitions +volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sigprocmask.3p b/man3p/sigprocmask.3p new file mode 100644 index 000000000..7b87ea9c9 --- /dev/null +++ b/man3p/sigprocmask.3p @@ -0,0 +1,144 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_SIGMASK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_sigmask +.SH NAME +pthread_sigmask, sigprocmask \- examine and change blocked signals +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +\fP +.LP +\fBint pthread_sigmask(int\fP \fIhow\fP\fB, const sigset_t *restrict\fP +\fIset\fP\fB, +.br +\ \ \ \ \ \ sigset_t *restrict\fP \fIoset\fP\fB); +.br +\fP +.LP +\fBint sigprocmask(int\fP \fIhow\fP\fB, const sigset_t *restrict\fP +\fIset\fP\fB, +.br +\ \ \ \ \ \ sigset_t *restrict\fP \fIoset\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_sigmask\fP() function shall examine or change (or both) +the calling thread's signal mask, regardless of the number +of threads in the process. The function shall be equivalent to \fIsigprocmask\fP(), +without the restriction that the call be made +in a single-threaded process. +.LP +In a single-threaded process, the \fIsigprocmask\fP() function shall +examine or change (or both) the signal mask of the calling +thread. +.LP +If the argument \fIset\fP is not a null pointer, it points to a set +of signals to be used to change the currently blocked +set. +.LP +The argument \fIhow\fP indicates the way in which the set is changed, +and the application shall ensure it consists of one of +the following values: +.TP 7 +SIG_BLOCK +The resulting set shall be the union of the current set and the signal +set pointed to by \fIset\fP. +.TP 7 +SIG_SETMASK +The resulting set shall be the signal set pointed to by \fIset\fP. +.TP 7 +SIG_UNBLOCK +The resulting set shall be the intersection of the current set and +the complement of the signal set pointed to by +\fIset\fP. +.sp +.LP +If the argument \fIoset\fP is not a null pointer, the previous mask +shall be stored in the location pointed to by \fIoset\fP. +If \fIset\fP is a null pointer, the value of the argument \fIhow\fP +is not significant and the process' signal mask shall be +unchanged; thus the call can be used to enquire about currently blocked +signals. +.LP +If there are any pending unblocked signals after the call to \fIsigprocmask\fP(), +at least one of those signals shall be +delivered before the call to \fIsigprocmask\fP() returns. +.LP +It is not possible to block those signals which cannot be ignored. +This shall be enforced by the system without causing an error +to be indicated. +.LP +If any of the SIGFPE, SIGILL, SIGSEGV, or SIGBUS signals are generated +while they are blocked, the result is undefined, unless +the signal was generated by the \fIkill\fP() function, the \fIsigqueue\fP() +function, or the \fIraise\fP() +function. +.LP +If \fIsigprocmask\fP() fails, the thread's signal mask shall not be +changed. +.LP +The use of the \fIsigprocmask\fP() function is unspecified in a multi-threaded +process. +.SH RETURN VALUE +.LP +Upon successful completion \fIpthread_sigmask\fP() shall return 0; +otherwise, it shall return the corresponding error number. +.LP +Upon successful completion, \fIsigprocmask\fP() shall return 0; otherwise, +-1 shall be returned, \fIerrno\fP shall be set to +indicate the error, and the process' signal mask shall be unchanged. +.SH ERRORS +.LP +The \fIpthread_sigmask\fP() and \fIsigprocmask\fP() functions +shall fail if: +.TP 7 +.B EINVAL +The value of the \fIhow\fP argument is not equal to one of the defined +values. +.sp +.LP +The \fIpthread_sigmask\fP() function shall not return an error code +of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +When a process' signal mask is changed in a signal-catching function +that is installed by \fIsigaction\fP(), the restoration of the signal +mask on return from the signal-catching +function overrides that change (see \fIsigaction\fP()). If the signal-catching +function +was installed with \fIsignal\fP(), it is unspecified whether this +occurs. +.LP +See \fIkill\fP() for a discussion of the requirement on delivery of +signals. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsigaction\fP() , \fIsigaddset\fP() , \fIsigdelset\fP() , \fIsigemptyset\fP() +, \fIsigfillset\fP() , \fIsigismember\fP() , \fIsigpending\fP() , +\fIsigqueue\fP() , \fIsigsuspend\fP() , the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sigqueue.3p b/man3p/sigqueue.3p new file mode 100644 index 000000000..63269efca --- /dev/null +++ b/man3p/sigqueue.3p @@ -0,0 +1,139 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGQUEUE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sigqueue +.SH NAME +sigqueue \- queue a signal to a process (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sigqueue(pid_t\fP \fIpid\fP\fB, int\fP \fIsigno\fP\fB, const union +sigval\fP \fIvalue\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsigqueue\fP() function shall cause the signal specified by +\fIsigno\fP to be sent with the value specified by +\fIvalue\fP to the process specified by \fIpid\fP. If \fIsigno\fP +is zero (the null signal), error checking is performed but no +signal is actually sent. The null signal can be used to check the +validity of \fIpid\fP. +.LP +The conditions required for a process to have permission to queue +a signal to another process are the same as for the \fIkill\fP() function. +.LP +The \fIsigqueue\fP() function shall return immediately. If SA_SIGINFO +is set for \fIsigno\fP and if the resources were +available to queue the signal, the signal shall be queued and sent +to the receiving process. If SA_SIGINFO is not set for +\fIsigno\fP, then \fIsigno\fP shall be sent at least once to the receiving +process; it is unspecified whether \fIvalue\fP shall +be sent to the receiving process as a result of this call. +.LP +If the value of \fIpid\fP causes \fIsigno\fP to be generated for the +sending process, and if \fIsigno\fP is not blocked for +the calling thread and if no other thread has \fIsigno\fP unblocked +or is waiting in a \fIsigwait\fP() function for \fIsigno\fP, either +\fIsigno\fP or at least the pending, unblocked +signal shall be delivered to the calling thread before the \fIsigqueue\fP() +function returns. Should any multiple pending signals +in the range SIGRTMIN to SIGRTMAX be selected for delivery, it shall +be the lowest numbered one. The selection order between +realtime and non-realtime signals, or between multiple pending non-realtime +signals, is unspecified. +.SH RETURN VALUE +.LP +Upon successful completion, the specified signal shall have been queued, +and the \fIsigqueue\fP() function shall return a value +of zero. Otherwise, the function shall return a value of -1 and set +\fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIsigqueue\fP() function shall fail if: +.TP 7 +.B EAGAIN +No resources are available to queue the signal. The process has already +queued {SIGQUEUE_MAX} signals that are still pending at +the receiver(s), or a system-wide resource limit has been exceeded. +.TP 7 +.B EINVAL +The value of the \fIsigno\fP argument is an invalid or unsupported +signal number. +.TP 7 +.B EPERM +The process does not have the appropriate privilege to send the signal +to the receiving process. +.TP 7 +.B ESRCH +The process \fIpid\fP does not exist. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIsigqueue\fP() function allows an application to queue a realtime +signal to itself or to another process, specifying the +application-defined value. This is common practice in realtime applications +on existing realtime systems. It was felt that +specifying another function in the \fIsig\fP... name space already +carved out for signals was preferable to extending the +interface to \fIkill\fP(). +.LP +Such a function became necessary when the put/get event function of +the message queues was removed. It should be noted that the +\fIsigqueue\fP() function implies reduced performance in a security-conscious +implementation as the access permissions between the +sender and receiver have to be checked on each send when the \fIpid\fP +is resolved into a target process. Such access checks were +necessary only at message queue open in the previous interface. +.LP +The standard developers required that \fIsigqueue\fP() have the same +semantics with respect to the null signal as \fIkill\fP(), and that +the same permission checking be used. But because of the difficulty +of +implementing the "broadcast" semantic of \fIkill\fP() (for example, +to process groups) and +the interaction with resource allocation, this semantic was not adopted. +The \fIsigqueue\fP() function queues a signal to a single +process specified by the \fIpid\fP argument. +.LP +The \fIsigqueue\fP() function can fail if the system has insufficient +resources to queue the signal. An explicit limit on the +number of queued signals that a process could send was introduced. +While the limit is "per-sender", this volume of +IEEE\ Std\ 1003.1-2001 does not specify that the resources be part +of the state of the sender. This would require either +that the sender be maintained after exit until all signals that it +had sent to other processes were handled or that all such +signals that had not yet been acted upon be removed from the queue(s) +of the receivers. This volume of +IEEE\ Std\ 1003.1-2001 does not preclude this behavior, but an implementation +that allocated queuing resources from a +system-wide pool (with per-sender limits) and that leaves queued signals +pending after the sender exits is also permitted. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIRealtime Signals\fP , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sigrelse.3p b/man3p/sigrelse.3p new file mode 100644 index 000000000..de0bfc345 --- /dev/null +++ b/man3p/sigrelse.3p @@ -0,0 +1 @@ +.so man3p/sigset.3p diff --git a/man3p/sigset.3p b/man3p/sigset.3p new file mode 100644 index 000000000..1e80053a2 --- /dev/null +++ b/man3p/sigset.3p @@ -0,0 +1,140 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGHOLD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sighold +.SH NAME +sighold, sigignore, sigpause, sigrelse, sigset \- signal management +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sighold(int\fP \fIsig\fP\fB); +.br +int sigignore(int\fP \fIsig\fP\fB); +.br +int sigpause(int\fP \fIsig\fP\fB); +.br +int sigrelse(int\fP \fIsig\fP\fB); +.br +void (*sigset(int\fP \fIsig\fP\fB, void (*\fP\fIdisp\fP\fB)(int)))(int); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +Use of any of these functions is unspecified in a multi-threaded process. +.LP +The \fIsighold\fP(), \fIsigignore\fP(), \fIsigpause\fP(), \fIsigrelse\fP(), +and \fIsigset\fP() functions provide simplified +signal management. +.LP +The \fIsigset\fP() function shall modify signal dispositions. The +\fIsig\fP argument specifies the signal, which may be any +signal except SIGKILL and SIGSTOP. The \fIdisp\fP argument specifies +the signal's disposition, which may be SIG_DFL, SIG_IGN, or +the address of a signal handler. If \fIsigset\fP() is used, and \fIdisp\fP +is the address of a signal handler, the system shall +add \fIsig\fP to the calling process' signal mask before executing +the signal handler; when the signal handler returns, the system +shall restore the calling process' signal mask to its state prior +to the delivery of the signal. In addition, if \fIsigset\fP() is +used, and \fIdisp\fP is equal to SIG_HOLD, \fIsig\fP shall be added +to the calling process' signal mask and \fIsig\fP's +disposition shall remain unchanged. If \fIsigset\fP() is used, and +\fIdisp\fP is not equal to SIG_HOLD, \fIsig\fP shall be +removed from the calling process' signal mask. +.LP +The \fIsighold\fP() function shall add \fIsig\fP to the calling process' +signal mask. +.LP +The \fIsigrelse\fP() function shall remove \fIsig\fP from the calling +process' signal mask. +.LP +The \fIsigignore\fP() function shall set the disposition of \fIsig\fP +to SIG_IGN. +.LP +The \fIsigpause\fP() function shall remove \fIsig\fP from the calling +process' signal mask and suspend the calling process +until a signal is received. The \fIsigpause\fP() function shall restore +the process' signal mask to its original state before +returning. +.LP +If the action for the SIGCHLD signal is set to SIG_IGN, child processes +of the calling processes shall not be transformed into +zombie processes when they terminate. If the calling process subsequently +waits for its children, and the process has no +unwaited-for children that were transformed into zombie processes, +it shall block until all of its children terminate, and \fIwait\fP(), +\fIwaitid\fP(), and \fIwaitpid\fP() shall fail and set \fIerrno\fP +to [ECHILD]. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsigset\fP() shall return SIG_HOLD if +the signal had been blocked and the signal's previous +disposition if it had not been blocked. Otherwise, SIG_ERR shall be +returned and \fIerrno\fP set to indicate the error. +.LP +The \fIsigpause\fP() function shall suspend execution of the thread +until a signal is received, whereupon it shall return -1 +and set \fIerrno\fP to [EINTR]. +.LP +For all other functions, upon successful completion, 0 shall be returned. +Otherwise, -1 shall be returned and \fIerrno\fP set +to indicate the error. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +.B EINVAL +The \fIsig\fP argument is an illegal signal number. +.sp +.LP +The \fIsigset\fP() and \fIsigignore\fP() functions shall fail if: +.TP 7 +.B EINVAL +An attempt is made to catch a signal that cannot be caught, or to +ignore a signal that cannot be ignored. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIsigaction\fP() function provides a more comprehensive and reliable +mechanism +for controlling signals; new applications should use \fIsigaction\fP() +rather than +\fIsigset\fP(). +.LP +The \fIsighold\fP() function, in conjunction with \fIsigrelse\fP() +or \fIsigpause\fP(), may be used to establish critical +regions of code that require the delivery of a signal to be temporarily +deferred. +.LP +The \fIsigsuspend\fP() function should be used in preference to \fIsigpause\fP() +for broader portability. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISignal Concepts\fP , \fIexec\fP() , \fIpause\fP() , \fIsigaction\fP() +, \fIsignal\fP() , \fIsigsuspend\fP() , \fIwaitid\fP() , the Base +Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sigsetjmp.3p b/man3p/sigsetjmp.3p new file mode 100644 index 000000000..627f9cacd --- /dev/null +++ b/man3p/sigsetjmp.3p @@ -0,0 +1,103 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGSETJMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sigsetjmp +.SH NAME +sigsetjmp \- set jump point for a non-local goto +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sigsetjmp(sigjmp_buf\fP \fIenv\fP\fB, int\fP \fIsavemask\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsigsetjmp\fP() function shall be equivalent to the \fIsetjmp\fP() +function, +except as follows: +.IP " *" 3 +References to \fIsetjmp\fP() are equivalent to \fIsigsetjmp\fP(). +.LP +.IP " *" 3 +References to \fIlongjmp\fP() are equivalent to \fIsiglongjmp\fP(). +.LP +.IP " *" 3 +If the value of the \fIsavemask\fP argument is not 0, \fIsigsetjmp\fP() +shall also save the current signal mask of the calling +thread as part of the calling environment. +.LP +.SH RETURN VALUE +.LP +If the return is from a successful direct invocation, \fIsigsetjmp\fP() +shall return 0. If the return is from a call to \fIsiglongjmp\fP(), +\fIsigsetjmp\fP() shall return a non-zero value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The distinction between \fIsetjmp\fP()/ \fIlongjmp\fP() and \fIsigsetjmp\fP()/ +\fIsiglongjmp\fP() is only significant for programs which use \fIsigaction\fP(), +\fIsigprocmask\fP(), or \fIsigsuspend\fP(). +.LP +Note that since this function is defined in terms of \fIsetjmp\fP(), +if \fIsavemask\fP +is zero, it is unspecified whether the signal mask is saved. +.SH RATIONALE +.LP +The ISO\ C standard specifies various restrictions on the usage of +the \fIsetjmp\fP() macro in order to permit implementors to recognize +the name in the compiler and not +implement an actual function. These same restrictions apply to the +\fIsigsetjmp\fP() macro. +.LP +There are processors that cannot easily support these calls, but this +was not considered a sufficient reason to exclude +them. +.LP +4.2 BSD, 4.3 BSD, and XSI-conformant systems provide functions named +\fI_setjmp\fP() +and \fI_longjmp\fP() that, together with \fIsetjmp\fP() and \fIlongjmp\fP(), +provide the same +functionality as \fIsigsetjmp\fP() and \fIsiglongjmp\fP(). On those +systems, \fIsetjmp\fP() and \fIlongjmp\fP() save and restore signal +masks, while \fI_setjmp\fP() and \fI_longjmp\fP() do not. On System +V Release 3 and in corresponding issues of the SVID, \fIsetjmp\fP() +and \fIlongjmp\fP() are explicitly defined +not to save and restore signal masks. In order to permit existing +practice in both cases, the relation of \fIsetjmp\fP() and \fIlongjmp\fP() +to signal masks is not +specified, and a new set of functions is defined instead. +.LP +The \fIlongjmp\fP() and \fIsiglongjmp\fP() +functions operate as in the previous issue provided the matching \fIsetjmp\fP() +or +\fIsigsetjmp\fP() has been performed in the same thread. Non-local +jumps into contexts saved by other threads would be at best a +questionable practice and were not considered worthy of standardization. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsiglongjmp\fP() , \fIsignal\fP() , \fIsigprocmask\fP() , \fIsigsuspend\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sigsuspend.3p b/man3p/sigsuspend.3p new file mode 100644 index 000000000..a0d5a6267 --- /dev/null +++ b/man3p/sigsuspend.3p @@ -0,0 +1,79 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGSUSPEND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sigsuspend +.SH NAME +sigsuspend \- wait for a signal +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sigsuspend(const sigset_t *\fP\fIsigmask\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsigsuspend\fP() function shall replace the current signal mask +of the calling thread with the set of signals pointed to +by \fIsigmask\fP and then suspend the thread until delivery of a signal +whose action is either to execute a signal-catching +function or to terminate the process. This shall not cause any other +signals that may have been pending on the process to become +pending on the thread. +.LP +If the action is to terminate the process then \fIsigsuspend\fP() +shall never return. If the action is to execute a +signal-catching function, then \fIsigsuspend\fP() shall return after +the signal-catching function returns, with the signal mask +restored to the set that existed prior to the \fIsigsuspend\fP() call. +.LP +It is not possible to block signals that cannot be ignored. This is +enforced by the system without causing an error to be +indicated. +.SH RETURN VALUE +.LP +Since \fIsigsuspend\fP() suspends thread execution indefinitely, there +is no successful completion return value. If a return +occurs, -1 shall be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIsigsuspend\fP() function shall fail if: +.TP 7 +.B EINTR +A signal is caught by the calling process and control is returned +from the signal-catching function. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Normally, at the beginning of a critical code section, a specified +set of signals is blocked using the \fIsigprocmask\fP() function. +When the thread has completed the critical section and needs to +wait for the previously blocked signal(s), it pauses by calling \fIsigsuspend\fP() +with the mask that was returned by the \fIsigprocmask\fP() call. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISignal Concepts\fP , \fIpause\fP() , \fIsigaction\fP() , \fIsigaddset\fP() +, \fIsigdelset\fP() , \fIsigemptyset\fP() , \fIsigfillset\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sigtimedwait.3p b/man3p/sigtimedwait.3p new file mode 100644 index 000000000..403e8070e --- /dev/null +++ b/man3p/sigtimedwait.3p @@ -0,0 +1 @@ +.so man3p/sigwaitinfo.3p diff --git a/man3p/sigwait.3p b/man3p/sigwait.3p new file mode 100644 index 000000000..eb8440447 --- /dev/null +++ b/man3p/sigwait.3p @@ -0,0 +1,106 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGWAIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sigwait +.SH NAME +sigwait \- wait for queued signals +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sigwait(const sigset_t *restrict\fP \fIset\fP\fB, int *restrict\fP +\fIsig\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsigwait\fP() function shall select a pending signal from \fIset\fP, +atomically clear it from the system's set of +pending signals, and return that signal number in the location referenced +by \fIsig\fP. If prior to the call to \fIsigwait\fP() +there are multiple pending instances of a single signal number, it +is implementation-defined whether upon successful return there +are any remaining pending signals for that signal number. \ If the +implementation supports queued signals and there are +multiple signals queued for the signal number selected, the first +such queued signal shall cause a return from \fIsigwait\fP() and +the remainder shall remain queued. If no signal in \fIset\fP is +pending at the time of the call, the thread shall be suspended until +one or more becomes pending. The signals defined by \fIset\fP +shall have been blocked at the time of the call to \fIsigwait\fP(); +otherwise, the behavior is undefined. The effect of +\fIsigwait\fP() on the signal actions for the signals in \fIset\fP +is unspecified. +.LP +If more than one thread is using \fIsigwait\fP() to wait for the same +signal, no more than one of these threads shall return +from \fIsigwait\fP() with the signal number. Which thread returns +from \fIsigwait\fP() if more than a single thread is waiting is +unspecified. +.LP +Should any of the multiple pending signals in the range SIGRTMIN to +SIGRTMAX be selected, it shall be the lowest numbered one. The +selection order between realtime and non-realtime signals, or between +multiple pending non-realtime signals, is unspecified. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsigwait\fP() shall store the signal +number of the received signal at the location referenced by +\fIsig\fP and return zero. Otherwise, an error number shall be returned +to indicate the error. +.SH ERRORS +.LP +The \fIsigwait\fP() function may fail if: +.TP 7 +.B EINVAL +The \fIset\fP argument contains an invalid or unsupported signal number. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +To provide a convenient way for a thread to wait for a signal, this +volume of IEEE\ Std\ 1003.1-2001 provides the +\fIsigwait\fP() function. For most cases where a thread has to wait +for a signal, the \fIsigwait\fP() function should be quite +convenient, efficient, and adequate. +.LP +However, requests were made for a lower-level primitive than \fIsigwait\fP() +and for semaphores that could be used by threads. +After some consideration, threads were allowed to use semaphores and +\fIsem_post\fP() was +defined to be async-signal and async-cancel-safe. +.LP +In summary, when it is necessary for code run in response to an asynchronous +signal to notify a thread, \fIsigwait\fP() should +be used to handle the signal. Alternatively, if the implementation +provides semaphores, they also can be used, either following +\fIsigwait\fP() or from within a signal handling routine previously +registered with \fIsigaction\fP(). +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISignal Concepts\fP , \fIRealtime +Signals\fP , \fIpause\fP() , \fIpthread_sigmask\fP() , \fIsigaction\fP() +, \fIsigpending\fP() , \fIsigsuspend\fP() , \fIsigwaitinfo\fP() , +the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sigwaitinfo.3p b/man3p/sigwaitinfo.3p new file mode 100644 index 000000000..113ac95ab --- /dev/null +++ b/man3p/sigwaitinfo.3p @@ -0,0 +1,263 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIGTIMEDWAIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sigtimedwait +.SH NAME +sigtimedwait, sigwaitinfo \- wait for queued signals (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sigtimedwait(const sigset_t *restrict\fP \fIset\fP\fB, +.br +\ \ \ \ \ \ siginfo_t *restrict\fP \fIinfo\fP\fB, +.br +\ \ \ \ \ \ const struct timespec *restrict\fP \fItimeout\fP\fB); +.br +int sigwaitinfo(const sigset_t *restrict\fP \fIset\fP\fB, +.br +\ \ \ \ \ \ siginfo_t *restrict\fP \fIinfo\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsigtimedwait\fP() function shall be equivalent to \fIsigwaitinfo\fP() +except that if none of the signals specified by +\fIset\fP are pending, \fIsigtimedwait\fP() shall wait for the time +interval specified in the \fBtimespec\fP structure +referenced by \fItimeout\fP. If the \fBtimespec\fP structure pointed +to by \fItimeout\fP is zero-valued and if none of the +signals specified by \fIset\fP are pending, then \fIsigtimedwait\fP() +shall return immediately with an error. If \fItimeout\fP +is the NULL pointer, the behavior is unspecified. \ If the Monotonic +Clock option is supported, the CLOCK_MONOTONIC +clock shall be used to measure the time interval specified by the +\fItimeout\fP argument. +.LP +The \fIsigwaitinfo\fP() function selects the pending signal from the +set specified by \fIset\fP. Should any of multiple +pending signals in the range SIGRTMIN to SIGRTMAX be selected, it +shall be the lowest numbered one. The selection order between +realtime and non-realtime signals, or between multiple pending non-realtime +signals, is unspecified. If no signal in \fIset\fP is +pending at the time of the call, the calling thread shall be suspended +until one or more signals in \fIset\fP become pending or +until it is interrupted by an unblocked, caught signal. +.LP +The \fIsigwaitinfo\fP() function shall be equivalent to the \fIsigwait\fP() +function +if the \fIinfo\fP argument is NULL. If the \fIinfo\fP argument is +non-NULL, the \fIsigwaitinfo\fP() function shall be equivalent +to \fIsigwait\fP(), except that the selected signal number shall be +stored in the +\fIsi_signo\fP member, and the cause of the signal shall be stored +in the \fIsi_code\fP member. If any value is queued to the +selected signal, the first such queued value shall be dequeued and, +if the \fIinfo\fP argument is non-NULL, the value shall be +stored in the \fIsi_value\fP member of \fIinfo\fP. The system resource +used to queue the signal shall be released and returned to +the system for other use. If no value is queued, the content of the +\fIsi_value\fP member is undefined. If no further signals are +queued for the selected signal, the pending indication for that signal +shall be reset. +.SH RETURN VALUE +.LP +Upon successful completion (that is, one of the signals specified +by \fIset\fP is pending or is generated) \fIsigwaitinfo\fP() +and \fIsigtimedwait\fP() shall return the selected signal number. +Otherwise, the function shall return a value of -1 and set +\fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIsigtimedwait\fP() function shall fail if: +.TP 7 +.B EAGAIN +No signal specified by \fIset\fP was generated within the specified +timeout period. +.sp +.LP +The \fIsigtimedwait\fP() and \fIsigwaitinfo\fP() functions may fail +if: +.TP 7 +.B EINTR +The wait was interrupted by an unblocked, caught signal. It shall +be documented in system documentation whether this error +causes these functions to fail. +.sp +.LP +The \fIsigtimedwait\fP() function may also fail if: +.TP 7 +.B EINVAL +The \fItimeout\fP argument specified a \fItv_nsec\fP value less than +zero or greater than or equal to 1000 million. +.sp +.LP +An implementation only checks for this error if no signal is pending +in \fIset\fP and it is necessary to wait. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIsigtimedwait\fP() function times out and returns an [EAGAIN] +error. Application writers should note that this is +inconsistent with other functions such as \fIpthread_cond_timedwait\fP() +that return [ETIMEDOUT]. +.SH RATIONALE +.LP +Existing programming practice on realtime systems uses the ability +to pause waiting for a selected set of events and handle the +first event that occurs in-line instead of in a signal-handling function. +This allows applications to be written in an +event-directed style similar to a state machine. This style of programming +is useful for largescale transaction processing in which +the overall throughput of an application and the ability to clearly +track states are more important than the ability to minimize +the response time of individual event handling. +.LP +It is possible to construct a signal-waiting macro function out of +the realtime signal function mechanism defined in this volume +of IEEE\ Std\ 1003.1-2001. However, such a macro has to include the +definition of a generalized handler for all signals to +be waited on. A significant portion of the overhead of handler processing +can be avoided if the signal-waiting function is provided +by the kernel. This volume of IEEE\ Std\ 1003.1-2001 therefore provides +two signal-waiting functions-one that waits +indefinitely and one with a timeout-as part of the overall realtime +signal function specification. +.LP +The specification of a function with a timeout allows an application +to be written that can be broken out of a wait after a set +period of time if no event has occurred. It was argued that setting +a timer event before the wait and recognizing the timer event +in the wait would also implement the same functionality, but at a +lower performance level. Because of the performance degradation +associated with the user-level specification of a timer event and +the subsequent cancellation of that timer event after the wait +completes for a valid event, and the complexity associated with handling +potential race conditions associated with the user-level +method, the separate function has been included. +.LP +Note that the semantics of the \fIsigwaitinfo\fP() function are nearly +identical to that of the \fIsigwait\fP() function defined by this +volume of IEEE\ Std\ 1003.1-2001. The only +difference is that \fIsigwaitinfo\fP() returns the queued signal value +in the \fIvalue\fP argument. The return of the queued +value is required so that applications can differentiate between multiple +events queued to the same signal number. +.LP +The two distinct functions are being maintained because some implementations +may choose to implement the POSIX Threads Extension +functions and not implement the queued signals extensions. Note, though, +that \fIsigwaitinfo\fP() does not return the queued value +if the \fIvalue\fP argument is NULL, so the POSIX Threads Extension +\fIsigwait\fP() +function can be implemented as a macro on \fIsigwaitinfo\fP(). +.LP +The \fIsigtimedwait\fP() function was separated from the \fIsigwaitinfo\fP() +function to address concerns regarding the +overloading of the \fItimeout\fP pointer to indicate indefinite wait +(no timeout), timed wait, and immediate return, and concerns +regarding consistency with other functions where the conditional and +timed waits were separate functions from the pure blocking +function. The semantics of \fIsigtimedwait\fP() are specified such +that \fIsigwaitinfo\fP() could be implemented as a macro with +a NULL pointer for \fItimeout\fP. +.LP +The \fIsigwait\fP functions provide a synchronous mechanism for threads +to wait for asynchronously-generated signals. One +important question was how many threads that are suspended in a call +to a \fIsigwait\fP() +function for a signal should return from the call when the signal +is sent. Four choices were considered: +.IP " 1." 4 +Return an error for multiple simultaneous calls to \fIsigwait\fP functions +for the same signal. +.LP +.IP " 2." 4 +One or more threads return. +.LP +.IP " 3." 4 +All waiting threads return. +.LP +.IP " 4." 4 +Exactly one thread returns. +.LP +.LP +Prohibiting multiple calls to \fIsigwait\fP() for the same signal +was felt to be overly +restrictive. The "one or more" behavior made implementation of conforming +packages easy at the expense of forcing POSIX threads +clients to protect against multiple simultaneous calls to \fIsigwait\fP() +in application +code in order to achieve predictable behavior. There was concern that +the "all waiting threads" behavior would result in "signal +broadcast storms", consuming excessive CPU resources by replicating +the signals in the general case. Furthermore, no convincing +examples could be presented that delivery to all was either simpler +or more powerful than delivery to one. +.LP +Thus, the consensus was that exactly one thread that was suspended +in a call to a \fIsigwait\fP function for a signal should +return when that signal occurs. This is not an onerous restriction +as: +.IP " *" 3 +A multi-way signal wait can be built from the single-way wait. +.LP +.IP " *" 3 +Signals should only be handled by application-level code, as library +routines cannot guess what the application wants to do with +signals generated for the entire process. +.LP +.IP " *" 3 +Applications can thus arrange for a single thread to wait for any +given signal and call any needed routines upon its +arrival. +.LP +.LP +In an application that is using signals for interprocess communication, +signal processing is typically done in one place. +Alternatively, if the signal is being caught so that process cleanup +can be done, the signal handler thread can call separate +process cleanup routines for each portion of the application. Since +the application main line started each portion of the +application, it is at the right abstraction level to tell each portion +of the application to clean up. +.LP +Certainly, there exist programming styles where it is logical to consider +waiting for a single signal in multiple threads. A +simple \fIsigwait_multiple\fP() routine can be constructed to achieve +this goal. A possible implementation would be to have each +\fIsigwait_multiple\fP() caller registered as having expressed interest +in a set of signals. The caller then waits on a +thread-specific condition variable. A single server thread calls a +\fIsigwait\fP() +function on the union of all registered signals. When the \fIsigwait\fP() +function +returns, the appropriate state is set and condition variables are +broadcast. New \fIsigwait_multiple\fP() callers may cause the +pending \fIsigwait\fP() call to be canceled and reissued in order +to update the set of +signals being waited for. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIRealtime Signals\fP , \fIpause\fP() , \fIpthread_sigmask\fP() , +\fIsigaction\fP() , \fIsigpending\fP() , \fIsigsuspend\fP() , \fIsigwait\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sin.3p b/man3p/sin.3p new file mode 100644 index 000000000..79ce5aed5 --- /dev/null +++ b/man3p/sin.3p @@ -0,0 +1,117 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SIN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sin +.SH NAME +sin, sinf, sinl \- sine function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double sin(double\fP \fIx\fP\fB); +.br +float sinf(float\fP \fIx\fP\fB); +.br +long double sinl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the sine of their argument \fIx\fP, +measured in radians. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the sine +of \fIx\fP. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, \fIx\fP shall be returned. +.LP +If \fIx\fP is subnormal, a range error may occur and \fIx\fP should +be returned. +.LP +If \fIx\fP is \(+-Inf, a domain error shall occur, and either a NaN +(if supported), or an implementation-defined value +shall be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The \fIx\fP argument is \(+-Inf. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be raised. +.sp +.LP +These functions may fail if: +.TP 7 +Range\ Error +The value of \fIx\fP is subnormal +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Taking the Sine of a 45-Degree Angle +.sp +.RS +.nf + +\fB#include +\&... +double radians = 45.0 * M_PI / 180; +double result; +\&... +result = sin(radians); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +These functions may lose accuracy when their argument is near a multiple +of pi or is far +from 0.0. +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIasin\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sinf.3p b/man3p/sinf.3p new file mode 100644 index 000000000..16915109d --- /dev/null +++ b/man3p/sinf.3p @@ -0,0 +1 @@ +.so man3p/sin.3p diff --git a/man3p/sinh.3p b/man3p/sinh.3p new file mode 100644 index 000000000..1726fa4c9 --- /dev/null +++ b/man3p/sinh.3p @@ -0,0 +1,103 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SINH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sinh +.SH NAME +sinh, sinhf, sinhl \- hyperbolic sine functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double sinh(double\fP \fIx\fP\fB); +.br +float sinhf(float\fP \fIx\fP\fB); +.br +long double sinhl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the hyperbolic sine of their argument +\fIx\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the hyperbolic +sine of \fIx\fP. +.LP +If the result would cause an overflow, a range error shall occur and +\(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL +(with the same sign as \fIx\fP) shall be returned as appropriate for +the type of the function. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0 or \(+-Inf, \fIx\fP shall be returned. +.LP +If \fIx\fP is subnormal, a range error may occur and \fIx\fP should +be returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Range\ Error +The result would cause an overflow. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be +raised. +.sp +.LP +These functions may fail if: +.TP 7 +Range\ Error +The value \fIx\fP is subnormal. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIasinh\fP() , \fIcosh\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() +, \fIisnan\fP() , \fItanh\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sinhf.3p b/man3p/sinhf.3p new file mode 100644 index 000000000..20d9a2dd6 --- /dev/null +++ b/man3p/sinhf.3p @@ -0,0 +1 @@ +.so man3p/sinh.3p diff --git a/man3p/sinhl.3p b/man3p/sinhl.3p new file mode 100644 index 000000000..20d9a2dd6 --- /dev/null +++ b/man3p/sinhl.3p @@ -0,0 +1 @@ +.so man3p/sinh.3p diff --git a/man3p/sinl.3p b/man3p/sinl.3p new file mode 100644 index 000000000..16915109d --- /dev/null +++ b/man3p/sinl.3p @@ -0,0 +1 @@ +.so man3p/sin.3p diff --git a/man3p/sleep.3p b/man3p/sleep.3p new file mode 100644 index 000000000..74a5c2a9c --- /dev/null +++ b/man3p/sleep.3p @@ -0,0 +1,159 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SLEEP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sleep +.SH NAME +sleep \- suspend execution for an interval of time +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +unsigned sleep(unsigned\fP \fIseconds\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsleep\fP() function shall cause the calling thread to be suspended +from execution until either the number of realtime +seconds specified by the argument \fIseconds\fP has elapsed or a signal +is delivered to the calling thread and its action is to +invoke a signal-catching function or to terminate the process. The +suspension time may be longer than requested due to the +scheduling of other activity by the system. +.LP +If a SIGALRM signal is generated for the calling process during execution +of \fIsleep\fP() and if the SIGALRM signal is being +ignored or blocked from delivery, it is unspecified whether \fIsleep\fP() +returns when the SIGALRM signal is scheduled. If the +signal is being blocked, it is also unspecified whether it remains +pending after \fIsleep\fP() returns or it is discarded. +.LP +If a SIGALRM signal is generated for the calling process during execution +of \fIsleep\fP(), except as a result of a prior call +to \fIalarm\fP(), and if the SIGALRM signal is not being ignored or +blocked from delivery, +it is unspecified whether that signal has any effect other than causing +\fIsleep\fP() to return. +.LP +If a signal-catching function interrupts \fIsleep\fP() and examines +or changes either the time a SIGALRM is scheduled to be +generated, the action associated with the SIGALRM signal, or whether +the SIGALRM signal is blocked from delivery, the results are +unspecified. +.LP +If a signal-catching function interrupts \fIsleep\fP() and calls \fIsiglongjmp\fP() +or \fIlongjmp\fP() to restore an environment saved prior to the \fIsleep\fP() +call, the +action associated with the SIGALRM signal and the time at which a +SIGALRM signal is scheduled to be generated are unspecified. It +is also unspecified whether the SIGALRM signal is blocked, unless +the process' signal mask is restored as part of the +environment. +.LP +Interactions between \fIsleep\fP() and any of \fIsetitimer\fP(), \fIualarm\fP(), +or \fIusleep\fP() are unspecified. +.SH RETURN VALUE +.LP +If \fIsleep\fP() returns because the requested time has elapsed, the +value returned shall be 0. If \fIsleep\fP() returns due +to delivery of a signal, the return value shall be the "unslept" amount +(the requested time minus the time actually slept) in +seconds. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +There are two general approaches to the implementation of the \fIsleep\fP() +function. One is to use the \fIalarm\fP() function to schedule a SIGALRM +signal and then suspend the process waiting for that +signal. The other is to implement an independent facility. This volume +of IEEE\ Std\ 1003.1-2001 permits either +approach. +.LP +In order to comply with the requirement that no primitive shall change +a process attribute unless explicitly described by this +volume of IEEE\ Std\ 1003.1-2001, an implementation using SIGALRM +must carefully take into account any SIGALRM signal +scheduled by previous \fIalarm\fP() calls, the action previously established +for SIGALRM, +and whether SIGALRM was blocked. If a SIGALRM has been scheduled before +the \fIsleep\fP() would ordinarily complete, the +\fIsleep\fP() must be shortened to that time and a SIGALRM generated +(possibly simulated by direct invocation of the +signal-catching function) before \fIsleep\fP() returns. If a SIGALRM +has been scheduled after the \fIsleep\fP() would ordinarily +complete, it must be rescheduled for the same time before \fIsleep\fP() +returns. The action and blocking for SIGALRM must be saved +and restored. +.LP +Historical implementations often implement the SIGALRM-based version +using \fIalarm\fP() +and \fIpause\fP(). One such implementation is prone to infinite hangups, +as described in \fIpause\fP() . Another such implementation uses the +C-language \fIsetjmp\fP() and \fIlongjmp\fP() functions to avoid that +window. That implementation introduces a different problem: when the +SIGALRM signal interrupts a signal-catching function installed +by the user to catch a different signal, the \fIlongjmp\fP() aborts +that signal-catching +function. An implementation based on \fIsigprocmask\fP(), \fIalarm\fP(), +and \fIsigsuspend\fP() can avoid these +problems. +.LP +Despite all reasonable care, there are several very subtle, but detectable +and unavoidable, differences between the two types of +implementations. These are the cases mentioned in this volume of IEEE\ Std\ 1003.1-2001 +where some other activity relating +to SIGALRM takes place, and the results are stated to be unspecified. +All of these cases are sufficiently unusual as not to be of +concern to most applications. +.LP +See also the discussion of the term \fIrealtime\fP in \fIalarm\fP() +\&. +.LP +Since \fIsleep\fP() can be implemented using \fIalarm\fP(), the discussion +about alarms +occurring early under \fIalarm\fP() applies to \fIsleep\fP() as well. +.LP +Application writers should note that the type of the argument \fIseconds\fP +and the return value of \fIsleep\fP() is +\fBunsigned\fP. That means that a Strictly Conforming POSIX System +Interfaces Application cannot pass a value greater than the +minimum guaranteed value for {UINT_MAX}, which the ISO\ C standard +sets as 65535, and any application passing a larger value is +restricting its portability. A different type was considered, but +historical implementations, including those with a 16-bit +\fBint\fP type, consistently use either \fBunsigned\fP or \fBint\fP. +.LP +Scheduling delays may cause the process to return from the \fIsleep\fP() +function significantly after the requested time. In +such cases, the return value should be set to zero, since the formula +(requested time minus the time actually spent) yields a +negative number and \fIsleep\fP() returns an \fBunsigned\fP. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIalarm\fP() , \fIgetitimer\fP() , \fInanosleep\fP() , \fIpause\fP() +, \fIsigaction\fP() +, \fIsigsetjmp\fP() , \fIualarm\fP() , \fIusleep\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/snprintf.3p b/man3p/snprintf.3p new file mode 100644 index 000000000..b1ca7350d --- /dev/null +++ b/man3p/snprintf.3p @@ -0,0 +1 @@ +.so man3p/printf.3p diff --git a/man3p/sockatmark.3p b/man3p/sockatmark.3p new file mode 100644 index 000000000..5dc136d56 --- /dev/null +++ b/man3p/sockatmark.3p @@ -0,0 +1,117 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SOCKATMARK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sockatmark +.SH NAME +sockatmark \- determine whether a socket is at the out-of-band mark +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int sockatmark(int\fP \fIs\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsockatmark\fP() function shall determine whether the socket +specified by the descriptor \fIs\fP is at the out-of-band +data mark (see the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +Section 2.10.12, Socket Out-of-Band State). If the protocol for the +socket +supports out-of-band data by marking the stream with an out-of-band +data mark, the \fIsockatmark\fP() function shall return 1 when +all data preceding the mark has been read and the out-of-band data +mark is the first element in the receive queue. The +\fIsockatmark\fP() function shall not remove the mark from the stream. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIsockatmark\fP() function shall +return a value indicating whether the socket is at an +out-of-band data mark. If the protocol has marked the data stream +and all data preceding the mark has been read, the return value +shall be 1; if there is no mark, or if data precedes the mark in the +receive queue, the \fIsockatmark\fP() function shall return +0. Otherwise, it shall return a value of -1 and set \fIerrno\fP to +indicate the error. +.SH ERRORS +.LP +The \fIsockatmark\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIs\fP argument is not a valid file descriptor. +.TP 7 +.B ENOTTY +The \fIs\fP argument does not specify a descriptor for a socket. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The use of this function between receive operations allows an application +to determine which received data precedes the +out-of-band data and which follows the out-of-band data. +.LP +There is an inherent race condition in the use of this function. On +an empty receive queue, the current read of the location +might well be at the "mark", but the system has no way of knowing +that the next data segment that will arrive from the network +will carry the mark, and \fIsockatmark\fP() will return false, and +the next read operation will silently consume the mark. +.LP +Hence, this function can only be used reliably when the application +already knows that the out-of-band data has been seen by the +system or that it is known that there is data waiting to be read at +the socket (via SIGURG or \fIselect\fP()). See \fISocket Receive Queue\fP +, \fISocket Out-of-Band Data State\fP , \fISignals\fP , and \fIpselect\fP() +for +details. +.SH RATIONALE +.LP +The \fIsockatmark\fP() function replaces the historical SIOCATMARK +command to \fIioctl\fP() which implemented the same functionality +on many implementations. Using a wrapper +function follows the adopted conventions to avoid specifying commands +to the \fIioctl\fP() +function, other than those now included to support XSI STREAMS. The +\fIsockatmark\fP() function could be implemented as +follows: +.sp +.RS +.nf + +\fB#include +.sp + +int sockatmark(int s) +{ + int val; + if (ioctl(s,SIOCATMARK,&val)==-1) + return(-1); + return(val); +} +\fP +.fi +.RE +.LP +The use of [ENOTTY] to indicate an incorrect descriptor type matches +the historical behavior of SIOCATMARK. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpselect\fP() , \fIrecv\fP() , \fIrecvmsg\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/socket.3p b/man3p/socket.3p new file mode 100644 index 000000000..bf5857ebe --- /dev/null +++ b/man3p/socket.3p @@ -0,0 +1,150 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SOCKET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" socket +.SH NAME +socket \- create an endpoint for communication +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int socket(int\fP \fIdomain\fP\fB, int\fP \fItype\fP\fB, int\fP \fIprotocol\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsocket\fP() function shall create an unbound socket in a communications +domain, and return a file descriptor that can be +used in later function calls that operate on sockets. +.LP +The \fIsocket\fP() function takes the following arguments: +.TP 7 +\fIdomain\fP +Specifies the communications domain in which a socket is to be created. +.TP 7 +\fItype\fP +Specifies the type of socket to be created. +.TP 7 +\fIprotocol\fP +Specifies a particular protocol to be used with the socket. Specifying +a \fIprotocol\fP of 0 causes \fIsocket\fP() to use an +unspecified default protocol appropriate for the requested socket +type. +.sp +.LP +The \fIdomain\fP argument specifies the address family used in the +communications domain. The address families supported by the +system are implementation-defined. +.LP +Symbolic constants that can be used for the domain argument are defined +in the \fI\fP header. +.LP +The \fItype\fP argument specifies the socket type, which determines +the semantics of communication over the socket. The +following socket types are defined; implementations may specify additional +socket types: +.TP 7 +SOCK_STREAM +Provides sequenced, reliable, bidirectional, connection-mode byte +streams, and may provide a transmission mechanism for +out-of-band data. +.TP 7 +SOCK_DGRAM +Provides datagrams, which are connectionless-mode, unreliable messages +of fixed maximum length. +.TP 7 +SOCK_SEQPACKET +Provides sequenced, reliable, bidirectional, connection-mode transmission +paths for records. A record can be sent using one or +more output operations and received using one or more input operations, +but a single operation never transfers part of more than +one record. Record boundaries are visible to the receiver via the +MSG_EOR flag. +.sp +.LP +If the \fIprotocol\fP argument is non-zero, it shall specify a protocol +that is supported by the address family. If the +\fIprotocol\fP argument is zero, the default protocol for this address +family and type shall be used. The protocols supported by +the system are implementation-defined. +.LP +The process may need to have appropriate privileges to use the \fIsocket\fP() +function or to create some sockets. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsocket\fP() shall return a non-negative +integer, the socket file descriptor. Otherwise, a value +of -1 shall be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIsocket\fP() function shall fail if: +.TP 7 +.B EAFNOSUPPORT +.sp +The implementation does not support the specified address family. +.TP 7 +.B EMFILE +No more file descriptors are available for this process. +.TP 7 +.B ENFILE +No more file descriptors are available for the system. +.TP 7 +.B EPROTONOSUPPORT +.sp +The protocol is not supported by the address family, or the protocol +is not supported by the implementation. +.TP 7 +.B EPROTOTYPE +The socket type is not supported by the protocol. +.sp +.LP +The \fIsocket\fP() function may fail if: +.TP 7 +.B EACCES +The process does not have appropriate privileges. +.TP 7 +.B ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP 7 +.B ENOMEM +Insufficient memory was available to fulfill the request. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The documentation for specific address families specifies which protocols +each address family supports. The documentation for +specific protocols specifies which socket types each protocol supports. +.LP +The application can determine whether an address family is supported +by trying to create a socket with \fIdomain\fP set to the +protocol in question. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIaccept\fP() , \fIbind\fP() , \fIconnect\fP() +, \fIgetsockname\fP() , \fIgetsockopt\fP() , \fIlisten\fP() , \fIrecv\fP() +, \fIrecvfrom\fP() , \fIrecvmsg\fP() , \fIsend\fP() , \fIsendmsg\fP() +, \fIsetsockopt\fP() , \fIshutdown\fP() , \fIsocketpair\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/socketpair.3p b/man3p/socketpair.3p new file mode 100644 index 000000000..e7e20d463 --- /dev/null +++ b/man3p/socketpair.3p @@ -0,0 +1,152 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SOCKETPAIR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" socketpair +.SH NAME +socketpair \- create a pair of connected sockets +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int socketpair(int\fP \fIdomain\fP\fB, int\fP \fItype\fP\fB, int\fP +\fIprotocol\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIsocket_vector\fP\fB[2]); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsocketpair\fP() function shall create an unbound pair of connected +sockets in a specified \fIdomain\fP, of a specified +\fItype\fP, under the protocol optionally specified by the \fIprotocol\fP +argument. The two sockets shall be identical. The file +descriptors used in referencing the created sockets shall be returned +in \fIsocket_vector\fP[0] and \fIsocket_vector\fP[1]. +.LP +The \fIsocketpair\fP() function takes the following arguments: +.TP 7 +\fIdomain\fP +Specifies the communications domain in which the sockets are to be +created. +.TP 7 +\fItype\fP +Specifies the type of sockets to be created. +.TP 7 +\fIprotocol\fP +Specifies a particular protocol to be used with the sockets. Specifying +a \fIprotocol\fP of 0 causes \fIsocketpair\fP() to +use an unspecified default protocol appropriate for the requested +socket type. +.TP 7 +\fIsocket_vector\fP +Specifies a 2-integer array to hold the file descriptors of the created +socket pair. +.sp +.LP +The \fItype\fP argument specifies the socket type, which determines +the semantics of communications over the socket. The +following socket types are defined; implementations may specify additional +socket types: +.TP 7 +SOCK_STREAM +Provides sequenced, reliable, bidirectional, connection-mode byte +streams, and may provide a transmission mechanism for +out-of-band data. +.TP 7 +SOCK_DGRAM +Provides datagrams, which are connectionless-mode, unreliable messages +of fixed maximum length. +.TP 7 +SOCK_SEQPACKET +Provides sequenced, reliable, bidirectional, connection-mode transmission +paths for records. A record can be sent using one or +more output operations and received using one or more input operations, +but a single operation never transfers part of more than +one record. Record boundaries are visible to the receiver via the +MSG_EOR flag. +.sp +.LP +If the \fIprotocol\fP argument is non-zero, it shall specify a protocol +that is supported by the address family. If the +\fIprotocol\fP argument is zero, the default protocol for this address +family and type shall be used. The protocols supported by +the system are implementation-defined. +.LP +The process may need to have appropriate privileges to use the \fIsocketpair\fP() +function or to create some sockets. +.SH RETURN VALUE +.LP +Upon successful completion, this function shall return 0; otherwise, +-1 shall be returned and \fIerrno\fP set to indicate the +error. +.SH ERRORS +.LP +The \fIsocketpair\fP() function shall fail if: +.TP 7 +.B EAFNOSUPPORT +.sp +The implementation does not support the specified address family. +.TP 7 +.B EMFILE +No more file descriptors are available for this process. +.TP 7 +.B ENFILE +No more file descriptors are available for the system. +.TP 7 +.B EOPNOTSUPP +The specified protocol does not permit creation of socket pairs. +.TP 7 +.B EPROTONOSUPPORT +.sp +The protocol is not supported by the address family, or the protocol +is not supported by the implementation. +.TP 7 +.B EPROTOTYPE +The socket type is not supported by the protocol. +.sp +.LP +The \fIsocketpair\fP() function may fail if: +.TP 7 +.B EACCES +The process does not have appropriate privileges. +.TP 7 +.B ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP 7 +.B ENOMEM +Insufficient memory was available to fulfill the request. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The documentation for specific address families specifies which protocols +each address family supports. The documentation for +specific protocols specifies which socket types each protocol supports. +.LP +The \fIsocketpair\fP() function is used primarily with UNIX domain +sockets and need not be supported for other domains. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsocket\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sprintf.3p b/man3p/sprintf.3p new file mode 100644 index 000000000..b1ca7350d --- /dev/null +++ b/man3p/sprintf.3p @@ -0,0 +1 @@ +.so man3p/printf.3p diff --git a/man3p/sqrt.3p b/man3p/sqrt.3p new file mode 100644 index 000000000..be7e19025 --- /dev/null +++ b/man3p/sqrt.3p @@ -0,0 +1,101 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SQRT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sqrt +.SH NAME +sqrt, sqrtf, sqrtl \- square root function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double sqrt(double\fP \fIx\fP\fB); +.br +float sqrtf(float\fP \fIx\fP\fB); +.br +long double sqrtl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the square root of their argument \fIx\fP, +sqrt(x). +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the square +root of \fIx\fP. +.LP +For finite values of \fIx\fP < -0, a domain error shall occur, and +\ either a NaN (if supported), or \ an implementation-defined value +shall be returned. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0 or +Inf, \fIx\fP shall be returned. +.LP +If \fIx\fP is -Inf, a domain error shall occur, and either a NaN (if +supported), or an implementation-defined value shall be +returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The finite value of \fIx\fP is < -0, \ or \fIx\fP is -Inf. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Taking the Square Root of 9.0 +.sp +.RS +.nf + +\fB#include +\&... +double x = 9.0; +double result; +\&... +result = sqrt(x); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sqrtf.3p b/man3p/sqrtf.3p new file mode 100644 index 000000000..e21dfb9ba --- /dev/null +++ b/man3p/sqrtf.3p @@ -0,0 +1 @@ +.so man3p/sqrt.3p diff --git a/man3p/sqrtl.3p b/man3p/sqrtl.3p new file mode 100644 index 000000000..e21dfb9ba --- /dev/null +++ b/man3p/sqrtl.3p @@ -0,0 +1 @@ +.so man3p/sqrt.3p diff --git a/man3p/srand.3p b/man3p/srand.3p new file mode 100644 index 000000000..4cebbbb2c --- /dev/null +++ b/man3p/srand.3p @@ -0,0 +1 @@ +.so man3p/rand.3p diff --git a/man3p/srand48.3p b/man3p/srand48.3p new file mode 100644 index 000000000..a71d5ed19 --- /dev/null +++ b/man3p/srand48.3p @@ -0,0 +1 @@ +.so man3p/drand48.3p diff --git a/man3p/srandom.3p b/man3p/srandom.3p new file mode 100644 index 000000000..0f22b822b --- /dev/null +++ b/man3p/srandom.3p @@ -0,0 +1 @@ +.so man3p/random.3p diff --git a/man3p/sscanf.3p b/man3p/sscanf.3p new file mode 100644 index 000000000..0a084c9c9 --- /dev/null +++ b/man3p/sscanf.3p @@ -0,0 +1 @@ +.so man3p/scanf.3p diff --git a/man3p/stat.3p b/man3p/stat.3p new file mode 100644 index 000000000..97df59d86 --- /dev/null +++ b/man3p/stat.3p @@ -0,0 +1,226 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" stat +.SH NAME +stat \- get file status +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int stat(const char *restrict\fP \fIpath\fP\fB, struct stat *restrict\fP +\fIbuf\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstat\fP() function shall obtain information about the named +file and write it to the area pointed to by the \fIbuf\fP +argument. The \fIpath\fP argument points to a pathname naming a file. +Read, write, or execute permission of the named file is not +required. An implementation that provides additional or alternate +file access control mechanisms may, under implementation-defined +conditions, cause \fIstat\fP() to fail. In particular, the system +may deny the existence of the file specified by \fIpath\fP. +.LP +If the named file is a symbolic link, the \fIstat\fP() function shall +continue pathname resolution using the contents of the +symbolic link, and shall return information pertaining to the resulting +file if the file exists. +.LP +The \fIbuf\fP argument is a pointer to a \fBstat\fP structure, as +defined in the \fI\fP header, into which information is +placed concerning the file. +.LP +The \fIstat\fP() function shall update any time-related fields (as +described in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.7, File Times Update), before writing +into the \fBstat\fP structure. +.LP +Unless otherwise specified, the structure members \fIst_mode\fP, \fIst_ino\fP, +\fIst_dev\fP, \fIst_uid\fP, \fIst_gid\fP, +\fIst_atime\fP, \fIst_ctime\fP, and \fIst_mtime\fP shall have meaningful +values for all file types defined in this volume of +IEEE\ Std\ 1003.1-2001. The value of the member \fIst_nlink\fP shall +be set to the number of links to the file. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIstat\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied for a component of the path prefix. +.TP 7 +.B EIO +An error occurred while reading from the file system. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.TP 7 +.B EOVERFLOW +The file size in bytes or the number of blocks allocated to the file +or the file serial number cannot be represented correctly +in the structure pointed to by \fIbuf\fP. +.sp +.LP +The \fIstat\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.TP 7 +.B EOVERFLOW +A value to be stored would overflow one of the members of the \fBstat\fP +structure. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Obtaining File Status Information +.LP +The following example shows how to obtain file status information +for a file named \fB/home/cnd/mod1\fP. The structure variable +\fIbuffer\fP is defined for the \fBstat\fP structure. +.sp +.RS +.nf + +\fB#include +#include +#include +.sp + +struct stat buffer; +int status; +\&... +status = stat("/home/cnd/mod1", &buffer); +\fP +.fi +.RE +.SS Getting Directory Information +.LP +The following example fragment gets status information for each entry +in a directory. The call to the \fIstat\fP() function +stores file information in the \fBstat\fP structure pointed to by +\fIstatbuf\fP. The lines that follow the \fIstat\fP() call +format the fields in the \fBstat\fP structure for presentation to +the user of the program. +.sp +.RS +.nf + +\fB#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +.sp + +struct dirent *dp; +struct stat statbuf; +struct passwd *pwd; +struct group *grp; +struct tm *tm; +char datestring[256]; +\&... +/* Loop through directory entries. */ +while ((dp = readdir(dir)) != NULL) { +.sp + + /* Get entry's information. */ + if (stat(dp->d_name, &statbuf) == -1) + continue; +.sp + + /* Print out type, permissions, and number of links. */ + printf("%10.10s", sperm (statbuf.st_mode)); + printf("%4d", statbuf.st_nlink); +.sp + + /* Print out owner's name if it is found using getpwuid(). */ + if ((pwd = getpwuid(statbuf.st_uid)) != NULL) + printf(" %-8.8s", pwd->pw_name); + else + printf(" %-8d", statbuf.st_uid); +.sp + + /* Print out group name if it is found using getgrgid(). */ + if ((grp = getgrgid(statbuf.st_gid)) != NULL) + printf(" %-8.8s", grp->gr_name); + else + printf(" %-8d", statbuf.st_gid); +.sp + + /* Print size of file. */ + printf(" %9jd", (intmax_t)statbuf.st_size); +.sp + + tm = localtime(&statbuf.st_mtime); +.sp + + /* Get localized date string. */ + strftime(datestring, sizeof(datestring), nl_langinfo(D_T_FMT), tm); +.sp + + printf(" %s %s\\n", datestring, dp->d_name); +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The intent of the paragraph describing "additional or alternate file +access control mechanisms" is to allow a secure +implementation where a process with a label that does not dominate +the file's label cannot perform a \fIstat\fP() function. This +is not related to read permission; a process with a label that dominates +the file's label does not need read permission. An +implementation that supports write-up operations could fail \fIfstat\fP() +function calls +even though it has a valid file descriptor open for writing. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfstat\fP() , \fIlstat\fP() , \fIreadlink\fP() , \fIsymlink\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/statvfs.3p b/man3p/statvfs.3p new file mode 100644 index 000000000..cb7d2656a --- /dev/null +++ b/man3p/statvfs.3p @@ -0,0 +1,169 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FSTATVFS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fstatvfs +.SH NAME +fstatvfs, statvfs \- get file system information +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int fstatvfs(int\fP \fIfildes\fP\fB, struct statvfs *\fP\fIbuf\fP\fB); +.br +int statvfs(const char *restrict\fP \fIpath\fP\fB, struct statvfs +*restrict\fP \fIbuf\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIfstatvfs\fP() function shall obtain information about the file +system containing the file referenced by +\fIfildes\fP. +.LP +The \fIstatvfs\fP() function shall obtain information about the file +system containing the file named by \fIpath\fP. +.LP +For both functions, the \fIbuf\fP argument is a pointer to a \fBstatvfs\fP +structure that shall be filled. Read, write, or +execute permission of the named file is not required. +.LP +The following flags can be returned in the \fIf_flag\fP member: +.TP 7 +ST_RDONLY +Read-only file system. +.TP 7 +ST_NOSUID +Setuid/setgid bits ignored by \fIexec\fP. +.sp +.LP +It is unspecified whether all members of the \fBstatvfs\fP structure +have meaningful values on all file systems. +.SH RETURN VALUE +.LP +Upon successful completion, \fIstatvfs\fP() shall return 0. Otherwise, +it shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fIfstatvfs\fP() and \fIstatvfs\fP() functions shall fail if: +.TP 7 +.B EIO +An I/O error occurred while reading the file system. +.TP 7 +.B EINTR +A signal was caught during execution of the function. +.TP 7 +.B EOVERFLOW +One of the values to be returned cannot be represented correctly in +the structure pointed to by \fIbuf\fP. +.sp +.LP +The \fIfstatvfs\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not an open file descriptor. +.sp +.LP +The \fIstatvfs\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied on a component of the path prefix. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of a pathname exceeds {PATH_MAX} or a pathname component +is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix of \fIpath\fP is not a directory. +.sp +.LP +The \fIstatvfs\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Obtaining File System Information Using fstatvfs() +.LP +The following example shows how to obtain file system information +for the file system upon which the file named +\fB/home/cnd/mod1\fP resides, using the \fIfstatvfs\fP() function. +The \fB/home/cnd/mod1\fP file is opened with read/write +privileges and the open file descriptor is passed to the \fIfstatvfs\fP() +function. +.sp +.RS +.nf + +\fB#include +#include +.sp + +struct statvfs buffer; +int status; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +status = fstatvfs(fildes, &buffer); +\fP +.fi +.RE +.SS Obtaining File System Information Using statvfs() +.LP +The following example shows how to obtain file system information +for the file system upon which the file named +\fB/home/cnd/mod1\fP resides, using the \fIstatvfs\fP() function. +.sp +.RS +.nf + +\fB#include +.sp + +struct statvfs buffer; +int status; +\&... +status = statvfs("/home/cnd/mod1", &buffer); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchmod\fP() , \fIchown\fP() , \fIcreat\fP() , \fIdup\fP() , \fIexec\fP() +, \fIfcntl\fP() , \fIlink\fP() , \fImknod\fP() , \fIopen\fP() , \fIpipe\fP() +, \fIread\fP() , \fItime\fP() , \fIunlink\fP() , \fIutime\fP() , \fIwrite\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/stderr.3p b/man3p/stderr.3p new file mode 100644 index 000000000..ce7d4f1af --- /dev/null +++ b/man3p/stderr.3p @@ -0,0 +1 @@ +.so man3p/stdin.3p diff --git a/man3p/stdin.3p b/man3p/stdin.3p new file mode 100644 index 000000000..6f9ed9a4d --- /dev/null +++ b/man3p/stdin.3p @@ -0,0 +1,87 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STDIN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" stdin +.SH NAME +stderr, stdin, stdout \- standard I/O streams +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +extern FILE *stderr, *stdin, *stdout; +.br +\fP +.SH DESCRIPTION +.LP +A file with associated buffering is called a \fIstream\fP and is declared +to be a pointer to a defined type \fBFILE\fP. The \fIfopen\fP() function +shall create certain descriptive data for a stream and return a pointer +to designate the stream in all further transactions. Normally, there +are three open streams with constant pointers declared in the +\fI\fP header and associated with the standard open files. +.LP +At program start-up, three streams shall be predefined and need not +be opened explicitly: \fIstandard input\fP (for reading +conventional input), \fIstandard output\fP (for writing conventional +output), and \fIstandard error\fP (for writing diagnostic +output). When opened, the standard error stream is not fully buffered; +the standard input and standard output streams are fully +buffered if and only if the stream can be determined not to refer +to an interactive device. +.LP +The +following symbolic values in \fI\fP define the file descriptors +that shall +be associated with the C-language \fIstdin\fP, \fIstdout\fP, and \fIstderr\fP +when the application is started: +.TP 7 +STDIN_FILENO +Standard input value, \fIstdin\fP. Its value is 0. +.TP 7 +STDOUT_FILENO +Standard output value, \fIstdout\fP. Its value is 1. +.TP 7 +STDERR_FILENO +Standard error value, \fIstderr\fP. Its value is 2. +.sp +.LP +The \fIstderr\fP stream is expected to be open for reading and writing. +.SH RETURN VALUE +.LP +None. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfclose\fP() , \fIfeof\fP() , \fIferror\fP() , +\fIfileno\fP() , \fIfopen\fP() , \fIfread\fP() , \fIfseek\fP() , \fIgetc\fP() +, \fIgets\fP() , \fIpopen\fP() , \fIprintf\fP() , \fIputc\fP() , \fIputs\fP() +, \fIread\fP() , \fIscanf\fP() , \fIsetbuf\fP() , \fIsetvbuf\fP() +, \fItmpfile\fP() , \fIungetc\fP() , \fIvprintf\fP() , the Base Definitions +volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/stdout.3p b/man3p/stdout.3p new file mode 100644 index 000000000..ce7d4f1af --- /dev/null +++ b/man3p/stdout.3p @@ -0,0 +1 @@ +.so man3p/stdin.3p diff --git a/man3p/strcasecmp.3p b/man3p/strcasecmp.3p new file mode 100644 index 000000000..1f9514e5d --- /dev/null +++ b/man3p/strcasecmp.3p @@ -0,0 +1,72 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRCASECMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strcasecmp +.SH NAME +strcasecmp, strncasecmp \- case-insensitive string comparisons +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int strcasecmp(const char *\fP\fIs1\fP\fB, const char *\fP\fIs2\fP\fB); +.br +int strncasecmp(const char *\fP\fIs1\fP\fB, const char *\fP\fIs2\fP\fB, +size_t\fP \fIn\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrcasecmp\fP() function shall compare, while ignoring differences +in case, the string pointed to by \fIs1\fP to the +string pointed to by \fIs2\fP. The \fIstrncasecmp\fP() function shall +compare, while ignoring differences in case, not more than +\fIn\fP bytes from the string pointed to by \fIs1\fP to the string +pointed to by \fIs2\fP. +.LP +In the POSIX locale, \fIstrcasecmp\fP() and \fIstrncasecmp\fP() shall +behave as if the strings had been converted to lowercase +and then a byte comparison performed. The results are unspecified +in other locales. +.SH RETURN VALUE +.LP +Upon completion, \fIstrcasecmp\fP() shall return an integer greater +than, equal to, or less than 0, if the string pointed to by +\fIs1\fP is, ignoring case, greater than, equal to, or less than the +string pointed to by \fIs2\fP, respectively. +.LP +Upon successful completion, \fIstrncasecmp\fP() shall return an integer +greater than, equal to, or less than 0, if the possibly +null-terminated array pointed to by \fIs1\fP is, ignoring case, greater +than, equal to, or less than the possibly null-terminated +array pointed to by \fIs2\fP, respectively. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strcat.3p b/man3p/strcat.3p new file mode 100644 index 000000000..4f4a1710b --- /dev/null +++ b/man3p/strcat.3p @@ -0,0 +1,59 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRCAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strcat +.SH NAME +strcat \- concatenate two strings +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *strcat(char *restrict\fP \fIs1\fP\fB, const char *restrict\fP +\fIs2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrcat\fP() function shall append a copy of the string pointed +to by \fIs2\fP (including the terminating null byte) to +the end of the string pointed to by \fIs1\fP. The initial byte of +\fIs2\fP overwrites the null byte at the end of \fIs1\fP. If +copying takes place between objects that overlap, the behavior is +undefined. +.SH RETURN VALUE +.LP +The \fIstrcat\fP() function shall return \fIs1\fP; no return value +is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +This issue is aligned with the ISO\ C standard; this does not affect +compatibility with XPG3 applications. Reliable error +detection by this function was never guaranteed. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrncat\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strchr.3p b/man3p/strchr.3p new file mode 100644 index 000000000..c6cec819b --- /dev/null +++ b/man3p/strchr.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRCHR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strchr +.SH NAME +strchr \- string scanning operation +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *strchr(const char *\fP\fIs\fP\fB, int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrchr\fP() function shall locate the first occurrence of \fIc\fP +(converted to a \fBchar\fP) in the string pointed to +by \fIs\fP. The terminating null byte is considered to be part of +the string. +.SH RETURN VALUE +.LP +Upon completion, \fIstrchr\fP() shall return a pointer to the byte, +or a null pointer if the byte was not found. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrrchr\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strcmp.3p b/man3p/strcmp.3p new file mode 100644 index 000000000..0f082174c --- /dev/null +++ b/man3p/strcmp.3p @@ -0,0 +1,100 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRCMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strcmp +.SH NAME +strcmp \- compare two strings +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int strcmp(const char *\fP\fIs1\fP\fB, const char *\fP\fIs2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrcmp\fP() function shall compare the string pointed to by +\fIs1\fP to the string pointed to by \fIs2\fP. +.LP +The sign of a non-zero return value shall be determined by the sign +of the difference between the values of the first pair of +bytes (both interpreted as type \fBunsigned char\fP) that differ in +the strings being compared. +.SH RETURN VALUE +.LP +Upon completion, \fIstrcmp\fP() shall return an integer greater than, +equal to, or less than 0, if the string pointed to by +\fIs1\fP is greater than, equal to, or less than the string pointed +to by \fIs2\fP, respectively. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Checking a Password Entry +.LP +The following example compares the information read from standard +input to the value of the name of the user entry. If the +\fIstrcmp\fP() function returns 0 (indicating a match), a further +check will be made to see if the user entered the proper old +password. The \fIcrypt\fP() function shall encrypt the old password +entered by the user, +using the value of the encrypted password in the \fBpasswd\fP structure +as the salt. If this value matches the value of the +encrypted \fBpasswd\fP in the structure, the entered password \fIoldpasswd\fP +is the correct user's password. Finally, the +program encrypts the new password so that it can store the information +in the \fBpasswd\fP structure. +.sp +.RS +.nf + +\fB#include +#include +#include +\&... +int valid_change; +struct passwd *p; +char user[100]; +char oldpasswd[100]; +char newpasswd[100]; +char savepasswd[100]; +\&... +if (strcmp(p->pw_name, user) == 0) { + if (strcmp(p->pw_passwd, crypt(oldpasswd, p->pw_passwd)) == 0) { + strcpy(savepasswd, crypt(newpasswd, user)); + p->pw_passwd = savepasswd; + valid_change = 1; + } + else { + fprintf(stderr, "Old password is not valid\\n"); + } +} +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrncmp\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strcoll.3p b/man3p/strcoll.3p new file mode 100644 index 000000000..75b7f6a97 --- /dev/null +++ b/man3p/strcoll.3p @@ -0,0 +1,96 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRCOLL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strcoll +.SH NAME +strcoll \- string comparison using collating information +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int strcoll(const char *\fP\fIs1\fP\fB, const char *\fP\fIs2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrcoll\fP() function shall compare the string pointed to by +\fIs1\fP to the string pointed to by \fIs2\fP, both +interpreted as appropriate to the \fILC_COLLATE\fP category of the +current locale. +.LP +The +\fIstrcoll\fP() function shall not change the setting of \fIerrno\fP +if successful. +.LP +Since no return value is reserved to indicate an error, an application +wishing to check for error situations should set +\fIerrno\fP to 0, then call \fIstrcoll\fP(), then check \fIerrno\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIstrcoll\fP() shall return an integer +greater than, equal to, or less than 0, according to +whether the string pointed to by \fIs1\fP is greater than, equal to, +or less than the string pointed to by \fIs2\fP when both are +interpreted as appropriate to the current locale. \ On error, \fIstrcoll\fP() +may set \fIerrno\fP, but no return +value is reserved to indicate an error. +.SH ERRORS +.LP +The \fIstrcoll\fP() function may fail if: +.TP 7 +.B EINVAL +The \fIs1\fP or \fIs2\fP arguments contain characters outside the +domain of the collating sequence. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Comparing Nodes +.LP +The following example uses an application-defined function, \fInode_compare\fP(), +to compare two nodes based on an alphabetical +ordering of the \fIstring\fP field. +.sp +.RS +.nf + +\fB#include +\&... +struct node { /* These are stored in the table. */ + char *string; + int length; +}; +\&... +int node_compare(const void *node1, const void *node2) +{ + return strcoll(((const struct node *)node1)->string, + ((const struct node *)node2)->string); +} +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIstrxfrm\fP() and \fIstrcmp\fP() +functions should be used for sorting large lists. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrcmp\fP() , \fIstrxfrm\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strcpy.3p b/man3p/strcpy.3p new file mode 100644 index 000000000..f85585a8a --- /dev/null +++ b/man3p/strcpy.3p @@ -0,0 +1,119 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRCPY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strcpy +.SH NAME +strcpy \- copy a string +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *strcpy(char *restrict\fP \fIs1\fP\fB, const char *restrict\fP +\fIs2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrcpy\fP() function shall copy the string pointed to by \fIs2\fP +(including the terminating null byte) into the array +pointed to by \fIs1\fP. If copying takes place between objects that +overlap, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIstrcpy\fP() function shall return \fIs1\fP; no return value +is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Initializing a String +.LP +The following example copies the string \fB"----------"\fP into the +\fIpermstring\fP variable. +.sp +.RS +.nf + +\fB#include +\&... +static char permstring[11]; +\&... +strcpy(permstring, "----------"); +\&... +\fP +.fi +.RE +.SS Storing a Key and Data +.LP +The following example allocates space for a key using \fImalloc\fP() +then uses +\fIstrcpy\fP() to place the key there. Then it allocates space for +data using \fImalloc\fP(), and uses \fIstrcpy\fP() to place data there. +(The user-defined function +\fIdbfree\fP() frees memory previously allocated to an array of type +\fBstruct element *\fP.) +.sp +.RS +.nf + +\fB#include +#include +#include +\&... +/* Structure used to read data and store it. */ +struct element { + char *key; + char *data; +}; +.sp + +struct element *tbl, *curtbl; +char *key, *data; +int count; +\&... +void dbfree(struct element *, int); +\&... +if ((curtbl->key = malloc(strlen(key) + 1)) == NULL) { + perror("malloc"); dbfree(tbl, count); return NULL; +} +strcpy(curtbl->key, key); +.sp + +if ((curtbl->data = malloc(strlen(data) + 1)) == NULL) { + perror("malloc"); free(curtbl->key); dbfree(tbl, count); return NULL; +} +strcpy(curtbl->data, data); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +Character movement is performed differently in different implementations. +Thus, overlapping moves may yield surprises. +.LP +This issue is aligned with the ISO\ C standard; this does not affect +compatibility with XPG3 applications. Reliable error +detection by this function was never guaranteed. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrncpy\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strcspn.3p b/man3p/strcspn.3p new file mode 100644 index 000000000..89a3a2dce --- /dev/null +++ b/man3p/strcspn.3p @@ -0,0 +1,55 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRCSPN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strcspn +.SH NAME +strcspn \- get the length of a complementary substring +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t strcspn(const char *\fP\fIs1\fP\fB, const char *\fP\fIs2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrcspn\fP() function shall compute the length (in bytes) of +the maximum initial segment of the string pointed to by +\fIs1\fP which consists entirely of bytes \fInot\fP from the string +pointed to by \fIs2\fP. +.SH RETURN VALUE +.LP +The \fIstrcspn\fP() function shall return the length of the computed +segment of the string pointed to by \fIs1\fP; no return +value is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrspn\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strdup.3p b/man3p/strdup.3p new file mode 100644 index 000000000..5ed67eb25 --- /dev/null +++ b/man3p/strdup.3p @@ -0,0 +1,61 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRDUP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strdup +.SH NAME +strdup \- duplicate a string +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *strdup(const char *\fP\fIs1\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrdup\fP() function shall return a pointer to a new string, +which is a duplicate of the string pointed to by \fIs1\fP. +The returned pointer can be passed to \fIfree\fP(). A null pointer +is returned if the new +string cannot be created. +.SH RETURN VALUE +.LP +The \fIstrdup\fP() function shall return a pointer to a new string +on success. Otherwise, it shall return a null pointer and +set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fIstrdup\fP() function may fail if: +.TP 7 +.B ENOMEM +Storage space available is insufficient. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfree\fP() , \fImalloc\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strerror.3p b/man3p/strerror.3p new file mode 100644 index 000000000..78b5b6df7 --- /dev/null +++ b/man3p/strerror.3p @@ -0,0 +1,113 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRERROR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strerror +.SH NAME +strerror, strerror_r \- get error message string +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *strerror(int\fP \fIerrnum\fP\fB); +.br +\fP +.LP +\fBint strerror_r(int\fP \fIerrnum\fP\fB, char *\fP\fIstrerrbuf\fP\fB, +size_t\fP +\fIbuflen\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +For \fIstrerror\fP(): The functionality described on this reference +page is aligned with the ISO\ C standard. Any +conflict between the requirements described here and the ISO\ C standard +is unintentional. This volume of +IEEE\ Std\ 1003.1-2001 defers to the ISO\ C standard. +.LP +The \fIstrerror\fP() function shall map the error number in \fIerrnum\fP +to a locale-dependent error message string and shall +return a pointer to it. Typically, the values for \fIerrnum\fP come +from \fIerrno\fP, but \fIstrerror\fP() shall map any value +of type \fBint\fP to a message. +.LP +The string pointed to shall not be modified by the application, but +may be overwritten by a subsequent call to \fIstrerror\fP() +\ or \fIperror\fP(). +.LP +The +contents of the error message strings returned by \fIstrerror\fP() +should be determined by the setting of the \fILC_MESSAGES\fP +category in the current locale. +.LP +The implementation shall behave as if no function defined in this +volume of IEEE\ Std\ 1003.1-2001 calls +\fIstrerror\fP(). +.LP +The +\fIstrerror\fP() function shall not change the setting of \fIerrno\fP +if successful. +.LP +Since no return value is reserved to indicate an error, an application +wishing to check for error situations should set +\fIerrno\fP to 0, then call \fIstrerror\fP(), then check \fIerrno\fP. +.LP +The \fIstrerror\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.LP +The \fIstrerror_r\fP() function shall map the error number in \fIerrnum\fP +to a locale-dependent error message string and shall +return the string in the buffer pointed to by \fIstrerrbuf\fP, with +length \fIbuflen\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIstrerror\fP() shall return a pointer +to the generated message string. On error \fIerrno\fP may +be set, but no return value is reserved to indicate an error. +.LP +Upon successful completion, \fIstrerror_r\fP() shall return 0. Otherwise, +an error number shall be returned to indicate the error. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +.B EINVAL +The value of \fIerrnum\fP is not a valid error number. +.sp +.LP +The \fIstrerror_r\fP() function may fail if: +.TP 7 +.B ERANGE +Insufficient storage was supplied via \fIstrerrbuf\fP and \fIbuflen\fP +to contain the generated message string. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIperror\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strerror_r.3p b/man3p/strerror_r.3p new file mode 100644 index 000000000..d1f57d736 --- /dev/null +++ b/man3p/strerror_r.3p @@ -0,0 +1 @@ +.so man3p/strerror.3p diff --git a/man3p/strfmon.3p b/man3p/strfmon.3p new file mode 100644 index 000000000..15e718ef8 --- /dev/null +++ b/man3p/strfmon.3p @@ -0,0 +1,283 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRFMON" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strfmon +.SH NAME +strfmon \- convert monetary value to a string +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +ssize_t strfmon(char *restrict\fP \fIs\fP\fB, size_t\fP \fImaxsize\fP\fB, +.br +\ \ \ \ \ \ const char *restrict\fP \fIformat\fP\fB, ...); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrfmon\fP() function shall place characters into the array +pointed to by \fIs\fP as controlled by the string pointed +to by \fIformat\fP. No more than \fImaxsize\fP bytes are placed into +the array. +.LP +The format is a character string, beginning and ending in its initial +state, if any, that contains two types of objects: +\fIplain characters\fP, which are simply copied to the output stream, +and \fIconversion specifications\fP, each of which shall +result in the fetching of zero or more arguments which are converted +and formatted. The results are undefined if there are +insufficient arguments for the format. If the format is exhausted +while arguments remain, the excess arguments are simply +ignored. +.LP +The application shall ensure that a conversion specification consists +of the following sequence: +.IP " *" 3 +A \fB'%'\fP character +.LP +.IP " *" 3 +Optional flags +.LP +.IP " *" 3 +Optional field width +.LP +.IP " *" 3 +Optional left precision +.LP +.IP " *" 3 +Optional right precision +.LP +.IP " *" 3 +A required conversion specifier character that determines the conversion +to be performed +.LP +.SS Flags +.LP +One or more of the following optional flags can be specified to control +the conversion: +.TP 7 +\fB=\fP\fIf\fP +An \fB'='\fP followed by a single character \fIf\fP which is used +as the numeric fill character. In order to work with +precision or width counts, the fill character shall be a single byte +character; if not, the behavior is undefined. The default +numeric fill character is the . This flag does not affect field +width filling which always uses the . +This flag is ignored unless a left precision (see below) is specified. +.TP 7 +\fB^\fP +Do not format the currency amount with grouping characters. The default +is to insert the grouping characters if defined for the +current locale. +.TP 7 +\fB+\fP\ or\ \fB(\fP +Specify the style of representing positive and negative currency amounts. +Only one of \fB'+'\fP or \fB'('\fP may be +specified. If \fB'+'\fP is specified, the locale's equivalent of \fB'+'\fP +and \fB'-'\fP are used (for example, in the +U.S., the empty string if positive and \fB'-'\fP if negative). If +\fB'('\fP is specified, negative amounts are enclosed +within parentheses. If neither flag is specified, the \fB'+'\fP style +is used. +.TP 7 +\fB!\fP +Suppress the currency symbol from the output conversion. +.TP 7 +\fB-\fP +Specify the alignment. If this flag is present the result of the conversion +is left-justified (padded to the right) rather than +right-justified. This flag shall be ignored unless a field width (see +below) is specified. +.sp +.SS Field Width +.TP 7 +\fIw\fP +A decimal digit string \fIw\fP specifying a minimum field width in +bytes in which the result of the conversion is +right-justified (or left-justified if the flag \fB'-'\fP is specified). +The default is 0. +.sp +.SS Left Precision +.TP 7 +\fB#\fP\fIn\fP +A \fB'#'\fP followed by a decimal digit string \fIn\fP specifying +a maximum number of digits expected to be formatted to +the left of the radix character. This option can be used to keep the +formatted output from multiple calls to the \fIstrfmon\fP() +function aligned in the same columns. It can also be used to fill +unused positions with a special character as in +\fB"$***123.45"\fP . This option causes an amount to be formatted +as if it has the number of digits specified by \fIn\fP. If +more than \fIn\fP digit positions are required, this conversion specification +is ignored. Digit positions in excess of those +actually required are filled with the numeric fill character (see +the \fB=\fP\fIf\fP flag above). +.LP +If grouping has not been suppressed with the \fB'^'\fP flag, and it +is defined for the current locale, grouping separators +are inserted before the fill characters (if any) are added. Grouping +separators are not applied to fill characters even if the fill +character is a digit. +.LP +To ensure alignment, any characters appearing before or after the +number in the formatted output such as currency or sign +symbols are padded as necessary with s to make their positive +and negative formats an equal length. +.sp +.SS Right Precision +.TP 7 +\fB\&.\fP\fIp\fP +A period followed by a decimal digit string \fIp\fP specifying the +number of digits after the radix character. If the value of +the right precision \fIp\fP is 0, no radix character appears. If a +right precision is not included, a default specified by the +current locale is used. The amount being formatted is rounded to the +specified number of digits prior to formatting. +.sp +.SS Conversion Specifier Characters +.LP +The conversion specifier characters and their meanings are: +.TP 7 +\fBi\fP +The \fBdouble\fP argument is formatted according to the locale's international +currency format (for example, in the U.S.: USD +1,234.56). If the argument is \(+-Inf or NaN, the result of the conversion +is unspecified. +.TP 7 +\fBn\fP +The \fBdouble\fP argument is formatted according to the locale's national +currency format (for example, in the U.S.: +$1,234.56). If the argument is \(+-Inf or NaN, the result of the conversion +is unspecified. +.TP 7 +\fB%\fP +Convert to a \fB'%'\fP ; no argument is converted. The entire conversion +specification shall be \fB%%\fP . +.sp +.SS Locale Information +.LP +The \fILC_MONETARY\fP category of the program's locale affects the +behavior of this function including the monetary radix +character (which may be different from the numeric radix character +affected by the \fILC_NUMERIC\fP category), the grouping +separator, the currency symbols, and formats. The international currency +symbol should be conformant with the ISO\ 4217:1995 +standard. +.LP +If the value of \fImaxsize\fP is greater than {SSIZE_MAX}, the result +is implementation-defined. +.SH RETURN VALUE +.LP +If the total number of resulting bytes including the terminating null +byte is not more than \fImaxsize\fP, \fIstrfmon\fP() +shall return the number of bytes placed into the array pointed to +by \fIs\fP, not including the terminating null byte. Otherwise, +-1 shall be returned, the contents of the array are unspecified, and +\fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +The \fIstrfmon\fP() function shall fail if: +.TP 7 +.B E2BIG +Conversion stopped due to lack of space in the buffer. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +Given a locale for the U.S. and the values 123.45, -123.45, and 3456.781, +the following output might be produced. Square +brackets ( \fB"[]"\fP ) are used in this example to delimit the output. +.sp +.RS +.nf + +\fB%n [$123.45] \fP Default formatting +\fB [-$123.45] + [$3,456.78] +.sp + +%11n [ $123.45] \fP Right align within an 11-character field +\fB [ -$123.45] + [ $3,456.78] +.sp + +%#5n [ $ 123.45] \fP Aligned columns for values up to 99999 +\fB [-$ 123.45] + [ $ 3,456.78] +.sp + +%=*#5n [ $***123.45] \fP Specify a fill character +\fB [-$***123.45] + [ $*3,456.78] +.sp + +%=0#5n [ $000123.45] \fP Fill characters do not use grouping +\fB [-$000123.45] \fP even if the fill character is a digit +\fB [ $03,456.78] +.sp + +%^#5n [ $ 123.45] \fP Disable the grouping separator +\fB [-$ 123.45] + [ $ 3456.78] +.sp + +%^#5.0n [ $ 123] \fP Round off to whole units +\fB [-$ 123] + [ $ 3457] +.sp + +%^#5.4n [ $ 123.4500] \fP Increase the precision +\fB [-$ 123.4500] + [ $ 3456.7810] +.sp + +%(#5n [$ 123.45] \fP Use an alternative pos/neg style +\fB [($ 123.45)] + [$ 3,456.78] +.sp + +%!(#5n [ 123.45] \fP Disable the currency symbol +\fB [( 123.45)] + [ 3,456.78] +.sp + +%-14#5.4n [ $ 123.4500 ] \fP Left-justify the output +\fB [-$ 123.4500 ] + [ $ 3,456.7810 ] +.sp + +%14#5.4n [ $ 123.4500] \fP Corresponding right-justified output +\fB [ -$ 123.4500] + [ $ 3,456.7810] +\fP +.fi +.RE +.LP +See also the EXAMPLES section in \fIfprintf\fP(). +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +Lowercase conversion characters are reserved for future standards +use and uppercase for implementation-defined use. +.SH SEE ALSO +.LP +\fIfprintf\fP() , \fIlocaleconv\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strftime.3p b/man3p/strftime.3p new file mode 100644 index 000000000..3b30c610e --- /dev/null +++ b/man3p/strftime.3p @@ -0,0 +1,429 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRFTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strftime +.SH NAME +strftime \- convert date and time to a string +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t strftime(char *restrict\fP \fIs\fP\fB, size_t\fP \fImaxsize\fP\fB, +.br +\ \ \ \ \ \ const char *restrict\fP \fIformat\fP\fB, const struct +tm *restrict\fP +\fItimeptr\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrftime\fP() function shall place bytes into the array pointed +to by \fIs\fP as controlled by the string pointed to by +\fIformat\fP. The format is a character string, beginning and ending +in its initial shift state, if any. The \fIformat\fP string +consists of zero or more conversion specifications and ordinary characters. +A conversion specification consists of a \fB'%'\fP +character, possibly followed by an \fBE\fP or \fBO\fP modifier, and +a terminating conversion specifier character that +determines the conversion specification's behavior. All ordinary characters +(including the terminating null byte) are copied +unchanged into the array. If copying takes place between objects that +overlap, the behavior is undefined. No more than +\fImaxsize\fP bytes are placed into the array. Each conversion specifier +is replaced by appropriate characters as described in the +following list. The appropriate characters are determined using the +\fILC_TIME\fP category of the current locale and by the values +of zero or more members of the broken-down time structure pointed +to by \fItimeptr\fP, as specified in brackets in the +description. If any of the specified values are outside the normal +range, the characters stored are unspecified. +.LP +Local timezone information is used as though \fIstrftime\fP() called +\fItzset\fP(). +.LP +The following conversion specifications are supported: +.TP 7 +\fB%a\fP +Replaced by the locale's abbreviated weekday name. [ \fItm_wday\fP] +.TP 7 +\fB%A\fP +Replaced by the locale's full weekday name. [ \fItm_wday\fP] +.TP 7 +\fB%b\fP +Replaced by the locale's abbreviated month name. [ \fItm_mon\fP] +.TP 7 +\fB%B\fP +Replaced by the locale's full month name. [ \fItm_mon\fP] +.TP 7 +\fB%c\fP +Replaced by the locale's appropriate date and time representation. +(See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP.) +.TP 7 +\fB%C\fP +Replaced by the year divided by 100 and truncated to an integer, as +a decimal number [00,99]. [ \fItm_year\fP] +.TP 7 +\fB%d\fP +Replaced by the day of the month as a decimal number [01,31]. [ \fItm_mday\fP] +.TP 7 +\fB%D\fP +Equivalent to \fB%m\fP / \fB%d\fP / \fB%y\fP . [ \fItm_mon\fP, \fItm_mday\fP, +\fItm_year\fP] +.TP 7 +\fB%e\fP +Replaced by the day of the month as a decimal number [1,31]; a single +digit is preceded by a space. [ \fItm_mday\fP] +.TP 7 +\fB%F\fP +Equivalent to \fB%Y\fP - \fB%m\fP - \fB%d\fP (the ISO\ 8601:2000 standard +date format). [ \fItm_year\fP, +\fItm_mon\fP, \fItm_mday\fP] +.TP 7 +\fB%g\fP +Replaced by the last 2 digits of the week-based year (see below) as +a decimal number [00,99]. [ \fItm_year\fP, \fItm_wday\fP, +\fItm_yday\fP] +.TP 7 +\fB%G\fP +Replaced by the week-based year (see below) as a decimal number (for +example, 1977). [ \fItm_year\fP, \fItm_wday\fP, +\fItm_yday\fP] +.TP 7 +\fB%h\fP +Equivalent to \fB%b\fP . [ \fItm_mon\fP] +.TP 7 +\fB%H\fP +Replaced by the hour (24-hour clock) as a decimal number [00,23]. +[ \fItm_hour\fP] +.TP 7 +\fB%I\fP +Replaced by the hour (12-hour clock) as a decimal number [01,12]. +[ \fItm_hour\fP] +.TP 7 +\fB%j\fP +Replaced by the day of the year as a decimal number [001,366]. [ \fItm_yday\fP] +.TP 7 +\fB%m\fP +Replaced by the month as a decimal number [01,12]. [ \fItm_mon\fP] +.TP 7 +\fB%M\fP +Replaced by the minute as a decimal number [00,59]. [ \fItm_min\fP] +.TP 7 +\fB%n\fP +Replaced by a . +.TP 7 +\fB%p\fP +Replaced by the locale's equivalent of either a.m. or p.m. [ \fItm_hour\fP] +.TP 7 +\fB%r\fP +Replaced by the time in a.m. and p.m. notation; \ in the POSIX locale +this shall be equivalent to \fB%I\fP : +\fB%M\fP : \fB%S\fP \fB%p\fP . [ \fItm_hour\fP, +\fItm_min\fP, \fItm_sec\fP] +.TP 7 +\fB%R\fP +Replaced by the time in 24-hour notation ( \fB%H\fP : \fB%M\fP ). +[ \fItm_hour\fP, \fItm_min\fP] +.TP 7 +\fB%S\fP +Replaced by the second as a decimal number [00,60]. [ \fItm_sec\fP] +.TP 7 +\fB%t\fP +Replaced by a . +.TP 7 +\fB%T\fP +Replaced by the time ( \fB%H\fP : \fB%M\fP : \fB%S\fP ). [ \fItm_hour\fP, +\fItm_min\fP, \fItm_sec\fP] +.TP 7 +\fB%u\fP +Replaced by the weekday as a decimal number [1,7], with 1 representing +Monday. [ \fItm_wday\fP] +.TP 7 +\fB%U\fP +Replaced by the week number of the year as a decimal number [00,53]. +The first Sunday of January is the first day of week 1; +days in the new year before this are in week 0. [ \fItm_year\fP, \fItm_wday\fP, +\fItm_yday\fP] +.TP 7 +\fB%V\fP +Replaced by the week number of the year (Monday as the first day of +the week) as a decimal number [01,53]. If the week +containing 1 January has four or more days in the new year, then it +is considered week 1. Otherwise, it is the last week of the +previous year, and the next week is week 1. Both January 4th and the +first Thursday of January are always in week 1. [ +\fItm_year\fP, \fItm_wday\fP, \fItm_yday\fP] +.TP 7 +\fB%w\fP +Replaced by the weekday as a decimal number [0,6], with 0 representing +Sunday. [ \fItm_wday\fP] +.TP 7 +\fB%W\fP +Replaced by the week number of the year as a decimal number [00,53]. +The first Monday of January is the first day of week 1; +days in the new year before this are in week 0. [ \fItm_year\fP, \fItm_wday\fP, +\fItm_yday\fP] +.TP 7 +\fB%x\fP +Replaced by the locale's appropriate date representation. (See the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP.) +.TP 7 +\fB%X\fP +Replaced by the locale's appropriate time representation. (See the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP.) +.TP 7 +\fB%y\fP +Replaced by the last two digits of the year as a decimal number [00,99]. +[ \fItm_year\fP] +.TP 7 +\fB%Y\fP +Replaced by the year as a decimal number (for example, 1997). [ \fItm_year\fP] +.TP 7 +\fB%z\fP +Replaced by the offset from UTC in the ISO\ 8601:2000 standard format +( \fB+hhmm\fP or \fB-hhmm\fP ), or by no +characters if no timezone is determinable. For example, \fB"-0430"\fP +means 4 hours 30 minutes behind UTC (west of Greenwich). +\ If \fItm_isdst\fP is zero, the standard time offset is used. If +\fItm_isdst\fP is greater than zero, the daylight savings +time offset is used. If \fItm_isdst\fP is negative, no characters +are returned. [ \fItm_isdst\fP] +.TP 7 +\fB%Z\fP +Replaced by the timezone name or abbreviation, or by no bytes if no +timezone information exists. [ \fItm_isdst\fP] +.TP 7 +\fB%%\fP +Replaced by \fB%\fP . +.sp +.LP +If a conversion specification does not correspond to any of the above, +the behavior is undefined. +.LP +If +a \fBstruct tm\fP broken-down time structure is created by \fIlocaltime\fP() +or \fIlocaltime_r\fP(), or modified by \fImktime\fP(), and the value +of \fITZ\fP is subsequently modified, the results of the \fB%Z\fP +and \fB%z\fP \fIstrftime\fP() conversion specifiers are undefined, +when \fIstrftime\fP() is called with such a broken-down +time structure. +.LP +If a \fBstruct tm\fP broken-down time structure is created or modified +by \fIgmtime\fP() or \fIgmtime_r\fP(), it is unspecified +whether the result of the \fB%Z\fP and \fB%z\fP conversion specifiers +shall refer to UTC or the current local timezone, when +\fIstrftime\fP() is called with such a broken-down time structure. +.SS Modified Conversion Specifiers +.LP +Some conversion specifiers can be modified by the \fBE\fP or \fBO\fP +modifier characters to indicate that an alternative +format or specification should be used rather than the one normally +used by the unmodified conversion specifier. If the alternative +format or specification does not exist for the current locale (see +ERA in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 7.3.5, LC_TIME), the behavior shall +be as if the unmodified conversion specification were used. +.TP 7 +\fB%Ec\fP +Replaced by the locale's alternative appropriate date and time representation. +.TP 7 +\fB%EC\fP +Replaced by the name of the base year (period) in the locale's alternative +representation. +.TP 7 +\fB%Ex\fP +Replaced by the locale's alternative date representation. +.TP 7 +\fB%EX\fP +Replaced by the locale's alternative time representation. +.TP 7 +\fB%Ey\fP +Replaced by the offset from \fB%EC\fP (year only) in the locale's +alternative representation. +.TP 7 +\fB%EY\fP +Replaced by the full alternative year representation. +.TP 7 +\fB%Od\fP +Replaced by the day of the month, using the locale's alternative numeric +symbols, filled as needed with leading zeros if there +is any alternative symbol for zero; otherwise, with leading spaces. +.TP 7 +\fB%Oe\fP +Replaced by the day of the month, using the locale's alternative numeric +symbols, filled as needed with leading spaces. +.TP 7 +\fB%OH\fP +Replaced by the hour (24-hour clock) using the locale's alternative +numeric symbols. +.TP 7 +\fB%OI\fP +Replaced by the hour (12-hour clock) using the locale's alternative +numeric symbols. +.TP 7 +\fB%Om\fP +Replaced by the month using the locale's alternative numeric symbols. +.TP 7 +\fB%OM\fP +Replaced by the minutes using the locale's alternative numeric symbols. +.TP 7 +\fB%OS\fP +Replaced by the seconds using the locale's alternative numeric symbols. +.TP 7 +\fB%Ou\fP +Replaced by the weekday as a number in the locale's alternative representation +(Monday=1). +.TP 7 +\fB%OU\fP +Replaced by the week number of the year (Sunday as the first day of +the week, rules corresponding to \fB%U\fP ) using the +locale's alternative numeric symbols. +.TP 7 +\fB%OV\fP +Replaced by the week number of the year (Monday as the first day of +the week, rules corresponding to \fB%V\fP ) using the +locale's alternative numeric symbols. +.TP 7 +\fB%Ow\fP +Replaced by the number of the weekday (Sunday=0) using the locale's +alternative numeric symbols. +.TP 7 +\fB%OW\fP +Replaced by the week number of the year (Monday as the first day of +the week) using the locale's alternative numeric +symbols. +.TP 7 +\fB%Oy\fP +Replaced by the year (offset from \fB%C\fP ) using the locale's alternative +numeric symbols. +.sp +.LP +\fB%g\fP , \fB%G\fP , and \fB%V\fP give values according to the ISO\ 8601:2000 +standard week-based year. In this +system, weeks begin on a Monday and week 1 of the year is the week +that includes January 4th, which is also the week that includes +the first Thursday of the year, and is also the first week that contains +at least four days in the year. If the first Monday of +January is the 2nd, 3rd, or 4th, the preceding days are part of the +last week of the preceding year; thus, for Saturday 2nd January +1999, \fB%G\fP is replaced by 1998 and \fB%V\fP is replaced by 53. +If December 29th, 30th, or 31st is a Monday, it and any +following days are part of week 1 of the following year. Thus, for +Tuesday 30th December 1997, \fB%G\fP is replaced by 1998 and +\fB%V\fP is replaced by 01. +.LP +If a conversion specifier is not one of the above, the behavior is +undefined. +.SH RETURN VALUE +.LP +If the total number of resulting bytes including the terminating null +byte is not more than \fImaxsize\fP, \fIstrftime\fP() +shall return the number of bytes placed into the array pointed to +by \fIs\fP, not including the terminating null byte. Otherwise, +0 shall be returned and the contents of the array are unspecified. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Getting a Localized Date String +.LP +The following example first sets the locale to the user's default. +The locale information will be used in the \fInl_langinfo\fP() and +\fIstrftime\fP() functions. The \fInl_langinfo\fP() function returns +the localized date string which specifies how the date is +laid out. The \fIstrftime\fP() function takes this information and, +using the \fBtm\fP structure for values, places the date and +time information into \fIdatestring\fP. +.sp +.RS +.nf + +\fB#include +#include +#include +\&... +struct tm *tm; +char datestring[256]; +\&... +setlocale (LC_ALL, ""); +\&... +strftime (datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The range of values for \fB%S\fP is [00,60] rather than [00,59] to +allow for the occasional leap second. +.LP +Some of the conversion specifications are duplicates of others. They +are included for compatibility with \fInl_cxtime\fP() and +\fInl_ascxtime\fP(), which were published in Issue 2. +.LP +Applications should use \fB%Y\fP (4-digit years) in preference to +\fB%y\fP (2-digit years). +.LP +In the C locale, the \fBE\fP and \fBO\fP modifiers are ignored and +the replacement strings for the following specifiers +are: +.TP 7 +\fB%a\fP +The first three characters of \fB%A\fP . +.TP 7 +\fB%A\fP +One of Sunday, Monday, ..., Saturday. +.TP 7 +\fB%b\fP +The first three characters of \fB%B\fP . +.TP 7 +\fB%B\fP +One of January, February, ..., December. +.TP 7 +\fB%c\fP +Equivalent to \fB%a\fP \fB%b\fP \fB%e\fP \fB%T\fP \fB%Y\fP . +.TP 7 +\fB%p\fP +One of AM or PM. +.TP 7 +\fB%r\fP +Equivalent to \fB%I\fP : \fB%M\fP : \fB%S\fP \fB%p\fP . +.TP 7 +\fB%x\fP +Equivalent to \fB%m\fP / \fB%d\fP / \fB%y\fP . +.TP 7 +\fB%X\fP +Equivalent to \fB%T\fP . +.TP 7 +\fB%Z\fP +Implementation-defined. +.sp +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIasctime\fP() , \fIclock\fP() , \fIctime\fP() +, \fIdifftime\fP() , \fIgetdate\fP() , \fIgmtime\fP() , \fIlocaltime\fP() +, \fImktime\fP() , +\fIstrptime\fP() , \fItime\fP() , \fItzset\fP() , +\fIutime\fP() , Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 7.3.5, LC_TIME, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strlen.3p b/man3p/strlen.3p new file mode 100644 index 000000000..e8f45686c --- /dev/null +++ b/man3p/strlen.3p @@ -0,0 +1,80 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRLEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strlen +.SH NAME +strlen \- get string length +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t strlen(const char *\fP\fIs\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrlen\fP() function shall compute the number of bytes in the +string to which \fIs\fP points, not including the +terminating null byte. +.SH RETURN VALUE +.LP +The \fIstrlen\fP() function shall return the length of \fIs\fP; no +return value shall be reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Getting String Lengths +.LP +The following example sets the maximum length of \fIkey\fP and \fIdata\fP +by using \fIstrlen\fP() to get the lengths of those +strings. +.sp +.RS +.nf + +\fB#include +\&... +struct element { + char *key; + char *data; +}; +\&... +char *key, *data; +int len; +.sp + +*keylength = *datalength = 0; +\&... +if ((len = strlen(key)) > *keylength) + *keylength = len; +if ((len = strlen(data)) > *datalength) + *datalength = len; +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strncasecmp.3p b/man3p/strncasecmp.3p new file mode 100644 index 000000000..bfb795da1 --- /dev/null +++ b/man3p/strncasecmp.3p @@ -0,0 +1 @@ +.so man3p/strcasecmp.3p diff --git a/man3p/strncat.3p b/man3p/strncat.3p new file mode 100644 index 000000000..78c8b8591 --- /dev/null +++ b/man3p/strncat.3p @@ -0,0 +1,58 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRNCAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strncat +.SH NAME +strncat \- concatenate a string with part of another +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *strncat(char *restrict\fP \fIs1\fP\fB, const char *restrict\fP +\fIs2\fP\fB, size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrncat\fP() function shall append not more than \fIn\fP bytes +(a null byte and bytes that follow it are not appended) +from the array pointed to by \fIs2\fP to the end of the string pointed +to by \fIs1\fP. The initial byte of \fIs2\fP overwrites +the null byte at the end of \fIs1\fP. A terminating null byte is always +appended to the result. If copying takes place between +objects that overlap, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIstrncat\fP() function shall return \fIs1\fP; no return value +shall be reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrcat\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strncmp.3p b/man3p/strncmp.3p new file mode 100644 index 000000000..50e3e9649 --- /dev/null +++ b/man3p/strncmp.3p @@ -0,0 +1,62 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRNCMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strncmp +.SH NAME +strncmp \- compare part of two strings +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int strncmp(const char *\fP\fIs1\fP\fB, const char *\fP\fIs2\fP\fB, +size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrncmp\fP() function shall compare not more than \fIn\fP bytes +(bytes that follow a null byte are not compared) from +the array pointed to by \fIs1\fP to the array pointed to by \fIs2\fP. +.LP +The sign of a non-zero return value is determined by the sign of the +difference between the values of the first pair of bytes +(both interpreted as type \fBunsigned char\fP) that differ in the +strings being compared. +.SH RETURN VALUE +.LP +Upon successful completion, \fIstrncmp\fP() shall return an integer +greater than, equal to, or less than 0, if the possibly +null-terminated array pointed to by \fIs1\fP is greater than, equal +to, or less than the possibly null-terminated array pointed to +by \fIs2\fP respectively. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrcmp\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strncpy.3p b/man3p/strncpy.3p new file mode 100644 index 000000000..770cfdd5e --- /dev/null +++ b/man3p/strncpy.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRNCPY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strncpy +.SH NAME +strncpy \- copy part of a string +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *strncpy(char *restrict\fP \fIs1\fP\fB, const char *restrict\fP +\fIs2\fP\fB, size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrncpy\fP() function shall copy not more than \fIn\fP bytes +(bytes that follow a null byte are not copied) from the +array pointed to by \fIs2\fP to the array pointed to by \fIs1\fP. +If copying takes place between objects that overlap, the +behavior is undefined. +.LP +If the array pointed to by \fIs2\fP is a string that is shorter than +\fIn\fP bytes, null bytes shall be appended to the copy +in the array pointed to by \fIs1\fP, until \fIn\fP bytes in all are +written. +.SH RETURN VALUE +.LP +The \fIstrncpy\fP() function shall return \fIs1\fP; no return value +is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Character movement is performed differently in different implementations. +Thus, overlapping moves may yield surprises. +.LP +If there is no null byte in the first \fIn\fP bytes of the array pointed +to by \fIs2\fP, the result is not +null-terminated. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrcpy\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strpbrk.3p b/man3p/strpbrk.3p new file mode 100644 index 000000000..cc3867982 --- /dev/null +++ b/man3p/strpbrk.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRPBRK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strpbrk +.SH NAME +strpbrk \- scan a string for a byte +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *strpbrk(const char *\fP\fIs1\fP\fB, const char *\fP\fIs2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrpbrk\fP() function shall locate the first occurrence in +the string pointed to by \fIs1\fP of any byte from the +string pointed to by \fIs2\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIstrpbrk\fP() shall return a pointer +to the byte or a null pointer if no byte from \fIs2\fP +occurs in \fIs1\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrchr\fP() , \fIstrrchr\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strptime.3p b/man3p/strptime.3p new file mode 100644 index 000000000..ca79ec421 --- /dev/null +++ b/man3p/strptime.3p @@ -0,0 +1,298 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRPTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strptime +.SH NAME +strptime \- date and time conversion +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *strptime(const char *restrict\fP \fIbuf\fP\fB, const char *restrict\fP +\fIformat\fP\fB, +.br +\ \ \ \ \ \ struct tm *restrict\fP \fItm\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrptime\fP() function shall convert the character string pointed +to by \fIbuf\fP to values which are stored in the +\fBtm\fP structure pointed to by \fItm\fP, using the format specified +by \fIformat\fP. +.LP +The \fIformat\fP is composed of zero or more directives. Each directive +is composed of one of the following: one or more +white-space characters (as specified by \fIisspace\fP()); an ordinary +character (neither +\fB'%'\fP nor a white-space character); or a conversion specification. +Each conversion specification is composed of a +\fB'%'\fP character followed by a conversion character which specifies +the replacement required. The application shall ensure +that there is white-space or other non-alphanumeric characters between +any two conversion specifications. The following conversion +specifications are supported: +.TP 7 +\fB%a\fP +The day of the week, using the locale's weekday names; either the +abbreviated or full name may be specified. +.TP 7 +\fB%A\fP +Equivalent to \fB%a\fP . +.TP 7 +\fB%b\fP +The month, using the locale's month names; either the abbreviated +or full name may be specified. +.TP 7 +\fB%B\fP +Equivalent to \fB%b\fP . +.TP 7 +\fB%c\fP +Replaced by the locale's appropriate date and time representation. +.TP 7 +\fB%C\fP +The century number [00,99]; leading zeros are permitted but not required. +.TP 7 +\fB%d\fP +The day of the month [01,31]; leading zeros are permitted but not +required. +.TP 7 +\fB%D\fP +The date as \fB%m\fP / \fB%d\fP / \fB%y\fP . +.TP 7 +\fB%e\fP +Equivalent to \fB%d\fP . +.TP 7 +\fB%h\fP +Equivalent to \fB%b\fP . +.TP 7 +\fB%H\fP +The hour (24-hour clock) [00,23]; leading zeros are permitted but +not required. +.TP 7 +\fB%I\fP +The hour (12-hour clock) [01,12]; leading zeros are permitted but +not required. +.TP 7 +\fB%j\fP +The day number of the year [001,366]; leading zeros are permitted +but not required. +.TP 7 +\fB%m\fP +The month number [01,12]; leading zeros are permitted but not required. +.TP 7 +\fB%M\fP +The minute [00,59]; leading zeros are permitted but not required. +.TP 7 +\fB%n\fP +Any white space. +.TP 7 +\fB%p\fP +The locale's equivalent of a.m or p.m. +.TP 7 +\fB%r\fP +12-hour clock time using the AM/PM notation if \fBt_fmt_ampm\fP is +not an empty string in the LC_TIME portion of the current +locale; in the POSIX locale, this shall be equivalent to \fB%I\fP +: \fB%M\fP : \fB%S\fP \fB%p\fP . +.TP 7 +\fB%R\fP +The time as \fB%H\fP : \fB%M\fP . +.TP 7 +\fB%S\fP +The seconds [00,60]; leading zeros are permitted but not required. +.TP 7 +\fB%t\fP +Any white space. +.TP 7 +\fB%T\fP +The time as \fB%H\fP : \fB%M\fP : \fB%S\fP . +.TP 7 +\fB%U\fP +The week number of the year (Sunday as the first day of the week) +as a decimal number [00,53]; leading zeros are permitted but +not required. +.TP 7 +\fB%w\fP +The weekday as a decimal number [0,6], with 0 representing Sunday; +leading zeros are permitted but not required. +.TP 7 +\fB%W\fP +The week number of the year (Monday as the first day of the week) +as a decimal number [00,53]; leading zeros are permitted but +not required. +.TP 7 +\fB%x\fP +The date, using the locale's date format. +.TP 7 +\fB%X\fP +The time, using the locale's time format. +.TP 7 +\fB%y\fP +The year within century. When a century is not otherwise specified, +values in the range [69,99] shall refer to years 1969 to +1999 inclusive, and values in the range [00,68] shall refer to years +2000 to 2068 inclusive; leading zeros shall be permitted but +shall not be required. +.TP 7 +\fBNote:\fP +.RS +It is expected that in a future version of IEEE\ Std\ 1003.1-2001 +the default century inferred from a 2-digit year will +change. (This would apply to all commands accepting a 2-digit year +as input.) +.RE +.sp +.TP 7 +\fB%Y\fP +The year, including the century (for example, 1988). +.TP 7 +\fB%%\fP +Replaced by \fB%\fP . +.sp +.SS Modified Conversion Specifiers +.LP +Some conversion specifiers can be modified by the \fBE\fP and \fBO\fP +modifier characters to indicate that an alternative +format or specification should be used rather than the one normally +used by the unmodified conversion specifier. If the alternative +format or specification does not exist in the current locale, the +behavior shall be as if the unmodified conversion specification +were used. +.TP 7 +\fB%Ec\fP +The locale's alternative appropriate date and time representation. +.TP 7 +\fB%EC\fP +The name of the base year (period) in the locale's alternative representation. +.TP 7 +\fB%Ex\fP +The locale's alternative date representation. +.TP 7 +\fB%EX\fP +The locale's alternative time representation. +.TP 7 +\fB%Ey\fP +The offset from \fB%EC\fP (year only) in the locale's alternative +representation. +.TP 7 +\fB%EY\fP +The full alternative year representation. +.TP 7 +\fB%Od\fP +The day of the month using the locale's alternative numeric symbols; +leading zeros are permitted but not required. +.TP 7 +\fB%Oe\fP +Equivalent to \fB%Od\fP . +.TP 7 +\fB%OH\fP +The hour (24-hour clock) using the locale's alternative numeric symbols. +.TP 7 +\fB%OI\fP +The hour (12-hour clock) using the locale's alternative numeric symbols. +.TP 7 +\fB%Om\fP +The month using the locale's alternative numeric symbols. +.TP 7 +\fB%OM\fP +The minutes using the locale's alternative numeric symbols. +.TP 7 +\fB%OS\fP +The seconds using the locale's alternative numeric symbols. +.TP 7 +\fB%OU\fP +The week number of the year (Sunday as the first day of the week) +using the locale's alternative numeric symbols. +.TP 7 +\fB%Ow\fP +The number of the weekday (Sunday=0) using the locale's alternative +numeric symbols. +.TP 7 +\fB%OW\fP +The week number of the year (Monday as the first day of the week) +using the locale's alternative numeric symbols. +.TP 7 +\fB%Oy\fP +The year (offset from \fB%C\fP ) using the locale's alternative numeric +symbols. +.sp +.LP +A conversion specification composed of white-space characters is executed +by scanning input up to the first character that is +not white-space (which remains unscanned), or until no more characters +can be scanned. +.LP +A conversion specification that is an ordinary character is executed +by scanning the next character from the buffer. If the +character scanned from the buffer differs from the one comprising +the directive, the directive fails, and the differing and +subsequent characters remain unscanned. +.LP +A series of conversion specifications composed of \fB%n\fP , \fB%t\fP +, white-space characters, or any combination is +executed by scanning up to the first character that is not white space +(which remains unscanned), or until no more characters can +be scanned. +.LP +Any other conversion specification is executed by scanning characters +until a character matching the next directive is scanned, +or until no more characters can be scanned. These characters, except +the one matching the next directive, are then compared to the +locale values associated with the conversion specifier. If a match +is found, values for the appropriate \fBtm\fP structure members +are set to values corresponding to the locale information. Case is +ignored when matching items in \fIbuf\fP such as month or +weekday names. If no match is found, \fIstrptime\fP() fails and no +more characters are scanned. +.SH RETURN VALUE +.LP +Upon successful completion, \fIstrptime\fP() shall return a pointer +to the character following the last character parsed. +Otherwise, a null pointer shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Several "equivalent to" formats and the special processing of white-space +characters are provided in order to ease the use of +identical \fIformat\fP strings for \fIstrftime\fP() and \fIstrptime\fP(). +.LP +Applications should use \fB%Y\fP (4-digit years) in preference to +\fB%y\fP (2-digit years). +.LP +It is unspecified whether multiple calls to \fIstrptime\fP() using +the same \fBtm\fP structure will update the current +contents of the structure or overwrite all contents of the structure. +Conforming applications should make a single call to +\fIstrptime\fP() with a format and all data needed to completely specify +the date and time being converted. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +The \fIstrptime\fP() function is expected to be mandatory in the next +version of this volume of +IEEE\ Std\ 1003.1-2001. +.SH SEE ALSO +.LP +\fIscanf\fP() , \fIstrftime\fP() , \fItime\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strrchr.3p b/man3p/strrchr.3p new file mode 100644 index 000000000..281164416 --- /dev/null +++ b/man3p/strrchr.3p @@ -0,0 +1,74 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRRCHR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strrchr +.SH NAME +strrchr \- string scanning operation +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *strrchr(const char *\fP\fIs\fP\fB, int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrrchr\fP() function shall locate the last occurrence of \fIc\fP +(converted to a \fBchar\fP) in the string pointed to +by \fIs\fP. The terminating null byte is considered to be part of +the string. +.SH RETURN VALUE +.LP +Upon successful completion, \fIstrrchr\fP() shall return a pointer +to the byte or a null pointer if \fIc\fP does not occur in +the string. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Finding the Base Name of a File +.LP +The following example uses \fIstrrchr\fP() to get a pointer to the +base name of a file. The \fIstrrchr\fP() function searches +backwards through the name of the file to find the last \fB'/'\fP +character in \fIname\fP. This pointer (plus one) will point +to the base name of the file. +.sp +.RS +.nf + +\fB#include +\&... +const char *name; +char *basename; +\&... +basename = strrchr(name, '/') + 1; +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrchr\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strspn.3p b/man3p/strspn.3p new file mode 100644 index 000000000..45f99d600 --- /dev/null +++ b/man3p/strspn.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRSPN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strspn +.SH NAME +strspn \- get length of a substring +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t strspn(const char *\fP\fIs1\fP\fB, const char *\fP\fIs2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrspn\fP() function shall compute the length (in bytes) of +the maximum initial segment of the string pointed to by +\fIs1\fP which consists entirely of bytes from the string pointed +to by \fIs2\fP. +.SH RETURN VALUE +.LP +The \fIstrspn\fP() function shall return the length of \fIs1\fP; no +return value is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrcspn\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strstr.3p b/man3p/strstr.3p new file mode 100644 index 000000000..ce41fa7f7 --- /dev/null +++ b/man3p/strstr.3p @@ -0,0 +1,58 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRSTR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strstr +.SH NAME +strstr \- find a substring +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *strstr(const char *\fP\fIs1\fP\fB, const char *\fP\fIs2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrstr\fP() function shall locate the first occurrence in the +string pointed to by \fIs1\fP of the sequence of bytes +(excluding the terminating null byte) in the string pointed to by +\fIs2\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIstrstr\fP() shall return a pointer +to the located string or a null pointer if the string is not +found. +.LP +If \fIs2\fP points to a string with zero length, the function shall +return \fIs1\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrchr\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strtod.3p b/man3p/strtod.3p new file mode 100644 index 000000000..151077681 --- /dev/null +++ b/man3p/strtod.3p @@ -0,0 +1,274 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRTOD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strtod +.SH NAME +strtod, strtof, strtold \- convert a string to a double-precision number +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double strtod(const char *restrict\fP \fInptr\fP\fB, char **restrict\fP +\fIendptr\fP\fB); +.br +float strtof(const char *restrict\fP \fInptr\fP\fB, char **restrict\fP +\fIendptr\fP\fB); +.br +long double strtold(const char *restrict\fP \fInptr\fP\fB, char **restrict\fP +\fIendptr\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall convert the initial portion of the string pointed +to by \fInptr\fP to \fBdouble\fP, \fBfloat\fP, and +\fBlong double\fP representation, respectively. First, they decompose +the input string into three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space characters (as +specified by \fIisspace\fP()) +.LP +.IP " 2." 4 +A subject sequence interpreted as a floating-point constant or representing +infinity or NaN +.LP +.IP " 3." 4 +A final string of one or more unrecognized characters, including the +terminating null byte of the input string +.LP +.LP +Then they shall attempt to convert the subject sequence to a floating-point +number, and return the result. +.LP +The expected form of the subject sequence is an optional plus or minus +sign, then one of the following: +.IP " *" 3 +A non-empty sequence of decimal digits optionally containing a radix +character, then an optional exponent part +.LP +.IP " *" 3 +A 0x or 0X, then a non-empty sequence of hexadecimal digits optionally +containing a radix character, then an optional binary +exponent part +.LP +.IP " *" 3 +One of INF or INFINITY, ignoring case +.LP +.IP " *" 3 +One of NAN or NAN(\fIn-char-sequence_opt\fP), ignoring case in the +NAN part, where: +.sp +.RS +.nf + +\fBn-char-sequence: + digit + nondigit + n-char-sequence digit + n-char-sequence nondigit +\fP +.fi +.RE +.LP +.LP +The subject sequence is defined as the longest initial subsequence +of the input string, starting with the first non-white-space +character, that is of the expected form. The subject sequence contains +no characters if the input string is not of the expected +form. +.LP +If the subject sequence has the expected form for a floating-point +number, the sequence of characters starting with the first +digit or the decimal-point character (whichever occurs first) shall +be interpreted as a floating constant of the C language, except +that the radix character shall be used in place of a period, and that +if neither an exponent part nor a radix character appears in +a decimal floating-point number, or if a binary exponent part does +not appear in a hexadecimal floating-point number, an exponent +part of the appropriate type with value zero is assumed to follow +the last digit in the string. If the subject sequence begins with +a minus sign, the sequence shall be interpreted as negated. A character +sequence INF or INFINITY shall be interpreted as an +infinity, if representable in the return type, else as if it were +a floating constant that is too large for the range of the return +type. A character sequence NAN or NAN(\fIn-char-sequence_opt\fP) shall +be interpreted as a quiet NaN, if +supported in the return type, else as if it were a subject sequence +part that does not have the expected form; the meaning of the +\fIn\fP-char sequences is implementation-defined. A pointer to the +final string is stored in the object pointed to by +\fIendptr\fP, provided that \fIendptr\fP is not a null pointer. +.LP +If the subject sequence has the hexadecimal form and FLT_RADIX is +a power of 2, the value resulting from the conversion is +correctly rounded. +.LP +The +radix character is defined in the program's locale (category \fILC_NUMERIC +).\fP In the POSIX locale, or in a locale where the +radix character is not defined, the radix character shall default +to a period ( \fB'.'\fP ). +.LP +In other than the C \ or POSIX locales, other +implementation-defined subject sequences may be accepted. +.LP +If the subject sequence is empty or does not have the expected form, +no conversion shall be performed; the value of \fIstr\fP +is stored in the object pointed to by \fIendptr\fP, provided that +\fIendptr\fP is not a null pointer. +.LP +The +\fIstrtod\fP() function shall not change the setting of \fIerrno\fP +if successful. +.LP +Since 0 is returned on error and is also a valid return on success, +an application wishing to check for error situations should +set \fIerrno\fP to 0, then call \fIstrtod\fP(), \fIstrtof\fP(), or +\fIstrtold\fP(), then check \fIerrno\fP. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the converted +value. If no conversion could be performed, 0 shall be +returned, and \fIerrno\fP may be set to [EINVAL]. +.LP +If the correct value is outside the range of representable values, +\(+-HUGE_VAL, \(+-HUGE_VALF, or \(+-HUGE_VALL +shall be returned (according to the sign of the value), and \fIerrno\fP +shall be set to [ERANGE]. +.LP +If the correct value would cause an underflow, a value whose magnitude +is no greater than the smallest normalized positive +number in the return type shall be returned and \fIerrno\fP set to +[ERANGE]. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +.B ERANGE +The value to be returned would cause overflow \ or underflow. +.sp +.LP +These functions may fail if: +.TP 7 +.B EINVAL +No +conversion could be performed. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +If the subject sequence has the hexadecimal form and FLT_RADIX is +not a power of 2, and the result is not exactly representable, +the result should be one of the two numbers in the appropriate internal +format that are adjacent to the hexadecimal floating source +value, with the extra stipulation that the error should have a correct +sign for the current rounding direction. +.LP +If the subject sequence has the decimal form and at most DECIMAL_DIG +(defined in \fI\fP) significant digits, the result should +be correctly rounded. If the subject +sequence \fID\fP has the decimal form and more than DECIMAL_DIG significant +digits, consider the two bounding, adjacent decimal +strings \fIL\fP and \fIU\fP, both having DECIMAL_DIG significant digits, +such that the values of \fIL\fP, \fID\fP, and \fIU\fP +satisfy \fIL\fP <= \fID\fP <= \fIU\fP. The result should be one of +the (equal or adjacent) values that would be obtained +by correctly rounding \fIL\fP and \fIU\fP according to the current +rounding direction, with the extra stipulation that the error +with respect to \fID\fP should have a correct sign for the current +rounding direction. +.LP +The changes to \fIstrtod\fP() introduced by the ISO/IEC\ 9899:1999 +standard can alter the behavior of well-formed +applications complying with the ISO/IEC\ 9899:1990 standard and thus +earlier versions of the base documents. One such example +would be: +.sp +.RS +.nf + +\fBint +what_kind_of_number (char *s) +{ + char *endp; + double d; + long l; +.sp + + d = strtod(s, &endp); + if (s != endp && *endp == `\\0') + printf("It's a float with value %g\\n", d); + else + { + l = strtol(s, &endp, 0); + if (s != endp && *endp == `\\0') + printf("It's an integer with value %ld\\n", 1); + else + return 1; + } + return 0; +} +\fP +.fi +.RE +.LP +If the function is called with: +.sp +.RS +.nf + +\fBwhat_kind_of_number ("0x10") +\fP +.fi +.RE +.LP +an ISO/IEC\ 9899:1990 standard-compliant library will result in the +function printing: +.sp +.RS +.nf + +\fBIt's an integer with value 16 +\fP +.fi +.RE +.LP +With the ISO/IEC\ 9899:1999 standard, the result is: +.sp +.RS +.nf + +\fBIt's a float with value 16 +\fP +.fi +.RE +.LP +The change in behavior is due to the inclusion of floating-point numbers +in hexadecimal notation without requiring that either a +decimal point or the binary exponent be present. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisspace\fP() , \fIlocaleconv\fP() , \fIscanf\fP() , \fIsetlocale\fP() +, \fIstrtol\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strtof.3p b/man3p/strtof.3p new file mode 100644 index 000000000..e7802a071 --- /dev/null +++ b/man3p/strtof.3p @@ -0,0 +1 @@ +.so man3p/strtod.3p diff --git a/man3p/strtoimax.3p b/man3p/strtoimax.3p new file mode 100644 index 000000000..7b3c8d2f9 --- /dev/null +++ b/man3p/strtoimax.3p @@ -0,0 +1,78 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRTOIMAX" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strtoimax +.SH NAME +strtoimax, strtoumax \- convert string to integer type +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +intmax_t strtoimax(const char *restrict\fP \fInptr\fP\fB, char **restrict\fP +\fIendptr\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIbase\fP\fB); +.br +uintmax_t strtoumax(const char *restrict\fP \fInptr\fP\fB, char **restrict\fP +\fIendptr\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIbase\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall be equivalent to the \fIstrtol\fP(), \fIstrtoll\fP(), +\fIstrtoul\fP(), and \fIstrtoull\fP() functions, except that the initial +portion of the string shall be converted to +\fBintmax_t\fP and \fBuintmax_t\fP representation, respectively. +.SH RETURN VALUE +.LP +These functions shall return the converted value, if any. +.LP +If no conversion could be performed, zero shall be returned. +.LP +If the correct value is outside the range of representable values, +{INTMAX_MAX}, {INTMAX_MIN}, or {UINTMAX_MAX} shall be +returned (according to the return type and sign of the value, if any), +and \fIerrno\fP shall be set to [ERANGE]. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +.B ERANGE +The value to be returned is not representable. +.sp +.LP +These functions may fail if: +.TP 7 +.B EINVAL +The value of \fIbase\fP is not supported. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrtol\fP() , \fIstrtoul\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strtok.3p b/man3p/strtok.3p new file mode 100644 index 000000000..dc4d732da --- /dev/null +++ b/man3p/strtok.3p @@ -0,0 +1,179 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRTOK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strtok +.SH NAME +strtok, strtok_r \- split string into tokens +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *strtok(char *restrict\fP \fIs1\fP\fB, const char *restrict\fP +\fIs2\fP\fB); +.br +\fP +.LP +\fBchar *strtok_r(char *restrict\fP \fIs\fP\fB, const char *restrict\fP +\fIsep\fP\fB, +.br +\ \ \ \ \ \ char **restrict\fP \fIlasts\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +For \fIstrtok\fP(): The functionality described on this reference +page is aligned with the ISO\ C standard. Any +conflict between the requirements described here and the ISO\ C standard +is unintentional. This volume of +IEEE\ Std\ 1003.1-2001 defers to the ISO\ C standard. +.LP +A sequence of calls to \fIstrtok\fP() breaks the string pointed to +by \fIs1\fP into a sequence of tokens, each of which is +delimited by a byte from the string pointed to by \fIs2\fP. The first +call in the sequence has \fIs1\fP as its first argument, +and is followed by calls with a null pointer as their first argument. +The separator string pointed to by \fIs2\fP may be different +from call to call. +.LP +The first call in the sequence searches the string pointed to by \fIs1\fP +for the first byte that is \fInot\fP contained in +the current separator string pointed to by \fIs2\fP. If no such byte +is found, then there are no tokens in the string pointed to +by \fIs1\fP and \fIstrtok\fP() shall return a null pointer. If such +a byte is found, it is the start of the first token. +.LP +The \fIstrtok\fP() function then searches from there for a byte that +\fIis\fP contained in the current separator string. If no +such byte is found, the current token extends to the end of the string +pointed to by \fIs1\fP, and subsequent searches for a token +shall return a null pointer. If such a byte is found, it is overwritten +by a null byte, which terminates the current token. The +\fIstrtok\fP() function saves a pointer to the following byte, from +which the next search for a token shall start. +.LP +Each subsequent call, with a null pointer as the value of the first +argument, starts searching from the saved pointer and +behaves as described above. +.LP +The implementation shall behave as if no function defined in this +volume of IEEE\ Std\ 1003.1-2001 calls +\fIstrtok\fP(). +.LP +The +\fIstrtok\fP() function need not be reentrant. A function that is +not required to be reentrant is not required to be thread-safe. +.LP +The \fIstrtok_r\fP() function considers the null-terminated string +\fIs\fP as a sequence of zero or more text tokens separated by +spans of one or more characters from the separator string \fIsep\fP. +The argument \fIlasts\fP points to a user-provided pointer +which points to stored information necessary for \fIstrtok_r\fP() +to continue scanning the same string. +.LP +In the first call to \fIstrtok_r\fP(), \fIs\fP points to a null-terminated +string, \fIsep\fP to a null-terminated string of +separator characters, and the value pointed to by \fIlasts\fP is ignored. +The \fIstrtok_r\fP() function shall return a pointer to +the first character of the first token, write a null character into +\fIs\fP immediately following the returned token, and update +the pointer to which \fIlasts\fP points. +.LP +In subsequent calls, \fIs\fP is a NULL pointer and \fIlasts\fP shall +be unchanged from the previous call so that subsequent +calls shall move through the string \fIs\fP, returning successive +tokens until no tokens remain. The separator string \fIsep\fP +may be different from call to call. When no token remains in \fIs\fP, +a NULL pointer shall be returned. +.SH RETURN VALUE +.LP +Upon successful completion, \fIstrtok\fP() shall return a pointer +to the first byte of a token. Otherwise, if there is no +token, \fIstrtok\fP() shall return a null pointer. +.LP +The \fIstrtok_r\fP() function shall return a pointer to the token +found, or a NULL pointer when no token is found. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Searching for Word Separators +.LP +The following example searches for tokens separated by s. +.sp +.RS +.nf + +\fB#include +\&... +char *token; +char *line = "LINE TO BE SEPARATED"; +char *search = " "; +.sp + +/* Token will point to "LINE". */ +token = strtok(line, search); +.sp + +/* Token will point to "TO". */ +token = strtok(NULL, search); +\fP +.fi +.RE +.SS Breaking a Line +.LP +The following example uses \fIstrtok\fP() to break a line into two +character strings separated by any combination of +s, s, or s. +.sp +.RS +.nf + +\fB#include +\&... +struct element { + char *key; + char *data; +}; +\&... +char line[LINE_MAX]; +char *key, *data; +\&... +key = strtok(line, " \\n"); +data = strtok(NULL, " \\n"); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIstrtok_r\fP() function is thread-safe and stores its state +in a user-supplied buffer instead of possibly using a static +data area that may be overwritten by an unrelated call from another +thread. +.SH RATIONALE +.LP +The \fIstrtok\fP() function searches for a separator string within +a larger string. It returns a pointer to the last substring +between separator strings. This function uses static storage to keep +track of the current string position between calls. The new +function, \fIstrtok_r\fP(), takes an additional argument, \fIlasts\fP, +to keep track of the current position in the string. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strtok_r.3p b/man3p/strtok_r.3p new file mode 100644 index 000000000..1aa7121e7 --- /dev/null +++ b/man3p/strtok_r.3p @@ -0,0 +1 @@ +.so man3p/strtok.3p diff --git a/man3p/strtol.3p b/man3p/strtol.3p new file mode 100644 index 000000000..9c4e08dba --- /dev/null +++ b/man3p/strtol.3p @@ -0,0 +1,151 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRTOL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strtol +.SH NAME +strtol, strtoll \- convert a string to a long integer +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +long strtol(const char *restrict\fP \fIstr\fP\fB, char **restrict\fP +\fIendptr\fP\fB, int\fP \fIbase\fP\fB); +.br +long long strtoll(const char *restrict\fP \fIstr\fP\fB, char **restrict\fP +\fIendptr\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIbase\fP\fB) +.br +\fP +.SH DESCRIPTION +.LP +These functions shall convert the initial portion of the string pointed +to by \fIstr\fP to a type \fBlong\fP and \fBlong +long\fP representation, respectively. First, they decompose the input +string into three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space characters (as +specified by \fIisspace\fP()) +.LP +.IP " 2." 4 +A subject sequence interpreted as an integer represented in some radix +determined by the value of \fIbase\fP +.LP +.IP " 3." 4 +A final string of one or more unrecognized characters, including the +terminating null byte of the input string. +.LP +.LP +Then they shall attempt to convert the subject sequence to an integer, +and return the result. +.LP +If the value of \fIbase\fP is 0, the expected form of the subject +sequence is that of a decimal constant, octal constant, or +hexadecimal constant, any of which may be preceded by a \fB'+'\fP +or \fB'-'\fP sign. A decimal constant begins with a +non-zero digit, and consists of a sequence of decimal digits. An octal +constant consists of the prefix \fB'0'\fP optionally +followed by a sequence of the digits \fB'0'\fP to \fB'7'\fP only. +A hexadecimal constant consists of the prefix 0x or 0X +followed by a sequence of the decimal digits and letters \fB'a'\fP +(or \fB'A'\fP ) to \fB'f'\fP (or \fB'F'\fP ) with +values 10 to 15 respectively. +.LP +If the value of \fIbase\fP is between 2 and 36, the expected form +of the subject sequence is a sequence of letters and digits +representing an integer with the radix specified by \fIbase\fP, optionally +preceded by a \fB'+'\fP or \fB'-'\fP sign. The +letters from \fB'a'\fP (or \fB'A'\fP ) to \fB'z'\fP (or \fB'Z'\fP +) inclusive are ascribed the values 10 to 35; only +letters whose ascribed values are less than that of \fIbase\fP are +permitted. If the value of \fIbase\fP is 16, the characters 0x +or 0X may optionally precede the sequence of letters and digits, following +the sign if present. +.LP +The subject sequence is defined as the longest initial subsequence +of the input string, starting with the first non-white-space +character that is of the expected form. The subject sequence shall +contain no characters if the input string is empty or consists +entirely of white-space characters, or if the first non-white-space +character is other than a sign or a permissible letter or +digit. +.LP +If the subject sequence has the expected form and the value of \fIbase\fP +is 0, the sequence of characters starting with the +first digit shall be interpreted as an integer constant. If the subject +sequence has the expected form and the value of \fIbase\fP +is between 2 and 36, it shall be used as the base for conversion, +ascribing to each letter its value as given above. If the subject +sequence begins with a minus sign, the value resulting from the conversion +shall be negated. A pointer to the final string shall be +stored in the object pointed to by \fIendptr\fP, provided that \fIendptr\fP +is not a null pointer. +.LP +In other than the C \ or POSIX locales, other +implementation-defined subject sequences may be accepted. +.LP +If the subject sequence is empty or does not have the expected form, +no conversion is performed; the value of \fIstr\fP is +stored in the object pointed to by \fIendptr\fP, provided that \fIendptr\fP +is not a null pointer. +.LP +The +\fIstrtol\fP() function shall not change the setting of \fIerrno\fP +if successful. +.LP +Since 0, {LONG_MIN} or {LLONG_MIN}, and {LONG_MAX} or {LLONG_MAX} +are returned on error and are also valid returns on success, +an application wishing to check for error situations should set \fIerrno\fP +to 0, then call \fIstrtol\fP() or \fIstrtoll\fP(), +then check \fIerrno\fP. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the converted +value, if any. If no conversion could be performed, 0 +shall be returned \ and \fIerrno\fP may be set to [EINVAL]. +.LP +If the correct value is outside the range of representable values, +{LONG_MIN}, {LONG_MAX}, {LLONG_MIN}, or {LLONG_MAX} shall be +returned (according to the sign of the value), and \fIerrno\fP set +to [ERANGE]. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +.B ERANGE +The value to be returned is not representable. +.sp +.LP +These functions may fail if: +.TP 7 +.B EINVAL +The value of \fIbase\fP is not supported. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisalpha\fP() , \fIscanf\fP() , \fIstrtod\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strtold.3p b/man3p/strtold.3p new file mode 100644 index 000000000..e7802a071 --- /dev/null +++ b/man3p/strtold.3p @@ -0,0 +1 @@ +.so man3p/strtod.3p diff --git a/man3p/strtoll.3p b/man3p/strtoll.3p new file mode 100644 index 000000000..93a836e8b --- /dev/null +++ b/man3p/strtoll.3p @@ -0,0 +1 @@ +.so man3p/strtol.3p diff --git a/man3p/strtoul.3p b/man3p/strtoul.3p new file mode 100644 index 000000000..06392c3bc --- /dev/null +++ b/man3p/strtoul.3p @@ -0,0 +1,154 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRTOUL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strtoul +.SH NAME +strtoul, strtoull \- convert a string to an unsigned long +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +unsigned long strtoul(const char *restrict\fP \fIstr\fP\fB, +.br +\ \ \ \ \ \ char **restrict\fP \fIendptr\fP\fB, int\fP \fIbase\fP\fB); +.br +unsigned long long strtoull(const char *restrict\fP \fIstr\fP\fB, +.br +\ \ \ \ \ \ char **restrict\fP \fIendptr\fP\fB, int\fP \fIbase\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall convert the initial portion of the string pointed +to by \fIstr\fP to a type \fBunsigned long\fP and +\fBunsigned long long\fP representation, respectively. First, they +decompose the input string into three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space characters (as +specified by \fIisspace\fP()) +.LP +.IP " 2." 4 +A subject sequence interpreted as an integer represented in some radix +determined by the value of \fIbase\fP +.LP +.IP " 3." 4 +A final string of one or more unrecognized characters, including the +terminating null byte of the input string +.LP +.LP +Then they shall attempt to convert the subject sequence to an unsigned +integer, and return the result. +.LP +If the value of \fIbase\fP is 0, the expected form of the subject +sequence is that of a decimal constant, octal constant, or +hexadecimal constant, any of which may be preceded by a \fB'+'\fP +or \fB'-'\fP sign. A decimal constant begins with a +non-zero digit, and consists of a sequence of decimal digits. An octal +constant consists of the prefix \fB'0'\fP optionally +followed by a sequence of the digits \fB'0'\fP to \fB'7'\fP only. +A hexadecimal constant consists of the prefix 0x or 0X +followed by a sequence of the decimal digits and letters \fB'a'\fP +(or \fB'A'\fP ) to \fB'f'\fP (or \fB'F'\fP ) with +values 10 to 15 respectively. +.LP +If the value of \fIbase\fP is between 2 and 36, the expected form +of the subject sequence is a sequence of letters and digits +representing an integer with the radix specified by \fIbase\fP, optionally +preceded by a \fB'+'\fP or \fB'-'\fP sign. The +letters from \fB'a'\fP (or \fB'A'\fP ) to \fB'z'\fP (or \fB'Z'\fP +) inclusive are ascribed the values 10 to 35; only +letters whose ascribed values are less than that of \fIbase\fP are +permitted. If the value of \fIbase\fP is 16, the characters 0x +or 0X may optionally precede the sequence of letters and digits, following +the sign if present. +.LP +The subject sequence is defined as the longest initial subsequence +of the input string, starting with the first non-white-space +character that is of the expected form. The subject sequence shall +contain no characters if the input string is empty or consists +entirely of white-space characters, or if the first non-white-space +character is other than a sign or a permissible letter or +digit. +.LP +If the subject sequence has the expected form and the value of \fIbase\fP +is 0, the sequence of characters starting with the +first digit shall be interpreted as an integer constant. If the subject +sequence has the expected form and the value of \fIbase\fP +is between 2 and 36, it shall be used as the base for conversion, +ascribing to each letter its value as given above. If the subject +sequence begins with a minus sign, the value resulting from the conversion +shall be negated. A pointer to the final string shall be +stored in the object pointed to by \fIendptr\fP, provided that \fIendptr\fP +is not a null pointer. +.LP +In other than the C \ or POSIX locales, other +implementation-defined subject sequences may be accepted. +.LP +If the subject sequence is empty or does not have the expected form, +no conversion shall be performed; the value of \fIstr\fP +shall be stored in the object pointed to by \fIendptr\fP, provided +that \fIendptr\fP is not a null pointer. +.LP +The +\fIstrtoul\fP() function shall not change the setting of \fIerrno\fP +if successful. +.LP +Since 0, {ULONG_MAX}, and {ULLONG_MAX} are returned on error and are +also valid returns on success, an application wishing to +check for error situations should set \fIerrno\fP to 0, then call +\fIstrtoul\fP() or \fIstrtoull\fP(), then check \fIerrno\fP. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the converted +value, if any. If no conversion could be performed, 0 +shall be returned \ and \fIerrno\fP may be set to [EINVAL]. If +the +correct value is outside the range of representable values, {ULONG_MAX} +or {ULLONG_MAX} shall be returned and \fIerrno\fP set to +[ERANGE]. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +.B EINVAL +The value of \fIbase\fP is not supported. +.TP 7 +.B ERANGE +The value to be returned is not representable. +.sp +.LP +These functions may fail if: +.TP 7 +.B EINVAL +No +conversion could be performed. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisalpha\fP() , \fIscanf\fP() , \fIstrtod\fP() , \fIstrtol\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/strtoull.3p b/man3p/strtoull.3p new file mode 100644 index 000000000..eb8b498dc --- /dev/null +++ b/man3p/strtoull.3p @@ -0,0 +1 @@ +.so man3p/strtoul.3p diff --git a/man3p/strtoumax.3p b/man3p/strtoumax.3p new file mode 100644 index 000000000..c9558ba01 --- /dev/null +++ b/man3p/strtoumax.3p @@ -0,0 +1 @@ +.so man3p/strtoimax.3p diff --git a/man3p/strxfrm.3p b/man3p/strxfrm.3p new file mode 100644 index 000000000..d1e6fe269 --- /dev/null +++ b/man3p/strxfrm.3p @@ -0,0 +1,89 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "STRXFRM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" strxfrm +.SH NAME +strxfrm \- string transformation +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t strxfrm(char *restrict\fP \fIs1\fP\fB, const char *restrict\fP +\fIs2\fP\fB, size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIstrxfrm\fP() function shall transform the string pointed to +by \fIs2\fP and place the resulting string into the array +pointed to by \fIs1\fP. The transformation is such that if \fIstrcmp\fP() +is applied to +two transformed strings, it shall return a value greater than, equal +to, or less than 0, corresponding to the result of \fIstrcoll\fP() +applied to the same two original strings. No more than \fIn\fP bytes +are placed +into the resulting array pointed to by \fIs1\fP, including the terminating +null byte. If \fIn\fP is 0, \fIs1\fP is permitted to +be a null pointer. If copying takes place between objects that overlap, +the behavior is undefined. +.LP +The +\fIstrxfrm\fP() function shall not change the setting of \fIerrno\fP +if successful. +.LP +Since no return value is reserved to indicate an error, an application +wishing to check for error situations should set +\fIerrno\fP to 0, then call \fIstrxfrm\fP(), then check \fIerrno\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIstrxfrm\fP() shall return the length +of the transformed string (not including the terminating +null byte). If the value returned is \fIn\fP or more, the contents +of the array pointed to by \fIs1\fP are unspecified. +.LP +On +error, \fIstrxfrm\fP() may set \fIerrno\fP but no return value is +reserved to indicate an error. +.SH ERRORS +.LP +The \fIstrxfrm\fP() function may fail if: +.TP 7 +.B EINVAL +The string pointed to by the \fIs2\fP argument contains characters +outside the domain of the collating sequence. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The transformation function is such that two transformed strings can +be ordered by \fIstrcmp\fP() as appropriate to collating sequence +information in the program's locale (category +\fILC_COLLATE ).\fP +.LP +The fact that when \fIn\fP is 0 \fIs1\fP is permitted to be a null +pointer is useful to determine the size of the \fIs1\fP +array prior to making the transformation. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrcmp\fP() , \fIstrcoll\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/swab.3p b/man3p/swab.3p new file mode 100644 index 000000000..a0756648f --- /dev/null +++ b/man3p/swab.3p @@ -0,0 +1,60 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SWAB" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" swab +.SH NAME +swab \- swap bytes +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void swab(const void *restrict\fP \fIsrc\fP\fB, void *restrict\fP +\fIdest\fP\fB, +.br +\ \ \ \ \ \ ssize_t\fP \fInbytes\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIswab\fP() function shall copy \fInbytes\fP bytes, which are +pointed to by \fIsrc\fP, to the object pointed to by +\fIdest\fP, exchanging adjacent bytes. The \fInbytes\fP argument should +be even. If \fInbytes\fP is odd, \fIswab\fP() copies +and exchanges \fInbytes\fP-1 bytes and the disposition of the last +byte is unspecified. If copying takes place between objects +that overlap, the behavior is undefined. If \fInbytes\fP is negative, +\fIswab\fP() does nothing. +.SH RETURN VALUE +.LP +None. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/swapcontext.3p b/man3p/swapcontext.3p new file mode 100644 index 000000000..974f94a73 --- /dev/null +++ b/man3p/swapcontext.3p @@ -0,0 +1 @@ +.so man3p/makecontext.3p diff --git a/man3p/swprintf.3p b/man3p/swprintf.3p new file mode 100644 index 000000000..229818897 --- /dev/null +++ b/man3p/swprintf.3p @@ -0,0 +1 @@ +.so man3p/wprintf.3p diff --git a/man3p/swscanf.3p b/man3p/swscanf.3p new file mode 100644 index 000000000..672fbc26f --- /dev/null +++ b/man3p/swscanf.3p @@ -0,0 +1 @@ +.so man3p/wscanf.3p diff --git a/man3p/symlink.3p b/man3p/symlink.3p new file mode 100644 index 000000000..5515d2ed0 --- /dev/null +++ b/man3p/symlink.3p @@ -0,0 +1,126 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SYMLINK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" symlink +.SH NAME +symlink \- make a symbolic link to a file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int symlink(const char *\fP\fIpath1\fP\fB, const char *\fP\fIpath2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsymlink\fP() function shall create a symbolic link called \fIpath2\fP +that contains the string pointed to by +\fIpath1\fP ( \fIpath2\fP is the name of the symbolic link created, +\fIpath1\fP is the string contained in the symbolic +link). +.LP +The string pointed to by \fIpath1\fP shall be treated only as a character +string and shall not be validated as a pathname. +.LP +If the \fIsymlink\fP() function fails for any reason other than [EIO], +any file named by \fIpath2\fP shall be unaffected. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsymlink\fP() shall return 0; otherwise, +it shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fIsymlink\fP() function shall fail if: +.TP 7 +.B EACCES +Write permission is denied in the directory where the symbolic link +is being created, or search permission is denied for a +component of the path prefix of \fIpath2\fP. +.TP 7 +.B EEXIST +The \fIpath2\fP argument names an existing file or symbolic link. +.TP 7 +.B EIO +An I/O error occurs while reading from or writing to the file system. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath2\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath2\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX} or the length of the +\fIpath1\fP argument is longer than {SYMLINK_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath2\fP does not name an existing file or \fIpath2\fP +is an empty string. +.TP 7 +.B ENOSPC +The directory in which the entry for the new symbolic link is being +placed cannot be extended because no space is left on the +file system containing the directory, or the new symbolic link cannot +be created because no space is left on the file system which +shall contain the link, or the file system is out of file-allocation +resources. +.TP 7 +.B ENOTDIR +A component of the path prefix of \fIpath2\fP is not a directory. +.TP 7 +.B EROFS +The new symbolic link would reside on a read-only file system. +.sp +.LP +The \fIsymlink\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath2\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath2\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX} bytes (including the terminating null byte), +or the length of the string pointed to by \fIpath1\fP +exceeded {SYMLINK_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Like a hard link, a symbolic link allows a file to have multiple logical +names. The presence of a hard link guarantees the +existence of a file, even after the original name has been removed. +A symbolic link provides no such assurance; in fact, the file +named by the \fIpath1\fP argument need not exist when the link is +created. A symbolic link can cross file system boundaries. +.LP +Normal permission checks are made on each component of the symbolic +link pathname during its resolution. +.SH RATIONALE +.LP +Since IEEE\ Std\ 1003.1-2001 does not require any association of file +times with symbolic links, there is no requirement +that file times be updated by \fIsymlink\fP(). +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIlchown\fP() , \fIlink\fP() , \fIlstat\fP() , \fIopen\fP() , \fIreadlink\fP() +, \fIunlink\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sync.3p b/man3p/sync.3p new file mode 100644 index 000000000..c50756e74 --- /dev/null +++ b/man3p/sync.3p @@ -0,0 +1,56 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SYNC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sync +.SH NAME +sync \- schedule file system updates +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void sync(void); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsync\fP() function shall cause all information in memory that +updates file systems to be scheduled for writing out to +all file systems. +.LP +The writing, although scheduled, is not necessarily complete upon +return from \fIsync\fP(). +.SH RETURN VALUE +.LP +The \fIsync\fP() function shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfsync\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/sysconf.3p b/man3p/sysconf.3p new file mode 100644 index 000000000..a75cb6c8e --- /dev/null +++ b/man3p/sysconf.3p @@ -0,0 +1,308 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SYSCONF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" sysconf +.SH NAME +sysconf \- get configurable system variables +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +long sysconf(int\fP \fIname\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIsysconf\fP() function provides a method for the application +to determine the current value of a configurable system +limit or option ( \fIvariable\fP). The implementation shall support +all of the variables listed in the following table and may +support others. +.LP +The \fIname\fP argument represents the system variable to be queried. +The following table lists the minimal set of system +variables from \fI\fP or \fI\fP that can be returned +by \fIsysconf\fP(), and the symbolic constants +defined in \fI\fP that are the corresponding values used +for +\fIname\fP. +.TS C +center; l1 l. +\fBVariable\fP \fBValue of Name\fP +{AIO_LISTIO_MAX} _SC_AIO_LISTIO_MAX +{AIO_MAX} _SC_AIO_MAX +{AIO_PRIO_DELTA_MAX} _SC_AIO_PRIO_DELTA_MAX +{ARG_MAX} _SC_ARG_MAX +{ATEXIT_MAX} _SC_ATEXIT_MAX +{BC_BASE_MAX} _SC_BC_BASE_MAX +{BC_DIM_MAX} _SC_BC_DIM_MAX +{BC_SCALE_MAX} _SC_BC_SCALE_MAX +{BC_STRING_MAX} _SC_BC_STRING_MAX +{CHILD_MAX} _SC_CHILD_MAX +Clock ticks/second _SC_CLK_TCK +{COLL_WEIGHTS_MAX} _SC_COLL_WEIGHTS_MAX +{DELAYTIMER_MAX} _SC_DELAYTIMER_MAX +{EXPR_NEST_MAX} _SC_EXPR_NEST_MAX +{HOST_NAME_MAX} _SC_HOST_NAME_MAX +{IOV_MAX} _SC_IOV_MAX +{LINE_MAX} _SC_LINE_MAX +{LOGIN_NAME_MAX} _SC_LOGIN_NAME_MAX +{NGROUPS_MAX} _SC_NGROUPS_MAX +Maximum size of \fIgetgrgid_r\fP() and _SC_GETGR_R_SIZE_MAX +\fIgetgrnam_r\fP() data buffers \ +Maximum size of \fIgetpwuid_r\fP() and _SC_GETPW_R_SIZE_MAX +\fIgetpwnam_r\fP() data buffers \ +{MQ_OPEN_MAX} _SC_MQ_OPEN_MAX +{MQ_PRIO_MAX} _SC_MQ_PRIO_MAX +{OPEN_MAX} _SC_OPEN_MAX +_POSIX_ADVISORY_INFO _SC_ADVISORY_INFO +_POSIX_BARRIERS _SC_BARRIERS +_POSIX_ASYNCHRONOUS_IO _SC_ASYNCHRONOUS_IO +_POSIX_CLOCK_SELECTION _SC_CLOCK_SELECTION +_POSIX_CPUTIME _SC_CPUTIME +_POSIX_FILE_LOCKING _SC_FILE_LOCKING +_POSIX_FSYNC _SC_FSYNC +_POSIX_IPV6 _SC_IPV6 +_POSIX_JOB_CONTROL _SC_JOB_CONTROL +_POSIX_MAPPED_FILES _SC_MAPPED_FILES +_POSIX_MEMLOCK _SC_MEMLOCK +_POSIX_MEMLOCK_RANGE _SC_MEMLOCK_RANGE +_POSIX_MEMORY_PROTECTION _SC_MEMORY_PROTECTION +_POSIX_MESSAGE_PASSING _SC_MESSAGE_PASSING +_POSIX_MONOTONIC_CLOCK _SC_MONOTONIC_CLOCK +_POSIX_MULTI_PROCESS _SC_MULTI_PROCESS +_POSIX_PRIORITIZED_IO _SC_PRIORITIZED_IO +_POSIX_PRIORITY_SCHEDULING _SC_PRIORITY_SCHEDULING +_POSIX_RAW_SOCKETS _SC_RAW_SOCKETS +_POSIX_READER_WRITER_LOCKS _SC_READER_WRITER_LOCKS +_POSIX_REALTIME_SIGNALS _SC_REALTIME_SIGNALS +_POSIX_REGEXP _SC_REGEXP +_POSIX_SAVED_IDS _SC_SAVED_IDS +_POSIX_SEMAPHORES _SC_SEMAPHORES +_POSIX_SHARED_MEMORY_OBJECTS _SC_SHARED_MEMORY_OBJECTS +_POSIX_SHELL _SC_SHELL +_POSIX_SPAWN _SC_SPAWN +_POSIX_SPIN_LOCKS _SC_SPIN_LOCKS +_POSIX_SPORADIC_SERVER _SC_SPORADIC_SERVER +_POSIX_SYMLOOP_MAX _SC_SYMLOOP_MAX +_POSIX_SYNCHRONIZED_IO _SC_SYNCHRONIZED_IO +_POSIX_THREAD_ATTR_STACKADDR _SC_THREAD_ATTR_STACKADDR +_POSIX_THREAD_ATTR_STACKSIZE _SC_THREAD_ATTR_STACKSIZE +_POSIX_THREAD_CPUTIME _SC_THREAD_CPUTIME +_POSIX_THREAD_PRIO_INHERIT _SC_THREAD_PRIO_INHERIT +_POSIX_THREAD_PRIO_PROTECT _SC_THREAD_PRIO_PROTECT +_POSIX_THREAD_PRIORITY_SCHEDULING _SC_THREAD_PRIORITY_SCHEDULING +_POSIX_THREAD_PROCESS_SHARED _SC_THREAD_PROCESS_SHARED +_POSIX_THREAD_SAFE_FUNCTIONS _SC_THREAD_SAFE_FUNCTIONS +_POSIX_THREAD_SPORADIC_SERVER _SC_THREAD_SPORADIC_SERVER +_POSIX_THREADS _SC_THREADS +_POSIX_TIMEOUTS _SC_TIMEOUTS +_POSIX_TIMERS _SC_TIMERS +_POSIX_TRACE _SC_TRACE +_POSIX_TRACE_EVENT_FILTER _SC_TRACE_EVENT_FILTER +_POSIX_TRACE_INHERIT _SC_TRACE_INHERIT +_POSIX_TRACE_LOG _SC_TRACE_LOG +_POSIX_TYPED_MEMORY_OBJECTS _SC_TYPED_MEMORY_OBJECTS +_POSIX_VERSION _SC_VERSION +_POSIX_V6_ILP32_OFF32 _SC_V6_ILP32_OFF32 +_POSIX_V6_ILP32_OFFBIG _SC_V6_ILP32_OFFBIG +_POSIX_V6_LP64_OFF64 _SC_V6_LP64_OFF64 +_POSIX_V6_LPBIG_OFFBIG _SC_V6_LPBIG_OFFBIG +_POSIX2_C_BIND _SC_2_C_BIND +_POSIX2_C_DEV _SC_2_C_DEV +_POSIX2_C_VERSION _SC_2_C_VERSION +_POSIX2_CHAR_TERM _SC_2_CHAR_TERM +_POSIX2_FORT_DEV _SC_2_FORT_DEV +_POSIX2_FORT_RUN _SC_2_FORT_RUN +_POSIX2_LOCALEDEF _SC_2_LOCALEDEF +_POSIX2_PBS _SC_2_PBS +_POSIX2_PBS_ACCOUNTING _SC_2_PBS_ACCOUNTING +_POSIX2_PBS_CHECKPOINT _SC_2_PBS_CHECKPOINT +_POSIX2_PBS_LOCATE _SC_2_PBS_LOCATE +_POSIX2_PBS_MESSAGE _SC_2_PBS_MESSAGE +_POSIX2_PBS_TRACK _SC_2_PBS_TRACK +_POSIX2_SW_DEV _SC_2_SW_DEV +_POSIX2_UPE _SC_2_UPE +_POSIX2_VERSION _SC_2_VERSION +_REGEX_VERSION _SC_REGEX_VERSION +{PAGE_SIZE} _SC_PAGE_SIZE +{PAGESIZE} _SC_PAGESIZE +{PTHREAD_DESTRUCTOR_ITERATIONS} _SC_THREAD_DESTRUCTOR_ITERATIONS +{PTHREAD_KEYS_MAX} _SC_THREAD_KEYS_MAX +{PTHREAD_STACK_MIN} _SC_THREAD_STACK_MIN +{PTHREAD_THREADS_MAX} _SC_THREAD_THREADS_MAX +{RE_DUP_MAX} _SC_RE_DUP_MAX +{RTSIG_MAX} _SC_RTSIG_MAX +{SEM_NSEMS_MAX} _SC_SEM_NSEMS_MAX +{SEM_VALUE_MAX} _SC_SEM_VALUE_MAX +{SIGQUEUE_MAX} _SC_SIGQUEUE_MAX +{STREAM_MAX} _SC_STREAM_MAX +{SYMLOOP_MAX} _SC_SYMLOOP_MAX +{TIMER_MAX} _SC_TIMER_MAX +{TTY_NAME_MAX} _SC_TTY_NAME_MAX +{TZNAME_MAX} _SC_TZNAME_MAX +_XBS5_ILP32_OFF32 (\fBLEGACY\fP) _SC_XBS5_ILP32_OFF32 (\fBLEGACY\fP) +_XBS5_ILP32_OFFBIG (\fBLEGACY\fP) _SC_XBS5_ILP32_OFFBIG (\fBLEGACY\fP) +_XBS5_LP64_OFF64 (\fBLEGACY\fP) _SC_XBS5_LP64_OFF64 (\fBLEGACY\fP) +_XBS5_LPBIG_OFFBIG (\fBLEGACY\fP) _SC_XBS5_LPBIG_OFFBIG (\fBLEGACY\fP) +_XOPEN_CRYPT _SC_XOPEN_CRYPT +_XOPEN_ENH_I18N _SC_XOPEN_ENH_I18N +_XOPEN_LEGACY _SC_XOPEN_LEGACY +_XOPEN_REALTIME _SC_XOPEN_REALTIME +_XOPEN_REALTIME_THREADS _SC_XOPEN_REALTIME_THREADS +_XOPEN_SHM _SC_XOPEN_SHM +_XOPEN_STREAMS _SC_XOPEN_STREAMS +_XOPEN_UNIX _SC_XOPEN_UNIX +_XOPEN_VERSION _SC_XOPEN_VERSION +_XOPEN_XCU_VERSION _SC_XOPEN_XCU_VERSION +.TE +.SH RETURN VALUE +.LP +If \fIname\fP is an invalid value, \fIsysconf\fP() shall return -1 +and set \fIerrno\fP to indicate the error. If the variable +corresponding to \fIname\fP has no limit, \fIsysconf\fP() shall return +-1 without changing the value of \fIerrno\fP. Note that +indefinite limits do not imply infinite limits; see \fI\fP. +.LP +Otherwise, \fIsysconf\fP() shall return the current variable value +on the system. The value returned shall not be more +restrictive than the corresponding value described to the application +when it was compiled with the implementation's \fI\fP or +\fI\fP. The +value shall not change during the lifetime of the calling process, +\ except that \fIsysconf\fP(_SC_OPEN_MAX) may return different +values before and after a call to \fIsetrlimit\fP() which changes +the RLIMIT_NOFILE soft +limit. +.SH ERRORS +.LP +The \fIsysconf\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of the \fIname\fP argument is invalid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +As -1 is a permissible return value in a successful situation, an +application wishing to check for error situations should set +\fIerrno\fP to 0, then call \fIsysconf\fP(), and, if it returns -1, +check to see if \fIerrno\fP is non-zero. +.LP +If the value of \fIsysconf\fP(_SC_2_VERSION) is not equal to the value +of the _POSIX2_VERSION symbolic constant, the utilities +available via \fIsystem\fP() or \fIpopen\fP() might +not behave as described in the Shell and Utilities volume of IEEE\ Std\ 1003.1-2001. +This would mean that the application +is not running in an environment that conforms to the Shell and Utilities +volume of IEEE\ Std\ 1003.1-2001. Some +applications might be able to deal with this, others might not. However, +the functions defined in this volume of +IEEE\ Std\ 1003.1-2001 continue to operate as specified, even if \fIsysconf\fP(_SC_2_VERSION) +reports that the utilities +no longer perform as specified. +.SH RATIONALE +.LP +This functionality was added in response to requirements of application +developers and of system vendors who deal with many +international system configurations. It is closely related to \fIpathconf\fP() +and \fIfpathconf\fP(). +.LP +Although a conforming application can run on all systems by never +demanding more resources than the minimum values published in +this volume of IEEE\ Std\ 1003.1-2001, it is useful for that application +to be able to use the actual value for the +quantity of a resource available on any given system. To do this, +the application makes use of the value of a symbolic constant in +\fI\fP or \fI\fP. +.LP +However, once compiled, the application must still be able to cope +if the amount of resource available is increased. To that +end, an application may need a means of determining the quantity of +a resource, or the presence of an option, at execution +time. +.LP +Two examples are offered: +.IP " 1." 4 +Applications may wish to act differently on systems with or without +job control. Applications vendors who wish to distribute +only a single binary package to all instances of a computer architecture +would be forced to assume job control is never available +if it were to rely solely on the \fI\fP value published +in this volume of +IEEE\ Std\ 1003.1-2001. +.LP +.IP " 2." 4 +International applications vendors occasionally require knowledge +of the number of clock ticks per second. Without these +facilities, they would be required to either distribute their applications +partially in source form or to have 50 Hz and 60 Hz +versions for the various countries in which they operate. +.LP +.LP +It is the knowledge that many applications are actually distributed +widely in executable form that leads to this facility. If +limited to the most restrictive values in the headers, such applications +would have to be prepared to accept the most limited +environments offered by the smallest microcomputers. Although this +is entirely portable, there was a consensus that they should be +able to take advantage of the facilities offered by large systems, +without the restrictions associated with source and object +distributions. +.LP +During the discussions of this feature, it was pointed out that it +is almost always possible for an application to discern what +a value might be at runtime by suitably testing the various functions +themselves. And, in any event, it could always be written to +adequately deal with error returns from the various functions. In +the end, it was felt that this imposed an unreasonable level of +complication and sophistication on the application writer. +.LP +This runtime facility is not meant to provide ever-changing values +that applications have to check multiple times. The values +are seen as changing no more frequently than once per system initialization, +such as by a system administrator or operator with an +automatic configuration program. This volume of IEEE\ Std\ 1003.1-2001 +specifies that they shall not change within the +lifetime of the process. +.LP +Some values apply to the system overall and others vary at the file +system or directory level. The latter are described in \fIpathconf\fP() +\&. +.LP +Note that all values returned must be expressible as integers. String +values were considered, but the additional flexibility of +this approach was rejected due to its added complexity of implementation +and use. +.LP +Some values, such as {PATH_MAX}, are sometimes so large that they +must not be used to, say, allocate arrays. The +\fIsysconf\fP() function returns a negative value to show that this +symbolic constant is not even defined in this case. +.LP +Similar to \fIpathconf\fP(), this permits the implementation not to +have a limit. When +one resource is infinite, returning an error indicating that some +other resource limit has been reached is conforming behavior. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIconfstr\fP() , \fIpathconf\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP, the Shell +and Utilities volume of IEEE\ Std\ 1003.1-2001, \fIgetconf\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/syslog.3p b/man3p/syslog.3p new file mode 100644 index 000000000..043b748e9 --- /dev/null +++ b/man3p/syslog.3p @@ -0,0 +1,261 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CLOSELOG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" closelog +.SH NAME +closelog, openlog, setlogmask, syslog \- control system log +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void closelog(void); +.br +void openlog(const char *\fP\fIident\fP\fB, int\fP \fIlogopt\fP\fB, +int\fP \fIfacility\fP\fB); +.br +int setlogmask(int\fP \fImaskpri\fP\fB); +.br +void syslog(int\fP \fIpriority\fP\fB, const char *\fP\fImessage\fP\fB, +\&... /*\fP \fIarguments\fP \fB*/); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsyslog\fP() function shall send a message to an implementation-defined +logging facility, which may log it in an +implementation-defined system log, write it to the system console, +forward it to a list of users, or forward it to the logging +facility on another host over the network. The logged message shall +include a message header and a message body. The message header +contains at least a timestamp and a tag string. +.LP +The message body is generated from the \fImessage\fP and following +arguments in the same manner as if these were arguments to +\fIprintf\fP(), except that the additional conversion specification +\fB%m\fP shall be +recognized; it shall convert no arguments, shall cause the output +of the error message string associated with the value of +\fIerrno\fP on entry to \fIsyslog\fP(), and may be mixed with argument +specifications of the \fB"%\fP\fIn\fP\fB$"\fP form. +If a complete conversion specification with the \fBm\fP conversion +specifier character is not just \fB%m\fP , the behavior is +undefined. A trailing may be added if needed. +.LP +Values of the \fIpriority\fP argument are formed by OR'ing together +a severity-level value and an optional facility value. If +no facility value is specified, the current default facility value +is used. +.LP +Possible values of severity level include: +.TP 7 +LOG_EMERG +A panic condition. +.TP 7 +LOG_ALERT +A condition that should be corrected immediately, such as a corrupted +system database. +.TP 7 +LOG_CRIT +Critical conditions, such as hard device errors. +.TP 7 +LOG_ERR +Errors. +.TP 7 +LOG_WARNING +.sp +Warning messages. +.TP 7 +LOG_NOTICE +Conditions that are not error conditions, but that may require special +handling. +.TP 7 +LOG_INFO +Informational messages. +.TP 7 +LOG_DEBUG +Messages that contain information normally of use only when debugging +a program. +.sp +.LP +The facility indicates the application or system component generating +the message. Possible facility values include: +.TP 7 +LOG_USER +Messages generated by arbitrary processes. This is the default facility +identifier if none is specified. +.TP 7 +LOG_LOCAL0 +Reserved for local use. +.TP 7 +LOG_LOCAL1 +Reserved for local use. +.TP 7 +LOG_LOCAL2 +Reserved for local use. +.TP 7 +LOG_LOCAL3 +Reserved for local use. +.TP 7 +LOG_LOCAL4 +Reserved for local use. +.TP 7 +LOG_LOCAL5 +Reserved for local use. +.TP 7 +LOG_LOCAL6 +Reserved for local use. +.TP 7 +LOG_LOCAL7 +Reserved for local use. +.sp +.LP +The \fIopenlog\fP() function shall set process attributes that affect +subsequent calls to \fIsyslog\fP(). The \fIident\fP +argument is a string that is prepended to every message. The \fIlogopt\fP +argument indicates logging options. Values for +\fIlogopt\fP are constructed by a bitwise-inclusive OR of zero or +more of the following: +.TP 7 +LOG_PID +Log the process ID with each message. This is useful for identifying +specific processes. +.TP 7 +LOG_CONS +Write messages to the system console if they cannot be sent to the +logging facility. The \fIsyslog\fP() function ensures that +the process does not acquire the console as a controlling terminal +in the process of writing the message. +.TP 7 +LOG_NDELAY +Open the connection to the logging facility immediately. Normally +the open is delayed until the first message is logged. This +is useful for programs that need to manage the order in which file +descriptors are allocated. +.TP 7 +LOG_ODELAY +Delay open until \fIsyslog\fP() is called. +.TP 7 +LOG_NOWAIT +Do not wait for child processes that may have been created during +the course of logging the message. This option should be used +by processes that enable notification of child termination using SIGCHLD, +since \fIsyslog\fP() may otherwise block waiting for a +child whose exit status has already been collected. +.sp +.LP +The \fIfacility\fP argument encodes a default facility to be assigned +to all messages that do not have an explicit facility +already encoded. The initial default facility is LOG_USER. +.LP +The \fIopenlog\fP() and \fIsyslog\fP() functions may allocate a file +descriptor. It is not necessary to call \fIopenlog\fP() +prior to calling \fIsyslog\fP(). +.LP +The \fIcloselog\fP() function shall close any open file descriptors +allocated by previous calls to \fIopenlog\fP() or +\fIsyslog\fP(). +.LP +The \fIsetlogmask\fP() function shall set the log priority mask for +the current process to \fImaskpri\fP and return the +previous mask. If the \fImaskpri\fP argument is 0, the current log +mask is not modified. Calls by the current process to +\fIsyslog\fP() with a priority not set in \fImaskpri\fP shall be rejected. +The default log mask allows all priorities to be +logged. A call to \fIopenlog\fP() is not required prior to calling +\fIsetlogmask\fP(). +.LP +Symbolic constants for use as values of the \fIlogopt\fP, \fIfacility\fP, +\fIpriority\fP, and \fImaskpri\fP arguments are +defined in the \fI\fP header. +.SH RETURN VALUE +.LP +The \fIsetlogmask\fP() function shall return the previous log priority +mask. The \fIcloselog\fP(), \fIopenlog\fP(), and +\fIsyslog\fP() functions shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Using openlog() +.LP +The following example causes subsequent calls to \fIsyslog\fP() to +log the process ID with each message, and to write messages +to the system console if they cannot be sent to the logging facility. +.sp +.RS +.nf + +\fB#include +.sp + +char *ident = "Process demo"; +int logopt = LOG_PID | LOG_CONS; +int facility = LOG_USER; +\&... +openlog(ident, logopt, facility); +\fP +.fi +.RE +.SS Using setlogmask() +.LP +The following example causes subsequent calls to \fIsyslog\fP() to +accept error messages, and to reject all other messages. +.sp +.RS +.nf + +\fB#include +.sp + +int result; +int mask = LOG_MASK (LOG_ERR); +\&... +result = setlogmask(mask); +\fP +.fi +.RE +.SS Using syslog +.LP +The following example sends the message \fB"This is a message"\fP +to the default logging facility, marking the message as an +error message generated by random processes. +.sp +.RS +.nf + +\fB#include +.sp + +char *message = "This is a message"; +int priority = LOG_ERR | LOG_USER; +\&... +syslog(priority, message); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIprintf\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/system.3p b/man3p/system.3p new file mode 100644 index 000000000..b7d8243bc --- /dev/null +++ b/man3p/system.3p @@ -0,0 +1,315 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SYSTEM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" system +.SH NAME +system \- issue a command +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int system(const char *\fP\fIcommand\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If \fIcommand\fP is a null pointer, the \fIsystem\fP() function shall +determine whether the host environment has a command +processor. If \fIcommand\fP is not a null pointer, the \fIsystem\fP() +function shall pass the string pointed to by \fIcommand\fP +to that command processor to be executed in an implementation-defined +manner; this might then cause the program calling +\fIsystem\fP() to behave in a non-conforming manner or to terminate. +.LP +The +environment of the executed command shall be as if a child process +were created using \fIfork\fP(), and the child process invoked the +\fIsh\fP utility +using \fIexecl\fP() as follows: +.sp +.RS +.nf + +\fBexecl(<\fP\fIshell path\fP\fB>, "sh", "-c",\fP \fIcommand\fP\fB, (char *)0); +\fP +.fi +.RE +.LP +where <\fIshell path\fP> is an unspecified pathname for the \fIsh\fP +utility. +.LP +The \fIsystem\fP() function shall ignore the SIGINT and SIGQUIT signals, +and shall block the SIGCHLD signal, while waiting for +the command to terminate. If this might cause the application to miss +a signal that would have killed it, then the application +should examine the return value from \fIsystem\fP() and take whatever +action is appropriate to the application if the command +terminated due to receipt of a signal. +.LP +The \fIsystem\fP() function shall not affect the termination status +of any child of the calling processes other than the +process or processes it itself creates. +.LP +The \fIsystem\fP() function shall not return until the child process +has terminated. +.SH RETURN VALUE +.LP +If \fIcommand\fP is a null pointer, \fIsystem\fP() shall return non-zero +to indicate that a command processor is available, or +zero if none is available. The \fIsystem\fP() function shall always +return non-zero when \fIcommand\fP is NULL. +.LP +If +\fIcommand\fP is not a null pointer, \fIsystem\fP() shall return the +termination status of the command language interpreter in +the format specified by \fIwaitpid\fP(). The termination status shall +be as defined for +the \fIsh\fP utility; otherwise, the termination status is unspecified. +If some error prevents +the command language interpreter from executing after the child process +is created, the return value from \fIsystem\fP() shall be +as if the command language interpreter had terminated using \fIexit\fP(127) +or \fI_exit\fP(127). If a child process cannot be +created, or if the termination status for the command language interpreter +cannot be obtained, \fIsystem\fP() shall return -1 and +set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The +\fIsystem\fP() function may set \fIerrno\fP values as described by +\fIfork\fP() . +.LP +In addition, \fIsystem\fP() may fail if: +.TP 7 +.B ECHILD +The status of the child process created by \fIsystem\fP() is no longer +available. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +If the return value of \fIsystem\fP() is not -1, its value can be +decoded through the use of the macros described in \fI\fP. +For convenience, these macros are also provided in \fI\fP. +.LP +Note that, while \fIsystem\fP() must ignore SIGINT and SIGQUIT and +block SIGCHLD while waiting for the child to terminate, the +handling of signals in the executed command is as specified by \fIfork\fP() +and \fIexec\fP. For example, if SIGINT is being caught or is set to +SIG_DFL when \fIsystem\fP() is called, +then the child is started with SIGINT handling set to SIG_DFL. +.LP +Ignoring SIGINT and SIGQUIT in the parent process prevents coordination +problems (two processes reading from the same terminal, +for example) when the executed command ignores or catches one of the +signals. It is also usually the correct action when the user +has given a command to the application to be executed synchronously +(as in the \fB'!'\fP command in many interactive +applications). In either case, the signal should be delivered only +to the child process, not to the application itself. There is +one situation where ignoring the signals might have less than the +desired effect. This is when the application uses \fIsystem\fP() +to perform some task invisible to the user. If the user typed the +interrupt character ( \fB"^C"\fP , for example) while +\fIsystem\fP() is being used in this way, one would expect the application +to be killed, but only the executed command is killed. +Applications that use \fIsystem\fP() in this way should carefully +check the return status from \fIsystem\fP() to see if the +executed command was successful, and should take appropriate action +when the command fails. +.LP +Blocking SIGCHLD while waiting for the child to terminate prevents +the application from catching the signal and obtaining status +from \fIsystem\fP()'s child process before \fIsystem\fP() can get +the status itself. +.LP +The context in which the utility is ultimately executed may differ +from that in which \fIsystem\fP() was called. For example, +file descriptors that have the FD_CLOEXEC flag set are closed, and +the process ID and parent process ID are different. Also, if the +executed utility changes its environment variables or its current +working directory, that change is not reflected in the caller's +context. +.LP +There is no defined way for an application to find the specific path +for the shell. However, \fIconfstr\fP() can provide a value for \fIPATH\fP +that is guaranteed to find the \fIsh\fP utility. +.SH RATIONALE +.LP +The \fIsystem\fP() function should not be used by programs that have +set user (or group) ID privileges. The \fIfork\fP() and \fIexec\fP +family of functions (except \fIexeclp\fP() and \fIexecvp\fP()), should +be used +instead. This prevents any unforeseen manipulation of the environment +of the user that could cause execution of commands not +anticipated by the calling program. +.LP +There are three levels of specification for the \fIsystem\fP() function. +The ISO\ C standard gives the most basic. It +requires that the function exists, and defines a way for an application +to query whether a command language interpreter exists. It +says nothing about the command language or the environment in which +the command is interpreted. +.LP +IEEE\ Std\ 1003.1-2001 places additional restrictions on \fIsystem\fP(). +It requires that if there is a command +language interpreter, the environment must be as specified by \fIfork\fP() +and \fIexec\fP. This ensures, for example, that close-on- \fIexec\fP +works, that file locks are not inherited, and that the process ID +is different. It also specifies the return value from +\fIsystem\fP() when the command line can be run, thus giving the application +some information about the command's completion +status. +.LP +Finally, IEEE\ Std\ 1003.1-2001 requires the command to be interpreted +as in the shell command language defined in the +Shell and Utilities volume of IEEE\ Std\ 1003.1-2001. +.LP +Note that, \fIsystem\fP(NULL) is required to return non-zero, indicating +that there is a command language interpreter. At first +glance, this would seem to conflict with the ISO\ C standard which +allows \fIsystem\fP(NULL) to return zero. There is no +conflict, however. A system must have a command language interpreter, +and is non-conforming if none is present. It is therefore +permissible for the \fIsystem\fP() function on such a system to implement +the behavior specified by the ISO\ C standard as +long as it is understood that the implementation does not conform +to IEEE\ Std\ 1003.1-2001 if \fIsystem\fP(NULL) returns +zero. +.LP +It was explicitly decided that when \fIcommand\fP is NULL, \fIsystem\fP() +should not be required to check to make sure that +the command language interpreter actually exists with the correct +mode, that there are enough processes to execute it, and so on. +The call \fIsystem\fP(NULL) could, theoretically, check for such problems +as too many existing child processes, and return zero. +However, it would be inappropriate to return zero due to such a (presumably) +transient condition. If some condition exists that is +not under the control of this application and that would cause any +\fIsystem\fP() call to fail, that system has been rendered +non-conforming. +.LP +Early drafts required, or allowed, \fIsystem\fP() to return with \fIerrno\fP +set to [EINTR] if it was interrupted with a +signal. This error return was removed, and a requirement that \fIsystem\fP() +not return until the child has terminated was added. +This means that if a \fIwaitpid\fP() call in \fIsystem\fP() exits +with \fIerrno\fP set +to [EINTR], \fIsystem\fP() must reissue the \fIwaitpid\fP(). This +change was made for two +reasons: +.IP " 1." 4 +There is no way for an application to clean up if \fIsystem\fP() returns +[EINTR], short of calling \fIwait\fP(), and that could have the undesirable +effect of returning the status of children other +than the one started by \fIsystem\fP(). +.LP +.IP " 2." 4 +While it might require a change in some historical implementations, +those implementations already have to be changed because +they use \fIwait\fP() instead of \fIwaitpid\fP(). +.LP +.LP +Note that if the application is catching SIGCHLD signals, it will +receive such a signal before a successful \fIsystem\fP() call +returns. +.LP +To conform to IEEE\ Std\ 1003.1-2001, \fIsystem\fP() must use \fIwaitpid\fP(), +or some similar function, instead of \fIwait\fP(). +.LP +The following code sample illustrates how \fIsystem\fP() might be +implemented on an implementation conforming to +IEEE\ Std\ 1003.1-2001. +.sp +.RS +.nf + +\fB#include +int system(const char *cmd) +{ + int stat; + pid_t pid; + struct sigaction sa, savintr, savequit; + sigset_t saveblock; + if (cmd == NULL) + return(1); + sa.sa_handler = SIG_IGN; + sigemptyset(&sa.sa_mask); + sa.sa_flags = 0; + sigemptyset(&savintr.sa_mask); + sigemptyset(&savequit.sa_mask); + sigaction(SIGINT, &sa, &savintr); + sigaction(SIGQUIT, &sa, &savequit); + sigaddset(&sa.sa_mask, SIGCHLD); + sigprocmask(SIG_BLOCK, &sa.sa_mask, &saveblock); + if ((pid = fork()) == 0) { + sigaction(SIGINT, &savintr, (struct sigaction *)0); + sigaction(SIGQUIT, &savequit, (struct sigaction *)0); + sigprocmask(SIG_SETMASK, &saveblock, (sigset_t *)0); + execl("/bin/sh", "sh", "-c", cmd, (char *)0); + _exit(127); + } + if (pid == -1) { + stat = -1; /* errno comes from fork() */ + } else { + while (waitpid(pid, &stat, 0) == -1) { + if (errno != EINTR){ + stat = -1; + break; + } + } + } + sigaction(SIGINT, &savintr, (struct sigaction *)0); + sigaction(SIGQUIT, &savequit, (struct sigaction *)0); + sigprocmask(SIG_SETMASK, &saveblock, (sigset_t *)0); + return(stat); +} +\fP +.fi +.RE +.LP +Note that, while a particular implementation of \fIsystem\fP() (such +as the one above) can assume a particular path for the +shell, such a path is not necessarily valid on another system. The +above example is not portable, and is not intended to be. +.LP +One reviewer suggested that an implementation of \fIsystem\fP() might +want to use an environment variable such as \fISHELL\fP +to determine which command interpreter to use. The supposed implementation +would use the default command interpreter if the one +specified by the environment variable was not available. This would +allow a user, when using an application that prompts for +command lines to be processed using \fIsystem\fP(), to specify a different +command interpreter. Such an implementation is +discouraged. If the alternate command interpreter did not follow the +command line syntax specified in the Shell and Utilities +volume of IEEE\ Std\ 1003.1-2001, then changing \fISHELL\fP would +render \fIsystem\fP() non-conforming. This would affect +applications that expected the specified behavior from \fIsystem\fP(), +and since the Shell and Utilities volume of +IEEE\ Std\ 1003.1-2001 does not mention that \fISHELL\fP affects \fIsystem\fP(), +the application would not know that it +needed to unset \fISHELL .\fP +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIpipe\fP() , \fIwaitpid\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP, +\fI\fP, \fI\fP, the +Shell and Utilities volume of IEEE\ Std\ 1003.1-2001, \fIsh\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tan.3p b/man3p/tan.3p new file mode 100644 index 000000000..153cf5154 --- /dev/null +++ b/man3p/tan.3p @@ -0,0 +1,144 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TAN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tan +.SH NAME +tan, tanf, tanl \- tangent function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double tan(double\fP \fIx\fP\fB); +.br +float tanf(float\fP \fIx\fP\fB); +.br +long double tanl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the tangent of their argument \fIx\fP, +measured in radians. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the tangent +of \fIx\fP. +.LP +If the correct value would cause underflow, and is not representable, +a range error may occur, and \ either 0.0 (if +supported), or \ an implementation-defined value shall be +returned. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, \fIx\fP shall be returned. +.LP +If \fIx\fP is subnormal, a range error may occur and \fIx\fP should +be returned. +.LP +If \fIx\fP is \(+-Inf, a domain error shall occur, and either a NaN +(if supported), or an implementation-defined value +shall be returned. +.LP +If the correct value would cause underflow, and is representable, +a range error may occur and the correct value shall be +returned. +.LP +If the correct value would cause overflow, a range error shall occur +and \fItan\fP(), \fItanf\fP(), and \fItanl\fP() shall +return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL, respectively, +with the same sign as the correct value of the +function. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The value of \fIx\fP is \(+-Inf. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be raised. +.TP 7 +Range\ Error +The result overflows +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be raised. +.sp +.LP +These functions may fail if: +.TP 7 +Range\ Error +The result underflows, \ or the value of \fIx\fP is subnormal. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Taking the Tangent of a 45-Degree Angle +.sp +.RS +.nf + +\fB#include +\&... +double radians = 45.0 * M_PI / 180; +double result; +\&... +result = tan (radians); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +There are no known floating-point representations such that for a +normal argument, \fItan\fP( \fIx\fP) is either overflow or +underflow. +.LP +These functions may lose accuracy when their argument is near a multiple +of pi/2 or is far +from 0.0. +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIatan\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tanf.3p b/man3p/tanf.3p new file mode 100644 index 000000000..d38ba0566 --- /dev/null +++ b/man3p/tanf.3p @@ -0,0 +1 @@ +.so man3p/tan.3p diff --git a/man3p/tanh.3p b/man3p/tanh.3p new file mode 100644 index 000000000..2b15103e1 --- /dev/null +++ b/man3p/tanh.3p @@ -0,0 +1,87 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TANH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tanh +.SH NAME +tanh, tanhf, tanhl \- hyperbolic tangent functions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double tanh(double\fP \fIx\fP\fB); +.br +float tanhf(float\fP \fIx\fP\fB); +.br +long double tanhl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the hyperbolic tangent of their argument +\fIx\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the hyperbolic +tangent of \fIx\fP. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0, \fIx\fP shall be returned. +.LP +If \fIx\fP is \(+-Inf, \(+-1 shall be returned. +.LP +If \fIx\fP is subnormal, a range error may occur and \fIx\fP should +be returned. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +Range\ Error +The value of \fIx\fP is subnormal. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIatanh\fP() , \fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() +, \fItan\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tanhf.3p b/man3p/tanhf.3p new file mode 100644 index 000000000..d7797f292 --- /dev/null +++ b/man3p/tanhf.3p @@ -0,0 +1 @@ +.so man3p/tanh.3p diff --git a/man3p/tanhl.3p b/man3p/tanhl.3p new file mode 100644 index 000000000..d7797f292 --- /dev/null +++ b/man3p/tanhl.3p @@ -0,0 +1 @@ +.so man3p/tanh.3p diff --git a/man3p/tanl.3p b/man3p/tanl.3p new file mode 100644 index 000000000..d38ba0566 --- /dev/null +++ b/man3p/tanl.3p @@ -0,0 +1 @@ +.so man3p/tan.3p diff --git a/man3p/tcdrain.3p b/man3p/tcdrain.3p new file mode 100644 index 000000000..bc3f409c9 --- /dev/null +++ b/man3p/tcdrain.3p @@ -0,0 +1,78 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TCDRAIN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tcdrain +.SH NAME +tcdrain \- wait for transmission of output +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int tcdrain(int\fP \fIfildes\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fItcdrain\fP() function shall block until all output written +to the object referred to by \fIfildes\fP is transmitted. +The \fIfildes\fP argument is an open file descriptor associated with +a terminal. +.LP +Any attempts to use \fItcdrain\fP() from a process which is a member +of a background process group on a \fIfildes\fP +associated with its controlling terminal, shall cause the process +group to be sent a SIGTTOU signal. If the calling process is +blocking or ignoring SIGTTOU signals, the process shall be allowed +to perform the operation, and no signal is sent. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fItcdrain\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B EINTR +A signal interrupted \fItcdrain\fP(). +.TP 7 +.B ENOTTY +The file associated with \fIfildes\fP is not a terminal. +.sp +.LP +The \fItcdrain\fP() function may fail if: +.TP 7 +.B EIO +The process group of the writing process is orphaned, and the writing +process is not ignoring or blocking SIGTTOU. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fItcflush\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 11, General Terminal Interface, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tcflow.3p b/man3p/tcflow.3p new file mode 100644 index 000000000..089b533ec --- /dev/null +++ b/man3p/tcflow.3p @@ -0,0 +1,98 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TCFLOW" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tcflow +.SH NAME +tcflow \- suspend or restart the transmission or reception of data +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int tcflow(int\fP \fIfildes\fP\fB, int\fP \fIaction\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fItcflow\fP() function shall suspend or restart transmission +or reception of data on the object referred to by +\fIfildes\fP, depending on the value of \fIaction\fP. The \fIfildes\fP +argument is an open file descriptor associated with a +terminal. +.IP " *" 3 +If \fIaction\fP is TCOOFF, output shall be suspended. +.LP +.IP " *" 3 +If \fIaction\fP is TCOON, suspended output shall be restarted. +.LP +.IP " *" 3 +If \fIaction\fP is TCIOFF, the system shall transmit a STOP character, +which is intended to cause the terminal device to stop +transmitting data to the system. +.LP +.IP " *" 3 +If \fIaction\fP is TCION, the system shall transmit a START character, +which is intended to cause the terminal device to start +transmitting data to the system. +.LP +.LP +The default on the opening of a terminal file is that neither its +input nor its output are suspended. +.LP +Attempts to use \fItcflow\fP() from a process which is a member of +a background process group on a \fIfildes\fP associated +with its controlling terminal, shall cause the process group to be +sent a SIGTTOU signal. If the calling process is blocking or +ignoring SIGTTOU signals, the process shall be allowed to perform +the operation, and no signal is sent. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fItcflow\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B EINVAL +The \fIaction\fP argument is not a supported value. +.TP 7 +.B ENOTTY +The file associated with \fIfildes\fP is not a terminal. +.sp +.LP +The \fItcflow\fP() function may fail if: +.TP 7 +.B EIO +The process group of the writing process is orphaned, and the writing +process is not ignoring or blocking SIGTTOU. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fItcsendbreak\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 11, General Terminal Interface, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tcflush.3p b/man3p/tcflush.3p new file mode 100644 index 000000000..20f42321c --- /dev/null +++ b/man3p/tcflush.3p @@ -0,0 +1,92 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TCFLUSH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tcflush +.SH NAME +tcflush \- flush non-transmitted output data, non-read input data, +or both +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int tcflush(int\fP \fIfildes\fP\fB, int\fP \fIqueue_selector\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +Upon successful completion, \fItcflush\fP() shall discard data written +to the object referred to by \fIfildes\fP (an open file +descriptor associated with a terminal) but not transmitted, or data +received but not read, depending on the value of +\fIqueue_selector\fP: +.IP " *" 3 +If \fIqueue_selector\fP is TCIFLUSH, it shall flush data received +but not read. +.LP +.IP " *" 3 +If \fIqueue_selector\fP is TCOFLUSH, it shall flush data written but +not transmitted. +.LP +.IP " *" 3 +If \fIqueue_selector\fP is TCIOFLUSH, it shall flush both data received +but not read and data written but not transmitted. +.LP +.LP +Attempts to use \fItcflush\fP() from a process which is a member of +a background process group on a \fIfildes\fP associated +with its controlling terminal shall cause the process group to be +sent a SIGTTOU signal. If the calling process is blocking or +ignoring SIGTTOU signals, the process shall be allowed to perform +the operation, and no signal is sent. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fItcflush\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B EINVAL +The \fIqueue_selector\fP argument is not a supported value. +.TP 7 +.B ENOTTY +The file associated with \fIfildes\fP is not a terminal. +.sp +.LP +The \fItcflush\fP() function may fail if: +.TP 7 +.B EIO +The process group of the writing process is orphaned, and the writing +process is not ignoring or blocking SIGTTOU. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fItcdrain\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 11, General Terminal Interface, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tcgetattr.3p b/man3p/tcgetattr.3p new file mode 100644 index 000000000..cd2253720 --- /dev/null +++ b/man3p/tcgetattr.3p @@ -0,0 +1,109 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TCGETATTR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tcgetattr +.SH NAME +tcgetattr \- get the parameters associated with the terminal +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int tcgetattr(int\fP \fIfildes\fP\fB, struct termios *\fP\fItermios_p\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fItcgetattr\fP() function shall get the parameters associated +with the terminal referred to by \fIfildes\fP and store +them in the \fBtermios\fP structure referenced by \fItermios_p\fP. +The \fIfildes\fP argument is an open file descriptor +associated with a terminal. +.LP +The \fItermios_p\fP argument is a pointer to a \fBtermios\fP structure. +.LP +The \fItcgetattr\fP() operation is allowed from any process. +.LP +If the terminal device supports different input and output baud rates, +the baud rates stored in the \fBtermios\fP structure +returned by \fItcgetattr\fP() shall reflect the actual baud rates, +even if they are equal. If differing baud rates are not +supported, the rate returned as the output baud rate shall be the +actual baud rate. If the terminal device does not support split +baud rates, the input baud rate stored in the \fBtermios\fP structure +shall be the output rate (as one of the symbolic +values). +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fItcgetattr\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B ENOTTY +The file associated with \fIfildes\fP is not a terminal. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Care must be taken when changing the terminal attributes. Applications +should always do a \fItcgetattr\fP(), save the +\fBtermios\fP structure values returned, and then do a \fItcsetattr\fP(), +changing only +the necessary fields. The application should use the values saved +from the \fItcgetattr\fP() to reset the terminal state whenever +it is done with the terminal. This is necessary because terminal attributes +apply to the underlying port and not to each individual +open instance; that is, all processes that have used the terminal +see the latest attribute changes. +.LP +A program that uses these functions should be written to catch all +signals and take other appropriate actions to ensure that +when the program terminates, whether planned or not, the terminal +device's state is restored to its original state. +.LP +Existing practice dealing with error returns when only part of a request +can be honored is based on calls to the \fIioctl\fP() function. In +historical BSD and System V implementations, the corresponding \fIioctl\fP() +returns zero if the requested actions were semantically correct, even +if some of the +requested changes could not be made. Many existing applications assume +this behavior and would no longer work correctly if the +return value were changed from zero to -1 in this case. +.LP +Note that either specification has a problem. When zero is returned, +it implies everything succeeded even if some of the changes +were not made. When -1 is returned, it implies everything failed even +though some of the changes were made. +.LP +Applications that need all of the requested changes made to work properly +should follow \fItcsetattr\fP() with a call to \fItcgetattr\fP() and +compare the appropriate field +values. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fItcsetattr\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 11, General Terminal Interface, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tcgetpgrp.3p b/man3p/tcgetpgrp.3p new file mode 100644 index 000000000..1c02f934a --- /dev/null +++ b/man3p/tcgetpgrp.3p @@ -0,0 +1,72 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TCGETPGRP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tcgetpgrp +.SH NAME +tcgetpgrp \- get the foreground process group ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +pid_t tcgetpgrp(int\fP \fIfildes\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fItcgetpgrp\fP() function shall return the value of the process +group ID of the foreground process group associated with +the terminal. +.LP +If there is no foreground process group, \fItcgetpgrp\fP() shall return +a value greater than 1 that does not match the process +group ID of any existing process group. +.LP +The \fItcgetpgrp\fP() function is allowed from a process that is a +member of a background process group; however, the +information may be subsequently changed by a process that is a member +of a foreground process group. +.SH RETURN VALUE +.LP +Upon successful completion, \fItcgetpgrp\fP() shall return the value +of the process group ID of the foreground process +associated with the terminal. Otherwise, -1 shall be returned and +\fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fItcgetpgrp\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B ENOTTY +The calling process does not have a controlling terminal, or the file +is not the controlling terminal. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsetsid\fP() , \fIsetpgid\fP() , \fItcsetpgrp\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tcgetsid.3p b/man3p/tcgetsid.3p new file mode 100644 index 000000000..48de214f9 --- /dev/null +++ b/man3p/tcgetsid.3p @@ -0,0 +1,64 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TCGETSID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tcgetsid +.SH NAME +tcgetsid \- get the process group ID for the session leader for the +controlling terminal +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +pid_t tcgetsid(int\fP \fIfildes\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fItcgetsid\fP() function shall obtain the process group ID of +the session for which the terminal specified by +\fIfildes\fP is the controlling terminal. +.SH RETURN VALUE +.LP +Upon successful completion, \fItcgetsid\fP() shall return the process +group ID associated with the terminal. Otherwise, a value +of (\fBpid_t\fP)-1 shall be returned and \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +The \fItcgetsid\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B ENOTTY +The calling process does not have a controlling terminal, or the file +is not the controlling terminal. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tcsendbreak.3p b/man3p/tcsendbreak.3p new file mode 100644 index 000000000..eabfe3e88 --- /dev/null +++ b/man3p/tcsendbreak.3p @@ -0,0 +1,87 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TCSENDBREAK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tcsendbreak +.SH NAME +tcsendbreak \- send a break for a specific duration +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int tcsendbreak(int\fP \fIfildes\fP\fB, int\fP \fIduration\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If the terminal is using asynchronous serial data transmission, \fItcsendbreak\fP() +shall cause transmission of a continuous +stream of zero-valued bits for a specific duration. If \fIduration\fP +is 0, it shall cause transmission of zero-valued bits for at +least 0.25 seconds, and not more than 0.5 seconds. If \fIduration\fP +is not 0, it shall send zero-valued bits for an +implementation-defined period of time. +.LP +The \fIfildes\fP argument is an open file descriptor associated with +a terminal. +.LP +If the terminal is not using asynchronous serial data transmission, +it is implementation-defined whether \fItcsendbreak\fP() +sends data to generate a break condition or returns without taking +any action. +.LP +Attempts to use \fItcsendbreak\fP() from a process which is a member +of a background process group on a \fIfildes\fP +associated with its controlling terminal shall cause the process group +to be sent a SIGTTOU signal. If the calling process is +blocking or ignoring SIGTTOU signals, the process shall be allowed +to perform the operation, and no signal is sent. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fItcsendbreak\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B ENOTTY +The file associated with \fIfildes\fP is not a terminal. +.sp +.LP +The \fItcsendbreak\fP() function may fail if: +.TP 7 +.B EIO +The process group of the writing process is orphaned, and the writing +process is not ignoring or blocking SIGTTOU. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 11, +General +Terminal Interface, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tcsetattr.3p b/man3p/tcsetattr.3p new file mode 100644 index 000000000..1a6b9131e --- /dev/null +++ b/man3p/tcsetattr.3p @@ -0,0 +1,159 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TCSETATTR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tcsetattr +.SH NAME +tcsetattr \- set the parameters associated with the terminal +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int tcsetattr(int\fP \fIfildes\fP\fB, int\fP \fIoptional_actions\fP\fB, +.br +\ \ \ \ \ \ const struct termios *\fP\fItermios_p\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fItcsetattr\fP() function shall set the parameters associated +with the terminal referred to by the open file descriptor +\fIfildes\fP (an open file descriptor associated with a terminal) +from the \fBtermios\fP structure referenced by \fItermios_p\fP +as follows: +.IP " *" 3 +If \fIoptional_actions\fP is TCSANOW, the change shall occur immediately. +.LP +.IP " *" 3 +If \fIoptional_actions\fP is TCSADRAIN, the change shall occur after +all output written to \fIfildes\fP is transmitted. This +function should be used when changing parameters that affect output. +.LP +.IP " *" 3 +If \fIoptional_actions\fP is TCSAFLUSH, the change shall occur after +all output written to \fIfildes\fP is transmitted, and +all input so far received but not read shall be discarded before the +change is made. +.LP +.LP +If the output baud rate stored in the \fBtermios\fP structure pointed +to by \fItermios_p\fP is the zero baud rate, B0, the +modem control lines shall no longer be asserted. Normally, this shall +disconnect the line. +.LP +If the input baud rate stored in the \fBtermios\fP structure pointed +to by \fItermios_p\fP is 0, the input baud rate given to +the hardware is the same as the output baud rate stored in the \fBtermios\fP +structure. +.LP +The \fItcsetattr\fP() function shall return successfully if it was +able to perform any of the requested actions, even if some +of the requested actions could not be performed. It shall set all +the attributes that the implementation supports as requested and +leave all the attributes not supported by the implementation unchanged. +If no part of the request can be honored, it shall return +-1 and set \fIerrno\fP to [EINVAL]. If the input and output baud rates +differ and are a combination that is not supported, neither +baud rate shall be changed. A subsequent call to \fItcgetattr\fP() +shall return the +actual state of the terminal device (reflecting both the changes made +and not made in the previous \fItcsetattr\fP() call). The +\fItcsetattr\fP() function shall not change the values found in the +\fBtermios\fP structure under any circumstances. +.LP +The effect of \fItcsetattr\fP() is undefined if the value of the \fBtermios\fP +structure pointed to by \fItermios_p\fP was +not derived from the result of a call to \fItcgetattr\fP() on \fIfildes\fP; +an +application should modify only fields and flags defined by this volume +of IEEE\ Std\ 1003.1-2001 between the call to \fItcgetattr\fP() and +\fItcsetattr\fP(), leaving all other fields and flags +unmodified. +.LP +No actions defined by this volume of IEEE\ Std\ 1003.1-2001, other +than a call to \fItcsetattr\fP() or a close of the +last file descriptor in the system associated with this terminal device, +shall cause any of the terminal attributes defined by this +volume of IEEE\ Std\ 1003.1-2001 to change. +.LP +If \fItcsetattr\fP() is called from a process which is a member of +a background process group on a \fIfildes\fP associated +with its controlling terminal: +.IP " *" 3 +If the calling process is blocking or ignoring SIGTTOU signals, the +operation completes normally and no signal is sent. +.LP +.IP " *" 3 +Otherwise, a SIGTTOU signal shall be sent to the process group. +.LP +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fItcsetattr\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B EINTR +A signal interrupted \fItcsetattr\fP(). +.TP 7 +.B EINVAL +The \fIoptional_actions\fP argument is not a supported value, or an +attempt was made to change an attribute represented in the +\fBtermios\fP structure to an unsupported value. +.TP 7 +.B ENOTTY +The file associated with \fIfildes\fP is not a terminal. +.sp +.LP +The \fItcsetattr\fP() function may fail if: +.TP 7 +.B EIO +The process group of the writing process is orphaned, and the writing +process is not ignoring or blocking SIGTTOU. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +If trying to change baud rates, applications should call \fItcsetattr\fP() +then call \fItcgetattr\fP() in order to determine what baud rates +were actually selected. +.SH RATIONALE +.LP +The \fItcsetattr\fP() function can be interrupted in the following +situations: +.IP " *" 3 +It is interrupted while waiting for output to drain. +.LP +.IP " *" 3 +It is called from a process in a background process group and SIGTTOU +is caught. +.LP +.LP +See also the RATIONALE section in \fItcgetattr\fP() . +.SH FUTURE DIRECTIONS +.LP +Using an input baud rate of 0 to set the input rate equal to the output +rate may not necessarily be supported in a future +version of this volume of IEEE\ Std\ 1003.1-2001. +.SH SEE ALSO +.LP +\fIcfgetispeed\fP() , \fItcgetattr\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General Terminal Interface, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tcsetpgrp.3p b/man3p/tcsetpgrp.3p new file mode 100644 index 000000000..2a6050bd8 --- /dev/null +++ b/man3p/tcsetpgrp.3p @@ -0,0 +1,84 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TCSETPGRP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tcsetpgrp +.SH NAME +tcsetpgrp \- set the foreground process group ID +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int tcsetpgrp(int\fP \fIfildes\fP\fB, pid_t\fP \fIpgid_id\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If the process has a controlling terminal, \fItcsetpgrp\fP() shall +set the foreground process group ID associated with the +terminal to \fIpgid_id\fP. The application shall ensure that the file +associated with \fIfildes\fP is the controlling terminal of +the calling process and the controlling terminal is currently associated +with the session of the calling process. The application +shall ensure that the value of \fIpgid_id\fP matches a process group +ID of a process in the same session as the calling +process. +.LP +Attempts to use \fItcsetpgrp\fP() from a process which is a member +of a background process group on a \fIfildes\fP associated +with its controlling terminal shall cause the process group to be +sent a SIGTTOU signal. If the calling process is blocking or +ignoring SIGTTOU signals, the process shall be allowed to perform +the operation, and no signal is sent. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fItcsetpgrp\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B EINVAL +This implementation does not support the value in the \fIpgid_id\fP +argument. +.TP 7 +.B ENOTTY +The calling process does not have a controlling terminal, or the file +is not the controlling terminal, or the controlling +terminal is no longer associated with the session of the calling process. +.TP 7 +.B EPERM +The value of \fIpgid_id\fP is a value supported by the implementation, +but does not match the process group ID of a process in +the same session as the calling process. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fItcgetpgrp\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tdelete.3p b/man3p/tdelete.3p new file mode 100644 index 000000000..e706cafc8 --- /dev/null +++ b/man3p/tdelete.3p @@ -0,0 +1 @@ +.so man3p/tsearch.3p diff --git a/man3p/telldir.3p b/man3p/telldir.3p new file mode 100644 index 000000000..710219853 --- /dev/null +++ b/man3p/telldir.3p @@ -0,0 +1,59 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TELLDIR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" telldir +.SH NAME +telldir \- current location of a named directory stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +long telldir(DIR *\fP\fIdirp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fItelldir\fP() function shall obtain the current location associated +with the directory stream specified by +\fIdirp\fP. +.LP +If the most recent operation on the directory stream was a \fIseekdir\fP(), +the +directory position returned from the \fItelldir\fP() shall be the +same as that supplied as a \fIloc\fP argument for \fIseekdir\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, \fItelldir\fP() shall return the current +location of the specified directory stream. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIopendir\fP() , \fIreaddir\fP() , \fIseekdir\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tempnam.3p b/man3p/tempnam.3p new file mode 100644 index 000000000..3ad869a53 --- /dev/null +++ b/man3p/tempnam.3p @@ -0,0 +1,109 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TEMPNAM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tempnam +.SH NAME +tempnam \- create a name for a temporary file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *tempnam(const char *\fP\fIdir\fP\fB, const char *\fP\fIpfx\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fItempnam\fP() function shall generate a pathname that may be +used for a temporary file. +.LP +The \fItempnam\fP() function allows the user to control the choice +of a directory. The \fIdir\fP argument points to the name +of the directory in which the file is to be created. If \fIdir\fP +is a null pointer or points to a string which is not a name for +an appropriate directory, the path prefix defined as P_tmpdir in the +\fI\fP +header shall be used. If that directory is not accessible, an implementation-defined +directory may be used. +.LP +Many applications prefer their temporary files to have certain initial +letter sequences in their names. The \fIpfx\fP argument +should be used for this. This argument may be a null pointer or point +to a string of up to five bytes to be used as the beginning +of the filename. +.LP +Some implementations of \fItempnam\fP() may use \fItmpnam\fP() internally. +On such +implementations, if called more than {TMP_MAX} times in a single process, +the behavior is implementation-defined. +.SH RETURN VALUE +.LP +Upon successful completion, \fItempnam\fP() shall allocate space for +a string, put the generated pathname in that space, and +return a pointer to it. The pointer shall be suitable for use in a +subsequent call to \fIfree\fP(). Otherwise, it shall return a null +pointer and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fItempnam\fP() function shall fail if: +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Generating a Pathname +.LP +The following example generates a pathname for a temporary file in +directory \fB/tmp\fP, with the prefix \fIfile\fP. After the +filename has been created, the call to \fIfree\fP() deallocates the +space used to store the +filename. +.sp +.RS +.nf + +\fB#include +#include +\&... +char *directory = "/tmp"; +char *fileprefix = "file"; +char *file; +.sp + +file = tempnam(directory, fileprefix); +free(file); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +This function only creates pathnames. It is the application's responsibility +to create and remove the files. Between the time a +pathname is created and the file is opened, it is possible for some +other process to create a file with the same name. Applications +may find \fItmpfile\fP() more useful. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfopen\fP() , \fIfree\fP() , \fIopen\fP() , \fItmpfile\fP() , \fItmpnam\fP() +, \fIunlink\fP() , +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tfind.3p b/man3p/tfind.3p new file mode 100644 index 000000000..e706cafc8 --- /dev/null +++ b/man3p/tfind.3p @@ -0,0 +1 @@ +.so man3p/tsearch.3p diff --git a/man3p/tgamma.3p b/man3p/tgamma.3p new file mode 100644 index 000000000..045d61457 --- /dev/null +++ b/man3p/tgamma.3p @@ -0,0 +1,124 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TGAMMA" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tgamma +.SH NAME +tgamma, tgammaf, tgammal \- compute gamma() function +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double tgamma(double\fP \fIx\fP\fB); +.br +float tgammaf(float\fP \fIx\fP\fB); +.br +long double tgammal(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall compute the \fIgamma\fP() function of \fIx\fP. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return \fIGamma\fP( +\fIx\fP). +.LP +If \fIx\fP is a negative integer, a domain error shall occur, and +either a NaN (if supported), or an implementation-defined +value shall be returned. +.LP +If the correct value would cause overflow, a range error shall occur +and \fItgamma\fP(), \fItgammaf\fP(), and \fItgammal\fP() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, or \(+-HUGE_VALL, respectively, +with the same sign as the correct value of +the function. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is +Inf, \fIx\fP shall be returned. +.LP +If \fIx\fP is \(+-0, a pole error shall occur, and \fItgamma\fP(), +\fItgammaf\fP(), and \fItgammal\fP() shall return +\(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL, respectively. +.LP +If \fIx\fP is -Inf, a domain error shall occur, and either a NaN (if +supported), or an implementation-defined value shall be +returned. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +Domain\ Error +The value of \fIx\fP is a negative integer, \ or \fIx\fP is -Inf. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be +raised. +.TP 7 +Pole\ Error +The value of \fIx\fP is zero. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the divide-by-zero floating-point exception shall be +raised. +.br +.TP 7 +Range\ Error +The value overflows. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +For IEEE\ Std\ 754-1985 \fBdouble\fP, overflow happens when 0 < \fIx\fP +< 1/DBL_MAX, and 171.7 < +\fIx\fP. +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +This function is named \fItgamma\fP() in order to avoid conflicts +with the historical \fIgamma\fP() and \fIlgamma\fP() functions. +.SH FUTURE DIRECTIONS +.LP +It is possible that the error response for a negative integer argument +may be changed to a pole error and a return value of +\(+-Inf. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIlgamma\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment +of Error Conditions for Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tgammaf.3p b/man3p/tgammaf.3p new file mode 100644 index 000000000..42d38b882 --- /dev/null +++ b/man3p/tgammaf.3p @@ -0,0 +1 @@ +.so man3p/tgamma.3p diff --git a/man3p/tgammal.3p b/man3p/tgammal.3p new file mode 100644 index 000000000..42d38b882 --- /dev/null +++ b/man3p/tgammal.3p @@ -0,0 +1 @@ +.so man3p/tgamma.3p diff --git a/man3p/time.3p b/man3p/time.3p new file mode 100644 index 000000000..c3ea3e955 --- /dev/null +++ b/man3p/time.3p @@ -0,0 +1,152 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" time +.SH NAME +time \- get time +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +time_t time(time_t *\fP\fItloc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fItime\fP() function shall return the value of time \ in seconds +since the Epoch. +.LP +The \fItloc\fP argument points to an area where the return value is +also stored. If \fItloc\fP is a null pointer, no value is +stored. +.SH RETURN VALUE +.LP +Upon successful completion, \fItime\fP() shall return the value of +time. Otherwise, (\fBtime_t\fP)-1 shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Getting the Current Time +.LP +The following example uses the \fItime\fP() function to calculate +the time elapsed, in seconds, since the Epoch, \fIlocaltime\fP() to +convert that value to a broken-down time, and \fIasctime\fP() to convert +the broken-down time values into a printable string. +.sp +.RS +.nf + +\fB#include +#include +.sp + +int main(void) +{ +time_t result; +.sp + + result = time(NULL); + printf("%s%ju secs since the Epoch\\n", + asctime(localtime(&result)), + (uintmax_t)result); + return(0); +} +\fP +.fi +.RE +.LP +This example writes the current time to \fIstdout\fP in a form like +this: +.sp +.RS +.nf + +\fBWed Jun 26 10:32:15 1996 +835810335 secs since the Epoch +\fP +.fi +.RE +.SS Timing an Event +.LP +The following example gets the current time, prints it out in the +user's format, and prints the number of minutes to an event +being timed. +.sp +.RS +.nf + +\fB#include +#include +\&... +time_t now; +int minutes_to_event; +\&... +time(&now); +minutes_to_event = ...; +printf("The time is "); +puts(asctime(localtime(&now))); +printf("There are %d minutes to the event.\\n", + minutes_to_event); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fItime\fP() function returns a value in seconds (type \fBtime_t\fP) +while \fItimes\fP() returns a set of values in clock ticks (type \fBclock_t\fP). +Some historical +implementations, such as 4.3 BSD, have mechanisms capable of returning +more precise times (see below). A generalized timing scheme +to unify these various timing mechanisms has been proposed but not +adopted. +.LP +Implementations in which \fBtime_t\fP is a 32-bit signed integer (many +historical implementations) fail in the year 2038. +IEEE\ Std\ 1003.1-2001 does not address this problem. However, the +use of the \fBtime_t\fP type is mandated in order to +ease the eventual fix. +.LP +The use of the \fI\fP header instead of \fI\fP +allows compatibility with the ISO\ C standard. +.LP +Many historical implementations (including Version 7) and the 1984 +/usr/group standard use \fBlong\fP instead of \fBtime_t\fP. +This volume of IEEE\ Std\ 1003.1-2001 uses the latter type in order +to agree with the ISO\ C standard. +.LP +4.3 BSD includes \fItime\fP() only as an alternate function to the +more flexible \fIgettimeofday\fP() function. +.SH FUTURE DIRECTIONS +.LP +In a future version of this volume of IEEE\ Std\ 1003.1-2001, \fBtime_t\fP +is likely to be required to be capable of +representing times far in the future. Whether this will be mandated +as a 64-bit type or a requirement that a specific date in the +future be representable (for example, 10000 AD) is not yet determined. +Systems purchased after the approval of this volume of +IEEE\ Std\ 1003.1-2001 should be evaluated to determine whether their +lifetime will extend past 2038. +.SH SEE ALSO +.LP +\fIasctime\fP() , \fIclock\fP() , \fIctime\fP() +, \fIdifftime\fP() , \fIgettimeofday\fP() , \fIgmtime\fP() , \fIlocaltime\fP() +, \fImktime\fP() , +\fIstrftime\fP() , \fIstrptime\fP() , \fIutime\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/timer_create.3p b/man3p/timer_create.3p new file mode 100644 index 000000000..188f93a70 --- /dev/null +++ b/man3p/timer_create.3p @@ -0,0 +1,197 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TIMER_CREATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" timer_create +.SH NAME +timer_create \- create a per-process timer (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int timer_create(clockid_t\fP \fIclockid\fP\fB, struct sigevent *restrict\fP +\fIevp\fP\fB, +.br +\ \ \ \ \ \ timer_t *restrict\fP \fItimerid\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fItimer_create\fP() function shall create a per-process timer +using the specified clock, \fIclock_id\fP, as the timing +base. The \fItimer_create\fP() function shall return, in the location +referenced by \fItimerid\fP, a timer ID of type +\fBtimer_t\fP used to identify the timer in timer requests. This timer +ID shall be unique within the calling process until the +timer is deleted. The particular clock, \fIclock_id\fP, is defined +in \fI\fP. +The timer whose ID is returned shall be in a disarmed state upon return +from \fItimer_create\fP(). +.LP +The \fIevp\fP argument, if non-NULL, points to a \fBsigevent\fP structure. +This structure, allocated by the application, +defines the asynchronous notification to occur as specified in \fISignal +Generation and +Delivery\fP when the timer expires. If the \fIevp\fP argument is NULL, +the effect is as if the \fIevp\fP argument pointed to +a \fBsigevent\fP structure with the \fIsigev_notify\fP member having +the value SIGEV_SIGNAL, the \fIsigev_signo\fP having a +default signal number, and the \fIsigev_value\fP member having the +value of the timer ID. +.LP +Each implementation shall define a set of clocks that can be used +as timing bases for per-process timers. All implementations +shall support a \fIclock_id\fP of CLOCK_REALTIME. \ If the Monotonic +Clock option is supported, implementations shall +support a \fIclock_id\fP of CLOCK_MONOTONIC. +.LP +Per-process timers shall not be inherited by a child process across +a \fIfork\fP() and +shall be disarmed and deleted by an \fIexec\fP. +.LP +If _POSIX_CPUTIME is defined, implementations shall support \fIclock_id\fP +values representing the CPU-time clock of the calling +process. +.LP +If _POSIX_THREAD_CPUTIME is defined, implementations shall support +\fIclock_id\fP values representing the CPU-time clock of the +calling thread. +.LP +It is implementation-defined whether a \fItimer_create\fP() function +will succeed if the value defined by \fIclock_id\fP +corresponds to the CPU-time clock of a process or thread different +from the process or thread invoking the function. +.SH RETURN VALUE +.LP +If the call succeeds, \fItimer_create\fP() shall return zero and update +the location referenced by \fItimerid\fP to a +\fBtimer_t\fP, which can be passed to the per-process timer calls. +If an error occurs, the function shall return a value of -1 and +set \fIerrno\fP to indicate the error. The value of \fItimerid\fP +is undefined if an error occurs. +.SH ERRORS +.LP +The \fItimer_create\fP() function shall fail if: +.TP 7 +.B EAGAIN +The system lacks sufficient signal queuing resources to honor the +request. +.TP 7 +.B EAGAIN +The calling process has already created all of the timers it is allowed +by this implementation. +.TP 7 +.B EINVAL +The specified clock ID is not defined. +.TP 7 +.B ENOTSUP +The implementation does not support the creation of a timer attached +to the CPU-time clock that is specified by +\fIclock_id\fP and associated with a process or thread different from +the process or thread invoking \fItimer_create\fP(). +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.br +.SH RATIONALE +.LP +.SS Periodic Timer Overrun and Resource Allocation +.LP +The specified timer facilities may deliver realtime signals (that +is, queued signals) on implementations that support this +option. Since realtime applications cannot afford to lose notifications +of asynchronous events, like timer expirations or +asynchronous I/O completions, it must be possible to ensure that sufficient +resources exist to deliver the signal when the event +occurs. In general, this is not a difficulty because there is a one-to-one +correspondence between a request and a subsequent signal +generation. If the request cannot allocate the signal delivery resources, +it can fail the call with an [EAGAIN] error. +.LP +Periodic timers are a special case. A single request can generate +an unspecified number of signals. This is not a problem if the +requesting process can service the signals as fast as they are generated, +thus making the signal delivery resources available for +delivery of subsequent periodic timer expiration signals. But, in +general, this cannot be assured-processing of periodic timer +signals may "overrun''; that is, subsequent periodic timer expirations +may occur before the currently pending signal has been +delivered. +.LP +Also, for signals, according to the POSIX.1-1990 standard, if subsequent +occurrences of a pending signal are generated, it is +implementation-defined whether a signal is delivered for each occurrence. +This is not adequate for some realtime applications. So a +mechanism is required to allow applications to detect how many timer +expirations were delayed without requiring an indefinite +amount of system resources to store the delayed expirations. +.LP +The specified facilities provide for an overrun count. The overrun +count is defined as the number of extra timer expirations +that occurred between the time a timer expiration signal is generated +and the time the signal is delivered. The signal-catching +function, if it is concerned with overruns, can retrieve this count +on entry. With this method, a periodic timer only needs one +"signal queuing resource" that can be allocated at the time of the +\fItimer_create\fP() function call. +.LP +A function is defined to retrieve the overrun count so that an application +need not allocate static storage to contain the +count, and an implementation need not update this storage asynchronously +on timer expirations. But, for some high-frequency +periodic applications, the overhead of an additional system call on +each timer expiration may be prohibitive. The functions, as +defined, permit an implementation to maintain the overrun count in +user space, associated with the \fItimerid\fP. The \fItimer_getoverrun\fP() +function can then be implemented as a macro that uses the +\fItimerid\fP argument (which may just be a pointer to a user space +structure containing the counter) to locate the overrun count +with no system call overhead. Other implementations, less concerned +with this class of applications, can avoid the asynchronous +update of user space by maintaining the count in a system structure +at the cost of the extra system call to obtain it. +.SS Timer Expiration Signal Parameters +.LP +The Realtime Signals Extension option supports an application-specific +datum that is delivered to the extended signal handler. +This value is explicitly specified by the application, along with +the signal number to be delivered, in a \fBsigevent\fP +structure. The type of the application-defined value can be either +an integer constant or a pointer. This explicit specification of +the value, as opposed to always sending the timer ID, was selected +based on existing practice. +.LP +It is common practice for realtime applications (on non-POSIX systems +or realtime extended POSIX systems) to use the parameters +of event handlers as the case label of a switch statement or as a +pointer to an application-defined data structure. Since +\fItimer_id\fPs are dynamically allocated by the \fItimer_create\fP() +function, they can be used for neither of these functions +without additional application overhead in the signal handler; for +example, to search an array of saved timer IDs to associate the +ID with a constant or application data structure. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclock_getres\fP() , \fItimer_delete\fP() , \fItimer_getoverrun\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/timer_delete.3p b/man3p/timer_delete.3p new file mode 100644 index 000000000..6c33544ef --- /dev/null +++ b/man3p/timer_delete.3p @@ -0,0 +1,62 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TIMER_DELETE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" timer_delete +.SH NAME +timer_delete \- delete a per-process timer (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int timer_delete(timer_t\fP \fItimerid\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fItimer_delete\fP() function deletes the specified timer, \fItimerid\fP, +previously created by the \fItimer_create\fP() function. If the timer +is armed when \fItimer_delete\fP() is called, +the behavior shall be as if the timer is automatically disarmed before +removal. The disposition of pending signals for the deleted +timer is unspecified. +.SH RETURN VALUE +.LP +If successful, the \fItimer_delete\fP() function shall return a value +of zero. Otherwise, the function shall return a value of +-1 and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fItimer_delete\fP() function shall fail if: +.TP 7 +.B EINVAL +The timer ID specified by \fItimerid\fP is not a valid timer ID. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fItimer_create\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/timer_getoverrun.3p b/man3p/timer_getoverrun.3p new file mode 100644 index 000000000..d82746b7f --- /dev/null +++ b/man3p/timer_getoverrun.3p @@ -0,0 +1 @@ +.so man3p/timer_gettime.3p diff --git a/man3p/timer_gettime.3p b/man3p/timer_gettime.3p new file mode 100644 index 000000000..4ee467cb6 --- /dev/null +++ b/man3p/timer_gettime.3p @@ -0,0 +1,175 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TIMER_GETOVERRUN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" timer_getoverrun +.SH NAME +timer_getoverrun, timer_gettime, timer_settime \- per-process timers +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int timer_getoverrun(timer_t\fP \fItimerid\fP\fB); +.br +int timer_gettime(timer_t\fP \fItimerid\fP\fB, struct itimerspec *\fP\fIvalue\fP\fB); +.br +int timer_settime(timer_t\fP \fItimerid\fP\fB, int\fP \fIflags\fP\fB, +.br +\ \ \ \ \ \ const struct itimerspec *restrict\fP \fIvalue\fP\fB, +.br +\ \ \ \ \ \ struct itimerspec *restrict\fP \fIovalue\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fItimer_gettime\fP() function shall store the amount of time +until the specified timer, \fItimerid\fP, expires and the +reload value of the timer into the space pointed to by the \fIvalue\fP +argument. The \fIit_value\fP member of this structure +shall contain the amount of time before the timer expires, or zero +if the timer is disarmed. This value is returned as the interval +until timer expiration, even if the timer was armed with absolute +time. The \fIit_interval\fP member of \fIvalue\fP shall contain +the reload value last set by \fItimer_settime\fP(). +.LP +The \fItimer_settime\fP() function shall set the time until the next +expiration of the timer specified by \fItimerid\fP from +the \fIit_value\fP member of the \fIvalue\fP argument and arm the +timer if the \fIit_value\fP member of \fIvalue\fP is +non-zero. If the specified timer was already armed when \fItimer_settime\fP() +is called, this call shall reset the time until next +expiration to the \fIvalue\fP specified. If the \fIit_value\fP member +of \fIvalue\fP is zero, the timer shall be disarmed. The +effect of disarming or resetting a timer with pending expiration notifications +is unspecified. +.LP +If the flag TIMER_ABSTIME is not set in the argument \fIflags\fP, +\fItimer_settime\fP() shall behave as if the time until next +expiration is set to be equal to the interval specified by the \fIit_value\fP +member of \fIvalue\fP. That is, the timer shall +expire in \fIit_value\fP nanoseconds from when the call is made. If +the flag TIMER_ABSTIME is set in the argument \fIflags\fP, +\fItimer_settime\fP() shall behave as if the time until next expiration +is set to be equal to the difference between the absolute +time specified by the \fIit_value\fP member of \fIvalue\fP and the +current value of the clock associated with \fItimerid\fP. +That is, the timer shall expire when the clock reaches the value specified +by the \fIit_value\fP member of \fIvalue\fP. If the +specified time has already passed, the function shall succeed and +the expiration notification shall be made. +.LP +The reload value of the timer shall be set to the value specified +by the \fIit_interval\fP member of \fIvalue\fP. When a timer +is armed with a non-zero \fIit_interval\fP, a periodic (or repetitive) +timer is specified. +.LP +Time values that are between two consecutive non-negative integer +multiples of the resolution of the specified timer shall be +rounded up to the larger multiple of the resolution. Quantization +error shall not cause the timer to expire earlier than the +rounded time value. +.LP +If the argument \fIovalue\fP is not NULL, the \fItimer_settime\fP() +function shall store, in the location referenced by +\fIovalue\fP, a value representing the previous amount of time before +the timer would have expired, or zero if the timer was +disarmed, together with the previous timer reload value. Timers shall +not expire before their scheduled time. +.LP +Only a single signal shall be queued to the process for a given timer +at any point in time. When a timer for which a signal is +still pending expires, no signal shall be queued, and a timer overrun +shall occur. \ When a timer +expiration signal is delivered to or accepted by a process, if the +implementation supports the Realtime Signals Extension, the +\fItimer_getoverrun\fP() function shall return the timer expiration +overrun count for the specified timer. The overrun count +returned contains the number of extra timer expirations that occurred +between the time the signal was generated (queued) and when +it was delivered or accepted, up to but not including an implementation-defined +maximum of {DELAYTIMER_MAX}. If the number of such +extra expirations is greater than or equal to {DELAYTIMER_MAX}, then +the overrun count shall be set to {DELAYTIMER_MAX}. The value +returned by \fItimer_getoverrun\fP() shall apply to the most recent +expiration signal delivery or acceptance for the timer. If no expiration +signal has been delivered for the timer, or if the +Realtime Signals Extension is not supported, the return value of \fItimer_getoverrun\fP() +is unspecified. +.SH RETURN VALUE +.LP +If the \fItimer_getoverrun\fP() function succeeds, it shall return +the timer expiration overrun count as explained above. +.LP +If the \fItimer_gettime\fP() or \fItimer_settime\fP() functions succeed, +a value of 0 shall be returned. +.LP +If an error occurs for any of these functions, the value -1 shall +be returned, and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fItimer_getoverrun\fP(), \fItimer_gettime\fP(), and \fItimer_settime\fP() +functions shall fail if: +.TP 7 +.B EINVAL +The \fItimerid\fP argument does not correspond to an ID returned by +\fItimer_create\fP() but not yet deleted by \fItimer_delete\fP(). +.sp +.LP +The \fItimer_settime\fP() function shall fail if: +.TP 7 +.B EINVAL +A \fIvalue\fP structure specified a nanosecond value less than zero +or greater than or equal to 1000 million, and the +\fIit_value\fP member of that structure did not specify zero seconds +and nanoseconds. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Practical clocks tick at a finite rate, with rates of 100 hertz and +1000 hertz being common. The inverse of this tick rate is +the clock resolution, also called the clock granularity, which in +either case is expressed as a time duration, being 10 +milliseconds and 1 millisecond respectively for these common rates. +The granularity of practical clocks implies that if one reads a +given clock twice in rapid succession, one may get the same time value +twice; and that timers must wait for the next clock tick +after the theoretical expiration time, to ensure that a timer never +returns too soon. Note also that the granularity of the clock +may be significantly coarser than the resolution of the data format +used to set and get time and interval values. Also note that +some implementations may choose to adjust time and/or interval values +to exactly match the ticks of the underlying clock. +.LP +This volume of IEEE\ Std\ 1003.1-2001 defines functions that allow +an application to determine the +implementation-supported resolution for the clocks and requires an +implementation to document the resolution supported for timers +and \fInanosleep\fP() if they differ from the supported clock resolution. +This is more +of a procurement issue than a runtime application issue. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclock_getres\fP() , \fItimer_create\fP() , the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/timer_settime.3p b/man3p/timer_settime.3p new file mode 100644 index 000000000..d82746b7f --- /dev/null +++ b/man3p/timer_settime.3p @@ -0,0 +1 @@ +.so man3p/timer_gettime.3p diff --git a/man3p/times.3p b/man3p/times.3p new file mode 100644 index 000000000..8d0992077 --- /dev/null +++ b/man3p/times.3p @@ -0,0 +1,158 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TIMES" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" times +.SH NAME +times \- get process and waited-for child process times +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +clock_t times(struct tms *\fP\fIbuffer\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fItimes\fP() function shall fill the \fBtms\fP structure pointed +to by \fIbuffer\fP with time-accounting information. +The \fBtms\fP structure is defined in \fI\fP. +.LP +All times are measured in terms of the number of clock ticks used. +.LP +The times of a terminated child process shall be included in the \fItms_cutime\fP +and \fItms_cstime\fP elements of the parent +when \fIwait\fP() or \fIwaitpid\fP() returns the +process ID of this terminated child. If a child process has not waited +for its children, their times shall not be included in its +times. +.IP " *" 3 +The \fItms_utime\fP structure member is the CPU time charged for the +execution of user instructions of the calling process. +.LP +.IP " *" 3 +The \fItms_stime\fP structure member is the CPU time charged for execution +by the system on behalf of the calling process. +.LP +.IP " *" 3 +The \fItms_cutime\fP structure member is the sum of the \fItms_utime\fP +and \fItms_cutime\fP times of the child +processes. +.LP +.IP " *" 3 +The \fItms_cstime\fP structure member is the sum of the \fItms_stime\fP +and \fItms_cstime\fP times of the child +processes. +.LP +.SH RETURN VALUE +.LP +Upon successful completion, \fItimes\fP() shall return the elapsed +real time, in clock ticks, since an arbitrary point in the +past (for example, system start-up time). This point does not change +from one invocation of \fItimes\fP() within the process to +another. The return value may overflow the possible range of type +\fBclock_t\fP. If \fItimes\fP() fails, (\fBclock_t\fP)-1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Timing a Database Lookup +.LP +The following example defines two functions, \fIstart_clock\fP() and +\fIend_clock\fP(), that are used to time a lookup. It +also defines variables of type \fBclock_t\fP and \fBtms\fP to measure +the duration of transactions. The \fIstart_clock\fP() +function saves the beginning times given by the \fItimes\fP() function. +The \fIend_clock\fP() function gets the ending times and +prints the difference between the two times. +.sp +.RS +.nf + +\fB#include +#include +\&... +void start_clock(void); +void end_clock(char *msg); +\&... +static clock_t st_time; +static clock_t en_time; +static struct tms st_cpu; +static struct tms en_cpu; +\&... +void +start_clock() +{ + st_time = times(&st_cpu); +} +.sp + +/* This example assumes that the result of each subtraction + is within the range of values that can be represented in + an integer type. */ +void +end_clock(char *msg) +{ + en_time = times(&en_cpu); +.sp + + fputs(msg,stdout); + printf("Real Time: %jd, User Time %jd, System Time %jd\\n", + (intmax_t)(en_time - st_time), + (intmax_t)(en_cpu.tms_utime - st_cpu.tms_utime), + (intmax_t)(en_cpu.tms_stime - st_cpu.tms_stime)); +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +Applications should use \fIsysconf\fP(_SC_CLK_TCK) to determine the +number of clock ticks per second as it may vary from system +to system. +.SH RATIONALE +.LP +The accuracy of the times reported is intentionally left unspecified +to allow implementations flexibility in design, from +uniprocessor to multi-processor networks. +.LP +The inclusion of times of child processes is recursive, so that a +parent process may collect the total times of all of its +descendants. But the times of a child are only added to those of its +parent when its parent successfully waits on the child. Thus, +it is not guaranteed that a parent process can always see the total +times of all its descendants; see also the discussion of the +term ``realtime'' in \fIalarm\fP() . +.LP +If the type \fBclock_t\fP is defined to be a signed 32-bit integer, +it overflows in somewhat more than a year if there are 60 +clock ticks per second, or less than a year if there are 100. There +are individual systems that run continuously for longer than +that. This volume of IEEE\ Std\ 1003.1-2001 permits an implementation +to make the reference point for the returned value be +the start-up time of the process, rather than system start-up time. +.LP +The term ``charge'' in this context has nothing to do with billing +for services. The operating system accounts for time used in +this way. That information must be correct, regardless of how that +information is used. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIalarm\fP() , \fIexec\fP() , \fIfork\fP() , \fIsysconf\fP() , \fItime\fP() +, \fIwait\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/timezone.3p b/man3p/timezone.3p new file mode 100644 index 000000000..3c5f1bc17 --- /dev/null +++ b/man3p/timezone.3p @@ -0,0 +1 @@ +.so man3p/tzset.3p diff --git a/man3p/tmpfile.3p b/man3p/tmpfile.3p new file mode 100644 index 000000000..24d9a069b --- /dev/null +++ b/man3p/tmpfile.3p @@ -0,0 +1,113 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TMPFILE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tmpfile +.SH NAME +tmpfile \- create a temporary file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +FILE *tmpfile(void); +.br +\fP +.SH DESCRIPTION +.LP +The \fItmpfile\fP() function shall create a temporary file and open +a corresponding stream. The file shall be automatically +deleted when all references to the file are closed. The file is opened +as in \fIfopen\fP() +for update (\fIw\fP+). +.LP +In +some implementations, a permanent file may be left behind if the process +calling \fItmpfile\fP() is killed while it is processing +a call to \fItmpfile\fP(). +.LP +An error message may be written to standard error if the stream cannot +be opened. +.SH RETURN VALUE +.LP +Upon successful completion, \fItmpfile\fP() shall return a pointer +to the stream of the file that is created. Otherwise, it +shall return a null pointer \ and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fItmpfile\fP() function shall fail if: +.TP 7 +.B EINTR +A +signal was caught during \fItmpfile\fP(). +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENFILE +The maximum allowable number of files is currently open in the system. +.TP 7 +.B ENOSPC +The directory or file system which would contain the new file cannot +be expanded. +.TP 7 +.B EOVERFLOW +The file is a regular file and the size of the file cannot be represented +correctly in an object of type \fBoff_t\fP. +.sp +.LP +The \fItmpfile\fP() function may fail if: +.TP 7 +.B EMFILE +{FOPEN_MAX} streams are currently open in the calling process. +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Creating a Temporary File +.LP +The following example creates a temporary file for update, and returns +a pointer to a stream for the created file in the +\fIfp\fP variable. +.sp +.RS +.nf + +\fB#include +\&... +FILE *fp; +.sp + +fp = tmpfile (); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +It should be possible to open at least {TMP_MAX} temporary files during +the lifetime of the program (this limit may be shared +with \fItmpnam\fP()) and there should be no limit on the number simultaneously +open other +than this limit and any limit on the number of open files ( {FOPEN_MAX}). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfopen\fP() , \fItmpnam\fP() , \fIunlink\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tmpnam.3p b/man3p/tmpnam.3p new file mode 100644 index 000000000..0dade09b5 --- /dev/null +++ b/man3p/tmpnam.3p @@ -0,0 +1,100 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TMPNAM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tmpnam +.SH NAME +tmpnam \- create a name for a temporary file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *tmpnam(char *\fP\fIs\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fItmpnam\fP() function shall generate a string that is a valid +filename and that is not the same as the name of an +existing file. The function is potentially capable of generating {TMP_MAX} +different strings, but any or all of them may already be +in use by existing files and thus not be suitable return values. +.LP +The \fItmpnam\fP() function generates a different string each time +it is called from the same process, up to {TMP_MAX} times. +If it is called more than {TMP_MAX} times, the behavior is implementation-defined. +.LP +The implementation shall behave as if no function defined in this +volume of IEEE\ Std\ 1003.1-2001 calls +\fItmpnam\fP(). +.LP +If +the application uses any of the functions guaranteed to be available +if either _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS is +defined, the application shall ensure that the \fItmpnam\fP() function +is called with a non-NULL parameter. +.SH RETURN VALUE +.LP +Upon successful completion, \fItmpnam\fP() shall return a pointer +to a string. If no suitable string can be generated, the +\fItmpnam\fP() function shall return a null pointer. +.LP +If the argument \fIs\fP is a null pointer, \fItmpnam\fP() shall leave +its result in an internal static object and return a +pointer to that object. Subsequent calls to \fItmpnam\fP() may modify +the same object. If the argument \fIs\fP is not a null +pointer, it is presumed to point to an array of at least L_tmpnam +\fBchar\fPs; \fItmpnam\fP() shall write its result in that +array and shall return the argument as its value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Generating a Filename +.LP +The following example generates a unique filename and stores it in +the array pointed to by \fIptr\fP. +.sp +.RS +.nf + +\fB#include +\&... +char filename[L_tmpnam+1]; +char *ptr; +.sp + +ptr = tmpnam(filename); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +This function only creates filenames. It is the application's responsibility +to create and remove the files. +.LP +Between the time a pathname is created and the file is opened, it +is possible for some other process to create a file with the +same name. Applications may find \fItmpfile\fP() more useful. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfopen\fP() , \fIopen\fP() , \fItempnam\fP() , +\fItmpfile\fP() , \fIunlink\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/toascii.3p b/man3p/toascii.3p new file mode 100644 index 000000000..a3b27caa2 --- /dev/null +++ b/man3p/toascii.3p @@ -0,0 +1,52 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TOASCII" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" toascii +.SH NAME +toascii \- translate an integer to a 7-bit ASCII character +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int toascii(int\fP \fIc\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fItoascii\fP() function shall convert its argument into a 7-bit +ASCII character. +.SH RETURN VALUE +.LP +The \fItoascii\fP() function shall return the value (\fIc\fP &0x7f). +.SH ERRORS +.LP +No errors are returned. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIisascii\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/tolower.3p b/man3p/tolower.3p new file mode 100644 index 000000000..8fd20918c --- /dev/null +++ b/man3p/tolower.3p @@ -0,0 +1,60 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TOLOWER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tolower +.SH NAME +tolower \- transliterate uppercase characters to lowercase +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int tolower(int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fItolower\fP() function has as a domain a type \fBint\fP, the +value of which is representable as an \fBunsigned char\fP +or the value of EOF. If the argument has any other value, the behavior +is undefined. If the argument of \fItolower\fP() represents +an uppercase letter, and there exists a corresponding lowercase letter +\ (as defined by character type information in the program +locale category \fILC_CTYPE ),\fP the result shall be the +corresponding lowercase letter. All other arguments in the domain +are returned unchanged. +.SH RETURN VALUE +.LP +Upon successful completion, \fItolower\fP() shall return the lowercase +letter corresponding to the argument passed; otherwise, +it shall return the argument unchanged. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsetlocale\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, Locale, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/toupper.3p b/man3p/toupper.3p new file mode 100644 index 000000000..37ec1dd21 --- /dev/null +++ b/man3p/toupper.3p @@ -0,0 +1,59 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TOUPPER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" toupper +.SH NAME +toupper \- transliterate lowercase characters to uppercase +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int toupper(int\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fItoupper\fP() function has as a domain a type \fBint\fP, the +value of which is representable as an \fBunsigned char\fP +or the value of EOF. If the argument has any other value, the behavior +is undefined. If the argument of \fItoupper\fP() represents +a lowercase letter, and there exists a corresponding uppercase letter +\ (as defined by character type information in the program +locale category \fILC_CTYPE ),\fP the result shall be the +corresponding uppercase letter. All other arguments in the domain +are returned unchanged. +.SH RETURN VALUE +.LP +Upon successful completion, \fItoupper\fP() shall return the uppercase +letter corresponding to the argument passed. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsetlocale\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, Locale, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/towctrans.3p b/man3p/towctrans.3p new file mode 100644 index 000000000..342d519d2 --- /dev/null +++ b/man3p/towctrans.3p @@ -0,0 +1,81 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TOWCTRANS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" towctrans +.SH NAME +towctrans \- wide-character transliteration +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wint_t towctrans(wint_t\fP \fIwc\fP\fB, wctrans_t\fP \fIdesc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fItowctrans\fP() function shall transliterate the wide-character +code \fIwc\fP using the mapping described by +\fIdesc\fP. The current setting of the \fILC_CTYPE\fP category should +be the same as during the call to \fIwctrans\fP() that returned the +value \fIdesc\fP. \ If the value +of \fIdesc\fP is invalid (that is, not obtained by a call to \fIwctrans\fP() +or +\fIdesc\fP is invalidated by a subsequent call to \fIsetlocale\fP() +that has affected +category \fILC_CTYPE ),\fP the result is unspecified. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to 0 before calling \fItowctrans\fP(). If +\fIerrno\fP is non-zero on return, an error has occurred. +.SH RETURN VALUE +.LP +If successful, the \fItowctrans\fP() function shall return the mapped +value of \fIwc\fP using the mapping described by +\fIdesc\fP. Otherwise, it shall return \fIwc\fP unchanged. +.SH ERRORS +.LP +The \fItowctrans\fP() function may fail if: +.TP 7 +.B EINVAL +\fIdesc\fP contains an invalid transliteration descriptor. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The strings \fB"tolower"\fP and \fB"toupper"\fP are reserved for the +standard mapping names. In the table below, the +functions in the left column are equivalent to the functions in the +right column. +.sp +.RS +.nf + +\fBtowlower(\fP\fIwc\fP\fB) towctrans(\fP\fIwc\fP\fB, wctrans("tolower")) +towupper(\fP\fIwc\fP\fB) towctrans(\fP\fIwc\fP\fB, wctrans("toupper")) +\fP +.fi +.RE +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fItowlower\fP() , \fItowupper\fP() , \fIwctrans\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/towlower.3p b/man3p/towlower.3p new file mode 100644 index 000000000..35fc045f0 --- /dev/null +++ b/man3p/towlower.3p @@ -0,0 +1,62 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TOWLOWER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" towlower +.SH NAME +towlower \- transliterate uppercase wide-character code to lowercase +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wint_t towlower(wint_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fItowlower\fP() function has as a domain a type \fBwint_t\fP, +the value of which the application shall ensure is a +character representable as a \fBwchar_t\fP, and a wide-character code +corresponding to a valid character in the current locale or +the value of WEOF. If the argument has any other value, the behavior +is undefined. If the argument of \fItowlower\fP() represents +an uppercase wide-character code, and there exists a corresponding +lowercase wide-character code (as defined by character type +information in the program locale category \fILC_CTYPE ),\fP the result +shall be the corresponding lowercase wide-character code. +All other arguments in the domain are returned unchanged. +.SH RETURN VALUE +.LP +Upon successful completion, \fItowlower\fP() shall return the lowercase +letter corresponding to the argument passed; otherwise, +it shall return the argument unchanged. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsetlocale\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, Locale, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/towupper.3p b/man3p/towupper.3p new file mode 100644 index 000000000..f2bbf7521 --- /dev/null +++ b/man3p/towupper.3p @@ -0,0 +1,62 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TOWUPPER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" towupper +.SH NAME +towupper \- transliterate lowercase wide-character code to uppercase +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wint_t towupper(wint_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fItowupper\fP() function has as a domain a type \fBwint_t\fP, +the value of which the application shall ensure is a +character representable as a \fBwchar_t\fP, and a wide-character code +corresponding to a valid character in the current locale or +the value of WEOF. If the argument has any other value, the behavior +is undefined. If the argument of \fItowupper\fP() represents +a lowercase wide-character code, and there exists a corresponding +uppercase wide-character code (as defined by character type +information in the program locale category \fILC_CTYPE ),\fP the result +shall be the corresponding uppercase wide-character code. +All other arguments in the domain are returned unchanged. +.SH RETURN VALUE +.LP +Upon successful completion, \fItowupper\fP() shall return the uppercase +letter corresponding to the argument passed. Otherwise, +it shall return the argument unchanged. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsetlocale\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 7, Locale, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/trunc.3p b/man3p/trunc.3p new file mode 100644 index 000000000..781553acd --- /dev/null +++ b/man3p/trunc.3p @@ -0,0 +1,61 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TRUNC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" trunc +.SH NAME +trunc, truncf, truncl \- round to truncated integer value +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double trunc(double\fP \fIx\fP\fB); +.br +float truncf(float\fP \fIx\fP\fB); +.br +long double truncl(long double\fP \fIx\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall round their argument to the integer value, in +floating format, nearest to but no larger in magnitude than +the argument. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the truncated +integer value. +.LP +If +\fIx\fP is NaN, a NaN shall be returned. +.LP +If \fIx\fP is \(+-0 or \(+-Inf, \fIx\fP shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/truncate.3p b/man3p/truncate.3p new file mode 100644 index 000000000..c2cbb8023 --- /dev/null +++ b/man3p/truncate.3p @@ -0,0 +1,123 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TRUNCATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" truncate +.SH NAME +truncate \- truncate a file to a specified length +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int truncate(const char *\fP\fIpath\fP\fB, off_t\fP \fIlength\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fItruncate\fP() function shall cause the regular file named by +\fIpath\fP to have a size which shall be equal to +\fIlength\fP bytes. +.LP +If the file previously was larger than \fIlength\fP, the extra data +is discarded. If the file was previously shorter than +\fIlength\fP, its size is increased, and the extended area appears +as if it were zero-filled. +.LP +The application shall ensure that the process has write permission +for the file. +.LP +If the request would cause the file size to exceed the soft file size +limit for the process, the request shall fail and the +implementation shall generate the SIGXFSZ signal for the process. +.LP +This function shall not modify the file offset for any open file descriptions +associated with the file. Upon successful +completion, if the file size is changed, this function shall mark +for update the \fIst_ctime\fP and \fIst_mtime\fP fields of the +file, and the S_ISUID and S_ISGID bits of the file mode may be cleared. +.SH RETURN VALUE +.LP +Upon successful completion, \fItruncate\fP() shall return 0. Otherwise, +-1 shall be returned, and \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +The \fItruncate\fP() function shall fail if: +.TP 7 +.B EINTR +A signal was caught during execution. +.TP 7 +.B EINVAL +The \fIlength\fP argument was less than 0. +.TP 7 +.B EFBIG \fRor\fP EINVAL +The \fIlength\fP argument was greater than the maximum file size. +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to a file system. +.TP 7 +.B EACCES +A component of the path prefix denies search permission, or write +permission is denied on the file. +.TP 7 +.B EISDIR +The named file is a directory. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix of \fIpath\fP is not a directory. +.TP 7 +.B EROFS +The named file resides on a read-only file system. +.sp +.LP +The \fItruncate\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIopen\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/truncf.3p b/man3p/truncf.3p new file mode 100644 index 000000000..440bc9f44 --- /dev/null +++ b/man3p/truncf.3p @@ -0,0 +1 @@ +.so man3p/trunc.3p diff --git a/man3p/truncl.3p b/man3p/truncl.3p new file mode 100644 index 000000000..440bc9f44 --- /dev/null +++ b/man3p/truncl.3p @@ -0,0 +1 @@ +.so man3p/trunc.3p diff --git a/man3p/tsearch.3p b/man3p/tsearch.3p new file mode 100644 index 000000000..fe24abd0c --- /dev/null +++ b/man3p/tsearch.3p @@ -0,0 +1,244 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TDELETE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tdelete +.SH NAME +tdelete, tfind, tsearch, twalk \- manage a binary search tree +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +void *tdelete(const void *restrict\fP \fIkey\fP\fB, void **restrict\fP +\fIrootp\fP\fB, +.br +\ \ \ \ \ \ int(*\fP\fIcompar\fP\fB)(const void *, const void *)); +.br +void *tfind(const void *\fP\fIkey\fP\fB, void *const *\fP\fIrootp\fP\fB, +.br +\ \ \ \ \ \ int(*\fP\fIcompar\fP\fB)(const void *, const void *)); +.br +void *tsearch(const void *\fP\fIkey\fP\fB, void **\fP\fIrootp\fP\fB, +.br +\ \ \ \ \ \ int (*\fP\fIcompar\fP\fB)(const void *, const void *)); +.br +void twalk(const void *\fP\fIroot\fP\fB, +.br +\ \ \ \ \ \ void (*\fP\fIaction\fP\fB)(const void *, VISIT, int)); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fItdelete\fP(), \fItfind\fP(), \fItsearch\fP(), and \fItwalk\fP() +functions manipulate binary search trees. Comparisons +are made with a user-supplied routine, the address of which is passed +as the \fIcompar\fP argument. This routine is called with +two arguments, which are the pointers to the elements being compared. +The application shall ensure that the user-supplied routine +returns an integer less than, equal to, or greater than 0, according +to whether the first argument is to be considered less than, +equal to, or greater than the second argument. The comparison function +need not compare every byte, so arbitrary data may be +contained in the elements in addition to the values being compared. +.LP +The \fItsearch\fP() function shall build and access the tree. The +\fIkey\fP argument is a pointer to an element to be accessed +or stored. If there is a node in the tree whose element is equal to +the value pointed to by \fIkey\fP, a pointer to this found +node shall be returned. Otherwise, the value pointed to by \fIkey\fP +shall be inserted (that is, a new node is created and the +value of \fIkey\fP is copied to this node), and a pointer to this +node returned. Only pointers are copied, so the application +shall ensure that the calling routine stores the data. The \fIrootp\fP +argument points to a variable that points to the root node +of the tree. A null pointer value for the variable pointed to by \fIrootp\fP +denotes an empty tree; in this case, the variable +shall be set to point to the node which shall be at the root of the +new tree. +.LP +Like \fItsearch\fP(), \fItfind\fP() shall search for a node in the +tree, returning a pointer to it if found. However, if it is +not found, \fItfind\fP() shall return a null pointer. The arguments +for \fItfind\fP() are the same as for \fItsearch\fP(). +.LP +The \fItdelete\fP() function shall delete a node from a binary search +tree. The arguments are the same as for \fItsearch\fP(). +The variable pointed to by \fIrootp\fP shall be changed if the deleted +node was the root of the tree. The \fItdelete\fP() +function shall return a pointer to the parent of the deleted node, +or a null pointer if the node is not found. +.LP +The \fItwalk\fP() function shall traverse a binary search tree. The +\fIroot\fP argument is a pointer to the root node of the +tree to be traversed. (Any node in a tree may be used as the root +for a walk below that node.) The argument \fIaction\fP is the +name of a routine to be invoked at each node. This routine is, in +turn, called with three arguments. The first argument shall be +the address of the node being visited. The structure pointed to by +this argument is unspecified and shall not be modified by the +application, but it shall be possible to cast a pointer-to-node into +a pointer-to-pointer-to-element to access the element stored +in the node. The second argument shall be a value from an enumeration +data type: +.sp +.RS +.nf + +\fBtypedef enum { preorder, postorder, endorder, leaf } VISIT; +\fP +.fi +.RE +.LP +(defined in \fI\fP), depending on whether this is the first, +second, or +third time that the node is visited (during a depth-first, left-to-right +traversal of the tree), or whether the node is a leaf. The +third argument shall be the level of the node in the tree, with the +root being level 0. +.LP +If the calling function alters the pointer to the root, the result +is undefined. +.SH RETURN VALUE +.LP +If the node is found, both \fItsearch\fP() and \fItfind\fP() shall +return a pointer to it. If not, \fItfind\fP() shall return +a null pointer, and \fItsearch\fP() shall return a pointer to the +inserted item. +.LP +A null pointer shall be returned by \fItsearch\fP() if there is not +enough space available to create a new node. +.LP +A null pointer shall be returned by \fItdelete\fP(), \fItfind\fP(), +and \fItsearch\fP() if \fIrootp\fP is a null pointer on +entry. +.LP +The \fItdelete\fP() function shall return a pointer to the parent +of the deleted node, or a null pointer if the node is not +found. +.LP +The \fItwalk\fP() function shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The following code reads in strings and stores structures containing +a pointer to each string and a count of its length. It then +walks the tree, printing out the stored strings and their lengths +in alphabetical order. +.sp +.RS +.nf + +\fB#include +#include +#include +.sp + +#define STRSZ 10000 +#define NODSZ 500 +.sp + +struct node { /* Pointers to these are stored in the tree. */ + char *string; + int length; +}; +.sp + +char string_space[STRSZ]; /* Space to store strings. */ +struct node nodes[NODSZ]; /* Nodes to store. */ +void *root = NULL; /* This points to the root. */ +.sp + +int main(int argc, char *argv[]) +{ + char *strptr = string_space; + struct node *nodeptr = nodes; + void print_node(const void *, VISIT, int); + int i = 0, node_compare(const void *, const void *); +.sp + + while (gets(strptr) != NULL && i++ < NODSZ) { + /* Set node. */ + nodeptr->string = strptr; + nodeptr->length = strlen(strptr); + /* Put node into the tree. */ + (void) tsearch((void *)nodeptr, (void **)&root, + node_compare); + /* Adjust pointers, so we do not overwrite tree. */ + strptr += nodeptr->length + 1; + nodeptr++; + } + twalk(root, print_node); + return 0; +} +.sp + +/* + * This routine compares two nodes, based on an + * alphabetical ordering of the string field. + */ +int +node_compare(const void *node1, const void *node2) +{ + return strcmp(((const struct node *) node1)->string, + ((const struct node *) node2)->string); +} +.sp + +/* + * This routine prints out a node, the second time + * twalk encounters it or if it is a leaf. + */ +void +print_node(const void *ptr, VISIT order, int level) +{ + const struct node *p = *(const struct node **) ptr; +.sp + + if (order == postorder || order == leaf) { + (void) printf("string = %s, length = %d\\n", + p->string, p->length); + } +} +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIroot\fP argument to \fItwalk\fP() is one level of indirection +less than the \fIrootp\fP arguments to \fItdelete\fP() +and \fItsearch\fP(). +.LP +There are two nomenclatures used to refer to the order in which tree +nodes are visited. The \fItsearch\fP() function uses +\fBpreorder\fP, \fBpostorder\fP, and \fBendorder\fP to refer respectively +to visiting a node before any of its children, after +its left child and before its right, and after both its children. +The alternative nomenclature uses \fBpreorder\fP, +\fBinorder\fP, and \fBpostorder\fP to refer to the same visits, which +could result in some confusion over the meaning of +\fBpostorder\fP. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIhcreate\fP() , \fIlsearch\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ttyname.3p b/man3p/ttyname.3p new file mode 100644 index 000000000..650bd4b82 --- /dev/null +++ b/man3p/ttyname.3p @@ -0,0 +1,103 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TTYNAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ttyname +.SH NAME +ttyname, ttyname_r \- find the pathname of a terminal +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +char *ttyname(int\fP \fIfildes\fP\fB); +.br +\fP +.LP +\fBint ttyname_r(int\fP \fIfildes\fP\fB, char *\fP\fIname\fP\fB, size_t\fP +\fInamesize\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIttyname\fP() function shall return a pointer to a string containing +a null-terminated pathname of the terminal +associated with file descriptor \fIfildes\fP. The return value may +point to static data whose content is overwritten by each +call. +.LP +The \fIttyname\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.LP +The \fIttyname_r\fP() function shall store the null-terminated pathname +of the terminal associated with the file descriptor +\fIfildes\fP in the character array referenced by \fIname\fP. The +array is \fInamesize\fP characters long and should have space +for the name and the terminating null character. The maximum length +of the terminal name shall be {TTY_NAME_MAX}. +.SH RETURN VALUE +.LP +Upon successful completion, \fIttyname\fP() shall return a pointer +to a string. Otherwise, a null pointer shall be returned and +\fIerrno\fP set to indicate the error. +.LP +If successful, the \fIttyname_r\fP() function shall return zero. Otherwise, +an error number shall be returned to indicate the +error. +.SH ERRORS +.LP +The \fIttyname\fP() function may fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B ENOTTY +The \fIfildes\fP argument does not refer to a terminal. +.sp +.LP +The \fIttyname_r\fP() function may fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B ENOTTY +The \fIfildes\fP argument does not refer to a terminal. +.TP 7 +.B ERANGE +The value of \fInamesize\fP is smaller than the length of the string +to be returned including the terminating null character. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The term ``terminal'' is used instead of the historical term ``terminal +device'' in order to avoid a reference to an undefined +term. +.LP +The thread-safe version places the terminal name in a user-supplied +buffer and returns a non-zero value if it fails. The +non-thread-safe version may return the name in a static data area +that may be overwritten by each call. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ttyname_r.3p b/man3p/ttyname_r.3p new file mode 100644 index 000000000..50a133d3d --- /dev/null +++ b/man3p/ttyname_r.3p @@ -0,0 +1 @@ +.so man3p/ttyname.3p diff --git a/man3p/twalk.3p b/man3p/twalk.3p new file mode 100644 index 000000000..e706cafc8 --- /dev/null +++ b/man3p/twalk.3p @@ -0,0 +1 @@ +.so man3p/tsearch.3p diff --git a/man3p/tzname.3p b/man3p/tzname.3p new file mode 100644 index 000000000..3c5f1bc17 --- /dev/null +++ b/man3p/tzname.3p @@ -0,0 +1 @@ +.so man3p/tzset.3p diff --git a/man3p/tzset.3p b/man3p/tzset.3p new file mode 100644 index 000000000..7dab87928 --- /dev/null +++ b/man3p/tzset.3p @@ -0,0 +1,100 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TZSET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tzset +.SH NAME +daylight, timezone, tzname, tzset \- set timezone conversion information +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +\fP +.LP +\fBextern int daylight; +.br +extern long timezone; +.br +\fP +.LP +\fBextern char *tzname[2]; +.br +void tzset(void); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fItzset\fP() function shall use the value of the environment +variable \fITZ\fP to set time conversion information used by +\fIctime\fP() , \fIlocaltime\fP() , \fImktime\fP() , and \fIstrftime\fP() +\&. If \fITZ\fP is absent from the +environment, implementation-defined default timezone information shall +be used. +.LP +The \fItzset\fP() function shall set the external variable \fItzname\fP +as follows: +.sp +.RS +.nf + +\fBtzname[0] = "\fP\fIstd\fP\fB"; +tzname[1] = "\fP\fIdst\fP\fB"; +\fP +.fi +.RE +.LP +where \fIstd\fP and \fIdst\fP are as described in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables. +.LP +The \fItzset\fP() function also shall set the external variable \fIdaylight\fP +to 0 if Daylight Savings Time conversions should +never be applied for the timezone in use; otherwise, non-zero. The +external variable \fItimezone\fP shall be set to the +difference, in seconds, between Coordinated Universal Time (UTC) and +local standard time. +.SH RETURN VALUE +.LP +The \fItzset\fP() function shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +Example \fITZ\fP variables and their timezone differences are given +in the table below: +.TS C +center; l l. +TZ timezone +EST5EDT 5*60*60 +GMT0 0*60*60 +JST-9 -9*60*60 +MET-1MEST -1*60*60 +MST7MDT 7*60*60 +PST8PDT 8*60*60 +.TE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIctime\fP() , \fIlocaltime\fP() , \fImktime\fP() , \fIstrftime\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ualarm.3p b/man3p/ualarm.3p new file mode 100644 index 000000000..23aa1053b --- /dev/null +++ b/man3p/ualarm.3p @@ -0,0 +1,89 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UALARM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ualarm +.SH NAME +ualarm \- set the interval timer +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +useconds_t ualarm(useconds_t\fP \fIuseconds\fP\fB, useconds_t\fP \fIinterval\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIualarm\fP() function shall cause the SIGALRM signal to be generated +for the calling process after the number of realtime +microseconds specified by the \fIuseconds\fP argument has elapsed. +When the \fIinterval\fP argument is non-zero, repeated timeout +notification occurs with a period in microseconds specified by the +\fIinterval\fP argument. If the notification signal, SIGALRM, +is not caught or ignored, the calling process is terminated. +.LP +Implementations may place limitations on the granularity of timer +values. For each interval timer, if the requested timer value +requires a finer granularity than the implementation supports, the +actual timer value shall be rounded up to the next supported +value. +.LP +Interactions between \fIualarm\fP() and any of the following are unspecified: +.sp +.RS +.nf + +\fIalarm\fP() +\fInanosleep\fP() +\fIsetitimer\fP() +\fItimer_create\fP() +\fItimer_delete\fP() +\fItimer_getoverrun\fP() +\fItimer_gettime\fP() +\fItimer_settime\fP() +\fIsleep\fP() +.fi +.RE +.SH RETURN VALUE +.LP +The \fIualarm\fP() function shall return the number of microseconds +remaining from the previous \fIualarm\fP() call. If no +timeouts are pending or if \fIualarm\fP() has not previously been +called, \fIualarm\fP() shall return 0. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications are recommended to use \fInanosleep\fP() if the Timers +option is +supported, or \fIsetitimer\fP(), \fItimer_create\fP(), \fItimer_delete\fP(), +\fItimer_getoverrun\fP(), \fItimer_gettime\fP(), or \fItimer_settime\fP() +instead of this function. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIalarm\fP() , \fInanosleep\fP() , \fIsetitimer\fP() , \fIsleep\fP() +, \fItimer_create\fP() , \fItimer_delete\fP() , \fItimer_getoverrun\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ulimit.3p b/man3p/ulimit.3p new file mode 100644 index 000000000..3768085a4 --- /dev/null +++ b/man3p/ulimit.3p @@ -0,0 +1,92 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ULIMIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ulimit +.SH NAME +ulimit \- get and set process limits +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +long ulimit(int\fP \fIcmd\fP\fB, ...); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIulimit\fP() function shall control process limits. The process +limits that can be controlled by this function include +the maximum size of a single file that can be written (this is equivalent +to using \fIsetrlimit\fP() with RLIMIT_FSIZE). The \fIcmd\fP values, +defined in \fI\fP, include: +.TP 7 +UL_GETFSIZE +Return the file size limit (RLIMIT_FSIZE) of the process. The limit +shall be in units of 512-byte blocks and shall be inherited +by child processes. Files of any size can be read. The return value +shall be the integer part of the soft file size limit divided +by 512. If the result cannot be represented as a \fBlong\fP, the result +is unspecified. +.TP 7 +UL_SETFSIZE +Set the file size limit for output operations of the process to the +value of the second argument, taken as a \fBlong\fP, +multiplied by 512. If the result would overflow an \fBrlim_t\fP, the +actual value set is unspecified. Any process may decrease its +own limit, but only a process with appropriate privileges may increase +the limit. The return value shall be the integer part of the +new file size limit divided by 512. +.sp +.LP +The \fIulimit\fP() function shall not change the setting of \fIerrno\fP +if successful. +.LP +As all return values are permissible in a successful situation, an +application wishing to check for error situations should set +\fIerrno\fP to 0, then call \fIulimit\fP(), and, if it returns -1, +check to see if \fIerrno\fP is non-zero. +.SH RETURN VALUE +.LP +Upon successful completion, \fIulimit\fP() shall return the value +of the requested limit. Otherwise, -1 shall be returned and +\fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIulimit\fP() function shall fail and the limit shall be unchanged +if: +.TP 7 +.B EINVAL +The \fIcmd\fP argument is not valid. +.TP 7 +.B EPERM +A process not having appropriate privileges attempts to increase its +file size limit. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetrlimit\fP() , \fIsetrlimit\fP() , \fIwrite\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/umask.3p b/man3p/umask.3p new file mode 100644 index 000000000..8dbfff7a6 --- /dev/null +++ b/man3p/umask.3p @@ -0,0 +1,74 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UMASK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" umask +.SH NAME +umask \- set and get the file mode creation mask +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +mode_t umask(mode_t\fP \fIcmask\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIumask\fP() function shall set the process' file mode creation +mask to \fIcmask\fP and return the previous value of the +mask. Only the file permission bits of \fIcmask\fP (see \fI\fP) +are +used; the meaning of the other bits is implementation-defined. +.LP +The process' file mode creation mask is used during \fIopen\fP(), +\fIcreat\fP(), \fImkdir\fP(), and \fImkfifo\fP() to turn off permission +bits in the \fImode\fP argument supplied. Bit positions that +are set in \fIcmask\fP are cleared in the mode of the created file. +.SH RETURN VALUE +.LP +The file permission bits in the value returned by \fIumask\fP() shall +be the previous value of the file mode creation mask. The +state of any other bits in that value is unspecified, except that +a subsequent call to \fIumask\fP() with the returned value as +\fIcmask\fP shall leave the state of the mask the same as its state +before the first call, including any unspecified use of those +bits. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Unsigned argument and return types for \fIumask\fP() were proposed. +The return type and the argument were both changed to +\fBmode_t\fP. +.LP +Historical implementations have made use of additional bits in \fIcmask\fP +for their implementation-defined purposes. The +addition of the text that the meaning of other bits of the field is +implementation-defined permits these implementations to conform +to this volume of IEEE\ Std\ 1003.1-2001. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcreat\fP() , \fImkdir\fP() , \fImkfifo\fP() , +\fIopen\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/uname.3p b/man3p/uname.3p new file mode 100644 index 000000000..41014276a --- /dev/null +++ b/man3p/uname.3p @@ -0,0 +1,91 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UNAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" uname +.SH NAME +uname \- get the name of the current system +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int uname(struct utsname *\fP\fIname\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIuname\fP() function shall store information identifying the +current system in the structure pointed to by +\fIname\fP. +.LP +The \fIuname\fP() function uses the \fButsname\fP structure defined +in \fI\fP. +.LP +The \fIuname\fP() function shall return a string naming the current +system in the character array \fIsysname\fP. Similarly, +\fInodename\fP shall contain the name of this node within an implementation-defined +communications network. The arrays +\fIrelease\fP and \fIversion\fP shall further identify the operating +system. The array \fImachine\fP shall contain a name that +identifies the hardware that the system is running on. +.LP +The format of each member is implementation-defined. +.SH RETURN VALUE +.LP +Upon successful completion, a non-negative value shall be returned. +Otherwise, -1 shall be returned and \fIerrno\fP set to +indicate the error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The inclusion of the \fInodename\fP member in this structure does +not imply that it is sufficient information for interfacing +to communications networks. +.SH RATIONALE +.LP +The values of the structure members are not constrained to have any +relation to the version of this volume of +IEEE\ Std\ 1003.1-2001 implemented in the operating system. An application +should instead depend on _POSIX_VERSION and +related constants defined in \fI\fP. +.LP +This volume of IEEE\ Std\ 1003.1-2001 does not define the sizes of +the members of the structure and permits them to be +of different sizes, although most implementations define them all +to be the same size: eight bytes plus one byte for the string +terminator. That size for \fInodename\fP is not enough for use with +many networks. +.LP +The \fIuname\fP() function originated in System III, System V, and +related implementations, and it does not exist in Version 7 +or 4.3 BSD. The values it returns are set at system compile time in +those historical implementations. +.LP +4.3 BSD has \fIgethostname\fP() and \fIgethostid\fP(), which return +a symbolic name and a numeric value, respectively. There are +related \fIsethostname\fP() and \fIsethostid\fP() functions that are +used to set the values the other two functions return. The +former functions are included in this specification, the latter are +not. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ungetc.3p b/man3p/ungetc.3p new file mode 100644 index 000000000..82a50f1a1 --- /dev/null +++ b/man3p/ungetc.3p @@ -0,0 +1,78 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UNGETC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ungetc +.SH NAME +ungetc \- push byte back into input stream +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int ungetc(int\fP \fIc\fP\fB, FILE *\fP\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIungetc\fP() function shall push the byte specified by \fIc\fP +(converted to an \fBunsigned char\fP) back onto the +input stream pointed to by \fIstream\fP. The pushed-back bytes shall +be returned by subsequent reads on that stream in the reverse +order of their pushing. A successful intervening call (with the stream +pointed to by \fIstream\fP) to a file-positioning function +( \fIfseek\fP(), \fIfsetpos\fP(), or \fIrewind\fP()) shall discard +any pushed-back bytes for the stream. The external storage +corresponding to the stream shall be unchanged. +.LP +One byte of push-back shall be provided. If \fIungetc\fP() is called +too many times on the same stream without an intervening +read or file-positioning operation on that stream, the operation may +fail. +.LP +If the value of \fIc\fP equals that of the macro EOF, the operation +shall fail and the input stream shall be left +unchanged. +.LP +A successful call to \fIungetc\fP() shall clear the end-of-file indicator +for the stream. The value of the file-position +indicator for the stream after reading or discarding all pushed-back +bytes shall be the same as it was before the bytes were pushed +back. The file-position indicator is decremented by each successful +call to \fIungetc\fP(); if its value was 0 before a call, its +value is unspecified after the call. +.SH RETURN VALUE +.LP +Upon successful completion, \fIungetc\fP() shall return the byte pushed +back after conversion. Otherwise, it shall return +EOF. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfseek\fP() , \fIgetc\fP() , \fIfsetpos\fP() , +\fIread\fP() , \fIrewind\fP() , \fIsetbuf\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/ungetwc.3p b/man3p/ungetwc.3p new file mode 100644 index 000000000..bfa458641 --- /dev/null +++ b/man3p/ungetwc.3p @@ -0,0 +1,87 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UNGETWC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ungetwc +.SH NAME +ungetwc \- push wide-character code back into the input stream +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +wint_t ungetwc(wint_t\fP \fIwc\fP\fB, FILE *\fP\fIstream\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIungetwc\fP() function shall push the character corresponding +to the wide-character code specified by \fIwc\fP back onto +the input stream pointed to by \fIstream\fP. The pushed-back characters +shall be returned by subsequent reads on that stream in +the reverse order of their pushing. A successful intervening call +(with the stream pointed to by \fIstream\fP) to a +file-positioning function ( \fIfseek\fP(), \fIfsetpos\fP(), or \fIrewind\fP()) +discards any +pushed-back characters for the stream. The external storage corresponding +to the stream is unchanged. +.LP +At least one character of push-back shall be provided. If \fIungetwc\fP() +is called too many times on the same stream without +an intervening read or file-positioning operation on that stream, +the operation may fail. +.LP +If the value of \fIwc\fP equals that of the macro WEOF, the operation +shall fail and the input stream shall be left +unchanged. +.LP +A successful call to \fIungetwc\fP() shall clear the end-of-file indicator +for the stream. The value of the file-position +indicator for the stream after reading or discarding all pushed-back +characters shall be the same as it was before the characters +were pushed back. The file-position indicator is decremented (by one +or more) by each successful call to \fIungetwc\fP(); if its +value was 0 before a call, its value is unspecified after the call. +.SH RETURN VALUE +.LP +Upon successful completion, \fIungetwc\fP() shall return the wide-character +code corresponding to the pushed-back character. +Otherwise, it shall return WEOF. +.SH ERRORS +.LP +The \fIungetwc\fP() function may fail if: +.TP 7 +.B EILSEQ +An +invalid character sequence is detected, or a wide-character code does +not correspond to a valid character. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfseek\fP() , \fIfsetpos\fP() , \fIread\fP() , +\fIrewind\fP() , \fIsetbuf\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/unlink.3p b/man3p/unlink.3p new file mode 100644 index 000000000..534415d10 --- /dev/null +++ b/man3p/unlink.3p @@ -0,0 +1,269 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UNLINK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" unlink +.SH NAME +unlink \- remove a directory entry +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int unlink(const char *\fP\fIpath\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIunlink\fP() function shall remove a link to a file. If \fIpath\fP +names a symbolic link, \fIunlink\fP() shall remove +the symbolic link named by \fIpath\fP and shall not affect any file +or directory named by the contents of the symbolic link. +Otherwise, \fIunlink\fP() shall remove the link named by the pathname +pointed to by \fIpath\fP and shall decrement the link count +of the file referenced by the link. +.LP +When the file's link count becomes 0 and no process has the file open, +the space occupied by the file shall be freed and the +file shall no longer be accessible. If one or more processes have +the file open when the last link is removed, the link shall be +removed before \fIunlink\fP() returns, but the removal of the file +contents shall be postponed until all references to the file +are closed. +.LP +The \fIpath\fP argument shall not name a directory unless the process +has appropriate privileges and the implementation +supports using \fIunlink\fP() on directories. +.LP +Upon successful completion, \fIunlink\fP() shall mark for update the +\fIst_ctime\fP and \fIst_mtime\fP fields of the parent +directory. Also, if the file's link count is not 0, the \fIst_ctime\fP +field of the file shall be marked for update. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. If +-1 is returned, the named file shall not be changed. +.SH ERRORS +.LP +The \fIunlink\fP() function shall fail and shall not unlink the file +if: +.TP 7 +.B EACCES +Search permission is denied for a component of the path prefix, or +write permission is denied on the directory containing the +directory entry to be removed. +.TP 7 +.B EBUSY +The file named by the \fIpath\fP argument cannot be unlinked because +it is being used by the system or another process and the +implementation considers this an error. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.TP 7 +.B EPERM +The file named by \fIpath\fP is a directory, and either the calling +process does not have appropriate privileges, or the +implementation prohibits using \fIunlink\fP() on directories. +.TP 7 +.B EPERM \fRor\fP EACCES +.sp +The S_ISVTX flag is set on the directory containing the file referred +to by the \fIpath\fP argument and the caller is not the file +owner, nor is the caller the directory owner, nor does the caller +have appropriate privileges. +.TP 7 +.B EROFS +The directory entry to be unlinked is part of a read-only file system. +.sp +.LP +The \fIunlink\fP() function may fail and not unlink the file if: +.TP 7 +.B EBUSY +The file named by \fIpath\fP is a named STREAM. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.TP 7 +.B ETXTBSY +The entry to be unlinked is the last directory entry to a pure procedure +(shared text) file that is being executed. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Removing a Link to a File +.LP +The following example shows how to remove a link to a file named \fB/home/cnd/mod1\fP +by removing the entry named +\fB/modules/pass1\fP. +.sp +.RS +.nf + +\fB#include +.sp + +char *path = "/modules/pass1"; +int status; +\&... +status = unlink(path); +\fP +.fi +.RE +.SS Checking for an Error +.LP +The following example fragment creates a temporary password lock file +named \fBLOCKFILE\fP, which is defined as +\fB/etc/ptmp\fP, and gets a file descriptor for it. If the file cannot +be opened for writing, \fIunlink\fP() is used to remove +the link between the file descriptor and \fBLOCKFILE\fP. +.sp +.RS +.nf + +\fB#include +#include +#include +#include +#include +#include +.sp + +#define LOCKFILE "/etc/ptmp" +.sp + +int pfd; /* Integer for file descriptor returned by open call. */ +FILE *fpfd; /* File pointer for use in putpwent(). */ +\&... +/* Open password Lock file. If it exists, this is an error. */ +if ((pfd = open(LOCKFILE, O_WRONLY| O_CREAT | O_EXCL, S_IRUSR + | S_IWUSR | S_IRGRP | S_IROTH)) == -1) { + fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\\n"); + exit(1); +} +.sp + +/* Lock file created; proceed with fdopen of lock file so that + putpwent() can be used. + */ +if ((fpfd = fdopen(pfd, "w")) == NULL) { + close(pfd); + unlink(LOCKFILE); + exit(1); +} +\fP +.fi +.RE +.SS Replacing Files +.LP +The following example fragment uses \fIunlink\fP() to discard links +to files, so that they can be replaced with new versions of +the files. The first call removes the link to \fBLOCKFILE\fP if an +error occurs. Successive calls remove the links to +\fBSAVEFILE\fP and \fBPASSWDFILE\fP so that new links can be created, +then removes the link to \fBLOCKFILE\fP when it is no +longer needed. +.sp +.RS +.nf + +\fB#include +#include +#include +#include +#include +#include +.sp + +#define LOCKFILE "/etc/ptmp" +#define PASSWDFILE "/etc/passwd" +#define SAVEFILE "/etc/opasswd" +\&... +/* If no change was made, assume error and leave passwd unchanged. */ +if (!valid_change) { + fprintf(stderr, "Could not change password for user %s\\n", user); + unlink(LOCKFILE); + exit(1); +} +.sp + +/* Change permissions on new password file. */ +chmod(LOCKFILE, S_IRUSR | S_IRGRP | S_IROTH); +.sp + +/* Remove saved password file. */ +unlink(SAVEFILE); +.sp + +/* Save current password file. */ +link(PASSWDFILE, SAVEFILE); +.sp + +/* Remove current password file. */ +unlink(PASSWDFILE); +.sp + +/* Save new password file as current password file. */ +link(LOCKFILE,PASSWDFILE); +.sp + +/* Remove lock file. */ +unlink(LOCKFILE); +.sp + +exit(0); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +Applications should use \fIrmdir\fP() to remove a directory. +.SH RATIONALE +.LP +Unlinking a directory is restricted to the superuser in many historical +implementations for reasons given in \fIlink\fP() (see also \fIrename\fP()). +.LP +The meaning of [EBUSY] in historical implementations is "mount point +busy". Since this volume of +IEEE\ Std\ 1003.1-2001 does not cover the system administration concepts +of mounting and unmounting, the description of the +error was changed to "resource busy". (This meaning is used by some +device drivers when a second process tries to open an +exclusive use device.) The wording is also intended to allow implementations +to refuse to remove a directory if it is the root or +current working directory of any process. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclose\fP() , \fIlink\fP() , \fIremove\fP() , \fIrmdir\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/unlockpt.3p b/man3p/unlockpt.3p new file mode 100644 index 000000000..2cc05c799 --- /dev/null +++ b/man3p/unlockpt.3p @@ -0,0 +1,67 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UNLOCKPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" unlockpt +.SH NAME +unlockpt \- unlock a pseudo-terminal master/slave pair +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int unlockpt(int\fP \fIfildes\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIunlockpt\fP() function shall unlock the slave pseudo-terminal +device associated with the master to which \fIfildes\fP +refers. +.LP +Conforming applications shall ensure that they call \fIunlockpt\fP() +before opening the slave side of a pseudo-terminal +device. +.SH RETURN VALUE +.LP +Upon successful completion, \fIunlockpt\fP() shall return 0. Otherwise, +it shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fIunlockpt\fP() function may fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a file descriptor open for writing. +.TP 7 +.B EINVAL +The \fIfildes\fP argument is not associated with a master pseudo-terminal +device. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgrantpt\fP() , \fIopen\fP() , \fIptsname\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/unsetenv.3p b/man3p/unsetenv.3p new file mode 100644 index 000000000..ecb0bbedd --- /dev/null +++ b/man3p/unsetenv.3p @@ -0,0 +1,74 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UNSETENV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" unsetenv +.SH NAME +unsetenv \- remove an environment variable +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int unsetenv(const char *\fP\fIname\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIunsetenv\fP() function shall remove an environment variable +from the environment of the calling process. The \fIname\fP +argument points to a string, which is the name of the variable to +be removed. The named argument shall not contain an \fB'='\fP +character. If the named variable does not exist in the current environment, +the environment shall be unchanged and the function is +considered to have completed successfully. +.LP +If the application modifies \fIenviron\fP or the pointers to which +it points, the behavior of \fIunsetenv\fP() is undefined. +The \fIunsetenv\fP() function shall update the list of pointers to +which \fIenviron\fP points. +.LP +The \fIunsetenv\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +Upon successful completion, zero shall be returned. Otherwise, -1 +shall be returned, \fIerrno\fP set to indicate the error, and +the environment shall be unchanged. +.SH ERRORS +.LP +The \fIunsetenv\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fIname\fP argument is a null pointer, points to an empty string, +or points to a string containing an \fB'='\fP +character. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Refer to the RATIONALE section in \fIsetenv\fP() . +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetenv\fP() , \fIsetenv\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/usleep.3p b/man3p/usleep.3p new file mode 100644 index 000000000..f9c3e3939 --- /dev/null +++ b/man3p/usleep.3p @@ -0,0 +1,124 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "USLEEP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" usleep +.SH NAME +usleep \- suspend execution for an interval +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int usleep(useconds_t\fP \fIuseconds\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIusleep\fP() function shall cause the calling thread to be suspended +from execution until either the number of realtime +microseconds specified by the argument \fIuseconds\fP has elapsed +or a signal is delivered to the calling thread and its action is +to invoke a signal-catching function or to terminate the process. +The suspension time may be longer than requested due to the +scheduling of other activity by the system. +.LP +The \fIuseconds\fP argument shall be less than one million. If the +value of \fIuseconds\fP is 0, then the call has no +effect. +.LP +If a SIGALRM signal is generated for the calling process during execution +of \fIusleep\fP() and if the SIGALRM signal is being +ignored or blocked from delivery, it is unspecified whether \fIusleep\fP() +returns when the SIGALRM signal is scheduled. If the +signal is being blocked, it is also unspecified whether it remains +pending after \fIusleep\fP() returns or it is discarded. +.LP +If a SIGALRM signal is generated for the calling process during execution +of \fIusleep\fP(), except as a result of a prior call +to \fIalarm\fP(), and if the SIGALRM signal is not being ignored or +blocked from delivery, +it is unspecified whether that signal has any effect other than causing +\fIusleep\fP() to return. +.LP +If a signal-catching function interrupts \fIusleep\fP() and examines +or changes either the time a SIGALRM is scheduled to be +generated, the action associated with the SIGALRM signal, or whether +the SIGALRM signal is blocked from delivery, the results are +unspecified. +.LP +If a signal-catching function interrupts \fIusleep\fP() and calls +\fIsiglongjmp\fP() or \fIlongjmp\fP() to restore an +environment saved prior to the \fIusleep\fP() call, the action associated +with the SIGALRM signal and the time at which a SIGALRM +signal is scheduled to be generated are unspecified. It is also unspecified +whether the SIGALRM signal is blocked, unless the +process' signal mask is restored as part of the environment. +.LP +Implementations may place limitations on the granularity of timer +values. For each interval timer, if the requested timer value +requires a finer granularity than the implementation supports, the +actual timer value shall be rounded up to the next supported +value. +.LP +Interactions between \fIusleep\fP() and any of the following are unspecified: +.sp +.RS +.nf + +\fInanosleep\fP() +\fIsetitimer\fP() +\fItimer_create\fP() +\fItimer_delete\fP() +\fItimer_getoverrun\fP() +\fItimer_gettime\fP() +\fItimer_settime\fP() +\fIualarm\fP() +\fIsleep\fP() +.fi +.RE +.SH RETURN VALUE +.LP +Upon successful completion, \fIusleep\fP() shall return 0; otherwise, +it shall return -1 and set \fIerrno\fP to indicate the +error. +.SH ERRORS +.LP +The \fIusleep\fP() function may fail if: +.TP 7 +.B EINVAL +The time interval specified one million or more microseconds. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications are recommended to use \fInanosleep\fP() if the Timers +option is +supported, or \fIsetitimer\fP(), \fItimer_create\fP(), \fItimer_delete\fP(), +\fItimer_getoverrun\fP(), \fItimer_gettime\fP(), or \fItimer_settime\fP() +instead of this function. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIalarm\fP() , \fIgetitimer\fP() , \fInanosleep\fP() , \fIsigaction\fP() +, \fIsleep\fP() +, \fItimer_create\fP() , \fItimer_delete\fP() , \fItimer_getoverrun\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/utime.3p b/man3p/utime.3p new file mode 100644 index 000000000..05c41c673 --- /dev/null +++ b/man3p/utime.3p @@ -0,0 +1,125 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" utime +.SH NAME +utime \- set file access and modification times +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int utime(const char *\fP\fIpath\fP\fB, const struct utimbuf *\fP\fItimes\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIutime\fP() function shall set the access and modification times +of the file named by the \fIpath\fP argument. +.LP +If \fItimes\fP is a null pointer, the access and modification times +of the file shall be set to the current time. The effective +user ID of the process shall match the owner of the file, or the process +has write permission to the file or has appropriate +privileges, to use \fIutime\fP() in this manner. +.LP +If \fItimes\fP is not a null pointer, \fItimes\fP shall be interpreted +as a pointer to a \fButimbuf\fP structure and the +access and modification times shall be set to the values contained +in the designated structure. Only a process with the effective +user ID equal to the user ID of the file or a process with appropriate +privileges may use \fIutime\fP() this way. +.LP +The \fButimbuf\fP structure is defined in the \fI\fP header. +The times +in the structure \fButimbuf\fP are measured in seconds since the Epoch. +.LP +Upon successful completion, \fIutime\fP() shall mark the time of the +last file status change, \fIst_ctime\fP, to be updated; +see \fI\fP. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP shall be set to indicate the +error, and the file times shall not be affected. +.SH ERRORS +.LP +The \fIutime\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied by a component of the path prefix; or +the \fItimes\fP argument is a null pointer and the effective +user ID of the process does not match the owner of the file, the process +does not have write permission for the file, and the +process does not have appropriate privileges. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.TP 7 +.B EPERM +The \fItimes\fP argument is not a null pointer and the calling process' +effective user ID does not match the owner of the file +and the calling process does not have the appropriate privileges. +.TP 7 +.B EROFS +The file system containing the file is read-only. +.sp +.LP +The \fIutime\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIactime\fP structure member must be present so that an application +may set it, even though an implementation may ignore +it and not change the access time on the file. If an application intends +to leave one of the times of a file unchanged while +changing the other, it should use \fIstat\fP() to retrieve the file's +\fIst_atime\fP and +\fIst_mtime\fP parameters, set \fIactime\fP and \fImodtime\fP in the +buffer, and change one of them before making the +\fIutime\fP() call. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/utimes.3p b/man3p/utimes.3p new file mode 100644 index 000000000..70b1f1df7 --- /dev/null +++ b/man3p/utimes.3p @@ -0,0 +1,117 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "UTIMES" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" utimes +.SH NAME +utimes \- set file access and modification times (\fBLEGACY\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int utimes(const char *\fP\fIpath\fP\fB, const struct timeval\fP \fItimes[2]\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIutimes\fP() function shall set the access and modification +times of the file pointed to by the \fIpath\fP argument to +the value of the \fItimes\fP argument. The \fIutimes\fP() function +allows time specifications accurate to the microsecond. +.LP +For \fIutimes\fP(), the \fItimes\fP argument is an array of \fBtimeval\fP +structures. The first array member represents the +date and time of last access, and the second member represents the +date and time of last modification. The times in the +\fBtimeval\fP structure are measured in seconds and microseconds since +the Epoch, although rounding toward the nearest second may +occur. +.LP +If the \fItimes\fP argument is a null pointer, the access and modification +times of the file shall be set to the current time. +The effective user ID of the process shall match the owner of the +file, or has write access to the file or appropriate privileges +to use this call in this manner. Upon completion, \fIutimes\fP() shall +mark the time of the last file status change, +\fIst_ctime\fP, for update. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP shall be set to indicate the +error, and the file times shall not be affected. +.SH ERRORS +.LP +The \fIutimes\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied by a component of the path prefix; or +the \fItimes\fP argument is a null pointer and the effective +user ID of the process does not match the owner of the file and write +access is denied. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.TP 7 +.B EPERM +The \fItimes\fP argument is not a null pointer and the calling process' +effective user ID has write access to the file but +does not match the owner of the file and the calling process does +not have the appropriate privileges. +.TP 7 +.B EROFS +The file system containing the file is read-only. +.sp +.LP +The \fIutimes\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate result +whose length exceeds {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +For applications portability, the \fIutime\fP() function should be +used to set file +access and modification times instead of \fIutimes\fP(). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +This function may be withdrawn in a future version. +.SH SEE ALSO +.LP +\fIutime\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/va_arg.3p b/man3p/va_arg.3p new file mode 100644 index 000000000..af590bdaa --- /dev/null +++ b/man3p/va_arg.3p @@ -0,0 +1,32 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "VA_ARG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" va_arg +.SH NAME +va_arg, va_copy, va_end, va_start \- handle variable argument list +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +\fP \fItype\fP \fBva_arg(va_list\fP \fIap\fP\fB,\fP \fItype\fP\fB); +.br +void va_copy(va_list\fP \fIdest\fP\fB, va_list\fP \fIsrc\fP\fB); +.br +void va_end(va_list\fP \fIap\fP\fB); +.br +void va_start(va_list\fP \fIap\fP\fB,\fP \fIargN\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +Refer to the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP. +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/va_copy.3p b/man3p/va_copy.3p new file mode 100644 index 000000000..1b563f7a2 --- /dev/null +++ b/man3p/va_copy.3p @@ -0,0 +1 @@ +.so man3p/va_arg.3p diff --git a/man3p/va_end.3p b/man3p/va_end.3p new file mode 100644 index 000000000..1b563f7a2 --- /dev/null +++ b/man3p/va_end.3p @@ -0,0 +1 @@ +.so man3p/va_arg.3p diff --git a/man3p/va_start.3p b/man3p/va_start.3p new file mode 100644 index 000000000..1b563f7a2 --- /dev/null +++ b/man3p/va_start.3p @@ -0,0 +1 @@ +.so man3p/va_arg.3p diff --git a/man3p/vfork.3p b/man3p/vfork.3p new file mode 100644 index 000000000..533636e68 --- /dev/null +++ b/man3p/vfork.3p @@ -0,0 +1,113 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "VFORK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" vfork +.SH NAME +vfork \- create a new process; share virtual memory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +pid_t vfork(void); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIvfork\fP() function shall be equivalent to \fIfork\fP(), except +that the behavior +is undefined if the process created by \fIvfork\fP() either modifies +any data other than a variable of type \fBpid_t\fP used to +store the return value from \fIvfork\fP(), or returns from the function +in which \fIvfork\fP() was called, or calls any other +function before successfully calling \fI_exit\fP() or one of the \fIexec\fP +family of functions. +.SH RETURN VALUE +.LP +Upon successful completion, \fIvfork\fP() shall return 0 to the child +process and return the process ID of the child process to +the parent process. Otherwise, -1 shall be returned to the parent, +no child process shall be created, and \fIerrno\fP shall be set +to indicate the error. +.SH ERRORS +.LP +The \fIvfork\fP() function shall fail if: +.TP 7 +.B EAGAIN +The system-wide limit on the total number of processes under execution +would be exceeded, or the system-imposed limit on the +total number of processes under execution by a single user would be +exceeded. +.TP 7 +.B ENOMEM +There is insufficient swap space for the new process. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Conforming applications are recommended not to depend on \fIvfork\fP(), +but to use \fIfork\fP() instead. The \fIvfork\fP() function may be +withdrawn in a future version. +.LP +On some implementations, \fIvfork\fP() is equivalent to \fIfork\fP(). +.LP +The \fIvfork\fP() function differs from \fIfork\fP() only in that +the child process can +share code and data with the calling process (parent process). This +speeds cloning activity significantly at a risk to the +integrity of the parent process if \fIvfork\fP() is misused. +.LP +The use of \fIvfork\fP() for any purpose except as a prelude to an +immediate call to a function from the \fIexec\fP family, or to \fI_exit\fP(), +is not advised. +.LP +The \fIvfork\fP() function can be used to create new processes without +fully copying the address space of the old process. If a +forked process is simply going to call \fIexec\fP, the data space +copied from the parent to +the child by \fIfork\fP() is not used. This is particularly inefficient +in a paged +environment, making \fIvfork\fP() particularly useful. Depending upon +the size of the parent's data space, \fIvfork\fP() can give +a significant performance improvement over \fIfork\fP(). +.LP +The \fIvfork\fP() function can normally be used just like \fIfork\fP(). +It does not work, +however, to return while running in the child's context from the caller +of \fIvfork\fP() since the eventual return from +\fIvfork\fP() would then return to a no longer existent stack frame. +Care should be taken, also, to call \fI_exit\fP() rather than \fIexit\fP() +if \fIexec\fP cannot be used, since \fIexit\fP() flushes and closes +standard I/O channels, thereby damaging the parent process' standard +I/O data structures. (Even with \fIfork\fP(), it is wrong to call +\fIexit\fP(), since buffered +data would then be flushed twice.) +.LP +If signal handlers are invoked in the child process after \fIvfork\fP(), +they must follow the same rules as other code in the +child process. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +This function may be withdrawn in a future version. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIexit\fP() , \fIfork\fP() , \fIwait\fP() , the Base +Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/vfprintf.3p b/man3p/vfprintf.3p new file mode 100644 index 000000000..9eff46eb2 --- /dev/null +++ b/man3p/vfprintf.3p @@ -0,0 +1 @@ +.so man3p/vprintf.3p diff --git a/man3p/vfscanf.3p b/man3p/vfscanf.3p new file mode 100644 index 000000000..d2b5770bd --- /dev/null +++ b/man3p/vfscanf.3p @@ -0,0 +1 @@ +.so man3p/vscanf.3p diff --git a/man3p/vfwprintf.3p b/man3p/vfwprintf.3p new file mode 100644 index 000000000..ca09784e3 --- /dev/null +++ b/man3p/vfwprintf.3p @@ -0,0 +1 @@ +.so man3p/vwprintf.3p diff --git a/man3p/vfwscanf.3p b/man3p/vfwscanf.3p new file mode 100644 index 000000000..022cd008f --- /dev/null +++ b/man3p/vfwscanf.3p @@ -0,0 +1 @@ +.so man3p/vwscanf.3p diff --git a/man3p/vprintf.3p b/man3p/vprintf.3p new file mode 100644 index 000000000..56eb75b6f --- /dev/null +++ b/man3p/vprintf.3p @@ -0,0 +1,75 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "VFPRINTF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" vfprintf +.SH NAME +vfprintf, vprintf, vsnprintf, vsprintf \- format output of a stdarg +argument list +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int vfprintf(FILE *restrict\fP \fIstream\fP\fB, const char *restrict\fP +\fIformat\fP\fB, +.br +\ \ \ \ \ \ va_list\fP \fIap\fP\fB); +.br +int vprintf(const char *restrict\fP \fIformat\fP\fB, va_list\fP \fIap\fP\fB); +.br +int vsnprintf(char *restrict\fP \fIs\fP\fB, size_t\fP \fIn\fP\fB, +const char *restrict\fP \fIformat\fP\fB, +.br +\ \ \ \ \ \ va_list\fP \fIap\fP\fB); +.br +int vsprintf(char *restrict\fP \fIs\fP\fB, const char *restrict\fP +\fIformat\fP\fB, va_list\fP \fIap\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIvprintf\fP(), \fIvfprintf\fP(), \fIvsnprintf\fP(), and \fIvsprintf\fP() +functions shall be equivalent to \fIprintf\fP(), \fIfprintf\fP(), +\fIsnprintf\fP(), and \fIsprintf\fP() respectively, +except that instead of being called with a variable number of arguments, +they are called with an argument list as defined by \fI\fP. +.LP +These functions shall not invoke the \fIva_end\fP macro. As these +functions invoke the \fIva_arg\fP macro, the value of +\fIap\fP after the return is unspecified. +.SH RETURN VALUE +.LP +Refer to \fIfprintf\fP() . +.SH ERRORS +.LP +Refer to \fIfprintf\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications using these functions should call \fIva_end\fP(\fIap\fP) +afterwards to clean up. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfprintf\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/vscanf.3p b/man3p/vscanf.3p new file mode 100644 index 000000000..5790fc6d6 --- /dev/null +++ b/man3p/vscanf.3p @@ -0,0 +1,71 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "VFSCANF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" vfscanf +.SH NAME +vfscanf, vscanf, vsscanf \- format input of a stdarg argument list +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int vfscanf(FILE *restrict\fP \fIstream\fP\fB, const char *restrict\fP +\fIformat\fP\fB, +.br +\ \ \ \ \ \ va_list\fP \fIarg\fP\fB); +.br +int vscanf(const char *restrict\fP \fIformat\fP\fB, va_list\fP \fIarg\fP\fB); +.br +int vsscanf(const char *restrict\fP \fIs\fP\fB, const char *restrict\fP +\fIformat\fP\fB, +.br +\ \ \ \ \ \ va_list\fP \fIarg\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIvscanf\fP(), \fIvfscanf\fP(), and \fIvsscanf\fP() functions +shall be equivalent to the \fIscanf\fP(), \fIfscanf\fP(), and \fIsscanf\fP() +functions, respectively, except that instead of being called with +a variable number +of arguments, they are called with an argument list as defined in +the \fI\fP header. These functions shall not invoke the +\fIva_end\fP macro. As these +functions invoke the \fIva_arg\fP macro, the value of \fIap\fP after +the return is unspecified. +.SH RETURN VALUE +.LP +Refer to \fIfscanf\fP() . +.SH ERRORS +.LP +Refer to \fIfscanf\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications using these functions should call \fIva_end\fP( \fIap\fP) +afterwards to clean up. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfscanf\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/vsnprintf.3p b/man3p/vsnprintf.3p new file mode 100644 index 000000000..9eff46eb2 --- /dev/null +++ b/man3p/vsnprintf.3p @@ -0,0 +1 @@ +.so man3p/vprintf.3p diff --git a/man3p/vsprintf.3p b/man3p/vsprintf.3p new file mode 100644 index 000000000..9eff46eb2 --- /dev/null +++ b/man3p/vsprintf.3p @@ -0,0 +1 @@ +.so man3p/vprintf.3p diff --git a/man3p/vsscanf.3p b/man3p/vsscanf.3p new file mode 100644 index 000000000..d2b5770bd --- /dev/null +++ b/man3p/vsscanf.3p @@ -0,0 +1 @@ +.so man3p/vscanf.3p diff --git a/man3p/vswprintf.3p b/man3p/vswprintf.3p new file mode 100644 index 000000000..ca09784e3 --- /dev/null +++ b/man3p/vswprintf.3p @@ -0,0 +1 @@ +.so man3p/vwprintf.3p diff --git a/man3p/vswscanf.3p b/man3p/vswscanf.3p new file mode 100644 index 000000000..022cd008f --- /dev/null +++ b/man3p/vswscanf.3p @@ -0,0 +1 @@ +.so man3p/vwscanf.3p diff --git a/man3p/vwprintf.3p b/man3p/vwprintf.3p new file mode 100644 index 000000000..bf13bb17e --- /dev/null +++ b/man3p/vwprintf.3p @@ -0,0 +1,75 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "VFWPRINTF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" vfwprintf +.SH NAME +vfwprintf, vswprintf, vwprintf \- wide-character formatted output of +a stdarg argument list +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +#include +.br +.sp +int vfwprintf(FILE *restrict\fP \fIstream\fP\fB, const wchar_t *restrict\fP +\fIformat\fP\fB, +.br +\ \ \ \ \ \ va_list\fP \fIarg\fP\fB); +.br +int vswprintf(wchar_t *restrict\fP \fIws\fP\fB, size_t\fP \fIn\fP\fB, +.br +\ \ \ \ \ \ const wchar_t *restrict\fP \fIformat\fP\fB, va_list\fP +\fIarg\fP\fB); +.br +int vwprintf(const wchar_t *restrict\fP \fIformat\fP\fB, va_list\fP +\fIarg\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIvfwprintf\fP(), \fIvswprintf\fP(), and \fIvwprintf\fP() functions +shall be equivalent to \fIfwprintf\fP(), \fIswprintf\fP(), and \fIwprintf\fP() +respectively, except that instead of being called with a variable +number of +arguments, they are called with an argument list as defined by \fI\fP. +.LP +These functions shall not invoke the \fIva_end\fP macro. However, +as these functions do invoke the \fIva_arg\fP macro, the +value of \fIap\fP after the return is unspecified. +.SH RETURN VALUE +.LP +Refer to \fIfwprintf\fP() . +.SH ERRORS +.LP +Refer to \fIfwprintf\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications using these functions should call \fIva_end\fP(\fIap\fP) +afterwards to clean up. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfwprintf\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/vwscanf.3p b/man3p/vwscanf.3p new file mode 100644 index 000000000..da95107e9 --- /dev/null +++ b/man3p/vwscanf.3p @@ -0,0 +1,75 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "VFWSCANF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" vfwscanf +.SH NAME +vfwscanf, vswscanf, vwscanf \- wide-character formatted input of a +stdarg argument list +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +#include +.br +.sp +int vfwscanf(FILE *restrict\fP \fIstream\fP\fB, const wchar_t *restrict\fP +\fIformat\fP\fB, +.br +\ \ \ \ \ \ va_list\fP \fIarg\fP\fB); +.br +int vswscanf(const wchar_t *restrict\fP \fIws\fP\fB, const wchar_t +*restrict\fP \fIformat\fP\fB, +.br +\ \ \ \ \ \ va_list\fP \fIarg\fP\fB); +.br +int vwscanf(const wchar_t *restrict\fP \fIformat\fP\fB, va_list\fP +\fIarg\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIvfwscanf\fP(), \fIvswscanf\fP(), and \fIvwscanf\fP() functions +shall be equivalent to the \fIfwscanf\fP(), \fIswscanf\fP(), and \fIwscanf\fP() +functions, respectively, except that instead of being called with +a variable number +of arguments, they are called with an argument list as defined in +the \fI\fP header. These functions shall not invoke the +\fIva_end\fP macro. As these +functions invoke the \fIva_arg\fP macro, the value of \fIap\fP after +the return is unspecified. +.SH RETURN VALUE +.LP +Refer to \fIfwscanf\fP() . +.SH ERRORS +.LP +Refer to \fIfwscanf\fP() . +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Applications using these functions should call \fIva_end\fP( \fIap\fP) +afterwards to clean up. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfwscanf\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wait.3p b/man3p/wait.3p new file mode 100644 index 000000000..72821507c --- /dev/null +++ b/man3p/wait.3p @@ -0,0 +1,486 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WAIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wait +.SH NAME +wait, waitpid \- wait for a child process to stop or terminate +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +pid_t wait(int *\fP\fIstat_loc\fP\fB); +.br +pid_t waitpid(pid_t\fP \fIpid\fP\fB, int *\fP\fIstat_loc\fP\fB, int\fP +\fIoptions\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwait\fP() and \fIwaitpid\fP() functions shall obtain status +information pertaining to one of the caller's child +processes. Various options permit status information to be obtained +for child processes that have terminated or stopped. If status +information is available for two or more child processes, the order +in which their status is reported is unspecified. +.LP +The \fIwait\fP() function shall suspend execution of the calling thread +until status information for one of the terminated +child processes of the calling process is available, or until delivery +of a signal whose action is either to execute a +signal-catching function or to terminate the process. If more than +one thread is suspended in \fIwait\fP() or \fIwaitpid\fP() +awaiting termination of the same process, exactly one thread shall +return the process status at the time of the target process +termination. If status information is available prior to the call +to \fIwait\fP(), return shall be immediate. +.LP +The \fIwaitpid\fP() function shall be equivalent to \fIwait\fP() if +the \fIpid\fP argument is (\fBpid_t\fP)-1 and the +\fIoptions\fP argument is 0. Otherwise, its behavior shall be modified +by the values of the \fIpid\fP and \fIoptions\fP +arguments. +.LP +The \fIpid\fP argument specifies a set of child processes for which +\fIstatus\fP is requested. The \fIwaitpid\fP() function +shall only return the status of a child process from this set: +.IP " *" 3 +If \fIpid\fP is equal to (\fBpid_t\fP)-1, \fIstatus\fP is requested +for any child process. In this respect, \fIwaitpid\fP() +is then equivalent to \fIwait\fP(). +.LP +.IP " *" 3 +If \fIpid\fP is greater than 0, it specifies the process ID of a single +child process for which \fIstatus\fP is requested. +.LP +.IP " *" 3 +If \fIpid\fP is 0, \fIstatus\fP is requested for any child process +whose process group ID is equal to that of the calling +process. +.LP +.IP " *" 3 +If \fIpid\fP is less than (\fBpid_t\fP)-1, \fIstatus\fP is requested +for any child process whose process group ID is equal to +the absolute value of \fIpid\fP. +.LP +.LP +The \fIoptions\fP argument is constructed from the bitwise-inclusive +OR of zero or more of the following flags, defined in the +\fI\fP header: +.TP 7 +WCONTINUED +The \fIwaitpid\fP() function shall report the status of any continued +child process specified by \fIpid\fP whose status has not +been reported since it continued from a job control stop. +.TP 7 +WNOHANG +The \fIwaitpid\fP() function shall not suspend execution of the calling +thread if \fIstatus\fP is not immediately available +for one of the child processes specified by \fIpid\fP. +.TP 7 +WUNTRACED +The status of any child processes specified by \fIpid\fP that are +stopped, and whose status has not yet been reported since +they stopped, shall also be reported to the requesting process. +.sp +.LP +If the calling process has SA_NOCLDWAIT set or has SIGCHLD set to +SIG_IGN, and the process has no unwaited-for children that were +transformed into zombie processes, the calling thread shall block +until all of the children of the process containing the calling +thread terminate, and \fIwait\fP() and \fIwaitpid\fP() shall fail +and set \fIerrno\fP to [ECHILD]. +.LP +If \fIwait\fP() or \fIwaitpid\fP() return because the status of a +child process is available, these functions shall return a +value equal to the process ID of the child process. In this case, +if the value of the argument \fIstat_loc\fP is not a null +pointer, information shall be stored in the location pointed to by +\fIstat_loc\fP. The value stored at the location pointed to by +\fIstat_loc\fP shall be 0 if and only if the status returned is from +a terminated child process that terminated by one of the +following means: +.IP " 1." 4 +The process returned 0 from \fImain\fP(). +.LP +.IP " 2." 4 +The process called \fI_exit\fP() or \fIexit\fP() +with a \fIstatus\fP argument of 0. +.LP +.IP " 3." 4 +The process was terminated because the last thread in the process +terminated. +.LP +.LP +Regardless of its value, this information may be interpreted using +the following macros, which are defined in \fI\fP and +evaluate to integral expressions; the \fIstat_val\fP argument is +the integer value pointed to by \fIstat_loc\fP. +.TP 7 +WIFEXITED(\fIstat_val\fP) +.sp +Evaluates to a non-zero value if \fIstatus\fP was returned for a child +process that terminated normally. +.TP 7 +WEXITSTATUS(\fIstat_val\fP) +.sp +If the value of WIFEXITED(\fIstat_val\fP) is non-zero, this macro +evaluates to the low-order 8 bits of the \fIstatus\fP argument +that the child process passed to \fI_exit\fP() or \fIexit\fP(), or +the value the child process returned from \fImain\fP(). +.TP 7 +WIFSIGNALED(\fIstat_val\fP) +.sp +Evaluates to a non-zero value if \fIstatus\fP was returned for a child +process that terminated due to the receipt of a signal that +was not caught (see \fI\fP). +.TP 7 +WTERMSIG(\fIstat_val\fP) +.sp +If the value of WIFSIGNALED(\fIstat_val\fP) is non-zero, this macro +evaluates to the number of the signal that caused the +termination of the child process. +.TP 7 +WIFSTOPPED(\fIstat_val\fP) +.sp +Evaluates to a non-zero value if \fIstatus\fP was returned for a child +process that is currently stopped. +.TP 7 +WSTOPSIG(\fIstat_val\fP) +.sp +If the value of WIFSTOPPED(\fIstat_val\fP) is non-zero, this macro +evaluates to the number of the signal that caused the child +process to stop. +.TP 7 +WIFCONTINUED(\fIstat_val\fP) +.sp +Evaluates to a non-zero value if \fIstatus\fP was returned for a child +process that has continued from a job control stop. +.sp +.LP +It is unspecified whether the \fIstatus\fP value returned by calls +to \fIwait\fP() or \fIwaitpid\fP() for processes created by +\fIposix_spawn\fP() or \fIposix_spawnp\fP() can indicate a WIFSTOPPED(\fIstat_val\fP) +before subsequent calls to +\fIwait\fP() or \fIwaitpid\fP() indicate WIFEXITED(\fIstat_val\fP) +as the result of an error detected before the new process +image starts executing. +.LP +It is unspecified whether the \fIstatus\fP value returned by calls +to \fIwait\fP() or \fIwaitpid\fP() for processes created +by \fIposix_spawn\fP() or \fIposix_spawnp\fP() can indicate a WIFSIGNALED(\fIstat_val\fP) +if a signal is sent to the +parent's process group after \fIposix_spawn\fP() or \fIposix_spawnp\fP() +is called. +.LP +If the information pointed to by \fIstat_loc\fP was stored by a call +to \fIwaitpid\fP() that specified the WUNTRACED flag +\ and did not specify the WCONTINUED flag, exactly one of the +macros WIFEXITED(*\fIstat_loc\fP), WIFSIGNALED(*\fIstat_loc\fP), and +WIFSTOPPED(*\fIstat_loc\fP) shall evaluate to a non-zero +value. +.LP +If the information pointed to by \fIstat_loc\fP was stored by a call +to \fIwaitpid\fP() that specified the WUNTRACED \ and +WCONTINUED flags, exactly one of the macros +WIFEXITED(*\fIstat_loc\fP), WIFSIGNALED(*\fIstat_loc\fP), WIFSTOPPED(*\fIstat_loc\fP), +\ and +WIFCONTINUED(*\fIstat_loc\fP) shall evaluate to a non-zero +value. +.LP +If the information pointed to by \fIstat_loc\fP was stored by a call +to \fIwaitpid\fP() that did not specify the WUNTRACED +\ or WCONTINUED flags, or by a call to the \fIwait\fP() +function, exactly one of the macros WIFEXITED(*\fIstat_loc\fP) and +WIFSIGNALED(*\fIstat_loc\fP) shall evaluate to a non-zero +value. +.LP +If the information pointed to by \fIstat_loc\fP was stored by a call +to \fIwaitpid\fP() that did not specify the WUNTRACED +flag +\ and specified the WCONTINUED flag, or by a call to the +\fIwait\fP() function, exactly one of the macros WIFEXITED(*\fIstat_loc\fP), +WIFSIGNALED(*\fIstat_loc\fP), \ and +WIFCONTINUED(*\fIstat_loc\fP) shall evaluate to a non-zero +value. +.LP +If _POSIX_REALTIME_SIGNALS is defined, and the implementation queues +the SIGCHLD signal, then if \fIwait\fP() or +\fIwaitpid\fP() returns because the status of a child process is available, +any pending SIGCHLD signal associated with the process +ID of the child process shall be discarded. Any other pending SIGCHLD +signals shall remain pending. +.LP +Otherwise, if SIGCHLD is blocked, if \fIwait\fP() or \fIwaitpid\fP() +return because the status of a child process is +available, any pending SIGCHLD signal shall be cleared unless the +status of another child process is available. +.LP +For all other conditions, it is unspecified whether child \fIstatus\fP +will be available when a SIGCHLD signal is +delivered. +.LP +There may be additional implementation-defined circumstances under +which \fIwait\fP() or \fIwaitpid\fP() report \fIstatus\fP. +This shall not occur unless the calling process or one of its child +processes explicitly makes use of a non-standard extension. In +these cases the interpretation of the reported \fIstatus\fP is implementation-defined. +.LP +If a parent process terminates without waiting for all of its child +processes to terminate, the remaining child processes shall be +assigned a new parent process ID corresponding to an implementation-defined +system process. +.SH RETURN VALUE +.LP +If \fIwait\fP() or \fIwaitpid\fP() returns because the status of a +child process is available, these functions shall return a +value equal to the process ID of the child process for which \fIstatus\fP +is reported. If \fIwait\fP() or \fIwaitpid\fP() +returns due to the delivery of a signal to the calling process, -1 +shall be returned and \fIerrno\fP set to [EINTR]. If +\fIwaitpid\fP() was invoked with WNOHANG set in \fIoptions\fP, it +has at least one child process specified by \fIpid\fP for +which \fIstatus\fP is not available, and \fIstatus\fP is not available +for any process specified by \fIpid\fP, 0 is returned. +Otherwise, (\fBpid_t\fP)-1 shall be returned, and \fIerrno\fP set +to indicate the error. +.SH ERRORS +.LP +The \fIwait\fP() function shall fail if: +.TP 7 +.B ECHILD +The calling process has no existing unwaited-for child processes. +.TP 7 +.B EINTR +The function was interrupted by a signal. The value of the location +pointed to by \fIstat_loc\fP is undefined. +.sp +.LP +The \fIwaitpid\fP() function shall fail if: +.TP 7 +.B ECHILD +The process specified by \fIpid\fP does not exist or is not a child +of the calling process, or the process group specified by +\fIpid\fP does not exist or does not have any member process that +is a child of the calling process. +.TP 7 +.B EINTR +The function was interrupted by a signal. The value of the location +pointed to by \fIstat_loc\fP is undefined. +.TP 7 +.B EINVAL +The \fIoptions\fP argument is not valid. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +A call to the \fIwait\fP() or \fIwaitpid\fP() function only returns +\fIstatus\fP on an immediate child process of the calling +process; that is, a child that was produced by a single \fIfork\fP() +call (perhaps followed +by an \fIexec\fP or other function calls) from the parent. If a child +produces grandchildren +by further use of \fIfork\fP(), none of those grandchildren nor any +of their descendants +affect the behavior of a \fIwait\fP() from the original parent process. +Nothing in this volume of IEEE\ Std\ 1003.1-2001 +prevents an implementation from providing extensions that permit a +process to get \fIstatus\fP from a grandchild or any other +process, but a process that does not use such extensions must be guaranteed +to see \fIstatus\fP from only its direct children. +.LP +The \fIwaitpid\fP() function is provided for three reasons: +.IP " 1." 4 +To support job control +.LP +.IP " 2." 4 +To permit a non-blocking version of the \fIwait\fP() function +.LP +.IP " 3." 4 +To permit a library routine, such as \fIsystem\fP() or \fIpclose\fP(), +to wait for its children without interfering with other terminated +children for +which the process has not waited +.LP +.LP +The first two of these facilities are based on the \fIwait3\fP() function +provided by 4.3 BSD. The function uses the +\fIoptions\fP argument, which is equivalent to an argument to \fIwait3\fP(). +The WUNTRACED flag is used only in conjunction with +job control on systems supporting job control. Its name comes from +4.3 BSD and refers to the fact that there are two types of +stopped processes in that implementation: processes being traced via +the \fIptrace\fP() debugging facility and (untraced) +processes stopped by job control signals. Since \fIptrace\fP() is +not part of this volume of IEEE\ Std\ 1003.1-2001, only +the second type is relevant. The name WUNTRACED was retained because +its usage is the same, even though the name is not intuitively +meaningful in this context. +.LP +The third reason for the \fIwaitpid\fP() function is to permit independent +sections of a process to spawn and wait for children +without interfering with each other. For example, the following problem +occurs in developing a portable shell, or command +interpreter: +.sp +.RS +.nf + +\fBstream = popen("/bin/true"); +(void) system("sleep 100"); +(void) pclose(stream); +\fP +.fi +.RE +.LP +On all historical implementations, the final \fIpclose\fP() fails +to reap the +\fIwait\fP() \fIstatus\fP of the \fIpopen\fP(). +.LP +The status values are retrieved by macros, rather than given as specific +bit encodings as they are in most historical +implementations (and thus expected by existing programs). This was +necessary to eliminate a limitation on the number of signals an +implementation can support that was inherent in the traditional encodings. +This volume of IEEE\ Std\ 1003.1-2001 does +require that a \fIstatus\fP value of zero corresponds to a process +calling \fI_exit\fP(0), as this is the most common encoding +expected by existing programs. Some of the macro names were adopted +from 4.3 BSD. +.LP +These macros syntactically operate on an arbitrary integer value. +The behavior is undefined unless that value is one stored by a +successful call to \fIwait\fP() or \fIwaitpid\fP() in the location +pointed to by the \fIstat_loc\fP argument. An early proposal +attempted to make this clearer by specifying each argument as *\fIstat_loc\fP +rather than \fIstat_val\fP. However, that did not +follow the conventions of other specifications in this volume of IEEE\ Std\ 1003.1-2001 +or traditional usage. It also could +have implied that the argument to the macro must literally be *\fIstat_loc\fP; +in fact, that value can be stored or passed as an +argument to other functions before being interpreted by these macros. +.LP +The extension that affects \fIwait\fP() and \fIwaitpid\fP() and is +common in historical implementations is the \fIptrace\fP() +function. It is called by a child process and causes that child to +stop and return a \fIstatus\fP that appears identical to the +\fIstatus\fP indicated by WIFSTOPPED. The \fIstatus\fP of \fIptrace\fP() +children is traditionally returned regardless of the +WUNTRACED flag (or by the \fIwait\fP() function). Most applications +do not need to concern themselves with such extensions because +they have control over what extensions they or their children use. +However, applications, such as command interpreters, that invoke +arbitrary processes may see this behavior when those arbitrary processes +misuse such extensions. +.LP +Implementations that support \fBcore\fP file creation or other implementation-defined +actions on termination of some processes +traditionally provide a bit in the \fIstatus\fP returned by \fIwait\fP() +to indicate that such actions have occurred. +.LP +Allowing the \fIwait\fP() family of functions to discard a pending +SIGCHLD signal that is associated with a successfully +waited-for child process puts them into the \fIsigwait\fP() and \fIsigwaitinfo\fP() +category with respect to SIGCHLD. +.LP +This definition allows implementations to treat a pending SIGCHLD +signal as accepted by the process in \fIwait\fP(), with the +same meaning of "accepted" as when that word is applied to the \fIsigwait\fP() +family of +functions. +.LP +Allowing the \fIwait\fP() family of functions to behave this way permits +an implementation to be able to deal precisely with +SIGCHLD signals. +.LP +In particular, an implementation that does accept (discard) the SIGCHLD +signal can make the following guarantees regardless of +the queuing depth of signals in general (the list of waitable children +can hold the SIGCHLD queue): +.IP " 1." 4 +If a SIGCHLD signal handler is established via \fIsigaction\fP() without +the +SA_RESETHAND flag, SIGCHLD signals can be accurately counted; that +is, exactly one SIGCHLD signal will be delivered to or accepted +by the process for every child process that terminates. +.LP +.IP " 2." 4 +A single \fIwait\fP() issued from a SIGCHLD signal handler can be +guaranteed to return immediately with status information for +a child process. +.LP +.IP " 3." 4 +When SA_SIGINFO is requested, the SIGCHLD signal handler can be guaranteed +to receive a non-NULL pointer to a \fBsiginfo_t\fP +structure that describes a child process for which a wait via \fIwaitpid\fP() +or \fIwaitid\fP() will not block or fail. +.LP +.IP " 4." 4 +The \fIsystem\fP() function will not cause a process' SIGCHLD handler +to be called as a +result of the \fIfork\fP()/ \fIexec\fP executed within +\fIsystem\fP() because \fIsystem\fP() will accept +the SIGCHLD signal when it performs a \fIwaitpid\fP() for its child +process. This is a desirable behavior of \fIsystem\fP() so that it +can be used in a library without causing side effects to the application +linked with the library. +.LP +.LP +An implementation that does not permit the \fIwait\fP() family of +functions to accept (discard) a pending SIGCHLD signal +associated with a successfully waited-for child, cannot make the guarantees +described above for the following reasons: +.TP 7 +Guarantee #1 +.sp +Although it might be assumed that reliable queuing of all SIGCHLD +signals generated by the system can make this guarantee, the +counter-example is the case of a process that blocks SIGCHLD and performs +an indefinite loop of \fIfork\fP()/ \fIwait\fP() operations. If the +implementation supports queued signals, then +eventually the system will run out of memory for the queue. The guarantee +cannot be made because there must be some limit to the +depth of queuing. +.TP 7 +Guarantees #2 and #3 +.sp +These cannot be guaranteed unless the \fIwait\fP() family of functions +accepts the SIGCHLD signal. Otherwise, a \fIfork\fP()/ \fIwait\fP() +executed while SIGCHLD is blocked (as in the \fIsystem\fP() function) +will result in an invocation of the handler when SIGCHLD is unblocked, +after the process has disappeared. +.TP 7 +Guarantee #4 +.sp +Although possible to make this guarantee, \fIsystem\fP() would have +to set the SIGCHLD +handler to SIG_DFL so that the SIGCHLD signal generated by its \fIfork\fP() +would be +discarded (the SIGCHLD default action is to be ignored), then restore +it to its previous setting. This would have the undesirable +side effect of discarding all SIGCHLD signals pending to the process. +.sp +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIexit\fP() , \fIfork\fP() , \fIwaitid\fP() , the +Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/waitid.3p b/man3p/waitid.3p new file mode 100644 index 000000000..4405bc74a --- /dev/null +++ b/man3p/waitid.3p @@ -0,0 +1,121 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WAITID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" waitid +.SH NAME +waitid \- wait for a child process to change state +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int waitid(idtype_t\fP \fIidtype\fP\fB, id_t\fP \fIid\fP\fB, siginfo_t +*\fP\fIinfop\fP\fB, int\fP +\fIoptions\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIwaitid\fP() function shall suspend the calling thread until +one child of the process containing the calling thread +changes state. It records the current state of a child in the structure +pointed to by \fIinfop\fP. If a child process changed +state prior to the call to \fIwaitid\fP(), \fIwaitid\fP() shall return +immediately. If more than one thread is suspended in \fIwait\fP() +or \fIwaitpid\fP() waiting for termination +of the same process, exactly one thread shall return the process status +at the time of the target process termination. +.LP +The \fIidtype\fP and \fIid\fP arguments are used to specify which +children \fIwaitid\fP() waits for. +.LP +If \fIidtype\fP is P_PID, \fIwaitid\fP() shall wait for the child +with a process ID equal to (\fBpid_t\fP)\fIid\fP. +.LP +If \fIidtype\fP is P_PGID, \fIwaitid\fP() shall wait for any child +with a process group ID equal to +(\fBpid_t\fP)\fIid\fP. +.LP +If \fIidtype\fP is P_ALL, \fIwaitid\fP() shall wait for any children +and \fIid\fP is ignored. +.LP +The \fIoptions\fP argument is used to specify which state changes +\fIwaitid\fP() shall wait for. It is formed by OR'ing +together one or more of the following flags: +.TP 7 +WEXITED +Wait for processes that have exited. +.TP 7 +WSTOPPED +Status shall be returned for any child that has stopped upon receipt +of a signal. +.TP 7 +WCONTINUED +Status shall be returned for any child that was stopped and has been +continued. +.TP 7 +WNOHANG +Return immediately if there are no children to wait for. +.TP 7 +WNOWAIT +Keep the process whose status is returned in \fIinfop\fP in a waitable +state. This shall not affect the state of the process; +the process may be waited for again after this call completes. +.sp +.LP +The application shall ensure that the \fIinfop\fP argument points +to a \fBsiginfo_t\fP structure. If \fIwaitid\fP() returns +because a child process was found that satisfied the conditions indicated +by the arguments \fIidtype\fP and \fIoptions\fP, then +the structure pointed to by \fIinfop\fP shall be filled in by the +system with the status of the process. The \fIsi_signo\fP +member shall always be equal to SIGCHLD. +.SH RETURN VALUE +.LP +If WNOHANG was specified and there are no children to wait for, 0 +shall be returned. If \fIwaitid\fP() returns due to the +change of state of one of its children, 0 shall be returned. Otherwise, +-1 shall be returned and \fIerrno\fP set to indicate the +error. +.SH ERRORS +.LP +The \fIwaitid\fP() function shall fail if: +.TP 7 +.B ECHILD +The calling process has no existing unwaited-for child processes. +.TP 7 +.B EINTR +The \fIwaitid\fP() function was interrupted by a signal. +.TP 7 +.B EINVAL +An invalid value was specified for \fIoptions\fP, or \fIidtype\fP +and \fIid\fP specify an invalid set of processes. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIexit\fP() , \fIwait\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/waitpid.3p b/man3p/waitpid.3p new file mode 100644 index 000000000..f84d64ea7 --- /dev/null +++ b/man3p/waitpid.3p @@ -0,0 +1 @@ +.so man3p/wait.3p diff --git a/man3p/wcrtomb.3p b/man3p/wcrtomb.3p new file mode 100644 index 000000000..1e4981a7f --- /dev/null +++ b/man3p/wcrtomb.3p @@ -0,0 +1,101 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCRTOMB" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcrtomb +.SH NAME +wcrtomb \- convert a wide-character code to a character (restartable) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t wcrtomb(char *restrict\fP \fIs\fP\fB, wchar_t\fP \fIwc\fP\fB, +mbstate_t *restrict\fP \fIps\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If \fIs\fP is a null pointer, the \fIwcrtomb\fP() function shall be +equivalent to the call: +.sp +.RS +.nf + +\fBwcrtomb(\fP\fIbuf\fP\fB, L'\\0',\fP \fIps\fP\fB) +\fP +.fi +.RE +.LP +where \fIbuf\fP is an internal buffer. +.LP +If \fIs\fP is not a null pointer, the \fIwcrtomb\fP() function shall +determine the number of bytes needed to represent the +character that corresponds to the wide character given by \fIwc\fP +(including any shift sequences), and store the resulting bytes +in the array whose first element is pointed to by \fIs\fP. At most +{MB_CUR_MAX} bytes are stored. If \fIwc\fP is a null wide +character, a null byte shall be stored, preceded by any shift sequence +needed to restore the initial shift state. The resulting +state described shall be the initial conversion state. +.LP +If \fIps\fP is a null pointer, the \fIwcrtomb\fP() function shall +use its own internal \fBmbstate_t\fP object, which is +initialized at program start-up to the initial conversion state. Otherwise, +the \fBmbstate_t\fP object pointed to by \fIps\fP +shall be used to completely describe the current conversion state +of the associated character sequence. The implementation shall +behave as if no function defined in this volume of IEEE\ Std\ 1003.1-2001 +calls \fIwcrtomb\fP(). +.LP +If +the application uses any of the _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS +functions, the application shall ensure that the +\fIwcrtomb\fP() function is called with a non-NULL \fIps\fP argument. +.LP +The behavior of this function shall be affected by the \fILC_CTYPE\fP +category of the current locale. +.SH RETURN VALUE +.LP +The \fIwcrtomb\fP() function shall return the number of bytes stored +in the array object (including any shift sequences). When +\fIwc\fP is not a valid wide character, an encoding error shall occur. +In this case, the function shall store the value of the +macro [EILSEQ] in \fIerrno\fP and shall return (\fBsize_t\fP)-1; the +conversion state shall be undefined. +.SH ERRORS +.LP +The \fIwcrtomb\fP() function may fail if: +.TP 7 +.B EINVAL +\fIps\fP points to an object that contains an invalid conversion state. +.TP 7 +.B EILSEQ +Invalid wide-character code is detected. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImbsinit\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcscat.3p b/man3p/wcscat.3p new file mode 100644 index 000000000..3485e7c19 --- /dev/null +++ b/man3p/wcscat.3p @@ -0,0 +1,58 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSCAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcscat +.SH NAME +wcscat \- concatenate two wide-character strings +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wchar_t *wcscat(wchar_t *restrict\fP \fIws1\fP\fB, const wchar_t *restrict\fP +\fIws2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcscat\fP() function shall append a copy of the wide-character +string pointed to by \fIws2\fP (including the +terminating null wide-character code) to the end of the wide-character +string pointed to by \fIws1\fP. The initial wide-character +code of \fIws2\fP shall overwrite the null wide-character code at +the end of \fIws1\fP. If copying takes place between objects +that overlap, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIwcscat\fP() function shall return \fIws1\fP; no return value +is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcsncat\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcschr.3p b/man3p/wcschr.3p new file mode 100644 index 000000000..99d867d1c --- /dev/null +++ b/man3p/wcschr.3p @@ -0,0 +1,58 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSCHR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcschr +.SH NAME +wcschr \- wide-character string scanning operation +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wchar_t *wcschr(const wchar_t *\fP\fIws\fP\fB, wchar_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcschr\fP() function shall locate the first occurrence of \fIwc\fP +in the wide-character string pointed to by +\fIws\fP. The application shall ensure that the value of \fIwc\fP +is a character representable as a type \fBwchar_t\fP and a +wide-character code corresponding to a valid character in the current +locale. The terminating null wide-character code is +considered to be part of the wide-character string. +.SH RETURN VALUE +.LP +Upon completion, \fIwcschr\fP() shall return a pointer to the wide-character +code, or a null pointer if the wide-character code +is not found. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcsrchr\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcscmp.3p b/man3p/wcscmp.3p new file mode 100644 index 000000000..2ec2f9bec --- /dev/null +++ b/man3p/wcscmp.3p @@ -0,0 +1,60 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSCMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcscmp +.SH NAME +wcscmp \- compare two wide-character strings +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int wcscmp(const wchar_t *\fP\fIws1\fP\fB, const wchar_t *\fP\fIws2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcscmp\fP() function shall compare the wide-character string +pointed to by \fIws1\fP to the wide-character string +pointed to by \fIws2\fP. +.LP +The sign of a non-zero return value shall be determined by the sign +of the difference between the values of the first pair of +wide-character codes that differ in the objects being compared. +.SH RETURN VALUE +.LP +Upon completion, \fIwcscmp\fP() shall return an integer greater than, +equal to, or less than 0, if the wide-character string +pointed to by \fIws1\fP is greater than, equal to, or less than the +wide-character string pointed to by \fIws2\fP, +respectively. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcsncmp\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcscoll.3p b/man3p/wcscoll.3p new file mode 100644 index 000000000..8ad195328 --- /dev/null +++ b/man3p/wcscoll.3p @@ -0,0 +1,74 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSCOLL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcscoll +.SH NAME +wcscoll \- wide-character string comparison using collating information +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int wcscoll(const wchar_t *\fP\fIws1\fP\fB, const wchar_t *\fP\fIws2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcscoll\fP() function shall compare the wide-character string +pointed to by \fIws1\fP to the wide-character string +pointed to by \fIws2\fP, both interpreted as appropriate to the \fILC_COLLATE\fP +category of the current locale. +.LP +The +\fIwcscoll\fP() function shall not change the setting of \fIerrno\fP +if successful. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to 0 before calling \fIwcscoll\fP(). If +\fIerrno\fP is non-zero on return, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, \fIwcscoll\fP() shall return an integer +greater than, equal to, or less than 0, according to +whether the wide-character string pointed to by \fIws1\fP is greater +than, equal to, or less than the wide-character string +pointed to by \fIws2\fP, when both are interpreted as appropriate +to the current locale. \ On error, +\fIwcscoll\fP() shall set \fIerrno\fP, but no return value is reserved +to indicate an error. +.SH ERRORS +.LP +The \fIwcscoll\fP() function may fail if: +.TP 7 +.B EINVAL +The \fIws1\fP or \fIws2\fP arguments contain wide-character codes +outside the domain of the collating sequence. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIwcsxfrm\fP() and \fIwcscmp\fP() +functions should be used for sorting large lists. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcscmp\fP() , \fIwcsxfrm\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcscpy.3p b/man3p/wcscpy.3p new file mode 100644 index 000000000..a384860fb --- /dev/null +++ b/man3p/wcscpy.3p @@ -0,0 +1,56 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSCPY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcscpy +.SH NAME +wcscpy \- copy a wide-character string +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wchar_t *wcscpy(wchar_t *restrict\fP \fIws1\fP\fB, const wchar_t *restrict\fP +\fIws2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcscpy\fP() function shall copy the wide-character string pointed +to by \fIws2\fP (including the terminating null +wide-character code) into the array pointed to by \fIws1\fP. If copying +takes place between objects that overlap, the behavior is +undefined. +.SH RETURN VALUE +.LP +The \fIwcscpy\fP() function shall return \fIws1\fP; no return value +is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcsncpy\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcscspn.3p b/man3p/wcscspn.3p new file mode 100644 index 000000000..6b469a57b --- /dev/null +++ b/man3p/wcscspn.3p @@ -0,0 +1,56 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSCSPN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcscspn +.SH NAME +wcscspn \- get the length of a complementary wide substring +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t wcscspn(const wchar_t *\fP\fIws1\fP\fB, const wchar_t *\fP\fIws2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcscspn\fP() function shall compute the length (in wide characters) +of the maximum initial segment of the wide-character +string pointed to by \fIws1\fP which consists entirely of wide-character +codes \fInot\fP from the wide-character string pointed +to by \fIws2\fP. +.SH RETURN VALUE +.LP +The \fIwcscspn\fP() function shall return the length of the initial +substring of \fIws1\fP; no return value is reserved to +indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcsspn\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcsftime.3p b/man3p/wcsftime.3p new file mode 100644 index 000000000..1e449dc5b --- /dev/null +++ b/man3p/wcsftime.3p @@ -0,0 +1,83 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSFTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcsftime +.SH NAME +wcsftime \- convert date and time to a wide-character string +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t wcsftime(wchar_t *restrict\fP \fIwcs\fP\fB, size_t\fP \fImaxsize\fP\fB, +.br +\ \ \ \ \ \ const wchar_t *restrict\fP \fIformat\fP\fB, const struct +tm *restrict\fP +\fItimeptr\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcsftime\fP() function shall be equivalent to the \fIstrftime\fP() +function, +except that: +.IP " *" 3 +The argument \fIwcs\fP points to the initial element of an array of +wide characters into which the generated output is to be +placed. +.LP +.IP " *" 3 +The argument \fImaxsize\fP indicates the maximum number of wide characters +to be placed in the output array. +.LP +.IP " *" 3 +The argument \fIformat\fP is a wide-character string and the conversion +specifications are replaced by corresponding sequences +of wide characters. +.LP +.IP " *" 3 +The return value indicates the number of wide characters placed in +the output array. +.LP +.LP +If copying takes place between objects that overlap, the behavior +is undefined. +.SH RETURN VALUE +.LP +If the total number of resulting wide-character codes including the +terminating null wide-character code is no more than +\fImaxsize\fP, \fIwcsftime\fP() shall return the number of wide-character +codes placed into the array pointed to by \fIwcs\fP, +not including the terminating null wide-character code. Otherwise, +zero is returned and the contents of the array are +unspecified. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIstrftime\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcslen.3p b/man3p/wcslen.3p new file mode 100644 index 000000000..0572c9096 --- /dev/null +++ b/man3p/wcslen.3p @@ -0,0 +1,52 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSLEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcslen +.SH NAME +wcslen \- get wide-character string length +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t wcslen(const wchar_t *\fP\fIws\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcslen\fP() function shall compute the number of wide-character +codes in the wide-character string to which \fIws\fP +points, not including the terminating null wide-character code. +.SH RETURN VALUE +.LP +The \fIwcslen\fP() function shall return the length of \fIws\fP; no +return value is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcsncat.3p b/man3p/wcsncat.3p new file mode 100644 index 000000000..ee05c3c75 --- /dev/null +++ b/man3p/wcsncat.3p @@ -0,0 +1,62 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSNCAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcsncat +.SH NAME +wcsncat \- concatenate a wide-character string with part of another +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wchar_t *wcsncat(wchar_t *restrict\fP \fIws1\fP\fB, const wchar_t +*restrict\fP \fIws2\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcsncat\fP() function shall append not more than \fIn\fP wide-character +codes (a null wide-character code and +wide-character codes that follow it are not appended) from the array +pointed to by \fIws2\fP to the end of the wide-character +string pointed to by \fIws1\fP. The initial wide-character code of +\fIws2\fP shall overwrite the null wide-character code at the +end of \fIws1\fP. A terminating null wide-character code shall always +be appended to the result. If copying takes place between +objects that overlap, the behavior is undefined. +.SH RETURN VALUE +.LP +The \fIwcsncat\fP() function shall return \fIws1\fP; no return value +is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcscat\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcsncmp.3p b/man3p/wcsncmp.3p new file mode 100644 index 000000000..2710e3da0 --- /dev/null +++ b/man3p/wcsncmp.3p @@ -0,0 +1,62 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSNCMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcsncmp +.SH NAME +wcsncmp \- compare part of two wide-character strings +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int wcsncmp(const wchar_t *\fP\fIws1\fP\fB, const wchar_t *\fP\fIws2\fP\fB, +size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcsncmp\fP() function shall compare not more than \fIn\fP wide-character +codes (wide-character codes that follow a null +wide-character code are not compared) from the array pointed to by +\fIws1\fP to the array pointed to by \fIws2\fP. +.LP +The sign of a non-zero return value shall be determined by the sign +of the difference between the values of the first pair of +wide-character codes that differ in the objects being compared. +.SH RETURN VALUE +.LP +Upon successful completion, \fIwcsncmp\fP() shall return an integer +greater than, equal to, or less than 0, if the possibly +null-terminated array pointed to by \fIws1\fP is greater than, equal +to, or less than the possibly null-terminated array pointed +to by \fIws2\fP, respectively. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcscmp\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcsncpy.3p b/man3p/wcsncpy.3p new file mode 100644 index 000000000..832129d2e --- /dev/null +++ b/man3p/wcsncpy.3p @@ -0,0 +1,66 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSNCPY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcsncpy +.SH NAME +wcsncpy \- copy part of a wide-character string +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wchar_t *wcsncpy(wchar_t *restrict\fP \fIws1\fP\fB, const wchar_t +*restrict\fP \fIws2\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcsncpy\fP() function shall copy not more than \fIn\fP wide-character +codes (wide-character codes that follow a null +wide-character code are not copied) from the array pointed to by \fIws2\fP +to the array pointed to by \fIws1\fP. If copying takes +place between objects that overlap, the behavior is undefined. +.LP +If the array pointed to by \fIws2\fP is a wide-character string that +is shorter than \fIn\fP wide-character codes, null +wide-character codes shall be appended to the copy in the array pointed +to by \fIws1\fP, until \fIn\fP wide-character codes in +all are written. +.SH RETURN VALUE +.LP +The \fIwcsncpy\fP() function shall return \fIws1\fP; no return value +is reserved to indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +If there is no null wide-character code in the first \fIn\fP wide-character +codes of the array pointed to by \fIws2\fP, the +result is not null-terminated. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcscpy\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcspbrk.3p b/man3p/wcspbrk.3p new file mode 100644 index 000000000..4ca9544bf --- /dev/null +++ b/man3p/wcspbrk.3p @@ -0,0 +1,54 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSPBRK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcspbrk +.SH NAME +wcspbrk \- scan a wide-character string for a wide-character code +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wchar_t *wcspbrk(const wchar_t *\fP\fIws1\fP\fB, const wchar_t *\fP\fIws2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcspbrk\fP() function shall locate the first occurrence in +the wide-character string pointed to by \fIws1\fP of any +wide-character code from the wide-character string pointed to by \fIws2\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIwcspbrk\fP() shall return a pointer +to the wide-character code or a null pointer if no +wide-character code from \fIws2\fP occurs in \fIws1\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcschr\fP() , \fIwcsrchr\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcsrchr.3p b/man3p/wcsrchr.3p new file mode 100644 index 000000000..4402d0f09 --- /dev/null +++ b/man3p/wcsrchr.3p @@ -0,0 +1,58 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSRCHR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcsrchr +.SH NAME +wcsrchr \- wide-character string scanning operation +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wchar_t *wcsrchr(const wchar_t *\fP\fIws\fP\fB, wchar_t\fP \fIwc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcsrchr\fP() function shall locate the last occurrence of \fIwc\fP +in the wide-character string pointed to by +\fIws\fP. The application shall ensure that the value of \fIwc\fP +is a character representable as a type \fBwchar_t\fP and a +wide-character code corresponding to a valid character in the current +locale. The terminating null wide-character code shall be +considered to be part of the wide-character string. +.SH RETURN VALUE +.LP +Upon successful completion, \fIwcsrchr\fP() shall return a pointer +to the wide-character code or a null pointer if \fIwc\fP +does not occur in the wide-character string. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcschr\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcsrtombs.3p b/man3p/wcsrtombs.3p new file mode 100644 index 000000000..f8ea7db0d --- /dev/null +++ b/man3p/wcsrtombs.3p @@ -0,0 +1,111 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSRTOMBS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcsrtombs +.SH NAME +wcsrtombs \- convert a wide-character string to a character string +(restartable) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t wcsrtombs(char *restrict\fP \fIdst\fP\fB, const wchar_t **restrict\fP +\fIsrc\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIlen\fP\fB, mbstate_t *restrict\fP \fIps\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcsrtombs\fP() function shall convert a sequence of wide characters +from the array indirectly pointed to by \fIsrc\fP +into a sequence of corresponding characters, beginning in the conversion +state described by the object pointed to by \fIps\fP. If +\fIdst\fP is not a null pointer, the converted characters shall then +be stored into the array pointed to by \fIdst\fP. Conversion +continues up to and including a terminating null wide character, which +shall also be stored. Conversion shall stop earlier in the +following cases: +.IP " *" 3 +When a code is reached that does not correspond to a valid character +.LP +.IP " *" 3 +When the next character would exceed the limit of \fIlen\fP total +bytes to be stored in the array pointed to by \fIdst\fP (and +\fIdst\fP is not a null pointer) +.LP +.LP +Each conversion shall take place as if by a call to the \fIwcrtomb\fP() +function. +.LP +If \fIdst\fP is not a null pointer, the pointer object pointed to +by \fIsrc\fP shall be assigned either a null pointer (if +conversion stopped due to reaching a terminating null wide character) +or the address just past the last wide character converted +(if any). If conversion stopped due to reaching a terminating null +wide character, the resulting state described shall be the +initial conversion state. +.LP +If \fIps\fP is a null pointer, the \fIwcsrtombs\fP() function shall +use its own internal \fBmbstate_t\fP object, which is +initialized at program start-up to the initial conversion state. Otherwise, +the \fBmbstate_t\fP object pointed to by \fIps\fP +shall be used to completely describe the current conversion state +of the associated character sequence. The implementation shall +behave as if no function defined in this volume of IEEE\ Std\ 1003.1-2001 +calls \fIwcsrtombs\fP(). +.LP +If +the application uses any of the _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS +functions, the application shall ensure that the +\fIwcsrtombs\fP() function is called with a non-NULL \fIps\fP argument. +.LP +The behavior of this function shall be affected by the \fILC_CTYPE\fP +category of the current locale. +.SH RETURN VALUE +.LP +If conversion stops because a code is reached that does not correspond +to a valid character, an encoding error occurs. In this +case, the \fIwcsrtombs\fP() function shall store the value of the +macro [EILSEQ] in \fIerrno\fP and return (\fBsize_t\fP)-1; the +conversion state is undefined. Otherwise, it shall return the number +of bytes in the resulting character sequence, not including +the terminating null (if any). +.SH ERRORS +.LP +The \fIwcsrtombs\fP() function may fail if: +.TP 7 +.B EINVAL +\fIps\fP points to an object that contains an invalid conversion state. +.TP 7 +.B EILSEQ +A wide-character code does not correspond to a valid character. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImbsinit\fP() , \fIwcrtomb\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcsspn.3p b/man3p/wcsspn.3p new file mode 100644 index 000000000..a6b6f23f3 --- /dev/null +++ b/man3p/wcsspn.3p @@ -0,0 +1,56 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSSPN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcsspn +.SH NAME +wcsspn \- get the length of a wide substring +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t wcsspn(const wchar_t *\fP\fIws1\fP\fB, const wchar_t *\fP\fIws2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcsspn\fP() function shall compute the length (in wide characters) +of the maximum initial segment of the wide-character +string pointed to by \fIws1\fP which consists entirely of wide-character +codes from the wide-character string pointed to by +\fIws2\fP. +.SH RETURN VALUE +.LP +The \fIwcsspn\fP() function shall return the length of the initial +substring of \fIws1\fP; no return value is reserved to +indicate an error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcscspn\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcsstr.3p b/man3p/wcsstr.3p new file mode 100644 index 000000000..efa6a1d98 --- /dev/null +++ b/man3p/wcsstr.3p @@ -0,0 +1,61 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSSTR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcsstr +.SH NAME +wcsstr \- find a wide-character substring +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wchar_t *wcsstr(const wchar_t *restrict\fP \fIws1\fP\fB, +.br +\ \ \ \ \ \ const wchar_t *restrict\fP \fIws2\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcsstr\fP() function shall locate the first occurrence in the +wide-character string pointed to by \fIws1\fP of the +sequence of wide characters (excluding the terminating null wide character) +in the wide-character string pointed to by +\fIws2\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIwcsstr\fP() shall return a pointer +to the located wide-character string, or a null pointer if +the wide-character string is not found. +.LP +If \fIws2\fP points to a wide-character string with zero length, the +function shall return \fIws1\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcschr\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcstod.3p b/man3p/wcstod.3p new file mode 100644 index 000000000..eeaf50269 --- /dev/null +++ b/man3p/wcstod.3p @@ -0,0 +1,212 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSTOD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcstod +.SH NAME +wcstod, wcstof, wcstold \- convert a wide-character string to a double-precision +number +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double wcstod(const wchar_t *restrict\fP \fInptr\fP\fB, wchar_t **restrict\fP +\fIendptr\fP\fB); +.br +float wcstof(const wchar_t *restrict\fP \fInptr\fP\fB, wchar_t **restrict\fP +\fIendptr\fP\fB); +.br +long double wcstold(const wchar_t *restrict\fP \fInptr\fP\fB, +.br +\ \ \ \ \ \ wchar_t **restrict\fP \fIendptr\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall convert the initial portion of the wide-character +string pointed to by \fInptr\fP to \fBdouble\fP, +\fBfloat\fP, and \fBlong double\fP representation, respectively. First, +they shall decompose the input wide-character string into +three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space wide-character +codes (as specified by \fIiswspace\fP()) +.LP +.IP " 2." 4 +A subject sequence interpreted as a floating-point constant or representing +infinity or NaN +.LP +.IP " 3." 4 +A final wide-character string of one or more unrecognized wide-character +codes, including the terminating null wide-character +code of the input wide-character string +.LP +.LP +Then they shall attempt to convert the subject sequence to a floating-point +number, and return the result. +.LP +The expected form of the subject sequence is an optional plus or minus +sign, then one of the following: +.IP " *" 3 +A non-empty sequence of decimal digits optionally containing a radix +character, then an optional exponent part +.LP +.IP " *" 3 +A 0x or 0X, then a non-empty sequence of hexadecimal digits optionally +containing a radix character, then an optional binary +exponent part +.LP +.IP " *" 3 +One of INF or INFINITY, or any other wide string equivalent except +for case +.LP +.IP " *" 3 +One of NAN or NAN(\fIn-wchar-sequence_opt\fP), or any other wide string +ignoring case in the NAN part, +where: +.sp +.RS +.nf + +\fBn-wchar-sequence: + digit + nondigit + n-wchar-sequence digit + n-wchar-sequence nondigit +\fP +.fi +.RE +.LP +.LP +The subject sequence is defined as the longest initial subsequence +of the input wide string, starting with the first +non-white-space wide character, that is of the expected form. The +subject sequence contains no wide characters if the input wide +string is not of the expected form. +.LP +If the subject sequence has the expected form for a floating-point +number, the sequence of wide characters starting with the +first digit or the radix character (whichever occurs first) shall +be interpreted as a floating constant according to the rules of +the C language, except that the radix character shall be used in place +of a period, and that if neither an exponent part nor a +radix character appears in a decimal floating-point number, or if +a binary exponent part does not appear in a hexadecimal +floating-point number, an exponent part of the appropriate type with +value zero shall be assumed to follow the last digit in the +string. If the subject sequence begins with a minus sign, the sequence +shall be interpreted as negated. A wide-character sequence +INF or INFINITY shall be interpreted as an infinity, if representable +in the return type, else as if it were a floating constant +that is too large for the range of the return type. A wide-character +sequence NAN or +NAN(\fIn-wchar-sequence_opt\fP) shall be interpreted as a quiet NaN, +if supported in the return type, +else as if it were a subject sequence part that does not have the +expected form; the meaning of the \fIn\fP-wchar sequences is +implementation-defined. A pointer to the final wide string shall be +stored in the object pointed to by \fIendptr\fP, provided that +\fIendptr\fP is not a null pointer. +.LP +If the subject sequence has the hexadecimal form and FLT_RADIX is +a power of 2, the conversion shall be rounded in an +implementation-defined manner. +.LP +The +radix character shall be as defined in the program's locale (category +\fILC_NUMERIC ).\fP In the POSIX locale, or in a locale +where the radix character is not defined, the radix character shall +default to a period ( \fB'.'\fP ). +.LP +In other than the C \ or POSIX locales, other +implementation-defined subject sequences may be accepted. +.LP +If the subject sequence is empty or does not have the expected form, +no conversion shall be performed; the value of \fInptr\fP +shall be stored in the object pointed to by \fIendptr\fP, provided +that \fIendptr\fP is not a null pointer. +.LP +The +\fIwcstod\fP() function shall not change the setting of \fIerrno\fP +if successful. +.LP +Since 0 is returned on error and is also a valid return on success, +an application wishing to check for error situations should +set \fIerrno\fP to 0, then call \fIwcstod\fP(), \fIwcstof\fP(), or +\fIwcstold\fP(), then check \fIerrno\fP. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the converted +value. If no conversion could be performed, 0 shall be +returned \ and \fIerrno\fP may be set to [EINVAL]. +.LP +If the correct value is outside the range of representable values, +\(+-HUGE_VAL, \(+-HUGE_VALF, or \(+-HUGE_VALL +shall be returned (according to the sign of the value), and \fIerrno\fP +shall be set to [ERANGE]. +.LP +If the correct value would cause underflow, a value whose magnitude +is no greater than the smallest normalized positive number +in the return type shall be returned and \fIerrno\fP set to [ERANGE]. +.SH ERRORS +.LP +The \fIwcstod\fP() function shall fail if: +.TP 7 +.B ERANGE +The value to be returned would cause overflow or underflow. +.sp +.LP +The \fIwcstod\fP() function may fail if: +.TP 7 +.B EINVAL +No +conversion could be performed. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +If the subject sequence has the hexadecimal form and FLT_RADIX is +not a power of 2, and the result is not exactly representable, +the result should be one of the two numbers in the appropriate internal +format that are adjacent to the hexadecimal floating source +value, with the extra stipulation that the error should have a correct +sign for the current rounding direction. +.LP +If the subject sequence has the decimal form and at most DECIMAL_DIG +(defined in \fI\fP) significant digits, the result should +be correctly rounded. If the subject +sequence \fID\fP has the decimal form and more than DECIMAL_DIG significant +digits, consider the two bounding, adjacent decimal +strings \fIL\fP and \fIU\fP, both having DECIMAL_DIG significant digits, +such that the values of \fIL\fP, \fID\fP, and \fIU\fP +satisfy \fB"L <= D <= U"\fP . The result should be one of the (equal +or adjacent) values that would be obtained by +correctly rounding \fIL\fP and \fIU\fP according to the current rounding +direction, with the extra stipulation that the error +with respect to \fID\fP should have a correct sign for the current +rounding direction. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswspace\fP() , \fIlocaleconv\fP() , \fIscanf\fP() , \fIsetlocale\fP() +, \fIwcstol\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, +\fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcstof.3p b/man3p/wcstof.3p new file mode 100644 index 000000000..d7b324726 --- /dev/null +++ b/man3p/wcstof.3p @@ -0,0 +1 @@ +.so man3p/wcstod.3p diff --git a/man3p/wcstoimax.3p b/man3p/wcstoimax.3p new file mode 100644 index 000000000..0e69db2c2 --- /dev/null +++ b/man3p/wcstoimax.3p @@ -0,0 +1,82 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSTOIMAX" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcstoimax +.SH NAME +wcstoimax, wcstoumax \- convert a wide-character string to an integer +type +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +intmax_t wcstoimax(const wchar_t *restrict\fP \fInptr\fP\fB, +.br +\ \ \ \ \ \ wchar_t **restrict\fP \fIendptr\fP\fB, int\fP \fIbase\fP\fB); +.br +uintmax_t wcstoumax(const wchar_t *restrict\fP \fInptr\fP\fB, +.br +\ \ \ \ \ \ wchar_t **restrict\fP \fIendptr\fP\fB, int\fP \fIbase\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall be equivalent to the \fIwcstol\fP(), \fIwcstoll\fP(), +\fIwcstoul\fP(), and \fIwcstoull\fP() functions, respectively, except +that the initial portion of the wide string +shall be converted to \fBintmax_t\fP and \fBuintmax_t\fP representation, +respectively. +.SH RETURN VALUE +.LP +These functions shall return the converted value, if any. +.LP +If no conversion could be performed, zero shall be returned. If the +correct value is outside the range of representable values, +{INTMAX_MAX}, {INTMAX_MIN}, or {UINTMAX_MAX} shall be returned (according +to the return type and sign of the value, if any), and +\fIerrno\fP shall be set to [ERANGE]. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +.B EINVAL +The value of \fIbase\fP is not supported. +.TP 7 +.B ERANGE +The value to be returned is not representable. +.sp +.LP +These functions may fail if: +.TP 7 +.B EINVAL +No conversion could be performed. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcstol\fP() , \fIwcstoul\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcstok.3p b/man3p/wcstok.3p new file mode 100644 index 000000000..259603a7a --- /dev/null +++ b/man3p/wcstok.3p @@ -0,0 +1,92 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSTOK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcstok +.SH NAME +wcstok \- split a wide-character string into tokens +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wchar_t *wcstok(wchar_t *restrict\fP \fIws1\fP\fB, const wchar_t *restrict\fP +\fIws2\fP\fB, +.br +\ \ \ \ \ \ wchar_t **restrict\fP \fIptr\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +A sequence of calls to \fIwcstok\fP() shall break the wide-character +string pointed to by \fIws1\fP into a sequence of tokens, +each of which shall be delimited by a wide-character code from the +wide-character string pointed to by \fIws2\fP. The \fIptr\fP +argument points to a caller-provided \fBwchar_t\fP pointer into which +the \fIwcstok\fP() function shall store information +necessary for it to continue scanning the same wide-character string. +.LP +The first call in the sequence has \fIws1\fP as its first argument, +and is followed by calls with a null pointer as their first +argument. The separator string pointed to by \fIws2\fP may be different +from call to call. +.LP +The first call in the sequence shall search the wide-character string +pointed to by \fIws1\fP for the first wide-character code +that is \fInot\fP contained in the current separator string pointed +to by \fIws2\fP. If no such wide-character code is found, +then there are no tokens in the wide-character string pointed to by +\fIws1\fP and \fIwcstok\fP() shall return a null pointer. If +such a wide-character code is found, it shall be the start of the +first token. +.LP +The \fIwcstok\fP() function shall then search from there for a wide-character +code that \fIis\fP contained in the current +separator string. If no such wide-character code is found, the current +token extends to the end of the wide-character string +pointed to by \fIws1\fP, and subsequent searches for a token shall +return a null pointer. If such a wide-character code is found, +it shall be overwritten by a null wide character, which terminates +the current token. The \fIwcstok\fP() function shall save a +pointer to the following wide-character code, from which the next +search for a token shall start. +.LP +Each subsequent call, with a null pointer as the value of the first +argument, shall start searching from the saved pointer and +behave as described above. +.LP +The implementation shall behave as if no function calls \fIwcstok\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, the \fIwcstok\fP() function shall return +a pointer to the first wide-character code of a token. +Otherwise, if there is no token, \fIwcstok\fP() shall return a null +pointer. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcstol.3p b/man3p/wcstol.3p new file mode 100644 index 000000000..aaed2586e --- /dev/null +++ b/man3p/wcstol.3p @@ -0,0 +1,157 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSTOL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcstol +.SH NAME +wcstol, wcstoll \- convert a wide-character string to a long integer +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +long wcstol(const wchar_t *restrict\fP \fInptr\fP\fB, wchar_t **restrict\fP +\fIendptr\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIbase\fP\fB); +.br +long long wcstoll(const wchar_t *restrict\fP \fInptr\fP\fB, +.br +\ \ \ \ \ \ wchar_t **restrict\fP \fIendptr\fP\fB, int\fP \fIbase\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +These functions shall convert the initial portion of the wide-character +string pointed to by \fInptr\fP to \fBlong\fP, \fBlong +long\fP, \fBunsigned long\fP, and \fBunsigned long long\fP representation, +respectively. First, they shall decompose the input +string into three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space wide-character +codes (as specified by \fIiswspace\fP()) +.LP +.IP " 2." 4 +A subject sequence interpreted as an integer represented in some radix +determined by the value of \fIbase\fP +.LP +.IP " 3." 4 +A final wide-character string of one or more unrecognized wide-character +codes, including the terminating null wide-character +code of the input wide-character string +.LP +.LP +Then they shall attempt to convert the subject sequence to an integer, +and return the result. +.LP +If \fIbase\fP is 0, the expected form of the subject sequence is that +of a decimal constant, octal constant, or hexadecimal +constant, any of which may be preceded by a \fB'+'\fP or \fB'-'\fP +sign. A decimal constant begins with a non-zero digit, and +consists of a sequence of decimal digits. An octal constant consists +of the prefix \fB'0'\fP optionally followed by a sequence +of the digits \fB'0'\fP to \fB'7'\fP only. A hexadecimal constant +consists of the prefix 0x or 0X followed by a sequence of +the decimal digits and letters \fB'a'\fP (or \fB'A'\fP ) to \fB'f'\fP +(or \fB'F'\fP ) with values 10 to 15 +respectively. +.LP +If the value of \fIbase\fP is between 2 and 36, the expected form +of the subject sequence is a sequence of letters and digits +representing an integer with the radix specified by \fIbase\fP, optionally +preceded by a \fB'+'\fP or \fB'-'\fP sign, but +not including an integer suffix. The letters from \fB'a'\fP (or \fB'A'\fP +) to \fB'z'\fP (or \fB'Z'\fP ) inclusive are +ascribed the values 10 to 35; only letters whose ascribed values are +less than that of \fIbase\fP shall be permitted. If the value +of \fIbase\fP is 16, the wide-character code representations of 0x +or 0X may optionally precede the sequence of letters and +digits, following the sign if present. +.LP +The subject sequence is defined as the longest initial subsequence +of the input wide-character string, starting with the first +non-white-space wide-character code that is of the expected form. +The subject sequence contains no wide-character codes if the +input wide-character string is empty or consists entirely of white-space +wide-character code, or if the first non-white-space +wide-character code is other than a sign or a permissible letter or +digit. +.LP +If the subject sequence has the expected form and \fIbase\fP is 0, +the sequence of wide-character codes starting with the first +digit shall be interpreted as an integer constant. If the subject +sequence has the expected form and the value of \fIbase\fP is +between 2 and 36, it shall be used as the base for conversion, ascribing +to each letter its value as given above. If the subject +sequence begins with a minus sign, the value resulting from the conversion +shall be negated. A pointer to the final wide-character +string shall be stored in the object pointed to by \fIendptr\fP, provided +that \fIendptr\fP is not a null pointer. +.LP +In other than the C \ or POSIX locales, other +implementation-defined subject sequences may be accepted. +.LP +If the subject sequence is empty or does not have the expected form, +no conversion shall be performed; the value of \fInptr\fP +shall be stored in the object pointed to by \fIendptr\fP, provided +that \fIendptr\fP is not a null pointer. +.LP +These functions shall not change the setting of \fIerrno\fP if successful. +.LP +Since 0, {LONG_MIN} or {LLONG_MIN} and {LONG_MAX} or {LLONG_MAX} are +returned on error and are also valid returns on success, an +application wishing to check for error situations should set \fIerrno\fP +to 0, then call \fIwcstol\fP() or \fIwcstoll\fP(), then +check \fIerrno\fP. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the converted +value, if any. If no conversion could be performed, 0 +shall be returned \ and \fIerrno\fP may be set to indicate the error. +If the correct value is outside the range of representable values, +{LONG_MIN}, {LONG_MAX}, {LLONG_MIN}, or {LLONG_MAX} shall +be returned (according to the sign of the value), and \fIerrno\fP +set to [ERANGE]. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +.B EINVAL +The value of \fIbase\fP is not supported. +.TP 7 +.B ERANGE +The value to be returned is not representable. +.sp +.LP +These functions may fail if: +.TP 7 +.B EINVAL +No +conversion could be performed. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswalpha\fP() , \fIscanf\fP() , \fIwcstod\fP() , the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcstold.3p b/man3p/wcstold.3p new file mode 100644 index 000000000..d7b324726 --- /dev/null +++ b/man3p/wcstold.3p @@ -0,0 +1 @@ +.so man3p/wcstod.3p diff --git a/man3p/wcstoll.3p b/man3p/wcstoll.3p new file mode 100644 index 000000000..2a8f17ad8 --- /dev/null +++ b/man3p/wcstoll.3p @@ -0,0 +1 @@ +.so man3p/wcstol.3p diff --git a/man3p/wcstombs.3p b/man3p/wcstombs.3p new file mode 100644 index 000000000..9c44eb628 --- /dev/null +++ b/man3p/wcstombs.3p @@ -0,0 +1,87 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSTOMBS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcstombs +.SH NAME +wcstombs \- convert a wide-character string to a character string +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t wcstombs(char *restrict\fP \fIs\fP\fB, const wchar_t *restrict\fP +\fIpwcs\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcstombs\fP() function shall convert the sequence of wide-character +codes that are in the array pointed to by +\fIpwcs\fP into a sequence of characters that begins in the initial +shift state and store these characters into the array pointed +to by \fIs\fP, stopping if a character would exceed the limit of \fIn\fP +total bytes or if a null byte is stored. Each +wide-character code shall be converted as if by a call to \fIwctomb\fP(), +except that the +shift state of \fIwctomb\fP() shall not be affected. +.LP +The behavior of this function shall be affected by the \fILC_CTYPE\fP +category of the current locale. +.LP +No more than \fIn\fP bytes shall be modified in the array pointed +to by \fIs\fP. If copying takes place between objects that +overlap, the behavior is undefined. \ If \fIs\fP is a null pointer, +\fIwcstombs\fP() shall return the length required to convert +the entire array regardless of the value of \fIn\fP, but no values +are stored. +.LP +The \fIwcstombs\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +If a wide-character code is encountered that does not correspond to +a valid character (of one or more bytes each), +\fIwcstombs\fP() shall return (\fBsize_t\fP)-1. Otherwise, \fIwcstombs\fP() +shall return the number of bytes stored in the +character array, not including any terminating null byte. The array +shall not be null-terminated if the value returned is +\fIn\fP. +.SH ERRORS +.LP +The \fIwcstombs\fP() function may fail if: +.TP 7 +.B EILSEQ +A +wide-character code does not correspond to a valid character. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImblen\fP() , \fImbtowc\fP() , \fImbstowcs\fP() , \fIwctomb\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcstoul.3p b/man3p/wcstoul.3p new file mode 100644 index 000000000..0164b5242 --- /dev/null +++ b/man3p/wcstoul.3p @@ -0,0 +1,159 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSTOUL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcstoul +.SH NAME +wcstoul, wcstoull \- convert a wide-character string to an unsigned +long +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +unsigned long wcstoul(const wchar_t *restrict\fP \fInptr\fP\fB, +.br +\ \ \ \ \ \ wchar_t **restrict\fP \fIendptr\fP\fB, int\fP \fIbase\fP\fB); +.br +unsigned long long wcstoull(const wchar_t *restrict\fP \fInptr\fP\fB, +.br +\ \ \ \ \ \ wchar_t **restrict\fP \fIendptr\fP\fB, int\fP \fIbase\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcstoul\fP() and \fIwcstoull\fP() functions shall convert the +initial portion of the wide-character string pointed to +by \fInptr\fP to \fBunsigned long\fP and \fBunsigned long long\fP +representation, respectively. First, they shall decompose the +input wide-character string into three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space wide-character +codes (as specified by \fIiswspace\fP()) +.LP +.IP " 2." 4 +A subject sequence interpreted as an integer represented in some radix +determined by the value of \fIbase\fP +.LP +.IP " 3." 4 +A final wide-character string of one or more unrecognized wide-character +codes, including the terminating null wide-character +code of the input wide-character string +.LP +.LP +Then they shall attempt to convert the subject sequence to an unsigned +integer, and return the result. +.LP +If \fIbase\fP is 0, the expected form of the subject sequence is that +of a decimal constant, octal constant, or hexadecimal +constant, any of which may be preceded by a \fB'+'\fP or \fB'-'\fP +sign. A decimal constant begins with a non-zero digit, and +consists of a sequence of decimal digits. An octal constant consists +of the prefix \fB'0'\fP optionally followed by a sequence +of the digits \fB'0'\fP to \fB'7'\fP only. A hexadecimal constant +consists of the prefix 0x or 0X followed by a sequence of +the decimal digits and letters \fB'a'\fP (or \fB'A'\fP ) to \fB'f'\fP +(or \fB'F'\fP ) with values 10 to 15 +respectively. +.LP +If the value of \fIbase\fP is between 2 and 36, the expected form +of the subject sequence is a sequence of letters and digits +representing an integer with the radix specified by \fIbase\fP, optionally +preceded by a \fB'+'\fP or \fB'-'\fP sign, but +not including an integer suffix. The letters from \fB'a'\fP (or \fB'A'\fP +) to \fB'z'\fP (or \fB'Z'\fP ) inclusive are +ascribed the values 10 to 35; only letters whose ascribed values are +less than that of \fIbase\fP shall be permitted. If the value +of \fIbase\fP is 16, the wide-character codes 0x or 0X may optionally +precede the sequence of letters and digits, following the +sign if present. +.LP +The subject sequence is defined as the longest initial subsequence +of the input wide-character string, starting with the first +wide-character code that is not white space and is of the expected +form. The subject sequence contains no wide-character codes if +the input wide-character string is empty or consists entirely of white-space +wide-character codes, or if the first wide-character +code that is not white space is other than a sign or a permissible +letter or digit. +.LP +If the subject sequence has the expected form and \fIbase\fP is 0, +the sequence of wide-character codes starting with the first +digit shall be interpreted as an integer constant. If the subject +sequence has the expected form and the value of \fIbase\fP is +between 2 and 36, it shall be used as the base for conversion, ascribing +to each letter its value as given above. If the subject +sequence begins with a minus sign, the value resulting from the conversion +shall be negated. A pointer to the final wide-character +string shall be stored in the object pointed to by \fIendptr\fP, provided +that \fIendptr\fP is not a null pointer. +.LP +In other than the C \ or POSIX locales, other +implementation-defined subject sequences may be accepted. +.LP +If the subject sequence is empty or does not have the expected form, +no conversion shall be performed; the value of \fInptr\fP +shall be stored in the object pointed to by \fIendptr\fP, provided +that \fIendptr\fP is not a null pointer. +.LP +The +\fIwcstoul\fP() function shall not change the setting of \fIerrno\fP +if successful. +.LP +Since 0, {ULONG_MAX}, and {ULLONG_MAX} are returned on error and 0 +is also a valid return on success, an application wishing to +check for error situations should set \fIerrno\fP to 0, then call +\fIwcstoul\fP() or \fIwcstoull\fP(), then check \fIerrno\fP. +.SH RETURN VALUE +.LP +Upon successful completion, the \fIwcstoul\fP() and \fIwcstoull\fP() +functions shall return the converted value, if any. If no +conversion could be performed, 0 shall be returned \ and \fIerrno\fP +may be set to indicate the error. If the correct value is outside +the range of representable values, +{ULONG_MAX} or {ULLONG_MAX} respectively shall be returned and \fIerrno\fP +set to [ERANGE]. +.SH ERRORS +.LP +These functions shall fail if: +.TP 7 +.B EINVAL +The value of \fIbase\fP is not supported. +.TP 7 +.B ERANGE +The value to be returned is not representable. +.sp +.LP +These functions may fail if: +.TP 7 +.B EINVAL +No +conversion could be performed. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswalpha\fP() , \fIscanf\fP() , \fIwcstod\fP() , \fIwcstol\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcstoull.3p b/man3p/wcstoull.3p new file mode 100644 index 000000000..3c699d093 --- /dev/null +++ b/man3p/wcstoull.3p @@ -0,0 +1 @@ +.so man3p/wcstoul.3p diff --git a/man3p/wcstoumax.3p b/man3p/wcstoumax.3p new file mode 100644 index 000000000..990ecdc58 --- /dev/null +++ b/man3p/wcstoumax.3p @@ -0,0 +1 @@ +.so man3p/wcstoimax.3p diff --git a/man3p/wcswcs.3p b/man3p/wcswcs.3p new file mode 100644 index 000000000..7bdf1602f --- /dev/null +++ b/man3p/wcswcs.3p @@ -0,0 +1,63 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSWCS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcswcs +.SH NAME +wcswcs \- find a wide substring (\fBLEGACY\fP) +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wchar_t *wcswcs(const wchar_t *\fP\fIws1\fP\fB, const wchar_t *\fP\fIws2\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcswcs\fP() function shall locate the first occurrence in the +wide-character string pointed to by \fIws1\fP of the +sequence of wide-character codes (excluding the terminating null wide-character +code) in the wide-character string pointed to by +\fIws2\fP. +.SH RETURN VALUE +.LP +Upon successful completion, \fIwcswcs\fP() shall return a pointer +to the located wide-character string or a null pointer if the +wide-character string is not found. +.LP +If \fIws2\fP points to a wide-character string with zero length, the +function shall return \fIws1\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +This function was not included in the final ISO/IEC\ 9899:1990/Amendment +1:1995 (E). Application developers are strongly +encouraged to use the \fIwcsstr\fP() function instead. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +This function may be withdrawn in a future version. +.SH SEE ALSO +.LP +\fIwcschr\fP() , \fIwcsstr\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcswidth.3p b/man3p/wcswidth.3p new file mode 100644 index 000000000..44c91073a --- /dev/null +++ b/man3p/wcswidth.3p @@ -0,0 +1,63 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSWIDTH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcswidth +.SH NAME +wcswidth \- number of column positions of a wide-character string +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int wcswidth(const wchar_t *\fP\fIpwcs\fP\fB, size_t\fP \fIn\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcswidth\fP() function shall determine the number of column +positions required for \fIn\fP wide-character codes (or +fewer than \fIn\fP wide-character codes if a null wide-character code +is encountered before \fIn\fP wide-character codes are +exhausted) in the string pointed to by \fIpwcs\fP. +.SH RETURN VALUE +.LP +The \fIwcswidth\fP() function either shall return 0 (if \fIpwcs\fP +points to a null wide-character code), or return the number +of column positions to be occupied by the wide-character string pointed +to by \fIpwcs\fP, or return -1 (if any of the first +\fIn\fP wide-character codes in the wide-character string pointed +to by \fIpwcs\fP is not a printable wide-character code). +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +This function was removed from the final ISO/IEC\ 9899:1990/Amendment +1:1995 (E), and the return value for a non-printable +wide character is not specified. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcwidth\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 3.103, Column Position, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcsxfrm.3p b/man3p/wcsxfrm.3p new file mode 100644 index 000000000..c30fbe905 --- /dev/null +++ b/man3p/wcsxfrm.3p @@ -0,0 +1,93 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCSXFRM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcsxfrm +.SH NAME +wcsxfrm \- wide-character string transformation +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +size_t wcsxfrm(wchar_t *restrict\fP \fIws1\fP\fB, const wchar_t *restrict\fP +\fIws2\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcsxfrm\fP() function shall transform the wide-character string +pointed to by \fIws2\fP and place the resulting +wide-character string into the array pointed to by \fIws1\fP. The +transformation shall be such that if \fIwcscmp\fP() is applied to +two transformed wide strings, it shall return a value greater than, +equal to, or less than 0, corresponding to the result of \fIwcscoll\fP() +applied to the +same two original wide-character strings. No more than \fIn\fP wide-character +codes shall be placed into the resulting array +pointed to by \fIws1\fP, including the terminating null wide-character +code. If \fIn\fP is 0, \fIws1\fP is permitted to be a +null pointer. If copying takes place between objects that overlap, +the behavior is undefined. +.LP +The +\fIwcsxfrm\fP() function shall not change the setting of \fIerrno\fP +if successful. +.LP +Since no return value is reserved to indicate an error, an application +wishing to check for error situations should set +\fIerrno\fP to 0, then call \fIwcsxfrm\fP(), then check \fIerrno\fP. +.SH RETURN VALUE +.LP +The \fIwcsxfrm\fP() function shall return the length of the transformed +wide-character string (not including the terminating +null wide-character code). If the value returned is \fIn\fP or more, +the contents of the array pointed to by \fIws1\fP are +unspecified. +.LP +On +error, the \fIwcsxfrm\fP() function may set \fIerrno\fP, but no return +value is reserved to indicate an error. +.SH ERRORS +.LP +The \fIwcsxfrm\fP() function may fail if: +.TP 7 +.B EINVAL +The wide-character string pointed to by \fIws2\fP contains wide-character +codes outside the domain of the collating sequence. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The transformation function is such that two transformed wide-character +strings can be ordered by \fIwcscmp\fP() as appropriate to collating +sequence information in the program's locale (category +\fILC_COLLATE ).\fP +.LP +The fact that when \fIn\fP is 0 \fIws1\fP is permitted to be a null +pointer is useful to determine the size of the \fIws1\fP +array prior to making the transformation. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcscmp\fP() , \fIwcscoll\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wctob.3p b/man3p/wctob.3p new file mode 100644 index 000000000..91e1922e7 --- /dev/null +++ b/man3p/wctob.3p @@ -0,0 +1,62 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCTOB" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wctob +.SH NAME +wctob \- wide-character to single-byte conversion +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int wctob(wint_t\fP \fIc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwctob\fP() function shall determine whether \fIc\fP corresponds +to a member of the extended character set whose +character representation is a single byte when in the initial shift +state. +.LP +The behavior of this function shall be affected by the \fILC_CTYPE\fP +category of the current locale. +.SH RETURN VALUE +.LP +The \fIwctob\fP() function shall return EOF if \fIc\fP does not correspond +to a character with length one in the initial shift +state. Otherwise, it shall return the single-byte representation of +that character as an \fBunsigned char\fP converted to +\fBint\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIbtowc\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wctomb.3p b/man3p/wctomb.3p new file mode 100644 index 000000000..34ddcbdc2 --- /dev/null +++ b/man3p/wctomb.3p @@ -0,0 +1,90 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCTOMB" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wctomb +.SH NAME +wctomb \- convert a wide-character code to a character +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int wctomb(char *\fP\fIs\fP\fB, wchar_t\fP \fIwchar\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwctomb\fP() function shall determine the number of bytes needed +to represent the character corresponding to the +wide-character code whose value is \fIwchar\fP (including any change +in the shift state). It shall store the character +representation (possibly multiple bytes and any special bytes to change +shift state) in the array object pointed to by \fIs\fP (if +\fIs\fP is not a null pointer). At most {MB_CUR_MAX} bytes shall be +stored. If \fIwchar\fP is 0, a null byte shall be stored, +preceded by any shift sequence needed to restore the initial shift +state, and \fIwctomb\fP() shall be left in the initial shift +state. +.LP +The +behavior of this function is affected by the \fILC_CTYPE\fP category +of the current locale. For a state-dependent encoding, this +function shall be placed into its initial state by a call for which +its character pointer argument, \fIs\fP, is a null pointer. +Subsequent calls with \fIs\fP as other than a null pointer shall cause +the internal state of the function to be altered as +necessary. A call with \fIs\fP as a null pointer shall cause this +function to return a non-zero value if encodings have state +dependency, and 0 otherwise. Changing the \fILC_CTYPE\fP category +causes the shift state of this function to be unspecified. +.LP +The \fIwctomb\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.LP +The implementation shall behave as if no function defined in this +volume of IEEE\ Std\ 1003.1-2001 calls +\fIwctomb\fP(). +.SH RETURN VALUE +.LP +If \fIs\fP is a null pointer, \fIwctomb\fP() shall return a non-zero +or 0 value, if character encodings, respectively, do or +do not have state-dependent encodings. If \fIs\fP is not a null pointer, +\fIwctomb\fP() shall return -1 if the value of +\fIwchar\fP does not correspond to a valid character, or return the +number of bytes that constitute the character corresponding to +the value of \fIwchar\fP. +.LP +In no case shall the value returned be greater than the value of the +{MB_CUR_MAX} macro. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImblen\fP() , \fImbtowc\fP() , \fImbstowcs\fP() , \fIwcstombs\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wctrans.3p b/man3p/wctrans.3p new file mode 100644 index 000000000..1e33995fb --- /dev/null +++ b/man3p/wctrans.3p @@ -0,0 +1,74 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCTRANS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wctrans +.SH NAME +wctrans \- define character mapping +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wctrans_t wctrans(const char *\fP\fIcharclass\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwctrans\fP() function is defined for valid character mapping +names identified in the current locale. The +\fIcharclass\fP is a string identifying a generic character mapping +name for which codeset-specific information is required. The +following character mapping names are defined in all locales: \fBtolower\fP +and \fBtoupper\fP. +.LP +The function shall return a value of type \fBwctrans_t\fP, which can +be used as the second argument to subsequent calls of \fItowctrans\fP(). +The \fIwctrans\fP() function shall determine values of \fBwctrans_t\fP +according to the rules of the coded character set defined by character +mapping information in the program's locale (category +\fILC_CTYPE ).\fP The values returned by \fIwctrans\fP() shall be +valid until a call to \fIsetlocale\fP() that modifies the category +\fILC_CTYPE .\fP +.SH RETURN VALUE +.LP +The \fIwctrans\fP() function shall return 0 \ and may set \fIerrno\fP +to indicate the error \ if the given character mapping name is not +valid for the current +locale (category \fILC_CTYPE );\fP otherwise, it shall return a non-zero +object of type \fBwctrans_t\fP that can be used in calls +to \fItowctrans\fP(). +.SH ERRORS +.LP +The \fIwctrans\fP() function may fail if: +.TP 7 +.B EINVAL +The character mapping name pointed to by \fIcharclass\fP is not valid +in the current locale. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fItowctrans\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wctype.3p b/man3p/wctype.3p new file mode 100644 index 000000000..92173be9d --- /dev/null +++ b/man3p/wctype.3p @@ -0,0 +1,109 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCTYPE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wctype +.SH NAME +wctype \- define character class +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wctype_t wctype(const char *\fP\fIproperty\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwctype\fP() function is defined for valid character class names +as defined in the current locale. The \fIproperty\fP +argument is a string identifying a generic character class for which +codeset-specific type information is required. The following +character class names shall be defined in all locales: +.TS C +center; lw(26) lw(26) lw(26). +T{ +\fB +.br +alnum +.br +alpha +.br +blank +.br +cntrl +.br +\fP +T} T{ +\fB +.br +digit +.br +graph +.br +lower +.br +print +.br +\fP +T} T{ +\fB +.br +punct +.br +space +.br +upper +.br +xdigit +.br +\fP +T} +.TE +.LP +Additional character class names defined in the locale definition +file (category \fILC_CTYPE )\fP can also be specified. +.LP +The function shall return a value of type \fBwctype_t\fP, which can +be used as the second argument to subsequent calls of \fIiswctype\fP(). +The \fIwctype\fP() function shall determine values of \fBwctype_t\fP +according to the rules of the coded character set defined by character +type information in the program's locale (category +\fILC_CTYPE ).\fP The values returned by \fIwctype\fP() shall be valid +until a call to \fIsetlocale\fP() that modifies the category \fILC_CTYPE +\&.\fP +.SH RETURN VALUE +.LP +The \fIwctype\fP() function shall return 0 if the given character +class name is not valid for the current locale (category +\fILC_CTYPE );\fP otherwise, it shall return an object of type \fBwctype_t\fP +that can be used in calls to \fIiswctype\fP(). +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIiswctype\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wcwidth.3p b/man3p/wcwidth.3p new file mode 100644 index 000000000..e9ae2152d --- /dev/null +++ b/man3p/wcwidth.3p @@ -0,0 +1,61 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WCWIDTH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wcwidth +.SH NAME +wcwidth \- number of column positions of a wide-character code +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int wcwidth(wchar_t\fP \fIwc\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIwcwidth\fP() function shall determine the number of column +positions required for the wide character \fIwc\fP. The +application shall ensure that the value of \fIwc\fP is a character +representable as a \fBwchar_t\fP, and is a wide-character code +corresponding to a valid character in the current locale. +.SH RETURN VALUE +.LP +The \fIwcwidth\fP() function shall either return 0 (if \fIwc\fP is +a null wide-character code), or return the number of column +positions to be occupied by the wide-character code \fIwc\fP, or return +-1 (if \fIwc\fP does not correspond to a printable +wide-character code). +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +This function was removed from the final ISO/IEC\ 9899:1990/Amendment +1:1995 (E), and the return value for a non-printable +wide character is not specified. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwcswidth\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wmemchr.3p b/man3p/wmemchr.3p new file mode 100644 index 000000000..e293dc620 --- /dev/null +++ b/man3p/wmemchr.3p @@ -0,0 +1,64 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WMEMCHR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wmemchr +.SH NAME +wmemchr \- find a wide character in memory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wchar_t *wmemchr(const wchar_t *\fP\fIws\fP\fB, wchar_t\fP \fIwc\fP\fB, +size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwmemchr\fP() function shall locate the first occurrence of +\fIwc\fP in the initial \fIn\fP wide characters of the +object pointed to by \fIws\fP. This function shall not be affected +by locale and all \fBwchar_t\fP values shall be treated +identically. The null wide character and \fBwchar_t\fP values not +corresponding to valid characters shall not be treated +specially. +.LP +If \fIn\fP is zero, the application shall ensure that \fIws\fP is +a valid pointer and the function behaves as if no valid +occurrence of \fIwc\fP is found. +.SH RETURN VALUE +.LP +The \fIwmemchr\fP() function shall return a pointer to the located +wide character, or a null pointer if the wide character does +not occur in the object. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwmemcmp\fP() , \fIwmemcpy\fP() , \fIwmemmove\fP() , \fIwmemset\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wmemcmp.3p b/man3p/wmemcmp.3p new file mode 100644 index 000000000..6d62b6314 --- /dev/null +++ b/man3p/wmemcmp.3p @@ -0,0 +1,65 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WMEMCMP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wmemcmp +.SH NAME +wmemcmp \- compare wide characters in memory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int wmemcmp(const wchar_t *\fP\fIws1\fP\fB, const wchar_t *\fP\fIws2\fP\fB, +size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwmemcmp\fP() function shall compare the first \fIn\fP wide +characters of the object pointed to by \fIws1\fP to the +first \fIn\fP wide characters of the object pointed to by \fIws2\fP. +This function shall not be affected by locale and all +\fBwchar_t\fP values shall be treated identically. The null wide character +and \fBwchar_t\fP values not corresponding to valid +characters shall not be treated specially. +.LP +If \fIn\fP is zero, the application shall ensure that \fIws1\fP and +\fIws2\fP are valid pointers, and the function shall +behave as if the two objects compare equal. +.SH RETURN VALUE +.LP +The \fIwmemcmp\fP() function shall return an integer greater than, +equal to, or less than zero, respectively, as the object +pointed to by \fIws1\fP is greater than, equal to, or less than the +object pointed to by \fIws2\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwmemchr\fP() , \fIwmemcpy\fP() , \fIwmemmove\fP() , \fIwmemset\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wmemcpy.3p b/man3p/wmemcpy.3p new file mode 100644 index 000000000..036c19886 --- /dev/null +++ b/man3p/wmemcpy.3p @@ -0,0 +1,63 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WMEMCPY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wmemcpy +.SH NAME +wmemcpy \- copy wide characters in memory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wchar_t *wmemcpy(wchar_t *restrict\fP \fIws1\fP\fB, const wchar_t +*restrict\fP \fIws2\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwmemcpy\fP() function shall copy \fIn\fP wide characters from +the object pointed to by \fIws2\fP to the object pointed +to by \fIws1\fP. This function shall not be affected by locale and +all \fBwchar_t\fP values shall be treated identically. The +null wide character and \fBwchar_t\fP values not corresponding to +valid characters shall not be treated specially. +.LP +If \fIn\fP is zero, the application shall ensure that \fIws1\fP and +\fIws2\fP are valid pointers, and the function shall copy +zero wide characters. +.SH RETURN VALUE +.LP +The \fIwmemcpy\fP() function shall return the value of \fIws1\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwmemchr\fP() , \fIwmemcmp\fP() , \fIwmemmove\fP() , \fIwmemset\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wmemmove.3p b/man3p/wmemmove.3p new file mode 100644 index 000000000..8cc9d9b14 --- /dev/null +++ b/man3p/wmemmove.3p @@ -0,0 +1,68 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WMEMMOVE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wmemmove +.SH NAME +wmemmove \- copy wide characters in memory with overlapping areas +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wchar_t *wmemmove(wchar_t *\fP\fIws1\fP\fB, const wchar_t *\fP\fIws2\fP\fB, +size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwmemmove\fP() function shall copy \fIn\fP wide characters from +the object pointed to by \fIws2\fP to the object +pointed to by \fIws1\fP. Copying shall take place as if the \fIn\fP +wide characters from the object pointed to by \fIws2\fP are +first copied into a temporary array of \fIn\fP wide characters that +does not overlap the objects pointed to by \fIws1\fP or +\fIws2\fP, and then the \fIn\fP wide characters from the temporary +array are copied into the object pointed to by \fIws1\fP. +.LP +This function shall not be affected by locale and all \fBwchar_t\fP +values shall be treated identically. The null wide +character and \fBwchar_t\fP values not corresponding to valid characters +shall not be treated specially. +.LP +If \fIn\fP is zero, the application shall ensure that \fIws1\fP and +\fIws2\fP are valid pointers, and the function shall copy +zero wide characters. +.SH RETURN VALUE +.LP +The \fIwmemmove\fP() function shall return the value of \fIws1\fP. +.SH ERRORS +.LP +No errors are defined +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwmemchr\fP() , \fIwmemcmp\fP() , \fIwmemcpy\fP() , \fIwmemset\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wmemset.3p b/man3p/wmemset.3p new file mode 100644 index 000000000..a202c5377 --- /dev/null +++ b/man3p/wmemset.3p @@ -0,0 +1,61 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WMEMSET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wmemset +.SH NAME +wmemset \- set wide characters in memory +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +wchar_t *wmemset(wchar_t *\fP\fIws\fP\fB, wchar_t\fP \fIwc\fP\fB, +size_t\fP \fIn\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwmemset\fP() function shall copy the value of \fIwc\fP into +each of the first \fIn\fP wide characters of the object +pointed to by \fIws\fP. This function shall not be affected by locale +and all \fBwchar_t\fP values shall be treated identically. +The null wide character and \fBwchar_t\fP values not corresponding +to valid characters shall not be treated specially. +.LP +If \fIn\fP is zero, the application shall ensure that \fIws\fP is +a valid pointer, and the function shall copy zero wide +characters. +.SH RETURN VALUE +.LP +The \fIwmemset\fP() functions shall return the value of \fIws\fP. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIwmemchr\fP() , \fIwmemcmp\fP() , \fIwmemcpy\fP() , \fIwmemmove\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wordexp.3p b/man3p/wordexp.3p new file mode 100644 index 000000000..3322245e2 --- /dev/null +++ b/man3p/wordexp.3p @@ -0,0 +1,377 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WORDEXP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" wordexp +.SH NAME +wordexp, wordfree \- perform word expansions +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +int wordexp(const char *restrict\fP \fIwords\fP\fB, wordexp_t *restrict\fP +\fIpwordexp\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIflags\fP\fB); +.br +void wordfree(wordexp_t *\fP\fIpwordexp\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwordexp\fP() function shall perform word expansions as described +in the Shell and Utilities volume of +IEEE\ Std\ 1003.1-2001, Section 2.6, Word Expansions, subject to +quoting as in the Shell and Utilities volume of IEEE\ Std\ 1003.1-2001, +Section 2.2, Quoting, and place the list of expanded words into the +structure pointed +to by \fIpwordexp\fP. +.LP +The \fIwords\fP argument is a pointer to a string containing one or +more words to be expanded. The expansions shall be the same +as would be performed by the command line interpreter if \fIwords\fP +were the part of a command line representing the arguments to +a utility. Therefore, the application shall ensure that \fIwords\fP +does not contain an unquoted or any of the +unquoted shell special characters \fB'|'\fP , \fB'&'\fP , \fB';'\fP +, \fB'<'\fP , \fB'>'\fP except in the +context of command substitution as specified in the Shell and Utilities +volume of IEEE\ Std\ 1003.1-2001, Section 2.6.3, Command Substitution. +It also shall not contain unquoted parentheses +or braces, except in the context of command or variable substitution. +The application shall ensure that every member of +\fIwords\fP which it expects to have expanded by \fIwordexp\fP() does +not contain an unquoted initial comment character. The +application shall also ensure that any words which it intends to be +ignored (because they begin or continue a comment) are deleted +from \fIwords\fP. If the argument \fIwords\fP contains an unquoted +comment character (number sign) that is the beginning of a +token, \fIwordexp\fP() shall either treat the comment character as +a regular character, or interpret it as a comment indicator and +ignore the remainder of \fIwords\fP. +.LP +The structure type \fBwordexp_t\fP is defined in the \fI\fP +header +and includes at least the following members: +.TS C +center; l1 l1 lw(40). +\fBMember Type\fP \fBMember Name\fP T{ +.na +\fBDescription\fP +.ad +T} +\fBsize_t\fP \fIwe_wordc\fP T{ +.na +Count of words matched by \fIwords\fP. +.ad +T} +\fBchar **\fP \fIwe_wordv\fP T{ +.na +Pointer to list of expanded words. +.ad +T} +\fBsize_t\fP \fIwe_offs\fP T{ +.na +Slots to reserve at the beginning of \fIpwordexp\fP->\fIwe_wordv\fP. +.ad +T} +.TE +.LP +The \fIwordexp\fP() function shall store the number of generated words +into \fIpwordexp\fP->\fIwe_wordc\fP and a pointer +to a list of pointers to words in \fIpwordexp\fP->\fIwe_wordv\fP. +Each individual field created during field splitting (see +the Shell and Utilities volume of IEEE\ Std\ 1003.1-2001, Section +2.6.5, Field Splitting) or pathname expansion (see the Shell and Utilities +volume of IEEE\ Std\ 1003.1-2001, Section 2.6.6, Pathname Expansion) +shall be a separate word in the +\fIpwordexp\fP->\fIwe_wordv\fP list. The words shall be in order as +described in the Shell and Utilities volume of +IEEE\ Std\ 1003.1-2001, Section 2.6, Word Expansions. The first +pointer after the last word pointer shall be a null pointer. The expansion +of special parameters described in the Shell and +Utilities volume of IEEE\ Std\ 1003.1-2001, Section 2.5.2, Special +Parameters is unspecified. +.LP +It is the caller's responsibility to allocate the storage pointed +to by \fIpwordexp\fP. The \fIwordexp\fP() function shall +allocate other space as needed, including memory pointed to by \fIpwordexp\fP->\fIwe_wordv\fP. +The \fIwordfree\fP() function +frees any memory associated with \fIpwordexp\fP from a previous call +to \fIwordexp\fP(). +.LP +The \fIflags\fP argument is used to control the behavior of \fIwordexp\fP(). +The value of \fIflags\fP is the +bitwise-inclusive OR of zero or more of the following constants, which +are defined in \fI\fP: +.TP 7 +WRDE_APPEND +Append words generated to the ones from a previous call to \fIwordexp\fP(). +.TP 7 +WRDE_DOOFFS +Make use of \fIpwordexp\fP->\fIwe_offs\fP. If this flag is set, \fIpwordexp\fP->\fIwe_offs\fP +is used to specify how +many null pointers to add to the beginning of \fIpwordexp\fP->\fIwe_wordv\fP. +In other words, +\fIpwordexp\fP->\fIwe_wordv\fP shall point to \fIpwordexp\fP->\fIwe_offs\fP +null pointers, followed by +\fIpwordexp\fP->\fIwe_wordc\fP word pointers, followed by a null pointer. +.TP 7 +WRDE_NOCMD +If the implementation supports the utilities defined in the Shell +and Utilities volume of IEEE\ Std\ 1003.1-2001, fail +if command substitution, as specified in the Shell and Utilities volume +of IEEE\ Std\ 1003.1-2001, Section 2.6.3, Command Substitution, is +requested. +.TP 7 +WRDE_REUSE +The \fIpwordexp\fP argument was passed to a previous successful call +to \fIwordexp\fP(), and has not been passed to +\fIwordfree\fP(). The result shall be the same as if the application +had called \fIwordfree\fP() and then called \fIwordexp\fP() +without WRDE_REUSE. +.TP 7 +WRDE_SHOWERR +Do not redirect \fIstderr\fP to \fB/dev/null\fP. +.TP 7 +WRDE_UNDEF +Report error on an attempt to expand an undefined shell variable. +.sp +.LP +The WRDE_APPEND flag can be used to append a new set of words to those +generated by a previous call to \fIwordexp\fP(). The +following rules apply to applications when two or more calls to \fIwordexp\fP() +are made with the same value of \fIpwordexp\fP +and without intervening calls to \fIwordfree\fP(): +.IP " 1." 4 +The first such call shall not set WRDE_APPEND. All subsequent calls +shall set it. +.LP +.IP " 2." 4 +All of the calls shall set WRDE_DOOFFS, or all shall not set it. +.LP +.IP " 3." 4 +After the second and each subsequent call, \fIpwordexp\fP->\fIwe_wordv\fP +shall point to a list containing the +following: +.RS +.IP " a." 4 +Zero or more null pointers, as specified by WRDE_DOOFFS and \fIpwordexp\fP->\fIwe_offs\fP +.LP +.IP " b." 4 +Pointers to the words that were in the \fIpwordexp\fP->\fIwe_wordv\fP +list before the call, in the same order as before +.LP +.IP " c." 4 +Pointers to the new words generated by the latest call, in the specified +order +.LP +.RE +.LP +.IP " 4." 4 +The count returned in \fIpwordexp\fP->\fIwe_wordc\fP shall be the +total number of words from all of the calls. +.LP +.IP " 5." 4 +The application can change any of the fields after a call to \fIwordexp\fP(), +but if it does it shall reset them to the +original value before a subsequent call, using the same \fIpwordexp\fP +value, to \fIwordfree\fP() or \fIwordexp\fP() with the +WRDE_APPEND or WRDE_REUSE flag. +.LP +.LP +If the implementation supports the utilities defined in the Shell +and Utilities volume of IEEE\ Std\ 1003.1-2001, and +\fIwords\fP contains an unquoted character- , \fB'|'\fP , +\fB'&'\fP , \fB';'\fP , \fB'<'\fP , +\fB'>'\fP , \fB'('\fP , \fB')'\fP , \fB'{'\fP , \fB'}'\fP - in an +inappropriate context, \fIwordexp\fP() shall +fail, and the number of expanded words shall be 0. +.LP +Unless WRDE_SHOWERR is set in \fIflags\fP, \fIwordexp\fP() shall redirect +\fIstderr\fP to \fB/dev/null\fP for any utilities +executed as a result of command substitution while expanding \fIwords\fP. +If WRDE_SHOWERR is set, \fIwordexp\fP() may write +messages to \fIstderr\fP if syntax errors are detected while expanding +\fIwords\fP. +.LP +The application shall ensure that if WRDE_DOOFFS is set, then \fIpwordexp\fP->\fIwe_offs\fP +has the same value for each +\fIwordexp\fP() call and \fIwordfree\fP() call using a given \fIpwordexp\fP. +.LP +The following constants are defined as error return values: +.TP 7 +WRDE_BADCHAR +One of the unquoted characters- , \fB'|'\fP , \fB'&'\fP , +\fB';'\fP , \fB'<'\fP , +\fB'>'\fP , \fB'('\fP , \fB')'\fP , \fB'{'\fP , \fB'}'\fP - appears +in \fIwords\fP in an inappropriate +context. +.TP 7 +WRDE_BADVAL +Reference to undefined shell variable when WRDE_UNDEF is set in \fIflags\fP. +.TP 7 +WRDE_CMDSUB +Command substitution requested when WRDE_NOCMD was set in \fIflags\fP. +.TP 7 +WRDE_NOSPACE +Attempt to allocate memory failed. +.TP 7 +WRDE_SYNTAX +Shell syntax error, such as unbalanced parentheses or unterminated +string. +.sp +.SH RETURN VALUE +.LP +Upon successful completion, \fIwordexp\fP() shall return 0. Otherwise, +a non-zero value, as described in \fI\fP, shall be returned +to indicate an error. If \fIwordexp\fP() returns the +value WRDE_NOSPACE, then \fIpwordexp\fP->\fIwe_wordc\fP and \fIpwordexp\fP->\fIwe_wordv\fP +shall be updated to reflect +any words that were successfully expanded. In other cases, they shall +not be modified. +.LP +The \fIwordfree\fP() function shall not return a value. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIwordexp\fP() function is intended to be used by an application +that wants to do all of the shell's expansions on a word +or words obtained from a user. For example, if the application prompts +for a filename (or list of filenames) and then uses +\fIwordexp\fP() to process the input, the user could respond with +anything that would be valid as input to the shell. +.LP +The WRDE_NOCMD flag is provided for applications that, for security +or other reasons, want to prevent a user from executing +shell commands. Disallowing unquoted shell special characters also +prevents unwanted side effects, such as executing a command or +writing a file. +.SH RATIONALE +.LP +This function was included as an alternative to \fIglob\fP(). There +had been continuing +controversy over exactly what features should be included in \fIglob\fP(). +It is hoped that +by providing \fIwordexp\fP() (which provides all of the shell word +expansions, but which may be slow to execute) and \fIglob\fP() (which +is faster, but which only performs pathname expansion, without tilde +or parameter +expansion) this will satisfy the majority of applications. +.LP +While \fIwordexp\fP() could be implemented entirely as a library routine, +it is expected that most implementations run a shell +in a subprocess to do the expansion. +.LP +Two different approaches have been proposed for how the required information +might be presented to the shell and the results +returned. They are presented here as examples. +.LP +One proposal is to extend the \fIecho\fP utility by adding a \fB-q\fP +option. This option +would cause \fIecho\fP to add a backslash before each backslash and + that occurs +within an argument. The \fIwordexp\fP() function could then invoke +the shell as follows: +.sp +.RS +.nf + +\fB(void) strcpy(buffer, "echo -q"); +(void) strcat(buffer,\fP \fIwords\fP\fB); +if ((flags & WRDE_SHOWERR) == 0) + (void) strcat(buffer, "2>/dev/null"); +f = popen(buffer, "r"); +\fP +.fi +.RE +.LP +The \fIwordexp\fP() function would read the resulting output, remove +unquoted backslashes, and break into words at unquoted +s. If the WRDE_NOCMD flag was set, \fIwordexp\fP() would have +to scan \fIwords\fP before starting the subshell to +make sure that there would be no command substitution. In any case, +it would have to scan \fIwords\fP for unquoted special +characters. +.LP +Another proposal is to add the following options to \fIsh\fP: +.TP 7 +\fB-w\fP\ \fIwordlist\fP +.sp +This option provides a wordlist expansion service to applications. +The words in \fIwordlist\fP shall be expanded and the following +written to standard output: +.RS +.IP " 1." 4 +The count of the number of words after expansion, in decimal, followed +by a null byte +.LP +.IP " 2." 4 +The number of bytes needed to represent the expanded words (not including +null separators), in decimal, followed by a null +byte +.LP +.IP " 3." 4 +The expanded words, each terminated by a null byte +.LP +.RE +.LP +If an error is encountered during word expansion, \fIsh\fP exits with +a non-zero status +after writing the former to report any words successfully expanded +.TP 7 +\fB-P\fP +Run in "protected" mode. If specified with the \fB-w\fP option, no +command substitution shall be performed. +.sp +.LP +With these options, \fIwordexp\fP() could be implemented fairly simply +by creating a subprocess using \fIfork\fP() and executing \fIsh\fP +using the line: +.sp +.RS +.nf + +\fBexecl(<\fP\fIshell path\fP\fB>, "sh", "-P", "-w",\fP \fIwords\fP\fB, (char *)0); +\fP +.fi +.RE +.LP +after directing standard error to \fB/dev/null\fP. +.LP +It seemed objectionable for a library routine to write messages to +standard error, unless explicitly requested, so +\fIwordexp\fP() is required to redirect standard error to \fB/dev/null\fP +to ensure that no messages are generated, even for +commands executed for command substitution. The WRDE_SHOWERR flag +can be specified to request that error messages be written. +.LP +The WRDE_REUSE flag allows the implementation to avoid the expense +of freeing and reallocating memory, if that is possible. A +minimal implementation can call \fIwordfree\fP() when WRDE_REUSE is +set. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfnmatch\fP() , \fIglob\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, the Shell and Utilities +volume +of IEEE\ Std\ 1003.1-2001, Chapter 2, Shell Command Language +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wordfree.3p b/man3p/wordfree.3p new file mode 100644 index 000000000..830933fe9 --- /dev/null +++ b/man3p/wordfree.3p @@ -0,0 +1 @@ +.so man3p/wordexp.3p diff --git a/man3p/wprintf.3p b/man3p/wprintf.3p new file mode 100644 index 000000000..62b2c88fb --- /dev/null +++ b/man3p/wprintf.3p @@ -0,0 +1,610 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FWPRINTF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fwprintf +.SH NAME +fwprintf, swprintf, wprintf \- print formatted wide-character output +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int fwprintf(FILE *restrict\fP \fIstream\fP\fB, const wchar_t *restrict\fP +\fIformat\fP\fB, ...); +.br +int swprintf(wchar_t *restrict\fP \fIws\fP\fB, size_t\fP \fIn\fP\fB, +.br +\ \ \ \ \ \ const wchar_t *restrict\fP \fIformat\fP\fB, ...); +.br +int wprintf(const wchar_t *restrict\fP \fIformat\fP\fB, ...); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfwprintf\fP() function shall place output on the named output +\fIstream\fP. The \fIwprintf\fP() function shall place +output on the standard output stream \fIstdout\fP. The \fIswprintf\fP() +function shall place output followed by the null wide +character in consecutive wide characters starting at *\fIws\fP; no +more than \fIn\fP wide characters shall be written, including +a terminating null wide character, which is always added (unless \fIn\fP +is zero). +.LP +Each of these functions shall convert, format, and print its arguments +under control of the \fIformat\fP wide-character string. +The \fIformat\fP is composed of zero or more directives: \fIordinary +wide-characters\fP, which are simply copied to the output +stream, and \fIconversion specifications\fP, each of which results +in the fetching of zero or more arguments. The results are +undefined if there are insufficient arguments for the \fIformat\fP. +If the \fIformat\fP is exhausted while arguments remain, the +excess arguments are evaluated but are otherwise ignored. +.LP +Conversions can be applied to the \fIn\fPth argument after the \fIformat\fP +in the argument list, rather than to the next unused +argument. In this case, the conversion specifier wide character \fB%\fP +(see below) is replaced by the sequence \fB"%n$"\fP , +where \fIn\fP is a decimal integer in the range [1,{NL_ARGMAX}], giving +the position of the argument in the argument list. This +feature provides for the definition of \fIformat\fP wide-character +strings that select arguments in an order appropriate to +specific languages (see the EXAMPLES section). +.LP +The \fIformat\fP can contain either numbered argument specifications +(that is, \fB"%\fP\fIn\fP\fB$"\fP and +\fB"*\fP\fIm\fP\fB$"\fP), or unnumbered argument conversion specifications +(that is, \fB%\fP and \fB*\fP ), but not +both. The only exception to this is that \fB%%\fP can be mixed with +the \fB"%\fP\fIn\fP\fB$"\fP form. The results of +mixing numbered and unnumbered argument specifications in a \fIformat\fP +wide-character string are undefined. When numbered +argument specifications are used, specifying the \fIN\fPth argument +requires that all the leading arguments, from the first to the +(\fIN\fP-1)th, are specified in the \fIformat\fP wide-character string. +.LP +In \fIformat\fP wide-character strings containing the \fB"%\fP\fIn\fP\fB$"\fP +form of conversion specification, numbered +arguments in the argument list can be referenced from the \fIformat\fP +wide-character string as many times as required. +.LP +In \fIformat\fP wide-character strings containing the \fB%\fP form +of conversion specification, each argument in the +argument list shall be used exactly once. +.LP +All +forms of the \fIfwprintf\fP() function allow for the insertion of +a locale-dependent radix character in the output string, output +as a wide-character value. The radix character is defined in the program's +locale (category \fILC_NUMERIC ).\fP In the POSIX +locale, or in a locale where the radix character is not defined, the +radix character shall default to a period ( \fB'.'\fP ). +.LP +Each conversion specification is introduced by the \fB'%'\fP wide +character \ or by the +wide-character sequence \fB"%\fP\fIn\fP\fB$"\fP, \ after +which the following appear in sequence: +.IP " *" 3 +Zero or more \fIflags\fP (in any order), which modify the meaning +of the conversion specification. +.LP +.IP " *" 3 +An optional minimum \fIfield width\fP. If the converted value has +fewer wide characters than the field width, it shall be +padded with spaces by default on the left; it shall be padded on the +right, if the left-adjustment flag ( \fB'-'\fP ), described +below, is given to the field width. The field width takes the form +of an asterisk ( \fB'*'\fP ), described below, or a decimal +integer. +.LP +.IP " *" 3 +An optional \fIprecision\fP that gives the minimum number of digits +to appear for the \fBd\fP , \fBi\fP , \fBo\fP , +\fBu\fP , \fBx\fP , and \fBX\fP conversion specifiers; the number +of digits to appear after the radix character for the +\fBa\fP , \fBA\fP , \fBe\fP , \fBE\fP , \fBf\fP , and \fBF\fP conversion +specifiers; the maximum number of +significant digits for the \fBg\fP and \fBG\fP conversion specifiers; +or the maximum number of wide characters to be printed +from a string in the \fBs\fP conversion specifiers. The precision +takes the form of a period ( \fB'.'\fP ) followed either by +an asterisk ( \fB'*'\fP ), described below, or an optional decimal +digit string, where a null digit string is treated as 0. If a +precision appears with any other conversion wide character, the behavior +is undefined. +.LP +.IP " *" 3 +An optional length modifier that specifies the size of the argument. +.LP +.IP " *" 3 +A \fIconversion specifier\fP wide character that indicates the type +of conversion to be applied. +.LP +.LP +A field width, or precision, or both, may be indicated by an asterisk +( \fB'*'\fP ). In this case an argument of type +\fBint\fP supplies the field width or precision. Applications shall +ensure that arguments specifying field width, or precision, or +both appear in that order before the argument, if any, to be converted. +A negative field width is taken as a \fB'-'\fP flag +followed by a positive field width. A negative precision is taken +as if the precision were omitted. \ In +\fIformat\fP wide-character strings containing the \fB"%\fP\fIn\fP\fB$"\fP +form of a conversion specification, a field +width or precision may be indicated by the sequence \fB"*\fP\fIm\fP\fB$"\fP, +where \fIm\fP is a decimal integer in the +range [1,{NL_ARGMAX}] giving the position in the argument list (after +the \fIformat\fP argument) of an integer argument containing +the field width or precision, for example: +.sp +.RS +.nf + +\fBwprintf(L"%1$d:%2$.*3$d:%4$.*3$d\\n", hour, min, precision, sec); +\fP +.fi +.RE +.LP +The flag wide characters and their meanings are: +.TP 7 +\fB'\fP +The integer portion of the result of a decimal conversion ( \fB%i\fP +, \fB%d\fP , \fB%u\fP , \fB%f\fP , \fB%F\fP , +\fB%g\fP , or \fB%G\fP ) shall be formatted with thousands' grouping +wide characters. For other conversions, the behavior is +undefined. The numeric grouping wide character is used. +.TP 7 +\fB-\fP +The result of the conversion shall be left-justified within the field. +The conversion shall be right-justified if this flag is +not specified. +.TP 7 +\fB+\fP +The result of a signed conversion shall always begin with a sign ( +\fB'+'\fP or \fB'-'\fP ). The conversion shall begin +with a sign only when a negative value is converted if this flag is +not specified. +.TP 7 + +If the first wide character of a signed conversion is not a sign, +or if a signed conversion results in no wide characters, a + shall be prefixed to the result. This means that if the +and \fB'+'\fP flags both appear, the + flag shall be ignored. +.TP 7 +\fB#\fP +Specifies that the value is to be converted to an alternative form. +For \fBo\fP conversion, it increases the precision (if +necessary) to force the first digit of the result to be 0. For \fBx\fP +or \fBX\fP conversion specifiers, a non-zero result +shall have 0x (or 0X) prefixed to it. For \fBa\fP , \fBA\fP , \fBe\fP +, \fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP +, and \fBG\fP conversion specifiers, the result shall always contain +a radix character, even if no digits follow it. Without +this flag, a radix character appears in the result of these conversions +only if a digit follows it. For \fBg\fP and \fBG\fP +conversion specifiers, trailing zeros shall \fInot\fP be removed from +the result as they normally are. For other conversion +specifiers, the behavior is undefined. +.TP 7 +\fB0\fP +For \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , \fBx\fP , \fBX\fP , \fBa\fP +, \fBA\fP , \fBe\fP , +\fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP , and \fBG\fP conversion specifiers, +leading zeros (following any indication +of sign or base) are used to pad to the field width; no space padding +is performed. If the \fB'0'\fP and \fB'-'\fP flags both +appear, the \fB'0'\fP flag shall be ignored. For \fBd\fP , \fBi\fP +, \fBo\fP , \fBu\fP , \fBx\fP , and \fBX\fP +conversion specifiers, if a precision is specified, the \fB'0'\fP +flag shall be ignored. If the \fB'0'\fP and \fB'"\fP +flags both appear, the grouping wide characters are inserted before +zero padding. For other conversions, the behavior is +undefined. +.sp +.LP +The length modifiers and their meanings are: +.TP 7 +\fBhh\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , or \fBX\fP conversion specifier +applies to a \fBsigned char\fP or \fBunsigned char\fP argument (the +argument will have been promoted according to the integer +promotions, but its value shall be converted to \fBsigned char\fP +or \fBunsigned char\fP before printing); or that a following +\fBn\fP conversion specifier applies to a pointer to a \fBsigned char\fP +argument. +.TP 7 +\fBh\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , or \fBX\fP conversion specifier +applies to a \fBshort\fP or \fBunsigned short\fP argument (the argument +will have been promoted according to the integer +promotions, but its value shall be converted to \fBshort\fP or \fBunsigned +short\fP before printing); or that a following +\fBn\fP conversion specifier applies to a pointer to a \fBshort\fP +argument. +.TP 7 +\fBl\fP\ (ell) +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , or \fBX\fP conversion specifier +applies to a \fBlong\fP or \fBunsigned long\fP argument; that a following +\fBn\fP conversion specifier applies to a pointer to +a \fBlong\fP argument; that a following \fBc\fP conversion specifier +applies to a \fBwint_t\fP argument; that a following +\fBs\fP conversion specifier applies to a pointer to a \fBwchar_t\fP +argument; or has no effect on a following \fBa\fP , +\fBA\fP , \fBe\fP , \fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP , or \fBG\fP +conversion specifier. +.TP 7 +\fBll\fP\ (ell-ell) +.sp +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , or \fBX\fP conversion specifier +applies to a \fBlong long\fP or \fBunsigned long long\fP argument; +or that a following \fBn\fP conversion specifier applies to +a pointer to a \fBlong long\fP argument. +.TP 7 +\fBj\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , or \fBX\fP conversion specifier +applies to an \fBintmax_t\fP or \fBuintmax_t\fP argument; or that +a following \fBn\fP conversion specifier applies to a +pointer to an \fBintmax_t\fP argument. +.TP 7 +\fBz\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , or \fBX\fP conversion specifier +applies to a \fBsize_t\fP or the corresponding signed integer type +argument; or that a following \fBn\fP conversion specifier +applies to a pointer to a signed integer type corresponding to a \fBsize_t\fP +argument. +.TP 7 +\fBt\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , or \fBX\fP conversion specifier +applies to a \fBptrdiff_t\fP or the corresponding \fBunsigned\fP type +argument; or that a following \fBn\fP conversion +specifier applies to a pointer to a \fBptrdiff_t\fP argument. +.TP 7 +\fBL\fP +Specifies that a following \fBa\fP , \fBA\fP , \fBe\fP , \fBE\fP , +\fBf\fP , \fBF\fP , \fBg\fP , or +\fBG\fP conversion specifier applies to a \fBlong double\fP argument. +.sp +.LP +If a length modifier appears with any conversion specifier other than +as specified above, the behavior is undefined. +.LP +The conversion specifiers and their meanings are: +.TP 7 +\fBd\fP,\ \fBi\fP +The \fBint\fP argument shall be converted to a signed decimal in the +style \fB"[-]\fP\fIdddd"\fP. The precision specifies +the minimum number of digits to appear; if the value being converted +can be represented in fewer digits, it shall be expanded with +leading zeros. The default precision shall be 1. The result of converting +zero with an explicit precision of zero shall be no wide +characters. +.TP 7 +\fBo\fP +The \fBunsigned\fP argument shall be converted to unsigned octal format +in the style \fB"dddd"\fP . The precision specifies +the minimum number of digits to appear; if the value being converted +can be represented in fewer digits, it shall be expanded with +leading zeros. The default precision shall be 1. The result of converting +zero with an explicit precision of zero shall be no wide +characters. +.TP 7 +\fBu\fP +The \fBunsigned\fP argument shall be converted to unsigned decimal +format in the style \fB"dddd"\fP . The precision +specifies the minimum number of digits to appear; if the value being +converted can be represented in fewer digits, it shall be +expanded with leading zeros. The default precision shall be 1. The +result of converting zero with an explicit precision of zero +shall be no wide characters. +.TP 7 +\fBx\fP +The \fBunsigned\fP argument shall be converted to unsigned hexadecimal +format in the style \fB"dddd"\fP ; the letters +\fB"abcdef"\fP are used. The precision specifies the minimum number +of digits to appear; if the value being converted can be +represented in fewer digits, it shall be expanded with leading zeros. +The default precision shall be 1. The result of converting +zero with an explicit precision of zero shall be no wide characters. +.TP 7 +\fBX\fP +Equivalent to the \fBx\fP conversion specifier, except that letters +\fB"ABCDEF"\fP are used instead of \fB"abcdef"\fP +\&. +.TP 7 +\fBf\fP,\ \fBF\fP +The \fBdouble\fP argument shall be converted to decimal notation in +the style \fB"[-]\fP\fIddd.ddd"\fP, where the number +of digits after the radix character shall be equal to the precision +specification. If the precision is missing, it shall be taken +as 6; if the precision is explicitly zero and no \fB'#'\fP flag is +present, no radix character shall appear. If a radix +character appears, at least one digit shall appear before it. The +value shall be rounded in an implementation-defined manner to the +appropriate number of digits. +.LP +A \fBdouble\fP argument representing an infinity shall be converted +in one of the styles \fB"[-]inf"\fP or +\fB"[-]infinity"\fP ; which style is implementation-defined. A \fBdouble\fP +argument representing a NaN shall be converted in +one of the styles \fB"[-]nan"\fP or \fB"[-]nan(\fP\fIn-char-sequence\fP\fB)"\fP; +which style, and the meaning of any +\fIn-char-sequence\fP, is implementation-defined. The \fBF\fP conversion +specifier produces \fB"INF"\fP , +\fB"INFINITY"\fP , or \fB"NAN"\fP instead of \fB"inf"\fP , \fB"infinity"\fP +, or \fB"nan"\fP , respectively. +.TP 7 +\fBe\fP,\ \fBE\fP +The \fBdouble\fP argument shall be converted in the style \fB"[-]\fP\fId.ddd\fPe\fB\(+-dd"\fP, +where there shall be +one digit before the radix character (which is non-zero if the argument +is non-zero) and the number of digits after it shall be +equal to the precision; if the precision is missing, it shall be taken +as 6; if the precision is zero and no \fB'#'\fP flag is +present, no radix character shall appear. The value shall be rounded +in an implementation-defined manner to the appropriate number +of digits. The \fBE\fP conversion wide character shall produce a number +with \fB'E'\fP instead of \fB'e'\fP introducing +the exponent. The exponent shall always contain at least two digits. +If the value is zero, the exponent shall be zero. +.LP +A \fBdouble\fP argument representing an infinity or NaN shall be converted +in the style of an \fBf\fP or \fBF\fP +conversion specifier. +.TP 7 +\fBg\fP,\ \fBG\fP +The \fBdouble\fP argument shall be converted in the style \fBf\fP +or \fBe\fP (or in the style \fBF\fP or \fBE\fP +in the case of a \fBG\fP conversion specifier), with the precision +specifying the number of significant digits. If an explicit +precision is zero, it shall be taken as 1. The style used depends +on the value converted; style \fBe\fP (or \fBE\fP ) shall +be used only if the exponent resulting from such a conversion is less +than -4 or greater than or equal to the precision. Trailing +zeros shall be removed from the fractional portion of the result; +a radix character shall appear only if it is followed by a digit. +.LP +A \fBdouble\fP argument representing an infinity or NaN shall be converted +in the style of an \fBf\fP or \fBF\fP +conversion specifier. +.TP 7 +\fBa\fP,\ \fBA\fP +A \fBdouble\fP argument representing a floating-point number shall +be converted in the style \fB"[-]0xh.hhhhp\(+-d"\fP, +where there shall be one hexadecimal digit (which is non-zero if the +argument is a normalized floating-point number and is +otherwise unspecified) before the decimal-point wide character and +the number of hexadecimal digits after it shall be equal to the +precision; if the precision is missing and FLT_RADIX is a power of +2, then the precision shall be sufficient for an exact +representation of the value; if the precision is missing and FLT_RADIX +is not a power of 2, then the precision shall be sufficient +to distinguish values of type \fBdouble\fP, except that trailing zeros +may be omitted; if the precision is zero and the +\fB'#'\fP flag is not specified, no decimal-point wide character shall +appear. The letters \fB"abcdef"\fP are used for +\fBa\fP conversion and the letters \fB"ABCDEF"\fP for \fBA\fP conversion. +The \fBA\fP conversion specifier produces a +number with \fB'X'\fP and \fB'P'\fP instead of \fB'x'\fP and \fB'p'\fP +\&. The exponent shall always contain at least one +digit, and only as many more digits as necessary to represent the +decimal exponent of 2. If the value is zero, the exponent shall +be zero. +.LP +A \fBdouble\fP argument representing an infinity or NaN shall be converted +in the style of an \fBf\fP or \fBF\fP +conversion specifier. +.TP 7 +\fBc\fP +If no \fBl\fP (ell) qualifier is present, the \fBint\fP argument shall +be converted to a wide character as if by calling +the \fIbtowc\fP() function and the resulting wide character shall +be written. Otherwise, the +\fBwint_t\fP argument shall be converted to \fBwchar_t\fP, and written. +.TP 7 +\fBs\fP +If no \fBl\fP (ell) qualifier is present, the application shall ensure +that the argument is a pointer to a character array +containing a character sequence beginning in the initial shift state. +Characters from the array shall be converted as if by +repeated calls to the \fImbrtowc\fP() function, with the conversion +state described by an +\fBmbstate_t\fP object initialized to zero before the first character +is converted, and written up to (but not including) the +terminating null wide character. If the precision is specified, no +more than that many wide characters shall be written. If the +precision is not specified, or is greater than the size of the array, +the application shall ensure that the array contains a null +wide character. +.LP +If an \fBl\fP (ell) qualifier is present, the application shall ensure +that the argument is a pointer to an array of type +\fBwchar_t\fP. Wide characters from the array shall be written up +to (but not including) a terminating null wide character. If no +precision is specified, or is greater than the size of the array, +the application shall ensure that the array contains a null wide +character. If a precision is specified, no more than that many wide +characters shall be written. +.TP 7 +\fBp\fP +The application shall ensure that the argument is a pointer to \fBvoid\fP. +The value of the pointer shall be converted to a +sequence of printable wide characters in an implementation-defined +manner. +.TP 7 +\fBn\fP +The application shall ensure that the argument is a pointer to an +integer into which is written the number of wide characters +written to the output so far by this call to one of the \fIfwprintf\fP() +functions. No argument shall be converted, but one shall +be consumed. If the conversion specification includes any flags, a +field width, or a precision, the behavior is undefined. +.TP 7 +\fBC\fP +Equivalent to \fBlc\fP . +.TP 7 +\fBS\fP +Equivalent to \fBls\fP . +.TP 7 +\fB%\fP +Output a \fB'%'\fP wide character; no argument shall be converted. +The entire conversion specification shall be \fB%%\fP +\&. +.sp +.LP +If a conversion specification does not match one of the above forms, +the behavior is undefined. +.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 shall be expanded to contain the conversion +result. Characters generated by \fIfwprintf\fP() and +\fIwprintf\fP() shall be printed as if \fIfputwc\fP() had been called. +.LP +For \fBa\fP and \fBA\fP conversions, if FLT_RADIX is not a power of +2 and the result is not exactly representable in the +given precision, the result should be one of the two adjacent numbers +in hexadecimal floating style with the given precision, with +the extra stipulation that the error should have a correct sign for +the current rounding direction. +.LP +For \fBe\fP , \fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP , and \fBG\fP +conversion specifiers, if the number of +significant decimal digits is at most DECIMAL_DIG, then the result +should be correctly rounded. If the number of significant +decimal digits is more than DECIMAL_DIG but the source value is exactly +representable with DECIMAL_DIG digits, then the result +should be an exact representation with trailing zeros. Otherwise, +the source value is bounded by two adjacent decimal strings +\fIL\fP < \fIU\fP, both having DECIMAL_DIG significant digits; the +value of the resultant decimal string \fID\fP should +satisfy \fIL\fP <= \fID\fP <= \fIU\fP, with the extra stipulation +that the error should have a correct sign for the +current rounding direction. +.LP +The +\fIst_ctime\fP and \fIst_mtime\fP fields of the file shall be marked +for update between the call to a successful execution of +\fIfwprintf\fP() or \fIwprintf\fP() and the next successful completion +of a call to \fIfflush\fP() or \fIfclose\fP() on the same stream, +or a +call to \fIexit\fP() or \fIabort\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the number +of wide characters transmitted, excluding the terminating +null wide character in the case of \fIswprintf\fP(), or a negative +value if an output error was encountered, \ and set +\fIerrno\fP to indicate the error. +.LP +If \fIn\fP or more wide characters were requested to be written, \fIswprintf\fP() +shall return a negative value, \ and set +\fIerrno\fP to indicate the error. +.SH ERRORS +.LP +For the conditions under which \fIfwprintf\fP() and \fIwprintf\fP() +fail and may fail, refer to \fIfputwc\fP() . +.LP +In addition, all forms of \fIfwprintf\fP() may fail if: +.TP 7 +.B EILSEQ +A wide-character code that does not correspond to a valid character +has been detected. +.TP 7 +.B EINVAL +There are insufficient arguments. +.sp +.LP +In addition, \fIwprintf\fP() and \fIfwprintf\fP() may fail if: +.TP 7 +.B ENOMEM +Insufficient storage space is available. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +To print the language-independent date and time format, the following +statement could be used: +.sp +.RS +.nf + +\fBwprintf(format, weekday, month, day, hour, min); +\fP +.fi +.RE +.LP +For American usage, \fIformat\fP could be a pointer to the wide-character +string: +.sp +.RS +.nf + +\fBL"%s, %s %d, %d:%.2d\\n" +\fP +.fi +.RE +.LP +producing the message: +.sp +.RS +.nf + +\fBSunday, July 3, 10:02 +\fP +.fi +.RE +.LP +whereas for German usage, \fIformat\fP could be a pointer to the wide-character +string: +.sp +.RS +.nf + +\fBL"%1$s, %3$d. %2$s, %4$d:%5$.2d\\n" +\fP +.fi +.RE +.LP +producing the message: +.sp +.RS +.nf + +\fBSonntag, 3. Juli, 10:02 +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIbtowc\fP() , \fIfputwc\fP() , \fIfwscanf\fP() , \fImbrtowc\fP() +, \fIsetlocale\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 7, +Locale, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/write.3p b/man3p/write.3p new file mode 100644 index 000000000..32f270c2d --- /dev/null +++ b/man3p/write.3p @@ -0,0 +1,585 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WRITE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" write +.SH NAME +pwrite, write \- write on a file +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +\fP +.LP +\fBssize_t pwrite(int\fP \fIfildes\fP\fB, const void *\fP\fIbuf\fP\fB, +size_t\fP +\fInbyte\fP\fB, +.br +\ \ \ \ \ \ off_t offset); \fP +\fB +.br +ssize_t write(int\fP \fIfildes\fP\fB, const void *\fP\fIbuf\fP\fB, +size_t\fP \fInbyte\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIwrite\fP() function shall attempt to write \fInbyte\fP bytes +from the buffer pointed to by \fIbuf\fP to the file +associated with the open file descriptor, \fIfildes\fP. +.LP +Before any action described below is taken, and if \fInbyte\fP is +zero and the file is a regular file, the \fIwrite\fP() +function may detect and return errors as described below. In the absence +of errors, or if error detection is not performed, the +\fIwrite\fP() function shall return zero and have no other results. +If \fInbyte\fP is zero and the file is not a regular file, +the results are unspecified. +.LP +On a regular file or other file capable of seeking, the actual writing +of data shall proceed from the position in the file +indicated by the file offset associated with \fIfildes\fP. Before +successful return from \fIwrite\fP(), the file offset shall be +incremented by the number of bytes actually written. On a regular +file, if this incremented file offset is greater than the length +of the file, the length of the file shall be set to this file offset. +.LP +On a file not capable of seeking, writing shall always take place +starting at the current position. The value of a file offset +associated with such a device is undefined. +.LP +If the O_APPEND flag of the file status flags is set, the file offset +shall be set to the end of the file prior to each write +and no intervening file modification operation shall occur between +changing the file offset and the write operation. +.LP +If a \fIwrite\fP() requests that more bytes be written than there +is room for (for example, \ the process' +file size limit or the physical end of a medium), only as many +bytes as there is room for shall be written. For example, suppose +there is space for 20 bytes more in a file before reaching a +limit. A write of 512 bytes will return 20. The next write of a non-zero +number of bytes would give a failure return (except as +noted below). +.LP +If the request would cause the file size to exceed the soft file size +limit for the process and there is no room for any bytes to +be written, the request shall fail and the implementation shall generate +the SIGXFSZ signal for the thread. +.LP +If \fIwrite\fP() is interrupted by a signal before it writes any data, +it shall return -1 with \fIerrno\fP set to [EINTR]. +.LP +If \fIwrite\fP() is interrupted by a signal after it successfully +writes some data, it shall return the number of bytes +written. +.LP +If the value of \fInbyte\fP is greater than {SSIZE_MAX}, the result +is implementation-defined. +.LP +After a \fIwrite\fP() to a regular file has successfully returned: +.IP " *" 3 +Any successful \fIread\fP() from each byte position in the file that +was modified by that +write shall return the data specified by the \fIwrite\fP() for that +position until such byte positions are again modified. +.LP +.IP " *" 3 +Any subsequent successful \fIwrite\fP() to the same byte position +in the file shall overwrite that file data. +.LP +.LP +Write requests to a pipe or FIFO shall be handled in the same way +as a regular file with the following exceptions: +.IP " *" 3 +There is no file offset associated with a pipe, hence each write request +shall append to the end of the pipe. +.LP +.IP " *" 3 +Write requests of {PIPE_BUF} bytes or less shall not be interleaved +with data from other processes doing writes on the same +pipe. Writes of greater than {PIPE_BUF} bytes may have data interleaved, +on arbitrary boundaries, with writes by other processes, +whether or not the O_NONBLOCK flag of the file status flags is set. +.LP +.IP " *" 3 +If the O_NONBLOCK flag is clear, a write request may cause the thread +to block, but on normal completion it shall return +\fInbyte\fP. +.LP +.IP " *" 3 +If the O_NONBLOCK flag is set, \fIwrite\fP() requests shall be handled +differently, in the following ways: +.RS +.IP " *" 3 +The \fIwrite\fP() function shall not block the thread. +.LP +.IP " *" 3 +A write request for {PIPE_BUF} or fewer bytes shall have the following +effect: if there is sufficient space available in the +pipe, \fIwrite\fP() shall transfer all the data and return the number +of bytes requested. Otherwise, \fIwrite\fP() shall transfer +no data and return -1 with \fIerrno\fP set to [EAGAIN]. +.LP +.IP " *" 3 +A write request for more than {PIPE_BUF} bytes shall cause one of +the following: +.RS +.IP " *" 3 +When at least one byte can be written, transfer what it can and return +the number of bytes written. When all data previously +written to the pipe is read, it shall transfer at least {PIPE_BUF} +bytes. +.LP +.IP " *" 3 +When no data can be written, transfer no data, and return -1 with +\fIerrno\fP set to [EAGAIN]. +.LP +.RE +.LP +.RE +.LP +.LP +When attempting to write to a file descriptor (other than a pipe or +FIFO) that supports non-blocking writes and cannot accept +the data immediately: +.IP " *" 3 +If the O_NONBLOCK flag is clear, \fIwrite\fP() shall block the calling +thread until the data can be accepted. +.LP +.IP " *" 3 +If the O_NONBLOCK flag is set, \fIwrite\fP() shall not block the thread. +If some data can be written without blocking the +thread, \fIwrite\fP() shall write what it can and return the number +of bytes written. Otherwise, it shall return -1 and set +\fIerrno\fP to [EAGAIN]. +.LP +.LP +Upon successful completion, where \fInbyte\fP is greater than 0, \fIwrite\fP() +shall mark for update the \fIst_ctime\fP and +\fIst_mtime\fP fields of the file, and if the file is a regular file, +the S_ISUID and S_ISGID bits of the file mode may be +cleared. +.LP +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +\fIfildes\fP. +.LP +If \fIfildes\fP refers to a socket, \fIwrite\fP() shall be equivalent +to \fIsend\fP() +with no flags set. +.LP +If the O_DSYNC bit has been set, write I/O operations on the file +descriptor shall complete as defined by synchronized I/O data +integrity completion. +.LP +If the O_SYNC bit has been set, write I/O operations on the file descriptor +shall complete as defined by synchronized I/O file +integrity completion. +.LP +If \fIfildes\fP refers to a shared memory object, the result of the +\fIwrite\fP() function is unspecified. +.LP +If \fIfildes\fP refers to a typed memory object, the result of the +\fIwrite\fP() function is unspecified. +.LP +If \fIfildes\fP refers to a STREAM, the operation of \fIwrite\fP() +shall be determined by the values of the minimum and maximum +\fInbyte\fP range (packet size) accepted by the STREAM. These values +are determined by the topmost STREAM module. If \fInbyte\fP +falls within the packet size range, \fInbyte\fP bytes shall be written. +If \fInbyte\fP does not fall within the range and the +minimum packet size value is 0, \fIwrite\fP() shall break the buffer +into maximum packet size segments prior to sending the data +downstream (the last segment may contain less than the maximum packet +size). If \fInbyte\fP does not fall within the range and the +minimum value is non-zero, \fIwrite\fP() shall fail with \fIerrno\fP +set to [ERANGE]. Writing a zero-length buffer ( \fInbyte\fP +is 0) to a STREAMS device sends 0 bytes with 0 returned. However, +writing a zero-length buffer to a STREAMS-based pipe or FIFO +sends no message and 0 is returned. The process may issue I_SWROPT +\fIioctl\fP() to enable +zero-length messages to be sent across the pipe or FIFO. +.LP +When writing to a STREAM, data messages are created with a priority +band of 0. When writing to a STREAM that is not a pipe or +FIFO: +.IP " *" 3 +If O_NONBLOCK is clear, and the STREAM cannot accept data (the STREAM +write queue is full due to internal flow control +conditions), \fIwrite\fP() shall block until data can be accepted. +.LP +.IP " *" 3 +If O_NONBLOCK is set and the STREAM cannot accept data, \fIwrite\fP() +shall return -1 and set \fIerrno\fP to [EAGAIN]. +.LP +.IP " *" 3 +If O_NONBLOCK is set and part of the buffer has been written while +a condition in which the STREAM cannot accept additional data +occurs, \fIwrite\fP() shall terminate and return the number of bytes +written. +.LP +.LP +In addition, \fIwrite\fP() shall fail if the STREAM head has processed +an asynchronous error before the call. In this case, the +value of \fIerrno\fP does not reflect the result of \fIwrite\fP(), +but reflects the prior error. +.LP +The \fIpwrite\fP() function shall be equivalent to \fIwrite\fP(), +except that it writes into a given position without changing +the file pointer. The first three arguments to \fIpwrite\fP() are +the same as \fIwrite\fP() with the addition of a fourth +argument offset for the desired position inside the file. +.SH RETURN VALUE +.LP +Upon successful completion, \fIwrite\fP() \ and \fIpwrite\fP() +shall return the number of bytes actually written to the file associated +with \fIfildes\fP. This number +shall never be greater than \fInbyte\fP. Otherwise, -1 shall be returned +and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIwrite\fP() and \fIpwrite\fP() functions shall fail +if: +.TP 7 +.B EAGAIN +The O_NONBLOCK flag is set for the file descriptor and the thread +would be delayed in the \fIwrite\fP() operation. +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor open for +writing. +.TP 7 +.B EFBIG +An attempt was made to write a file that exceeds the implementation-defined +maximum file size \ or the +process' file size limit, \ and there was no room for any bytes +to be written. +.TP 7 +.B EFBIG +The file is a regular file, \fInbyte\fP is greater than 0, and the +starting position is greater than or equal to the offset +maximum established in the open file description associated with \fIfildes\fP. +.TP 7 +.B EINTR +The write operation was terminated due to the receipt of a signal, +and no data was transferred. +.TP 7 +.B EIO +The process is a member of a background process group attempting to +write to its controlling terminal, TOSTOP is set, the +process is neither ignoring nor blocking SIGTTOU, and the process +group of the process is orphaned. This error may also be returned +under implementation-defined conditions. +.TP 7 +.B ENOSPC +There was no free space remaining on the device containing the file. +.TP 7 +.B EPIPE +An attempt is made to write to a pipe or FIFO that is not open for +reading by any process, or that only has one end open. A +SIGPIPE signal shall also be sent to the thread. +.TP 7 +.B ERANGE +The transfer request size was outside the range supported by the STREAMS +file associated with \fIfildes\fP. +.sp +.LP +The \fIwrite\fP() function shall fail if: +.TP 7 +.B EAGAIN \fRor\fP EWOULDBLOCK +.sp +The file descriptor is for a socket, is marked O_NONBLOCK, and write +would block. +.TP 7 +.B ECONNRESET +A write was attempted on a socket that is not connected. +.TP 7 +.B EPIPE +A write was attempted on a socket that is shut down for writing, or +is no longer connected. In the latter case, if the socket +is of type SOCK_STREAM, the SIGPIPE signal is generated to the calling +process. +.sp +.LP +The \fIwrite\fP() and \fIpwrite\fP() functions may fail +if: +.TP 7 +.B EINVAL +The STREAM or multiplexer referenced by \fIfildes\fP is linked (directly +or indirectly) downstream from a multiplexer. +.TP 7 +.B EIO +A physical I/O error has occurred. +.TP 7 +.B ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP 7 +.B ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.TP 7 +.B ENXIO +A hangup occurred on the STREAM being written to. +.sp +.LP +A +write to a STREAMS file may fail if an error message has been received +at the STREAM head. In this case, \fIerrno\fP is set to the +value included in the error message. +.LP +The \fIwrite\fP() function may fail if: +.TP 7 +.B EACCES +A write was attempted on a socket and the calling process does not +have appropriate privileges. +.TP 7 +.B ENETDOWN +A write was attempted on a socket and the local network interface +used to reach the destination is down. +.TP 7 +.B ENETUNREACH +.sp +A write was attempted on a socket and no route to the network is present. +.sp +.LP +The \fIpwrite\fP() function shall fail and the file pointer remain +unchanged if: +.TP 7 +.B EINVAL +The \fIoffset\fP argument is invalid. The value is negative. +.TP 7 +.B ESPIPE +\fIfildes\fP is associated with a pipe or FIFO. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Writing from a Buffer +.LP +The following example writes data from the buffer pointed to by \fIbuf\fP +to the file associated with the file descriptor +\fIfd\fP. +.sp +.RS +.nf + +\fB#include +#include +\&... +char buf[20]; +size_t nbytes; +ssize_t bytes_written; +int fd; +\&... +strcpy(buf, "This is a test\\n"); +nbytes = strlen(buf); +.sp + +bytes_written = write(fd, buf, nbytes); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +See also the RATIONALE section in \fIread\fP() . +.LP +An attempt to write to a pipe or FIFO has several major characteristics: +.IP " *" 3 +\fIAtomic/non-atomic\fP: A write is atomic if the whole amount written +in one operation is not interleaved with data from any +other process. This is useful when there are multiple writers sending +data to a single reader. Applications need to know how large +a write request can be expected to be performed atomically. This maximum +is called {PIPE_BUF}. This volume of +IEEE\ Std\ 1003.1-2001 does not say whether write requests for more +than {PIPE_BUF} bytes are atomic, but requires that +writes of {PIPE_BUF} or fewer bytes shall be atomic. +.LP +.IP " *" 3 +\fIBlocking/immediate\fP: Blocking is only possible with O_NONBLOCK +clear. If there is enough space for all the data requested +to be written immediately, the implementation should do so. Otherwise, +the process may block; that is, pause until enough space is +available for writing. The effective size of a pipe or FIFO (the maximum +amount that can be written in one operation without +blocking) may vary dynamically, depending on the implementation, so +it is not possible to specify a fixed value for it. +.LP +.IP " *" 3 +\fIComplete/partial/deferred\fP: A write request: +.sp +.RS +.nf + +\fBint fildes; +size_t nbyte; +ssize_t ret; +char *buf; +.sp + +ret = write(fildes, buf, nbyte); +\fP +.fi +.RE +.LP +may return: +.TP 7 +Complete +.RS +\fIret\fP=\fInbyte\fP +.RE +.TP 7 +Partial +.RS +\fIret\fP<\fInbyte\fP +.LP +This shall never happen if \fInbyte\fP<= {PIPE_BUF}. If it does happen +(with \fInbyte\fP> {PIPE_BUF}), this volume of +IEEE\ Std\ 1003.1-2001 does not guarantee atomicity, even if \fIret\fP<= +{PIPE_BUF}, because atomicity is guaranteed +according to the amount \fIrequested\fP, not the amount \fIwritten\fP. +.RE +.TP 7 +Deferred: +.RS +\fIret\fP=-1, \fIerrno\fP=[EAGAIN] +.LP +This error indicates that a later request may succeed. It does not +indicate that it \fIshall\fP succeed, even if +\fInbyte\fP<= {PIPE_BUF}, because if no process reads from the pipe +or FIFO, the write never succeeds. An application could +usefully count the number of times [EAGAIN] is caused by a particular +value of \fInbyte\fP> {PIPE_BUF} and perhaps do later +writes with a smaller value, on the assumption that the effective +size of the pipe may have decreased. +.RE +.sp +.LP +Partial and deferred writes are only possible with O_NONBLOCK set. +.LP +.LP +The relations of these properties are shown in the following tables: +.TS C +center;c2 s2 s2 s. +\fBWrite to a Pipe or FIFO with O_NONBLOCK \fIclear\fP\fP +.T& +l l l l. +\fBImmediately Writable:\fP \fBNone\fP \fBSome\fP \fInbyte\fP +\fInbyte\fP<={PIPE_BUF} Atomic blocking Atomic blocking Atomic immediate +\ \fInbyte\fP \fInbyte\fP \fInbyte\fP +\fInbyte\fP>{PIPE_BUF} Blocking \fInbyte\fP Blocking \fInbyte\fP Blocking \fInbyte\fP +.TE +.LP +If the O_NONBLOCK flag is clear, a write request shall block if the +amount writable immediately is less than that requested. If +the flag is set (by \fIfcntl\fP()), a write request shall never block. +.TS C +center;c2 s2 s2 s. +\fBWrite to a Pipe or FIFO with O_NONBLOCK \fIset\fP\fP +.T& +l l l l. +\fBImmediately Writable:\fP \fBNone\fP \fBSome\fP \fInbyte\fP +\fInbyte\fP<={PIPE_BUF} -1, [EAGAIN] -1, [EAGAIN] Atomic \fInbyte\fP +\fInbyte\fP>{PIPE_BUF} -1, [EAGAIN] <\fInbyte\fP or -1, <=\fInbyte\fP or -1, +\ \ [EAGAIN] [EAGAIN] +.TE +.LP +There is no exception regarding partial writes when O_NONBLOCK is +set. With the exception of writing to an empty pipe, this +volume of IEEE\ Std\ 1003.1-2001 does not specify exactly when a partial +write is performed since that would require +specifying internal details of the implementation. Every application +should be prepared to handle partial writes when O_NONBLOCK is +set and the requested amount is greater than {PIPE_BUF}, just as every +application should be prepared to handle partial writes on +other kinds of file descriptors. +.LP +The intent of forcing writing at least one byte if any can be written +is to assure that each write makes progress if there is +any room in the pipe. If the pipe is empty, {PIPE_BUF} bytes must +be written; if not, at least some progress must have been +made. +.LP +Where this volume of IEEE\ Std\ 1003.1-2001 requires -1 to be returned +and \fIerrno\fP set to [EAGAIN], most historical +implementations return zero (with the O_NDELAY flag set, which is +the historical predecessor of O_NONBLOCK, but is not itself in +this volume of IEEE\ Std\ 1003.1-2001). The error indications in this +volume of IEEE\ Std\ 1003.1-2001 were chosen +so that an application can distinguish these cases from end-of-file. +While \fIwrite\fP() cannot receive an indication of +end-of-file, \fIread\fP() can, and the two functions have similar +return values. Also, some +existing systems (for example, Eighth Edition) permit a write of zero +bytes to mean that the reader should get an end-of-file +indication; for those systems, a return value of zero from \fIwrite\fP() +indicates a successful write of an end-of-file +indication. +.LP +Implementations are allowed, but not required, to perform error checking +for \fIwrite\fP() requests of zero bytes. +.LP +The concept of a {PIPE_MAX} limit (indicating the maximum number of +bytes that can be written to a pipe in a single operation) +was considered, but rejected, because this concept would unnecessarily +limit application writing. +.LP +See also the discussion of O_NONBLOCK in \fIread\fP() . +.LP +Writes can be serialized with respect to other reads and writes. If +a \fIread\fP() of file +data can be proven (by any means) to occur after a \fIwrite\fP() of +the data, it must reflect that \fIwrite\fP(), even if the +calls are made by different processes. A similar requirement applies +to multiple write operations to the same file position. This +is needed to guarantee the propagation of data from \fIwrite\fP() +calls to subsequent \fIread\fP() calls. This requirement is particularly +significant for networked file systems, where +some caching schemes violate these semantics. +.LP +Note that this is specified in terms of \fIread\fP() and \fIwrite\fP(). +The XSI +extensions \fIreadv\fP() and \fIwritev\fP() also +obey these semantics. A new "high-performance" write analog that did +not follow these serialization requirements would also be +permitted by this wording. This volume of IEEE\ Std\ 1003.1-2001 is +also silent about any effects of application-level +caching (such as that done by \fIstdio\fP). +.LP +This volume of IEEE\ Std\ 1003.1-2001 does not specify the value of +the file offset after an error is returned; there +are too many cases. For programming errors, such as [EBADF], the concept +is meaningless since no file is involved. For errors that +are detected immediately, such as [EAGAIN], clearly the pointer should +not change. After an interrupt or hardware error, however, +an updated value would be very useful and is the behavior of many +implementations. +.LP +This volume of IEEE\ Std\ 1003.1-2001 does not specify behavior of +concurrent writes to a file from multiple processes. +Applications should use some form of concurrency control. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchmod\fP() , \fIcreat\fP() , \fIdup\fP() , \fIfcntl\fP() , \fIgetrlimit\fP() +, \fIlseek\fP() , +\fIopen\fP() , \fIpipe\fP() , \fIulimit\fP() , \fIwritev\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, +\fI\fP, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/writev.3p b/man3p/writev.3p new file mode 100644 index 000000000..aba53f254 --- /dev/null +++ b/man3p/writev.3p @@ -0,0 +1,124 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WRITEV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" writev +.SH NAME +writev \- write a vector +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +ssize_t writev(int\fP \fIfildes\fP\fB, const struct iovec *\fP\fIiov\fP\fB, +int\fP \fIiovcnt\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIwritev\fP() function shall be equivalent to \fIwrite\fP(), +except as described +below. The \fIwritev\fP() function shall gather output data from the +\fIiovcnt\fP buffers specified by the members of the +\fIiov\fP array: \fIiov\fP[0], \fIiov\fP[1], ..., \fIiov\fP[\fIiovcnt\fP-1]. +The \fIiovcnt\fP argument is valid if greater +than 0 and less than or equal to {IOV_MAX}, as defined in \fI\fP. +.LP +Each \fIiovec\fP entry specifies the base address and length of an +area in memory from which data should be written. The +\fIwritev\fP() function shall always write a complete area before +proceeding to the next. +.LP +If \fIfildes\fP refers to a regular file and all of the \fIiov_len\fP +members in the array pointed to by \fIiov\fP are 0, +\fIwritev\fP() shall return 0 and have no other effect. For other +file types, the behavior is unspecified. +.LP +If the sum of the \fIiov_len\fP values is greater than {SSIZE_MAX}, +the operation shall fail and no data shall be +transferred. +.SH RETURN VALUE +.LP +Upon successful completion, \fIwritev\fP() shall return the number +of bytes actually written. Otherwise, it shall return a +value of -1, the file-pointer shall remain unchanged, and \fIerrno\fP +shall be set to indicate an error. +.SH ERRORS +.LP +Refer to \fIwrite\fP() . +.LP +In addition, the \fIwritev\fP() function shall fail if: +.TP 7 +.B EINVAL +The sum of the \fIiov_len\fP values in the \fIiov\fP array would overflow +an \fBssize_t\fP. +.sp +.LP +The \fIwritev\fP() function may fail and set \fIerrno\fP to: +.TP 7 +.B EINVAL +The \fIiovcnt\fP argument was less than or equal to 0, or greater +than {IOV_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Writing Data from an Array +.LP +The following example writes data from the buffers specified by members +of the \fIiov\fP array to the file associated with the +file descriptor \fIfd\fP. +.sp +.RS +.nf + +\fB#include +#include +#include +\&... +ssize_t bytes_written; +int fd; +char *buf0 = "short string\\n"; +char *buf1 = "This is a longer string\\n"; +char *buf2 = "This is the longest string in this example\\n"; +int iovcnt; +struct iovec iov[3]; +.sp + +iov[0].iov_base = buf0; +iov[0].iov_len = strlen(buf0); +iov[1].iov_base = buf1; +iov[1].iov_len = strlen(buf1); +iov[2].iov_base = buf2; +iov[2].iov_len = strlen(buf2); +\&... +iovcnt = sizeof(iov) / sizeof(struct iovec); +.sp + +bytes_written = writev(fd, iov, iovcnt); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Refer to \fIwrite\fP() . +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIreadv\fP() , \fIwrite\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI\fP, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/wscanf.3p b/man3p/wscanf.3p new file mode 100644 index 000000000..322d28c53 --- /dev/null +++ b/man3p/wscanf.3p @@ -0,0 +1,517 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FWSCANF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fwscanf +.SH NAME +fwscanf, swscanf, wscanf \- convert formatted wide-character input +.SH SYNOPSIS +.LP +\fB#include +.br +#include +.br +.sp +int fwscanf(FILE *restrict\fP \fIstream\fP\fB, const wchar_t *restrict\fP +\fIformat\fP\fB, ... ); +.br +int swscanf(const wchar_t *restrict\fP \fIws\fP\fB, +.br +\ \ \ \ \ \ const wchar_t *restrict\fP \fIformat\fP\fB, ... ); +.br +int wscanf(const wchar_t *restrict\fP \fIformat\fP\fB, ... ); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfwscanf\fP() function shall read from the named input \fIstream\fP. +The \fIwscanf\fP() function shall read from the +standard input stream \fIstdin\fP. The \fIswscanf\fP() function shall +read from the wide-character string \fIws\fP. Each +function reads wide characters, interprets them according to a format, +and stores the results in its arguments. Each expects, as +arguments, a control wide-character string \fIformat\fP described +below, and a set of \fIpointer\fP arguments indicating where +the converted input should be stored. The result is undefined if there +are insufficient arguments for the format. If the +\fIformat\fP is exhausted while arguments remain, the excess arguments +are evaluated but are otherwise ignored. +.LP +Conversions can be applied to the \fIn\fPth argument after the \fIformat\fP +in the argument list, rather than to the next unused +argument. In this case, the conversion specifier wide character \fB%\fP +(see below) is replaced by the sequence \fB"%n$"\fP , +where \fIn\fP is a decimal integer in the range [1,{NL_ARGMAX}]. This +feature provides for the definition of \fIformat\fP +wide-character strings that select arguments in an order appropriate +to specific languages. In \fIformat\fP wide-character strings +containing the \fB"%\fP\fIn\fP\fB$"\fP form of conversion specifications, +it is unspecified whether numbered arguments in +the argument list can be referenced from the \fIformat\fP wide-character +string more than once. +.LP +The \fIformat\fP can contain either form of a conversion specification-that +is, \fB%\fP or \fB"%\fP\fIn\fP\fB$"\fP- +but the two forms cannot normally be mixed within a single \fIformat\fP +wide-character string. The only exception to this is that +\fB%%\fP or \fB%*\fP can be mixed with the \fB"%\fP\fIn\fP\fB$"\fP +form. When numbered argument specifications are +used, specifying the \fIN\fPth argument requires that all the leading +arguments, from the first to the ( \fIN\fP-1)th, are +pointers. +.LP +The +\fIfwscanf\fP() function in all its forms allows for detection of +a language-dependent radix character in the input string, +encoded as a wide-character value. The radix character is defined +in the program's locale (category \fILC_NUMERIC ).\fP In the +POSIX locale, or in a locale where the radix character is not defined, +the radix character shall default to a period ( \fB'.'\fP +). +.LP +The \fIformat\fP is a wide-character string composed of zero or more +directives. Each directive is composed of one of the +following: one or more white-space wide characters ( s, s, +s, s, or +s); an ordinary wide character (neither \fB'%'\fP nor a +white-space character); or a conversion specification. +Each conversion specification is introduced by a \fB'%'\fP \ or +the sequence \fB"%\fP\fIn\fP\fB$"\fP after which the following appear +in sequence: +.IP " *" 3 +An optional assignment-suppressing character \fB'*'\fP . +.LP +.IP " *" 3 +An optional non-zero decimal integer that specifies the maximum field +width. +.LP +.IP " *" 3 +An optional length modifier that specifies the size of the receiving +object. +.LP +.IP " *" 3 +A conversion specifier wide character that specifies the type of conversion +to be applied. The valid conversion specifiers are +described below. +.LP +.LP +The \fIfwscanf\fP() functions shall execute each directive of the +format in turn. If a directive fails, as detailed below, the +function shall return. Failures are described as input failures (due +to the unavailability of input bytes) or matching failures +(due to inappropriate input). +.LP +A directive composed of one or more white-space wide characters is +executed by reading input until no more valid input can be +read, or up to the first wide character which is not a white-space +wide character, which remains unread. +.LP +A directive that is an ordinary wide character shall be executed as +follows. The next wide character is read from the input and +compared with the wide character that comprises the directive; if +the comparison shows that they are not equivalent, the directive +shall fail, and the differing and subsequent wide characters remain +unread. Similarly, if end-of-file, an encoding error, or a read +error prevents a wide character from being read, the directive shall +fail. +.LP +A directive that is a conversion specification defines a set of matching +input sequences, as described below for each conversion +wide character. A conversion specification is executed in the following +steps. +.LP +Input white-space wide characters (as specified by \fIiswspace\fP() +) shall be skipped, unless the +conversion specification includes a \fB[\fP , \fBc\fP , or \fBn\fP +conversion specifier. +.LP +An item shall be read from the input, unless the conversion specification +includes an \fBn\fP conversion specifier wide +character. An input item is defined as the longest sequence of input +wide characters, not exceeding any specified field width, +which is an initial subsequence of a matching sequence. The first +wide character, if any, after the input item shall remain unread. +If the length of the input item is zero, the execution of the conversion +specification shall fail; this condition is a matching +failure, unless end-of-file, an encoding error, or a read error prevented +input from the stream, in which case it is an input +failure. +.LP +Except in the case of a \fB%\fP conversion specifier, the input item +(or, in the case of a \fB%n\fP conversion +specification, the count of input wide characters) shall be converted +to a type appropriate to the conversion wide character. If +the input item is not a matching sequence, the execution of the conversion +specification shall fail; this condition is a matching +failure. Unless assignment suppression was indicated by a \fB'*'\fP +, the result of the conversion shall be placed in the object +pointed to by the first argument following the \fIformat\fP argument +that has not already received a conversion result if the +conversion specification is introduced by \fB%\fP , \ or in the +\fIn\fPth argument if introduced by the wide-character +sequence \fB"%\fP\fIn\fP\fB$"\fP. If this object does not +have an appropriate type, or if the result of the conversion cannot +be represented in the space provided, the behavior is +undefined. +.LP +The length modifiers and their meanings are: +.TP 7 +\fBhh\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBsigned +char\fP or \fBunsigned char\fP. +.TP 7 +\fBh\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBshort\fP +or \fBunsigned short\fP. +.TP 7 +\fBl\fP\ (ell) +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBlong\fP +or \fBunsigned long\fP; that a following \fBa\fP , +\fBA\fP , \fBe\fP , \fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP , or \fBG\fP +conversion specifier applies to an +argument with type pointer to \fBdouble\fP; or that a following \fBc\fP +, \fBs\fP , or \fB[\fP conversion specifier +applies to an argument with type pointer to \fBwchar_t\fP. +.TP 7 +\fBll\fP\ (ell-ell) +.sp +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP conversion +specifier applies to an argument with type pointer to \fBlong long\fP +or \fBunsigned long long\fP. +.TP 7 +\fBj\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBintmax_t\fP +or \fBuintmax_t\fP. +.TP 7 +\fBz\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBsize_t\fP +or the corresponding signed integer type. +.TP 7 +\fBt\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBptrdiff_t\fP +or the corresponding \fBunsigned\fP type. +.TP 7 +\fBL\fP +Specifies that a following \fBa\fP , \fBA\fP , \fBe\fP , \fBE\fP , +\fBf\fP , \fBF\fP , \fBg\fP , or +\fBG\fP conversion specifier applies to an argument with type pointer +to \fBlong double\fP. +.sp +.LP +If a length modifier appears with any conversion specifier other than +as specified above, the behavior is undefined. +.LP +The following conversion specifier wide characters are valid: +.TP 7 +\fBd\fP +Matches an optionally signed decimal integer, whose format is the +same as expected for the subject sequence of \fIwcstol\fP() with the +value 10 for the \fIbase\fP argument. In the absence of a size modifier, +the application shall ensure that the corresponding argument is a +pointer to \fBint\fP. +.TP 7 +\fBi\fP +Matches an optionally signed integer, whose format is the same as +expected for the subject sequence of \fIwcstol\fP() with 0 for the +\fIbase\fP argument. In the absence of a size modifier, the +application shall ensure that the corresponding argument is a pointer +to \fBint\fP. +.TP 7 +\fBo\fP +Matches an optionally signed octal integer, whose format is the same +as expected for the subject sequence of \fIwcstoul\fP() with the value +8 for the \fIbase\fP argument. In the absence of a size modifier, +the application shall ensure that the corresponding argument is a +pointer to \fBunsigned\fP. +.TP 7 +\fBu\fP +Matches an optionally signed decimal integer, whose format is the +same as expected for the subject sequence of \fIwcstoul\fP() with +the value 10 for the \fIbase\fP argument. In the absence of a size +modifier, +the application shall ensure that the corresponding argument is a +pointer to \fBunsigned\fP. +.TP 7 +\fBx\fP +Matches an optionally signed hexadecimal integer, whose format is +the same as expected for the subject sequence of \fIwcstoul\fP() with +the value 16 for the \fIbase\fP argument. In the absence of a size +modifier, +the application shall ensure that the corresponding argument is a +pointer to \fBunsigned\fP. +.TP 7 +\fBa\fP,\ \fBe\fP,\ \fBf\fP,\ \fBg\fP +.sp +Matches an optionally signed floating-point number, infinity, or NaN +whose format is the same as expected for the subject sequence +of \fIwcstod\fP(). In the absence of a size modifier, the application +shall ensure that the +corresponding argument is a pointer to \fBfloat\fP. +.LP +If the \fIfwprintf\fP() family of functions generates character string +representations +for infinity and NaN (a symbolic entity encoded in floating-point +format) to support IEEE\ Std\ 754-1985, the +\fIfwscanf\fP() family of functions shall recognize them as input. +.TP 7 +\fBs\fP +Matches a sequence of non white-space wide characters. If no \fBl\fP +(ell) qualifier is present, characters from the input +field shall be converted as if by repeated calls to the \fIwcrtomb\fP() +function, with the +conversion state described by an \fBmbstate_t\fP object initialized +to zero before the first wide character is converted. The +application shall ensure that the corresponding argument is a pointer +to a character array large enough to accept the sequence and +the terminating null character, which shall be added automatically. +.LP +Otherwise, the application shall ensure that the corresponding argument +is a pointer to an array of \fBwchar_t\fP large enough +to accept the sequence and the terminating null wide character, which +shall be added automatically. +.TP 7 +\fB[\fP +Matches a non-empty sequence of wide characters from a set of expected +wide characters (the \fIscanset\fP). If no \fBl\fP +(ell) qualifier is present, wide characters from the input field shall +be converted as if by repeated calls to the \fIwcrtomb\fP() function, +with the conversion state described by an \fBmbstate_t\fP object +initialized to zero before the first wide character is converted. +The application shall ensure that the corresponding argument is a +pointer to a character array large enough to accept the sequence and +the terminating null character, which shall be added +automatically. +.LP +If an \fBl\fP (ell) qualifier is present, the application shall ensure +that the corresponding argument is a pointer to an +array of \fBwchar_t\fP large enough to accept the sequence and the +terminating null wide character, which shall be added +automatically. +.LP +The conversion specification includes all subsequent wide characters +in the \fIformat\fP string up to and including the +matching right square bracket ( \fB']'\fP ). The wide characters between +the square brackets (the \fIscanlist\fP) comprise the +scanset, unless the wide character after the left square bracket is +a circumflex ( \fB'^'\fP ), in which case the scanset +contains all wide characters that do not appear in the scanlist between +the circumflex and the right square bracket. If the +conversion specification begins with \fB"[]"\fP or \fB"[^]"\fP , the +right square bracket is included in the scanlist and the +next right square bracket is the matching right square bracket that +ends the conversion specification; otherwise, the first right +square bracket is the one that ends the conversion specification. +If a \fB'-'\fP is in the scanlist and is not the first wide +character, nor the second where the first wide character is a \fB'^'\fP +, nor the last wide character, the behavior is +implementation-defined. +.TP 7 +\fBc\fP +Matches a sequence of wide characters of exactly the number specified +by the field width (1 if no field width is present in the +conversion specification). +.LP +If no \fBl\fP (ell) length modifier is present, characters from the +input field shall be converted as if by repeated calls to +the \fIwcrtomb\fP() function, with the conversion state described +by an \fBmbstate_t\fP +object initialized to zero before the first wide character is converted. +The corresponding argument shall be a pointer to the +initial element of a character array large enough to accept the sequence. +No null character is added. +.LP +If an \fBl\fP (ell) length modifier is present, the corresponding +argument shall be a pointer to the initial element of an +array of \fBwchar_t\fP large enough to accept the sequence. No null +wide character is added. +.LP +Otherwise, the application shall ensure that the corresponding argument +is a pointer to an array of \fBwchar_t\fP large enough +to accept the sequence. No null wide character is added. +.TP 7 +\fBp\fP +Matches an implementation-defined set of sequences, which shall be +the same as the set of sequences that is produced by the +\fB%p\fP conversion specification of the corresponding \fIfwprintf\fP() +functions. The +application shall ensure that the corresponding argument is a pointer +to a pointer to \fBvoid\fP. The interpretation of the input +item is implementation-defined. If the input item is a value converted +earlier during the same program execution, the pointer that +results shall compare equal to that value; otherwise, the behavior +of the \fB%p\fP conversion is undefined. +.TP 7 +\fBn\fP +No input is consumed. The application shall ensure that the corresponding +argument is a pointer to the integer into which is to +be written the number of wide characters read from the input so far +by this call to the \fIfwscanf\fP() functions. Execution of a +\fB%n\fP conversion specification shall not increment the assignment +count returned at the completion of execution of the +function. No argument shall be converted, but one shall be consumed. +If the conversion specification includes an +assignment-suppressing wide character or a field width, the behavior +is undefined. +.TP 7 +\fBC\fP +Equivalent to \fBlc\fP . +.TP 7 +\fBS\fP +Equivalent to \fBls\fP . +.TP 7 +\fB%\fP +Matches a single \fB'%'\fP wide character; no conversion or assignment +shall occur. The complete conversion specification +shall be \fB%%\fP . +.sp +.LP +If a conversion specification is invalid, the behavior is undefined. +.LP +The conversion specifiers \fBA\fP , \fBE\fP , \fBF\fP , \fBG\fP , +and \fBX\fP are also valid and shall be +equivalent to, respectively, \fBa\fP , \fBe\fP , \fBf\fP , \fBg\fP +, and \fBx\fP . +.LP +If end-of-file is encountered during input, conversion is terminated. +If end-of-file occurs before any wide characters matching +the current conversion specification (except for \fB%n\fP ) have been +read (other than leading white-space, where permitted), +execution of the current conversion specification shall terminate +with an input failure. Otherwise, unless execution of the current +conversion specification is terminated with a matching failure, execution +of the following conversion specification (if any) shall +be terminated with an input failure. +.LP +Reaching the end of the string in \fIswscanf\fP() shall be equivalent +to encountering end-of-file for \fIfwscanf\fP(). +.LP +If conversion terminates on a conflicting input, the offending input +shall be left unread in the input. Any trailing white space +(including ) shall be left unread unless matched by a conversion +specification. The success of literal matches and +suppressed assignments is only directly determinable via the \fB%n\fP +conversion specification. +.LP +The +\fIfwscanf\fP() and \fIwscanf\fP() functions may mark the \fIst_atime\fP +field of the file associated with \fIstream\fP for +update. The \fIst_atime\fP field shall be marked for update by the +first successful execution of \fIfgetc\fP(), \fIfgetwc\fP(), \fIfgets\fP(), +\fIfgetws\fP(), \fIfread\fP(), \fIgetc\fP(), \fIgetwc\fP(), \fIgetchar\fP(), +\fIgetwchar\fP(), \fIgets\fP(), \fIfscanf\fP(), or \fIfwscanf\fP() +using \fIstream\fP that returns data not supplied by a prior +call to \fIungetc\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the number +of successfully matched and assigned input items; this +number can be zero in the event of an early matching failure. If the +input ends before the first matching failure or conversion, +EOF shall be returned. If a read error occurs, the error indicator +for the stream is set, EOF shall be returned, \ and +\fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +For the conditions under which the \fIfwscanf\fP() functions shall +fail and may fail, refer to \fIfgetwc\fP() . +.LP +In addition, \fIfwscanf\fP() may fail if: +.TP 7 +.B EILSEQ +Input byte sequence does not form a valid character. +.TP 7 +.B EINVAL +There are insufficient arguments. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The call: +.sp +.RS +.nf + +\fBint i, n; float x; char name[50]; +n = wscanf(L"%d%f%s", &i, &x, name); +\fP +.fi +.RE +.LP +with the input line: +.sp +.RS +.nf + +\fB25 54.32E-1 Hamster +\fP +.fi +.RE +.LP +assigns to \fIn\fP the value 3, to \fIi\fP the value 25, to \fIx\fP +the value 5.432, and \fIname\fP contains the string +\fB"Hamster"\fP . +.LP +The call: +.sp +.RS +.nf + +\fBint i; float x; char name[50]; +(void) wscanf(L"%2d%f%*d %[0123456789]", &i, &x, name); +\fP +.fi +.RE +.LP +with input: +.sp +.RS +.nf + +\fB56789 0123 56a72 +\fP +.fi +.RE +.LP +assigns 56 to \fIi\fP, 789.0 to \fIx\fP, skips 0123, and places the +string \fB"56\\0"\fP in \fIname\fP. The next call to \fIgetchar\fP() +shall return the character \fB'a'\fP . +.SH APPLICATION USAGE +.LP +In format strings containing the \fB'%'\fP form of conversion specifications, +each argument in the argument list is used +exactly once. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetwc\fP() , \fIfwprintf\fP() , \fIsetlocale\fP() , \fIwcstod\fP() +, \fIwcstol\fP() , +\fIwcstoul\fP() , \fIwcrtomb\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI\fP, \fI\fP, +\fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/y0.3p b/man3p/y0.3p new file mode 100644 index 000000000..8ff21ca95 --- /dev/null +++ b/man3p/y0.3p @@ -0,0 +1,113 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "Y0" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" y0 +.SH NAME +y0, y1, yn \- Bessel functions of the second kind +.SH SYNOPSIS +.LP +\fB#include +.br +.sp +double y0(double\fP \fIx\fP\fB); +.br +double y1(double\fP \fIx\fP\fB); +.br +double yn(int\fP \fIn\fP\fB, double\fP \fIx\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIy0\fP(), \fIy1\fP(), and \fIyn\fP() functions shall compute +Bessel functions of \fIx\fP of the second kind of orders +0, 1, and \fIn\fP, respectively. +.LP +An application wishing to check for error situations should set \fIerrno\fP +to zero and call +\fIfeclearexcept\fP(FE_ALL_EXCEPT) before calling these functions. +On return, if \fIerrno\fP is non-zero or +\fIfetestexcept\fP(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) +is non-zero, an error has occurred. +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the relevant +Bessel value of \fIx\fP of the second kind. +.LP +If \fIx\fP is NaN, NaN shall be returned. +.LP +If the \fIx\fP argument to these functions is negative, -HUGE_VAL +or NaN shall be returned, and a domain error may occur. +.LP +If \fIx\fP is 0.0, -HUGE_VAL shall be returned and a range error may +occur. +.LP +If the correct result would cause underflow, 0.0 shall be returned +and a range error may occur. +.LP +If the correct result would cause overflow, -HUGE_VAL or 0.0 shall +be returned and a range error may occur. +.SH ERRORS +.LP +These functions may fail if: +.TP 7 +Domain\ Error +The value of \fIx\fP is negative. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [EDOM]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the invalid floating-point exception shall be +raised. +.TP 7 +Range\ Error +The value of \fIx\fP is 0.0, or the correct result would cause overflow. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the overflow floating-point exception shall be +raised. +.TP 7 +Range\ Error +The value of \fIx\fP is too large in magnitude, or the correct result +would cause underflow. +.LP +If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, +then \fIerrno\fP shall be set to [ERANGE]. If the +integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, +then the underflow floating-point exception shall be +raised. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling +& MATH_ERREXCEPT) are independent of +each other, but at least one of them must be non-zero. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIfeclearexcept\fP() , \fIfetestexcept\fP() , \fIisnan\fP() , \fIj0\fP() +, the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 4.18, Treatment of Error Conditions +for +Mathematical Functions, \fI\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/man3p/y1.3p b/man3p/y1.3p new file mode 100644 index 000000000..442ed02d0 --- /dev/null +++ b/man3p/y1.3p @@ -0,0 +1 @@ +.so man3p/y0.3p diff --git a/man3p/yn.3p b/man3p/yn.3p new file mode 100644 index 000000000..442ed02d0 --- /dev/null +++ b/man3p/yn.3p @@ -0,0 +1 @@ +.so man3p/y0.3p diff --git a/man4/console.4 b/man4/console.4 new file mode 100644 index 000000000..743173091 --- /dev/null +++ b/man4/console.4 @@ -0,0 +1,91 @@ +.\" Copyright (c) 1994 Andries Brouwer (aeb@cwi.nl), Mon Oct 31 21:03:19 MET 1994 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" Modified, Sun Feb 26 14:58:45 1995, faith@cs.unc.edu +.\" " +.TH CONSOLE 4 1994-10-31 "Linux" "Linux Programmer's Manual" +.SH NAME +console \- console terminal and virtual consoles +.SH DESCRIPTION +A Linux system has up to 63 \fIvirtual consoles\fP +(character devices with major number 4 and minor number 1 to 63), +usually called \fB/dev/tty\fP\fIn\fP with 1 \(<= \fIn\fP \(<= 63. +The current console is also addressed by +\fB/dev/console\fP or \fB/dev/tty0\fP, the character device with +major number 4 and minor number 0. +The device files /dev/* are usually created using the script MAKEDEV, +or using +.BR mknod (1), +usually with mode 0622 and owner root.tty. +.LP +Before kernel version 1.1.54 the number of virtual consoles was +compiled into the kernel (in tty.h: #define NR_CONSOLES 8) +and could be changed by editing and recompiling. +Since version 1.1.54 virtual consoles are created on the fly, +as soon as they are needed. +.LP +Common ways to start a process on a console are: +(a) tell +.BR init (8) +(in +.BR inittab (5)) +to start a +.BR getty (8) +on the console; +(b) ask +.BR openvt (1) +to start a process on the console; +(c) start X - it will find the first unused console, +and display its output there. +(There is also the ancient +.BR doshell (8).) +.LP +Common ways to switch consoles are: (a) use Alt+F\fIn\fP or +Ctrl+Alt+F\fIn\fP to switch to console \fIn\fP; AltGr+F\fIn\fP +might bring you to console \fIn\fP+12 [here Alt and AltGr refer +to the left and right Alt keys, respectively]; +(b) use Alt+RightArrow or Alt+LeftArrow to cycle through +the presently allocated consoles; (c) use the program chvt(1). +(The key mapping is user settable, see +.BR loadkeys (1); +the above mentioned key combinations are according to the default settings.) +.LP +The command +.BR deallocvt (1) +(formerly \fBdisalloc\fP) +will free the memory taken by the screen buffers for consoles +that no longer have any associated process. + +.SH PROPERTIES +Consoles carry a lot of state. I hope to document that some other time. +The most important fact is that the consoles simulate vt100 terminals. +In particular, a console is reset to the initial state by printing the two +characters ESC c. +All escape sequences can be found in +.BR console_codes (4). + +.LP +.SH FILES +.I /dev/console +.br +.I /dev/tty* +.SH "SEE ALSO" +.BR chvt (1), +.BR deallocvt (1), +.BR loadkeys (1), +.BR mknod (1), +.BR openvt (1), +.BR console_codes (4), +.BR console_ioctl (4), +.BR tty (4), +.BR ttys (4), +.BR charsets (7), +.BR getty (8), +.BR init (8), +.BR mapscrn (8), +.BR resizecons (8), +.BR setfont (8) diff --git a/man4/console_codes.4 b/man4/console_codes.4 new file mode 100644 index 000000000..2df2cc0ea --- /dev/null +++ b/man4/console_codes.4 @@ -0,0 +1,526 @@ +'\" t +.\" Copyright (c) 1996 Andries Brouwer , Mon Oct 31 22:13:04 1996 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" This is combined from many sources. +.\" For Linux, the definitive source is of course console.c. +.\" About vt100-like escape sequences in general there are +.\" the ISO 6429 and ISO 2022 norms, the descriptions of +.\" an actual vt100, and the xterm docs (ctlseqs.ms). +.\" Substantial portions of this text are derived from a write-up +.\" by Eric S. Raymond . +.\" +.\" Tiny correction, aeb, 961107. +.\" +.TH CONSOLE_CODES 4 1996-10-31 "Linux" "Linux Programmer's Manual" +.SH NAME +console_codes \- Linux console escape and control sequences +.SH DESCRIPTION +The Linux console implements a large subset of the VT102 and ECMA-48/ISO +6429/ANSI X3.64 terminal controls, plus certain private-mode sequences +for changing the color palette, character-set mapping, etc. +In the tabular descriptions below, the second column gives ECMA-48 or DEC +mnemonics (the latter if prefixed with DEC) for the given function. +Sequences without a mnemonic are neither ECMA-48 nor VT102. +.LP +After all the normal output processing has been done, and a +stream of characters arrives at the console driver for actual +printing, the first thing that happens is a translation from +the code used for processing to the code used for printing. +.LP +If the console is in UTF-8 mode, then the incoming bytes are +first assembled into 16-bit Unicode codes. Otherwise +each byte is transformed according to the current mapping table +(which translates it to a Unicode value). See the CHARACTER SETS +section below for discussion. +.LP +In the normal case, the Unicode value is converted to a font index, +and this is stored in video memory, so that the corresponding glyph +(as found in video ROM) appears on the screen. +Note that the use of Unicode (and the design of the PC hardware) +allows us to use 512 different glyphs simultaneously. +.LP +If the current Unicode value is a control character, or we are +currently processing an escape sequence, the value will treated +specially. Instead of being turned into a font index and rendered as +a glyph, it may trigger cursor movement or other control functions. +See the LINUX CONSOLE CONTROLS section below for discussion. +.LP +It is generally not good practice to hard-wire terminal controls into +programs. Linux supports a +.BR terminfo (5) +database of terminal capabilities. +Rather than emitting console escape sequences by hand, you will almost +always want to use a terminfo-aware screen library or utility such as +.BR ncurses (3), +.BR tput (1), +or +.BR reset (1). + +.SH "LINUX CONSOLE CONTROLS" + +This section describes all the control characters and escape sequences +that invoke special functions (i.e. anything other than writing a +glyph at the current cursor location) on the Linux console. +.SS "Control characters" +A character is a control character if (before transformation +according to the mapping table) it has one of the 14 codes +00 (NUL), 07 (BEL), 08 (BS), 09 (HT), 0a (LF), 0b (VT), +0c (FF), 0d (CR), 0e (SO), 0f (SI), 18 (CAN), 1a (SUB), +1b (ESC), 7f (DEL). +One can set a `display control characters' mode (see below), +and allow 07, 09, 0b, 18, 1a, 7f to be displayed as glyphs. +On the other hand, in UTF-8 mode all codes 00-1f are regarded +as control characters, regardless of any `display control characters' +mode. + +If we have a control character, it is acted upon immediately +and then discarded (even in the middle of an escape sequence) +and the escape sequence continues with the next character. +(However, ESC starts a new escape sequence, possibly aborting a previous +unfinished one, and CAN and SUB abort any escape sequence.) +The recognized control characters are BEL, BS, HT, LF, VT, FF, +CR, SO, SI, CAN, SUB, ESC, DEL, CSI. They do what one would expect: +.HP +BEL (0x07, ^G) beeps; +.HP +BS (0x08, ^H) backspaces one column +(but not past the beginning of the line); +.HP +HT (0x09, ^I) goes to the next tab stop or to the end of the line +if there is no earlier tab stop; +.HP +LF (0x0A, ^J), VT (0x0B, ^K) and FF (0x0C, ^L) all give a linefeed; +.HP +CR (0x0D, ^M) gives a carriage return; +.HP +SO (0x0E, ^N) activates the G1 character set, +and if LF/NL (new line mode) is set also a carriage return; +.HP +SI (0x0F, ^O) activates the G0 character set; +.HP +CAN (0x18, ^X) and SUB (0x1A, ^Z) interrupt escape sequences; +.HP +ESC (0x1B, ^[) starts an escape sequence; +.HP +DEL (0x7F) is ignored; +.HP +CSI (0x9B) is equivalent to ESC [. +.\" .LP +.SS "ESC- but not CSI-sequences" +.TS +l l l. +ESC c RIS Reset. +ESC D IND Linefeed. +ESC E NEL Newline. +ESC H HTS Set tab stop at current column. +ESC M RI Reverse linefeed. +ESC Z DECID DEC private identification. The kernel + returns the string ESC [ ? 6 c, claiming + that it is a VT102. +ESC 7 DECSC Save current state (cursor coordinates, + attributes, character sets pointed at by G0, G1). +ESC 8 DECRC Restore state most recently saved by ESC 7. +ESC [ CSI Control sequence introducer +ESC % Start sequence selecting character set +ESC % @ \0\0\0Select default (ISO 646 / ISO 8859-1) +ESC % G \0\0\0Select UTF-8 +ESC % 8 \0\0\0Select UTF-8 (obsolete) +ESC # 8 DECALN DEC screen alignment test - fill screen with E's. +ESC ( Start sequence defining G0 character set +ESC ( B \0\0\0Select default (ISO 8859-1 mapping) +ESC ( 0 \0\0\0Select vt100 graphics mapping +ESC ( U \0\0\0Select null mapping - straight to character ROM +ESC ( K \0\0\0Select user mapping - the map that is loaded by + \0\0\0the utility \fBmapscrn\fP(8). +ESC ) Start sequence defining G1 + (followed by one of B, 0, U, K, as above). +ESC > DECPNM Set numeric keypad mode +ESC = DECPAM Set application keypad mode +ESC ] OSC (Should be: Operating system command) + ESC ] P \fInrrggbb\fP: set palette, with parameter + given in 7 hexadecimal digits after the final P :-(. + Here \fIn\fP is the color (0-15), and \fIrrggbb\fP indicates + the red/green/blue values (0-255). + ESC ] R: reset palette +.TE +.SS "ECMA-48 CSI sequences" + +CSI (or ESC [) is followed by a sequence of parameters, +at most NPAR (16), that are decimal numbers separated by +semicolons. An empty or absent parameter is taken to be 0. +The sequence of parameters may be preceded by a single question mark. + +However, after CSI [ (or ESC [ [) a single character is read +and this entire sequence is ignored. (The idea is to ignore +an echoed function key.) + +The action of a CSI sequence is determined by its final character. + +.TS +l l l. +@ ICH Insert the indicated # of blank characters. +A CUU Move cursor up the indicated # of rows. +B CUD Move cursor down the indicated # of rows. +C CUF Move cursor right the indicated # of columns. +D CUB Move cursor left the indicated # of columns. +E CNL Move cursor down the indicated # of rows, to column 1. +F CPL Move cursor up the indicated # of rows, to column 1. +G CHA Move cursor to indicated column in current row. +H CUP Move cursor to the indicated row, column (origin at 1,1). +J ED Erase display (default: from cursor to end of display). + ESC [ 1 J: erase from start to cursor. + ESC [ 2 J: erase whole display. +K EL Erase line (default: from cursor to end of line). + ESC [ 1 K: erase from start of line to cursor. + ESC [ 2 K: erase whole line. +L IL Insert the indicated # of blank lines. +M DL Delete the indicated # of lines. +P DCH Delete the indicated # of characters on the current line. +X ECH Erase the indicated # of characters on the current line. +a HPR Move cursor right the indicated # of columns. +c DA Answer ESC [ ? 6 c: `I am a VT102'. +d VPA Move cursor to the indicated row, current column. +e VPR Move cursor down the indicated # of rows. +f HVP Move cursor to the indicated row, column. +g TBC Without parameter: clear tab stop at the current position. + ESC [ 3 g: delete all tab stops. +h SM Set Mode (see below). +l RM Reset Mode (see below). +m SGR Set attributes (see below). +n DSR Status report (see below). +q DECLL Set keyboard LEDs. + ESC [ 0 q: clear all LEDs + ESC [ 1 q: set Scroll Lock LED + ESC [ 2 q: set Num Lock LED + ESC [ 3 q: set Caps Lock LED +r DECSTBM Set scrolling region; parameters are top and bottom row. +s ? Save cursor location. +u ? Restore cursor location. +` HPA Move cursor to indicated column in current row. +.TE +.SS ECMA-48 Set Graphics Rendition + +The ECMA-48 SGR sequence ESC [ m sets display attributes. +Several attributes can be set in the same sequence. +.LP +.TS +l l. +par result +0 reset all attributes to their defaults +1 set bold +2 set half-bright (simulated with color on a color display) +4 set underscore (simulated with color on a color display) + (the colors used to simulate dim or underline are set + using ESC ] ...) +5 set blink +7 set reverse video +10 reset selected mapping, display control flag, + and toggle meta flag. +11 select null mapping, set display control flag, + reset toggle meta flag. +12 select null mapping, set display control flag, + set toggle meta flag. (The toggle meta flag + causes the high bit of a byte to be toggled + before the mapping table translation is done.) +21 set normal intensity (this is not compatible with ECMA-48) +22 set normal intensity +24 underline off +25 blink off +27 reverse video off +30 set black foreground +31 set red foreground +32 set green foreground +33 set brown foreground +34 set blue foreground +35 set magenta foreground +36 set cyan foreground +37 set white foreground +38 set underscore on, set default foreground color +39 set underscore off, set default foreground color +40 set black background +41 set red background +42 set green background +43 set brown background +44 set blue background +45 set magenta background +46 set cyan background +47 set white background +49 set default background color +.TE +.SS ECMA-48 Mode Switches +.TP +ESC [ 3 h +DECCRM (default off): Display control chars. +.TP +ESC [ 4 h +DECIM (default off): Set insert mode. +.TP +ESC [ 20 h +LF/NL (default off): Automatically follow echo of LF, VT or FF with CR. +.\" +.SS ECMA-48 Status Report Commands +.\" +.TP +ESC [ 5 n +Device status report (DSR): Answer is ESC [ 0 n (Terminal OK). +.TP +ESC [ 6 n +Cursor position report (CPR): Answer is ESC [ \fIy\fP ; \fIx\fP R, +where \fIx,y\fP is the cursor location. +.\" +.SS DEC Private Mode (DECSET/DECRST) sequences. +.\" +These are not described in ECMA-48. We list the Set Mode sequences; +the Reset Mode sequences are obtained by replacing the final `h' +by `l'. +.TP +ESC [ ? 1 h +DECCKM (default off): When set, the cursor keys send an ESC O prefix, +rather than ESC [. +.TP +ESC [ ? 3 h +DECCOLM (default off = 80 columns): 80/132 col mode switch. The +driver sources note that this alone does not suffice; some user-mode +utility such as +.BR resizecons (8) +has to change the hardware registers on the console video card. +.TP +ESC [ ? 5 h +DECSCNM (default off): Set reverse-video mode. +.TP +ESC [ ? 6 h +DECOM (default off): When set, cursor addressing is relative to +the upper left corner of the scrolling region. +.TP +ESC [ ? 7 h +DECAWM (default on): Set autowrap on. In this mode, a graphic +character emitted after column 80 (or column 132 of DECCOLM is on) +forces a wrap to the beginning of the following line first. +.TP +ESC [ ? 8 h +DECARM (default on): Set keyboard autorepreat on. +.TP +ESC [ ? 9 h +X10 Mouse Reporting (default off): Set reporting mode to 1 (or reset to +0) \- see below. +.TP +ESC [ ? 25 h +DECCM (default on): Make cursor visible. +.TP +ESC [ ? 1000 h +X11 Mouse Reporting (default off): Set reporting mode to 2 (or reset +to 0) \- see below. +.\" +.SS Linux Console Private CSI Sequences +.\" +The following sequences are neither ECMA-48 nor native VT102. They +are native to the Linux console driver. Colors are in SGR parameters: +0 = black, 1 = red, 2 = green, 3 = brown, 4 = blue, 5 = magenta, 6 = +cyan, 7 = white. + +.TS +l l. +ESC [ 1 ; \fIn\fP ] Set color \fIn\fP as the underline color +ESC [ 2 ; \fIn\fP ] Set color \fIn\fP as the dim color +ESC [ 8 ] Make the current color pair the default attributes. +ESC [ 9 ; \fIn\fP ] Set screen blank timeout to \fIn\fP minutes. +ESC [ 10 ; \fIn\fP ] Set bell frequency in Hz. +ESC [ 11 ; \fIn\fP ] Set bell duration in msec. +ESC [ 12 ; \fIn\fP ] Bring specified console to the front. +ESC [ 13 ] Unblank the screen. +ESC [ 14 ; \fIn\fP ] Set the VESA powerdown interval in minutes. +.TE + +.SH "CHARACTER SETS" + +The kernel knows about 4 translations of bytes into console-screen symbols. +The four tables are: a) Latin1 -> PC, b) VT100 graphics -> PC, c) PC -> PC, +d) user-defined. + +There are two character sets, called G0 and G1, and one of them +is the current character set. (Initially G0.) +Typing ^N causes G1 to become current, ^O causes G0 to become current. + +These variables G0 and G1 point at a translation table, and can be changed +by the user. Initially they point at tables a) and b), respectively. +The sequences ESC ( B and ESC ( 0 and ESC ( U and ESC ( K cause G0 to point +at translation table a), b), c) and d), respectively. +The sequences ESC ) B and ESC ) 0 and ESC ) U and ESC ) K cause G1 to point +at translation table a), b), c) and d), respectively. + +The sequence ESC c causes a terminal reset, which is what you want if the +screen is all garbled. The oft-advised "echo ^V^O" will only make G0 current, +but there is no guarantee that G0 points at table a). +In some distributions there is a program +.BR reset (1) +that just does "echo ^[c". +If your terminfo entry for the console is correct (and has an entry rs1=\\Ec), +then "tput reset" will also work. + +The user-defined mapping table can be set using +.BR mapscrn (8). +The result of the mapping is that if a symbol c is printed, the symbol +s = map[c] is sent to the video memory. The bitmap that corresponds to +s is found in the character ROM, and can be changed using +.BR setfont(8). + +.SH "MOUSE TRACKING" + +The mouse tracking facility is intended to return xterm-compatible +mouse status reports. Because the console driver has no way to know +the device or type of the mouse, these reports are returned in the +console input stream only when the virtual terminal driver receives +a mouse update ioctl. These ioctls must be generated by a mouse-aware +user-mode application such as the \fBgpm(8)\fR daemon. + +Parameters for all mouse tracking escape sequences generated by +\fIxterm\fP encode numeric parameters in a single character as +\fIvalue\fP+040. For example, `!' is 1. The screen +coordinate system is 1-based. + +The X10 compatibility mode sends an escape sequence on button press +encoding the location and the mouse button pressed. +It is enabled by sending ESC [ ? 9 h and disabled with ESC [ ? 9 l. +On button press, \fIxterm\fP sends +ESC [ M \fIbxy\fP (6 characters). Here \fIb\fP is button\-1, +and \fIx\fP and \fIy\fP are the x and y coordinates of the mouse +when the button was pressed. +This is the same code the kernel also produces. + +Normal tracking mode (not implemented in Linux 2.0.24) sends an escape +sequence on both button press and release. Modifier information is +also sent. It is enabled by sending ESC [ ? 1000 h and disabled with +ESC [ 1000 l. On button press or release, \fIxterm\fP sends ESC [ M +\fIbxy\fP. The low two bits of \fIb\fP encode button information: +0=MB1 pressed, 1=MB2 pressed, 2=MB3 pressed, 3=release. The upper +bits encode what modifiers were down when the button was pressed and +are added together: 4=Shift, 8=Meta, 16=Control. Again \fIx\fP and +\fIy\fP are the x and y coordinates of the mouse event. The upper +left corner is (1,1). + +.SH "COMPARISONS WITH OTHER TERMINALS" + +Many different terminal types are described, like the Linux console, +as being `VT100-compatible'. Here we discuss differences vbetween the +Linux console an the two most important others, the DEC VT102 and +.BR xterm (1). +.\" +.SS Control-character handling +The vt102 also recognized the following control characters: +.HP +NUL (0x00) was ignored; +.HP +ENQ (0x05) triggered an answerback message; +.HP +DC1 (0x11, ^Q, XON) resumed transmission; +.HP +DC3 (0x13, ^S, XOFF) caused vt100 to ignore (and stop transmitting) +all codes except XOFF and XON. +.LP +VT100-like DC1/DC3 processing may be enabled by the tty driver. +.LP +The +.I xterm +program (in vt100 mode) recognizes the control characters +BEL, BS, HT, LF, VT, FF, CR, SO, SI, ESC. +.\" +.SS Escape sequences +VT100 console sequences not implemented on the Linux console: +.LP +.TS +l l l. +ESC N SS2 Single shift 2. (Select G2 character set for the next + character only.) +ESC O SS3 Single shift 3. (Select G3 character set for the next + character only.) +ESC P DCS Device control string (ended by ESC \e) +ESC X SOS Start of string. +ESC ^ PM Privacy message (ended by ESC \e) +ESC \e ST String terminator +ESC * ... Designate G2 character set +ESC + ... Designate G3 character set +.TE + +The program +.I xterm +(in vt100 mode) recognizes ESC c, ESC # 8, ESC >, ESC =, +ESC D, ESC E, ESC H, ESC M, ESC N, ESC O, ESC P ... ESC \, +ESC Z (it answers ESC [ ? 1 ; 2 c, `I am a vt100 with advanced video option') +and ESC ^ ... ESC \ with the same meanings as indicated above. +It accepts ESC (, ESC ), ESC *, ESC + followed by 0, A, B for +the DEC special character and line drawing set, UK, and USASCII, +respectively. +It accepts ESC ] for the setting of certain resources: +.LP +.TS +l l. +ESC ] 0 ; txt BEL Set icon name and window title to txt. +ESC ] 1 ; txt BEL Set icon name to txt. +ESC ] 2 ; txt BEL Set window title to txt. +ESC ] 4 6 ; name BEL Change log file to name (normally disabled + by a compile-time option) +ESC ] 5 0 ; fn BEL Set font to fn. +.TE + +It recognizes the following with slightly modified meaning: +.LP +.TS +l l l. +ESC 7 DECSC Save cursor +ESC 8 DECRC Restore cursor +.TE + +It also recognizes +.LP +.TS +l l l. +ESC F Cursor to lower left corner of screen (if enabled by + the hpLowerleftBugCompat resource) +ESC l Memory lock (per HP terminals). + Locks memory above the cursor. +ESC m Memory unlock (per HP terminals). +ESC n LS2 Invoke the G2 character set. +ESC o LS3 Invoke the G3 character set. +ESC | LS3R Invoke the G3 character set as GR. + Has no visible effect in xterm. +ESC } LS2R Invoke the G2 character set as GR. + Has no visible effect in xterm. +ESC ~ LS1R Invoke the G1 character set as GR. + Has no visible effect in xterm. +.TE + +It does not recognize ESC % ... +.\" +.SS CSI Sequences +The +.I xterm +program (as of XFree86 3.1.2G) does not recognize the blink or invisible-mode +SGRs. Stock X11R6 versions do not recognize the color-setting SGRs. +All other ECMA-48 CSI sequences recognized by Linux are also recognized by +.IR xterm , +and vice-versa. + +The +.I xterm +program will recognize all of the DEC Private Mode sequences listed +above, but none of the Linux private-mode sequences. For discussion +of +.IR xterm 's +own private-mode sequences, refer to the +.I Xterm Control Sequences +document by Edward Moy and Stephen Gildea, available with the X +distribution. + +.SH BUGS + +In 2.0.23, CSI is broken, and NUL is not ignored inside escape sequences. + +.SH "SEE ALSO" +.BR console (4), +.BR console_ioctl (4), +.BR charsets (7) diff --git a/man4/console_ioctl.4 b/man4/console_ioctl.4 new file mode 100644 index 000000000..640343e5e --- /dev/null +++ b/man4/console_ioctl.4 @@ -0,0 +1,570 @@ +.\" Copyright (c) 1995 Jim Van Zandt and aeb +.\" Sun Feb 26 11:46:23 MET 1995 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified, Sun Feb 26 15:04:20 1995, faith@cs.unc.edu +.\" Modified, Thu Apr 20 22:08:17 1995, jrv@vanzandt.mv.com +.\" Modified, Mon Sep 18 22:32:47 1995, hpa@storm.net (H. Peter Anvin) +.\" " +.TH CONSOLE_IOCTLS 4 1995-09-18 "Linux" "Linux Programmer's Manual" +.SH NAME +console ioctl \- ioctl's for console terminal and virtual consoles +.SH DESCRIPTION +The following Linux-peculiar \fBioctl()\fP requests are supported. +Each requires a third argument, assumed here to be \fIargp\fP. +.IP \fBKDGETLED\fP +Get state of LEDs. \fIargp\fP points to a long int. The lower three bits +of \fI*argp\fP are set to the state of the LEDs, as follows: + + LED_CAP 0x04 caps lock led + LEC_NUM 0x02 num lock led + LED_SCR 0x01 scroll lock led + +.IP \fBKDSETLED\fP +Set the LEDs. The LEDs are set to correspond to the lower three bits of +\fIargp\fP. However, if a higher order bit is set, +the LEDs revert to normal: displaying the state of the +keyboard functions of caps lock, num lock, and scroll lock. +.LP +Before 1.1.54, the LEDs just reflected the state of the corresponding +keyboard flags, and KDGETLED/KDSETLED would also change the keyboard +flags. Since 1.1.54 the leds can be made to display arbitrary +information, but by default they display the keyboard flags. +The following two ioctl's are used to access the keyboard flags. + +.IP \fBKDGKBLED\fP +Get keyboard flags CapsLock, NumLock, ScrollLock (not lights). +\fIargp\fP points to a char which is set to the flag state. +The low order three bits (mask 0x7) get the current flag state, +and the low order bits of the next nibble (mask 0x70) get +the default flag state. (Since 1.1.54.) + +.IP \fBKDSKBLED\fP +Set keyboard flags CapsLock, NumLock, ScrollLock (not lights). +\fIargp\fP has the desired flag state. +The low order three bits (mask 0x7) have the flag state, +and the low order bits of the next nibble (mask 0x70) have +the default flag state. (Since 1.1.54.) + +.IP \fBKDGKBTYPE\fP +Get keyboard type. This returns the value KB_101, defined as 0x02. + +.IP \fBKDADDIO\fP +Add I/O port as valid. Equivalent to ioperm(arg,1,1). + +.IP \fBKDDELIO\fP +Delete I/O port as valid. Equivalent to ioperm(arg,1,0). + +.IP \fBKDENABIO\fP +Enable I/O to video board. Equivalent to ioperm(0x3b4, 0x3df-0x3b4+1, 1). + +.IP \fBKDDISABIO\fP +Disable I/O to video board. Equivalent to ioperm(0x3b4, 0x3df-0x3b4+1, 0). + +.IP \fBKDSETMODE\fP +Set text/graphics mode. \fIargp\fP is one of these: + + KD_TEXT 0x00 + KD_GRAPHICS 0x01 + +.IP \fBKDGETMODE\fP +Get text/graphics mode. \fIargp\fP points to a long which is set to one +of the above values. + +.IP \fBKDMKTONE\fP +Generate tone of specified length. +The lower 16 bits of \fIargp\fP specify the period in clock cycles, +and the upper 16 bits give the duration in msec. +If the duration is zero, the sound is turned off. +Control returns immediately. +For example, \fIargp\fP = (125<<16) + 0x637 would specify +the beep normally associated with a ctrl-G. +(Thus since 0.99pl1; broken in 2.1.49-50.) + +.IP \fBKIOCSOUND\fP +Start or stop sound generation. The lower 16 bits of +\fIargp\fP specify the period in clock cycles +(that is, \fIargp\fP = 1193180/frequency). +\fIargp\fP = 0 turns sound off. +In either case, control returns immediately. + +.IP \fBGIO_CMAP\fP +Get the current default colour map from kernel. \fIargp\fP points to +a 48-byte array. (Since 1.3.3.) + +.IP \fBPIO_CMAP\fP +Change the default text-mode colour map. \fIargp\fP points to a +48-byte array which contains, in order, the Red, Green, and Blue +values for the 16 available screen colours: 0 is off, and 255 is full +intensity. The default colours are, in order: black, dark red, dark +green, brown, dark blue, dark purple, dark cyan, light grey, dark +grey, bright red, bright green, yellow, bright blue, bright purple, +bright cyan and white. (Since 1.3.3.) + +.IP \fBGIO_FONT\fP +Gets 256-character screen font in expanded form. \fIargp\fP points to +an 8192 byte array. Fails with error code \fBEINVAL\fP if the +currently loaded font is a 512-character font, or if the console is +not in text mode. + +.IP \fBGIO_FONTX\fP +Gets screen font and associated information. \fIargp\fP points to a +struct consolefontdesc (see \fBPIO_FONTX\fP). On call, the +\fIcharcount\fP field should be set to the maximum number of +characters that would fit in the buffer pointed to by \fIchardata\fP. +On return, the \fIcharcount\fP and \fIcharheight\fP are filled with +the respective data for the currently loaded font, and the +\fIchardata\fP array contains the font data if the initial value of +\fIcharcount\fP indicated enough space was available; otherwise the +buffer is untouched and \fIerrno\fP is set to \fBENOMEM\fP. (Since +1.3.1.) + +.IP \fBPIO_FONT\fP +Sets 256-character screen font. Load font into the EGA/VGA character +generator. \fIargp\fP points to a 8192 byte map, with 32 bytes per +character. Only first \fIN\fP of them are used for an 8x\fIN\fP font +(0 < \fIN\fP <= 32). This call also invalidates the Unicode mapping. + +.IP \fBPIO_FONTX\fP +Sets screen font and associated rendering information. \fIargp\fP +points to a + +.nf +struct consolefontdesc { + u_short \fIcharcount\fP; /* characters in font (256 or 512) */ + u_short \fIcharheight\fP; /* scan lines per character (1-32) */ + char *\fIchardata\fP; /* font data in expanded form */ +}; +.fi + +If necessary, the screen will be appropriately resized, and +\fBSIGWINCH\fP sent to the appropriate processes. This call also +invalidates the Unicode mapping. (Since 1.3.1.) + +.IP \fBPIO_FONTRESET\fP +Resets the screen font, size and Unicode mapping to the bootup +defaults. \fIargp\fP is unused, but should be set to \fBNULL\fP to +ensure compatibility with future versions of Linux. (Since 1.3.28.) + +.IP \fBGIO_SCRNMAP\fP +Get screen mapping from kernel. \fIargp\fP points to an area of size +E_TABSZ, which is loaded with the font positions used to display each +character. This call is likely to return useless information if the +currently loaded font is more than 256 characters. + +.IP \fBGIO_UNISCRNMAP\fP +Get full Unicode screen mapping from kernel. \fIargp\fP points to an +area of size E_TABSZ*sizeof(unsigned short), which is loaded with the +Unicodes each character represent. A special set of Unicodes, +starting at U+F000, are used to represent ``direct to font'' mappings. +(Since 1.3.1.) + +.IP \fBPIO_SCRNMAP\fP +Loads the ``user definable'' (fourth) table in the kernel which maps +bytes into console screen symbols. \fIargp\fP points to an area of +size E_TABSZ. + +.IP \fBPIO_UNISCRNMAP\fP +Loads the ``user definable'' (fourth) table in the kernel which maps +bytes into Unicodes, which are then translated into screen symbols +according to the currently loaded Unicode-to-font map. Special +Unicodes starting at U+F000 can be used to map directly to the font +symbols. (Since 1.3.1.) + +.IP \fBGIO_UNIMAP\fP +Get Unicode-to-font mapping from kernel. \fIargp\fP points to a + +.nf +struct unimapdesc { + u_short \fIentry_ct\fP; + struct unipair *\fIentries\fP; +}; +.fi + +where \fIentries\fP points to an array of + +.nf +struct unipair { + u_short \fIunicode\fP; + u_short \fIfontpos\fP; +}; +.fi + +(Since 1.1.92.) + +.IP \fBPIO_UNIMAP\fP +Put unicode-to-font mapping in kernel. \fIargp\fP points to a +struct unimapdesc. (Since 1.1.92) + +.IP \fBPIO_UNIMAPCLR\fP +Clear table, possibly advise hash algorithm. \fIargp\fP points to a + +.nf +struct unimapinit { + u_short \fIadvised_hashsize\fP; /* 0 if no opinion */ + u_short \fIadvised_hashstep\fP; /* 0 if no opinion */ + u_short \fIadvised_hashlevel\fP; /* 0 if no opinion */ +}; +.fi + +(Since 1.1.92.) + +.IP \fBKDGKBMODE\fP +Gets current keyboard mode. \fIargp\fP points to a long which is set to one +of these: + + K_RAW 0x00 + K_XLATE 0x01 + K_MEDIUMRAW 0x02 + K_UNICODE 0x03 + +.IP \fBKDSKBMODE\fP +Sets current keyboard mode. +\fIargp\fP is a long equal to one of the above values. + +.IP \fBKDGKBMETA\fP +Gets meta key handling mode. \fIargp\fP points to a long which is +set to one of these: + + K_METABIT 0x03 set high order bit + K_ESCPREFIX 0x04 escape prefix + +.IP \fBKDSKBMETA\fP +Sets meta key handling mode. +\fIargp\fP is a long equal to one of the above values. + +.IP \fBKDGKBENT\fP +Gets one entry in key translation table (keycode to action code). +\fIargp\fP points to a + +.nf +struct kbentry { + u_char \fIkb_table\fP; + u_char \fIkb_index\fP; + u_short \fIkb_value\fP; +}; +.fi + +with the first two members filled in: +\fIkb_table\fP selects the key table (0 <= \fIkb_table\fP < MAX_NR_KEYMAPS), +and \fIkb_index\fP is the keycode (0 <= \fIkb_index\fP < NR_KEYS). +\fIkb_value\fP is set to the corresponding action code, +or K_HOLE if there is no such key, +or K_NOSUCHMAP if \fIkb_table\fP is invalid. + +.IP \fBKDSKBENT\fP +Sets one entry in translation table. \fIargp\fP points to a struct kbentry. + +.IP \fBKDGKBSENT\fP +Gets one function key string. \fIargp\fP points to a + +.nf +struct kbsentry { + u_char \fIkb_func\fP; + u_char \fIkb_string\fP[512]; +}; +.fi + +\fIkb_string\fP is set to the (NULL terminated) string corresponding to +the \fIkb_func\fPth function key action code. + +.IP \fBKDSKBSENT\fP +Sets one function key string entry. \fIargp\fP points to a struct kbsentry. + +.IP \fBKDGKBDIACR\fP +Read kernel accent table. \fIargp\fP points to a + +.nf +struct kbdiacrs { + unsigned int \fIkb_cnt\fP; + struct kbdiacr \fIkbdiacr\fP[256]; +}; +.fi + +where \fIkb_cnt\fP is the number of entries in the array, each of which +is a + +struct kbdiacr { u_char \fIdiacr\fP, \fIbase\fP, \fIresult\fP; +}; + +.IP \fBKDGETKEYCODE\fP +Read kernel keycode table entry (scan code to keycode). +\fIargp\fP points to a + +.nf +struct kbkeycode { unsigned int \fIscancode\fP, \fIkeycode\fP; }; +.fi + +\fIkeycode\fP is set to correspond to the given \fIscancode\fP. +(89 <= \fIscancode\fP <= 255 only. +For 1 <= \fIscancode\fP <= 88, \fIkeycode\fP==\fIscancode\fP.) +(Since 1.1.63.) + +.IP \fBKDSETKEYCODE\fP +Write kernel keycode table entry. \fIargp\fP points to struct kbkeycode. +(Since 1.1.63.) + +.IP \fBKDSIGACCEPT\fP +The calling process indicates its willingness to accept the signal +\fIargp\fP when it is generated by pressing an appropriate key combination. +(1 <= \fIargp\fP <= NSIG). +(See spawn_console() in linux/drivers/char/keyboard.c.) + +.IP \fBVT_OPENQRY\fP +Returns the first available (non-opened) console. +\fIargp\fP points to an int which is set to the +number of the vt (1 <= \fI*argp\fP <= MAX_NR_CONSOLES). + +.IP \fBVT_GETMODE\fP +Get mode of active vt. \fIargp\fP points to a + +.nf +struct vt_mode { + char \fImode\fP; /* vt mode */ + char \fIwaitv\fP; /* if set, hang on writes if not active */ + short \fIrelsig\fP; /* signal to raise on release req */ + short \fIacqsig\fP; /* signal to raise on acquisition */ + short \fIfrsig\fP; /* unused (set to 0) */ +}; +.fi + +\&...which is set to the mode of the active vt. +\fImode\fP is set to one of these values: + + VT_AUTO auto vt switching + VT_PROCESS process controls switching + VT_ACKACQ acknowledge switch + +.IP \fBVT_SETMODE\fP +Set mode of active vt. \fIargp\fP points to a struct vt_mode. + +.IP \fBVT_GETSTATE\fP +Get global vt state info. \fIargp\fP points to a + +.nf +struct vt_stat { + ushort \fIv_active\fP; /* active vt */ + ushort \fIv_signal\fP; /* signal to send */ + ushort \fIv_state\fP; /* vt bitmask */ +}; +.fi + +For each vt in use, the corresponding bit in the \fIv_state\fP member is set. +(Kernels 1.0 through 1.1.92.) + +.IP \fBVT_RELDISP\fP +Release a display. + +.IP \fBVT_ACTIVATE\fP +Switch to vt \fIargp\fP (1 <= \fIargp\fP <= MAX_NR_CONSOLES). + +.IP \fBVT_WAITACTIVE\fP +Wait until vt \fIargp\fP has been activated. + +.IP \fBVT_DISALLOCATE\fP +Deallocate the memory associated with vt \fIargp\fP. +(Since 1.1.54.) + +.IP \fBVT_RESIZE\fP +Set the kernel's idea of screensize. \fIargp\fP points to a + +.nf +struct vt_sizes { + ushort \fIv_rows\fP; /* # rows */ + ushort \fIv_cols\fP; /* # columns */ + ushort \fIv_scrollsize\fP; /* no longer used */ +}; +.fi + +Note that this does not change the videomode. +See resizecons(8). (Since 1.1.54.) + +.IP \fBVT_RESIZEX\fP +Set the kernel's idea of various screen parameters. \fIargp\fP +points to a + +.nf +struct vt_consize { + ushort \fIv_rows\fP; /* number of rows */ + ushort \fIv_cols\fP; /* number of columns */ + ushort \fIv_vlin\fP; /* number of pixel rows on screen */ + ushort \fIv_clin\fP; /* number of pixel rows per character */ + ushort \fIv_vcol\fP; /* number of pixel columns on screen */ + ushort \fIv_ccol\fP; /* number of pixel columns per character */ +}; +.fi + +Any parameter may be set to zero, indicating ``no change'', but if +multiple parameters are set, they must be self-consistent. Note that +this does not change the videomode. See resizecons(8). (Since 1.3.3.) + +.PP +The action of the following ioctls depends on the first byte in the struct +pointed to by \fIargp\fP, referred to here as the \fIsubcode\fP. +These are legal only for the superuser or the owner of the current tty. +.IP "\fBTIOCLINUX, subcode=0\fP" +Dump the screen. +Disappeared in 1.1.92. (With kernel 1.1.92 or later, read from +/dev/vcsN or /dev/vcsaN instead.) + +.IP "\fBTIOCLINUX, subcode=1\fP" +Get task information. Disappeared in 1.1.92. + +.IP "\fBTIOCLINUX, subcode=2\fP" +Set selection. +\fIargp\fP points to a + + struct {char \fIsubcode\fP; + short \fIxs\fP, \fIys\fP, \fIxe\fP, \fIye\fP; + short \fIsel_mode\fP; + } + +\fIxs\fP and \fIys\fP are the starting column and row. +\fIxe\fP and \fIye\fP are the ending +column and row. (Upper left corner is row=column=1.) +\fIsel_mode\fP is 0 for character-by-character selection, +1 for word-by-word selection, +or 2 for line-by-line selection. +The indicated screen characters are highlighted and saved +in the static array sel_buffer in devices/char/console.c. + +.IP "\fBTIOCLINUX, subcode=3\fP" +Paste selection. +The characters in the selection buffer are +written to \fIfd\fP. + +.IP "\fBTIOCLINUX, subcode=4\fP" +Unblank the screen. + +.IP "\fBTIOCLINUX, subcode=5\fP" +Sets contents of a 256-bit look up table defining characters in a "word", +for word-by-word selection. (Since 1.1.32.) + +.IP "\fBTIOCLINUX, subcode=6\fP" +\fIargp\fP points to a char which is set to the value of the kernel +variable \fIshift_state\fP. (Since 1.1.32.) + +.IP "\fBTIOCLINUX, subcode=7\fP" +\fIargp\fP points to a char which is set to the value of the kernel +variable \fIreport_mouse\fP. (Since 1.1.33.) + +.IP "\fBTIOCLINUX, subcode=8\fP" +Dump screen width and height, cursor position, and all the +character-attribute pairs. +(Kernels 1.1.67 through 1.1.91 only. +With kernel 1.1.92 or later, read from /dev/vcsa* instead.) + +.IP "\fBTIOCLINUX, subcode=9\fP" +Restore screen width and height, cursor position, and all the +character-attribute pairs. +(Kernels 1.1.67 through 1.1.91 only. +With kernel 1.1.92 or later, write to /dev/vcsa* instead.) + +.IP "\fBTIOCLINUX, subcode=10\fP" +Handles the Power Saving +feature of the new generation of monitors. +VESA screen blanking mode is set to \fIargp\fP[1], which governs what +screen blanking does: + + \fI0\fP: Screen blanking is disabled. + + \fI1\fP: The current video adapter +register settings are saved, then the controller is programmed to turn off +the vertical synchronization pulses. This puts the monitor into "standby" mode. +If your monitor has an Off_Mode timer, then +it will eventually power down by itself. + + \fI2\fP: The current +settings are saved, then both the vertical and horizontal +synchronization pulses are turned off. +This puts the monitor into "off" mode. +If your monitor has no Off_Mode timer, +or if you want your monitor to power down immediately when the +blank_timer times out, then you choose this option. +(\fICaution:\fP Powering down frequently will damage the monitor.) + +(Since 1.1.76.) + +.SH "RETURN VALUE" +On success, 0 is returned. On error \-1 is returned, and \fIerrno\fP is set. +.SH ERRORS +\fIerrno\fP may take on these values: + +.TP +.B EBADF +The file descriptor is invalid. +.TP +.B +ENOTTY +The file descriptor is not associated with a character special device, +or the specified request does not apply to it. +.TP +.B EINVAL +The file descriptor or \fIargp\fP is invalid. +.TP +.B EPERM +Insufficient permission. +.SH WARNING +Do not regard this man page as documentation of the Linux console ioctl's. +This is provided for the curious only, as an alternative to reading the +source. Ioctl's are undocumented Linux internals, liable to be changed +without warning. (And indeed, this page more or less describes the +situation as of kernel version 1.1.94; there are many minor and not-so-minor +differences with earlier versions.) + +Very often, ioctl's are introduced for communication between the +kernel and one particular well-known program (fdisk, hdparm, setserial, +tunelp, loadkeys, selection, setfont, etc.), and their behavior will be +changed when required by this particular program. + +Programs using these ioctl's will not be portable to other versions +of Unix, will not work on older versions of Linux, and will not work +on future versions of Linux. + +Use POSIX functions. + +.SH "SEE ALSO" +.BR dumpkeys (1), +.BR kbd_mode (1), +.BR loadkeys (1), +.BR mknod (1), +.BR setleds (1), +.BR setmetamode (1), +.BR execve (2), +.BR fcntl (2), +.BR ioperm (2), +.BR termios (3), +.BR console (4), +.BR console_codes (4), +.BR mt (4), +.BR sd (4), +.BR tty (4), +.BR tty_ioctl (4), +.BR ttys (4), +.BR vcs (4), +.BR vcsa (4), +.BR charsets (7), +.BR mapscrn (8), +.BR resizecons (8), +.BR setfont (8), +.IR /usr/include/linux/kd.h , +.I /usr/include/linux/vt.h diff --git a/man4/dsp56k.4 b/man4/dsp56k.4 new file mode 100644 index 000000000..d0104a055 --- /dev/null +++ b/man4/dsp56k.4 @@ -0,0 +1,99 @@ +'\" t +.\" Copyright (c) 2000 lars brinkhoff +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified, Thu Jan 27 19:16:19 CET 2000, lars@nocrew.org +.\" +.TH DSP56K 4 2000-03-01 "Special files" "Linux Programmer's Manual" +.SH NAME +dsp56k \- DSP56001 interface device +.SH SYNOPSIS +.nf +#include +.sp +.BI "ssize_t read(int " fd ", void *" data ", size_t " length ); +.BI "ssize_t write(int " fd ", void *" data ", size_t " length ); +.BI "int ioctl(int " fd ", \s-1DSP56K_UPLOAD\s+1, struct dsp56k_upload *" program ); +.BI "int ioctl(int " fd ", \s-1DSP56K_SET_TX_WSIZE\s+1, int " wsize ); +.BI "int ioctl(int " fd ", \s-1DSP56K_SET_RX_WSIZE\s+1, int " wsize ); +.BI "int ioctl(int " fd ", \s-1DSP56K_HOST_FLAGS\s+1, struct dsp56k_host_flags *" flags ); +.BI "int ioctl(int " fd ", \s-1DSP56K_HOST_CMD\s+1, int " cmd ); +.fi +.SH CONFIGURATION +The dsp56k device is a character device with major number 55 and minor +number 0. +.SH DESCRIPTION +The Motorola DSP56001 is a fully programmable 24-bit digital signal +processor found in Atari Falcon030-compatible computers. The +\fBdsp56k\fP special file is used to control the DSP56001, and +to send and receive data using the bi-directional handshaked host +port. +.PP +To send a data stream to the signal processor, use write() to the +device, and read() to receive processed data. The data can be sent or +received in 8, 16, 24, or 32-bit quantities on the host side, but will +always be seen as 24-bit quantities in the DSP56001. +.PP +The following +.IR ioctl (2) +calls are used to control the +\fBdsp56k\fP device: +.IP \fBDSP56K_UPLOAD\fP +resets the DSP56001 and uploads a program. The third ioctl() argument +must be a pointer to a \fBstruct dsp56k_binary\fP with members +\fBbin\fP pointing to a DSP56001 binary program, and \fBlen\fP set to +the length of the program, counted in 24-bit words. +.IP \fBDSP56K_SET_TX_WSIZE\fP +sets the transmit word size. Allowed values are in the range 1 to 4, +and is the number of bytes that will be sent at a time to the +DSP56001. These data quantities will either be padded with zero +bytes, or truncated to fit the native 24-bit data format of the +DSP56001. +.IP \fBDSP56K_SET_RX_WSIZE\fP +sets the receive word size. Allowed values are in the range 1 to 4, +and is the number of bytes that will be received at a time from the +DSP56001. These data quantities will either truncated, or padded with +a zero byte to fit the native 24-bit data format of the DSP56001. +.IP \fBDSP56K_HOST_FLAGS\fP +read and write the host flags. The host flags are four +general-purpose bits that can be read by both the hosting computer and +the DSP56001. Bits 0 and 1 can be written by the host, and bits 2 and +3 can be written by the DSP56001. + +To access the host flags, the third ioctl() argument must be a pointer +to a \fBstruct dsp56k_host_flags\fP. If bit 0 or 1 is set in the +\fBdir\fP member, the corresponding bit in \fBout\fP will be written +to the host flags. The state of all host flags will be returned in +the lower four bits of the \fBstatus\fP member. +.IP \fBDSP56K_HOST_CMD\fP +sends a host command. Allowed values are in the range 0 to 31, and is a +user-defined command handled by the program running in the DSP56001. +.SH FILES +/dev/dsp56k +.SH AUTHORS +Fredrik Noring , lars brinkhoff , +Tomas Berndtsson . +.SH "SEE ALSO" +linux/include/asm-m68k/dsp56k.h, +linux/drivers/char/dsp56k.c, +http://dsp56k.nocrew.org/, +DSP56000/DSP56001 Digital Signal Processor User's Manual diff --git a/man4/epoll.4 b/man4/epoll.4 new file mode 100644 index 000000000..3357d9af2 --- /dev/null +++ b/man4/epoll.4 @@ -0,0 +1,370 @@ +.\" +.\" epoll by Davide Libenzi ( efficient event notification retrieval ) +.\" Copyright (C) 2003 Davide Libenzi +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program; if not, write to the Free Software +.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +.\" +.\" Davide Libenzi +.\" +.\" +.TH EPOLL 4 "2002-10-23" Linux "Linux Programmer's Manual" +.SH NAME +epoll \- I/O event notification facility +.SH SYNOPSIS +.B #include +.SH DESCRIPTION +.B epoll +is a variant of +.BR poll (2) +that can be used either as Edge or Level Triggered interface and scales +well to large numbers of watched fds. Three system calls are provided to +set up and control an +.B epoll +set: +.BR epoll_create (2), +.BR epoll_ctl (2), +.BR epoll_wait (2). + +An +.B epoll +set is connected to a file descriptor created by +.BR epoll_create (2). +Interest for certain file descriptors is then registered via +.BR epoll_ctl (2). +Finally, the actual wait is started by +.BR epoll_wait (2). + +.SH NOTES +The +.B epoll +event distribution interface is able to behave both as Edge Triggered +( ET ) and Level Triggered ( LT ). The difference between ET and LT +event distribution mechanism can be described as follows. Suppose that +this scenario happens : +.TP +.B 1 +The file descriptor that represents the read side of a pipe ( +.B RFD +) is added inside the +.B epoll +device. +.TP +.B 2 +Pipe writer writes 2Kb of data on the write side of the pipe. +.TP +.B 3 +A call to +.BR epoll_wait (2) +is done that will return +.B RFD +as ready file descriptor. +.TP +.B 4 +The pipe reader reads 1Kb of data from +.BR RFD . +.TP +.B 5 +A call to +.BR epoll_wait (2) +is done. +.PP + +If the +.B RFD +file descriptor has been added to the +.B epoll +interface using the +.B EPOLLET +flag, the call to +.BR epoll_wait (2) +done in step +.B 5 +will probably hang because of the available data still present in the file +input buffers and the remote peer might be expecting a response based on the +data it already sent. The reason for this is that Edge Triggered event +distribution delivers events only when events happens on the monitored file. +So, in step +.B 5 +the caller might end up waiting for some data that is already present inside +the input buffer. In the above example, an event on +.B RFD +will be generated because of the write done in +.B 2 +, and the event is consumed in +.BR 3 . +Since the read operation done in +.B 4 +does not consume the whole buffer data, the call to +.BR epoll_wait (2) +done in step +.B 5 +might lock indefinitely. The +.B epoll +interface, when used with the +.B EPOLLET +flag ( Edge Triggered ) +should use non-blocking file descriptors to avoid having a blocking +read or write starve the task that is handling multiple file descriptors. +The suggested way to use +.B epoll +as an Edge Triggered ( +.B EPOLLET +) interface is below, and possible pitfalls to avoid follow. +.RS +.TP +.B i +with non-blocking file descriptors +.TP +.B ii +by going to wait for an event only after +.BR read (2) +or +.BR write (2) +return EAGAIN +.RE +.PP +On the contrary, when used as a Level Triggered interface, +.B epoll +is by all means a faster +.BR poll (2), +and can be used wherever the latter is used since it shares the +same semantics. Since even with the Edge Triggered +.B epoll +multiple events can be generated up on receival of multiple chunks of data, +the caller has the option to specify the +.B EPOLLONESHOT +flag, to tell +.B epoll +to disable the associated file descriptor after the receival of an event with +.BR epoll_wait (2). +When the +.B EPOLLONESHOT +flag is specified, it is caller responsibility to rearm the file descriptor using +.BR epoll_ctl (2) +with +.BR EPOLL_CTL_MOD . + +.SH EXAMPLE FOR SUGGESTED USAGE + +While the usage of +.B epoll +when employed like a Level Triggered interface does have the same +semantics of +.BR poll (2), +an Edge Triggered usage requires more clarifiction to avoid stalls +in the application event loop. In this example, listener is a +non-blocking socket on which +.BR listen (2) +has been called. The function do_use_fd() uses the new ready +file descriptor until EAGAIN is returned by either +.BR read (2) +or +.BR write (2). +An event driven state machine application should, after having received +EAGAIN, record its current state so that at the next call to do_use_fd() +it will continue to +.BR read (2) +or +.BR write (2) +from where it stopped before. + +.nf +struct epoll_event ev, *events; + +for(;;) { + nfds = epoll_wait(kdpfd, events, maxevents, -1); + + for(n = 0; n < nfds; ++n) { + if(events[n].data.fd == listener) { + client = accept(listener, (struct sockaddr *) &local, + &addrlen); + if(client < 0){ + perror("accept"); + continue; + } + setnonblocking(client); + ev.events = EPOLLIN | EPOLLET; + ev.data.fd = client; + if (epoll_ctl(kdpfd, EPOLL_CTL_ADD, client, &ev) < 0) { + fprintf(stderr, "epoll set insertion error: fd=%d\n", + client); + return -1; + } + } + else + do_use_fd(events[n].data.fd); + } +} +.fi + +When used as an Edge triggered interface, for performance reasons, it is +possible to add the file descriptor inside the epoll interface ( +.B EPOLL_CTL_ADD +) once by specifying ( +.BR EPOLLIN | EPOLLOUT +). This allows you to avoid +continuously switching between +.B EPOLLIN +and +.B EPOLLOUT +calling +.BR epoll_ctl (2) +with +.BR EPOLL_CTL_MOD . + +.SH QUESTIONS AND ANSWERS (from linux-kernel) + +.RS +.TP +.B Q1 +What happens if you add the same fd to an epoll_set twice? +.TP +.B A1 +You will probably get EEXIST. However, it is possible that two +threads may add the same fd twice. This is a harmless condition. +.TP +.B Q2 +Can two +.B epoll +sets wait for the same fd? If so, are events reported +to both +.B epoll +sets fds? +.TP +.B A2 +Yes. However, it is not recommended. Yes it would be reported to both. +.TP +.B Q3 +Is the +.B epoll +fd itself poll/epoll/selectable? +.TP +.B A3 +Yes. +.TP +.B Q4 +What happens if the +.B epoll +fd is put into its own fd set? +.TP +.B A4 +It will fail. However, you can add an +.B epoll +fd inside another epoll fd set. +.TP +.B Q5 +Can I send the +.B epoll +fd over a unix-socket to another process? +.TP +.B A5 +No. +.TP +.B Q6 +Will the close of an fd cause it to be removed from all +.B epoll +sets automatically? +.TP +.B A6 +Yes. +.TP +.B Q7 +If more than one event comes in between +.BR epoll_wait (2) +calls, are they combined or reported separately? +.TP +.B A7 +They will be combined. +.TP +.B Q8 +Does an operation on an fd affect the already collected but not yet reported +events? +.TP +.B A8 +You can do two operations on an existing fd. Remove would be meaningless for +this case. Modify will re-read available I/O. +.TP +.B Q9 +Do I need to continuously read/write an fd until EAGAIN when using the +.B EPOLLET +flag ( Edge Triggered behaviour ) ? +.TP +.B A9 +No you don't. Receiving an event from +.BR epoll_wait (2) +should suggest to you that such file descriptor is ready for the requested I/O +operation. You have simply to consider it ready until you will receive the +next EAGAIN. When and how you will use such file descriptor is entirely up +to you. Also, the condition that the read/write I/O space is exhausted can +be detected by checking the amount of data read/write from/to the target +file descriptor. For example, if you call +.BR read (2) +by asking to read a certain amount of data and +.BR read (2) +returns a lower number of bytes, you can be sure to have exhausted the read +I/O space for such file descriptor. Same is valid when writing using the +.BR write (2) +function. +.RE + +.SH POSSIBLE PITFALLS AND WAYS TO AVOID THEM +.RS +.TP +.B o Starvation ( Edge Triggered ) +.PP +If there is a large amount of I/O space, it is possible that by trying to drain +it the other files will not get processed causing starvation. This +is not specific to +.BR epoll . +.PP +.PP +The solution is to maintain a ready list and mark the file descriptor as ready +in its associated data structure, thereby allowing the application to +remember which files need to be processed but still round robin amongst +all the ready files. This also supports ignoring subsequent events you +receive for fd's that are already ready. +.PP + +.TP +.B o If using an event cache... +.PP +If you use an event cache or store all the fd's returned from +.BR epoll_wait (2), +then make sure to provide a way to mark its closure dynamically (ie- caused by +a previous event's processing). Suppose you receive 100 events from +.BR epoll_wait (2), +and in eventi #47 a condition causes event #13 to be closed. +If you remove the structure and close() the fd for event #13, then your +event cache might still say there are events waiting for that fd causing +confusion. +.PP +.PP +One solution for this is to call, during the processing of event 47, +.BR epoll_ctl ( EPOLL_CTL_DEL ) +to delete fd 13 and close(), then mark its associated +data structure as removed and link it to a cleanup list. If you find another +event for fd 13 in your batch processing, you will discover the fd had been +previously removed and there will be no confusion. +.PP + +.RE +.SH CONFORMING TO +.BR epoll (4) +is a new API introduced in Linux kernel 2.5.44. +Its interface should be finalized in Linux kernel 2.5.66. +.SH "SEE ALSO" +.BR epoll_create (2), +.BR epoll_ctl (2), +.BR epoll_wait (2) diff --git a/man4/fd.4 b/man4/fd.4 new file mode 100644 index 000000000..c449cc84d --- /dev/null +++ b/man4/fd.4 @@ -0,0 +1,208 @@ +'\" t +.\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de) +.\" and 1994,1995 Alain Knaff (Alain.Knaff@imag.fr) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified, Sun Feb 26 15:00:02 1995, faith@cs.unc.edu +.\" +.TH FD 4 1995-01-29 "Special files" "Linux Programmer's Manual" +.SH NAME +fd \- floppy disk device +.SH CONFIGURATION +Floppy drives are block devices with major number 2. Typically they +are owned by root.floppy (i.e., user root, group floppy) and have +either mode 0660 (access checking via group membership) or mode 0666 +(everybody has access). The minor +numbers encode the device type, drive number, and controller number. +For each device type (that is, combination of density and track count) +there is a base minor number. To this base number, add the drive's +number on its controller and 128 if the drive is on the secondary +controller. In the following device tables, \fIn\fP represents the +drive number. +.PP +\fBWarning: If you use formats with more tracks +than supported by your drive, you may cause it mechanical damage.\fP Trying +once if more tracks than the usual 40/80 are supported should not +damage it, but no warranty is given for that. Don't create device +entries for those formats to prevent their usage if you are not sure. +.PP +Drive independent device files which automatically detect the media +format and capacity: +.PP +.TS +l l. +Name Base minor # +_ +\fBfd\fP\fIn\fP 0 +.TE +.PP +5.25 inch double density device files: +.PP +.TS +lw(1i) l l l l l. +Name Capac. Cyl. Sect. Heads Base minor # +_ +\fBfd\fP\fIn\fP\fBd360\fP 360K 40 9 2 4 +.TE +.PP +5.25 inch high density device files: +.PP +.TS +lw(1i) l l l l l. +Name Capac. Cyl. Sect. Heads Base minor # +_ +\fBfd\fP\fIn\fP\fBh360\fP 360K 40 9 2 20 +\fBfd\fP\fIn\fP\fBh410\fP 410K 41 10 2 48 +\fBfd\fP\fIn\fP\fBh420\fP 420K 42 10 2 64 +\fBfd\fP\fIn\fP\fBh720\fP 720K 80 9 2 24 +\fBfd\fP\fIn\fP\fBh880\fP 880K 80 11 2 80 +\fBfd\fP\fIn\fP\fBh1200\fP 1200K 80 15 2 8 +\fBfd\fP\fIn\fP\fBh1440\fP 1440K 80 18 2 40 +\fBfd\fP\fIn\fP\fBh1476\fP 1476K 82 18 2 56 +\fBfd\fP\fIn\fP\fBh1494\fP 1494K 83 18 2 72 +\fBfd\fP\fIn\fP\fBh1600\fP 1600K 80 20 2 92 +.TE +.PP +3.5 inch double density device files: +.PP +.TS +lw(1i) l l l l l. +Name Capac. Cyl. Sect. Heads Base minor # +_ +\fBfd\fP\fIn\fP\fBD360\fP 360K 80 9 1 12 +\fBfd\fP\fIn\fP\fBD720\fP 720K 80 9 2 16 +\fBfd\fP\fIn\fP\fBD800\fP 800K 80 10 2 120 +\fBfd\fP\fIn\fP\fBD1040\fP 1040K 80 13 2 84 +\fBfd\fP\fIn\fP\fBD1120\fP 1120K 80 14 2 88 +.TE +.PP +3.5 inch high density device files: +.PP +.TS +lw(1i) l l l l l. +Name Capac. Cyl. Sect. Heads Base minor # +_ +\fBfd\fP\fIn\fP\fBH360\fP 360K 40 9 2 12 +\fBfd\fP\fIn\fP\fBH720\fP 720K 80 9 2 16 +\fBfd\fP\fIn\fP\fBH820\fP 820K 82 10 2 52 +\fBfd\fP\fIn\fP\fBH830\fP 830K 83 10 2 68 +\fBfd\fP\fIn\fP\fBH1440\fP 1440K 80 18 2 28 +\fBfd\fP\fIn\fP\fBH1600\fP 1600K 80 20 2 124 +\fBfd\fP\fIn\fP\fBH1680\fP 1680K 80 21 2 44 +\fBfd\fP\fIn\fP\fBH1722\fP 1722K 82 21 2 60 +\fBfd\fP\fIn\fP\fBH1743\fP 1743K 83 21 2 76 +\fBfd\fP\fIn\fP\fBH1760\fP 1760K 80 22 2 96 +\fBfd\fP\fIn\fP\fBH1840\fP 1840K 80 23 2 116 +\fBfd\fP\fIn\fP\fBH1920\fP 1920K 80 24 2 100 +.TE +.PP +3.5 inch extra density device files: +.PP +.TS +lw(1i) l l l l l. +Name Capac. Cyl. Sect. Heads Base minor # +_ +\fBfd\fP\fIn\fP\fBE2880\fP 2880K 80 36 2 32 +\fBfd\fP\fIn\fP\fBCompaQ\fP 2880K 80 36 2 36 +\fBfd\fP\fIn\fP\fBE3200\fP 3200K 80 40 2 104 +\fBfd\fP\fIn\fP\fBE3520\fP 3520K 80 44 2 108 +\fBfd\fP\fIn\fP\fBE3840\fP 3840K 80 48 2 112 +.TE +.SH DESCRIPTION +\fBfd\fP special files access the floppy disk drives in raw mode. +The following +.BR ioctl (2) +calls are supported by \fBfd\fP devices: +.IP \fBFDCLRPRM\fP +clears the media information of a drive (geometry of disk in drive). +.IP \fBFDSETPRM\fP +sets the media information of a drive. The media information will be +lost when the media is changed. +.IP \fBFDDEFPRM\fP +sets the media information of a drive (geometry of disk in drive). The +media information will not be lost when the media is changed. This +will disable autodetection. In order to re-enable autodetection, you +have to issue an \fBFDCLRPRM\fP . +.IP \fBFDGETDRVTYP\fP +returns the type of a drive (name parameter). For formats which work +in several drive types, \fBFDGETDRVTYP\fP returns a name which is +appropriate for the oldest drive type which supports this format. +.IP \fBFDFLUSH\fP +invalidates the buffer cache for the given drive. +.IP \fBFDSETMAXERRS\fP +sets the error thresholds for reporting errors, aborting the operation, +recalibrating, resetting, and reading sector by sector. +.IP \fBFDSETMAXERRS\fP +gets the current error thresholds. +.IP \fBFDGETDRVTYP\fP +gets the internal name of the drive. +.IP \fBFDWERRORCLR\fP +clears the write error statistics. +.IP \fBFDWERRORGET\fP +reads the write error statistics. These include the total number of +write errors, the location and disk of the first write error, and the +location and disk of the last write error. Disks are identified by a +generation number which is incremented at (almost) each disk change. +.IP \fBFDTWADDLE\fP +Switch the drive motor off for a few microseconds. This might be +needed in order to access a disk whose sectors are too close together. +.IP \fBFDSETDRVPRM\fP +sets various drive parameters. +.IP \fBFDGETDRVPRM\fP +reads these parameters back. +.IP \fBFDGETDRVSTAT\fP +gets the cached drive state (disk changed, write protected et al.) +.IP \fBFDPOLLDRVSTAT\fP +polls the drive and return its state. +.IP \fBFDGETFDCSTAT\fP +gets the floppy controller state. +.IP \fBFDRESET\fP +resets the floppy controller under certain conditions. +.IP \fBFDRAWCMD\fP +sends a raw command to the floppy controller. +.PP +For more precise information, consult also the and + include files, as well as the manual page for +floppycontrol. +.SH NOTES +The various formats allow to read and write many types of disks. +However, if a floppy is formatted with a too small inter sector gap, +performance may drop, up to needing a few seconds to access an entire +track. To prevent this, use interleaved formats. It is not possible to +read floppies which are formatted using GCR (group code recording), +which is used by Apple II and Macintosh computers (800k disks). +Reading floppies which are hard sectored (one hole per sector, with +the index hole being a little skewed) is not supported. This used to +be common with older 8 inch floppies. +.SH FILES +/dev/fd* +.SH AUTHORS +Alain Knaff (Alain.Knaff@imag.fr), David Niemi +(niemidc@clark.net), Bill Broadhurst (bbroad@netcom.com). +.SH "SEE ALSO" +.BR chown (1), +.BR floppycontrol (1), +.BR getfdprm (1), +.BR mknod (1), +.BR superformat (1), +.BR mount (8), +.BR setfdprm (8) diff --git a/man4/fifo.4 b/man4/fifo.4 new file mode 100644 index 000000000..1fc736382 --- /dev/null +++ b/man4/fifo.4 @@ -0,0 +1,57 @@ +.\" This man page is Copyright (C) 1999 Claus Fischer. +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" +.\" 990620 - page created - aeb@cwi.nl +.\" +.TH FIFO 4 1999-06-20 "Linux" "Linux Programmer's Manual" +.SH NAME +fifo \- first-in first-out special file, named pipe +.SH DESCRIPTION +A FIFO special file (a named pipe) is similar to a pipe, +except that it is accessed as part of the file system. +It can be opened by multiple processes for reading or +writing. When processes are exchanging data via the FIFO, +the kernel passes all data internally without writing it +to the file system. Thus, the FIFO special file has no +contents on the file system, the file system entry merely +serves as a reference point so that processes can access +the pipe using a name in the file system. +.PP +The kernel maintains exactly one pipe object for each +FIFO special file that is opened by at least one process. +The FIFO must be opened on both ends (reading and writing) +before data can be passed. Normally, opening the FIFO blocks +until the other end is opened also. +.PP +A process can open a FIFO in non-blocking mode. In this +case, opening for read only will succeed even if noone has +opened on the write side yet; opening for write only will +fail with ENXIO (no such device or address) unless the other +end has already been opened. +.PP +Under Linux, opening a FIFO for read and write will succeed +both in blocking and non-blocking mode. POSIX leaves this +behaviour undefined. This can be used to open a FIFO for +writing while there are no readers available. A process +that uses both ends of the connection in order to communicate +with itself should be very careful to avoid deadlocks. +.SH NOTES +When a process tries to write to a FIFO that is not opened +for read on the other side, the process is sent a SIGPIPE +signal. + +FIFO special files can be created by +.BR mkfifo (3), +and are specially indicated in +.IR "ls -l" . +.SH "SEE ALSO" +.BR mkfifo (1), +.BR open (2), +.BR pipe (2), +.BR sigaction (2), +.BR signal (2), +.BR socketpair (2), +.BR mkfifo (3) diff --git a/man4/full.4 b/man4/full.4 new file mode 100644 index 000000000..7d15fe20b --- /dev/null +++ b/man4/full.4 @@ -0,0 +1,52 @@ +.\" -*- nroff -*- +.\" +.\" This man-page is Copyright (C) 1997 John S. Kallal +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" correction, aeb, 970825 +.TH FULL 4 1997-08-02 "Linux" "Linux Programmer's Manual" +.SH NAME +full \- always full device +.SH DESCRIPTION +File \fB/dev/full\fP has major device number 1 +and minor device number 7. +.LP +Writes to the \fB/dev/full\fP device will fail with an ENOSPC error. + +Reads from the \fB/dev/full\fP device will return \\0 characters. + +Seeks on \fB/dev/full\fP will always succeed. +.SH CONFIGURING +If your system does not have \fB/dev/full\fP created already, it +can be created with the following commands: +.nf + + mknod -m 666 /dev/full c 1 7 + chown root:root /dev/full + +.fi +.SH FILES +/dev/full +.SH "SEE ALSO" +.BR mknod (1), +.BR null (4), +.BR zero (4) diff --git a/man4/futex.4 b/man4/futex.4 new file mode 100644 index 000000000..e99322650 --- /dev/null +++ b/man4/futex.4 @@ -0,0 +1,79 @@ +.\" This manpage has been automatically generated by docbook2man +.\" from a DocBook document. This tool can be found at: +.\" +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng . +.TH FUTEX 4 2002-12-31 "" "Linux Programmer's Manual" +.SH NAME +futex \- Fast Userspace Locking +.SH SYNOPSIS +.nf +#include +.fi +.SH DESCRIPTION +.PP +The Linux kernel provides futexes ('Fast Userspace muTexes') as a building block for fast userspace +locking and semaphores. Futexes are very basic and lend themselves well for building higher level +locking abstractions such as POSIX mutexes. +.PP +This page does not set out to document all design decisions but restricts itself to issues relevant for +application and library development. Most programmers will in fact not be using futexes directly but +instead rely on system libraries built on them, such as the NPTL pthreads implementation. +.PP +A futex is identified by a piece of memory which can be shared between different processes. In these +different processes, it need not have identical addresses. In its bare form, a futex has semaphore +semantics; it is a counter that can be incremented and decremented atomically; processes can wait for the +value to become positive. +.PP +Futex operation is entirely userspace for the non-contended case. The kernel is only involved to arbitrate +the contended case. As any sane design will strive for non-contension, futexes are also optimised +for this situation. +.PP +In its bare form, a futex is an aligned integer which is only touched by atomic assembler +instructions. Processes can share this integer over mmap, via shared segments or because they +share memory space, in which case the application is commonly called multithreaded. +.SH "SEMANTICS" +.PP +Any futex operation starts in userspace, but it may necessary to communicate with the kernel using the +\fBfutex\fR(2) system call. +.PP +To 'up' a futex, execute the proper assembler instructions that will cause the host CPU to atomically +increment the integer. Afterwards, check if it has in fact changed from 0 to 1, in which case +there were no waiters and the operation is done. This is the non-contended case which is fast and +should be common. +.PP +In the contended case, the atomic increment changed the counter from -1 (or some other negative number). If this is detected, +there are waiters. Userspace should now set the counter to 1 and instruct the kernel to wake up any +waiters using the FUTEX_WAKE operation. +.PP +Waiting on a futex, to 'down' it, is the reverse operation. Atomically decrement the counter and +check if it changed to 0, in which case the operation is done and the futex was uncontended. In all +other circumstances, the process should set the counter to -1 and request that the kernel wait for +another process to up the futex. This is done using the FUTEX_WAIT operation. +.PP +The futex system call can optionally be passed a timeout specifying how long the kernel should +wait for the futex to be upped. In this case, semantics are more complex and the programmer is referred +to \fBfutex\fR(2) for +more details. The same holds for asynchronous futex waiting. +.SH "NOTES" +.PP +To reiterate, bare futexes are not intended as an easy to use abstraction for end-users. Implementors +are expected to be assembly literate and to have read the sources of the futex userspace library referenced +below. +.PP +This man page illustrates the most common use of the \fBfutex\fR(2) primitives: it is by no means the only one. +.SH "AUTHORS" +.PP +Futexes were designed and worked on by Hubertus Franke (IBM Thomas J. Watson Research Center), +Matthew Kirkwood, Ingo Molnar (Red Hat) and Rusty Russell (IBM Linux Technology Center). This page written +by bert hubert. +.SH "VERSIONS" +.PP +Initial futex support was merged in Linux 2.5.7 but with different semantics from those described above. +Current semantics are available from Linux 2.5.40 onwards. +.SH "SEE ALSO" +.PP +\fBfutex\fR(2), +`Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux' (proceedings of the Ottawa Linux +Symposium 2002), +futex example library, futex-*.tar.bz2 . diff --git a/man4/hd.4 b/man4/hd.4 new file mode 100644 index 000000000..1470cd45b --- /dev/null +++ b/man4/hd.4 @@ -0,0 +1,97 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 16:56:20 1993 by Rik Faith +.\" Modified Mon Oct 21 21:38:51 1996 by Eric S. Raymond +.\" (and some more by aeb) +.\" +.TH HD 4 1992-12-17 "Linux" "Linux Programmer's Manual" +.SH NAME +hd \- MFM/IDE hard disk devices +.SH DESCRIPTION +The \fBhd*\fP devices are block devices to access MFM/IDE hard disk drives +in raw mode. The master drive on the primary IDE controller (major device +number 3) is \fBhda\fR; the slave drive is \fBhdb\fR. The master +drive of the second controller (major device number 22) is \fBhdc\fR +and the slave \fBhdd\fR. +.LP +General IDE block device names have the form +.BI hd X\c +, or +.BI hd XP\c +, where +.I X +is a letter denoting the physical drive, and +.I P +is a number denoting the partition on that physical drive. +The first form, +.BI hd X, +is used to address the whole drive. +Partition numbers are assigned in the order the partitions +are discovered, and only non-empty, non-extended partitions +get a number. However, partition numbers 1-4 are given to the +four partitions described in the MBR (the `primary' partitions), +regardless of whether they are unused or extended. +Thus, the first logical partition will be +.BI hd X 5\c +\&. +Both DOS-type partitioning and BSD-disklabel partitioning are supported. +You can have at most 63 partitions on an IDE disk. +.LP +For example, +.B /dev/hda +refers to all of the first IDE drive in the system; and +.B /dev/hdb3 +refers to the third DOS `primary' partition on the second one. +.LP +They are typically created by: +.RS +.sp +mknod -m 660 /dev/hda b 3 0 +.br +mknod -m 660 /dev/hda1 b 3 1 +.br +mknod -m 660 /dev/hda2 b 3 2 +.br +\&... +.br +mknod -m 660 /dev/hda8 b 3 8 +.br +mknod -m 660 /dev/hdb b 3 64 +.br +mknod -m 660 /dev/hdb1 b 3 65 +.br +mknod -m 660 /dev/hdb2 b 3 66 +.br +\&... +.br +mknod -m 660 /dev/hdb8 b 3 72 +.br +chown root:disk /dev/hd* +.RE +.SH FILES +/dev/hd* +.SH "SEE ALSO" +.BR chown (1), +.BR mknod (1), +.BR sd (4), +.BR mount (8) diff --git a/man4/initrd.4 b/man4/initrd.4 new file mode 100644 index 000000000..bc1d3b069 --- /dev/null +++ b/man4/initrd.4 @@ -0,0 +1,422 @@ +.\" -*- nroff -*- +.\" This man-page is Copyright (C) 1997 John S. Kallal +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and author(s) of this work. +.\" +.\" If the you wish to distribute versions of this work under other +.\" conditions than the above, please contact the author(s) at the following +.\" for permission: +.\" +.\" John S. Kallal - +.\" email: +.\" mail: 518 Kerfoot Farm RD, Wilmington, DE 19803-2444, USA +.\" phone: (302)654-5478 +.\" +.\" $Id: initrd.4,v 0.9 1997/11/07 05:05:32 kallal Exp kallal $ +.TH INITRD 4 1997-11-06 "Linux 2.0" "Linux Programmer's Manual" +.SH NAME +initrd \- boot loader initialized RAM disk +.\" +.\" +.\" +.SH DESCRIPTION +The special file +.B /dev/initrd +is a read-only block device. +Device +.B /dev/initrd +is a RAM disk that is initialized (e.g. loaded) by the boot loader before +the kernel is started. +The kernel then can use the the block device +.BR /dev/initrd "'s " +contents for a two phased system boot-up. +.PP +In the first boot-up phase, the kernel starts up +and mounts an initial root file-system from the contents +of +.B /dev/initrd +(e.g. RAM disk initialized by the boot loader). +In the second phase, additional drivers or other modules +are loaded from the initial root device's contents. +After loading the additional modules, a new root file system +(i.e. the normal root file system) is mounted from a +different device. +.\" +.\" +.\" +.SH "BOOT-UP OPERATION" +When booting up with +.BR initrd ", the system boots as follows:" +.RS 0.2i +.PP +1. The boot loader loads the kernel program and +.BR /dev/initrd "'s contents into memory." +.PP +2. On kernel startup, the kernel uncompresses and copies the contents of the device +.B /dev/initrd +onto device +.B /dev/ram0 +and then frees the memory used by +.BR /dev/initrd "." +.PP +3. The kernel then read-write mounts device +.B /dev/ram0 +as the initial root file system. +.PP +4. If the indicated normal root file system is also the initial root file-system +(e.g. +.B /dev/ram0 +) then the kernel skips to the last step for the usual boot sequence. +.PP +5. If the executable file +.BR /linuxrc " is present in the initial root file-system, " /linuxrc +is executed with uid 0. +(The file +.B /linuxrc +must have executable permission. +The file +.B /linuxrc +can be any valid executable, including a shell script.) +.PP +6. If +.B /linuxrc +is not executed or when +.B /linuxrc +terminates, the normal root file system is mounted. +(If +.BR /linuxrc +exits with any file-systems mounted on the initial root +file-system, then the behavior of the kernel is +.BR UNSPECIFIED "." +See the +.BR NOTES +section for the current kernel behavior.) +.PP +7. If the normal root file has directory +.BR /initrd ", device" +.B /dev/ram0 +is moved from +.BR / " to " /initrd "." +Otherwise if directory +.BR /initrd " does not exist device " /dev/ram0 " is unmounted." +(When moved from +.BR / " to " /initrd ", " /dev/ram0 +is not unmounted and therefore processes can remain running from +.BR /dev/ram0 "." +If directory +.BR /initrd +does not exist on the normal root file-system +and any processes remain running from +.BR /dev/ram0 " when " /linuxrc +exits, the behavior of the kernel is +.BR UNSPECIFIED "." +See the +.BR NOTES +section for the current kernel behavior.) +.PP +8. The usual boot sequence (e.g. invocation of +.BR /sbin/init ") is performed on the normal root file system." +.\" +.\" +.\" +.SH OPTIONS +The following boot loader options when used with +.BR initrd ", affect the kernel's boot-up operation:" +.TP +.BI initrd= "filename" +Specifies the file to load as the contents of +.BR /dev/initrd "." +.RB "For " LOADLIN +this is a command line option. +.RB "For " LILO " you have to use this command in the +.BR LILO " configuration file " /etc/lilo.config "." +The filename specified with this +option will typically be a gzipped file-system image. +.TP +.B noinitrd +This boot time option disables the two phase boot-up operation. +The kernel performs the usual boot sequence as if +.B /dev/initrd +was not initialized. +With this option, any contents of +.B /dev/initrd +loaded into memory by the boot loader contents are preserved. +This option permits the contents of +.B /dev/initrd +to be any data and need not be limited to a file system image. +However, device +.B /dev/initrd +is read-only and can be read only one time after system startup. +.TP +.BI root= "device-name" +Specifies the device to be used as the normal root file system. +.RB "For " LOADLIN +this is a command line option. +.RB "For " LILO " this is a boot time option or +can be used as an option line in the +.BR LILO " configuration file " /etc/lilo.config "." +The device specified by the this option must be a mountable +device having a suitable root file-system. +.\" +.\" +.\" +.SH "CHANGING THE NORMAL ROOT FILE SYSTEM" +By default, +the kernel's settings +(e.g. set in the kernel file with +.B rdev +or compiled into the kernel file), +or the boot loader option setting +is used for the normal root file systems. +For a NFS-mounted normal root file system, one has to use the +.BR nfs_root_name " and " nfs_root_addrs +boot options to give the NFS settings. +For more information on NFS-mounted root see the kernel documentation file +.BR nfsroot.txt "." +For more information on setting the root file system also see the +.BR LILO " and " LOADLIN " documentation." +.PP +It is also possible for the +.BR /linuxrc +executable to change the normal root device. +For +.BR /linuxrc +to change the normal root device, +.BR /proc " must be mounted." +After mounting +.BR /proc ", " /linuxrc +changes the normal root device by writing into the proc files +.BR /proc/sys/kernel/real-root-dev ", " +.BR /proc/sys/kernel/nfs-root-name ", and " +.BR /proc/sys/kernel/nfs-root-addrs "." +For a physical root device, the root device is changed by having +.BR /linuxrc +write the new root file system device number into +.BR /proc/sys/kernel/real-root-dev "." +For a NFS root file system, the root device is changed by having +.BR /linuxrc +write the NFS setting into files +.BR /proc/sys/kernel/nfs-root-name " and " +.BR /proc/sys/kernel/nfs-root-addrs +and then writing 0xff (e.g. the pseudo-NFS-device number) into file +.BR /proc/sys/kernel/real-root-dev "." +For example, the following shell command line would change +the normal root device to +.BR /dev/hdb1 : +.nf + echo 0x365 >/proc/sys/kernel/real-root-dev +.fi +For a NFS example, the following shell command lines would change the +normal root device to the NFS directory +.BR /var/nfsroot +on a local networked NFS server with IP number 193.8.232.7 for a system with +IP number 193.8.232.7 and named 'idefix': +.nf + echo /var/nfsroot >/proc/sys/kernel/nfs-root-name + echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \\ + >/proc/sys/kernel/nfs-root-addrs + echo 255 >/proc/sys/kernel/real-root-dev +.fi +.\" +.\" +.\" +.SH USAGE +The main motivation for implementing +.BR initrd +was to allow for modular kernel configuration at system installation. +.PP +A possible system installation scenario is as follows: +.RS 0.2i +.PP +1. The loader program boots from floppy or other media with a minimal kernel +(e.g. support for +.BR /dev/ram ", " /dev/initrd ", and the ext2 file-system) and loads " +.BR /dev/initrd " with a gzipped version of the initial file-system. +.PP +2. The executable +.BR /linuxrc +determines what is needed to (1) mount the normal root file-system +(i.e. device type, device drivers, file system) and (2) the +distribution media (e.g. CD-ROM, network, tape, ...). This can be +done by asking the user, by auto-probing, or by using a hybrid +approach. +.PP +3. The executable +.BR /linuxrc +loads the necessary modules from the initial root file-system. +.PP +4. The executable +.BR /linuxrc +creates and populates the root file system. (At this stage the normal +root file system does not have to be a +completed system yet.) +.PP +5. The executable +.BR /linuxrc " sets " /proc/sys/kernel/real-root-dev, +unmount +.BR /proc ", " +the normal root file system and any other file +systems it has mounted, and then terminates. +.PP +6. The kernel then mounts the normal root file system. +.PP +7. Now that the file system is accessible and intact, +the boot loader can be installed. +.PP +8. The boot loader is configured to load into +.BR /dev/initrd +a file system with the set of modules that was used to bring up the system. +(e.g. Device +.BR /dev/ram0 +can be modified, then unmounted, and finally, the image is written from +.BR /dev/ram0 +to a file.) +.PP +9. The system is now bootable and additional installation tasks can be +performed. +.RE +.PP +The key role of +.BR /dev/initrd +in the above is to re-use the configuration data during normal system operation +without requiring initial kernel selection, a large generic kernel or, +recompiling the kernel. +.PP +A second scenario is for installations where Linux runs on systems with +different hardware configurations in a single administrative network. +In such cases, it may be desirable to use only a small set of kernels +(ideally only one) and to keep the system-specific part of configuration +information as small as possible. +In this case, create a common file +with all needed modules. +Then, only the the +.B /linuxrc +file or a file executed by +.B /linuxrc +would be different. +.PP +A third scenario is more convenient recovery disks. +Because information like the location of the root file-system +partition is not needed at boot time, the system loaded from +.B /dev/initrd +can use a dialog and/or auto-detection followed by a +possible sanity check. +.PP +Last but not least, Linux distributions on CD-ROM may use +.BR initrd +for easy installation from the CD-ROM. +The distribution can use +.BR LOADLIN +to directly load +.BR /dev/initrd +from CD-ROM without the need of any floppies. +The distribution could also use a +.BR LILO +boot floppy and then bootstrap a bigger ram disk via +.BR /dev/initrd " from the CD-ROM." +.\" +.\" +.\" +.SH CONFIGURATION +The +.B /dev/initrd +is a read-only block device assigned +major number 1 and minor number 250. +Typically +.B /dev/initrd +is owned by +.B root.disk +with mode 0400 (read access by root only). +If the Linux system does not have +.B /dev/initrd +already created, it can be created with the following commands: +.nf +\fB + mknod -m 400 /dev/initrd b 1 250 + chown root:disk /dev/initrd +\fP +.fi +Also, support for both "RAM disk" and "Initial RAM disk" +(e.g. +.BR CONFIG_BLK_DEV_RAM=y " and " CONFIG_BLK_DEV_INITRD=y +) support must be compiled directly into the Linux kernel to use +.BR /dev/initrd "." +When using +.BR /dev/initrd ", " +the RAM disk driver cannot be loaded as a module. +.\" +.\" +.\" +.SH FILES +.I /dev/initrd +.br +.I /dev/ram0 +.br +.I /linuxrc +.br +.I /initrd +.SH "SEE ALSO" +.BR chown (1), +.BR mknod (1), +.BR ram (4), +.BR freeramdisk (8), +.BR rdev (8) + +The documentation file +.I initrd.txt +in the kernel source package, the LILO documentation, +the LOADLIN documentation, the SYSLINUX documentation. +.\" +.\" +.\" +.SH NOTES +1. With the current kernel, any file systems that remain mounted when +.BR /dev/ram0 " is moved from " / " to " /initrd +continue to be accessible. However, the +.BR /proc/mounts +entries are not updated. +.PP +2. With the current kernel, if directory +.BR /initrd " does not exist, then " /dev/ram0 +will NOT be fully unmounted if +.BR /dev/ram0 +is used by any process or has any file-system mounted on it. +If +.BR /dev/ram0 " is NOT fully unmounted, " +then +.BR /dev/ram0 +will remain in memory. +.PP +3. Users of +.BR /dev/initrd +should not depend on the behavior give in the above notes. +The behavior may change in future versions of the Linux kernel. +.\" +.\" +.\" +.SH AUTHOR +The kernel code for device +.BR initrd +was written by Werner Almesberger and +Hans Lermen . +The code for +.BR initrd +was added to the baseline Linux kernel in development version 1.3.73. diff --git a/man4/intro.4 b/man4/intro.4 new file mode 100644 index 000000000..0068cf41e --- /dev/null +++ b/man4/intro.4 @@ -0,0 +1,33 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 16:57:14 1993 by Rik Faith (faith@cs.unc.edu) +.TH INTRO 4 1993-07-24 "Linux" "Linux Programmer's Manual" +.SH NAME +intro \- Introduction to special files +.SH DESCRIPTION +This chapter describes special files. +.SH FILES +/dev/* \(em device files +.SH AUTHORS +Look at the header of the manual page for the author(s) and copyright +conditions. Note that these can be different from page to page! diff --git a/man4/kmem.4 b/man4/kmem.4 new file mode 100644 index 000000000..d4c1762c5 --- /dev/null +++ b/man4/kmem.4 @@ -0,0 +1 @@ +.so man4/mem.4 diff --git a/man4/lp.4 b/man4/lp.4 new file mode 100644 index 000000000..873f26b52 --- /dev/null +++ b/man4/lp.4 @@ -0,0 +1,110 @@ +'\" t +.\" Copyright (c) Michael Haardt (michael@cantor.informatik.rwth-aachen.de), Sun Jan 15 19:16:33 1995 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified, Sun Feb 26 15:02:58 1995, faith@cs.unc.edu +.TH LP 4 1995-01-15 "Special files" "Linux Programmer's Manual" +.SH NAME +lp \- line printer devices +.SH SYNOPSIS +.B #include +.SH CONFIGURATION +\fBlp\fP[0\(en2] are character devices for the parallel line printers; +they have major number 6 and minor number 0\(en2. The minor numbers +correspond to the printer port base addresses 0x03bc, 0x0378 and 0x0278. +Usually they have mode 220 and are owned by root and group lp. You can +use printer ports either with polling or with interrupts. Interrupts +are recommended when high traffic is expected, e.g.\& for laser +printers. For usual dot matrix printers polling will usually be +enough. The default is polling. +.SH DESCRIPTION +The following +.BR ioctl (2) +calls are supported: +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPTIME, int \fP\fIarg\fP\fB)\fP" +Sets the amount of time that the driver sleeps before rechecking the printer +when the printer's buffer appears to be filled to \fIarg\fP. If you +have a fast printer, decrease this number; if you have a slow printer +then increase it. This is in hundredths of a second, the default 2 +being 0.02 seconds. It only influences the polling driver. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPCHAR, int \fP\fIarg\fP\fB)\fP" +Sets the maximum number of busy-wait iterations which the polling driver does +while waiting for the printer to get ready for receiving a character to +\fIarg\fP. If printing is too slow, increase this number; if the +system gets too slow, decrease this number. The default is 1000. +It only influences the polling driver. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPABORT, int \fP\fIarg\fP\fB)\fP" +If \fIarg\fP is 0, the printer driver will retry on errors, otherwise +it will abort. The default is 0. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPABORTOPEN, int \fP\fIarg\fP\fB)\fP" +If \fIarg\fP is 0, +.BR open (2) +will be aborted on error, otherwise error will be ignored. The default is +to ignore it. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPCAREFUL, int \fP\fIarg\fP\fB)\fP" +If \fIarg\fP is 0, then the out-of-paper, offline and error signals are +required to be false on all writes, otherwise they are ignored. The +default is to ignore them. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPWAIT, int \fP\fIarg\fP\fB)\fP" +Sets the number of busy waiting iterations to wait before strobing the +printer to accept a just-written character, and the number of iterations to +wait before turning the strobe off again, +to \fIarg\fP. The specification says this time should be 0.5 +microseconds, but experience has shown the delay caused by the code is +already enough. For that reason, the default value is 0. This is +used for both the polling and the interrupt driver. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPSETIRQ, int \fP\fIarg\fP\fB)\fP" +This ioctl() requires superuser privileges. It takes an int containing the +new IRQ as argument. As a side effect, the printer will be reset. When +\fIarg\fP is 0, the polling driver will be used, which is also default. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPGETIRQ, int *\fP\fIarg\fP\fB)\fP" +Stores the currently used IRQ in \fIarg\fP. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPGETSTATUS, int *\fP\fIarg\fP\fB)\fP" +Stores the value of the status port in \fIarg\fP. The bits have the following +meaning: +.sp +.TS +l l. +LP_PBUSY inverted busy input, active high +LP_PACK unchanged acknowledge input, active low +LP_POUTPA unchanged out-of-paper input, active high +LP_PSELECD unchanged selected input, active high +LP_PERRORP unchanged error input, active low +.TE +.sp +Refer to your printer manual for the meaning of the signals. +Note that undocumented bits may also be set, depending on your printer. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPRESET)\fP" +Resets the printer. No argument is used. +.SH FILES +/dev/lp* +.SH AUTHORS +The printer driver was originally written by Jim Weigand and Linus +Torvalds. It was further improved by Michael K.\& Johnson. The +interrupt code was written by Nigel Gamble. Alan Cox modularised it. +LPCAREFUL, LPABORT, LPGETSTATUS were added by Chris Metcalf. +.SH "SEE ALSO" +.BR chmod (1), +.BR chown (1), +.BR mknod (1), +.BR lpcntl (8), +.BR tunelp (8) diff --git a/man4/mem.4 b/man4/mem.4 new file mode 100644 index 000000000..5a7df3adf --- /dev/null +++ b/man4/mem.4 @@ -0,0 +1,79 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 16:59:10 1993 by Rik Faith (faith@cs.unc.edu) +.TH MEM 4 1992-11-21 "Linux" "Linux Programmer's Manual" +.SH NAME +mem, kmem, port \- system memory, kernel memory and system ports +.SH DESCRIPTION +\fBMem\fP is a character device file +that is an image of the main memory of the +computer. It may be used, for example, to examine (and even patch) the +system. +.LP +Byte addresses in mem are interpreted as physical memory addresses. +References to non-existent locations cause errors to be returned. +.LP +Examining and patching is likely to lead to unexpected results +when read-only or write-only bits are present. +.LP +It is typically created by: +.RS +.sp +mknod -m 660 /dev/mem c 1 1 +.br +chown root:mem /dev/mem +.sp +.RE +.LP +The file kmem is the same as mem, except that the kernel virtual memory +rather than physical memory is accessed. +.LP +It is typically created by: +.RS +.sp +mknod -m 640 /dev/kmem c 1 2 +.br +chown root:mem /dev/kmem +.sp +.RE +.LP +\fBPort\fP is similar to mem, but the IO ports are accessed. +.LP +It is typically created by: +.RS +.sp +mknod -m 660 /dev/port c 1 4 +.br +chown root:mem /dev/port +.sp +.RE +.SH FILES +.I /dev/mem +.br +.I /dev/kmem +.br +.I /dev/port +.SH "SEE ALSO" +.BR chown (1), +.BR mknod (1), +.BR ioperm (2) diff --git a/man4/mouse.4 b/man4/mouse.4 new file mode 100644 index 000000000..8ed5161fe --- /dev/null +++ b/man4/mouse.4 @@ -0,0 +1,148 @@ +'\" t +.\"roff.\" Copyright +.\" This manpage is Copyright (C) 1996 Michael Haardt. +.\" Updates Nov 1998, Andries Brouwer +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.TH MOUSE 4 1996-02-10 "Special files" "Linux Programmer's Manual" +.SH NAME +mouse \- serial mouse interface +.SH CONFIG +Serial mice are connected to a serial RS232/V24 dialout line, see +.BR ttys (4) +for a description. +.SH DESCRIPTION +.SS Introduction +The pinout of the usual 9 pin plug as used for serial mice is: + +.TS +center; +r c l. +pin name used for +2 RX Data +3 TX -12 V, Imax = 10 mA +4 DTR +12 V, Imax = 10 mA +7 RTS +12 V, Imax = 10 mA +5 GND Ground +.TE + +This is the specification, in fact 9 V suffices with most mice. +.PP +The mouse driver can recognize a mouse by dropping RTS to low and raising +it again. About 14 ms later the mouse will send 0x4D ('M') on the data line. +After a further 63 ms, a Microsoft-compatible 3-button mouse will send +0x33 ('3'). +.PP +The relative mouse movement is sent as \fIdx\fP (positive means right) +and \fIdy\fP (positive means down). Various mice can operate at different +speeds. To select speeds, cycle through the +speeds 9600, 4800, 2400 and 1200 bit/s, each time writing the two characters +from the table below and waiting 0.1 seconds. The following table shows +available speeds and the strings that select them: + +.TS +center; +l l. +bit/s string +9600 *q +4800 *p +2400 *o +1200 *n +.TE + +The first byte of a data packet can be used to synchronisation purposes. +.SS "Microsoft protocol" +The \fBMicrosoft\fP protocol uses 1 start bit, 7 data bits, no parity +and one stop bit at the speed of 1200 bits/sec. Data is sent to RxD in +3-byte packets. The \fIdx\fP and \fIdy\fP movements are sent as +two's-complement, \fIlb\fP (\fIrb\fP) are set when the left (right) +button is pressed: + +.TS +center; +r c c c c c c c. +byte d6 d5 d4 d3 d2 d1 d0 +1 1 lb rb dy7 dy6 dx7 dx6 +2 0 dx5 dx4 dx3 dx2 dx1 dx0 +3 0 dy5 dy4 dy3 dy2 dy1 dy0 +.TE +.SS "3-button Microsoft protocol" +Original Microsoft mice only have two buttons. However, there are some +three button mice which also use the Microsoft protocol. Pressing or +releasing the middle button is reported by sending a packet with zero +movement and no buttons pressed. +(Thus, unlike for the other two buttons, the status of the middle +button is not reported in each packet.) +.SS "Logitech protocol" +Logitech serial 3-button mice use a different extension of the +Microsoft protocol: when the middle button is up, the above 3-byte +packet is sent. When the middle button is down a 4-byte packet is +sent, where the 4th byte has value 0x20 (or at least has the 0x20 +bit set). In particular, a press of the middle button is reported +as 0,0,0,0x20 when no other buttons are down. +.SS "Mousesystems protocol" +The \fBMousesystems\fP protocol uses 1 start bit, 8 data bits, no parity +and two stop bits at the speed of 1200 bits/sec. Data is sent to RxD in +5-byte packets. \fIdx\fP is sent as the sum of the two two's-complement +values, \fIdy\fP is send as negated sum of the two two's-complement +values. \fIlb\fP (\fImb\fP, \fIrb\fP) are cleared when the left (middle, +right) button is pressed: + +.TS +center; +r c c c c c c c c. +byte d7 d6 d5 d4 d3 d2 d1 d0 +1 1 0 0 0 0 lb mb rb +2 0 dxa6 dxa5 dxa4 dxa3 dxa2 dxa1 dxa0 +3 0 dya6 dya5 dya4 dya3 dya2 dya1 dya0 +4 0 dxb6 dxb5 dxb4 dxb3 dxb2 dxb1 dxb0 +5 0 dyb6 dyb5 dyb4 dyb3 dyb2 dyb1 dyb0 +.TE + +Bytes 4 and 5 describe the change that occurred since bytes 2 and 3 +were transmitted. +.SS "Sun protocol" +The \fBSun\fP protocol is the 3-byte version of the above 5-byte +Mousesystems protocol: the last two bytes are not sent. +.SS "MM protocol" +The \fBMM\fP protocol uses 1 start bit, 8 data bits, odd parity and one +stop bit at the speed of 1200 bits/sec. Data is sent to RxD in 3-byte +packets. \fIdx\fP and \fIdy\fP are sent as single signed values, the +sign bit indicating a negative value. \fIlb\fP (\fImb\fP, \fIrb\fP) are +set when the left (middle, right) button is pressed: + +.TS +center; +r c c c c c c c c. +byte d7 d6 d5 d4 d3 d2 d1 d0 +1 1 0 0 dxs dys lb mb rb +2 0 dx6 dx5 dx4 dx3 dx2 dx1 dx0 +3 0 dy6 dy5 dy4 dy3 dy2 dy1 dy0 +.TE + +.SH FILES +.TP +.I /dev/mouse +A commonly used symlink pointing to a mouse device. + +.SH "SEE ALSO" +.BR ttys (4), +.BR gpm (8) diff --git a/man4/null.4 b/man4/null.4 new file mode 100644 index 000000000..8add9cd98 --- /dev/null +++ b/man4/null.4 @@ -0,0 +1,52 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 17:00:12 1993 by Rik Faith (faith@cs.unc.edu) +.TH NULL 4 1992-11-21 "Linux" "Linux Programmer's Manual" +.SH NAME +null, zero \- data sink +.SH DESCRIPTION +Data written on a \fBnull\fP or \fBzero\fP special file is discarded. +.PP +Reads from the \fBnull\fP special file always return end of file, whereas +reads from \fBzero\fP always return \e0 characters. +.LP +\fBnull\fP and \fBzero\fP are typically created by: +.RS +.sp +mknod -m 666 /dev/null c 1 3 +.br +mknod -m 666 /dev/zero c 1 5 +.br +chown root:mem /dev/null /dev/zero +.sp +.RE +.SH NOTES +If these devices are not writable and readable for all users, many +programs will act strange. +.SH FILES +.I /dev/null +.br +.I /dev/zero +.SH "SEE ALSO" +.BR chown (1), +.BR mknod (1) diff --git a/man4/port.4 b/man4/port.4 new file mode 100644 index 000000000..d4c1762c5 --- /dev/null +++ b/man4/port.4 @@ -0,0 +1 @@ +.so man4/mem.4 diff --git a/man4/ptmx.4 b/man4/ptmx.4 new file mode 100644 index 000000000..b50d4e710 --- /dev/null +++ b/man4/ptmx.4 @@ -0,0 +1 @@ +.so man4/pts.4 diff --git a/man4/pts.4 b/man4/pts.4 new file mode 100644 index 000000000..e98263554 --- /dev/null +++ b/man4/pts.4 @@ -0,0 +1,70 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" This man page was written by Jeremy Phelps . +.\" Notes added - aeb +.\" Redistribute and revise at will. +.\" +.TH PTS 4 "2002-10-09" "Linux" "Linux Programmer's Manual" +.SH NAME +ptmx and pts \- pseudo-terminal master and slave +.SH DESCRIPTION +The file \fB/dev/ptmx\fP is a character file with major number 5 and +minor number 2, usually of mode 0666 and owner.group of root.root. +It is used to create a pseudo-terminal master and slave pair. +.PP +When a process opens \fB/dev/ptmx\fP, it gets a file +descriptor for a pseudo-terminal master (PTM), +and a pseudo-terminal slave (PTS) device is created in the +.I /dev/pts +directory. Each file descriptor obtained by opening \fB/dev/ptmx\fP +is an independent PTM with its own associated PTS, whose path can +be found by passing the descriptor to +.BR ptsname (3). +.PP +Before opening the pseudo-terminal slave, you must pass the master's file +descriptor to +.BR grantpt (3) +and +.BR unlockpt (3). +.PP +Once both the pseudo-terminal master and slave are open, the slave provides +processes with an interface that is identical to that of a real terminal. +.PP +Data written to the slave is presented on the master descriptor as input. +Data written to the master is presented to the slave as input. +.PP +In practice, pseudo-terminals are used for implementing terminal emulators +such as +.BR xterm (1), +in which data read from the pseudo-terminal master is interpreted by the +application in the same way +a real terminal would interpret the data, and for implementing remote-login +programs such as +.BR sshd (8), +in which data read from the pseudo-terminal master is sent across the network +to a client program that is connected to a terminal or terminal emulator. +.PP +Pseudo-terminals can also be used to send input to programs that normally +refuse to read input from pipes (such as +.BR su (8), +and +.BR passwd (8)). +.SH FILES +.IR /dev/ptmx , +.I /dev/pts/* +.SH NOTES +The Linux support for the above (known as Unix98 pty naming) +is done using the +.I devpts +filesystem, that should be mounted on +.IR /dev/pts . +.LP +Before this Unix98 scheme, master ptys were called +.IR /dev/ptyp0 ", ..." +and slave ptys +.IR /dev/ttyp0 ", ..." +and one needed lots of preallocated device nodes. +.SH "SEE ALSO" +.BR getpt (3), +.BR grantpt (3), +.BR ptsname (3), +.BR unlockpt (3) diff --git a/man4/ram.4 b/man4/ram.4 new file mode 100644 index 000000000..1a3fb9f59 --- /dev/null +++ b/man4/ram.4 @@ -0,0 +1,43 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 17:01:11 1993 by Rik Faith (faith@cs.unc.edu) +.TH RAM 4 1992-11-21 "Linux" "Linux Programmer's Manual" +.SH NAME +ram \- ram disk device +.SH DESCRIPTION +The \fBRam\fP device is a block device to access the ram disk in raw mode. +.LP +It is typically created by: +.RS +.sp +mknod -m 660 /dev/ram b 1 1 +.br +chown root:disk /dev/ram +.sp +.RE +.SH FILES +/dev/ram +.SH "SEE ALSO" +.BR chown (1), +.BR mknod (1), +.BR mount (8) diff --git a/man4/random.4 b/man4/random.4 new file mode 100644 index 000000000..d12c43cef --- /dev/null +++ b/man4/random.4 @@ -0,0 +1,134 @@ +.\" Copyright (c) 1997 John S. Kallal (kallal@voicenet.com) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" Some changes by tytso and aeb. +.\" +.TH RANDOM 4 2003-10-25 "Linux" "Linux Programmer's Manual" +.SH NAME +random, urandom \- kernel random number source devices +.SH DESCRIPTION +The character special files \fB/dev/random\fP and +\fB/dev/urandom\fP (present since Linux 1.3.30) +provide an interface to the kernel's random number generator. +File \fB/dev/random\fP has major device number 1 +and minor device number 8. File \fB/dev/urandom\fP +has major device number 1 and minor device number 9. +.LP +The random number generator gathers environmental noise +from device drivers and other sources into an entropy pool. +The generator also keeps an estimate of the +number of bits of noise in the entropy pool. +From this entropy pool random numbers are created. +.LP +When read, the \fB/dev/random\fP device will only return random bytes +within the estimated number of bits of noise in the entropy +pool. \fB/dev/random\fP should be suitable for uses that need very +high quality randomness such as one-time pad or key generation. +When the entropy pool is empty, reads from \fB/dev/random\fP will block +until additional environmental noise is gathered. +.LP +When read, \fB/dev/urandom\fP device will return as many bytes as are +requested. As a result, if there is not sufficient entropy in the +entropy pool, the returned values are theoretically vulnerable to a +cryptographic attack on the algorithms used by the driver. Knowledge of +how to do this is not available in the current non-classified +literature, but it is theoretically possible that such an attack may +exist. If this is a concern in your application, use \fB/dev/random\fP +instead. +.SH CONFIGURING +If your system does not have +\fB/dev/random\fP and \fB/dev/urandom\fP created already, they +can be created with the following commands: + +.nf + mknod -m 644 /dev/random c 1 8 + mknod -m 644 /dev/urandom c 1 9 + chown root:root /dev/random /dev/urandom +.fi + +When a Linux system starts up without much operator interaction, +the entropy pool may be in a fairly predictable state. +This reduces the actual amount of noise in the entropy pool +below the estimate. In order to counteract this effect, it helps to carry +entropy pool information across shut-downs and start-ups. +To do this, add the following lines to an appropriate script +which is run during the Linux system start-up sequence: + +.nf + echo "Initializing kernel random number generator..." + # Initialize kernel random number generator with random seed + # from last shut-down (or start-up) to this start-up. Load and + # then save 512 bytes, which is the size of the entropy pool. + if [ -f /var/random-seed ]; then + cat /var/random-seed >/dev/urandom + fi + dd if=/dev/urandom of=/var/random-seed count=1 +.fi + +Also, add the following lines in an appropriate script which is +run during the Linux system shutdown: + +.nf + # Carry a random seed from shut-down to start-up for the random + # number generator. Save 512 bytes, which is the size of the + # random number generator's entropy pool. + echo "Saving random seed..." + dd if=/dev/urandom of=/var/random-seed count=1 +.fi +.SH "PROC INTERFACE" +The files in the directory +.I /proc/sys/kernel/random +(present since 2.3.16) provide an additional interface to the +.B /dev/random +device. +.LP +The read-only file +.I entropy_avail +gives the available entropy. Normally, this will be 4096 (bits), +a full entropy pool. +.LP +The file +.I poolsize +gives the size of the entropy pool. Normally, this will be 512 (bytes). +It can be changed to any value for which an algorithm is available. +Currently the choices are 32, 64, 128, 256, 512, 1024, 2048. +.LP +The file +.I read_wakeup_threshold +contains the number of bits of entropy required for waking up processes +that sleep waiting for entropy from +.BR /dev/random . +The default is 64. +The file +.I write_wakeup_threshold +contains the number of bits of entropy below which we wake up +processes that do a +.I select() +or +.I poll() +for write access to +.BR /dev/random . +These values can be changed by writing to the files. +.LP +The read-only files +.I uuid +and +.I boot_id +contain random strings like 6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9. +The former is generated afresh for each read, the latter was +generated once. +.SH FILES +/dev/random +.br +/dev/urandom +.SH AUTHOR +The kernel's random number generator was written by +Theodore Ts'o (tytso@athena.mit.edu). +.SH "SEE ALSO" +mknod (1) +.br +RFC 1750, "Randomness Recommendations for Security" diff --git a/man4/sd.4 b/man4/sd.4 new file mode 100644 index 000000000..391048fff --- /dev/null +++ b/man4/sd.4 @@ -0,0 +1,129 @@ +.\" sd.4 +.\" Copyright 1992 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH SD 4 1992-12-17 "" "Linux Programmer's Manual" +.SH NAME +sd \- Driver for SCSI Disk Drives +.SH SYNOPSIS +#include /* for HDIO_GETGEO */ +#include /* for BLKGETSIZE and BLKRRPART */ +.SH CONFIG +The block device name has the following form: +.BI sd lp, +where +.I l +is a letter denoting the physical drive, and +.I p +is a number denoting the partition on that physical drive. Often, the +partition number, +.IR p , +will be left off when the device corresponds to the whole drive. + +SCSI disks have a major device number of 8, and a minor device number of +the form (16 * +.IR drive_number ") + " partition_number , +where +.I drive_number +is the number of the physical drive in order of detection, and +.I partition_number +is as follows: +.sp +partition 0 is the whole drive +.br +partitions 1-4 are the DOS "primary" partitions +.br +partitions 5-8 are the DOS "extended" (or "logical") partitions + +For example, +.B /dev/sda +will have major 8, minor 0, and will refer to all of the first SCSI drive +in the system; and +.B /dev/sdb3 +will have major 8, minor 19, and will refer to the third DOS "primary" +partition on the second SCSI drive in the system. + +At this time, only block devices are provided. Raw devices have not yet +been implemented. +.SH DESCRIPTION +The following +.IR ioctl s +are provided: +.TP +HDIO_GETGEO +.RS +Returns the BIOS disk parameters in the following structure: +.RS +.nf +.ft B +struct hd_geometry { + unsigned char heads; + unsigned char sectors; + unsigned short cylinders; + unsigned long start; +}; +.ft R +.fi +.RE + +A pointer to this structure is passed as the +.BR ioctl (2) +parameter. + +The information returned in the parameter is the disk geometry of the drive +.I "as understood by DOS!" +This geometry is +.I not +the physical geometry of the drive. It is used when constructing the +drive's partition table, however, and is needed for convenient operation +of +.BR fdisk (1), +.BR efdisk (1), +and +.BR lilo (1). +If the geometry information is not available, zero will be returned for all +of the parameters. +.RE +.TP +BLKGETSIZE +Returns the device size in sectors. The +.BR ioctl (2) +parameter should be a pointer to a +.BR long . +.TP +BLKRRPART +Forces a re-read of the SCSI disk partition tables. No parameter is needed. + +The +.BR scsi (4) +.IR ioctl s +are also supported. If the +.BR ioctl (2) +parameter is required, and it is NULL, then +.IR ioctl () +will return -EINVAL. +.SH FILES +/dev/sd[a-h]: the whole device +.br +/dev/sd[a-h][0-8]: individual block partitions +.SH "SEE ALSO" +.BR scsi (4) diff --git a/man4/sk98lin.4 b/man4/sk98lin.4 new file mode 100644 index 000000000..73bdf6e87 --- /dev/null +++ b/man4/sk98lin.4 @@ -0,0 +1,461 @@ +.\" (C)Copyright 1999-2003 Marvell(R) -- linux@syskonnect.de +.\" sk98lin.4 1.1 2003/12/17 10:03:18 +.\" This manpage can be viewed using `groff -Tascii -man sk98lin.4 | less` +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH SK98LIN 4 "2003/12/17 10:03:18" "sk98lin 6.21" +.SH NAME +sk98lin \- Marvell/SysKonnect Gigabit Ethernet driver v6.21 +.SH SYNOPSIS +.B insmod sk98lin.o +.RB [ Speed_A=\c +.IR i,j,... ] +.RB [ Speed_B=\c +.IR i,j,... ] +.RB [ AutoNeg_A=\c +.IR i,j,... ] +.RB [ AutoNeg_B=\c +.IR i,j,... ] +.RB [ DupCap_A=\c +.IR i,j,... ] +.RB [ DupCap_B=\c +.IR i,j,... ] +.RB [ FlowCtrl_A=\c +.IR i,j,... ] +.RB [ FlowCtrl_B=\c +.IR i,j,... ] +.RB [ Role_A=\c +.IR i,j,... ] +.RB [ Role_B=\c +.IR i,j,... ] +.RB [ ConType=\c +.IR i,j,... ] +.RB [ Moderation=\c +.IR i,j,... ] +.RB [ IntsPerSec=\c +.IR i,j,... ] +.RB [ PrefPort=\c +.IR i,j,... ] +.RB [ RlmtMode=\c +.IR i,j,... ] +.SH DESCRIPTION +.B sk98lin +is the Gigabit Ethernet driver for Marvell and SysKonnect network adapter cards. +It supports SysKonnect SK-98xx/SK-95xx compliant Gigabit Ethernet Adapter and any Yukon compliant chipset. + +When loading the driver using insmod, parameters for the network adapter cards might be stated as a sequence of comma separated commands. If for instance two network adapters are installed and AutoNegotiation on Port A of the first adapter should be ON, but on the Port A of the second adapter switched OFF, one must enter: + + insmod sk98lin.o AutoNeg_A=On,Off + +After +.B sk98lin +is bound to one or more adapter cards and the +.IR /proc +filesystem is mounted on your system, a dedicated statistics file will be created in folder +.IR /proc/net/sk98lin +for all ports of the installed network adapter cards. Those files are named +.IR eth[x] +whereas +.IR x +is the number of the interface that has been assigned to a dedicated port by the system. + +If loading is finished, any desired IP address can be assigned to the respective +.IR eth[x] +interface using the +.BR ifconfig (8) +command. This causes the adapter to connect to the Ethernet and to display a status message on the console saying "ethx: network connection up using port y" followed by the configured or detected connection parameters. + +The +.B sk98lin +also supports large frames (also called jumbo frames). Using jumbo frames can improve throughput tremendously when transferring large amounts of data. To enable large frames, the MTU (maximum transfer unit) size for an interface is to be set to a high value. The default MTU size is 1500 and can be changed up to 9000 (bytes). Setting the MTU size can be done when assigning the IP address to the interface or later by using the +.BR ifconfig (8) +command with the mtu parameter. If for instance eth0 needs an IP address and a large frame MTU size, the following two commands might be used: + + ifconfig eth0 10.1.1.1 + ifconfig eth0 mtu 9000 + +Those two commands might even be combined into one: + + ifconfig eth0 10.1.1.1 mtu 9000 + +Note that large frames can only be used if your network infrastructure allows to do so. This means, that any switch being used in your Ethernet must also support large frames. Quite some switches support large frames, but need to be configured to do so. Most of the times, their default setting is to support only standard frames with an MTU size of 1500 (bytes). In addition to the switches inside the network, all network adapters that are to be used must also be enabled regarding jumbo frames. If an adapter is not set to receive large frames it will simply drop them. + +Switching back to the standard Ethernet frame size can be done by using the +.BR ifconfig (8) +command again: + + ifconfig eth0 mtu 1500 + +The Marvell/SysKonnect Gigabit Ethernet driver for Linux is able to support VLAN and Link Aggregation according to IEEE standards 802.1, 802.1q, and 802.3ad. Those features are only available after installation of open source modules which can be found on the Internet: + +.IR VLAN \c +: http://www.candelatech.com/~greear/vlan.html +.br +.IR Link +.IR Aggregation \c +: http://www.st.rim.or.jp/~yumo + +.br +Note that Marvell/SysKonnect does not offer any support for these open source modules and does not take the responsibility for any kind of failures or problems arising when using these modules. +.SH PARAMETERS +.TP +.BI Speed_A= i,j,... +This parameter is used to set the speed capabilities of port A of an adapter card. It is only valid for Yukon copper adapters. Possible values are: +.IR 10 +, +.IR 100 +, +.IR 1000 +or +.IR Auto +whereas +.IR Auto +is the default. Usually, the speed is negotiated between the two ports during link establishment. If this fails, a port can be forced to a specific setting with this parameter. +.TP +.BI Speed_B= i,j,... +This parameter is used to set the speed capabilities of port B of an adapter card. It is only valid for Yukon copper adapters. Possible values are: +.IR 10 +, +.IR 100 +, +.IR 1000 +or +.IR Auto +whereas +.IR Auto +is the default. Usually, the speed is negotiated between the two ports during link establishment. If this fails, a port can be forced to a specific setting with this parameter. +.TP +.BI AutoNeg_A= i,j,... +Enables or disables the use of autonegotiation of port A of an adapter card. Possible values are: +.IR On +, +.IR Off +or +.IR Sense +whereas +.IR On +is the default. The +.IR Sense +mode automatically detects whether the link partner supports auto-negotiation or not. +.TP +.BI AutoNeg_B= i,j,... +Enables or disables the use of autonegotiation of port B of an adapter card. Possible values are: +.IR On +, +.IR Off +or +.IR Sense +whereas +.IR On +is the default. The +.IR Sense +mode automatically detects whether the link partner supports auto-negotiation or not. +.TP +.BI DupCap_A= i,j,... +This parameter indicates the duplex mode to be used for port A of an adapter card. Possible values are: +.IR Half +, +.IR Full +or +.IR Both +whereas +.IR Both +is the default. This parameter is only relevant if AutoNeg_A of port A is not set to +.IR Sense. +If AutoNeg_A is set to +.IR On +, all three values of DupCap_A ( +.IR Half +, +.IR Full +or +.IR Both +) might be stated. If AutoNeg_A is set to +.IR Off +, only DupCap_A values +.IR Full +and +.IR Half +are allowed. This DupCap_A parameter is useful if your link partner does not support all possible duplex combinations. +.TP +.BI DupCap_B= i,j,... +This parameter indicates the duplex mode to be used for port B of an adapter card. Possible values are: +.IR Half +, +.IR Full +or +.IR Both +whereas +.IR Both +is the default. This parameter is only relevant if AutoNeg_B of port B is not set to +.IR Sense. +If AutoNeg_B is set to +.IR On +, all three values of DupCap_B ( +.IR Half +, +.IR Full +or +.IR Both +) might be stated. If AutoNeg_B is set to +.IR Off +, only DupCap_B values +.IR Full +and +.IR Half +are allowed. This DupCap_B parameter is useful if your link partner does not support all possible duplex combinations. +.TP +.BI FlowCtrl_A= i,j,... +This parameter can be used to set the flow control capabilities the port reports during auto-negotiation. Possible values are: +.IR Sym +, +.IR SymOrRem +, +.IR LocSend +or +.IR None +whereas +.IR SymOrRem +is the default. The different modes have the following meaning: + +.br +.IR Sym += Symmetric + both link partners are allowed to send PAUSE frames +.br +.IR SymOrRem += SymmetricOrRemote + both or only remote partner are allowed to send PAUSE frames +.br +.IR LocSend += LocalSend + only local link partner is allowed to send PAUSE frames +.br +.IR None += None + no link partner is allowed to send PAUSE frames + +Note that this parameter is ignored if AutoNeg_A is set to +.IR Off . +.TP +.BI FlowCtrl_B= i,j,... +This parameter can be used to set the flow control capabilities the port reports during auto-negotiation. Possible values are: +.IR Sym +, +.IR SymOrRem +, +.IR LocSend +or +.IR None +whereas +.IR SymOrRem +is the default. The different modes have the following meaning: + +.IR Sym += Symmetric + both link partners are allowed to send PAUSE frames +.br +.IR SymOrRem += SymmetricOrRemote + both or only remote partner are allowed to send PAUSE frames +.br +.IR LocSend += LocalSend + only local link partner is allowed to send PAUSE frames +.br +.IR None += None + no link partner is allowed to send PAUSE frames +.br + +Note that this parameter is ignored if AutoNeg_B is set to +.IR Off . +.TP +.BI Role_A= i,j,... +This parameter is only valid for 1000Base-T adapter cards. For two 1000Base-T ports to communicate, one must take the role of the master (providing timing information), while the other must be the slave. Possible values are: +.IR Auto +, +.IR Master +or +.IR Slave +whereas +.IR Auto +is the default. Usually, the role of a port is negotiated between two ports during link establishment, but if that fails the port A of an adapter card can be forced to a specific setting with this parameter. +.TP +.BI Role_B= i,j,... +This parameter is only valid for 1000Base-T adapter cards. For two 1000Base-T ports to communicate, one must take the role of the master (providing timing information), while the other must be the slave. Possible values are: +.IR Auto +, +.IR Master +or +.IR Slave +whereas +.IR Auto +is the default. Usually, the role of a port is negotiated between two ports during link establishment, but if that fails the port B of an adapter card can be forced to a specific setting with this parameter. +.TP +.BI ConType= i,j,... +This parameter is a combination of all five per-port parameters within one single parameter. This simplifies the configuration of both ports of an adapter card. The different values of this variable reflect the most meaningful combinations of port parameters. Possible values and their corresponding combination of per-port parameters: + +.br +.ad l +ConType | DupCap AutoNeg FlowCtrl Role Speed +--------+------------------------------------------- +.br +.IR Auto \c + | Both On SymOrRem Auto Auto +.br +.IR 100FD \c + | Full Off None Auto 100 +.br +.IR 100HD \c + | Half Off None Auto 100 +.br +.IR 10FD \c + | Full Off None Auto 10 +.br +.IR 10HD \c + | Half Off None Auto 10 + +.ad b +Stating any other port parameter together with this +.IR ConType +parameter will result in a merged configuration of those settings. This is due to +the fact, that the per-port parameters (e.g. +.IR Speed_A +) have a higher priority than the combined variable +.IR ConType +. +.TP +.BI Moderation= i,j,... +Interrupt moderation is employed to limit the maximum number of interrupts the driver has to serve. That is, one or more interrupts (which indicate any transmit or receive packet to be processed) are queued until the driver processes them. When queued interrupts are to be served, is determined by the +.IR IntsPerSec +parameter, which is explained later below. Possible moderation modes are: +.IR None +, +.IR Static +or +.IR Dynamic +whereas +.IR None +is the default. The different modes have the following meaning: + +.IR None +No interrupt moderation is applied on the adapter card. Therefore, each transmit or receive interrupt is served immediately as soon as it appears on the interrupt line of the adapter card. + +.br +.IR Static +Interrupt moderation is applied on the adapter card. All transmit and receive interrupts are queued until a complete moderation interval ends. If such a moderation interval ends, all queued interrupts are processed in one big bunch without any delay. The term +.IR Static +reflects the fact, that interrupt moderation is always enabled, regardless how much network load is currently passing via a particular interface. In addition, the duration of the moderation interval has a fixed length that never changes while the driver is operational. + +.br +.IR Dynamic +Interrupt moderation might be applied on the adapter card, depending on the load of the system. If the driver detects that the system load is too high, the driver tries to shield the system against too much network load by enabling interrupt moderation. If - at a later time - the CPU utilization decreases again (or if the network load is negligible) the interrupt moderation will automatically be disabled. + +Interrupt moderation should be used when the driver has to handle one or more interfaces with a high network load, which - as a consequence - leads also to a high CPU utilization. When moderation is applied in such high network load situations, CPU load might be reduced by 20-30% on slow computers. + +Note that the drawback of using interrupt moderation is an increase of the round-trip-time (RTT), due to the queuing and serving of interrupts at dedicated +moderation times. +.TP +.BI IntsPerSec= i,j,... +This parameter determines the length of any interrupt moderation interval. +Assuming that static interrupt moderation is to be used, an +.IR IntsPerSec +parameter value of 2000 will lead to an interrupt moderation interval of +500 microseconds. Possible values for this parameter are in the range of 30...40000 (interrupts per second). The default value is 2000. + +This parameter is only used, if either static or dynamic interrupt moderation +is enabled on a network adapter card. This parameter is ignored if no moderation is +applied. + +Note that the duration of the moderation interval is to be chosen with care. +At first glance, selecting a very long duration (e.g. only 100 interrupts per +second) seems to be meaningful, but the increase of packet-processing delay +is tremendous. On the other hand, selecting a very short moderation time might +compensate the use of any moderation being applied. +.TP +.BI PrefPort= i,j,... +This parameter is used to force the preferred port to A or B (on dual-port network adapters). The preferred port is the one that is used if both ports A and B are detected as fully functional. Possible values are: +.IR A +or +.IR B +whereas +.IR A +is the default. +.TP +.BI RlmtMode= i,j,... +RLMT monitors the status of the port. If the link of the active port fails, RLMT switches immediately to the standby link. The virtual link is maintained as long as at least one 'physical' link is up. This parameters states how RLMT should monitor both ports. Possible values are: +.IR CheckLinkState +, +.IR CheckLocalPort +, +.IR CheckSeg +or +.IR DualNet +whereas +.IR CheckLinkState +is the default. The different modes have the following meaning: + +.IR CheckLinkState +Check link state only: RLMT uses the link state reported by the adapter hardware for each individual port to determine whether a port can be used for all network traffic or not. + +.br +.IR CheckLocalPort +In this mode, RLMT monitors the network path between the two ports of an adapter by regularly exchanging packets between them. This mode requires a network configuration in which the two ports are able to "see" each other (i.e. there must not be any router between the ports). + +.br +.IR CheckSeg +Check local port and segmentation: This mode supports the same functions as the CheckLocalPort mode and additionally checks network segmentation between the ports. Therefore, this mode is only to be used if Gigabit Ethernet switches are installed on the network that have been configured to use the Spanning Tree protocol. + +.br +.IR DualNet +In this mode, ports A and B are used as separate devices. If you have a dual port adapter, port A will be configured as +.IR eth[x] and port B as +.IR eth[x+1] +. Both ports can be used independently with distinct IP addresses. The preferred port setting is not used. RLMT is turned off. + +Note that RLMT modes +.IR CheckLocalPort +and +.IR CheckLinkState +are designed to operate in configurations where a network path between the ports on one adapter exists. Moreover, they are not designed to work where adapters are connected back-to-back. +.SH FILES +.TP +.B /proc/net/sk98lin/eth[x] +.br +The statistics file of a particular interface of an adapter card. It contains generic information about the adapter card plus a detailed summary of all transmit and receive counters. +.TP +.B /usr/src/linux/Documentation/network/sk98lin.txt +.br +This is the +.IR README +file of the +.IR sk98lin +driver. It contains a detailed installation HOWTO and describes all parameters of the driver. It denotes also common problems and provides the solution to them. +.SH BUGS +Report any bugs to linux@syskonnect.de +.SH AUTHORS +Ralph Roesler \- rroesler@syskonnect.de +.br +Mirko Lindner \- mlindner@syskonnect.de +.SH "SEE ALSO" +modprobe(8), insmod(8), ifconfig(8). diff --git a/man4/st.4 b/man4/st.4 new file mode 100644 index 000000000..bf5095485 --- /dev/null +++ b/man4/st.4 @@ -0,0 +1,691 @@ +.\" Copyright 1995 Robert K. Nichols (Robert.K.Nichols@att.com) +.\" Copyright 1999 Kai Mäkisara (Kai.Makisara@metla.fi) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.TH ST 4 1999-01-18 "Linux 2.0 - 2.2" "Linux Programmer's Manual" +.SH NAME +st \- SCSI tape device +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int ioctl(int " fd ", int " request " [, (void *)" arg3 "]);" +.BI "int ioctl(int " fd ", \s-1MTIOCTOP\s+1, (struct mtop *)" mt_cmd ); +.BI "int ioctl(int " fd ", \s-1MTIOCGET\s+1, (struct mtget *)" mt_status ); +.BI "int ioctl(int " fd ", \s-1MTIOCPOS\s+1, (struct mtpos *)" mt_pos ); +.fi +.SH DESCRIPTION +The +.B st +driver provides the interface to a variety of SCSI tape devices. +Currently, the driver takes control of all detected devices of type +\(lqsequential-access.\(rq +The +.B st +driver uses major device number 9. +.PP +Each device uses eight minor device numbers. The lower-most five bits +in the minor numbers are assigned sequentially in the order of +detection. The minor numbers can be grouped into +two sets of four numbers: the principal (auto-rewind) minor device numbers, +.IR n , +and a \(lqno-rewind\(rq device numbers, +.IR "" ( n "+ 128)." +Devices opened using the principal device number will be sent a +\s-1REWIND\s+1 command when they are closed. +Devices opened using the \(lqno-rewind\(rq device number will not. +(Note that using an auto-rewind device for positioning the tape with, +for instance, mt does not lead to the desired result: the tape is +rewound after the mt command and the next command starts from the +beginning of the tape). +.PP +Within each group, four minor numbers are available to define +devices with different characteristics (block size, compression, +density, etc.) When the system starts up, only the first device is +available. The other three are activated when the default +characteristics are defined (see below). (By changing compile-time +constants, it is possible to change the balance between the maximum +number of tape drives and the number of minor numbers for each +drive. The default allocation allows control of 32 tape drives. +For instance, it is possible to control up to 64 tape drives +with two minor numbers for different options.) +.PP +Devices are typically created by: +.RS +.nf +mknod -m 666 /dev/st0 c 9 0 +mknod -m 666 /dev/st0l c 9 32 +mknod -m 666 /dev/st0m c 9 64 +mknod -m 666 /dev/st0a c 9 96 +mknod -m 666 /dev/nst0 c 9 128 +mknod -m 666 /dev/nst0l c 9 160 +mknod -m 666 /dev/nst0m c 9 192 +mknod -m 666 /dev/nst0a c 9 224 +.fi +.RE +.PP +There is no corresponding block device. +.PP +The driver uses an internal buffer that has to be large enough to hold +at least one tape block. In kernels before 2.1.121, the buffer is +allocated as one contiguous block. This limits the block size to the +largest contiguous block of memory the kernel allocator can provide. +The limit is currently 128 kB for the 32-bit architectures and +256 kB for the 64-bit architectures. In newer kernels the driver +allocates the buffer in several parts if necessary. By default, the +maximum number of parts is 16. This means that the maximum block size +is very large (2 MB if allocation of 16 blocks of 128 kB succeeds). +.PP +The driver's internal buffer size is determined by a compile-time +constant which can be overridden with a kernel startup option. +In addition to this, the driver tries to allocate a larger temporary +buffer at run-time if necessary. However, run-time allocation of large +contiguous blocks of memory may fail and it is advisable not to rely +too much on dynamic buffer allocation with kernels older than 2.1.121 +(this applies also to demand-loading the driver with kerneld or kmod). +.PP +The driver does not specifically support any tape drive brand or +model. After system start-up the tape device options are defined by +the drive firmware. For example, if the drive firmware selects fixed +block mode, the tape device uses fixed block mode. The options can +be changed with explicit +.B ioctl() +calls and remain in effect when the device is closed and reopened. +Setting the options affects both the auto-rewind and the non-rewind +device. +.PP +Different options can be specified for the different devices within +the subgroup of four. The options take effect when the device is +opened. For example, the system administrator can define +one device that writes in fixed block mode with a certain block size, +and one which writes in variable block mode (if the drive supports +both modes). +.PP +The driver supports +.B tape partitions +if they are supported by the drive. (Note that the tape partitions +have nothing to do with disk partitions. A partitioned tape can be +seen as several logical tapes within one medium.) Partition +support has to be enabled with an ioctl. The tape +location is preserved within each partition across partition changes. +The partition used for subsequent tape operations is +selected with an ioctl. The partition switch is executed together with +the next tape operation in order to avoid unnecessary tape +movement. The maximum number of partitions on a tape is defined by a +compile-time constant (originally four). The driver contains an +ioctl that can format a tape with either one or two partitions. +.PP +Device +.B /dev/tape +is usually created as a hard or soft link to the default tape device +on the system. +.SH "DATA TRANSFER" +The driver supports operation in both fixed block mode and variable +block mode (if supported by the drive). In fixed block mode the drive +writes blocks of the specified size and the block size is not +dependent on the byte counts of the write system calls. In variable +block mode one tape block is written for each write call and the byte +count determines the size of the corresponding tape block. Note that +the blocks on the tape do don't contain any information about the +writing mode: when reading, the only important thing is to use +commands that accept the block sizes on the tape. +.PP +In variable block mode the read byte count does not have to match +the tape block size exactly. If the byte count is larger than the +next block on tape, the driver returns the data and the function +returns the actual block size. If the block size is larger than the +byte count, the requested amount of data from the start of the block +is returned and the rest of the block is discarded. +.PP +In fixed block mode the read byte counts can be arbitrary if +buffering is enabled, or a multiple of the tape block size if +buffering is disabled. Kernels before 2.1.121 allow writes with +arbitrary byte count if buffering is enabled. In all other cases +(kernel before 2.1.121 with buffering disabled or newer kernel) the +write byte count must be a multiple of the tape block size. +.PP +A filemark is automatically written to tape if the last tape operation +before close was a write. +.PP +When a filemark is encountered while reading, the following +happens. If there are data remaining in the buffer when the filemark +is found, the buffered data is returned. The next read returns zero +bytes. The following read returns data from the next file. The end of +recorded data is signaled by returning zero bytes for two consecutive +read calls. The third read returns an error. +.SH IOCTLS +The driver supports three ioctl requests. +Requests not recognized by the +.B st +driver are passed to the +.B SCSI +driver. +The definitions below are from +.BR /usr/include/linux/mtio.h : +.SS "\s-1MTIOCTOP\s+1 \- Perform a tape operation" +.PP +This request takes an argument of type +.BR "(struct mtop *)" . +Not all drives support all operations. +The driver returns an EIO error if the drive rejects an operation. +.PP +.nf +.ta +.4i +.7i +1i +/* Structure for \s-1MTIOCTOP\s+1 \- mag tape op command: */ +struct mtop { + short mt_op; /* operations defined below */ + int mt_count; /* how many of them */ +}; +.fi +.PP +Magnetic Tape operations for normal tape use: +.PD 0 +.IP MTBSF 14 +Backward space over +.B mt_count +filemarks. +.IP MTBSFM +Backward space over +.B mt_count +filemarks. +Reposition the tape to the EOT side of the last filemark. +.IP MTBSR +Backward space over +.B mt_count +records (tape blocks). +.IP MTBSS +Backward space over +.B mt_count +setmarks. +.IP MTCOMPRESSION +Enable compression of tape data within the drive if +.B mt_count +is non-zero and disable compression if +.B mt_count +is zero. This command uses the MODE page 15 supported by most DATs. +.IP MTEOM +Go to the end of the recorded media (for appending files). +.IP MTERASE +Erase tape. +.IP MTFSF +Forward space over +.B mt_count +filemarks. +.IP MTFSFM +Forward space over +.B mt_count +filemarks. +Reposition the tape to the BOT side of the last filemark. +.IP MTFSR +Forward space over +.B mt_count +records (tape blocks). +.IP MTFSS +Forward space over +.B mt_count +setmarks. +.IP MTLOAD +Execute the SCSI load command. A special case is available for some HP +autoloaders. If +.B mt_count +is the constant MT_ST_HPLOADER_OFFSET plus a number, the number is +sent to the drive to control the autoloader. +.IP MTLOCK +Lock the tape drive door. +.IP MTMKPART +Format the tape into one or two partitions. If +.B mt_count +is non-zero, it gives the size of the first partition and the second +partition contains the rest of the tape. If +.B mt_count +is zero, the tape is formatted into one partition. +This command is not allowed for a drive unless the partition support +is enabled for the drive (see MT_ST_CAN_PARTITIONS below). +.IP MTNOP +No op \- flushes the driver's buffer as a side effect. +Should be used before reading status with \s-1MTIOCGET\s+1. +.IP MTOFFL +Rewind and put the drive off line. +.IP MTRESET +Reset drive. +.IP MTRETEN +Retension tape. +.IP MTREW +Rewind. +.IP MTSEEK +Seek to the tape block number specified in +.BR mt_count . +This operation requires either a SCSI-2 drive that supports the \s-1LOCATE\s+1 +command (device-specific address) +or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive +Viper, Wangtek, ... ). +The block number should be one that was previously returned by +\s-1MTIOCPOS\s+1 if device-specific addresses are used. +.IP MTSETBLK +Set the drive's block length to the value specified in +.BR mt_count . +A block length of zero sets the drive to variable block size mode. +.IP MTSETDENSITY +Set the tape density to the code in +.BR mt_count . +The density codes supported by a drive can be found from the drive +documentation. +.IP MTSETPART +The active partition is switched to +.B mt_count . +The partitions are numbered from zero. This command is not allowed for +a drive unless the partition support is enabled for the drive (see +MT_ST_CAN_PARTITIONS below). +.IP MTUNLOAD +Execute the SCSI unload command (does not eject the tape). +.IP MTUNLOCK +Unlock the tape drive door. +.IP MTWEOF +Write +.B mt_count +filemarks. +.IP MTWSM +Write +.B mt_count +setmarks. +.PD +.PP +Magnetic Tape operations for setting of device options (by the superuser): +.PD 0 +.IP MTSETDRVBUFFER 8 +Set various drive and driver options according to bits encoded in +.BR mt_count . +These consist of the drive's buffering mode, 13 Boolean driver +options, the buffer write threshold, defaults for the block size and +density, and timeouts (only in kernels >= 2.1). +A single operation can affect only one item in the list above (the +Booleans counted as one item.) +.PD +.IP +A value having zeros in the high-order 4 bits will be used to set the +drive's buffering mode. +The buffering modes are: +.RS 12 +.IP 0 4 +The drive will not report \s-1GOOD\s+1 status on write commands until the data +blocks are actually written to the medium. +.PD 0 +.IP 1 +The drive may report \s-1GOOD\s+1 status on write commands as soon as all the +data has been transferred to the drive's internal buffer. +.IP 2 +The drive may report \s-1GOOD\s+1 status on write commands as soon as (a) all +the data has been transferred to the drive's internal buffer, and +(b) all buffered data from different initiators has been successfully +written to the medium. +.PD +.RE +.IP "" +To control the write threshold the value in +.B mt_count +must include the constant +\s-1MT_ST_WRITE_THRESHOLD\s+1 logically ORed with a block count in the low 28 +bits. +The block count refers to 1024-byte blocks, not the physical block +size on the tape. +The threshold cannot exceed the driver's internal buffer size (see +.BR \s-1DESCRIPTION\s+1 , +above). +.IP +To set and clear the Boolean options +the value in +.B mt_count +must include one the constants \s-1MT_ST_BOOLEANS\s+1, +\s-1MT_ST_SETBOOLEANS\s+1, \s-1MT_ST_CLEARBOOLEANS\s+1, or +\s-1MT_ST_DEFBOOLEANS\s+1 logically ORed with +whatever combination of the following options is desired. +Using \s-1MT_ST_BOOLEANS\s+1 the options can be set to the values +defined in the corresponding bits. With \s-1MT_ST_SETBOOLEANS\s+1 the +options can be selectively set and with \s-1MT_ST_DEFBOOLEANS\s+1 +selectively cleared. +.IP "" +The default options for a tape device are set with +\s-1MT_ST_DEFBOOLEANS\s+1. A non-active tape device (e.g., device with +minor 32 or 160) is activated when the default options for it are +defined the first time. An activated device inherits from the device +activated at start-up the options not set explicitly. +.IP "" +The Boolean options are: +.IP +.PD 0 +.RS +.IP "\s-1MT_ST_BUFFER_WRITES\s+1 (Default: true)" +Buffer all write operations in fixed block mode. +If this option is false and the drive uses a fixed block size, then +all write operations must be for a multiple of the block size. +This option must be set false to write reliable multi-volume archives. +.IP "\s-1MT_ST_ASYNC_WRITES\s+1 (Default: true)" +When this options is true write operations return immediately without +waiting for the data to be transferred to the drive if the data fits +into the driver's buffer. +The write threshold determines how full the buffer must be before a +new SCSI write command is issued. +Any errors reported by the drive will be held until the next +operation. +This option must be set false to write reliable multi-volume archives. +.IP "\s-1MT_ST_READ_AHEAD\s+1 (Default: true)" +This option causes the driver to provide read buffering and +read-ahead in fixed block mode. +If this option is false and the drive uses a fixed block size, then +all read operations must be for a multiple of the block size. +.IP "\s-1MT_ST_TWO_FM\s+1 (Default: false)" +This option modifies the driver behavior when a file is closed. +The normal action is to write a single filemark. +If the option is true the driver will write two filemarks and +backspace over the second one. +.PD +.IP +Note: +This option should not be set true for QIC tape drives since they are +unable to overwrite a filemark. +These drives detect the end of recorded data by testing for blank tape +rather than two consecutive filemarks. Most other current drives also +detect the end of recorded data and using two filemarks is usually +necessary only when interchanging tapes with some other systems. +.PP +.PD 0 +.IP "\s-1MT_ST_DEBUGGING\s+1 (Default: false)" +This option turns on various debugging messages from the driver +(effective only if the driver was compiled with \s-1DEBUG\s+1 defined +non-zero). +.IP "\s-1MT_ST_FAST_EOM\s+1 (Default: false)" +This option causes the \s-1MTEOM\s+1 operation to be sent directly to the +drive, potentially speeding up the operation but causing the driver to +lose track of the current file number normally returned by the +\s-1MTIOCGET\s+1 request. +If \s-1MT_ST_FAST_EOM\s+1 is false the driver will respond to an +\s-1MTEOM\s+1 request by forward spacing over files. +.IP "\s-1MT_ST_AUTO_LOCK\s+1 (Default: false)" +When this option is true, the drive door is locked when the device is +opened and unlocked when it is closed. +.IP "\s-1MT_ST_DEF_WRITES\s+1 (Default: false)" +The tape options (block size, mode, compression, etc.) may change +when changing from one device linked to a drive to another device +linked to the same drive depending on how the devices are +defined. This option defines when the changes are enforced by the +driver using SCSI-commands and when the drives auto-detection +capabilities are relied upon. If this option is false, the driver +sends the SCSI-commands immediately when the device is changed. If the +option is true, the SCSI-commands are not sent until a write is +requested. In this case the drive firmware is allowed to detect the +tape structure when reading and the SCSI-commands are used only to +make sure that a tape is written according to the correct specification. +.IP "\s-1MT_ST_CAN_BSR\s+1 (Default: false)" +When read-ahead is used, the tape must sometimes be spaced backward to the +correct position when the device is closed and the SCSI command to +space backwards over records is used for this purpose. Some older +drives can't process this command reliably and this option can be used +to instruct the driver not to use the command. The end result is that, +with read-ahead and fixed block mode, the tape may not be correctly +positioned within a file when the device is closed. +.IP "\s-1MT_ST_NO_BLKLIMS\s+1 (Default: false)" +Some drives don't accept the READ BLOCK LIMITS SCSI command. If +this is used, the driver does not use the command. The drawback is +that the driver can't check before sending commands if the selected +block size is acceptable to the drive. +.IP "\s-1MT_ST_CAN_PARTITIONS\s+1 (Default: false)" +This option enables support for several partitions within a +tape. The option applies to all devices linked to a drive. +.IP "\s-1MT_ST_SCSI2LOGICAL\s+1 (Default: false)" +This option instructs the driver to use the logical block addresses +defined in the SCSI-2 standard when performing the seek and tell +operations (both with MTSEEK and MTIOCPOS commands and when changing tape +partition). Otherwise the device-specific addresses are used. +It is highly advisable to set this option if the drive supports the +logical addresses because they count also filemarks. There are some +drives that only support the logical block addresses. +.IP "\s-1MT_ST_SYSV\s+1 (Default: false)" +When this option is enabled, the tape devices use the SystemV +semantics. Otherwise the BSD semantics are used. The most important +difference between the semantics is what happens when a device used +for reading is closed: in SYSV semantics the tape is spaced forward +past the next filemark if this has not happened while using the +device. In BSD semantics the tape position is not changed. +.IP \s-1EXAMPLE\s+1 +.nf +.ta +.4i +.7i +1i +.BI "struct mtop " mt_cmd ; +.IB "mt_cmd.mt_op" " = \s-1MTSETDRVBUFFER\s+1;" +.IB "mt_cmd.mt_count" " = \s-1MT_ST_BOOLEANS\s+1 |" +.B " \s-1MT_ST_BUFFER_WRITES\s+1 |" +.B " \s-1MT_ST_ASYNC_WRITES\s+1;" +.BI "ioctl(" fd ", \s-1MTIOCTOP\s+1, &" mt_cmd ");" +.fi +.RE +.PD +.IP "" +The default block size for a device can be set with +\s-1MT_ST_DEF_BLKSIZE\s+1 and the default density code can be set with +\s-1MT_ST_DEFDENSITY\s+1. The values for the parameters are ORed +with the operation code. +.IP "" +With kernels 2.1.x and later, the timeout values can be set with the +subcommand \s-1MT_ST_SET_TIMEOUT\s+1 or'ed with the timeout in seconds. +The long timeout (used for rewinds and other commands +that may take a long time) can be set with +\s-1MT_ST_SET_LONG_TIMEOUT\s+1. The kernel defaults are very long to +make sure that a successful command is not timed out with any +drive. Because of this the driver may seem stuck even if it is only +waiting for the timeout. These commands can be used to set more +practical values for a specific drive. The timeouts set for one device +apply for all devices linked to the same drive. +.SS "\s-1MTIOCGET\s+1 \- Get status" +.PP +This request takes an argument of type +.BR "(struct mtget *)" . +.PP +.nf +/* structure for \s-1MTIOCGET\s+1 - mag tape get status command */ +struct mtget { + long mt_type; + long mt_resid; + /* the following registers are device dependent */ + long mt_dsreg; + long mt_gstat; + long mt_erreg; + /* The next two fields are not always used */ + daddr_t mt_fileno; + daddr_t mt_blkno; +}; +.fi +.IP \fBmt_type\fP 11 +The header file defines many values for +.BR mt_type , +but the current driver reports only the generic types +\s-1MT_ISSCSI1\s+1 (Generic SCSI-1 tape) and \s-1MT_ISSCSI2\s+1 (Generic SCSI-2 tape). +.PD 0 +.IP \fBmt_resid\fP +contains the current tape partition number. +.IP \fBmt_dsreg\fP +reports the drive's current settings for block size (in the low 24 +bits) and density (in the high 8 bits). +These fields are defined by \s-1MT_ST_BLKSIZE_SHIFT\s+1, \s-1MT_ST_BLKSIZE_MASK\s+1, +\s-1MT_ST_DENSITY_SHIFT\s+1, and \s-1MT_ST_DENSITY_MASK\s+1. +.IP \fBmt_gstat\fP +reports generic (device independent) status information. +The header file defines macros for testing these status bits: +.RS +.HP 4 +\s-1GMT_EOF(\s+1\fIx\fP\s-1)\s+1: +The tape is positioned just after a filemark +(always false after an \s-1MTSEEK\s+1 operation). +.HP +\s-1GMT_BOT(\s+1\fIx\fP\s-1)\s+1: +The tape is positioned at the beginning of the first file (always false +after an \s-1MTSEEK\s+1 operation). +.HP +\s-1GMT_EOT(\s+1\fIx\fP\s-1)\s+1: +A tape operation has reached the physical End Of Tape. +.HP +\s-1GMT_SM(\s+1\fIx\fP\s-1)\s+1: +The tape is currently positioned at a setmark +(always false after an \s-1MTSEEK\s+1 operation). +.HP +\s-1GMT_EOD(\s+1\fIx\fP\s-1)\s+1: +The tape is positioned at the end of recorded data. +.HP +\s-1GMT_WR_PROT(\s+1\fIx\fP\s-1)\s+1: +The drive is write-protected. +For some drives this can also mean that the drive does not support +writing on the current medium type. +.HP +\s-1GMT_ONLINE(\s+1\fIx\fP\s-1)\s+1: +The last +.B open() +found the drive with a tape in place and ready for operation. +.HP +\s-1GMT_D_6250(\s+1\fIx\fP\s-1)\s+1, \s-1GMT_D_1600(\s+1\fIx\fP\s-1)\s+1, \s-1GMT_D_800(\s+1\fIx\fP\s-1)\s+1: +This \(lqgeneric\(rq status information reports the current +density setting for 9-track \(12" tape drives only. +.HP +\s-1GMT_DR_OPEN(\s+1\fIx\fP\s-1)\s+1: +The drive does not have a tape in place. +.HP +\s-1GMT_IM_REP_EN(\s+1\fIx\fP\s-1)\s+1: +Immediate report mode. This bit is set if there are no guarantees that +the data has been physically written to the tape when the write call +returns. It is set zero only when the driver does not buffer data and +the drive is set not to buffer data. +.RE +.IP \fBmt_erreg\fP +The only field defined in +.B mt_erreg +is the recovered error count in the low 16 bits (as defined by +\s-1MT_ST_SOFTERR_SHIFT\s+1 and \s-1MT_ST_SOFTERR_MASK\s+1). +Due to inconsistencies in the way drives report recovered errors, this +count is often not maintained (most drives do not by default report +soft errors but this can be changed with a SCSI MODE SELECT command). +.IP \fBmt_fileno\fP +reports the current file number (zero-based). +This value is set to \-1 when the file number is unknown (e.g., after +\s-1MTBSS\s+1 +or \s-1MTSEEK\s+1). +.IP \fBmt_blkno\fP +reports the block number (zero-based) within the current file. +This value is set to \-1 when the block number is unknown (e.g., after +\s-1MTBSF\s+1, +\s-1MTBSS\s+1, or \s-1MTSEEK\s+1). +.PD +.SS "\s-1MTIOCPOS\s+1 \- Get tape position" +.PP +This request takes an argument of type +.B "(struct mtpos *)" +and reports the drive's notion of the current tape block number, +which is not the same as +.B mt_blkno +returned by \s-1MTIOCGET\s+1. +This drive must be a SCSI-2 drive that supports the \s-1READ POSITION\s+1 +command (device-specific address) +or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive +Viper, Wangtek, ... ). +.PP +.nf +/* structure for \s-1MTIOCPOS\s+1 - mag tape get position command */ +struct mtpos { + long mt_blkno; /* current block number */ +}; + +.fi +.SH "RETURN VALUE" +.IP EIO 14 +The requested operation could not be completed. +.IP ENOSPC +A write operation could not be completed because the tape reached +end-of-medium. +.IP EACCES +An attempt was made to write or erase a write-protected tape. +(This error is not detected during +.BR open() .) +.IP EFAULT +The command parameters point to memory not belonging to the calling +process. +.IP ENXIO +During opening, the tape device does not exist. +.IP EBUSY +The device is already in use or the driver was unable to allocate a +buffer. +.IP EOVERFLOW +An attempt was made to read or write a variable-length block that is +larger than the driver's internal buffer. +.IP EINVAL +An +.B ioctl() +had an illegal argument, or a requested block size was illegal. +.IP ENOSYS +Unknown +.BR ioctl() . +.IP EROFS +Open is attempted with O_WRONLY or O_RDWR when the tape in the drive is +write-protected. +.SH FILES +/dev/st* : the auto-rewind SCSI tape devices +.br +/dev/nst* : the non-rewind SCSI tape devices +.SH AUTHOR +The driver has been written by Kai M\(:akisara (Kai.Makisara@metla.fi) +starting from a driver written by Dwayne Forsyth. Several other +people have also contributed to the driver. +.SH "SEE ALSO" +.BR mt (1) +.PP +The file README.st in the kernel sources contains the most recent +information about the driver and its configuration +possibilities. +.SH NOTES +1. When exchanging data between systems, both systems have to agree on +the physical tape block size. The parameters of a drive after startup +are often not the ones most operating systems use with these +devices. Most systems use drives in variable block mode if the drive +supports that mode. This applies to most modern drives, including +DATs, 8mm helical scan drives, DLTs, etc. It may be advisable use +these drives in variable block mode also in Linux (i.e., use MTSETBLK +or MTSETDEFBLK at system startup to set the mode), at least when +exchanging data with foreign system. The drawback of +this is that a fairly large tape block size has to be used to get +acceptable data transfer rates on the SCSI bus. +.PP +2. Many programs (e.g., tar) allow the user to specify the blocking +factor on command line. Note that this determines the physical block +size on tape only in variable block mode. +.PP +3. In order to use SCSI tape drives, the basic SCSI driver, +a SCSI-adapter driver and the SCSI tape driver must be either +configured into the kernel or loaded as modules. If the SCSI-tape +driver is not present, the drive is recognized but the tape support +described in this page is not available. +.PP +4. The driver writes error messages to the console/log. The SENSE +codes written into some messages are automatically translated to text +if verbose SCSI messages are enabled in kernel configuration. +.SH COPYRIGHT +Copyright \(co 1995 Robert K. Nichols. +.br +Copyright \(co 1999 Kai M\(:akisara. +.PP +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. +Additional permissions are contained in the header of the source file. diff --git a/man4/tty.4 b/man4/tty.4 new file mode 100644 index 000000000..08852df7d --- /dev/null +++ b/man4/tty.4 @@ -0,0 +1,59 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2003-04-07 by Michael Kerrisk +.\" +.TH TTY 4 2003-04-07 "Linux" "Linux Programmer's Manual" +.SH NAME +tty \- controlling terminal +.SH DESCRIPTION +The file \fB/dev/tty\fP is a character file with major number 5 and +minor number 0, usually of mode 0666 and owner.group root.tty. It is a +synonym for the controlling terminal of a process, if any. +.LP +In addition to the \fBioctl()\fP requests supported by the device that +\fBtty\fP refers to, the \fBioctl()\fP request \fBTIOCNOTTY\fP is supported. +.SS TIOCNOTTY +Detach the current process from its controlling terminal. +.sp +If the process is the session leader, +then SIGHUP and SIGCONT signals are sent to the foreground process group +and all processes in the current session lose their controlling tty. +.sp +This \fBioctl()\fP call only works on file descriptors connected +to \fB/dev/tty\fP. It is used by daemon processes when they are invoked +by a user at a terminal. +The process attempts to open \fB/dev/tty\fP. If the open succeeds, it +detaches itself from the terminal by using \fBTIOCNOTTY\fP, while if the +open fails, it is obviously not attached to a terminal and does not need +to detach itself. +.SH FILES +/dev/tty +.SH "SEE ALSO" +.BR chown (1), +.BR getty (1), +.BR mknod (1), +.BR ioctl (2), +.BR termios (3), +.BR console (4), +.BR ttys (4) diff --git a/man4/ttyS.4 b/man4/ttyS.4 new file mode 100644 index 000000000..70ed88518 --- /dev/null +++ b/man4/ttyS.4 @@ -0,0 +1,51 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 17:03:24 1993 by Rik Faith (faith@cs.unc.edu) +.TH TTYS 4 1992-12-19 "Linux" "Linux Programmer's Manual" +.SH NAME +ttyS \- serial terminal lines +.SH DESCRIPTION +\fBttyS[0-3]\fP are character devices for the serial terminal lines. +.LP +They are typically created by: +.RS +.sp +mknod -m 660 /dev/ttyS0 c 4 64 # base address 0x3f8 +.br +mknod -m 660 /dev/ttyS1 c 4 65 # base address 0x2f8 +.br +mknod -m 660 /dev/ttyS2 c 4 66 # base address 0x3e8 +.br +mknod -m 660 /dev/ttyS3 c 4 67 # base address 0x2e8 +.br +chown root:tty /dev/ttyS[0-3] +.sp +.RE +.SH FILES +/dev/ttyS[0-3] +.SH "SEE ALSO" +.BR chown (1), +.BR getty (1), +.BR mknod (1), +.BR tty (4), +.BR setserial (8) diff --git a/man4/tty_ioctl.4 b/man4/tty_ioctl.4 new file mode 100644 index 000000000..1f32c38d4 --- /dev/null +++ b/man4/tty_ioctl.4 @@ -0,0 +1,434 @@ +.\" Copyright 2002 Walter Harms +.\" and Andries Brouwer . +.\" Distributed under GPL. +.\" +.TH TTY_IOCTL 4 2002-12-29 "Linux" "Linux Programmer's Manual" +.SH NAME +tty ioctl \- ioctls for terminals and serial lines +.SH SYNOPSIS +.sp +.BR "#include " +.sp +.BI "int ioctl(int " fd ", int " cmd ", ...);" +.sp +.SH DESCRIPTION +The +.I ioctl() +call for terminals and serial ports accepts many possible command arguments. +Most require a third argument, of varying type, here called \fIargp\fP +or \fIarg\fP. +.LP +Use of +.I ioctl +makes for non-portable programs. Use the POSIX interface described in +.BR termios (3) +whenever possible. + +.SS "Get and Set Terminal Attributes" +.TP +.BI "TCGETS struct termios *" argp +Equivalent to +.IR "tcgetattr(fd, argp)" . +.br +Get the current serial port settings. +.TP +.BI "TCSETS const struct termios *" argp +Equivalent to +.IR "tcsetattr(fd, TCSANOW, argp)" . +.br +Set the current serial port settings. +.TP +.BI "TCSETSW const struct termios *" argp +Equivalent to +.IR "tcsetattr(fd, TCSADRAIN, argp)" . +.br +Allow the output buffer to drain, and +set the current serial port settings. +.TP +.BI "TCSETSF const struct termios *" argp +Equivalent to +.IR "tcsetattr(fd, TCSAFLUSH, argp)" . +.br +Allow the output buffer to drain, discard pending input, and +set the current serial port settings. +.LP +The following four ioctls are just like TCGETS, TCSETS, TCSETSW, TCSETSF, +except that they take a +.B "struct termio *" +instead of a +.BR "struct termios *" . +.TP +.BI "TCGETA struct termio *" argp +.TP +.BI "TCSETA const struct termio *" argp +.TP +.BI "TCSETAW const struct termio *" argp +.TP +.BI "TCSETAF const struct termio *" argp + +.SS "Locking the termios structure" +The termios structure of a tty can be locked. The lock is itself +a termios structure, with nonzero bits or fields indicating a +locked value. +.TP +.BI "TIOCGLCKTRMIOS struct termios *" argp +Gets the locking status of the termios structure of +the terminal. +.TP +.BI "TIOCSLCKTRMIOS const struct termios *" argp +Sets the locking status of the termios structure of +the terminal. Only root can do this. + +.SS "Get and Set Window Size" +Window sizes are kept in the kernel, but not used by the kernel +(except in the case of virtual consoles, where the kernel will +update the window size when the size of the virtual console changes, +e.g. by loading a new font). +.TP +.BI "TIOCGWINSZ struct winsize *" argp +Get window size. +.TP +.BI "TIOCSWINSZ const struct winsize *" argp +Set window size. +.LP +The struct used by these ioctls is defined as + +.nf +struct winsize { + unsigned short ws_row; + unsigned short ws_col; + unsigned short ws_xpixel; /* unused */ + unsigned short ws_ypixel; /* unused */ +}; +.fi + +When the window size changes, a SIGWINCH signal is sent to the +foreground process group. + +.SS "Sending a Break" +.TP +.BI "TCSBRK int " arg +Equivalent to +.IR "tcsendbreak(fd, arg)" . +.br +If the terminal is using asynchronous serial data transmission, and +.I arg +is zero, then send a break (a stream of zero bits) for between +0.25 and 0.5 seconds. If the terminal is not using asynchronous +serial data transmission, then either a break is sent, or the function +returns without doing anything. +When +.I arg +is nonzero, nobody knows what will happen. + +(SVR4, UnixWare, Solaris, Linux treat +.I "tcsendbreak(fd,arg)" +with nonzero +.I arg +like +.IR "tcdrain(fd)" . +SunOS treats +.I arg +as a multiplier, and sends a stream of bits +.I arg +times as long as done for zero +.IR arg . +DG-UX and AIX treat +.I arg +(when nonzero) as a timeinterval measured in milliseconds. +HP-UX ignores +.IR arg .) +.TP +.BI "TCSBRKP int " arg +So-called "POSIX version" of TCSBRK. It treats nonzero +.I arg +as a timeinterval measured in deciseconds, and does nothing +when the driver does not support breaks. +.TP +.BI "TIOCSBRK void" +Turn break on, that is, start sending zero bits. +.TP +.BI "TIOCCBRK void" +Turn break off, that is, stop sending zero bits. + +.SS "Software flow control" +.TP +.BI "TCXONC int " arg +Equivalent to +.IR "tcflow(fd, arg)" . +.br +See +.BR tcflow (3) +for the argument values TCOOFF, TCOON, TCIOFF, TCION. + +.SS "Buffer count and flushing" +.TP +.BI "FIONREAD int *" argp +Get the number of bytes in the input buffer. +.TP +.BI "TIOCINQ int *" argp +Same as FIONREAD. +.TP +.BI "TIOCOUTQ int *" argp +Get the number of bytes in the output buffer. +.TP +.BI "TCFLSH int " arg +Equivalent to +.IR "tcflush(fd, arg)" . +.br +See +.BR tcflush (3) +for the argument values TCIFLUSH, TCOFLUSH, TCIOFLUSH. + +.SS "Faking input" +.TP +.BI "TIOCSTI const char *" argp +Insert the given byte in the input queue. + +.SS "Redirecting console output" +.TP +.BI "TIOCCONS void" +Redirect output that would have gone to +.I /dev/console +or +.I /dev/tty0 +to the given tty. If that was a pty master, send it to the slave. +Anybody can do this as long as the output was not redirected yet. +If it was redirected already EBUSY is returned, +but root may stop redirection by using this ioctl with +.I fd +pointing at +.I /dev/console +or +.IR /dev/tty0 . + +.SS "Controlling tty" +.TP +.BI "TIOCSCTTY int " arg +Make the given tty the controlling tty of the current process. +The current process must be a session leader and not have a +controlling tty already. If this tty is already the controlling tty +of a different session group then the ioctl fails with EPERM, +unless the caller is root and +.I arg +equals 1, in which case the tty is stolen, and all processes that had +it as controlling tty lose it. +.TP +.BI TIOCNOTTY void +If the given tty was the controlling tty of the current process, +give up this controlling tty. If the process was session leader, +then send SIGHUP and SIGCONT to the foreground process group +and all processes in the current session lose their controlling tty. + +.SS "Process group and session ID" +.TP +.BI "TIOCGPGRP pid_t *" argp +When successful, equivalent to +.IR "*argp = tcgetpgrp(fd)" . +.br +Get the process group ID of the foreground proces group on this tty. +.TP +.BI "TIOCSPGRP const pid_t *" argp +Equivalent to +.IR "tcsetpgrp(fd, *argp)" . +.br +Set the foreground process group id of this tty. +.TP +.BI "TIOCGSID pid_t *" argp +Get the session ID of the given tty. This will fail with ENOTTY +in case the tty is not a master pty and not our controlling tty. Strange. + +.SS "Exclusive mode" +.TP +.BI "TIOCEXCL void" +Put the tty into exclusive mode. +No further +.BR open (2) +operations on the terminal are permitted. +(They will fail with EBUSY, except for root.) +.TP +.BI "TIOCNXCL void" +Disable exclusive mode. + +.SS "Line discipline" +.TP +.BI "TIOCGETD int *" argp +Get the line discipline of the tty. +.TP +.BI "TIOCSETD const int *" argp +Set the line discipline of the tty. + +.SS "Pseudo-tty ioctls" +.TP +.BI "TIOCPKT const int *" argp +Enable (when +.RI * argp +is nonzero) or disable packet mode. +Can be applied to the master side of a pseudotty only (and will return +ENOTTY otherwise). In packet mode, each subsequent +.BR read (2) +will return a packet that either contains a single nonzero control byte, +or has a single zero byte followed by data written on the slave side of +the pty. If the first byte is not TIOCPKT_DATA (0), it is an OR of one +or more of the following bits: + +.nf +TIOCPKT_FLUSHREAD The read queue for the terminal is flushed. +TIOCPKT_FLUSHWRITE The write queue for the terminal is flushed. +TIOCPKT_STOP Output to the terminal is stopped. +TIOCPKT_START Output to the terminal is restarted. +TIOCPKT_DOSTOP t_stopc is `^S' and t_startc is `^Q'. +TIOCPKT_NOSTOP the start and stop characters are not `^S/^Q'. +.fi + +While this mode is in use, the presence +of control status information to be read +from the master side may be detected by a +.BR select (2) +for exceptional conditions. + +This mode is used by +.BR rlogin (1) +and +.BR rlogind (8) +to implement a remote-echoed, locally `^S/^Q' flow-controlled remote login. + +The BSD ioctls TIOCSTOP, TIOCSTART, TIOCUCNTL, TIOCREMOTE +have not been implemented under Linux. + +.SS "Modem control" +.TP +.BI "TIOCMGET int *" argp +get the status of modem bits. +.TP +.BI "TIOCMSET const int *" argp +set the status of modem bits. +.TP +.BI "TIOCMBIC const int *" argp +clear the indicated modem bits. +.TP +.BI "TIOCMBIS const int *" argp +set the indicated modem bits. +.LP +Bits used by these four ioctls: + +.nf +TIOCM_LE DSR (data set ready/line enable) +TIOCM_DTR DTR (data terminal ready) +TIOCM_RTS RTS (request to send) +TIOCM_ST Secondary TXD (transmit) +TIOCM_SR Secondary RXD (receive) +TIOCM_CTS CTS (clear to send) +TIOCM_CAR DCD (data carrier detect) +TIOCM_CD see TIOCM_CAR +TIOCM_RNG RNG (ring) +TIOCM_RI see TIOCM_RNG +TIOCM_DSR DSR (data set ready) +.fi + +.SS "Marking a line as local" +.TP +.BI "TIOCGSOFTCAR int *" argp +("Get software carrier flag") +Get the status of the CLOCAL flag in the c_cflag field of the +termios structure. +.TP +.BI "TIOCSSOFTCAR const int *" argp +("Set software carrier flag") +Set the CLOCAL flag in the termios structure when +.RI * argp +is nonzero, and clear it otherwise. +.LP +If the CLOCAL flag for a line is off, the hardware carrier detect (DCD) +signal is significant, and an +.BR open (2) +of the corresponding tty will block until DCD is asserted, +unless the O_NONBLOCK flag is given. +If CLOCAL is set, the line behaves as if DCD is always asserted. +The software carrier flag is usually turned on for local devices, +and is off for lines with modems. + +.SS "Linux specific" +For the TIOCLINUX ioctl, see +.BR console_ioctl (4). + +.SS "Kernel debugging" +.sp +.BR "#include " +.sp +.TP +.BI "TIOCTTYGSTRUCT struct tty_struct *" argp +Get the tty_struct corresponding to +.IR fd . +.\" +.\" .SS "Serial info" +.\" .sp +.\" .BR "#include " +.\" .sp +.\" .TP +.\" .BI "TIOCGSERIAL struct serial_struct *" argp +.\" Get serial info. +.\" .TP +.\" .BI "TIOCSSERIAL const struct serial_struct *" argp +.\" Set serial info. + +.SH "RETURN VALUE" +The +.I ioctl() +system call returns 0 on success. On error it returns \-1 and sets +.I errno +appropriately. + +.SH ERRORS +.TP +.B ENOIOCTLCMD +Unknown command. +.TP +.B EINVAL +Invalid command parameter. +.TP +.B EPERM +Insufficient permission. +.TP +.B ENOTTY +Inappropriate +.IR fd . +.SH EXAMPLE +Check the condition of DTR on the serial port. + +.nf +#include +#include +#include + +main() { + int fd, serial; + + fd = open("/dev/ttyS0", O_RDONLY); + ioctl(fd, TIOCMGET, &serial); + if (serial & TIOCM_DTR) + puts("TIOCM_DTR is not set"); + else + puts("TIOCM_DTR is set"); + close(fd); +} +.fi + +.SH "SEE ALSO" +.BR ioctl (2), +.BR termios (3), +.BR console_ioctl (4) + +.\" FIONBIO const int * +.\" FIONCLEX void +.\" FIOCLEX void +.\" FIOASYNC const int * +.\" from serial.c: +.\" TIOCSERCONFIG void +.\" TIOCSERGWILD int * +.\" TIOCSERSWILD const int * +.\" TIOCSERGSTRUCT struct async_struct * +.\" TIOCSERGETLSR int * +.\" TIOCSERGETMULTI struct serial_multiport_struct * +.\" TIOCSERSETMULTI const struct serial_multiport_struct * +.\" TIOCGSERIAL, TIOCSSERIAL (see above) diff --git a/man4/urandom.4 b/man4/urandom.4 new file mode 100644 index 000000000..b95979fa8 --- /dev/null +++ b/man4/urandom.4 @@ -0,0 +1 @@ +.so man4/random.4 diff --git a/man4/vcs.4 b/man4/vcs.4 new file mode 100644 index 000000000..de5e352a1 --- /dev/null +++ b/man4/vcs.4 @@ -0,0 +1,114 @@ +.\" Copyright (c) 1995 James R. Van Zandt +.\" Sat Feb 18 09:11:07 EST 1995 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified, Sun Feb 26 15:08:05 1995, faith@cs.unc.edu +.\" " +.TH VCS 4 1995-02-19 "Linux" "Linux Programmer's Manual" +.SH NAME +vcs, vcsa \- virtual console memory +.SH DESCRIPTION +\fB/dev/vcs0\fP is a character device with major number 7 and minor number +0, usually of mode 0644 and owner root.tty. It refers to the memory +of the currently +displayed virtual console terminal. +.LP +\fB/dev/vcs[1-63]\fP are character devices for virtual console +terminals, they have major number 7 and minor number 1 to 63, usually +mode 0644 and owner root.tty. \fB/dev/vcsa[0-63]\fP are the same, but +including attributes, and prefixed with four bytes giving the screen +dimensions and cursor position: \fIlines\fP, \fIcolumns\fP, \fIx\fP, \fIy\fP. +(\fIx\fP = \fIy\fP = 0 at the top left corner of the screen.) +.PP +These replace the screendump +.IR ioctl s +of \fBconsole\fP(4), so the system +administrator can control access using file system permissions. +.PP +The devices for the first eight virtual consoles may be created by: + +.nf + for x in 0 1 2 3 4 5 6 7 8; do + mknod -m 644 /dev/vcs$x c 7 $x; + mknod -m 644 /dev/vcsa$x c 7 $[$x+128]; + done + chown root:tty /dev/vcs* +.fi + +No +.IR ioctl () +requests are supported. +.SH EXAMPLES +You may do a screendump on vt3 by switching to vt1 and typing +\fIcat /dev/vcs3 >foo\fP. Note that the output does not contain +newline characters, so some processing may be required, like +in \fIfold -w 81 /dev/vcs3 | lpr\fP or (horrors) +\fIsetterm -dump 3 -file /proc/self/fd/1\fP. +.LP +The \fI/dev/vcsa0\fP device is used for Braille support. + +This program displays the character and screen attributes under the +cursor of the second virtual console, then changes the background color +there: + +.nf + #include + #include + #include + #include + + int main() { + int fd; + char *device = "/dev/vcsa2"; + struct {unsigned char lines, cols, x, y;} scrn; + char ch, attrib; + + fd = open(device, O_RDWR); + if (fd < 0) { + perror(device); + exit(1); + } + (void)read(fd, &scrn, 4); + (void)lseek(fd, 4 + 2*(scrn.y*scrn.cols + scrn.x), 0); + (void)read(fd, &ch, 1); + (void)read(fd, &attrib, 1); + printf("ch='%c' attrib=0x%02x\\n", ch, attrib); + attrib ^= 0x10; + (void)lseek(fd, -1, 1); + (void)write(fd, &attrib, 1); + return 0; + } +.fi + +.SH FILES +/dev/vcs[0-63] +.br +/dev/vcsa[0-63] +.SH AUTHOR +Andries Brouwer +.SH HISTORY +Introduced with version 1.1.92 of the Linux kernel. +.SH "SEE ALSO" +.BR selection (1), +.BR console (4), +.BR tty (4), +.BR ttys (4) diff --git a/man4/vcsa.4 b/man4/vcsa.4 new file mode 100644 index 000000000..ffe8d9be5 --- /dev/null +++ b/man4/vcsa.4 @@ -0,0 +1 @@ +.so man4/vcs.4 diff --git a/man4/wavelan.4 b/man4/wavelan.4 new file mode 100644 index 000000000..b939522f7 --- /dev/null +++ b/man4/wavelan.4 @@ -0,0 +1,152 @@ +.\" From jt@hplb.hpl.hp.com Thu Dec 19 18:31:49 1996 +.\" From: Jean Tourrilhes +.\" Address: HP Labs, Filton Road, Stoke Gifford, Bristol BS12 6QZ, U.K. +.\" Jean II - HPLB - '96 +.\" wavelan.c.4 +.\" +.TH WAVELAN 4 1996-10-22 "Univ. of Sydney (Basser Dep. of Comp. Sci.)" +.\" +.\" NAME part +.\" +.SH NAME +wavelan \- AT&T GIS WaveLAN ISA device driver +.\" +.\" SYNOPSIS part +.\" +.SH SYNOPSIS +.BI "insmod wavelan_cs.o [io=" B,B.. "] [ irq=" I,I.. "] [name=" N,N.. ] +.\" +.\" DESCRIPTION part +.\" +.SH DESCRIPTION +.I wavelan +is the low-level device driver for the NCR / AT&T / Lucent +.B WaveLAN ISA +and Digital (DEC) +.B RoamAbout DS +wireless ethernet adapter. This driver is available as a module or +might be compiled in the kernel. This driver supports multiple cards +in both forms (up to 4) and allocates the next available ethernet +device (eth0..eth#) for each card found, unless a device name is +explicitly specified (see below). This device name will be reported +in the kernel log file with the MAC address, NWID and frequency used +by the card. +.\" +.\" PARAMETER part +.\" +.SH PARAMETERS +This section apply to the module form (parameters passed on the +.BR insmod (8) +command line). If the driver is included in the kernel, use the +.I ether=IRQ,IO,NAME +syntax on the kernel command line. +.TP +.B io +Specify the list of base address where to search for wavelan cards +(setting by dip switch on the card). If you don't specify any io +address, the driver will scan 0x390 and 0x3E0 addresses, which might +conflict with other hardware... +.TP +.B irq +Set the list of irq that each wavelan card should use (the value is +saved in permanent storage for future use). +.TP +.B name +Set the list of name to be used for each wavelan cards device (name +used by +.BR ifconfig (8)). +.\" +.\" WIRELESS part +.\" +.SH "WIRELESS EXTENSIONS" +Use +.BR iwconfig (8) +to manipulate wireless extensions. +.\" NWID sub part +.SS NWID (or domain) +Set the network ID +.RI [ 0 +to +.IR FFFF ] +or disable it +.RI [ off ]. +As the NWID is stored in the card Permanent Storage Area, it will be +reuse at any further invocation of the driver. +.\" Frequency sub part +.SS Frequency & channels +For the 2.4GHz 2.00 Hardware, you are able to set the frequency by +specifying one of the 10 defined channels +.RI ( 2.412, +.I 2.422, 2.425, 2.4305, 2.432, 2.442, 2.452, 2.460, 2.462 +or +.IR 2.484 ) +or directly by its value. The frequency is changed immediately and +permanentely. Frequency availability depend on the regulations... +.\" Spy sub part +.SS Statistics spy +Set a list of MAC addresses in the driver (up to 8) and get the last +quality of link for each of those (see +.BR iwspy (8)). +.\" /proc/net/wireless part +.SS /proc/net/wireless +.I status +is the status reported by the modem. +.I Link quality +reports the quality of the modulation on the air (direct sequence +spread spectrum) [max = 16]. +.I Level +and +.I Noise +refer to the signal level and noise level [max = 64]. +The +.I crypt discarded packet +and +.I misc discarded packet +counters are not implemented. +.\" +.\" IOCTL part +.\" +.SH "PRIVATE IOCTL" +You may use +.BR iwpriv (8) +to manipulate private ioctls. +.\" threshold part +.SS Quality and Level threshold +Enable you the define the quality and level threshold used by the +modem (packet below that level are discarded). +.\" Histogram part +.SS Histogram +This functionality allow to set a number of signal level intervals and +to count the number of packets received in each of those defined +intervals. This distribution might be used to calculate the mean value +and standard deviation of the signal level. +.\" +.\" SPECIFIC part +.\" +.SH "SPECIFIC NOTES" +This driver will fail to detect some +.B non NCR/ATT&T/Lucent +Wavelan cards. If it's your case, you must look in the source code on +how to add your card to the detection routine. +.PP +Some of the mentioned features are optional. You may enable to disable +them by changing flags in the driver header and recompile. +.\" +.\" AUTHOR part +.\" +.SH AUTHOR +Bruce Janson \- bruce@cs.usyd.edu.au +.br +Jean Tourrilhes \- jt@hplb.hpl.hp.com +.br +(+ others - see source code for details) +.\" +.\" SEE ALSO part +.\" +.SH "SEE ALSO" +.BR wavelan_cs (4), +.BR ifconfig (8), +.BR insmod (8), +.BR iwconfig (8), +.BR iwspy (8), +.BR iwpriv (8) diff --git a/man4/zero.4 b/man4/zero.4 new file mode 100644 index 000000000..15a39be05 --- /dev/null +++ b/man4/zero.4 @@ -0,0 +1 @@ +.so man4/null.4 diff --git a/man5/acct.5 b/man5/acct.5 new file mode 100644 index 000000000..6b1ebfe0a --- /dev/null +++ b/man5/acct.5 @@ -0,0 +1,42 @@ +.\" Copyright (c) 1995 Dirk Eddelbuettel (Dirk.Eddelbuettel@qed.econ.queensu.ca) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, +.\" USA. +.\" +.TH ACCT 5 2003-11-01 "Linux" "Linux Programmer's Manual" +.SH NAME +acct \- execution accounting file +.SH SYNOPSIS +.B #include +.SH DESCRIPTION +If the kernel was compiled with the process accounting option enabled, +the system call +.RS +acct("/somewhere/accountingfile"); +.RE +will start the process accounting. Each time a process terminates +a record for this process is appended to the accounting file. +The accounting structure +.B "struct acct" +is also described in the file +.IR /usr/include/linux/acct.h . +.SH "SEE ALSO" +.BR sa (1), +.BR acct (2) diff --git a/man5/charmap.5 b/man5/charmap.5 new file mode 100644 index 000000000..6755b7cef --- /dev/null +++ b/man5/charmap.5 @@ -0,0 +1,128 @@ +.\" Hey emacs, this is -*- nroff -*- +.\" +.\" This file is part of locale(1) which displays the settings of the +.\" current locale. +.\" Copyright (C) 1994 Jochen Hein (Hein@Student.TU-Clausthal.de) +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program; if not, write to the Free Software +.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA. +.\" +.TH CHARMAP 5 1994-11-28 "National Language Support" "Linux User Manual" +.SH NAME +charmap \- character symbols to define character encodings +.SH DESCRIPTION +A character set description (charmap) defines a characterset of +available characters and their encodings. All supported character +sets should have the +.B portable character set +as a proper subset. +.\" Not true anymore: +.\" The portable character set is defined in the file +.\" .I /usr/lib/nls/charmap/POSIX +.\" .I /usr/share/i18n/charmap/POSIX +.\" for reference purposes. +.SH SYNTAX +The charmap file starts with a header, that may consist of the +following keywords: +.TP +.I +is followed by the name of the codeset. +.TP +.I +is followed by the max number of bytes for a multibyte-character. +Multibyte characters are currently not supported. The default value +is 1. +.TP +.I +is followed by the min number of bytes for a character. This +value must be less or equal than +.B mb_cur_max. +If not specified, it defaults to +.B mb_cur_max. +.TP +.I +is followed by a character that should be used as the +escape-character for the rest of the file to mark characters that +should be interpreted in a special way. It defaults to +the backslash ( +.B \\\\ +). +.TP +.I +is followed by a character that will be used as the +comment-character for the rest of the file. It defaults to the +number sign ( +.B # +). + +.PP +The charmap-definition itself starts with the keyword +.B CHARMAP +in column 1. + +The following lines may have one of the two following forms to +define the character-encodings: +.TP +.I +This form defines exactly one character and its encoding. + +.TP +.I ... +This form defines a couple of characters. This is only useful for +mutlibyte-characters, which are currently not implemented. + +.PP +The last line in a charmap-definition file must contain +.B END CHARMAP. +.SH "SYMBOLIC NAMES" +A +.B symbolic name +for a character contains only characters of the +.B portable character set. +The name itself is enclosed between angle brackets. +Characters following an +.B +are interpreted as itself; for example, the sequence +.B '<\\\\\\\\\\\\>>' +represents the symbolic name +.B '\\\\>' +enclosed in angle brackets. +.SH "CHARACTER ENCODING" +The +encoding may be in each of the following three forms: +.TP +.I d +with a decimal number +.TP +.I x +with a hexadecimal number +.TP +.I +with an octal number. + +.\" XXX - comments +.\" XXX - char ... char + +.SH FILES +.I /usr/share/i18n/charmaps/* +.SH AUTHOR +Jochen Hein (jochen.hein@delphi.central.de) +.SH "CONFORMING TO" +POSIX.2 +.SH "SEE ALSO" +.BR locale (1), +.BR localedef (1), +.BR localeconv (3), +.BR setlocale (3), +.BR locale (5) diff --git a/man5/complex.5 b/man5/complex.5 new file mode 100644 index 000000000..1347aded6 --- /dev/null +++ b/man5/complex.5 @@ -0,0 +1,49 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" +.TH COMPLEX 5 2002-07-28 "" "complex math" +.SH NAME +complex \- basics of complex mathematics +.SH SYNOPSIS +.B #include +.SH DESCRIPTION +Complex numbers are numbers of the form z = a+b*i, where a and b are +real numbers and i = sqrt(-1), so that i*i = -1. +.br +There are other ways to represent that number. The pair (a,b) of real +numbers may be viewed as a point in the plane, given by X- and +Y-coordinates. This same point may also be described by giving +the pair of real numbers (r,phi), where r is the distance to the origin O, +and phi the angle between the X-axis and the line Oz. Now +z = r*exp(i*phi) = r*(cos(phi)+i*sin(phi)). +.PP +The basic operations are defined on z = a+b*i and w = c+d*i as: +.TP +.B addition: z+w = (a+c) + (b+d)*i +.TP +.B multiplication: z*w = (a*c - b*d) + (a*d + b*c)*i +.TP +.B division: z/w = ((a*c + b*d)/(c*c + d*d)) + ((b*c - a*d)/(c*c + d*d))*i +.PP +Nearly all math function have a complex counterpart but there are +some complex only functions. +.SH EXAMPLE +Your C-compiler can work with complex numbers if it supports the C99 standard. +Link with -lm. The imaginary unit is represented by I. +.sp +.nf +/* check that exp(i*pi) == -1 */ +#include /* for atan */ +#include +main() { + double pi = 4*atan(1); + complex z = cexp(I*pi); + printf("%f+%f*i\\n", creal(z), cimag(z)); +} +.fi +.SH "SEE ALSO" +.BR cabs (3), +.BR carg (3), +.BR cexp (3), +.BR cimag (3), +.BR creal (3) diff --git a/man5/dir_colors.5 b/man5/dir_colors.5 new file mode 100644 index 000000000..e8b814b61 --- /dev/null +++ b/man5/dir_colors.5 @@ -0,0 +1,343 @@ +.\" +.\" manpage for /etc/dir_colors, config file for dircolors(1) +.\" extracted from color-ls 3.12.0.3 dircolors(1) manpage +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.\" Modified Sat Dec 22 22:25:33 2001 by Martin Schulze +.\" +.TH DIR_COLORS 5 2001-12-26 "GNU fileutils 4.1" +.SH NAME +dir_colors \- configuration file for dircolors(1) +.SH DESCRIPTION +The program +.BR ls (1) +uses the environment variable +.B LS_COLORS +to determine the colors in which the filenames are to be displayed. +This environment variable is usually set by a command like + +.RS +eval `dircolors some_path/dir_colors` +.RE + +found in a system default shell initialization file, like +.I /etc/profile +or +.IR /etc/csh.cshrc . +(See also +.BR dircolors (1).) +Usually, the file used here is +.I /etc/DIR_COLORS +and can be overridden by a +.I .dir_colors +file in one's home directory. +.PP +This configuration file consists of several statements, one per line. +Anything right of a hash mark (#) is treated as a comment, if the +hash mark is at the beginning of a line or is preceded by at least one +whitespace. Blank lines are ignored. +.PP +The +.I global +section of the file consists of any statement before the first +.B TERM +statement. Any statement in the global section of the file is +considered valid for all terminal types. Following the global section +is one or more +.I terminal-specific +sections, preceded by one or more +.B TERM +statements which specify the terminal types (as given by the +.B TERM +environment variable) the following declarations apply to. It is +always possible to override a global declaration by a subsequent +terminal-specific one. +.PP +The following statements are recognized; case is insignificant: +.PP +.TP +.B TERM \fIterminal-type\fR +Starts a terminal-specific section and specifies which terminal it +applies to. Multiple +.B TERM +statements can be used to create a section which applies for several +terminal types. +.TP +.B COLOR yes|all|no|none|tty +(Slackware only; ignored by GNU +.BR dircolors (1).) +Specifies that colorization should always be enabled (\fIyes\fR or +\fIall\fR), never enabled (\fIno\fR or \fInone\fR), or enabled only if +the output is a terminal (\fItty\fR). The default is \fIno\fR. +.TP +.B EIGHTBIT yes|no +(Slackware only; ignored by GNU +.BR dircolors (1).) +Specifies that eight-bit ISO 8859 characters should be enabled by +default. For compatibility reasons, this can also be specified as 1 for +\fIyes\fR or 0 for \fIno\fR. The default is \fIno\fR. +.TP +.B OPTIONS \fIoptions\fR +(Slackware only; ignored by GNU +.BR dircolors (1).) +Adds command line options to the default +.B ls +command line. The options can be any valid +.B ls +command line options, and should include the leading minus sign. +Please note that +.B dircolors +does not verify the validity of these options. +.TP +.B NORMAL \fIcolor-sequence\fR +Specifies the color used for normal (non-filename) text. +.TP +.B FILE \fIcolor-sequence\fR +Specifies the color used for a regular file. +.TP +.B DIR \fIcolor-sequence\fR +Specifies the color used for directories. +.TP +.B LINK \fIcolor-sequence\fR +Specifies the color used for a symbolic link. +.TP +.B ORPHAN \fIcolor-sequence\fR +Specifies the color used for an orphaned symbolic link (one which +points to a nonexistent file). If this is unspecified, +.B ls +will use the +.B LINK +color instead. +.TP +.B MISSING \fIcolor-sequence\fR +Specifies the color used for a missing file (a nonexistent file which +nevertheless has a symbolic link pointing to it). If this is unspecified, +.B ls +will use the +.B FILE +color instead. +.TP +.B FIFO \fIcolor-sequence\fR +Specifies the color used for a FIFO (named pipe). +.TP +.B SOCK \fIcolor-sequence\fR +Specifies the color used for a socket. +.TP +.B DOOR \fIcolor-sequence\fR +(Supported since file-utils 4.1) +Specifies the color used for a door (Solaris 2.5 and later). +.TP +.B BLK \fIcolor-sequence\fR +Specifies the color used for a block device special file. +.TP +.B CHR \fIcolor-sequence\fR +Specifies the color used for a character device special file. +.TP +.B EXEC \fIcolor-sequence\fR +Specifies the color used for a file with the executable attribute set. +.TP +.B LEFTCODE \fIcolor-sequence\fR +Specifies the +.I "left code" +for non-ISO\ 6429 terminals (see below). +.TP +.B RIGHTCODE \fIcolor-sequence\fR +Specifies the +.I "right code" +for non-ISO\ 6429 terminals (see below). +.TP +.B ENDCODE \fIcolor-sequence\fR +Specifies the +.I "end code" +for non-ISO\ 6429 terminals (see below). +.TP +\fB*\fIextension\fR \fIcolor-sequence\fR +Specifies the color used for any file that ends in \fIextension\fR. +.TP +\fB .\fIextension\fR \fIcolor-sequence\fR +Same as \fB*\fR.\fIextension\fR. Specifies the color used for any file that +ends in .\fIextension\fR. Note that the period is included in the +extension, which makes it impossible to specify an extension not +starting with a period, such as +.B ~ +for +.B emacs +backup files. This form should be considered obsolete. +.SH "ISO 6429 (ANSI) COLOR SEQUENCES" +Most color-capable ASCII terminals today use ISO 6429 (ANSI) color sequences, +and many common terminals without color capability, including +.B xterm +and the widely used and cloned DEC VT100, will recognize ISO 6429 color +codes and harmlessly eliminate them from the output or emulate them. +.B ls +uses ISO 6429 codes by default, assuming colorization is enabled. + +ISO 6429 color sequences are composed of sequences of numbers +separated by semicolons. The most common codes are: +.sp +.RS +.2i +.ta 1.0i +.nf + 0 to restore default color + 1 for brighter colors + 4 for underlined text + 5 for flashing text +30 for black foreground +31 for red foreground +32 for green foreground +33 for yellow (or brown) foreground +34 for blue foreground +35 for purple foreground +36 for cyan foreground +37 for white (or gray) foreground +40 for black background +41 for red background +42 for green background +43 for yellow (or brown) background +44 for blue background +45 for purple background +46 for cyan background +47 for white (or gray) background +.fi +.RE +.sp +Not all commands will work on all systems or display devices. +.PP +.B ls +uses the following defaults: +.sp +.RS +.2i +.ta 1.0i 2.5i +.nf +\fBNORMAL\fR 0 Normal (non-filename) text +\fBFILE\fR 0 Regular file +\fBDIR\fR 32 Directory +\fBLINK\fR 36 Symbolic link +\fBORPHAN\fR undefined Orphanned symbolic link +\fBMISSING\fR undefined Missing file +\fBFIFO\fR 31 Named pipe (FIFO) +\fBSOCK\fR 33 Socket +\fBBLK\fR 44;37 Block device +\fBCHR\fR 44;37 Character device +\fBEXEC\fR 35 Executable file +.fi +.RE +.sp +A few terminal programs do not recognize the default +properly. If all text gets colorized after you do a directory +listing, change the +.B NORMAL +and +.B FILE +codes to the numerical codes for your normal foreground and background +colors. +.SH "OTHER TERMINAL TYPES (ADVANCED CONFIGURATION)" +If you have a color-capable (or otherwise highlighting) terminal (or +printer!) which uses a different set of codes, you can still generate +a suitable setup. To do so, you will have to use the +.BR LEFTCODE , +.BR RIGHTCODE , +and +.BR ENDCODE +definitions. +.PP +When writing out a filename, +.B ls +generates the following output sequence: +.B LEFTCODE +.I typecode +.B RIGHTCODE +.I filename +.BR ENDCODE , +where the +.I typecode +is the color sequence that depends on the type or name of file. If the +.B ENDCODE +is undefined, the sequence +.B "LEFTCODE NORMAL RIGHTCODE" +will be used instead. The purpose of the left- and rightcodes is +merely to reduce the amount of typing necessary (and to hide ugly +escape codes away from the user). If they are not appropriate for +your terminal, you can eliminate them by specifying the respective +keyword on a line by itself. +.PP +.B NOTE: +If the +.B ENDCODE +is defined in the global section of the setup file, it +.I cannot +be undefined in a terminal-specific section of the file. This means +any +.B NORMAL +definition will have no effect. A different +.B ENDCODE +can, however, be specified, which would have the same effect. +.SH "ESCAPE SEQUENCES" +To specify control- or blank characters in the color sequences or +filename extensions, either C-style \e-escaped notation or +.BR stty -style +^-notation can be used. The C-style notation +includes the following characters: +.sp +.RS +.2i +.ta 1.0i +.nf +\fB\ea\fR Bell (ASCII 7) +\fB\eb\fR Backspace (ASCII 8) +\fB\ee\fR Escape (ASCII 27) +\fB\ef\fR Form feed (ASCII 12) +\fB\en\fR Newline (ASCII 10) +\fB\er\fR Carriage Return (ASCII 13) +\fB\et\fR Tab (ASCII 9) +\fB\ev\fR Vertical Tab (ASCII 11) +\fB\e?\fR Delete (ASCII 127) +\fB\e\fInnn\fR Any character (octal notation) +\fB\ex\fInnn\fR Any character (hexadecimal notation) +\fB\e_\fR Space +\fB\e\e\fR Backslash (\e) +\fB\e^\fR Caret (^) +\fB\e#\fR Hash mark (#) +.fi +.RE +.sp +Please note that escapes are necessary to enter a space, backslash, +caret, or any control character anywhere in the string, as well as a +hash mark as the first character. +.SH NOTES +The default +.B LEFTCODE +and +.B RIGHTCODE +definitions, which are used by ISO 6429 terminals are: +.sp +.RS +.2i +.ta 1.0i +.nf +\fBLEFTCODE\fR \ee[ +\fBRIGHTCODE\fR m +.fi +.RE +.sp +The default +.B ENDCODE +is undefined. +.SH "SEE ALSO" +.BR dircolors (1), +.BR ls (1), +.BR stty (1), +.BR xterm (1) +.SH FILES +.TP +.I /etc/DIR_COLORS +System-wide configuration file. +.TP +.I ~/.dir_colors +Per-user configuration file. +.SH NOTES +This page describes the +.B dir_colors +file format as used in the fileutils-4.1 package; +other versions may differ slightly. diff --git a/man5/elf.5 b/man5/elf.5 new file mode 100644 index 000000000..7d9671457 --- /dev/null +++ b/man5/elf.5 @@ -0,0 +1,1369 @@ +.\" $OpenBSD: elf.5,v 1.12 2003/10/27 20:23:58 jmc Exp $ +.\"Copyright (c) 1999 Jeroen Ruigrok van der Werven +.\"All rights reserved. +.\" +.\"Redistribution and use in source and binary forms, with or without +.\"modification, are permitted provided that the following conditions +.\"are met: +.\"1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\"2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\"THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\"ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\"IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\"ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\"FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\"DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\"OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\"HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\"LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\"OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\"SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man5/elf.5,v 1.21 2001/10/01 16:09:23 ru Exp $ +.\" +.\" Slightly adapted - aeb, 2004-01-01 +.Dd July 31, 1999 +.Dt ELF 5 +.Os +.Sh NAME +.Nm elf +.Nd format of ELF executable binary files +.Sh SYNOPSIS +.\" .Fd #include +.Fd #include +.Sh DESCRIPTION +The header file +.\" .Aq Pa elf_abi.h +.Aq Pa elf.h +defines the format of ELF executable binary files. +Amongst these files are +normal executable files, relocatable object files, core files and shared +libraries. +.Pp +An executable file using the ELF file format consists of an ELF header, +followed by a program header table or a section header table, or both. +The ELF header is always at offset zero of the file. +The program header +table and the section header table's offset in the file are defined in the +ELF header. +The two tables describe the rest of the particularities of +the file. +.Pp +.\" Applications which wish to process ELF binary files for their native +.\" architecture only should include +.\" .Aq Pa elf_abi.h +.\" in their source code. +.\" These applications should need to refer to +.\" all the types and structures by their generic names +.\" .Dq Elf_xxx +.\" and to the macros by +.\" .Dq ELF_xxx . +.\" Applications written this way can be compiled on any architecture, +.\" regardless of whether the host is 32-bit or 64-bit. +.\" .Pp +.\" Should an application need to process ELF files of an unknown +.\" architecture, then the application needs to explicitly use either +.\" .Dq Elf32_xxx +.\" or +.\" .Dq Elf64_xxx +.\" type and structure names. +.\" Likewise, the macros need to be identified by +.\" .Dq ELF32_xxx +.\" or +.\" .Dq ELF64_xxx . +.\" .Pp +This header file describes the above mentioned headers as C structures +and also includes structures for dynamic sections, relocation sections and +symbol tables. +.Pp +The following types are used for N-bit architectures (N=32,64, +ElfN stands for Elf32 or Elf64, uintN_t stands for uint32_t or uint64_t): +.Bd -literal -offset indent +ElfN_Addr Unsigned program address, uintN_t +ElfN_Off Unsigned file offset, uintN_t +ElfN_Section Unsigned section index, uint16_t +ElfN_Versym Unsigned version symbol information, uint16_t +Elf_Byte unsigned char +ElfN_Half uint16_t +ElfN_Sword int32_t +ElfN_Word uint32_t +ElfN_Sxword int64_t +ElfN_Xword uint64_t +.\" Elf32_Size Unsigned object size +.Ed +.Pp +(Note: The *BSD terminology is a bit different. There Elf64_Half is +twice as large as Elf32_Half, and Elf64Quarter is used for uint16_t. +In order to avoid confusion these types are replaced by explicit ones +in the below.) +.Pp +All data structures that the file format defines follow the +.Dq natural +size and alignment guidelines for the relevant class. +If necessary, +data structures contain explicit padding to ensure 4-byte alignment +for 4-byte objects, to force structure sizes to a multiple of 4, etc. +.Pp +The ELF header is described by the type Elf32_Ehdr or Elf64_Ehdr: +.Bd -literal -offset indent +#define EI_NIDENT 16 + +typedef struct { + unsigned char e_ident[EI_NIDENT]; + uint16_t e_type; + uint16_t e_machine; + uint32_t e_version; + ElfN_Addr e_entry; + ElfN_Off e_phoff; + ElfN_Off e_shoff; + uint32_t e_flags; + uint16_t e_ehsize; + uint16_t e_phentsize; + uint16_t e_phnum; + uint16_t e_shentsize; + uint16_t e_shnum; + uint16_t e_shstrndx; +} ElfN_Ehdr; +.Ed +.Pp +The fields have the following meanings: +.Bl -tag -width "e_phentsize" -offset indent +.It Dv e_ident +This array of bytes specifies to interpret the file, +independent of the processor or the file's remaining contents. +Within this array everything is named by macros, which start with +the prefix +.Sy EI_ +and may contain values which start with the prefix +.Sy ELF . +The following macros are defined: +.Bl -tag -width "EI_VERSION" \" EI_ABIVERSION +.It Dv EI_MAG0 +The first byte of the magic number. +It must be filled with +.Sy ELFMAG0 . +(0: 0x7f) +.It Dv EI_MAG1 +The second byte of the magic number. +It must be filled with +.Sy ELFMAG1 . +(1: 'E') +.It Dv EI_MAG2 +The third byte of the magic number. +It must be filled with +.Sy ELFMAG2 . +(2: 'L') +.It Dv EI_MAG3 +The fourth byte of the magic number. +It must be filled with +.Sy ELFMAG3 . +(3: 'F') +.It Dv EI_CLASS +The fifth byte identifies the architecture for this binary: +.Pp +.Bl -tag -width "ELFCLASSNONE" -compact +.It Dv ELFCLASSNONE +This class is invalid. +.It Dv ELFCLASS32 +This defines the 32-bit architecture. +It supports machines with files +and virtual address spaces up to 4 Gigabytes. +.It Dv ELFCLASS64 +This defines the 64-bit architecture. +.El +.It Dv EI_DATA +The sixth byte specifies the data encoding of the processor-specific +data in the file. +Currently these encodings are supported: +.Pp +.Bl -tag -width "ELFDATA2LSB" -compact +.It Dv ELFDATANONE +Unknown data format. +.It Dv ELFDATA2LSB +Two's complement, little-endian. +.It Dv ELFDATA2MSB +Two's complement, big-endian. +.El +.It Dv EI_VERSION +The version number of the ELF specification: +.Pp +.Bl -tag -width "EV_CURRENT" -compact +.It Dv EV_NONE +Invalid version. +.It Dv EV_CURRENT +Current version. +.El +.It Dv EI_OSABI +This byte identifies the operating system +and ABI to which the object is targeted. +Some fields in other ELF structures have flags +and values that have platform specific meanings; +the interpretation of those fields is determined by the value of this byte. +E.g.: +.Pp +.Bl -tag -width "ELFOSABI_STANDALONE" -compact +.It Dv ELFOSABI_SYSV +UNIX System V ABI. +.\" 0 +.\" synonym: ELFOSABI_NONE +.It Dv ELFOSABI_HPUX +HP-UX ABI. +.\" 1 +.It Dv ELFOSABI_NETBSD +NetBSD ABI. +.\" 2 +.It Dv ELFOSABI_LINUX +Linux ABI. +.\" 3 +.\" .It Dv ELFOSABI_HURD +.\" Hurd ABI. +.\" 4 +.\" .It Dv ELFOSABI_86OPEN +.\" 86Open Common IA32 ABI. +.\" 5 +.It Dv ELFOSABI_SOLARIS +Solaris ABI. +.\" 6 +.\" .It Dv ELFOSABI_MONTEREY +.\" Monterey project ABI. Now replaced by +.\" ELFOSABI_AIX +.\" 7 +.It Dv ELFOSABI_IRIX +IRIX ABI. +.\" 8 +.It Dv ELFOSABI_FREEBSD +FreeBSD ABI. +.\" 9 +.It Dv ELFOSABI_TRU64 +TRU64 UNIX ABI. +.\" 10 +.\" ELFOSABI_MODESTO +.\" 11 +.\" ELFOSABI_OPENBSD +.\" 12 +.It Dv ELFOSABI_ARM +ARM architecture ABI. +.\" 97 +.It Dv ELFOSABI_STANDALONE +Stand-alone (embedded) ABI. +.\" 255 +.El +.It Dv EI_ABIVERSION +This byte identifies the version of the ABI +to which the object is targeted. +This field is used to distinguish among incompatible versions of an ABI. +The interpretation of this version number +is dependent on the ABI identified by the EI_OSABI field. +Applications conforming to this specification use the value 0. +.It Dv EI_PAD +Start of padding. +These bytes are reserved and set to zero. +Programs +which read them should ignore them. +The value for EI_PAD will change in +the future if currently unused bytes are given meanings. +.It Dv EI_BRAND +Start of architecture identification. +.It Dv EI_NIDENT +The size of the e_ident array. +.El +.Pp +.It Dv e_type +This member of the structure identifies the object file type: +.Pp +.Bl -tag -width "ET_NONE" -compact +.It Dv ET_NONE +An unknown type. +.It Dv ET_REL +A relocatable file. +.It Dv ET_EXEC +An executable file. +.It Dv ET_DYN +A shared object. +.It Dv ET_CORE +A core file. +.El +.Pp +.It Dv e_machine +This member specifies the required architecture for an individual file. +E.g.: +.Pp +.Bl -tag -width "EM_MIPS_RS4_BE" -compact +.It Dv EM_NONE +An unknown machine. +.\" 0 +.It Dv EM_M32 +AT&T WE 32100. +.\" 1 +.It Dv EM_SPARC +Sun Microsystems SPARC. +.\" 2 +.It Dv EM_386 +Intel 80386. +.\" 3 +.It Dv EM_68K +Motorola 68000. +.\" 4 +.It Dv EM_88K +Motorola 88000. +.\" 5 +.\" .It Dv EM_486 +.\" Intel 80486. +.\" 6 +.It Dv EM_860 +Intel 80860. +.\" 7 +.It Dv EM_MIPS +MIPS RS3000 (big-endian only). +.\" 8 +.\" EM_S370 +.\" 9 +.\" .It Dv EM_MIPS_RS4_BE +.\" MIPS RS4000 (big-endian only). Deprecated. +.\" 10 +.\" EM_MIPS_RS3_LE (MIPS R3000 little-endian) +.\" 10 +.It Dv EM_PARISC +HPPA. +.\" 15 +.It Dv EM_SPARC32PLUS +SPARC with enhanced instruction set. +.\" 18 +.It Dv EM_PPC +PowerPC. +.\" 20 +.\" EM_PPC64 +.\" 21 +.\" EM_S390 +.\" 22 +.\" EM_SH +.\" 42 +.It Dv EM_SPARCV9 +SPARC v9 64-bit. +.\" 43 +.\" EM_IA_64 +.\" 50 +.\" EM_X86_64 +.\" 62 +.It Dv EM_VAX +DEC Vax. +.\" 75 +.\" EM_CRIS +.\" 76 +.\" .It Dv EM_ALPHA +.\" Compaq [DEC] Alpha. +.\" .It Dv EM_ALPHA_EXP +.\" Compaq [DEC] Alpha with enhanced instruction set. +.El +.Pp +.It Dv e_version +This member identifies the file version: +.Pp +.Bl -tag -width "EV_CURRENT" -compact +.It Dv EV_NONE +Invalid version. +.It Dv EV_CURRENT +Current version. +.El +.It Dv e_entry +This member gives the virtual address to which the system first transfers +control, thus starting the process. +If the file has no associated entry +point, this member holds zero. +.It Dv e_phoff +This member holds the program header table's file offset in bytes. +If +the file has no program header table, this member holds zero. +.It Dv e_shoff +This member holds the section header table's file offset in bytes. +If the +file has no section header table this member holds zero. +.It Dv e_flags +This member holds processor-specific flags associated with the file. +Flag names take the form EF_`machine_flag'. +Currently no flags have been defined. +.It Dv e_ehsize +This member holds the ELF header's size in bytes. +.It Dv e_phentsize +This member holds the size in bytes of one entry in the file's program header +table; all entries are the same size. +.It Dv e_phnum +This member holds the number of entries in the program header +table. +Thus the product of +.Sy e_phentsize +and +.Sy e_phnum +gives the table's size +in bytes. +If a file has no program header, +.Sy e_phnum +holds the value zero. +.It Dv e_shentsize +This member holds a sections header's size in bytes. +A section header is one +entry in the section header table; all entries are the same size. +.It Dv e_shnum +This member holds the number of entries in the section header table. +Thus +the product of +.Sy e_shentsize +and +.Sy e_shnum +gives the section header table's size in bytes. +If a file has no section +header table, +.Sy e_shnum +holds the value of zero. +.It Dv e_shstrndx +This member holds the section header table index of the entry associated +with the section name string table. +If the file has no section name string +table, this member holds the value +.Sy SHN_UNDEF . +.Bl -tag -width "SHN_LORESERVE" +.It Dv SHN_UNDEF +This value marks an undefined, missing, irrelevant, or otherwise meaningless +section reference. +For example, a symbol +.Dq defined +relative to section number +.Sy SHN_UNDEF +is an undefined symbol. +.It Dv SHN_LORESERVE +This value specifies the lower bound of the range of reserved indices. +.It Dv SHN_LOPROC +Values greater than or equal to +.Sy SHN_HIPROC +are reserved for processor-specific semantics. +.It Dv SHN_HIPROC +Values less than or equal to +.Sy SHN_LOPROC +are reserved for processor-specific semantics. +.It Dv SHN_ABS +This value specifies absolute values for the corresponding reference. +For +example, symbols defined relative to section number +.Sy SHN_ABS +have absolute values and are not affected by relocation. +.It Dv SHN_COMMON +Symbols defined relative to this section are common symbols, such as Fortran +COMMON or unallocated C external variables. +.It Dv SHN_HIRESERVE +This value specifies the upper bound of the range of reserved +indices between +.Sy SHN_LORESERVE +and +.Sy SHN_HIRESERVE , +inclusive; the values do +not reference the section header table. +That is, the section header table +does +.Em not +contain entries for the reserved indices. +.El +.El +.Pp +An executable or shared object file's program header table is an array of +structures, each describing a segment or other information the system needs +to prepare the program for execution. +An object file +.Em segment +contains one or more +.Em sections . +Program headers are meaningful only for executable and shared object files. +A file specifies its own program header size with the ELF header's +.Sy e_phentsize +and +.Sy e_phnum +members. +The ELF program header is described by the type Elf32_Phdr or Elf64_Phdr +depending on the architecture: +.Bd -literal -offset indent +typedef struct { + uint32_t p_type; + Elf32_Off p_offset; + Elf32_Addr p_vaddr; + Elf32_Addr p_paddr; + uint32_t p_filesz; + uint32_t p_memsz; + uint32_t p_flags; + uint32_t p_align; +} Elf32_Phdr; +.Ed +.Bd -literal -offset indent +typedef struct { + uint32_t p_type; + uint32_t p_flags; + Elf64_Off p_offset; + Elf64_Addr p_vaddr; + Elf64_Addr p_paddr; + uint64_t p_filesz; + uint64_t p_memsz; + uint64_t p_align; +} Elf64_Phdr; +.Ed +.Pp +The main difference between the 32-bit and the 64-bit program header lies +in the location of the +.Sy p_flags +member in the total struct. +.Bl -tag -width "p_offset" -offset indent +.It Dv p_type +This member of the Phdr struct tells what kind of segment this array +element describes or how to interpret the array element's information. +.Bl -tag -width "PT_DYNAMIC" +.It Dv PT_NULL +The array element is unused and the other members' values are undefined. +This lets the program header have ignored entries. +.It Dv PT_LOAD +The array element specifies a loadable segment, described by +.Sy p_filesz +and +.Sy p_memsz . +The bytes from the file are mapped to the beginning of the memory +segment. +If the segment's memory size +.Pq Sy p_memsz +is larger than the file size +.Pq Sy p_filesz , +the +.Dq extra +bytes are defined to hold the value 0 and to follow the segment's +initialized area. +The file size may not be larger than the memory size. +Loadable segment entries in the program header table appear in ascending +order, sorted on the +.Sy p_vaddr +member. +.It Dv PT_DYNAMIC +The array element specifies dynamic linking information. +.It Dv PT_INTERP +The array element specifies the location and size of a null-terminated +path name to invoke as an interpreter. +This segment type is meaningful +only for executable files (though it may occur for shared objects). +However it may not occur more than once in a file. +If it is present, it must precede any loadable segment entry. +.It Dv PT_NOTE +The array element specifies the location and size for auxiliary information. +.It Dv PT_SHLIB +This segment type is reserved but has unspecified semantics. +Programs that +contain an array element of this type do not conform to the ABI. +.It Dv PT_PHDR +The array element, if present, specifies the location and size of the program +header table itself, both in the file and in the memory image of the program. +This segment type may not occur more than once in a file. +Moreover, it may +only occur if the program header table is part of the memory image of the +program. +If it is present, it must precede any loadable segment entry. +.It Dv PT_LOPROC +Values greater than or equal to +.Sy PT_HIPROC +are reserved for processor-specific semantics. +.It Dv PT_HIPROC +Values less than or equal to +.Sy PT_LOPROC +are reserved for processor-specific semantics. +.El +.Pp +.It Dv p_offset +This member holds the offset from the beginning of the file at which +the first byte of the segment resides. +.It Dv p_vaddr +This member holds the virtual address at which the first byte of the +segment resides in memory. +.It Dv p_paddr +On systems for which physical addressing is relevant, this member is +reserved for the segment's physical address. +Under +.Bx +this member is +not used and must be zero. +.It Dv p_filesz +This member holds the number of bytes in the file image of the segment. +It may be zero. +.It Dv p_memsz +This member holds the number of bytes in the memory image of the segment. +It may be zero. +.It Dv p_flags +This member holds flags relevant to the segment: +.Pp +.Bl -tag -width "PF_X" -compact +.It Dv PF_X +An executable segment. +.It Dv PF_W +A writable segment. +.It Dv PF_R +A readable segment. +.El +.Pp +A text segment commonly has the flags +.Sy PF_X +and +.Sy PF_R . +A data segment commonly has +.Sy PF_X , +.Sy PF_W +and +.Sy PF_R . +.It Dv p_align +This member holds the value to which the segments are aligned in memory +and in the file. +Loadable process segments must have congruent values for +.Sy p_vaddr +and +.Sy p_offset , +modulo the page size. +Values of zero and one mean no alignment is required. +Otherwise, +.Sy p_align +should be a positive, integral power of two, and +.Sy p_vaddr +should equal +.Sy p_offset , +modulo +.Sy p_align . +.El +.Pp +A file's section header table lets one locate all the file's sections. +The +section header table is an array of Elf32_Shdr or Elf64_Shdr structures. +The +ELF header's +.Sy e_shoff +member gives the byte offset from the beginning of the file to the section +header table. +.Sy e_shnum +holds the number of entries the section header table contains. +.Sy e_shentsize +holds the size in bytes of each entry. +.Pp +A section header table index is a subscript into this array. +Some section +header table indices are reserved. +An object file does not have sections for +these special indices: +.Bl -tag -width "SHN_LORESERVE" +.It Dv SHN_UNDEF +This value marks an undefined, missing, irrelevant or otherwise meaningless +section reference. +.It Dv SHN_LORESERVE +This value specifies the lower bound of the range of reserved indices. +.It Dv SHN_LOPROC +Values greater than or equal to +.Sy SHN_HIPROC +are reserved for processor-specific semantics. +.It Dv SHN_HIPROC +Values less than or equal to +.Sy SHN_LOPROC +are reserved for processor-specific semantics. +.It Dv SHN_ABS +This value specifies the absolute value for the corresponding reference. +For +example, a symbol defined relative to section number +.Sy SHN_ABS +has an absolute value and is not affected by relocation. +.It Dv SHN_COMMON +Symbols defined relative to this section are common symbols, such as FORTRAN +COMMON or unallocated C external variables. +.It Dv SHN_HIRESERVE +This value specifies the upper bound of the range of reserved indices. +The +system reserves indices between +.Sy SHN_LORESERVE +and +.Sy SHN_HIRESERVE , +inclusive. +The section header table does not contain entries for the +reserved indices. +.El +.Pp +The section header has the following structure: +.Bd -literal -offset indent +typedef struct { + uint32_t sh_name; + uint32_t sh_type; + uint32_t sh_flags; + Elf32_Addr sh_addr; + Elf32_Off sh_offset; + uint32_t sh_size; + uint32_t sh_link; + uint32_t sh_info; + uint32_t sh_addralign; + uint32_t sh_entsize; +} Elf32_Shdr; +.Ed +.Bd -literal -offset indent +typedef struct { + uint32_t sh_name; + uint32_t sh_type; + uint64_t sh_flags; + Elf64_Addr sh_addr; + Elf64_Off sh_offset; + uint64_t sh_size; + uint32_t sh_link; + uint32_t sh_info; + uint64_t sh_addralign; + uint64_t sh_entsize; +} Elf64_Shdr; +.Ed +.Bl -tag -width "sh_addralign" +.It Dv sh_name +This member specifies the name of the section. +Its value is an index +into the section header string table section, giving the location of +a null-terminated string. +.It Dv sh_type +This member categorizes the section's contents and semantics. +.Bl -tag -width "SHT_PROGBITS" +.It Dv SHT_NULL +This value marks the section header as inactive. +It does not +have an associated section. +Other members of the section header +have undefined values. +.It Dv SHT_PROGBITS +This section holds information defined by the program, whose +format and meaning are determined solely by the program. +.It Dv SHT_SYMTAB +This section holds a symbol table. +Typically, +.Sy SHT_SYMTAB +provides symbols for link editing, though it may also be used +for dynamic linking. +As a complete symbol table, it may contain +many symbols unnecessary for dynamic linking. +An object file can +also contain a +.Sy SHN_DYNSYM +section. +.It Dv SHT_STRTAB +This section holds a string table. +An object file may have multiple +string table sections. +.It Dv SHT_RELA +This section holds relocation entries with explicit addends, such +as type +.Sy Elf32_Rela +for the 32-bit class of object files. +An object may have multiple +relocation sections. +.It Dv SHT_HASH +This section holds a symbol hash table. +An object participating in +dynamic linking must contain a symbol hash table. +An object file may +have only one hash table. +.It Dv SHT_DYNAMIC +This section holds information for dynamic linking. +An object file may +have only one dynamic section. +.It Dv SHT_NOTE +This section holds information that marks the file in some way. +.It Dv SHT_NOBITS +A section of this type occupies no space in the file but otherwise +resembles +.Sy SHN_PROGBITS . +Although this section contains no bytes, the +.Sy sh_offset +member contains the conceptual file offset. +.It Dv SHT_REL +This section holds relocation offsets without explicit addends, such +as type +.Sy Elf32_Rel +for the 32-bit class of object files. +An object file may have multiple +relocation sections. +.It Dv SHT_SHLIB +This section is reserved but has unspecified semantics. +.It Dv SHT_DYNSYM +This section holds a minimal set of dynamic linking symbols. +An +object file can also contain a +.Sy SHN_SYMTAB +section. +.It Dv SHT_LOPROC +This value up to and including +.Sy SHT_HIPROC +is reserved for processor-specific semantics. +.It Dv SHT_HIPROC +This value down to and including +.Sy SHT_LOPROC +is reserved for processor-specific semantics. +.It Dv SHT_LOUSER +This value specifies the lower bound of the range of indices reserved for +application programs. +.It Dv SHT_HIUSER +This value specifies the upper bound of the range of indices reserved for +application programs. +Section types between +.Sy SHT_LOUSER +and +.Sy SHT_HIUSER +may be used by the application, without conflicting with current or future +system-defined section types. +.El +.Pp +.It Dv sh_flags +Sections support one-bit flags that describe miscellaneous attributes. +If a flag bit is set in +.Sy sh_flags , +the attribute is +.Dq on +for the section. +Otherwise, the attribute is +.Dq off +or does not apply. +Undefined attributes are set to zero. +.Pp +.Bl -tag -width "SHF_EXECINSTR" -compact +.It Dv SHF_WRITE +This section contains data that should be writable during process +execution. +.It Dv SHF_ALLOC +This section occupies memory during process execution. +Some control +sections do not reside in the memory image of an object file. +This +attribute is off for those sections. +.It Dv SHF_EXECINSTR +This section contains executable machine instructions. +.It Dv SHF_MASKPROC +All bits included in this mask are reserved for processor-specific +semantics. +.El +.Pp +.It Dv sh_addr +If this section appears in the memory image of a process, this member +holds the address at which the section's first byte should reside. +Otherwise, the member contains zero. +.It Dv sh_offset +This member's value holds the byte offset from the beginning of the file +to the first byte in the section. +One section type, +.Sy SHT_NOBITS , +occupies no space in the file, and its +.Sy sh_offset +member locates the conceptual placement in the file. +.It Dv sh_size +This member holds the section's size in bytes. +Unless the section type +is +.Sy SHT_NOBITS , +the section occupies +.Sy sh_size +bytes in the file. +A section of type +.Sy SHT_NOBITS +may have a non-zero size, but it occupies no space in the file. +.It Dv sh_link +This member holds a section header table index link, whose interpretation +depends on the section type. +.It Dv sh_info +This member holds extra information, whose interpretation depends on the +section type. +.It Dv sh_addralign +Some sections have address alignment constraints. +If a section holds a +doubleword, the system must ensure doubleword alignment for the entire +section. +That is, the value of +.Sy sh_addr +must be congruent to zero, modulo the value of +.Sy sh_addralign . +Only zero and positive integral powers of two are allowed. +Values of zero +or one mean the section has no alignment constraints. +.It Dv sh_entsize +Some sections hold a table of fixed-sized entries, such as a symbol table. +For such a section, this member gives the size in bytes for each entry. +This member contains zero if the section does not hold a table of +fixed-size entries. +.El +.Pp +Various sections hold program and control information: +.Bl -tag -width ".shstrtab" +.It .bss +This section holds uninitialized data that contributes to the program's +memory image. +By definition, the system initializes the data with zeros +when the program begins to run. +This section is of type +.Sy SHT_NOBITS . +The attribute types are +.Sy SHF_ALLOC +and +.Sy SHF_WRITE . +.It .comment +This section holds version control information. +This section is of type +.Sy SHT_PROGBITS . +No attribute types are used. +.It .ctors +This section holds initialized pointers to the C++ constructor functions. +This section is of type +.Sy SHT_PROGBITS . +The attribute types are +.Sy SHF_ALLOC +and +.Sy SHF_WRITE . +.It .data +This section holds initialized data that contribute to the program's +memory image. +This section is of type +.Sy SHT_PROGBITS . +The attribute types are +.Sy SHF_ALLOC +and +.Sy SHF_WRITE . +.It .data1 +This section holds initialized data that contribute to the program's +memory image. +This section is of type +.Sy SHT_PROGBITS . +The attribute types are +.Sy SHF_ALLOC +and +.Sy SHF_WRITE . +.It .debug +This section holds information for symbolic debugging. +The contents +are unspecified. +This section is of type +.Sy SHT_PROGBITS . +No attribute types are used. +.It .dtors +This section holds initialized pointers to the C++ destructor functions. +This section is of type +.Sy SHT_PROGBITS . +The attribute types are +.Sy SHF_ALLOC +and +.Sy SHF_WRITE . +.It .dynamic +This section holds dynamic linking information. +The section's attributes +will include the +.Sy SHF_ALLOC +bit. +Whether the +.Sy SHF_WRITE +bit is set is processor-specific. +This section is of type +.Sy SHT_DYNAMIC . +See the attributes above. +.It .dynstr +This section holds strings needed for dynamic linking, most commonly +the strings that represent the names associated with symbol table entries. +This section is of type +.Sy SHT_STRTAB . +The attribute type used is +.Sy SHF_ALLOC . +.It .dynsym +This section holds the dynamic linking symbol table. +This section is of type +.Sy SHT_DYNSYM . +The attribute used is +.Sy SHF_ALLOC . +.It .fini +This section holds executable instructions that contribute to the process +termination code. +When a program exits normally the system arranges to +execute the code in this section. +This section is of type +.Sy SHT_PROGBITS . +The attributes used are +.Sy SHF_ALLOC +and +.Sy SHF_EXECINSTR . +.It .got +This section holds the global offset table. +This section is of type +.Sy SHT_PROGBITS . +The attributes are processor-specific. +.It .hash +This section holds a symbol hash table. +This section is of type +.Sy SHT_HASH . +The attribute used is +.Sy SHF_ALLOC . +.It .init +This section holds executable instructions that contribute to the process +initialization code. +When a program starts to run the system arranges to +execute the code in this section before calling the main program entry point. +This section is of type +.Sy SHT_PROGBITS . +The attributes used are +.Sy SHF_ALLOC +and +.Sy SHF_EXECINSTR . +.It .interp +This section holds the pathname of a program interpreter. +If the file has +a loadable segment that includes the section, the section's attributes will +include the +.Sy SHF_ALLOC +bit. +Otherwise, that bit will be off. +This section is of type +.Sy SHT_PROGBITS . +.It .line +This section holds line number information for symbolic debugging, which +describes the correspondence between the program source and the machine code. +The contents are unspecified. +This section is of type +.Sy SHT_PROGBITS . +No attribute types are used. +.It .note +This section holds information in the +.Dq Note Section +format described below. +This section is of type +.Sy SHT_NOTE . +No attribute types are used. +.Ox +native executables usually contain a +.Sy .note.openbsd.ident +section to identify themselves, for the kernel to bypass any compatibility +ELF binary emulation tests when loading the file. +.It .plt +This section holds the procedure linkage table. +This section is of type +.Sy SHT_PROGBITS . +The attributes are processor-specific. +.It .relNAME +This section holds relocation information as described below. +If the file +has a loadable segment that includes relocation, the section's attributes +will include the +.Sy SHF_ALLOC +bit. +Otherwise the bit will be off. +By convention, +.Dq NAME +is supplied by the section to which the relocations apply. +Thus a relocation +section for +.Sy .text +normally would have the name +.Sy .rel.text . +This section is of type +.Sy SHT_REL . +.It .relaNAME +This section holds relocation information as described below. +If the file +has a loadable segment that includes relocation, the section's attributes +will include the +.Sy SHF_ALLOC +bit. +Otherwise the bit will be off. +By convention, +.Dq NAME +is supplied by the section to which the relocations apply. +Thus a relocation +section for +.Sy .text +normally would have the name +.Sy .rela.text . +This section is of type +.Sy SHT_RELA . +.It .rodata +This section holds read-only data that typically contributes to a +non-writable segment in the process image. +This section is of type +.Sy SHT_PROGBITS . +The attribute used is +.Sy SHF_ALLOC . +.It .rodata1 +This section holds read-only data that typically contributes to a +non-writable segment in the process image. +This section is of type +.Sy SHT_PROGBITS . +The attribute used is +.Sy SHF_ALLOC . +.It .shstrtab +This section holds section names. +This section is of type +.Sy SHT_STRTAB . +No attribute types are used. +.It .strtab +This section holds strings, most commonly the strings that represent the +names associated with symbol table entries. +If the file has a loadable +segment that includes the symbol string table, the section's attributes +will include the +.Sy SHF_ALLOC +bit. +Otherwise the bit will be off. +This section is of type +.Sy SHT_STRTAB . +.It .symtab +This section holds a symbol table. +If the file has a loadable segment +that includes the symbol table, the section's attributes will include +the +.Sy SHF_ALLOC +bit. +Otherwise the bit will be off. +This section is of type +.Sy SHT_SYMTAB . +.It .text +This section holds the +.Dq text , +or executable instructions, of a program. +This section is of type +.Sy SHT_PROGBITS . +The attributes used are +.Sy SHF_ALLOC +and +.Sy SHF_EXECINSTR . +.El +.Pp +String table sections hold null-terminated character sequences, commonly +called strings. +The object file uses these strings to represent symbol +and section names. +One references a string as an index into the string +table section. +The first byte, which is index zero, is defined to hold +a null character. +Similarly, a string table's last byte is defined to +hold a null character, ensuring null termination for all strings. +.Pp +An object file's symbol table holds information needed to locate and +relocate a program's symbolic definitions and references. +A symbol table +index is a subscript into this array. +.Bd -literal -offset indent +typedef struct { + uint32_t st_name; + Elf32_Addr st_value; + uint32_t st_size; + unsigned char st_info; + unsigned char st_other; + uint16_t st_shndx; +} Elf32_Sym; +.Ed +.Bd -literal -offset indent +typedef struct { + uint32_t st_name; + unsigned char st_info; + unsigned char st_other; + uint16_t st_shndx; + Elf64_Addr st_value; + uint64_t st_size; +} Elf64_Sym; +.Ed +.Bl -tag -width "st_value" +.It Dv st_name +This member holds an index into the object file's symbol string table, +which holds character representations of the symbol names. +If the value +is non-zero, it represents a string table index that gives the symbol +name. +Otherwise, the symbol table has no name. +.It Dv st_value +This member gives the value of the associated symbol. +.It Dv st_size +Many symbols have associated sizes. +This member holds zero if the symbol +has no size or an unknown size. +.It Dv st_info +This member specifies the symbol's type and binding attributes: +.Bl -tag -width "STT_SECTION" +.It Dv STT_NOTYPE +The symbol's type is not defined. +.It Dv STT_OBJECT +The symbol is associated with a data object. +.It Dv STT_FUNC +The symbol is associated with a function or other executable code. +.It Dv STT_SECTION +The symbol is associated with a section. +Symbol table entries of +this type exist primarily for relocation and normally have +.Sy STB_LOCAL +bindings. +.It Dv STT_FILE +By convention, the symbol's name gives the name of the source file +associated with the object file. +A file symbol has +.Sy STB_LOCAL +bindings, its section index is +.Sy SHN_ABS , +and it precedes the other +.Sy STB_LOCAL +symbols of the file, if it is present. +.It Dv STT_LOPROC +This value up to and including +.Sy STT_HIPROC +is reserved for processor-specific semantics. +.It Dv STT_HIPROC +This value down to and including +.Sy STT_LOPROC +is reserved for processor-specific semantics. +.El +.Bl -tag -width "STB_GLOBAL" +.It Dv STB_LOCAL +Local symbols are not visible outside the object file containing their +definition. +Local symbols of the same name may exist in multiple files +without interfering with each other. +.It Dv STB_GLOBAL +Global symbols are visible to all object files being combined. +One file's +definition of a global symbol will satisfy another file's undefined +reference to the same symbol. +.It Dv STB_WEAK +Weak symbols resemble global symbols, but their definitions have lower +precedence. +.It Dv STB_LOPROC +This value up to and including +.Sy STB_HIPROC +is reserved for processor-specific semantics. +.It Dv STB_HIPROC +This value down to and including +.Sy STB_LOPROC +is reserved for processor-specific semantics. +.Pp +There are macros for packing and unpacking the binding and type fields: +.Pp +.Bl -tag -width "ELF32_ST_INFO(bind, type)" -compact +.It Xo +.Fn ELF32_ST_BIND info +.Xc +or +.Fn ELF64_ST_BIND info +extract a binding from an st_info value. +.It Xo +.Fn ELF64_ST_TYPE info +.Xc +or +.Fn ELF32_ST_TYPE info +extract a type from an st_info value. +.It Xo +.Fn ELF32_ST_INFO bind type +.Xc +or +.Fn ELF64_ST_INFO bind type +convert a binding and a type into an st_info value. +.El +.El +.Pp +.It Dv st_other +This member currently holds zero and has no defined meaning. +.It Dv st_shndx +Every symbol table entry is +.Dq defined +in relation to some section. +This member holds the relevant section +header table index. +.El +.Pp +Relocation is the process of connecting symbolic references with +symbolic definitions. +Relocatable files must have information that +describes how to modify their section contents, thus allowing executable +and shared object files to hold the right information for a process' +program image. +Relocation entries are these data. +.Pp +Relocation structures that do not need an addend: +.Bd -literal -offset indent +typedef struct { + Elf32_Addr r_offset; + uint32_t r_info; +} Elf32_Rel; +.Ed +.Bd -literal -offset indent +typedef struct { + Elf64_Addr r_offset; + uint64_t r_info; +} Elf64_Rel; +.Ed +.Pp +Relocation structures that need an addend: +.Bd -literal -offset indent +typedef struct { + Elf32_Addr r_offset; + uint32_t r_info; + int32_t r_addend; +} Elf32_Rela; +.Ed +.Bd -literal -offset indent +typedef struct { + Elf64_Addr r_offset; + uint64_t r_info; + int64_t r_addend; +} Elf64_Rela; +.Ed +.Bl -tag -width "r_offset" +.It Dv r_offset +This member gives the location at which to apply the relocation action. +For a relocatable file, the value is the byte offset from the beginning +of the section to the storage unit affected by the relocation. +For an +executable file or shared object, the value is the virtual address of +the storage unit affected by the relocation. +.It Dv r_info +This member gives both the symbol table index with respect to which the +relocation must be made and the type of relocation to apply. +Relocation +types are processor-specific. +When the text refers to a relocation +entry's relocation type or symbol table index, it means the result of +applying +.Sy ELF_[32|64]_R_TYPE +or +.Sy ELF[32|64]_R_SYM , +respectively, to the entry's +.Sy r_info +member. +.It Dv r_addend +This member specifies a constant addend used to compute the value to be +stored into the relocatable field. +.El +.Sh SEE ALSO +.Xr as 1 , +.Xr gdb 1 , +.Xr ld 1 , +.Xr objdump 1 , +.Xr execve 2 , +.Xr core 5 +.Rs +.%A Hewlett-Packard +.%B Elf-64 Object File Format +.Re +.Rs +.%A Santa Cruz Operation +.%B System V Application Binary Interface +.Re +.Rs +.%A Unix System Laboratories +.%T Object Files +.%B "Executable and Linking Format (ELF)" +.Re +.Sh HISTORY +.Ox +ELF support first appeared in +.Ox 1.2 , +although not all supported platforms use it as the native +binary file format. +ELF in itself first appeared in +.At V . +The ELF format is an adopted standard. +.Sh AUTHORS +The original version of this manual page was written by +.An Jeroen Ruigrok van der Werven +.Aq asmodai@FreeBSD.org +with inspiration from BSDi's +.Bsx +.Nm elf +manpage. diff --git a/man5/environ.5 b/man5/environ.5 new file mode 100644 index 000000000..326e5cc11 --- /dev/null +++ b/man5/environ.5 @@ -0,0 +1,221 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" and Andries Brouwer (aeb@cwi.nl), Fri Feb 14 21:47:50 1997. +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sun Jul 25 10:45:30 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Jul 21 21:25:26 1996 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Mon Oct 21 17:47:19 1996 by Eric S. Raymond (esr@thyrsus.com) +.\" Modified Wed Aug 27 20:28:58 1997 by Nicolás Lichtmaier (nick@debian.org) +.\" Modified Mon Sep 21 00:00:26 1998 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Wed Jan 24 06:37:24 2001 by Eric S. Raymond (esr@thyrsus.com) +.\" Modified Thu Dec 13 23:53:27 2001 by Martin Schulze +.\" +.TH ENVIRON 5 2001-12-14 "Linux" "Linux Programmer's Manual" +.SH NAME +environ \- user environment +.SH SYNOPSIS +.ad l +.nf +.B extern char **environ; +.br +.fi +.ad b +.SH DESCRIPTION +The variable +.I environ +points to an array of strings called the `environment'. +(This variable must be declared in the user program, +but is declared in the header file +.I unistd.h +in case the header files came from libc4 or libc5, and +in case they came from glibc and +.B _GNU_SOURCE +was defined.) +This array of strings is made available to the process by the +.BR exec (3) +call that started the process. By convention these strings +have the form `\fIname\fP\fB=\fP\fIvalue\fP'. Common examples are: +.TP +.B USER +The name of the logged-in user (used by some BSD-derived programs). +.TP +.B LOGNAME +The name of the logged-in user (used by some System-V derived programs). +.TP +.B HOME +A user's login directory, set by +.BR login (1) +from the password file +.BR passwd (5). +.TP +.B LANG +The name of a locale to use for locale categories when not overridden +by \fBLC_ALL\fP or more specific environment variables like +\fBLC_COLLATE\fP, \fBLC_CTYPE\fP, \fBLC_MESSAGES\fP, \fBLC_MONETARY\fP, +\fBLC_NUMERIC\fP, \fBLC_TIME\fP, cf. +.BR locale (5). +.TP +.B PATH +The sequence of directory prefixes that \fBsh\fP(1) and many other +programs apply in searching for a file known by an incomplete path name. +The prefixes are separated by `\fB:\fP'. +(Similarly one has \fBCDPATH\fP used by some shells to find the target +of a change directory command, \fBMANPATH\fP used by \fBman\fP(1) to +find manual pages, etc.) +.TP +.B PWD +The current working directory. Set by some shells. +.TP +.B SHELL +The file name of the user's login shell. +.TP +.B TERM +The terminal type for which output is to be prepared. +.TP +.B PAGER +The user's preferred utility to display text files. +.TP +.BR EDITOR / VISUAL +The user's preferred utility to edit text files. +.TP +.B BROWSER +The user's preferred utility to browse URLs. Sequence of colon-separated +browser commands. See http://www.catb.org/~esr/BROWSER/ . +.PP +Further names may be placed in the environment by the \fBexport\fP +command and `name=value' in +.BR sh (1), +or by the \fBsetenv\fP command if you use +.BR csh (1). +Arguments may also be placed in the +environment at the point of an +.BR exec (3). +A C program can manipulate its environment using the functions +.BR getenv (3), +.BR putenv (3), +.BR setenv (3), +and +.BR unsetenv (3). + +Note that the behaviour of many programs and library routines is +influenced by the presence or value of certain environment variables. +A random collection: +.LP +The variables +.BR LANG ", " LANGUAGE ", " NLSPATH ", " LOCPATH ", " LC_ALL ", " LC_MESSAGES ", " +etc. influence locale handling, cf. +.BR locale (5). +.LP +.B TMPDIR +influences the path prefix of names created by +\fBtmpnam(3)\fP and other routines, the temporary directory used by +\fBsort\fP(1) and other programs, etc. +.LP +.BR LD_LIBRARY_PATH ", " LD_PRELOAD +and other LD_* variables influence +the behaviour of the dynamic loader/linker. +.LP +.B POSIXLY_CORRECT +makes certain programs and library routines follow +the prescriptions of POSIX. +.LP +The behaviour of \fBmalloc\fP(3) is influenced by MALLOC_* variables. +.LP +The variable +.B HOSTALIASES +gives the name of a file containing aliases +to be used with \fBgethostbyname\fP(3). +.LP +.BR TZ " and " TZDIR +give time zone information used by +.BR tzset (3) +and through that by functions like +.IR ctime (), +.IR localtime (), +.IR mktime (), +.IR strftime (). +See also +.BR tzselect (1). +.LP +.B TERMCAP +gives information on how to address a given terminal +(or gives the name of a file containing such information). +.LP +.BR COLUMNS " and " LINES +tell applications about the window size, possibly overriding the actual size. +.LP +.BR PRINTER " or " LPDEST +may specify the desired printer to use. See +.BR lpr (1). +.LP +Etc. +.SH BUGS +Clearly there is a security risk here. Many a system command has been +tricked into mischief by a user who specified unusual values for +.BR IFS " or " LD_LIBRARY_PATH . + +There is also the risk of name space pollution. +Programs like +.I make +and +.I autoconf +allow overriding of default utility names from the +environment with similarly named variables in all caps. +Thus one uses +.B CC +to select the desired C compiler (and similarly +.BR MAKE , +.BR AR , +.BR AS , +.BR FC , +.BR LD , +.BR LEX , +.BR RM , +.BR YACC , +etc.). +However, in some traditional uses such an environment variable +gives options for the program instead of a pathname. +Thus, one has +.BR MORE , +.BR LESS , +and +.BR GZIP . +Such usage is considered mistaken, and to be avoided in new +programs. The authors of +.I gzip +should consider renaming their option to +.BR GZIP_OPT . +.SH "SEE ALSO" +.BR bash (1), +.BR csh (1), +.BR login (1), +.BR sh (1), +.BR tcsh (1), +.BR execve (2), +.BR clearenv (3), +.BR exec (3), +.BR getenv (3), +.BR putenv (3), +.BR setenv (3), +.BR unsetenv (3), +.BR locale (5) diff --git a/man5/fs.5 b/man5/fs.5 new file mode 100644 index 000000000..6e96517ae --- /dev/null +++ b/man5/fs.5 @@ -0,0 +1,162 @@ +.\" Copyright 1996 Daniel Quinlan (Daniel.Quinlan@linux.org) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH FILESYSTEMS 5 2001-12-07 "" "Linux Programmer's Manual" +.nh +.SH NAME +filesystems \- Linux filesystem types: minix, ext, ext2, ext3, xia, msdos, +umsdos, vfat, proc, nfs, iso9660, hpfs, sysv, smb, ncpfs +.SH DESCRIPTION +When, as is customary, the +.B proc +filesystem is mounted on +.IR /proc , +you can find in the file +.I /proc/filesystems +which filesystems your kernel currently supports. +If you need a currently unsupported one, insert the corresponding +module or recompile the kernel. + +In order to use a filesystem, you have to +.I mount +it, see +.BR mount (8) +for the mount command, and for the available mount options. + +Below a short description of a few of the available filesystems. + +.TP +.B "minix" +is the filesystem used in the Minix operating system, the first to run +under Linux. It has a number of shortcomings: a 64MB partition size +limit, short filenames, a single time stamp, etc. +It remains useful for floppies and RAM disks. +.TP +.B ext +is an elaborate extension of the +.B minix +filesystem. It has been completely superseded by the second version +of the extended filesystem +.RB ( ext2 ) +and has been removed from the kernel (in 2.1.21). +.TP +.B ext2 +is the high performance disk filesystem used by Linux for fixed disks +as well as removable media. +The second extended filesystem was designed as an extension of the +extended file system +.RB ( ext ). +.B ext2 +offers the best performance (in terms of speed and CPU usage) of +the filesystems supported under Linux. +.TP +.B ext3 +is a journaling version of the ext2 filesystem. It is easy to +switch back and forth between ext2 and ext3. +.TP +.B xiafs +was designed and implemented to be a stable, safe filesystem by +extending the Minix filesystem code. It provides the basic most +requested features without undue complexity. +The +.B xia +filesystem is no longer actively developed or maintained. +It was removed from the kernel in 2.1.21. +.TP +.B msdos +is the filesystem used by DOS, Windows, and some OS/2 computers. +.B msdos +filenames can be no longer than 8 characters, followed by an +optional period and 3 character extension. +.TP +.B umsdos +is an extended DOS filesystem used by Linux. It adds capability for +long filenames, UID/GID, POSIX permissions, and special files +(devices, named pipes, etc.) under the DOS filesystem, without +sacrificing compatibility with DOS. +.TP +.B vfat +is an extended DOS filesystem used by Microsoft Windows95 and Windows NT. +VFAT adds the capability to use long filenames under the MSDOS filesystem. +.TP +.B proc +is a pseudo-filesystem which is used as an interface to kernel data +structures rather than reading and interpreting +.IR /dev/kmem . +In particular, its files do not take disk space. See proc(5). +.TP +.B iso9660 +is a CD-ROM filesystem type conforming to the ISO 9660 standard. +.RS +.TP +.B "High Sierra" +Linux supports High Sierra, the precursor to the ISO 9660 standard for +CD-ROM filesystems. It is automatically recognized within the +.B iso9660 +filesystem support under Linux. +.TP +.B "Rock Ridge" +Linux also supports the System Use Sharing Protocol records specified +by the Rock Ridge Interchange Protocol. They are used to further +describe the files in the +.B iso9660 +filesystem to a UNIX host, and provide information such as long +filenames, UID/GID, POSIX permissions, and devices. It is +automatically recognized within the +.B iso9660 +filesystem support under Linux. +.RE +.TP +.B hpfs +is the High Performance Filesystem, used in OS/2. This filesystem is +read-only under Linux due to the lack of available documentation. +.TP +.B sysv +is an implementation of the SystemV/Coherent filesystem for Linux. It +implements all of Xenix FS, SystemV/386 FS, and Coherent FS. +.TP +.B nfs +is the network filesystem used to access disks located on remote computers. +.TP +.B smb +is a network filesystem that supports the SMB protocol, used by +Windows for Workgroups, Windows NT, and Lan Manager. +.sp +To use +.B smb +fs, you need a special mount program, which can be found in the ksmbfs +package, found at +.IR ftp://sunsite.unc.edu/pub/Linux/system/Filesystems/smbfs . +.TP +.B ncpfs +is a network filesystem that supports the NCP protocol, used by +Novell NetWare. +.sp +To use +.BR ncpfs , +you need special programs, which can be found at +.IR ftp://linux01.gwdg.de/pub/ncpfs . +.SH "SEE ALSO" +.BR proc (5), +.BR fsck (8), +.BR mkfs (8), +.BR mount (8) diff --git a/man5/ftpusers.5 b/man5/ftpusers.5 new file mode 100644 index 000000000..9b429c756 --- /dev/null +++ b/man5/ftpusers.5 @@ -0,0 +1,46 @@ +.\" Copyright (c) 2000 Christoph J. Thompson +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.TH FTPUSERS 5 2000-08-27 "File formats" "Linux Programmer's Manual" +.SH NAME +ftpusers \- list of users that may not log in via the FTP daemon +.SH DESCRIPTION +The text file +.B ftpusers +contains a list of users that may not log in using the +File Transfer Protocol (FTP) server daemon. This file is used not merely for +system administration purposes but for improving security within a TCP/IP +networked environment. It will typically contain a list of the users that +either have no business using ftp or have too many privileges to be allowed +to log in through the FTP server daemon. +Such users usually include root, daemon, bin, uucp, and news. +If your FTP server daemon doesn't use +.B ftpusers +then it is suggested that you read its documentation to find out how to +block access for certain users. Washington University FTP server Daemon +(wuftpd) and Professional FTP Daemon (proftpd) are known to make use of +.BR ftpusers . +.SH FORMAT +The format of +.B ftpusers +is very simple. There is one account name (or user name) per line. +Lines starting with a # are ignored. +.SH FILES +.I /etc/ftpusers +.SH "SEE ALSO" +.BR passwd (5), +.BR proftpd (8), +.BR wuftpd (8) diff --git a/man5/group.5 b/man5/group.5 new file mode 100644 index 000000000..1356ddb12 --- /dev/null +++ b/man5/group.5 @@ -0,0 +1,54 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 17:06:03 1993 by Rik Faith (faith@cs.unc.edu) +.TH GROUP 5 1992-12-29 "Linux" "Linux Programmer's Manual" +.SH NAME +group \- user group file +.SH DESCRIPTION +\fB/etc/group\fP is an ASCII file which defines the groups to which users +belong. There is one entry per line, and each line has the format: +.sp +.RS +group_name:passwd:GID:user_list +.RE +.sp +The field descriptions are: +.IP group_name +the name of the group. +.IP password +the (encrypted) group password. If this field is +empty, no password is needed. +.IP GID +the numerical group ID. +.IP user_list +all the group member's user names, separated by commas. +.SH BUGS +As the 4.2BSD +.BR initgroups (3) +man page says: Noone seems to keep /etc/group up-to-date. +.SH FILES +/etc/group +.SH "SEE ALSO" +.BR login (1), +.BR newgrp (1), +.BR passwd (5) diff --git a/man5/host.conf.5 b/man5/host.conf.5 new file mode 100644 index 000000000..5bf1d6a03 --- /dev/null +++ b/man5/host.conf.5 @@ -0,0 +1,192 @@ +.\" Copyright (c) 1997 Martin Schulze (joey@infodrom.north.de) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, +.\" USA. +.\" +.\" Much of the text is copied from the manpage of resolv+(8). +.\" +.\" 2003-08-23 Martin Schulze Updated according to glibc 2.3.2 +.TH HOST.CONF 5 2003-08-23 "Debian GNU/Linux" "Linux System Administration" +.SH NAME +host.conf \- resolver configuration file +.SH DESCRIPTION +The file +.I /etc/host.conf +contains configuration information specific to the resolver library. +It should contain one configuration keyword per line, followed by +appropriate configuration information. The keywords recognized are +.IR order ", " trim ", " multi ", " nospoof ", " spoof ", and " reorder . +These keywords are described below. + +.TP +.I order +This keyword specifies how host lookups are to be performed. It +should be followed by one or more lookup methods, separated by commas. +Valid methods are +.IR bind ", " hosts ", and " nis . +.TP +.I trim +This keyword may be listed more than once. Each time it should be +followed by a list of domains, separated by colons (`:'), semicolons +(`;') or commas (`,'), with the leading dot. When set, the +resolv+ library will automatically trim the given domain name from the +end of any hostname resolved via DNS. This is intended for use with +local hosts and domains. (Related note: trim will not affect hostnames +gathered via NIS or the hosts file. Care should be taken to +ensure that the first hostname for each entry in the hosts file is +fully qualified or non-qualified, as appropriate for the local +installation.) +.TP +.I multi +Valid values are +.IR on " and " off . +If set to +.IR on , +the resolv+ library will return all valid addresses for a host that +appears in the +.I /etc/hosts +file, +instead of only the first. This is +.I off +by default, as it may cause a substantial performance loss at sites +with large hosts files. +.TP +.I nospoof +Valid values are +.IR on " and " off . +If set to +.IR on , +the resolv+ library will attempt to prevent hostname spoofing to +enhance the security of +.BR rlogin " and " rsh . +It works as follows: after performing a host address lookup, resolv+ +will perform a hostname lookup for that address. If the two hostnames +do not match, the query will fail. +The default value is +.IR off . +.TP +.I spoofalert +Valid values are +.IR on " and " off . +If this option is set to +.I on +and the +.I nospoof +option is also set, resolv+ will log a warning of the error via the +syslog facility. The default value is +.IR off . +.TP +.I spoof +Valid values are +.IR off ", " nowarn " and " warn . +If this option is set to +.IR off , +spoofed addresses are permitted and no warnings will be emitted +via the syslog facility. +If this option is set to +.IR warn , +resolv+ will attempt to prevent hostname spoofing to +enhance the security and log a warning of the error via the syslog +facility. +If this option is set to +.IR nowarn , +the resolv+ library will attempt to prevent hostname spoofing to +enhance the security but not emit warnings via the syslog facility. +Setting this option to anything else is equal to setting it to +.IR nowarn . +.TP +.I reorder +Valid values are +.IR on " and " off . +If set to +.IR on , +resolv+ will attempt to reorder host addresses so that local addresses +(i.e., on the same subnet) are listed first when a +.BR gethostbyname (3) +is performed. Reordering is done for all lookup methods. The default +value is +.IR off . +.SH ENVIRONMENT +There are six environment variables that can be used to allow users to +override the behavior which is configured in +.IR /etc/host.conf . +.TP +.B RESOLV_HOST_CONF +If set this variable points to a file that should be read instead of +.IR /etc/host.conf . +.TP +.B RESOLV_SERV_ORDER +Overrides the +.I order +command. +.TP +.B RESOLV_SPOOF_CHECK +Overrides the +.IR nospoof ", " spoofalert " and " spoof +commands in the same way as the +.I spoof +command is parsed. Valid values are +.IR off ", " nowarn " and " warn . +.TP +.B RESOLV_MULTI +Overrides the +.I multi +command. +.TP +.B RESOLV_REORDER +Overrides the +.I reorder +command. +.TP +.B RESOLV_ADD_TRIM_DOMAINS +A list of domains, separated by colons (`:'), semicolons (`;') or +commas (`,'), with the leading dot, which will be added to the list of +domains that should be trimmed. +.TP +.B RESOLV_OVERRIDE_TRIM_DOMAINS +A list of domains, separated by colons (`:'), semicolons (`;') or +commas (`,'), with the leading dot, which will replace the list of +domains that should be trimmed. Overrides the +.I trim +command. +.SH FILES +.TP +.I /etc/host.conf +Resolver configuration file +.TP +.I /etc/resolv.conf +Resolver configuration file +.TP +.I /etc/hosts +Local hosts database +.SH NOTES +The following differences exist compared to the original implementation. +A new command +.I spoof +and a new environment variable +.B RESOLV_SPOOF_CHECK +can take arguments like +.IR off ", " nowarn " and " warn . +Line comments can appear anywhere and not only at the beginning of a line. +.SH "SEE ALSO" +.BR gethostbyname (3), +.BR hostname (7), +.BR named (8), +.BR resolv+ (8) diff --git a/man5/hosts.5 b/man5/hosts.5 new file mode 100644 index 000000000..334fee197 --- /dev/null +++ b/man5/hosts.5 @@ -0,0 +1,107 @@ +.\" Hey, Emacs! This is an -*- nroff -*- source file. +.\" Copyright (c) 2000 Manoj Srivastava +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, +.\" USA. +.\" +.\" Minor polishing, aeb +.\" Modified, 2002-06-16, Mike Coleman +.\" +.TH HOSTS 5 2002-06-16 "Debian" "Linux Programmer's Manual" +.SH NAME +hosts \- The static table lookup for host names +.SH SYNOPSIS +.B /etc/hosts +.SH DESCRIPTION +This manual page describes the format of the +.I /etc/hosts +file. This file is a simple text file that associates IP addresses +with hostnames, one line per IP address. For each host a single +line should be present with the following information: +.RS +.PP +IP_address canonical_hostname aliases +.RE +.PP +Fields of the entry are separated by any number of blanks and/or +tab characters. Text from a "#" character until the end of the line is +a comment, and is ignored. Host names may contain only alphanumeric +characters, minus signs ("-"), and periods ("."). They must begin with an +alphabetic character and end with an alphanumeric character. +Aliases provide for name changes, alternate spellings, +shorter hostnames, or generic hostnames (for example, +.IR localhost ). +The format of the host table is described in RFC 952. +.PP +The Berkeley Internet Name Domain (BIND) Server implements the +Internet name server for UNIX systems. It augments or replaces the +.I /etc/hosts +file or host name lookup, and frees a host from relying on +.I /etc/hosts +being up to date and complete. +.PP +In modern systems, even though the host table has been superseded by +DNS, it is still widely used for: +.TP +.B bootstrapping +Most systems have a small host table containing the name and address +information for important hosts on the local network. This is useful +when DNS is not running, for example during system bootup. +.TP +.B NIS +Sites that use NIS use the host table as input to the NIS host +database. Even though NIS can be used with DNS, most NIS sites still +use the host table with an entry for all local hosts as a backup. +.TP +.B isolated nodes +Very small sites that are isolated from the network use the host table +instead of DNS. If the local information rarely changes, and the +network is not connected to the Internet, DNS offers little +advantage. +.SH EXAMPLE +.nf + 127.0.0.1 localhost + 192.168.1.10 foo.mydomain.org foo + 192.168.1.13 bar.mydomain.org bar + 216.234.231.5 master.debian.org master + 205.230.163.103 www.opensource.org +.fi +.SH "HISTORICAL NOTE" +Before the advent of DNS, the host table was the only way of resolving +hostnames on the fledgling Internet. Indeed, this file could be +created from the official host data base maintained at the Network +Information Control Center (NIC), though local changes were often +required to bring it up to date regarding unofficial aliases and/or +unknown hosts. The NIC no longer maintains the hosts.txt files, +though looking around at the time of writing (circa 2000), there are +historical hosts.txt files on the WWW. I just found three, from 92, +94, and 95. +.SH FILES +.I /etc/hosts +.SH "SEE ALSO" +.BR hostname (1), +.BR resolver (3), +.BR resolver (5), +.BR hostname (7), +.BR named (8), +Internet RFC 952 +.SH AUTHOR +This manual page was written by Manoj Srivastava , +for the Debian GNU/Linux system. diff --git a/man5/hosts.equiv.5 b/man5/hosts.equiv.5 new file mode 100644 index 000000000..cbc0eb3e0 --- /dev/null +++ b/man5/hosts.equiv.5 @@ -0,0 +1,56 @@ +.\" Copyright (c) 1995 Peter Tobias +.\" This file may be distributed under the GNU General Public License. +.TH HOSTS.EQUIV 5 2003-08-24 "Linux" "Linux Programmer's Manual" +.SH NAME +/etc/hosts.equiv \- list of hosts and users that are granted "trusted" +\fBr\fP command access to your system +.SH DESCRIPTION +The \fBhosts.equiv\fP file allows or denies hosts and users to use +the \fBr\fP-commands (e.g. \fBrlogin\fP, \fBrsh\fP or \fBrcp\fP) without +supplying a password. +.PP +The file uses the following format: +.TP +\fI[ + | - ]\fP \fI[hostname]\fP \fI[username]\fP +.PP +The \fIhostname\fP is the name of a host which is logically equivalent +to the local host. Users logged into that host are allowed to access +like-named user accounts on the local host without supplying a password. +The \fIhostname\fP may be (optionally) preceded by a plus (+) sign. +If the plus sign is used alone it allows any host to access your system. +You can expicitly deny access to a host by preceding the \fIhostname\fP +by a minus (-) sign. Users from that host must always supply a password. +For security reasons you should always use the FQDN of the hostname and +not the short hostname. +.PP +The \fIusername\fP entry grants a specific user access to all user +accounts (except root) without supplying a password. That means the +user is NOT restricted to like-named accounts. The \fIusername\fP may +be (optionally) preceded by a plus (+) sign. You can also explicitly +deny access to a specific user by preceding the \fIusername\fP with +a minus (-) sign. This says that the user is not trusted no matter +what other entries for that host exist. +.PP +Netgroups can be specified by preceding the netgroup by an @ sign. +.PP +Be extremely careful when using the plus (+) sign. A simple typographical +error could result in a standalone plus sign. A standalone plus sign is +a wildcard character that means "any host"! +.SH FILES +.I /etc/hosts.equiv +.SH NOTES +Some systems will only honor the contents of this file when it has owner +root and no write permission for anybody else. Some exceptionally +paranoid systems even require that there be no other hard links to the file. +.PP +Modern systems use the Pluggable Authentication Modules library (PAM). +With PAM a standalone plus sign is only considered a wildcard +character which means "any host" when the word +.I promiscuous +is added to the auth component line in your PAM file for +the particular service +.RB "(e.g. " rlogin ). +.SH "SEE ALSO" +.BR rhosts (5), +.BR rlogind (8), +.BR rshd (8) diff --git a/man5/intro.5 b/man5/intro.5 new file mode 100644 index 000000000..792e4af0a --- /dev/null +++ b/man5/intro.5 @@ -0,0 +1,33 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 17:06:52 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Jan 14 00:34:09 1996 by Andries Brouwer (aeb@cwi.nl) +.TH INTRO 5 1993-07-24 "Linux" "Linux Programmer's Manual" +.SH NAME +intro \- Introduction to file formats +.SH DESCRIPTION +This chapter describes various file formats and protocols, +and the used C structures, if any. +.SH AUTHORS +Look at the header of the manual page for the author(s) and copyright +conditions. Note that these can be different from page to page! diff --git a/man5/ipc.5 b/man5/ipc.5 new file mode 100644 index 000000000..b7c1051cd --- /dev/null +++ b/man5/ipc.5 @@ -0,0 +1,383 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH IPC 5 1993-11-01 "Linux 0.99.13" "Linux Programmer's Manual" +.SH NAME +ipc \- System V interprocess communication mechanisms +.SH SYNOPSIS +.nf +.B +# include +.B +# include +.B +# include +.B +# include +.B +# include +.SH DESCRIPTION +This manual page refers to the Linux implementation of the System V +interprocess communication mechanisms: +message queues, semaphore sets, and shared memory segments. +In the following, the word +.B resource +means an instantiation of one among such mechanisms. +.SS Resource Access Permissions +For each resource, the system uses a common structure of type +.BR "struct ipc_perm" +to store information needed in determining permissions to perform an +ipc operation. +The +.B ipc_perm +structure, defined by the +.I +system header file, includes the following members: +.sp +.B + ushort cuid; +/* creator user id */ +.br +.B + ushort cgid; +/* creator group id */ +.br +.B + ushort uid; +/* owner user id */ +.br +.B + ushort gid; +/* owner group id */ +.br +.B + ushort mode; +/* r/w permissions */ +.PP +The +.B mode +member of the +.B ipc_perm +structure defines, with its lower 9 bits, the access permissions to the +resource for a process executing an ipc system call. +The permissions are interpreted as follows: +.sp +.nf + 0400 Read by user. + 0200 Write by user. +.sp .5 + 0040 Read by group. + 0020 Write by group. +.sp .5 + 0004 Read by others. + 0002 Write by others. +.fi +.PP +Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. +Furthermore, +"write" +effectively means +"alter" +for a semaphore set. +.PP +The same system header file also defines the following symbolic +constants: +.TP 14 +.B IPC_CREAT +Create entry if key doesn't exist. +.TP +.B IPC_EXCL +Fail if key exists. +.TP +.B IPC_NOWAIT +Error if request must wait. +.TP +.B IPC_PRIVATE +Private key. +.TP +.B IPC_RMID +Remove resource. +.TP +.B IPC_SET +Set resource options. +.TP +.B IPC_STAT +Get resource options. +.PP +Note that +.B IPC_PRIVATE +is a +.B key_t +type, while all the other symbolic constants are flag fields and can +be OR'ed into an +.B int +type variable. +.SS Message Queues +A message queue is uniquely identified by a positive integer +.RI "(its " msqid ) +and has an associated data structure of type +.BR "struct msqid_ds" , +defined in +.IR , +containing the following members: +.sp +.B + struct ipc_perm msg_perm; +.br +.B + ushort msg_qnum; +/* no of messages on queue */ +.br +.B + ushort msg_qbytes; +/* bytes max on a queue */ +.br +.B + ushort msg_lspid; +/* pid of last msgsnd call */ +.br +.B + ushort msg_lrpid; +/* pid of last msgrcv call */ +.br +.B + time_t msg_stime; +/* last msgsnd time */ +.br +.B + time_t msg_rtime; +/* last msgrcv time */ +.br +.B + time_t msg_ctime; +/* last change time */ +.TP 11 +.B msg_perm +.B ipc_perm +structure that specifies the access permissions on the message +queue. +.TP +.B msg_qnum +Number of messages currently on the message queue. +.TP +.B msg_qbytes +Maximum number of bytes of message text allowed on the message +queue. +.TP +.B msg_lspid +ID of the process that performed the last +.B msgsnd +system call. +.TP +.B msg_lrpid +ID of the process that performed the last +.B msgrcv +system call. +.TP +.B msg_stime +Time of the last +.B msgsnd +system call. +.TP +.B msg_rtime +Time of the last +.B msgcv +system call. +.TP +.B msg_ctime +Time of the last +system call that changed a member of the +.B msqid_ds +structure. +.SS Semaphore Sets +A semaphore set is uniquely identified by a positive integer +.RI "(its " semid ) +and has an associated data structure of type +.BR "struct semid_ds" , +defined in +.IR , +containing the following members: +.sp +.B + struct ipc_perm sem_perm; +.br +.B + time_t sem_otime; +/* last operation time */ +.br +.B + time_t sem_ctime; +/* last change time */ +.br +.B + ushort sem_nsems; +/* count of sems in set */ +.TP 11 +.B sem_perm +.B ipc_perm +structure that specifies the access permissions on the semaphore +set. +.TP +.B sem_otime +Time of last +.B semop +system call. +.TP +.B sem_ctime +Time of last +.B semctl +system call that changed a member of the above structure or of one +semaphore belonging to the set. +.TP +.B sem_nsems +Number of semaphores in the set. +Each semaphore of the set is referenced by a non-negative integer +ranging from +.B 0 +to +.BR sem_nsems\-1 . +.PP +A semaphore is a data structure of type +.B "struct sem" +containing the following members: +.sp +.B + ushort semval; +/* semaphore value */ +.br +.B + short sempid; +/* pid for last operation */ +.br +.B + ushort semncnt; +/* nr awaiting semval to increase */ +.br +.B + ushort semzcnt; +/* nr awaiting semval = 0 */ +.TP 11 +.B semval +Semaphore value: a non-negative integer. +.TP +.B sempid +ID of the last process that performed a semaphore operation +on this semaphore. +.TP +.B semncnt +Number of processes suspended awaiting for +.B semval +to increase. +.TP +.B semznt +Number of processes suspended awaiting for +.B semval +to become zero. +.SS Shared Memory Segments +A shared memory segment is uniquely identified by a positive integer +.RI "(its " shmid ) +and has an associated data structure of type +.BR "struct shmid_ds" , +defined in +.IR , +containing the following members: +.sp +.B + struct ipc_perm shm_perm; +.br +.B + int shm_segsz; +/* size of segment */ +.br +.B + ushort shm_cpid; +/* pid of creator */ +.br +.B + ushort shm_lpid; +/* pid, last operation */ +.br +.B + short shm_nattch; +/* no. of current attaches */ +.br +.B + time_t shm_atime; +/* time of last attach */ +.br +.B + time_t shm_dtime; +/* time of last detach */ +.br +.B + time_t shm_ctime; +/* time of last change */ +.TP 11 +.B shm_perm +.B ipc_perm +structure that specifies the access permissions on the shared memory +segment. +.TP +.B shm_segsz +Size in bytes of the shared memory segment. +.TP +.B shm_cpid +ID of the process that created the shared memory segment. +.TP +.B shm_lpid +ID of the last process that executed a +.B shmat +or +.B shmdt +system call. +.TP +.B shm_nattch +Number of current alive attaches for this shared memory segment. +.TP +.B shm_atime +Time of the last +.B shmat +system call. +.TP +.B shm_dtime +Time of the last +.B shmdt +system call. +.TP +.B shm_ctime +Time of the last +.B shmctl +system call that changed +.BR shmid_ds . +.SH "SEE ALSO" +.BR msgctl (2), +.BR msgget (2), +.BR msgrcv (2), +.BR msgsnd (2), +.BR semctl (2), +.BR semget (2), +.BR semop (2), +.BR shmat (2), +.BR shmctl (2), +.BR shmdt (2), +.BR shmget (2), +.BR ftok (3) diff --git a/man5/issue.5 b/man5/issue.5 new file mode 100644 index 000000000..27ca843a5 --- /dev/null +++ b/man5/issue.5 @@ -0,0 +1,38 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sun Jul 25 11:06:22 1993 by Rik Faith +.\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond +.TH ISSUE 5 1993-07-24 "Linux" "Linux Programmer's Manual" +.SH NAME +issue \- pre-login message and identification file +.SH DESCRIPTION +The file \fB/etc/issue\fP is a text file which contains a message or +system identification to be printed before the login prompt. It may +contain various \fB@\fP\fIchar\fP and \fB\e\fP\fIchar\fP sequences, if +supported by +.BR getty (1). +.SH FILES +/etc/issue +.SH "SEE ALSO" +.BR getty (1), +.BR motd (5) diff --git a/man5/locale.5 b/man5/locale.5 new file mode 100644 index 000000000..836663af2 --- /dev/null +++ b/man5/locale.5 @@ -0,0 +1,576 @@ +.\" Hey Emacs, this is -*- nroff -*- +.\" +.\" This file is part of locale(1) which displays the settings of the +.\" current locale. +.\" Copyright (C) 1994 Jochen Hein (Hein@Student.TU-Clausthal.de) +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program; if not, write to the Free Software +.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA. +.\" +.TH LOCALE 5 1994-11-09 "National Language Support" "Linux User Manual" +.SH NAME +locale \- Describes a locale definition file +.SH DESCRIPTION +The +.B locale +definition files contains all the information that the +.BR localedef (1) +command needs to convert it into the binary locale database. + +The definition files consist of sections which each describe a +locale category in detail. +.SH SYNTAX +The locale definition file starts with a header that may consist +of the following keywords: +.TP +.I +is followed by a character that should be used as the +escape-character for the rest of the file to mark characters that +should be interpreted in a special way. It defaults to +the backslash ( +.B \\\\ +). +.TP +.I +is followed by a character that will be used as the +comment-character for the rest of the file. It defaults to the +number sign (#). + +.PP +The locale definition has one part for each locale category. +Each part can be copied from another existing locale or +can be defined from scratch. If the category should be copied, +the only valid keyword in the definition is +.B copy +followed by the name of the locale which should be copied. + +.SS LC_CTYPE +The definition for the +.B LC_CTYPE +category starts with the string +.I LC_CTYPE +in the first column. + +There are the following keywords allowed: + +.TP +.I upper +followed by a list of uppercase letters. The letters +.B A +trough +.B Z +are included automatically. Characters also specified as +.BR cntrl , +.BR digit , +.BR punct , +or +.B space +are not allowed. + +.TP +.I lower +followed by a list of lowercase letters. The letters +.B a +trough +.B z +are included automatically. Characters also specified as +.BR cntrl , +.BR digit , +.BR punct , +or +.B space +are not allowed. + +.TP +.I alpha +followed by a list of letters. All character specified as either +.B upper +or +.B lower +are automatically included. Characters also specified as +.BR cntrl , +.BR digit , +.BR punct , +or +.B space +are not allowed. + +.TP +.I digit +followed by the characters classified as numeric digits. Only the +digits +.B 0 +trough +.B 9 +are allowed. They are included by default in this class. + +.TP +.I space +followed by a list of characters defined as white-space +characters. Characters also specified as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR graph , +or +.B xdigit +are not allowed. The characters +.BR , +.BR , +.BR , +.BR , +.BR , +and +.B +are automatically included. + +.TP +.I cntrl +followed by a list of control characters. +Characters also specified as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR punct , +.BR graph , +.BR print , +or +.B xdigit +are not allowed. +.TP +.I punct +followed by a list of punctuation characters. Characters also +specified as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR cntrl , +.BR xdigit , +or the +.B +character are not allowed. + +.TP +.I graph +followed by a list of printable characters, not including the +.B +character. The characters defined as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR xdigit , +and +.B punct +are automatically included. +Characters also specified as +.B cntrl +are not allowed. + +.TP +.I print +followed by a list of printable characters, including the +.B +character. The characters defined as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR xdigit , +.BR punct , +and the +.B +character are automatically included. +Characters also specified as +.B cntrl +are not allowed. + +.TP +.I xdigit +followed by a list of characters classified as hexadecimal +digits. The decimal digits must be included followed by one or +more set of six characters in ascending order. The following +characters are included by default: +.B 0 +trough +.BR 9 , +.B a +trough +.BR f , +.B A +trough +.BR F . + +.TP +.I blank +followed by a list of characters classified as +.BR blank . +The characters +.B +and +.B +are automatically included. + +.TP +.I toupper +followed by a list of mappings from lowercase to uppercase +letters. Each mapping is a pair of a lowercase and an uppercase letter +separated with a +.B , +and enclosed in parentheses. The members of the list are separated +with semicolons. +.TP +.I tolower +followed by a list of mappings from uppercase to lowercase +letters. If the keyword tolower is not present, the reverse of the +toupper list is used. + +.PP +The +.B LC_CTYPE +definition ends with the string +.I END LC_CYTPE. + +.SS LC_COLLATE +The +.B LC_COLLATE +category defines the rules for collating characters. Due to +limitations of libc not all POSIX-options are implemented. + +The definition starts with the string +.B LC_COLLATE +in the first column. + +There are the following keywords allowed: + +.TP +.I collating-element + +.TP +.I collating-symbol + +.PP +The order-definition starts with a line: +.TP +.I order_start +.PP +followed by a list of keywords out of +.B forward, +.B backward, +or +.B position. +The order definition consists of lines that describe the order +and is terminated with the keyword +.TP +.I order_end. +.PP + +For more details see the sources in +.B /usr/lib/nls/src +notably the examples +.B POSIX, +.B Example +and +.B Example2 + +.PP +The +.B LC_COLLATE +definition ends with the string +.I END LC_COLLATE. + +.SS LC_MONETARY +The definition starts with the string +.B LC_MONETARY +in the first column. + +There are the following keywords allowed: + +.TP +.I int_curr_symbol +followed by the international currency symbol. This must be a +4-character string containing the international currency symbol as +defined by the ISO 4217 standard (three characters) followed by a +separator. +.TP +.I currency_symbol +followed by the local currency symbol. +.TP +.I mon_decimal_point +followed by the string that will be used as the decimal delimiter +when formatting monetary quantities. +.TP +.I mon_thousands_sep +followed by the string that will be used as a group separator +when formatting monetary quantities. +.TP +.I mon_grouping +followed by a string that describes the formatting of numeric +quantities. +.TP +.I positive_sign +followed by a string that is used to indicate a positive sign for +monetary quantities. +.TP +.I negative_sign +followed by a string that is used to indicate a negative sign for +monetary quantities. +.TP +.I int_frac_digits +followed by the number of fractional digits that should be used when +formatting with the +.B int_curr_symbol. +.TP +.I frac_digits +followed by the number of fractional digits that should be used when +formatting with the +.B currency_symbol. +.TP +.I p_cs_precedes +followed by an integer set to +.B 1 +if the +.I currency_symbol +or +.I int_curr_symbol + should precede the formatted monetary quantity or set to +.B 0 +if the symbol succeeds the value. +.TP +.I p_sep_by_space +followed by an integer. +.RS +.TP +.B 0 +means that no space should be printed between the symbol and the +value. +.TP +.B 1 +means that a space should be printed between the symbol and the +value. +.TP +.B 2 +means that a space should be printed between the symbol and the +sign string, if adjacent. +.RE +.TP +.I n_cs_precedes +.RS +.TP +.B 0 +- the symbol succeeds the value. +.TP +.B 1 +- the symbol precedes the value. +.RE +.TP +.I n_sep_by_space +An integer set to +.B 0 +if no space separates the +.I currency_symbol +or +.I int_curr_symbol +from the value for a negative monetary quantity, set to +.B 1 +if a space separates the symbol from the value and set to +.B 2 +if a space separates the symbol and the sign string, if adjacent. +.TP +.I p_sign_posn +.RS +.TP +.B 0 +Parentheses enclose the quantity and the +.I currency_symbol +or +.I int_curr_symbol. +.TP +.B 1 +The sign string precedes the quantity and the +.I currency_symbol +or the +.I int_curr_symbol. +.TP +.B 2 +The sign string succeeds the quantity and the +.I currency_symbol +or the +.I int_curr_symbol. +.TP +.B 3 +The sign string precedes the +.I currency_symbol +or the +.I int_curr_symbol. +.TP +.B 4 +The sign string succeeds the +.I currency_symbol +or the +.I int_curr_symbol. +.RE +.TP +.I n_sign_posn +.RS +.TP +.B 0 +Parentheses enclose the quantity and the +.I currency_symbol +or +.I int_curr_symbol. +.TP +.B 1 +The sign string precedes the quantity and the +.I currency_symbol +or the +.I int_curr_symbol. +.TP +.B 2 +The sign string succeeds the quantity and the +.I currency_symbol +or the +.I int_curr_symbol. +.TP +.B 3 +The sign string precedes the +.I currency_symbol +or the +.I int_curr_symbol. +.TP +.B 4 +The sign string succeeds the +.I currency_symbol +or the +.I int_curr_symbol. +.RE +.PP +The +.B LC_MONETARY +definition ends with the string +.I END LC_MONETARY. + +.SS LC_NUMERIC +The definition starts with the string +.B LC_NUMERIC +in the first column. + +The following keywords are allowed: + +.TP +.I decimal_point +followed by the string that will be used as the decimal delimiter +when formatting numeric quantities. +.TP +.I thousands_sep +followed by the string that will be used as a group separator +when formatting numeric quantities. +.TP +.I grouping +followed by a string that describes the formatting of numeric +quantities. +.PP +The +.B LC_NUMERIC +definition ends with the string +.I END LC_NUMERIC. + +.SS LC_TIME +The definition starts with the string +.B LC_TIME +in the first column. + +The following keywords are allowed: + +.TP +.I abday +followed by a list of abbreviated weekday names. The list starts with +Sunday or its translation. +.TP +.I day +followed by a list of weekday names. The list starts with Sunday. +.TP +.I abmon +followed by a list of abbreviated month names. +.TP +.I mon +followed by a list of month names. +.TP +.I am_pm +The appropriate representation of the +.B am +and +.B pm +strings. +.TP +.I d_t_fmt +The appropriate date and time format. +.TP +.I d_fmt +The appropriate date format. +.TP +.I t_fmt +The appropriate time format. +.TP +.I t_fmt_ampm +The appropriate time format when using 12h clock format. +.PP +The +.B LC_TIME +definition ends with the string +.I END LC_TIME. + +.SS LC_MESSAGES +The definition starts with the string +.B LC_MESSAGES +in the first column. + +The following keywords are allowed: + +.TP +.I yesexpr +followed by a regular expression that describes possible +yes-responses. +.TP +.I noexpr +followed by a regular expression that describes possible +no-responses. + +.PP +The +.B LC_MESSAGES +definition ends with the string +.I END LC_MESSAGES. + +See the POSIX.2 standard for details. +.SH FILES +/usr/lib/locale/ +\- database for the current locale setting of that category +.br +/usr/lib/nls/charmap/* \- charmap-files +.SH BUGS +The manpage isn't complete. +.\" .SH AUTHOR +.\" Jochen Hein (Hein@Student.TU-Clausthal.de) +.SH "CONFORMING TO" +POSIX.2 +.SH "SEE ALSO" +.BR locale (1), +.BR localedef (1), +.BR localeconv (3), +.BR setlocale (3), +.BR charmap (5) diff --git a/man5/motd.5 b/man5/motd.5 new file mode 100644 index 000000000..904b0258b --- /dev/null +++ b/man5/motd.5 @@ -0,0 +1,40 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 17:08:16 1993 by Rik Faith +.\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond +.TH MOTD 5 1992-12-29 "Linux" "Linux Programmer's Manual" +.SH NAME +motd \- message of the day +.SH DESCRIPTION +The contents of \fB/etc/motd\fP are displayed by +.BR login (1) +after a successful login but just before it executes the login shell. + +The abbreviation "motd" stands for "message of the day", and this file +has been traditionally used for exactly that (it requires much less disk +space than mail to all users). +.SH FILES +/etc/motd +.SH "SEE ALSO" +.BR login (1), +.BR issue (5) diff --git a/man5/nologin.5 b/man5/nologin.5 new file mode 100644 index 000000000..5fb01379a --- /dev/null +++ b/man5/nologin.5 @@ -0,0 +1,37 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sun Jul 25 11:06:34 1993 by Rik Faith (faith@cs.unc.edu) +.\" Corrected Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond (esr@thyrsus.com) +.TH NOLOGIN 5 1992-12-29 "Linux" "Linux Programmer's Manual" +.SH NAME +nologin \- prevent non-root users from logging into the system +.SH DESCRIPTION +If the file \fB/etc/nologin\fP exists, +.BR login (1) +will allow access only to root. Other users will +be shown the contents of this file and their logins will be refused. +.SH FILES +/etc/nologin +.SH "SEE ALSO" +.BR login (1), +.BR shutdown (8) diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5 new file mode 100644 index 000000000..6e175eb24 --- /dev/null +++ b/man5/nscd.conf.5 @@ -0,0 +1,125 @@ +.\" -*- nroff -*- +.\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany +.\" Author: Thorsten Kukuk +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of the +.\" License, or (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +.\" General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this program; see the file COPYING. If not, +.\" write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, +.\" Boston, MA 02111-1307, USA. +.\" +.TH NSCD.CONF 5 1999-10 "GNU C Library" +.SH NAME +/etc/nscd.conf - name service cache daemon configuration file +.SH DESCRIPTION +The file +.B /etc/nscd.conf +is read from +.BR nscd (8) +at startup. Each line specifies either an attribute and a value, or an +attribute, service, and a value. Fields are separated either by SPACE +or TAB characters. A `#' (number sign) indicates the beginning of a +comment; following characters, up to the end of the line, +are not interpreted by nscd. + + +Valid services are passwd, group, or hosts. + +.B logfile +.I debug-file-name +.RS +Specifies name of the file to which debug info should be written. +.RE + +.B debug-level +.I value +.RS +Sets the desired debug level. +.RE + +.B threads +.I number +.RS +This is the number of threads that are started to wait for +requests. At least five threads will always be created. +.RE + +.B server-user +.I user +.RS +If this option is set, nscd will run as this user and not as root. +If a separate cache for every user is used (-S parameter), this +option is ignored. +.RE + +.B enable-cache +.I service +.I +.RS +Enables or disables the specified +.I service +cache. +.RE + +.B positive-time-to-live +.I service +.I value +.RS +Sets the TTL (time-to-live) for positive entries (successful queries) +in the specified cache for +.IR service . +.I Value +is in seconds. Larger values increase cache hit rates and reduce mean +response times, but increase problems with cache coherence. +.RE + +.B negative-time-to-live +.I service +.I value +.RS +Sets the TTL (time-to-live) for negative entries (unsuccessful queries) +in the specified cache for +.IR service . +.I Value +is in seconds. Can result in significant performance improvements if there +are several files owned by uids (user IDs) not in system databases (for +example untarring the linux kernel sources as root); should be kept small +to reduce cache coherency problems. +.RE + +.B suggested-size +.I service +.I value +.RS +This is the internal hash table size, +.I value +should remain a prime number for optimum efficiency. +.RE + +.B check-files +.I service +.I +.RS +Enables or disables checking the file belonging to the specified +.I service +for changes. The files are +.IR /etc/passwd , +.IR /etc/group , +and +.IR /etc/hosts . +.RE + +.SH "SEE ALSO" +.BR nscd (8) +.SH AUTHOR +.B nscd +was written by Thorsten Kukuk and Ulrich Drepper. diff --git a/man5/nsswitch.conf.5 b/man5/nsswitch.conf.5 new file mode 100644 index 000000000..4c2170345 --- /dev/null +++ b/man5/nsswitch.conf.5 @@ -0,0 +1,264 @@ +.\" Copyright (c) 1998, 1999 Thorsten Kukuk (kukuk@vt.uni-paderborn.de) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" This manual page based on the GNU C Library info pages. +.\" +.TH NSSWITCH.CONF 5 1999-01-17 "Linux" "Linux Programmer's Manual" +.SH NAME +nsswitch.conf \- System Databases and Name Service Switch configuration file +.SH DESCRIPTION +Various functions in the C Library need to be configured to work +correctly in the local environment. Traditionally, this was done by +using files (e.g., `/etc/passwd'), but other nameservices (like the +Network Information Service (NIS) and the Domain Name Service (DNS)) +became popular, and were hacked into the C library, usually with a fixed +search order. +.LP +The Linux libc5 with NYS support and the GNU C Library 2.x (libc.so.6) +contain a cleaner solution of this problem. It is designed after a method +used by Sun Microsystems in the C library of Solaris 2. We follow their +name and call this scheme "Name Service Switch" (NSS). The sources for +the "databases" and their lookup order are specified in the +.B /etc/nsswitch.conf +file. +.LP +The following databases are available in the NSS: +.TP +.B aliases +Mail aliases, used by +.BR sendmail (8). +Presently ignored. +.TP +.B ethers +Ethernet numbers. +.TP +.B group +Groups of users, used by +.BR getgrent (3) +functions. +.TP +.B hosts +Host names and numbers, used by +.BR gethostbyname (3) +and similar functions. +.TP +.B netgroup +Network wide list of hosts and users, used for access rules. +C libraries before glibc 2.1 only support netgroups over NIS. +.TP +.B network +Network names and numbers, used by +.BR getnetent (3) +functions. +.TP +.B passwd +User passwords, used by +.BR getpwent (3) +functions. +.TP +.B protocols +Network protocols, used by +.BR getprotoent (3) +functions. +.TP +.B publickey +Public and secret keys for Secure_RPC used by NFS and NIS+. +.TP +.B rpc +Remote procedure call names and numbers, used by +.BR getrpcbyname (3) +and similar functions. +.TP +.B services +Network services, used by +.BR getservent (3) +functions. +.TP +.B shadow +Shadow user passwords, used by +.BR getspnam (3). +.LP +An example +.B /etc/nsswitch.conf +(namely, the default used when +.B /etc/nsswitch.conf +is missing): +.sp 1n +.PD 0 +.TP 16 +passwd: +compat +.TP +group: +compat +.TP +shadow: +compat +.sp 1n +.TP +hosts: +dns [!UNAVAIL=return] files +.TP +networks: +nis [NOTFOUND=return] files +.TP +ethers: +nis [NOTFOUND=return] files +.TP +protocols: +nis [NOTFOUND=return] files +.TP +rpc: +nis [NOTFOUND=return] files +.TP +services: +nis [NOTFOUND=return] files +.PD +.LP +The first column is the database. +The rest of the line specifies how the lookup process works. +You can specify the way it works for each database individually. +.LP +The configuration specification for each database can contain two +different items: +.PD 0 +.TP +* The service specification like `files', `db', or `nis'. +.TP +* The reaction on lookup result like `[NOTFOUND=return]'. +.PD +.LP +For libc5 with NYS, the allowed service specifications are `files', `nis', +and `nisplus'. For hosts, you could specify `dns' as extra service, for +passwd and group `compat', but not for shadow. +.LP +For glibc, you must have a file called +.BI /lib/libnss_SERVICE.so. X +for every SERVICE you are using. On a standard installation, you could use +`files', `db', `nis', and `nisplus'. For hosts, you could specify `dns' as +extra service, for passwd, group, and shadow `compat'. These services will not +be used by libc5 with NYS. +The version number +.I X +is 1 for glibc 2.0 and 2 for glibc 2.1. +.LP +The second item in the specification gives the user much finer +control on the lookup process. Action items are placed between two +service names and are written within brackets. The general form is +.LP +`[' ( `!'? STATUS `=' ACTION )+ `]' +.LP +where +.sp 1n +.PD 0 +.TP +STATUS => success | notfound | unavail | tryagain +.TP +ACTION => return | continue +.PD +.LP +The case of the keywords is insignificant. The STATUS values are +the results of a call to a lookup function of a specific service. They +mean: +.TP +.B success +No error occurred and the wanted entry is returned. The default +action for this is `return'. +.TP +.B notfound +The lookup process works ok but the needed value was not found. +The default action is `continue'. +.TP +.B unavail +The service is permanently unavailable. This can either mean the +needed file is not available, or, for DNS, the server is not +available or does not allow queries. The default action is +`continue'. +.TP +.B tryagain +The service is temporarily unavailable. This could mean a file is +locked or a server currently cannot accept more connections. The +default action is `continue'. +.LP +.SS Interaction with +/- syntax (compat mode) +Linux libc5 without NYS does not have the name service switch but does +allow the user some policy control. In +.B /etc/passwd +you could have entries of the form +user or +@netgroup +(include the specified user from the NIS passwd map), +-user or -@netgroup (exclude the specified user), +and + (include every user, except the excluded ones, from the NIS +passwd map). Since most people only put a + at the end of +.B /etc/passwd +to include everything from NIS, the switch provides a faster +alternative for this case (`passwd: files nis') which doesn't +require the single + entry in +.BR /etc/passwd , +.BR /etc/group , +and +.BR /etc/shadow . +If this is not sufficient, the NSS `compat' service provides full ++/- semantics. By default, the source is `nis', but this may be +overriden by specifying `nisplus' as source for the pseudo-databases +.BR passwd_compat, +.B group_compat +and +.BR shadow_compat. +This pseudo-databases are only available in GNU C Library. +.SH FILES +A service named SERVICE is implemented by a shared object library named +.BI libnss_SERVICE.so. X +that resides in +.IR /lib . +.TP 25 +.PD 0 +.B /etc/nsswitch.conf +configuration file +.TP +.BI /lib/libnss_compat.so. X +implements `compat' source for glibc2 +.TP +.BI /lib/libnss_db.so. X +implements `db' source for glibc2 +.TP +.BI /lib/libnss_dns.so. X +implements `dns' source for glibc2 +.TP +.BI /lib/libnss_files.so. X +implements `files' source for glibc2 +.TP +.BI /lib/libnss_hesiod.so. X +implements `hesiod' source for glibc2 +.TP +.BI /lib/libnss_nis.so. X +implements `nis' source for glibc2 +.TP +.B /lib/libnss_nisplus.so.2 +implements `nisplus' source for glibc 2.1 +.SH NOTES +Within each process that uses +.BR nsswitch.conf , +the entire file is read only once; if the file is later changed, the +process will continue using the old configuration. +.LP +With Solaris, it isn't possible to link programs using the NSS Service +statically. With Linux, this is no problem. diff --git a/man5/passwd.5 b/man5/passwd.5 new file mode 100644 index 000000000..139762607 --- /dev/null +++ b/man5/passwd.5 @@ -0,0 +1,127 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sun Jul 25 10:46:28 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Aug 21 18:12:27 1994 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Jun 18 01:53:57 1995 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Mon Jan 5 20:24:40 MET 1998 by Michael Haardt +.\" (michael@cantor.informatik.rwth-aachen.de) +.TH PASSWD 5 1998-01-05 "File formats" "Linux Programmer's Manual" +.SH NAME +passwd \- password file +.SH DESCRIPTION +.B Passwd +is a text file, that contains a list of the system's accounts, +giving for each account some useful information like user ID, +group ID, home directory, shell, etc. +Often, it also contains the encrypted passwords for each account. +It should have general read permission (many utilities, like +.BR ls (1) +use it to map user IDs to user names), but write access only for the +superuser. +.PP +In the good old days there was no great problem with this general +read permission. Everybody could read the encrypted passwords, but the +hardware was too slow to crack a well-chosen password, and moreover, the +basic assumption used to be that of a friendly user-community. These days +many people run some version of the shadow password suite, where +.I /etc/passwd +has *'s instead of encrypted passwords, and the encrypted passwords are in +.I /etc/shadow +which is readable by the superuser only. +.PP +Regardless of whether shadow passwords are used, many sysadmins +use a star in the encrypted password field to make sure +that this user can not authenticate him- or herself using a +password. (But see the Notes below.) +.PP +If you create a new login, first put a star in the password field, +then use +.BR passwd (1) +to set it. +.PP +There is one entry per line, and each line has the format: +.sp +.RS +account:password:UID:GID:GECOS:directory:shell +.RE +.sp +The field descriptions are: +.sp +.RS +.TP 1.0in +.I account +the name of the user on the system. It should not contain capital letters. +.TP +.I password +the encrypted user password or a star. +.TP +.I UID +the numerical user ID. +.TP +.I GID +the numerical primary group ID for this user. +.TP +.I GECOS +This field is optional and only used for informational purposes. +Usually, it contains the full user name. GECOS means General Electric +Comprehensive Operating System, which has been renamed to GCOS when +GE's large systems division was sold to Honeywell. Dennis Ritchie has +reported: "Sometimes we sent printer output or batch jobs to the GCOS +machine. The gcos field in the password file was a place to stash the +information for the $IDENTcard. Not elegant." +.TP +.I directory +the user's $HOME directory. +.TP +.I shell +the program to run at login (if empty, use +.BR /bin/sh ). +If set to a non-existing executable, the user will be unable to login +through +.BR login (1). +.RE +.SH NOTE +If you want to create +user groups, their GIDs must be equal and there must be an entry in +\fI/etc/group\fP, or no group will exist. +.PP +If the encrypted password is set to a star, the user will be unable +to login using +.BR login (1), +but may still login using +.BR rlogin (1), +run existing processes and initiate new ones through +.BR rsh (1), +.BR cron (1), +.BR at (1), +or mail filters, etc. Trying to lock an account by simply changing the +shell field yields the same result and additionally allows the use of +.BR su (1). +.SH FILES +.I /etc/passwd +.SH "SEE ALSO" +.BR login (1), +.BR passwd (1), +.BR su (1), +.BR group (5), +.BR shadow (5) diff --git a/man5/proc.5 b/man5/proc.5 new file mode 100644 index 000000000..8165ba7d9 --- /dev/null +++ b/man5/proc.5 @@ -0,0 +1,1462 @@ +.\" Copyright (C) 1994, 1995 by Daniel Quinlan (quinlan@yggdrasil.com) +.\" with networking additions from Alan Cox (A.Cox@swansea.ac.uk) +.\" and scsi additions from Michael Neuffer (neuffer@mail.uni-mainz.de) +.\" and sysctl additions from Andries Brouwer (aeb@cwi.nl) +.\" and System V IPC (as well as various other) additions from +.\" Michael Kerrisk (mtk16@ext.canterbury.ac.nz) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified 1995-05-17 by faith@cs.unc.edu +.\" Minor changes by aeb and Marty Leisner (leisner@sdsp.mc.xerox.com). +.\" Modified 1996-04-13, 1996-07-22 by aeb@cwi.nl +.\" Modified 2001-12-16 by rwhron@earthlink.net +.\" Modified 2002-07-13 by jbelton@shaw.ca +.\" Modified 2002-07-22, 2003-05-27, 2004-04-06, 2004-05-25 +.\" by Michael Kerrisk +.\" +.TH PROC 5 2004-05-25 "" "Linux Programmer's Manual" +.SH NAME +proc \- process information pseudo-filesystem + +.SH DESCRIPTION +The +.I proc +filesystem is a pseudo-filesystem which is used as an interface to +kernel data structures. It is commonly mounted at +.IR /proc . +Most of it is read-only, but some files allow kernel variables to be +changed. +.LP +The following outline gives a quick tour through the /proc hierarchy. +.PD 1 +.TP +.I /proc/[number] +There is a numerical subdirectory for each running process; the +subdirectory is named by the process ID. +Each such subdirectory contains the following +pseudo-files and directories. +.TP +.I /proc/[number]/cmdline +This holds the complete command line for the process, unless the whole +process has been swapped out or the process is a zombie. In +either of these latter cases, there is nothing in this file: i.e. a +read on this file will return 0 characters. +The command line arguments appear in this file as a set of +null-separated strings, with a further null byte after the last string. +.TP +.I /proc/[number]/cwd +This is a link to the current working directory of the process. To find +out +the cwd of process 20, for instance, you can do this: + +.br +.nf +.ft CW +cd /proc/20/cwd; /bin/pwd +.fi +.ft + +Note that the pwd command is often a shell builtin, and might +not work properly. In bash, you may use pwd -P. +.TP +.I /proc/[number]/environ +This file contains the environment for the process. +The entries are separated by null characters, +and there may be a null character at the end. +Thus, to print out the environment of process 1, you would do: + +.br +.nf +.ft CW +(cat /proc/1/environ; echo) | tr "\\000" "\\n" +.fi +.ft P + +(For a reason why one should want to do this, see +.BR lilo (8).) +.TP +.I /proc/[number]/exe +Under Linux 2.2 and later, this file is a symbolic link +containing the actual path name of the executed command. +This symbolic link can be dereferenced normally - attempting to open +it will open the executable. You can even type +.I /proc/[number]/exe +to run another copy of the same process as [number]. + +Under Linux 2.0 and earlier +.I /proc/[number]/exe +is a pointer to the binary which was executed, +and appears as a symbolic link. A +.BR readlink (2) +call on this file under Linux 2.0 returns a string in the format: + +[device]:inode + +For example, [0301]:1502 would be inode 1502 on device major 03 (IDE, +MFM, etc. drives) minor 01 (first partition on the first drive). + +.BR find (1) +with the -inum option can be used to locate the file. +.TP +.I /proc/[number]/fd +This is a subdirectory containing one entry for each file which the +process has open, named by its file descriptor, and which is a +symbolic link to the actual file. Thus, 0 is +standard input, 1 standard output, 2 standard error, etc. + +Programs that will take a filename, but will not take the standard +input, and which write to a file, but will not send their output to +standard output, can be effectively foiled this way, assuming that -i +is the flag designating an input file and -o is the flag designating +an output file: +.br +.nf + +\f(CWfoobar -i /proc/self/fd/0 -o /proc/self/fd/1 ...\fR + +.fi +.br +and you have a working filter. +.\" The following is not true in my tests (MTK): +.\" Note that this will not work for +.\" programs that seek on their files, as the files in the fd directory +.\" are not seekable. + +/proc/self/fd/N is approximately the same as /dev/fd/N in some UNIX +and UNIX-like systems. Most Linux MAKEDEV scripts symbolically link +/dev/fd to /proc/self/fd, in fact. +.TP +.I /proc/[number]/maps +A file containing the currently mapped memory regions and their access +permissions. + +The format is: + +.nf +.ft CW +.in 8n +address perms offset dev inode pathname +08048000-08056000 r-xp 00000000 03:0c 64593 /usr/sbin/gpm +08056000-08058000 rw-p 0000d000 03:0c 64593 /usr/sbin/gpm +08058000-0805b000 rwxp 00000000 00:00 0 +40000000-40013000 r-xp 00000000 03:0c 4165 /lib/ld-2.2.4.so +40013000-40015000 rw-p 00012000 03:0c 4165 /lib/ld-2.2.4.so +4001f000-40135000 r-xp 00000000 03:0c 45494 /lib/libc-2.2.4.so +40135000-4013e000 rw-p 00115000 03:0c 45494 /lib/libc-2.2.4.so +4013e000-40142000 rw-p 00000000 00:00 0 +bffff000-c0000000 rwxp 00000000 00:00 0 +.ft +.fi +.in + +where address is the address space in the process that it occupies, +perms is a set of permissions: + +.nf +.in +5 +r = read +w = write +x = execute +s = shared +p = private (copy on write) +.fi +.in + +offset is the offset into the file/whatever, dev is the device +(major:minor), and inode is the inode on that device. 0 indicates +that no inode is associated with the memory region, as the case would +be with bss. + +Under Linux 2.0 there is no field giving pathname. +.TP +.I /proc/[number]/mem +This file can be used to access the pages of a process's memory through +.BR open (2), +.BR read (2), +and +.BR fseek (3). +.TP +.I /proc/[number]/root +Unix and Linux support the idea of a per-process root of the +filesystem, set by the +.BR chroot (2) +system call. This file is a symbolic link that points to the process's +root directory, and behaves as exe, fd/*, etc. do. +.TP +.I /proc/[number]/stat +Status information about the process. This is used by +.BR ps (1). +It is defined in +.IR /usr/src/linux/fs/proc/array.c "." + +The fields, in order, with their proper +.BR scanf (3) +format specifiers, are: +.RS +.TP +\fIpid\fP %d +The process id. +.TP +\fIcomm\fP %s +The filename of the executable, in parentheses. This is visible +whether or not the executable is swapped out. +.TP +\fIstate\fP %c +One character from the string "RSDZTW" where R is running, S is +sleeping in an interruptible wait, D is waiting in uninterruptible +disk sleep, Z is zombie, T is traced or stopped (on a signal), +and W is paging. +.TP +\fIppid\fP %d +The PID of the parent. +.TP +\fIpgrp\fP %d +The process group ID of the process. +.TP +\fIsession\fP %d +The session ID of the process. +.TP +.\" tty_nr needs better explanation. +\fItty_nr\fP %d +The tty the process uses. +.TP +\fItpgid\fP %d +.\" This field and following, up to and including wchan added 0.99.1 +The process group ID of the process which currently owns the tty that +the process is connected to. +.TP +\fIflags\fP %lu +The kernel flags word of the process. For bit meanings, +see the PF_* defines in +.IR . +Details depend on the kernel version. +.TP +\fIminflt\fP %lu +The number of minor faults the process has made which have not +required loading a memory page from disk. +.TP +\fIcminflt\fP %lu +The number of minor faults that the process's +waited-for children have made. +.TP +\fImajflt\fP %lu +The number of major faults the process has made which have +required loading a memory page from disk. +.TP +\fIcmajflt\fP %lu +The number of major faults that the process's +waited-for children have made. +.TP +\fIutime\fP %lu +The number of jiffies that this process has been scheduled in user +mode. +.TP +\fIstime\fP %lu +The number of jiffies that this process has been scheduled in kernel +mode. +.TP +\fIcutime\fP %ld +The number of jiffies that this process's +waited-for children have been scheduled in user mode. (See also +.BR times (2).) +.TP +\fIcstime\fP %ld +The number of jiffies that this process's +waited-for children have been scheduled in kernel mode. +.TP +\fIpriority\fP %ld +The standard nice value, plus fifteen. The value is never negative in +the kernel. +.TP +\fInice\fP %ld +The nice value ranges from 19 (nicest) to -19 (not nice to others). +.TP +.\" .TP +.\" \fIcounter\fP %ld +.\" The current maximum size in jiffies of the process's next timeslice, +.\" or what is currently left of its current timeslice, if it is the +.\" currently running process. +.\" .TP +.\" \fItimeout\fP %u +.\" The time in jiffies of the process's next timeout. +\fI0\fP %ld +This value is hard coded to 0 as a placeholder for a removed field. +.TP +\fIitrealvalue\fP %ld +The time in jiffies before the next SIGALRM is sent to the process +due to an interval timer. +.TP +\fIstarttime\fP %lu +The time in jiffies the process started after system boot. +.TP +\fIvsize\fP %lu +Virtual memory size in bytes. +.TP +\fIrss\fP %ld +Resident Set Size: number of pages the process has in real memory, +minus 3 for administrative purposes. This is just the pages which +count towards text, data, or stack space. This does not include pages +which have not been demand-loaded in, or which are swapped out. +.TP +\fIrlim\fP %lu +Current limit in bytes on the rss of the process (usually +4294967295 on i386). +.TP +\fIstartcode\fP %lu +The address above which program text can run. +.TP +\fIendcode\fP %lu +The address below which program text can run. +.TP +\fIstartstack\fP %lu +The address of the start of the stack. +.TP +\fIkstkesp\fP %lu +The current value of esp (stack pointer), as found in the +kernel stack page for the process. +.TP +\fIkstkeip\fP %lu +The current EIP (instruction pointer). +.TP +\fIsignal\fP %lu +The bitmap of pending signals (usually 0). +.TP +\fIblocked\fP %lu +The bitmap of blocked signals (usually 0, 2 for shells). +.TP +\fIsigignore\fP %lu +The bitmap of ignored signals. +.TP +\fIsigcatch\fP %lu +The bitmap of catched signals. +.TP +\fIwchan\fP %lu +This is the "channel" in which the process is waiting. It is the +address of a system call, and can be looked up in a namelist if you +need a textual name. (If you have an up-to-date /etc/psdatabase, then +try \fIps -l\fP to see the WCHAN field in action.) +.TP +\fInswap\fP %lu +Number of pages swapped - not maintained. +.TP +\fIcnswap\fP %lu +Cumulative \fInswap\fP for child processes. +.TP +\fIexit_signal\fP %d +Signal to be sent to parent when we die. +.TP +\fIprocessor\fP %d +CPU number last executed on. +.RE +.TP +.I /proc/[number]/statm +Provides information about memory status in pages. The columns are: + size total program size + resident resident set size + share shared pages + trs text (code) + drs data/stack + lrs library + dt dirty pages +.TP +.I /proc/[number]/status +Provides much of the information in +.I /proc/[number]/stat +and +.I /proc/[number]/statm +in a format that's easier for humans to parse. +.TP +.I /proc/apm +Advanced power management version and battery information +when CONFIG_APM is defined at kernel compilation time. +.TP +.I /proc/bus +Contains subdirectories for installed busses. +.TP +.I /proc/bus/pccard +Subdirectory for pcmcia devices when CONFIG_PCMCIA is set +at kernel compilation time. +.TP +.I /proc/bus/pccard/drivers +.TP +.I /proc/bus/pci +Contains various bus subdirectories and pseudo-files containing +information about pci busses, installed devices, and device +drivers. Some of these files are not ASCII. +.TP +.I /proc/bus/pci/devices +Information about pci devices. They may be accessed through +.BR lspci (8) +and +.BR setpci (8). +.TP +.I /proc/cmdline +Arguments passed to the Linux kernel at boot time. Often done via +a boot manager such as +.BR lilo (1). +.TP +.I /proc/cpuinfo +This is a collection of CPU and system architecture dependent items, +for each supported architecture a different list. +Two common entries are \fIprocessor\fP which gives CPU number and +\fIbogomips\fP; a system constant that is calculated +during kernel initialization. SMP machines have information for +each CPU. +.TP +.I /proc/devices +Text listing of major numbers and device groups. This can be used by +MAKEDEV scripts for consistency with the kernel. +.TP +.IR /proc/diskstats " (since Linux 2.5.69)" +This file contains disk I/O statistics for each disk device. +See the kernel source file +.I Documentation/iostats.txt +for further information. +.TP +.I /proc/dma +This is a list of the registered \fIISA\fP DMA (direct memory access) +channels in use. +.TP +.I /proc/driver +Empty subdirectory. +.TP +.I /proc/execdomains +List of the execution domains (ABI personalities). +.TP +.I /proc/fb +Frame buffer information when CONFIG_FB is defined during kernel +compilation. +.TP +.I /proc/filesystems +A text listing of the filesystems which were compiled into the kernel. +Incidentally, this is used by +.BR mount (1) +to cycle through different filesystems when none is specified. +.TP +.I /proc/fs +Empty subdirectory. +.TP +.I /proc/ide +This directory +exists on systems with the ide bus. There are directories for each +ide channel and attached device. Files include: + +.nf +cache buffer size in KB +capacity number of sectors +driver driver version +geometry physical and logical geometry +identify in hexidecimal +media media type +model manufacturer's model number +settings drive settings +smart_thresholds in hexidecimal +smart_values in hexidecimal +.fi + +The +.BR hdparm (8) +utility provides access to this information in a friendly format. +.TP +.I /proc/interrupts +This is used to record the number of interrupts per each IRQ on (at +least) the i386 architechure. Very easy to read formatting, done in +ASCII. +.TP +.I /proc/iomem +I/O memory map in Linux 2.4. +.TP +.I /proc/ioports +This is a list of currently registered Input-Output port regions that +are in use. +.TP +.IR /proc/kallsyms " (since Linux 2.5.71)" +This holds the kernel exported symbol definitions used by the +.BR modules (X) +tools to dynamically link and bind loadable modules. +In Linux 2.5.47 and earlier, a similar file with slightly different syntax +was named +.IR ksyms . +.TP +.I /proc/kcore +This file represents the physical memory of the system and is stored +in the ELF core file format. With this pseudo-file, and an unstripped +kernel (/usr/src/linux/vmlinux) binary, GDB can be used to +examine the current state of any kernel data structures. + +The total length of the file is the size of physical memory (RAM) plus +4KB. +.TP +.I /proc/kmsg +This file can be used instead of the +.BR syslog (2) +system call to read kernel messages. A process must have superuser +privileges to read this file, and only one process should read this +file. This file should not be read if a syslog process is running +which uses the +.BR syslog (2) +system call facility to log kernel messages. + +Information in this file is retrieved with the +.BR dmesg (8) +program. +.TP +.IR /proc/ksyms " (Linux 1.1.23-2.5.47)" +See +.IR /proc/kallsyms . +.TP +.I /proc/loadavg +The load average numbers give the number of jobs in the run queue (state +R) +or waiting for disk I/O (state D) averaged over 1, 5, and 15 minutes. +They are the same as the load average numbers given by +.BR uptime (1) +and other programs. +.TP +.I /proc/locks +This file shows current file locks +.RB ( flock "(2) and " fcntl (2)) +and leases +.RB ( fcntl (2)). +.TP +.I /proc/malloc +This file is only present if CONFIGDEBUGMALLOC was defined during +compilation. +.TP +.I /proc/meminfo +This is used by +.BR free (1) +to report the amount of free and used memory (both physical and swap) +on the system as well as the shared memory and buffers used by the +kernel. + +It is in the same format as +.BR free (1), +except in bytes rather than KB. +.TP +.I /proc/mounts +This is a list of all the file systems currently mounted on the system. +The format of this file is documented in +.IR fstab (5). +.TP +.I /proc/modules +A text list of the modules that have been loaded by the system. +See also +.BR lsmod (8). +.TP +.I /proc/mtrr +Memory Type Range Registers. +See +.I /usr/src/linux/Documentation/mtrr.txt +for details. +.TP +.I /proc/net +various net pseudo-files, all of which give the status of some part of +the networking layer. These files contain ASCII structures and are, +therefore, readable with cat. However, the standard +.BR netstat (8) +suite provides much cleaner access to these files. +.TP +.I /proc/net/arp +This holds an ASCII readable dump of the kernel ARP table used for +address resolutions. It will show both dynamically learned and +pre-programmed ARP entries. The format is: + +.nf +.ft CW +.in 8n +IP address HW type Flags HW address Mask Device +192.168.0.50 0x1 0x2 00:50:BF:25:68:F3 * eth0 +192.168.0.250 0x1 0xc 00:00:00:00:00:00 * eth0 +.ft +.fi +.in + +Here 'IP address' is the IPv4 address of the machine and the 'HW type' +is the hardware type of the address from RFC 826. The flags are the internal +flags of the ARP structure (as defined in /usr/include/linux/if_arp.h) and +the 'HW address' is the data link layer mapping for that IP address if +it is known. +.TP +.I /proc/net/dev +The dev pseudo-file contains network device status information. This gives +the number of received and sent packets, the number of errors and +collisions +and other basic statistics. These are used by the +.BR ifconfig (8) +program to report device status. The format is: + +.nf +.ft CW +.in 1n +Inter-| Receive | Transmit + face |bytes packets errs drop fifo frame compressed multicast|bytes packets errs drop fifo colls carrier compressed + lo: 2776770 11307 0 0 0 0 0 0 2776770 11307 0 0 0 0 0 0 + eth0: 1215645 2751 0 0 0 0 0 0 1782404 4324 0 0 0 427 0 0 + ppp0: 1622270 5552 1 0 0 0 0 0 354130 5669 0 0 0 0 0 0 + tap0: 7714 81 0 0 0 0 0 0 7714 81 0 0 0 0 0 0 +.in +.ft +.fi +.\" .TP +.\" .I /proc/net/ipx +.\" No information. +.\" .TP +.\" .I /proc/net/ipx_route +.\" No information. +.TP +.I /proc/net/dev_mcast +Defined in +.IR /usr/src/linux/net/core/dev_mcast.c : +.nf +.in +5 +indx ifterface_name dmi_u dmi_g dmi_address +2 eth0 1 0 01005e000001 +3 eth1 1 0 01005e000001 +4 eth2 1 0 01005e000001 +.in +.fi +.TP +.I /proc/net/igmp +Internet Group Management Protocol. Defined in +.IR /usr/src/linux/net/core/igmp.c . +.TP +.I /proc/net/rarp +This file uses the same format as the +.I arp +file and contains the current reverse mapping database used to provide +.BR rarp (8) +reverse address lookup services. If RARP is not configured into the +kernel, +this file will not be present. +.TP +.I /proc/net/raw +Holds a dump of the RAW socket table. Much of the information is not of +use +apart from debugging. The 'sl' value is the kernel hash slot for the +socket, +the 'local address' is the local address and protocol number pair."St" is +the internal status of the socket. The "tx_queue" and "rx_queue" are the +outgoing and incoming data queue in terms of kernel memory usage. +The "tr", "tm->when", and "rexmits" fields are not used by RAW. +The uid field holds the creator euid of the socket. +.\" .TP +.\" .I /proc/net/route +.\" No information, but looks similar to +.\" .BR route (8). +.TP +.I /proc/net/snmp +This file holds the ASCII data needed for the IP, ICMP, TCP, and UDP +management +information bases for an snmp agent. +.TP +.I /proc/net/tcp +Holds a dump of the TCP socket table. Much of the information is not +of use apart from debugging. The "sl" value is the kernel hash slot +for the socket, the "local address" is the local address and port number pair. +The "remote address" is the remote address and port number pair +(if connected). 'St' is the internal status of the socket. +The 'tx_queue' and 'rx_queue' are the +outgoing and incoming data queue in terms of kernel memory usage. +The "tr", "tm->when", and "rexmits" fields hold internal information of +the kernel socket state and are only useful for debugging. The uid field +holds the creator euid of the socket. +.TP +.I /proc/net/udp +Holds a dump of the UDP socket table. Much of the information is not of +use apart from debugging. The "sl" value is the kernel hash slot for the +socket, the "local address" is the local address and port number pair. +The "remote address" is the remote address and port number pair +(if connected). "St" is the internal status of the socket. +The "tx_queue" and "rx_queue" are the outgoing and incoming data queue +in terms of kernel memory usage. The "tr", "tm->when", and "rexmits" fields +are not used by UDP. The uid field holds the creator euid of the socket. +The format is: + +.nf +.ft CW +.in 1n +sl local_address rem_address st tx_queue rx_queue tr rexmits tm->when uid + 1: 01642C89:0201 0C642C89:03FF 01 00000000:00000001 01:000071BA 00000000 0 + 1: 00000000:0801 00000000:0000 0A 00000000:00000000 00:00000000 6F000100 0 + 1: 00000000:0201 00000000:0000 0A 00000000:00000000 00:00000000 00000000 0 +.in +.ft +.fi +.TP +.I /proc/net/unix +Lists the UNIX domain sockets present within the system and their +status. The format is: +.nf +.sp .5 +.ft CW +Num RefCount Protocol Flags Type St Path + 0: 00000002 00000000 00000000 0001 03 + 1: 00000001 00000000 00010000 0001 01 /dev/printer +.ft +.sp .5 +.fi + +Here 'Num' is the kernel table slot number, 'RefCount' is the number +of users of the socket, 'Protocol' is currently always 0, 'Flags' +represent the internal kernel flags holding the status of the +socket. Currently, type is always '1' (Unix domain datagram sockets are +not yet supported in the kernel). 'St' is the internal state of the +socket and Path is the bound path (if any) of the socket. +.TP +.I /proc/partitions +Contains major and minor numbers of each partition as well as number +of blocks and partition name. +.TP +.I /proc/pci +This is a listing of all PCI devices found during kernel initialization +and their configuration. +.TP +.I /proc/scsi +A directory with the scsi midlevel pseudo-file and various SCSI lowlevel +driver +directories, which contain a file for each SCSI host in this system, all +of +which give the status of some part of the SCSI IO subsystem. +These files contain ASCII structures and are, therefore, readable with +cat. + +You can also write to some of the files to reconfigure the subsystem or +switch +certain features on or off. +.TP +.I /proc/scsi/scsi +This is a listing of all SCSI devices known to the kernel. The listing is +similar to the one seen during bootup. +scsi currently supports only the \fIadd-single-device\fP command which +allows +root to add a hotplugged device to the list of known devices. + +An +.B echo 'scsi add-single-device 1 0 5 0' > /proc/scsi/scsi +will cause +host scsi1 to scan on SCSI channel 0 for a device on ID 5 LUN 0. If there +is already a device known on this address or the address is invalid, an +error will be returned. +.TP +.I /proc/scsi/[drivername] +\fI[drivername]\fP can currently be NCR53c7xx, aha152x, aha1542, aha1740, +aic7xxx, buslogic, eata_dma, eata_pio, fdomain, in2000, pas16, qlogic, +scsi_debug, seagate, t128, u15-24f, ultrastore, or wd7000. +These directories show up for all drivers that registered at least one +SCSI +HBA. Every directory contains one file per registered host. Every +host-file is named after the number the host was assigned during +initialization. + +Reading these files will usually show driver and host configuration, +statistics etc. + +Writing to these files allows different things on different hosts. +For example, with the \fIlatency\fP and \fInolatency\fP commands, +root can switch on and off command latency measurement code in the +eata_dma driver. With the \fIlockup\fP and \fIunlock\fP commands, +root can control bus lockups simulated by the scsi_debug driver. +.TP +.I /proc/self +This directory refers to the process accessing the /proc filesystem, +and is identical to the /proc directory named by the process ID of the +same process. +.TP +.I /proc/slabinfo +Information about kernel caches. The columns are: +.nf +cache-name +num-active-objs +total-objs +object-size +num-active-slabs +total-slabs +num-pages-per-slab +.fi +See +.BR slabinfo (5) +for details. +.TP +.I /proc/stat +kernel/system statistics. Varies with architecture. Common +entries include: +.RS +.TP +\fIcpu 3357 0 4313 1362393\fP +The number of jiffies (1/100ths of a second) that the system spent in +user mode, user mode with low priority (nice), system mode, and the +idle task, respectively. The last value should be 100 times the +second entry in the uptime pseudo-file. +.TP +\fIpage 5741 1808\fP +The number of pages the system paged in and the number that were paged +out (from disk). +.TP +\fIswap 1 0\fP +The number of swap pages that have been brought in and out. +.TP +\fIintr 1462898\fP +The number of interrupts received from the system boot. +.TP +\fIdisk_io: (2,0):(31,30,5764,1,2) (3,0):\fP... +(major,minor):(noinfo, read_io_ops, blks_read, write_io_ops, blks_written) +.TP +\fIctxt 115315\fP +The number of context switches that the system underwent. +.TP +\fIbtime 769041601\fP +boot time, in seconds since the epoch (January 1, 1970). +.TP +\fIprocesses 86031\fP +Number of forks since boot. +.RE +.TP +.I /proc/swaps +Swap areas in use. See also +.BR swapon (8). +.TP +.I /proc/sys +This directory (present since 1.3.57) contains a number of files +and subdirectories corresponding to kernel variables. +These variables can be read and sometimes modified using +the \fIproc\fP file system, and the +.BR sysctl (2) +system call. Presently, there are subdirectories +.IR abi ", " debug ", " dev ", " fs ", " kernel ", " net ", " proc ", " +.IR rxrpc ", " sunrpc " and " vm +that each contain more files and subdirectories. +.TP +.I /proc/sys/abi +This directory may contain files with application binary information. +On some systems, it is not present. +.TP +.I /proc/sys/debug +This directory may be empty. +.TP +.I /proc/sys/dev +This directory contains device specific information (eg dev/cdrom/info). +On +some systems, it may be empty. +.TP +.I /proc/sys/fs +This contains the subdirectory +.IR binfmt_misc +and files +.IR dentry-state ", " dir-notify-enable ", " dquot-nr ", " file-max ", " +.IR file-nr ", " inode-max ", " inode-nr ", " inode-state ", " +.IR lease-break-time ", " leases-enable ", " overflowgid ", " overflowuid +.IR super-max " and " super-nr +with function fairly clear from the name. +.TP +.I /proc/sys/fs/binfmt_misc +Documentation for files in this directory can in the kernel sources in +.IR Documentation/binfmt_misc.txt . +.TP +.I /proc/sys/fs/dentry-state +This file contains six numbers, +.IR nr_dentry ", " nr_unused ", " age_limit " (age in seconds), " +want_pages +(pages requested by system) and two dummy values. +nr_dentry seems to be 0 all the time. +nr_unused seems to be the number of unused dentries. +age_limit is the age in seconds after which dcache entries +can be reclaimed when memory is short and want_pages is +nonzero when the kernel has called shrink_dcache_pages() and the +dcache isn't pruned yet. +.TP +.I /proc/sys/fs/dir-notify-enable +This file can be used to disable or enable the +.I dnotify +interface described in +.BR fcntl (2) +on a system-wide basis. +A value of 0 in this file disables the interface, +and a value of 1 enables it. +.TP +.I /proc/sys/fs/dquot-max +This file shows the maximum number of cached disk quota entries. +On some (2.4) systems, it is not present. +If the number of free cached disk quota entries is very low and +you have some awesome number of simultaneous system users, +you might want to raise the limit. +.TP +.I /proc/sys/fs/dquot-nr +This file shows the number of allocated disk quota +entries and the number of free disk quota entries. +.TP +.I /proc/sys/fs/file-max +This file defines +a system-wide limit on the number of open files for all processes. +(See also +.BR setrlimit (2), +which can be used by a process to set the per-process limit, +.BR RLIMIT_NOFILE , +on the number of files it may open.) +If you get lots +of error messages about running out of file handles, +try increasing this value: +.br + +.br +.nf +.ft CW +echo 100000 > /proc/sys/fs/file-max +.fi +.ft + +The kernel constant +.I NR_OPEN +imposes an upper limit on the value that may be placed in +.IR file-max . + +If you increase +.IR /proc/sys/fs/file-max "," +be sure to increase +.I /proc/sys/fs/inode-max +to 3-4 times the new +value of +.IR /proc/sys/fs/file-max "," +or you will run out of inodes. +.TP +.I /proc/sys/fs/file-nr +This (read-only) file +gives the number of files presently opened. +It contains three numbers: The number of allocated +file handles, the number of free file handles and the maximum +number of file handles. The kernel allocates file handles dynamically, +but it +doesn't free them again. If the number of allocated files is close to the + +maximum, you should consider increasing the maximum. +When the number of free file handles is +large, you've encountered a peak in your usage of file +handles and you probably don't need to increase the maximum. +.TP +.I /proc/sys/fs/inode-max +This file contains the maximum number of in-memory inodes. +On some (2.4) systems, it may not be +present. This value should be 3-4 times larger +than the value in file-max, since stdin, stdout and network sockets also +need an inode to handle them. When you regularly run +out of inodes, you need to increase this value. +.TP +.I /proc/sys/fs/inode-nr +This file contains the first two values from inode-state. +.TP +.I /proc/sys/fs/inode-state +This file +contains seven numbers: nr_inodes, nr_free_inodes, preshrink and four +dummy +values. +nr_inodes is the number of inodes the system has +allocated. This can be slightly more than inode-max because +Linux allocates them one pageful at a time. +nr_free_inodes represents the number of free inodes. +preshrink is nonzero when the nr_inodes > inode-max and the +system needs to prune the inode list instead of allocating +more. +.TP +.I /proc/sys/fs/lease-break-time +This file +specifies the grace period that the kernel grants to a process +holding a file lease +.RB ( fcntl (2)) +after it has sent a signal to that process notifying it +that another process is waiting to open the file. +If the lease holder does not remove or downgrade the lease within +this grace period, the kernel forcibly breaks the lease. +.TP +.I /proc/sys/fs/leases-enable +This file can be used to enable or disable file leases +.RB ( fcntl (2)) +on a system-wide basis. +If this file contains the value 0, leases are disabled. +A non-zero value enables leases. +.TP +.IR /proc/sys/fs/overflowgid " and " /proc/sys/fs/overflowuid +These files +allow you to change the value of the fixed UID and GID. +The default is 65534. +Some filesystems only support 16-bit UIDs and GIDs, although in Linux +UIDs and GIDs are 32 bits. When one of these filesystems is mounted +with writes enabled, any UID or GID that would exceed 65535 is translated +to the overflow value before being written to disk. +.TP +.I /proc/sys/fs/super-max +This file +controls the maximum number of superblocks, and +thus the maximum number of mounted filesystems the kernel +can have. You only need to increase super-max if you need to +mount more filesystems than the current value in super-max +allows you to. +.TP +.I /proc/sys/fs/super-nr +This file +contains the number of filesystems currently mounted. +.TP +.I /proc/sys/kernel +This directory contains files +.IR acct ", " cad_pid ", " cap-bound ", " +.IR core_pattern ", " core_uses_pid ", " +.IR ctrl-alt-del ", " dentry-state ", " domainname ", " +.IR hotplug ", " hostname ", " +.IR htab-reclaim " (PowerPC only), " +.IR java-appletviewer " (binfmt_java, obsolete), " +.IR java-interpreter " (binfmt_java, obsolete), " l2cr " (PowerPC only), " +.IR modprobe ", " msgmax ", " msgmnb ", " +.IR msgmni ", " osrelease ", " ostype ", " overflowgid ", " overflowuid , +.IR panic ", " panic_on_oops ", " pid_max ", " +.IR powersave-nap " (PowerPC only), " printk ", " pty ", " random ", " +.IR real-root-dev ", " reboot-cmd " (SPARC only), " rtsig-max ", " +.IR rtsig-nr ", " sem ", " sg-big-buff ", " +.IR shmall ", " shmmax ", " shmmni ", " sysrq ", " tainted ", " threads-max , +.IR version " and " zero-paged " (PowerPC only) " +with function fairly clear from the name. +.TP +.I /proc/sys/kernel/acct +This file +contains three numbers: highwater, lowwater and frequency. +If BSD-style process accounting is enabled these values control +its behaviour. If free space on filesystem where the log lives +goes below lowwater percent accounting suspends. If free space gets +above highwater percent accounting resumes. Frequency determines +how often the kernel checks the amount of free space (value is in +seconds). Default values are 4, 2 and 30. +That is, suspend accounting if <= 2% of space is free; resume it +if >= 4% of space is free; consider information about amount of free space +valid for 30 seconds. +.TP +.I /proc/sys/kernel/cap-bound +This file holds the value of the kernel +.IR "capability bounding set" +(expressed as a signed decimal number). +This set is ANDed against the capabilities permitted to a process +during exec. +.TP +.I /proc/sys/kernel/core_pattern +This file +(new in Linux 2.5) provides finer control over the form of +a core filename than the obsolete +.IR /proc/sys/kernel/core_uses_pid +file described below. +The name for a core file is controlled by defining a template in +.IR /proc/sys/kernel/core_pattern . +The template can contain % specifiers which are substituted +by the following values when a core file is created: +.nf + + %% A single % character + %p PID of dumped process + %u real UID of dumped process + %g real GID of dumped process + %s number of signal causing dump + %t time of dump (secs since 0:00h, 1 Jan 1970) + %h hostname (same as the 'nodename' + returned by \fBuname\fP(2)) + %e executable filename + +.fi +A single % at the end of the template is dropped from the +core filename, as is the combination of a % followed by any +character other than those listed above. +All other characters in the template become a literal +part of the core filename. +The maximum size of the resulting core filename is 64 bytes. +The default value in this file is "core". +For backward compatibility, if +.I /proc/sys/kernel/core_pattern +does not include "%p" and +.I /proc/sys/kernel/core_uses_pid +is non-zero, then .PID will be appended to the core filename. +.TP +.I /proc/sys/kernel/core_uses_pid +This file +can be used control the naming of a core dump file on Linux 2.4. +If this file contains the value 0, then a core dump file is simply named +.IR core . +If this file contains a non-zero value, then the core dump file includes +the process ID in a name of the form +.IR core.PID . +.TP +.I /proc/sys/kernel/ctrl-alt-del +This file +controls the handling of Ctrl-Alt-Del from the keyboard. +When the value in this file is 0, Ctrl-Alt-Del is trapped and +sent to the +.BR init (1) +program to handle a graceful restart. +When the value is > 0, Linux's reaction to a Vulcan +Nerve Pinch (tm) will be an immediate reboot, without even +syncing its dirty buffers. +Note: when a program (like dosemu) has the keyboard in 'raw' +mode, the ctrl-alt-del is intercepted by the program before it +ever reaches the kernel tty layer, and it's up to the program +to decide what to do with it. +.TP +.I /proc/sys/kernel/hotplug +This file +contains the path for the hotplug policy agent. +The default value in this file "/sbin/hotplug". +.TP +.IR /proc/sys/kernel/domainname " and " /proc/sys/kernel/hostname +can be used to set the NIS/YP domainname and the +hostname of your box in exactly the same way as the commands +domainname and hostname, i.e.: +.br + +.br +# echo "darkstar" > /proc/sys/kernel/hostname +.br +# echo "mydomain" > /proc/sys/kernel/domainname +.br + +.br +has the same effect as +.br + +.br +# hostname "darkstar" +.br +# domainname "mydomain" +.br + +.br +Note, however, that the classic darkstar.frop.org has the +hostname "darkstar" and DNS (Internet Domain Name Server) +domainname "frop.org", not to be confused with the NIS (Network +Information Service) or YP (Yellow Pages) domainname. These two +domain names are in general different. For a detailed discussion +see the +.BR hostname (1) +man page. +.TP +.I /proc/sys/kernel/htab-reclaim +(PowerPC only) If this file is set to a non-zero value, +the PowerPC htab +(see kernel file Documentation/powerpc/ppc_htab.txt) is pruned +each time the system hits the idle loop. +.TP +.I /proc/sys/kernel/l2cr +(PowerPC only) This file +contains a flag that controls the L2 cache of G3 processor +boards. If 0, the cache is disabled. Enabled if nonzero. +.TP +.I /proc/sys/kernel/modprobe +This file +is described by the kernel source file Documentation/kmod.txt. +.TP +.I /proc/sys/kernel/msgmax +This file defines +a system-wide limit specifying the maximum number of bytes in +a single message written on a System V message queue. +.TP +.I /proc/sys/kernel/msgmni +This file defines the system-wide limit on the number of +message queue identifiers. +(This file is only present in Linux 2.4 onwards.) +.TP +.I /proc/sys/kernel/msgmnb +This file defines a system-wide paramter used to initialise the +.I msg_qbytes +setting for subsequenly created message queues. +The +.I msg_qbytes +setting specifies the maximum number of bytes that may be written to the +message queue. +.TP +.IR /proc/sys/kernel/ostype " and " /proc/sys/kernel/osrelease +These files +give substrings of +.IR /proc/version . +.TP +.IR /proc/sys/kernel/overflowgid " and " /proc/sys/kernel/overflowuid +These files duplicate the files +.I /proc/sys/fs/overflowgid +and +.IR /proc/sys/fs/overflowuid . +.TP +.I /proc/sys/kernel/panic +gives read/write access to the kernel variable +.IR panic_timeout . +If this is zero, the kernel will loop on a panic; if nonzero +it indicates that the kernel should autoreboot after this number +of seconds. When you use the +software watchdog device driver, the recommended setting is 60. +.TP +.I /proc/sys/kernel/panic_on_oops +This file (new in Linux 2.5) controls the kernel's behaviour when an oops +or +BUG is encountered. If this file contains 0, then the system +tries to continue operation. If it contains 1, then the system +delays a few seconds (to give klogd time to record the oops output) +and then panics. +If the +.I /proc/sys/kernel/panic +file is also non-zero then the machine will be rebooted. +.TP +.I /proc/sys/kernel/pid_max +This file +(new in Linux 2.5) +specifies the value at which PIDs wrap around +(i.e., the value in this file is one greater than the maximum PID). +The default value for this file, 32768, +results in the same range of PIDs as on earlier kernels. +The value in this file can be set to any value up to 2^22 +(PID_MAX_LIMIT, approximately 4 million). +.TP +.IR /proc/sys/kernel/powersave-nap " (PowerPC only)" +This file +contains a flag. If set, Linux-PPC will use the 'nap' mode of +powersaving, +otherwise the 'doze' mode will be used. +.TP +.I /proc/sys/kernel/printk +The four values in this file +are console_loglevel, default_message_loglevel, minimum_console_level and +default_console_loglevel. +These values influence printk() behavior when printing or +logging error messages. See +.BR syslog (2) +for more info on the different loglevels. +Messages with a higher priority than +console_loglevel will be printed to the console. +Messages without an explicit priority +will be printed with priority default_message_level. +minimum_console_loglevel is the minimum (highest) value to which +console_loglevel can be set. +default_console_loglevel is the default value for console_loglevel. +.TP +.IR /proc/sys/kernel/pty " (since Linux 2.6.4)" +This directory +contains two files relating to the number of Unix 98 +pseudo-terminals (see +.BR pts (4)) +on the system. +.TP +.I /proc/sys/kernel/pty/max +This file defines the maximum number of pseudo-terminals. +.TP +.I /proc/sys/kernel/pty/nr +This read-only file +indicates how many pseudo-terminals are currently in use. +.TP +.\" FIXME say more about random +.I /proc/sys/kernel/random +This directory +contains various parameters controlling the operation of the file +.IR /dev/random . +.TP +.I /proc/sys/kernel/real-root-dev +This file +is documented in the kernel source file Documentation/initrd.txt. +.TP +.IR /proc/sys/kernel/reboot-cmd " (Sparc only) " +This file seems to be a way to give an argument to the SPARC +ROM/Flash boot loader. Maybe to tell it what to do after +rebooting? +.TP +.I /proc/sys/kernel/rtsig-max +This file can be used to tune the maximum number +of POSIX realtime (queued) signals that can be outstanding +in the system. +.TP +.I /proc/sys/kernel/rtsig-nr +This file shows the number POSIX realtime signals currently queued. +.TP +.IR /proc/sys/kernel/sem " (since Linux 2.4)" +This file contains 4 numbers defining limits for System V IPC semaphores. +These fields are, in order: +.RS +.IP SEMMSL 8 +The maximum semaphores per semaphore set. +.IP SEMMNS 8 +A system-wide limit on the number of semaphores in all semaphore sets. +.IP SEMOPM 8 +The maximum number of operations that may be specified in a +.BR semop (2) +call. +.IP SEMMNI 8 +A system-wide limit on the maximum number of semaphore identifiers. +.RE +.TP +.I /proc/sys/kernel/sg-big-buff +This file +shows the size of the generic SCSI device (sg) buffer. +You can't tune it just yet, but you could change it on +compile time by editing include/scsi/sg.h and changing +the value of SG_BIG_BUFF. However, there shouldn't be any reason to +change +this value. +.TP +.I /proc/sys/kernel/shmall +This file +contains the system-wide limit on the total number of pages of +System V shared memory. +.TP +.I /proc/sys/kernel/shmmax +This file +can be used to query and set the run time limit +on the maximum (System V IPC) shared memory segment size that can be +created. +Shared memory segments up to 1Gb are now supported in the +kernel. This value defaults to SHMMAX. +.TP +.I /proc/sys/kernel/shmmni +(available in Linux 2.4 and onwards) +This file +specifies the system-wide maximum number of System V shared memory +segments that can be created. +.TP +.I /proc/sys/kernel/version +contains a string like: +.br + +.br +#5 Wed Feb 25 21:49:24 MET 1998.TP +.br + +.br +The '#5' means that +this is the fifth kernel built from this source base and the +date behind it indicates the time the kernel was built. +.TP +.IR /proc/sys/kernel/zero-paged " (PowerPC only) " +This file +contains a flag. When enabled (non-zero), Linux-PPC will pre-zero pages in +the idle loop, possibly speeding up get_free_pages. +.TP +.I /proc/sys/net +This directory contains networking stuff. +.TP +.I /proc/sys/proc +This directory may be empty. +.TP +.I /proc/sys/sunrpc +This directory supports Sun remote procedure call for network file system +(NFS). On some systems, it is not present. +.TP +.I /proc/sys/vm +This directory contains files for memory management tuning, buffer and +cache +management. +.TP +.I /proc/sys/vm/overcommit_memory +This file contains the kernel virtual memory accounting mode. Values are: +.br +0: heuristic overcommit (this is the default) +.br +1: always overcommit, never check +.br +2: always check, never overcommit +.br +In mode 0, calls of +.BR mmap (2) +with MAP_NORESERVE set are not checked, and the default check is very weak, +leading to the risk of getting a process "OOM-killed". +Under Linux 2.4 any nonzero value implies mode 1. +In mode 2 (available since Linux 2.6), the total virtual address space +on the system is limited to (SS + RAM*(r/100)), +where SS is the size of the swap space, and RAM +is the size of the physical memory, and r is the contents of the file +.IR /proc/sys/vm/overcommit_ratio . +.TP +.I /proc/sys/vm/overcommit_ratio +See the description of +.IR /proc/sys/vm/overcommit_memory . +.TP +.I /proc/sysvipc +Subdirectory containing the pseudo-files +.IR msg ", " sem " and " shm "." +These files list the System V Interprocess Communication (IPC) objects +(respectively: message queues, semaphores, and shared memory) +that currently exist on the system, +providing similar information to that available via +.BR ipcs (1). +These files have headers and are formatted (one IPC object per line) +for easy understanding. +.BR ipc (5) +provides further background on the information shown by these files. +.TP +.I /proc/tty +Subdirectory containing the psuedo-files and subdirectories for +tty drivers and line disciplines. +.TP +.I /proc/uptime +This file contains two numbers: the uptime of the system (seconds), +and the amount of time spent in idle process (seconds). +.TP +.I /proc/version +This string identifies the kernel version that is currently running. +It includes the contents of /proc/sys/ostype, /proc/sys/osrelease and +/proc/sys/version. For example: +.nf +.in -2 +.ft CW +Linux version 1.0.9 (quinlan@phaze) #1 Sat May 14 01:51:54 EDT 1994 +.ft +.in +2 +.fi +.TP +.IR /proc/vmstat " (since Linux 2.6)" +This file displays various virtual memory statistics. + +.RE +.RE +.SH "SEE ALSO" +.BR cat (1), +.BR find (1), +.BR free (1), +.BR mount (1), +.BR ps (1), +.BR tr (1), +.BR uptime (1), +.BR chroot (2), +.BR mmap (2), +.BR readlink (2), +.BR syslog (2), +.BR slabinfo (5), +.BR hier (7), +.BR arp (8), +.BR dmesg (8), +.BR hdparm (8), +.BR ifconfig (8), +.BR init (8), +.BR lsmod (8), +.BR lspci (8), +.BR netstat (8), +.BR procinfo (8), +.BR route (8) +.br +.I /usr/src/linux/Documentation/filesystems/proc.txt +.SH CAVEATS +Note that many strings (i.e., the environment and command line) are in +the internal format, with sub-fields terminated by NUL bytes, so you +may find that things are more readable if you use \fIod -c\fP or \fItr +"\\000" "\\n"\fP to read them. +Alternatively, \fIecho `cat `\fP works well. + +This manual page is incomplete, possibly inaccurate, and is the kind +of thing that needs to be updated very often. +.SH ACKNOWLEDGEMENTS +The material on /proc/sys/fs and /proc/sys/kernel is closely based on +kernel source documentation files written by Rik van Riel. diff --git a/man5/protocols.5 b/man5/protocols.5 new file mode 100644 index 000000000..645cc57ac --- /dev/null +++ b/man5/protocols.5 @@ -0,0 +1,82 @@ +.\" Copyright (c) 1995 Martin Schulze +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 1995-10-18 Martin Schulze +.\" * first released +.\" 2002-09-22 Seth W. Klein +.\" * protocol numbers are now assigned by the IANA +.\" +.TH PROTOCOLS 5 2002-09-22 "Linux" "Linux Programmer's Manual" +.SH NAME +protocols \- the protocols definition file +.SH DESCRIPTION +This file is a plain ASCII file, describing the various DARPA internet +protocols that are available from the TCP/IP subsystem. It should be +consulted instead of using the numbers in the ARPA include files, or, +even worse, just guessing them. These numbers will occur in the +protocol field of any ip header. + +Keep this file untouched since changes would result in incorrect ip +packages. Protocol numbers and names are specified by the IANA +(Internet Assigned Numbers Authority). +.\" .. by the DDN Network Information Center. + +Each line is of the following format: + +.RS +.I protocol number aliases ... +.RE + +where the fields are delimited by spaces or tabs. +Empty lines are ignored. +If a line contains a hash mark (#), the hash mark and the part +of the line following it are ignored. + +The field descriptions are: + +.TP +.I protocol +the native name for the protocol. For example ip, tcp, or udp. +.TP +.I number +the official number for this protocol as it will appear within the ip +header. +.TP +.I aliases +optional aliases for the protocol. +.LP + +This file might be distributed over a network using a networkwide +naming service like Yellow Pages/NIS or BIND/Hesiod. + +.SH FILES +.TP +.I /etc/protocols +The protocols definition file. +.SH "SEE ALSO" +.BR getprotoent (3) + +Guide to Yellow Pages Service + +Guide to BIND/Hesiod Service + +http://www.iana.org/assignments/protocol-numbers diff --git a/man5/resolv.conf.5 b/man5/resolv.conf.5 new file mode 100644 index 000000000..dac44f702 --- /dev/null +++ b/man5/resolv.conf.5 @@ -0,0 +1,195 @@ +.\" Copyright (c) 1986 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms are permitted +.\" provided that the above copyright notice and this paragraph are +.\" duplicated in all such forms and that any documentation, +.\" advertising materials, and other materials related to such +.\" distribution and use acknowledge that the software was developed +.\" by the University of California, Berkeley. The name of the +.\" University may not be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" +.\" @(#)resolver.5 5.9 (Berkeley) 12/14/89 +.\" $Id: resolver.5,v 8.6 1999/05/21 00:01:02 vixie Exp $ +.\" +.\" Added ndots remark by Bernhard R. Link - debian bug #182886 +.\" +.TH RESOLV.CONF 5 2004-10-31 +.UC 4 +.SH NAME +resolv.conf \- resolver configuration file +.SH SYNOPSIS +/etc/resolv.conf +.SH DESCRIPTION +The +.I resolver +is a set of routines in the C library +that provide access to the Internet Domain Name System (DNS). +The resolver configuration file contains information that is read +by the resolver routines the first time they are invoked by a process. +The file is designed to be human readable and contains a list of +keywords with values that provide various types of resolver information. +.LP +On a normally configured system this file should not be necessary. +The only name server to be queried will be on the local machine; +the domain name is determined from the host name +and the domain search path is constructed from the domain name. +.LP +The different configuration options are: +.TP +\fBnameserver\fP Name server IP address +Internet address (in dot notation) of a name server +that the resolver should query. +Up to MAXNS (currently 3, see ) name servers may be listed, +one per keyword. +If there are multiple servers, +the resolver library queries them in the order listed. +If no \fBnameserver\fP entries are present, +the default is to use the name server on the local machine. +(The algorithm used is to try a name server, and if the query times out, +try the next, until out of name servers, +then repeat trying all the name servers +until a maximum number of retries are made.) +.TP +\fBdomain\fP Local domain name. +Most queries for names within this domain can use short names +relative to the local domain. +If no \fBdomain\fP entry is present, the domain is determined +from the local host name returned by +\fIgethostname\fP(); +the domain part is taken to be everything after the first `.'. +Finally, if the host name does not contain a domain part, the root +domain is assumed. +.TP +\fBsearch\fP Search list for host-name lookup. +The search list is normally determined from the local domain name; +by default, it contains only the local domain name. +This may be changed by listing the desired domain search path +following the \fIsearch\fP keyword with spaces or tabs separating +the names. +Resolver queries having fewer than +.I ndots +dots (default is 1) in them will be attempted using each component +of the search path in turn until a match is found. +For environments with multiple subdomains please read +.BI "options ndots:" n +below to avoid man-in-the-middle attacks and unnecessary +traffic for the root-dns-servers. +.\" When having a resolv.conv with a line +.\" search subdomain.domain.tld domain.tld +.\" and doing a hostlookup, for example by +.\" ping host.anothersubdomain +.\" it sends dns-requests for +.\" host.anothersubdomain. +.\" host.anothersubdomain.subdomain.domain.tld. +.\" host.anothersubdomain.domain.tld. +.\" thus not only causing unnecessary traffic for the root-dns-servers +.\" but broadcasting information to the outside and making man-in-the-middle +.\" attacks possible. +Note that this process may be slow and will generate a lot of network +traffic if the servers for the listed domains are not local, +and that queries will time out if no server is available +for one of the domains. +.IP +The search list is currently limited to six domains +with a total of 256 characters. +.TP +\fBsortlist\fP +Sortlist allows addresses returned by gethostbyname to be sorted. +A sortlist is specified by IP address netmask pairs. The netmask is +optional and defaults to the natural netmask of the net. The IP address +and optional network pairs are separated by slashes. Up to 10 pairs may +be specified. E.g., +.br +.in +2 +sortlist 130.155.160.0/255.255.240.0 130.155.0.0 +.in -2 +.br +.TP +\fBoptions\fP +Options allows certain internal resolver variables to be modified. +The syntax is +.RS +.IP +\fBoptions\fP \fIoption\fP \fI...\fP +.LP +where \fIoption\fP is one of the following: +.TP +\fBdebug\fP +sets RES_DEBUG in +.IR _res.options . +.TP +.BI ndots: n +sets a threshold for the number of dots which +must appear in a name given to \fBres_query\fP() (see +.BR resolver (3)) +before an \fIinitial absolute query\fP will be made. The default for +\fIn\fP is ``1'', meaning that if there are any dots in a name, the name +will be tried first as an absolute name before any \fIsearch list\fP +elements are appended to it. +.TP +.BI timeout: n +sets the amount of time the resolver will wait for a +response from a remote name server before retrying the +query via a different name server. Measured in seconds, +the default is RES_TIMEOUT (currently 5, see ). +.TP +.BI attempts: n +sets the number of times the resolver will send a +query to its name servers before giving up and returning +an error to the calling application. The default +is RES_DFLRETRY (currently 2, see ). +.TP +.B rotate +sets RES_ROTATE in +.IR _res.options , +which causes round robin selection of nameservers from among those listed. +This has the effect of spreading the query load among all listed servers, +rather than having all clients try the first listed server first every time. +.TP +.B no-check-names +sets RES_NOCHECKNAME in +.IR _res.options , +which disables the modern BIND checking of incoming host names and +mail names for invalid characters such as underscore (_), non-ASCII, +or control characters. +.TP +.B inet6 +sets RES_USE_INET6 in +.IR _res.options . +This has the effect of trying a AAAA query before an A query inside the +.IR gethostbyname () +function, and of mapping IPv4 responses in IPv6 ``tunnelled form'' +if no AAAA records are found but an A record set exists. +.RE +.LP +The \fIdomain\fP and \fIsearch\fP keywords are mutually exclusive. +If more than one instance of these keywords is present, +the last instance wins. +.LP +The \fIsearch\fP keyword of a system's \fIresolv.conf\fP file can be +overridden on a per-process basis by setting the environment variable +``\s-1LOCALDOMAIN\s+1'' to a space-separated list of search domains. +.LP +The \fIoptions\fP keyword of a system's \fIresolv.conf\fP file can be +amended on a per-process basis by setting the environment variable +``\s-1RES_OPTIONS\s+1'' to a space-separated list of resolver options +as explained above under \fBoptions\fP. +.LP +The keyword and value must appear on a single line, and the keyword +(e.g. \fBnameserver\fP) must start the line. The value follows +the keyword, separated by white space. +.SH FILES +.IR /etc/resolv.conf , +.I +.SH "SEE ALSO" +.BR gethostbyname (3), +.BR resolver (3), +.BR hostname (7), +.BR named (8) +.br +Name Server Operations Guide for BIND diff --git a/man5/resolver.5 b/man5/resolver.5 new file mode 100644 index 000000000..86104b96c --- /dev/null +++ b/man5/resolver.5 @@ -0,0 +1 @@ +.so man5/resolv.conf.5 diff --git a/man5/rpc.5 b/man5/rpc.5 new file mode 100644 index 000000000..5150b56d7 --- /dev/null +++ b/man5/rpc.5 @@ -0,0 +1,74 @@ +.\" @(#)rpc.5 2.2 88/08/03 4.0 RPCSRC; from 1.4 87/11/27 SMI; +.TH RPC 5 1985-09-26 +.SH NAME +rpc \- rpc program number data base +.SH SYNOPSIS +.B /etc/rpc +.SH DESCRIPTION +The +.I rpc +file contains user readable names that +can be used in place of rpc program numbers. +Each line has the following information: +.HP 10 +name of server for the rpc program +.br +.ns +.HP 10 +rpc program number +.br +.ns +.HP 10 +aliases +.LP +Items are separated by any number of blanks and/or +tab characters. +A '#' indicates the beginning of a comment; characters from +the '#' to the end of the line are not interpreted by routines +which search the file. +.LP +Here is an example of the \fI/etc/rpc\fP file from the Sun RPC Source +distribution. +.nf +.ta 1.5i +0.5i +1.0i +1.0i +# +# rpc 88/08/01 4.0 RPCSRC; from 1.12 88/02/07 SMI +# +portmapper 100000 portmap sunrpc +rstatd 100001 rstat rstat_svc rup perfmeter +rusersd 100002 rusers +nfs 100003 nfsprog +ypserv 100004 ypprog +mountd 100005 mount showmount +ypbind 100007 +walld 100008 rwall shutdown +yppasswdd 100009 yppasswd +etherstatd 100010 etherstat +rquotad 100011 rquotaprog quota rquota +sprayd 100012 spray +3270_mapper 100013 +rje_mapper 100014 +selection_svc 100015 selnsvc +database_svc 100016 +rexd 100017 rex +alis 100018 +sched 100019 +llockmgr 100020 +nlockmgr 100021 +x25.inr 100022 +statmon 100023 +status 100024 +bootparam 100026 +ypupdated 100028 ypupdate +keyserv 100029 keyserver +tfsd 100037 +nsed 100038 +nsemntd 100039 +.fi +.DT +.SH FILES +.TP +.I /etc/rpc +rpc program number data base +.SH "SEE ALSO" +.BR getrpcent (3) diff --git a/man5/securetty.5 b/man5/securetty.5 new file mode 100644 index 000000000..7c710303f --- /dev/null +++ b/man5/securetty.5 @@ -0,0 +1,43 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sun Jul 25 11:06:27 1993 by Rik Faith (faith@cs.unc.edu) +.TH SECURETTY 5 1992-12-29 "Linux" "Linux Programmer's Manual" +.SH NAME +securetty \- file which lists ttys from which root can log in +.SH DESCRIPTION +The file +.I /etc/securetty +is used by (some versions of) +.BR login (1). +The file contains the device names of tty lines +(one per line, without leading +.IR /dev/ ) +on which root is allowed to login. +See +.BR login.defs (5) +if you use the shadow suite. +.SH FILES +.I /etc/securetty +.SH "SEE ALSO" +.BR login (1), +.BR login.defs (5) diff --git a/man5/services.5 b/man5/services.5 new file mode 100644 index 000000000..6a9a855d3 --- /dev/null +++ b/man5/services.5 @@ -0,0 +1,207 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 1996 Austin Donnelly , +.\" with additional material (c) 1995 Martin Schulze +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" This manpage was made by merging two independently written manpages, +.\" one written by Martin Schulze (18 Oct 95), the other written by +.\" Austin Donnelly, (9 Jan 96). +.\" +.\" Thu Jan 11 12:14:41 1996 Austin Donnelly +.\" * Merged two services(5) manpages +.\" +.TH SERVICES 5 1996-01-11 "Linux" "Linux Programmer's Manual" +.SH NAME +services \- Internet network services list +.SH DESCRIPTION +.B services +is a plain ASCII file providing a mapping between friendly textual +names for internet services, and their underlying assigned port +numbers and protocol types. Every networking program should look into +this file to get the port number (and protocol) for its service. +The C library routines +.BR getservent (3), +.BR getservbyname (3), +.BR getservbyport (3), +.BR setservent (3), +and +.BR endservent (3) +support querying this file from programs. + +Port numbers are assigned by the IANA (Internet Assigned Numbers +Authority), and their current policy is to assign both TCP and UDP +protocols when assigning a port number. Therefore, most entries will +have two entries, even for TCP only services. + +Port numbers below 1024 (so-called 'low numbered' ports) can only be +bound to by root (see +.BR bind (2), +.BR tcp (7), +and +.BR udp (7)). +This is so clients connecting to low numbered ports can trust +that the service running on the port is the standard implementation, +and not a rogue service run by a user of the machine. Well-known port +numbers specified by the IANA are normally located in this root-only +space. + +The presence of an entry for a service in the +.B services +file does not necessarily mean that the service is currently running +on the machine. See +.BR inetd.conf (5) +for the configuration of Internet services offered. Note that not all +networking services are started by +.BR inetd (8), +and so won't appear in +.BR inetd.conf (5). +In particular, news (NNTP) and mail (SMTP) servers are often +initialized from the system boot scripts. + +The location of the +.B services +file is defined by +.B _PATH_SERVICES +in +.IR /usr/include/netdb.h "." +This is usually set to +.IR /etc/services "." + +Each line describes one service, and is of the form: +.IP +\f2service-name\ \ \ port\f3/\f2protocol\ \ \ \f1[\f2aliases ...\f1] +.TP +where: +.TP 10 +.I service-name +is the friendly name the service is known by and looked up under. It +is case sensitive. Often, the client program is named after the +.IR service-name "." +.TP +.I port +is the port number (in decimal) to use for this service. +.TP +.I protocol +is the type of protocol to be used. This field should match an entry +in the +.BR protocols (5) +file. Typical values include +.B tcp +and +.BR udp . +.TP +.I aliases +is an optional space or tab separated list of other names for this +service (but see the BUGS section below). Again, the names are case +sensitive. +.PP + +Either spaces or tabs may be used to separate the fields. + +Comments are started by the hash sign (#) and continue until the end +of the line. Blank lines are skipped. + +The +.I service-name +should begin in the first column of the file, since leading spaces are +not stripped. +.I service-names +can be any printable characters excluding space and tab. However, +a conservative choice of characters should be used to minimize +inter-operability problems. E.g., a-z, 0-9, and hyphen (\-) would seem a +sensible choice. + +Lines not matching this format should not be present in the +file. (Currently, they are silently skipped by +.BR getservent (3), +.BR getservbyname (3), +and +.BR getservbyport (3). +However, this behaviour should not be relied on.) + +As a backwards compatibility feature, the slash (/) between the +.I port +number and +.I protocol +name can in fact be either a slash or a comma (,). Use of the comma in +modern installations is depreciated. + +This file might be distributed over a network using a network-wide +naming service like Yellow Pages/NIS or BIND/Hesiod. + +A sample +.B services +file might look like this: +.RS +.nf +.sp +.ta 3i +netstat 15/tcp +qotd 17/tcp quote +msp 18/tcp # message send protocol +msp 18/udp # message send protocol +chargen 19/tcp ttytst source +chargen 19/udp ttytst source +ftp 21/tcp +# 22 - unassigned +telnet 23/tcp +.sp +.fi +.RE +.SH BUGS +There is a maximum of 35 aliases, due to the way the +.BR getservent (3) +code is written. + +Lines longer than +.B BUFSIZ +(currently 1024) characters will be ignored by +.BR getservent (3), +.BR getservbyname (3), +and +.BR getservbyport (3). +However, this will also cause the next line to be mis-parsed. +.SH FILES +.TP +.I /etc/services +The Internet network services list +.TP +.I /usr/include/netdb.h +Definition of +.B _PATH_SERVICES +.SH "SEE ALSO" +.BR listen (2), +.BR endservent (3), +.BR getservbyname (3), +.BR getservbyport (3), +.BR getservent (3), +.BR setservent (3), +.BR inetd.conf (5), +.BR protocols (5), +.BR inetd (8) + +Assigned Numbers RFC, most recently RFC 1700, (AKA STD0002) + +Guide to Yellow Pages Service + +Guide to BIND/Hesiod Service diff --git a/man5/shells.5 b/man5/shells.5 new file mode 100644 index 000000000..cd7d091cb --- /dev/null +++ b/man5/shells.5 @@ -0,0 +1,52 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Thu May 20 20:45:48 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 17:11:07 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Nov 21 10:49:38 1993 by Michael Haardt +.\" Modified Sun Feb 26 15:09:15 1995 by Rik Faith (faith@cs.unc.edu) +.TH SHELLS 5 1993-11-21 "" "Linux Programmer's Manual" +.SH NAME +shells \- pathnames of valid login shells +.SH DESCRIPTION +.B /etc/shells +is a text file which contains the full pathnames of valid login shells. +This file is consulted by +.BR chsh (1) +and available to be queried by other programs. +.PP +Be aware that there are programs which consult this file to +find out if a user is a normal user. E.g.: ftp daemons traditionally +disallow access to users with shells not included in this file. +.SH EXAMPLES +.B /etc/shells +may contain the following paths: +.sp +.RS +.I /bin/sh +.br +.I /bin/csh +.RE +.SH FILES +.I /etc/shells +.SH "SEE ALSO" +.BR chsh (1), +.BR getusershell (3) diff --git a/man5/slabinfo.5 b/man5/slabinfo.5 new file mode 100644 index 000000000..ec53777fc --- /dev/null +++ b/man5/slabinfo.5 @@ -0,0 +1,111 @@ +.\" Copyright (c) 2001 Andreas Dilger (adilger@turbolinux.com) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH SLABINFO 5 2001-06-19 "" "Linux manual" +.SH NAME +/proc/slabinfo \- Kernel slab allocator statistics +.SH SYNOPSIS +.B cat /proc/slabinfo +.SH DESCRIPTION +Frequently used objects in the Linux kernel +(buffer heads, inodes, dentries, etc.) +have their own cache. The file +.I /proc/slabinfo +gives statistics. For example: +.LP +.RS +.nf +% cat /proc/slabinfo +slabinfo - version: 1.1 +kmem_cache 60 78 100 2 2 1 +blkdev_requests 5120 5120 96 128 128 1 +mnt_cache 20 40 96 1 1 1 +inode_cache 7005 14792 480 1598 1849 1 +dentry_cache 5469 5880 128 183 196 1 +filp 726 760 96 19 19 1 +buffer_head 67131 71240 96 1776 1781 1 +vm_area_struct 1204 1652 64 23 28 1 +\&... +size-8192 1 17 8192 1 17 2 +size-4096 41 73 4096 41 73 1 +\&... +.fi +.RE +.LP +For each slab cache, the cache name, the number of currently +active objects, the total number of available objects, the +size of each object in bytes, the number of pages with at +least one active object, the total number of allocated pages, +and the number of pages per slab are given. + +Note that because of object alignment and slab cache overhead, +objects are not normally packed tightly into pages. Pages with +even one in-use object are considered in-use and cannot be +freed. + +Kernels compiled with slab cache statistics will also have +"(statistics)" in the first line of output, and will have 5 +additional columns, namely: the high water mark of active +objects; the number of times objects have been allocated; +the number of times the cache has grown (new pages added +to this cache); the number of times the cache has been +reaped (unused pages removed from this cache); and the +number of times there was an error allocating new pages +to this cache. If slab cache statistics are not enabled +for this kernel, these columns will not be shown. + +SMP systems will also have "(SMP)" in the first line of +output, and will have two additional columns for each slab, +reporting the slab allocation policy for the CPU-local +cache (to reduce the need for inter-CPU synchronization +when allocating objects from the cache). The first column +is the per-CPU limit: the maximum number of objects that +will be cached for each CPU. The second column is the +batchcount: the maximum number of free objects in the +global cache that will be transferred to the per-CPU cache +if it is empty, or the number of objects to be returned +to the global cache if the per-CPU cache is full. + +If both slab cache statistics and SMP are defined, there +will be four additional columns, reporting the per-CPU +cache statistics. The first two are the per-CPU cache +allocation hit and miss counts: the number of times an +object was or was not available in the per-CPU cache +for allocation. The next two are the per-CPU cache free +hit and miss counts: the number of times a freed object +could or could not fit within the per-CPU cache limit, +before flushing objects to the global cache. + +It is possible to tune the SMP per-CPU slab cache limit +and batchcount via: + +.nf +echo "\fIcache_name limit batchcount\fP" > /proc/slabinfo +.fi + +.SH AVAILABILITY +.I /proc/slabinfo +exists since Linux 2.1.23. +SMP per-CPU caches exist since Linux 2.4.0-test3. + +.SH FILES +.I diff --git a/man5/termcap.5 b/man5/termcap.5 new file mode 100644 index 000000000..a330f8b86 --- /dev/null +++ b/man5/termcap.5 @@ -0,0 +1,451 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified formatting Sat Jul 24 17:13:38 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified (extensions and corrections) Sun May 1 14:21:25 MET DST 1994 Michael Haardt +.\" If mistakes in the capabilities are found, please send a bug report to: +.\" michael@moria.de +.\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond (esr@thyrsus.com) +.TH TERMCAP 5 "" "Linux" "Linux Programmer's Manual" +.SH NAME +termcap \- terminal capability database +.SH DESCRIPTION +The termcap database is an obsolete facility for describing the +capabilities of character-cell terminals and printers. It is retained +only for capability with old programs; new ones should use the +.BR terminfo (5) +database and associated libraries. +.LP +.B /etc/termcap +is an ASCII file (the database master) that lists the capabilities of +many different types of terminals. Programs can read termcap to find +the particular escape codes needed to control the visual attributes of +the terminal actually in use. (Other aspects of the terminal are +handled by stty.) The termcap database is indexed on the TERM +environment variable. +.LP +Termcap entries must be defined on a single logical line, with `\\' +used to suppress the newline. Fields are separated by `:'. The first +field of each entry starts at the left-hand margin, and contains a list +of names for the terminal, separated by '|'. +.LP +The first subfield may (in BSD termcap entries from versions 4.3 and +prior) contain a short name consisting of two characters. This short +name may consist of capital or small letters. In 4.4BSD termcap +entries this field is omitted. +.LP +The second subfield (first, in the newer 4.4BSD format) contains the +name used by the environment variable TERM. It should be spelled in +lowercase letters. Selectable hardware capabilities should be marked +by appending a hyphen and a suffix to this name. See below for an +example. Usual suffixes are w (more than 80 characters wide), am +(automatic margins), nam (no automatic margins), and rv (reverse video +display). The third subfield contains a long and descriptive name for +this termcap entry. +.LP +Subsequent fields contain the terminal capabilities; any continued +capability lines must be indented one tab from the left margin. +.LP +Although there is no defined order, it is suggested to write first +boolean, then numeric, and then string capabilities, each sorted +alphabetically without looking at lower or upper spelling. Capabilities +of similar functions can be written in one line. +.LP +.nf +Example for: +.sp +Head line: vt|vt101|DEC VT 101 terminal in 80 character mode:\e +Head line: Vt|vt101-w|DEC VT 101 terminal in (wide) 132 character mode:\e +Boolean: :bs:\e +Numeric: :co#80:\e +String: :sr=\eE[H:\e +.SS "Boolean Capabilities" +.nf +5i Printer will not echo on screen +am Automatic margins which means automatic line wrap +bs Control-H (8 dec.) performs a backspace +bw Backspace on left margin wraps to previous line and right margin +da Display retained above screen +db Display retained below screen +eo A space erases all characters at cursor position +es Escape sequences and special characters work in status line +gn Generic device +hc This is a hardcopy terminal +HC The cursor is hard to see when not on bottom line +hs Has a status line +hz Hazeltine bug, the terminal can not print tilde characters +in Terminal inserts nulls, not spaces, to fill whitespace +km Terminal has a meta key +mi Cursor movement works in insert mode +ms Cursor movement works in standout/underline mode +NP No pad character +NR ti does not reverse te +nx No padding, must use XON/XOFF +os Terminal can overstrike +ul Terminal underlines although it can not overstrike +xb Beehive glitch, f1 sends ESCAPE, f2 sends ^C +xn Newline/wraparound glitch +xo Terminal uses xon/xoff protocol +xs Text typed over standout text will be displayed in standout +xt Teleray glitch, destructive tabs and odd standout mode +.fi +.SS "Numeric Capabilities" +.nf +co Number of columns +dB Delay in milliseconds for backspace on hardcopy terminals +dC Delay in milliseconds for carriage return on hardcopy terminals +dF Delay in milliseconds for form feed on hardcopy terminals +dN Delay in milliseconds for new line on hardcopy terminals +dT Delay in milliseconds for tabulator stop on hardcopy terminals +dV Delay in milliseconds for vertical tabulator stop on hardcopy terminals +it Difference between tab positions +lh Height of soft labels +lm Lines of memory +lw Width of soft labels +li Number of lines +Nl Number of soft labels +pb Lowest baud rate which needs padding +sg Standout glitch +ug Underline glitch +vt virtual terminal number +ws Width of status line if different from screen width +.fi +.SS "String Capabilities" +.nf +!1 shifted save key +!2 shifted suspend key +!3 shifted undo key +#1 shifted help key +#2 shifted home key +#3 shifted input key +#4 shifted cursor left key +%0 redo key +%1 help key +%2 mark key +%3 message key +%4 move key +%5 next-object key +%6 open key +%7 options key +%8 previous-object key +%9 print key +%a shifted message key +%b shifted move key +%c shifted next key +%d shifted options key +%e shifted previous key +%f shifted print key +%g shifted redo key +%h shifted replace key +%i shifted cusor right key +%j shifted resume key +&0 shifted cancel key +&1 reference key +&2 refresh key +&3 replace key +&4 restart key +&5 resume key +&6 save key +&7 suspend key +&8 undo key +&9 shifted begin key +*0 shifted find key +*1 shifted command key +*2 shifted copy key +*3 shifted create key +*4 shifted delete character +*5 shifted delete line +*6 select key +*7 shifted end key +*8 shifted clear line key +*9 shifted exit key +@0 find key +@1 begin key +@2 cancel key +@3 close key +@4 command key +@5 copy key +@6 create key +@7 end key +@8 enter/send key +@9 exit key +al Insert one line +AL Indert %1 lines +ac Pairs of block graphic characters to map alternate character set +ae End alternative character set +as Start alternative character set for block graphic characters +bc Backspace, if not ^H +bl Audio bell +bt Move to previous tab stop +cb Clear from beginning of line to cursor +cc Dummy command character +cd Clear to end of screen +ce Clear to end of line +ch Move cursor horizontally only to column %1 +cl Clear screen and cursor home +cm Cursor move to row %1 and column %2 (on screen) +CM Move cursor to row %1 and column %2 (in memory) +cr Carriage return +cs Scroll region from line %1 to %2 +ct Clear tabs +cv Move cursor vertically only to line %1 +dc Delete one character +DC Delete %1 characters +dl Delete one line +DL Delete %1 lines +dm Begin delete mode +do Cursor down one line +DO Cursor down #1 lines +ds Disable status line +eA Enable alternate character set +ec Erase %1 characters starting at cursor +ed End delete mode +ei End insert mode +ff Formfeed character on hardcopy terminals +fs Return character to its position before going to status line +F1 The string sent by function key f11 +F2 The string sent by function key f12 +F3 The string sent by function key f13 +\&... \&... +F9 The string sent by function key f19 +FA The string sent by function key f20 +FB The string sent by function key f21 +\&... \&... +FZ The string sent by function key f45 +Fa The string sent by function key f46 +Fb The string sent by function key f47 +\&... \&... +Fr The string sent by function key f63 +hd Move cursor a half line down +ho Cursor home +hu Move cursor a half line up +i1 Initialization string 1 at login +i3 Initialization string 3 at login +is Initialization string 2 at login +ic Insert one character +IC Insert %1 characters +if Initialization file +im Begin insert mode +ip Insert pad time and needed special characters after insert +iP Initialization program +K1 upper left key on keypad +K2 center key on keypad +K3 upper right key on keypad +K4 bottom left key on keypad +K5 bottom right key on keypad +k0 Function key 0 +k1 Function key 1 +k2 Function key 2 +k3 Function key 3 +k4 Function key 4 +k5 Function key 5 +k6 Function key 6 +k7 Function key 7 +k8 Function key 8 +k9 Function key 9 +k; Function key 10 +ka Clear all tabs key +kA Insert line key +kb Backspace key +kB Back tab stop +kC Clear screen key +kd Cursor down key +kD Key for delete character under cursor +ke turn keypad off +kE Key for clear to end of line +kF Key for scolling forward/down +kh Cursor home key +kH Cursor hown down key +kI Insert character/Insert mode key +kl Cursor left key +kL Key for delete line +kM Key for exit insert mode +kN Key for next page +kP Key for previous page +kr Cursor right key +kR Key for scolling backward/up +ks Turn keypad on +kS Clear to end of screen key +kt Clear this tab key +kT Set tab here key +ku Cursor up key +l0 Label of zeroth function key, if not f0 +l1 Label of first function key, if not f1 +l2 Label of first function key, if not f2 +\&... \&... +la Label of tenth function key, if not f10 +le Cursor left one character +ll Move cursor to lower left corner +LE Cursor left %1 characters +LF Turn soft labels off +LO Turn soft labels on +mb Start blinking +MC Clear soft margins +md Start bold mode +me End all mode like so, us, mb, md and mr +mh Start half bright mode +mk Dark mode (Characters invisible) +ML Set left soft margin +mm Put terminal in meta mode +mo Put terminal out of meta mode +mp Turn on protected attribute +mr Start reverse mode +MR Set right soft margin +nd Cursor right one character +nw Carriage return command +pc Padding character +pf Turn printer off +pk Program key %1 to send string %2 as if typed by user +pl Program key %1 to execute string %2 in local mode +pn Program soft label %1 to to show string %2 +po Turn the printer on +pO Turn the printer on for %1 (<256) bytes +ps Print screen contents on printer +px Program key %1 to send string %2 to computer +r1 Reset string 1 to set terminal to sane modes +r2 Reset string 2 to set terminal to sane modes +r3 Reset string 3 to set terminal to sane modes +RA disable automatic margins +rc Restore saved cursor position +rf Reset string file name +RF Request for input from terminal +RI Cursor right %1 characters +rp Repeat character %1 for %2 times +rP Padding after character sent in replace mode +rs Reset string +RX Turn off XON/XOFF flow control +sa Set %1 %2 %3 %4 %5 %6 %7 %8 %9 attributes +SA enable automatic margins +sc Save cursor position +se End standout mode +sf Normal scroll one line +SF Normal scroll %1 lines +so Start standout mode +sr Reverse scroll +SR scroll back %1 lines +st Set tabulator stop in all rows at current column +SX Turn on XON/XOFF flow control +ta move to next hardware tab +tc Read in terminal description from another entry +te End program that uses cursor motion +ti Begin program that uses cursor motion +ts Move cursor to column %1 of status line +uc Underline character under cursor and move cursor right +ue End underlining +up Cursor up one line +UP Cursor up %1 lines +us Start underlining +vb Visible bell +ve Normal cursor visible +vi Cursor unvisible +vs Standout cursor +wi Set window from line %1 to %2 and column %3 to %4 +XF XOFF character if not ^S +.fi +.LP +There are several ways of defining the control codes for string capabilities: +.LP +Normal Characters except '^','\e' and '%' repesent themself. +.LP +A '^x' means Control-x. Control-A equals 1 decimal. +.LP +\ex means a special code. x can be one of the following charaters: +.RS +E Escape (27) +.br +n Linefeed (10) +.br +r Carriage return (13) +.br +t Tabulation (9) +.br +b Backspace (8) +.br +f Form feed (12) +.br +0 Null character. A \exxx specifies the octal character xxx. +.RE +.IP i +Increments paramters by one. +.IP r +Single parameter capability +.IP + +Add value of next character to this parameter and do binary output +.IP 2 +Do ASCII output of this parameter with a field with of 2 +.IP d +Do ASCII output of this parameter with a field with of 3 +.IP % +Print a '%' +.LP +If you use binary output, then you should avoid the null character +because it terminates the string. You should reset tabulator expansion +if a tabulator can be the binary output of a parameter. +.IP Warning: +The above metacharacters for parameters may be wrong, they document Minix +termcap which may not be compatible with Linux termcap. +.LP +The block graphic characters can be specified by three string capabilities: +.IP as +start the alternative charset +.IP ae +end it +.IP ac +pairs of characters. The first character is the name of the block graphic +symbol and the second characters is its definition. +.LP +The following names are available: +.sp +.nf ++ right arrow (>) +, left arrow (<) +\&. down arrow (v) +0 full square (#) +I latern (#) +- upper arrow (^) +\&' rhombus (+) +a chess board (:) +f degree (') +g plus-minus (#) +h square (#) +j right bottom corner (+) +k right upper corner (+) +l left upper corner (+) +m left bottom corner (+) +n cross (+) +o upper horizontal line (-) +q middle horizontal line (-) +s bottom horizontal line (_) +t left tee (+) +u right tee (+) +v bottom tee (+) +w normal tee (+) +x vertical line (|) +~ paragraph (???) +.fi +.sp +The values in parentheses are suggested defaults which are used by curses, +if the capabilities are missing. +.SH "SEE ALSO" +.BR curses (3), +.BR termcap (3), +.BR terminfo (5) diff --git a/man5/ttytype.5 b/man5/ttytype.5 new file mode 100644 index 000000000..096274ab1 --- /dev/null +++ b/man5/ttytype.5 @@ -0,0 +1,64 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 17:17:50 1993 by Rik Faith +.\" Modified Thu Oct 19 21:25:21 MET 1995 by Martin Schulze +.\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond +.\" xk +.TH TTYTYPE 5 1993-07-24 "Linux" "Linux Programmer's Manual" +.SH NAME +ttytype \- terminal device to default terminal type mapping +.SH DESCRIPTION +The +.I /etc/ttytype +file associates termcap/terminfo terminal type names +with tty lines. Each line consists of a terminal type, followed by +whitespace, followed by a tty name (a device name without the +.IR /dev/ ") prefix." + +This association is used by the program +.BR tset (1) +to set the environment variable TERM to the default terminal name for +the user's current tty. + +This facility was designed for a traditional time-sharing environment +featuring character-cell terminals hardwired to a Unix minicomputer. +It is little used on modern workstation and personal Unixes. +.SH EXAMPLE +A typical +.I /etc/ttytype +is: +.RS +.sp +con80x25 tty1 +.br +vt320 ttys0 +.sp +.RE +.SH FILES +.TP +.I /etc/ttytype +the tty definitions file. +.SH "SEE ALSO" +.BR getty (1), +.BR termcap (5), +.BR terminfo (5) diff --git a/man5/tzfile.5 b/man5/tzfile.5 new file mode 100644 index 000000000..91f67ef4d --- /dev/null +++ b/man5/tzfile.5 @@ -0,0 +1,138 @@ +.\" @(#)tzfile.5 7.11 +.\" This file is in the public domain, so clarified as of +.\" 1996-06-05 by Arthur David Olson . +.TH TZFILE 5 +.SH NAME +tzfile \- time zone information +.SH SYNOPSIS +.B +#include +.SH DESCRIPTION +The time zone information files used by +.BR tzset (3) +begin with the magic characters "TZif" to identify then as +time zone information files, +followed by sixteen bytes reserved for future use, +followed by six four-byte values of type +.BR long , +written in a ``standard'' byte order +(the high-order byte of the value is written first). +These values are, +in order: +.TP +.I tzh_ttisgmtcnt +The number of UTC/local indicators stored in the file. +.TP +.I tzh_ttisstdcnt +The number of standard/wall indicators stored in the file. +.TP +.I tzh_leapcnt +The number of leap seconds for which data is stored in the file. +.TP +.I tzh_timecnt +The number of "transition times" for which data is stored +in the file. +.TP +.I tzh_typecnt +The number of "local time types" for which data is stored +in the file (must not be zero). +.TP +.I tzh_charcnt +The number of characters of "time zone abbreviation strings" +stored in the file. +.PP +The above header is followed by +.I tzh_timecnt +four-byte values of type +.BR long , +sorted in ascending order. +These values are written in ``standard'' byte order. +Each is used as a transition time (as returned by +.BR time (2)) +at which the rules for computing local time change. +Next come +.I tzh_timecnt +one-byte values of type +.BR "unsigned char" ; +each one tells which of the different types of ``local time'' types +described in the file is associated with the same-indexed transition time. +These values serve as indices into an array of +.I ttinfo +structures that appears next in the file; +these structures are defined as follows: +.in +.5i +.sp +.nf +.ta .5i +\w'unsigned int\0\0'u +struct ttinfo { + long tt_gmtoff; + int tt_isdst; + unsigned int tt_abbrind; +}; +.in -.5i +.fi +.sp +Each structure is written as a four-byte value for +.I tt_gmtoff +of type +.BR long , +in a standard byte order, followed by a one-byte value for +.I tt_isdst +and a one-byte value for +.IR tt_abbrind . +In each structure, +.I tt_gmtoff +gives the number of seconds to be added to UTC, +.I tt_isdst +tells whether +.I tm_isdst +should be set by +.BR localtime (3), +and +.I tt_abbrind +serves as an index into the array of time zone abbreviation characters +that follow the +.I ttinfo +structure(s) in the file. +.PP +Then there are +.I tzh_leapcnt +pairs of four-byte values, written in standard byte order; +the first value of each pair gives the time +(as returned by +.BR time (2)) +at which a leap second occurs; +the second gives the +.I total +number of leap seconds to be applied after the given time. +The pairs of values are sorted in ascending order by time. +.PP +Then there are +.I tzh_ttisstdcnt +standard/wall indicators, each stored as a one-byte value; +they tell whether the transition times associated with local time types +were specified as standard time or wall clock time, +and are used when a time zone file is used in handling POSIX-style +time zone environment variables. +.PP +Finally, there are +.I tzh_ttisgmtcnt +UTC/local indicators, each stored as a one-byte value; +they tell whether the transition times associated with local time types +were specified as UTC or local time, +and are used when a time zone file is used in handling POSIX-style +time zone environment variables. +.PP +.I Localtime +uses the first standard-time +.I ttinfo +structure in the file +(or simply the first +.I ttinfo +structure in the absence of a standard-time structure) +if either +.I tzh_timecnt +is zero or the time argument is less than the first transition time recorded +in the file. +.\" .SH "SEE ALSO" +.\" .BR newctime (3) diff --git a/man5/utmp.5 b/man5/utmp.5 new file mode 100644 index 000000000..576e72c68 --- /dev/null +++ b/man5/utmp.5 @@ -0,0 +1,242 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-02-26 by Michael Haardt +.\" Modified 1996-07-20 by Michael Haardt +.\" Modified 1997-07-02 by Nicolás Lichtmaier +.\" Modified 2004-10-31 by aeb, following Gwenole Beauchesne +.TH UTMP 5 2004-10-31 "File formats" "Linux Programmer's Manual" +.SH NAME +utmp, wtmp \- login records +.SH SYNOPSIS +#include +.SH DESCRIPTION +The +.I utmp +file allows one to discover information about who is currently using the +system. There may be more users currently using the system, because not +all programs use utmp logging. +.PP +.B Warning: +.I utmp +must not be writable, because many system programs (foolishly) +depend on its integrity. You risk faked system logfiles and +modifications of system files if you leave +.I utmp +writable to any user. +.PP +The file is a sequence of entries with the following structure declared +in the include file (note that this is only one of several definitions +around; details depend on the version of libc): +.in +3 +.nf +.sp +.ta 3i +#define UT_UNKNOWN 0 +#define RUN_LVL 1 +#define BOOT_TIME 2 +#define NEW_TIME 3 +#define OLD_TIME 4 +#define INIT_PROCESS 5 +#define LOGIN_PROCESS 6 +#define USER_PROCESS 7 +#define DEAD_PROCESS 8 +#define ACCOUNTING 9 + +#define UT_LINESIZE 12 +#define UT_NAMESIZE 32 +#define UT_HOSTSIZE 256 + +struct exit_status { + short int e_termination; /* process termination status. */ + short int e_exit; /* process exit status. */ +}; + +struct utmp { + short ut_type; /* type of login */ + pid_t ut_pid; /* pid of login process */ + char ut_line[UT_LINESIZE]; /* device name of tty \- "/dev/" */ + char ut_id[4]; /* init id or abbrev. ttyname */ + char ut_user[UT_NAMESIZE]; /* user name */ + char ut_host[UT_HOSTSIZE]; /* hostname for remote login */ + struct exit_status ut_exit; /* The exit status of a process + marked as DEAD_PROCESS. */ + long ut_session; /* session ID, used for windowing*/ + struct timeval ut_tv; /* time entry was made. */ + int32_t ut_addr_v6[4]; /* IP address of remote host. */ + char __unused[20]; /* Reserved for future use. */ +}; + +/* Backwards compatibility hacks. */ +#define ut_name ut_user +#ifndef _NO_UT_TIME +#define ut_time ut_tv.tv_sec +#endif +#define ut_xtime ut_tv.tv_sec +#define ut_addr ut_addr_v6[0] +.sp +.fi +.in +This structure gives the name of the special file associated with the +user's terminal, the user's login name, and the time of login in the form +of +.BR time (2). +String fields are terminated by \fB'\e0'\fP if they are shorter than the size +of the field. +.PP +The first entries ever created result from +.BR init (8) +processing +.BR inittab (5). +Before an entry is processed, though, +.BR init (8) +cleans up utmp by setting \fIut_type\fP to \fBDEAD_PROCESS\fP, clearing +\fIut_user\fP, \fIut_host\fP, and \fIut_time\fP with null bytes for each +record which \fIut_type\fP is not \fBDEAD_PROCESS\fP or \fBRUN_LVL\fP +and where no process with PID \fIut_pid\fP exists. If no empty record +with the needed \fIut_id\fP can be found, init creates a new one. It +sets \fIut_id\fP from the inittab, \fIut_pid\fP and \fIut_time\fP to the +current values, and \fIut_type\fP to \fBINIT_PROCESS\fP. +.PP +.BR getty (8) +locates the entry by the pid, changes \fIut_type\fP to +\fBLOGIN_PROCESS\fP, changes \fIut_time\fP, sets \fIut_line\fP, and waits +for connection to be established. +.BR login (8), +after a user has been +authenticated, changes \fIut_type\fP to \fBUSER_PROCESS\fP, changes +\fIut_time\fP, and sets \fIut_host\fP and \fIut_addr\fP. Depending on +.BR getty (8) +and +.BR login (8), +records may be located by +\fIut_line\fP instead of the preferable \fIut_pid\fP. +.PP +When +.BR init (8) +finds that a process has exited, it locates its utmp +entry by \fIut_pid\fP, sets \fIut_type\fP to \fBDEAD_PROCESS\fP, and +clears \fIut_user\fP, \fIut_host\fP and \fIut_time\fP with null bytes. +.PP +.BR xterm (1) +and other terminal emulators directly create a +\fBUSER_PROCESS\fP record and generate the \fIut_id\fP by using the last +two letters of \fI/dev/ttyp\fP\fI%c\fP or by using \fIp\fP\fI%d\fP for +\fI/dev/pts/\fP\fI%d\fP. If they find a \fBDEAD_PROCESS\fP for this id, +they recycle it, otherwise they create a new entry. If they can, they +will mark it as \fBDEAD_PROCESS\fP on exiting and it is advised that +they null \fIut_line\fP, \fIut_time\fP, \fIut_user\fP, and \fIut_host\fP +as well. +.PP +\fIxdm\fP(8) should not create a utmp record, because there is no +assigned terminal. Letting it create one will result in errors, such +as 'finger: cannot stat /dev/machine.dom'. It should create wtmp entries, +though, just like +.BR ftpd (8) +does. +.PP +.BR telnetd (8) +sets up a \fBLOGIN_PROCESS\fP entry and leaves the rest to +.BR login (8) +as usual. After the telnet session ends, +.BR telnetd (8) +cleans up utmp in the described way. +.PP +The \fIwtmp\fP file records all logins and logouts. Its format is +exactly like \fIutmp\fP except that a null user name indicates a logout +on the associated terminal. Furthermore, the terminal name \fB~\fP +with user name \fBshutdown\fP or \fBreboot\fP indicates a system +shutdown or reboot and the pair of terminal names \fB|\fP/\fB}\fP +logs the old/new system time when +.BR date (1) +changes it. \fIwtmp\fP is maintained by +.BR login (1), +.BR init (1), +and some versions of +.BR getty (1). +Neither of these programs creates the file, so if it is +removed, record-keeping is turned off. +.SH FILES +/var/run/utmp +.br +/var/log/wtmp +.SH "CONFORMING TO" +Linux utmp entries conform neither to v7/BSD nor to SYSV; they are a +mix of the two. v7/BSD has fewer fields; most importantly it lacks +\fIut_type\fP, which causes native v7/BSD-like programs to display (for +example) dead or login entries. Further, there is no configuration file +which allocates slots to sessions. BSD does so because it lacks +\fIut_id\fP fields. In Linux (as in SYSV), the \fIut_id\fP field of a +record will never change once it has been set, which reserves that slot +without needing a configuration file. Clearing \fIut_id\fP may result +in race conditions leading to corrupted utmp entries and and potential +security holes. Clearing the above mentioned fields by filling them +with null bytes is not required by SYSV semantics, but it allows to run +many programs which assume BSD semantics and which do not modify utmp. +Linux uses the BSD conventions for line contents, as documented above. +.PP +SYSV only uses the type field to mark them and logs informative messages +such as e.g.\& \fB"new time"\fP in the line field. \fBUT_UNKNOWN\fP seems +to be a Linux invention. +SYSV has no \fIut_host\fP or \fIut_addr_v6\fP fields. +.PP +Unlike various other +systems, where utmp logging can be disabled by removing the file, utmp +must always exist on Linux. If you want to disable \fIwho\fP(1) then +do not make utmp world readable. +.PP +Note that the utmp struct from libc5 has changed in libc6. Because of this, +binaries using the old libc5 struct will corrupt +.IR /var/run/utmp " and/or " /var/log/wtmp . +Debian systems include a patched libc5 which uses the new utmp format. +The problem still exists with wtmp since it's accessed directly in +libc5. +.SH RESTRICTIONS +The file format is machine dependent, so it is recommended that it be +processed only on the machine architecture where it was created. +.PP +Note that on platforms which can run both 32-bit and 64-bit applications +(x86-64, ppc64, s390x, etc.), the sizes of the fields of a struct utmp +must be the same in 32-bit mode as in 64-bit mode. +This is achieved by changing the type of +.I ut_session +to int32_t, and that of +.I ut_tv +to a struct with two int32_t fields +.I tv_sec +and +.IR tv_usec . +(Thus, in order to fill it, first get the time into a real struct timeval, +then copy the two fields to +.IR ut_tv .) +.SH BUGS +This manpage is based on the libc5 one, things may work differently now. +.SH "SEE ALSO" +.BR ac (1), +.BR date (1), +.BR last (1), +.BR login (1), +.BR who (1), +.BR getutent (3), +.BR updwtmp (3), +.BR init (8) diff --git a/man5/wtmp.5 b/man5/wtmp.5 new file mode 100644 index 000000000..1fa9e5a5d --- /dev/null +++ b/man5/wtmp.5 @@ -0,0 +1 @@ +.so man5/utmp.5 diff --git a/man6/intro.6 b/man6/intro.6 new file mode 100644 index 000000000..74e6a4b69 --- /dev/null +++ b/man6/intro.6 @@ -0,0 +1,32 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 17:19:57 1993 by Rik Faith (faith@cs.unc.edu) +.TH INTRO 6 1993-07-24 "Linux" "Linux Programmer's Manual" +.SH NAME +intro \- Introduction to games +.SH DESCRIPTION +This chapter describes all the games and funny little programs +available on the system. +.SH AUTHORS +Look at the header of the manual page for the author(s) and copyright +conditions. Note that these can be different from page to page! diff --git a/man7/LDP.7 b/man7/LDP.7 new file mode 100644 index 000000000..28f003408 --- /dev/null +++ b/man7/LDP.7 @@ -0,0 +1,92 @@ +.ig \"-*- nroff -*- +Copyright (C) 2000 Stein Gjoen + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be included in +translations approved by the Free Software Foundation instead of in +the original English. +.. +.TH "LDP Introduction" 7 2001-11-15 "LDP" +.SH NAME +LDP \- Intro to the Linux Documentation Project, with help, guides and documents +.SH SYNOPSIS +The Linux Documentation Project (LDP) provides a variety of +free documentation resources including +guides, FAQs, HOWTOs, and man-pages to the Linux community. + +.SH AUTHORS +The various documents in the LDP archives are maintained by individual +authors, and are listed in the beginning of each HOWTO. If you have +any questions or inputs to a document we encourage you to contact the +authors directly. + +.SH "WEB PAGES" +The LDP has its own dedicated web site as do many of +the various translations projects which are linked from the +main LDP web site at +.RS +\fBhttp://www\&.tldp\&.org/\fP +.RE +which you may wish to bookmark. + +.SH "MAN PAGES" +A web page with status information for manual pages and translations +is found at +.RS +\fBhttp://www\&.win\&.tue\&.nl/~aeb/linux/man/\fP +.RE + +.SH "MAILING LISTS" +LDP has a number of mailing lists, such as +.PP +.PD 0 +.TP +.PD +\fB\fP +Announcements from the LDP project +.TP +\fB\fP +General discussion on the LDP project +.TP +\fB\fP +Questions about the use of DocBook +.PP +For subscription information, see the website. +.PP +If you are interested in DocBook beyond the simple markup of your LDP +document, you may want to consider joining one of the OASIS DocBook +mailing lists. Please see +\fBhttp://docbook\&.org/mailinglist/index\&.html\fP +for more information. + +.SH FILES +Most distributions include the HOWTOs and mini-HOWTOs in the installation +.PD 0 +.TP +\fB/usr/doc/\fP (old place for documentation) +.TP +\fB/usr/share/doc/\fP (new place for documentation) +.TP +\fB/usr/share/doc/HOWTO/\fP (HOWTO files) +.TP +\fB/usr/share/doc/HOWTO/mini/\fP (mini-HOWTO files) +.PD +.SH "SEE ALSO" +.BR info (1), +.BR man (1), +.BR xman (1x) +.PP +\fBinfo\fP pages as read with +.BR emacs (1) +or +.BR info (1) diff --git a/man7/arp.7 b/man7/arp.7 new file mode 100644 index 000000000..253a9c11d --- /dev/null +++ b/man7/arp.7 @@ -0,0 +1,265 @@ +'\" t +.\" This man page is Copyright (C) 1999 Matthew Wilcox . +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" Modified June 1999 Andi Kleen +.\" $Id: arp.7,v 1.10 2000/04/27 19:31:38 ak Exp $ +.TH ARP 7 1999-06-03 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +arp \- Linux ARP kernel module. +.SH DESCRIPTION +This kernel protocol module implements the Address Resolution +Protocol defined in RFC 826. +It is used to convert between Layer2 hardware addresses +and IPv4 protocol addresses on directly connected networks. +The user normally doesn't interact directly with this module except to +configure it; +instead it provides a service for other protocols in the kernel. + +A user process can receive ARP packets by using +.BR packet (7) +sockets. There is also a mechanism for managing the ARP cache +in user-space by using +.BR netlink (7) +sockets. The ARP table can also be controlled via +.B ioctl (2) +on any +.B PF_INET +socket. + +The ARP module maintains a cache of mappings between hardware addresses +and protocol addresses. The cache has a limited size so old and less +frequently used entries are garbage-collected. Entries which are marked +as permanent are never deleted by the garbage-collector. The cache can +be directly manipulated by the use of ioctls and its behaviour can be +tuned by the sysctls defined below. + +When there is no positive feedback for an existing mapping after some +time (see the sysctls below) a neighbour cache entry is considered stale. +Positive feedback can be gotten from a higher layer; for example from +a successful TCP ACK. Other protocols can signal forward progress +using the +.B MSG_CONFIRM +flag to +.BR sendmsg (2). +When there is no forward progress ARP tries to reprobe. +It first tries to ask a local arp daemon +.B app_solicit +times for an updated MAC address. +If that fails and an old MAC address is known an unicast probe is send +.B ucast_solicit +times. If that fails too it will broadcast a new ARP +request to the network. Requests are only send when there is data queued +for sending. + +Linux will automatically add a non-permanent proxy arp entry when it receives +a request for an address it forwards to and proxy arp is enabled on the +receiving interface. When there is a reject route for the target +no proxy arp entry is added. + +.SH IOCTLS +Three ioctls are available on all +.B PF_INET +sockets. +They take a pointer to a +.B struct arpreq +as their parameter. + +.nf +.ta 4 20 33 +struct arpreq +{ + struct sockaddr arp_pa; /* protocol address */ + struct sockaddr arp_ha; /* hardware address */ + int arp_flags; /* flags */ + struct sockaddr arp_netmask; /* netmask of protocol address */ + char arp_dev[16]; +}; +.fi + +.BR SIOCSARP ", " SIOCDARP " and " SIOCGARP +respectively set, delete and get an ARP mapping. +Setting & deleting ARP maps are privileged operations and may +only be performed by a process with the +.B CAP_NET_ADMIN +capability or an effective UID of 0. + +.I arp_pa +must be an +.B AF_INET +socket and +.I arp_ha +must have the same type as the device which is specified in +.IR arp_dev . +.I arp_dev +is a zero-terminated string which names a device. + +.TS +tab(:) allbox; +c s +l l. +\fIarp_flags\fR +flag:meaning +ATF_COM:Lookup complete +ATF_PERM:Permanent entry +ATF_PUBL:Publish entry +ATF_USETRAILERS:Trailers requested +ATF_NETMASK:Use a netmask +ATF_DONTPUB:Don't answer +.TE + +.PP + +If the +.B ATF_NETMASK +flag is set, then +.I arp_netmask +should be valid. +Linux 2.2 does not support proxy network ARP entries, so this +should be set to 0xffffffff, or 0 to remove an existing proxy arp entry. +.B ATF_USETRAILERS +is obsolete and should not be used. + +.SH SYSCTLS +ARP supports a sysctl interface to configure parameters on a global +or per-interface basis. +The sysctls can be accessed by reading or writing the +.B /proc/sys/net/ipv4/neigh/*/* +files or with the +.BR sysctl (2) +interface. Each interface in the system has its own directory in +/proc/sys/net/ipv4/neigh/. +The setting in the `default' directory is used for all newly created devices. +Unless otherwise specified time related sysctls are specified in seconds. +.TP +.B anycast_delay +The maximum number of jiffies to delay before replying to a +IPv6 neighbour solicitation message. +Anycast support is not yet implemented. +Defaults to 1 second. +.TP +.B app_solicit +The maximum number of probes to send to the user space ARP daemon via +netlink before dropping back to multicast probes (see +.IR mcast_solicit ). +Defaults to 0. +.TP +.B base_reachable_time +Once a neighbour has been found, the entry is considered to be valid +for at least a random value between +.IR base_reachable_time "/2 and 3*" base_reachable_time /2. +An entry's validity will be extended if it receives positive feedback +from higher level protocols. +Defaults to 30 seconds. +.TP +.B delay_first_probe_time +Delay before first probe after it has been decided that a neighbour +is stale. +Defaults to 5 seconds. +.TP +.B gc_interval +How frequently the garbage collector for neighbour entries +should attempt to run. +Defaults to 30 seconds. +.TP +.B gc_stale_time +Determines how often to check for stale neighbour entries. When +a neighbour entry is considered stale it is resolved again before +sending data to it. +Defaults to 60 seconds. +.TP +.B gc_thresh1 +The minimum number of entries to keep in the ARP cache. +The garbage collector will not run if there are fewer than +this number of entries in the cache. +Defaults to 128. +.TP +.B gc_thresh2 +The soft maximum number of entries to keep in the ARP cache. +The garbage collector will allow the number of entries to exceed +this for 5 seconds before collection will be performed. +Defaults to 512. +.TP +.B gc_thresh3 +The hard maximum number of entries to keep in the ARP cache. +The garbage collector will always run if there are more than +this number of entries in the cache. +Defaults to 1024. +.TP +.B locktime +The minimum number of jiffies to keep an ARP entry in the cache. +This prevents ARP cache thrashing if there is more than one potential +mapping (generally due to network misconfiguration). +Defaults to 1 second. +.TP +.B mcast_solicit +The maximum number of attempts to resolve an address by multicast/broadcast +before marking the entry as unreachable. +Defaults to 3. +.TP +.B proxy_delay +When an ARP request for a known proxy-ARP address is received, delay up to +.I proxy_delay +jiffies before replying. +This is used to prevent network flooding in some cases. +Defaults to 0.8 seconds. +.TP +.B proxy_qlen +The maximum number of packets which may be queued to proxy-ARP addresses. +Defaults to 64. +.TP +.B retrans_time +The number of jiffies to delay before retransmitting a request. +Defaults to 1 second. +.TP +.B ucast_solicit +The maximum number of attempts to send unicast probes before asking +the ARP daemon (see +.IR app_solicit ). +Defaults to 3. +.TP +.B unres_qlen +The maximum number of packets which may be queued for each unresolved +address by other network layers. +Defaults to 3. + +.SH BUGS +Some timer settings are specified in jiffies, which is architecture related. +On the Alpha a jiffy is 1/1024 of a second, on most other architectures it +is 1/100s. + +There is no way to signal positive feedback from user space. This means +connection oriented protocols implemented in user space will generate +excessive ARP traffic, because ndisc will regularly reprobe the MAC address. +The same problem applies for some kernel protocols (e.g. NFS over UDP). + +This man page mashes IPv4 specific and shared between IPv4 and IPv6 +functionality together. + +.SH VERSIONS +The +.B struct arpreq +changed in Linux 2.0 to include the +.I arp_dev +member and the ioctl numbers changed at the same time. +Support for the old ioctls was dropped in Linux 2.2. + +Support for proxy arp entries for networks (netmask not equal 0xffffffff) +was dropped in Linux 2.2. It is replaced by automatic proxy arp setup by +the kernel for all reachable hosts on other interfaces (when forwarding and +proxy arp is enabled for the interface). + +The neigh/* sysctls did not exist before Linux 2.2. + +.SH "SEE ALSO" +.BR capabilities (7), +.BR ip (7) +.PP +RFC826 for a description of ARP. +.br +RFC2461 for a description of IPv6 neighbour discovery and the base +algorithms used. +.LP +Linux 2.2+ IPv4 ARP uses the IPv6 algorithms when applicable. diff --git a/man7/ascii.7 b/man7/ascii.7 new file mode 100644 index 000000000..e6f410867 --- /dev/null +++ b/man7/ascii.7 @@ -0,0 +1,183 @@ +'\" t +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de) +.\" Created Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 +.\" USA. +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1994-05-15 by Daniel Quinlan (quinlan@yggdrasil.com) +.\" Modified 1994-11-22 by Daniel Quinlan (quinlan@yggdrasil.com) +.\" Modified 1995-07-11 by Daniel Quinlan (quinlan@yggdrasil.com) +.\" Modified 1996-12-18 by Michael Haardt and aeb +.\" Modified 1999-05-31 by Dimitri Papadopoulos (dpo@club-internet.fr) +.\" Modified 1999-08-08 by Michael Haardt (michael@moria.de) +.\" Modified 2004-04-01 by aeb +.\" +.TH ASCII 7 2004-04-01 "Linux" "Linux Programmer's Manual" +.SH NAME +ascii \- the ASCII character set encoded in octal, decimal, and hexadecimal +.SH DESCRIPTION +ASCII is the American Standard Code for Information Interchange. +It is a 7-bit code. Many 8-bit codes (such as ISO 8859-1, the +Linux default character set) contain ASCII as their lower half. +The international counterpart of ASCII is known as ISO 646. +.LP +The following table contains the 128 ASCII characters. +.LP +C program \f(CW'\eX'\fP escapes are noted. +.LP +.if t \{\ +.in 1i +.ft CW +\} +.TS +l l l l l l l l l. +Oct Dec Hex Char Oct Dec Hex Char +_ +000 0 00 NUL '\e0' 100 64 40 @ +001 1 01 SOH 101 65 41 A +002 2 02 STX 102 66 42 B +003 3 03 ETX 103 67 43 C +004 4 04 EOT 104 68 44 D +005 5 05 ENQ 105 69 45 E +006 6 06 ACK 106 70 46 F +007 7 07 BEL '\ea' 107 71 47 G +010 8 08 BS '\eb' 110 72 48 H +011 9 09 HT '\et' 111 73 49 I +012 10 0A LF '\en' 112 74 4A J +013 11 0B VT '\ev' 113 75 4B K +014 12 0C FF '\ef' 114 76 4C L +015 13 0D CR '\er' 115 77 4D M +016 14 0E SO 116 78 4E N +017 15 0F SI 117 79 4F O +020 16 10 DLE 120 80 50 P +021 17 11 DC1 121 81 51 Q +022 18 12 DC2 122 82 52 R +023 19 13 DC3 123 83 53 S +024 20 14 DC4 124 84 54 T +025 21 15 NAK 125 85 55 U +026 22 16 SYN 126 86 56 V +027 23 17 ETB 127 87 57 W +030 24 18 CAN 130 88 58 X +031 25 19 EM 131 89 59 Y +032 26 1A SUB 132 90 5A Z +033 27 1B ESC 133 91 5B [ +034 28 1C FS 134 92 5C \e '\e\e' +035 29 1D GS 135 93 5D ] +036 30 1E RS 136 94 5E ^ +037 31 1F US 137 95 5F \&_ +040 32 20 SPACE 140 96 60 \` +041 33 21 ! 141 97 61 a +042 34 22 " 142 98 62 b +043 35 23 # 143 99 63 c +044 36 24 $ 144 100 64 d +045 37 25 % 145 101 65 e +046 38 26 & 146 102 66 f +047 39 27 ' 147 103 67 g +050 40 28 ( 150 104 68 h +051 41 29 ) 151 105 69 i +052 42 2A * 152 106 6A j +053 43 2B + 153 107 6B k +054 44 2C , 154 108 6C l +055 45 2D \- 155 109 6D m +056 46 2E . 156 110 6E n +057 47 2F / 157 111 6F o +060 48 30 0 160 112 70 p +061 49 31 1 161 113 71 q +062 50 32 2 162 114 72 r +063 51 33 3 163 115 73 s +064 52 34 4 164 116 74 t +065 53 35 5 165 117 75 u +066 54 36 6 166 118 76 v +067 55 37 7 167 119 77 w +070 56 38 8 170 120 78 x +071 57 39 9 171 121 79 y +072 58 3A : 172 122 7A z +073 59 3B ; 173 123 7B { +074 60 3C < 174 124 7C | +075 61 3D = 175 125 7D } +076 62 3E > 176 126 7E ~ +077 63 3F ? 177 127 7F DEL +.TE +.fi +.if t \{\ +.in +.ft P +\} +.SH HISTORY +An +.B ascii +manual page appeared in Version 7 of AT&T UNIX. +.LP +On older terminals, the underscore code is displayed as a left arrow, +called backarrow, the caret is displayed as an up-arrow and the vertical +bar has a hole in the middle. +.LP +Uppercase and lowercase characters differ by just one bit and the +ASCII character 2 differs from the double quote by just one bit, too. +That made it much easier to encode characters mechanically or with a +non-microcontroller-based electronic keyboard and that pairing was found +on old teletypes. +.LP +The ASCII standard was published by the United States of America +Standards Institute (USASI) in 1968. +.\" +.\" ASA was the American Standards Association and X3 was an ASA sectional +.\" committee on computers and data processing. Its name changed to +.\" American National Standards Committee X3 (ANSC-X3) and now it is known +.\" as Accredited Standards Committee X3 (ASC X3). It is accredited by ANSI +.\" and administered by ITI. The subcommittee X3.2 worked on coded +.\" character sets; the task group working on ASCII appears to have been +.\" designated X3.2.4. In 1966, ASA became the United States of America +.\" Standards Institute (USASI) and published ASCII in 1968. It became the +.\" American National Standards Institute (ANSI) in 1969 and is the +.\" U.S. member body of ISO; private and non-profit. +.\" +.SH "SEE ALSO" +.BR iso_8859-1 (7), +.BR iso_8859-15 (7), +.BR iso_8859-16 (7), +.BR iso_8859-2 (7), +.BR iso_8859-7 (7), +.BR iso_8859-9 (7) +.SH TABLES +For convenience, let us give more compact tables in hex and decimal. +.sp +.nf + 2 3 4 5 6 7 30 40 50 60 70 80 90 100 110 120 + ------------- --------------------------------- +0: 0 @ P ` p 0: ( 2 < F P Z d n x +1: ! 1 A Q a q 1: ) 3 = G Q [ e o y +2: " 2 B R b r 2: * 4 > H R \e f p z +3: # 3 C S c s 3: ! + 5 ? I S ] g q { +4: $ 4 D T d t 4: " , 6 @ J T ^ h r | +5: % 5 E U e u 5: # - 7 A K U _ i s } +6: & 6 F V f v 6: $ . 8 B L V ` j t ~ +7: ' 7 G W g w 7: % / 9 C M W a k u DEL +8: ( 8 H X h x 8: & 0 : D N X b l v +9: ) 9 I Y i y 9: ' 1 ; E O Y c m w +A: * : J Z j z +B: + ; K [ k { +C: , < L \e l | +D: - = M ] m } +E: . > N ^ n ~ +F: / ? O _ o DEL +.fi diff --git a/man7/boot.7 b/man7/boot.7 new file mode 100644 index 000000000..d1341ef7f --- /dev/null +++ b/man7/boot.7 @@ -0,0 +1,194 @@ +.\" Written by Oron Peled . +.\" May be distributed subject to the GPL. +.\" +.\" I tried to be as much generic in the description as possible: +.\" - General boot sequence is applicable to almost any +.\" OS/Machine (DOS/PC, Linux/PC, Solaris/SPARC, CMS/S390) +.\" - kernel and init(8) is applicable to almost any Unix/Linux +.\" - boot scripts are applicable to SYSV-R4 based Unix/Linux +.TH BOOT 7 2002-06-07 "" "Linux Programmer's Manual" +.SH "NAME" +.LP +boot\-scripts \- General description of boot sequence +.SH "DESCRIPTION" +.LP +The boot sequence varies in details among systems +but can be roughly divided to the following steps: +(i) hardware boot, (ii) OS loader, +(iii) kernel startup, (iv) init and inittab, +(v) boot scripts. +We will describe each of these in more detail below. + +.SS "Hardware\-boot" +After power\-on or hard reset, control is given +to a program stored on read only memory (normally +PROM). In PC we usually call this program the +\fBBIOS\fR. + +This program normally makes a basic self\-test of the +machine and accesses non\-volatile memory to read +further parameters. This memory in the PC is +battery\-backed CMOS memory, so most people +refer to it as the \fBCMOS\fR, although outside +of the PC world, it is usually called \fBnvram\fR +(non\-volatile ram). + +The parameters stored in the nvram vary between +systems, but as a minimum, the hardware boot program +should know what is the boot device, or which devices +to probe as possible boot devices. + +Then the hardware boot stage accesses the boot device, +loads the OS Loader, which is located on a fixed position +on the boot device, and transfers control to it. + +.TP +Note: +We do not cover here booting from network. Those who want +to investigate this subject may want to research: +DHCP, TFTP, PXE, Etherboot. + +.SS "OS Loader" +In PC, the OS Loader is located in the first sector +of the boot device \- this is the \fBMBR\fR +(Master Boot Record). + +In most systems, this primary loader is very +limited due to various constraints. Even on non\-PC systems +there are some limitations to the size and complexity +of this loader, but the size limitation of the PC MBR +(512 bytes including the partition table) makes it +almost impossible to squeeze a full OS Loader into it. + +Therefore, most operating systems make the primary loader +call a secondary OS loader which may be located on +a specified disk partition. + +In Linux the OS loader is normally +.BR lilo (8) +or +.BR grub (8). +Both of them may install either as secondary loaders +(where the DOS installed MBR points to them), or +as a two part loader where they provide special MBR +containing the bootstrap code to load the second part +of the loader from the root partition. + +The main job of the OS Loader is to locate the kernel +on the disk, load it and run it. Most OS loaders allow +interactive use, to enable specification of alternative +kernel (maybe a backup in case the last compiled one +isn't functioning) and to pass optional parameters +to the kernel. + +.SS "Kernel Startup" +When the kernel is loaded, it initializes the devices (via +their drivers), starts the swapper (it is a "kernel process", +called kswapd in modern Linux kernels), and mounts the root +file system (/). + +Some of the parameters that may be passed to the kernel +relate to these activities (e.g: You can override the +default root file system). For further information +on Linux kernel parameters read +.BR bootparam (7). + +Only then the kernel creates the first (user land) +process which is numbered 1. This process executes the +program +.IR /sbin/init , +passing any parameters that weren't handled by the kernel already. + +.SS "init and inittab" +When init starts it reads +.I /etc/inittab +for further instructions. +This file defines what should be run in different \fIrun-levels\fR. + +This gives the system administrator an easy management scheme, where +each run-level is associated with a set of services (e.g: +\fBS\fR is \fIsingle\-user\fR, on \fB2\fR most network +services start, etc.). The administrator may change the current +run-level via +.BR init (8) +and query the current run-level via +.BR runlevel (8). + +However, since it is not convenient to manage individual services +by editing this file, inittab only bootstraps a set of scripts +that actually start/stop the individual services. + +.SS "Boot Scripts" + +.TP +Note: +The following description applies to SYSV\-R4 based system, which +currently covers most commercial Unices (Solaris, HPUX, Irix, Tru64) +as well as the major Linux distributions (RedHat, Debian, Mandrake, +Suse, Caldera). Some systems (Slackware Linux, FreeBSD, OpenBSD) +have a somewhat different scheme of boot scripts. +.LP + +For each managed service (mail, nfs server, cron, etc.) there is +a single startup script located in a specific directory +.RI ( /etc/init.d +in most versions of Linux). +Each of these scripts accepts as a single argument +the word 'start' \-\- causing it to start the service, or the word +'stop' \-\- causing it to stop the service. The script may optionally +accept other "convenience" parameters (e.g: 'restart', to stop and then +start, 'status' do display the service status). Running the script +without parameters displays the possible arguments. + +.SS "Sequencing Directories" +To make specific scripts start/stop at specific run-levels and in +specific order, there are \fIsequencing directories\fR. These +are normally in \fB/etc/rc[0\-6S].d\fR. In each of these directories +there are links (usually symbolic) to the scripts in the \fIinit.d\fR +directory. + +A primary script (usually \fI/etc/rc\fR) is called from inittab(5) +and calls the services scripts via the links in the sequencing directories. +All links with names that begin with 'S' are being called with +the argument 'start' (thereby starting the service). All links with +names that begin with 'K' are being called with the argument 'stop' +(thereby stopping the service). + +To define the starting or stopping order within the same run-level, +the names of the links contain order-numbers. +Also, to make the names clearer, they usually +end with the name of the service they refer to. Example: +the link \fI/etc/rc2.d/S80sendmail\fR starts the sendmail service on +runlevel 2. This happens after \fI/etc/rc2.d/S12syslog\fR is run +but before \fI/etc/rc2.d/S90xfs\fR is run. + +To manage the boot order and run-levels, we have to manage these links. +However, on many versions of Linux, there are tools to help with this task +(e.g: +.BR chkconfig (8)). + +.SS "Boot Configuration" +Usually the daemons started may optionally receive command line options +and parameters. To allow system administrators to change these +parameters without editing the boot scripts themselves, +configuration files are used. These are located in a specific +directory (\fI/etc/sysconfig\fR on RedHat systems) and are +used by the boot scripts. + +In older Unices, these files contained the actual command line +options for the daemons, but in modern Linux systems (and also +in HPUX), these files just contain shell variables. The boot +scripts in \fI/etc/init.d\fR \fBsource\fR the configuration +files, and then use the variable values. +.SH "FILES" +.LP +.IR /etc/init.d/ , +.IR /etc/rc[S0\-6].d/ . +.I /etc/sysconfig/ + +.SH "SEE ALSO" +.BR inittab (5), +.BR bootparam (7), +.BR init (8), +.BR runlevel (8), +.BR shutdown (8) diff --git a/man7/bootparam.7 b/man7/bootparam.7 new file mode 100644 index 000000000..e196ebb56 --- /dev/null +++ b/man7/bootparam.7 @@ -0,0 +1,1234 @@ +.\" Copyright (c) 1995,1997 Paul Gortmaker and Andries Brouwer +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" This man page written 950814 by aeb, based on Paul Gortmaker's HOWTO +.\" (dated v1.0.1, 15/08/95). +.\" Major update, aeb, 970114. +.\" +.TH BOOTPARAM 7 1995-01-14 "Linux 2.1.21" "Linux Programmer's Manual" +.SH NAME +bootparam \- Introduction to boot time parameters of the Linux kernel +.SH DESCRIPTION +The Linux kernel accepts certain `command line options' or `boot time +parameters' at the moment it is started. In general this is used to +supply the kernel with information about hardware parameters that +the kernel would not be able to determine on its own, or to avoid/override +the values that the kernel would otherwise detect. + +When the kernel is booted directly by the BIOS (say from a floppy to +which you copied a kernel using `cp zImage /dev/fd0'), +you have no opportunity to specify any parameters. +So, in order to take advantage of this possibility you have to +use software that is able to pass parameters, like LILO or loadlin. +For a few parameters one can also modify the kernel image itself, +using rdev, see +.BR rdev (8) +for further details. + +The LILO program (LInux LOader) written by Werner Almesberger is the +most commonly used. It has the ability to boot various kernels, and +stores the configuration information in a plain text file. (See +.BR lilo (8) +and +.BR lilo.conf (5).) +LILO can boot DOS, OS/2, Linux, FreeBSD, UnixWare, etc., and is quite flexible. + +The other commonly used Linux loader is `LoadLin' which is a DOS +program that has the capability to launch a Linux kernel from the DOS +prompt (with boot-args) assuming that certain resources are available. +This is good for people that want to launch Linux from DOS. + +It is also very useful if you have certain hardware which relies on +the supplied DOS driver to put the hardware into a known state. A +common example is `SoundBlaster Compatible' sound cards that require +the DOS driver to twiddle a few mystical registers to put the card +into a SB compatible mode. Booting DOS with the supplied driver, and +then loading Linux from the DOS prompt with loadlin avoids the reset +of the card that happens if one rebooted instead. + +.SH "THE ARGUMENT LIST" + +The kernel command line is parsed into a list of strings +(boot arguments) separated by spaces. Most of the boot args +take the form of: +.IP +name[=value_1][,value_2]...[,value_10] +.LP +where `name' is a unique keyword that is used to identify what part of +the kernel the associated values (if any) are to be given to. +Note the limit of 10 is real, as the present code only handles 10 comma +separated parameters per keyword. (However, you can re-use the same +keyword with up to an additional 10 parameters in unusually +complicated situations, assuming the setup function supports it.) + +Most of the sorting goes on in linux/init/main.c. First, the kernel +checks to see if the argument is any of the special arguments `root=', +`nfsroot=', `nfsaddrs=', `ro', `rw', `debug' or `init'. The meaning +of these special arguments is described below. + +Then it walks a list of setup functions (contained in the bootsetups +array) to see if the specified argument string (such as `foo') has +been associated with a setup function (`foo_setup()') for a particular +device or part of the kernel. If you passed the kernel the line +foo=3,4,5,6 then the kernel would search the bootsetups array to see +if `foo' was registered. If it was, then it would call the setup +function associated with `foo' (foo_setup()) and hand it the arguments +3, 4, 5 and 6 as given on the kernel command line. + +Anything of the form `foo=bar' that is not accepted as a setup function +as described above is then interpreted as an environment variable to +be set. A (useless?) example would be to use `TERM=vt100' as a boot +argument. + +Any remaining arguments that were not picked up by the kernel and were +not interpreted as environment variables are then passed onto process +one, which is usually the init program. The most common argument that +is passed to the init process is the word `single' which instructs init +to boot the computer in single user mode, and not launch all the usual +daemons. Check the manual page for the version of init installed on +your system to see what arguments it accepts. + +.SH "GENERAL NON-DEVICE SPECIFIC BOOT ARGS" + +.SS "`init=...'" + +This sets the initial command to be executed by the kernel. +If this is not set, or cannot be found, the kernel will try +.IR /etc/init , +then +.IR /bin/init , +then +.IR /sbin/init , +then +.IR /bin/sh +and panic if all of this fails. + +.SS "`nfsaddrs=...'" + +This sets the nfs boot address to the given string. +This boot address is used in case of a net boot. + +.SS "`nfsroot=...'" + +This sets the nfs root name to the given string. If this string +does not begin with '/' or ',' or a digit, then it is prefixed by +`/tftpboot/'. This root name is used in case of a net boot. + +.SS "`no387'" + +(Only when CONFIG_BUGi386 is defined.) +Some i387 coprocessor chips have bugs that show up when used in 32 bit +protected mode. For example, some of the early ULSI-387 chips would +cause solid lockups while performing floating point calculations. +Using the `no387' boot arg causes Linux to ignore the maths +coprocessor even if you have one. Of course you must then have your +kernel compiled with math emulation support! + +.SS "`no-hlt'" + +(Only when CONFIG_BUGi386 is defined.) +Some of the early i486DX-100 chips have a problem with the `hlt' +instruction, in that they can't reliably return to operating mode +after this instruction is used. Using the `no-hlt' instruction tells +Linux to just run an infinite loop when there is nothing else to do, +and to not halt the CPU. This allows people with these broken chips +to use Linux. + +.SS "`root=...'" + +This argument tells the kernel what device is to be used as the root +filesystem while booting. The default of this setting is determined +at compile time, and usually is the value of the root device of the +system that the kernel was built on. To override this value, and +select the second floppy drive as the root device, one would +use `root=/dev/fd1'. (The root device can also be set using +.BR rdev (8).) + +The root device can be specified symbolically or numerically. +A symbolic specification has the form /dev/XXYN, where XX designates +the device type (`hd' for ST-506 compatible hard disk, with Y in +`a'-`d'; `sd' for SCSI compatible disk, with Y in `a'-`e'; +`ad' for Atari ACSI disk, with Y in `a'-`e', +`ez' for a Syquest EZ135 parallel port removable drive, with Y=`a', +`xd' for XT compatible disk, with Y either `a' or `b'; `fd' for +floppy disk, with Y the floppy drive number - fd0 would be +the DOS `A:' drive, and fd1 would be `B:'), Y the driver letter or +number, and N the number (in decimal) of the partition on this device +(absent in the case of floppies). Recent kernels allow many other +types, mostly for CD-ROMs: nfs, ram, scd, mcd, cdu535, aztcd, cm206cd, +gscd, sbpcd, sonycd, bpcd. +(The type nfs specifies a net boot; ram refers to a ram disk.) + +Note that this has nothing to do with the designation of these +devices on your file system. The `/dev/' part is purely conventional. + +The more awkward and less portable numeric specification of the above +possible root devices in major/minor format is also accepted. (E.g., +/dev/sda3 is major 8, minor 3, so you could use `root=0x803' as an +alternative.) + +.SS "`ro' and `rw'" + +The `ro' option tells the kernel to mount the root filesystem +as `readonly' so that filesystem consistency check programs (fsck) +can do their work on a quiescent file system. No processes can +write to files on the filesystem in question until it is `remounted' +as read/write capable, e.g., by `mount -w -n -o remount /'. +(See also +.BR mount (8).) + +The `rw' option tells the kernel to mount the root filesystem read/write. +This is the default. + +The choice between read-only and read/write can also be set using +.BR rdev (8). + +.SS "`reserve=...'" + +This is used to protect I/O port regions from probes. The form of the +command is: +.IP +.BI reserve= iobase,extent[,iobase,extent]... +.LP +In some machines it may be necessary to prevent device drivers from +checking for devices (auto-probing) in a specific region. This may be +because of hardware that reacts badly to the probing, or hardware +that would be mistakenly identified, or merely +hardware you don't want the kernel to initialize. + +The reserve boot-time argument specifies an I/O port region that +shouldn't be probed. A device driver will not probe a reserved region, +unless another boot argument explicitly specifies that it do so. + +For example, the boot line +.IP +reserve=0x300,32 blah=0x300 +.LP +keeps all device drivers except the driver for `blah' from probing +0x300-0x31f. + +.SS "`mem=...'" + +The BIOS call defined in the PC specification that returns +the amount of installed memory was only designed to be able +to report up to 64MB. Linux uses this BIOS call at boot to +determine how much memory is installed. If you have more than 64MB of +RAM installed, you can use this boot arg to tell Linux how much memory +you have. The value is in decimal or hexadecimal (prefix 0x), +and the suffixes `k' (times 1024) or `M' (times 1048576) can be used. +Here is a quote from Linus on usage of the `mem=' parameter. + +\&``The kernel will accept any `mem=xx' parameter you give it, and if it +turns out that you lied to it, it will crash horribly sooner or later. +The parameter indicates the highest addressable RAM address, so +\&`mem=0x1000000' means you have 16MB of memory, for example. For a +96MB machine this would be `mem=0x6000000'. + +NOTE NOTE NOTE: some machines might use the top of memory for BIOS +cacheing or whatever, so you might not actually have up to the full +96MB addressable. The reverse is also true: some chipsets will map +the physical memory that is covered by the BIOS area into the area +just past the top of memory, so the top-of-mem might actually be 96MB ++ 384kB for example. If you tell linux that it has more memory than +it actually does have, bad things will happen: maybe not at once, but +surely eventually.'' + +.SS "`panic=N'" +By default the kernel will not reboot after a panic, but this option +will cause a kernel reboot after N seconds (if N > 0). +This panic timeout can also be set by "echo N > /proc/sys/kernel/panic". + +.SS "`reboot=[warm|cold][,[bios|hard]]'" +(Only when CONFIG_BUGi386 is defined.) +Since 2.0.22 a reboot is by default a cold reboot. +One asks for the old default with `reboot=warm'. +(A cold reboot may be required to reset certain hardware, +but might destroy not yet written data in a disk cache. +A warm reboot may be faster.) +By default a reboot is hard, by asking the keyboard controller +to pulse the reset line low, but there is at least one type +of motherboard where that doesn't work. The option `reboot=bios' will +instead jump through the BIOS. + +.SS "`nosmp'" and "`maxcpus=N'" +(Only when __SMP__ is defined.) +A command-line option of `nosmp' or `maxcpus=0' will disable SMP +activation entirely; an option `maxcpus=N' limits the maximum number +of CPUs activated in SMP mode to N. + + +.SH "BOOT ARGUMENTS FOR USE BY KERNEL DEVELOPERS" + +.SS "`debug'" + +Kernel messages are handed off to the kernel log daemon klogd so that they +may be logged to disk. Messages with a priority above +.I console_loglevel +are also printed on the console. (For these levels, see .) +By default this variable is set to log anything more important than +debug messages. This boot argument will cause the kernel to also +print the messages of DEBUG priority. +The console loglevel can also be set at run time via an option +to klogd. See +.BR klogd (8). + +.SS "`profile=N'" + +It is possible to enable a kernel profiling function, +if one wishes to find out where the kernel is spending its CPU cycles. +Profiling is enabled by setting the variable +.I prof_shift +to a nonzero value. This is done either by specifying CONFIG_PROFILE at +compile time, or by giving the `profile=' option. +Now the value that +.I prof_shift +gets will be N, when given, or CONFIG_PROFILE_SHIFT, when that is given, +or 2, the default. The significance of this variable is that it +gives the granularity of the profiling: each clock tick, if the +system was executing kernel code, a counter is incremented: +.IP +profile[address >> prof_shift]++; +.LP +The raw profiling information can be read from +.IR /proc/profile . +Probably you'll want to use a tool such as readprofile.c to digest it. +Writing to +.I /proc/profile +will clear the counters. + +.SS "`swap=N1,N2,N3,N4,N5,N6,N7,N8'" +Set the eight parameters max_page_age, page_advance, page_decline, +page_initial_age, age_cluster_fract, age_cluster_min, pageout_weight, +bufferout_weight that control the kernel swap algorithm. +For kernel tuners only. + +.SS "`buff=N1,N2,N3,N4,N5,N6'" +Set the six parameters max_buff_age, buff_advance, buff_decline, +buff_initial_age, bufferout_weight, buffermem_grace that control +kernel buffer memory management. For kernel tuners only. + + + +.SH "BOOT ARGUMENTS FOR RAMDISK USE" +(Only if the kernel was compiled with CONFIG_BLK_DEV_RAM.) +In general it is a bad idea to use a ramdisk under Linux - +the system will use available memory more efficiently itself. +But while booting (or while constructing boot floppies) +it is often useful to load the floppy contents into a +ramdisk. One might also have a system in which first +some modules (for filesystem or hardware) must be loaded +before the main disk can be accessed. + +In Linux 1.3.48, ramdisk handling was changed drastically. +Earlier, the memory was allocated statically, and there was +a `ramdisk=N' parameter to tell its size. (This could also +be set in the kernel image at compile time, or by use of +.BR rdev (8).) +These days ram disks use the buffer cache, and grow dynamically. +For a lot of information (e.g., how to use +.BR rdev (8) +in conjunction with the new ramdisk setup), see +.IR /usr/src/linux/Documentation/ramdisk.txt . + +There are four parameters, two boolean and two integral. + +.SS "`load_ramdisk=N'" +If N=1, do load a ramdisk. If N=0, do not load a ramdisk. +(This is the default.) + +.SS "`prompt_ramdisk=N'" +If N=1, do prompt for insertion of the floppy. (This is the default.) +If N=0, do not prompt. (Thus, this parameter is never needed.) + +.SS "`ramdisk_size=N' or (obsolete) `ramdisk=N' +Set the maximal size of the ramdisk(s) to N kB. The default is 4096 (4 MB). + +.SS "`ramdisk_start=N'" +Sets the starting block number (the offset on the floppy where +the ramdisk starts) to N. +This is needed in case the ramdisk follows a kernel image. + +.SS "`noinitrd'" +(Only if the kernel was compiled with CONFIG_BLK_DEV_RAM +and CONFIG_BLK_DEV_INITRD.) +These days it is possible to compile the kernel to use initrd. +When this feature is enabled, the boot process will load the kernel +and an initial ramdisk; then the kernel converts initrd into +a "normal" ramdisk, which is mounted read-write as root device; +then /linuxrc is executed; afterwards the "real" root file system is mounted, +and the initrd filesystem is moved over to /initrd; finally +the usual boot sequence (e.g. invocation of /sbin/init) is performed. + +For a detailed description of the initrd feature, see +.IR /usr/src/linux/Documentation/initrd.txt . + +The `noinitrd' option tells the kernel that although it was compiled for +operation with initrd, it should not go through the above steps, but +leave the initrd data under +.IR /dev/initrd . +(This device can be used only once - the data is freed as soon as +the last process that used it has closed +.IR /dev/initrd .) + + +.SH "BOOT ARGUMENTS FOR SCSI DEVICES" + +General notation for this section: + +.I iobase +-- the first I/O port that the SCSI host occupies. These are +specified in hexidecimal notation, and usually lie in the range from +0x200 to 0x3ff. + +.I irq +-- the hardware interrupt that the card is configured to use. +Valid values will be dependent on the card in question, but will +usually be 5, 7, 9, 10, 11, 12, and 15. The other values are usually +used for common peripherals like IDE hard disks, floppies, serial +ports, etc. + +.I scsi-id +-- the ID that the host adapter uses to identify itself on the +SCSI bus. Only some host adapters allow you to change this value, as +most have it permanently specified internally. The usual default value +is 7, but the Seagate and Future Domain TMC-950 boards use 6. + +.I parity +-- whether the SCSI host adapter expects the attached devices +to supply a parity value with all information exchanges. Specifying a +one indicates parity checking is enabled, and a zero disables parity +checking. Again, not all adapters will support selection of parity +behaviour as a boot argument. + +.SS "`max_scsi_luns=...'" + +A SCSI device can have a number of `sub-devices' contained within +itself. The most common example is one of the new SCSI CD-ROMs that +handle more than one disk at a time. Each CD is addressed as a +`Logical Unit Number' (LUN) of that particular device. But most +devices, such as hard disks, tape drives and such are only one device, +and will be assigned to LUN zero. + +Some poorly designed SCSI devices cannot handle being probed for +LUNs not equal to zero. Therefore, if the compile time flag +CONFIG_SCSI_MULTI_LUN is not set, newer kernels will by default +only probe LUN zero. + +To specify the number of probed LUNs at boot, one enters +`max_scsi_luns=n' as a boot arg, where n is a number between one and +eight. To avoid problems as described above, one would use n=1 to +avoid upsetting such broken devices. + +.SS "SCSI tape configuration" + +Some boot time configuration of the SCSI tape driver can be achieved +by using the following: +.IP +.BI st= buf_size[,write_threshold[,max_bufs]] +.LP +The first two numbers are specified in units of kB. The default +.I buf_size +is 32kB, and the maximum size that can be specified is a +ridiculous 16384kB. The +.I write_threshold +is the value at which the buffer is committed to tape, with a +default value of 30kB. The maximum number of buffers varies +with the number of drives detected, and has a default of two. +An example usage would be: +.IP +st=32,30,2 +.LP +Full details can be found in the README.st file that is in the scsi +directory of the kernel source tree. + +.SS "Adaptec aha151x, aha152x, aic6260, aic6360, SB16-SCSI configuration" + +The aha numbers refer to cards and the aic numbers refer to the actual +SCSI chip on these type of cards, including the Soundblaster-16 SCSI. + +The probe code for these SCSI hosts looks for an installed BIOS, and +if none is present, the probe will not find your card. Then you will +have to use a boot arg of the form: +.IP +.BI aha152x= iobase[,irq[,scsi-id[,reconnect[,parity]]]] +.LP +If the driver was compiled with debugging enabled, a sixth +value can be specified to set the debug level. + +All the parameters are as described at the top of this section, and the +.I reconnect +value will allow device disconnect/reconnect if a non-zero value +is used. An example usage is as follows: +.IP +aha152x=0x340,11,7,1 +.LP +Note that the parameters must be specified in order, meaning that if +you want to specify a parity setting, then you will have to specify an +iobase, irq, scsi-id and reconnect value as well. + +.SS "Adaptec aha154x configuration" + +The aha1542 series cards have an i82077 floppy controller onboard, +while the aha1540 series cards do not. These are busmastering cards, +and have parameters to set the ``fairness'' that is used to share +the bus with other devices. The boot arg looks like the following. +.IP +.BI aha1542= iobase[,buson,busoff[,dmaspeed]] +.LP +Valid iobase values are usually one of: 0x130, 0x134, 0x230, 0x234, +0x330, 0x334. Clone cards may permit other values. + +The +.IR buson ", " busoff +values refer to the number of microseconds that the +card dominates the ISA bus. The defaults are 11us on, and 4us off, so +that other cards (such as an ISA LANCE Ethernet card) have a chance to +get access to the ISA bus. + +The +.I dmaspeed +value refers to the rate (in MB/s) at which the DMA +(Direct Memory Access) transfers proceed. The default is 5MB/s. +Newer revision cards allow you to select this value as part of the +soft-configuration, older cards use jumpers. You can use values up to +10MB/s assuming that your motherboard is capable of handling it. +Experiment with caution if using values over 5MB/s. + +.SS "Adaptec aha274x, aha284x, aic7xxx configuration" + +These boards can accept an argument of the form: +.IP +.BI aic7xxx= extended,no_reset +.LP +The +.I extended +value, if non-zero, indicates that extended translation for large +disks is enabled. The +.I no_reset +value, if non-zero, tells the driver not to reset the SCSI bus when +setting up the host adaptor at boot. + +.SS "AdvanSys SCSI Hosts configuration (`advansys=')" + +The AdvanSys driver can accept up to four i/o addresses that will be +probed for an AdvanSys SCSI card. Note that these values (if used) do +not effect EISA or PCI probing in any way. They are only used for +probing ISA and VLB cards. In addition, if the driver has been +compiled with debugging enabled, the level of debugging output can be +set by adding an 0xdeb[0-f] parameter. The 0-f allows setting the +level of the debugging messages to any of 16 levels of verbosity. + +.SS "AM53C974" +.IP +.BI AM53C974= host-scsi-id,target-scsi-id,max-rate,max-offset +.LP + +.SS "BusLogic SCSI Hosts configuration (`BusLogic=')" +.IP +.BI BusLogic= N1,N2,N3,N4,N5,S1,S2,... +.LP +For an extensive discussion of the BusLogic command line parameters, +see +.IR /usr/src/linux/drivers/scsi/BusLogic.c +(lines 3149-3270 in the kernel version I am looking at). The text +below is a very much abbreviated extract. + +The parameters N1-N5 are integers. The parameters S1,... are strings. +N1 is the I/O Address at which the Host Adapter is located. +N2 is the Tagged Queue Depth to use for Target Devices that support +Tagged Queuing. +N3 is the Bus Settle Time in seconds. This is the amount of time +to wait between a Host Adapter Hard Reset which +initiates a SCSI Bus Reset and issuing any SCSI Commands. +N4 is the Local Options (for one Host Adapter). +N5 is the Global Options (for all Host Adapters). + +The string options are used to provide control over Tagged Queuing +(TQ:Default, TQ:Enable, TQ:Disable, TQ:), over +Error Recovery (ER:Default, ER:HardReset, ER:BusDeviceReset, +ER:None, ER:), and over Host Adapter Probing +(NoProbe, NoProbeISA, NoSortPCI). + +.SS "EATA/DMA configuration" +The default list of i/o ports to be probed can be changed by +.IP +.BI eata= iobase,iobase,... . +.LP + +.SS "Future Domain TMC-16x0 configuration" +.IP +.BI fdomain= iobase,irq[,adapter_id] +.LP + +.SS "Great Valley Products (GVP) SCSI controller configuration" +.IP +.BI gvp11= dma_transfer_bitmask +.LP + +.SS "Future Domain TMC-8xx, TMC-950 configuration" +.IP +.BI tmc8xx= mem_base,irq +.LP +The +.I mem_base +value is the value of the memory mapped I/O region that +the card uses. This will usually be one of the following values: +0xc8000, 0xca000, 0xcc000, 0xce000, 0xdc000, 0xde000. + +.SS "IN2000 configuration" +.IP +.BI in2000= S +.LP +where S is a comma-separated string of items keyword[:value]. +Recognized keywords (possibly with value) are: +ioport:addr, noreset, nosync:x, period:ns, disconnect:x, +debug:x, proc:x. For the function of these parameters, see +.IR /usr/src/linux/drivers/scsi/in2000.c . + +.SS "NCR5380 and NCR53C400 configuration" +The boot arg is of the form +.IP +.BI ncr5380= iobase,irq,dma +.LP +or +.IP +.BI ncr53c400= iobase,irq +.LP +If the card doesn't use interrupts, then an IRQ value of 255 (0xff) will +disable interrupts. An IRQ value of 254 means to autoprobe. More +details can be found in the file +.IR /usr/src/linux/drivers/scsi/README.g_NCR5380 . + +.SS "NCR53C8xx configuration" +.IP +.BI ncr53c8xx= S +.LP +where S is a comma-separated string of items keyword:value. +Recognized keywords are: mpar (master_parity), spar (scsi_parity), +disc (disconnection), specf (special_features), ultra (ultra_scsi), +fsn (force_sync_nego), tags (default_tags), sync (default_sync), +verb (verbose), debug (debug), burst (burst_max). +For the function of the assigned values, see +.IR /usr/src/linux/drivers/scsi/ncr53c8xx.c . + +.SS "NCR53c406a configuration" +.IP +.BI ncr53c406a= iobase[,irq[,fastpio]] +.LP +Specify irq = 0 for non-interrupt driven mode. +Set fastpio = 1 for fast pio mode, 0 for slow mode. + +.SS "Pro Audio Spectrum configuration" + +The PAS16 uses a NC5380 SCSI chip, and newer models support +jumperless configuration. The boot arg is of the form: +.IP +.BI pas16= iobase,irq +.LP +The only difference is that you can specify an IRQ value of 255, which +will tell the driver to work without using interrupts, albeit at a +performance loss. The iobase is usually 0x388. + +.SS "Seagate ST-0x configuration" + +If your card is not detected at boot time, +you will then have to use a boot arg of the form: +.IP +.BI st0x= mem_base,irq +.LP +The +.I mem_base +value is the value of the memory mapped I/O region that +the card uses. This will usually be one of the following values: +0xc8000, 0xca000, 0xcc000, 0xce000, 0xdc000, 0xde000. + +.SS "Trantor T128 configuration" + +These cards are also based on the NCR5380 chip, and accept the +following options: +.IP +.BI t128= mem_base,irq +.LP +The valid values for +.I mem_base +are as follows: 0xcc000, 0xc8000, 0xdc000, 0xd8000. + +.SS "UltraStor 14F/34F configuration" +The default list of i/o ports to be probed can be changed by +.IP +.BI eata= iobase,iobase,... . +.LP + +.SS "WD7000 configuration" +.IP +.BI wd7000= irq,dma,iobase +.LP + +.SS "Commodore Amiga A2091/590 SCSI controller configuration" +.IP +.BI wd33c93= S +.LP +where S is a comma-separated string of options. Recognized options are +nosync:bitmask, nodma:x, period:ns, disconnect:x, debug:x, +clock:x, next. For details, see +.IR /usr/src/linux/drivers/scsi/wd33c93.c . + +.SH "HARD DISKS" + +.SS "IDE Disk/CD-ROM Driver Parameters" + +The IDE driver accepts a number of parameters, which range from disk +geometry specifications, to support for broken controller chips. Drive +specific options are specified by using `hdX=' with X in `a'-`h'. + +Non-drive specific options are specified with the prefix `hd='. Note +that using a drive specific prefix for a non-drive specific option +will still work, and the option will just be applied as expected. + +Also note that `hd=' can be used to refer to the next unspecified +drive in the (a, ..., h) sequence. For the following discussions, +the `hd=' option will be cited for brevity. See the file +README.ide in linux/drivers/block for more details. + +.SS "The `hd=cyls,heads,sects[,wpcom[,irq]]' options" + +These options are used to specify the physical geometry of the disk. +Only the first three values are required. The cylinder/head/sectors +values will be those used by fdisk. The write precompensation value +is ignored for IDE disks. The IRQ value specified will be the IRQ +used for the interface that the drive resides on, and is not really a +drive specific parameter. + +.SS "The `hd=serialize' option" + +The dual IDE interface CMD-640 chip is broken as designed such that +when drives on the secondary interface are used at the same time as +drives on the primary interface, it will corrupt your data. Using this +option tells the driver to make sure that both interfaces are never +used at the same time. + +.SS "The `hd=dtc2278' option" + +This option tells the driver that you have a DTC-2278D IDE interface. +The driver then tries to do DTC specific operations to enable the +second interface and to enable faster transfer modes. + +.SS "The `hd=noprobe' option" + +Do not probe for this drive. For example, +.IP +hdb=noprobe hdb=1166,7,17 +.LP +would disable the probe, but still specify the drive geometry so +that it would be registered as a valid block device, and hence +usable. + +.SS "The `hd=nowerr' option" + +Some drives apparently have the WRERR_STAT bit stuck on permanently. +This enables a work-around for these broken devices. + +.SS "The `hd=cdrom' option" + +This tells the IDE driver that there is an ATAPI compatible CD-ROM +attached in place of a normal IDE hard disk. In most cases the CD-ROM +is identified automatically, but if it isn't then this may help. + +.SS "Standard ST-506 Disk Driver Options (`hd=')" + +The standard disk driver can accept geometry arguments for the disks +similar to the IDE driver. Note however that it only expects three +values (C/H/S) -- any more or any less and it will silently ignore +you. Also, it only accepts `hd=' as an argument, i.e. `hda=' +and so on are not valid here. The format is as follows: +.IP +hd=cyls,heads,sects +.LP +If there are two disks installed, the above is repeated with the +geometry parameters of the second disk. + +.SS "XT Disk Driver Options (`xd=')" + +If you are unfortunate enough to be using one of these old 8 bit cards +that move data at a whopping 125kB/s then here is the scoop. +If the card is not recognised, you will have to use a boot arg of the form: +.IP +xd=type,irq,iobase,dma_chan +.LP +The type value specifies the particular manufacturer of the card, +overriding autodetection. For the types to use, consult the +.I drivers/block/xd.c +source file of the kernel you are using. The type is an index in the list +.I xd_sigs +and in the course of time +.\" 1.1.50, 1.3.81, 1.3.99, 2.0.34, 2.1.67, 2.1.78, 2.1.127 +types have been added to or deleted from the middle of the list, +changing all type numbers. Today (Linux 2.5.0) the types are +0=generic; 1=DTC 5150cx; 2,3=DTC 5150x; 4,5=Western Digital; +6,7,8=Seagate; 9=Omti; 10=XEBEC, and where here several types are +given with the same designation, they are equivalent. + +The xd_setup() function does no checking on the values, and assumes +that you entered all four values. Don't disappoint it. Here is an +example usage for a WD1002 controller with the BIOS disabled/removed, +using the `default' XT controller parameters: +.IP +xd=2,5,0x320,3 +.LP + +.SS "Syquest's EZ* removable disks" +.IP +.BI ez= iobase[,irq[,rep[,nybble]]] +.LP + +.SH "IBM MCA BUS DEVICES" +See also +.IR /usr/src/linux/Documentation/mca.txt . + +.SS "PS/2 ESDI hard disks" +It is possible to specify the desired geometry at boot time: +.IP +.BI ed= cyls,heads,sectors. +.LP +For a ThinkPad-720, add the option +.IP +.BR tp720=1 . +.LP + +.SS "IBM Microchannel SCSI Subsystem configuration" +.IP +.BI ibmmcascsi= N +.LP +where N is the \fIpun\fP (SCSI ID) of the subsystem. + +.SH "CD-ROMs (Non-SCSI/ATAPI/IDE)" + +.SS "The Aztech Interface" + +The syntax for this type of card is: +.IP +aztcd=iobase[,magic_number] +.LP +If you set the magic_number to 0x79 then the driver will try and run +anyway in the event of an unknown firmware version. All other values +are ignored. + +.SS "Parallel port CD-ROM drives" +Syntax: +.IP +pcd.driveN=prt,pro,uni,mod,slv,dly +.br +pcd.nice=nice +.LP +where `port' is the base address, `pro' is the protocol number, `uni' +is the unit selector (for chained devices), `mod' is the mode (or -1 +to choose the best automatically), `slv' is 1 if it should be a slave, +and `dly' is a small integer for slowing down port accesses. The +`nice' parameter controls the driver's use of idle CPU time, at the +expense of some speed. + +.SS "The CDU-31A and CDU-33A Sony Interface" + +This CD-ROM interface is found on some of the Pro Audio Spectrum sound +cards, and other Sony supplied interface cards. The syntax is as +follows: +.IP +cdu31a=iobase,[irq[,is_pas_card]] +.LP +Specifying an IRQ value of zero tells the driver that hardware +interrupts aren't supported (as on some PAS cards). If your card +supports interrupts, you should use them as it cuts down on the CPU +usage of the driver. + +The +.I is_pas_card +should be entered as `PAS' if using a Pro Audio Spectrum card, +and otherwise it should not be specified at all. + +.SS "The CDU-535 Sony Interface" + +The syntax for this CD-ROM interface is: +.IP +sonycd535=iobase[,irq] +.LP +A zero can be used for the I/O base as a `placeholder' if one wishes +to specify an IRQ value. + +.SS "The GoldStar Interface" + +The syntax for this CD-ROM interface is: +.IP +gscd=iobase +.LP + +.SS "The ISP16 CD-ROM Interface" +Syntax: +.IP +isp16=[iobase[,irq[,dma[,type]]]] +.LP +(three integers and a string). If the type is given as `noisp16', +the interface will not be configured. Other recognized types +are: `Sanyo", `Sony', `Panasonic' and `Mitsumi'. + +.SS "The Mitsumi Standard Interface" + +The syntax for this CD-ROM interface is: +.IP +mcd=iobase,[irq[,wait_value]] +.LP +The +.I wait_value +is used as an internal timeout value for people who are +having problems with their drive, and may or may not be implemented +depending on a compile time #define. +The Mitsumi FX400 is an IDE/ATAPI CD-ROM player and does not use +the mcd driver. + +.SS "The Mitsumi XA/MultiSession Interface" + +This is for the same hardware as above, but the driver has extended features. +Syntax: +.IP +mcdx=iobase[,irq] +.LP + +.SS "The Optics Storage Interface" + +The syntax for this type of card is: +.IP +optcd=iobase +.LP + +.SS "The Phillips CM206 Interface" + +The syntax for this type of card is: +.IP +cm206=[iobase][,irq] +.LP + +The driver assumes numbers between 3 and 11 are IRQ values, and +numbers between 0x300 and 0x370 are I/O ports, so you can specify one, +or both numbers, in any order. It also accepts `cm206=auto' to enable +autoprobing. + +.SS "The Sanyo Interface" + +The syntax for this type of card is: +.IP +sjcd=iobase[,irq[,dma_channel]] +.LP + +.SS "The SoundBlaster Pro Interface" + +The syntax for this type of card is: +.IP +sbpcd=iobase,type +.LP +where type is one of the following (case sensitive) strings: +`SoundBlaster', `LaserMate', or `SPEA'. The I/O base is that of the +CD-ROM interface, and not that of the sound portion of the card. + +.SH "ETHERNET DEVICES" + +Different drivers make use of different parameters, but they all at +least share having an IRQ, an I/O port base value, and a name. In its +most generic form, it looks something like this: +.IP +ether=irq,iobase[,param_1[,...param_8]],name +.LP +The first non-numeric argument is taken as the name. The param_n +values (if applicable) usually have different meanings for each +different card/driver. Typical param_n values are used to specify +things like shared memory address, interface selection, DMA channel +and the like. + +The most common use of this parameter is to force probing for a second +ethercard, as the default is to only probe for one. This can be +accomplished with a simple: +.IP +ether=0,0,eth1 +.LP +Note that the values of zero for the IRQ and I/O base in the above +example tell the driver(s) to autoprobe. + +The Ethernet-HowTo has extensive documentation on using multiple +cards and on the card/driver specific implementation +of the param_n values where used. Interested readers should refer to +the section in that document on their particular card. + +.SH "THE FLOPPY DISK DRIVER" + +There are many floppy driver options, and they are all listed in +README.fd in linux/drivers/block. This information is taken directly +from that file. + +.SS "floppy=mask,allowed_drive_mask" + +Sets the bitmask of allowed drives to mask. By default, only units 0 +and 1 of each floppy controller are allowed. This is done because +certain non-standard hardware (ASUS PCI motherboards) mess up the +keyboard when accessing units 2 or 3. This option is somewhat +obsoleted by the cmos option. + +.SS "floppy=all_drives" + +Sets the bitmask of allowed drives to all drives. Use this if you have +more than two drives connected to a floppy controller. + +.SS "floppy=asus_pci" + +Sets the bitmask to allow only units 0 and 1. (The default) + +.SS "floppy=daring" + +Tells the floppy driver that you have a well behaved floppy +controller. This allows more efficient and smoother operation, but +may fail on certain controllers. This may speed up certain operations. + +.SS "floppy=0,daring" + +Tells the floppy driver that your floppy controller should be used +with caution. + +.SS "floppy=one_fdc" + +Tells the floppy driver that you have only floppy controller (default) + +.SS "floppy=two_fdc or floppy=address,two_fdc" + +Tells the floppy driver that you have two floppy controllers. The +second floppy controller is assumed to be at address. If address is +not given, 0x370 is assumed. + +.SS "floppy=thinkpad" + +Tells the floppy driver that you have a Thinkpad. Thinkpads use an +inverted convention for the disk change line. + +.SS "floppy=0,thinkpad" + +Tells the floppy driver that you don't have a Thinkpad. + +.SS "floppy=drive,type,cmos" + +Sets the cmos type of drive to type. Additionally, this drive is +allowed in the bitmask. This is useful if you have more than two +floppy drives (only two can be described in the physical cmos), or if +your BIOS uses non-standard CMOS types. Setting the CMOS to 0 for the +first two drives (default) makes the floppy driver read the physical +cmos for those drives. + +.SS "floppy=unexpected_interrupts" + +Print a warning message when an unexpected interrupt is received +(default behaviour) + +.SS "floppy=no_unexpected_interrupts or floppy=L40SX" + +Don't print a message when an unexpected interrupt is received. This +is needed on IBM L40SX laptops in certain video modes. (There seems to +be an interaction between video and floppy. The unexpected interrupts +only affect performance, and can safely be ignored.) + +.SH "THE SOUND DRIVER" + +The sound driver can also accept boot args to override the compiled in +values. This is not recommended, as it is rather complex. It is +described in the Readme.Linux file, in linux/drivers/sound. It accepts +a boot arg of the form: +.IP +sound=device1[,device2[,device3...[,device10]]] +.LP +where each deviceN value is of the following format 0xTaaaId and the +bytes are used as follows: + +T - device type: 1=FM, 2=SB, 3=PAS, 4=GUS, 5=MPU401, 6=SB16, +7=SB16-MPU401 + +aaa - I/O address in hex. + +I - interrupt line in hex (i.e 10=a, 11=b, ...) + +d - DMA channel. + +As you can see it gets pretty messy, and you are better off to compile +in your own personal values as recommended. Using a boot arg of +`sound=0' will disable the sound driver entirely. + + +.SH "ISDN DRIVERS" + +.SS "The ICN ISDN driver" +Syntax: +.IP +icn=iobase,membase,icn_id1,icn_id2 +.LP +where icn_id1,icn_id2 are two strings used to identify the +card in kernel messages. + +.SS "The PCBIT ISDN driver" +Syntax: +.IP +pcbit=membase1,irq1[,membase2,irq2] +.LP +where membaseN is the shared memory base of the N'th card, and irqN is +the interrupt setting of the N'th card. The default is IRQ 5 and +membase 0xD0000. + +.SS "The Teles ISDN driver" +Syntax: +.IP +teles=iobase,irq,membase,protocol,teles_id +.LP +where iobase is the i/o port address of the card, membase is the +shared memory base address of the card, irq is the interrupt channel +the card uses, and teles_id is the unique ASCII string identifier. + +.SH "SERIAL PORT DRIVERS" + +.SS "The RISCom/8 Multiport Serial Driver (`riscom8=')" +Syntax: +.IP +riscom=iobase1[,iobase2[,iobase3[,iobase4]]] +.LP +More details can be found in +.IR /usr/src/linux/Documentation/riscom8.txt . + +.SS "The DigiBoard Driver (`digi=')" +If this option is used, it should have precisely six parameters. +Syntax: +.IP +digi=status,type,altpin,numports,iobase,membase +.LP +The parameters maybe given as integers, or as strings. +If strings are used, then iobase and membase should be given +in hexadecimal. +The integer arguments (fewer may be given) are in order: +status (Enable(1) or Disable(0) this card), +type (PC/Xi(0), PC/Xe(1), PC/Xeve(2), PC/Xem(3)), +altpin (Enable(1) or Disable(0) alternate pin arrangement), +numports (number of ports on this card), +iobase (I/O Port where card is configured (in HEX)), +membase (base of memory window (in HEX)). +Thus, the following two boot prompt arguments are equivalent: +.IP +digi=E,PC/Xi,D,16,200,D0000 +.br +digi=1,0,0,16,0x200,851968 +.LP +More details can be found in +.IR /usr/src/linux/Documentation/digiboard.txt . + +.SS "The Baycom Serial/Parallel Radio Modem" +Syntax: +.IP +baycom=iobase,irq,modem +.LP +There are precisely 3 parameters; for several cards, give +several `baycom=' commands. The modem parameter is a string +that can take one of the values ser12, ser12*, par96, par96*. +Here the * denotes that software DCD is to be used, and +ser12/par96 chooses between the supported modem types. +For more details, see +.IR /usr/src/linux/drivers/net/README.baycom . + +.SS "Soundcard radio modem driver" +Syntax: +.IP +soundmodem=iobase,irq,dma[,dma2[,serio[,pario]]],0,mode +.LP +All parameters except the last are integers; +the dummy 0 is required because of a bug in the setup code. +The mode parameter is a string with syntax hw:modem, +where hw is one of sbc, wss, wssfdx and modem is one of +afsk1200, fsk9600. + +.SH "THE LINE PRINTER DRIVER" + +.SS "`lp='" +Syntax: +.IP +lp=0 +.br +lp=auto +.br +lp=reset +.br +lp=port[,port...] +.LP +You can tell the printer driver what ports to use and what ports not +to use. The latter comes in handy if you don't want the printer driver +to claim all available parallel ports, so that other drivers +(e.g. PLIP, PPA) can use them instead. + +The format of the argument is multiple port names. For example, +lp=none,parport0 would use the first parallel port for lp1, and +disable lp0. To disable the printer driver entirely, one can use +lp=0. + +.SS "WDT500/501 driver" +Syntax: +.IP +wdt=io,irq +.LP + +.SH "MOUSE DRIVERS" + +.SS "`bmouse=irq'" +The busmouse driver only accepts one parameter, that being the +hardware IRQ value to be used. + +.SS "`msmouse=irq'" +And precisely the same is true for the msmouse driver. + +.SS "ATARI mouse setup" +.LP +atamouse=threshold[,y-threshold] +.IP +If only one argument is given, it is used for both +x-threshold and y-threshold. Otherwise, the first argument +is the x-threshold, and the second the y-threshold. +These values must lie between 1 and 20 (inclusive); the default is 2. + +.SH "VIDEO HARDWARE" + +.SS "`no-scroll'" +This option tells the console driver not to use hardware scroll +(where a scroll is effected by moving the screen origin in video +memory, instead of moving the data). It is required by certain +Braille machines. + +.SH AUTHORS +Linus Torvalds (and many others) + +.SH "SEE ALSO" +.BR lilo.conf (5), +.BR klogd (8), +.BR lilo (8), +.BR mount (8), +.BR rdev (8) + +Large parts of this man page have been derived from the +Boot Parameter HOWTO (version 1.0.1) written by Paul Gortmaker. +More information may be found in this (or a more recent) HOWTO. +An uptodate source of information is +.IR /usr/src/linux/Documentation/kernel-parameters.txt . diff --git a/man7/capabilities.7 b/man7/capabilities.7 new file mode 100644 index 000000000..deb3c380c --- /dev/null +++ b/man7/capabilities.7 @@ -0,0 +1,402 @@ +.\" Copyright (c) 2002 by Michael Kerrisk (mtk16@ext.canterbury.ac.nz) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" +.\" 6 Aug 2002 - Initial Creation +.\" Modified 2003-05-23, Michael Kerrisk, +.\" Modified 2004-05-27, Michael Kerrisk, +.\" +.\" +.TH CAPABILITIES 7 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +capabilities \- overview of Linux capabilities +.SH DESCRIPTION + +For the purpose of performing permission checks, +traditional Unix implementations distinguish two categories of processes: +.I privileged +processes (whose effective user ID is 0, referred to as superuser or root), +and +.I unprivileged +processes (whose effective UID is non-zero). +Privileged processes bypass all kernel permission checks, +while unprivileged processes are subject to full permission +checking based on the process's credentials +(usually: effective UID, effective GID, and supplementary group list). + +Starting with kernel 2.2, Linux provides an +(as yet incomplete) system of +.IR capabilities , +which divide the privileges traditionally associated with superuser +into distinct units that can be independently enabled and disabled. +.SS Capabilities List + +As at Linux 2.6.6, the following capabilities are implemented: +.TP +.B CAP_CHOWN +Allow arbitrary changes to file UIDs and GIDs (see +.BR chown (2)). +.TP +.B CAP_DAC_OVERRIDE +Bypass file read, write, and execute permission checks. +(DAC = "discretionary access control".) +.TP +.B CAP_DAC_READ_SEARCH +Bypass file read permission checks and +directory read and execute permission checks. +.TP +.B CAP_FOWNER +Bypass permission checks on operations that normally +require the file system UID of the process to match the UID of +the file (e.g., +.BR chmod (2), +.BR utime (2)), +excluding those operations covered by the +.B CAP_DAC_OVERRIDE +and +.BR CAP_DAC_READ_SEARCH ; +set extended file attributes (see +.BR chattr (1)) +on arbitrary files; +set Access Control Lists (ACLs) on arbitrary files; +ignore directory sticky bit on file deletion. +.TP +.B CAP_FSETID +Don't clear set-user-ID and set-group-ID bits when a file is modified; +permit setting of the set-group-ID bit for a file whose GID does not match +the file system or any of the supplementary GIDs of the calling process. +.TP +.B CAP_IPC_LOCK +Permit memory locking +.RB ( mlock (2), +.BR mlockall (2), +.BR mmap (2), +.BR shmctl (2)). +.TP +.B CAP_IPC_OWNER +Bypass permission checks for operations on System V IPC objects. +.TP +.B CAP_KILL +Bypass permission checks for sending signals (see +.BR kill (2)). +This includes use of the KDSIGACCEPT ioctl. +.\" FIXME: CAP_KILL also an effect for threads + setting child +.\" termination signal to other than SIGCHLD +.TP +.B CAP_LEASE +(Linux 2.4 onwards) Allow file leases to be established on +arbitrary files (see +.BR fcntl (2)). +.TP +.B CAP_LINUX_IMMUTABLE +Allow setting of the +.B EXT2_APPEND_FL +and +.B EXT2_IMMUTABLE_FL +.\" These attributes are now available on ext2, ext3, Reiserfs +extended file attributes (see +.BR chattr (1)). +.TP +.B CAP_MKNOD +(Linux 2.4 onwards) +Allow creation of special files using +.BR mknod (2). +.TP +.B CAP_NET_ADMIN +Allow various network-related operations +(e.g., setting privileged socket options, +enabling multicasting, interface configuration, +modifying routing tables). +.TP +.B CAP_NET_BIND_SERVICE +Allow binding to Internet domain reserved socket ports +(port numbers less than 1024). +.TP +.B CAP_NET_BROADCAST +(Unused) Allow socket broadcasting, and listening multicasts. +.TP +.B CAP_NET_RAW +Permit use of RAW and PACKET sockets. +.\" Also various IP options and setsockopt(SO_BINDTODEVICE) +.TP +.B CAP_SETGID +Allow arbitrary manipulations of process GIDs and supplementary GID list; +allow forged GID when passing socket credentials via Unix domain sockets. +.TP +.B CAP_SETPCAP +Grant or remove any capability in the caller's +permitted capability set to or from any other process. +.TP +.B CAP_SETUID +Allow arbitrary manipulations of process UIDs +.RB ( setuid (2), +.BR setreuid (2), +.BR setresuid (2), +.BR setfsuid (2)); +allow forged UID when passing socket credentials via Unix domain sockets. +.\" FIXME: CAP_SETUID also an effect in exec() +.TP +.B CAP_SYS_ADMIN +Permit a range of system administration operations including: +.BR quotactl (2), +.BR mount (2), +.BR umount (2), +.BR swapon (2) , +.BR swapoff (2) , +.BR sethostname (2), +.BR setdomainname (2), +.B IPC_SET +and +.B IPC_RMID +operations on arbitrary System V IPC objects; +perform operations on +.I trusted +and +.I security +Extended Attributes (see +.BR attr (5)); +allow forged UID when passing socket credentials; +exceed +.I /proc/sys/fs/file-max +limit in system calls that open files (e.g., +.BR accept (2), +.BR execve (2), +.BR open (2), +.BR pipe (2)) +.TP +.B CAP_SYS_BOOT +Permit calls to +.BR reboot (2). +.TP +.B CAP_SYS_CHROOT +Permit calls to +.BR chroot (2). +.TP +.B CAP_SYS_MODULE +Allow loading and unloading of kernel modules; +allow modifications to capability bounding set (see +.BR init_module (2) +and +.BR delete_module (2)). +.TP +.B CAP_SYS_NICE +Allow raising process nice value +.RB ( nice (2), +.BR setpriority (2)) +and changing of the nice value for arbitrary processes; +allow setting of real-time scheduling policies for calling process, +and setting scheduling policies and priorities for arbitrary processes +.RB ( sched_setscheduler (2), +.BR sched_setparam (2)); +set CPU affinity for arbitrary processes +.RB ( sched_setaffinity ()). +.TP +.B CAP_SYS_PACCT +Permit calls to +.BR acct (2). +.TP +.B CAP_SYS_PTRACE +Allow arbitrary processes to be traced using +.BR ptrace (2) +.TP +.B CAP_SYS_RAWIO +Permit I/O port operations +.RB ( iopl (2) +and +.BR ioperm (2)); +access +.IT /proc/kcore . +.TP +.B CAP_SYS_RESOURCE +Permit: use of reserved space on ext2 file systems; +.BR ioctl (2) +calls controlling ext3 journaling; +disk quota limits to be overridden; +resource limits to be increased (see +.BR setrlimit (2)); +.B RLIMIT_NPROC +resource limit to be overridden; +.I msg_qbytes +limit for a message queue to be +raised above the limit in +.IR /proc/sys/kernel/msgmnb +(see +.BR msgop (2) +and +.BR msgctl (2). +.TP +.B CAP_SYS_TIME +Allow modification of system clock +.RB ( settimeofday (2), +.BR stime (2), +.BR adjtimex (2)); +allow modification of real-time (hardware) clock +.TP +.B CAP_SYS_TTY_CONFIG +Permit calls to +.BR vhangup (2). +.SS Process Capabilities +Each process has three capability sets containing zero or more +of the above capabilities: +.TP +.IR Effective : +the capabilities used by the kernel to +perform permission checks for the process. +.TP +.IR Permitted : +the capabilities that the process may assume +(i.e., a limiting superset for the effective and inheritable sets). +If a process drops a capability from its permitted set, +it can never re-acquire that capability (unless it execs a +set-UID-root program). +.TP +.IR Inherited : +the capabilities preserved across an +.BR execve (2). +.PP +In the current implementation, a process is granted all permitted and +effective capabilities (subject to the operation of the +capability bounding set described below) +when it execs a set-UID-root program, +or if a process with a real UID of zero execs a new program. +.PP +A child created via +.BR fork (2) +inherits copies of its parent's capability sets. +.PP +Using +.BR capset (2), +a process may manipulate its own capability sets, or, if it has the +.B CAP_SETPCAP +capability, those of another process. + +.SS Capability bounding set +When a program is execed, the permitted and effective capabities are ANDed +with the current value of the so-called +.IR "capability bounding set" , +defined in the file +.IR /proc/sys/kernel/cap-bound . +This parameter can be used to place a system-wide limit on the +capabilities granted to all subsequently executed programs. +(Confusingly, this bit mask parameter is expressed as a +signed decimal number in +.IR /proc/sys/kernel/cap-bound .) + +Only the +.B init +process may set bits in the capability bounding set; +other than that, the superuser may only clear bits in this set. + +On a standard system the capability bounding set always masks out the +.B CAP_SETPCAP +capability. +To remove this restriction, modify the definition of +.B CAP_INIT_EFF_SET +in +.I include/linux/capability.h +and rebuild the kernel. + +.SS Current and Future Implementation +A full implementation of capabilities requires: +.IP 1. 4 +that for all privileged operations, +the kernel check whether the process has the required +capability in its effective set. +.IP 2. 4 +that the kernel provide +system calls allowing a process's capability sets to +be changed and retrieved. +.IP 3. 4 +file system support for attaching capabilities to an executable file, +so that a process gains those capabilities when the file is execed. +.PP +As at Linux 2.6.6, only the first two of these requirements are met. + +Eventually, it should be possible to associate three +capability sets with an executable file, which, +in conjunction with the capability sets of the process, +will determine the capabilities of a process after an +.IR exec : +.TP +.IR Allowed : +this set is ANDed with the process's inherited set to determine which +inherited capabilities are permitted to the process after the exec. +.TP +.IR Forced : +the capabilities automatically permitted to the process, +regardless of the process's inherited capabilities. +.TP +.IR Effective : +those capabilities in the process's new permitted set are +also to be set in the new effective set. +(F(effective) would normally be either all zeroes or all ones.) +.PP +In the meantime, since the current implementation does not +support file capability sets, during an exec: +.IP 1. 4 +All three file capability sets are initially assumed to be cleared. +.IP 2. 4 +If a set-UID-root program is being execed, +or the real user ID of the process is 0 (root) +then the file allowed and forced sets are defined to be all ones +(i.e., all capabilities set). +.IP 3. 4 +If a set-UID-root program is being executed, +then the file effective set is defined to be all ones. +.PP +During an exec, the kernel calculates the new capabilities of +the process using the following algorithm: +.in +4 +.nf + +P'(permitted) = (P(inherited) & F(allowed)) | (F(forced) & cap_bset) + +P'(effective) = P'(permitted) & F(effective) + +P'(inherited) = P(inherited) [i.e., unchanged] + +.fi +.in -4 +where: +.IP P 10 +denotes the value of a process capability set before the exec +.IP P' 10 +denotes the value of a capability set after the exec +.IP F 10 +denotes a file capability set +.IP cap_bset 10 +is the value of the capability bounding set. +.SH NOTES +The +.I libcap +package provides a suite of routines for setting and +getting process capabilities that is more comfortable and less likely +to change than the interface provided by +.BR capset (2) +and +.BR capget (2). +.SH "CONFORMING TO" +No standards govern capabilities, but the Linux capability implementation +is based on the withdrawn POSIX 1003.1e draft standard. +.SH BUGS +There is as yet no file system support allowing capabilities to be +associated with executable files. +.SH "SEE ALSO" +.BR capget (2), +.BR prctl (2) diff --git a/man7/charsets.7 b/man7/charsets.7 new file mode 100644 index 000000000..83fb41f90 --- /dev/null +++ b/man7/charsets.7 @@ -0,0 +1,322 @@ +.\" Copyright (c) 1996 Eric S. Raymond +.\" and Andries Brouwer +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" This is combined from many sources, including notes by aeb and +.\" research by esr. Portions derive from a writeup by Roman Czyborra. +.\" +.\" Last changed by David Starner . +.TH CHARSETS 7 2001-05-07 "Linux" "Linux Programmer's Manual" +.SH NAME +charsets \- programmer's view of character sets and internationalization +.SH DESCRIPTION +Linux is an international operating system. Various of its utilities +and device drivers (including the console driver) support multilingual +character sets including Latin-alphabet letters with diacritical +marks, accents, ligatures, and entire non-Latin alphabets including +Greek, Cyrillic, Arabic, and Hebrew. +.LP +This manual page presents a programmer's-eye view of different +character-set standards and how they fit together on Linux. Standards +discussed include ASCII, ISO 8859, KOI8-R, Unicode, ISO 2022 and +ISO 4873. The primary emphasis is on character sets actually used as +locale character sets, not the myriad others that can be found in data +from other systems. +.LP +A complete list of charsets used in a officially supported locale in glibc +2.2.3 is: ISO-8859-{1,2,3,5,6,7,8,9,13,15}, CP1251, UTF-8, EUC-{KR,JP,TW}, +KOI8-{R,U}, GB2312, GB18030, GBK, BIG5, BIG5-HKSCS and TIS-620 (in no +particular order.) (Romanian may be switching to ISO-8859-16.) + +.SH ASCII +ASCII (American Standard Code For Information Interchange) is the original +7-bit character set, originally designed for American English. It is +currently described by the ECMA-6 standard. +.LP +Various ASCII variants replacing the dollar sign with other currency +symbols and replacing punctuation with non-English alphabetic characters +to cover German, French, Spanish and others in 7 bits exist. All are +deprecated; GNU libc doesn't support locales whose character sets aren't +true supersets of ASCII. (These sets are also known as ISO-646, a close +relative of ASCII that permitted replacing these characters.) +.LP +As Linux was written for hardware designed in the US, it natively +supports ASCII. + +.SH ISO 8859 +ISO 8859 is a series of 15 8-bit character sets all of which have US +ASCII in their low (7-bit) half, invisible control characters in +positions 128 to 159, and 96 fixed-width graphics in positions 160-255. +.LP +Of these, the most important is ISO 8859-1 (Latin-1). It is natively +supported in the Linux console driver, fairly well supported in X11R6, +and is the base character set of HTML. +.LP +Console support for the other 8859 character sets is available under +Linux through user-mode utilities (such as +.BR setfont (8)) +.\" // some distributions still have the deprecated consolechars +that modify keyboard bindings and the EGA graphics +table and employ the "user mapping" font table in the console +driver. +.LP +Here are brief descriptions of each set: +.TP +8859-1 (Latin-1) +Latin-1 covers most Western European languages such as Albanian, Catalan, +Danish, Dutch, English, Faroese, Finnish, French, German, Galician, +Irish, Icelandic, Italian, Norwegian, Portuguese, Spanish, and +Swedish. The lack of the ligatures Dutch ij, French oe and old-style +,,German`` quotation marks is considered tolerable. +.TP +8859-2 (Latin-2) +Latin-2 supports most Latin-written Slavic and Central European +languages: Croatian, Czech, German, Hungarian, Polish, Rumanian, +Slovak, and Slovene. +.TP +8859-3 (Latin-3) +Latin-3 is popular with authors of Esperanto, Galician, and Maltese. +(Turkish is now written with 8859-9 instead.) +.TP +8859-4 (Latin-4) +Latin-4 introduced letters for Estonian, Latvian, and Lithuanian. It +is essentially obsolete; see 8859-10 (Latin-6) and 8859-13 (Latin-7). +.TP +8859-5 +Cyrillic letters supporting Bulgarian, Byelorussian, Macedonian, +Russian, Serbian and Ukrainian. Ukrainians read the letter `ghe' +with downstroke as `heh' and would need a ghe with upstroke to write a +correct ghe. See the discussion of KOI8-R below. +.TP +8859-6 +Supports Arabic. The 8859-6 glyph table is a fixed font of separate +letter forms, but a proper display engine should combine these +using the proper initial, medial, and final forms. +.TP +8859-7 +Supports Modern Greek. +.TP +8859-8 +Supports modern Hebrew without niqud (punctuation signs). Niqud +and full-fledged Biblical Hebrew are outside the scope of this +character set; under Linux, UTF-8 is the preferred encoding for +these. +.TP +8859-9 (Latin-5) +This is a variant of Latin-1 that replaces Icelandic letters with +Turkish ones. +.TP +8859-10 (Latin-6) +Latin 6 adds the last Inuit (Greenlandic) and Sami (Lappish) letters +that were missing in Latin 4 to cover the entire Nordic area. RFC +1345 listed a preliminary and different `latin6'. Skolt Sami still +needs a few more accents than these. +.TP +8859-11 +This only exists as a rejected draft standard. The draft standard +was identical to TIS-620, which is used under Linux for Thai. +.TP +8859-12 +This set does not exist. While Vietnamese has been suggested for this +space, it does not fit within the 96 (non-combining) characters ISO +8859 offers. UTF-8 is the preferred character set for Vietnamese use +under Linux. +.TP +8859-13 (Latin-7) +Supports the Baltic Rim languages; in particular, it includes Latvian +characters not found in Latin-4. +.TP +8859-14 (Latin-8) +This is the Celtic character set, covering Gaelic and Welsh. +This charset also contains the dotted characters needed for Old Irish. +.TP +8859-15 (Latin-9) +This adds the Euro sign and French and Finnish letters that were missing in +Latin-1. +.TP +8859-16 (Latin-10) +This set covers many of the languages covered by 8859-2, and supports +Romanian more completely then that set does. +.SH KOI8-R +KOI8-R is a non-ISO character set popular in Russia. The lower half +is US ASCII; the upper is a Cyrillic character set somewhat better +designed than ISO 8859-5. KOI8-U is a common character set, based off +KOI8-R, that has better support for Ukrainian. Neither of these sets +are ISO-2022 compatible, unlike the ISO-8859 series. +.LP +Console support for KOI8-R is available under Linux through user-mode +utilities that modify keyboard bindings and the EGA graphics table, +and employ the "user mapping" font table in the console driver. + +.\" Thanks to Tomohiro KUBOTA for the following sections about +.\" national standards. +.SH JIS X 0208 +JIS X 0208 is a Japanese national standard character set. Though +there are some more Japanese national standard character sets (like +JIS X 0201, JIS X 0212, and JIS X 0213), this is the most important +one. Characters are mapped into a 94x94 two-byte matrix, +whose each byte is in the range 0x21-0x7e. Note that JIS X 0208 +is a character set, not an encoding. This means that JIS X 0208 +itself is not used for expressing text data. JIS X 0208 is used +as a component to construct encodings such as EUC-JP, Shift_JIS, +and ISO-2022-JP. EUC-JP is the most important encoding for Linux +and includes US ASCII and JIS X 0208. In EUC-JP, JIS X 0208 +characters are expressed in two bytes, each of which is the +JIS X 0208 code plus 0x80. + +.SH KS X 1001 +KS X 1001 is a Korean national standard character set. Just as +JIS X 0208, characters are mapped into a 94x94 two-byte matrix. +KS X 1001 is used like JIS X 0208, as a component +to construct encodings such as EUC-KR, Johab, and ISO-2022-KR. +EUC-KR is the most important encoding for Linux and includes +US ASCII and KS X 1001. KS C 5601 is an older name for KS X 1001. + +.SH GB 2312 +GB 2312 is a mainland Chinese national standard character set used +to express simplified Chinese. Just like JIS X 0208, characters are +mapped into a 94x94 two-byte matrix used to construct EUC-CN. EUC-CN +is the most important encoding for Linux and includes US ASCII and +GB 2312. Note that EUC-CN is often called as GB, GB 2312, or CN-GB. + +.SH Big5 +Big5 is a popular character set in Taiwan to express traditional +Chinese. (Big5 is both a character set and an encoding.) It is a +superset of US ASCII. Non-ASCII characters are expressed in two +bytes. Bytes 0xa1-0xfe are used as leading bytes for two-byte +characters. Big5 and its extension is widely used in Taiwan and Hong +Kong. It is not ISO 2022-compliant. + +.SH TIS 620 +TIS 620 is a Thai national standard character set and a superset +of US ASCII. Like ISO 8859 series, Thai characters are mapped into +0xa1-0xfe. TIS 620 is the only commonly used character set under +Linux besides UTF-8 to have combining characters. + +.SH UNICODE +Unicode (ISO 10646) is a standard which aims to unambiguously represent every +character in every human language. Unicode's structure permits 20.1 bits +to encode every character. Since most computers don't include 20.1-bit +integers, Unicode is usually encoded as 32-bit integers internally and +either a series of 16-bit integers (UTF-16) (needing two 16-bit integers +only when encoding certain rare characters) or a series of 8-bit bytes +(UTF-8). Information on Unicode is available at . +.LP +Linux represents Unicode using the 8-bit Unicode Transformation Format +(UTF-8). UTF-8 is a variable length encoding of Unicode. It uses 1 +byte to code 7 bits, 2 bytes for 11 bits, 3 bytes for 16 bits, 4 bytes +for 21 bits, 5 bytes for 26 bits, 6 bytes for 31 bits. +.LP +Let 0,1,x stand for a zero, one, or arbitrary bit. A byte 0xxxxxxx +stands for the Unicode 00000000 0xxxxxxx which codes the same symbol +as the ASCII 0xxxxxxx. Thus, ASCII goes unchanged into UTF-8, and +people using only ASCII do not notice any change: not in code, and not +in file size. +.LP +A byte 110xxxxx is the start of a 2-byte code, and 110xxxxx 10yyyyyy +is assembled into 00000xxx xxyyyyyy. A byte 1110xxxx is the start +of a 3-byte code, and 1110xxxx 10yyyyyy 10zzzzzz is assembled +into xxxxyyyy yyzzzzzz. +(When UTF-8 is used to code the 31-bit ISO 10646 +then this progression continues up to 6-byte codes.) +.LP +For most people who use ISO-8859 character sets, this means that the +characters outside of ASCII are now coded with two bytes. This tends +to expand ordinary text files by only one or two percent. For Russian +or Greek users, this expands ordinary text files by 100%, since text in +those languages is mostly outside of ASCII. For Japanese users this means +that the 16-bit codes now in common use will take three bytes. While there +are algorithmic conversions from some character sets (esp. ISO-8859-1) to +Unicode, general conversion requires carrying around conversion tables, +which can be quite large for 16-bit codes. +.LP +Note that UTF-8 is self-synchronizing: 10xxxxxx is a tail, any other +byte is the head of a code. Note that the only way ASCII bytes occur +in a UTF-8 stream, is as themselves. In particular, there are no +embedded NULs or '/'s that form part of some larger code. +.LP +Since ASCII, and, in particular, NUL and '/', are unchanged, the +kernel does not notice that UTF-8 is being used. It does not care at +all what the bytes it is handling stand for. +.LP +Rendering of Unicode data streams is typically handled through +`subfont' tables which map a subset of Unicode to glyphs. Internally +the kernel uses Unicode to describe the subfont loaded in video RAM. +This means that in UTF-8 mode one can use a character set with 512 +different symbols. This is not enough for Japanese, Chinese and +Korean, but it is enough for most other purposes. +.LP +At the current time, the console driver does not handle combining +characters. So Thai, Sioux and any other script needing combining +characters can't be handled on the console. + +.SH "ISO 2022 AND ISO 4873" +The ISO 2022 and 4873 standards describe a font-control model +based on VT100 practice. This model is (partially) supported +by the Linux kernel and by +.BR xterm (1). +It is popular in Japan and Korea. +.LP +There are 4 graphic character sets, called G0, G1, G2 and G3, +and one of them is the current character set for codes with +high bit zero (initially G0), and one of them is the current +character set for codes with high bit one (initially G1). +Each graphic character set has 94 or 96 characters, and is +essentially a 7-bit character set. It uses codes either +040-0177 (041-0176) or 0240-0377 (0241-0376). +G0 always has size 94 and uses codes 041-0176. +.LP +Switching between character sets is done using the shift functions +^N (SO or LS1), ^O (SI or LS0), ESC n (LS2), ESC o (LS3), +ESC N (SS2), ESC O (SS3), ESC ~ (LS1R), ESC } (LS2R), ESC | (LS3R). +The function LS\fIn\fP makes character set G\fIn\fP the current one +for codes with high bit zero. +The function LS\fIn\fPR makes character set G\fIn\fP the current one +for codes with high bit one. +The function SS\fIn\fP makes character set G\fIn\fP (\fIn\fP=2 or 3) +the current one for the next character only (regardless of the value +of its high order bit). +.LP +A 94-character set is designated as G\fIn\fP character set +by an escape sequence ESC ( xx (for G0), ESC ) xx (for G1), +ESC * xx (for G2), ESC + xx (for G3), where xx is a symbol +or a pair of symbols found in the ISO 2375 International +Register of Coded Character Sets. +For example, ESC ( @ selects the ISO 646 character set as G0, +ESC ( A selects the UK standard character set (with pound +instead of number sign), ESC ( B selects ASCII (with dollar +instead of currency sign), ESC ( M selects a character set +for African languages, ESC ( ! A selects the Cuban character +set, etc. etc. +.LP +A 96-character set is designated as G\fIn\fP character set +by an escape sequence ESC - xx (for G1), ESC . xx (for G2) +or ESC / xx (for G3). +For example, ESC - G selects the Hebrew alphabet as G1. +.LP +A multibyte character set is designated as G\fIn\fP character set +by an escape sequence ESC $ xx or ESC $ ( xx (for G0), +ESC $ ) xx (for G1), ESC $ * xx (for G2), ESC $ + xx (for G3). +For example, ESC $ ( C selects the Korean character set for G0. +The Japanese character set selected by ESC $ B has a more +recent version selected by ESC & @ ESC $ B. +.LP +ISO 4873 stipulates a narrower use of character sets, where G0 +is fixed (always ASCII), so that G1, G2 and G3 +can only be invoked for codes with the high order bit set. +In particular, ^N and ^O are not used anymore, ESC ( xx +can be used only with xx=B, and ESC ) xx, ESC * xx, ESC + xx +are equivalent to ESC - xx, ESC . xx, ESC / xx, respectively. + +.SH "SEE ALSO" +.BR console (4), +.BR console_codes (4), +.BR console_ioctl (4), +.BR ascii (7), +.BR iso_8859-1 (7), +.BR unicode (7), +.BR utf-8 (7) diff --git a/man7/ddp.7 b/man7/ddp.7 new file mode 100644 index 000000000..5a874fb08 --- /dev/null +++ b/man7/ddp.7 @@ -0,0 +1,240 @@ +.\" This man page is Copyright (C) 1998 Alan Cox. +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" $Id: ddp.7,v 1.3 1999/05/13 11:33:22 freitag Exp $ +.TH DDP 7 1999-05-01 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +ddp \- Linux AppleTalk protocol implementation +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.IB ddp_socket " = socket(PF_APPLETALK, SOCK_DGRAM, 0);" +.br +.IB raw_socket " = socket(PF_APPLETALK, SOCK_RAW, " protocol ");" +.SH DESCRIPTION +Linux implements the Appletalk protocols described in +.IR "Inside Appletalk" . +Only the DDP layer and AARP are present in +the kernel. They are designed to be used via the +.B netatalk +protocol +libraries. This page documents the interface for those who wish or need to +use the DDP layer directly. +.PP +The communication between Appletalk and the user program works using a +BSD-compatible socket interface. For more information on sockets, see +.BR socket (7). +.PP +An AppleTalk socket is created by calling the +.BR socket (2) +function with a +.B PF_APPLETALK +socket family argument. Valid socket types are +.B SOCK_DGRAM +to open a +.B ddp +socket or +.B SOCK_RAW +to open a +.B raw +socket. +.I protocol +is the Appletalk protocol to be received or sent. For +.B SOCK_RAW +you must specify +.BR ATPROTO_DDP . +.PP +Raw sockets may be only opened by a process with effective user id 0 or when the process has the +.B CAP_NET_RAW +capability. +.SH "ADDRESS FORMAT" +An Appletalk socket address is defined as a combination of a network number, +a node number, and a port number. +.PP +.RS +.nf +.ta 4n 20n 32n +struct at_addr { + u_short s_net; + u_char s_node; +}; + +struct sockaddr_atalk { + sa_family_t sat_family; /* address family */ + u_char sat_port; /* port */ + struct at_addr sat_addr; /* net/node */ +}; +.ta +.fi +.RE +.PP +.I sat_family +is always set to +.B AF_APPLETALK. +.I sat_port +contains the port. The port numbers below 129 are known as +.B reserved ports. +Only processes with the effective user id 0 or the +.B CAP_NET_BIND_SERVICE +capability may +.BR bind (2) +to these sockets. +.I sat_addr +is the host address. +The +.I net +member of +.B struct at_addr +contains the host network in network byte order. The value of +.B AT_ANYNET +is a +wildcard and also implies \(lqthis network.\(rq +The +.I node +member of +.B struct at_addr +contains the host node number. The value of +.B AT_ANYNODE +is a +wildcard and also implies \(lqthis node.\(rq The value of +.B ATADDR_BCAST +is a link +local broadcast address. +.\" XXX this doesn't make sense [johnl] +.SH "SOCKET OPTIONS" +No protocol-specific socket options are supported. +.SH SYSCTLS +IP supports a sysctl interface to configure some global AppleTalk parameters. +The sysctls can be accessed by reading or writing the +.B /proc/sys/net/atalk/* +files or with the +.BR sysctl (2) +interface. +.TP +.B aarp-expiry-time +The time interval (in seconds) before an AARP cache entry expires. +.TP +.B aarp-resolve-time +The time interval (in seconds) before an AARP cache entry is resolved. +.TP +.B aarp-retransmit-limit +The number of retransmissions of an AARP query before the node is declared +dead. +.TP +.B aarp-tick-time +The timer rate (in seconds) for the timer driving AARP. +.PP +The default values match the specification and should never need to be +changed. + +.SH IOCTLS +All ioctls described in +.BR socket (7) +apply to ddp. + +.\" XXX Add a chapter about multicasting + +.SH NOTES +Be very careful with the +.B SO_BROADCAST +option \- it is not privileged in Linux. It is easy to overload the network +with careless sending to broadcast addresses. +.SH VERSIONS +Appletalk is supported by Linux 2.0 or higher. The +.B sysctl +interface is +new in Linux 2.2. +.SH ERRORS +.\" XXX document all errors. We should really fix the kernels to give more uniform +.\" error returns (ENOMEM vs ENOBUFS, EPERM vs EACCES etc.) +.TP +.B ENOTCONN +The operation is only defined on a connected socket, but the socket wasn't +connected. +.TP +.B EINVAL +Invalid argument passed. +.TP +.B EMSGSIZE +Datagram is bigger than the DDP MTU. +.TP +.B EACCES +The user tried to execute an operation without the necessary permissions. These +include sending to a broadcast address without having the broadcast flag set, +and trying to bind to a reserved port without effective user id 0 or +.BR CAP_NET_BIND_SERVICE . +.TP +.B EADDRINUSE +Tried to bind to an address already in use. +.TP +.BR ENOMEM " and " ENOBUFS +Not enough memory available. +.TP +.BR ENOPROTOOPT " and " EOPNOTSUPP +Invalid socket option passed. +.TP +.B EPERM +User doesn't have permission to set high priority, make a configuration change, +or send signals to the requested process or group, +.TP +.B EADDRNOTAVAIL +A non-existent interface was requested or the requested source address was +not local. +.TP +.B EAGAIN +Operation on a nonblocking socket would block. +.TP +.B ESOCKTNOSUPPORT +The socket was unconfigured, or an unknown socket type was requested. +.TP +.B EISCONN +.BR connect (2) +was called on an already connected socket. +.TP +.B EALREADY +A connection operation on a non-blocking socket is already in progress. +.TP +.B ECONNABORTED +A connection was closed during an +.BR accept (2). +.TP +.B EPIPE +The connection was unexpectedly closed or shut down by the other end. +.TP +.B ENOENT +.B SIOCGSTAMP +was called on a socket where no packet arrived. +.TP +.B EHOSTUNREACH +No routing table entry matches the destination address. +.TP +.B ENODEV +Network device not available or not capable of sending IP. +.TP +.B ENOPKG +A kernel subsystem was not configured. +.SH COMPATIBILITY +The basic AppleTalk socket interface is compatible with +.B netatalk +on BSD-derived systems. Many BSD systems fail to check +.B SO_BROADCAST +when sending broadcast frames; this can lead to compatibility problems. +.PP +The +raw +socket mode is unique to Linux and exists to support the alternative CAP +package and AppleTalk monitoring tools more easily. +.SH BUGS +There are too many inconsistent error values. +.PP +The ioctls used to configure routing tables, devices, AARP tables and other +devices are not yet described. +.SH "SEE ALSO" +.BR recvmsg (2), +.BR sendmsg (2), +.BR capabilities (7), +.BR socket (7) diff --git a/man7/glob.7 b/man7/glob.7 new file mode 100644 index 000000000..02ead1c5b --- /dev/null +++ b/man7/glob.7 @@ -0,0 +1,187 @@ +.\" Copyright (c) 1998 Andries Brouwer +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 2003-08-24 fix for / by John Kristoff + joey +.\" +.TH GLOB 7 2003-08-24 "Unix" "Linux Programmer's Manual" +.SH NAME +glob \- Globbing pathnames +.SH DESCRIPTION +Long ago, in Unix V6, there was a program +.I /etc/glob +that would expand wildcard patterns. +Soon afterwards this became a shell built-in. + +These days there is also a library routine +.BR glob (3) +that will perform this function for a user program. + +The rules are as follows (POSIX 1003.2, 3.13). +.SH "WILDCARD MATCHING" +A string is a wildcard pattern if it contains one of the +characters `?', `*' or `['. Globbing is the operation +that expands a wildcard pattern into the list of pathnames +matching the pattern. Matching is defined by: + +A `?' (not between brackets) matches any single character. + +A `*' (not between brackets) matches any string, +including the empty string. + +.SS "Character classes" +An expression `[...]' where the first character after the +leading `[' is not an `!' matches a single character, +namely any of the characters enclosed by the brackets. +The string enclosed by the brackets cannot be empty; +therefore `]' can be allowed between the brackets, provided +that it is the first character. (Thus, `[][!]' matches the +three characters `[', `]' and `!'.) + +.SS Ranges +There is one special convention: +two characters separated by `-' denote a range. +(Thus, `[A-Fa-f0-9]' is equivalent to `[ABCDEFabcdef0123456789]'.) +One may include `-' in its literal meaning by making it the +first or last character between the brackets. +(Thus, `[]-]' matches just the two characters `]' and `-', +and `[--0]' matches the three characters `-', `.', `0', since `/' +cannot be matched.) + +.SS Complementation +An expression `[!...]' matches a single character, namely +any character that is not matched by the expression obtained +by removing the first `!' from it. +(Thus, `[!]a-]' matches any single character except `]', `a' and `-'.) + +One can remove the special meaning of `?', `*' and `[' by +preceding them by a backslash, or, in case this is part of +a shell command line, enclosing them in quotes. +Between brackets these characters stand for themselves. +Thus, `[[?*\e]' matches the four characters `[', `?', `*' and `\e'. + +.SH PATHNAMES +Globbing is applied on each of the components of a pathname +separately. A `/' in a pathname cannot be matched by a `?' or `*' +wildcard, or by a range like `[.-0]'. A range cannot contain an +explicit `/' character; this would lead to a syntax error. + +If a filename starts with a `.', this character must be matched explicitly. +(Thus, `rm *' will not remove .profile, and `tar c *' will not +archive all your files; `tar c .' is better.) + +.SH "EMPTY LISTS" +The nice and simple rule given above: `expand a wildcard pattern +into the list of matching pathnames' was the original Unix +definition. It allowed one to have patterns that expand into +an empty list, as in +.br +.nf + xv -wait 0 *.gif *.jpg +.fi +where perhaps no *.gif files are present (and this is not +an error). +However, POSIX requires that a wildcard pattern is left +unchanged when it is syntactically incorrect, or the list of +matching pathnames is empty. +With +.I bash +one can force the classical behaviour by setting +.IR allow_null_glob_expansion=true . + +(Similar problems occur elsewhere. E.g., where old scripts have +.br +.nf + rm `find . -name "*~"` +.fi +new scripts require +.br +.nf + rm -f nosuchfile `find . -name "*~"` +.fi +to avoid error messages from +.I rm +called with an empty argument list.) + +.SH NOTES +.SS Regular expressions +Note that wildcard patterns are not regular expressions, +although they are a bit similar. First of all, they match +filenames, rather than text, and secondly, the conventions +are not the same: e.g., in a regular expression `*' means zero or +more copies of the preceding thing. + +Now that regular expressions have bracket expressions where +the negation is indicated by a `^', POSIX has declared the +effect of a wildcard pattern `[^...]' to be undefined. + +.SS Character classes and Internationalization +Of course ranges were originally meant to be ASCII ranges, +so that `[ -%]' stands for `[ !"#$%]' and `[a-z]' stands +for "any lowercase letter". +Some Unix implementations generalized this so that a range X-Y +stands for the set of characters with code between the codes for +X and for Y. However, this requires the user to know the +character coding in use on the local system, and moreover, is +not convenient if the collating sequence for the local alphabet +differs from the ordering of the character codes. +Therefore, POSIX extended the bracket notation greatly, +both for wildcard patterns and for regular expressions. +In the above we saw three types of items that can occur in a bracket +expression: namely (i) the negation, (ii) explicit single characters, +and (iii) ranges. POSIX specifies ranges in an internationally +more useful way and adds three more types: + +(iii) Ranges X-Y comprise all characters that fall between X +and Y (inclusive) in the currect collating sequence as defined +by the LC_COLLATE category in the current locale. + +(iv) Named character classes, like +.br +.nf +[:alnum:] [:alpha:] [:blank:] [:cntrl:] +[:digit:] [:graph:] [:lower:] [:print:] +[:punct:] [:space:] [:upper:] [:xdigit:] +.fi +so that one can say `[[:lower:]]' instead of `[a-z]', and have +things work in Denmark, too, where there are three letters past `z' +in the alphabet. +These character classes are defined by the LC_CTYPE category +in the current locale. + +(v) Collating symbols, like `[.ch.]' or `[.a-acute.]', +where the string between `[.' and `.]' is a collating +element defined for the current locale. Note that this may +be a multi-character element. + +(vi) Equivalence class expressions, like `[=a=]', +where the string between `[=' and `=]' is any collating +element from its equivalence class, as defined for the +current locale. For example, `[[=a=]]' might be equivalent +to `[aáàäâ]' (warning: Latin-1 here), that is, +to `[a[.a-acute.][.a-grave.][.a-umlaut.][.a-circumflex.]]'. + +.SH "SEE ALSO" +.BR sh (1), +.BR fnmatch (3), +.BR glob (3), +.BR locale (7), +.BR regex (7) diff --git a/man7/hier.7 b/man7/hier.7 new file mode 100644 index 000000000..2b8c21a53 --- /dev/null +++ b/man7/hier.7 @@ -0,0 +1,472 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sun Jul 25 11:05:58 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sat Feb 10 16:18:03 1996 by Urs Thuermann (urs@isnogud.escape.de) +.\" Modified Mon Jun 16 20:02:00 1997 by Nicolás Lichtmaier +.\" Modified Mon Feb 6 16:41:00 1999 by Nicolás Lichtmaier +.\" Modified Tue Feb 8 16:46:45 2000 by Chris Pepper +.\" Modified Fri Sep 7 20:32:45 2001 by Tammy Fox +.TH HIER 7 2001-09-07 "Linux" "Linux Programmer's Manual" +.SH NAME +hier \- Description of the file system hierarchy +.SH DESCRIPTION +A typical Linux system has, among others, the following directories: +.TP +.I / +This is the root directory. This is where the whole tree starts. +.TP +.I /bin +This directory contains executable programs which are needed in +single user mode and to bring the system up or repair it. +.TP +.I /boot +Contains static files for the boot loader. This directory only holds +the files which are needed during the boot process. The map installer +and configuration files should go to +.I /sbin +and +.IR /etc . +.TP +.I /dev +Special or device files, which refer to physical devices. See +mknod(1). +.TP +.I /dos +If both MS\-DOS and Linux are run on one computer, this is a typical +place to mount a DOS file system. +.TP +.I /etc +Contains configuration files which are local to the machine. Some +larger software packages, like X11, can have their own subdirectories +below +.IR /etc . +Site-wide configuration files may be placed here or in +.IR /usr/etc . +Nevertheless, programs should always look for these files in +.I /etc +and you may have links for these files to +.IR /usr/etc . +.TP +.I /etc/opt +Host-specific configuration files for add-on applications installed +in +.IR /opt . +.TP +.I /etc/sgml +This directory contains the configuration files for SGML and XML (optional). +.TP +.I /etc/skel +When a new user account is created, files from this directory are +usually copied into the user's home directory. +.TP +.I /etc/X11 +Configuration files for the X11 window system (optional). +.TP +.I /home +On machines with home directories for users, these are usually beneath +this directory, directly or not. The structure of this directory +depends on local administration decisions. +.TP +.I /lib +This directory should hold those shared libraries that are necessary +to boot the system and to run the commands in the root filesystem. +.TP +.I /mnt +This directory contains mount points for temporarily mounted filesystems +.TP +.I /opt +This directory should contain add-on packages that contain static files. +.TP +.I /proc +This is a mount point for the +.I proc +filesystem, which provides information about running processes and +the kernel. This pseudo-file system is described in more detail in +.BR proc (5). +.TP +.I /root +This directory is usually the home directory for the root user (optional). +.TP +.I /sbin +Like +.IR /bin , +this directory holds commands needed to boot the system, but which are +usually not executed by normal users. +.TP +.I /tmp +This directory contains temporary files which may be deleted with no +notice, such as by a regular job or at system boot up. +.TP +.I /usr +This directory is usually mounted from a separate partition. It +should hold only sharable, read-only data, so that it can be mounted +by various machines running Linux. +.TP +.I /usr/X11R6 +The X\-Window system, version 11 release 6 (optional). +.TP +.I /usr/X11R6/bin +Binaries which belong to the X\-Windows system; often, there is a +symbolic link from the more traditional +.I /usr/bin/X11 +to here. +.TP +.I /usr/X11R6/lib +Data files associated with the X\-Windows system. +.TP +.I /usr/X11R6/lib/X11 +These contain miscellaneous files needed to run X; Often, there is a +symbolic link from +.I /usr/lib/X11 +to this directory. +.TP +.I /usr/X11R6/include/X11 +Contains include files needed for compiling programs using the X11 +window system. Often, there is a symbolic link from +.I /usr/include/X11 +to this directory. +.TP +.I /usr/bin +This is the primary directory for executable programs. Most programs +executed by normal users which are not needed for booting or for +repairing the system and which are not installed locally should be +placed in this directory. +.TP +.I /usr/bin/X11 +is the traditional place to look for X11 executables; on Linux, it +usually is a symbolic link to +.IR /usr/X11R6/bin . +.TP +.I /usr/dict +Replaced by +.IR /usr/share/dict . +.TP +.I /usr/doc +Replaced by +.IR /usr/share/doc . +.TP +.I /usr/etc +Site-wide configuration files to be shared between several machines +may be stored in this directory. However, commands should always +reference those files using the +.I /etc +directory. Links from files in +.I /etc +should point to the appropriate files in +.IR /usr/etc . +.TP +.I /usr/games +Binaries for games and educational programs (optional). +.TP +.I /usr/include +Include files for the C compiler. +.TP +.I /usr/include/X11 +Include files for the C compiler and the X\-Windows system. This is +usually a symbolic link to +.I /usr/X11R6/include/X11. +.TP +.I /usr/include/asm +Include files which declare some assembler functions. This used to be a +symbolic link to +.IR /usr/src/linux/include/asm . +.TP +.I /usr/include/linux +This contains information which may change from system release to +system release and used to be a symbolic link to +.I /usr/src/linux/include/linux +to get at operating system specific information. + +(Note that one should have include files there that work correctly with +the current libc and in user space. However, Linux kernel source is not +designed to be used with user programs and does not know anything +about the libc you are using. It is very likely that things will break +if you let +.I /usr/include/asm +and +.I /usr/include/linux +point at a random kernel tree. Debian systems don't do this +and use headers from a known good kernel +version, provided in the libc*-dev package.) +.TP +.I /usr/include/g++ +Include files to use with the GNU C++ compiler. +.TP +.I /usr/lib +Object libraries, including dynamic libraries, plus some executables +which usually are not invoked directly. More complicated programs may +have whole subdirectories there. +.TP +.I /usr/lib/X11 +The usual place for data files associated with X programs, and +configuration files for the X system itself. On Linux, it usually is +a symbolic link to +.IR /usr/X11R6/lib/X11 . +.TP +.I /usr/lib/gcc-lib +contains executables and include files for the GNU C compiler, +.BR gcc (1). +.TP +.I /usr/lib/groff +Files for the GNU groff document formatting system. +.TP +.I /usr/lib/uucp +Files for +.BR uucp (1). +.TP +.I /usr/local +This is where programs which are local to the site typically go. +.TP +.I /usr/local/bin +Binaries for programs local to the site. +.TP +.I /usr/local/doc +Local documentation. +.TP +.I /usr/local/etc +Configuration files associated with locally installed programs. +.TP +.I /usr/local/games +Binaries for locally installed games. +.TP +.I /usr/local/lib +Files associated with locally installed programs. +.TP +.I /usr/local/include +Header files for the local C compiler. +.TP +.I /usr/local/info +Info pages associated with locally installed programs. +.TP +.I /usr/local/man +Man pages associated with locally installed programs. +.TP +.I /usr/local/sbin +Locally installed programs for system administration. +.TP +.I /usr/local/share +Local application data that can be shared among different architectures +of the same OS. +.TP +.I /usr/local/src +Source code for locally installed software. +.TP +.I /usr/man +Replaced by +.IR /usr/share/man . +.TP +.I /usr/sbin +This directory contains program binaries for system administration +which are not essential for the boot process, for mounting +.IR /usr , +or for system repair. +.TP +.I /usr/share +This directory contains subdirectories with specific application data, that +can be shared among different architectures of the same OS. +Often one finds stuff here that used to live in +.I /usr/doc +or +.I /usr/lib +or +.IR /usr/man . +.TP +.I /usr/share/dict +Contains the word lists used by spell checkers. +.TP +.I /usr/share/doc +Documentation about installed programs. +.TP +.I /usr/share/games +Static data files for games in +.IR /usr/games . +.TP +.I /usr/share/info +Info pages go here. +.TP +.I /usr/share/locale +Locale information goes here. +.TP +.I /usr/share/man +Manpages go here in subdirectories according to the man page sections. +.TP +.I /usr/share/man//man[1-9] +These directories contain manual pages for the specific locale in source code +form. Systems which use a unique language and code set for all manual pages +may omit the substring. +.TP +.I /usr/share/misc +Miscellaneous data that can be shared among different architectures of the +same OS. +.TP +.I /usr/share/nls +The message catalogs for native language support go here. +.TP +.I /usr/share/sgml +Files for SGML and XML. +.TP +.I /usr/share/terminfo +The datebase for terminfo. +.TP +.I /usr/share/tmac +Troff macros that are not distributed with groff. +.TP +.I /usr/share/zoneinfo +Files for timezone information. +.TP +.I /usr/src +Source files for different parts of the system, included with some packages +for reference purposes. Don't work here with your own projects, as files +below /usr should be read-only except when installing software. +.TP +.I /usr/src/linux +This was the traditional place for the kernel source. +Some distributions put here the source for the default kernel they ship. +You should probably use another directory when building your own kernel. +.TP +.I /usr/tmp +Obsolete. This should be a link +to +.IR /var/tmp . +This link is present only for compatibility reasons and shouldn't be used. +.TP +.I /var +This directory contains files which may change in size, such as spool +and log files. +.TP +.I /var/adm +This directory is superseded by +.I /var/log +and should be a symbolic link to +.IR /var/log . +.TP +.I /var/backups +Reserved for historical reasons. +.TP +.I /var/cache +Data cached for programs. +.TP +.IR /var/catman/cat[1-9] " or " /var/cache/man/cat[1-9] +These directories contain preformatted manual pages according to their +man page section. (The use of preformatted manual pages is deprecated.) +.TP +.I /var/cron +Reserved for historical reasons. +.TP +.I /var/lib +Variable state information for programs. +.TP +.I /var/local +Variable data for +.IR /usr/local . +.TP +.I /var/lock +Lock files are placed in this directory. The naming convention for +device lock files is +.I LCK.. +where +.I +is the device's name in the filesystem. +The format used is that of HDU UUCP lock files, i.e. lock files +contain a PID as a 10-byte ASCII decimal number, followed by a newline +character. +.TP +.I /var/log +Miscellaneous log files. +.TP +.I /var/opt +Variable data for +.IR /opt . +.TP +.I /var/mail +Users' mailboxes. Replaces +.IR /var/spool/mail . +.TP +.I /var/msgs +Reserved for historical reasons. +.TP +.I /var/preserve +Reserved for historical reasons. +.TP +.I /var/run +Run-time variable files, like files holding process identifiers (PIDs) +and logged user information +.IR (utmp) . +Files in this directory are usually cleared when the system boots. +.TP +.I /var/spool +Spooled (or queued) files for various programs. +.TP +.I /var/spool/at +Spooled jobs for +.BR at (1). +.TP +.I /var/spool/cron +Spooled jobs for +.BR cron (1). +.TP +.I /var/spool/lpd +Spooled files for printing. +.TP +.I /var/spool/mail +Replaced by +.IR /var/mail . +.TP +.I /var/spool/mqueue +Queued outgoing mail. +.TP +.I /var/spool/news +Spool directory for news. +.TP +.I /var/spool/rwho +Spooled files for +.BR rwhod (8). +.TP +.I /var/spool/smail +Spooled files for the +.BR smail (1) +mail delivery program. +.TP +.I /var/spool/uucp +Spooled files for +.BR uucp (1). +.TP +.I /var/tmp +Like +.IR /tmp , +this directory holds temporary files stored for an unspecified duration. +.TP +.I /var/yp +Database files for NIS. +.SH "CONFORMS TO" +The Filesystem Hierarchy Standard, Version 2.2 +.SH BUGS +This list is not exhaustive; different systems may be configured +differently. +.SH "SEE ALSO" +.BR find (1), +.BR ln (1), +.BR mount (1), +.BR proc (5) + +The Filesystem Hierarchy Standard diff --git a/man7/icmp.7 b/man7/icmp.7 new file mode 100644 index 000000000..b6f3931df --- /dev/null +++ b/man7/icmp.7 @@ -0,0 +1,116 @@ +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" $Id: icmp.7,v 1.6 2000/08/14 08:03:45 ak Exp $ +.TH ICMP 7 1999-04-27 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +icmp, IPPROTO_ICMP \- Linux IPv4 ICMP kernel module. +.SH DESCRIPTION +This kernel protocol module implements the Internet Control Message Protocol +defined in RFC792. It is used to signal error conditions and for diagnosis. +The user doesn't interact directly with this module; instead it communicates +with the other protocols in the kernel and these pass the ICMP +errors to the application layers. The kernel ICMP module also +answers ICMP requests. +.PP +A user protocol may receive ICMP packets for all local sockets by opening +a raw socket with the protocol +.BR IPPROTO_ICMP . +See +.BR raw (7) +for more information. +The types of ICMP packets passed to the socket can be filtered using the +.B ICMP_FILTER +socket option. ICMP packets are always processed by the kernel too, even +when passed to a user socket. +.LP +Linux limits the rate of ICMP error packets to each destination. +.B ICMP_REDIRECT +and +.B ICMP_DEST_UNREACH +are also limited by the destination route of the incoming packets. +.SH SYSCTLS +ICMP supports a sysctl interface to configure some global IP parameters. +The sysctls can be accessed by reading or writing the +.B /proc/sys/net/ipv4/* +files or with the +.BR sysctl (2) +interface. Most of these sysctls are rate limitations for specific ICMP types. +Linux 2.2 uses a token bucket filter to limit ICMPs. +.\" XXX better description needed +The value is the timeout in jiffies until the token bucket filter is cleared +after a burst. A jiffy is a system dependent unit, usually 10ms on x86 and +about 1ms on alpha and IA64. +.TP +.B icmp_destunreach_rate +Maximum rate to send ICMP Destination Unreachable packets. This limits the +rate at which packets are sent to any individual route or destination. +The limit does not affect sending of +.B ICMP_FRAG_NEEDED +packets needed for path MTU discovery. +.TP +.B icmp_echo_ignore_all +If this value is non-zero, Linux will ignore all +.B ICMP_ECHO +requests. +.TP +.B icmp_echo_ignore_broadcasts +If this value is non-zero, Linux will ignore all +.B ICMP_ECHO +packets sent to broadcast addresses. +.TP +.B icmp_echoreply_rate +Maximum rate for sending +.B ICMP_ECHOREPLY +packets in response to +.B ICMP_ECHOREQUEST +packets. +.TP +.B icmp_paramprob_rate +Maximum rate for sending +.B ICMP_PARAMETERPROB +packets. +These packets are sent when a packet arrives with an invalid IP header. +.TP +.B icmp_timeexceed_rate +Maximum rate for sending +.B ICMP_TIME_EXCEEDED +packets. These packets are +sent to prevent loops when a packet has crossed too many hops. +.SH NOTES +As many other implementations don't support +.B IPPROTO_ICMP +raw sockets, this feature +should not be relied on in portable programs. +.\" not really true ATM +.\" .PP +.\" Linux ICMP should be compliant to RFC1122. +.PP +.B ICMP_REDIRECT +packets are not sent when Linux is not acting as a router. +They are also only accepted from the old gateway defined in the routing table and +the redirect routes are expired after some time. +.PP +The 64-bit timestamp returned by +.B ICMP_TIMESTAMP +is in milliseconds since January 1, 1970. +.PP +Linux ICMP internally uses a raw socket to send ICMPs. This raw socket +may appear in +.BR netstat (8) +output with a zero inode. +.PP +.SH VERSIONS +Support for the +.B ICMP_ADDRESS +request was removed in 2.2. +.PP +Support for +.B ICMP_SOURCE_QUENCH +was removed in Linux 2.2. +.SH "SEE ALSO" +.BR ip (7) +.PP +RFC792 for a description of the ICMP protocol. diff --git a/man7/intro.7 b/man7/intro.7 new file mode 100644 index 000000000..1f12b3b24 --- /dev/null +++ b/man7/intro.7 @@ -0,0 +1,36 @@ +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de), Fri Apr 2 11:32:09 MET DST +.\" 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified by Thomas Koenig (ig25@rz.uni-karlsruhe.de) 24 Apr 1993 +.\" Modified Sat Jul 24 17:28:08 1993 by Rik Faith (faith@cs.unc.edu) +.TH INTRO 7 1993-04-23 "Linux" "Linux Programmer's Manual" +.SH NAME +intro \- Introduction to conventions and miscellany section +.SH DESCRIPTION +This chapter describes conventions and protocols, +character set standards, the standard file system layout, +and miscellaneous other things. +.SH AUTHORS +Look at the header of the manual page for the author(s) and copyright +conditions. Note that these can be different from page to page! diff --git a/man7/ip.7 b/man7/ip.7 new file mode 100644 index 000000000..6d2f4ce79 --- /dev/null +++ b/man7/ip.7 @@ -0,0 +1,921 @@ +'\" t +.\" Don't change the line above. it tells man that tbl is needed. +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" $Id: ip.7,v 1.19 2000/12/20 18:10:31 ak Exp $ +.TH IP 7 2001-06-19 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +ip \- Linux IPv4 protocol implementation +.SH SYNOPSIS +.B #include +.br +.\" .B #include -- does not exist anymore +.\" .B #include -- never include +.B #include +.br +.B #include \fR/* superset of previous */ +.sp +.IB tcp_socket " = socket(PF_INET, SOCK_STREAM, 0);" +.br +.IB raw_socket " = socket(PF_INET, SOCK_RAW, " protocol ");" +.br +.IB udp_socket " = socket(PF_INET, SOCK_DGRAM, " protocol ");" +.SH DESCRIPTION +Linux implements the Internet Protocol, version 4, +described in RFC791 and RFC1122. +.B ip +contains a level 2 +multicasting implementation conforming to RFC1112. It also contains an IP +router including a packet filter. +.\" XXX: has someone verified that 2.1 is really 1812 compliant? +.PP +The programmer's interface is BSD sockets compatible. +For more information on sockets, see +.BR socket (7). +.PP +An IP socket is created by calling the +.BR socket (2) +function as +.BR "socket(PF_INET, socket_type, protocol)" . +Valid socket types are +.B SOCK_STREAM +to open a +.BR tcp (7) +socket, +.B SOCK_DGRAM +to open a +.BR udp (7) +socket, or +.B SOCK_RAW +to open a +.BR raw (7) +socket to access the IP protocol directly. +.I protocol +is the IP protocol in the IP header to be received or sent. The only valid +values for +.I protocol +are +.B 0 +and +.B IPPROTO_TCP +for TCP sockets and +.B 0 +and +.B IPPROTO_UDP +for UDP sockets. For +.B SOCK_RAW +you may specify +a valid IANA IP protocol defined in +RFC1700 +assigned numbers. +.PP +.\" XXX ip current does an autobind in listen, but I'm not sure if that should +.\" be documented. +When a process wants to receive new incoming packets or connections, it +should bind a socket to a local interface address using +.BR bind (2). +Only one IP socket may be bound to any given local (address, port) pair. +When +.B INADDR_ANY +is specified in the bind call the socket will be bound to +.I all +local interfaces. When +.BR listen (2) +or +.BR connect (2) +are called on a unbound socket the socket is automatically bound to a +random free port with the local address set to +.BR INADDR_ANY . + +A TCP local socket address that has been bound is unavailable for some time after closing, +unless the +.B SO_REUSEADDR +flag has been set. Care should be taken when using this flag as it +makes TCP less reliable. + +.SH "ADDRESS FORMAT" +An IP socket address is defined as a combination of an IP interface address +and a port number. The basic IP protocol does not supply port numbers, they +are implemented by higher level protocols like +.BR udp (7) +and +.BR tcp (7). +On raw sockets +.B sin_port +is set to the IP protocol. + +.PP +.RS +.nf +.ta 4n 19n 31n +struct sockaddr_in { + sa_family_t sin_family; /* address family: AF_INET */ + u_int16_t sin_port; /* port in network byte order */ + struct in_addr sin_addr; /* internet address */ +}; + +/* Internet address. */ +struct in_addr { + u_int32_t s_addr; /* address in network byte order */ +}; +.ta +.fi +.RE +.PP +.I sin_family +is always set to +.BR AF_INET . +This is required; in Linux 2.2 most networking functions return +.B EINVAL +when this setting is missing. +.I sin_port +contains the port in network byte order. The port numbers below 1024 are called +.IR "reserved ports" . +Only processes with effective user id 0 or the +.B CAP_NET_BIND_SERVICE +capability may +.BR bind (2) +to these sockets. Note that the raw IPv4 protocol as such has no concept of a +port, they are only implemented by higher protocols like +.BR tcp (7) +and +.BR udp (7). +.PP +.I sin_addr +is the IP host address. +The +.I addr +member of +.B struct in_addr +contains the host interface address in network order. +.B in_addr +should be only accessed using the +.BR inet_aton (3), +.BR inet_addr (3), +.BR inet_makeaddr (3) +library functions or directly with the name resolver (see +.BR gethostbyname (3)). +IPv4 addresses are divided into unicast, broadcast +and multicast addresses. Unicast addresses specify a single interface of a host, +broadcast addresses specify all hosts on a network and multicast addresses +address all hosts in a multicast group. Datagrams to broadcast addresses +can be only sent or received when the +.B SO_BROADCAST +socket flag is set. +In the current implementation connection oriented sockets are only allowed +to use unicast addresses. +.\" Leave a loophole for XTP @) + +Note that the address and the port are always stored in network order. +In particular, this means that you need to call +.BR htons (3) +on the number that is assigned to a port. All address/port manipulation +functions in the standard library work in network order. + +There are several special addresses: +.B INADDR_LOOPBACK +(127.0.0.1) +always refers to the local host via the loopback device; +.B INADDR_ANY +(0.0.0.0) +means any address for binding; +.B INADDR_BROADCAST +(255.255.255.255) +means any host and has the same effect on bind as +.B INADDR_ANY +for historical reasons. + +.SH "SOCKET OPTIONS" + +IP supports some protocol specific socket options that can be set with +.BR setsockopt (2) +and read with +.BR getsockopt (2). +The socket option level for IP is +.BR SOL_IP . +A boolean integer flag is zero when it is false, otherwise true. + +.TP +.B IP_OPTIONS +Sets or get the IP options to be sent with every packet from this +socket. The arguments are a pointer to a memory buffer containing the options +and the option length. +The +.BR setsockopt (2) +call sets the IP options associated with a socket. +The maximum option size for IPv4 is 40 bytes. See RFC791 for the allowed +options. When the initial connection request packet for a +.B SOCK_STREAM +socket contains IP options, the IP options will be set automatically +to the options from the initial packet with routing headers reversed. +Incoming packets are not allowed to change options after the connection +is established. +The processing of all incoming source routing options +is disabled by default and can be enabled by using the +.B accept_source_route +sysctl. Other options like timestamps are still handled. +For datagram sockets, IP options can be only set by the local user. +Calling +.BR getsockopt (2) +with +.I IP_OPTIONS +puts the current IP options used for sending into the supplied buffer. + +.TP +.B IP_PKTINFO +Pass an +.I IP_PKTINFO +ancillary message that contains a +.B pktinfo +structure that supplies some information about the incoming packet. +This only works for datagram oriented sockets. +The argument is a flag that tells the socket whether the IP_PKTINFO message +should be passed or not. The message itself can only be sent/retrieved +as control message with a packet using +.BR recvmsg (2) +or +.BR sendmsg (2). + +.IP +.RS +.ta 4n 19n 33n +.nf +struct in_pktinfo { + unsigned int ipi_ifindex; /* Interface index */ + struct in_addr ipi_spec_dst; /* Local address */ + struct in_addr ipi_addr; /* Header Destination address */ +}; +.fi +.RE +.IP +.\" XXX elaborate on that. +.B ipi_ifindex +is the unique index of the interface the packet was received on. +.B ipi_spec_dst +is the local address of the packet and +.B ipi_addr +is the destination address in the packet header. +If +.I IP_PKTINFO +is passed to +.BR sendmsg (2) +and +.\" This field is grossly misnamed +.B ipi_spec_dst +is not zero, then it is used as the local source address for the routing +table lookup and for setting up IP source route options. +When +.B ipi_ifindex +is not zero the primary local address of the interface specified by the +index overwrites +.I ipi_spec_dst +for the routing table lookup. +.TP +.B IP_RECVTOS +If enabled the +.I IP_TOS +ancillary message is passed with incoming packets. It contains a byte which +specifies the Type of Service/Precedence field of the packet header. +Expects a boolean integer flag. + +.TP +.B IP_RECVTTL +When this flag is set +pass a +.I IP_RECVTTL +control message with the time to live +field of the received packet as a byte. Not supported for +.B SOCK_STREAM +sockets. + +.TP +.B IP_RECVOPTS +Pass all incoming IP options to the user in a +.I IP_OPTIONS +control message. The routing header and other options are already filled in +for the local host. Not supported for +.I SOCK_STREAM +sockets. + +.TP +.B IP_RETOPTS +Identical to +.I IP_RECVOPTS +but returns raw unprocessed options with timestamp and route record +options not filled in for this hop. + +.TP +.B IP_TOS +Set or receive the Type-Of-Service (TOS) field that is sent with every IP packet +originating from this socket. It is used to prioritize packets on the network. +TOS is a byte. There are some standard TOS flags defined: +.B IPTOS_LOWDELAY +to minimize delays for interactive traffic, +.B IPTOS_THROUGHPUT +to optimize throughput, +.B IPTOS_RELIABILITY +to optimize for reliability, +.B IPTOS_MINCOST +should be used for "filler data" where slow transmission doesn't matter. +At most one of these TOS values can be specified. Other bits are invalid and +shall be cleared. +Linux sends +.B IPTOS_LOWDELAY +datagrams first by default, +but the exact behaviour depends on the configured queueing discipline. +.\" XXX elaborate on this +Some high priority levels may require an effective user id of 0 or the +.B CAP_NET_ADMIN +capability. +The priority can also be set in a protocol independent way by the +.RB ( SOL_SOCKET ", " SO_PRIORITY ) +socket option (see +.BR socket (7)). + +.TP +.B IP_TTL +Set or retrieve the current time to live field that is send in every packet +send from this socket. + +.TP +.B IP_HDRINCL +If enabled +the user supplies an ip header in front of the user data. Only valid +for +.B SOCK_RAW +sockets. See +.BR raw (7) +for more information. When this flag is enabled the values set by +.IR IP_OPTIONS , +.I IP_TTL +and +.I IP_TOS +are ignored. + +.TP +.BR IP_RECVERR " (defined in )" +Enable extended reliable error message passing. +When enabled on a datagram socket all +generated errors will be queued in a per-socket error queue. When the user +receives an error from a socket operation the errors can +be received by calling +.BR recvmsg (2) +with the +.B MSG_ERRQUEUE +flag set. The +.B sock_extended_err +structure describing the error will be passed in a ancillary message with +the type +.I IP_RECVERR +and the level +.BR SOL_IP . +This is useful for reliable error handling on unconnected sockets. +The received data portion of the error queue +contains the error packet. +.IP +The +.I IP_RECVERR +control message contains a +.B sock_extended_err +structure: +.IP +.RS +.ne 18 +.nf +.ta 4n 20n 32n +#define SO_EE_ORIGIN_NONE 0 +#define SO_EE_ORIGIN_LOCAL 1 +#define SO_EE_ORIGIN_ICMP 2 +#define SO_EE_ORIGIN_ICMP6 3 + +struct sock_extended_err { + u_int32_t ee_errno; /* error number */ + u_int8_t ee_origin; /* where the error originated */ + u_int8_t ee_type; /* type */ + u_int8_t ee_code; /* code */ + u_int8_t ee_pad; + u_int32_t ee_info; /* additional information */ + u_int32_t ee_data; /* other data */ + /* More data may follow */ +}; + +struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *); +.ta +.fi +.RE +.IP +.B ee_errno +contains the errno number of the queued error. +.B ee_origin +is the origin code of where the error originated. +The other fields are protocol specific. The macro +.B SO_EE_OFFENDER +returns a pointer to the address of the network object +where the error originated from given a pointer to the ancillary message. +If this address is not known, the +.I sa_family +member of the +.B sockaddr +contains +.B AF_UNSPEC +and the other fields of the +.B sockaddr +are undefined. +.IP +IP uses the +.B sock_extended_err +structure as follows: +.I ee_origin +is set to +.B SO_EE_ORIGIN_ICMP +for errors received as an ICMP packet, or +.B SO_EE_ORIGIN_LOCAL +for locally generated errors. Unknown values should be ignored. +.I ee_type +and +.I ee_code +are set from the type and code fields of the ICMP header. +.I ee_info +contains the discovered MTU for +.B EMSGSIZE +errors. The message also contains the +.I sockaddr_in of the node +caused the error, which can be accessed with the +.B SO_EE_OFFENDER +macro. The +.I sin_family +field of the SO_EE_OFFENDER address is +.I AF_UNSPEC +when the source was unknown. +When the error originated from the network, all IP options +.RI ( IP_OPTIONS ", " IP_TTL ", " +etc.) enabled on the socket and contained in the +error packet are passed as control messages. The payload of the packet +causing the error is returned as normal payload. +.\" XXX: is it a good idea to document that? It is a dubious feature. +.\" On +.\" .B SOCK_STREAM +.\" sockets, +.\" .I IP_RECVERR +.\" has slightly different semantics. Instead of +.\" saving the errors for the next timeout, it passes all incoming errors +.\" immediately to the +.\" user. This might be useful for very short-lived TCP connections which +.\" need fast error handling. Use this option with care: it makes TCP unreliable +.\" by not allowing it to recover properly from routing shifts and other normal +.\" conditions and breaks the protocol specification. +Note that TCP has no error queue; +.B MSG_ERRQUEUE +is illegal on +.B SOCK_STREAM +sockets. +Thus all errors are returned by socket function return or +.B SO_ERROR +only. +.IP +For raw sockets, +.I IP_RECVERR +enables passing of all received ICMP errors to the +application, otherwise errors are only reported on connected sockets +.IP +It sets or retrieves an integer boolean flag. +.I IP_RECVERR +defaults to off. + +.TP +.B IP_MTU_DISCOVER +Sets or receives the Path MTU Discovery setting +for a socket. When enabled, Linux will perform Path MTU Discovery +as defined in RFC1191 +on this socket. The don't fragment flag is set on all outgoing datagrams. +The system-wide default is controlled by the +.B ip_no_pmtu_disc +sysctl for +.B SOCK_STREAM +sockets, and disabled on all others. For non +.B SOCK_STREAM +sockets it is the user's responsibility to packetize the data +in MTU sized chunks and to do the retransmits if necessary. +The kernel will reject packets that are bigger than the known +path MTU if this flag is set (with +.B EMSGSIZE +). + +.TS +tab(:); +c l +l l. +Path MTU discovery flags:Meaning +IP_PMTUDISC_WANT:Use per-route settings. +IP_PMTUDISC_DONT:Never do Path MTU Discovery. +IP_PMTUDISC_DO:Always do Path MTU Discovery. +.TE + + +When PMTU discovery is enabled the kernel automatically keeps track of +the path MTU per destination host. +When it is connected to a specific peer with +.BR connect (2) +the currently known path MTU can be retrieved conveniently using the +.B IP_MTU +socket option (e.g. after a +.B EMSGSIZE +error occurred). It may change over time. +For connectionless sockets with many destinations +the new also MTU for a given destination can also be accessed using the +error queue (see +.BR IP_RECVERR ). +A new error will be queued for every incoming MTU update. + +While MTU discovery is in progress initial packets from datagram sockets +may be dropped. Applications using UDP should be aware of this and not +take it into account for their packet retransmit strategy. + +To bootstrap the path MTU discovery process on unconnected sockets it +is possible to start with a big datagram size +(up to 64K-headers bytes long) and let it shrink by updates of the path MTU. +.\" XXX this is an ugly hack + +To get an initial estimate of the +path MTU connect a datagram socket to the destination address using +.BR connect (2) +and retrieve the MTU by calling +.BR getsockopt (2) +with the +.B IP_MTU +option. + +.TP +.B IP_MTU +Retrieve the current known path MTU of the current socket. +Only valid when the socket has been connected. Returns an integer. Only valid +as a +.BR getsockopt (2). +.\" +.TP +.B IP_ROUTER_ALERT +Pass all to-be forwarded packets with the +IP Router Alert +option +set to this socket. Only valid for raw sockets. This is useful, for instance, for user +space RSVP daemons. The tapped packets are not forwarded by the kernel, it is +the users responsibility to send them out again. Socket binding is ignored, +such packets are only filtered by protocol. +Expects an integer flag. +.\" +.TP +.B IP_MULTICAST_TTL +Set or reads the time-to-live value of outgoing multicast packets for this +socket. It is +very important for multicast packets to set the smallest TTL possible. +The default is 1 which means that multicast packets don't leave the local +network unless the user program explicitly requests it. Argument is an +integer. +.\" +.TP +.B IP_MULTICAST_LOOP +Sets or reads a boolean integer argument whether sent multicast packets should be +looped back to the local sockets. +.\" +.TP +.B IP_ADD_MEMBERSHIP +Join a multicast group. Argument is a +.B struct ip_mreqn +structure. +.PP +.RS +.nf +.ta 4n 19n 34n +struct ip_mreqn { + struct in_addr imr_multiaddr; /* IP multicast group address */ + struct in_addr imr_address; /* IP address of local interface */ + int imr_ifindex; /* interface index */ +}; +.fi +.RE +.IP +.I imr_multiaddr +contains the address of the multicast group the application wants to join or leave. +It must be a valid multicast address. +.I imr_address +is the address of the local interface with which the system should join the multicast +group; if it is equal to +.B INADDR_ANY +an appropriate interface is chosen by the system. +.I imr_ifindex +is the interface index of the interface that should join/leave the +.I imr_multiaddr +group, or 0 to indicate any interface. +.IP +For compatibility, the old +.B ip_mreq +structure is still supported. It differs from +.B ip_mreqn +only by not including +the +.I imr_ifindex +field. Only valid as a +.BR setsockopt (2). +.\" +.TP +.B IP_DROP_MEMBERSHIP +Leave a multicast group. Argument is an +.B ip_mreqn +or +.B ip_mreq +structure similar to +.IR IP_ADD_MEMBERSHIP . +.\" +.TP +.B IP_MULTICAST_IF +Set the local device for a multicast socket. Argument is an +.B ip_mreqn +or +.B ip_mreq +structure similar to +.IR IP_ADD_MEMBERSHIP . +.IP +When an invalid socket option is passed, +.B ENOPROTOOPT +is returned. +.SH SYSCTLS +The IP protocol +supports the sysctl interface to configure some global options. The sysctls +can be accessed by reading or writing the +.B /proc/sys/net/ipv4/* +files or using the +.BR sysctl (2) +interface. +.\" +.TP +.B ip_default_ttl +Set the default time-to-live value of outgoing packets. This can be changed +per socket with the +.I IP_TTL +option. +.\" +.TP +.B ip_forward +Enable IP forwarding with a boolean flag. IP forwarding can be also set on a +per interface basis. +.\" +.TP +.B ip_dynaddr +Enable dynamic socket address and masquerading entry rewriting on interface +address change. This is useful for dialup interface with changing IP addresses. +0 means no rewriting, 1 turns it on and 2 enables verbose mode. +.\" +.TP +.B ip_autoconfig +Not documented. +.\" +.TP +.B ip_local_port_range +Contains two integers that define the default local port range allocated to +sockets. Allocation starts with the first number and ends with the second number. +Note that these should not conflict with the ports used by masquerading (although +the case is handled). Also arbitary choices may cause problems with some +firewall packet filters that make assumptions about the local ports in use. +First number should be at least >1024, better >4096 to avoid clashes with well +known ports and to minimize firewall problems. +.\" +.TP +.B ip_no_pmtu_disc +If enabled, don't do Path MTU Discovery for TCP sockets by default. Path MTU +discovery may fail if misconfigured firewalls (that drop all ICMP packets) or +misconfigured interfaces (e.g., a point-to-point link where the both ends don't +agree on the MTU) are on the path. It is better to fix the broken routers on +the path than to turn off Path MTU Discovery globally, because not doing it +incurs a high cost to the network. +.\" +.TP +.BR ipfrag_high_thresh ", " ipfrag_low_thresh +If the amount of queued IP fragments reaches +.BR ipfrag_high_thresh , +the queue +is pruned down to +.BR ipfrag_low_thresh . +Contains an integer with the number of +bytes. +.TP +.B ip_always_defrag +[New with Kernel 2.2.13; in earlier kernel version the feature was controlled +at compile time by the +.B CONFIG_IP_ALWAYS_DEFRAG +option] + +When this boolean frag is enabled (not equal 0) incoming fragments +(parts of IP packets +that arose when some host between origin and destination decided +that the packets were too large and cut them into pieces) will be +reassembled (defragmented) before being processed, even if they are +about to be forwarded. + +Only enable if running either a firewall that is the sole link +to your network or a transparent proxy; never ever turn on here for a +normal router or host. Otherwise fragmented communication may me disturbed +when the fragments would travel over different links. Defragmentation +also has a large memory and CPU time cost. + +This is automagically turned on when masquerading or transparent +proxying are configured. +.TP +.B neigh/* +See +.BR arp (7). +.\" XXX Document the conf/*/* sysctls +.\" XXX Document the route/* sysctls +.\" XXX document them all +.SH IOCTLS +All ioctls described in +.BR socket (7) +apply to ip. +.PP +The ioctls to configure firewalling are documented in +.BR ipfw (4) +from the +.B ipchains +package. +.PP +Ioctls to configure generic device parameters are described in +.BR netdevice (7). +.\" XXX Add a chapter about multicasting +.SH NOTES +Be very careful with the +.B SO_BROADCAST +option \- it is not privileged in Linux. It is easy to overload the network +with careless broadcasts. For new application protocols +it is better to use a multicast group instead of broadcasting. Broadcasting +is discouraged. +.PP +Some other BSD sockets implementations provide +.I IP_RCVDSTADDR +and +.I IP_RECVIF +socket options to get the destination address and the interface of +received datagrams. Linux has the more general +.I IP_PKTINFO +for the same task. +.PP +.SH ERRORS +.\" XXX document all errors. We should really fix the kernels to give more uniform +.\" error returns (ENOMEM vs ENOBUFS, EPERM vs EACCES etc.) +.TP +.B ENOTCONN +The operation is only defined on a connected socket, but the socket wasn't +connected. +.TP +.B EINVAL +Invalid argument passed. +For send operations this can be caused by sending to a +.I blackhole +route. +.TP +.B EMSGSIZE +Datagram is bigger than an MTU on the path and it cannot be fragmented. +.TP +.B EACCES +The user tried to execute an operation without the necessary permissions. +These include: +Sending a packet to a broadcast address without having the +.B SO_BROADCAST +flag set. +Sending a packet via a +.I prohibit +route. +Modifying firewall settings without +.B CAP_NET_ADMIN +or effective user id 0. +Binding to a reserved port without the +.B CAP_NET_BIND_SERVICE +capacibility or effective user id 0. + +.TP +.B EADDRINUSE +Tried to bind to an address already in use. +.TP +.BR ENOPROTOOPT " and " EOPNOTSUPP +Invalid socket option passed. +.TP +.B EPERM +User doesn't have permission to set high priority, change configuration, +or send signals to the requested process or group. +.TP +.B EADDRNOTAVAIL +A non-existent interface was requested or the requested source address was +not local. +.TP +.B EAGAIN +Operation on a non-blocking socket would block. +.TP +.B ESOCKTNOSUPPORT +The socket is not configured or an unknown socket type was requested. +.TP +.B EISCONN +.BR connect (2) +was called on an already connected socket. +.TP +.B EALREADY +An connection operation on a non-blocking socket is already in progress. +.TP +.B ECONNABORTED +A connection was closed during an +.BR accept (2). +.TP +.B EPIPE +The connection was unexpectedly closed or shut down by the other end. +.TP +.B ENOENT +.B SIOCGSTAMP +was called on a socket where no packet arrived. +.TP +.B EHOSTUNREACH +No valid routing table entry matches the destination address. This error +can be caused by a ICMP message from a remote router or for the local +routing table. +.TP +.B ENODEV +Network device not available or not capable of sending IP. +.TP +.B ENOPKG +A kernel subsystem was not configured. +.TP +.BR ENOBUFS ", " ENOMEM +Not enough free memory. +This often means that the memory allocation is limited by the socket buffer +limits, not by the system memory, but this is not 100% consistent. +.PP +Other errors may be generated by the overlaying protocols; see +.BR tcp (7), +.BR raw (7), +.BR udp (7) +and +.BR socket (7). +.SH VERSIONS +.IR IP_PKTINFO , +.IR IP_MTU , +.IR IP_MTU_DISCOVER , +.IR IP_PKTINFO , +.I IP_RECVERR +and +.I IP_ROUTER_ALERT +are new options in Linux 2.2. +They are also all Linux specific and should not be used in +programs intended to be portable. +.PP +.B struct ip_mreqn +is new in Linux 2.2. Linux 2.0 only supported +.BR ip_mreq . +.PP +The sysctls were introduced with Linux 2.2. +.SH COMPATIBILITY +For compatibility with Linux 2.0, the obsolete +.BI "socket(PF_INET, SOCK_RAW, " protocol ) +syntax is still supported to open a +.BR packet (7) +socket. This is deprecated and should be replaced by +.BI "socket(PF_PACKET, SOCK_RAW, " protocol ) +instead. The main difference is the +new +.B sockaddr_ll +address structure for generic link layer information instead of the old +.BR sockaddr_pkt . +.SH BUGS +There are too many inconsistent error values. +.PP +The ioctls to configure IP-specific interface options and ARP tables are +not described. +.PP +Some versions of glibc forget to declare +.IR in_pktinfo . +Workaround currently is to copy it into your program from this man page. +.PP +Receiving the original destination address with +.B MSG_ERRQUEUE +in +.I msg_name +by +.BR recvmsg (2) +does not work in some 2.2 kernels. +.\" .SH AUTHORS +.\" This man page was written by Andi Kleen. +.SH "SEE ALSO" +.BR recvmsg (2), +.BR sendmsg (2), +.BR ipfw (4), +.BR capabilities (7), +.BR netlink (7), +.BR raw (7), +.BR socket (7), +.BR tcp (7), +.BR udp (7) +.PP +RFC791 for the original IP specification. +.br +RFC1122 for the IPv4 host requirements. +.br +RFC1812 for the IPv4 router requirements. +\" LocalWords: XXX autobind INADDR REUSEADDR diff --git a/man7/ipv6.7 b/man7/ipv6.7 new file mode 100644 index 000000000..b2655a457 --- /dev/null +++ b/man7/ipv6.7 @@ -0,0 +1,266 @@ +.\" This man page is Copyright (C) 2000 Andi Kleen . +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" $Id: ipv6.7,v 1.3 2000/12/20 18:10:31 ak Exp $ +.TH IPV6 7 1999-06-29 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +ipv6, PF_INET6 \- Linux IPv6 protocol implementation +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.sp +.IB tcp6_socket " = socket(PF_INET6, SOCK_STREAM, 0);" +.br +.IB raw6_socket " = socket(PF_INET6, SOCK_RAW, " protocol ");" +.br +.IB udp6_socket " = socket(PF_INET6, SOCK_DGRAM, " protocol ");" +.SH DESCRIPTION +Linux 2.2 optionally implements the Internet Protocol, version 6. +This man page contains a description of the IPv6 basic API as +implemented by the Linux kernel and glibc 2.1. The interface +is based on the BSD sockets interface; see +.BR socket (7). +.PP +The IPv6 API aims to be mostly compatible with the +.BR ip (7) +v4 API. Only differences are described in this man page. +.PP +To bind an +.I AF_INET6 +socket to any process the local address should be copied from the +.B in6addr_any +variable which has +.I in6_addr +type. +In static initializations +.B IN6ADDR_ANY_INIT +may also be used, which expands to a constant expression. +Both of them are in network order. +.PP +The IPv6 loopback address (::1) is available in the global +.B in6addr_loopback +variable. For initializations +.B IN6ADDR_LOOPBACK_INIT +should be used. +.PP +IPv4 connections can be handled with the v6 API by using the v4-mapped-on-v6 +address type; thus a program only needs only to support this API type to +support both protocols. This is handled transparently by the address +handling functions in libc. +.PP +IPv4 and IPv6 share the local port space. When you get an IPv4 connection +or packet to a IPv6 socket its source address will be mapped to v6 and it'll +be mapped to v6. +.SH "ADDRESS FORMAT" +.sp +.RS +.nf +.ta 4n 5n 20n +struct sockaddr_in6 { + u_int16_t sin6_family; /* AF_INET6 */ + u_int16_t sin6_port; /* port number */ + u_int32_t sin6_flowinfo; /* IPv6 flow information */ + struct in6_addr sin6_addr; /* IPv6 address */ + u_int32_t sin6_scope_id; /* Scope id (new in 2.4) */ +}; + +struct in6_addr { + unsigned char s6_addr[16]; /* IPv6 address */ +}; +.ta +.fi +.RE +.sp +.B sin6_family +is always set to +.B AF_INET6; +.B sin6_port +is the protocol port (see +.B sin_port +in +.BR ip (7)); +.B sin6_flowinfo +is the IPv6 flow identifier; +.B sin6_addr +is the 128bit IPv6 address. +.B sin6_scope_id +is an id of depending of on the scope of the address. It is new in Linux 2.4. +Linux only supports it for link scope addresses, in that case +.I sin6_scope_id +contains the interface index (see +.BR netdevice (7)) +.PP +IPv6 supports several address types: unicast to address a single +host, multicast to address a group of hosts, anycast to address the nearest +member of a group of hosts (not implemented in Linux), IPv4-on-IPv6 to +address a IPv4 host, and other reserved address types. +.PP +The address notation for IPv6 is a group of 16 2 digit hexadecimal numbers, +separated with a ':'. '::' stands for a string of 0 bits. Special addresses +are ::1 for loopback and ::FFFF: for IPv4-mapped-on-IPv6. +.PP +The port space of IPv6 is shared with IPv4. +.SH "SOCKET OPTIONS" +IPv6 supports some protocol specific socket options that can be set with +.BR setsockopt (2) +and read with +.BR getsockopt (2). +The socket option level for IPv6 is +.BR IPPROTO_IPV6 . +A boolean integer flag is zero when it is false, otherwise true. +.TP +.B IPV6_UNICAST_HOPS +Set the unicast hop limit for the socket. Argument is an pointer to an +integer. \-1 in the value means use the route default, otherwise it should be +between 0 and 255. +.TP +.B IPV6_MULTICAST_HOPS +Set the multicast hop limit for the socket. Argument is a pointer to an +integer. \-1 in the value means use the route default, otherwise it should be +between 0 and 255. +.TP +.B IPV6_MULTICAST_IF +Set the device for outgoing multicast packets on the socket. +This is only allowed +for +.I SOCK_DGRAM +and +.I SOCK_RAW +socket. +The argument is an pointer to an interface index (see +.BR netdevice (7)) +in an integer. +.TP +.B IPV6_ADDRFORM +Turn an +.I AF_INET6 +socket into a socket of a different address family. Only +.I AF_INET +is currently supported for that. It is only allowed for IPv6 sockets +that are connected and bound to a v4-mapped-on-v6 address. The argument +is a pointer to a integer containing +.B AF_INET. +This is useful to pass v4-mapped sockets as filedescriptors to programs that +don't know how to deal with the IPv6 API. +.TP +.B IPV6_PKTINFO +Set delivery of the +.B IPV6_PKTINFO +control message on incoming datagrams. Only allowed for +.B SOCK_DGRAM +or +.B SOCK_RAW +sockets. Argument is a pointer to a boolean value in an integer. +.TP +.nh +.B IPV6_RTHDR, IPV6_AUTHHDR, IPV6_DSTOPS, IPV6_HOPOPTS, IPV6_FLOWINFO, IPV6_HOPLIMIT +.hy +Set delivery of control messages for incoming datagrams containing extension +headers from the received packet. +.I IPV6_RTHDR +delivers the routing header, +.I IPV6_AUTHHDR +delivers the authentication header, +.I IPV6_DSTOPTS +delivers the destination options, +.I IPV6_HOPOPTS +delivers the hop options, +.I IPV6_FLOWINFO +delivers an integer containing the flow id, +.I IPV6_HOPLIMIT +delivers an integer containing the hop count of the packet. +The control messages have the same type as the socket option. All these +header options can also be set for outgoing packets +by putting the appropriate control message into the control buffer of +.BR sendmsg (2). +Only allowed for +.B SOCK_DGRAM +or +.B SOCK_RAW +sockets. Argument is a pointer to a boolean value. +.TP +.B IPV6_MULTICAST_LOOP +Control whether the socket sees multicast packets that is has send itself. +Argument is a pointer to boolean. +.TP +.B IPV6_ADD_MEMBERSHIP, IPV6_DROP_MEMBERSHIP +Control membership in multicast groups. Argument is a pointer to a +.B struct ipv6_mreq +structure. +.TP +.B IPV6_MTU +Set the MTU to be used for the socket. The MTU is limited by the device +MTU or the path mtu when path mtu discovery is enabled. +Argument is a pointer to integer. +.TP +.B IPV6_MTU_DISCOVER +Control path mtu discovery on the socket. See +.I IP_MTU_DISCOVER +in +.BR ip (7) +for details. +.TP +.B IPV6_RECVERR +Control receiving of asynchronous error options. See +.I IP_RECVERR +in +.BR ip (7) +for details. +Argument is a pointer to boolean. +.TP +.B IPV6_ROUTER_ALERT +Pass all forwarded packets containing an router alert option to this socket. +Only allowed for datagram sockets and for root. Argument is a pointer to +boolean. +.\" FLOWLABEL_MGR, FLOWINFO_SEND +.SH VERSIONS +The older +.I libinet6 +libc5 based IPv6 API implementation for Linux is not described here +and may vary in details. +.PP +Linux 2.4 will break binary compatibility for the sockaddr_in6 for 64bit +hosts by changing the alignment of +.I in6_addr +and adding an additional +.I sin6_scope_id +field. The kernel interfaces stay compatible, but a program including +sockaddr_in6 or in6_addr into other structures may not be. This is not +a problem for 32bit hosts like i386. +.PP +The +.B sin6_flowinfo +field is new in Linux 2.4. It is transparently passed/read by the kernel +when the passed address length contains it. Some programs that pass a +longer address buffer and then check the outgoing address length may break. +.SH "PORTING NOTES" +The +.B sockaddr_in6 +structure is bigger than the generic +.B sockaddr. +Programs that assume that all address types can be stored safely in a +.B struct sockaddr +need to be changed to use +.B struct sockaddr_storage +for that instead. +.SH BUGS +The IPv6 extended API as in RFC2292 is currently only partly implemented; +although the 2.2 kernel has near complete support for receiving options, +the macros for generating IPv6 options are missing in glibc 2.1. +.PP +IPSec support for EH and AH headers is missing. +.PP +Flow label management is not complete and not documented here. +.PP +This man page is not complete. +.SH "SEE ALSO" +.BR cmsg (3), +.BR ip (7) +.PP +RFC2553: IPv6 BASIC API. Linux tries to be compliant to this. +.PP +RFC2460: IPv6 specification. diff --git a/man7/iso-8859-1.7 b/man7/iso-8859-1.7 new file mode 100644 index 000000000..1969dfb2f --- /dev/null +++ b/man7/iso-8859-1.7 @@ -0,0 +1 @@ +.so man7/iso_8859-1.7 diff --git a/man7/iso-8859-15.7 b/man7/iso-8859-15.7 new file mode 100644 index 000000000..a4095d754 --- /dev/null +++ b/man7/iso-8859-15.7 @@ -0,0 +1 @@ +.so man7/iso_8859-15.7 diff --git a/man7/iso-8859-16.7 b/man7/iso-8859-16.7 new file mode 100644 index 000000000..b9c8e9182 --- /dev/null +++ b/man7/iso-8859-16.7 @@ -0,0 +1 @@ +.so man7/iso_8859-16.7 diff --git a/man7/iso-8859-2.7 b/man7/iso-8859-2.7 new file mode 100644 index 000000000..da36668dd --- /dev/null +++ b/man7/iso-8859-2.7 @@ -0,0 +1 @@ +.so man7/iso_8859-2.7 diff --git a/man7/iso-8859-7.7 b/man7/iso-8859-7.7 new file mode 100644 index 000000000..951384c99 --- /dev/null +++ b/man7/iso-8859-7.7 @@ -0,0 +1 @@ +.so man7/iso_8859-7.7 diff --git a/man7/iso-8859-9.7 b/man7/iso-8859-9.7 new file mode 100644 index 000000000..0fcc7d463 --- /dev/null +++ b/man7/iso-8859-9.7 @@ -0,0 +1 @@ +.so man7/iso_8859-9.7 diff --git a/man7/iso_8859-1.7 b/man7/iso_8859-1.7 new file mode 100644 index 000000000..188d20440 --- /dev/null +++ b/man7/iso_8859-1.7 @@ -0,0 +1,176 @@ +'\" t +.\" Copyright 1993-1995 Daniel Quinlan (quinlan@yggdrasil.com) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Slightly rearranged, aeb, 950713 +.\" Updated, dpo, 990531 +.TH ISO_8859-1 7 1999-05-31 "Linux" "Linux Programmer's Manual" +.nh +.SH NAME +iso_8859-1 \- the ISO 8859-1 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). Especially important is +ISO 8859-1, the "Latin Alphabet No. 1", which has become widely +implemented and may already be seen as the de-facto standard ASCII +replacement. +.P +ISO 8859-1 supports the following languages: Afrikaans, Basque, +Catalan, Danish, Dutch, English, Faeroese, Finnish, French, Galician, +German, Icelandic, Irish, Italian, Norwegian, Portuguese, Scottish, +Spanish, and Swedish. +.P +Note that the ISO 8859-1 characters are also the first 256 characters +of ISO 10646 (Unicode). +.SS "ISO 8859 Alphabets" +The full set of ISO 8859 alphabets includes: +.P +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS "ISO 8859-1 Characters" +The following table displays the characters in ISO 8859-1 (Latin-1), +which are printable and unlisted in the +.BR ascii (7) +manual page. The fourth column will only show the proper glyphs +in an environment configured for ISO 8859-1. + +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ¡ INVERTED EXCLAMATION MARK +242 162 A2 ¢ CENT SIGN +243 163 A3 £ POUND SIGN +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 ¥ YEN SIGN +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 © COPYRIGHT SIGN +252 170 AA ª FEMININE ORDINAL INDICATOR +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF ¯ MACRON +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 ´ ACUTE ACCENT +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ¸ CEDILLA +271 185 B9 ¹ SUPERSCRIPT ONE +272 186 BA º MASCULINE ORDINAL INDICATOR +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ¼ VULGAR FRACTION ONE QUARTER +275 189 BD ½ VULGAR FRACTION ONE HALF +276 190 BE ¾ VULGAR FRACTION THREE QUARTERS +277 191 BF ¿ INVERTED QUESTION MARK +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Ð LATIN CAPITAL LETTER ETH +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH TILDE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER Y WITH ACUTE +336 222 DE Þ LATIN CAPITAL LETTER THORN +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 ð LATIN SMALL LETTER ETH +361 241 F1 ñ LATIN SMALL LETTER N WITH TILDE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER Y WITH ACUTE +376 254 FE þ LATIN SMALL LETTER THORN +377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS +.TE +.SH "SEE ALSO" +.BR ascii (7), +.BR iso_8859-15 (7) diff --git a/man7/iso_8859-15.7 b/man7/iso_8859-15.7 new file mode 100644 index 000000000..138f80435 --- /dev/null +++ b/man7/iso_8859-15.7 @@ -0,0 +1,174 @@ +'\" t +.\" Copyright 1993-1995 Daniel Quinlan (quinlan@yggdrasil.com) +.\" Copyright 1999 Dimitri Papadopoulos (dpo@club-internet.fr) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.TH ISO_8859-15 7 1999-05-31 "Linux" "Linux Programmer's Manual" +.nh +.SH NAME +iso_8859-15 \- the ISO 8859-15 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). Especially important is +ISO 8859-1, the "Latin Alphabet No. 1", which has become widely +implemented and may already be seen as the de-facto standard ASCII +replacement. However, it lacks the EURO symbol and does not fully +cover Finnish and French. ISO 8859-15 is a modification of ISO 8859-1 +that covers these needs. +.P +ISO 8859-15 supports the following languages: Albanian, Basque, Breton, +Catalan, Danish, Dutch, English, Estonian, Faroese, Finnish, French, +Frisian, Galician, German, Greenlandic, Icelandic, Irish Gaelic, +Italian, Latin, Luxemburgish, Norwegian, Portuguese, Rhaeto-Romanic, +Scottish Gaelic, Spanish, and Swedish. +.SS "ISO 8859 Alphabets" +The full set of ISO 8859 alphabets includes: +.P +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS "ISO 8859-15 Characters" +The following table displays the characters in ISO 8859-15 (Latin-9), +which are printable and unlisted in the +.BR ascii (7) +manual page. The fourth column will only show the proper glyphs +in an environment configured for ISO 8859-15. + +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ¡ INVERTED EXCLAMATION MARK +242 162 A2 ¢ CENT SIGN +243 163 A3 £ POUND SIGN +244 164 A4 ¤ EURO SIGN +245 165 A5 ¥ YEN SIGN +246 166 A6 ¦ LATIN CAPITAL LETTER S WITH CARON +247 167 A7 § SECTION SIGN +250 168 A8 ¨ LATIN SMALL LETTER S WITH CARON +251 169 A9 © COPYRIGHT SIGN +252 170 AA ª FEMININE ORDINAL INDICATOR +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF ¯ MACRON +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 ´ LATIN CAPITAL LETTER Z WITH CARON +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ¸ LATIN SMALL LETTER Z WITH CARON +271 185 B9 ¹ SUPERSCRIPT ONE +272 186 BA º MASCULINE ORDINAL INDICATOR +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ¼ LATIN CAPITAL LIGATURE OE +275 189 BD ½ LATIN SMALL LIGATURE OE +276 190 BE ¾ LATIN CAPITAL LETTER Y WITH DIAERESIS +277 191 BF ¿ INVERTED QUESTION MARK +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Ð LATIN CAPITAL LETTER ETH +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH TILDE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER Y WITH ACUTE +336 222 DE Þ LATIN CAPITAL LETTER THORN +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 ð LATIN SMALL LETTER ETH +361 241 F1 ñ LATIN SMALL LETTER N WITH TILDE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER Y WITH ACUTE +376 254 FE þ LATIN SMALL LETTER THORN +377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS +.TE +.SH "SEE ALSO" +.BR ascii (7), +.BR iso_8859-1 (7) diff --git a/man7/iso_8859-16.7 b/man7/iso_8859-16.7 new file mode 100644 index 000000000..085929cd5 --- /dev/null +++ b/man7/iso_8859-16.7 @@ -0,0 +1,179 @@ +'\" t +.\" Copyright 2002 Ionel Mugurel Ciobîcã (IMCiobica@netscape.net) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH ISO_8859-16 7 2003-03-05 "Linux" "Linux Programmer's Manual" +.nh +.SH NAME +iso_8859-16 \- the ISO 8859-16 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). ISO 8859-16, the "Latin +Alphabet No. 10" is used to encode Central and Eastern European Latin +characters and is not implemented yet by any program vendors. +.P +ISO 8859-16 supports the following languages: Albanian, Bosnian, +Croatian, English, Finnish, German, Hungarian, Irish, Polish, +Romanian, Slovenian and Serbian. +.P +Also note that the following Cyrillic-based languages have one-to-one +transliterations to Latin 10: Macedonian and Serbian. +.P +.SS "ISO 8859 Alphabets" +The full set of ISO 8859 alphabets includes: +.P +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS "ISO 8859-16 Characters" +The following table displays the characters in ISO 8859-16 (Latin-10), +which are printable and unlisted in the +.BR ascii (7) +manual page. The fourth column will only show the proper glyphs +in an environment configured for ISO 8859-16. + +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ¡ LATIN CAPITAL LETTER A WITH OGONEK +242 162 A2 ¢ LATIN SMALL LETTER A WITH OGONEK +243 163 A3 £ LATIN CAPITAL LETTER L WITH STROKE +244 164 A4 ¤ EURO SIGN +245 165 A5 ¥ DOUBLE LOW-9 QUOTATION MARK +246 166 A6 ¦ LATIN CAPITAL LETTER S WITH CARON +247 167 A7 § SECTION SIGN +250 168 A8 ¨ LATIN SMALL LETTER S WITH CARON +251 169 A9 © COPYRIGHT SIGN +252 170 AA ª LATIN CAPITAL LETTER S WITH COMMA BELOW +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ LATIN CAPITAL LETTER Z WITH ACUTE +255 173 AD ­ SOFT HYPHEN +256 174 AE ® LATIN SMALL LETTER Z WITH ACUTE +257 175 AF ¯ LATIN CAPITAL LETTER Z WITH DOT ABOVE +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² LATIN CAPITAL LETTER C WITH CARON +263 179 B3 ³ LATIN SMALL LETTER L WITH STROKE +264 180 B4 ´ LATIN CAPITAL LETTER Z WITH CARON +265 181 B5 µ LEFT DOUBLE QUOTATION MARK +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ¸ LATIN SMALL LETTER Z WITH CARON +271 185 B9 ¹ LATIN SMALL LETTER C WITH CARON +272 186 BA º LATIN SMALL LETTER S WITH COMMA BELOW +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ¼ LATIN CAPITAL LIGATURE OE +275 189 BD ½ LATIN SMALL LIGATURE OE +276 190 BE ¾ LATIN CAPITAL LETTER Y WITH DIAERESIS +277 191 BF ¿ LATIN SMALL LETTER Z WITH DOT ABOVE +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH BREVE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER C WITH ACUTE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Ð LATIN CAPITAL LETTER D WITH STROKE +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH ACUTE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH DOUBLE ACUTE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × LATIN CAPITAL LETTER S WITH ACUTE +330 216 D8 Ø LATIN CAPITAL LETTER U WITH DOUBLE ACUTE +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER E WITH OGONEK +336 222 DE Þ LATIN CAPITAL LETTER T WITH COMMA BELOW +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH BREVE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER C WITH ACUTE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 ð LATIN SMALL LETTER D WITH STROKE +361 241 F1 ñ LATIN SMALL LETTER N WITH ACUTE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH DOUBLE ACUTE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ LATIN SMALL LETTER S WITH ACUTE +370 248 F8 ø LATIN SMALL LETTER U WITH DOUBLE ACUTE +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER E WITH OGONEK +376 254 FE þ LATIN SMALL LETTER T WITH COMMA BELOW +377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS +.TE +.SH "SEE ALSO" +.BR ascii (7), +.BR iso_8859-1 (7), +.BR iso_8859-15 (7), +.BR iso_8859-2 (7) +.P +Additional information: +.I ISO 8859-16 (Latin 10) Resources +(http://bucovina.chem.tue.nl/fonturi/index-en.html). diff --git a/man7/iso_8859-2.7 b/man7/iso_8859-2.7 new file mode 100644 index 000000000..fb781f912 --- /dev/null +++ b/man7/iso_8859-2.7 @@ -0,0 +1,181 @@ +'\" t +.\" Copyright 1999 Roman Maurer (roman.maurer@hermes.si) +.\" Copyright 1993-1995 Daniel Quinlan (quinlan@yggdrasil.com) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Slightly rearranged, aeb, 950713 +.\" Updated, dpo, 990531 +.TH ISO_8859-2 7 1999-11-13 "Linux" "Linux Programmer's Manual" +.nh +.SH NAME +iso_8859-2 \- the ISO 8859-2 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). ISO 8859-2, the "Latin +Alphabet No. 2" is used to encode Central and Eastern European Latin +characters and is implemented by several program vendors. +.P +ISO 8859-2 supports the following languages: Albanian, Bosnian, +Croatian, Czech, English, Finnish, German, Hungarian, Irish, Polish, +Slovak, Slovenian and Sorbian. +.P +Also note that the following Cyrillic-based languages have one-to-one +transliterations to Latin 2: Macedonian and Serbian. +.P +.SS "ISO 8859 Alphabets" +The full set of ISO 8859 alphabets includes: +.P +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS "ISO 8859-2 Characters" +The following table displays the characters in ISO 8859-2 (Latin-2), +which are printable and unlisted in the +.BR ascii (7) +manual page. The fourth column will only show the proper glyphs +in an environment configured for ISO 8859-2. + +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ¡ LATIN CAPITAL LETTER A WITH OGONEK +242 162 A2 ¢ BREVE +243 163 A3 £ LATIN CAPITAL LETTER L WITH STROKE +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 ¥ LATIN CAPITAL LETTER L WITH CARON +246 166 A6 ¦ LATIN CAPITAL LETTER S WITH ACUTE +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 © LATIN CAPITAL LETTER S WITH CARON +252 170 AA ª LATIN CAPITAL LETTER S WITH CEDILLA +253 171 AB « LATIN CAPITAL LETTER T WITH CARON +254 172 AC ¬ LATIN CAPITAL LETTER Z WITH ACUTE +255 173 AD ­\[shc] SOFT HYPHEN +256 174 AE ® LATIN CAPITAL LETTER Z WITH CARON +257 175 AF ¯ LATIN CAPITAL LETTER Z WITH DOT ABOVE +260 176 B0 ° DEGREE SIGN +261 177 B1 ± LATIN SMALL LETTER A WITH OGONEK +262 178 B2 ² OGONEK +263 179 B3 ³ LATIN SMALL LETTER L WITH STROKE +264 180 B4 ´ ACUTE ACCENT +265 181 B5 µ LATIN SMALL LETTER L WITH CARON +266 182 B6 ¶ LATIN SMALL LETTER S WITH ACUTE +267 183 B7 · CARON +270 184 B8 ¸ CEDILLA +271 185 B9 ¹ LATIN SMALL LETTER S WITH CARON +272 186 BA º LATIN SMALL LETTER S WITH CEDILLA +273 187 BB » LATIN SMALL LETTER T WITH CARON +274 188 BC ¼ LATIN SMALL LETTER Z WITH ACUTE +275 189 BD ½ DOUBLE ACUTE ACCENT +276 190 BE ¾ LATIN SMALL LETTER Z WITH CARON +277 191 BF ¿ LATIN SMALL LETTER Z WITH DOT ABOVE +300 192 C0 À LATIN CAPITAL LETTER R WITH ACUTE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH BREVE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER L WITH ACUTE +306 198 C6 Æ LATIN CAPITAL LETTER C WITH ACUTE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER C WITH CARON +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH OGONEK +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER E WITH CARON +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER D WITH CARON +320 208 D0 Ð LATIN CAPITAL LETTER D WITH STROKE +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH ACUTE +322 210 D2 Ò LATIN CAPITAL LETTER N WITH CARON +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH DOUBLE ACUTE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ø LATIN CAPITAL LETTER R WITH CARON +331 217 D9 Ù LATIN CAPITAL LETTER U WITH RING ABOVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH DOUBLE ACUTE +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER Y WITH ACUTE +336 222 DE Þ LATIN CAPITAL LETTER T WITH CEDILLA +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER R WITH ACUTE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH BREVE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER L WITH ACUTE +346 230 E6 æ LATIN SMALL LETTER C WITH ACUTE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER C WITH CARON +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH OGONEK +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER E WITH CARON +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER D WITH CARON +360 240 F0 ð LATIN SMALL LETTER D WITH STROKE +361 241 F1 ñ LATIN SMALL LETTER N WITH ACUTE +362 242 F2 ò LATIN SMALL LETTER N WITH CARON +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH DOUBLE ACUTE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ø LATIN SMALL LETTER R WITH CARON +371 249 F9 ù LATIN SMALL LETTER U WITH RING ABOVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH DOUBLE ACUTE +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER Y WITH ACUTE +376 254 FE þ LATIN SMALL LETTER T WITH CEDILLA +377 255 FF ÿ DOT ABOVE +.TE +.SH "SEE ALSO" +.BR ascii (7), +.BR iso_8859-1 (7), +.BR iso_8859-16 (7) +.P +Additional information: +.I ISO 8859-2 (Latin 2) Resources +(http://sizif.mf.uni-lj.si/linux/cee/iso8859-2.html). diff --git a/man7/iso_8859-7.7 b/man7/iso_8859-7.7 new file mode 100644 index 000000000..6dc1e48c5 --- /dev/null +++ b/man7/iso_8859-7.7 @@ -0,0 +1,158 @@ +'\" t +.\" Copyright 1999 Dimitri Papadopoulos (dpo@club-internet.fr) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.TH ISO_8859-7 7 1999-05-31 "Linux" "Linux Programmer's Manual" +.nh +.SH NAME +iso_8859-7 \- the ISO 8859-7 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). ISO 8859-7 encodes the +characters used in modern monotonic Greek. +.SS "ISO 8859 Alphabets" +The full set of ISO 8859 alphabets includes: +.P +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS "ISO 8859-7 Characters" +The following table displays the characters in ISO 8859-7, which +are printable and unlisted in the +.BR ascii (7) +manual page. The fourth column will only show the proper glyphs +in an environment configured for ISO 8859-7. + +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ¡ MODIFIER LETTER REVERSED COMMA +242 162 A2 ¢ MODIFIER LETTER APOSTROPHE +243 163 A3 £ POUND SIGN +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 © COPYRIGHT SIGN +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +257 175 AF ¯ HORIZONTAL BAR +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 ´ GREEK TONOS +265 181 B5 µ GREEK DIALYTIKA TONOS +266 182 B6 ¶ GREEK CAPITAL LETTER ALPHA WITH TONOS +267 183 B7 · MIDDLE DOT +270 184 B8 ¸ GREEK CAPITAL LETTER EPSILON WITH TONOS +271 185 B9 ¹ GREEK CAPITAL LETTER ETA WITH TONOS +272 186 BA º GREEK CAPITAL LETTER IOTA WITH TONOS +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ¼ GREEK CAPITAL LETTER OMICRON WITH TONOS +275 189 BD ½ VULGAR FRACTION ONE HALF +276 190 BE ¾ GREEK CAPITAL LETTER UPSILON WITH TONOS +277 191 BF ¿ GREEK CAPITAL LETTER OMEGA WITH TONOS +300 192 C0 À GREEK SMALL LETTER IOTA WITH DIALYTIKA AND TONOS +301 193 C1 Á GREEK CAPITAL LETTER ALPHA +302 194 C2  GREEK CAPITAL LETTER BETA +303 195 C3 à GREEK CAPITAL LETTER GAMMA +304 196 C4 Ä GREEK CAPITAL LETTER DELTA +305 197 C5 Å GREEK CAPITAL LETTER EPSILON +306 198 C6 Æ GREEK CAPITAL LETTER ZETA +307 199 C7 Ç GREEK CAPITAL LETTER ETA +310 200 C8 È GREEK CAPITAL LETTER THETA +311 201 C9 É GREEK CAPITAL LETTER IOTA +312 202 CA Ê GREEK CAPITAL LETTER KAPPA +313 203 CB Ë GREEK CAPITAL LETTER LAMDA +314 204 CC Ì GREEK CAPITAL LETTER MU +315 205 CD Í GREEK CAPITAL LETTER NU +316 206 CE Î GREEK CAPITAL LETTER XI +317 207 CF Ï GREEK CAPITAL LETTER OMICRON +320 208 D0 Ð GREEK CAPITAL LETTER PI +321 209 D1 Ñ GREEK CAPITAL LETTER RHO +323 211 D3 Ó GREEK CAPITAL LETTER SIGMA +324 212 D4 Ô GREEK CAPITAL LETTER TAU +325 213 D5 Õ GREEK CAPITAL LETTER UPSILON +326 214 D6 Ö GREEK CAPITAL LETTER PHI +327 215 D7 × GREEK CAPITAL LETTER CHI +330 216 D8 Ø GREEK CAPITAL LETTER PSI +331 217 D9 Ù GREEK CAPITAL LETTER OMEGA +332 218 DA Ú GREEK CAPITAL LETTER IOTA WITH DIALYTIKA +333 219 DB Û GREEK CAPITAL LETTER UPSILON WITH DIALYTIKA +334 220 DC Ü GREEK SMALL LETTER ALPHA WITH TONOS +335 221 DD Ý GREEK SMALL LETTER EPSILON WITH TONOS +336 222 DE Þ GREEK SMALL LETTER ETA WITH TONOS +337 223 DF ß GREEK SMALL LETTER IOTA WITH TONOS +340 224 E0 à GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND TONOS +341 225 E1 á GREEK SMALL LETTER ALPHA +342 226 E2 â GREEK SMALL LETTER BETA +343 227 E3 ã GREEK SMALL LETTER GAMMA +344 228 E4 ä GREEK SMALL LETTER DELTA +345 229 E5 å GREEK SMALL LETTER EPSILON +346 230 E6 æ GREEK SMALL LETTER ZETA +347 231 E7 ç GREEK SMALL LETTER ETA +350 232 E8 è GREEK SMALL LETTER THETA +351 233 E9 é GREEK SMALL LETTER IOTA +352 234 EA ê GREEK SMALL LETTER KAPPA +353 235 EB ë GREEK SMALL LETTER LAMDA +354 236 EC ì GREEK SMALL LETTER MU +355 237 ED í GREEK SMALL LETTER NU +356 238 EE î GREEK SMALL LETTER XI +357 239 EF ï GREEK SMALL LETTER OMICRON +360 240 F0 ð GREEK SMALL LETTER PI +361 241 F1 ñ GREEK SMALL LETTER RHO +362 242 F2 ò GREEK SMALL LETTER FINAL SIGMA +363 243 F3 ó GREEK SMALL LETTER SIGMA +364 244 F4 ô GREEK SMALL LETTER TAU +365 245 F5 õ GREEK SMALL LETTER UPSILON +366 246 F6 ö GREEK SMALL LETTER PHI +367 247 F7 ÷ GREEK SMALL LETTER CHI +370 248 F8 ø GREEK SMALL LETTER PSI +371 249 F9 ù GREEK SMALL LETTER OMEGA +372 250 FA ú GREEK SMALL LETTER IOTA WITH DIALYTIKA +373 251 FB û GREEK SMALL LETTER UPSILON WITH DIALYTIKA +374 252 FC ü GREEK SMALL LETTER OMICRON WITH TONOS +375 253 FD ý GREEK SMALL LETTER UPSILON WITH TONOS +376 254 FE þ GREEK SMALL LETTER OMEGA WITH TONOS +.TE +.SH HISTORY +ISO 8859-7 was formerly known as ELOT-928 or ECMA-118:1986. +.SH "SEE ALSO" +.BR ascii (7) diff --git a/man7/iso_8859-9.7 b/man7/iso_8859-9.7 new file mode 100644 index 000000000..a15a445cc --- /dev/null +++ b/man7/iso_8859-9.7 @@ -0,0 +1,162 @@ +'\" t +.\" Copyright 2002 Dimitri Papadopoulos (dpo@club-internet.fr) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.TH ISO_8859-9 7 2002-09-24 "Linux" "Linux Programmer's Manual" +.nh +.SH NAME +iso_8859-9 \- the ISO 8859-9 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). ISO 8859-9, also known as +the "Latin Alphabet No. 5", encodes the characters used in Turkish. +.SS "ISO 8859 Alphabets" +The full set of ISO 8859 alphabets includes: +.P +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS "ISO 8859-9 Characters" +The following table displays the characters in ISO 8859-9 (Latin-5), +which are printable and unlisted in the +.BR ascii (7) +manual page. The fourth column will only show the proper glyphs +in an environment configured for ISO 8859-9. + +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ¡ INVERTED EXCLAMATION MARK +242 162 A2 ¢ CENT SIGN +243 163 A3 £ POUND SIGN +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 ¥ YEN SIGN +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 © COPYRIGHT SIGN +252 170 AA ª FEMININE ORDINAL INDICATOR +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF ¯ MACRON +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 ´ ACUTE ACCENT +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ¸ CEDILLA +271 185 B9 ¹ SUPERSCRIPT ONE +272 186 BA º MASCULINE ORDINAL INDICATOR +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ¼ VULGAR FRACTION ONE QUARTER +275 189 BD ½ VULGAR FRACTION ONE HALF +276 190 BE ¾ VULGAR FRACTION THREE QUARTERS +277 191 BF ¿ INVERTED QUESTION MARK +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Ð LATIN CAPITAL LETTER G WITH BREVE +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH TILDE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER I WITH DOT ABOVE +336 222 DE Þ LATIN CAPITAL LETTER S WITH CEDILLA +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 ð LATIN SMALL LETTER G WITH BREVE +361 241 F1 ñ LATIN SMALL LETTER N WITH TILDE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER DOTLESS I +376 254 FE þ LATIN SMALL LETTER S WITH CEDILLA +377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS +.TE +.SH "SEE ALSO" +.BR ascii (7) diff --git a/man7/iso_8859_1.7 b/man7/iso_8859_1.7 new file mode 100644 index 000000000..1969dfb2f --- /dev/null +++ b/man7/iso_8859_1.7 @@ -0,0 +1 @@ +.so man7/iso_8859-1.7 diff --git a/man7/iso_8859_15.7 b/man7/iso_8859_15.7 new file mode 100644 index 000000000..a4095d754 --- /dev/null +++ b/man7/iso_8859_15.7 @@ -0,0 +1 @@ +.so man7/iso_8859-15.7 diff --git a/man7/iso_8859_16.7 b/man7/iso_8859_16.7 new file mode 100644 index 000000000..b9c8e9182 --- /dev/null +++ b/man7/iso_8859_16.7 @@ -0,0 +1 @@ +.so man7/iso_8859-16.7 diff --git a/man7/iso_8859_2.7 b/man7/iso_8859_2.7 new file mode 100644 index 000000000..da36668dd --- /dev/null +++ b/man7/iso_8859_2.7 @@ -0,0 +1 @@ +.so man7/iso_8859-2.7 diff --git a/man7/iso_8859_7.7 b/man7/iso_8859_7.7 new file mode 100644 index 000000000..951384c99 --- /dev/null +++ b/man7/iso_8859_7.7 @@ -0,0 +1 @@ +.so man7/iso_8859-7.7 diff --git a/man7/iso_8859_9.7 b/man7/iso_8859_9.7 new file mode 100644 index 000000000..0fcc7d463 --- /dev/null +++ b/man7/iso_8859_9.7 @@ -0,0 +1 @@ +.so man7/iso_8859-9.7 diff --git a/man7/koi8-r.7 b/man7/koi8-r.7 new file mode 100644 index 000000000..8e60a5b82 --- /dev/null +++ b/man7/koi8-r.7 @@ -0,0 +1,195 @@ +'\" t +.\" Copyright 2001 Alexey Mahotkin +.\" +.\" Lots of text ripped from http://koi8.pp.ru/ +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.TH KOI8-R 7 2001-05-28 "Linux" "Linux Programmer's Manual" +.nh +.SH NAME +koi8-r \- Russian Net Character Set encoded in octal, decimal, and +hexadecimal +.SH DESCRIPTION +KOI8-R is the character set of choice for encoding Russian texts for +many Unix-like operation systems. KOI8-R is a successor for KOI-8, a +de-facto standard for Internet Mail, News, WWW and other interactive +services at least all over the ex-SU territory. +.PP +KOI8-R is defined by RFC1489 (Registration of a Cyrillic Character +Set). + +.SH NOTE +KOI8-R was designed for mixed Russian/English texts and covers +only Russian Cyrillic characters, so if you're looking for Ukrainian, +Byelorussian, etc. Cyrillic characters, try ISO-IR-111, or KOI8-U +(Ukrainian Character Set), or KOI8-C (for ancient Russian texts) +instead, which are identical to KOI8-R in the Russian Cyrillic letters +area. +.PP +A more complete set of Cyrillic characters is also defined by the +ISO-8859-5 character set. + +.SS "KOI8-R Characters" +The following table displays the characters in KOI8-R, which +are printable and unlisted in the +.BR ascii (7) +manual page. + +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +200 128 80 € FORMS LIGHT HORIZONTAL +201 129 81 FORMS LIGHT VERTICAL +202 130 82 ‚ FORMS LIGHT DOWN AND RIGHT +203 131 83 ƒ FORMS LIGHT DOWN AND LEFT +204 132 84 „ FORMS LIGHT UP AND RIGHT +205 133 85 … FORMS LIGHT UP AND LEFT +206 134 86 † FORMS LIGHT VERTICAL AND RIGHT +207 135 87 ‡ FORMS LIGHT VERTICAL AND LEFT +210 136 88 ˆ FORMS LIGHT DOWN AND HORIZONTAL +211 137 89 ‰ FORMS LIGHT UP AND HORIZONTAL +212 138 8A Š FORMS LIGHT VERTICAL AND HORIZONTAL +213 139 8B ‹ UPPER HALF BLOCK +214 140 8C Œ LOWER HALF BLOCK +215 141 8D FULL BLOCK +216 142 8E Ž LEFT HALF BLOCK +217 143 8F RIGHT HALF BLOCK +220 144 90 LIGHT SHADE +221 145 91 ‘ MEDIUM SHADE +222 146 92 ’ DARK SHADE +223 147 93 “ TOP HALF INTEGRAL +224 148 94 ” BLACK SMALL SQUARE +225 149 95 • BULLET OPERATOR +226 150 96 – SQUARE ROOT +227 151 97 — ALMOST EQUAL TO +230 152 98 ˜ LESS THAN OR EQUAL TO +231 153 99 ™ GREATER THAN OR EQUAL TO +232 154 9A š NON-BREAKING SPACE +233 155 9B › BOTTOM HALF INTEGRAL +234 156 9C œ DEGREE SIGN +235 157 9D SUPERSCRIPT DIGIT TWO +236 158 9E ž MIDDLE DOT +237 159 9F Ÿ DIVISION SIGN +240 160 A0   FORMS DOUBLE HORIZONTAL +241 161 A1 ¡ FORMS DOUBLE VERTICAL +242 162 A2 ¢ FORMS DOWN SINGLE AND RIGHT DOUBLE +243 163 A3 £ CYRILLIC SMALL LETTER IO +244 164 A4 ¤ FORMS DOWN DOUBLE AND RIGHT SINGLE +245 165 A5 ¥ FORMS DOUBLE DOWN AND RIGHT +246 166 A6 ¦ FORMS DOWN SINGLE AND LEFT DOUBLE +247 167 A7 § FORMS DOWN DOUBLE AND LEFT SINGLE +250 168 A8 ¨ FORMS DOUBLE DOWN AND LEFT +251 169 A9 © FORMS UP SINGLE AND RIGHT DOUBLE +252 170 AA ª FORMS UP DOUBLE AND RIGHT SINGLE +253 171 AB « FORMS DOUBLE UP AND RIGHT +254 172 AC ¬ FORMS UP SINGLE AND LEFT DOUBLE +255 173 AD ­ FORMS UP DOUBLE AND LEFT SINGLE +256 174 AE ® FORMS DOUBLE UP AND LEFT +257 175 AF ¯ FORMS VERTICAL SINGLE AND RIGHT DOUBLE +260 176 B0 ° FORMS VERTICAL DOUBLE AND RIGHT SINGLE +261 177 B1 ± FORMS DOUBLE VERTICAL AND RIGHT +262 178 B2 ² FORMS VERTICAL SINGLE AND LEFT DOUBLE +263 179 B3 ³ CYRILLIC CAPITAL LETTER IO +264 180 B4 ´ FORMS VERTICAL DOUBLE AND LEFT SINGLE +265 181 B5 µ FORMS DOUBLE VERTICAL AND LEFT +266 182 B6 ¶ FORMS DOWN SINGLE AND HORIZONTAL DOUBLE +267 183 B7 · FORMS DOWN DOUBLE AND HORIZONTAL SINGLE +270 184 B8 ¸ FORMS DOUBLE DOWN AND HORIZONTAL +271 185 B9 ¹ FORMS UP SINGLE AND HORIZONTAL DOUBLE +272 186 BA º FORMS UP DOUBLE AND HORIZONTAL SINGLE +273 187 BB » FORMS DOUBLE UP AND HORIZONTAL +274 188 BC ¼ FORMS VERTICAL SINGLE AND HORIZONTAL DOUBLE +275 189 BD ½ FORMS VERTICAL DOUBLE AND HORIZONTAL SINGLE +276 190 BE ¾ FORMS DOUBLE VERTICAL AND HORIZONTAL +277 191 BF ¿ COPYRIGHT SIGN +300 192 C0 À CYRILLIC SMALL LETTER IU +301 193 C1 Á CYRILLIC SMALL LETTER A +302 194 C2  CYRILLIC SMALL LETTER BE +303 195 C3 à CYRILLIC SMALL LETTER TSE +304 196 C4 Ä CYRILLIC SMALL LETTER DE +305 197 C5 Å CYRILLIC SMALL LETTER IE +306 198 C6 Æ CYRILLIC SMALL LETTER EF +307 199 C7 Ç CYRILLIC SMALL LETTER GE +310 200 C8 È CYRILLIC SMALL LETTER KHA +311 201 C9 É CYRILLIC SMALL LETTER II +312 202 CA Ê CYRILLIC SMALL LETTER SHORT II +313 203 CB Ë CYRILLIC SMALL LETTER KA +314 204 CC Ì CYRILLIC SMALL LETTER EL +315 205 CD Í CYRILLIC SMALL LETTER EM +316 206 CE Î CYRILLIC SMALL LETTER EN +317 207 CF Ï CYRILLIC SMALL LETTER O +320 208 D0 Ð CYRILLIC SMALL LETTER PE +321 209 D1 Ñ CYRILLIC SMALL LETTER IA +322 210 D2 Ò CYRILLIC SMALL LETTER ER +323 211 D3 Ó CYRILLIC SMALL LETTER ES +324 212 D4 Ô CYRILLIC SMALL LETTER TE +325 213 D5 Õ CYRILLIC SMALL LETTER U +326 214 D6 Ö CYRILLIC SMALL LETTER ZHE +327 215 D7 × CYRILLIC SMALL LETTER VE +330 216 D8 Ø CYRILLIC SMALL LETTER SOFT SIGN +331 217 D9 Ù CYRILLIC SMALL LETTER YERI +332 218 DA Ú CYRILLIC SMALL LETTER ZE +333 219 DB Û CYRILLIC SMALL LETTER SHA +334 220 DC Ü CYRILLIC SMALL LETTER REVERSED E +335 221 DD Ý CYRILLIC SMALL LETTER SHCHA +336 222 DE Þ CYRILLIC SMALL LETTER CHE +337 223 DF ß CYRILLIC SMALL LETTER HARD SIGN +340 224 E0 à CYRILLIC CAPITAL LETTER IU +341 225 E1 á CYRILLIC CAPITAL LETTER A +342 226 E2 â CYRILLIC CAPITAL LETTER BE +343 227 E3 ã CYRILLIC CAPITAL LETTER TSE +344 228 E4 ä CYRILLIC CAPITAL LETTER DE +345 229 E5 å CYRILLIC CAPITAL LETTER IE +346 230 E6 æ CYRILLIC CAPITAL LETTER EF +347 231 E7 ç CYRILLIC CAPITAL LETTER GE +350 232 E8 è CYRILLIC CAPITAL LETTER KHA +351 233 E9 é CYRILLIC CAPITAL LETTER II +352 234 EA ê CYRILLIC CAPITAL LETTER SHORT II +353 235 EB ë CYRILLIC CAPITAL LETTER KA +354 236 EC ì CYRILLIC CAPITAL LETTER EL +355 237 ED í CYRILLIC CAPITAL LETTER EM +356 238 EE î CYRILLIC CAPITAL LETTER EN +357 239 EF ï CYRILLIC CAPITAL LETTER O +360 240 F0 ð CYRILLIC CAPITAL LETTER PE +361 241 F1 ñ CYRILLIC CAPITAL LETTER IA +362 242 F2 ò CYRILLIC CAPITAL LETTER ER +363 243 F3 ó CYRILLIC CAPITAL LETTER ES +364 244 F4 ô CYRILLIC CAPITAL LETTER TE +365 245 F5 õ CYRILLIC CAPITAL LETTER U +366 246 F6 ö CYRILLIC CAPITAL LETTER ZHE +367 247 F7 ÷ CYRILLIC CAPITAL LETTER VE +370 248 F8 ø CYRILLIC CAPITAL LETTER SOFT SIGN +371 249 F9 ù CYRILLIC CAPITAL LETTER YERI +372 250 FA ú CYRILLIC CAPITAL LETTER ZE +373 251 FB û CYRILLIC CAPITAL LETTER SHA +374 252 FC ü CYRILLIC CAPITAL LETTER REVERSED E +375 253 FD ý CYRILLIC CAPITAL LETTER SHCHA +376 254 FE þ CYRILLIC CAPITAL LETTER CHE +377 255 FF ÿ CYRILLIC CAPITAL LETTER HARD SIGN + +.TE +.SH "SEE ALSO" +.BR ascii (7), +.BR iso-8859-7 (7) +(not yet written), +RFC1489, +http://koi8.pp.ru/ diff --git a/man7/latin1.7 b/man7/latin1.7 new file mode 100644 index 000000000..1969dfb2f --- /dev/null +++ b/man7/latin1.7 @@ -0,0 +1 @@ +.so man7/iso_8859-1.7 diff --git a/man7/latin10.7 b/man7/latin10.7 new file mode 100644 index 000000000..b9c8e9182 --- /dev/null +++ b/man7/latin10.7 @@ -0,0 +1 @@ +.so man7/iso_8859-16.7 diff --git a/man7/latin2.7 b/man7/latin2.7 new file mode 100644 index 000000000..da36668dd --- /dev/null +++ b/man7/latin2.7 @@ -0,0 +1 @@ +.so man7/iso_8859-2.7 diff --git a/man7/latin5.7 b/man7/latin5.7 new file mode 100644 index 000000000..0fcc7d463 --- /dev/null +++ b/man7/latin5.7 @@ -0,0 +1 @@ +.so man7/iso_8859-9.7 diff --git a/man7/latin9.7 b/man7/latin9.7 new file mode 100644 index 000000000..a4095d754 --- /dev/null +++ b/man7/latin9.7 @@ -0,0 +1 @@ +.so man7/iso_8859-15.7 diff --git a/man7/locale.7 b/man7/locale.7 new file mode 100644 index 000000000..c564a8ebe --- /dev/null +++ b/man7/locale.7 @@ -0,0 +1,204 @@ +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Sat Jul 24 17:28:34 1993 by Rik Faith +.\" Modified Sun Jun 01 17:16:34 1997 by Jochen Hein +.\" +.\" Modified Thu Apr 25 00:43:19 2002 by Bruno Haible +.\" +.TH LOCALE 7 1993-04-24 "Linux" "Linux Programmer's Manual" +.SH NAME +locale \- Description of multi-language support +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +A locale is a set of language and cultural rules. These cover aspects +such as language for messages, different character sets, lexigraphic +conventions, etc. A program needs to be able to determine its locale +and act accordingly to be portable to different cultures. +.PP +The header +.B +declares data types, functions and macros which are useful in this +task. +.PP +The functions it declares are +.B setlocale() +to set the current locale, and +.B localeconv() +to get information about number formatting. +.PP +There are different categories for local information a program might +need; they are declared as macros. Using them as the first argument +to the +.B setlocale() +function, it is possible to set one of these to the desired locale: +.TP +.B LC_COLLATE +This is used to change the behaviour of the functions +.B strcoll() +and +.BR strxfrm() , +which are used to compare strings in the local alphabet. For example, +the German sharp s is sorted as "ss". +.TP +.B LC_CTYPE +This changes the behaviour of the character handling and +classification functions, such as +.B isupper() +and +.BR toupper() , +and the multi\-byte character functions such as +.B mblen() +or +.BR wctomb() . +.TP +.B LC_MONETARY +changes the information returned by +.B localeconv() +which describes the way numbers are usually printed, with details such +as decimal point versus decimal comma. This information is internally +used by the function +.BR strfmon() . +.TP +.B LC_MESSAGES +changes the language messages are displayed in and how an affirmative or +negative answer looks like. The GNU C-library contains the +.BR gettext() , +.BR ngettext() , +and +.B rpmatch() +functions to ease the use of these information. The GNU gettext family of +functions also obey the environment variable +.BR LANGUAGE . +.TP +.B LC_NUMERIC +changes the information used by the +.B printf() +and +.B scanf() +family of functions, when they are advised to use the +locale-settings. This information can also be read with the +.B localeconv() +function. +.TP +.B LC_TIME +changes the behaviour of the +.B strftime() +function to display the current time in a locally acceptable form; for +example, most of Europe uses a 24\-hour clock vs. the US' 12\-hour +clock. +.TP +.B LC_ALL +All of the above. +.PP +If the second argument to +.B setlocale() +is empty string, +.BR """""" , +for the default locale, it is determined using the following steps: +.IP 1. +If there is a non-null environment variable +.BR LC_ALL , +the value of +.B LC_ALL +is used. +.IP 2. +If an environment variable with the same name as one of the categories +above exists and is non-null, its value is used for that category. +.IP 3. +If there is a non-null environment variable +.BR LANG , +the value of +.B LANG +is used. +.PP +Values about local numeric formatting is made available in a +.B struct lconv +returned by the +.B localeconv() +function, which has the following declaration: +.nf +struct lconv +{ + /* Numeric (non-monetary) information. */ + + char *decimal_point; /* Decimal point character. */ + char *thousands_sep; /* Thousands separator. */ + /* Each element is the number of digits in each group; + elements with higher indices are farther left. + An element with value CHAR_MAX means that no further grouping is done. + An element with value 0 means that the previous element is used + for all groups farther left. */ + char *grouping; + + /* Monetary information. */ + + /* First three chars are a currency symbol from ISO 4217. + Fourth char is the separator. Fifth char is '\0'. */ + char *int_curr_symbol; + char *currency_symbol; /* Local currency symbol. */ + char *mon_decimal_point; /* Decimal point character. */ + char *mon_thousands_sep; /* Thousands separator. */ + char *mon_grouping; /* Like `grouping' element (above). */ + char *positive_sign; /* Sign for positive values. */ + char *negative_sign; /* Sign for negative values. */ + char int_frac_digits; /* Int'l fractional digits. */ + char frac_digits; /* Local fractional digits. */ + /* 1 if currency_symbol precedes a positive value, 0 if succeeds. */ + char p_cs_precedes; + /* 1 if a space separates currency_symbol from a positive value. */ + char p_sep_by_space; + /* 1 if currency_symbol precedes a negative value, 0 if succeeds. */ + char n_cs_precedes; + /* 1 if a space separates currency_symbol from a negative value. */ + char n_sep_by_space; + /* Positive and negative sign positions: + 0 Parentheses surround the quantity and currency_symbol. + 1 The sign string precedes the quantity and currency_symbol. + 2 The sign string succeeds the quantity and currency_symbol. + 3 The sign string immediately precedes the currency_symbol. + 4 The sign string immediately succeeds the currency_symbol. */ + char p_sign_posn; + char n_sign_posn; +}; +.fi +.SH "CONFORMS TO" +.nf +POSIX.1 +.fi +The GNU gettext functions are specified in LI18NUX2000. +.SH "SEE ALSO" +.BR locale (1), +.BR localedef (1), +.BR gettext (3), +.BR localeconv (3), +.BR ngettext (3), +.BR nl_langinfo (3), +.BR rpmatch (3), +.BR setlocale (3), +.BR strcoll (3), +.BR strfmon (3), +.BR strftime (3), +.BR strxfrm (3) diff --git a/man7/mailaddr.7 b/man7/mailaddr.7 new file mode 100644 index 000000000..f2f624a36 --- /dev/null +++ b/man7/mailaddr.7 @@ -0,0 +1,114 @@ +.\" +.\" Copyright (c) 1983, 1987 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms are permitted +.\" provided that the above copyright notice and this paragraph are +.\" duplicated in all such forms and that any documentation, +.\" advertising materials, and other materials related to such +.\" distribution and use acknowledge that the software was developed +.\" by the University of California, Berkeley. The name of the +.\" University may not be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" +.\" @(#)mailaddr.7 6.5 (Berkeley) 2/14/89 +.\" +.\" Extensively rewritten by Arnt Gulbrandsen . My +.\" changes are placed under the same copyright as the original BSD page. +.\" +.\" Adjusted by Arnt Gulbrandsen in 2004 to +.\" account for changes since 1995. Route-addrs are now even less +.\" common, etc. Some minor wording improvements. Same copyright. +.\" +.TH MAILADDR 7 2004-09-15 linux "Linux User's Manual" \" -*- nroff -*- +.UC 5 +.SH NAME +mailaddr \- mail addressing description +.SH DESCRIPTION +.nh +This manual page gives a brief introduction to SMTP mail addresses, as +used on the Internet. These addresses are in the general format +.PP + user@domain +.PP +where a domain is a hierarchical dot-separated list of subdomains. +These examples are valid forms of the same address: +.PP + eric@monet.berkeley.edu +.br + Eric Allman +.br + eric@monet.berkeley.edu (Eric Allman) +.PP +The domain part ("monet.berkeley.edu") is a mail-accepting domain. It +can be a host and in the past it usually was, but it doesn't have to +be. The domain part is not case sensitive. +.PP +The local part ("eric") is often a user name, but its meaning is +defined by the local software. Sometimes it is case sensitive, +although that is unusual. If you see a local-part that looks like +garbage, it is usually because of a gateway between an internal e-mail +system and the net, here are some examples: +.PP + "surname/admd=telemail/c=us/o=hp/prmd=hp"@some.where +.br + USER%SOMETHING@some.where +.br + machine!machine!name@some.where +.br + I2461572@some.where +.PP +(These are, respectively, an X.400 gateway, a gateway to an arbitrary +internal mail system that lacks proper internet support, an UUCP +gateway, and the last one is just boring username policy.) +.PP +The real-name part ("Eric Allman") can either be placed before +<>, or in () at the end. (Strictly speaking the two aren't the same, +but the difference is beyond the scope of this page.) The name may +have to be quoted using "", e.g. if it contains ".": +.PP + "Eric P. Allman" +.SS Abbreviation. +.PP +Many mail systems let users abbreviate the domain name. For instance, +users at berkeley.edu may get away with "eric@monet" to send mail to +Eric Allman. +.I "This behavior is deprecated." +Sometimes it works, but you should not depend on it. +.SS Route-addrs. +.PP +In the past, sometimes one had to route route a message through +several hosts to get it to its final destination. Addresses which +show these relays are termed "route-addrs". These use the syntax: +.PP + <@hosta,@hostb:user@hostc> +.PP +This specifies that the message should be sent to hosta, from there +to hostb, and finally to hostc. Many hosts disregard route-addrs +and send directly to hostc. +.PP +Route-addrs are very unusual now. They occur sometimes in old mail +archives. It is generally possible to ignore all but the "user@hostc" +part of the address to determine the actual address. +.SS Postmaster. +.PP +Every site is required to have a user or user alias designated +"postmaster" to which problems with the mail system may be +addressed. The "postmaster" address is not case sensitive. +.SH FILES +.I /etc/aliases +.br +.I ~/.forward +.SH "SEE ALSO" +.BR binmail (1), +.BR mail (1), +.BR mconnect (1), +.BR aliases (5), +.BR forward (5), +.BR sendmail (8), +.BR vrfy (8) + +RFC2822 (Internet Message Format) diff --git a/man7/man.7 b/man7/man.7 new file mode 100644 index 000000000..a0b5f26eb --- /dev/null +++ b/man7/man.7 @@ -0,0 +1,714 @@ +.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler +.\" (faith@cs.unc.edu and dwheeler@ida.org) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified Sun Jul 25 11:06:05 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sat Jun 8 00:39:52 1996 by aeb +.\" Modified Wed Jun 16 23:00:00 1999 by David A. Wheeler (dwheeler@ida.org) +.\" Modified Thu Jul 15 12:43:28 1999 by aeb +.\" [todo: split this into man.7 describing the macros +.\" and manpage.7 describing the Linux man page conventions] +.\" Modified Sun Jan 6 18:26:25 2002 by Martin Schulze +.\" Modified Tue Jul 27 20:12:02 2004 by Colin Watson +.\" +.TH MAN 7 2004-07-27 "Linux" "Linux Programmer's Manual" +.SH NAME +man \- macros to format man pages +.SH SYNOPSIS +.B groff \-Tascii \-man +.I file +\&... +.LP +.B groff \-Tps \-man +.I file +\&... +.LP +.B man +.RI [ section ] +.I title +.SH DESCRIPTION +This manual page explains the +.B "groff tmac.an" +macro package (often called the +.B man +macro package) and related conventions for creating manual (man) pages. +This macro package should be used by developers when +writing or porting man pages for Linux. It is fairly compatible with other +versions of this macro package, so porting man pages should not be a major +problem (exceptions include the NET-2 BSD release, which uses a totally +different macro package called mdoc; see +.BR mdoc (7)). +.PP +Note that NET-2 BSD mdoc man pages can be used with +.B groff +simply by specifying the +.B \-mdoc +option instead of the +.B \-man +option. Using the +.B \-mandoc +option is, however, recommended, since this will automatically detect which +macro package is in use. +.SH PREAMBLE +The first command in a man page (after comment lines) should be +.RS +.sp +.B \&.TH +.IR "title section date source manual" , +.sp +.RE +where: +.RS +.TP 10 +.I title +The title of the man page (e.g., +.IR MAN ). +.TP +.I section +The section number the man page should be placed in (e.g., +.IR 7 ). +.TP +.I date +The date of the last revision\(emremember to change this every time a +change is made to the man page, since this is the most general way of doing +version control. +.TP +.I source +The source of the command. +.sp +For binaries, use something like: +.IR GNU ", " NET-2 ", " "SLS Distribution" ", " "MCC Distribution" . +.sp +For system calls, use the version of the kernel that you are currently +looking at: +.IR "Linux 0.99.11" . +.sp +For library calls, use the source of the function: +.IR GNU ", " "BSD 4.3" ", " "Linux DLL 4.4.1" . +.TP +.I manual +The title of the manual (e.g., +.IR "Linux Programmer's Manual" ). +.RE +.PP +Note that BSD mdoc-formatted pages begin with the +.B Dd +command, not the +.B TH +command. +.PP +The manual sections are traditionally defined as follows: +.RS +.TP 10 +.B 1 Commands +Those commands that can be executed by the user from within +a shell. +.TP +.B 2 System calls +Those functions which must be performed by the kernel. +.TP +.B 3 Library calls +Most of the +.I libc +functions, such as +.BR qsort (3). +.TP +.B 4 Special files +Files found in +.IR /dev . +.TP +.B 5 File formats and conventions +The format for +.I /etc/passwd +and other human-readable files. +.TP +.B 6 Games +.TP +.B 7 Conventions and miscellaneous +A description of the standard file system layout, network protocols, +ASCII and other character codes, this man page, and other things. +.TP +.B 8 System management commands +Commands like +.BR mount (8), +many of which only root can execute. +.TP +.B 9 Kernel routines +This is an obsolete manual section. +Once it was thought a good idea to document the Linux kernel here, +but in fact very little has been documented, and the documentation +that exists is outdated already. There are better sources of +information for kernel developers. +.RE +.SH SECTIONS +Sections are started with +.B \&.SH +followed by the heading name. If the name contains spaces and appears +on the same line as +.BR \&.SH , +then place the heading in double quotes. Traditional or suggested +headings include: +NAME, SYNOPSIS, DESCRIPTION, RETURN VALUE, +EXIT STATUS, ERROR HANDLING, ERRORS, +OPTIONS, USAGE, EXAMPLES, FILES, ENVIRONMENT, DIAGNOSTICS, SECURITY, +CONFORMING TO, NOTES, BUGS, AUTHOR, and SEE ALSO. +Where a traditional heading would apply, please use it; +this kind of consistency can make the information easier to understand. +However, feel free to create your own headings if they make things easier +to understand. +The only required heading is NAME, which should be the first section and +be followed on the next line by a one line description of the program: +.RS +.sp +\&.SH NAME +.br +chess \\- the game of chess +.sp +.RE +It is extremely important that this format is followed, and that there is a +backslash before the single dash which follows the command name. This +syntax is used by the +.BR makewhatis (8) +program to create a database of short command descriptions for the +.BR whatis (1) +and +.BR apropos (1) +commands. +.PP +Some other traditional sections have the following contents: +.TP 14 +.B SYNOPSIS +briefly describes the command or function's interface. +For commands, this shows the syntax of the command and its arguments +(including options); +boldface is used for as-is text and italics are used to indicate replaceable +arguments. Brackets ([]) surround optional arguments, vertical bars (|) +separate choices, and ellipses (\&...) can be repeated. +For functions, it shows any required data declarations or +.B #include +directives, followed by the function declaration. +.TP +.B DESCRIPTION +gives an explanation of what the command, function, or format does. +Discuss how it interacts with files and standard input, and what it +produces on standard output or standard error. +Omit internals and implementation details unless they're critical for +understanding the interface. +Describe the usual case; for information on options use the +.B OPTIONS +section. +If there is some kind of input grammar or complex set of subcommands, +consider describing them in a separate +.B USAGE +section (and just place an overview in the +.B DESCRIPTION +section). +.TP +.B RETURN VALUE +gives a +list of the values the library routine will return to the caller +and the conditions that cause these values to be returned. +.TP +.B EXIT STATUS +lists the possible exit status values or a program and +the conditions that cause these values to be returned. +.TP +.B OPTIONS +describes the options accepted by the program and how they change +its behavior. +.TP +.B USAGE +describes the grammar of any sublanguage this implements. +.TP +.B EXAMPLES +provides one or more examples describing how this function, file or +command is used. +.TP +.B FILES +lists the files the program or function uses, such as +configuration files, startup files, +and files the program directly operates on. +Give the full pathname of these files, and use the installation +process to modify the directory part to match user preferences. +For many programs, the default installation location is in +.IR /usr/local , +so your base manual page should use +.I /usr/local +as the base. +.TP +.B ENVIRONMENT +lists all environment variables that affect your program or function +and how they affect it. +.TP +.B DIAGNOSTICS +gives an overview of the most common error messages and how to +cope with them. You don't need to explain system error messages +or fatal signals that can appear during execution of any program +unless they're special in some way to your program. +.TP +.B SECURITY +discusses security issues and implications. +Warn about configurations or environments that should be avoided, +commands that may have security implications, and so on, especially +if they aren't obvious. +Discussing security in a separate section isn't necessary; +if it's easier to understand, place security information in the +other sections (such as the +.B DESCRIPTION +or +.B USAGE +section). +However, please include security information somewhere! +.TP +.B CONFORMING TO +describes any standards or conventions this implements. +.TP +.B NOTES +provides miscellaneous notes. +.TP +.B BUGS +lists limitations, known defects or inconveniences, +and other questionable activities. +.TP +.B AUTHOR +lists authors of the documentation or program so you can mail in bug +reports. +.TP +.B SEE ALSO +lists related man pages in alphabetical order, possibly followed by +other related pages or documents. +Conventionally this is the last section. +.SH FONTS +Although there are many arbitrary conventions for man pages in the UNIX +world, the existence of several hundred Linux-specific man pages defines our +font standards: +.IP +For functions, the arguments are always specified using italics, +.IR "even in the SYNOPSIS section" , +where the rest of the function is specified in bold: +.RS +.BI "int myfunction(int " argc ", char **" argv ); +.RE +.IP +Filenames are always in italics (e.g., +.IR "/usr/include/stdio.h" ), +except in the SYNOPSIS section, where included files are in bold (e.g., +.BR "#include " ). +.IP +Special macros, which are usually in upper case, are in bold (e.g., +.BR MAXINT ). +.IP +When enumerating a list of error codes, the codes are in bold (this list +usually uses the +.B \&.TP +macro). +.IP +Any reference to another man page (or to the subject of the current man +page) is in bold. If the manual section number is given, it is given in +Roman (normal) font, without any spaces (e.g., +.BR man (7)). +.LP +The commands to select the type face are: +.TP 4 +.B \&.B +Bold +.TP +.B \&.BI +Bold alternating with italics +(especially useful for function specifications) +.TP +.B \&.BR +Bold alternating with Roman +(especially useful for referring to other +manual pages) +.TP +.B \&.I +Italics +.TP +.B \&.IB +Italics alternating with bold +.TP +.B \&.IR +Italics alternating with Roman +.TP +.B \&.RB +Roman alternating with bold +.TP +.B \&.RI +Roman alternating with italics +.TP +.B \&.SB +Small alternating with bold +.TP +.B \&.SM +Small (useful for acronyms) +.LP +Traditionally, each command can have up to six arguments, but the GNU +implementation removes this limitation (you might still want to limit +yourself to 6 arguments for portability's sake). +Arguments are delimited by +spaces. Double quotes can be used to specify an argument which contains +spaces. All of the arguments will be printed next to each other without +intervening spaces, so that the +.B \&.BR +command can be used to specify a word in bold followed by a mark of +punctuation in Roman. +If no arguments are given, the command is applied to the following line +of text. +.SH "OTHER MACROS AND STRINGS" +.PP +Below are other relevant macros and predefined strings. +Unless noted otherwise, all macros +cause a break (end the current line of text). +Many of these macros set or use the "prevailing indent." +The "prevailing indent" value is set by any macro with the parameter +.I i +below; +macros may omit +.I i +in which case the current prevailing indent will be used. +As a result, successive indented paragraphs can use the same indent without +re-specifying the indent value. +A normal (non-indented) paragraph resets the prevailing indent value +to its default value (0.5 inches). +By default a given indent is measured in ens; try to ens or ems as units for +indents, since these will automatically adjust to font size changes. +The other key macro definitions are: +.SS "Normal Paragraphs" +.TP 9m +.B \&.LP +Same as +.B \&.PP +(begin a new paragraph). +.TP +.B \&.P +Same as +.B \&.PP +(begin a new paragraph). +.TP +.B \&.PP +Begin a new paragraph and reset prevailing indent. +.SS "Relative Margin Indent" +.TP 9m +.BI \&.RS " i" +Start relative margin indent - moves the left margin +.I i +to the right (if +.I i +is omitted, the prevailing indent value is used). +A new prevailing indent is set to 0.5 inches. +As a result, all following paragraph(s) will be +indented until the corresponding +.BR \&.RE . +.TP +.B \&.RE +End relative margin indent and +restores the previous value of the prevailing indent. +.SS "Indented Paragraph Macros" +.TP 9m +.BI \&.HP " i" +Begin paragraph with a hanging indent +(the first line of the paragraph is at the left margin of +normal paragraphs, and the rest of the paragraph's lines are indented). +.TP +.BI \&.IP " x i" +Indented paragraph with optional hanging tag. +If the tag +.I x +is omitted, the entire following paragraph is indented by +.IR i . +If the tag +.I x +is provided, it is hung at the left margin +before the following indented paragraph +(this is just like +.BR \&.TP +except the tag is included with the command instead of being on the +following line). +If the tag is too long, the text after the tag will be moved down to the +next line (text will not be lost or garbled). +For bulleted lists, use this macro with \e(bu (bullet) or \e(em (em dash) +as the tag, and for numbered lists, use the number or letter followed by +a period as the tag; +this simplifies translation to other formats. +.TP +.BI \&.TP " i" +Begin paragraph with hanging tag. The tag is given on the next line, but +its results are like those of the +.B \&.IP +command. +.SS "Hypertext Link Macros" +(Feature supported with groff only.) +In order to use hypertext link macros, it is necessary to load the +.B www.tmac +macro package. +Use the request +.B .mso www.tmac +to do this. +.TP 9m +.BI \&.URL " url link trailer" +Inserts a hypertext link to the URI (URL) +.IR url , +with +.I link +as the text of the link. +The +.I trailer +will be printed immediately afterwards. +When generating HTML this should translate into the HTML command +\fB\fIlink\fP\fB\fP\fItrailer\fP. +.\" The following is a kludge to get a paragraph into the listing. +.TP +.B " " +This and other related macros are new, and +many tools won't do anything with them, but +since many tools (including troff) will simply ignore undefined macros +(or at worst insert their text) these are safe to insert. +.PP +A number of other link macros are available. See +.BR groff_www (7) +for more details. +.SS "Miscellaneous Macros" +.TP 9m +.B \&.DT +Reset tabs to default tab values (every 0.5 inches); +does not cause a break. +.TP +.BI \&.PD " d" +Set inter-paragraph vertical distance to d +(if omitted, d=0.4v); +does not cause a break. +.TP +.BI \&.SS " t" +Subheading +.I t +(like +.BR \&.SH , +but used for a subsection inside a section). +.SS "Predefined Strings" +The +.B man +package has the following predefined strings: +.IP \e*R +Registration Symbol: \*R +.IP \e*S +Change to default font size +.IP \e*(Tm +Trademark Symbol: \*(Tm +.IP \e*(lq +Left angled doublequote: \*(lq +.IP \e*(rq +Right angled doublequote: \*(rq +.SH "SAFE SUBSET" +Although technically +.B man +is a troff macro package, in reality a large number of other tools +process man page files that don't implement all of troff's abilities. +Thus, it's best to avoid some of troff's more exotic abilities where possible +to permit these other tools to work correctly. +Avoid using the various troff preprocessors +(if you must, go ahead and use +.BR tbl (1), +but try to use the +.B IP +and +.B TP +commands instead for two-column tables). +Avoid using computations; most other tools can't process them. +Use simple commands that are easy to translate to other formats. +The following troff macros are believed to be safe (though in many cases +they will be ignored by translators): +.BR \e" , +.BR . , +.BR ad , +.BR bp , +.BR br , +.BR ce , +.BR de , +.BR ds , +.BR el , +.BR ie , +.BR if , +.BR fi , +.BR ft , +.BR hy , +.BR ig , +.BR in , +.BR na , +.BR ne , +.BR nf , +.BR nh , +.BR ps , +.BR so , +.BR sp , +.BR ti , +.BR tr . +.PP +You may also use many troff escape sequences (those sequences beginning +with \e). +When you need to include the backslash character as normal text, +use \ee. +Other sequences you may use, where x or xx are any characters and N +is any digit, include: +.BR \e' , +.BR \e` , +.BR \e- , +.BR \e. , +.BR \e" , +.BR \e% , +.BR \e*x , +.BR \e*(xx , +.BR \e(xx , +.BR \e$N , +.BR \enx , +.BR \en(xx , +.BR \efx , +and +.BR \ef(xx . +Avoid using the escape sequences for drawing graphics. +.PP +Do not use the optional parameter for +.B bp +(break page). +Use only positive values for +.B sp +(vertical space). +Don't define a macro +.RB ( de ) +with the same name as a macro in this or the +mdoc macro package with a different meaning; it's likely that +such redefinitions will be ignored. +Every positive indent +.RB ( in ) +should be paired with a matching negative indent +(although you should be using the +.B RS +and +.B RE +macros instead). +The condition test +.RB ( if,ie ) +should only have 't' or 'n' as the condition. +Only translations +.RB ( tr ) +that can be ignored should be used. +Font changes +.RB ( ft +and the \fB\ef\fP escape sequence) +should only have the values 1, 2, 3, 4, R, I, B, P, or CW +(the ft command may also have no parameters). +.PP +If you use capabilities beyond these, check the +results carefully on several tools. +Once you've confirmed that the additional capability is safe, +let the maintainer of this +document know about the safe command or sequence +that should be added to this list. +.SH NOTES +.PP +By all means include full URLs (or URIs) in the text itself; +some tools such as +.BR man2html (1) +can automatically turn them into hypertext links. +You can also use the new +.B URL +macro to identify links to related information. +If you include URLs, use the full URL +(e.g., ) to ensure that tools +can automatically find the URLs. +.PP +Tools processing these files should open the file and examine the first +non-whitespace character. A period (.) or single quote (') +at the beginning of a line indicates a troff-based file (such as man or mdoc). +A left angle bracket (<) indicates an SGML/XML-based +file (such as HTML or Docbook). Anything else suggests simple ASCII +text (e.g., a "catman" result). +.PP +Many man pages begin with '\e" followed by a space and a list of characters, +indicating how the page is to be preprocessed. +For portability's sake to non-troff translators we recommend that you avoid +using anything other than +.BR tbl (1), +and Linux can detect that automatically. +However, you might want to include this information so your man page +can be handled by other (less capable) systems. +Here are the definitions of the preprocessors invoked by these characters: +.TP 3 +.B e +eqn(1) +.TP +.B g +grap(1) +.TP +.B p +pic(1) +.TP +.B r +refer(1) +.TP +.B t +tbl(1) +.TP +.B v +vgrind(1) +.SH FILES +.IR /usr/share/groff/ [*/] tmac/tmac.an +.br +.I /usr/man/whatis +.SH BUGS +.PP +Most of the macros describe formatting (e.g., font type and spacing) instead +of marking semantic content (e.g., this text is a reference to another page), +compared to formats like mdoc and DocBook (even HTML has more semantic +markings). +This situation makes it harder to vary the +.B man +format for different media, +to make the formatting consistent for a given media, and to automatically +insert cross-references. +By sticking to the safe subset described above, it should be easier to +automate transitioning to a different reference page format in the future. +.LP +The Sun macro +.B TX +is not implemented. +.SH AUTHORS +.IP \(em 3m +James Clark (jjc@jclark.com) wrote the implementation of the macro package. +.IP \(em +Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of +this manual page. +.IP \(em +Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO +(which influenced this manual page). +.IP \(em +David A. Wheeler (dwheeler@ida.org) heavily modified this +manual page, such as adding detailed information on sections and macros. +.SH "SEE ALSO" +.BR apropos (1), +.BR groff (1), +.BR man (1), +.BR man2html (1), +.BR mdoc (7), +.BR mdoc.samples (7), +.BR groff_www (7), +.BR whatis (1) diff --git a/man7/mdoc.7 b/man7/mdoc.7 new file mode 100644 index 000000000..3c2f10908 --- /dev/null +++ b/man7/mdoc.7 @@ -0,0 +1,426 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mdoc.7 8.2 (Berkeley) 12/30/93 +.\" $Id: mdoc.7,v 1.8 1998/12/04 00:51:17 jkoshy Exp $ +.\" +.\" The December 30, 1993 version +.\" Modified by David A. Wheeler (dwheeler@ida.org) on 1999-07-11 +.\" to conform to Linux. +.\" +.\" +.Dd July 11, 1999 +.Dt MDOC 7 +.Os Linux +.Sh NAME +.Nm mdoc +.Nd quick reference guide for the +.Nm \-mdoc +macro package +.Sh SYNOPSIS +.Nm groff +.Fl m Ns Ar doc +.Ar files ... +.Sh DESCRIPTION +The +.Nm \-mdoc +package is a set of content-based and domain-based macros +used to format the +.Bx +man pages. +The macro names and their meanings are +listed below for quick reference; for +a detailed explanation on using the package, +see the tutorial sampler +.Xr mdoc.samples 7 . +.Pp +Note that this is not the usual macro package for Linux documentation, +although it is used for documentation of several widely-used programs; +see +.Xr man 7 . +.Pp +The macros are described in two groups, the first +includes the structural and physical page layout macros. +The second contains the manual and general text domain +macros which differentiate the +.Nm -\mdoc +package from other +.Xr troff +formatting packages. +.Sh PAGE STRUCTURE DOMAIN +.Ss Title Macros +To create a valid manual page, these three macros, in this order, +are required: +.Bl -tag -width "xxxx.Os OPERATINGxSYSTEM [version/release]" -compact +.It Li "\&.Dd " Ar "Month day, year" +Document date. +.It Li "\&.Dt " Ar "DOCUMENT_TITLE [section] [volume]" +Title, in upper case. +.It Li "\&.Os " Ar "OPERATING_SYSTEM [version/release]" +Operating system +.Pq Tn BSD . +.El +.Ss Page Layout Macros +Section headers, paragraph breaks, lists and displays. +.Bl -tag -width flag -compact +.It Li \&.Sh +Section Headers. +Valid headers, in the order of presentation: +.Bl -tag -width "RETURN VALUES" -compact +.It Ar NAME +Name section, should include the +.Ql \&.Nm +or +.Ql \&.Fn +and the +.Ql \&.Nd +macros. +.It Ar SYNOPSIS +Usage. +.It Ar DESCRIPTION +General description, should include +options and parameters. +.It Ar RETURN VALUES +Sections two and three function calls. +.It Ar ENVIRONMENT +Describe environment variables. +.It Ar FILES +Files associated with the subject. +.It Ar EXAMPLES +Examples and suggestions. +.It Ar DIAGNOSTICS +Normally used for section four device interface diagnostics. +.It Ar ERRORS +Sections two and three error and signal +handling. +.It Ar SEE ALSO +Cross references and citations. +.It Ar CONFORMING TO +Conformance to standards if applicable. +.It Ar HISTORY +If a standard is not applicable, the history +of the subject should be given. +.It Ar BUGS +Gotchas and caveats. +.It Ar other +Customized headers may be added at +the authors discretion. +.El +.It Li \&.Ss +Subsection Headers. +.It Li \&.Pp +Paragraph Break. +Vertical space (one line). +.It Li \&.D1 +(D-one) Display-one +Indent and display one text line. +.It Li \&.Dl +(D-ell) Display-one literal. +Indent and display one line of literal text. +.It Li \&.Bd +Begin-display block. +Display options: +.Bl -tag -width "xoffset string " -compact +.It Fl ragged +Unjustified (ragged edges). +.It Fl filled +Justified. +.It Fl literal +Literal text or code. +.It Fl file Ar name +Read in named +.Ar file +and display. +.It Fl offset Ar string +Offset display. +Acceptable +.Ar string +values: +.Bl -tag -width indent-two -compact +.It Ar left +Align block on left (default). +.It Ar center +Approximate center margin. +.It Ar indent +Six constant width spaces (a tab). +.It Ar indent-two +Two tabs. +.It Ar right +Left aligns block 2 inches from +right. +.It Ar xx Ns Cm n +Where +.Ar xx +is a number from +.No \&4 Ns Cm n +to +.No \&9\&9 Ns Cm n . +.It Ar Aa +Where +.Ar Aa +is a callable macro name. +.It Ar string +The width of +.Ar string +is used. +.El +.El +.It Li \&.Ed +End-display (matches \&.Bd). +.It Li \&.Bl +Begin-list. +Create lists or columns. Options: +.Bl -tag -width flag -compact +.It Ar List-types +.Bl -column xbullet -compact +.It Fl bullet Ta "Bullet Item List" +.It Fl item Ta "Unlabeled List" +.It Fl enum Ta "Enumerated List" +.It Fl tag Ta "Tag Labeled List" +.It Fl diag Ta "Diagnostic List" +.It Fl hang Ta "Hanging Labeled List" +.It Fl ohang Ta "Overhanging Labeled List" +.It Fl inset Ta "Inset or Run-on Labeled List" +.El +.It List-parameters +.Bl -tag -width "xcompact " -compact +.It Fl offset +(All lists.) See +.Ql \&.Bd +begin-display above. +.It Fl width +.Pf ( Fl tag +and +.Fl hang +lists only.) +See +.Ql \&.Bd . +.It Fl compact +(All lists.) +Suppresses blank lines. +.El +.El +.It Li \&.El +End-list. +.It Li \&.It +List item. +.El +.Sh MANUAL AND GENERAL TEXT DOMAIN MACROS +The manual and general text domain macros are special in that +most of them are parsed for callable macros +for example: +.Bl -tag -width ".Op Fl s Ar filex" -offset indent +.It Li "\&.Op Fl s Ar file" +Produces +.Op Fl s Ar file +.El +.Pp +In this example, the option enclosure macro +.Ql \&.Op +is parsed, and calls the callable content macro +.Ql \&Fl +which operates on the argument +.Ql s +and then calls the callable content macro +.Ql \&Ar +which operates on the argument +.Ql file . +Some macros may be callable, but are not parsed and vice versa. +These macros are indicated in the +.Em parsed +and +.Em callable +columns below. +.Pp +Unless stated, manual domain macros share a common syntax: +.Pp +.Dl \&.Va argument [\ .\ ,\ ;\ :\ (\ )\ [\ ]\ argument \...\ ] +.Pp +.Sy Note : +Opening and closing +punctuation characters are only recognized as such if they are presented +one at a time. +The string +.Ql ")," +is not recognized as punctuation and will be output with a leading white +space and in what ever font the calling macro uses. +The +argument list +.Ql "] ) ," +is recognized as three sequential closing punctuation characters +and a leading white space is not output between the characters +and the previous argument (if any). +The special meaning of a punctuation character may be escaped +with the string +.Ql \e& . +For example the following string, +.Bl -tag -width "&.Ar file1\ , file2\ , file3\ )\ ." -offset indent +.It Li "\&.Ar file1\ , file2\ , file3\ )\ ." +Produces +.Ar file1 , file2 , file3 ) . +.El +.ne 1i +.Ss Manual Domain Macros +.Bl -column "Name" "Parsed" Callable" -compact +.It Em Name Parsed Callable Description +.It Li \&Ad Ta Yes Ta Yes Ta "Address. (This macro may be deprecated.)" +.It Li \&An Ta Yes Ta Yes Ta "Author name." +.It Li \&Ar Ta Yes Ta Yes Ta "Command line argument." +.It Li \&Cd Ta \&No Ta \&No Ta "Configuration declaration (section four only)." +.It Li \&Cm Ta Yes Ta Yes Ta "Command line argument modifier." +.It Li \&Dv Ta Yes Ta Yes Ta "Defined variable (source code)." +.It Li \&Er Ta Yes Ta Yes Ta "Error number (source code)." +.It Li \&Ev Ta Yes Ta Yes Ta "Environment variable." +.It Li \&Fa Ta Yes Ta Yes Ta "Function argument." +.It Li \&Fd Ta Yes Ta Yes Ta "Function declaration." +.It Li \&Fn Ta Yes Ta Yes Ta "Function call (also .Fo and .Fc)." +.It Li \&Ic Ta Yes Ta Yes Ta "Interactive command." +.It Li \&Li Ta Yes Ta Yes Ta "Literal text." +.It Li \&Nm Ta Yes Ta Yes Ta "Command name." +.It Li \&Op Ta Yes Ta Yes Ta "Option (also .Oo and .Oc)." +.It Li \&Ot Ta Yes Ta Yes Ta "Old style function type (Fortran only)." +.It Li \&Pa Ta Yes Ta Yes Ta "Pathname or file name." +.It Li \&St Ta Yes Ta Yes Ta "Standards (-p1003.2, -p1003.1 or -ansiC)" +.It Li \&Va Ta Yes Ta Yes Ta "Variable name." +.It Li \&Vt Ta Yes Ta Yes Ta "Variable type (Fortran only)." +.It Li \&Xr Ta Yes Ta Yes Ta "Manual Page Cross Reference." +.El +.Ss General Text Domain Macros +.Bl -column "Name" "Parsed" Callable" -compact +.It Em "Name Parsed Callable Description" +.It Li \&%A Ta Yes Ta \&No Ta "Reference author." +.It Li \&%B Ta Yes Ta Yes Ta "Reference book title." +.It Li \&%\&C Ta \&No Ta \&No Ta "Reference place of publishing (city)." +.It Li \&%\&D Ta \&No Ta \&No Ta "Reference date." +.It Li \&%J Ta Yes Ta Yes Ta "Reference journal title." +.It Li \&%N Ta \&No Ta \&No Ta "Reference issue number." +.It Li \&%\&O Ta \&No Ta \&No Ta "Reference optional information." +.It Li \&%P Ta \&No Ta \&No Ta "Reference page number(s)." +.It Li \&%R Ta \&No Ta \&No Ta "Reference report Name." +.It Li \&%T Ta Yes Ta Yes Ta "Reference article title." +.It Li \&%V Ta \&No Ta \&No Ta "Reference volume." +.It Li \&Ac Ta Yes Ta Yes Ta "Angle close quote." +.It Li \&Ao Ta Yes Ta Yes Ta "Angle open quote." +.It Li \&Ap Ta Yes Ta Yes Ta "Apostrophe." +.It Li \&Aq Ta Yes Ta Yes Ta "Angle quote." +.It Li \&At Ta \&No Ta \&No Ta Tn "AT&T UNIX" +.It Li \&Bc Ta Yes Ta Yes Ta "Bracket close quote." +.It Li \&Bf Ta \&No Ta \&No Ta "Begin font mode." +.It Li \&Bo Ta Yes Ta Yes Ta "Bracket open quote." +.It Li \&Bq Ta Yes Ta Yes Ta "Bracket quote." +.It Li \&Bx Ta Yes Ta Yes Ta Bx . +.It Li \&Db Ta \&No Ta \&No Ta "Debug (default is \\*qoff\\*q)" +.It Li \&Dc Ta Yes Ta Yes Ta "Double close quote." +.It Li \&Do Ta Yes Ta Yes Ta "Double open quote." +.It Li \&Dq Ta Yes Ta Yes Ta "Double quote." +.It Li \&Ec Ta Yes Ta Yes Ta "Enclose string close quote." +.It Li \&Ef Ta \&No Ta \&No Ta "End font mode." +.It Li \&Em Ta Yes Ta Yes Ta "Emphasis (traditional English)." +.It Li \&Eo Ta Yes Ta Yes Ta "Enclose string open quote." +.It Li \&Fx Ta \&No Ta \&No Ta Tn "FreeBSD operating system" +.It Li \&No Ta Yes Ta Yes Ta "Normal text (no-op)." +.It Li \&Ns Ta Yes Ta Yes Ta "No space." +.It Li \&Pc Ta Yes Ta Yes Ta "Parenthesis close quote." +.It Li \&Pf Ta Yes Ta \&No Ta "Prefix string." +.It Li \&Po Ta Yes Ta Yes Ta "Parenthesis open quote." +.It Li \&Pq Ta Yes Ta Yes Ta "Parentheses quote." +.It Li \&Qc Ta Yes Ta Yes Ta "Straight Double close quote." +.It Li \&Ql Ta Yes Ta Yes Ta "Quoted literal." +.It Li \&Qo Ta Yes Ta Yes Ta "Straight Double open quote." +.It Li \&Qq Ta Yes Ta Yes Ta "Straight Double quote." +.It Li \&Re Ta \&No Ta \&No Ta "Reference end." +.It Li \&Rs Ta \&No Ta \&No Ta "Reference start." +.It Li \&Rv Ta \&No Ta \&No Ta "Return values (sections two and three only)." +.It Li \&Sc Ta Yes Ta Yes Ta "Single close quote." +.It Li \&So Ta Yes Ta Yes Ta "Single open quote." +.It Li \&Sq Ta Yes Ta Yes Ta "Single quote." +.It Li \&Sm Ta \&No Ta \&No Ta "Space mode (default is \\*qon\\*q)" +.It Li \&Sx Ta Yes Ta Yes Ta "Section Cross Reference." +.It Li \&Sy Ta Yes Ta Yes Ta "Symbolic (traditional English)." +.It Li \&Tn Ta Yes Ta Yes Ta "Trade or type name (small Caps)." +.It Li \&Ux Ta Yes Ta Yes Ta Ux +.It Li \&Xc Ta Yes Ta Yes Ta "Extend argument list close." +.It Li \&Xo Ta Yes Ta Yes Ta "Extend argument list open." +.El +.\" .It Sy \&Hf Ta \&No Ta \&No Ta "Include file with header" +.Pp +Macro names ending in +.Ql q +quote remaining items on the argument list. +Macro names ending in +.Ql o +begin a quote which may span more than one line of input and +are close quoted with the matching macro name ending in +.Ql c . +Enclosure macros may be nested and are limited to +eight arguments. +.Pp +Note: the extended argument list macros +.Pf ( Ql \&.Xo , +.Ql \&.Xc ) +and the function enclosure macros +.Pf ( Ql \&.Fo , +.Ql \&.Fc ) +are irregular. +The extended list macros are used when the number of macro arguments +would exceed the +.Xr troff +limitation of nine arguments. +.Pp +The macros UR (starting a URI/URL hypertext reference), UE (ending one), +and UN (identifying a target for a reference) are also available. +See +.Xr man 7 +for more information on these macros. +.Sh CONFIGURATION +For site specific configuration of the macro package, +see the file +.Pa /usr/src/share/tmac/README . +.Sh FILES +.Bl -tag -width "tmac.doc-ditroff" -compact +.It Pa tmac.doc +Manual and general text domain macros. +.It Pa tmac.doc-common +Common structural macros and definitions. +.It Pa tmac.doc-nroff +Site dependent +.Xr nroff +style file. +.It Pa tmac.doc-ditroff +Site dependent +.Xr troff +style file. +.It Pa tmac.doc-syms +Special defines (such as the standards macro). +.El +.Sh "SEE ALSO" +.Xr mdoc.samples 7 , +.Xr man 7 diff --git a/man7/mdoc.samples.7 b/man7/mdoc.samples.7 new file mode 100644 index 000000000..0d56677ba --- /dev/null +++ b/man7/mdoc.samples.7 @@ -0,0 +1,2938 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mdoc.samples.7 8.2 (Berkeley) 12/30/93 +.\" $Id: mdoc.samples.7,v 1.17 1998/12/03 03:38:45 jkoshy Exp $ +.\" +.\" This tutorial sampler invokes every macro in the package several +.\" times and is guaranteed to give a worst case performance +.\" for an already extremely slow package. +.\" +.Dd December 30, 1993 +.Os +.Dt MDOC.SAMPLES 7 +.Sh NAME +.Nm mdoc.samples +.Nd tutorial sampler for writing +.Bx +manuals with +.Nm \-mdoc +.Sh SYNOPSIS +.Nm man mdoc.samples +.Sh DESCRIPTION +A tutorial sampler for writing +.Bx +manual pages with the +.Nm \-mdoc +macro package, a +.Em content Ns \-based +and +.Em domain Ns \-based +formatting +package for +.Xr troff 1 . +Its predecessor, the +.Xr \-man 7 +package, +addressed page layout leaving the +manipulation of fonts and other +typesetting details to the individual author. +In +.Nm \-mdoc , +page layout macros +make up the +.Em "page structure domain" +which consists of macros for titles, section headers, displays +and lists. Essentially items which affect the physical position +of text on a formatted page. +In addition to the page structure domain, there are two more domains, +the manual domain and the general text domain. +The general text domain is defined as macros which +perform tasks such as quoting or emphasizing pieces of text. +The manual domain is defined as macros that are a subset of the +day to day informal language used to describe commands, routines +and related +.Bx +files. +Macros in the manual domain handle +command names, command line arguments and options, function names, +function parameters, pathnames, variables, cross +references to other manual pages, and so on. +These domain +items have value +for both the author and the future user of the manual page. +It is hoped the consistency gained +across the manual set will provide easier +translation to future documentation tools. +.Pp +Throughout the +.Ux +manual pages, a manual entry +is simply referred +to as a man page, regardless of actual length and without +sexist intention. +.Sh GETTING STARTED +Since a tutorial document is normally read when a person +desires to use the material immediately, the assumption has +been made that the user of this document may be impatient. +The material presented in the remained of this document is +outlined as follows: +.Bl -enum -offset indent +.It +.Tn "TROFF IDIOSYNCRASIES" +.Bl -tag -width flag -compact -offset indent +.It "Macro Usage" . +.It "Passing Space Characters in an Argument" . +.It "Trailing Blank Space Characters (a warning)" . +.It "Escaping Special Characters" . +.El +.It +.Tn "THE ANATOMY OF A MAN PAGE" +.Bl -tag -width flag -compact -offset indent +.It "A manual page template" . +.El +.It +.Tn "TITLE MACROS" . +.It +.Tn "INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS" . +.Bl -tag -width flag -compact -offset indent +.It "What's in a name..." . +.It "General Syntax" . +.El +.It +.Tn "MANUAL DOMAIN" +.Bl -tag -width flag -compact -offset indent +.It "Addresses" . +.It "Author name" . +.It "Arguments" . +.It "Configuration Declarations (section four only)" . +.It "Command Modifier" . +.It "Defined Variables" . +.It "Errno's (Section two only)" . +.It "Environment Variables" . +.It "Function Argument" . +.It "Function Declaration" . +.It "Flags" . +.It "Functions (library routines)" . +.It "Function Types" . +.\" .It "Header File (including source code)" . +.It "Interactive Commands" . +.It "Names" . +.It "Options" . +.It "Pathnames" . +.It "Variables" . +.It "Cross References" . +.El +.It +.Tn "GENERAL TEXT DOMAIN" +.Bl -tag -width flag -compact -offset indent +.It "AT&T Macro" . +.It "BSD Macro" . +.It "FreeBSD Macro" . +.It "UNIX Macro" . +.It "Enclosure/Quoting Macros" +.Bl -tag -width flag -compact -offset indent +.It "Angle Bracket Quote/Enclosure" . +.It "Bracket Quotes/Enclosure" . +.It "Double Quote macro/Enclosure" . +.It "Parenthesis Quote/Enclosure" . +.It "Single Quotes/Enclosure" . +.It "Prefix Macro" . +.El +.It "No\-Op or Normal Text Macro" . +.It "No Space Macro" . +.It "Section Cross References" . +.It "References and Citations" . +.It "Return Values (sections two and three only)" +.It "Trade Names (Acronyms and Type Names)" . +.It "Extended Arguments" . +.El +.It +.Tn "PAGE STRUCTURE DOMAIN" +.Bl -tag -width flag -compact -offset indent +.It "Section Headers" . +.It "Paragraphs and Line Spacing" . +.It "Keeps" . +.It "Displays" . +.It "Font Modes (Emphasis, Literal, and Symbolic)" . +.It "Lists and Columns" . +.El +.It +.Tn "PREDEFINED STRINGS" +.It +.Tn "DIAGNOSTICS" +.It +.Tn "FORMATTING WITH GROFF, TROFF AND NROFF" +.It +.Tn "BUGS" +.El +.ne 7 +.Sh TROFF IDIOSYNCRASIES +The +.Nm \-mdoc +package attempts to simplify the process of writing a man page. +Theoretically, one should not have to learn the dirty details of +.Xr troff 1 +to use +.Nm \-mdoc ; +however, there are a few +limitations which are unavoidable and best gotten out +of the way. +And, too, be forewarned, this package is +.Em not +fast. +.Ss Macro Usage +As in +.Xr troff 1 , +a macro is called by placing a +.Ql \&\. +(dot character) +at the beginning of +a line followed by the two character name for the macro. +Arguments may follow the macro separated by spaces. +It is the dot character at the beginning of the line which causes +.Xr troff 1 +to interpret the next two characters as a macro name. +To place a +.Ql \&\. +(dot character) +at the beginning of a line in some context other than +a macro invocation, precede the +.Ql \&\. +(dot) with the +.Ql \e& +escape sequence. +The +.Ql \e& +translates literally to a zero width space, and is never displayed in the +output. +.Pp +In general, +.Xr troff 1 +macros accept up to nine arguments, any +extra arguments are ignored. +Most macros in +.Nm \-mdoc +accept nine arguments and, +in limited cases, arguments may be continued or extended +on the +next line (See +.Sx Extensions ) . +A few macros handle quoted arguments (see +.Sx Passing Space Characters in an Argument +below). +.Pp +Most of the +.Nm \-mdoc +general text domain and manual domain macros are special +in that their argument lists are +.Em parsed +for callable macro names. +This means an argument on the argument list which matches +a general text or manual domain macro name and is determined +to be callable will be executed +or called when it is processed. +In this case +the argument, although the name of a macro, +is not preceded by a +.Ql \&\. +(dot). +It is in this manner that many macros are nested; for +example +the option macro, +.Ql \&.Op , +may +.Em call +the flag and argument macros, +.Ql \&Fl +and +.Ql \&Ar , +to specify an optional flag with an argument: +.Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent +.It Op Fl s Ar bytes +is produced by +.Li \&.Op \&Fl s \&Ar bytes +.El +.Pp +To prevent a two character +string from being interpreted as a macro name, precede +the string with the +escape sequence +.Ql \e& : +.Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent +.It Op \&Fl s \&Ar bytes +is produced by +.Li \&.Op \e&Fl s \e&Ar bytes +.El +.Pp +Here the strings +.Ql \&Fl +and +.Ql \&Ar +are not interpreted as macros. +Macros whose argument lists are parsed for callable arguments +are referred to +as parsed and macros which may be called from an argument +list are referred to as callable +throughout this document and in the companion quick reference +manual +.Xr mdoc 7 . +This is a technical +.Em faux pas +as almost all of the macros in +.Nm \-mdoc +are parsed, but as it was cumbersome to constantly refer to macros +as being callable and being able to call other macros, +the term parsed has been used. +.Ss Passing Space Characters in an Argument +Sometimes it is desirable to give as one argument a string +containing one or more blank space characters. +This may be necessary +to defeat the nine argument limit or to specify arguments to macros +which expect particular arrangement of items in the argument list. +For example, +the function macro +.Ql \&.Fn +expects the first argument to be the name of a function and any +remaining arguments to be function parameters. +As +.Tn "ANSI C" +stipulates the declaration of function parameters in the +parenthesized parameter list, each parameter is guaranteed +to be at minimum a two word string. +For example, +.Fa int foo . +.Pp +There are two possible ways to pass an argument which contains +an embedded space. +.Em Implementation note : +Unfortunately, the most convenient way +of passing spaces in between quotes by reassigning individual +arguments before parsing was fairly expensive speed wise +and space wise to implement in all the macros for +.Tn AT&T +.Xr troff . +It is not expensive for +.Xr groff +but for the sake of portability, has been limited +to the following macros which need +it the most: +.Pp +.Bl -tag -width 4n -offset indent -compact +.It Li \&Cd +Configuration declaration (section 4 +.Sx SYNOPSIS ) +.It Li \&Bl +Begin list (for the width specifier). +.It Li \&Em +Emphasized text. +.It Li \&Fn +Functions (sections two and four). +.It Li \&It +List items. +.It Li \&Li +Literal text. +.It Li \&Sy +Symbolic text. +.It Li \&%B +Book titles. +.It Li \&%J +Journal names. +.It Li \&%O +Optional notes for a reference. +.It Li \&%R +Report title (in a reference). +.It Li \&%T +Title of article in a book or journal. +.El +.Pp +One way of passing a string +containing blank spaces is to use the hard or unpaddable space character +.Ql \e\ , +that is, a blank space preceded by the escape character +.Ql \e . +This method may be used with any macro but has the side effect +of interfering with the adjustment of text +over the length of a line. +.Xr Troff +sees the hard space as if it were any other printable character and +cannot split the string into blank or newline separated pieces as one +would expect. +The method is useful for strings which are not expected +to overlap a line boundary. +For example: +.Bl -tag -width "fetch(char *str)" -offset indent +.It Fn fetch char\ *str +is created by +.Ql \&.Fn fetch char\e *str +.It Fn fetch "char *str" +can also be created by +.Ql \&.Fn fetch "\\*qchar *str\\*q" +.El +.Pp +If the +.Ql \e +or quotes +were omitted, +.Ql \&.Fn +would see three arguments and +the result would be: +.Pp +.Dl Fn fetch char *str +.Pp +For an example of what happens when the parameter list overlaps +a newline boundary, see the +.Sx BUGS +section. +.Ss Trailing Blank Space Characters +.Xr Troff +can be confused by blank space characters at the end of a line. +It +is a wise preventive measure to globally remove all blank spaces +from character sequences. +Should the need +arise to force a blank character at the end of a line, +it may be forced with an unpaddable space and the +.Ql \e& +escape character. +For example, +.Ql string\e\ \e& . +.Ss Escaping Special Characters +Special characters +like the newline character +.Ql \en , +are handled by replacing the +.Ql \e +with +.Ql \ee +(e.g. +.Ql \een ) +to preserve +the backslash. +.Sh THE ANATOMY OF A MAN PAGE +The body of a man page is easily constructed from a basic +template found in the file +.Pa /usr/share/misc/mdoc.template . +Several example man pages can also be found +in +.Pa /usr/share/examples/mdoc . +.Pp +.Ss A manual page template +.Bd -literal -offset indent +\&.\e" The following requests are required for all man pages. +\&.Dd Month day, year +\&.Os OPERATING_SYSTEM [version/release] +\&.Dt DOCUMENT_TITLE [section number] [volume] +\&.Sh NAME +\&.Nm name +\&.Nd one line description of name +\&.Sh SYNOPSIS +\&.Sh DESCRIPTION +\&.\e" The following requests should be uncommented and +\&.\e" used where appropriate. This next request is +\&.\e" for sections 2 and 3 function return values only. +\&.\e" .Sh RETURN VALUES +\&.\e" This next request is for sections 1, 6, 7 & 8 only +\&.\e" .Sh ENVIRONMENT +\&.\e" .Sh FILES +\&.\e" .Sh EXAMPLES +\&.\e" This next request is for sections 1, 6, 7 & 8 only +\&.\e" (command return values (to shell) and +\&.\e" fprintf/stderr type diagnostics) +\&.\e" .Sh DIAGNOSTICS +\&.\e" The next request is for sections 2 and 3 error +\&.\e" and signal handling only. +\&.\e" .Sh ERRORS +\&.\e" .Sh SEE ALSO +\&.\e" .Sh CONFORMING TO +\&.\e" .Sh HISTORY +\&.\e" .Sh AUTHORS +\&.\e" .Sh BUGS +.Ed +.Pp +The first items in the template are the macros +.Pq Li \&.Dd , \&.Os , \&.Dt ; +the document date, +the operating system the man page or subject source is developed +or modified for, +and the man page title +.Pq Em in upper case +along with the section of the manual the page +belongs in. +These macros identify the page, +and are discussed below in +.Sx TITLE MACROS . +.Pp +The remaining items in the template are section headers +.Pq Li \&.Sh ; +of which +.Sx NAME , +.Sx SYNOPSIS +and +.Sx DESCRIPTION +are mandatory. +The +headers are +discussed in +.Sx PAGE STRUCTURE DOMAIN , +after +presentation of +.Sx MANUAL DOMAIN . +Several content macros are used to demonstrate page layout macros; +reading about content macros before page layout macros is +recommended. +.Sh TITLE MACROS +The title macros are the first portion of the page structure +domain, but are presented first and separate for someone who +wishes to start writing a man page yesterday. +Three header macros designate the document title or manual page title, +the operating system, +and the date of authorship. +These macros are one called once at the very beginning of the document +and are used to construct the headers and footers only. +.Bl -tag -width 6n +.It Li \&.Dt DOCUMENT_TITLE section# [volume] +The document title is the +subject of the man page and must be in +.Tn CAPITALS +due to troff +limitations. +The section number may be 1,\ ...,\ 8, +and if it is specified, +the volume title may be omitted. +A volume title may be arbitrary or one of the following: +.\" .Cl +.\" USD UNIX User's Supplementary Documents +.\" .Cl +.\" PS1 UNIX Programmer's Supplementary Documents +.Pp +.Bl -column SMM -offset indent -compact +.It Li AMD UNIX Ancestral Manual Documents +.It Li SMM UNIX System Manager's Manual +.It Li URM UNIX Reference Manual +.It Li PRM UNIX Programmer's Manual +.El +.Pp +The default volume labeling is +.Li URM +for sections 1, 6, and 7; +.Li SMM +for section 8; +.Li PRM +for sections 2, 3, 4, and 5. +.\" .Cl +.\" MMI UNIX Manual Master Index +.\" .Cl +.\" CON UNIX Contributed Software Manual +.\" .Cl +.\" LOC UNIX Local Manual +.It Li \&.Os operating_system release# +The name of the operating system +should be the common acronym, e.g. +.Tn BSD +or +.Tn FreeBSD +or +.Tn ATT . +The release should be the standard release +nomenclature for the system specified, e.g. 4.3, 4.3+Tahoe, V.3, +V.4. +Unrecognized arguments are displayed as given in the page footer. +For instance, a typical footer might be: +.Pp +.Dl \&.Os BSD 4.3 +.Pp +or +.Dl \&.Os FreeBSD 2.2 +.Pp +or for a locally produced set +.Pp +.Dl \&.Os CS Department +.Pp +The Berkeley default, +.Ql \&.Os +without an argument, has been defined as +.Tn BSD +in the +site specific file +.Pa /usr/share/tmac/mdoc/doc-common . +It really should default to +.Tn LOCAL . +Note, if the +.Ql \&.Os +macro is not present, the bottom left corner of the page +will be ugly. +.It Li \&.Dd month day, year +The date should be written formally: +.Pp +.ne 5 +.Dl January 25, 1989 +.El +.Sh INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS +.Ss What's in a name... +The manual domain macro names are derived from the day to day +informal language used to describe commands, subroutines and related +files. +Slightly different variations of this language are used to describe +the three different aspects of writing a man page. +First, there is the description of +.Nm \-mdoc +macro request usage. +Second is the description of a +.Ux +command +.Em with +.Nm \-mdoc +macros and third, +the description of a command to a user in the verbal sense; +that is, discussion of a command in the text of a man page. +.Pp +In the first case, +.Xr troff 1 +macros are themselves a type of command; +the general syntax for a troff command is: +.Bd -filled -offset indent +\&.Va argument1 argument2 ... argument9 +.Ed +.Pp +The +.Ql \&.Va +is a macro command or request, and anything following it is an argument to +be processed. +In the second case, +the description of a +.Ux +command using the content macros is a +bit more involved; +a typical +.Sx SYNOPSIS +command line might be displayed as: +.Bd -filled -offset indent +.Nm filter +.Op Fl flag +.Ar infile outfile +.Ed +.Pp +Here, +.Nm filter +is the command name and the +bracketed string +.Fl flag +is a +.Em flag +argument designated as optional by the option brackets. +In +.Nm \-mdoc +terms, +.Ar infile +and +.Ar outfile +are +called +.Em arguments . +The macros which formatted the above example: +.Bd -literal -offset indent +\&.Nm filter +\&.Op \&Fl flag +\&.Ar infile outfile +.Ed +.Pp +In the third case, discussion of commands and command syntax +includes both examples above, but may add more detail. +The +arguments +.Ar infile +and +.Ar outfile +from the example above might be referred to as +.Em operands +or +.Em file arguments . +Some command line argument lists are quite long: +.Bl -tag -width make -offset indent +.It Nm make +.Op Fl eiknqrstv +.Op Fl D Ar variable +.Op Fl d Ar flags +.Op Fl f Ar makefile +.Bk -words +.Op Fl I Ar directory +.Ek +.Op Fl j Ar max_jobs +.Op Ar variable=value +.Bk -words +.Op Ar target ... +.Ek +.El +.Pp +Here one might talk about the command +.Nm make +and qualify the argument +.Ar makefile , +as an argument to the flag, +.Fl f , +or discuss the optional +file +operand +.Ar target . +In the verbal context, such detail can prevent confusion, +however the +.Nm \-mdoc +package +does not have a macro for an argument +.Em to +a flag. +Instead the +.Ql \&Ar +argument macro is used for an operand or file argument like +.Ar target +as well as an argument to a flag like +.Ar variable . +The make command line was produced from: +.Bd -literal -offset indent +\&.Nm make +\&.Op Fl eiknqrstv +\&.Op Fl D Ar variable +\&.Op Fl d Ar flags +\&.Op Fl f Ar makefile +\&.Op Fl I Ar directory +\&.Op Fl j Ar max_jobs +\&.Op Ar variable=value +\&.Bk -words +\&.Op Ar target ... +\&.Ek +.Ed +.Pp +The +.Ql \&.Bk +and +.Ql \&.Ek +macros are explained in +.Sx Keeps . +.Ss General Syntax +The manual domain and general text domain macros share a similar +syntax with a few minor deviations: +.Ql \&.Ar , +.Ql \&.Fl , +.Ql \&.Nm , +and +.Ql \&.Pa +differ only when called without arguments; +.Ql \&.Fn +and +.Ql \&.Xr +impose an order on their argument lists +and the +.Ql \&.Op +and +.Ql \&.Fn +macros +have nesting limitations. +All content macros +are capable of recognizing and properly handling punctuation, +provided each punctuation character is separated by a leading space. +If an request is given: +.Pp +.Dl \&.Li sptr, ptr), +.Pp +The result is: +.Pp +.Dl Li sptr, ptr), +.Pp +The punctuation is not recognized and all is output in the +literal font. If the punctuation is separated by a leading +white space: +.Pp +.Dl \&.Li "sptr , ptr ) ," +.Pp +The result is: +.Pp +.Dl Li sptr , ptr ) , +.Pp +The punctuation is now recognized and is output in the +default font distinguishing it from the strings in literal font. +.Pp +To remove the special meaning from a punctuation character +escape it with +.Ql \e& . +.Xr Troff +is limited as a macro language, and has difficulty +when presented with a string containing +a member of the mathematical, logical or +quotation set: +.Bd -literal -offset indent-two +\&{+,\-,/,*,\&%,<,>,<=,>=,=,==,&,`,',"} +.Ed +.Pp +The problem is that +.Xr troff +may assume it is supposed to actually perform the operation +or evaluation suggested by the characters. To prevent +the accidental evaluation of these characters, +escape them with +.Ql \e& . +Typical syntax is shown in the first content macro displayed +below, +.Ql \&.Ad . +.Sh MANUAL DOMAIN +.Ss Address Macro +The address macro identifies an address construct +of the form addr1[,addr2[,addr3]]. +.Pp +.Dl Usage: .Ad address ... \*(Pu +.Bl -tag -width ".Ad f1 , f2 , f3 :" -compact -offset 14n +.It Li \&.Ad addr1 +.Ad addr1 +.It Li \&.Ad addr1\ . +.Ad addr1 . +.It Li \&.Ad addr1\ , file2 +.Ad addr1 , file2 +.It Li \&.Ad f1\ , f2\ , f3\ : +.Ad f1 , f2 , f3 : +.It Li \&.Ad addr\ )\ )\ , +.Ad addr ) ) , +.El +.Pp +It is an error to call +.Ql \&.Ad +without arguments. +.Ql \&.Ad +is callable by other macros and is parsed. +.Ss Author Name +The +.Ql \&.An +macro is used to specify the name of the author of the item being +documented, or the name of the author of the actual manual page. +Any remaining arguments after the name information are assumed +to be punctuation. +.Pp +.Dl Usage: .An author_name \*(Pu +.Bl -tag -width ".An Joe Author ) ) ," -compact -offset 14n +.It Li \&.An Joe\ Author +.An Joe Author +.It Li \&.An Joe\ Author\ , +.An Joe\ Author , +.It Li \&.An Joe\ Author\ \&Aq\ nobody@FreeBSD.ORG +.An Joe Author Aq nobody@FreeBSD.ORG +.It Li \&.An Joe\ Author\ )\ )\ , +.An Joe Author ) ) , +.El +.Pp +The +.Ql \&.An +macro is parsed and is callable. +It is an error to call +.Ql \&.An +without +any arguments. +.Ss Argument Macro +The +.Ql \&.Ar +argument macro may be used whenever +a command line argument is referenced. +.Pp +.Dl Usage: .Ar argument ... \*(Pu +.Bl -tag -width ".Ar file1 file2" -compact -offset 15n +.It Li \&.Ar +.Ar +.It Li \&.Ar file1 +.Ar file1 +.It Li \&.Ar file1\ . +.Ar file1 . +.It Li \&.Ar file1 file2 +.Ar file1 file2 +.It Li \&.Ar f1 f2 f3\ : +.Ar f1 f2 f3 : +.It Li \&.Ar file\ )\ )\ , +.Ar file ) ) , +.El +.Pp +If +.Ql \&.Ar +is called without arguments +.Ql Ar +is assumed. +The +.Ql \&.Ar +macro is parsed and is callable. +.Ss Configuration Declaration (section four only) +The +.Ql \&.Cd +macro is used to demonstrate a +.Xr config 8 +declaration for a device interface in a section four manual. +This macro accepts quoted arguments (double quotes only). +.Pp +.Bl -tag -width "device le0 at scode?" -offset indent +.It Cd "device le0 at scode?" +produced by: +.Ql ".Cd device le0 at scode?" . +.El +.Ss Command Modifier +The command modifier is identical to the +.Ql \&.Fl +(flag) command with the exception +the +.Ql \&.Cm +macro does not assert a dash +in front of every argument. +Traditionally flags are marked by the +preceding dash, some commands or subsets of commands do not use them. +Command modifiers may also be specified in conjunction with interactive +commands such as editor commands. +See +.Sx Flags . +.Ss Defined Variables +A variable which is defined in an include file is specified +by the macro +.Ql \&.Dv . +.Pp +.Dl Usage: .Dv defined_variable ... \*(Pu +.Bl -tag -width ".Dv MAXHOSTNAMELEN" -compact -offset 14n +.It Li ".Dv MAXHOSTNAMELEN" +.Dv MAXHOSTNAMELEN +.It Li ".Dv TIOCGPGRP )" +.Dv TIOCGPGRP ) +.El +.Pp +It is an error to call +.Ql \&.Dv +without arguments. +.Ql \&.Dv +is parsed and is callable. +.Ss Errno's (Section two only) +The +.Ql \&.Er +errno macro specifies the error return value +for section two library routines. +The second example +below shows +.Ql \&.Er +used with the +.Ql \&.Bq +general text domain macro, as it would be used in +a section two manual page. +.Pp +.Dl Usage: .Er ERRNOTYPE ... \*(Pu +.Bl -tag -width ".Bq Er ENOTDIR" -compact -offset 14n +.It Li \&.Er ENOENT +.Er ENOENT +.It Li \&.Er ENOENT\ )\ ; +.Er ENOENT ) ; +.It Li \&.Bq \&Er ENOTDIR +.Bq Er ENOTDIR +.El +.Pp +It is an error to call +.Ql \&.Er +without arguments. +The +.Ql \&.Er +macro is parsed and is callable. +.Ss Environment Variables +The +.Ql \&.Ev +macro specifies an environment variable. +.Pp +.Dl Usage: .Ev argument ... \*(Pu +.Bl -tag -width ".Ev PRINTER ) ) ," -compact -offset 14n +.It Li \&.Ev DISPLAY +.Ev DISPLAY +.It Li \&.Ev PATH\ . +.Ev PATH . +.It Li \&.Ev PRINTER\ )\ )\ , +.Ev PRINTER ) ) , +.El +.Pp +It is an error to call +.Ql \&.Ev +without arguments. +The +.Ql \&.Ev +macro is parsed and is callable. +.Ss Function Argument +The +.Ql \&.Fa +macro is used to refer to function arguments (parameters) +outside of the +.Sx SYNOPSIS +section of the manual or inside +the +.Sx SYNOPSIS +section should a parameter list be too +long for the +.Ql \&.Fn +macro and the enclosure macros +.Ql \&.Fo +and +.Ql \&.Fc +must be used. +.Ql \&.Fa +may also be used to refer to structure members. +.Pp +.Dl Usage: .Fa function_argument ... \*(Pu +.Bl -tag -width ".Fa d_namlen\ )\ )\ ," -compact -offset 14n +.It Li \&.Fa d_namlen\ )\ )\ , +.Fa d_namlen ) ) , +.It Li \&.Fa iov_len +.Fa iov_len +.El +.Pp +It is an error to call +.Ql \&.Fa +without arguments. +.Ql \&.Fa +is parsed and is callable. +.Ss Function Declaration +The +.Ql \&.Fd +macro is used in the +.Sx SYNOPSIS +section with section two or three +functions. +The +.Ql \&.Fd +macro does not call other macros and is not callable by other +macros. +.Pp +.Dl Usage: .Fd include_file (or defined variable) +.Pp +In the +.Sx SYNOPSIS +section a +.Ql \&.Fd +request causes a line break if a function has already been presented +and a break has not occurred. +This leaves a nice vertical space +in between the previous function call and the declaration for the +next function. +.Ss Flags +The +.Ql \&.Fl +macro handles command line flags. +It prepends +a dash, +.Ql \- , +to the flag. +For interactive command flags, which +are not prepended with a dash, the +.Ql \&.Cm +(command modifier) +macro is identical, but without the dash. +.Pp +.Dl Usage: .Fl argument ... \*(Pu +.Bl -tag -width ".Fl \-s \-t \-v" -compact -offset 14n +.It Li \&.Fl +.Fl +.It Li \&.Fl cfv +.Fl cfv +.It Li \&.Fl cfv\ . +.Fl cfv . +.It Li \&.Fl s v t +.Fl s v t +.It Li \&.Fl -\ , +.Fl - , +.It Li \&.Fl xyz\ )\ , +.Fl xyz ) , +.El +.Pp +The +.Ql \&.Fl +macro without any arguments results +in a dash representing stdin/stdout. +Note that giving +.Ql \&.Fl +a single dash, will result in two dashes. +The +.Ql \&.Fl +macro is parsed and is callable. +.Ss Functions (library routines) +The .Fn macro is modeled on ANSI C conventions. +.Bd -literal +Usage: .Fn [type] function [[type] parameters ... \*(Pu] +.Ed +.Bl -tag -width ".Fn .int align. .const * char *sptrsxx" -compact +.It Li "\&.Fn getchar" +.Fn getchar +.It Li "\&.Fn strlen ) ," +.Fn strlen ) , +.It Li \&.Fn "\\*qint align\\*q" "\\*qconst * char *sptrs\\*q" , +.Fn "int align" "const * char *sptrs" , +.El +.Pp +It is an error to call +.Ql \&.Fn +without any arguments. +The +.Ql \&.Fn +macro +is parsed and is callable, +note that any call to another macro signals the end of +the +.Ql \&.Fn +call (it will close-parenthesis at that point). +.Pp +For functions that have more than eight parameters (and this +is rare), the +macros +.Ql \&.Fo +(function open) +and +.Ql \&.Fc +(function close) +may be used with +.Ql \&.Fa +(function argument) +to get around the limitation. For example: +.Bd -literal -offset indent +\&.Fo "int res_mkquery" +\&.Fa "int op" +\&.Fa "char *dname" +\&.Fa "int class" +\&.Fa "int type" +\&.Fa "char *data" +\&.Fa "int datalen" +\&.Fa "struct rrec *newrr" +\&.Fa "char *buf" +\&.Fa "int buflen" +\&.Fc +.Ed +.Pp +Produces: +.Bd -filled -offset indent +.Fo "int res_mkquery" +.Fa "int op" +.Fa "char *dname" +.Fa "int class" +.Fa "int type" +.Fa "char *data" +.Fa "int datalen" +.Fa "struct rrec *newrr" +.Fa "char *buf" +.Fa "int buflen" +.Fc +.Ed +.Pp +The +.Ql \&.Fo +and +.Ql \&.Fc +macros are parsed and are callable. +In the +.Sx SYNOPSIS +section, the function will always begin at +the beginning of line. +If there is more than one function +presented in the +.Sx SYNOPSIS +section and a function type has not been +given, a line break will occur, leaving a nice vertical space +between the current function name and the one prior. +At the moment, +.Ql \&.Fn +does not check its word boundaries +against troff line lengths and may split across a newline +ungracefully. +This will be fixed in the near future. +.Ss Function Type +This macro is intended for the +.Sx SYNOPSIS +section. +It may be used +anywhere else in the man page without problems, but its main purpose +is to present the function type in kernel normal form for the +.Sx SYNOPSIS +of sections two and three +(it causes a line break allowing the function name to appear +on the next line). +.Pp +.Dl Usage: .Ft type ... \*(Pu +.Bl -tag -width "\&.Ft struct stat" -offset 14n -compact +.It Li \&.Ft struct stat +.Ft struct stat +.El +.Pp +The +.Ql \&.Ft +request is not callable by other macros. +.Ss Interactive Commands +The +.Ql \&.Ic +macro designates an interactive or internal command. +.Pp +.Dl Usage: .Ic argument ... \*(Pu +.Bl -tag -width ".Ic setenv , unsetenvxx" -compact -offset 14n +.It Li \&.Ic :wq +.Ic :wq +.It Li \&.Ic do while {...} +.Ic do while {...} +.It Li \&.Ic setenv\ , unsetenv +.Ic setenv , unsetenv +.El +.Pp +It is an error to call +.Ql \&.Ic +without arguments. +The +.Ql \&.Ic +macro is parsed and is callable. +.Ss Name Macro +The +.Ql \&.Nm +macro is used for the document title or subject name. +It has the peculiarity of remembering the first +argument it was called with, which should +always be the subject name of the page. +When called without +arguments, +.Ql \&.Nm +regurgitates this initial name for the sole purpose +of making less work for the author. +Note: +a section two +or three document function name is addressed with the +.Ql \&.Nm +in the +.Sx NAME +section, and with +.Ql \&.Fn +in the +.Sx SYNOPSIS +and remaining sections. +For interactive commands, such as the +.Ql while +command keyword in +.Xr csh 1 , +the +.Ql \&.Ic +macro should be used. +While the +.Ql \&.Ic +is nearly identical +to +.Ql \&.Nm , +it can not recall the first argument it was invoked with. +.Pp +.Dl Usage: .Nm argument ... \*(Pu +.Bl -tag -width ".Nm mdoc.sample" -compact -offset 14n +.It Li \&.Nm mdoc.sample +.Nm mdoc.sample +.It Li \&.Nm \e-mdoc +.Nm \-mdoc . +.It Li \&.Nm foo\ )\ )\ , +.Nm foo ) ) , +.It Li \&.Nm +.Nm +.El +.Pp +The +.Ql \&.Nm +macro is parsed and is callable. +.Ss Options +The +.Ql \&.Op +macro +places option brackets around the any remaining arguments on the command +line, and places any +trailing punctuation outside the brackets. +The macros +.Ql \&.Oc +and +.Ql \&.Oo +may be used across one or more lines. +.Pp +.Dl Usage: .Op options ... \*(Pu +.Bl -tag -width ".Op Fl c Ar objfil Op Ar corfil ," -compact -offset indent +.It Li \&.Op +.Op +.It Li ".Op Fl k" +.Op Fl k +.It Li ".Op Fl k ) ." +.Op Fl k ) . +.It Li ".Op Fl k Ar kookfile" +.Op Fl k Ar kookfile +.It Li ".Op Fl k Ar kookfile ," +.Op Fl k Ar kookfile , +.It Li ".Op Ar objfil Op Ar corfil" +.Op Ar objfil Op Ar corfil +.It Li ".Op Fl c Ar objfil Op Ar corfil ," +.Op Fl c Ar objfil Op Ar corfil , +.It Li \&.Op word1 word2 +.Op word1 word2 +.El +.Pp +The +.Ql \&.Oc +and +.Ql \&.Oo +macros: +.Bd -literal -offset indent +\&.Oo +\&.Op \&Fl k \&Ar kilobytes +\&.Op \&Fl i \&Ar interval +\&.Op \&Fl c \&Ar count +\&.Oc +.Ed +.Pp +Produce: +.Oo +.Op Fl k Ar kilobytes +.Op Fl i Ar interval +.Op Fl c Ar count +.Oc +.Pp +The macros +.Ql \&.Op , +.Ql \&.Oc +and +.Ql \&.Oo +are parsed and are callable. +.Ss Pathnames +The +.Ql \&.Pa +macro formats path or file names. +.Pp +.Dl Usage: .Pa pathname \*(Pu +.Bl -tag -width ".Pa /tmp/fooXXXXX ) ." -compact -offset 14n +.It Li \&.Pa /usr/share +.Pa /usr/share +.It Li \&.Pa /tmp/fooXXXXX\ )\ . +.Pa /tmp/fooXXXXX ) . +.El +.Pp +The +.Ql \&.Pa +macro is parsed and is callable. +.Ss Variables +Generic variable reference: +.Pp +.Dl Usage: .Va variable ... \*(Pu +.Bl -tag -width ".Va char s ] ) ) ," -compact -offset 14n +.It Li \&.Va count +.Va count +.It Li \&.Va settimer , +.Va settimer , +.It Li \&.Va int\ *prt\ )\ : +.Va int\ *prt ) : +.It Li \&.Va char\ s\ ]\ )\ )\ , +.Va char\ s ] ) ) , +.El +.Pp +It is an error to call +.Ql \&.Va +without any arguments. +The +.Ql \&.Va +macro is parsed and is callable. +.Ss Manual Page Cross References +The +.Ql \&.Xr +macro expects the first argument to be +a manual page name, and the second argument, if it exists, +to be either a section page number or punctuation. +Any +remaining arguments are assumed to be punctuation. +.Pp +.Dl Usage: .Xr man_page [1,...,8] \*(Pu +.Bl -tag -width ".Xr mdoc 7 ) ) ," -compact -offset 14n +.It Li \&.Xr mdoc +.Xr mdoc +.It Li \&.Xr mdoc\ , +.Xr mdoc , +.It Li \&.Xr mdoc 7 +.Xr mdoc 7 +.It Li \&.Xr mdoc 7\ )\ )\ , +.Xr mdoc 7 ) ) , +.El +.Pp +The +.Ql \&.Xr +macro is parsed and is callable. +It is an error to call +.Ql \&.Xr +without +any arguments. +.Sh GENERAL TEXT DOMAIN +.Ss AT&T Macro +.Bd -literal -offset indent -compact +Usage: .At [v6 | v7 | 32v | V.1 | V.4] ... \*(Pu +.Ed +.Bl -tag -width ".At v6 ) ," -compact -offset 14n +.It Li ".At" +.At +.It Li ".At v6 ." +.At v6 . +.El +.Pp +The +.Ql \&.At +macro is +.Em not +parsed and +.Em not +callable. It accepts at most two arguments. +.Ss BSD Macro +.Dl Usage: .Bx [Version/release] ... \*(Pu +.Bl -tag -width ".Bx 4.3 ) ," -compact -offset 14n +.It Li ".Bx" +.Bx +.It Li ".Bx 4.3 ." +.Bx 4.3 . +.El +.Pp +The +.Ql \&.Bx +macro is parsed and is callable. +.Ss FreeBSD Macro +.Bd -literal -offset indent -compact +Usage: .Fx Version.release ... \*(Pu +.Ed +.Bl -tag -width ".Fx 2.2 ) ," -compact -offset 14n +.It Li ".Fx 2.2 ." +.Fx 2.2 . +.El +.Pp +The +.Ql \&.Fx +macro is +.Em not +parsed and +.Em not +callable. It accepts at most two arguments. +.Ss UNIX Macro +.Dl Usage: .Ux ... \*(Pu +.Bl -tag -width ".Ux 4.3 ) ," -compact -offset 14n +.It Li ".Ux" +.Ux +.El +.Pp +The +.Ql \&.Ux +macro is parsed and is callable. +.Ss Enclosure and Quoting Macros +The concept of enclosure is similar to quoting. +The object being to enclose one or more strings between +a pair of characters like quotes or parentheses. +The terms quoting and enclosure are used +interchangeably throughout this document. +Most of the +one line enclosure macros end +in small letter +.Ql q +to give a hint of quoting, but there are a few irregularities. +For each enclosure macro +there is also a pair of open and close macros which end +in small letters +.Ql o +and +.Ql c +respectively. +These can be used across one or more lines of text +and while they have nesting limitations, the one line quote macros +can be used inside +of them. +.Pp +.ne 5 +.Bd -filled -offset indent +.Bl -column "quote " "close " "open " "Enclose Stringx(in XX) " XXstringXX +.Em " Quote Close Open Function Result" +\&.Aq .Ac .Ao Angle Bracket Enclosure +\&.Bq .Bc .Bo Bracket Enclosure [string] +\&.Dq .Dc .Do Double Quote ``string'' + .Ec .Eo Enclose String (in XX) XXstringXX +\&.Pq .Pc .Po Parenthesis Enclosure (string) +\&.Ql Quoted Literal `st' or string +\&.Qq .Qc .Qo Straight Double Quote "string" +\&.Sq .Sc .So Single Quote `string' +.El +.Ed +.Pp +Except for the irregular macros noted below, all +of the quoting macros are parsed and callable. +All handle punctuation properly, as long as it +is presented one character at a time and separated by spaces. +The quoting macros examine opening and closing punctuation +to determine whether it comes before or after the +enclosing string. This makes some nesting possible. +.Bl -tag -width xxx,xxxx +.It Li \&.Ec , \&.Eo +These macros expect the first argument to be the +opening and closing strings respectively. +.It Li \&.Ql +The quoted literal macro behaves differently for +.Xr troff +than +.Xr nroff . +If formatted with +.Xr nroff , +a quoted literal is always quoted. If formatted with +troff, an item is only quoted if the width +of the item is less than three constant width characters. +This is to make short strings more visible where the font change +to literal (constant width) is less noticeable. +.It Li \&.Pf +The prefix macro is not callable, but it is parsed: +.Bl -tag -width "(namexx" -offset indent +.It Li ".Pf ( Fa name2" +becomes +.Pf ( Fa name2 . +.El +.Pp +The +.Ql \&.Ns +(no space) macro performs the analogous suffix function. +.El +.Pp +.ne 4 +Examples of quoting: +.Bl -tag -width ".Aq Pa ctype.h ) ,xxxxxxxx" -compact -offset indent +.It Li \&.Aq +.Aq +.It Li \&.Aq \&Ar ctype.h\ )\ , +.Aq Ar ctype.h ) , +.It Li \&.Bq +.Bq +.It Li \&.Bq \&Em Greek \&, French \&. +.Bq Em Greek , French . +.It Li \&.Dq +.Dq +.It Li ".Dq string abc ." +.Dq string abc . +.It Li ".Dq \'^[A-Z]\'" +.Dq \'^[A-Z]\' +.It Li "\&.Ql man mdoc" +.Ql man mdoc +.It Li \&.Qq +.Qq +.It Li "\&.Qq string ) ," +.Qq string ) , +.It Li "\&.Qq string Ns )," +.Qq string Ns ), +.It Li \&.Sq +.Sq +.It Li "\&.Sq string +.Sq string +.El +.Pp +For a good example of nested enclosure macros, see the +.Ql \&.Op +option macro. +It was created from the same +underlying enclosure macros as those presented in the list +above. +The +.Ql \&.Xo +and +.Ql \&.Xc +extended argument list macros +were also built from the same underlying routines and are a good +example of +.Nm \-mdoc +macro usage at its worst. +.Ss No\-Op or Normal Text Macro +The macro +.Ql \&.No +is +a hack for words in a macro command line which should +.Em not +be formatted and follows the conventional syntax +for content macros. +.Ss No Space Macro +The +.Ql \&.Ns +macro eliminates unwanted spaces in between macro requests. +It is useful for old style argument lists where there is no space +between the flag and argument: +.Bl -tag -width ".Op Fl I Ns Ar directoryxx" -offset indent +.It Li ".Op Fl I Ns Ar directory" +produces +.Op Fl I Ns Ar directory +.El +.Pp +Note: the +.Ql \&.Ns +macro always invokes the +.Ql \&.No +macro after eliminating the space unless another macro name +follows it. +The macro +.Ql \&.Ns +is parsed and is callable. +.Ss Section Cross References +The +.Ql \&.Sx +macro designates a reference to a section header +within the same document. +It is parsed and is callable. +.Pp +.Bl -tag -width "Li \&.Sx FILES" -offset 14n +.It Li \&.Sx FILES +.Sx FILES +.El +.Ss References and Citations +The following macros make a modest attempt to handle references. +At best, the macros make it convenient to manually drop in a subset of +refer style references. +.Pp +.Bl -tag -width 6n -offset indent -compact +.It Li ".Rs" +Reference Start. +Causes a line break and begins collection +of reference information until the +reference end macro is read. +.It Li ".Re" +Reference End. +The reference is printed. +.It Li ".%A" +Reference author name, one name per invocation. +.It Li ".%B" +Book title. +.It Li ".\&%C" +City/place. +.It Li ".\&%D" +Date. +.It Li ".%J" +Journal name. +.It Li ".%N" +Issue number. +.It Li ".%O" +Optional information. +.It Li ".%P" +Page number. +.It Li ".%R" +Report name. +.It Li ".%T" +Title of article. +.It Li ".%V" +Volume(s). +.El +.Pp +The macros beginning with +.Ql % +are not callable, and are parsed only for the trade name macro which +returns to its caller. +(And not very predictably at the moment either.) +The purpose is to allow trade names +to be pretty printed in +.Xr troff Ns / Ns Xr ditroff +output. +.Ss Return Values +The +.Ql \&.Rv +macro generates text for use in the +.Sx RETURN VALUES +section. +.Pp +.Dl Usage: .Rv [-std function] +.Pp +.Ql \&.Rv -std atexit +will generate the following text: +.Pp +.\" fake chapter 3 to avoid error message from Rv +.ds cH 3 +.Rv -std atexit +.\" and back to 7 again +.ds cH 7 +.Pp +The +.Fl std +option is valid only for manual page sections 2 and 3. +.Ss Trade Names (or Acronyms and Type Names) +The trade name macro is generally a small caps macro for +all upper case words longer than two characters. +.Pp +.Dl Usage: .Tn symbol ... \*(Pu +.Bl -tag -width ".Tn ASCII" -compact -offset 14n +.It Li \&.Tn DEC +.Tn DEC +.It Li \&.Tn ASCII +.Tn ASCII +.El +.Pp +The +.Ql \&.Tn +macro +is parsed and is callable by other macros. +.Ss Extended Arguments +The +.Ql \&.Xo +and +.Ql \&.Xc +macros allow one to extend an argument list +on a macro boundary. +Argument lists cannot +be extended within a macro +which expects all of its arguments on one line such +as +.Ql \&.Op . +.Pp +Here is an example of +.Ql \&.Xo +using the space mode macro to turn spacing off: +.Bd -literal -offset indent +\&.Sm off +\&.It Xo Sy I Ar operation +\&.No \een Ar count No \een +\&.Xc +\&.Sm on +.Ed +.Pp +Produces +.Bd -filled -offset indent +.Bl -tag -width flag -compact +.Sm off +.It Xo Sy I Ar operation +.No \en Ar count No \en +.Xc +.Sm on +.El +.Ed +.Pp +Another one: +.Bd -literal -offset indent +\&.Sm off +\&.It Cm S No \&/ Ar old_pattern Xo +\&.No \&/ Ar new_pattern +\&.No \&/ Op Cm g +\&.Xc +\&.Sm on +.Ed +.Pp +Produces +.Bd -filled -offset indent +.Bl -tag -width flag -compact +.Sm off +.It Cm S No \&/ Ar old_pattern Xo +.No \&/ Ar new_pattern +.No \&/ Op Cm g +.Xc +.Sm on +.El +.Ed +.Pp +Another example of +.Ql \&.Xo +and using enclosure macros: +Test the value of an variable. +.Bd -literal -offset indent +\&.It Xo +\&.Ic .ifndef +\&.Oo \e&! Oc Ns Ar variable +\&.Op Ar operator variable ... +\&.Xc +.Ed +.Pp +Produces +.Bd -filled -offset indent +.Bl -tag -width flag -compact +.It Xo +.Ic .ifndef +.Oo \&! Oc Ns Ar variable +.Op Ar operator variable ... +.Xc +.El +.Ed +.Pp +All of the above examples have used the +.Ql \&.Xo +macro on the argument list of the +.Ql \&.It +(list-item) +macro. +The extend macros are not used very often, and when they are +it is usually to extend the list-item argument list. +Unfortunately, this is also where the extend macros are the +most finicky. +In the first two examples, spacing was turned off; +in the third, spacing was desired in part of the output but +not all of it. +To make these macros work in this situation make sure +the +.Ql \&.Xo +and +.Ql \&.Xc +macros are placed as shown in the third example. +If the +.Ql \&.Xo +macro is not alone on the +.Ql \&.It +argument list, spacing will be unpredictable. +The +.Ql \&.Ns +(no space macro) +must not occur as the first or last macro on a line +in this situation. +Out of 900 manual pages (about 1500 actual pages) +currently released with +.Bx +only fifteen use the +.Ql \&.Xo +macro. +.Sh PAGE STRUCTURE DOMAIN +.Ss Section Headers +The first three +.Ql \&.Sh +section header macros +list below are required in every +man page. +The remaining section headers +are recommended at the discretion of the author +writing the manual page. +The +.Ql \&.Sh +macro can take up to nine arguments. +It is parsed and but is not callable. +.Bl -tag -width ".Sh SYNOPSIS" +.It \&.Sh NAME +The +.Ql \&.Sh NAME +macro is mandatory. +If not specified, +the headers, footers and page layout defaults +will not be set and things will be rather unpleasant. +The +.Sx NAME +section consists of at least three items. +The first is the +.Ql \&.Nm +name macro naming the subject of the man page. +The second is the Name Description macro, +.Ql \&.Nd , +which separates the subject +name from the third item, which is the description. +The +description should be the most terse and lucid possible, +as the space available is small. +.It \&.Sh SYNOPSIS +The +.Sx SYNOPSIS +section describes the typical usage of the +subject of a man page. +The macros required +are either +.Ql ".Nm" , +.Ql ".Cd" , +.Ql ".Fn" , +(and possibly +.Ql ".Fo" , +.Ql ".Fc" , +.Ql ".Fd" , +.Ql ".Ft" +macros). +The function name +macro +.Ql ".Fn" +is required +for manual page sections 2 and 3, the command and general +name macro +.Ql \&.Nm +is required for sections 1, 5, 6, 7, 8. +Section 4 manuals require a +.Ql ".Nm" , +.Ql ".Fd" +or a +.Ql ".Cd" +configuration device usage macro. +Several other macros may be necessary to produce +the synopsis line as shown below: +.Pp +.Bd -filled -offset indent +.Nm cat +.Op Fl benstuv +.Op Fl +.Ar +.Ed +.Pp +The following macros were used: +.Pp +.Dl \&.Nm cat +.Dl \&.Op \&Fl benstuv +.Dl \&.Op \&Fl +.Dl \&.Ar +.Pp +.Sy Note : +The macros +.Ql \&.Op , +.Ql \&.Fl , +and +.Ql \&.Ar +recognize the pipe bar character +.Ql \*(Ba , +so a command line such as: +.Pp +.Dl ".Op Fl a | Fl b" +.Pp +will not go orbital. +.Xr Troff +normally interprets a \*(Ba as a special operator. +See +.Sx PREDEFINED STRINGS +for a usable \*(Ba +character in other situations. +.It \&.Sh DESCRIPTION +In most cases the first text in the +.Sx DESCRIPTION +section +is a brief paragraph on the command, function or file, +followed by a lexical list of options and respective +explanations. +To create such a list, the +.Ql \&.Bl +begin-list, +.Ql \&.It +list-item and +.Ql \&.El +end-list +macros are used (see +.Sx Lists and Columns +below). +.El +.Pp +The following +.Ql \&.Sh +section headers are part of the +preferred manual page layout and must be used appropriately +to maintain consistency. +They are listed in the order +in which they would be used. +.Bl -tag -width SYNOPSIS +.It \&.Sh ENVIRONMENT +The +.Sx ENVIRONMENT +section should reveal any related +environment +variables and clues to their behavior and/or usage. +.It \&.Sh EXAMPLES +There are several ways to create examples. +See +the +.Sx EXAMPLES +section below +for details. +.It \&.Sh FILES +Files which are used or created by the man page subject +should be listed via the +.Ql \&.Pa +macro in the +.Sx FILES +section. +.It \&.Sh SEE ALSO +References to other material on the man page topic and +cross references to other relevant man pages should +be placed in the +.Sx SEE ALSO +section. +Cross references +are specified using the +.Ql \&.Xr +macro. +Cross references in the +.Sx SEE ALSO +section should be sorted by section number, and then +placed in alphabetical order and comma separated. For example: +.Pp +.Xr ls 1 , +.Xr ps 1 , +.Xr group 5 , +.Xr passwd 5 . +.Pp +At this time +.Xr refer 1 +style references are not accommodated. +.It \&.Sh CONFORMING TO +If the command, library function or file adheres to a +specific implementation such as +.St -p1003.2 +or +.St -ansiC +this should be noted here. +If the +command does not adhere to any standard, its history +should be noted in the +.Sx HISTORY +section. +.It \&.Sh HISTORY +Any command which does not adhere to any specific standards +should be outlined historically in this section. +.It \&.Sh AUTHORS +Credits, if need be, should be placed here. +.It \&.Sh DIAGNOSTICS +Diagnostics from a command should be placed in this section. +.It \&.Sh ERRORS +Specific error handling, especially from library functions +(man page sections 2 and 3) should go here. +The +.Ql \&.Er +macro is used to specify an errno. +.It \&.Sh BUGS +Blatant problems with the topic go here... +.El +.Pp +User specified +.Ql \&.Sh +sections may be added, +for example, this section was set with: +.Bd -literal -offset 14n +\&.Sh PAGE STRUCTURE DOMAIN +.Ed +.Ss Paragraphs and Line Spacing. +.Bl -tag -width 6n +.It \&.Pp +The +.Ql \&.Pp +paragraph command may +be used to specify a line space where necessary. +The macro is not necessary after a +.Ql \&.Sh +or +.Ql \&.Ss +macro or before +a +.Ql \&.Bl +macro. +(The +.Ql \&.Bl +macro asserts a vertical distance unless the -compact flag is given). +.El +.\" This worked with version one, need to redo for version three +.\" .Pp +.\" .Ds I +.\" .Cw (ax+bx+c) \ is\ produced\ by\ \& +.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& +.\" .Cl Cx \t\t +.\" .Li \&.Cx\ ( +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Va ax +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Sy \+ +.\" .Cx +.\" .Cl Cx \&(\& +.\" .Va ax +.\" .Cx + +.\" .Va by +.\" .Cx + +.\" .Va c ) +.\" .Cx \t +.\" .Em is produced by +.\" .Cx \t +.\" .Li \&.Va by +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Sy \+ +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Va c ) +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx +.\" .Cx +.\" .Cw +.\" .De +.\" .Pp +.\" This example shows the same equation in a different format. +.\" The spaces +.\" around the +.\" .Li \&+ +.\" signs were forced with +.\" .Li \e : +.\" .Pp +.\" .Ds I +.\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \& +.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& +.\" .Cl Cx \t\t +.\" .Li \&.Cx\ ( +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Va a +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Sy x +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx \e\ +\e\ \e& +.\" .Cx +.\" .Cl Cx \&(\& +.\" .Va a +.\" .Sy x +.\" .Cx \ +\ \& +.\" .Va b +.\" .Sy y +.\" .Cx \ +\ \& +.\" .Va c ) +.\" .Cx \t +.\" .Em is produced by +.\" .Cl Cx \t\t +.\" .Li \&.Va b +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Sy y +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx \e\ +\e\ \e& +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Va c ) +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx +.\" .Cx +.\" .Cw +.\" .De +.\" .Pp +.\" The incantation below was +.\" lifted from the +.\" .Xr adb 1 +.\" manual page: +.\" .Pp +.\" .Ds I +.\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by +.\" .Cl Cx \t\t +.\" .Li \&.Cx Op Sy ?/ +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Nm m +.\" .Cx +.\" .Cl Cx Op Sy ?/ +.\" .Nm m +.\" .Ad \ b1 e1 f1 +.\" .Op Sy ?/ +.\" .Cx \t +.\" .Em is produced by +.\" .Cx \t +.\" .Li \&.Ar \e\ b1 e1 f1 +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Op Sy ?/ +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx +.\" .Cx +.\" .Cw +.\" .De +.\" .Pp +.Ss Keeps +The only keep that is implemented at this time is for words. +The macros are +.Ql \&.Bk +(begin-keep) +and +.Ql \&.Ek +(end-keep). +The only option that +.Ql \&.Bk +accepts is +.Fl words +and is useful for preventing line breaks in the middle of options. +In the example for the make command line arguments (see +.Sx What's in a name ) , +the keep prevented +.Xr nroff +from placing up the +flag and the argument +on separate lines. +(Actually, the option macro used to prevent this from occurring, +but was dropped when the decision (religious) was made to force +right justified margins in +.Xr troff +as options in general look atrocious when spread across a sparse +line. +More work needs to be done with the keep macros, a +.Fl line +option needs to be added.) +.Ss Examples and Displays +There are five types of displays, a quickie one line indented display +.Ql \&.D1 , +a quickie one line literal display +.Ql \&.Dl , +and a block literal, block filled and block ragged which use +the +.Ql \&.Bd +begin-display +and +.Ql \&.Ed +end-display macros. +.Pp +.Bl -tag -width \&.Dlxx +.It Li \&.D1 +(D-one) Display one line of indented text. +This macro is parsed, but it is not callable. +.Pp +.Dl Fl ldghfstru +.Pp +The above was produced by: +.Li \&.Dl Fl ldghfstru . +.It Li \&.Dl +(D-ell) +Display one line of indented +.Em literal +text. +The +.Ql \&.Dl +example macro has been used throughout this +file. +It allows +the indent (display) of one line of text. +Its default font is set to +constant width (literal) however +it is parsed and will recognized other macros. +It is not callable however. +.Pp +.Dl % ls -ldg /usr/local/bin +.Pp +The above was produced by +.Li \&.Dl % ls -ldg /usr/local/bin . +.It Li \&.Bd +Begin-display. +The +.Ql \&.Bd +display must be ended with the +.Ql \&.Ed +macro. +Displays may be nested within displays and +lists. +.Ql \&.Bd +has the following syntax: +.Pp +.Dl ".Bd display-type [-offset offset_value] [-compact]" +.Pp +The display-type must be one of the following four types and +may have an offset specifier for indentation: +.Ql \&.Bd . +.Pp +.Bl -tag -width "file file_name " -compact +.It Fl ragged +Display a block of text as typed, +right (and left) margin edges are left ragged. +.It Fl filled +Display a filled (formatted) block. +The block of text is formatted (the edges are filled \- +not left unjustified). +.It Fl literal +Display a literal block, useful for source code or +simple tabbed or spaced text. +.It Fl file Ar file_name +The file name following the +.Fl file +flag is read and displayed. +Literal mode is +asserted and tabs are set at 8 constant width character +intervals, however any +.Xr troff/ Ns Nm \-mdoc +commands in file will be processed. +.It Fl offset Ar string +If +.Fl offset +is specified with one of the following strings, the string +is interpreted to indicate the level of indentation for the +forthcoming block of text: +.Pp +.Bl -tag -width "indent-two" -compact +.It Ar left +Align block on the current left margin, +this is the default mode of +.Ql \&.Bd . +.It Ar center +Supposedly center the block. +At this time +unfortunately, the block merely gets +left aligned about an imaginary center margin. +.It Ar indent +Indents by one default indent value or tab. +The default +indent value is also used for the +.Ql \&.D1 +display so one is guaranteed the two types of displays +will line up. +This indent is normally set to 6n or about two +thirds of an inch (six constant width characters). +.It Ar indent-two +Indents two times the default indent value. +.It Ar right +This +.Em left +aligns the block about two inches from +the right side of the page. +This macro needs +work and perhaps may never do the right thing by +.Xr troff . +.El +.El +.It ".Ed" +End-display. +.El +.Ss Font Modes +There are five macros for changing the appearance of the manual page text: +.Bl -tag -width \&.Emxx +.It \&.Em +Text may be stressed or emphasized with the +.Ql \&.Em +macro. +The usual font for emphasis is italic. +.Pp +.Dl Usage: .Em argument ... \*(Pu +.Bl -tag -width ".Em vide infra ) ) ," -compact -offset 14n +.It Li ".Em does not" +.Em does not +.It Li ".Em exceed 1024 ." +.Em exceed 1024 . +.It Li ".Em vide infra ) ) ," +.Em vide infra ) ) , +.El +.Pp +The +.Ql \&.Em +macro is parsed and is callable. +It is an error to call +.Ql \&.Em +without arguments. +.It \&.Li +The +.Ql \&.Li +literal macro may be used for special characters, +variable constants, anything which should be displayed as it +would be typed. +.Pp +.Dl Usage: .Li argument ... \*(Pu +.Bl -tag -width ".Li cntrl-D ) ," -compact -offset 14n +.It Li \&.Li \een +.Li \en +.It Li \&.Li M1 M2 M3\ ; +.Li M1 M2 M3 ; +.It Li \&.Li cntrl-D\ )\ , +.Li cntrl-D ) , +.It Li \&.Li 1024\ ... +.Li 1024 ... +.El +.Pp +The +.Ql \&.Li +macro is parsed and is callable. +.It \&.Sy +The symbolic emphasis macro is generally a boldface macro in +either the symbolic sense or the traditional English usage. +.Pp +.Dl Usage: .Sy symbol ... \*(Pu +.Bl -tag -width ".Sy Important Noticex" -compact -offset 14n +.It Li \&.Sy Important Notice +.Sy Important Notice +.El +.Pp +The +.Ql \&.Sy +macro is parsed and is callable. +Arguments to +.Ql \&.Sy +may be quoted. +.It Li \&.Bf +Begin font mode. +The +.Ql \&.Bf +font mode must be ended with the +.Ql \&.Ef +macro. +Font modes may be nested within other font modes. +.Ql \&.Bf +has the following syntax: +.Pp +.Dl ".Bf font-mode" +.Pp +The font-mode must be one of the following three types: +.Ql \&.Bf . +.Pp +.Bl -tag -width "file file_name " -compact +.It Sy \&Em | Fl emphasis +Same as if the +.Ql \&.Em +macro was used for the entire block of text. +.It Sy \&Li | Fl literal +Same as if the +.Ql \&.Li +macro was used for the entire block of text. +.It Sy \&Sy | Fl symbolic +Same as if the +.Ql \&.Sy +macro was used for the entire block of text. +.El +.It ".Ef" +End font mode. +.El +.Ss Tagged Lists and Columns +There are several types of lists which may be initiated with the +.Ql ".Bl" +begin-list macro. +Items within the list +are specified with the +.Ql ".It" +item macro and +each list must end with the +.Ql ".El" +macro. +Lists may be nested within themselves and within displays. +Columns may be used inside of lists, but lists are unproven +inside of columns. +.Pp +In addition, several list attributes may be specified such as +the width of a tag, the list offset, and compactness +(blank lines between items allowed or disallowed). +Most of this document has been formatted with a tag style list +.Pq Fl tag . +For a change of pace, the list-type used to present the list-types +is an over-hanging list +.Pq Fl ohang . +This type of list is quite popular with +.Tn TeX +users, but might look a bit funny after having read many pages of +tagged lists. +The following list types are accepted by +.Ql ".Bl" : +.Pp +.Bl -ohang -compact +.It Fl bullet +.It Fl item +.It Fl enum +These three are the simplest types of lists. +Once the +.Ql ".Bl" +macro has been given, items in the list are merely +indicated by a line consisting solely of the +.Ql ".It" +macro. +For example, the source text for a simple enumerated list +would look like: +.Bd -literal -offset indent-two +\&.Bl -enum -compact +\&.It +\&Item one goes here. +\&.It +\&And item two here. +\&.It +\&Lastly item three goes here. +\&.El +.Ed +.Pp +The results: +.Pp +.Bl -enum -offset indent-two -compact +.It +Item one goes here. +.It +And item two here. +.It +Lastly item three goes here. +.El +.Pp +A simple bullet list construction: +.Bd -literal -offset indent-two +\&.Bl -bullet -compact +\&.It +\&Bullet one goes here. +\&.It +\&Bullet two here. +\&.El +.Ed +.Pp +Produces: +.Bl -bullet -offset indent-two -compact +.It +Bullet one goes here. +.It +Bullet two here. +.El +.Pp +.It Fl tag +.It Fl diag +.It Fl hang +.It Fl ohang +.It Fl inset +These list-types collect arguments specified with the +.Ql \&.It +macro and create a label which may be +.Em inset +into the forthcoming text, +.Em hanged +from the forthcoming text, +.Em overhanged +from above and not indented or +.Em tagged . +This +list was constructed with the +.Ql Fl ohang +list-type. +The +.Ql \&.It +macro is parsed only for the inset, hang +and tag list-types and is not callable. +Here is an example of inset labels: +.Bl -inset -offset indent +.It Em Tag +The tagged list (also called a tagged paragraph) is the +most common type of list used in the Berkeley manuals. +.It Em Diag +Diag lists create section four diagnostic lists +and are similar to inset lists except callable +macros are ignored. +.It Em Hang +Hanged labels are a matter of taste. +.It Em Ohang +Overhanging labels are nice when space is constrained. +.It Em Inset +Inset labels are useful for controlling blocks of +paragraphs and are valuable for converting +.Nm \-mdoc +manuals to other formats. +.El +.Pp +Here is the source text which produced the above example: +.Bd -literal -offset indent +\&.Bl -inset -offset indent +\&.It Em Tag +\&The tagged list (also called a tagged paragraph) is the +\&most common type of list used in the Berkeley manuals. +\&.It Em Diag +\&Diag lists create section four diagnostic lists +\&and are similar to inset lists except callable +\¯os are ignored. +\&.It Em Hang +\&Hanged labels are a matter of taste. +\&.It Em Ohang +\&Overhanging labels are nice when space is constrained. +\&.It Em Inset +\&Inset labels are useful for controlling blocks of +\¶graphs and are valuable for converting +\&.Nm \-mdoc +\&manuals to other formats. +\&.El +.Ed +.Pp +Here is a hanged list with two items: +.Bl -hang -offset indent +.It Em Hanged +labels appear similar to tagged lists when the +label is smaller than the label width. +.It Em Longer hanged list labels +blend in to the paragraph unlike +tagged paragraph labels. +.El +.Pp +And the unformatted text which created it: +.Bd -literal -offset indent +\&.Bl -hang -offset indent +\&.It Em Hanged +\&labels appear similar to tagged lists when the +\&label is smaller than the label width. +\&.It Em Longer hanged list labels +\&blend in to the paragraph unlike +\&tagged paragraph labels. +\&.El +.Ed +.Pp +The tagged list which follows uses an optional width specifier to control +the width of the tag. +.Pp +.Bl -tag -width "PAGEIN" -compact -offset indent +.It SL +sleep time of the process (seconds blocked) +.It PAGEIN +number of disk +.Tn I/O Ns 's +resulting from references +by the process to pages not loaded in core. +.It UID +numerical user-id of process owner +.It PPID +numerical id of parent of process process priority +(non-positive when in non-interruptible wait) +.El +.Pp +The raw text: +.Bd -literal -offset indent +\&.Bl -tag -width "PAGEIN" -compact -offset indent +\&.It SL +\&sleep time of the process (seconds blocked) +\&.It PAGEIN +\&number of disk +\&.Tn I/O Ns 's +\&resulting from references +\&by the process to pages not loaded in core. +\&.It UID +\&numerical user-id of process owner +\&.It PPID +\&numerical id of parent of process process priority +\&(non-positive when in non-interruptible wait) +\&.El +.Ed +.Pp +Acceptable width specifiers: +.Bl -tag -width Ar -offset indent +.It Fl width Ar "\&Fl" +sets the width to the default width for a flag. +All callable +macros have a default width value. +The +.Ql \&.Fl , +value is presently +set to ten constant width characters or about five sixth of +an inch. +.It Fl width Ar "24n" +sets the width to 24 constant width characters or about two +inches. +The +.Ql n +is absolutely necessary for the scaling to work correctly. +.It Fl width Ar "ENAMETOOLONG" +sets width to the constant width length of the +string given. +.It Fl width Ar "\\*qint mkfifo\\*q" +again, the width is set to the constant width of the string +given. +.El +.Pp +If a width is not specified for the tag list type, the first +time +.Ql \&.It +is invoked, an attempt is made to determine an appropriate +width. +If the first argument to +.Ql ".It" +is a callable macro, the default width for that macro will be used +as if the macro name had been supplied as the width. +However, +if another item in the list is given with a different callable +macro name, a new and nested list is assumed. +.Sh PREDEFINED STRINGS +The following strings are predefined as may be used by +preceding with the troff string interpreting sequence +.Ql \&\e*(xx +where +.Em xx +is the name of the defined string or as +.Ql \&\e*x +where +.Em x +is the name of the string. +The interpreting sequence may be used any where in the text. +.Pp +.Bl -column "String " "Nroff " "Troff " -offset indent +.It Sy "String Nroff Troff" +.It Li "<=" Ta \&<\&= Ta \*(<= +.It Li ">=" Ta \&>\&= Ta \*(>= +.It Li "Rq" Ta "''" Ta \*(Rq +.It Li "Lq" Ta "``" Ta \*(Lq +.It Li "ua" Ta ^ Ta \*(ua +.It Li "aa" Ta ' Ta \*(aa +.It Li "ga" Ta \` Ta \*(ga +.\" .It Li "sL" Ta ` Ta \*(sL +.\" .It Li "sR" Ta ' Ta \*(sR +.It Li "q" Ta \&" Ta \*q +.It Li "Pi" Ta pi Ta \*(Pi +.It Li "Ne" Ta != Ta \*(Ne +.It Li "Le" Ta <= Ta \*(Le +.It Li "Ge" Ta >= Ta \*(Ge +.It Li "Lt" Ta < Ta \*(Gt +.It Li "Gt" Ta > Ta \*(Lt +.It Li "Pm" Ta +- Ta \*(Pm +.It Li "If" Ta infinity Ta \*(If +.It Li "Na" Ta \fINaN\fP Ta \*(Na +.It Li "Ba" Ta \fR\&|\fP Ta \*(Ba +.El +.Pp +.Sy Note : +The string named +.Ql q +should be written as +.Ql \e*q +since it is only one char. +.Sh DIAGNOSTICS +The debugging facilities for +.Nm \-mdoc +are limited, but can help detect subtle errors such +as the collision of an argument name with an internal +register or macro name. +(A what?) +A register is an arithmetic storage class for +.Xr troff +with a one or two character name. +All registers internal to +.Nm \-mdoc +for +.Xr troff +and +.Xr ditroff +are two characters and +of the form such as +.Ql \&Ar , + as +.Ql \&aR +or + as +.Ql \&C\&1 . +And adding to the muddle, +.Xr troff +has its own internal registers all of which are either +two lower case characters or a dot plus a letter or meta-character +character. +In one of the introduction examples, it was shown how to +prevent the interpretation of a macro name with the escape sequence +.Ql \e& . +This is sufficient for the internal register names also. +.Pp +.\" Every callable macro name has a corresponding register +.\" of the same name (). +.\" There are also specific registers which have +.\" been used for stacks and arrays and are listed in the +.\" .Sx Appendix . +.\" .Bd -ragged -offset 4n +.\" [A-Z][a-z] registers corresponding to macro names (example ``Ar'') +.\" [a-z][A-Z] registers corresponding to macro names (example ``aR'') +.\" C[0-9] argument types (example C1) +.\" O[0-9] offset stack (displays) +.\" h[0-9] horizontal spacing stack (lists) +.\" o[0-9] offset (stack) (lists) +.\" t[0-9] tag stack (lists) +.\" v[0-9] vertical spacing stack (lists) +.\" w[0-9] width tag/label stack +.\" .Ed +.\" .Pp +If a non-escaped register name is given in the argument list of a request +unpredictable behavior will occur. +In general, any time huge portions +of text do not appear where expected in the output, or small strings +such as list tags disappear, chances are there is a misunderstanding +about an argument type in the argument list. +Your mother never intended for you to remember this evil stuff - so here +is a way to find out whether or not your arguments are valid: The +.Ql \&.Db +(debug) +macro displays the interpretation of the argument list for most +macros. +Macros such as the +.Ql \&.Pp +(paragraph) +macro do not contain debugging information. +All of the callable macros do, +and it is strongly advised whenever in doubt, +turn on the +.Ql \&.Db +macro. +.Pp +.Dl Usage: \&.Db [on | off] +.Pp +An example of a portion of text with +the debug macro placed above and below an +artificially created problem (a flag argument +.Ql \&aC +which should be +.Ql \e&aC +in order to work): +.Bd -literal -offset indent +\&.Db on +\&.Op Fl aC Ar file ) +\&.Db off +.Ed +.Pp +The resulting output: +.Bd -literal -offset indent +DEBUGGING ON +DEBUG(argv) MACRO: `.Op' Line #: 2 + Argc: 1 Argv: `Fl' Length: 2 + Space: `' Class: Executable + Argc: 2 Argv: `aC' Length: 2 + Space: `' Class: Executable + Argc: 3 Argv: `Ar' Length: 2 + Space: `' Class: Executable + Argc: 4 Argv: `file' Length: 4 + Space: ` ' Class: String + Argc: 5 Argv: `)' Length: 1 + Space: ` ' Class: Closing Punctuation or suffix + MACRO REQUEST: .Op Fl aC Ar file ) +DEBUGGING OFF +.Ed +.Pp +The first line of information tells the name of the calling +macro, here +.Ql \&.Op , +and the line number it appears on. +If one or more files are involved +(especially if text from another file is included) the line number +may be bogus. +If there is only one file, it should be accurate. +The second line gives the argument count, the argument +.Pq Ql \&Fl +and its length. +If the length of an argument is two characters, the +argument is tested to see if it is executable (unfortunately, any +register which contains a non-zero value appears executable). +The third line gives the space allotted for a class, and the +class type. +The problem here is the argument aC should not be +executable. +The four types of classes are string, executable, closing +punctuation and opening punctuation. +The last line shows the entire +argument list as it was read. +In this next example, the offending +.Ql \&aC +is escaped: +.Bd -literal -offset indent +\&.Db on +\&.Em An escaped \e&aC +\&.Db off +.Ed +.Bd -literal -offset indent +DEBUGGING ON +DEBUG(fargv) MACRO: `.Em' Line #: 2 + Argc: 1 Argv: `An' Length: 2 + Space: ` ' Class: String + Argc: 2 Argv: `escaped' Length: 7 + Space: ` ' Class: String + Argc: 3 Argv: `aC' Length: 2 + Space: ` ' Class: String + MACRO REQUEST: .Em An escaped &aC +DEBUGGING OFF +.Ed +.Pp +The argument +.Ql \e&aC +shows up with the same length of 2 as the +.Ql \e& +sequence produces a zero width, but a register +named +.Ql \e&aC +was not found and the type classified as string. +.Pp +Other diagnostics consist of usage statements and are self explanatory. +.Sh GROFF, TROFF AND NROFF +The +.Nm \-mdoc +package does not need compatibility mode with +.Xr groff . +.Pp +The package inhibits page breaks, and the headers and footers +which normally occur at those breaks with +.Xr nroff , +to make the manual more efficient for viewing on-line. +At the moment, +.Xr groff +with +.Fl T Ns Ar ascii +does eject the imaginary remainder of the page at end of file. +The inhibiting of the page breaks makes +.Xr nroff Ns 'd +files unsuitable for hardcopy. +There is a register named +.Ql \&cR +which can be set to zero in the site dependent style file +.Pa /usr/src/share/tmac/doc-nroff +to restore the old style behavior. +.Sh FILES +.Bl -tag -width /usr/share/man0/template.doc -compact +.It Pa /usr/share/tmac/tmac.doc +manual macro package +.It Pa /usr/share/misc/mdoc.template +template for writing a man page +.It Pa /usr/share/examples/mdoc/* +several example man pages +.El +.Sh SEE ALSO +.Xr man 1 , +.Xr troff 1 , +.Xr mdoc 7 +.Sh BUGS +Undesirable hyphenation on the dash of a flag +argument is not yet resolved, and causes +occasional mishaps in the +.Sx DESCRIPTION +section. +(line break on the hyphen). +.Pp +Predefined strings are not declared in documentation. +.Pp +Section 3f has not been added to the header routines. +.Pp +.Ql \&.Nm +font should be changed in +.Sx NAME +section. +.Pp +.Ql \&.Fn +needs to have a check to prevent splitting up +if the line length is too short. +Occasionally it +separates the last parenthesis, and sometimes +looks ridiculous if a line is in fill mode. +.Pp +The method used to prevent header and footer page +breaks (other than the initial header and footer) when using +nroff occasionally places an unsightly partially filled line (blank) +at the would be bottom of the page. +.Pp +The list and display macros to not do any keeps +and certainly should be able to. +.\" Note what happens if the parameter list overlaps a newline +.\" boundary. +.\" to make sure a line boundary is crossed: +.\" .Bd -literal +.\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[] +.\" .Ed +.\" .Pp +.\" produces, nudge nudge, +.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] , +.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] , +.\" nudge +.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] . +.\" .Pp +.\" If double quotes are used, for example: +.\" .Bd -literal +.\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q +.\" .Ed +.\" .Pp +.\" produces, nudge nudge, +.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" , +.\" nudge +.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" , +.\" nudge +.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" . +.\" .Pp +.\" Not a pretty sight... +.\" In a paragraph, a long parameter containing unpaddable spaces as +.\" in the former example will cause +.\" .Xr troff +.\" to break the line and spread +.\" the remaining words out. +.\" The latter example will adjust nicely to +.\" justified margins, but may break in between an argument and its +.\" declaration. +.\" In +.\" .Xr nroff +.\" the right margin adjustment is normally ragged and the problem is +.\" not as severe. diff --git a/man7/netdevice.7 b/man7/netdevice.7 new file mode 100644 index 000000000..4274136ae --- /dev/null +++ b/man7/netdevice.7 @@ -0,0 +1,264 @@ +'\" t +.\" Don't change the first line, it tells man that tbl is needed. +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" $Id: netdevice.7,v 1.10 2000/08/17 10:09:54 ak Exp $ +.TH NETDEVICE 7 1999-05-02 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +netdevice \- Low level access to Linux network devices +.SH SYNOPSIS +.B "#include " +.br +.B "#include " +.SH DESCRIPTION +This man page describes the sockets interface which is used to configure +network devices. + +Linux supports some standard ioctls to configure network devices. They +can be used on any socket's file descriptor regardless of the family or type. +They pass an +.B ifreq +structure: + +.nf +.ta 4 12 20 +struct ifreq { + char ifr_name[IFNAMSIZ]; /* Interface name */ + union { + struct sockaddr ifr_addr; + struct sockaddr ifr_dstaddr; + struct sockaddr ifr_broadaddr; + struct sockaddr ifr_netmask; + struct sockaddr ifr_hwaddr; + short ifr_flags; + int ifr_ifindex; + int ifr_metric; + int ifr_mtu; + struct ifmap ifr_map; + char ifr_slave[IFNAMSIZ]; + char ifr_newname[IFNAMSIZ]; + char * ifr_data; + }; +}; + +struct ifconf { + int ifc_len; /* size of buffer */ + union { + char * ifc_buf; /* buffer address */ + struct ifreq *ifc_req; /* array of structures */ + }; +}; +.ta +.fi + +Normally, the user specifies which device to affect by setting +.B ifr_name +to the name of the interface. All other members of the structure may +share memory. + +.SH IOCTLS +If an ioctl is marked as privileged then using it requires an effective +user id of 0 or the +.B CAP_NET_ADMIN +capability. If this is not the case +.B EPERM +will be returned. + +.TP +.B SIOCGIFNAME +Given the +.BR ifr_ifindex , +return the name of the interface in +.BR ifr_name . +This is the only ioctl which returns its result in +.BR ifr_name . + +.TP +.B SIOCGIFINDEX +Retrieve the interface index of the interface into +.BR ifr_ifindex . + +.TP +.BR SIOCGIFFLAGS ", " SIOCSIFFLAGS +Get or set the active flag word of the device. +.B ifr_flags +contains a bitmask of the following values: + +.TS +tab(:); +c s +l l. +Device flags +IFF_UP:Interface is running. +IFF_BROADCAST:Valid broadcast address set. +IFF_DEBUG:Internal debugging flag. +IFF_LOOPBACK:Interface is a loopback interface. +IFF_POINTOPOINT:Interface is a point-to-point link. +IFF_RUNNING:Resources allocated. +IFF_NOARP:No arp protocol, L2 destination address not set. +IFF_PROMISC:Interface is in promiscuous mode. +IFF_NOTRAILERS:Avoid use of trailers. +IFF_ALLMULTI:Receive all multicast packets. +IFF_MASTER:Master of a load balancing bundle. +IFF_SLAVE:Slave of a load balancing bundle. +IFF_MULTICAST:Supports multicast +IFF_PORTSEL:Is able to select media type via ifmap. +IFF_AUTOMEDIA:Auto media selection active. +IFF_DYNAMIC:T{ +The addresses are lost when the interface goes down. +T} +.TE + +Setting the active flag word is a privileged operation, but any +process may read it. +.TP +.BR SIOCGIFMETRIC ", " SIOCSIFMETRIC +Get or set the metric of the device using +.BR ifr_metric . +This is currently not implemented; it sets +.B ifr_metric +to 0 if you attempt to read it and returns +.B EOPNOTSUPP +if you attempt to set it. +.TP +.BR SIOCGIFMTU ", " SIOCSIFMTU +Get or set the MTU (Maximum Transfer Unit) of a device using +.BR ifr_mtu . +Setting the MTU is a privileged operation. Setting the MTU to +too small values may cause kernel crashes. +.TP +.BR SIOCGIFHWADDR ", " SIOCSIFHWADDR +Get or set the hardware address of a device using +.BR ifr_hwaddr . +The hardware address is specified in a struct +.IR sockaddr . +.I sa_family +contains the ARPHRD_* device type, +.I sa_data +the L2 hardware address starting from byte 0. +Setting the hardware address is a privileged operation. +.TP +.B SIOCSIFHWBROADCAST +Set the hardware broadcast address of a device from +.BR ifr_hwaddr . +This is a privileged operation. +.TP +.BR SIOCGIFMAP ", " SIOCSIFMAP +Get or set the interface's hardware parameters using +.BR ifr_map . +Setting the parameters is a privileged operation. + +.nf +.ta 4 20 42 +struct ifmap +{ + unsigned long mem_start; + unsigned long mem_end; + unsigned short base_addr; + unsigned char irq; + unsigned char dma; + unsigned char port; +}; +.ta +.fi + +The interpretation of the ifmap structure depends on the device driver +and the architecture. +.TP +.BR SIOCADDMULTI ", " SIOCDELMULTI +Add an address to or delete an address from the device's link layer +multicast filters using +.BR ifr_hwaddr . +These are privileged operations. +See also +.BR packet (7) +for an alternative. +.TP +.BR SIOCGIFTXQLEN ", " SIOCSIFTXQLEN +Get or set the transmit queue length of a device using +.BR ifr_qlen . +Setting the transmit queue length is a privileged operation. +.TP +.B SIOCSIFNAME +Changes the name of the interface specified in +.BR ifr_name +to +.BR ifr_newname . +This is a privileged operation. It is only allowed when the interface +is not up. +.TP +.B SIOCGIFCONF +Return a list of interface (transport layer) addresses. This currently +means only addresses of the AF_INET (IPv4) family for compatibility. +The user passes a +.B ifconf +structure as argument to the ioctl. It contains a pointer to an array of +.I ifreq +structures in +.B ifc_req +and its length in bytes in +.B ifc_len. +The kernel fills the ifreqs with all current L3 interface addresses that +are running: +.I ifr_name +contains the interface name (eth0:1 etc.), +.I ifr_addr +the address. +The kernel returns with the actual length in +.IR ifc_len . +If +.I ifc_len +is equal to the original length the buffer probably has overflowed +and you should retry with a bigger buffer to get all addresses. +When no error occurs the ioctl returns 0; +otherwise \-1. Overflow is no error. +\" XXX Slaving isn't supported in 2.2 +.\" .TP +.\" .BR SIOCGIFSLAVE ", " SIOCSIFSLAVE +.\" Get or set the slave device using +.\" .BR ifr_slave . +.\" Setting the slave device is a privileged operation. +.\" .PP +.\" XXX add amateur radio stuff. +.PP +Most protocols support their own ioctls to configure protocol specific +interface options. See the protocol man pages for a description. +For configuring IP addresses see +.BR ip (7). +.PP +In addition some devices support private ioctls. These are not described here. +.SH NOTES +Strictly seen, +.B SIOCGIFCONF +is IP specific and belongs in +.BR ip (7). +.LP +The names of interfaces with no addresses or that don't have the +.B IFF_RUNNING +flag set can be found via +.IR /proc/net/dev . +.LP +Local IPv6 IP addresses can be found via /proc/net or via +.BR rtnetlink (7). +.SH BUGS +glibc 2.1 is missing the +.I ifr_newname +macro in net/if.h. Add the following to your program as workaround: +.sp +.RS +.nf +.ta 4 20 42 +#ifndef ifr_newname +#define ifr_newname ifr_ifru.ifru_slave +#endif +.ta +.fi +.RE +.SH "SEE ALSO" +.BR capabilities (7), +.BR ip (7), +.BR proc (7), +.BR rtnetlink (7) diff --git a/man7/netlink.7 b/man7/netlink.7 new file mode 100644 index 000000000..0541ef4a5 --- /dev/null +++ b/man7/netlink.7 @@ -0,0 +1,254 @@ +'\" t +.\" Don't change the first line, it tells man that tbl is needed. +.\" This man page copyright 1998 by Andi Kleen. Subject to the GPL. +.\" This manpage copyright 1998 by Andi Kleen. Subject to the GPL. +.\" Based on the original comments from Alexey Kuznetsov +.\" $Id: netlink.7,v 1.8 2000/06/22 13:23:00 ak Exp $ +.TH NETLINK 7 1999-04-27 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +netlink, PF_NETLINK \- Communication between kernel and user +.SH SYNOPSIS +.nf +.\" XXX +.B #include +.br +.B #include +.br +.B #include +.br +.PP +.BI "netlink_socket = socket(PF_NETLINK, " socket_type ", " netlink_family ); +.SH DESCRIPTION +Netlink is used to transfer information between kernel modules and user space processes. +It consists of a standard sockets based interface for user processes and an +internal kernel API for kernel modules. The internal kernel interface is not +documented in this man page. Also there is an obsolete netlink interface via +netlink character devices, this interface is not documented here and is only +provided for backwards compatibility. + +Netlink is a datagram oriented service. Both +.B SOCK_RAW +and +.B SOCK_DGRAM +are valid values for +.IR socket_type ; +however the netlink protocol does not distinguish between +datagram and raw sockets. + +.I netlink_family +selects the kernel module or netlink group to communicate with. +The currently assigned netlink families are: +.TP +.B NETLINK_ROUTE +Receives routing updates and may be used to modify the IPv4 routing +table (see +.BR rtnetlink (7)). +.TP +.B NETLINK_FIREWALL +Receives packets sent by the IPv4 firewall code. +.TP +.B NETLINK_ARPD +For managing the arp table in user space. +.TP +.B NETLINK_ROUTE6 +Receives and sends IPv6 routing table updates. +.TP +.B NETLINK_IP6_FW +to receive packets that failed the IPv6 firewall checks (currently not +implemented). +.TP +.BR NETLINK_TAPBASE ... NETLINK_TAPBASE+15 +are the instances of the +.B ethertap +device. Ethertap is a pseudo network tunnel device that allows an +ethernet driver to be simulated from user space. +.TP +.B NETLINK_SKIP +Reserved for ENskip. +.TP +.B NETLINK_USERSOCK +is reserved for future user space protocols. +.PP +Netlink messages consist of a byte stream with one or multiple +.B nlmsghdr +headers and associated payload. +For multipart messages the first and all following headers have the +.B NLM_F_MULTI +flag set, except for the last header +which has the type +.BR NLMSG_DONE . +The byte stream should only be accessed with the standard +.B NLMSG_* +macros, see +.BR netlink (3). + +Netlink is not a reliable protocol. It tries its best to deliver a +message to its destination(s), but may drop messages when an out of +memory condition or other error occurs. For reliable transfer the +sender can request an acknowledgement from the receiver by setting the +.B NLM_F_ACK +flag. An acknowledgment is an +.B NLMSG_ERROR +packet with the error field set to 0. The application must generate +acks for received messages itself. The kernel tries to send an +.B NLMSG_ERROR +message for every failed packet. A user process should follow this convention too. + +Each netlink family has a set of 32 multicast groups. +When +.BR bind (2) +is called on the socket, the +.B nl_groups +field in the +.B sockaddr_nl +should be set to a bitmask of the groups which it wishes to listen to. +The default value for this field is zero which means that no multicasts +will be received. +A socket may multicast messages to any of the multicast groups by setting +.B nl_groups +to a bitmask of the groups it wishes to send to when it calls +.BR sendmsg (2) +or does a +.BR connect (2). +Only users with an effective uid of 0 or the +.B CAP_NET_ADMIN +capability may send or listen to +a netlink multicast group. +Any replies to a message received for a multicast group +should be sent back to the sending pid and the multicast group. + +.RS +.nf +.ta 4 13 25 +struct nlmsghdr +{ + __u32 nlmsg_len; /* Length of message including header */ + __u16 nlmsg_type; /* Message content */ + __u16 nlmsg_flags; /* Additional flags */ + __u32 nlmsg_seq; /* Sequence number */ + __u32 nlmsg_pid; /* PID of the process that opened the socket */ +}; + + +struct nlmsgerr +{ + int error; /* negative errno or 0 for acks. */ + struct nlmsghdr msg; /* message header that caused the error */ +}; +.ta +.fi +.RE + +After each +.B nlmsghdr +the payload follows. +.B nlmsg_type +can be one of the standard message types: +.B NLMSG_NOOP +message is to be ignored, +.B NLMSG_ERROR +the message signals an error and the payload contains a +.I nlmsgerr +structure, +.B NLMSG_DONE +message terminates a multipart message, +.\" 2.1.130 does not seem to use it. +.\" .B NLMSG_OVERRUN +.\" data was lost. + +A netlink family usually specifies more message types, see the +appropriate man pages for that, e.g. +.BR rtnetlink (7) +for +.IR NETLINK_ROUTE . + +.TS +tab(:); +l s +l l. +Standard Flag bits in nlmsg_flags +NLM_F_REQUEST:set on all request messages +NLM_F_MULTI:T{ +the message is part of a multipart message terminated by +.B +NLMSG_DONE +.\" XXX describe that +T} +NLM_F_ACK:reply with an acknowledgment on success +NLM_F_ECHO:echo this request +.TE + +.TS +tab(:); +l s +l l. +Additional flag bits for GET requests +NLM_F_ROOT:Return the complete table instead of a single entry. +NLM_F_MATCH:Not implemented yet. +NLM_F_ATOMIC:Return an atomic snapshot of the table. +NLM_F_DUMP:not documented yet. +.TE + +.TS +tab(:); +l s +l l. +Additional flag bits for NEW requests +NLM_F_REPLACE:Override existing object. +NLM_F_EXCL:Don't replace if the object already exists. +NLM_F_CREATE:Create object if it doesn't already exist. +NLM_F_APPEND:Add to the end of the object list. +.TE + +Note that NLM_F_ATOMIC requires CAP_NET_ADMIN or super user rights. + +.SH "ADDRESS FORMATS" +The +.B sockaddr_nl +structure describes a netlink client in user space or in the kernel. +A sockaddr_nl can be either unicast (only send to one peer) or send +to netlink groups (nl_groups not equal 0). + +.RS +.nf +struct sockaddr_nl +{ + sa_family_t nl_family; /* AF_NETLINK */ + unsigned short nl_pad; /* zero */ + pid_t nl_pid; /* process pid */ + __u32 nl_groups; /* multicast groups mask */ +}; +.fi +.RE + +.B nl_pid +is the pid of the process owning the destination socket, or 0 if the +destination is in the kernel. +.B nl_groups +is a bitmask with every bit representing a netlink group number. +.\" XXX describe what that is. + + +.SH BUGS +This man page is not complete. + +.SH NOTES +It is often better to use netlink via +.B libnetlink +than via the low level kernel interface. + +.SH VERSIONS +The socket interface to netlink is a new feature of Linux 2.2 + +Linux 2.0 supported a more primitive device based netlink interface (which +is still available as a compatibility option). This obsolete interface is not +described here. + +.SH "SEE ALSO" +.BR cmsg (3), +.BR netlink (3), +.BR capabilities (7), +.BR rtnetlink (7) +.PP +ftp://ftp.inr.ac.ru/ip-routing/iproute2* +for libnetlink diff --git a/man7/operator.7 b/man7/operator.7 new file mode 100644 index 000000000..9d5b54ab4 --- /dev/null +++ b/man7/operator.7 @@ -0,0 +1,65 @@ +.\" Copyright (c) 1989, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)operator.7 8.1 (Berkeley) 6/9/93 +.\" +.\" Copied shamelessly from FreeBSD with minor changes. 2003-05-21 +.\" Brian M. Carlson +.\" +.\" Restored automatic formatting from FreeBSD. 2003-08-24 +.\" Martin Schulze +.\" +.Dd August 24, 2003 +.Dt OPERATOR 7 +.Os +.Sh NAME +.Nm C operator +.Nd C operator precedence and order of evaluation +.Sh DESCRIPTION +This manual page lists C operators and their precedence in evaluation. +.Bd -ragged -offset indent -compact +.Bl -column "= += -= *= /= %= <<= >>= &= ^= |=" +.It Sy "Operator Associativity" +.It "-------- -------------" +.It "\&() [] -> . left to right" +.It "\&! ~ ++ -- - (type) * & sizeof right to left" +.It "\&* / % left to right" +.It "\&+ - left to right" +.It "\&<< >> left to right" +.It "\&< <= > >= left to right" +.It "\&== != left to right" +.It "\&& left to right" +.It "\&^ left to right" +.It "\&| left to right" +.It "\&&& left to right" +.It "\&|| left to right" +.It "\&?: right to left" +.It "\&= += -= *= /= %= <<= >>= &= ^= |= right to left" +.It "\&, left to right" +.El +.Ed +.\" \ No newline at end of file diff --git a/man7/packet.7 b/man7/packet.7 new file mode 100644 index 000000000..2f1da5455 --- /dev/null +++ b/man7/packet.7 @@ -0,0 +1,406 @@ +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" $Id: packet.7,v 1.13 2000/08/14 08:03:45 ak Exp $ +.TH PACKET 7 1999-04-29 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +packet, PF_PACKET \- packet interface on device level. +.SH SYNOPSIS +.nf +.B #include +.br +.B #include +.br +.B #include /* the L2 protocols */ +.sp +.BI "packet_socket = socket(PF_PACKET, int " socket_type ", int "protocol ); +.fi +.SH DESCRIPTION +Packet sockets are used to receive or send raw packets at the device driver +(OSI Layer 2) +level. They allow the user to implement protocol modules in user space +on top of the physical layer. + +The +.I socket_type +is either +.B SOCK_RAW +for raw packets including the link level header or +.B SOCK_DGRAM +for cooked packets with the link level header removed. The link level +header information is available in a common format in a +.BR sockaddr_ll . +.I protocol +is the IEEE 802.3 protocol number in network order. See the +.B +include file for a list of allowed protocols. When protocol +is set to +.B htons(ETH_P_ALL) +then all protocols are received. +All incoming packets of that protocol type will be passed to the packet +socket before they are passed to the protocols implemented in the kernel. + +Only processes with effective uid 0 or the +.B CAP_NET_RAW +capability may open packet sockets. + +.B SOCK_RAW +packets are passed to and from the device driver without any changes in +the packet data. When receiving a packet, the address is still parsed and +passed in a standard +.B sockaddr_ll +address structure. When transmitting a packet, the user supplied buffer +should contain the physical layer header. That packet is then +queued unmodified to the network driver of the interface defined by the +destination address. Some device drivers always add other headers. +.B SOCK_RAW +is similar to but not compatible with the obsolete +.B SOCK_PACKET +of Linux 2.0. + +.B SOCK_DGRAM +operates on a slightly higher level. The physical header is removed before +the packet is passed to the user. Packets sent through a +.B SOCK_DGRAM +packet socket get a suitable physical layer header based on the information +in the +.B sockaddr_ll +destination address before they are queued. + +By default all packets of the specified protocol type +are passed to a packet socket. To only get packets from a specific interface +use +.BR bind (2) +specifying an address in a +.B struct sockaddr_ll +to bind the packet socket to an interface. Only the +.B sll_protocol +and the +.B sll_ifindex +address fields are used for purposes of binding. + +The +.BR connect (2) +operation is not supported on packet sockets. + +When the +.B MSG_TRUNC +flag is passed to +.BR recvmsg (2), +.BR recv (2), +.BR recvfrom (2) +the real length of the packet on the wire is always returned, even when it +is longer than the buffer. + +.SH "ADDRESS TYPES" +The sockaddr_ll is a device independent physical layer address. + +.RS +.nf +.ta 4n 20n 35n +struct sockaddr_ll { + unsigned short sll_family; /* Always AF_PACKET */ + unsigned short sll_protocol; /* Physical layer protocol */ + int sll_ifindex; /* Interface number */ + unsigned short sll_hatype; /* Header type */ + unsigned char sll_pkttype; /* Packet type */ + unsigned char sll_halen; /* Length of address */ + unsigned char sll_addr[8]; /* Physical layer address */ +}; +.ta +.fi +.RE + +.B sll_protocol +is the standard ethernet protocol type in network order as defined +in the +.B linux/if_ether.h +include file. It defaults to the socket's protocol. +.B sll_ifindex +is the interface index of the interface +(see +.BR netdevice (7)); +0 matches any interface (only legal for binding). +.B sll_hatype +is a ARP type as defined in the +.B linux/if_arp.h +include file. +.B sll_pkttype +contains the packet type. Valid types are +.B PACKET_HOST +for a packet addressed to the local host, +.B PACKET_BROADCAST +for a physical layer broadcast packet, +.B PACKET_MULTICAST +for a packet sent to a physical layer multicast address, +.B PACKET_OTHERHOST +for a packet to some other host that has been caught by a device driver +in promiscuous mode, and +.B PACKET_OUTGOING +for a packet originated from the local host that is looped back to a packet +socket. These types make only sense for receiving. +.B sll_addr +and +.B sll_halen +contain the physical layer (e.g. IEEE 802.3) address and its length. The +exact interpretation depends on the device. + +When you send packets it is enough to specify +.BR sll_family , +.BR sll_addr , +.BR sll_halen , +.BR sll_ifindex . +The other fields should be 0. +.B sll_hatype +and +.B sll_pkttype +are set on received packets for your information. +For bind only +.B sll_protocol +and +.B sll_ifindex +are used. + +.SH "SOCKET OPTIONS" +Packet sockets can be used to configure physical layer multicasting +and promiscuous mode. It works by calling +.BR setsockopt (2) +on a packet socket for SOL_PACKET and one of the options +.B PACKET_ADD_MEMBERSHIP +to add a binding or +.B PACKET_DROP_MEMBERSHIP +to drop it. +They both expect a +.B packet_mreq +structure as argument: + +.RS +.nf +.ta 4n 20n 35n +struct packet_mreq +{ + int mr_ifindex; /* interface index */ + unsigned short mr_type; /* action */ + unsigned short mr_alen; /* address length */ + unsigned char mr_address[8]; /* physical layer address */ +}; +.ta +.fi +.RE + +.B mr_ifindex +contains the interface index for the interface whose status +should be changed. +The +.B mr_type +parameter specifies which action to perform. +.B PACKET_MR_PROMISC +enables receiving all packets on a shared medium - often known as +``promiscuous mode'', +.B PACKET_MR_MULTICAST +binds the socket to the physical layer multicast group specified in +.B mr_address +and +.BR mr_alen , +and +.B PACKET_MR_ALLMULTI +sets the socket up to receive all multicast packets arriving at the interface. + +In addition the traditional ioctls +.B SIOCSIFFLAGS, +.B SIOCADDMULTI, +.B SIOCDELMULTI +can be used for the same purpose. + + +.SH IOCTLS +.B SIOCGSTAMP +can be used to receive the time stamp of the last received packet. Argument +is a +.B struct timeval. + +In addition all standard ioctls defined in +.BR netdevice (7) +and +.BR socket (7) +are valid on packet sockets. + +.SH "ERROR HANDLING" +Packet sockets do no error handling other than errors occurred while passing +the packet to the device driver. They don't have the concept of a pending +error. + +.SH COMPATIBILITY +In Linux 2.0, the only way to get a packet socket was by calling +.BI "socket(PF_INET, SOCK_PACKET, " protocol )\fR. +This is still supported but strongly deprecated. +The main difference between the two methods is that +.B SOCK_PACKET +uses the old +.B struct sockaddr_pkt +to specify an interface, which doesn't provide physical layer independence. + +.RS +.nf +.ta 4n 20n 35n +struct sockaddr_pkt +{ + unsigned short spkt_family; + unsigned char spkt_device[14]; + unsigned short spkt_protocol; +}; +.ta +.fi +.RE + +.B spkt_family +contains +the device type, +.B spkt_protocol +is the IEEE 802.3 protocol type as defined in +.B +and +.B spkt_device +is the device name as a null terminated string, e.g. eth0. + +This structure is obsolete and should not be used in new code. + +.SH NOTES +For portable programs it is suggested to use +.B PF_PACKET +via +.BR pcap (3); +although this only covers a subset of the +.B PF_PACKET +features. + +The +.B SOCK_DGRAM +packet sockets make no attempt to create or parse the IEEE 802.2 LLC header +for a IEEE 802.3 frame. +When +.B ETH_P_802_3 +is specified as protocol for sending the kernel creates the +802.3 frame and fills out the length field; the user has to supply the LLC +header to get a fully conforming packet. Incoming 802.3 packets are not +multiplexed on the DSAP/SSAP protocol fields; instead they are supplied to the +user as protocol +.B ETH_P_802_2 +with the LLC header prepended. It is thus not possible to bind to +.B ETH_P_802_3; +bind to +.B ETH_P_802_2 +instead and do the protocol multiplex yourself. +The default for sending is the standard Ethernet DIX +encapsulation with the protocol filled in. + +Packet sockets are not subject to the input or output firewall chains. + +.SH ERRORS +.TP +.B ENETDOWN +Interface is not up. + +.TP +.B ENOTCONN +No interface address passed. + +.TP +.B ENODEV +Unknown device name or interface index specified in interface address. + +.TP +.B EMSGSIZE +Packet is bigger than interface MTU. + +.TP +.B ENOBUFS +Not enough memory to allocate the packet. + +.TP +.B EFAULT +User passed invalid memory address. + +.TP +.B EINVAL +Invalid argument. + +.TP +.B ENXIO +Interface address contained illegal interface index. + +.TP +.B EPERM +User has insufficient privileges to carry out this operation. + +.TP +.B EADDRNOTAVAIL +Unknown multicast group address passed. + +.TP +.B ENOENT +No packet received. + +In addition other errors may be generated by the low-level driver. +.SH VERSIONS +.B PF_PACKET +is a new feature in Linux 2.2. Earlier Linux versions supported only +.B SOCK_PACKET. + +.SH BUGS +glibc 2.1 does not have a define for +.B SOL_PACKET. +The suggested workaround is to use +.RS +.nf +#ifndef SOL_PACKET +#define SOL_PACKET 263 +#endif +.fi +.RE +This is fixed in later glibc versions and also does not occur on libc5 systems. + +The IEEE 802.2/803.3 LLC handling could be considered as a bug. + +Socket filters are not documented. + +The +.I MSG_TRUNC +recvmsg extension is an ugly hack and should be replaced by a control message. +There is currently no way to get the original destination address of +packets via SOCK_DGRAM. + +.SH HISTORICAL NOTE +The include file +.I +is present since glibc2.1. Older systems need +.sp +.nf +.B #include +.br +.B #include +.br +.B #include /* The L2 protocols */ +.br +.fi +.\" .SH CREDITS +.\" This man page was written by Andi Kleen with help from Matthew Wilcox. +.\" PF_PACKET in Linux 2.2 was implemented +.\" by Alexey Kuznetsov, based on code by Alan Cox and others. +.SH "SEE ALSO" +.BR socket (2), +.BR pcap (3), +.BR capabilities (7), +.BR ip (7), +.BR raw (7), +.BR socket (7) + +RFC 894 for the standard IP Ethernet encapsulation. + +RFC 1700 for the IEEE 802.3 IP encapsulation. + +The +.I +include file for physical layer protocols. diff --git a/man7/posixoptions.7 b/man7/posixoptions.7 new file mode 100644 index 000000000..641381e0c --- /dev/null +++ b/man7/posixoptions.7 @@ -0,0 +1,787 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.TH POSIXOPTIONS 7 2003-08-24 "POSIX" "Linux Programmer's Manual" +.SH NAME +posixoptions \- optional parts of the POSIX standard +.SH DESCRIPTION +The POSIX standard (the information below is from POSIX 1003.1-2001) +describes a set of behaviours and interfaces for a compliant system. +However, many interfaces are optional and there are feature test macros +to test the availability of interfaces at compile time, and functions +.BR sysconf (3), +.BR fpathconf (3), +.BR pathconf (3), +.BR confstr (3) +to do this at run time. From shell scripts one can use +.BR getconf (1). +For more detail, see +.BR sysconf (3). +.LP +We give the name of the POSIX abbreviation, the option, the name of the +.B sysconf() +parameter used to inquire about the option, and possibly +a very short description. +Much more precise detail can be found in the POSIX standard itself, +versions of which can nowadays be accessed freely on the web. +.SS "ADV - _POSIX_ADVISORY_INFO - _SC_ADVISORY_INFO" +The advisory functions +.br +.nf +.in +4 +.IR posix_fadvise() , +.IR posix_fallocate() , +.IR posix_memalign() , +.IR posix_madvise() +.br +.in -4 +.fi +are present. +.SS "AIO - _POSIX_ASYNCHRONOUS_IO - _SC_ASYNCHRONOUS_IO" +The header +.I +is present. +The functions +.br +.nf +.in +4 +.IR aio_cancel() , +.IR aio_error() , +.IR aio_fsync() , +.IR aio_read() , +.IR aio_return() , +.IR aio_suspend() , +.IR aio_write() , +.IR lio_listio() +.br +.in -4 +.fi +are present. +.SS "BAR - _POSIX_BARRIERS - _SC_BARRIERS" +This option implies the _POSIX_THREADS and +_POSIX_THREAD_SAFE_FUNCTIONS options. +The functions +.br +.nf +.in +4 +.IR pthread_barrier_destroy() , +.IR pthread_barrier_init() , +.IR pthread_barrier_wait() , +.IR pthread_barrierattr_destroy() , +.IR pthread_barrierattr_init() +.in -4 +.br +.fi +are present. +.\" .SS "BE" +.\" Batch environment. +.\" .SS "CD" +.\" C development. +.SS "--- - POSIX_CHOWN_RESTRICTED" +If this option is in effect (as it always is under POSIX 1003.1-2001) +then only root may change the owner of a file, and non-root can only +set the group of a file to one of the groups it belongs to. +This affects the functions +.IR chown() , +.IR fchown() . +.\" What about lchown() ? +.SS "CS - _POSIX_CLOCK_SELECTION - _SC_CLOCK_SELECTION" +This option implies the _POSIX_TIMERS option. +The functions +.br +.nf +.in +4 +.IR pthread_condattr_getclock() , +.IR pthread_condattr_setclock() , +.IR clock_nanosleep() +.in -4 +.br +.fi +are present. +If CLOCK_REALTIME is changed by the function +.IR clock_settime() , +then this affects all timers set for an absolute time. +.SS "CPT - _POSIX_CPUTIME - _SC_CPUTIME" +The clockID CLOCK_PROCESS_CPUTIME_ID is supported. +The initial value of this clock is 0 for each process. +This option implies the _POSIX_TIMERS option. +The function +.IR clock_getcpuclockid() +is present. +.\" .SS "FD" +.\" Fortran development +.\" .SS "FR" +.\" Fortran runtime +.SS "--- - _POSIX_FILE_LOCKING - _SC_FILE_LOCKING" +This option has been deleted. Not in final XPG6. +.SS "FSC - _POSIX_FSYNC - _SC_FSYNC " +The function +.I fsync() +is present. +.SS "IP6 - _POSIX_IPV6 - _SC_IPV6" +Internet Protocol Version 6 is supported. +.SS "--- - _POSIX_JOB_CONTROL - _SC_JOB_CONTROL" +If this option is in effect (as it always is under POSIX 1003.1-2001) +then the system implements POSIX \- style job control, and the functions +.br +.nf +.in +4 +.IR setpgid() , +.IR tcdrain() , +.IR tcflush() , +.IR tcgetpgrp() , +.IR tcsendbreak() , +.IR tcsetattr() , +.IR tcsetpgrp() +.in -4 +are present. +.fi +.SS "MF - _POSIX_MAPPED_FILES - _SC_MAPPED_FILES" +Shared memory is supported. The include file +.I +is present. The functions +.IR mmap() , +.IR msync() , +.IR munmap() +are present. +.SS "ML - _POSIX_MEMLOCK - _SC_MEMLOCK" +Shared memory can be locked into core. The functions +.IR mlockall() , +.IR munlockall() +are present. +.SS "MR/MLR - _POSIX_MEMLOCK_RANGE - _SC_MEMLOCK_RANGE" +More precisely, ranges can be locked into core. The functions +.IR mlock() , +.IR munlock() +are present. +.SS "MPR - _POSIX_MEMORY_PROTECTION - _SC_MEMORY_PROTECTION" +The function +.I mprotect() +is present. +.SS "MSG - _POSIX_MESSAGE_PASSING - _SC_MESSAGE_PASSING" +The include file +.IR +is present. The functions +.br +.nf +.in +4 +.IR mq_close() , +.IR mq_getattr() , +.IR mq_notify() , +.IR mq_open() , +.IR mq_receive() , +.IR mq_send() , +.IR mq_setattr() , +.IR mq_unlink() +.br +.in -4 +.fi +are present. +.SS "MON - _POSIX_MONOTONIC_CLOCK - _SC_MONOTONIC_CLOCK" +.nf +CLOCK_MONOTONIC is supported. +This option implies the _POSIX_TIMERS option. +Affected functions are +.in +4 +.IR aio_suspend() , +.IR clock_getres() , +.IR clock_gettime() , +.IR clock_settime() , +.IR timer_create() . +.in -4 +.fi +.SS "--- - _POSIX_MULTI_PROCESS - _SC_MULTI_PROCESS" +This option has been deleted. Not in final XPG6. +.\" .SS "MX" +.\" IEC 60559 Floating-Point Option. +.SS "--- - _POSIX_NO_TRUNC" +If this option is in effect (as it always is under POSIX 1003.1-2001) +then pathname components longer than NAME_MAX are not truncated, +but give an error. +This property may be dependent on the path prefix of the component. +.SS "PIO - _POSIX_PRIORITIZED_IO - _SC_PRIORITIZED_IO" +This option says that one can specify priorities for asynchronous I/O. +This affects the functions +.br +.nf +.in +4 +.IR aio_read() , +.IR aio_write() . +.in -4 +.fi +.SS "PS - _POSIX_PRIORITY_SCHEDULING - _SC_PRIORITY_SCHEDULING" +The include file +.I +is present. The functions +.br +.nf +.in +4 +.IR sched_get_priority_max() , +.IR sched_get_priority_min() , +.IR sched_getparam() , +.IR sched_getscheduler() , +.IR sched_rr_get_interval() , +.IR sched_setparam() , +.IR sched_setscheduler() , +.IR sched_yield() +.in -4 +.br +.fi +are present. +If also _POSIX_SPAWN is in effect, then the functions +.br +.nf +.in +4 +.IR posix_spawnattr_getschedparam() , +.IR posix_spawnattr_getschedpolicy() , +.IR posix_spawnattr_setschedparam() , +.IR posix_spawnattr_setschedpolicy() +.in -4 +are present. +.fi +.SS "RS - _POSIX_RAW_SOCKETS" +Raw sockets are supported. Affected functions are +.IR getsockopt() , +.IR setsockopt() . +.SS "--- - _POSIX_READER_WRITER_LOCKS - _SC_READER_WRITER_LOCKS" +This option implies the _POSIX_THREADS option. Conversely, +under POSIX 1003.1-2001 the _POSIX_THREADS option implies this option. +.nf +The functions +.in +4 +.IR pthread_rwlock_destroy() , +.IR pthread_rwlock_init() , +.IR pthread_rwlock_rdlock() , +.IR pthread_rwlock_tryrdlock() , +.IR pthread_rwlock_trywrlock() , +.IR pthread_rwlock_unlock() , +.IR pthread_rwlock_wrlock() , +.IR pthread_rwlockattr_destroy() , +.IR pthread_rwlockattr_init() +.in -4 +are present. +.fi +.SS "RTS - _POSIX_REALTIME_SIGNALS - _SC_REALTIME_SIGNALS" +Realtime signals are supported. The functions +.br +.nf +.in +4 +.IR sigqueue() , +.IR sigtimedwait() , +.IR sigwaitinfo() +.br +.in -4 +.fi +are present. +.SS "--- - _POSIX_REGEXP - _SC_REGEXP" +If this option is in effect (as it always is under POSIX 1003.1-2001) +then POSIX regular expressions are supported and the functions +.br +.nf +.in +4 +.IR regcomp() , +.IR regerror() , +.IR regexec() , +.IR regfree() +.br +.in -4 +.fi +are present. +.SS "--- - _POSIX_SAVED_IDS - _SC_SAVED_IDS" +If this option is in effect (as it always is under POSIX 1003.1-2001) +then a process has a saved set-user-ID and a saved set-group-ID. +Affected functions are +.br +.nf +.in +4 +.IR exec() , +.IR kill() , +.IR seteuid() , +.IR setegid() , +.IR setgid() , +.IR setuid() . +.br +.in -4 +.fi +.\" .SS "SD" +.\" Software development +.SS "SEM - _POSIX_SEMAPHORES - _SC_SEMAPHORES" +The include file +.I +is present. +The functions +.br +.nf +.in +4 +.IR sem_close() , +.IR sem_destroy() , +.IR sem_getvalue() , +.IR sem_init() , +.IR sem_open() , +.IR sem_post() , +.IR sem_trywait() , +.IR sem_unlink() , +.IR sem_wait() +.br +.in -4 +.fi +are present. +.SS "SHM - _POSIX_SHARED_MEMORY_OBJECTS - _SC_SHARED_MEMORY_OBJECTS" +The functions +.br +.nf +.in +4 +.IR mmap() , +.IR munmap() , +.IR shm_open() , +.IR shm_unlink() +.br +.in -4 +.fi +are present. +.SS "--- - _POSIX_SHELL - _SC_SHELL" +If this option is in effect (as it always is under POSIX 1003.1-2001), +the function +.IR system() +is present. +.SS "SPN - _POSIX_SPAWN - _SC_SPAWN" +This option describes support for process creation in a context where +it is difficult or impossible to use +.IR fork() , +e.g. because no MMU is present. +If _POSIX_SPAWN is in effect, then the include file +.I +and the functions +.br +.nf +.in +4 +.IR posix_spawn() , +.IR posix_spawn_file_actions_addclose() , +.IR posix_spawn_file_actions_adddup2() , +.IR posix_spawn_file_actions_addopen() , +.IR posix_spawn_file_actions_destroy() , +.IR posix_spawn_file_actions_init() , +.IR posix_spawnattr_destroy() , +.IR posix_spawnattr_getsigdefault() , +.IR posix_spawnattr_getflags() , +.IR posix_spawnattr_getpgroup() , +.IR posix_spawnattr_getsigmask() , +.IR posix_spawnattr_init() , +.IR posix_spawnattr_setsigdefault() , +.IR posix_spawnattr_setflags() , +.IR posix_spawnattr_setpgroup() , +.IR posix_spawnattr_setsigmask() , +.IR posix_spawnp() +.in -4 +.br +.fi +are present. +If also _POSIX_PRIORITY_SCHEDULING is in effect, then +the functions +.br +.nf +.in +4 +.IR posix_spawnattr_getschedparam() , +.IR posix_spawnattr_getschedpolicy() , +.IR posix_spawnattr_setschedparam() , +.IR posix_spawnattr_setschedpolicy() +.in -4 +are present. +.fi +.SS "SPI - _POSIX_SPIN_LOCKS - _SC_SPIN_LOCKS" +This option implies the _POSIX_THREADS and +_POSIX_THREAD_SAFE_FUNCTIONS options. +The functions +.br +.nf +.in +4 +.IR pthread_spin_destroy() , +.IR pthread_spin_init() , +.IR pthread_spin_lock() , +.IR pthread_spin_trylock() , +.IR pthread_spin_unlock() +.in -4 +.br +.fi +are present. +.SS "SS - _POSIX_SPORADIC_SERVER - _SC_SPORADIC_SERVER" +The scheduling policy SCHED_SPORADIC is supported. +This option implies the _POSIX_PRIORITY_SCHEDULING option. +Affected functions are +.br +.nf +.in +4 +.IR sched_setparam() , +.IR sched_setscheduler() . +.in -4 +.br +.fi +.SS "SIO - _POSIX_SYNCHRONIZED_IO - _SC_SYNCHRONIZED_IO" +Affected functions are +.IR open() , +.IR msync() , +.IR fsync() , +.IR fdatasync() . +.SS "TSA - _POSIX_THREAD_ATTR_STACKADDR - _SC_THREAD_ATTR_STACKADDR" +Affected functions are +.br +.nf +.in +4 +.IR pthread_attr_getstack() , +.IR pthread_attr_getstackaddr() , +.IR pthread_attr_setstack() , +.IR pthread_attr_setstackaddr() . +.in -4 +.br +.fi +.SS "TSS - _POSIX_THREAD_ATTR_STACKSIZE - _SC_THREAD_ATTR_STACKSIZE" +Affected functions are +.br +.nf +.in +4 +.IR pthread_attr_getstack() , +.IR pthread_attr_getstacksize() , +.IR pthread_attr_setstack() , +.IR pthread_attr_setstacksize() . +.in -4 +.br +.fi +.SS "TCT - _POSIX_THREAD_CPUTIME - _SC_THREAD_CPUTIME" +The clockID CLOCK_THREAD_CPUTIME_ID is supported. +This option implies the _POSIX_TIMERS option. +Affected functions are +.br +.nf +.in +4 +.IR pthread_getcpuclockid() , +.IR clock_getres() , +.IR clock_gettime() , +.IR clock_settime() , +.IR timer_create() . +.in -4 +.br +.fi +.SS "TPI - _POSIX_THREAD_PRIO_INHERIT - _SC_THREAD_PRIO_INHERIT" +Affected functions are +.br +.nf +.in +4 +.IR pthread_mutexattr_getprotocol() , +.IR pthread_mutexattr_setprotocol() . +.in -4 +.br +.fi +.SS "TPP - _POSIX_THREAD_PRIO_PROTECT - _SC_THREAD_PRIO_PROTECT" +Affected functions are +.br +.nf +.in +4 +.IR pthread_mutex_getprioceiling() , +.IR pthread_mutex_setprioceiling() , +.IR pthread_mutexattr_getprioceiling() , +.IR pthread_mutexattr_getprotocol() , +.IR pthread_mutexattr_setprioceiling() , +.IR pthread_mutexattr_setprotocol() . +.in -4 +.br +.fi +.SS "TPS - _POSIX_THREAD_PRIORITY_SCHEDULING - _SC_THREAD_PRIORITY_SCHEDULING" +If this option is in effect, the different threads inside a process +can run with different priorities and/or different schedulers. +Affected functions are +.br +.nf +.in +4 +.IR pthread_attr_getinheritsched() , +.IR pthread_attr_getschedpolicy() , +.IR pthread_attr_getscope() , +.IR pthread_attr_setinheritsched() , +.IR pthread_attr_setschedpolicy() , +.IR pthread_attr_setscope() , +.IR pthread_getschedparam() , +.IR pthread_setschedparam() , +.IR pthread_setschedprio() . +.in -4 +.br +.fi +.SS "TSH - _POSIX_THREAD_PROCESS_SHARED - _SC_THREAD_PROCESS_SHARED" +Affected functions are +.br +.nf +.in +4 +.IR pthread_barrierattr_getpshared() , +.IR pthread_barrierattr_setpshared() , +.IR pthread_condattr_getpshared() , +.IR pthread_condattr_setpshared() , +.IR pthread_mutexattr_getpshared() , +.IR pthread_mutexattr_setpshared() , +.IR pthread_rwlockattr_getpshared() , +.IR pthread_rwlockattr_setpshared() . +.in -4 +.br +.fi +.SS "TSF - _POSIX_THREAD_SAFE_FUNCTIONS - _SC_THREAD_SAFE_FUNCTIONS" +Affected functions are +.br +.nf +.in +4 +.IR readdir_r() , +.IR getgrgid_r() , +.IR getgrnam_r() , +.IR getpwnam_r() , +.IR getpwuid_r() , +.IR flockfile() , +.IR ftrylockfile() , +.IR funlockfile() , +.IR getc_unlocked() , +.IR getchar_unlocked() , +.IR putc_unlocked() , +.IR putchar_unlocked() , +.IR rand_r() , +.IR strerror_r() , +.IR strtok_r() , +.IR asctime_r() , +.IR ctime_r() , +.IR gmtime_r() , +.IR localtime_r() . +.in -4 +.br +.fi +.SS "TSP - _POSIX_THREAD_SPORADIC_SERVER - _SC_THREAD_SPORADIC_SERVER" +This option implies the _POSIX_THREAD_PRIORITY_SCHEDULING option. +Affected functions are +.br +.nf +.in +4 +.IR sched_getparam() , +.IR sched_setparam() , +.IR sched_setscheduler() . +.in -4 +.br +.fi +.SS "THR - _POSIX_THREADS - _SC_THREADS" +Basic support for POSIX threads is available. The functions +.br +.nf +.in +4 +.IR pthread_atfork() , +.IR pthread_attr_destroy() , +.IR pthread_attr_getdetachstate() , +.IR pthread_attr_getschedparam() , +.IR pthread_attr_init() , +.IR pthread_attr_setdetachstate() , +.IR pthread_attr_setschedparam() , +.IR pthread_cancel() , +.IR pthread_cleanup_push() , +.IR pthread_cleanup_pop() , +.IR pthread_cond_broadcast() , +.IR pthread_cond_destroy() , +.IR pthread_cond_init() , +.IR pthread_cond_signal() , +.IR pthread_cond_timedwait() , +.IR pthread_cond_wait() , +.IR pthread_condattr_destroy() , +.IR pthread_condattr_init() , +.IR pthread_create() , +.IR pthread_detach() , +.IR pthread_equal() , +.IR pthread_exit() , +.IR pthread_getspecific() , +.IR pthread_join( , +.IR pthread_key_create() , +.IR pthread_key_delete() , +.IR pthread_mutex_destroy() , +.IR pthread_mutex_init() , +.IR pthread_mutex_lock() , +.IR pthread_mutex_trylock() , +.IR pthread_mutex_unlock() , +.IR pthread_mutexattr_destroy() , +.IR pthread_mutexattr_init() , +.IR pthread_once() , +.IR pthread_rwlock_destroy() , +.IR pthread_rwlock_init() , +.IR pthread_rwlock_rdlock() , +.IR pthread_rwlock_tryrdlock() , +.IR pthread_rwlock_trywrlock() , +.IR pthread_rwlock_unlock() , +.IR pthread_rwlock_wrlock() , +.IR pthread_rwlockattr_destroy() , +.IR pthread_rwlockattr_init() , +.IR pthread_self() , +.IR pthread_setcancelstate() , +.IR pthread_setcanceltype() , +.IR pthread_setspecific() , +.IR pthread_testcancel() +.in -4 +.br +.fi +are present. +.SS "TMO - _POSIX_TIMEOUTS - _SC_TIMEOUTS" +The functions +.br +.nf +.in +4 +.IR mq_timedreceive() , +.IR mq_timedsend() , +.IR pthread_mutex_timedlock() , +.IR pthread_rwlock_timedrdlock() , +.IR pthread_rwlock_timedwrlock() , +.IR sem_timedwait() , +.IR posix_trace_timedgetnext_event() +.in -4 +.br +.fi +are present. +.SS "TMR - _POSIX_TIMERS - _SC_TIMERS" +The functions +.br +.nf +.in +4 +.IR clock_getres() , +.IR clock_gettime() , +.IR clock_settime() , +.IR nanosleep() , +.IR timer_create() , +.IR timer_delete() , +.IR timer_gettime() , +.IR timer_getoverrun() , +.IR timer_settime() +.in -4 +.br +.fi +are present. +.SS "TRC - _POSIX_TRACE - _SC_TRACE" +POSIX tracing is available. The functions +.br +.nf +.in +4 +.IR posix_trace_attr_destroy() , +.IR posix_trace_attr_getclockres() , +.IR posix_trace_attr_getcreatetime() , +.IR posix_trace_attr_getgenversion() , +.IR posix_trace_attr_getmaxdatasize() , +.IR posix_trace_attr_getmaxsystemeventsize() , +.IR posix_trace_attr_getmaxusereventsize() , +.IR posix_trace_attr_getname() , +.IR posix_trace_attr_getstreamfullpolicy() , +.IR posix_trace_attr_getstreamsize() , +.IR posix_trace_attr_init() , +.IR posix_trace_attr_setmaxdatasize() , +.IR posix_trace_attr_setname() , +.IR posix_trace_attr_setstreamsize() , +.IR posix_trace_attr_setstreamfullpolicy() , +.IR posix_trace_clear() , +.IR posix_trace_create() , +.IR posix_trace_event() , +.IR posix_trace_eventid_equal() , +.IR posix_trace_eventid_get_name() , +.IR posix_trace_eventid_open() , +.IR posix_trace_eventtypelist_getnext_id() , +.IR posix_trace_eventtypelist_rewind() , +.IR posix_trace_flush() , +.IR posix_trace_get_attr() , +.IR posix_trace_get_status() , +.IR posix_trace_getnext_event() , +.IR posix_trace_shutdown() , +.IR posix_trace_start() , +.IR posix_trace_stop() , +.IR posix_trace_trygetnext_event() +.in -4 +.br +.fi +are present. +.SS "TEF - _POSIX_TRACE_EVENT_FILTER - _SC_TRACE_EVENT_FILTER" +This option implies the _POSIX_TRACE option. +The functions +.br +.nf +.in +4 +.IR posix_trace_eventset_add() , +.IR posix_trace_eventset_del() , +.IR posix_trace_eventset_empty() , +.IR posix_trace_eventset_fill() , +.IR posix_trace_eventset_ismember() , +.IR posix_trace_get_filter() , +.IR posix_trace_set_filter() , +.IR posix_trace_trid_eventid_open() +.in -4 +.br +.fi +are present. +.SS "TRI - _POSIX_TRACE_INHERIT - _SC_TRACE_INHERIT" +Tracing children of the traced process is supported. +This option implies the _POSIX_TRACE option. +The functions +.br +.nf +.in +4 +.IR posix_trace_attr_getinherited() , +.IR posix_trace_attr_setinherited() +.in -4 +.br +.fi +are present. +.SS "TRL - _POSIX_TRACE_LOG - _SC_TRACE_LOG" +This option implies the _POSIX_TRACE option. +The functions +.br +.nf +.in +4 +.IR posix_trace_attr_getlogfullpolicy() , +.IR posix_trace_attr_getlogsize() , +.IR posix_trace_attr_setlogfullpolicy() , +.IR posix_trace_attr_setlogsize() , +.IR posix_trace_close() , +.IR posix_trace_create_withlog() , +.IR posix_trace_open() , +.IR posix_trace_rewind() +.in -4 +.br +.fi +are present. +.SS "TYM - _POSIX_TYPED_MEMORY_OBJECTS - _SC_TYPED_MEMORY_OBJECT" +The functions +.br +.nf +.in +4 +.IR posix_mem_offset() , +.IR posix_typed_mem_get_info() , +.IR posix_typed_mem_open() +.in -4 +.br +.fi +are present. +.SS "--- - _POSIX_VDISABLE" +Always present (probably 0). Value to set a changeable special control +character to to indicate that it is disabled. + +.SH "XOPEN EXTENSIONS" +.BR _XOPEN_CRYPT , +.BR _XOPEN_LEGACY , +.BR _XOPEN_REALTIME , +.BR _XOPEN_REALTIME_THREADS , +.BR _XOPEN_UNIX . + +.\" To be described. + +.SH "SEE ALSO" +.BR sysconf (3) diff --git a/man7/raw.7 b/man7/raw.7 new file mode 100644 index 000000000..44e80a3d1 --- /dev/null +++ b/man7/raw.7 @@ -0,0 +1,263 @@ +'\" t +.\" Don't change the first line, it tells man that we need tbl. +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" Please send bug reports, corrections and suggestions for improvements to +.\" +.\" $Id: raw.7,v 1.6 1999/06/05 10:32:08 freitag Exp $ +.TH RAW 7 1998-10-02 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +raw, SOCK_RAW \- Linux IPv4 raw sockets +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.BI "raw_socket = socket(PF_INET, SOCK_RAW, int " protocol ); + +.SH DESCRIPTION +Raw sockets allow new IPv4 protocols to be implemented in user space. +A raw socket receives or sends the raw datagram not including link level headers. + +The IPv4 layer generates an IP header when sending a packet unless the +.B IP_HDRINCL +socket option is enabled on the socket. +When it is enabled, the packet must contain an IP header. +For receiving the IP header is always included in the packet. + +Only processes with an effective user id of 0 or the +.B CAP_NET_RAW +capability are allowed to open raw sockets. + +All packets or errors matching the +.I protocol +number specified +for the raw socket are passed to this socket. For a list of the +allowed protocols see RFC1700 assigned numbers and +.BR getprotobyname (3). + +A protocol of +.B IPPROTO_RAW +implies enabled +.B IP_HDRINCL +and is able to send any IP protocol that is specified in the passed header. +Receiving of all IP protocols via +.B IPPROTO_RAW +is not possible using raw sockets. + +.TS +tab(:) allbox; +c s +l l. +IP Header fields modified on sending by IP_HDRINCL +IP Checksum:Always filled in. +Source Address:Filled in when zero. +Packet Id:Filled in when zero. +Total Length:Always filled in. +.TE +.PP + +If +.B IP_HDRINCL +is specified and the IP header has a non-zero destination address then +the destination address of the socket is used to route the packet. When +.B MSG_DONTROUTE +is specified the destination address should refer to a local interface, +otherwise a routing table lookup is done anyways but gatewayed routes +are ignored. + +If +.B IP_HDRINCL +isn't set then IP header options can be set on raw sockets with +.BR setsockopt (2); +see +.BR ip (7) +for more information. + +In Linux 2.2 all IP header fields and options can be set using +IP socket options. This means raw sockets are usually only needed for new +protocols or protocols with no user interface (like ICMP). + +When a packet is received, it is passed to any raw sockets which have +been bound to its protocol before it is passed to other protocol handlers +(e.g. kernel protocol modules). + +.SH "ADDRESS FORMAT" + +Raw sockets use the standard +.B sockaddr_in +address structure defined in +.BR ip (7). +The +The +.B sin_port +field could be used to specify the IP protocol number, +but it is ignored for sending in Linux 2.2 and should be always +set to 0 (see BUGS) +For incoming packets +.B sin_port +is set to the protocol of the packet. +See the +.B +include file for valid IP protocols. + +.SH "SOCKET OPTIONS" +Raw socket options can be set with +.BR setsockopt (2) +and read with +.BR getsockopt (2) +by passing the +.I SOL_RAW +family flag. + +.TP +.B ICMP_FILTER +Enable a special filter for raw sockets bound to the +.B IPPROTO_ICMP +protocol. The value has a bit set for each ICMP message type which +should be filtered out. The default is to filter no ICMP messages. + +.PP +In addition all +.BR ip (7) +.B SOL_IP +socket options valid for datagram sockets are supported. + +.SH NOTES +Raw sockets fragment a packet when its total length exceeds the interface MTU +(but see BUGS). +A more network friendly and faster alternative is to implement path MTU +discovery as described in the +.B IP_MTU_DISCOVER +section of +.BR ip (7). + +A raw socket can be bound to a specific local address using the +.BR bind (2) +call. If it isn't bound all packets with the specified IP protocol are received. +In addition a RAW socket can be bound to a specific network device using +.B SO_BINDTODEVICE; +see +.BR socket (7). + +An +.B IPPROTO_RAW +socket is send only. +If you really want to receive all IP packets use a +.BR packet (7) +socket with the +.B ETH_P_IP +protocol. Note that packet sockets don't reassemble IP fragments, unlike raw sockets. + +If you want to receive all ICMP packets for a datagram socket it is often better +to use +.B IP_RECVERR +on that particular socket; see +.BR ip (7). + +Raw sockets may tap all IP protocols in Linux, even +protocols like ICMP or TCP which have a protocol module in the kernel. In +this case the packets are passed to both the kernel module and the raw +socket(s). This should not be relied upon in portable programs, many other BSD +socket implementation have limitations here. + +Linux never changes headers passed from the user (except for filling in some +zeroed fields as described for +.BR IP_HDRINCL ). +This differs from many other implementations of raw sockets. + +RAW sockets are generally rather unportable and should be avoided in programs +intended to be portable. + +Sending on raw sockets should take the IP protocol from +.B sin_port; +this ability was lost in Linux 2.2. Work around is to use +.B IP_HDRINCL. + +.SH "ERROR HANDLING" +Errors originating from the network are only passed to the user when the +socket is connected or the +.B IP_RECVERR +flag is enabled. For connected sockets only +.B EMSGSIZE +and +.B EPROTO +are passed for compatibility. With +.B IP_RECVERR +all network errors are saved in the error queue. +.SH ERRORS +.TP +.B EMSGSIZE +Packet too big. Either Path MTU Discovery is enabled (the +.B IP_MTU_DISCOVER +socket flag) or the packet size exceeds the maximum allowed IPv4 packet size +of 64KB. +.TP +.B EACCES +User tried to send to a broadcast address without having the broadcast flag +set on the socket. +.TP +.B EPROTO +An ICMP error has arrived reporting a parameter problem. +.TP +.B EFAULT +An invalid memory address was supplied. +.TP +.B EOPNOTSUPP +Invalid flag has been passed to a socket call (like +.BR MSG_OOB ). +.TP +.B EINVAL +Invalid argument. +.TP +.B EPERM +The user doesn't have permission to open raw sockets. Only processes +with a effective user id of 0 or the +.B CAP_NET_RAW +attribute may do that. + +.SH VERSIONS +.B IP_RECVERR +and +.B ICMP_FILTER +are new in Linux 2.2. They are Linux extensions +and should not be used in portable programs. + +Linux 2.0 enabled some bug-to-bug compatibility with BSD in the raw socket code +when the SO_BSDCOMPAT flag was set - that has been removed in 2.2. + +.SH BUGS +Transparent proxy extensions are not described. + +When the +.B IP_HDRINCL +option is set datagrams will not be fragmented and are limited to the interface +MTU. This is a limitation in Linux 2.2. + +Setting the IP protocol for sending in +.B sin_port +got lost in Linux 2.2. The protocol that socket was bound to or that +was specified in the initial +.BR socket (2) +call is always used. + +.SH AUTHORS +This man page was written by Andi Kleen. + +.SH "SEE ALSO" +.BR recvmsg (2), +.BR sendmsg (2), +.BR capabilities (7), +.BR ip (7), +.BR socket (7) + +.B RFC1191 +for path MTU discovery. + +.B RFC791 +and the +.B +include file for the IP protocol. diff --git a/man7/regex.7 b/man7/regex.7 new file mode 100644 index 000000000..9a87d31d3 --- /dev/null +++ b/man7/regex.7 @@ -0,0 +1,264 @@ +.\" From Henry Spencer's regex package (as found in the apache +.\" distribution). The package carries the following copyright: +.\" +.\" Copyright 1992, 1993, 1994 Henry Spencer. All rights reserved. +.\" This software is not subject to any license of the American Telephone +.\" and Telegraph Company or of the Regents of the University of California. +.\" +.\" Permission is granted to anyone to use this software for any purpose +.\" on any computer system, and to alter it and redistribute it, subject +.\" to the following restrictions: +.\" +.\" 1. The author is not responsible for the consequences of use of this +.\" software, no matter how awful, even if they arise from flaws in it. +.\" +.\" 2. The origin of this software must not be misrepresented, either by +.\" explicit claim or by omission. Since few users ever read sources, +.\" credits must appear in the documentation. +.\" +.\" 3. Altered versions must be plainly marked as such, and must not be +.\" misrepresented as being the original software. Since few users +.\" ever read sources, credits must appear in the documentation. +.\" +.\" 4. This notice may not be removed or altered. +.\" +.\" In order to comply with `credits must appear in the documentation' +.\" I added an AUTHOR paragraph below - aeb. +.\" +.\" In the default nroff environment there is no dagger \(dg. +.ie t .ds dg \(dg +.el .ds dg (!) +.TH REGEX 7 1994-02-07 +.SH NAME +regex \- POSIX 1003.2 regular expressions +.SH DESCRIPTION +Regular expressions (``RE''s), +as defined in POSIX 1003.2, come in two forms: +modern REs (roughly those of +.IR egrep ; +1003.2 calls these ``extended'' REs) +and obsolete REs (roughly those of +.BR ed (1); +1003.2 ``basic'' REs). +Obsolete REs mostly exist for backward compatibility in some old programs; +they will be discussed at the end. +1003.2 leaves some aspects of RE syntax and semantics open; +`\*(dg' marks decisions on these aspects that +may not be fully portable to other 1003.2 implementations. +.PP +A (modern) RE is one\*(dg or more non-empty\*(dg \fIbranches\fR, +separated by `|'. +It matches anything that matches one of the branches. +.PP +A branch is one\*(dg or more \fIpieces\fR, concatenated. +It matches a match for the first, followed by a match for the second, etc. +.PP +A piece is an \fIatom\fR possibly followed +by a single\*(dg `*', `+', `?', or \fIbound\fR. +An atom followed by `*' matches a sequence of 0 or more matches of the atom. +An atom followed by `+' matches a sequence of 1 or more matches of the atom. +An atom followed by `?' matches a sequence of 0 or 1 matches of the atom. +.PP +A \fIbound\fR is `{' followed by an unsigned decimal integer, +possibly followed by `,' +possibly followed by another unsigned decimal integer, +always followed by `}'. +The integers must lie between 0 and RE_DUP_MAX (255\*(dg) inclusive, +and if there are two of them, the first may not exceed the second. +An atom followed by a bound containing one integer \fIi\fR +and no comma matches +a sequence of exactly \fIi\fR matches of the atom. +An atom followed by a bound +containing one integer \fIi\fR and a comma matches +a sequence of \fIi\fR or more matches of the atom. +An atom followed by a bound +containing two integers \fIi\fR and \fIj\fR matches +a sequence of \fIi\fR through \fIj\fR (inclusive) matches of the atom. +.PP +An atom is a regular expression enclosed in `()' (matching a match for the +regular expression), +an empty set of `()' (matching the null string)\*(dg, +a \fIbracket expression\fR (see below), `.' +(matching any single character), `^' (matching the null string at the +beginning of a line), `$' (matching the null string at the +end of a line), a `\e' followed by one of the characters +`^.[$()|*+?{\e' +(matching that character taken as an ordinary character), +a `\e' followed by any other character\*(dg +(matching that character taken as an ordinary character, +as if the `\e' had not been present\*(dg), +or a single character with no other significance (matching that character). +A `{' followed by a character other than a digit is an ordinary +character, not the beginning of a bound\*(dg. +It is illegal to end an RE with `\e'. +.PP +A \fIbracket expression\fR is a list of characters enclosed in `[]'. +It normally matches any single character from the list (but see below). +If the list begins with `^', +it matches any single character +(but see below) \fInot\fR from the rest of the list. +If two characters in the list are separated by `\-', this is shorthand +for the full \fIrange\fR of characters between those two (inclusive) in the +collating sequence, +e.g. `[0-9]' in ASCII matches any decimal digit. +It is illegal\*(dg for two ranges to share an +endpoint, e.g. `a-c-e'. +Ranges are very collating-sequence-dependent, +and portable programs should avoid relying on them. +.PP +To include a literal `]' in the list, make it the first character +(following a possible `^'). +To include a literal `\-', make it the first or last character, +or the second endpoint of a range. +To use a literal `\-' as the first endpoint of a range, +enclose it in `[.' and `.]' to make it a collating element (see below). +With the exception of these and some combinations using `[' (see next +paragraphs), all other special characters, including `\e', lose their +special significance within a bracket expression. +.PP +Within a bracket expression, a collating element (a character, +a multi-character sequence that collates as if it were a single character, +or a collating-sequence name for either) +enclosed in `[.' and `.]' stands for the +sequence of characters of that collating element. +The sequence is a single element of the bracket expression's list. +A bracket expression containing a multi-character collating element +can thus match more than one character, +e.g. if the collating sequence includes a `ch' collating element, +then the RE `[[.ch.]]*c' matches the first five characters +of `chchcc'. +.PP +Within a bracket expression, a collating element enclosed in `[=' and +`=]' is an equivalence class, standing for the sequences of characters +of all collating elements equivalent to that one, including itself. +(If there are no other equivalent collating elements, +the treatment is as if the enclosing delimiters were `[.' and `.]'.) +For example, if o and \o'o^' are the members of an equivalence class, +then `[[=o=]]', `[[=\o'o^'=]]', and `[o\o'o^']' are all synonymous. +An equivalence class may not\*(dg be an endpoint +of a range. +.PP +Within a bracket expression, the name of a \fIcharacter class\fR enclosed +in `[:' and `:]' stands for the list of all characters belonging to that +class. +Standard character class names are: +.PP +.RS +.nf +.ta 3c 6c 9c +alnum digit punct +alpha graph space +blank lower upper +cntrl print xdigit +.fi +.RE +.PP +These stand for the character classes defined in +.BR wctype (3). +A locale may provide others. +A character class may not be used as an endpoint of a range. +.PP +There are two special cases\*(dg of bracket expressions: +the bracket expressions `[[:<:]]' and `[[:>:]]' match the null string at +the beginning and end of a word respectively. +A word is defined as a sequence of +word characters +which is neither preceded nor followed by +word characters. +A word character is an +.I alnum +character (as defined by +.BR wctype (3)) +or an underscore. +This is an extension, +compatible with but not specified by POSIX 1003.2, +and should be used with +caution in software intended to be portable to other systems. +.PP +In the event that an RE could match more than one substring of a given +string, +the RE matches the one starting earliest in the string. +If the RE could match more than one substring starting at that point, +it matches the longest. +Subexpressions also match the longest possible substrings, subject to +the constraint that the whole match be as long as possible, +with subexpressions starting earlier in the RE taking priority over +ones starting later. +Note that higher-level subexpressions thus take priority over +their lower-level component subexpressions. +.PP +Match lengths are measured in characters, not collating elements. +A null string is considered longer than no match at all. +For example, +`bb*' matches the three middle characters of `abbbc', +`(wee|week)(knights|nights)' matches all ten characters of `weeknights', +when `(.*).*' is matched against `abc' the parenthesized subexpression +matches all three characters, and +when `(a*)*' is matched against `bc' both the whole RE and the parenthesized +subexpression match the null string. +.PP +If case-independent matching is specified, +the effect is much as if all case distinctions had vanished from the +alphabet. +When an alphabetic that exists in multiple cases appears as an +ordinary character outside a bracket expression, it is effectively +transformed into a bracket expression containing both cases, +e.g. `x' becomes `[xX]'. +When it appears inside a bracket expression, all case counterparts +of it are added to the bracket expression, so that (e.g.) `[x]' +becomes `[xX]' and `[^x]' becomes `[^xX]'. +.PP +No particular limit is imposed on the length of REs\*(dg. +Programs intended to be portable should not employ REs longer +than 256 bytes, +as an implementation can refuse to accept such REs and remain +POSIX-compliant. +.PP +Obsolete (``basic'') regular expressions differ in several respects. +`|', `+', and `?' are ordinary characters and there is no equivalent +for their functionality. +The delimiters for bounds are `\e{' and `\e}', +with `{' and `}' by themselves ordinary characters. +The parentheses for nested subexpressions are `\e(' and `\e)', +with `(' and `)' by themselves ordinary characters. +`^' is an ordinary character except at the beginning of the +RE or\*(dg the beginning of a parenthesized subexpression, +`$' is an ordinary character except at the end of the +RE or\*(dg the end of a parenthesized subexpression, +and `*' is an ordinary character if it appears at the beginning of the +RE or the beginning of a parenthesized subexpression +(after a possible leading `^'). +Finally, there is one new type of atom, a \fIback reference\fR: +`\e' followed by a non-zero decimal digit \fId\fR +matches the same sequence of characters +matched by the \fId\fRth parenthesized subexpression +(numbering subexpressions by the positions of their opening parentheses, +left to right), +so that (e.g.) `\e([bc]\e)\e1' matches `bb' or `cc' but not `bc'. +.SH "SEE ALSO" +.BR regex (3) +.PP +POSIX 1003.2, section 2.8 (Regular Expression Notation). +.SH BUGS +Having two kinds of REs is a botch. +.PP +The current 1003.2 spec says that `)' is an ordinary character in +the absence of an unmatched `('; +this was an unintentional result of a wording error, +and change is likely. +Avoid relying on it. +.PP +Back references are a dreadful botch, +posing major problems for efficient implementations. +They are also somewhat vaguely defined +(does +`a\e(\e(b\e)*\e2\e)*d' match `abbbd'?). +Avoid using them. +.PP +1003.2's specification of case-independent matching is vague. +The ``one case implies all cases'' definition given above +is current consensus among implementors as to the right interpretation. +.PP +The syntax for word boundaries is incredibly ugly. +.SH AUTHOR +This page was taken from Henry Spencer's regex package. diff --git a/man7/rtnetlink.7 b/man7/rtnetlink.7 new file mode 100644 index 000000000..54040c3af --- /dev/null +++ b/man7/rtnetlink.7 @@ -0,0 +1,468 @@ +'\" t +.\" Don't remove the line above, it tells man that tbl is needed. +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" Based on the original comments from Alexey Kuznetsov, written with +.\" help from Matthew Wilcox. +.\" $Id: rtnetlink.7,v 1.8 2000/01/22 01:55:04 freitag Exp $ +.TH RTNETLINK 7 1999-04-30 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +rtnetlink, NETLINK_ROUTE \- Linux IPv4 routing socket +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include + +.BI "rtnetlink_socket = socket(PF_NETLINK, int " socket_type ", NETLINK_ROUTE);" + +.SH DESCRIPTION +Rtnetlink allows the kernel's routing tables to be read and altered. +It is used within the kernel to communicate between +various subsystems, though this usage is not documented here, and for +communication with user-space programs. +Network routes, ip addresses, link parameters, neighbour setups, queueing +disciplines, traffic classes and packet classifiers may all be controlled +through +.B NETLINK_ROUTE +sockets. It is based on netlink messages, see +.BR netlink (7) +for more information. + +.\" XXX: all these macros could be moved to rtnetlink(3) + +.SH "ROUTING ATTRIBUTES" +Some rtnetlink messages have optional attributes after the initial header: + +.nf +.ta 4 19 32 +struct rtattr +{ + unsigned short rta_len; /* Length of option */ + unsigned short rta_type; /* Type of option */ + /* Data follows */ +}; +.fi + +These attributes should be only manipulated using the RTA_* macros or libnetlink, +see +.BR rtnetlink (3). + +.SH MESSAGES +Rtnetlink consists of these message types +(in addition to standard netlink messages): +.TP +.BR RTM_NEWLINK ", " RTM_DELLINK ", " RTM_GETLINK +Create, remove or get information about a specific network interface. +These messages contain an +.B ifinfomsg +structure followed by a series of +.B rtattr +structures. + +.nf +.ta 4 19 32 +struct ifinfomsg +{ + unsigned char ifi_family; /* AF_UNSPEC */ + unsigned short ifi_type; /* Device type */ + int ifi_index; /* Interface index */ + unsigned int ifi_flags; /* Device flags */ + unsigned int ifi_change; /* change mask */ +}; +.fi + +.\" XXX ifi_type +.B ifi_flags +contains the device flags, see +.BR netdevice(7); +.B ifi_index +is the unique interface index, +.B ifi_change +is reserved for future use and should be always set to 0xFFFFFFFF. + + +.TS +tab(:); +c +l l l. +Routing attributes +rta_type:value type:description +_ +IFLA_UNSPEC:-:unspecified. +IFLA_ADDRESS:hardware address:interface L2 address +IFLA_BROADCAST:hardware address:L2 broadcast address. +IFLA_IFNAME:asciiz string:Device name. +IFLA_MTU:unsigned int:MTU of the device. +IFLA_LINK:int:Link type. +IFLA_QDISC:asciiz string:Queueing discipline. +IFLA_STATS:T{ +struct net_device_stats +T}:Interface Statistics. +.TE +.TP +.BR RTM_NEWADDR ", " RTM_DELADDR ", " RTM_GETADDR +Add, remove or receive information about an IP address associated with +an interface. In Linux 2.2 an interface can carry multiple IP addresses, +this replaces the alias device concept in 2.0. In Linux 2.2 these messages +support IPv4 and IPv6 addresses. They contain an +.B ifaddrmsg +structure, optionally followed by +.B rtaddr +routing attributes. + +.nf +.ta 4 19 32 +struct ifaddrmsg +{ + unsigned char ifa_family; /* Address type */ + unsigned char ifa_prefixlen; /* Prefixlength of the address */ + unsigned char ifa_flags; /* Address flags */ + unsigned char ifa_scope; /* Address scope */ + int ifa_index; /* Interface index */ +}; +.fi + +.B ifa_family +is the address family type (currently +.B AF_INET +or +.B AF_INET6), +.B ifa_prefixlen +is the length of the address mask of the address if defined for the +family (like for IPv4), +.B ifa_scope +is the address scope, +.B ifa_index +is the interface index of the interface the address is associated with. +.B ifa_flags +is a flag word of +.B IFA_F_SECONDARY +for secondary address (old alias interface), +.B IFA_F_PERMANENT +for a permanent address set by the user and other undocumented flags. + +.TS +tab(:); +c +l l l. +Attributes +rta_type:value type:description +_ +IFA_UNSPEC:-:unspecified. +IFA_ADDRESS:raw protocol address:interface address +IFA_LOCAL:raw protocol address:local address +IFA_LABEL:asciiz string:name of the interface +IFA_BROADCAST:raw protocol address:broadcast address. +IFA_ANYCAST:raw protocol address:anycast address +IFA_CACHEINFO:struct ifa_cacheinfo:Address information. +.TE + +.\" XXX struct ifa_cacheinfo +.TP +.BR RTM_NEWROUTE ", " RTM_DELROUTE ", " RTM_GETROUTE +Create, remove or receive information about a network route. +These messages contain an +.B rtmsg +structure with an optional sequence of +.B rtattr +structures following. For +.B RTM_GETROUTE +setting +.B rtm_dst_len +and +.B rtm_src_len +to 0 means you get all entries for the specified routing table. +For the other fields except +.B rtm_table +and +.B rtm_protocol +0 is the wildcard. + +.nf +.ta 4 19 32 +struct rtmsg +{ + unsigned char rtm_family; /* Address family of route */ + unsigned char rtm_dst_len; /* Length of source */ + unsigned char rtm_src_len; /* Length of destination */ + unsigned char rtm_tos; /* TOS filter */ + + unsigned char rtm_table; /* Routing table id */ + unsigned char rtm_protocol; /* Routing protocol; see below */ + unsigned char rtm_scope; /* See below */ + unsigned char rtm_type; /* See below */ + + unsigned int rtm_flags; +}; +.fi + +.TS +tab(:); +l l +l l. +rtm_type:Route type +_ +RTN_UNSPEC:unknown route +RTN_UNICAST:a gateway or direct route +RTN_LOCAL:a local interface route +RTN_BROADCAST:T{ +a local broadcast route (sent as a broadcast) +T} +RTN_ANYCAST:T{ +a local broadcast route (sent as a unicast) +T} +RTN_MULTICAST:a multicast route +RTN_BLACKHOLE:a packet dropping route +RTN_UNREACHABLE:an unreachable destination +RTN_PROHIBIT:a packet rejection route +RTN_THROW:continue routing lookup in another table +RTN_NAT:a network address translation rule +RTN_XRESOLVE:T{ +refer to an external resolver (not implemented) +T} +.TE + +.TS +tab(:); +l l. +rtm_protocol:Route origin. +_ +RTPROT_UNSPEC:unknown +RTPROT_REDIRECT:T{ +by an ICMP redirect (currently unused) +T} +RTPROT_KERNEL:by the kernel +RTPROT_BOOT:during boot +RTPROT_STATIC:by the administrator +.TE + +Values larger than +.B RTPROT_STATIC +are not interpreted by the kernel, they are just for user information. They +may be used to tag the source of a routing information or to distingush between +multiple routing daemons. See +.BR +for the routing daemon identifiers which are already assigned. + +.B rtm_scope +is the distance to the destination: + +.TS +tab(:); +l l. +RT_SCOPE_UNIVERSE:global route +RT_SCOPE_SITE:T{ +interior route in the local autonomous system +T} +RT_SCOPE_LINK:route on this link +RT_SCOPE_HOST:route on the local host +RT_SCOPE_NOWHERE:destination doesn't exist +.TE + +The values between +.B RT_SCOPE_UNIVERSE +and +.B RT_SCOPE_SITE +are available to the user. + +The +.B rtm_flags +have the following meanings: + +.TS +tab(:); +l l. +RTM_F_NOTIFY:T{ +if the route changes, notify the user via rtnetlink +T} +RTM_F_CLONED:route is cloned from another route +RTM_F_EQUALIZE:a multicast equalizer (not yet implemented) +.TE + +.B rtm_table +specifies the routing table + +.TS +tab(:); +l l. +RT_TABLE_UNSPEC:an unspecified routing table +RT_TABLE_DEFAULT:the default table +RT_TABLE_MAIN:the main table +RT_TABLE_LOCAL:the local table +.TE + +The user may assign arbitary values between +.B RT_TABLE_UNSPEC +and +.BR RT_TABLE_DEFAULT . + +.TS +tab(:); +c +l l l. +Attributes +rta_type:value type:description +_ +RTA_UNSPEC:-:ignored. +RTA_DST:protocol address:Route destination address. +RTA_SRC:protocol address:Route source address. +RTA_IIF:int:Input interface index. +RTA_OIF:int:Output interface index. +RTA_GATEWAY:protocol address:The gateway of the route +RTA_PRIORITY:int:Priority of route. +RTA_PREFSRC:: +RTA_METRICS:int:Route metric +RTA_MULTIPATH:: +RTA_PROTOINFO:: +RTA_FLOW:: +RTA_CACHEINFO:: +.TE + +.B Fill these values in! +.TP +.BR RTM_NEWNEIGH ", " RTM_DELNEIGH ", " RTM_GETNEIGH +Add, remove or receive information about a neighbour table entry (e.g. an ARP +entry). The message contains an +.B ndmsg +structure. + +.nf +.ta 4 19 32 +struct ndmsg +{ + unsigned char ndm_family; + int ndm_ifindex; /* Interface index */ + __u16 ndm_state; /* State */ + __u8 ndm_flags; /* Flags */ + __u8 ndm_type; +}; + +struct nda_cacheinfo +{ + __u32 ndm_confirmed; + __u32 ndm_used; + __u32 ndm_updated; + __u32 ndm_refcnt; +}; +.fi + +.B ndm_state +is a bitmask of the following states: + +.TS +tab(:); +l l. +NUD_INCOMPLETE:a currently resolving cache entry +NUD_REACHABLE:a confirmed working cache entry +NUD_STALE:an expired cache entry +NUD_DELAY:an entry waiting for a timer +NUD_PROBE:a cache entry that is currently reprobed +NUD_FAILED:an invalid cache entry +NUD_NOARP:a device with no destination cache +NUD_PERMANENT:a static entry +.TE + +Valid +.B ndm_flags +are: + +.TS +tab(:); +l l. +NTF_PROXY:a proxy arp entry +NTF_ROUTER:an IPv6 router +.TE + +.B document the members of the struct better + +The +.B rtaddr +struct has the following meanings for the +.B rta_type +field: + +.TS +tab(:); +l l. +NDA_UNSPEC:unknown type +NDA_DST:a neighbour cache network layer destination address +NDA_LLADDR:a neighbour cache link layer address +NDA_CACHEINFO:cache statistics. +.TE + +If the +.B rta_type +field is +.B NDA_CACHEINFO +then a +.B struct nda_cacheinfo +header follows +.TP +.BR RTM_NEWRULE ", " RTM_DELRULE ", " RTM_GETRULE +Add, delete or retrieve a routing rule. Carries a +.B struct rtmsg +.TP +.BR RTM_NEWQDISC ", " RTM_DELQDISC ", " RTM_GETQDISC +Add, remove or get a queueing discipline. The message contains a +.B struct tcmsg +and may be followed by a series of +attributes. + +.nf +.ta 4 19 32 +struct tcmsg +{ + unsigned char tcm_family; + int tcm_ifindex; /* interface index */ + __u32 tcm_handle; /* Qdisc handle */ + __u32 tcm_parent; /* Parent qdisc */ + __u32 tcm_info; +}; +.fi + +.TS +tab(:); +c +l l l. +Attributes +rta_type:value type:Description +_ +TCA_UNSPEC:-:unspecified +TCA_KIND:asciiz string:Name of queueing discipline +TCA_OPTIONS:byte sequence:Qdisc specific options follow +TCA_STATS:struct tc_stats:Qdisc statistics. +TCA_XSTATS:qdisc specific:Module specific statistics. +TCA_RATE:struct tc_estimator:Rate limit. +.TE + +In addition various other qdisc module specific attributes are allowed. +For more information see the appropriate include files. +.TP +.BR RTM_NEWTCLASS ", " RTM_DELTCLASS ", " RTM_GETTCLASS +Add, remove or get a traffic class. These messages contain a +.B struct tcmsg +as described above. +.TP +.BR RTM_NEWTFILTER ", " RTM_DELTFILTER ", " RTM_GETTFILTER +Add, remove or receive information about a traffic filter. These +messages contain a +.B struct tcmsg +as described above. +.SH VERSIONS +.B rtnetlink +is a new feature of Linux 2.2. +.SH BUGS +This manual page is lacking and incomplete. + +.SH "SEE ALSO" +.BR cmsg (3), +.BR rtnetlink (3), +.BR ip (7), +.BR netlink (7) diff --git a/man7/signal.7 b/man7/signal.7 new file mode 100644 index 000000000..0418b6a29 --- /dev/null +++ b/man7/signal.7 @@ -0,0 +1,255 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" Copyright (c) 2002 by Michael Kerrisk (mtk16@ext.canterbury.ac.nz) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 17:34:08 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Jan 7 01:41:27 1996 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sun Apr 14 12:02:29 1996 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sat Nov 13 16:28:23 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 10 Apr 2002, by Michael Kerrisk (mtk16@ext.canterbury.ac.nz) +.\" Modified 7 Jun 2002, by Michael Kerrisk (mtk16@ext.canterbury.ac.nz) +.\" Added information on real-time signals +.\" Modified 13 Jun 2002, by Michael Kerrisk (mtk16@ext.canterbury.ac.nz) +.\" Noted that SIGSTKFLT is in fact unused +.\" +.TH SIGNAL 7 2002-06-13 "Linux 2.4.18" "Linux Programmer's Manual" +.SH NAME +signal \- list of available signals +.SH DESCRIPTION +Linux supports both POSIX reliable signals (hereinafter +"standard signals") and POSIX real-time signals. +.SS "Standard Signals" +Linux supports the standard signals listed below. Several signal numbers +are architecture dependent, as indicated in the "Value" column. +(Where three values are given, the first one is usually valid for +alpha and sparc, the middle one for i386, ppc and sh, and +the last one for mips. +A \- denotes that a signal is absent on the corresponding architecture.) + +The entries in the "Action" column of the table specify +the default action for the signal, as follows: +.IP Term +Default action is to terminate the process. +.IP Ign +Default action is to ignore the signal. +.IP Core +Default action is to terminate the process and dump core. +.IP Stop +Default action is to stop the process. +.PP +First the signals described in the original POSIX.1 standard. +.sp +.PP +.TS +l c c l +____ +lB c c l. +Signal Value Action Comment +SIGHUP \01 Term Hangup detected on controlling terminal + or death of controlling process +SIGINT \02 Term Interrupt from keyboard +SIGQUIT \03 Core Quit from keyboard +SIGILL \04 Core Illegal Instruction +SIGABRT \06 Core Abort signal from \fIabort\fP(3) +SIGFPE \08 Core Floating point exception +SIGKILL \09 Term Kill signal +SIGSEGV 11 Core Invalid memory reference +SIGPIPE 13 Term Broken pipe: write to pipe with no readers +SIGALRM 14 Term Timer signal from \fIalarm\fP(2) +SIGTERM 15 Term Termination signal +SIGUSR1 30,10,16 Term User\-defined signal 1 +SIGUSR2 31,12,17 Term User\-defined signal 2 +SIGCHLD 20,17,18 Ign Child stopped or terminated +SIGCONT 19,18,25 Continue if stopped +SIGSTOP 17,19,23 Stop Stop process +SIGTSTP 18,20,24 Stop Stop typed at tty +SIGTTIN 21,21,26 Stop tty input for background process +SIGTTOU 22,22,27 Stop tty output for background process +.TE + +The signals +.B SIGKILL +and +.B SIGSTOP +cannot be caught, blocked, or ignored. + +Next the signals not in the POSIX.1 standard but described in SUSv2 and +SUSv3 / POSIX 1003.1-2001. +.sp +.PP +.TS +l c c l +____ +lB c c l. +Signal Value Action Comment +SIGBUS 10,7,10 Core Bus error (bad memory access) +SIGPOLL Term Pollable event (Sys V). Synonym of SIGIO +SIGPROF 27,27,29 Term Profiling timer expired +SIGSYS 12,\-,12 Core Bad argument to routine (SVID) +SIGTRAP 5 Core Trace/breakpoint trap +SIGURG 16,23,21 Ign Urgent condition on socket (4.2 BSD) +SIGVTALRM 26,26,28 Term Virtual alarm clock (4.2 BSD) +SIGXCPU 24,24,30 Core CPU time limit exceeded (4.2 BSD) +SIGXFSZ 25,25,31 Core File size limit exceeded (4.2 BSD) +.TE + +Up to and including Linux 2.2, the default behaviour for +.BR SIGSYS ", " SIGXCPU ", " SIGXFSZ ", " +and (on architectures other than SPARC and MIPS) +.B SIGBUS +was to terminate the process (without a core dump). +(On some other Unices the default action for +.BR SIGXCPU " and " SIGXFSZ +is to terminate the process without a core dump.) +Linux 2.4 conforms to the POSIX 1003.1-2001 requirements for these signals, +terminating the process with a core dump. + +Next various other signals. +.sp +.PP +.TS +l c c l +____ +lB c c l. +Signal Value Action Comment +SIGIOT 6 Core IOT trap. A synonym for SIGABRT +SIGEMT 7,\-,7 Term +SIGSTKFLT \-,16,\- Term Stack fault on coprocessor (unused) +SIGIO 23,29,22 Term I/O now possible (4.2 BSD) +SIGCLD \-,\-,18 Ign A synonym for SIGCHLD +SIGPWR 29,30,19 Term Power failure (System V) +SIGINFO 29,\-,\- A synonym for SIGPWR +SIGLOST \-,\-,\- Term File lock lost +SIGWINCH 28,28,20 Ign Window resize signal (4.3 BSD, Sun) +SIGUNUSED \-,31,\- Term Unused signal (will be SIGSYS) +.TE + +(Signal 29 is +.B SIGINFO +/ +.B SIGPWR +on an alpha but +.B SIGLOST +on a sparc.) + +.B SIGEMT +is not specified in POSIX 1003.1-2001, but neverthless appears +on most other Unices, where its default action is typically to terminate +the process with a core dump. + +.B SIGPWR +(which is not specified in POSIX 1003.1-2001) is typically ignored +by default on those other Unices where it appears. + +.B SIGIO +(which is not specified in POSIX 1003.1-2001) is ignored by default +on several other Unices. +.SS "Real-time Signals" +Linux supports real-time signals as originally defined in the POSIX.4 +real-time extensions (and now included in POSIX 1003.1-2001). +Linux supports 32 real-time signals, numbered from 32 +.RB ( SIGRTMIN ) +to 63 +.RB ( SIGRTMAX ). +(Programs should always refer to real-time signals using notation +.BR SIGRTMIN +n, +since the range of real-time signal numbers varies across Unices.) +.PP +Unlike standard signals, real-time signals have no predefined meanings: +the entire set of real-time signals can be used for application-defined +purposes. +(Note, however, that the LinuxThreads implementation uses the first +three real-time signals.) +.PP +The default action for an unhandled real-time signal is to terminate the +receiving process. +.PP +Real-time signals are distinguished by the following: +.IP 1. 4 +Multiple instances of real-time signals can be queued. +By contrast, if multiple instances of a standard signal are delivered +while that signal is currently blocked, then only one instance is queued. +.IP 2. 4 +If the signal is sent using +.BR sigqueue (2), +an accompanying value (either an integer or a pointer) can be sent +with the signal. +If the receiving process establishes a handler for this signal using the +.B SA_SIGACTION +flag to +.BR sigaction (2) +then it can obtain this data via the +.I si_value +field of the +.I siginfo_t +structure passed as the second argument to the handler. +Furthermore, the +.I si_pid +and +.I si_uid +fields of this structure can be used to obtain the PID +and real user ID of the process sending the signal. +.IP 3. 4 +Real-time signals are delivered in a guaranteed order. +Multiple real-time signals of the same type are delivered in the order +they were sent. +If different real-time signals are sent to a process, they are delivered +starting with the lowest-numbered signal. +(I.e., low-numbered signals have highest priority.) +.PP +If both standard and real-time signals are pending for a process, +POSIX leaves it unspecified which is delivered first. +Linux, like many other implementations, gives priority +to standard signals in this case. +.PP +According to POSIX, an implementation should permit at least +_POSIX_SIGQUEUE_MAX (32) real-time signals to be queued to +a process. +However, rather than placing a per-process limit, Linux imposes +a system-wide limit on the number of queued real-time signals +for all processes. +This limit can be viewed and (with privilege) changed via the +.I /proc/sys/kernel/rtsig-max +file. +A related file, +.IR /proc/sys/kernel/rtsig-nr , +can be used to find out how many real-time signals are currently queued. +.SH "CONFORMING TO" +POSIX.1 +.SH BUGS +.B SIGIO +and +.B SIGLOST +have the same value. +The latter is commented out in the kernel source, but +the build process of some software still thinks that +signal 29 is +.BR SIGLOST . +.SH "SEE ALSO" +.BR kill (1), +.BR kill (2), +.BR setitimer (2), +.BR sigaction (2), +.BR signal (2), +.BR sigprocmask (2), +.BR sigqueue (2) diff --git a/man7/socket.7 b/man7/socket.7 new file mode 100644 index 000000000..890d90850 --- /dev/null +++ b/man7/socket.7 @@ -0,0 +1,588 @@ +'\" t +.\" Don't change the first line, it tells man that we need tbl. +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" and copyright (c) 1999 Matthew Wilcox. +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" +.\" 2002-10-30, Michael Kerrisk, mtk16@ext.canterbury.ac.nz +.\" Added description of SO_ACCEPTCONN +.\" 2004-05-20, aeb, added SO_RCVTIMEO/SO_SNDTIMEO text. +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" A few small grammar fixes +.\" +.\" FIXME: probably all PF_* shouls be AF_* in this page, since +.\" POSIX only specifies the latter values. +.\" +.TH SOCKET 7 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" +.SH NAME +socket - Linux socket interface +.SH SYNOPSIS +.B #include +.br +.IB mysocket " = socket(int " socket_family ", int " socket_type ", int " protocol ); + +.SH DESCRIPTION +This manual page describes the Linux networking socket layer user +interface. The BSD compatible sockets +are the uniform interface +between the user process and the network protocol stacks in the kernel. +The protocol modules are grouped into +.I protocol families +like +.BR PF_INET ", " PF_IPX ", " PF_PACKET +and +.I socket types +like +.B SOCK_STREAM +or +.BR SOCK_DGRAM . +See +.BR socket (2) +for more information on families and types. + +.SH "SOCKET LAYER FUNCTIONS" +These functions are used by the user process to send or receive packets and +to do other socket operations. For more information see their respective +manual pages. + +.BR socket (2) +creates a socket, +.BR connect (2) +connects a socket to a remote socket address, +the +.BR bind (2) +function binds a socket to a local socket address, +.BR listen (2) +tells the socket that new connections shall be accepted, and +.BR accept (2) +is used to get a new socket with a new incoming connection. +.BR socketpair (2) +returns two connected anonymous sockets (only implemented for a few +local families like +.BR PF_UNIX ) +.PP +.BR send (2), +.BR sendto (2), +and +.BR sendmsg (2) +send data over a socket, and +.BR recv (2), +.BR recvfrom (2), +.BR recvmsg (2) +receive data from a socket. +.BR poll (2) +and +.BR select (2) +wait for arriving data or a readiness to send data. +In addition, the standard I/O operations like +.BR write (2), +.BR writev (2), +.BR sendfile (2), +.BR read (2), +and +.BR readv (2) +can be used to read and write data. +.PP +.BR getsockname (2) +returns the local socket address and +.BR getpeername (2) +returns the remote socket address. +.BR getsockopt (2) +and +.BR setsockopt (2) +are used to set or get socket layer or protocol options. +.BR ioctl (2) +can be used to set or read some other options. +.PP +.BR close (2) +is used to close a socket. +.BR shutdown (2) +closes parts of a full duplex socket connection. +.PP +Seeking, or calling +.BR pread (2) +or +.BR pwrite (2) +with a non-zero position is not supported on sockets. +.PP +It is possible to do non-blocking IO on sockets by setting the +.B O_NONBLOCK +flag on a socket file descriptor using +.BR fcntl (2). +Then all operations that would block will (usually) +return with +.B EAGAIN +(operation should be retried later); +.BR connect (2) +will return +.B EINPROGRESS +error. +The user can then wait for various events via +.BR poll (2) +or +.BR select (2). +.PP +.TS +tab(:) allbox; +c s s +l l l. +I/O events +Event:Poll flag:Occurrence +Read:POLLIN:T{ +New data arrived. +T} +Read:POLLIN:T{ +A connection setup has been completed +(for connection-oriented sockets) +T} +Read:POLLHUP:T{ +A disconnection request has been initiated by the other end. +T} +Read:POLLHUP:T{ +A connection is broken (only for connection-oriented protocols). +When the socket is written +.B SIGPIPE +is also sent. +T} +Write:POLLOUT:T{ +Socket has enough send buffer space for writing new data. +T} +Read/Write:T{ +POLLIN| +.br +POLLOUT +T}:T{ +An outgoing +.BR connect (2) +finished. +T} +Read/Write:POLLERR:An asynchronous error occurred. +Read/Write:POLLHUP:The other end has shut down one direction. +Exception:POLLPRI:T{ +Urgent data arrived. +.B SIGURG +is sent then. +T} +.\" XXX not true currently +.\" It is no I/O event when the connection +.\" is broken from the local end using +.\" .BR shutdown (2) +.\" or +.\" .BR close (2) +.\" . +.TE + +.PP +An alternative to poll/select +is to let the kernel inform the application about events +via a +.B SIGIO +signal. For that the +.B FASYNC +flag must be set on a socket file descriptor +via +.BR fcntl (2) +and a valid signal handler for +.B SIGIO +must be installed via +.BR sigaction (2). +See the +.I SIGNALS +discussion below. +.SH "SOCKET OPTIONS" +These socket options can be set by using +.BR setsockopt (2) +and read with +.BR getsockopt (2) +with the socket level set to +.B SOL_SOCKET +for all sockets: +.TP +.B SO_KEEPALIVE +Enable sending of keep-alive messages on connection-oriented sockets. Expects +an integer boolean flag. +.TP +.B SO_OOBINLINE +If this option is enabled, out-of-band data is directly placed into the receive +data stream. Otherwise out-of-band data is only passed when the +.B MSG_OOB +flag is set during receiving. +.\" don't document it because it can do too much harm. +.\".B SO_NO_CHECK +.TP +.BR SO_RCVLOWAT " and " SO_SNDLOWAT +Specify the minimum number of bytes in the buffer until the socket layer +will pass the data to the protocol +.RB ( SO_SNDLOWAT ) +or the user on receiving +.RB ( SO_RCVLOWAT ). +These two values are not changeable in Linux and their argument size +is always fixed +to 1 byte. +.B getsockopt +is able to read them; +.B setsockopt +will always return +.BR ENOPROTOOPT . +.TP +.BR SO_RCVTIMEO " and " SO_SNDTIMEO +.\" Not implemented in 2.0. +.\" Implemented in 2.1.11 for getsockopt: always return a zero struct. +.\" Implemented in 2.3.41 for setsockopt, and actually used. +Specify the receiving or sending timeouts until reporting an error. +The parameter is a struct timeval. +If an input or output function blocks for this period of time, and +data has been sent or received, the return value of that function +will be the amount of data transferred; if no data has been transferred +and the timeout has been reached then -1 is returned with +.I errno +set to EAGAIN or EWOULDBLOCK +.\" in fact to EAGAIN +just as if the socket was specified to be nonblocking. +If the timeout is set to zero (the default) +then the operation will never timeout. +.TP +.B SO_BSDCOMPAT +Enable BSD bug-to-bug compatibility. This is used only by the UDP +protocol module and scheduled to be removed in future. +If enabled ICMP errors received for a UDP socket will not be passed +to the user program. Linux 2.0 also enabled BSD bug-to-bug compatibility +options (random header changing, skipping of the broadcast flag) for raw +sockets with this option, but that has been removed in Linux 2.2. It is +better to fix the user programs than to enable this flag. +.TP +.B SO_PASSCRED +Enable or disable the receiving of the +.B SCM_CREDENTIALS +control message. For more information see +.BR unix (7). +.TP +.B SO_PEERCRED +Return the credentials of the foreign process connected to this socket. +Only useful for +.B PF_UNIX +sockets; see +.BR unix (7). +Argument is a +.B ucred +structure. Only valid as a +.BR getsockopt . +.TP +.B SO_BINDTODEVICE +Bind this socket to a particular device like \(lqeth0\(rq, +as specified in the passed interface name. If the +name is an empty string or the option length is zero, the socket device +binding is removed. The passed option is a variable-length null terminated +interface name string with the maximum size of +.BR IFNAMSIZ . +If a socket is bound to an interface, +only packets received from that particular interface are processed by the +socket. Note that this only works for some socket types, particularly +.B AF_INET +sockets. It is not supported for packet sockets (use normal +.BR bind (8) +there). +.TP +.B SO_DEBUG +Enable socket debugging. Only allowed for processes with the +.B CAP_NET_ADMIN +capability or an effective user id of 0. +.TP +.B SO_REUSEADDR +Indicates that the rules used in validating addresses supplied in a +.BR bind (2) +call should allow reuse of local addresses. For +.B PF_INET +sockets this +means that a socket may bind, except when there +is an active listening socket bound to the address. +When the listening socket is bound to +.B INADDR_ANY +with a specific port then it is not possible +to bind to this port for any local address. +.TP +.B SO_TYPE +Gets the socket type as an integer (like +.BR SOCK_STREAM ). +Can only be read +with +.BR getsockopt . +.\" SO_ACCEPTCONN is in SUSv3, and its origin is explained in +.\" W R Stevens, UNPv1 +.TP +.B SO_ACCEPTCONN +Returns a value indicating whether or not this socket has been marked +to accept connections with +.BR listen (). +The value 0 indicates that this is not a listening socket, +the value 1 indicates that this is a listening socket. +Can only be read +with +.BR getsockopt . +.TP +.B SO_DONTROUTE +Don't send via a gateway, only send to directly connected hosts. +The same effect can be achieved by setting the +.B MSG_DONTROUTE +flag on a socket +.BR send (2) +operation. Expects an integer boolean flag. +.TP +.B SO_BROADCAST +Set or get the broadcast flag. When enabled, datagram sockets +receive packets sent to a broadcast address and they are allowed to send +packets to a broadcast address. +This option has no effect on stream-oriented sockets. +.TP +.B SO_SNDBUF +Sets or gets the maximum socket send buffer in bytes. The default value is set +by the +.B wmem_default +sysctl and the maximum allowed value is set by the +.B wmem_max +sysctl. +.TP +.B SO_RCVBUF +Sets or gets the maximum socket receive buffer in bytes. The default value is +set by the +.B rmem_default +sysctl and the maximum allowed value is set by the +.B rmem_max +sysctl. +.TP +.B SO_LINGER +Sets or gets the +.B SO_LINGER +option. The argument is a +.B linger +structure. +.PP +.RS +.nf +.ta 4n 10n 22n +struct linger { + int l_onoff; /* linger active */ + int l_linger; /* how many seconds to linger for */ +}; +.ta +.fi +.RE +.IP +When enabled, a +.BR close (2) +or +.BR shutdown (2) +will not return until all queued messages for the socket have been +successfully sent or the linger timeout has been reached. Otherwise, +the call returns immediately and the closing is done in the background. +When the socket is closed as part of +.BR exit (2), +it always lingers in the background. +.TP +.B SO_PRIORITY +Set the protocol-defined priority for all packets to be sent on this socket. +Linux uses this value to order the networking queues: packets with a higher +priority may be processed first depending on the selected device queueing +discipline. For +.BR ip (7), +this also sets the IP type-of-service (TOS) field for outgoing packets. +Setting a priority outside the range 0 to 6 requires the +.B CAP_NET_ADMIN +capability. +.TP +.B SO_ERROR +Get and clear the pending socket error. Only valid as a +.BR getsockopt . +Expects an integer. +.SH SIGNALS +When writing onto a connection-oriented socket that has been shut down +(by the local or the remote end) +.B SIGPIPE +is sent to the writing process and +.B EPIPE +is returned. +The signal is not sent when the write call +specified the +.B MSG_NOSIGNAL +flag. +.PP +When requested with the +.B FIOSETOWN +fcntl or +.B SIOCSPGRP +ioctl, +.B SIGIO +is sent when an I/O event occurs. It is possible to use +.BR poll (2) +or +.BR select (2) +in the signal handler to find out which socket the event occurred on. +An alternative (in Linux 2.2) is to set a realtime signal using the +.B F_SETSIG +fcntl; the handler of the real time signal will be called with +the file descriptor in the +.I si_fd +field of its +.IR siginfo_t . +See +.BR fcntl (2) +for more information. +.PP +Under some circumstances (e.g. multiple processes accessing a single socket), +the condition that caused the +.B SIGIO +may have already disappeared when the process reacts to the signal. +If this happens, the process should wait again because Linux will resend the +signal later. +.\" .SH ANCILLARY MESSAGES +.SH SYSCTLS +The core socket networking sysctls can be accessed using the +.B /proc/sys/net/core/* +files or with the +.BR sysctl (2) +interface. +.TP +.B rmem_default +contains the default setting in bytes of the socket receive buffer. +.TP +.B rmem_max +contains the maximum socket receive buffer size in bytes which a user may +set by using the +.B SO_RCVBUF +socket option. +.TP +.B wmem_default +contains the default setting in bytes of the socket send buffer. +.TP +.B wmem_max +contains the maximum socket send buffer size in bytes which a user may +set by using the +.B SO_SNDBUF +socket option. +.TP +.BR message_cost " and " message_burst +configure the token bucket filter used to load limit warning messages +caused by external network events. +.TP +.B netdev_max_backlog +Maximum number of packets in the global input queue. +.TP +.B optmem_max +Maximum length of ancillary data and user control data like the iovecs +per socket. +.\" netdev_fastroute is not documented because it is experimental +.SH IOCTLS +These ioctls can be accessed using +.BR ioctl (2): + +.RS +.nf +.IB error " = ioctl(" ip_socket ", " ioctl_type ", " &value_result ");" +.fi +.RE + +.TP +.B SIOCGSTAMP +Return a +.B struct timeval +with the receive timestamp of the last packet passed to the user. This is useful +for accurate round trip time measurements. See +.BR setitimer (2) +for a description of +.BR "struct timeval" . +.\" +.TP +.BR SIOCSPGRP +Set the process or process group to send +.B SIGIO +or +.B SIGURG +signals +to when an +asynchronous I/O operation has finished or urgent data is available. +The argument is a pointer to a +.BR pid_t . +If the argument is positive, send the signals to that process. If the +argument is negative, send the signals to the process group with the id +of the absolute value of the argument. +The process may only choose itself or its own process group to receive +signals unless it has the +.B CAP_KILL +capability or an effective UID of 0. +.TP +.B FIOASYNC +Change the +.B O_ASYNC +flag to enable or disable asynchronous IO mode of the socket. Asynchronous IO +mode means that the +.B SIGIO +signal or the signal set with +.B F_SETSIG +is raised when a new I/O event occurs. +.IP +Argument is an integer boolean flag. +.\" +.TP +.BR SIOCGPGRP +Get the current process or process group that receives +.B SIGIO +or +.B SIGURG +signals, +or 0 +when none is set. +.PP +Valid fcntls: +.TP +.BR FIOGETOWN +The same as the SIOCGPGRP ioctl. +.TP +.BR FIOSETOWN +The same as the SIOCSPGRP ioctl +.SH NOTES +Linux assumes that half of the send/receive buffer is used for internal +kernel structures; thus the sysctls are twice what can be observed +on the wire. + +Linux will only allow port re-use with the SO_REUSEADDR option +when this option was set both in the previous program that performed +a bind() to the port and in the program that wants to re-use the port. +This differs from some implementations (e.g., FreeBSD) +where only the later program needs to set the SO_REUSEADDR option. +Typically this difference is invisible, since, for example, a server +program is designed to always set this option. +.SH BUGS +The +.B CONFIG_FILTER +socket options +.B SO_ATTACH_FILTER +and +.B SO_DETACH_FILTER +are +not documented. The suggested interface to use them is via the libpcap +library. +.SH VERSIONS +.B SO_BINDTODEVICE +was introduced in Linux 2.0.30. +.B SO_PASSCRED +is new in Linux 2.2. +The sysctls are new in Linux 2.2. +.B SO_RCVTIMEO +and +.B SO_SNDTIMEO +are supported since Linux 2.3.41. Earlier, timeouts were fixed to +a protocol specific setting, and could not be read or written. +.\" .SH AUTHORS +.\" This man page was written by Andi Kleen. +.SH "SEE ALSO" +.BR getsockopt (2), +.BR setsockopt (2), +.BR socket (2), +.BR capabilities (7), +.BR ddp (7), +.BR ip (7), +.BR packet (7) diff --git a/man7/suffixes.7 b/man7/suffixes.7 new file mode 100644 index 000000000..b57aa4234 --- /dev/null +++ b/man7/suffixes.7 @@ -0,0 +1,276 @@ +'\" t +.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Modified Sat Jul 24 17:35:15 1993 by Rik Faith +.\" Modified Sun Feb 19 22:02:32 1995 by Rik Faith +.\" Modified Tue Oct 22 23:28:12 1996 by Eric S. Raymond +.\" Modified Sun Jan 26 21:56:56 1997 by Ralph Schleicher +.\" +.\" Modified Mon Jun 16 20:24:58 1997 by Nicolás Lichtmaier +.\" Modified Sun Oct 18 22:11:28 1998 by Joseph S. Myers +.\" Modified Mon Nov 16 17:24:47 1998 by Andries Brouwer +.\" Modified Thu Nov 16 23:28:25 2000 by David A. Wheeler +.\" +.TH SUFFIXES 7 2000-11-16 "Linux" "Linux Programmer's Manual" +.SH NAME +suffixes \- list of file suffixes +.SH DESCRIPTION +It is customary to indicate the contents of a file with the file suffix, +which consists of a period, followed by one or more letters. Many +standard utilities, such as compilers, use this to recognize the type of +file they are dealing with. The +.BR make (1) +utility is driven by rules based on file suffix. +.PP +Following is a list of suffixes which are likely to be found on a +Linux system. +.PP +.TS +l | l +_ | _ +lI | l . +Suffix File type + ,v files for RCS (Revision Control System) + - backup file + .C C++ source code, equivalent to \fI.cc\fP + .F Fortran source with \fBcpp\fP(1) directives + or file compressed using freeze + .S assembler source with \fBcpp\fP(1) directives + .Y file compressed using yabba + .Z file compressed using \fBcompress\fP(1) + .[0-9]+gf TeX generic font files + .[0-9]+pk TeX packed font files + .[1-9] manual page for the corresponding section + .[1-9][a-z] manual page for section plus subsection + .a static object code library + .ad X application default resource file + .ada Ada source (may be body, spec, or combination) + .adb Ada body source + .ads Ada spec source + .afm PostScript font metrics + .al Perl autoload file + .am \fBautomake\fP(1) input file + .arc \fBarc\fP(1) archive + .arj \fBarj\fP(1) archive + .asc PGP ASCII-armoured data + .asm (GNU) assember source file + .au Audio sound file + .aux LaTeX auxiliary file + .avi (msvideo) movie + .awk AWK language program + .b LILO boot loader image + .bak backup file + .bash \fBbash\fP(1) shell script + .bb basic block list data produced by + gcc -ftest-coverage + .bbg basic block graph data produced by + gcc -ftest-coverage + .bbl BibTeX output + .bdf X font file + .bib TeX bibliographic database, BibTeX input + .bm bitmap source + .bmp bitmap + .bz2 file compressed using \fBbzip2\fP(1) + .c C source + .cat message catalog files + .cc C++ source + .cf configuration file + .cfg configuration file + .cgi WWW content generating script or program + .cls LaTeX Class definition + .class Java compiled byte-code + .conf configuration file + .config configuration file + .cpp equivalent to \fI.cc\fR + .csh \fBcsh\fP(1) shell script + .cxx equivalent to \fI.cc\fR + .dat data file + .deb Debian software package + .def Modula-2 source for definition modules + .def other definition files + .desc initial part of mail message unpacked with + \fBmunpack\fP(1) + .diff file differences (\fBdiff\fP(1) command output) + .dir dbm data base directory file + .doc documentation file + .dsc Debian Source Control (source package) + .dtx LaTeX package source file + .dvi TeX's device independent output + .el Emacs-Lisp source + .elc compiled Emacs-Lisp source + .eps encapsulated PostScript + .exp Expect source code + .f Fortran source + .f77 Fortran 77 source + .f90 Fortran 90 source + .fas pre-compiled Common-Lisp + .fi Fortran include files + .fig FIG image file (used by \fBxfig\fP(1)) + .fmt TeX format file + .gif Compuserve Graphics Image File format + .gmo GNU format message catalog + .gsf Ghostscript fonts + .gz file compressed using \fBgzip\fP(1) + .h C or C++ header files + .help help file + .hf equivalent to \fI.help\fP + .hlp equivalent to \fI.help\fP + .htm poor man's \fI.html\fP + .html HTML document used with the World Wide Web + .hqx 7-bit encoded Macintosh file + .i C source after preprocessing + .icon bitmap source + .idx reference or datum-index file for hypertext + or database system + .image bitmap source + .in configuration template, especially for GNU Autoconf + .info files for the Emacs info browser + .info-[0-9]+ splitted info files + .ins LaTeX package install file for docstrip + .itcl itcl source code; + itcl ([incr Tcl]) is an OO extension of tcl + .java a Java source file + .jpeg Joint Photographic Experts Group format + .jpg poor man's \fI.jpeg\fP + .kmap \fBlyx\fP(1) keymap + .l equivalent to \fI.lex\fP or \fI.lisp\fP + .lex \fBlex\fP(1) or \fBflex\fP(1) files + .lha lharc archive + .lib Common-Lisp library + .lisp Lisp source + .ln files for use with \fBlint\fP(1) + .log log file, in particular produced by TeX + .lsm Linux Software Map entry + .lsp Common-Lisp source + .lzh lharc archive + .m Objective-C source code + .m4 \fBm4\fP(1) source + .mac macro files for various programs + .man manual page (usually source rather than formatted) + .map map files for various programs + .me Nroff source using the me macro package + .mf Metafont (font generator for TeX) source + .mgp MagicPoint file + .mm sources for \fBgroff\fP(1) in mm - format + .mo Message catalog binary file + .mod Modula-2 source for implementation modules + .mov (quicktime) movie + .mp Metapost source + .mp2 MPEG Layer 2 (audio) file + .mp3 MPEG Layer 3 (audio) file + .mpeg movie file + .o object file + .old old or backup file + .orig backup (original) version of a file, from \fBpatch\fP(1) + .out output file, often executable program (a.out) + .p Pascal source + .pag dbm data base data file + .patch file differences for \fBpatch\fP(1) + .pbm portable bitmap format + .pcf X11 font files + .pdf Adobe Portable Data Format + (use Acrobat/\fBacroread\fP or \fBxpdf\fP) + .perl Perl source (see .ph, .pl and .pm) + .pfa PostScript font definition files, ASCII format + .pfb PostScript font definition files, binary format + .pgm portable greymap format + .pgp PGP binary data + .ph Perl header file + .php PHP program file + .php3 PHP3 program file + .pid File to store daemon pid (e.g. crond.pid) + .pl TeX property list file or Perl library file + .pm Perl module + .png Portable Network Graphics file + .po Message catalog source + .pod \fBperldoc\fP(1) file + .ppm portable pixmap format + .pr bitmap source + .ps PostScript file + .py Python source + .pyc compiled python + .qt quicktime movie + .r RATFOR source (obsolete) + .rej patches that \fBpatch\fP(1) couldn't apply + .rpm RedHat software package + .rtf Rich Text Format file + .rules rules for something + .s assembler source + .sa stub libraries for a.out shared libraries + .sc \fBsc\fP(1) spreadsheed commands + .scm Scheme source code + .sed sed source file + .sgml SGML source file + .sh \fBsh\fP(1) scripts + .shar archive created by the \fBshar\fP(1) utility + .so Shared library or dynamically loadable object + .sql SQL source + .sqml SQML schema or query program + .sty LaTeX style files + .sym Modula-2 compiled definition modules + .tar archive created by the \fBtar\fP(1) utility + .tar.Z tar(1) archive compressed with \fBcompress\fP(1) + .tar.bz2 tar(1) archive compressed with \fBbzip2\fP(1) + .tar.gz tar(1) archive compressed with \fBgzip\fP(1) + .taz tar(1) archive compressed with \fBcompress\fP(1) + .tcl tcl source code + .tex TeX or LaTeX source + .texi equivalent to \fI.texinfo\fP + .texinfo Texinfo documentation source + .text text file + .tfm TeX font metric file + .tgz tar archive compressed with \fBgzip\fP(1) + .tif poor man's \fI.tiff\fP + .tiff Tagged Image File Format + .tk tcl/tk script + .tmp temporary file + .tmpl template files + .txt equivalent to \fI.text\fP + .uu equivalent to \fI.uue\fP + .uue binary file encoded with \fBuuencode\fP(1) + .vf TeX virtual font file + .vpl TeX virtual property list file + .w Silvio Levi's CWEB + .wav wave sound file + .web Donald Knuth's WEB + .wml Source file for Web Meta Language + .xbm X11 bitmap source + .xcf GIMP graphic + .xml eXtended Markup Language file + .xsl XSL stylesheet + .xpm X11 pixmap source + .xs Perl xsub file produced by h2xs + .y \fByacc\fP(1) or \fBbison\fP(1) (parser generator) files + .z File compressed using \fBpack\fP(1) (or an old \fBgzip\fP(1)) + .zip \fBzip\fP(1) archive + .zoo \fBzoo\fP(1) archive + ~ Emacs or \fBpatch\fP(1) backup file + rc startup (`run control') file, e.g. \fI.newsrc\fP +.TE +.SH "CONFORMS TO" +General UNIX conventions. +.SH BUGS +This list is not exhaustive. +.SH "SEE ALSO" +.BR file (1), +.BR make (1) diff --git a/man7/tcp.7 b/man7/tcp.7 new file mode 100644 index 000000000..d28b81876 --- /dev/null +++ b/man7/tcp.7 @@ -0,0 +1,711 @@ +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" +.\" 2.4 Updates by Nivedita Singhvi 4/20/02 . +.\" +.TH TCP 7 2003-08-21 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +tcp \- TCP protocol +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B tcp_socket = socket(PF_INET, SOCK_STREAM, 0); +.SH DESCRIPTION +This is an implementation of the TCP protocol defined in +RFC793, RFC1122 and RFC2001 with the NewReno and SACK +extensions. It provides a reliable, stream oriented, full +duplex connection between two sockets on top of +.BR ip (7), +for both v4 and v6 versions. +TCP guarantees that the data arrives in order and +retransmits lost packets. It generates and checks a per +packet checksum to catch transmission errors. TCP does not +preserve record boundaries. + +A fresh TCP socket has no remote or local address and is not +fully specified. To create an outgoing TCP connection use +.BR connect (2) +to establish a connection to another TCP socket. +To receive new incoming connections +.BR bind (2) +the socket first to a local address and port and then call +.BR listen (2) +to put the socket into listening state. After that a new +socket for each incoming connection can be accepted +using +.BR accept (2). +A socket which has had +.B accept +or +.B connect +successfully called on it is fully specified and may +transmit data. Data cannot be transmitted on listening or +not yet connected sockets. + +Linux supports RFC1323 TCP high performance +extensions. These include Protection Against Wrapped +Sequence Numbers (PAWS), Window Scaling and +Timestamps. Window scaling allows the use +of large (> 64K) TCP windows in order to support links with high +latency or bandwidth. To make use of them, the send and +receive buffer sizes must be increased. +They can be set globally with the +.B net.ipv4.tcp_wmem +and +.B net.ipv4.tcp_rmem +sysctl variables, or on individual sockets by using the +.B SO_SNDBUF +and +.B SO_RCVBUF +socket options with the +.BR setsockopt (2) +call. + +The maximum sizes for socket buffers declared via the +.B SO_SNDBUF +and +.B SO_RCVBUF +mechanisms are limited by the global +.B net.core.rmem_max +and +.B net.core.wmem_max +sysctls. Note that TCP actually allocates twice the size of +the buffer requested in the +.BR setsockopt (2) +call, and so a succeeding +.BR getsockopt (2) +call will not return the same size of buffer as requested +in the +.BR setsockopt (2) +call. TCP uses this for administrative purposes and internal +kernel structures, and the sysctl variables reflect the +larger sizes compared to the actual TCP windows. +On individual connections, the socket buffer size must be +set prior to the +.B listen() +or +.B connect() +calls in order to have it take effect. See +.BR socket (7) +for more information. +.PP +TCP supports urgent data. Urgent data is used to signal the +receiver that some important message is part of the data +stream and that it should be processed as soon as possible. +To send urgent data specify the +.B MSG_OOB +option to +.BR send (2). +When urgent data is received, the kernel sends a +.B SIGURG +signal to the reading process or the process or process +group that has been set for the socket using the +.B SIOCSPGRP +or +.B FIOSETOWN +ioctls. When the +.B SO_OOBINLINE +socket option is enabled, urgent data is put into the normal +data stream (and can be tested for by the +.B SIOCATMARK +ioctl), +otherwise it can be only received when the +.B MSG_OOB +flag is set for +.BR sendmsg (2). + +Linux 2.4 introduced a number of changes for improved +throughput and scaling, as well as enhanced functionality. +Some of these features include support for zerocopy +.BR sendfile (2), +Explicit Congestion Notification, new +management of TIME_WAIT sockets, keep-alive socket options +and support for Duplicate SACK extensions. +.SH "ADDRESS FORMATS" +TCP is built on top of IP (see +.BR ip (7)). +The address formats defined by +.BR ip (7) +apply to TCP. TCP only supports point-to-point +communication; broadcasting and multicasting are not +supported. +.SH SYSCTLS +These variables can be accessed by the +.B /proc/sys/net/ipv4/* +files or with the +.BR sysctl (2) +interface. In addition, most IP sysctls also apply to TCP; see +.BR ip (7). +.TP +.B tcp_abort_on_overflow +Enable resetting connections if the listening service is too +slow and unable to keep up and accept them. It is not +enabled by default. It means that if overflow occurred due +to a burst, the connection will recover. Enable this option +_only_ if you are really sure that the listening daemon +cannot be tuned to accept connections faster. Enabling this +option can harm the clients of your server. +.TP +.B tcp_adv_win_scale +Count buffering overhead as bytes/2^tcp_adv_win_scale +(if tcp_adv_win_scale > 0) or bytes-bytes/2^(-tcp_adv_win_scale), +if it is <= 0. The default is 2. + +The socket receive buffer space is shared between the +application and kernel. TCP maintains part of the buffer as +the TCP window, this is the size of the receive window +advertised to the other end. The rest of the space is used +as the "application" buffer, used to isolate the network +from scheduling and application latencies. The +.B tcp_adv_win_scale +default value of 2 implies that the space +used for the application buffer is one fourth that of the +total. +.TP +.B tcp_app_win +This variable defines how many +bytes of the TCP window are reserved for buffering +overhead. + +A maximum of (window/2^tcp_app_win, mss) bytes in the window +are reserved for the application buffer. A value of 0 +implies that no amount is reserved. The default value is 31. +.TP +.B tcp_dsack +Enable RFC2883 TCP Duplicate SACK support. +It is enabled by default. +.TP +.B tcp_ecn +Enable RFC2884 Explicit Congestion Notification. It is not +enabled by default. When enabled, connectivity to some +destinations could be affected due to older, misbehaving +routers along the path causing connections to be dropped. +.TP +.B tcp_fack +Enable TCP Forward Acknowledgement support. It is enabled by +default. +.TP +.B tcp_fin_timeout +How many seconds to wait for a final FIN packet before the +socket is forcibly closed. This is strictly a violation of +the TCP specification, but required to prevent +denial-of-service (DoS) attacks. The default value in 2.4 +kernels is 60, down from 180 in 2.2. +.TP +.B tcp_keepalive_intvl +The number of seconds between TCP keep-alive probes. +The default value is 75 seconds. +.TP +.B tcp_keepalive_probes +The maximum number of TCP keep-alive probes to send +before giving up and killing the connection if +no response is obtained from the other end. +The default value is 9. +.TP +.B tcp_keepalive_time +The number of seconds a connection needs to be idle +before TCP begins sending out keep-alive probes. +Keep-alives are only sent when the +.B SO_KEEPALIVE +socket option is enabled. The default value is 7200 seconds +(2 hours). An idle connection is terminated after +approximately an additional 11 minutes (9 probes an interval +of 75 seconds apart) when keep-alive is enabled. + +Note that underlying connection tracking mechanisms and +application timeouts may be much shorter. +.TP +.B tcp_max_orphans +The maximum number of orphaned (not attached to any user file +handle) TCP sockets allowed in the system. When this number +is exceeded, the orphaned connection is reset and a warning +is printed. This limit exists only to prevent simple DoS +attacks. Lowering this limit is not recommended. Network +conditions might require you to increase the number of +orphans allowed, but note that each orphan can eat up to ~64K +of unswappable memory. The default initial value is set +equal to the kernel parameter NR_FILE. This initial default +is adjusted depending on the memory in the system. +.TP +.B tcp_max_syn_backlog +The maximum number of queued connection requests which have +still not received an acknowledgement from the connecting +client. If this number is exceeded, the kernel will begin +dropping requests. The default value of 256 is increased to +1024 when the memory present in the system is adequate or +greater (>= 128Mb), and reduced to 128 for those systems with +very low memory (<= 32Mb). It is recommended that if this +needs to be increased above 1024, TCP_SYNQ_HSIZE in +include/net/tcp.h be modified to keep +TCP_SYNQ_HSIZE*16<=tcp_max_syn_backlog, and the kernel be +recompiled. +.TP +.B tcp_max_tw_buckets +The maximum number of sockets in TIME_WAIT state allowed in +the system. This limit exists only to prevent simple DoS +attacks. The default value of NR_FILE*2 is adjusted +depending on the memory in the system. If this number is +exceeded, the socket is closed and a warning is printed. +.TP +.B tcp_mem +This is a vector of 3 integers: [low, pressure, high]. These +bounds are used by TCP to track its memory usage. The +defaults are calculated at boot time from the amount of +available memory. + +.I low +- TCP doesn't regulate its memory allocation when the number +of pages it has allocated globally is below this number. + +.I pressure +- when the amount of memory allocated by TCP +exceeds this number of pages, TCP moderates its memory +consumption. This memory pressure state is exited +once the number of pages allocated falls below +the +.B low +mark. + +.I high +- the maximum number of pages, globally, that TCP +will allocate. This value overrides any other limits +imposed by the kernel. +.TP +.B tcp_orphan_retries +The maximum number of attempts made to probe the other +end of a connection which has been closed by our end. +The default value is 8. +.TP +.B tcp_reordering +The maximum a packet can be reordered in a TCP packet stream +without TCP assuming packet loss and going into slow start. +The default is 3. It is not advisable to change this number. +This is a packet reordering detection metric designed to +minimize unnecessary back off and retransmits provoked by +reordering of packets on a connection. +.TP +.B tcp_retrans_collapse +Try to send full-sized packets during retransmit. +This is enabled by default. +.TP +.B tcp_retries1 +The number of times TCP will attempt to retransmit a +packet on an established connection normally, +without the extra effort of getting the network +layers involved. Once we exceed this number of +retransmits, we first have the network layer +update the route if possible before each new retransmit. +The default is the RFC specified minimum of 3. +.TP +.B tcp_retries2 +The maximum number of times a TCP packet is retransmitted +in established state before giving up. The default +value is 15, which corresponds to a duration of +approximately between 13 to 30 minutes, depending +on the retransmission timeout. The RFC1122 specified +minimum limit of 100 seconds is typically deemed too +short. +.TP +.B tcp_rfc1337 +Enable TCP behaviour conformant with RFC 1337. +This is not enabled by default. When not enabled, +if a RST is received in TIME_WAIT state, we close +the socket immediately without waiting for the end +of the TIME_WAIT period. +.TP +.B tcp_rmem +This is a vector of 3 integers: [min, default, +max]. These parameters are used by TCP to regulate receive +buffer sizes. TCP dynamically adjusts the size of the +receive buffer from the defaults listed below, in the range +of these sysctl variables, depending on memory available +in the system. + +.I min +- minimum size of the receive buffer used by each TCP +socket. The default value is 4K, and is lowered to +PAGE_SIZE bytes in low memory systems. This value +is used to ensure that in memory pressure mode, +allocations below this size will still succeed. This is not +used to bound the size of the receive buffer declared +using +.B SO_RCVBUF +on a socket. + +.I default +- the default size of the receive buffer for a TCP socket. +This value overwrites the initial default buffer size from +the generic global +.B net.core.rmem_default +defined for all protocols. The default value is 87380 +bytes, and is lowered to 43689 in low memory systems. If +larger receive buffer sizes are desired, this value should +be increased (to affect all sockets). To employ large TCP +windows, the +.B net.ipv4.tcp_window_scaling +must be enabled (default). + +.I max +- the maximum size of the receive buffer used by +each TCP socket. This value does not override the global +.BR net.core.rmem_max . +This is not used to limit the size of the receive buffer +declared using +.B SO_RCVBUF +on a socket. +The default value of 87380*2 bytes is lowered to 87380 +in low memory systems. +.TP +.B tcp_sack +Enable RFC2018 TCP Selective Acknowledgements. +It is enabled by default. +.TP +.B tcp_stdurg +Enable the strict RFC793 interpretation of the TCP +urgent-pointer field. The default is to use the +BSD-compatible interpretation of the urgent-pointer, pointing +to the first byte after the urgent data. The RFC793 +interpretation is to have it point to the last byte of urgent +data. Enabling this option may lead to interoperatibility +problems. +.TP +.B tcp_synack_retries +The maximum number of times a SYN/ACK segment +for a passive TCP connection will be retransmitted. +This number should not be higher than 255. The default +value is 5. +.TP +.B tcp_syncookies +Enable TCP syncookies. The kernel must be compiled with +.BR CONFIG_SYN_COOKIES . +Send out syncookies when the syn backlog queue of a socket +overflows. The syncookies feature attempts to protect a +socket from a SYN flood attack. This should be used as a +last resort, if at all. This is a violation of the TCP +protocol, and conflicts with other areas of TCP such as TCP +extensions. It can cause problems for clients and relays. +It is not recommended as a tuning mechanism for heavily +loaded servers to help with overloaded or misconfigured +conditions. For recommended alternatives see +.BR tcp_max_syn_backlog , +.BR tcp_synack_retries , +.BR tcp_abort_on_overflow . +.TP +.B tcp_syn_retries +The maximum number of times initial SYNs for an active TCP +connection attempt will be retransmitted. This value should +not be higher than 255. The default value is 5, which +corresponds to approximately 180 seconds. +.TP +.B tcp_timestamps +Enable RFC1323 TCP timestamps. This is enabled +by default. +.TP +.B tcp_tw_recycle +Enable fast recycling of TIME-WAIT sockets. It is +not enabled by default. Enabling this option is not +recommended since this causes problems when working +with NAT (Network Address Translation). +.TP +.B tcp_window_scaling +Enable RFC1323 TCP window scaling. It is enabled by +default. This feature allows the use of a large window +(> 64K) on a TCP connection, should the other end support it. +Normally, the 16 bit window length field in the TCP header +limits the window size to less than 64K bytes. If larger +windows are desired, applications can increase the size of +their socket buffers and the window scaling option will be +employed. If +.B tcp_window_scaling +is disabled, TCP will not negotiate the use of window +scaling with the other end during connection setup. +.TP +.B tcp_wmem +This is a vector of 3 integers: [min, default, max]. These +parameters are used by TCP to regulate send buffer sizes. +TCP dynamically adjusts the size of the send buffer from the +default values listed below, in the range of these sysctl +variables, depending on memory available. + +.I min +- minimum size of the send buffer used by each TCP socket. +The default value is 4K bytes. +This value is used to ensure that in memory pressure mode, +allocations below this size will still succeed. This is not +used to bound the size of the send buffer declared +using +.B SO_SNDBUF +on a socket. + +.I default +- the default size of the send buffer for a TCP socket. +This value overwrites the initial default buffer size from +the generic global +.B net.core.wmem_default +defined for all protocols. The default value is 16K bytes. +If larger send buffer sizes are desired, this value +should be increased (to affect all sockets). To employ +large TCP windows, the sysctl variable +.B net.ipv4.tcp_window_scaling +must be enabled (default). + +.I max +- the maximum size of the send buffer used by +each TCP socket. This value does not override the global +.BR net.core.wmem_max . +This is not used to limit the size of the send buffer +declared using +.B SO_SNDBUF +on a socket. +The default value is 128K bytes. It is lowered to 64K +depending on the memory available in the system. +.SH "SOCKET OPTIONS" +To set or get a TCP socket option, call +.BR getsockopt (2) +to read or +.BR setsockopt (2) +to write the option with the option level argument set to +.BR SOL_TCP. +In addition, +most +.B SOL_IP +socket options are valid on TCP sockets. For more +information see +.BR ip (7). +.TP +.B TCP_CORK +If set, don't send out partial frames. All queued +partial frames are sent when the option is cleared again. +This is useful for prepending headers before calling +.BR sendfile (2), +or for throughput optimization. This option cannot be +combined with +.BR TCP_NODELAY. +This option should not be used in code intended to be +portable. +.TP +.B TCP_DEFER_ACCEPT +Allows a listener to be awakened only when data arrives on +the socket. Takes an integer value (seconds), this can +bound the maximum number of attempts TCP will make to +complete the connection. This option should not be used in +code intended to be portable. +.TP +.B TCP_INFO +Used to collect information about this socket. The kernel +returns a struct tcp_info as defined in the file +/usr/include/linux/tcp.h. This option should not be used in +code intended to be portable. +.TP +.B TCP_KEEPCNT +The maximum number of keepalive probes TCP should send +before dropping the connection. This option should not be +used in code intended to be portable. +.TP +.B TCP_KEEPIDLE +The time (in seconds) the connection needs to remain idle +before TCP starts sending keepalive probes, if the socket +option SO_KEEPALIVE has been set on this socket. This +option should not be used in code intended to be portable. +.TP +.B TCP_KEEPINTVL +The time (in seconds) between individual keepalive probes. +This option should not be used in code intended to be +portable. +.TP +.B TCP_LINGER2 +The lifetime of orphaned FIN_WAIT2 state sockets. This +option can be used to override the system wide sysctl +.B tcp_fin_timeout +on this socket. This is not to be confused with the +.BR socket (7) +level option +.BR SO_LINGER . +This option should not be used in code intended to be +portable. +.TP +.B TCP_MAXSEG +The maximum segment size for outgoing TCP packets. If this +option is set before connection establishment, it also +changes the MSS value announced to the other end in the +initial packet. Values greater than the (eventual) +interface MTU have no effect. TCP will also impose +its minimum and maximum bounds over the value provided. +.TP +.B TCP_NODELAY +If set, disable the Nagle algorithm. This means that segments +are always sent as soon as possible, even if there is only a +small amount of data. When not set, data is buffered until there +is a sufficient amount to send out, thereby avoiding the +frequent sending of small packets, which results in poor +utilization of the network. This option cannot be used +at the same time as the option +.BR TCP_CORK . +.TP +.B TCP_QUICKACK +Enable quickack mode if set or disable quickack +mode if cleared. In quickack mode, acks are sent +immediately, rather than delayed if needed in accordance +to normal TCP operation. This flag is not permanent, +it only enables a switch to or from quickack mode. +Subsequent operation of the TCP protocol will +once again enter/leave quickack mode depending on +internal protocol processing and factors such as +delayed ack timeouts occurring and data transfer. +This option should not be used in code intended to be +portable. +.TP +.B TCP_SYNCNT +Set the number of SYN retransmits that TCP should send before +aborting the attempt to connect. It cannot exceed 255. +This option should not be used in code intended to be +portable. +.TP +.B TCP_WINDOW_CLAMP +Bound the size of the advertised window to this value. The +kernel imposes a minimum size of SOCK_MIN_RCVBUF/2. +This option should not be used in code intended to be +portable. +.SH IOCTLS +These ioctls can be accessed using +.BR ioctl (2). +The correct syntax is: +.PP +.RS +.nf +.BI int " value"; +.IB error " = ioctl(" tcp_socket ", " ioctl_type ", &" value ");" +.fi +.RE +.TP +.BR SIOCINQ +Returns the amount of queued unread data in the receive +buffer. Argument is a pointer to an integer. The socket +must not be in LISTEN state, otherwise an error (EINVAL) +is returned. +.TP +.B SIOCATMARK +Returns true when the all urgent data has been already +received by the user program. This is used together with +.BR SO_OOBINLINE . +Argument is an pointer to an integer for the test result. +.TP +.B SIOCOUTQ +Returns the amount of unsent data in the socket send queue +in the passed integer value pointer. The socket must not +be in LISTEN state, otherwise an error (EINVAL) +is returned. +.SH "ERROR HANDLING" +When a network error occurs, TCP tries to resend the +packet. If it doesn't succeed after some time, either +.B ETIMEDOUT +or the last received error on this connection is reported. +.PP +Some applications require a quicker error notification. +This can be enabled with the +.B SOL_IP +level +.B IP_RECVERR +socket option. When this option is enabled, all incoming +errors are immediately passed to the user program. Use this +option with care \- it makes TCP less tolerant to routing +changes and other normal network conditions. +.SH NOTES +When an error occurs doing a connection setup occurring in a +socket write +.B SIGPIPE +is only raised when the +.B SO_KEEPALIVE +socket option is set. +.PP +TCP has no real out-of-band data; it has urgent data. In +Linux this means if the other end sends newer out-of-band +data the older urgent data is inserted as normal data into +the stream (even when +.B SO_OOBINLINE +is not set). This differs from BSD based stacks. +.PP +Linux uses the BSD compatible interpretation of the urgent +pointer field by default. This violates RFC1122, but is +required for interoperability with other stacks. It can be +changed by the +.B tcp_stdurg +sysctl. +.SH ERRORS +.TP +.B EPIPE +The other end closed the socket unexpectedly or a read is +executed on a shut down socket. +.TP +.B ETIMEDOUT +The other end didn't acknowledge retransmitted data after +some time. +.TP +.B EAFNOTSUPPORT +Passed socket address type in +.I sin_family +was not +.BR AF_INET . +.PP +Any errors defined for +.BR ip (7) +or the generic socket layer may also be returned for TCP. +.SH BUGS +Not all errors are documented. +.br +IPv6 is not described. +.\" Only a single Linux kernel version is described +.\" Info for 2.2 was lost. Should be added again, +.\" or put into a separate page. +.SH VERSIONS +Support for Explicit Congestion Notification, zerocopy +sendfile, reordering support and some SACK extensions +(DSACK) were introduced in 2.4. +Support for forward acknowledgement (FACK), TIME_WAIT recycling, +per connection keepalive socket options and sysctls +were introduced in 2.3. + +The default values and descriptions for the sysctl variables +given above are applicable for the 2.4 kernel. +.SH AUTHORS +This man page was originally written by Andi Kleen. +It was updated for 2.4 by Nivedita Singhvi with input from +Alexey Kuznetsov's Documentation/networking/ip-sysctls.txt +document. +.SH "SEE ALSO" +.BR accept (2), +.BR bind (2), +.BR connect (2), +.BR getsockopt (2), +.BR listen (2), +.BR recvmsg (2), +.BR sendfile (2), +.BR sendmsg (2), +.BR socket (2), +.BR sysctl (2), +.BR ip (7), +.BR socket (7) +.sp +RFC793 for the TCP specification. +.br +RFC1122 for the TCP requirements and a description +of the Nagle algorithm. +.br +RFC1323 for TCP timestamp and window scaling options. +.br +RFC1644 for a description of TIME_WAIT assassination +hazards. +.br +RFC2481 for a description of Explicit Congestion +Notification. +.br +RFC2581 for TCP congestion control algorithms. +.br +RFC2018 and RFC2883 for SACK and extensions to SACK. diff --git a/man7/udp.7 b/man7/udp.7 new file mode 100644 index 000000000..7d1528681 --- /dev/null +++ b/man7/udp.7 @@ -0,0 +1,161 @@ +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" $Id: udp.7,v 1.7 2000/01/22 01:55:05 freitag Exp $ +.TH UDP 7 1998-10-02 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +udp \- User Datagram Protocol for IPv4 +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B udp_socket = socket(PF_INET, SOCK_DGRAM, 0); +.SH DESCRIPTION +This is an implemention of the User Datagram Protocol described in RFC768. It +implements a connectionless, unreliable datagram packet service. +Packets may be reordered or duplicated before they arrive. UDP +generates and checks checksums to catch transmission errors. + +When a UDP socket is created, its local and remote addresses are unspecified. +Datagrams can be sent immediately using +.BR sendto (2) +or +.BR sendmsg (2) +with a valid destination address as an argument. When +.BR connect (2) +is called on the socket the default destination address is set and datagrams +can now be sent using +.BR send (2) +or +.BR write (2) +without specifying an destination address. +It is still possible to send to other destinations by passing an address to +.BR sendto (2) +or +.BR sendmsg (2). +In order to receive packets the socket can be bound to an local +address first by using +.BR bind (2). +Otherwise the socket layer will automatically assign +a free local port out of the range defined by +.I net.ipv4.ip_local_port_range +and bind the socket to +.IR INADDR_ANY . + +All receive operations return only one packet. When the packet is smaller +than the passed buffer only that much data is returned, when it is bigger +the packet is truncated and the +.B MSG_TRUNC +flag is set. +.I MSG_WAITALL +is not supported. + +IP options may be sent or received using the socket options described in +.BR ip (7). +They are only processed by the kernel when the appropriate sysctl +is enabled (but still passed to the user even when it is turned off). See +.BR ip (7). + +When the +.B MSG_DONTROUTE +flag is set on sending the destination address must refer to an local +interface address and the packet is only sent to that interface. + +UDP fragments a packet when its total length exceeds the interface MTU +(Maximum Transmission Unit). +A more network friendly alternative is to use path MTU discovery +as described in the +.B IP_MTU_DISCOVER +section of +.BR ip (7). + +.SH "ADDRESS FORMAT" +UDP uses the IPv4 +.B sockaddr_in +address format described in +.BR ip (7). + +.SH "ERROR HANDLING" +All fatal errors will be passed to the user as an error return even +when the socket is not connected. This includes asynchronous errors +received from the network. You may get an error for an earlier packet +that was sent on the same socket. +This behaviour differs from many other BSD socket implementations +which don't pass any errors unless the socket is connected. +Linux's behaviour is mandated by +.BR RFC1122 . + +For compatibility with legacy code it is possible to set the +.B SO_BSDCOMPAT +SOL_SOCKET option to receive remote errors only when the socket has been +connected (except for +.B EPROTO +and +.BR EMSGSIZE ). +It is better to fix the +code to handle errors properly than to enable this option. +Locally generated errors are always passed. + +When the +.B IP_RECVERR +option is enabled all errors are stored in the socket error queue +and can be received by +.BR recvmsg (2) +with the +.B MSG_ERRQUEUE +flag set. +.SH IOCTLS +These ioctls can be accessed using +.BR ioctl (2). +The correct syntax is: +.PP +.RS +.nf +.BI int " value"; +.IB error " = ioctl(" tcp_socket ", " ioctl_type ", &" value ");" +.fi +.RE +.TP +.BR FIONREAD " (" SIOCINQ ) +Gets a pointer to an integer as argument. Returns the size of the next +pending datagram in the integer in bytes, or 0 when no datagram is pending. +.TP +.BR TIOCOUTQ " (" SIOCOUTQ ) +Returns the number of data bytes in the local send queue. Only supported +with Linux 2.4 and above. +.PP +In addition all ioctls documented in +.BR ip (7) +and +.BR socket (7) +are supported. +.SH ERRORS +All errors documented for +.BR socket (7) +or +.BR ip (7) +may be returned by a send or receive on a UDP socket. + +.B ECONNREFUSED +No receiver was associated with the destination address. This might be +caused by a previous packet sent over the socket. + +.SH VERSIONS +IP_RECVERR is a new feature in Linux 2.2. + +.SH CREDITS +This man page was written by Andi Kleen. + +.SH "SEE ALSO" +.BR ip (7), +.BR raw (7), +.BR socket (7) + +RFC768 for the User Datagram Protocol. +.br +RFC1122 for the host requirements. +.br +RFC1191 for a description of path MTU discovery. diff --git a/man7/unicode.7 b/man7/unicode.7 new file mode 100644 index 000000000..89607cc15 --- /dev/null +++ b/man7/unicode.7 @@ -0,0 +1,288 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) Markus Kuhn, 1995, 2001 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 1995-11-26 Markus Kuhn +.\" First version written +.\" 2001-05-11 Markus Kuhn +.\" Update +.\" +.TH UNICODE 7 2001-05-11 "GNU" "Linux Programmer's Manual" +.SH NAME +Unicode \- the Universal Character Set +.SH DESCRIPTION +The international standard +.B ISO 10646 +defines the +.BR "Universal Character Set (UCS)" . +UCS contains all characters of all other character set standards. It +also guarantees +.BR "round-trip compatibility" , +i.e., conversion tables can be built such that no information is lost +when a string is converted from any other encoding to UCS and back. + +UCS contains the characters required to represent practically all +known languages. This includes not only the Latin, Greek, Cyrillic, +Hebrew, Arabic, Armenian, and Georgian scripts, but also also Chinese, +Japanese and Korean Han ideographs as well as scripts such as +Hiragana, Katakana, Hangul, Devanagari, Bengali, Gurmukhi, Gujarati, +Oriya, Tamil, Telugu, Kannada, Malayalam, Thai, Lao, Khmer, Bopomofo, +Tibetan, Runic, Ethiopic, Canadian Syllabics, Cherokee, Mongolian, +Ogham, Myanmar, Sinhala, Thaana, Yi, and others. For scripts not yet +covered, research on how to best encode them for computer usage is +still going on and they will be added eventually. This might +eventually include not only Hieroglyphs and various historic +Indo-European languages, but even some selected artistic scripts such +as Tengwar, Cirth, and Klingon. UCS also covers a large number of +graphical, typographical, mathematical and scientific symbols, +including those provided by TeX, Postscript, APL, MS-DOS, MS-Windows, +Macintosh, OCR fonts, as well as many word processing and publishing +systems, and more are being added. + +The UCS standard (ISO 10646) describes a +.I "31-bit character set architecture" +consisting of 128 24-bit +.IR groups , +each divided into 256 16-bit +.I planes +made up of 256 8-bit +.I rows +with 256 +.I column +positions, one for each character. Part 1 of the standard +.RB ( "ISO 10646-1" ) +defines the first 65534 code positions (0x0000 to 0xfffd), which form +the +.IR "Basic Multilingual Plane (BMP)" , +that is plane 0 in group 0. Part 2 of the standard +.RB ( "ISO 10646-2" ) +adds characters to group 0 outside the BMP in several +.I "supplementary planes" +in the range 0x10000 to 0x10ffff. There are no plans to add characters +beyond 0x10ffff to the standard, therefore of the entire code space, +only a small fraction of group 0 will ever be actually used in the +foreseeable future. The BMP contains all characters found in the +commonly used other character sets. The supplemental planes added by +ISO 10646-2 cover only more exotic characters for special scientific, +dictionary printing, publishing industry, higher-level protocol and +enthusiast needs. +.PP +The representation of each UCS character as a 2-byte word is referred +to as the +.B UCS-2 +form (only for BMP characters), whereas +.B UCS-4 +is the representation of each character by a 4-byte word. +In addition, there exist two encoding forms +.B UTF-8 +for backwards compatibility with ASCII processing software and +.B UTF-16 +for the backwards compatible handling of non-BMP characters up to +0x10ffff by UCS-2 software. +.PP +The UCS characters 0x0000 to 0x007f are identical to those of the +classic +.B US-ASCII +character set and the characters in the range 0x0000 to 0x00ff +are identical to those in +.BR "ISO 8859-1 Latin-1" . +.SH "COMBINING CHARACTERS" +Some code points in +.B UCS +have been assigned to +.IR "combining characters" . +These are similar to the non-spacing accent keys on a typewriter. A +combining character just adds an accent to the previous character. The +most important accented characters have codes of their own in UCS, +however, the combining character mechanism allows us to add accents +and other diacritical marks to any character. The combining characters +always follow the character which they modify. For example, the German +character Umlaut-A ("Latin capital letter A with diaeresis") can +either be represented by the precomposed UCS code 0x00c4, or +alternatively as the combination of a normal "Latin capital letter A" +followed by a "combining diaeresis": 0x0041 0x0308. +.PP +Combining characters are essential for instance for encoding the Thai +script or for mathematical typesetting and users of the International +Phonetic Alphabet. +.SH "IMPLEMENTATION LEVELS" +As not all systems are expected to support advanced mechanisms like +combining characters, ISO 10646-1 specifies the following three +.I implementation levels +of UCS: +.TP 0.9i +Level 1 +Combining characters and +.B Hangul Jamo +(a variant encoding of the Korean script, where a Hangul syllable +glyph is coded as a triplet or pair of vovel/consonant codes) are not +supported. +.TP +Level 2 +In addition to level 1, combining characters are now allowed for some +languages where they are essential (e.g., Thai, Lao, Hebrew, +Arabic, Devanagari, Malayalam, etc.). +.TP +Level 3 +All +.B UCS +characters are supported. +.PP +The +.B Unicode 3.0 Standard +published by the +.B Unicode Consortium +contains exactly the +.B UCS Basic Multilingual Plane +at implementation level 3, as described in ISO 10646-1:2000. +.B Unicode 3.1 +added the supplemental planes of ISO 10646-2. The Unicode standard and +technical reports published by the Unicode Consortium provide much +additional information on the semantics and recommended usages of +various characters. They provide guidelines and algorithms for +editing, sorting, comparing, normalizing, converting and displaying +Unicode strings. +.SH "UNICODE UNDER LINUX" +Under GNU/Linux, the C type +.B wchar_t +is a signed 32-bit integer type. Its values are always interpreted +by the C library as +.B UCS +code values (in all locales), a convention that is signaled by the GNU +C library to applications by defining the constant +.B __STDC_ISO_10646__ +as specified in the ISO C 99 standard. + +UCS/Unicode can be used just like ASCII in input/output streams, +terminal communication, plaintext files, filenames, and environment +variables in the ASCII compatible +.B UTF-8 +multi-byte encoding. To signal the use of UTF-8 as the character +encoding to all applications, a suitable +.B locale +has to be selected via environment variables (e.g., +"LANG=en_GB.UTF-8"). +.PP +The +.B nl_langinfo(CODESET) +function returns the name of the selected encoding. Library functions +such as +.BR wctomb (3) +and +.BR mbsrtowcs (3) +can be used to transform the internal +.B wchar_t +characters and strings into the system character encoding and back +and +.BR wcwidth (3) +tells, how many positions (0\(en2) the cursor is advanced by the +output of a character. +.PP +Under Linux, in general only the BMP at implementation level 1 should +be used at the moment. Up to two combining characters per base +character for certain scripts (in particular Thai) are also supported +by some UTF-8 terminal emulators and ISO 10646 fonts (level 2), but in +general precomposed characters should be preferred where available +(Unicode calls this +.BR "Normalization Form C" ). +.SH "PRIVATE AREA" +In the +.BR BMP , +the range 0xe000 to 0xf8ff will never be assigned to any characters by +the standard and is reserved for private usage. For the Linux +community, this private area has been subdivided further into the +range 0xe000 to 0xefff which can be used individually by any end-user +and the Linux zone in the range 0xf000 to 0xf8ff where extensions are +coordinated among all Linux users. The registry of the characters +assigned to the Linux zone is currently maintained by H. Peter Anvin +. +.SH LITERATURE +.TP 0.2i +* +Information technology \(em Universal Multiple-Octet Coded Character +Set (UCS) \(em Part 1: Architecture and Basic Multilingual Plane. +International Standard ISO/IEC 10646-1, International Organization +for Standardization, Geneva, 2000. + +This is the official specification of +.BR UCS . +Available as a PDF file on CD-ROM from http://www.iso.ch/. +.TP +* +The Unicode Standard, Version 3.0. +The Unicode Consortium, Addison-Wesley, +Reading, MA, 2000, ISBN 0-201-61633-5. +.TP +* +S. Harbison, G. Steele. C: A Reference Manual. Fourth edition, +Prentice Hall, Englewood Cliffs, 1995, ISBN 0-13-326224-3. + +A good reference book about the C programming language. The fourth +edition covers the 1994 Amendment 1 to the ISO C 90 standard, which +adds a large number of new C library functions for handling wide and +multi-byte character encodings, but it does not yet cover ISO C 99, +which improved wide and multi-byte character support even further. +.TP +* +Unicode Technical Reports. +.RS +http://www.unicode.org/unicode/reports/ +.RE +.TP +* +Markus Kuhn: UTF-8 and Unicode FAQ for Unix/Linux. +.RS +http://www.cl.cam.ac.uk/~mgk25/unicode.html + +Provides subscription information for the +.B linux-utf8 +mailing list, which is the best place to look for advice on using +Unicode under Linux. +.RE +.TP +* +Bruno Haible: Unicode HOWTO. +.RS +ftp://ftp.ilog.fr/pub/Users/haible/utf8/Unicode-HOWTO.html +.RE +.SH BUGS +When this man page was last revised, the GNU C Library support for +.B UTF-8 +locales was mature and XFree86 support was in an advanced state, but +work on making applications (most notably editors) suitable for use in +.B UTF-8 +locales was still fully in progress. Current general +.B UCS +support under Linux usually provides for CJK double-width characters +and sometimes even simple overstriking combining characters, but +usually does not include support for scripts with right-to-left +writing direction or ligature substitution requirements such as +Hebrew, Arabic, or the Indic scripts. These scripts are currently only +supported in certain GUI applications (HTML viewers, word processors) +with sophisticated text rendering engines. +.SH AUTHOR +Markus Kuhn +.SH "SEE ALSO" +.BR setlocale (3), +.BR charsets (7), +.BR utf-8 (7) diff --git a/man7/units.7 b/man7/units.7 new file mode 100644 index 000000000..0dbdfbddd --- /dev/null +++ b/man7/units.7 @@ -0,0 +1,124 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH UNITS 7 2001-12-22 "Linux" "Linux Programmer's Manual" +.SH NAME +units, kilo, kibi, mega, mebi, giga, gibi \- decimal and binary prefixes +.SH DESCRIPTION +.SS Decimal prefixes +The SI system of units uses prefixes that indicate powers of ten. +A kilometer is 1000 meter, and a megawatt is 1000000 watt. +Below the standard prefixes. + +.RS +.TS +l l l. +Prefix Name Value +y yocto 10^-24 = 0.000000000000000000000001 +z zepto 10^-21 = 0.000000000000000000001 +a atto 10^-18 = 0.000000000000000001 +f femto 10^-15 = 0.000000000000001 +p pico 10^-12 = 0.000000000001 +n nano 10^-9 = 0.000000001 +u micro 10^-6 = 0.000001 +m milli 10^-3 = 0.001 +c centi 10^-2 = 0.01 +d deci 10^-1 = 0.1 +da deka 10^ 1 = 10 +h hecto 10^ 2 = 100 +k kilo 10^ 3 = 1000 +M mega 10^ 6 = 1000000 +G giga 10^ 9 = 1000000000 +T tera 10^12 = 1000000000000 +P peta 10^15 = 1000000000000000 +E exa 10^18 = 1000000000000000000 +Z zetta 10^21 = 1000000000000000000000 +Y yotta 10^24 = 1000000000000000000000000 +.TE +.RE + +The symbol for micro is the Greek letter mu, often written u +in an ASCII context where this Greek letter is not available. +See also +.sp +.RS +http://physics.nist.gov/cuu/Units/prefixes.html +.RE +.SS Binary prefixes +The binary prefixes resemble the decimal ones, but have an additional 'i' +(and "Ki" starts with a capital 'K'). The names are formed by taking the +first syllable of the names of the decimal prefix with roughly the same +size, followed by "bi" for "binary". + +.RS +.TS +l l l. +Prefix Name Value +Ki kibi 2^10 = 1024 +Mi mebi 2^20 = 1048576 +Gi gibi 2^30 = 1073741824 +Ti tebi 2^40 = 1099511627776 +Pi pebi 2^50 = 1125899906842624 +Ei exbi 2^60 = 1152921504606846976 +.TE +.RE + +See also +.sp +.RS +http://physics.nist.gov/cuu/Units/binary.html +.RE +.SS Discussion +Before these binary prefixes were introduced, it was fairly +common to use k=1000 and K=1024, just like b=bit, B=byte. +Unfortunately, the M is capital already, and cannot be +capitalized to indicate binary-ness. + +At first that didn't matter too much, since memory modules +and disks came in sizes that were powers of two, so everyone +knew that in such contexts "kilobyte" and "megabyte" meant +1024 and 1048576 bytes, respectively. What originally was a +sloppy use of the prefixes "kilo" and "mega" started to become +regarded as the "real true meaning" when computers were involved. +But then disk technology changed, and disk sizes became arbitrary numbers. +After a period of uncertainty all disk manufacturers settled on the +standard, namely k=1000, M=1000k, G=1000M. + +The situation was messy: in the 14k4 modems, k=1000; in the 1.44MB +.\" also common: 14.4k modem +diskettes, M=1024000; etc. In 1998 the IEC approved the standard +that defines the binary prefixes given above, enabling people +to be precise and unambiguous. + +Thus, today, MB = 1000000B and MiB = 1048576B. + +In the free software world programs are slowly +being changed to conform. When the Linux kernel boots and says + +.RS +.nf +hda: 120064896 sectors (61473 MB) w/2048KiB Cache +.fi +.RE + +the MB are megabytes and the KiB are kibibytes. diff --git a/man7/unix.7 b/man7/unix.7 new file mode 100644 index 000000000..a3cc7fbda --- /dev/null +++ b/man7/unix.7 @@ -0,0 +1,261 @@ +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" +.\" Modified, 2003-12-02, Michael Kerrisk, mtk16@ext.canterbury.ac.nz +.\" Modified, 2003-09-23, Adam Langley +.\" Modified, 2004-05-27, Michael Kerrisk, mtk16@ext.canterbury.ac.nz +.\" Added SOCK_SEQPACKET +.\" +.TH UNIX 7 2004-05-27 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +unix, PF_UNIX, AF_UNIX, PF_LOCAL, AF_LOCAL \- Sockets for local interprocess communication +.SH SYNOPSIS +.B #include +.br +.B #include + +.IB unix_socket " = socket(PF_UNIX, type, 0);" +.br +.IB error " = socketpair(PF_UNIX, type, 0, int *" sv ");" + +.SH DESCRIPTION +The +.B PF_UNIX +(also known as +.BR PF_LOCAL ) +socket family is used to communicate between processes on the same machine +efficiently. Unix sockets can be either anonymous (created by +.BR socketpair (2)) +or associated with a file of type socket. +Linux also supports an abstract namespace which is independent of the +file system. + +Valid types are: +.BR SOCK_STREAM , +for a stream-oriented socket and +.BR SOCK_DGRAM , +for a datagram-oriented socket that preserves message boundaries +(as on most Unix implementations, Unix domain datagram +sockets are always reliable and don't reorder datagrams); +and (since kernel 2.6.4) +.BR SOCK_SEQPACKET , +for a connection-oriented socket that preserves message boundaries +and delivers messages in the order that they were sent. + +Unix sockets support passing file descriptors or process credentials to other +processes using ancillary data. + +.SH "ADDRESS FORMAT" +A Unix address is defined as a filename in the filesystem or +as a unique string in the abstract namespace. Sockets created by +.BR socketpair (2) +are anonymous. For non-anonymous sockets the target address can be set +using +.BR connect (2). +The local address can be set using +.BR bind (2). +When a socket is connected and it doesn't already have a local address a +unique address in the abstract namespace will be generated automatically. + +.RS +.nf +#define UNIX_PATH_MAX 108 + +.ta 4n 17n 42n +struct sockaddr_un { + sa_family_t sun_family; /* AF_UNIX */ + char sun_path[UNIX_PATH_MAX]; /* pathname */ +}; +.fi +.RE + +.B sun_family +always contains +.BR AF_UNIX . +.B sun_path +contains the zero-terminated pathname of the socket in the file system. +If +.B sun_path +starts with a zero byte it refers to the abstract namespace maintained by +the Unix protocol module. +The socket's address in this namespace is given by the rest of the bytes in +.BR sun_path . +Note that names in the abstract namespace are not zero-terminated. + +.SH "SOCKET OPTIONS" +For historical reasons these socket options are specified with a +SOL_SOCKET type even though they are PF_UNIX specific. +They can be set with +.BR setsockopt (2) +and read with +.BR getsockopt (2) +by specifying SOL_SOCKET as the socket family. +.TP +.B SO_PASSCRED +Enables the receiving of the credentials of the sending process +ancillary message. When this option is set and the socket is not yet connected +a unique name in the abstract namespace will be generated automatically. +Expects an integer boolean flag. + +.SH "ANCILLARY MESSAGES" +Ancillary data is sent and received using +.BR sendmsg (2) +and +.BR recvmsg (2). +For historical reasons the ancillary message types listed below +are specified with a SOL_SOCKET type even though they are PF_UNIX specific. +To send them set the +.B cmsg_level +field of the struct +.B cmsghdr +to SOL_SOCKET and the +.B cmsg_type +field to the type. For more information see +.BR cmsg (3). + +.TP +.B SCM_RIGHTS +Send or receive a set of open file descriptors from another process. +The data portion contains an integer array of the file descriptors. +The passed file descriptors behave as though they have been created with +.BR dup (2). + +.TP +.B SCM_CREDENTIALS +Send or receive Unix credentials. This can be used for authentication. +The credentials are passed as a +.B struct ucred +ancillary message. + +.RS +.nf +.ta 4n 11n 17n +struct ucred { + pid_t pid; /* process id of the sending process */ + uid_t uid; /* user id of the sending process */ + gid_t gid; /* group id of the sending process */ +}; +.fi +.RE + +The credentials which the sender specifies are checked by the kernel. +A process with effective user ID 0 is allowed to specify values that do +not match its own. +The sender must specify its own process ID (unless it has the capability +.BR CAP_SYS_ADMIN ), +its user ID, effective user ID or set user ID (unless it has +.BR CAP_SETUID ), +and its group id, effective group ID or set group ID (unless it has +.BR CAP_SETGID ). +To receive a +.B struct ucred +message the +.B SO_PASSCRED +option must be enabled on the socket. + +.SH VERSIONS +.B SCM_CREDENTIALS +and the abstract namespace were introduced with Linux 2.2 and should not +be used in portable programs. +(Some BSD-derived systems also support credential passing, +but the implementation details differ.) + +.SH NOTES +In the Linux implementation, sockets which are visible in the +filesystem honour the permissions of the directory they are in. Their +owner, group and their permissions can be changed. +Creation of a new socket will fail if the process does not have write and +search (execute) permission on the directory the socket is created in. +Connecting to the socket object requires read/write permission. +This behavior differs from many BSD-derived systems which +ignore permissions for Unix sockets. Portable programs should not rely on +this feature for security. + +Binding to a socket with a filename creates a socket +in the file system that must be deleted by the caller when it is no +longer needed (using +.BR unlink (2)). +The usual Unix close-behind semantics apply; the socket can be unlinked +at any time and will be finally removed from the file system when the last +reference to it is closed. + +To pass file descriptors or credentials over a SOCK_STREAM, you need +to send/recv at least one byte of non-ancillary data in the same +send/recv_msg call. + +Unix domain stream sockets do not support the notion of out-of-band data. +.SH ERRORS +.TP +.B ENOMEM +Out of memory. +.TP +.B ECONNREFUSED +.BR connect (2) +called with a socket object that isn't listening. This can happen when +the remote socket does not exist or the filename is not a socket. +.TP +.B EINVAL +Invalid argument passed. A common cause is the missing setting of AF_UNIX +in the sun_type field of passed addresses or the socket being in an invalid +state for the applied operation. +.TP +.B EOPNOTSUPP +Stream operation called on non-stream oriented socket or tried to +use the out-of-band data option. +.TP +.B EPROTONOSUPPORT +Passed protocol is not PF_UNIX. +.TP +.B ESOCKTNOSUPPORT +Unknown socket type. +.TP +.B EPROTOTYPE +Remote socket does not match the local socket type (SOCK_DGRAM vs. +SOCK_STREAM) +.TP +.B EADDRINUSE +Selected local address is already taken or filesystem socket object already +exists. +.TP +.B EISCONN +.BR connect (2) +called on an already connected socket or a target address was +specified on a connected socket. +.TP +.B ENOTCONN +Socket operation needs a target address, but the socket is not connected. +.TP +.B ECONNRESET +Remote socket was unexpectedly closed. +.TP +.B EPIPE +Remote socket was closed on a stream socket. If enabled, a +.B SIGPIPE +is sent as well. This can be avoided by passing the +.B MSG_NOSIGNAL +flag to +.BR sendmsg (2) +or +.BR recvmsg (2). +.TP +.B EFAULT +User memory address was not valid. +.TP +.B EPERM +The sender passed invalid credentials in the +.BR "struct ucred" . +.PP +Other errors can be generated by the generic socket layer or +by the filesystem while generating a filesystem socket object. See +the appropriate manual pages for more information. +.SH "SEE ALSO" +.BR recvmsg (2), +.BR sendmsg (2), +.BR socket (2), +.BR socketpair (2), +.BR cmsg (3), +.BR capabilities (7), +.BR socket (7) diff --git a/man7/uri.7 b/man7/uri.7 new file mode 100644 index 000000000..755268452 --- /dev/null +++ b/man7/uri.7 @@ -0,0 +1,660 @@ +'\" +.\" (C) Copyright 1999-2000 David A. Wheeler (dwheeler@dwheeler.com) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Fragments of this document are directly derived from IETF standards. +.\" For those fragments which are directly derived from such standards, +.\" the following notice applies, which is the standard copyright and +.\" rights announcement of The Internet Society: +.\" +.\" Copyright (C) The Internet Society (1998). All Rights Reserved. +.\" This document and translations of it may be copied and furnished to +.\" others, and derivative works that comment on or otherwise explain it +.\" or assist in its implementation may be prepared, copied, published +.\" and distributed, in whole or in part, without restriction of any +.\" kind, provided that the above copyright notice and this paragraph are +.\" included on all such copies and derivative works. However, this +.\" document itself may not be modified in any way, such as by removing +.\" the copyright notice or references to the Internet Society or other +.\" Internet organizations, except as needed for the purpose of +.\" developing Internet standards in which case the procedures for +.\" copyrights defined in the Internet Standards process must be +.\" followed, or as required to translate it into languages other than English. +.\" +.\" Modified Fri Jul 25 23:00:00 1999 by David A. Wheeler (dwheeler@dwheeler.com) +.\" Modified Fri Aug 21 23:00:00 1999 by David A. Wheeler (dwheeler@dwheeler.com) +.\" Modified Tue Mar 14 2000 by David A. Wheeler (dwheeler@dwheeler.com) +.\" +.TH URI 7 2000-03-14 "Linux" "Linux Programmer's Manual" +.SH NAME +uri, url, urn \- uniform resource identifier (URI), including a URL or URN +.SH SYNOPSIS +.nf +.HP 0.2i +URI = [ absoluteURI | relativeURI ] [ "#" fragment ] +.HP +absoluteURI = scheme ":" ( hierarchical_part | opaque_part ) +.HP +relativeURI = ( net_path | absolute_path | relative_path ) [ "?" query ] +.sp +.HP +scheme = "http" | "ftp" | "gopher" | "mailto" | "news" | "telnet" | "file" | "man" | "info" | "whatis" | "ldap" | "wais" | \&... +.HP +hierarchical_part = ( net_path | absolute_path ) [ "?" query ] +.sp +.HP +net_path = "//" authority [ absolute_path ] +.HP +absolute_path = "/" path_segments +.HP +relative_path = relative_segment [ absolute_path ] +.fi +.SH DESCRIPTION +.PP +A Uniform Resource Identifier (URI) is a short string of characters +identifying an abstract or physical resource (for example, a web page). +A Uniform Resource Locator (URL) is a URI +that identifies a resource through its primary access +mechanism (e.g., its network "location"), rather than +by name or some other attribute of that resource. +A Uniform Resource Name (URN) is a URI +that must remain globally unique and persistent even when +the resource ceases to exist or becomes unavailable. +.PP +URIs are the standard way to name hypertext link destinations +for tools such as web browsers. +The string "http://www.kernelnotes.org" is a URL (and thus it's a URI). +Many people use the term URL loosely as a synonym for URI +(though technically URLs are a subset of URIs). +.PP +URIs can be absolute or relative. +An absolute identifier refers to a resource independent of +context, while a relative +identifier refers to a resource by describing the difference +from the current context. +Within a relative path reference, the complete path segments "." and +".." have special meanings: "the current hierarchy level" and "the +level above this hierarchy level", respectively, just like they do in +Unix-like systems. +A path segment which contains a colon +character can't be used as the first segment of a relative URI path +(e.g., "this:that"), because it would be mistaken for a scheme name; +precede such segments with ./ (e.g., "./this:that"). +Note that descendents of MS-DOS (e.g., Microsoft Windows) replace +devicename colons with the vertical bar ("|") in URIs, so "C:" becomes "C|". +.PP +A fragment identifier, if included, refers to a particular named portion +(fragment) of a resource; text after a '#' identifies the fragment. +A URI beginning with '#' refers to that fragment in the current resource. +.SH USAGE +There are many different URI schemes, each with specific +additional rules and meanings, but they are intentionally made to be +as similar as possible. +For example, many URL schemes +permit the authority to be the following format, called here an +.I ip_server +(square brackets show what's optional): +.HP +.IR "ip_server = " [ user " [ : " password " ] @ ] " host " [ : " port ] +.PP +This format allows you to optionally insert a user name, +a user plus password, and/or a port number. +The +.I host +is the name of the host computer, either its name as determined by DNS +or an IP address (numbers separated by periods). +Thus the URI + +logs into a web server on host xyz.com +as fred (using fredpassword) using port 8080. +Avoid including a password in a URI if possible because of the many +security risks of having a password written down. +If the URL supplies a user name but no password, and the remote +server requests a password, the program interpreting the URL +should request one from the user. +.PP +Here are some of the most common schemes in use on Unix-like systems +that are understood by many tools. +Note that many tools using URIs also have internal schemes or specialized +schemes; see those tools' documentation for information on those schemes. +.SS "http - Web (HTTP) server" +.RI http:// ip_server / path +.br +.RI http:// ip_server / path ? query +.PP +This is a URL accessing a web (HTTP) server. +The default port is 80. +If the path refers to a directory, the web server will choose what +to return; usually if there is a file named "index.html" or "index.htm" +its content is returned, otherwise, a list of the files in the current +directory (with appropriate links) is generated and returned. +An example is . +.PP +A query can be given in the archaic "isindex" format, consisting of a +word or phrase and not including an equal sign (=). +A query can also be in the longer "GET" format, which has one or more +query entries of the form +.IR key = value +separated by the ampersand character (&). +Note that +.I key +can be repeated more than once, though it's up to the web server +and its application programs to determine if there's any meaning to that. +There is an unfortunate interaction with HTML/XML/SGML and +the GET query format; when such URIs with more than one key +are embedded in SGML/XML documents (including HTML), the ampersand +(&) has to be rewritten as &. +Note that not all queries use this format; larger forms +may be too long to store as a URI, so they use a different +interaction mechanism (called POST) which does not include the data in the URI. +See the Common Gateway Interface specification at + for more information. +.SS "ftp - File Transfer Protocol (FTP)" +.RI ftp:// ip_server / path +.PP +This is a URL accessing a file through the file transfer protocol (FTP). +The default port (for control) is 21. +If no username is included, the user name "anonymous" is supplied, and +in that case many clients provide as the password the requestor's +Internet email address. +An example is +. +.SS "gopher - Gopher server" +.RI gopher:// ip_server / "gophertype selector" +.br +.RI gopher:// ip_server / "gophertype selector" %09 search +.br +.RI gopher:// ip_server / "gophertype selector" %09 search %09 gopher+_string +.br +.PP +The default gopher port is 70. +.I gophertype +is a single-character field to denote the +Gopher type of the resource to +which the URL refers. +The entire path may also be empty, in +which case the delimiting "/" is also optional and the gophertype +defaults to "1". +.PP +.I selector +is the Gopher selector string. In the Gopher protocol, +Gopher selector strings are a sequence of octets which may contain +any octets except 09 hexadecimal (US-ASCII HT or tab), 0A hexadecimal +(US-ASCII character LF), and 0D (US-ASCII character CR). +.SS "mailto - Email address" +.RI mailto: email-address +.PP +This is an email address, usually of the form +.IR name @ hostname . +See +.BR mailaddr (7) +for more information on the correct format of an email address. +Note that any % character must be rewritten as %25. +An example is . +.SS "news - Newsgroup or News message" +.RI news: newsgroup-name +.br +.RI news: message-id +.PP +A +.I newsgroup-name +is a period-delimited hierarchical name, such as +"comp.infosystems.www.misc". +If is "*" (as in ), it is used to refer +to "all available news groups". +An example is . +.PP +A +.I message-id +corresponds to the Message-ID of +.UR http://www.ietf.org/rfc/rfc1036.txt +IETF RFC 1036, +.UE +without the enclosing "<" +and ">"; it takes the form +.IR unique @ full_domain_name . +A message identifier may be distinguished from a news group name by the +presence of the "@" character. +.SS "telnet - Telnet login" +.RI telnet:// ip_server / +.PP +The Telnet URL scheme is used to designate interactive text services that +may be accessed by the Telnet protocol. The final "/" character may be omitted. +The default port is 23. +An example is . +.SS "file - Normal file" +.RI file:// ip_server / path_segments +.br +.RI file: path_segments +.PP +This represents a file or directory accessible locally. +As a special case, +.I host +can be the string "localhost" or the empty +string; this is interpreted as `the machine from which the URL is +being interpreted'. +If the path is to a directory, the viewer should display the +directory's contents with links to each containee; +not all viewers currently do this. +KDE supports generated files through the URL . +If the given file isn't found, browser writers may want to try to expand +the filename via filename globbing +(see +.BR glob (7) +and +.BR glob (3)). +.PP +The second format (e.g., ) +is a correct format for referring to +a local file. However, older standards did not permit this format, +and some programs don't recognize this as a URI. +A more portable syntax is to use an empty string as the server name, e.g., +; this form does the same thing +and is easily recognized by pattern matchers and older programs as a URI. +Note that if you really mean to say "start from the current location," don't +specify the scheme at all; use a relative address like <../test.txt>, +which has the side-effect of being scheme-independent. +An example of this scheme is . +.SS "man - Man page documentation" +.RI man: command-name +.br +.RI man: command-name ( section ) +.PP +This refers to local online manual (man) reference pages. +The command name can optionally be followed by a parenthesis and section number; +see +.BR man (7) +for more information on the meaning of the section numbers. +This URI scheme is unique to Unix-like systems (such as Linux) +and is not currently registered by the IETF. +An example is . +.SS "info - Info page documentation" +.RI info: virtual-filename +.br +.RI info: virtual-filename # nodename +.br +.RI info:( virtual-filename ) +.br +.RI info:( virtual-filename ) nodename +.PP +This scheme refers to online info reference pages (generated from +texinfo files), a documentation format used by programs such as the GNU tools. +This URI scheme is unique to Unix-like systems (such as Linux) +and is not currently registered by the IETF. +As of this writing, GNOME and KDE differ in their URI syntax +and do not accept the other's syntax. +The first two formats are the GNOME format; in nodenames all spaces +are written as underscores. +The second two formats are the KDE format; +spaces in nodenames must be written as spaces, even though this +is forbidden by the URI standards. +It's hoped that in the future most tools will understand all of these +formats and will always accept underscores for spaces in nodenames. +In both GNOME and KDE, if the form without the nodename is used the +nodename is assumed to be "Top". +Examples of the GNOME format are and . +Examples of the KDE format are and . +.SS "whatis - Documentation search" +.RI whatis: string +.PP +This scheme searches the database of short (one-line) descriptions of commands +and returns a list of descriptions containing that string. +Only complete word matches are returned. +See +.BR whatis (1). +This URI scheme is unique to Unix-like systems (such as Linux) +and is not currently registered by the IETF. +.SS "ghelp - GNOME help documentation" +.RI ghelp: name-of-application +.PP +This loads GNOME help for the given application. +Note that not much documentation currently exists in this format. +.SS "ldap - Lightweight Directory Access Protocol" +.RI ldap:// hostport +.br +.RI ldap:// hostport / +.br +.RI ldap:// hostport / dn +.br +.RI ldap:// hostport / dn ? attributes +.br +.RI ldap:// hostport / dn ? attributes ? scope +.br +.RI ldap:// hostport / dn ? attributes ? scope ? filter +.br +.RI ldap:// hostport / dn ? attributes ? scope ? filter ? extensions +.PP +This scheme supports queries to the +Lightweight Directory Access Protocol (LDAP), a protocol for querying +a set of servers for hierarchically-organized information +(such as people and computing resources). +More information on the LDAP URL scheme is available in +.UR http://www.ietf.org/rfc/rfc2255.txt +RFC 2255. +.UE +The components of this URL are: +.IP hostport 12 +the LDAP server to query, written as a hostname optionally followed by +a colon and the port number. +The default LDAP port is TCP port 389. +If empty, the client determines which the LDAP server to use. +.IP dn +the LDAP Distinguished Name, which identifies +the base object of the LDAP search (see +.UR http://www.ietf.org/rfc/rfc2253.txt +RFC 2253 +.UE +section 3). +.IP attributes +a comma-separated list of attributes to be returned; +see RFC 2251 section 4.1.5. If omitted, all attributes should be returned. +.IP scope +specifies the scope of the search, which can be one of +"base" (for a base object search), "one" (for a one-level search), +or "sub" (for a subtree search). If scope is omitted, "base" is assumed. +.IP filter +specifies the search filter (subset of entries +to return). If omitted, all entries should be returned. +See +.UR http://www.ietf.org/rfc/rfc2254.txt +RFC 2254 +.UE +section 4. +.IP extensions +a comma-separated list of type=value +pairs, where the =value portion may be omitted for options not +requiring it. An extension prefixed with a '!' is critical +(must be supported to be valid), otherwise it's non-critical (optional). +.PP +LDAP queries are easiest to explain by example. +Here's a query that asks ldap.itd.umich.edu for information about +the University of Michigan in the U.S.: +.RS +ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US +.RE +.PP +To just get its postal address attribute, request: +.RS +ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress +.RE +.PP +To ask a host.com at port 6666 for information about the person +with common name (cn) "Babs Jensen" at University of Michigan, request: +.RS +ldap://host.com:6666/o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen) +.RE +.SS "wais - Wide Area Information Servers" +.RI wais:// hostport / database +.br +.RI wais:// hostport / database ? search +.br +.RI wais:// hostport / database / wtype / wpath +.PP +This scheme designates a WAIS database, search, or document +(see +.UR http://www.ietf.org/rfc/rfc1625.txt +IETF RFC 1625 +.UE +for more information on WAIS). +Hostport is the hostname, optionally followed by a colon and port number +(the default port number is 210). +.PP +The first form designates a WAIS database for searching. +The second form designates a particular search of the WAIS database +.IR database . +The third form designates a particular document within a WAIS +database to be retrieved. +.I wtype +is the WAIS designation of the type of the object and +.I wpath +is the WAIS document-id. +.SS "other schemes" +There are many other URI schemes. +Most tools that accept URIs support a set of internal URIs +(e.g., Mozilla has the about: scheme for internal information, +and the GNOME help browser has the toc: scheme for various starting +locations). +There are many schemes that have been defined but are not as widely +used at the current time +(e.g., prospero). +The nntp: scheme is deprecated in favor of the news: scheme. +URNs are to be supported by the urn: scheme, with a hierarchical name space +(e.g., urn:ietf:... would identify IETF documents); at this time +URNs are not widely implemented. +Not all tools support all schemes. +.SH "CHARACTER ENCODING" +.PP +URIs use a limited number of characters so that they can be +typed in and used in a variety of situations. +.PP +The following characters are reserved, that is, they may appear in a +URI but their use is limited to their reserved purpose +(conflicting data must be escaped before forming the URI): +.IP + ; / ? : @ & = + $ , +.PP +Unreserved characters may be included in a URI. +Unreserved characters +include include upper and lower case English letters, +decimal digits, and the following +limited set of punctuation marks and symbols: +.IP + - _ . ! ~ * ' ( ) +.PP +All other characters must be escaped. +An escaped octet is encoded as a character triplet, consisting of the +percent character "%" followed by the two hexadecimal digits +representing the octet code (you can use upper or lower case letters +for the hexadecimal digits). For example, a blank space must be escaped +as "%20", a tab character as "%09", and the "&" as "%26". +Because the percent "%" character always has the reserved purpose of +being the escape indicator, it must be escaped as "%25". +It is common practice to escape space characters as the plus symbol (+) +in query text; this practice isn't uniformly defined +in the relevant RFCs (which recommend %20 instead) but any tool accepting +URIs with query text should be prepared for them. +A URI is always shown in its "escaped" form. +.PP +Unreserved characters can be escaped without changing the semantics +of the URI, but this should not be done unless the URI is being used +in a context that does not allow the unescaped character to appear. +For example, "%7e" is sometimes used instead of "~" in an http URL +path, but the two are equivalent for an http URL. +.PP +For URIs which must handle characters outside the US ASCII character set, +the HTML 4.01 specification (section B.2) and +IETF RFC 2718 (section 2.2.5) recommend the following approach: +.IP 1. 4 +translate the character sequences into UTF-8 (IETF RFC 2279) - see +.BR utf-8 (7) +- and then +.IP 2. +use the URI escaping mechanism, that is, +use the %HH encoding for unsafe octets. +.SH "WRITING A URI" +When written, URIs should be placed inside doublequotes +(e.g., "http://www.kernelnotes.org"), +enclosed in angle brackets (e.g., ), +or placed on a line by themselves. +A warning for those who use double-quotes: +.B never +move extraneous punctuation (such as the period ending a sentence or the +comma in a list) +inside a URI, since this will change the value of the URI. +Instead, use angle brackets instead, or +switch to a quoting system that never includes extraneous characters +inside quotation marks. +This latter system, called the 'new' or 'logical' quoting system by +"Hart's Rules" and the "Oxford Dictionary for Writers and Editors", +is preferred practice in Great Britain and hackers worldwide +(see the +.UR http://www.fwi.uva.nl/~mes/jargon/h/HackerWritingStyle.html +Jargon File's section on Hacker Writing Style +.UE +for more information). +Older documents suggested inserting the prefix "URL:" +just before the URI, but this form has never caught on. +.PP +The URI syntax was designed to be unambiguous. +However, as URIs have become commonplace, traditional media +(television, radio, newspapers, billboards, etc.) have increasingly +used abbreviated URI references consisting of +only the authority and path portions of the identified resource +(e.g., ). +Such references are primarily +intended for human interpretation rather than machine, with the +assumption that context-based heuristics are sufficient to complete +the URI (e.g., hostnames beginning with "www" are likely to have +a URI prefix of "http://" and hostnames beginning with "ftp" likely +to have a prefix of "ftp://"). +Many client implementations heuristically resolve these references. +Such heuristics may +change over time, particularly when new schemes are introduced. +Since an abbreviated URI has the same syntax as a relative URL path, +abbreviated URI references cannot be used where relative URIs are +permitted, and can only be used when there is no defined base +(such as in dialog boxes). +Don't use abbreviated URIs as hypertext links inside a document; +use the standard format as described here. +.SH NOTES +Any tool accepting URIs (e.g., a web browser) on a Linux system should +be able to handle (directly or indirectly) all of the schemes described here, +including the man: and info: schemes. +Handling them by invoking some other program is fine and in fact encouraged. +.PP +Technically the fragment isn't part of the URI. +.PP +For information on how to embed URIs (including URLs) in a data format, +see documentation on that format. +HTML uses the format +.I text +. +Texinfo files use the format @uref{\fIuri\fP}. +Man and mdoc have the recently-added UR macro, or just include the +URI in the text (viewers should be able to detect :// as part of a URI). +.PP +The GNOME and KDE desktop environments currently vary in the URIs they accept, +in particular in their respective help browsers. +To list man pages, GNOME uses while KDE uses , and +to list info pages, GNOME uses while KDE uses +(the author of this man page prefers the KDE approach here, though a more +regular format would be even better). +In general, KDE uses as a prefix to a set of generated +files. +KDE prefers documentation in HTML, accessed via the +. +GNOME prefers the ghelp scheme to store and find documentation. +Neither browser handles file: references to directories at the time +of this writing, making it difficult to refer to an entire directory with +a browsable URI. +As noted above, these environments differ in how they handle the info: scheme, +probably the most important variation. +It is expected that GNOME and KDE +will converge to common URI formats, and a future +version of this man page will describe the converged result. +Efforts to aid this convergence are encouraged. +.SH SECURITY +.PP +A URI does not in itself pose a security threat. +There is no general guarantee that a URL, which at one time +located a given resource, will continue to do so. Nor is there any +guarantee that a URL will not locate a different resource at some +later point in time; such a guarantee can only be +obtained from the person(s) controlling that namespace and the +resource in question. +.PP +It is sometimes possible to construct a URL such that an attempt to +perform a seemingly harmless operation, such as the +retrieval of an entity associated with the resource, will in fact +cause a possibly damaging remote operation to occur. The unsafe URL +is typically constructed by specifying a port number other than that +reserved for the network protocol in question. The client +unwittingly contacts a site that is in fact running a different +protocol. The content of the URL contains instructions that, when +interpreted according to this other protocol, cause an unexpected +operation. An example has been the use of a gopher URL to cause an +unintended or impersonating message to be sent via a SMTP server. +.PP +Caution should be used when using any URL that specifies a port +number other than the default for the protocol, especially when it is +a number within the reserved space. +.PP +Care should be taken when a URI contains escaped delimiters for a +given protocol (for example, CR and LF characters for telnet +protocols) that these are not unescaped before transmission. This +might violate the protocol, but avoids the potential for such +characters to be used to simulate an extra operation or parameter in +that protocol, which might lead to an unexpected and possibly harmful +remote operation to be performed. +.PP +It is clearly unwise to use a URI that contains a password which is +intended to be secret. In particular, the use of a password within +the 'userinfo' component of a URI is strongly disrecommended except +in those rare cases where the 'password' parameter is intended to be public. +.SH "CONFORMING TO" +.PP +.UR http://www.ietf.org/rfc/rfc2396.txt +IETF RFC 2396, +.UE +.UR http://www.w3.org/TR/REC-html40 +HTML 4.0. +.UE +.SH BUGS +.PP +Documentation may be placed in a variety of locations, so there +currently isn't a good URI scheme for general online documentation +in arbitrary formats. +References of the form + don't work because different distributions and +local installation requirements may place the files in different +directories +(it may be in /usr/doc, or /usr/local/doc, or /usr/share, or somewhere else). +Also, the directory ZZZ usually changes when a version changes +(though filename globbing could partially overcome this). +Finally, using the file: scheme doesn't easily support people who dynamically +load documentation from the Internet (instead of loading the files +onto a local filesystem). +A future URI scheme may be added (e.g., "userdoc:") to permit +programs to include cross-references to more detailed documentation without +having to know the exact location of that documentation. +Alternatively, a future version of the filesystem specification may +specify file locations sufficiently so that the file: scheme will +be able to locate documentation. +.PP +Many programs and file formats don't include a way to incorporate +or implement links using URIs. +.PP +Many programs can't handle all of these different URI formats; there +should be a standard mechanism to load an arbitrary URI that automatically +detects the users' environment (e.g., text or graphics, desktop environment, +local user preferences, and currently-executing tools) and invokes the +right tool for any URI. +.SH AUTHOR +David A. Wheeler (dwheeler@dwheeler.com) wrote this man page. +.SH "SEE ALSO" +.BR lynx (1), +.BR man2html (1), +.BR mailaddr (7), +.BR utf-8 (7) +.UR http://www.ietf.org/rfc/rfc2255.txt +IETF RFC 2255. +.UE diff --git a/man7/url.7 b/man7/url.7 new file mode 100644 index 000000000..079fb5e7b --- /dev/null +++ b/man7/url.7 @@ -0,0 +1 @@ +.so man7/uri.7 diff --git a/man7/utf-8.7 b/man7/utf-8.7 new file mode 100644 index 000000000..e364c2e05 --- /dev/null +++ b/man7/utf-8.7 @@ -0,0 +1,285 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) Markus Kuhn, 1996, 2001 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" 1995-11-26 Markus Kuhn +.\" First version written +.\" 2001-05-11 Markus Kuhn +.\" Update +.\" +.TH UTF-8 7 2001-05-11 "GNU" "Linux Programmer's Manual" +.SH NAME +UTF-8 \- an ASCII compatible multi-byte Unicode encoding +.SH DESCRIPTION +The +.B Unicode 3.0 +character set occupies a 16-bit code space. The most obvious +Unicode encoding (known as +.BR UCS-2 ) +consists of a sequence of 16-bit words. Such strings can contain as +parts of many 16-bit characters bytes like '\\0' or '/' which have a +special meaning in filenames and other C library function parameters. +In addition, the majority of UNIX tools expects ASCII files and can't +read 16-bit words as characters without major modifications. For these +reasons, +.B UCS-2 +is not a suitable external encoding of +.B Unicode +in filenames, text files, environment variables, etc. The +.BR "ISO 10646 Universal Character Set (UCS)" , +a superset of Unicode, occupies even a 31-bit code space and the obvious +.B UCS-4 +encoding for it (a sequence of 32-bit words) has the same problems. + +The +.B UTF-8 +encoding of +.B Unicode +and +.B UCS +does not have these problems and is the common way in which +.B Unicode +is used on Unix-style operating systems. +.SH PROPERTIES +The +.B UTF-8 +encoding has the following nice properties: +.TP 0.2i +* +.B UCS +characters 0x00000000 to 0x0000007f (the classic +.B US-ASCII +characters) are encoded simply as bytes 0x00 to 0x7f (ASCII +compatibility). This means that files and strings which contain only +7-bit ASCII characters have the same encoding under both +.B ASCII +and +.BR UTF-8 . +.TP +* +All +.B UCS +characters > 0x7f are encoded as a multi-byte sequence +consisting only of bytes in the range 0x80 to 0xfd, so no ASCII +byte can appear as part of another character and there are no +problems with e.g. '\\0' or '/'. +.TP +* +The lexicographic sorting order of +.B UCS-4 +strings is preserved. +.TP +* +All possible 2^31 UCS codes can be encoded using +.BR UTF-8 . +.TP +* +The bytes 0xfe and 0xff are never used in the +.B UTF-8 +encoding. +.TP +* +The first byte of a multi-byte sequence which represents a single non-ASCII +.B UCS +character is always in the range 0xc0 to 0xfd and indicates how long +this multi-byte sequence is. All further bytes in a multi-byte sequence +are in the range 0x80 to 0xbf. This allows easy resynchronization and +makes the encoding stateless and robust against missing bytes. +.TP +* +.B UTF-8 +encoded +.B UCS +characters may be up to six bytes long, however the +.B Unicode +standard specifies no characters above 0x10ffff, so Unicode characters +can only be up to four bytes long in +.BR UTF-8 . +.SH ENCODING +The following byte sequences are used to represent a character. The +sequence to be used depends on the UCS code number of the character: +.TP 0.4i +0x00000000 - 0x0000007F: +.RI 0 xxxxxxx +.TP +0x00000080 - 0x000007FF: +.RI 110 xxxxx +.RI 10 xxxxxx +.TP +0x00000800 - 0x0000FFFF: +.RI 1110 xxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.TP +0x00010000 - 0x001FFFFF: +.RI 11110 xxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.TP +0x00200000 - 0x03FFFFFF: +.RI 111110 xx +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.TP +0x04000000 - 0x7FFFFFFF: +.RI 1111110 x +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.PP +The +.I xxx +bit positions are filled with the bits of the character code number in +binary representation. Only the shortest possible multi-byte sequence +which can represent the code number of the character can be used. +.PP +The +.B UCS +code values 0xd800\(en0xdfff (UTF-16 surrogates) as well as 0xfffe and +0xffff (UCS non-characters) should not appear in conforming +.B UTF-8 +streams. +.SH EXAMPLES +The +.B Unicode +character 0xa9 = 1010 1001 (the copyright sign) is encoded +in UTF-8 as +.PP +.RS +11000010 10101001 = 0xc2 0xa9 +.RE +.PP +and character 0x2260 = 0010 0010 0110 0000 (the "not equal" symbol) is +encoded as: +.PP +.RS +11100010 10001001 10100000 = 0xe2 0x89 0xa0 +.RE +.SH "APPLICATION NOTES" +Users have to select a +.B UTF-8 +locale, for example with +.PP +.RS +export LANG=en_GB.UTF-8 +.RE +.PP +in order to activate the +.B UTF-8 +support in applications. +.PP +Application software that has to be aware of the used character +encoding should always set the locale with for example +.PP +.RS +setlocale(LC_CTYPE, "") +.RE +.PP +and programmers can then test the expression +.PP +.RS +strcmp(nl_langinfo(CODESET), "UTF-8") == 0 +.RE +.PP +to determine whether a +.B UTF-8 +locale has been selected and whether +therefore all plaintext standard input and output, terminal +communication, plaintext file content, filenames and environment +variables are encoded in +.BR UTF-8 . +.PP +Programmers accustomed to single-byte encodings such as +.B US-ASCII +or +.B ISO 8859 +have to be aware that two assumptions made so far are no longer valid +in +.B UTF-8 +locales. Firstly, a single byte does not necessarily correspond any +more to a single character. Secondly, since modern terminal emulators +in +.B UTF-8 +mode also support Chinese, Japanese, and Korean +.B double-width characters +as well as non-spacing +.BR "combining characters" , +outputting a single character does not necessarily advance the cursor +by one position as it did in +.BR ASCII . +Library functions such as +.BR mbsrtowcs (3) +and +.BR wcswidth (3) +should be used today to count characters and cursor positions. +.PP +The official ESC sequence to switch from an +.B ISO 2022 +encoding scheme (as used for instance by VT100 terminals) to +.B UTF-8 +is ESC % G +("\\x1b%G"). The corresponding return sequence from +.B UTF-8 +to ISO 2022 is ESC % @ ("\\x1b%@"). Other ISO 2022 sequences (such as +for switching the G0 and G1 sets) are not applicable in UTF-8 mode. +.PP +It can be hoped that in the foreseeable future, +.B UTF-8 +will replace +.B ASCII +and +.B ISO 8859 +at all levels as the common character encoding on POSIX systems, +leading to a significantly richer environment for handling plain text. +.SH SECURITY +The +.BR Unicode " and " UCS +standards require that producers of +.B UTF-8 +shall use the shortest form possible, e.g., producing a two-byte +sequence with first byte 0xc0 is non-conforming. +.B Unicode 3.1 +has added the requirement that conforming programs must not accept +non-shortest forms in their input. This is for security reasons: if +user input is checked for possible security violations, a program +might check only for the +.B ASCII +version of "/../" or ";" or NUL and overlook that there are many +.RB non- ASCII +ways to represent these things in a non-shortest +.B UTF-8 +encoding. +.SH STANDARDS +ISO/IEC 10646-1:2000, Unicode 3.1, RFC 2279, Plan 9. +.SH AUTHOR +Markus Kuhn +.SH "SEE ALSO" +.BR nl_langinfo (3), +.BR setlocale (3), +.BR charsets (7), +.BR unicode (7) diff --git a/man7/utf8.7 b/man7/utf8.7 new file mode 100644 index 000000000..52a90084f --- /dev/null +++ b/man7/utf8.7 @@ -0,0 +1 @@ +.so man7/utf-8.7 diff --git a/man7/x25.7 b/man7/x25.7 new file mode 100644 index 000000000..b06428b0d --- /dev/null +++ b/man7/x25.7 @@ -0,0 +1,112 @@ +.\" This man page is Copyright (C) 1998 Heiner Eisen. +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" $Id: x25.7,v 1.4 1999/05/18 10:35:12 freitag Exp $ +.TH X25 4 1998-12-01 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +x25, PF_X25 \- ITU-T X.25 / ISO-8208 protocol interface. + +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.B x25_socket = socket(PF_X25, SOCK_SEQPACKET, 0); + +.SH DESCRIPTION +X25 sockets provide an interface to the X.25 packet layer protocol. +This allows applications to +communicate over a public X.25 data network as standardised by +International Telecommunication Union's recommendation X.25 +(X.25 DTE-DCE mode). X25 sockets can also be used for communication +without an intermediate X.25 network (X.25 DTE-DTE mode) as described +in ISO-8208. +.PP +Message boundaries are preserved \- a +.BR read (2) +from a socket will +retrieve the same chunk of data as output with the corresponding +.BR write (2) +to the peer socket. When necessary, the kernel takes care +of segmenting and re-assembling long messages by means of +the X.25 M-bit. There is no hard-coded upper limit for the +message size. However, re-assembling of a long message might fail if +there is a temporary lack of system resources or when other constraints +(such as socket memory or buffer size limits) become effective. If that +occurs, the X.25 connection will be reset. +.SH "SOCKET ADDRESSES" +The +.B AF_X25 +socket address family uses the +.B struct sockaddr_x25 +for representing network addresses as defined in ITU-T +recommendation X.121. +.PP +.RS +.nf +.ta 4n 18n 32n +struct sockaddr_x25 { + sa_family_t sx25_family; /* must be AF_X25 */ + x25_address sx25_addr; /* X.121 Address */ +}; +.ta +.fi +.RE +.PP +.I sx25_addr +contains a char array +.I x25_addr[] +to be interpreted as a null-terminated string. +.I sx25_addr.x25_addr[] +consists of up to 15 (not counting the terminating 0) ASCII +characters forming the X.121 address. +Only the decimal digit characters from `0' to `9' are allowed. +.SH "SOCKET OPTIONS" +The following X.25 specific socket options can be set by using +.BR setsockopt (2) +and read with +.BR getsockopt (2) +with the level parameter set to +.BR SOL_X25 . +.TP +.B X25_QBITINCL +Controls whether the X.25 Q-bit (Qualified Data Bit) is accessible by the +user. It expects an integer argument. If set to 0 (default), +the Q-bit is never set for outgoing packets and the Q-bit of incoming +packets is ignored. If set to 1, an additional first byte is prepended +to each message read from or written to the socket. For data read from +the socket, a 0 first byte indicates that the Q-bits of the corresponding +incoming data packets were not set. A first byte with value 1 indicates +that the Q-bit of the corresponding incoming data packets was set. +If the first byte of the data written to the socket is 1 the Q-bit of the +corresponding outgoing data packets will be set. If the first byte is 0 +the Q-bit will not be set. +.SH BUGS +Plenty, as the X.25 PLP implementation is +.BR CONFIG_EXPERIMENTAL . +.PP +This man page is incomplete. +.PP +There is no dedicated application programmer's header file yet; +you need to include the kernel header file +.BR . +.B CONFIG_EXPERIMENTAL +might also imply that future versions of the +interface are not binary compatible. +.PP +X.25 N-Reset events are not propagated to the user process yet. Thus, +if a reset occurred, data might be lost without notice. +.SH "SEE ALSO" +.BR socket (2), +.BR socket (7) +.PP +Jonathan Simon Naylor: +\(lqThe Re-Analysis and Re-Implementation of X.25.\(rq +The URL is +.RS +.I ftp://ftp.pspt.fi/pub/ham/linux/ax25/x25doc.tgz +.RE +.SH VERSIONS +The PF_X25 protocol family is a new feature of Linux 2.2. diff --git a/man8/intro.8 b/man8/intro.8 new file mode 100644 index 000000000..6506fee77 --- /dev/null +++ b/man8/intro.8 @@ -0,0 +1,32 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" +.\" Modified Sat Jul 24 17:35:48 1993 by Rik Faith (faith@cs.unc.edu) +.TH INTRO 8 1993-07-24 "Linux" "Linux Programmer's Manual" +.SH NAME +intro \- Introduction to administration and privileged commands +.SH DESCRIPTION +This chapter describes commands which either can be or are only used by +the superuser, like daemons and hardware related commands. +.SH AUTHORS +Look at the header of the manual page for the author(s) and copyright +conditions. Note that these can be different from page to page! diff --git a/man8/ld-linux.8 b/man8/ld-linux.8 new file mode 100644 index 000000000..c57562024 --- /dev/null +++ b/man8/ld-linux.8 @@ -0,0 +1 @@ +.so man8/ld.so.8 diff --git a/man8/ld-linux.so.8 b/man8/ld-linux.so.8 new file mode 100644 index 000000000..c57562024 --- /dev/null +++ b/man8/ld-linux.so.8 @@ -0,0 +1 @@ +.so man8/ld.so.8 diff --git a/man8/ld.so.8 b/man8/ld.so.8 new file mode 100644 index 000000000..9fada679f --- /dev/null +++ b/man8/ld.so.8 @@ -0,0 +1,251 @@ +.\" This is in the public domain +.TH LD.SO 8 2001-12-16 "" "Linux Programmer's Manual" +.SH NAME +ld.so, ld-linux.so* \- dynamic linker/loader +.SH DESCRIPTION +The programs +.B ld.so +and +.B ld-linux.so* +find and load the shared libraries needed by a program, prepare +the program to run, and then run it. +.LP +Linux binaries require dynamic linking (linking at run time) +unless the +.B \-static +option was given to +.B ld +during compilation. +.LP +The program +.B ld.so +handles a.out binaries, a format used long ago; +.B ld-linux.so* +handles ELF (\fB/lib/ld-linux.so.1\fP for libc5, \fB/lib/ld-linux.so.2\fP +for glibc2), which everybody has been using for years now. +Otherwise both have the same behaviour, and use the same +support files and programs +.BR ldd (1), +.BR ldconfig (8) +and +.IR /etc/ld.so.conf . +.LP +The shared libraries needed by the program are searched for +in various places: +.IP o +(ELF only) Using the DT_RPATH dynamic section attribute +of the binary if present and DT_RUNPATH attribute does not exist. +Use of DT_RPATH is deprecated. +.IP o +Using the environment variable +.BR LD_LIBRARY_PATH . +Except if the executable is a setuid/setgid binary, in which case it +is ignored. +.IP o +(ELF only) Using the DT_RUNPATH dynamic section attribute +of the binary if present. +.IP o +From the cache file +.BR /etc/ld.so.cache +which contains a compiled list of candidate libraries previously found +in the augmented library path. If, however, the binary was linked with +.B -z nodeflib +linker option, libraries in the default library paths are skipped. +.IP o +In the default path +.BR /lib , +and then +.BR /usr/lib . +If the binary was linked with +.B -z nodeflib +linker option, this step is skipped. +.SH SYNOPSIS +The dynamic linker can be run either indirectly through running some +dynamically linked program or library (in which case no command line options +to the dynamic linker can be passed and, in the ELF case, the dynamic linker +which is stored in the +.B .interp +section of the program is executed) or directly by running: +.P +.B /lib/ld-linux.so.* +[OPTIONS] [PROGRAM [ARGUMENTS]] +.SH COMMAND LINE OPTIONS +.TP +.B --list +List all dependencies and how they are resolved. +.TP +.B --verify +Verify that program is dynamically linked and this dynamic linker can handle +it. +.TP +.B --library-path PATH +Override +.B LD_LIBRARY_PATH +environment variable setting (see below). +.TP +.B --ignore-rpath LIST +Ignore RPATH and RUNPATH information in object names in LIST. +This option has been supported by glibc2 for about one hour. +Then it was renamed into: +.TP +.B --inhibit-rpath LIST +.SH ENVIRONMENT +There are four important environment variables. +.TP +.B LD_LIBRARY_PATH +A colon-separated list of directories in which to search for +ELF libraries at execution-time. +Similar to the +.B PATH +environment variable. +.TP +.B LD_PRELOAD +A whitespace-separated list of additional, user-specified, ELF shared +libraries to be loaded before all others. +This can be used to selectively override functions in other shared libraries. +For setuid/setgid ELF binaries, only libraries in the standard search +directories that are also setuid will be loaded. +.TP +.B LD_BIND_NOW +(libc5; glibc since 2.1.1) +If set to non-empty string, causes the dynamic linker to resolve all symbols +at program startup instead of deferring function call resolval to the point +when they are first referenced. +This is useful when using a debugger. +.TP +.B LD_TRACE_LOADED_OBJECTS +(ELF only) +If set to non-empty string, causes the program to list its dynamic library +dependencies, as if run by +.BR ldd (1), +instead of running normally. +.LP +Then there are lots of more or less obscure variables, +many obsolete or only for internal use. +.TP +.B LD_WARN +(ELF only)(glibc since 2.1.3) +If set to non-empty string, warn about unresolved symbols. +.TP +.B LD_NOWARN +(a.out only)(libc5) +Suppress warnings about a.out libraries with incompatible minor +version numbers. +.TP +.B LD_BIND_NOT +(glibc since 2.1.95) +Do not update the GOT (global offset table) and PLT (procedure linkage table) +after resolving a symbol. +.TP +.B LD_DEBUG +(glibc since 2.1) +Output verbose debugging information about the dynamic linker. +If set to +.B all +prints all debugging information it has, if set to +.B help +prints a help message about which categories can be specified in this +environment variable. +.TP +.B LD_DEBUG_OUTPUT +(glibc since 2.1) +File where +.B LD_DEBUG +output should be fed into, default is standard output. +LD_DEBUG_OUTPUT is ignored for setuid/setgid binaries. +.TP +.B LD_VERBOSE +(glibc since 2.1) +If set to non-empty string, output symbol versioning information about the +program if querying information about the program (ie. either +.B LD_TRACE_LOADED_OBJECTS +has been set, or +.B --list +or +.B --verify +options have been given to the dynamic linker). +.TP +.B LD_PROFILE +(glibc since 2.1) +Shared object to be profiled. +.TP +.B LD_PROFILE_OUTPUT +(glibc since 2.1) +File where +.B LD_PROFILE +output should be stored, default is standard output. +LD_DEBUG_OUTPUT is ignored for setuid/setgid binaries. +.TP +.B LD_AOUT_LIBRARY_PATH +(libc5) +Version of LD_LIBRARY_PATH for a.out binaries only. +Old versions of ld-linux.so.1 also supported LD_ELF_LIBRARY_PATH. +.TP +.B LD_AOUT_PRELOAD +(libc5) +Version of LD_PRELOAD for a.out binaries only. +Old versions of ld-linux.so.1 also supported LD_ELF_PRELOAD. +.TP +.B LD_SHOW_AUXV +(glibc since 2.1) +Show auxiliary array passed up from the kernel. +.TP +.B LD_HWCAP_MASK +(glibc since 2.1) +Mask for hardware capabilities. +.TP +.B LD_ORIGIN_PATH +(glibc since 2.1) +Path where the binary is found (for non-setuid programs). +.TP +.B LD_DYNAMIC_WEAK +(glibc since 2.1.91) +Allow weak symbols to be overridden (reverting to old glibc behaviour). +.TP +.B LD_KEEPDIR +(a.out only)(libc5) +Don't ignore the directory in the names of a.out libraries to be loaded. +Use of this option is strongly discouraged. +.TP +.B LDD_ARGV0 +(libc5) +.IR argv [0] +to be used by +.BR ldd (1) +when none is present. +.SH FILES +.PD 0 +.TP +.B /lib/ld.so +a.out dynamic linker/loader +.TP +.BR /lib/ld-linux.so. { 1 , 2 } +ELF dynamic linker/loader +.TP +.B /etc/ld.so.cache +File containing a compiled list of directories in which to search for +libraries and an ordered list of candidate libraries. +.TP +.B /etc/ld.so.preload +File containing a whitespace separated list of ELF shared libraries to +be loaded before the program. +libraries and an ordered list of candidate libraries. +.TP +.B lib*.so* +shared libraries +.PD +.SH NOTES +The +.B ld.so +functionality is available for executables compiled using libc version +4.4.3 or greater. +ELF functionality is available since Linux 1.1.52 and libc5. +.SH SEE ALSO +.BR ldd (1), +.BR ldconfig (8) +.\" .SH AUTHORS +.\" ld.so: David Engel, Eric Youngdale, Peter MacDonald, Hongjiu Lu, Linus +.\" Torvalds, Lars Wirzenius and Mitch D'Souza +.\" ld-linux.so: Roland McGrath, Ulrich Drepper and others. +.\" +.\" In the above, (libc5) stands for David Engel's ld.so/ld-linux.so. diff --git a/man8/ldconfig.8 b/man8/ldconfig.8 new file mode 100644 index 000000000..57a146ded --- /dev/null +++ b/man8/ldconfig.8 @@ -0,0 +1,162 @@ +.\" -*- nroff -*- +.\" Copyright 1999 SuSE GmbH Nuernberg, Germany +.\" Author: Thorsten Kukuk +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of the +.\" License, or (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +.\" General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this program; see the file COPYING. If not, +.\" write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, +.\" Boston, MA 02111-1307, USA. +.\" +.\" Modified, 6 May 2002, Michael Kerrisk, mtk16@ext.canterbury.ac.nz +.\" Change listed order of /usr/lib and /lib +.TH LDCONFIG 8 2002-05-06 "GNU C Library" "Linux Programmer's Manual" +.SH NAME +/sbin/ldconfig \- configure dynamic linker run time bindings +.SH SYNOPSIS +.B /sbin/ldconfig +[ +.B \-nNvXV +] +[ +.BR \-f\ conf +] +[ +.BR \-C\ cache +] +[ +.BR \-r\ root +] +.IR directory \ ... +.PD 0 +.PP +.PD +.BR /sbin/ldconfig +.B \-l +[ +.B \-v +] +.IR library \ ... +.PD 0 +.PP +.PD +.B /sbin/ldconfig +.B \-p +.SH DESCRIPTION +.B ldconfig +creates the necessary links and cache to the most recent shared +libraries found in the directories specified on the command line, +in the file +.IR /etc/ld.so.conf , +and in the trusted directories +.RI ( /lib +and +.IR /usr/lib ). +The cache is used by the run-time linker, +.IR ld.so +or +.IR ld-linux.so . +.B ldconfig +checks the header and file names of the libraries it encounters when +determining which versions should have their links updated. +.PP +.B ldconfig +will attempt to deduce the type of ELF libs (ie. libc5 or libc6/glibc) +based on what C libs, if any, the library was linked against. Therefore, when +making dynamic libraries, it is wise to explicitly link against libc (use -lc). +.PP +Some existing libs do not contain enough information to allow the deduction of +their type. Therefore, the +.IR /etc/ld.so.conf +file format allows the specification of an expected type. This is +.B only +used for those ELF libs which we can not work out. The format +is "dirname=TYPE", where TYPE can be libc4, libc5, or libc6. +(This syntax also works on the command line.) Spaces are +.B not +allowed. Also see the +.B -p +option. +.B ldconfig +should normally be run by the super-user as it may require write +permission on some root owned directories and files. +.SH OPTIONS +.TP +.B \-v +Verbose mode. +Print current version number, the name of each directory as it +is scanned, and any links that are created. +Overrides quiet mode. +.TP +.B \-n +Only process directories specified on the command line. +Don't process the trusted directories +.RI ( /lib +and +.IR /usr/lib ) +nor those specified in +.IR /etc/ld.so.conf . +Implies +.BR \-N . +.TP +.B \-N +Don't rebuild the cache. +Unless +.B \-X +is also specified, links are still updated. +.TP +.B \-X +Don't update links. +Unless +.B \-N +is also specified, the cache is still rebuilt. +.TP +.B \-f conf +Use +.B conf +instead of +.IR /etc/ld.so.conf . +.TP +.B \-C cache +Use +.B cache +instead of +.IR /etc/ld.so.cache . +.TP +.B \-r root +Change to and use +.B root +as the root directory. +.TP +.B \-l +Library mode. Manually link individual libraries. Intended for +use by experts only. +.TP +.B \-p +Print the lists of directories and candidate libraries stored in +the current cache. + +.SH FILES +.PD 0 +.TP 20 +.B /lib/ld.so +run-time linker/loader +.TP 20 +.B /etc/ld.so.conf +File containing a list of colon, space, tab, newline, or comma spearated +directories in which to search for libraries. +.TP 20 +.B /etc/ld.so.cache +File containing an ordered list of libraries found in the directories +specified in +.BR /etc/ld.so.conf . +.PD diff --git a/man8/nscd.8 b/man8/nscd.8 new file mode 100644 index 000000000..b92a58963 --- /dev/null +++ b/man8/nscd.8 @@ -0,0 +1,71 @@ +.\" -*- nroff -*- +.\" Copyright 1999 SuSE GmbH Nuernberg, Germany +.\" Author: Thorsten Kukuk +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of the +.\" License, or (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +.\" General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this program; see the file COPYING. If not, +.\" write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, +.\" Boston, MA 02111-1307, USA. +.\" +.TH NSCD 8 1999-10 "GNU C Library" "Linux Programmer's Manual" +.SH NAME +/usr/sbin/nscd - name service cache daemon +.SH DESCRIPTION +Nscd is a daemon that provides a cache for the most common name service +requests. The default configuration file, +.IR /etc/nscd.conf , +determines the behavior of the cache daemon. See +.BR nscd.conf (5). + +Nscd provides cacheing for accesses of the +.BR passwd (5), +.BR group (5), +and +.BR hosts(5) +databases through standard libc interfaces, such as +.BR getpwnam (3), +.BR getpwuid (3), +.BR getgrnam (3), +.BR getgrgid (3), +.BR gethostbyname (3), +and others. + +There are two caches for each database: +a positive one for items found, and a negative one +for items not found. Each cache has a separate TTL (time-to-live) +period for its data. +Note that the shadow file is specifically not cached. +.BR getspnam (3) +calls remain uncached as a result. + +.SH OPTIONS +.TP +.B "\-\-help" +will give you a list with all options and what they do. + +.SH NOTES +Nscd doesn't know anything about the underlaying protocols for a +service. This also means, that if you change +.I /etc/resolv.conf +for DNS queries, nscd will continue to use the old one if you have +configured +.I /etc/nsswitch.conf +to use DNS for host lookups. In such a case, you need to restart +nscd. + +.SH "SEE ALSO" +.BR nscd.conf (5), +.BR nsswitch.conf (5) +.SH AUTHOR +.B nscd +was written by Thorsten Kukuk and Ulrich Drepper. diff --git a/man8/sync.8 b/man8/sync.8 new file mode 100644 index 000000000..c1dbd5124 --- /dev/null +++ b/man8/sync.8 @@ -0,0 +1,82 @@ +.\" Reboot/halt and Linux information extracted from Rick Faith's original +.\" sync(8) manpage, dating back to the Linux 0.99 days. The Linux-specific +.\" information is attributed to Linus Torvalds +.\" Copyright 1992, 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" May be distributed under the GNU General Public License +.TH SYNC 8 1998-11 "GNU fileutils 4.0" "Linux Programmer's Manual" +.SH NAME +sync \- synchronize data on disk with memory +.SH SYNOPSYS +.B "sync [\-\-help] [\-\-version]" +.SH DESCRIPTION +.B sync +writes any data buffered in memory out to disk. This can +include (but is not limited to) modified superblocks, modified inodes, +and delayed reads and writes. This must be implemented by the kernel; +The +.B sync +program does nothing but exercise the +.BR sync (2) +system call. +.PP +The kernel keeps data in memory to avoid doing (relatively slow) disk +reads and writes. This improves performance, but if the computer +crashes, data may be lost or the filesystem corrupted as a result. +.B sync +ensures that everything in memory is written to disk. +.PP +.B sync +should be called before the processor is halted in an unusual manner +(e.g., before causing a kernel panic when debugging new kernel code). +In general, the processor should be halted using the +.BR shutdown (8) +or +.BR reboot (8) +or +.BR halt (8) +commands, which will attempt to put the system in a quiescent state +before calling +.BR sync (2). +(Various implementations of these commands exist; consult your +documentation; on some systems one should not call +.BR reboot (8) +and +.BR halt (8) +directly.) +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variables LANG, LC_ALL, LC_CTYPE, and LC_MESSAGES have the +usual meaning. +.SH "CONFORMING TO" +POSIX 1003.2 +.SH NOTES +On Linux, +.B sync +is only guaranteed to schedule the dirty blocks for writing; it can +actually take a short time before all the blocks are finally written. +The +.BR reboot (8) +and +.BR halt (8) +commands take this into account by sleeping for a few seconds after +calling +.BR sync (2). +.PP +This page describes +.B sync +as found in the file\%utils-4.0 package; +other versions may differ slightly. +.SH "SEE ALSO" +.BR sync (2), +.BR halt (8), +.BR reboot (8), +.BR update (8) diff --git a/man8/tzselect.8 b/man8/tzselect.8 new file mode 100644 index 000000000..016831418 --- /dev/null +++ b/man8/tzselect.8 @@ -0,0 +1,44 @@ +.TH TZSELECT 8 +.SH NAME +tzselect \- select a time zone +.SH SYNOPSIS +.B tzselect +.SH DESCRIPTION +The +.B tzselect +program asks the user for information about the current location, +and outputs the resulting time zone description to standard output. +The output is suitable as a value for the TZ environment variable. +.PP +All interaction with the user is done via standard input and standard error. +.SH "ENVIRONMENT VARIABLES" +.TP +\fBAWK\fP +Name of a Posix-compliant +.I awk +program (default: +.BR awk ). +.TP +\fBTZDIR\fP +Name of the directory containing time zone data files (default: +.IR /usr/local/etc/zoneinfo ). +.SH FILES +.TP +\fBTZDIR\fP\fI/iso3166.tab\fP +Table of ISO 3166 2-letter country codes and country names. +.TP +\fBTZDIR\fP\fI/zone.tab\fP +Table of country codes, latitude and longitude, TZ values, and +descriptive comments. +.TP +\fBTZDIR\fP\fI/\fP\fITZ\fP +Time zone data file for time zone \fITZ\fP. +.SH "EXIT STATUS" +The exit status is zero if a time zone was successfully obtained from the user, +nonzero otherwise. +.SH "SEE ALSO" +.BR newctime (3), +.BR tzfile (5), +.BR zdump (8), +.BR zic (8) +.\" @(#)tzselect.8 1.3 diff --git a/man8/zdump.8 b/man8/zdump.8 new file mode 100644 index 000000000..7cc30e21f --- /dev/null +++ b/man8/zdump.8 @@ -0,0 +1,39 @@ +.TH ZDUMP 8 +.SH NAME +zdump \- time zone dumper +.SH SYNOPSIS +.B zdump +[ +.B \-v +] [ +.B \-c +cutoffyear ] [ zonename ... ] +.SH DESCRIPTION +.I Zdump +prints the current time in each +.I zonename +named on the command line. +.PP +These options are available: +.TP +.B \-v +For each +.I zonename +on the command line, +print the time at the lowest possible time value, +the time one day after the lowest possible time value, +the times both one second before and exactly at +each detected time discontinuity, +the time at one day less than the highest possible time value, +and the time at the highest possible time value. +Each line ends with +.B isdst=1 +if the given time is Daylight Saving Time or +.B isdst=0 +otherwise. +.TP +.BI "\-c " cutoffyear +Cut off the verbose output near the start of the given year. +.SH "SEE ALSO" +newctime(3), tzfile(5), zic(8) +.\" @(#)zdump.8 7.3 diff --git a/man8/zic.8 b/man8/zic.8 new file mode 100644 index 000000000..2da0eea5b --- /dev/null +++ b/man8/zic.8 @@ -0,0 +1,414 @@ +.TH ZIC 8 +.SH NAME +zic \- time zone compiler +.SH SYNOPSIS +.B zic +[ +.B \-v +] [ +.B \-d +.I directory +] [ +.B \-l +.I localtime +] [ +.B \-p +.I posixrules +] [ +.B \-L +.I leapsecondfilename +] [ +.B \-s +] [ +.B \-y +.I command +] [ +.I filename +\&... ] +.SH DESCRIPTION +.if t .ds lq `` +.if t .ds rq '' +.if n .ds lq \&"\" +.if n .ds rq \&"\" +.de q +\\$3\*(lq\\$1\*(rq\\$2 +.. +.I Zic +reads text from the file(s) named on the command line +and creates the time conversion information files specified in this input. +If a +.I filename +is +.BR \- , +the standard input is read. +.PP +These options are available: +.TP +.BI "\-d " directory +Create time conversion information files in the named directory rather than +in the standard directory named below. +.TP +.BI "\-l " timezone +Use the given time zone as local time. +.I Zic +will act as if the input contained a link line of the form +.sp +.ti +.5i +Link \fItimezone\fP localtime +.TP +.BI "\-p " timezone +Use the given time zone's rules when handling POSIX-format +time zone environment variables. +.I Zic +will act as if the input contained a link line of the form +.sp +.ti +.5i +Link \fItimezone\fP posixrules +.TP +.BI "\-L " leapsecondfilename +Read leap second information from the file with the given name. +If this option is not used, +no leap second information appears in output files. +.TP +.B \-v +Complain if a year that appears in a data file is outside the range +of years representable by +.IR time (2) +values. +.TP +.B \-s +Limit time values stored in output files to values that are the same +whether they're taken to be signed or unsigned. +You can use this option to generate SVVS-compatible files. +.TP +.BI "\-y " command +Use the given +.I command +rather than +.B yearistype +when checking year types (see below). +.PP +Input lines are made up of fields. +Fields are separated from one another by any number of white space characters. +Leading and trailing white space on input lines is ignored. +An unquoted sharp character (#) in the input introduces a comment which extends +to the end of the line the sharp character appears on. +White space characters and sharp characters may be enclosed in double quotes +(") if they're to be used as part of a field. +Any line that is blank (after comment stripping) is ignored. +Non-blank lines are expected to be of one of three types: +rule lines, zone lines, and link lines. +.PP +A rule line has the form +.nf +.ti +.5i +.ta \w'Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'TYPE\0\0'u +\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u +.sp +Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S +.sp +For example: +.ti +.5i +.sp +Rule US 1967 1973 \- Apr lastSun 2:00 1:00 D +.sp +.fi +The fields that make up a rule line are: +.TP "\w'LETTER/S'u" +.B NAME +Gives the (arbitrary) name of the set of rules this rule is part of. +.TP +.B FROM +Gives the first year in which the rule applies. +Any integer year can be supplied; the Gregorian calendar is assumed. +The word +.B minimum +(or an abbreviation) means the minimum year representable as an integer. +The word +.B maximum +(or an abbreviation) means the maximum year representable as an integer. +Rules can describe times that are not representable as time values, +with the unrepresentable times ignored; this allows rules to be portable +among hosts with differing time value types. +.TP +.B TO +Gives the final year in which the rule applies. +In addition to +.B minimum +and +.B maximum +(as above), +the word +.B only +(or an abbreviation) +may be used to repeat the value of the +.B FROM +field. +.TP +.B TYPE +Gives the type of year in which the rule applies. +If +.B TYPE +is +.B \- +then the rule applies in all years between +.B FROM +and +.B TO +inclusive. +If +.B TYPE +is something else, then +.I zic +executes the command +.ti +.5i +\fByearistype\fP \fIyear\fP \fItype\fP +.br +to check the type of a year: +an exit status of zero is taken to mean that the year is of the given type; +an exit status of one is taken to mean that the year is not of the given type. +.TP +.B IN +Names the month in which the rule takes effect. +Month names may be abbreviated. +.TP +.B ON +Gives the day on which the rule takes effect. +Recognized forms include: +.nf +.in +.5i +.sp +.ta \w'Sun<=25\0\0'u +5 the fifth of the month +lastSun the last Sunday in the month +lastMon the last Monday in the month +Sun>=8 first Sunday on or after the eighth +Sun<=25 last Sunday on or before the 25th +.fi +.in -.5i +.sp +Names of days of the week may be abbreviated or spelled out in full. +Note that there must be no spaces within the +.B ON +field. +.TP +.B AT +Gives the time of day at which the rule takes effect. +Recognized forms include: +.nf +.in +.5i +.sp +.ta \w'1:28:13\0\0'u +2 time in hours +2:00 time in hours and minutes +15:00 24-hour format time (for times after noon) +1:28:14 time in hours, minutes, and seconds +\- equivalent to 0 +.fi +.in -.5i +.sp +where hour 0 is midnight at the start of the day, +and hour 24 is midnight at the end of the day. +Any of these forms may be followed by the letter +.B w +if the given time is local +.q "wall clock" +time, +.B s +if the given time is local +.q standard +time, or +.B u +(or +.B g +or +.BR z ) +if the given time is universal time; +in the absence of an indicator, +wall clock time is assumed. +.TP +.B SAVE +Gives the amount of time to be added to local standard time when the rule is in +effect. +This field has the same format as the +.B AT +field +(although, of course, the +.B w +and +.B s +suffixes are not used). +.TP +.B LETTER/S +Gives the +.q "variable part" +(for example, the +.q S +or +.q D +in +.q EST +or +.q EDT ) +of time zone abbreviations to be used when this rule is in effect. +If this field is +.BR \- , +the variable part is null. +.PP +A zone line has the form +.sp +.nf +.ti +.5i +.ta \w'Zone\0\0'u +\w'Australia/Adelaide\0\0'u +\w'GMTOFF\0\0'u +\w'RULES/SAVE\0\0'u +\w'FORMAT\0\0'u +Zone NAME GMTOFF RULES/SAVE FORMAT [UNTIL] +.sp +For example: +.sp +.ti +.5i +Zone Australia/Adelaide 9:30 Aus CST 1971 Oct 31 2:00 +.sp +.fi +The fields that make up a zone line are: +.TP "\w'GMTOFF'u" +.B NAME +The name of the time zone. +This is the name used in creating the time conversion information file for the +zone. +.TP +.B GMTOFF +The amount of time to add to UTC to get standard time in this zone. +This field has the same format as the +.B AT +and +.B SAVE +fields of rule lines; +begin the field with a minus sign if time must be subtracted from UTC. +.TP +.B RULES/SAVE +The name of the rule(s) that apply in the time zone or, +alternately, an amount of time to add to local standard time. +If this field is +.B \- +then standard time always applies in the time zone. +.TP +.B FORMAT +The format for time zone abbreviations in this time zone. +The pair of characters +.B %s +is used to show where the +.q "variable part" +of the time zone abbreviation goes. +Alternately, +a slash (/) +separates standard and daylight abbreviations. +.TP +.B UNTIL +The time at which the UTC offset or the rule(s) change for a location. +It is specified as a year, a month, a day, and a time of day. +If this is specified, +the time zone information is generated from the given UTC offset +and rule change until the time specified. +The month, day, and time of day have the same format as the IN, ON, and AT +columns of a rule; trailing columns can be omitted, and default to the +earliest possible value for the missing columns. +.IP +The next line must be a +.q continuation +line; this has the same form as a zone line except that the +string +.q Zone +and the name are omitted, as the continuation line will +place information starting at the time specified as the +.B UNTIL +field in the previous line in the file used by the previous line. +Continuation lines may contain an +.B UNTIL +field, just as zone lines do, indicating that the next line is a further +continuation. +.PP +A link line has the form +.sp +.nf +.ti +.5i +.ta \w'Link\0\0'u +\w'Europe/Istanbul\0\0'u +Link LINK-FROM LINK-TO +.sp +For example: +.sp +.ti +.5i +Link Europe/Istanbul Asia/Istanbul +.sp +.fi +The +.B LINK-FROM +field should appear as the +.B NAME +field in some zone line; +the +.B LINK-TO +field is used as an alternate name for that zone. +.PP +Except for continuation lines, +lines may appear in any order in the input. +.PP +Lines in the file that describes leap seconds have the following form: +.nf +.ti +.5i +.ta \w'Leap\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u +\w'HH:MM:SS\0\0'u +\w'CORR\0\0'u +.sp +Leap YEAR MONTH DAY HH:MM:SS CORR R/S +.sp +For example: +.ti +.5i +.sp +Leap 1974 Dec 31 23:59:60 + S +.sp +.fi +The +.BR YEAR , +.BR MONTH , +.BR DAY , +and +.B HH:MM:SS +fields tell when the leap second happened. +The +.B CORR +field +should be +.q + +if a second was added +or +.q - +if a second was skipped. +.\" There's no need to document the following, since it's impossible for more +.\" than one leap second to be inserted or deleted at a time. +.\" The C Standard is in error in suggesting the possibility. +.\" See Terry J Quinn, The BIPM and the accurate measure of time, +.\" Proc IEEE 79, 7 (July 1991), 894-905. +.\" or +.\" .q ++ +.\" if two seconds were added +.\" or +.\" .q -- +.\" if two seconds were skipped. +The +.B R/S +field +should be (an abbreviation of) +.q Stationary +if the leap second time given by the other fields should be interpreted as UTC +or +(an abbreviation of) +.q Rolling +if the leap second time given by the other fields should be interpreted as +local wall clock time. +.SH NOTE +For areas with more than two types of local time, +you may need to use local standard time in the +.B AT +field of the earliest transition time's rule to ensure that +the earliest transition time recorded in the compiled file is correct. +.SH FILE +/usr/local/etc/zoneinfo standard directory used for created files +.SH "SEE ALSO" +newctime(3), tzfile(5), zdump(8) +.\" @(#)zic.8 7.19 diff --git a/man9/ksoftirqd.9 b/man9/ksoftirqd.9 new file mode 100644 index 000000000..8db23df10 --- /dev/null +++ b/man9/ksoftirqd.9 @@ -0,0 +1,41 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" This manpage is Copyright (C) 2003 Matthew Wilcox +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel is constantly changing, this manual page may +.\" be incorrect or out-of-date. The author(s) assume no responsibility +.\" for errors or omissions, or for damages resulting from the use of the +.\" information contained herein. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH KSOFTIRQD 9 2003-08-24 "Linux 2.6.0" "Linux Programmer's Manual" +.SH NAME +ksoftirqd \- Softirq daemon +.SH DESCRIPTION +.B ksoftirqd +is a per-cpu kernel thread that runs when the machine is under heavy +soft-interrupt load. Soft interrupts are normally serviced on return from +a hard interrupt, but it's possible for soft interrupts to be triggered +more quickly than they can be serviced. If a soft interrupt is triggered +for a second time while soft interrupts are being handled, the +.B ksoftirq +daemon is triggered to handle the soft interrupts in process context. +If +.B ksoftirqd +is taking more than a tiny percentage of CPU time, this indicates the +machine is under heavy soft interrupt load. +.SH HISTORY +.B ksoftirqd +was introduced during the 2.3 development series as part of the +softnet work by Alexey Kuznetsov and David Miller.